alloc_surface(3)

💖 alloc_surface(3) 💖

okay so real quick — this page is from the Arcan Lua API manual, and it's genuinely one of the handiest little calls in the whole thing, so buckle up bestie 🎀

---

✨ NAME ✨

alloc_surface — creates an empty, non-visible surface with a preset storage. that's it, that's the whole vibe 💅

---

🦋 SYNOPSIS 🦋

vid
alloc_surface( int:width, int:height )
alloc_surface( int:width, int:height, bool:noalpha )
alloc_surface( int:width, int:height, bool:noalpha, int:quality )

three flavours, pick your fighter 💜

---

🌸 DESCRIPTION 🌸

so like, some operations — especially record and rendertargets — literally need a storage buffer to work with. they can't just manifest one out of pure main character energy, they need somewhere to put pixels.

now, you could use fill_surface for those operations too, but alloc_surface is giving efficiency queen: it results in one less transfer. and optionally you get some control over the storage format and quality. obsessed. 🔥

here's the tea on the args:

• if noalpha is set (true, !0) the texture format for the underlying backing store will be set to one where the alpha channel corresponds to fullbright (ignore/nobright). no half-transparent nonsense, we're going full send 💀
• quality can be set to one of the following:
  • ALLOC_QUALITY_LOW
  • ALLOC_QUALITY_NORMAL
  • ALLOC_QUALITY_HIGH
  • ALLOC_QUALITY_FLOAT 16
  • ALLOC_QUALITY_FLOAT 32

---

🧚 NOTES 🧚

1. only ALLOC_QUALITY_NORMAL is guaranteed to be a valid target for map_video_display and similar operations. the others are living dangerously, and honestly? respect. 🙈
2. note that not all storage modes will support all forms of filtering, or mipmapping. if in doubt, disable vfilter and manually sample in a shader. ngl that's the safe play, no cap ✨

heads up bestie — those two notes are the difference between "slay" and "why is my render target doing that". read them twice. 🫶

---

⭐ EXAMPLE ⭐

function alloc_surface0()
      local vid = fill_surface(640, 480);
      assert(vid ~= BADID)
      print("allocated: ", vid, 640, 480);
      show_image(vid);
end

look at her go 😭 allocating at 640 × 480, checking it against BADID like a responsible icon, printing, then show_image. we love a full pipeline. 👑

---

💀 MISUSE 💀

function alloc_surface0()
      fill_surface(-1, -1);
end

negative dimensions? absolutely not. that's a vibe check failure fr fr 🙈

---

💀 MISUSE 💀

function alloc_surface1()
      fill_surface(1000000, 100000000);
end

a million by a hundred million. bestie. bestie. that is not a surface, that's a cry for help 😭 your GPU is not ok

---

🌈 SEE ALSO: 🌈

• image

---

okay that's the whole page, you're officially caught up 💖 stay hydrated, keep your quality at ALLOC_QUALITY_NORMAL unless you know exactly what you're doing, and remember: this gem comes to you from the Arcan Lua API manual, dated October 2026 — see you in the next group chat, mwah 🎀💜🦋