279 lines
6.8 KiB
Markdown
279 lines
6.8 KiB
Markdown
# 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].
|
||
|