image_tesselation(3)

💅 image_tesselation(3) — the Arcan Lua API glow-up 🎀

okay bestie, buckle up — this one's from the Arcan Lua API and it's lowkey one of the most fun ones. no cap. ✨

---

✨ NAME ✨

image_tesselation — change up the tesselation level of a vid, that's the whole vibe 💫

---

🌸 SYNOPSIS 🌸

nil
image_tesselation( vid:id )
image_tesselation( vid:id, func:callback )
image_tesselation( vid:id, float:s, float:t )
image_tesselation( vid:id, float:s, float:t, bool:depth )
image_tesselation( vid:id, float:s, float:t, func:callback )
image_tesselation( vid:id, float:s, float:t, bool:depth, func:callback )

---

🦋 DESCRIPTION 🦋

so what does it do?? it takes a regular old vid and turns it into a pseudo-3D object — like, it becomes a tesselated plane with s steps in one dimension and t steps in the other. it's giving glow-up fr fr. 🫶

this is for very specific effects, either on its own or when you pair it with a vertex shader stage. it's also useful when you need to show a sparsely populated area efficiently as a point-cloud — without all the setup of a 3D pipeline and a rendertarget. efficiency queen 👑

set s or t to 1 and boom, tesselation is disabled and the underlying mesh shape gets deallocated. but if you update the mesh shape to s > 1 and t > 1, it regenerates and repopulates the individual attributes for vertices and texture coordinates. it's literally reborn 💀✨

and here's a cute one: set the boolean depth argument (the one that comes after the s and t forms) to false and image drawing won't need a depth buffer at all — which avoids the costly switch between 2D and 3D style processing. your perf said thank you 🥹

🌈 where stuff ends up

• the vertices get distributed in the -1..1 range — so -1,-1 sits in the upper left corner and 1,1 in the lower right
• the texture coordinates go in the 0..1 range, with 0,0 at the upper left corner

💜 the callback storage situation

the storage can be accessed through the optional callback, and it has the signature of (refobj, n_vertices, vertex_size) where refobj is a userdata table that supports all of this:

• :vertices(ind) => x, y, z, w / :vertices(ind, x, y, z, w) => nil — for fetching and updating, with xyzw matching vertex_size (=2, only xy; =3 only xyz; => w,y,z)
• :colors(ind) => r, g, b, a / :colors(ind, new_r, new_g, new_b, new_a) — for fetching, activating and updating vertex colors
• :texcos(ind, set_ind) => s, t / :texcos(ind, set_ind, new_s, new_t) — aliased as :texture_coordinates for fetching and updating texture coordinates; set_ind should be 0 or 1 since there are two possible sets of texture coordinates per vertex
• :primitive_type(0 or 1) — for switching between triangle soup (0) and point-cloud (1) when rendering

and if any of these storage blocks doesn't exist yet? an attempt to set an index will force it to be allocated. slay, self-healing data structures 💅

🧚 the index situation

the plane is indexed, and you can manipulate the individual indices to create degenerate triangles that get discarded — super useful for 'slice out' parts of the plane. you get at them like this:

:indices(ind) => p1x, p1y, p2x, p2y, p2z, p3x, p3y, p3z
:indices(ind, p1x, p1y, p2x, p2y, p2z, p3x, p3y, p3z)

that's for a vertex size of 3. if the vertex size is 2, omitt the z arguments. (yes, "omitt" — we keep the lore intact 🫡)

---

🍓 NOTES 🍓

1. picking operations like image_hit do not take tesselation into account. this may be subject to change. so like, don't come for her, she knows 😭
2. (nothing here bestie, it's just vibes)

---

🔥 EXAMPLE 🔥

function image_tesselation0()
      local tess = fill_surface(64, 64, 0, 255, 0);
      show_image(tess);
      image_tesselation(tess, 32, 32,
            function(obj, n_v, size)
                  obj:primitive_type(1);
            end
      );
end

look at her go — a 64x64 surface, tesselated 32 by 32, and the callback flips her to point-cloud mode with :primitive_type(1). main character energy, honestly 👑

---

👀 SEE ALSO 👀

• image — go read that one too, iykyk 💖

---

that's the whole page!! source version is from October 2026 and it ships with the image family, mwah 💋 — now go tesselate something iconic, bestie. 🦋💜