text_surface(3)

✨ text_surface 💅

okay bestie, so this is the manual page for text_surface — which, no cap, makes a simplified text video object. and it's from the Library Functions Manual, which is giving very much "important stuff lives here" energy 🎀

---

🌸 NAME 🌸

text_surface — create a simplified text video object ✨

---

🦋 SYNOPSIS 🦋

vid
text_surface( int:rows, int:cols, vid:inplace, table:rowtable )

---

💖 DESCRIPTION 💖

okay so here's the tea 🍓: this whole thing creates a surface backed by a TUI screen that has rows and cols as its maximum dimensions. lowkey it's a cheaper form of render_text — literally the budget-friendly sibling — and you'd use it when you wanna keep text contents around for later querying and modification, without dealing with the parsing complexity and volatility of render_text. because render_text is a lot, and we respect that, but sometimes you just want the simple life 💅

the contents of rowtable is a table for each row to populate, and you can optionally pass an int:y and int:x to skip straight to specific positions — which is the move when you don't wanna fill your life (or your table) with a bunch of empty cells 🙈. each n-indexed entry in the rowtable can be either a string or an attribute table, and those are both covered below ⬇️

the storage representation and the cursor state of the surface? fully accessible through image_access_storage, as if it was an external frameserver with a tpack backed storage. slay 👑

⚠️ heads up bestie: this is still marked experimental, because some details are yet to be fleshed out and are subject to change. mainly: how one can alter the internal font representation (it currently uses the set default system font), getting feedback on shaped line offsets, and querying for picking, shaping, processing direction and ligature substitutions. so don't come for me if it shifts around, fr fr 😭

---

🔥 EXAMPLE 🔥

-- @group: image
-- @cfunction: textsurface
-- @related: render_text, image_access_storage
function text_surface0()
      show_image(text_surface(1, 10, {{"hi there"}}))
end

---

⭐ EXAMPLE (yes, another one, we eat) ⭐

-- @group: image
-- @cfunction: textsurface
-- @related: render_text, image_access_storage
function text_surface1()
      show_image(text_surface(1, 10, {{"hi", {bold = true, fr = 255, fg = 0, fb = 0}, "there"}})
end

notice how this second one mixes a plain string "hi" with a whole attribute table (bold = true, fr = 255, fg = 0, fb = 0) and then another string "there" — it's giving styled text main character energy 🔥

---

alright bestie, that's the whole page 🫶 this little gem came to you from the Arcan Lua API, dated October 2026 — so like, future iconic behavior 💜 go forth and make text surfaces, you've got this ✨💅