rendertarget_forceupdate(3)

📦
version 0.7.1 · 2 versions
, in nixos 26.05

💖 rendertarget_forceupdate(3) 💖

okay bestie, you're in the Arcan Lua API manual and this page is literally about rendertarget_forceupdate. it's giving "manual out-of-loop update" energy, and we're gonna get through every flag and caveat together 🫶

🌸 NAME 🌸

rendertarget_forceupdate — Manually perform an out-of-loop update of a rendertarget.

✨ SYNOPSIS ✨

the signatures are exactly these, and yes, nil is first:

nil
rendertarget_forceupdate( vid:rendertarget )
rendertarget_forceupdate( vid:rendertarget, bool:force_dirty=true )
rendertarget_forceupdate( vid:rendertarget, number:refresh )
rendertarget_forceupdate( vid:rendertarget, number:refresh,
       number:readback )
rendertarget_forceupdate( vid:rendertarget, number:refresh,
       number:readback, bool:allow_hw=false )

🦋 DESCRIPTION 🦋

By default, rendertargets update synchronously with the regular video refresh/redraw that is performed as part of the active synchronization strategy combined with the refreshrate hinted during creation.

This function covers two use-cases.

The first use case is to force an out-of-loop update of the specified target in 'manual' update mode (rate=0). By default this will always trigger a render pass. If the second argument is set to false, then the update will only be forced if the pipeline is actually dirty.

The second use case is to change the refresh and readback rates for the specified rendertarget. This can be used as an optimization to temporarily disable rendertargets without going through the process of rebuilding and migrating between rendertargets.

Any pending counters/timers for frame or tick/based automatic updates will be reset, and the update includes synchronizing with readback in the case of calctargets and recordtargets.

If allow_hw is set to true, the readback performed will instead be used to share the buffer of the rendertarget with the assigned sink. This has complex effects on the underlying graphics stack and may fail. If a failure can be detected it will automatically switch back to a software only approach (allow_hw=false), but it can also fail without warning.

bestie, that last part is not a cute little vibe — it can fail silently. read it twice. 💀

🌈 NOTES 🌈

  1. Trying to call this function on a VID that references an object that is not flagged as a rendertarget is a terminal state transition. terminal state transition is doing a lot of heavy lifting there, so yeah — don't.
  2. If a newrate is set, the rendertarget will not be updated directly. If that behaviour is desired, call the function again without the newrate argument.
  3. (no text here — the blank note is still part of the set, bestie 🫥)

🎀 EXAMPLE 🎀

here's the example, exactly as it is:

function rendertarget_forceupdate0()
      local dst = alloc_surface(320, 200);
      local a = color_surface(64, 64, 0, 255, 0);
      show_image(a);
      rotate_image(a, 45);
      define_rendertarget(dst, {a});
      rendertarget_forceupdate(dst);
      save_screenshot("test.png", FORMAT_PNG, dst);
      delete_image(dst);
end

💀 MISUSE 💀

this is the do-not-do-this example, and it is right here for a reason:

function rendertarget_forceupdate0()
      local a = fill_surface(32, 32, 255, 0, 0, 0);
      rendertarget_forceupdate(a);
end

👀 SEE ALSO: 👀

mwah 💖 this iconic page is from the Arcan Lua API manual, and the footer energy is source/version targetcontrol, dated October 2026, for rendertarget_forceupdate(3). byeee 🫶

📦 where this page comes from