load_image(3)

💅 load_image(3) — Arcan Lua API 🎀

okay bestie, welcome to load_image(3), the Arcan Lua API page that's about to make synchronous image loading your whole personality. it's giving "just get the picture on screen already" and honestly? iconic.

---

✨ NAME ✨

load_image — synchronously load supported images. yes, synchronously. we'll get to what that means for your vibes in a sec 🫶

---

🌸 SYNOPSIS 🌸

VID, fail:BADID
load_image( resource, startzv, desired width, desired height )

so you hand it a resource, a startzv, a desired width and a desired height, and it hands you back a VID — or it flops and you get fail:BADID. no cap, that's the whole deal 💜

---

🦋 DESCRIPTION 🦋

this routine sets up a brand new video object container and then attempts to load and decode an image from the resource you specified. key word: attempts. it's out here trying its best, and if the resource says no, you get fail:BADID in your life 😭

---

🧚 NOTES 🧚

1. the new VID has its opacity set to 0 — so it's hidden by default. it exists, it's just shy 🙈
2. this routine is synchronous, so it will block until the image has been loaded. like, fully stops and waits. no multitasking, no side quests, just vibes and decoding ⏳
3. desired width / desired height are capped to the engine compile-time values CONST_MAX_SURFACEW and CONST_MAX_SURFACEH (2048x2048). so dream big, but 2048x2048 is the ceiling, periodt 💅
4. if the engine is running in conservative mode, no local copy will be kept in memory and the resource will be reloaded on every operation that manipulates the current rendering context (e.g. stack push / pop or launch_target(external)). lowkey high maintenance, but that's the tradeoff 🫠
5. supported file formats vary with platform and engine build — the only ones guaranteed to work are PNG and JPEG. anything else is a gamble, and ngl we don't gamble with guarantees 🎰

---

🔥 EXAMPLE 🔥

function load_image0()
      vid = load_image("test.png");
      show_image(vid);
      vid2 = load_image("test.png", 2, 48, 48);
      show_image(vid);
end

look at her go 😌 first one loads test.png with defaults, shows it. then vid2 loads the same test.png with startzv of 2 and 48x48 dimensions — and then the example calls show_image(vid) again. yes, vid. we're showing you exactly what's written, bestie, no fixing ✨

---

💀 MISUSE 💀

function load_image0()
      vid = load_image();
end

called it with zero arguments. no resource. that's not a vibe check, that's a vibe fail 🚫

function load_image1()
      vid = load_image("test.png", -1, -1, -1);
end

negative startzv, negative width, negative height. like... why are we doing this. don't do this 🙈

---

👑 SEE ALSO 👑

• load_image_asynch(3) — the chill, non-blocking cousin. go say hi 🌈

---

and that's the whole page, bestie 💖 this little gem lives in the image manual, October 2026 edition, straight out of the Arcan Lua API — go load some pixels, synchronously, and slay ⭐🎀💜