# 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) <sub>function</sub>


: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) <sub>function</sub>


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) <sub>function</sub>


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) <sub>function</sub>


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() <sub>function</sub>


Create a new R-Tree for geometry queries.


**Returns**: An R-Tree object for quickly querying many rectangles or sprite bounds.


### make_texture(data) <sub>function</sub>


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) <sub>function</sub>


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) <sub>function</sub>


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) <sub>function</sub>


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) <sub>function</sub>


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) <sub>function</sub>


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) <sub>function</sub>




**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) <sub>function</sub>


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() <sub>function</sub>


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) <sub>function</sub>


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) <sub>function</sub>




**obj**: An object to check.


**Returns**: True if 'obj' has a .texture and a .rect property, indicating it's an image object.


### texture(path) <sub>function</sub>


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) <sub>function</sub>


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) <sub>function</sub>


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) <sub>function</sub>


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].