image_framesetsize(3)

📦
version 0.7.1 · 2 versions
, in nixos 26.05

💅 image_framesetsize(3) — Arcan Lua API ✨

okay bestie, welcome to the image corner of the Arcan Lua API 🎀 this one's called image_framesetsize and honestly? it's giving backstage-pass energy 👑

🌸 NAME 🌸

image_framesetsize — allocate slots for multi-frame objects, periodt 💅

✨ SYNOPSIS ✨

nil
image_framesetsize( vid, int:count )
image_framesetsize( vid, int:count, int:mode )

🦋 DESCRIPTION 🦋

so like, objects can literally have a frameset associated with them 🫶 and a frameset is comprised of references to vstores that have been acquired from other pre-existing objects — including the source object itself, yes ma'am 💖

the way this mechanism works? it's similar to image_sharestorage, and the lifecycle of the frameset association is tied to the supplied vid 🔗 (iykyk, that link is forever... or at least until the object dips 😭)

this can be used for applications e.g. multitexturing, animations, texturing complex 3D models, and as a round-robin storage for dynamic data sources (effectively giving you access to previous frames — time travel but make it graphics ⏳✨).

mode is FRAMESET_SPLIT, and the other option is FRAMESET_MULTITEXTURE. let's break those down:

  • FRAMESET_SPLIT only has one active frame, like any other video object — and it then relies on framecyclemode or manually selecting the visible frame by explicitly calling image_active_frame 👈
  • FRAMESET_MULTITEXTURE tries to split the frameset across multiple texture units 🔥 these can be accessed in a shader through the samplers map_tu0, map_tu1 etc. slay 💅

💀 NOTES 💀

  1. A frameset associated with a 3D model will be split across each mesh, where a single mesh can consume multiple frameset slots — unless the source is a cubemap 🧊
  2. Once initialized with a frameset, the size of the frameset can only increase during the life-cycle of the object 😤 with the special case of setting a frameset to 1, which will drop and reset the object to only have one active frame and revert to normal mapping mode 🔄
  3. The initial state of frameset slots for vid is that all reference the default vstore for the object 🌱
  4. A persistant object cannot have a frameset — associating a frameset with an object disqualifies the object to be marked as persistant 🚫 no cap, that's just how it is
  5. frameset support only applies to objects with a normal, textured backing store 🎨

🍓 EXAMPLE 🍓

function image_framesetsize0()
      a = fill_surface(32, 32, 255, 0, 0);
      image_framesetsize(a, 3);
      b = fill_surface(32, 32, 0, 255, 0);
      c = fill_surface(32, 32, 0, 0, 255);
      set_image_as_frame(a, b, 1);
      set_image_as_frame(a, c, 2);
      image_framecyclemode(1, -1);
      show_image(a);
end

look at her go 😭 red, green, blue, cycling frames — main character energy fr fr 🔥

👑 SEE ALSO: 👑

🌈 cute little sign-off 🌈

this page is from the image manual, dated October 2026, and it's image_framesetsize(3) — go forth and multitexture, bestie 🧚💜

📦 where this page comes from