image_clip_on(3)

💅 image_clip_on(3) — like, the Arcan Lua API one, bestie

okay so real talk, this is a page from the Arcan Lua API manual and it's all about telling a video object how to clip. it's giving "boundaries, but make it graphics" 🎀

---

✨ NAME ✨

image_clip_on — literally just controlling clipping for a video object. that's the whole gig. 💖

---

🌸 SYNOPSIS 🌸

nil
image_clip_on( vid:image )
image_clip_on( vid:image, int:mode )
image_clip_on( vid:image, int:mode=CLIP_SHALLOW, vid:cliptgt )

---

🦋 DESCRIPTION 🦋

so this one changes the clipping mode for whatever video object image is pointing at. easy. 🫶

by default the mode is CLIP_ON, and ngl bestie, that's the expensive one — it's the main character, it costs more 💀. it uses a stencil buffer to draw the entire hierarchy that you built with link_image. so if you've got a complex hierarchy with possibly rotated objects in it? this is the one for you, it eats. 🔥

your other option is CLIP_SHALLOW. this one only uses the immediate parent, and it gets a fast-path assuming that both objects are rotated — because that whole situation can be solved by adjusting object size and texture coordinates alone. no stencil buffer drama, just vibes. ⭐

now, if a cliptgt is provided along with the CLIP_SHALLOW clipping mode, then a specific object gets used for calculating the clipping bounds instead of using the one that link_image specified. obsessed, honestly. 🙈 this is useful when you need a transform hierarchy, but with specific clipping anchors. iykyk. 💅

---

🎀 NOTES 🎀

1. if a clip target is set to a non-existing or otherwise bad object, or it becomes invalid through deletion, clipping will revert to the image parent as if no clip target had been specified. so like… it snaps back, no cap. 😭

---

🌈 EXAMPLE 🌈

function image_clip_on0()
      a = fill_surface(64, 64, 255, 0, 0);
      b = fill_surface(64, 64, 0, 255, 0);
      link_image(b, a);
      move_image(b, 32, 32);
      show_image({a,b});
      image_clip_on(b, CLIP_SHALLOW);
end

look at her go 😌 two 64×64 surfaces, one linked to the other, one moved to 32, 32, both shown, then image_clip_on(b, CLIP_SHALLOW) — iconic, no notes. 👑

---

💀 MISUSE 💀

function image_clip_on0()
      image_clip_on(BADID);
end

yeah. don't do this one. that's a BADID, bestie, not a valid image. we do not pass garbage ids, periodt. 🙅‍♀️

---

🫶 SEE ALSO 🫶

• image_clip_off(3) — the other half of the clipping saga, go read her too 💜

---

and that's the whole page, mwah 💋 — brought to you by the image manual, October 2026 edition, image_clip_on(3). slay, go clip something. ✨🧚