stepframe_target(3)

✨ NAME ✨

okay bestie, welcome to stepframe_target(3) — it's part of the Arcan Lua API and it's the function that goes "hey, target, generate or consume a video frame please" 🎬💅

stepframe_target — request that the target generate / consume a video frame.

---

🦋 SYNOPSIS 🦋

bool
stepframe_target( vid:target )
stepframe_target( .B )
stepframe_target( vid:target, int:n_frames )
stepframe_target( .B )
stepframe_target( vid:target, int:n_frames, int:clock_id )
stepframe_target( .B )
stepframe_target( vid:target, int:n_frames, bool:synch )
stepframe_target( .B )
stepframe_target( vid:target, int:n_frames, bool:synch, int:x, int:y,
int:w, int:h )

---

🔥 DESCRIPTION 🔥

so the whole main-character purpose of this function is to have whatever target points at consume or generate a frame. that's it, that's the gig 🫶

the specifics? they vary a lil depending on what type the target actually has. there are two important distinctions: normal frameservers/clients, and the ones that are tied to offscreen render processes. iykyk 👑

if it's a normal client, only the first three forms are useful. the short version just sends an event to the client asking it to produce a frame (STEPFRAME), no cap.

the second form lets you further quantify how many frames it should advance (default is 1) — mostly useful for control over streaming video sources and similar clients where there's a continuous, seekable stream of logical time slices (frames). literally a stream of lil time slices 🍓

if the client has been forced into having synchronous size management through target_flags, then 'framestepping' also means acknowledging a pending resize lock. yes, it's doing double duty, slay ✨

if a clock_id is provided (default 0), it can also reference a custom client requested clock (CLOCKREQ event) for custom fireable timers. normally the engine takes care of these automatically, and this feature is mainly for specialised clients. main character energy only 💅

now, if the client is tied to another processing step through define_rendertarget or define_calctarget, this will issue a readback that's either synchronous if synch is set to true, or asynchronous if synch is set to false. pick your vibe 🌈

if a storage-coordinate region (x+w,y+h) is possible/defined, the processing stage gets a hint that only a certain region of the target should actually be considered. lowkey a crop, but make it a hint 🎀

⚠️ important one, bestie: the function will return false if a step is requested while a readback is already pending. this can happen if the receiving step — which, in the case of a recordtarget, is an external process — is slow to process. not me waiting on a slow external process 😭💀

---

🌸 SEE ALSO 🌸

• define_calctarget(3)
• define_recordtarget(3)

---

and that's the whole page, periodt 🧚 this one's targetcontrol, dated October 2026, and it's literally stepframe_target(3) — go forth and step those frames, ily 🫶💖