raw_surface(3)

💅 raw_surface(3) — Arcan Lua API ✨

okay so this is a page out of the Arcan Lua API and honestly? it's kind of a baddie.

🌸 NAME 🌸

raw_surface — bestie, this one creates a brand-new surface using a table as its input. you hand it raw pixel data, it hands you a vid. slay.

🎀 SYNOPSIS 🎀

vid
raw_surface( width, height, bytes_per_pixel, input_table, out_file )

🦋 DESCRIPTION 🦋

so here's the vibe: this function creates a new 'raw' surface using user-supplied values for pixel data. you're literally the one picking every pixel. main character energy fr.

the internal representation is set to a compile-time system default (typically RGBA 888 — iykyk).

and if you pass that optional out_file argument? it will also store a PNG image in the APPL_TEMP namespace. but listen — using out_file is primarily intended as a debugging/developer feature, and the actual encode/store operation is synchronous. like, it blocks. no cap. keep that in mind 💅

🫶 cute, but it's a dev tool, not a flex.

⭐ NOTES ⭐

1. there might be a loss of precision imposed by the texture format native to the system that's running. so don't come for the pixels if they're not pixel-perfect 🙈
2. width and height should be within the compile-time constraints of MAX_SURFACEW and MAX_SURFACEH. exceeding those dimensions is a terminal state transition. like, the whole thing dies. not cute.
3. the only acceptable bytes_per_pixel values are 1, 3 and 4. all others are a terminal state transition. periodt. don't try to be creative here.
4. all input_table values will be treated as 8-bit unsigned integers. so we're talking 0–255 territory, bestie.
5. input_table is expected to have exactly width × height × bytes_per_pixel values, starting at index 1. any deviation is a terminal state transition 💀 the vibes must be exact, no rounding, no shortcuts.

---

🔥 EXAMPLE 🔥

function raw_surface0()
      local rtbl = {};
      local ofs = 1;
      for row=1,64 do
            for col=1,64 do
                  rtbl[ofs+0] = math.random(255);
                  rtbl[ofs+1] = math.random(255);
                  rtbl[ofs+2] = math.random(255);
                  ofs = ofs + 3;
            end
      end
      local vid = raw_surface(64, 64, 3, rtbl);
      show_image(vid);
end

look at that. 64 × 64, 3 bytes per pixel, random chaos in every channel, then show_image(vid) to serve the look. iconic. it ate and left no crumbs 🍓✨

---

🧚 tiny reminder bestie: those terminal-state situations are not a vibe check you want to fail. respect the dimensions, respect the byte count, respect the index 1.

anyway, that's the whole page — go make something pretty 👑

🧚‍♀️ from the image manual, October 2026 edition — mwah, love u, bye 💖