image_access_storage(3)

💅 image_access_storage(3) — or, how to peek inside a textured video object

okay so first things first, this whole thing lives in the Arcan Lua API corner of the universe, and it's genuinely one of those "small but mighty" functions. bestie, let me tell you everything 💖

---

✨ NAME ✨

image_access_storage — get limited, blocking access to the underlying backing store of a textured video object. no cap, that's the whole vibe.

---

🦋 SYNOPSIS 🦋

true or false
image_access_storage( vid, callback(vtbl:context, int:width, int:height)
)
image_access_storage( vid, callback(vtbl:context, int:width, int:height,
int:cols, int:rows) )

like, yes, it returns true or false, and yes, the callback signature can have two whole extra arguments. we love range 👑

---

🎀 DESCRIPTION 🎀

So. This function permits limited, blocking access to a backing store. the ~primary purpose~ (and honestly the whole reason it exists) is to give you quick access to trivial measurements without the overhead of setting up a calctarget and performing readbacks. it's giving "I just need one tiny number, please don't make me build a whole thing" energy ✨

The function returns false if the backing store was unavailable. and like, it can be unavailable, so pls handle that (more on this in the notes, keep reading 🫶).

The context argument is described in define_calctarget.

Now here's the fun part: if the callback provides cols and rows, it means the table represents a textual backing store rather than a pixel one. in that case, the following extra functions are available in context:

(and that's literally where the original page ends that sentence — there's a colon and then nothing. iconic honestly. just know that extra functions exist there and go read define_calctarget(3) for the deets 🧚)

---

💀 NOTES 💀

1. The table provided in the callback is only valid during the scope of the callback. creating aliases outside this scope and trying to use any table method is a terminal state transition that may be difficult to debug. fr fr, do not keep a reference to that table, it will not go well 😭
2. Most frameserver connections do not synchronize the contents of the backing store buffer, because of the added bandwidth cost of performing an extra copy each update. this behavior can be changed by calling target_flags and enable TARGET_VSTORE_SYNCH for the specific frameserver. iykyk 🔥
3. The backing store of a texture video object is not always available, particularly when the engine is running in conservative mode. make sure that your appl can handle scenarios where the backing store cannot be read. seriously, don't be that person 🙈
4. :read is only permitted on a tui backed store. calling it on a regular one is a terminal state transition. that's a no-no, bestie 💀

---

🌈 EXAMPLE 🌈

function image_access_storage0()
      img = fill_surface(32, 32, 255, 0, 0);
      image_access_storage(a, function(tbl, w, h)
            print(w, h, tbl:get(1, 1));
      end);
end

look at her go 🥹 (and yeah, the example uses a while the surface was stored in img — that's exactly how it's written on the page, so we're keeping it character for character, no editing, periodt 💅)

---

💜 SEE ALSO 💜

• define_calctarget(3) — go read this, it's where context is actually explained 🌸

---

so yeah. limited, blocking, occasionally unavailable, always a little dramatic. slay 💖

and that's the whole page — brought to you by the image manual, dated October 2026, with image_access_storage(3) living in both the header and the footer like the main character she is 👑✨