graphics
Provides functionality for loading and managing images, fonts, textures, and sprite meshes. Includes both JavaScript and C-implemented routines for creating geometry buffers, performing rectangle packing, etc.
make_sprite_mesh(sprites) function
:param oldMesh (optional): An existing mesh object to reuse/resize if possible. Given an array of sprites, build a single geometry mesh for rendering them.
sprites: An array of sprite objects, each containing .rect (or transform), .src (UV region), .color, etc.
Returns: A GPU mesh object with pos, uv, color, and indices buffers for all sprites.
make_sprite_queue(sprites, camera, pipeline, sort) function
Given an array of sprites, optionally sort them, then build a queue of pipeline commands. Each group with a shared image becomes one command.
sprites: An array of sprite objects.
camera: (unused in the C code example) Typically a camera or transform for sorting?
pipeline: A pipeline object for rendering.
sort: An integer or boolean for whether to sort sprites; if truthy, sorts by layer & texture.
Returns: An array of pipeline commands: geometry with mesh references, grouped by image.
make_text_buffer(text, rect, angle, color, wrap, font) function
Generate a GPU buffer mesh of text quads for rendering with a font, etc.
text: The string to render.
rect: A rectangle specifying position and possibly wrapping.
angle: Rotation angle (unused or optional).
color: A color for the text (could be a vec4).
wrap: The width in pixels to wrap text, or 0 for no wrap.
font: A font object created by graphics.make_font or graphics.get_font.
Returns: A geometry buffer mesh (pos, uv, color, indices) for rendering text.
rectpack(width, height, sizes) function
Perform a rectangle packing using the stbrp library. Return positions for each rect.
width: The width of the area to pack into.
height: The height of the area to pack into.
sizes: An array of [w,h] pairs for the rectangles to pack.
Returns: An array of [x,y] coordinates placing each rect, or null if they don't fit.
make_rtree() function
Create a new R-Tree for geometry queries.
Returns: An R-Tree object for quickly querying many rectangles or sprite bounds.
make_texture(data) function
Convert raw image bytes into an SDL_Surface object.
data: Raw image bytes (PNG, JPG, etc.) as an ArrayBuffer.
Returns: An SDL_Surface object representing the decoded image in RAM, for use with GPU or software rendering.
make_gif(data) function
Load a GIF, returning its frames. If it's a single-frame GIF, the result may have .surface only.
data: An ArrayBuffer containing GIF data.
Returns: An object with frames[], each frame having its own .surface. Some also have a .texture for GPU use.
make_aseprite(data) function
Load an Aseprite/ASE file from an array of bytes, returning frames or animations.
data: An ArrayBuffer containing Aseprite (ASE) file data.
Returns: An object containing frames or animations, each with .surface. May also have top-level .surface for a single-layer case.
cull_sprites(sprites, camera) function
Filter an array of sprites to only those visible in the provided camera’s view.
sprites: An array of sprite objects (each has rect or transform).
camera: A camera or bounding rectangle defining the view area.
Returns: A new array of sprites that are visible in the camera's view.
rects_to_sprites(rects, image) function
Convert an array of rect coords into sprite objects referencing a single image.
rects: An array of rect coords or objects.
image: An image object (with .texture).
Returns: An array of sprite objects referencing the 'image' and each rect for UV or position.
make_surface(dimensions) function
Create a blank surface in RAM.
dimensions: The size object {width, height}, or an array [w,h].
Returns: A blank RGBA surface with the given dimensions, typically for software rendering or icons.
make_cursor(opts) function
opts: An object with {surface, hotx, hoty} or similar.
Returns: An SDL_Cursor object referencing the given surface for a custom mouse cursor.
make_font(data, size) function
Load a font from TTF/OTF data at the given size.
data: TTF/OTF file data as an ArrayBuffer.
size: Pixel size for rendering glyphs.
Returns: A font object with surface, texture, and glyph data, for text rendering with make_text_buffer.
make_sprite() function
Create a new sprite object, storing default properties.
Returns: A new sprite object, which typically has .rect, .color, .layer, .image, etc.
make_line_prim(points, thickness, startCap, endCap, color) function
Build a GPU mesh representing a thick polyline from an array of points, using parsl or a similar library under the hood.
points: An array of [x,y] points forming the line.
thickness: The thickness (width) of the polyline.
startCap: (Unused) Possibly the type of cap for the start.
endCap: (Unused) Possibly the type of cap for the end.
color: A color to apply to the line.
Returns: A geometry mesh object suitable for rendering the line via a pipeline command.
is_image(obj) function
obj: An object to check.
Returns: True if 'obj' has a .texture and a .rect property, indicating it's an image object.
texture(path) function
Load or retrieve a cached image, converting it into a GPU texture. If 'path' is already an object, it’s returned directly.
path: A string path to an image file or an already-loaded image object.
Returns: An image object with {surface, texture, frames?, etc.} depending on the format.
tex_hotreload(file) function
Reload the image for the given file, updating the cached copy in memory and GPU.
file: The file path that was changed on disk.
Returns: None
get_font(path, size) function
Load a font from file if not cached, or retrieve from cache if already loaded.
path: A string path to a font file, optionally with ".size" appended.
size: Pixel size of the font, if not included in 'path'.
Returns: A font object with .surface and .texture for rendering text.
queue_sprite_mesh(queue) function
Builds a single geometry mesh for all sprite-type commands in the queue, storing first_index/num_indices so they can be rendered in one draw call.
queue: An array of draw commands, some of which are {type:'sprite'} objects.
Returns: An array of references to GPU buffers [pos,uv,color,indices].