define_linktarget(3)

✨ define_linktarget(3) ✨

okay bestie so this one lives in the Arcan Lua API manual and it's literally the glow-up your render pipeline didn't know it needed 💅 it's called define_linktarget and it creates a linked offscreen rendering pipe. yes. we're doing pipes today. buckle up 🎀

---

🌸 SYNOPSIS 🌸

bool:status
define_linktarget( vid:dst, vid:link )
define_linktarget( vid:dst, vid:link, int:scale )
define_linktarget( vid:dst, vid:link, int:scale, int:rate )
define_linktarget( vid:dst, vid:link, int:scale, int:rate, int:format )

that's it, that's the whole vibe check — four ways to call it, and the args just keep stacking up like my iced coffee order 🧊

---

💖 DESCRIPTION 💖

so here's the tea ☕ — rendertargets and all their little friends (calctargets, recordtargets etc.) each have their own attachment pipelines, filled with the vids that are part of the related renderpass. and they have this restriction: you get one object allowed to be tagged as the camera or the view for that rendertarget. exactly one. no sharing, no swapping, no ✨polyamory✨ for your view params.

which lowkey caused SO much manual management 😭 because if you wanted to process the same set of objects with different view and storage parameters, you had to manage either two identical sets — and that leads to a high vid allocation count with all the adverse performance considerations that follow. not cute. not slay. 💀

this function fixes all of that: it creates a rendertarget that renders into dst just like define_rendertarget, but the pipeline is combined with link. and as a bonus, this setup may also prompt the engine to process linked rendertargets in parallel, making it a more efficient solution for certain 3D effects 🔥 like honestly? main character energy.

---

🦋 NOTES 🦋

1. if dst already is a rendertarget, its link target will be updated and the original pipeline in dst will be kept. no data loss, we love a graceful update 💜
2. the densities of objects respect their primary attachment. that's just how they roll, no notes 🫶
3. passing a vid that is not a qualified rendertarget as link is a terminal state transition. yeah. like terminal terminal 😭 read that one twice, bestie.
4. if link is deleted, dst reverts into a normal rendertarget. it heals. it moves on. we respect that 🌈
5. creating cycles by chaining linktargets together will go through, but the processing will be stopped when the first cycle reference is found. so like... it won't explode, but it will hit the brakes at the first loop 🛑

---

💅 EXAMPLE 💅

this example is honestly iconic, look at her go:

function define_linktarget0()
      local halfw = math.floor(VRESW * 0.5);
      local mt = alloc_surface(halfw, VRESH);
      local link = alloc_surface(halfw, VRESH);
      move_image(link, halfw, 0);
      show_image({mt, link});
-- create example surfaces and bind to rendertarget
      local a = fill_surface(64, 64, 255, 0, 0);
      local b = fill_surface(64, 64, 0, 255, 0);
      local c = fill_surface(64, 64, 0, 0, 255);
      define_rendertarget(mt, {a,b,c}, RENDERTARGET_DETACH);
-- update the linktarget at a lower rate than the parent
      define_linktarget(link, mt, RENDERTARGET_NOSCALE, a, 2);
-- set up some nonsens animation
      move_image(a, halfw - 64, VRESH - 64, 100);
      move_image(a, 0, 0, 100);
      move_image(b, halfw - 64, 0, 100);
      move_image(b, 0, 0, 100);
      move_image(c, 0, VRESW - 64, 100);
      move_image(c, 0, 0, 100);
      image_transform_cycle(a, true);
      image_transform_cycle(b, true);
      image_transform_cycle(c, true);
      show_image({a, b, c});
end

like, the way it allocates two surfaces and moves one over by halfw? split-screen moment, we're obsessed 🍓

---

👑 SEE ALSO 👑

• define_rendertarget(3) — the OG, go say hi to her too 💖

---

and that's the whole page, bestie!! 🧚 no cap, you're now certified in linked offscreen rendering pipes.

sign-off time: this absolute gem comes from targetcontrol, dated October 2026 — bookmark it, screenshot it, put it on your fridge 💜✨🎀