define_calctarget(3)

💅 define_calctarget(3) — Arcan Lua API 🎀

🌸 NAME 🌸

define_calctarget - Create a rendertarget with a periodic readback into a Lua callback

✨ SYNOPSIS ✨

nil
define_calctarget( dest_buffer, vid_table, detach, scale, samplerate,
callback )

bestie it returns nil, that's the whole mood 💖

🦋 DESCRIPTION 🦋

okay so this function inherits some of its behavior from define_rendertarget. Please refer to that function's description for assistance with the detach, scale, and samplerate functions. iykyk ✨

The callback will follow the prototype function(image, width, height) where image is a table with the following functions:

• get (x, y, [nchannels=1]) => r, [g, b, a]
• histogram_impose (destination, *int:mode*, *bool:norm*, *int:dst_row*)
• frequency (bin, *int:mode*, *bool:normalize*) => r,g,b,a

The get function can be used to sample the value at the specified coordinates (x,y) that must be 0 <= x < width, 0 <= y < height. Other values will result in a terminal state transition. For the nchannels argument, the permitted values 1, 3, 4 will determine the number of returned channels. no cap, those bounds are important 😭

The histogram_impose function will generate a histogram and store in the first row (or, if provided, dst_row) of destination, which subsequently must have at least a width of 256 pixels and at least dst_row number of rows, 0-indexed. slay but read the sizing rules twice 💅

The frequency function will return the number of occurrences from a specific histogram bin and bin should be 0 <= n < 256. The optional normalize argument, default to true, will normalize against the max-bin value per channel.

For both histogram_impose and frequency the possible mode values are HISTOGRAM_SPLIT (treat R, G, B, A channels as separate), HISTOGRAM_MERGE (treat R, G, B, A as packed and merge into one bin) or HISTOGRAM_MERGE_NOALPHA (treat R, G, B as packed and ignore A)

👑 NOTES 👑

1. The callback will be executed as part of the main loop and it is paramount that the processing done is kept to a minimum. fr fr keep it tiny, the main loop is busy 🫶
2. When the samplerate is set to 0 for a calctarget, both rendertarget_forceupdate and stepframe target need to be called in order to update the contents and issue a readback.

🍓 EXAMPLE 🍓

       function cbfun(source, w, h)
             print(srcary:get(0, 0));
       end
       function define_calctarget0()
             dstvid = fill_surface(64, 64, 0, 0, 0, 64, 64);
             srcvid = color_surface(64, 64, 255, 128, 64);
             define_calctarget(dstvid, {srcvid}, RENDERTARGET_DETACH,
                   RENDERTARGET_SCALE, 10, cbfun);
             show_image(srcvid);
             show_image(dstvid);
       end

💀 MISUSE 💀

       function cbfun(source, w, h)
             print(srcary:get(0, 0));
       end
       function define_calctarget0()
             dstvid = fill_surface(64, 64, 0, 0, 0, 64, 64);
             srcvid = color_surface(64, 64, 255, 128, 64);
             define_calctarget(WORLDID, {srcvid}, RENDERTARGET_DETACH,
             RENDERTARGET_SCALE, 10, cbfun);
       end

💀 MISUSE 💀

       function cbfun(source, w, h)
             print(srcary:get(0, 0));
       end
       function define_calctarget1()
             dstvid = fill_surface(64, 64, 0, 0, 0, 64, 64);
             srcvid = color_surface(64, 64, 255, 128, 64);
             define_calctarget(dstvid, {srcvid, WORLDID}, RENDERTARGET_DETACH,
             RENDERTARGET_SCALE, 10, cbfun);
       end

💀 MISUSE 💀

       function cbfun(source, w, h)
             print(srcary:get(0, 0));
       end
       function define_calctarget2()
             dstvid = fill_surface(64, 64, 0, 0, 0, 64, 64);
             srcvid = color_surface(64, 64, 255, 128, 64);
             define_calctarget(dstvid, {srcvid}, RENDERTARGET_DETACH,
                   RENDERTARGET_SCALE, 10, define_calctarget);
       end

🌈 SEE ALSO 🌈

define_rendertarget(3) define_recordtarget(3) fill_surface(3)

xoxo, the define_calctarget(3) page is brought to you by targetcontrol, dated October 2026 🫶💖✨