From 30c5da879bc47ed0c5f7fce7886ab9428ceb7872 Mon Sep 17 00:00:00 2001 From: John Alanbrook Date: Thu, 27 Feb 2025 16:51:48 -0600 Subject: [PATCH] fix various graphics and sound issues --- meson.build | 7 +- scripts/core/doc.js | 1166 ++++++++++++++++++++++++++++++++ scripts/core/engine.js | 1210 +--------------------------------- scripts/modules/graphics.js | 80 ++- scripts/modules/resources.js | 15 +- source/qjs_soloud.c | 8 +- 6 files changed, 1258 insertions(+), 1228 deletions(-) create mode 100644 scripts/core/doc.js diff --git a/meson.build b/meson.build index 39be1d07..c55bb047 100644 --- a/meson.build +++ b/meson.build @@ -117,10 +117,7 @@ quickjs_opts += 'default_library=static' deps += dependency('quickjs', static:true, default_options:quickjs_opts) -storefront = get_option('storefront') -if storefront == 'steam' - deps += dependency('qjs-steam',static:false) -endif +#deps += dependency('qjs-steam', static:false) deps += dependency('qjs-layout',static:true) deps += dependency('qjs-miniz',static:true) @@ -135,8 +132,6 @@ deps += dependency('chipmunk', static:true) deps += dependency('enet', static:true) deps += dependency('soloud', static:true) -#deps += dependency('qjs-chipmunk', static:false) - sources = [] src += ['anim.c', 'config.c', 'datastream.c','font.c','HandmadeMath.c','jsffi.c','model.c','render.c','script.c','simplex.c','spline.c', 'timer.c', 'transform.c','prosperon.c', 'wildmatch.c', 'sprite.c', 'rtree.c', 'qjs_dmon.c', 'qjs_nota.c', 'qjs_enet.c', 'qjs_soloud.c'] diff --git a/scripts/core/doc.js b/scripts/core/doc.js new file mode 100644 index 00000000..6e891077 --- /dev/null +++ b/scripts/core/doc.js @@ -0,0 +1,1166 @@ +prosperon.c_types.sprite[prosperon.DOC] = {} +prosperon.c_types.sprite[prosperon.DOC][prosperon.DOC] = `A 'sprite' is a simple struct for 2D drawing. It stores a rectangle (pos + size), +UV coordinates, color, and layer, as well as an associated 'image' object. The sprite +can be drawn via GPU or SDL_Renderer. Freed when no JS references remain. +`; + +prosperon.c_types.sprite[prosperon.DOC].set_affine = `Update this sprite's position and size from a transform's pos and scale. + +:param transform: The transform whose pos/scale will overwrite the sprite's rect. +:return: None +`; + +prosperon.c_types.sprite[prosperon.DOC].set_rect = `Set the sprite's rect (x, y, w, h) directly. + +:param rect: An object or array specifying x, y, width, and height. +:return: None +`; + +prosperon.c_types.sprite[prosperon.DOC].set_image = `Assign or replace the sprite's underlying image. Automatically updates UV if +the image has a 'rect' property. + +:param image: A JS object representing the image (with .texture, .rect, etc.). +:return: None +`; + +prosperon.c_types.sprite[prosperon.DOC].layer = `Get or set the sprite's z-layer integer. Sprites with higher layers typically +draw on top of lower layers. + +:param value: (when setting) An integer specifying the layer. +:return: The current layer (when getting), or None (when setting). +`; + +prosperon.c_types.sprite[prosperon.DOC].color = `Get or set the sprite's color tint as [r, g, b, a]. + +:param value: (when setting) An array [r, g, b, a] in the 0.0..1.0 range. +:return: The current color array (when getting), or None (when setting). +`; + + +// +// transform +// +prosperon.c_types.transform[prosperon.DOC] = {} +prosperon.c_types.transform[prosperon.DOC][prosperon.DOC] = `A hierarchical transform storing 3D or 2D position, rotation (as a quaternion), +and scale. Can have a parent transform. Freed automatically on GC. +`; + +prosperon.c_types.transform[prosperon.DOC].pos = `Get or set the transform's position as a 3D vector [x, y, z]. + +:param value: (when setting) [x, y, z]. +:return: The current position vector (when getting), or None (when setting). +`; + +prosperon.c_types.transform[prosperon.DOC].scale = `Get or set the transform's scale as a 3D vector [x, y, z]. +For 2D usage, z is often 1. + +:param value: (when setting) [sx, sy, sz]. +:return: The current scale (when getting), or None (when setting). +`; + +prosperon.c_types.transform[prosperon.DOC].rotation = `Get or set the transform's rotation as a quaternion [x, y, z, w]. +Angles in degrees or radians must first be converted prior to making a quaternion. + +:param value: (when setting) [qx, qy, qz, qw]. +:return: The current quaternion (when getting), or None (when setting). +`; + +prosperon.c_types.transform[prosperon.DOC].parent = `Get or set the transform's parent. If set, this transform becomes a child of +the parent (re-parenting). Must be another transform object or undefined. + +:param value: (when setting) Another transform or undefined. +:return: The current parent transform (when getting), or None (when setting). +`; + +prosperon.c_types.transform[prosperon.DOC].change_hook = `A user-supplied function that's called whenever the transform's local matrix changes. +If undefined, no hook is called. + +:param value: (when setting) A function. +:return: The current function or undefined. +`; + +prosperon.c_types.transform[prosperon.DOC].trs = `Set the transform's position, rotation, and scale in one call. + +:param pos: [x,y,z] for position, or undefined to keep existing. +:param quat: [qx,qy,qz,qw] for rotation, or undefined. +:param scale: [sx,sy,sz] for scale, or undefined. +:return: None +`; + +prosperon.c_types.transform[prosperon.DOC].phys2d = `Apply simple 2D velocity and angular velocity to this transform. + +:param velocity: [vx, vy] added to 'pos' each frame. +:param angularVel: A scalar for rotation in (radians/second). +:param dt: The time delta in seconds. +:return: None +`; + +prosperon.c_types.transform[prosperon.DOC].move = `Translate this transform by the specified vector. + +:param delta: [dx, dy, dz] to add to .pos +:return: None +`; + +prosperon.c_types.transform[prosperon.DOC].rotate = `Rotate this transform by an axis+angle. + +:param axis: [ax, ay, az] the axis of rotation. +:param angle: The angle in turns or radians (depending on usage). +:return: None +`; + +prosperon.c_types.transform[prosperon.DOC].angle = `Return the transform's rotation about a specified axis (x, y, or z). +For example, angle([1,0,0]) returns the roll about the X-axis. + +:param axis: Which axis [1,0,0] or [0,1,0] or [0,0,1]. +:return: The numeric angle in 'turns' or radians, depending on usage. +`; + +prosperon.c_types.transform[prosperon.DOC].lookat = `Rotate this transform so it looks toward the given world position. + +:param target: [x, y, z] position in world coords. +:return: None +`; + +prosperon.c_types.transform[prosperon.DOC].direction = `Rotate a vector by this transform's rotation, effectively "transforming" +a direction from local space to world space. + +:param localDir: [dx, dy, dz] in local transform coordinates. +:return: [dx', dy', dz'] direction in world space. +`; + +prosperon.c_types.transform[prosperon.DOC].unit = `Reset position, rotation, and scale to [0,0,0], identity rotation, and [1,1,1]. + +:return: None +`; + +prosperon.c_types.transform[prosperon.DOC].rect = `Set this transform's pos and scale from a 2D rect object {x, y, w, h}. + +:param rect: Object with .x, .y, .w, .h +:return: None +`; + +prosperon.c_types.transform[prosperon.DOC].array = `Return this transform's matrix as a 16-element float array in column-major order. + +:return: An array of 16 floats. +`; + +prosperon.c_types.transform[prosperon.DOC].torect = `Convert transform's 2D position/scale to a rect {x, y, w, h}. +Rotation is currently ignored. + +:return: A rect object {x, y, w, h}. +`; + +prosperon.c_types.transform[prosperon.DOC].children = `Return an array of child transforms belonging to this transform. + +:return: An array of transform objects. +`; + + +// +// font +// +prosperon.c_types.font[prosperon.DOC] = {} +prosperon.c_types.font[prosperon.DOC][prosperon.DOC] = `A bitmap or TTF-based font object storing glyph data. +Used for measuring/drawing text. Freed when GC sees no references. +`; + +prosperon.c_types.font[prosperon.DOC].linegap = `Get or set the font's additional line spacing above the built-in metrics. + +:param value: (when setting) The new line gap. +:return: The current line gap (when getting), or None (when setting). +`; + +prosperon.c_types.font[prosperon.DOC].height = `The baseline-to-baseline height in pixels. + +:return: The font's total height in px. +`; + +prosperon.c_types.font[prosperon.DOC].ascent = `How far above the baseline the font extends. + +:return: A scalar float for ascent. +`; + +prosperon.c_types.font[prosperon.DOC].descent = `How far below baseline the font extends. + +:return: A scalar float for descent. +`; + +prosperon.c_types.font[prosperon.DOC].text_size = `Measure a piece of text's width/height when rendered with this font. + +:param text: The string to measure. +:param letterSpacing: Extra spacing between characters. +:param wrap: If nonzero, word-wrap to this maximum width. +:return: [width, height] as a float array. +`; + + +// +// datastream +// +prosperon.c_types.datastream[prosperon.DOC]= {} +prosperon.c_types.datastream[prosperon.DOC][prosperon.DOC] = `A streaming media handle, typically for MPEG video. Freed automatically. +`; + +prosperon.c_types.datastream[prosperon.DOC].time = `Return the current playback time in seconds. + +:return: Current time as a float in seconds. +`; + +prosperon.c_types.datastream[prosperon.DOC].seek = `Seek to the specified time (in seconds). + +:param seconds: The time to jump to in the stream. +:return: None +`; + +prosperon.c_types.datastream[prosperon.DOC].advance = `Advance by a certain number of seconds, decoding video as needed. + +:param seconds: The amount of time to skip forward. +:return: None +`; + +prosperon.c_types.datastream[prosperon.DOC].duration = `Return the total duration of the video stream, in seconds, if known. + +:return: Float seconds duration, or 0 if unknown. +`; + +prosperon.c_types.datastream[prosperon.DOC].framerate = `Return the framerate (FPS) of the stream if known. + +:return: Float frames per second, or 0 if unknown. +`; + +prosperon.c_types.datastream[prosperon.DOC].callback = `A function to call whenever a new frame is decoded. If not set, no callback is invoked. + +:param fn: (when setting) A function that receives (surface). +:return: The existing function or undefined if none. +`; + + +// +// timer +// +prosperon.c_types.timer[prosperon.DOC] = {} +prosperon.c_types.timer[prosperon.DOC][prosperon.DOC] = `A scheduled callback or countdown. Freed automatically once no longer referenced +or once it completes. +`; + +prosperon.c_types.timer[prosperon.DOC].remain = `Get or set how many seconds remain before the timer triggers. + +:param value: (when setting) A float specifying new time remaining. +:return: The current time left (when getting), or None (when setting). +`; + +prosperon.c_types.timer[prosperon.DOC].fn = `Get or set the function called when the timer expires. + +:param value: (when setting) The function. +:return: The function or undefined if none is set. +`; + + +// +// rtree +// +prosperon.c_types.rtree[prosperon.DOC] = {} +prosperon.c_types.rtree[prosperon.DOC][prosperon.DOC] = `An R-tree for spatial lookups. Insert bounding boxes, query by bounding box, etc. +`; + +prosperon.c_types.rtree[prosperon.DOC].add = `Insert an object that has a 'rect' property {x, y, w, h} into the tree. + +:param obj: The object to add (must have rectAtom). +:return: None +`; + +prosperon.c_types.rtree[prosperon.DOC].delete = `Remove an object from the tree. Must match the same rect as used when adding. + +:param obj: The object to remove. +:return: None +`; + +prosperon.c_types.rtree[prosperon.DOC].query = `Return an array of objects whose bounding boxes intersect the given rect. + +:param rect: {x, y, w, h} bounding region to query. +:return: Array of objects that overlap that region. +`; + +prosperon.c_types.rtree[prosperon.DOC].size = `Indicates how many items are stored in the rtree. + +:return: Integer count of items in the tree. +`; + +prosperon.c_types.rtree[prosperon.DOC].forEach = `Call a function for every item in the rtree. + +:param callback: A function called with no arguments, or possibly (item). +:return: None +`; + +prosperon.c_types.rtree[prosperon.DOC].has = `Return true if the specified object is in the tree, false otherwise. + +:param obj: The object to check. +:return: True if found, else false. +`; + +prosperon.c_types.rtree[prosperon.DOC].values = `Return an array of all items currently in the rtree. + +:return: Array of all stored objects. +`; + + +// +// PHYSFS_File +// +prosperon.c_types.PHYSFS_File[prosperon.DOC] = {} +prosperon.c_types.PHYSFS_File[prosperon.DOC][prosperon.DOC] = `A file handle opened via PhysFS for writing or reading. Freed automatically when references go away. +`; + +prosperon.c_types.PHYSFS_File[prosperon.DOC].close = `Close this file handle. Throws on error. + +:return: None +`; + +prosperon.c_types.PHYSFS_File[prosperon.DOC].write = `Write data (string or ArrayBuffer) to the file. Throws on error. + +:param data: The data to write (string or ArrayBuffer). +:return: None +`; + +prosperon.c_types.PHYSFS_File[prosperon.DOC].buffer = `Enable an internal write buffer of the given size on this file. + +:param size: Size in bytes of the buffer. +:return: None +`; + +prosperon.c_types.PHYSFS_File[prosperon.DOC].tell = `Return the current position in the file. + +:return: A numeric offset. +`; + +prosperon.c_types.PHYSFS_File[prosperon.DOC].eof = `Return whether the file pointer is at end-of-file. + +:return: True if at EOF, false otherwise. +`; + + +// +// SDL_Camera +// +prosperon.c_types.SDL_Camera[prosperon.DOC] = {} +prosperon.c_types.SDL_Camera[prosperon.DOC][prosperon.DOC] = `A handle to a physical camera device. Freed when references drop or camera is closed. +`; + +prosperon.c_types.SDL_Camera[prosperon.DOC].frame = `Acquire the latest camera frame (as an SDL_Surface). Returns undefined if no +new frame is available yet. Throws on error. + +:return: SDL_Surface or undefined. +`; + +prosperon.c_types.SDL_Camera[prosperon.DOC].release_frame = `Release a frame surface previously acquired via camera.frame(). Must be +done for each acquired frame. + +:param surface: The surface to release. +:return: None +`; + + +// +// SDL_Cursor +// +prosperon.c_types.SDL_Cursor[prosperon.DOC] = {} +prosperon.c_types.SDL_Cursor[prosperon.DOC][prosperon.DOC] = `An SDL cursor handle. Freed automatically on GC. No direct methods. +`; + + +// +// SDL_Thread +// +prosperon.c_types.SDL_Thread[prosperon.DOC] = {} +prosperon.c_types.SDL_Thread[prosperon.DOC][prosperon.DOC] = `A handle to an SDL-created thread. Freed on GC after join. + +Note: The engine generally doesn't expose custom usage for threads. +`; + +prosperon.c_types.SDL_Thread[prosperon.DOC].wait = `Block until this thread terminates. + +:return: None +`; + + +// +// SDL_Window +// +prosperon.c_types.SDL_Window[prosperon.DOC] = {} +prosperon.c_types.SDL_Window[prosperon.DOC][prosperon.DOC] = `An application window, created via prosperon.engine_start or SDL calls. Freed on GC. +`; + +prosperon.c_types.SDL_Window[prosperon.DOC].fullscreen = `Toggle fullscreen mode for this window (SDL_WINDOW_FULLSCREEN). + +:return: None +`; + +prosperon.c_types.SDL_Window[prosperon.DOC].make_renderer = `Create an SDL_Renderer for 2D rendering tied to this window. + +:param name: The renderer driver name, e.g. "opengl" (may be optional). +:return: An SDL_Renderer object. +`; + +prosperon.c_types.SDL_Window[prosperon.DOC].make_gpu = `Create an SDL_GPUDevice for low-level GPU rendering on this window. + +:param debug: If true, enable debugging in the GPU device. +:param driverName: The GPU back-end driver, e.g. "opengl". +:return: An SDL_GPUDevice. +`; + +prosperon.c_types.SDL_Window[prosperon.DOC].keyboard_shown = `Return whether the on-screen keyboard is visible (mobile/tablet). + +:return: True if shown, false otherwise. +`; + +prosperon.c_types.SDL_Window[prosperon.DOC].theme = `Currently returns undefined. Placeholder for retrieving OS window theme info. + +:return: undefined +`; + +prosperon.c_types.SDL_Window[prosperon.DOC].safe_area = `Return a rect describing any OS-specific "safe" region for UI, e.g. on iPhone with a notch. + +:return: A rect object {x, y, w, h}. +`; + +prosperon.c_types.SDL_Window[prosperon.DOC].bordered = `Enable or disable window borders. + +:param flag: True to show borders, false to hide. +:return: None +`; + +prosperon.c_types.SDL_Window[prosperon.DOC].set_icon = `Set the window's icon from an SDL_Surface. + +:param surface: An SDL_Surface holding the icon. +:return: None +`; + +prosperon.c_types.SDL_Window[prosperon.DOC].mouse_grab = `Grab or ungrab the mouse for this window (so the pointer won't leave). + +:param flag: True to grab mouse input, false to release. +:return: None +`; + +prosperon.c_types.SDL_Window[prosperon.DOC].title = `Get or set the window's title text in the title bar. + +:param newTitle: (when setting) A string title. +:return: The current title if getting, or None if setting. +`; + +prosperon.c_types.SDL_Window[prosperon.DOC].size = `Get or set the window's size as [width, height]. + +:param newSize: (when setting) e.g. [640, 480] +:return: The current [width, height] or None if setting. +`; + + +// +// SDL_Renderer +// +prosperon.c_types.SDL_Renderer[prosperon.DOC] = {} +prosperon.c_types.SDL_Renderer[prosperon.DOC][prosperon.DOC] = `A 2D rendering context using the SDL renderer API. Freed automatically. +`; + +prosperon.c_types.SDL_Renderer[prosperon.DOC].draw_color = `Set the render draw color for subsequent primitive calls (rect, line, etc.). + +:param color: [r, g, b, a] in 0..1. +:return: None +`; + +prosperon.c_types.SDL_Renderer[prosperon.DOC].present = `Display whatever has been rendered (swap buffers). Must be called each frame. + +:return: None +`; + +prosperon.c_types.SDL_Renderer[prosperon.DOC].clear = `Clear the current render target with the renderer's draw color. + +:return: None +`; + +prosperon.c_types.SDL_Renderer[prosperon.DOC].rect = `Draw one or more outlines of rectangles. + +:param rectOrArray: A single rect {x,y,w,h} or an array of rects. +:param color: Optional [r,g,b,a]. If provided, overrides current draw color. +:return: None +`; + +prosperon.c_types.SDL_Renderer[prosperon.DOC].fillrect = `Fill one or more rectangles with the renderer's current color or an optional override. + +:param rectOrArray: A single rect {x,y,w,h} or an array of rects. +:param color: Optional [r,g,b,a]. +:return: None +`; + +prosperon.c_types.SDL_Renderer[prosperon.DOC].line = `Draw a sequence of lines connecting points in an array. + +:param points: An array of [x,y] points. Lines connect consecutive points. +:param color: Optional [r,g,b,a]. +:return: None +`; + +prosperon.c_types.SDL_Renderer[prosperon.DOC].point = `Draw a list of points (pixels). + +:param points: An array of [x,y] positions. +:param color: Optional [r,g,b,a]. +:return: None +`; + +prosperon.c_types.SDL_Renderer[prosperon.DOC].load_texture = `Create an SDL_Texture from a given SDL_Surface for use with this renderer. + +:param surface: An SDL_Surface. +:return: An SDL_Texture object. +`; + +prosperon.c_types.SDL_Renderer[prosperon.DOC].texture = `Draw a texture onto the render target. + +:param tex: The SDL_Texture to draw. +:param dstRect: The destination rect {x, y, w, h}. +:param srcRect: Optional portion of the texture to draw {x, y, w, h}. +:param color: Optional color mod [r,g,b,a]. +:return: None +`; + +prosperon.c_types.SDL_Renderer[prosperon.DOC].slice9 = `Draw a texture with 9-slice scaling. The argument includes edges {l, r, t, b} +for the corners/borders that remain unscaled. The rest is tiled or stretched. + +:param tex: The SDL_Texture. +:param dstRect: Destination region {x, y, w, h}. +:param edges: {l, r, t, b} for corner sizes in pixels. +:param srcRect: Optional portion in the texture. +:return: None +`; + +prosperon.c_types.SDL_Renderer[prosperon.DOC].tile = `Tile a texture repeatedly within the specified region. Optionally use a srcRect. + +:param tex: The SDL_Texture to tile. +:param dstRect: The region to fill {x, y, w, h}. +:param srcRect: Optional portion of texture. +:param scale: A float scale factor for each tile. +:return: None +`; + +prosperon.c_types.SDL_Renderer[prosperon.DOC].get_image = `Read back the rendered pixels into a new SDL_Surface. If rect is undefined, capture entire output. + +:param rect: Optional {x,y,w,h}. +:return: An SDL_Surface with the requested region's pixels. +`; + +prosperon.c_types.SDL_Renderer[prosperon.DOC].fasttext = `Draw debug text using an internal fast path. Typically used for quick debugging overlays. + +:param text: The string to draw. +:param pos: The [x, y] position to draw text. +:param color: Optional [r,g,b,a]. +:return: None +`; + +prosperon.c_types.SDL_Renderer[prosperon.DOC].geometry = `Render custom geometry from a mesh object {pos, uv, color, indices, count} with an optional texture. + +:param texture: The SDL_Texture or undefined. +:param meshObject: The geometry data with typed arrays. +:return: None +`; + +prosperon.c_types.SDL_Renderer[prosperon.DOC].scale = `Set a scaling factor for all subsequent rendering on this renderer. + +:param scaleVec2: [sx, sy] scaling factors. +:return: None +`; + +prosperon.c_types.SDL_Renderer[prosperon.DOC].logical_size = `Set a "logical" size that the renderer will scale to. +For example, (320, 240) can auto-scale up to the window resolution. + +:param size: [width, height]. +:return: None +`; + +prosperon.c_types.SDL_Renderer[prosperon.DOC].viewport = `Set the clipping viewport for rendering. Pass undefined to use the full render target. + +:param rect: {x, y, w, h}, or undefined. +:return: None +`; + +prosperon.c_types.SDL_Renderer[prosperon.DOC].clip = `Set or clear the clipping rectangle for drawing. Pass undefined to clear. + +:param rect: {x, y, w, h} or undefined. +:return: None +`; + +prosperon.c_types.SDL_Renderer[prosperon.DOC].vsync = `Enable or disable vertical sync. This may have no effect depending on the driver. + +:param flag: True or false. +:return: None +`; + +prosperon.c_types.SDL_Renderer[prosperon.DOC].coords = `Convert window coordinates to this renderer's coordinate space. + +:param pos: [x, y] in window space. +:return: [x, y] in renderer coordinate space. +`; + +prosperon.c_types.SDL_Renderer[prosperon.DOC].camera = `Set up a basic 2D camera matrix from a given transform. If 'centered' is true, +the origin is the center of the viewport, else top-left. + +:param cameraTransform: The transform whose pos is used. +:param centered: Boolean true or false. +:return: None +`; + +prosperon.c_types.SDL_Renderer[prosperon.DOC].get_viewport = `Return the current viewport rect. + +:return: {x, y, w, h} +`; + +prosperon.c_types.SDL_Renderer[prosperon.DOC].screen2world = `Convert a screen coordinate to world space based on the current camera transform. + +:param pos: [x, y] screen coords +:return: [wx, wy] in world space +`; + +prosperon.c_types.SDL_Renderer[prosperon.DOC].target = `Set or clear the current render target texture. Pass undefined to reset to the default/window. + +:param texture: An SDL_Texture or undefined +:return: None +`; + +prosperon.c_types.SDL_Renderer[prosperon.DOC].make_sprite_mesh = `Generate a mesh from an array of sprite objects, combining their positions, UVs, +and colors into a single geometry block. + +:param sprites: An array of sprite-like objects. +:return: A 'mesh' object with pos, uv, color, indices, etc. +`; + + +// +// SDL_Texture +// +prosperon.c_types.SDL_Texture[prosperon.DOC] = {} +prosperon.c_types.SDL_Texture[prosperon.DOC][prosperon.DOC] = `A 2D GPU-accelerated texture for rendering with SDL_Renderer. Freed automatically. +`; + +prosperon.c_types.SDL_Texture[prosperon.DOC].mode = `Set texture scale mode or filtering mode (nearest/linear). + +:param mode: A string or numeric mode to set (e.g., 'linear'). +:return: None +`; + +// +// SDL_Surface +// +prosperon.c_types.SDL_Surface[prosperon.DOC] = {} +prosperon.c_types.SDL_Surface[prosperon.DOC][prosperon.DOC] = `A software (CPU) image in memory. Freed when references vanish. Typically converted +to SDL_Texture for drawing, or used as raw pixel data. +`; + +prosperon.c_types.SDL_Surface[prosperon.DOC].blit = `Blit (copy) another surface onto this surface, scaling if needed. + +:param dstRect: Destination {x, y, w, h} +:param srcSurface: The source SDL_Surface +:param srcRect: {x, y, w, h} portion from source +:return: None +`; + +prosperon.c_types.SDL_Surface[prosperon.DOC].scale = `Return a new SDL_Surface scaled to [width, height] using linear filtering. + +:param newSize: [width, height] +:return: A new SDL_Surface with the scaled result. +`; + +prosperon.c_types.SDL_Surface[prosperon.DOC].fill = `Fill the entire surface with a single color. + +:param color: [r, g, b, a] in 0..1 +:return: None +`; + +prosperon.c_types.SDL_Surface[prosperon.DOC].rect = `Fill a sub-rectangle of the surface with a color. + +:param rect: {x, y, w, h} +:param color: [r, g, b, a] +:return: None +`; + +prosperon.c_types.SDL_Surface[prosperon.DOC].dup = `Make a copy of this surface in RGBA format. + +:return: A new SDL_Surface copy. +`; + + +// +// SDL_GPUDevice +// +prosperon.c_types.SDL_GPUDevice[prosperon.DOC] = {} +prosperon.c_types.SDL_GPUDevice[prosperon.DOC][prosperon.DOC] = `A handle for low-level GPU operations via SDL GPU. Freed on GC. +`; + +prosperon.c_types.SDL_GPUDevice[prosperon.DOC].claim_window = `Claim an existing SDL_Window so this GPU device can render to it. + +:param window: The SDL_Window to attach. +:return: None +`; + +prosperon.c_types.SDL_GPUDevice[prosperon.DOC].make_pipeline = `Create a new graphics pipeline from a descriptor object specifying shaders, +blend states, vertex format, etc. + +:param pipelineDesc: An object containing pipeline fields (vertexShader, blend, etc.). +:return: A SDL_GPUGraphicsPipeline handle. +`; + +prosperon.c_types.SDL_GPUDevice[prosperon.DOC].compute_pipeline = `Create a compute pipeline from a descriptor (shader code, threadgroup sizes, etc.). + +:param desc: An object with shader code, thread counts, etc. +:return: SDL_GPUComputePipeline handle. +`; + +prosperon.c_types.SDL_GPUDevice[prosperon.DOC].set_swapchain = `Specify how the swapchain (final rendered image) is composed, e.g. 'sdr', 'hdr', +and present mode like 'vsync' or 'immediate'. + +:param composition: E.g. 'sdr', 'linear', or 'hdr'. +:param presentMode: E.g. 'vsync', 'immediate', 'mailbox'. +:return: None +`; + +prosperon.c_types.SDL_GPUDevice[prosperon.DOC].sort_sprite = `A comparator function used for sorting sprite objects by layer, y, and texture. +Usually used internally. + +:param a: A sprite object. +:param b: Another sprite object. +:return: <0, 0, or >0 for sort ordering. +`; + +prosperon.c_types.SDL_GPUDevice[prosperon.DOC].make_sampler = `Create a sampler object specifying filtering, wrapping, anisotropy, etc. + +:param samplerDesc: An object with min_filter, mag_filter, etc. +:return: SDL_GPUSampler handle. +`; + +prosperon.c_types.SDL_GPUDevice[prosperon.DOC].load_texture = `Upload an SDL_Surface into a GPU texture, optionally compressing with DXT. Freed automatically. + +:param surface: An SDL_Surface. +:param compressionLevel: 0=none, 1=DXT1 or DXT5, 2=high quality, etc. +:return: SDL_GPUTexture +`; + +prosperon.c_types.SDL_GPUDevice[prosperon.DOC].texture = `Create a GPU texture with the specified format usage. + +:param desc: Object with {width, height, layers, type, format, usage, etc.} +:return: SDL_GPUTexture +`; + +prosperon.c_types.SDL_GPUDevice[prosperon.DOC].make_quad = `Return a simple 2-triangle quad geometry covering [0,1]x[0,1]. +Useful for post-processing passes. + +:return: A mesh {pos, uv, color, indices}. +`; + +prosperon.c_types.SDL_GPUDevice[prosperon.DOC].driver = `Return the name of the underlying GPU driver in use (e.g. 'OpenGL'). + +:return: A string with driver name. +`; + +prosperon.c_types.SDL_GPUDevice[prosperon.DOC].make_shader = `Compile raw shader code (vertex or fragment) in e.g. SPIR-V, MSL, or DXIL format. + +:param desc: {code:ArrayBuffer, stage:'vertex'|'fragment', format:'spv'|..., entrypoint:'main', ...} +:return: SDL_GPUShader object +`; + +prosperon.c_types.SDL_GPUDevice[prosperon.DOC].acquire_cmd_buffer = `Obtain a new command buffer for recording GPU commands. Must be submitted or canceled. + +:return: SDL_GPUCommandBuffer handle +`; + +prosperon.c_types.SDL_GPUDevice[prosperon.DOC].upload = `Upload CPU data into a list of GPU buffers, optionally reusing or returning a +transfer buffer. Typically you provide (cmdBuf, arrayOfTypedArrays, [transferBuffer]). + +:param cmdBuffer: The command buffer in which to record copy commands. +:param buffers: An array of typed-array data to upload, each must have a 'gpu' property or so. +:param transferBuffer: Optional existing GPU transfer buffer to reuse. +:return: The transfer buffer used or newly created. +`; + +prosperon.c_types.SDL_GPUDevice[prosperon.DOC].wait_for_fences = `Wait on an array of GPU fence objects, optionally requiring all or any. + +:param fences: An array of SDL_GPUFence objects. +:param waitAll: Boolean, true to wait for all fences, false for any. +:return: True if fences signaled, false on timeout or error. +`; + +prosperon.c_types.SDL_GPUDevice[prosperon.DOC].query_fence = `Check if the given fence has been signaled yet. Non-blocking. + +:param fence: SDL_GPUFence handle +:return: True if signaled, false if still pending +`; + +prosperon.c_types.SDL_GPUDevice[prosperon.DOC].shader_format = `Return an array of supported GPU shader binary formats (like 'spv', 'dxbc', etc.). + +:return: Array of strings naming supported formats. +`; + +prosperon.c_types.SDL_GPUDevice[prosperon.DOC].slice9 = `Generate a 9-slice tiling geometry in one shot. For advanced usage with GPU pipeline. + +:param texture: An SDL_GPUTexture +:param dstRect: The rectangle {x, y, w, h} +:param edges: {l, r, t, b} edge sizes +:return: A mesh object +`; + +prosperon.c_types.SDL_GPUDevice[prosperon.DOC].tile = `Generate geometry to tile a texture portion inside a dest rect. +Often used for repeating backgrounds. + +:param texture: The SDL_GPUTexture +:param srcRect: The portion to tile in pixels +:param dstRect: Where to fill +:param tileInfo: e.g. {repeat_x:true, repeat_y:true} +:return: A mesh object +`; + + +// +// SDL_GPUCommandBuffer +// +prosperon.c_types.SDL_GPUCommandBuffer[prosperon.DOC] = {} +prosperon.c_types.SDL_GPUCommandBuffer[prosperon.DOC][prosperon.DOC] = `A command buffer that accumulates rendering, copy, and compute operations. Freed after submission or GC. +`; + +prosperon.c_types.SDL_GPUCommandBuffer[prosperon.DOC].render_pass = `Begin a render pass with color/depth attachments. Provide an object with +'color_targets' and optional 'depth_stencil'. Returns an SDL_GPURenderPass handle. + +:param passDesc: {color_targets:[...], depth_stencil:...} +:return: SDL_GPURenderPass +`; + +prosperon.c_types.SDL_GPUCommandBuffer[prosperon.DOC].compute_pass = `Begin a compute pass reading/writing given arrays of textures and buffers. + +:param storageTextures: array of read/write textures +:param storageBuffers: array of read/write buffers +:return: SDL_GPUComputePass +`; + +prosperon.c_types.SDL_GPUCommandBuffer[prosperon.DOC].swapchain_pass = `Begin a render pass that directly targets the swapchain (the window). Clears +with the specified color. + +:param clearColor: [r,g,b,a] +:return: SDL_GPURenderPass +`; + +prosperon.c_types.SDL_GPUCommandBuffer[prosperon.DOC].acquire_swapchain = `Acquire the current swapchain texture from the window. Internal usage. + +:return: SDL_GPUTexture handle +`; + +prosperon.c_types.SDL_GPUCommandBuffer[prosperon.DOC].bind_vertex_buffer = `Bind a GPU buffer as the vertex buffer at a given slot. + +:param slot: Integer slot index. +:param buffer: The SDL_GPUBuffer. +:return: None +`; + +prosperon.c_types.SDL_GPUCommandBuffer[prosperon.DOC].bind_index_buffer = `Bind a GPU buffer as the index buffer (16-bit or 32-bit). + +:param buffer: The SDL_GPUBuffer. +:param offset: Optional offset in bytes. +:return: None +`; + +prosperon.c_types.SDL_GPUCommandBuffer[prosperon.DOC].bind_fragment_sampler = `Bind a texture+sampler pair to a particular fragment shader slot. + +:param slot: Index of the sampler binding. +:param texture: The SDL_GPUTexture +:param sampler: The SDL_GPUSampler +:return: None +`; + +prosperon.c_types.SDL_GPUCommandBuffer[prosperon.DOC].push_vertex_uniform_data = `Push raw data to a vertex shader uniform block. + +:param slot: The uniform buffer slot. +:param data: An ArrayBuffer with the data to upload. +:return: None +`; + +prosperon.c_types.SDL_GPUCommandBuffer[prosperon.DOC].push_fragment_uniform_data = `Push raw data to a fragment shader uniform block. + +:param slot: The uniform buffer slot index. +:param data: An ArrayBuffer with uniform data. +:return: None +`; + +prosperon.c_types.SDL_GPUCommandBuffer[prosperon.DOC].push_compute_uniform_data = `Push raw data to a compute shader uniform buffer. + +:param slot: The uniform buffer slot. +:param data: An ArrayBuffer with the data. +:return: None +`; + +prosperon.c_types.SDL_GPUCommandBuffer[prosperon.DOC].submit = `Submit this command buffer to the GPU and return a fence for synchronization. + +:return: An SDL_GPUFence +`; + +prosperon.c_types.SDL_GPUCommandBuffer[prosperon.DOC].cancel = `Cancel (discard) this command buffer without submitting. + +:return: None +`; + +prosperon.c_types.SDL_GPUCommandBuffer[prosperon.DOC].camera = `Write a camera transform (projection/view) to a uniform slot for 3D or 2D usage. + +:param cameraTransform: A camera object or transform with .pos, fov, etc. +:param uniformSlot: The integer uniform buffer slot to which data is pushed. +:return: None +`; + +prosperon.c_types.SDL_GPUCommandBuffer[prosperon.DOC].hud = `Write an orthographic full-screen "HUD" matrix to a uniform slot. Typically used +for 2D overlays. + +:param sizeVec2: [width, height] of the viewport area. +:param uniformSlot: The integer uniform buffer slot. +:return: None +`; + +prosperon.c_types.SDL_GPUCommandBuffer[prosperon.DOC].push_debug_group = `Push a named debug group marker onto the GPU command list (for debuggers/profilers). + +:param name: The debug label string. +:return: None +`; + +prosperon.c_types.SDL_GPUCommandBuffer[prosperon.DOC].pop_debug_group = `Pop the most recent debug group marker. + +:return: None +`; + +prosperon.c_types.SDL_GPUCommandBuffer[prosperon.DOC].debug_label = `Insert a one-off debug label at the current spot in the command list. + +:param label: The debug label string +:return: None +`; + +prosperon.c_types.SDL_GPUCommandBuffer[prosperon.DOC].blit = `Blit one GPU texture to another with optional flip mode, filter, and clear operations. + +:param blitDesc: { src:{texture,mip_level, etc}, dst:{texture,...}, load_op, flip, filter, clear_color:[r,g,b,a] } +:return: None +`; + + +// +// SDL_GPURenderPass +// +prosperon.c_types.SDL_GPURenderPass[prosperon.DOC] = {} +prosperon.c_types.SDL_GPURenderPass[prosperon.DOC][prosperon.DOC] = `A single pass of drawing commands with color/depth attachments. Freed after end() or GC. +`; + +prosperon.c_types.SDL_GPURenderPass[prosperon.DOC].bind_pipeline = `Bind a previously created graphics pipeline (shaders, states, vertex layouts, etc.). + +:param pipeline: The SDL_GPUGraphicsPipeline +:return: None +`; + +prosperon.c_types.SDL_GPURenderPass[prosperon.DOC].viewport = `Set the viewport for clipping or scaling draws, in pass-local coordinates. + +:param rect: {x,y,w,h} +:return: None +`; + +prosperon.c_types.SDL_GPURenderPass[prosperon.DOC].scissor = `Set a scissor rectangle for discarding pixels outside it. + +:param rect: {x,y,w,h} +:return: None +`; + +prosperon.c_types.SDL_GPURenderPass[prosperon.DOC].draw = `Issue a non-indexed draw call. + +:param primitiveType: e.g. SDL_GPU_PRIMITIVETYPE_TRIANGLELIST +:param baseVertex: Starting vertex offset. +:param firstVertex: The first vertex to draw. +:param vertexCount: How many vertices to draw. +:return: None +`; + +prosperon.c_types.SDL_GPURenderPass[prosperon.DOC].draw_indexed = `Issue an indexed draw call from the bound index buffer. + +:param primitiveType: The primitive type constant. +:param baseVertex: Offset in the vertex buffer. +:param firstIndex: Which index to start from. +:param indexCount: Number of indices to draw. +:param instanceCount: For instanced drawing, or 1 if normal. +:return: None +`; + +prosperon.c_types.SDL_GPURenderPass[prosperon.DOC].end = `End this render pass, finalizing the draw operations. + +:return: None +`; + +prosperon.c_types.SDL_GPURenderPass[prosperon.DOC].bind_index_buffer = `Bind an index buffer inside this pass, possibly overriding the global one. + +:param buffer: The SDL_GPUBuffer +:param elementSize16bit: If 2, uses 16-bit indices; if 4, uses 32-bit indices +:return: None +`; + +prosperon.c_types.SDL_GPURenderPass[prosperon.DOC].bind_buffers = `Bind multiple vertex buffers at consecutive slots. + +:param firstSlot: The starting vertex buffer slot. +:param arrayOfBuffers: An array of GPUBuffer objects +:return: None +`; + +prosperon.c_types.SDL_GPURenderPass[prosperon.DOC].bind_samplers = `Bind multiple texture/sampler pairs to either vertex or fragment slots. + +:param vertexOrFragment: Boolean, true for vertex stage, false for fragment. +:param firstSlot: The first sampler slot to bind. +:param samplerBindings: An array of {texture, sampler}. +:return: None +`; + +prosperon.c_types.SDL_GPURenderPass[prosperon.DOC].bind_storage_buffers = `Bind one or more storage buffers for read/write in the pipeline. + +:param firstSlot: Starting buffer slot index. +:param buffers: An array of SDL_GPUBuffer objects. +:return: None +`; + +prosperon.c_types.SDL_GPURenderPass[prosperon.DOC].bind_storage_textures = `Bind one or more storage textures for read/write in the pipeline. + +:param firstSlot: Starting texture slot index. +:param textures: An array of SDL_GPUTexture objects. +:return: None +`; + +// +// SDL_GPUComputePass +// +prosperon.c_types.SDL_GPUComputePass[prosperon.DOC] = {} +prosperon.c_types.SDL_GPUComputePass[prosperon.DOC][prosperon.DOC] = `A compute pass for dispatching compute pipelines. Freed after end() or GC. +`; + +prosperon.c_types.SDL_GPUComputePass[prosperon.DOC].dispatch = `Dispatch the compute pipeline with the specified threadgroup counts. + +:param x: Number of groups in X dimension +:param y: Number of groups in Y dimension +:param z: Number of groups in Z dimension +:return: None +`; + +prosperon.c_types.SDL_GPUComputePass[prosperon.DOC].end = `End this compute pass. + +:return: None +`; + +prosperon.c_types.SDL_GPUComputePass[prosperon.DOC].pipeline = `Bind a compute pipeline in this pass. + +:param computePipeline: The SDL_GPUComputePipeline +:return: None +`; + +prosperon.c_types.SDL_GPUComputePass[prosperon.DOC].samplers = `Bind a set of texture/sampler pairs for compute usage. + +:param arrayOfSamplerBindings: e.g. [ {texture, sampler}, ...] +:param firstSlot: The starting sampler slot. +:return: None +`; + +prosperon.c_types.SDL_GPUComputePass[prosperon.DOC].storage_buffers = `Bind an array of storage buffers for the compute shader. + +:param arrayOfBuffers: The buffers +:param firstSlot: Starting binding slot. +:return: None +`; + +prosperon.c_types.SDL_GPUComputePass[prosperon.DOC].storage_textures = `Bind an array of storage textures for the compute shader. + +:param arrayOfTextures: The textures +:param firstSlot: Starting binding slot +:return: None +`; + + +// +// SDL_GPUCopyPass +// +prosperon.c_types.SDL_GPUCopyPass[prosperon.DOC] = {} +prosperon.c_types.SDL_GPUCopyPass[prosperon.DOC][prosperon.DOC] = `A pass for CPU<->GPU or GPU<->GPU copy operations. No direct JS API besides internal usage. +`; + +// +// SDL_GPUFence +// +prosperon.c_types.SDL_GPUFence[prosperon.DOC] = {} +prosperon.c_types.SDL_GPUFence[prosperon.DOC][prosperon.DOC] = `A GPU fence for synchronization. Created upon commandBuffer.submit(). +Wait or query it with device.wait_for_fences or device.query_fence. +`; + +// +// SDL_GPUTransferBuffer +// +prosperon.c_types.SDL_GPUTransferBuffer[prosperon.DOC] = {} +prosperon.c_types.SDL_GPUTransferBuffer[prosperon.DOC][prosperon.DOC] = `A staging buffer used for copying data to or from GPU buffers/textures. Typically +allocated/used internally by device.upload(...). +`; + +// +// SDL_GPUShader +// +prosperon.c_types.SDL_GPUShader[prosperon.DOC] = {} +prosperon.c_types.SDL_GPUShader[prosperon.DOC][prosperon.DOC] = `A single compiled shader (vertex or fragment) in a GPU-friendly format +(e.g., SPIR-V, MSL). Combined into a pipeline for drawing. +`; + +// +// SDL_GPUSampler +// +prosperon.c_types.SDL_GPUSampler[prosperon.DOC] = {} +prosperon.c_types.SDL_GPUSampler[prosperon.DOC][prosperon.DOC] = `Defines how a texture is sampled (filter mode, address mode, anisotropy, compare op, etc.). +`; + +// +// SDL_GPUGraphicsPipeline +// +prosperon.c_types.SDL_GPUGraphicsPipeline[prosperon.DOC] = {} +prosperon.c_types.SDL_GPUGraphicsPipeline[prosperon.DOC][prosperon.DOC] = `Encapsulates vertex+fragment shaders, blend/cull states, and vertex attribute layouts. +Created via device.make_pipeline(...). +`; + +// +// SDL_GPUComputePipeline +// +prosperon.c_types.SDL_GPUComputePipeline[prosperon.DOC] = {} +prosperon.c_types.SDL_GPUComputePipeline[prosperon.DOC][prosperon.DOC] = `Encapsulates a compute shader program plus associated resource layouts. +Created via device.compute_pipeline(...). +`; + + +// Document the main prosperon object +prosperon[prosperon.DOC] = { + doc: `The main prosperon object providing event dispatch, signal handling, and engine management.`, + DOC: `Symbol used to store documentation references on objects.`, + on: `Register a callback function for a given event type. Returns a function to remove the callback.`, + dispatch: `Dispatch an event of the given type, calling all registered callbacks with the provided data.`, + PATH: `Array of directory paths that Prosperon will search to find scripts or modules.`, + c_types: `Prototype objects for all present defined c-types (like sprite, transform, etc)` +} + +// Document the actor object/prototype +actor[prosperon.DOC] = { + doc: `The actor object/prototype, serving as a base for all game actors or entities.`, + spawn: `Create a new actor from a script, optionally applying a config object, then call the new actor's 'awake' method.`, + kill: `Destroy this actor, removing it from the game along with all underlings. Frees resources and triggers garbage if defined.`, + clear: `Remove all child (underling) actors by calling kill on each.`, + delay: `Schedule a function to be called after a specified delay (in seconds) on this actor.`, + toString: `Return the script filename associated with this actor instance.` +} + +// Expand console.doc to document the console object and missing methods +console[prosperon.DOC] = {} +console[prosperon.DOC][prosperon.DOC] = `The console object provides various logging, debugging, and output methods.` +console[prosperon.DOC].spam = `Output a spam-level message for very verbose logging.` +console[prosperon.DOC].debug = `Output a debug-level message.` +console[prosperon.DOC].panic = `Output a panic-level message and exit the program.` +console[prosperon.DOC].assert = `If the condition is false, print an error and panic.` + +// Document the Register object +Register[prosperon.DOC] = { + doc: `Factory for creating and managing event registries (e.g. update, draw, etc.) within Prosperon.`, + add_cb: `Create or retrieve a registry for an event type, exposing a 'register' method for callbacks.`, + pull_registers: `Gather the names of all recognized event methods implemented by an object.`, + register_obj: `Bind an object's event method to the relevant registry. The unregistration handle goes in the actor's timers.`, + check_registers: `Automatically register recognized events (like 'update', 'gui', etc.) on an object.`, +} + +use[prosperon.DOC] = 'Return the value from the provided path to a module.' diff --git a/scripts/core/engine.js b/scripts/core/engine.js index c7d911de..285e0b07 100644 --- a/scripts/core/engine.js +++ b/scripts/core/engine.js @@ -1,1137 +1,6 @@ (function engine() { prosperon.DOC = Symbol('+documentation+') // Symbol for documentation references -// -// sprite -// -prosperon.c_types.sprite[prosperon.DOC] = {} -prosperon.c_types.sprite[prosperon.DOC][prosperon.DOC] = `A 'sprite' is a simple struct for 2D drawing. It stores a rectangle (pos + size), -UV coordinates, color, and layer, as well as an associated 'image' object. The sprite -can be drawn via GPU or SDL_Renderer. Freed when no JS references remain. -`; - -prosperon.c_types.sprite[prosperon.DOC].set_affine = `Update this sprite's position and size from a transform's pos and scale. - -:param transform: The transform whose pos/scale will overwrite the sprite's rect. -:return: None -`; - -prosperon.c_types.sprite[prosperon.DOC].set_rect = `Set the sprite's rect (x, y, w, h) directly. - -:param rect: An object or array specifying x, y, width, and height. -:return: None -`; - -prosperon.c_types.sprite[prosperon.DOC].set_image = `Assign or replace the sprite's underlying image. Automatically updates UV if -the image has a 'rect' property. - -:param image: A JS object representing the image (with .texture, .rect, etc.). -:return: None -`; - -prosperon.c_types.sprite[prosperon.DOC].layer = `Get or set the sprite's z-layer integer. Sprites with higher layers typically -draw on top of lower layers. - -:param value: (when setting) An integer specifying the layer. -:return: The current layer (when getting), or None (when setting). -`; - -prosperon.c_types.sprite[prosperon.DOC].color = `Get or set the sprite's color tint as [r, g, b, a]. - -:param value: (when setting) An array [r, g, b, a] in the 0.0..1.0 range. -:return: The current color array (when getting), or None (when setting). -`; - - -// -// transform -// -prosperon.c_types.transform[prosperon.DOC] = {} -prosperon.c_types.transform[prosperon.DOC][prosperon.DOC] = `A hierarchical transform storing 3D or 2D position, rotation (as a quaternion), -and scale. Can have a parent transform. Freed automatically on GC. -`; - -prosperon.c_types.transform[prosperon.DOC].pos = `Get or set the transform's position as a 3D vector [x, y, z]. - -:param value: (when setting) [x, y, z]. -:return: The current position vector (when getting), or None (when setting). -`; - -prosperon.c_types.transform[prosperon.DOC].scale = `Get or set the transform's scale as a 3D vector [x, y, z]. -For 2D usage, z is often 1. - -:param value: (when setting) [sx, sy, sz]. -:return: The current scale (when getting), or None (when setting). -`; - -prosperon.c_types.transform[prosperon.DOC].rotation = `Get or set the transform's rotation as a quaternion [x, y, z, w]. -Angles in degrees or radians must first be converted prior to making a quaternion. - -:param value: (when setting) [qx, qy, qz, qw]. -:return: The current quaternion (when getting), or None (when setting). -`; - -prosperon.c_types.transform[prosperon.DOC].parent = `Get or set the transform's parent. If set, this transform becomes a child of -the parent (re-parenting). Must be another transform object or undefined. - -:param value: (when setting) Another transform or undefined. -:return: The current parent transform (when getting), or None (when setting). -`; - -prosperon.c_types.transform[prosperon.DOC].change_hook = `A user-supplied function that's called whenever the transform's local matrix changes. -If undefined, no hook is called. - -:param value: (when setting) A function. -:return: The current function or undefined. -`; - -prosperon.c_types.transform[prosperon.DOC].trs = `Set the transform's position, rotation, and scale in one call. - -:param pos: [x,y,z] for position, or undefined to keep existing. -:param quat: [qx,qy,qz,qw] for rotation, or undefined. -:param scale: [sx,sy,sz] for scale, or undefined. -:return: None -`; - -prosperon.c_types.transform[prosperon.DOC].phys2d = `Apply simple 2D velocity and angular velocity to this transform. - -:param velocity: [vx, vy] added to 'pos' each frame. -:param angularVel: A scalar for rotation in (radians/second). -:param dt: The time delta in seconds. -:return: None -`; - -prosperon.c_types.transform[prosperon.DOC].move = `Translate this transform by the specified vector. - -:param delta: [dx, dy, dz] to add to .pos -:return: None -`; - -prosperon.c_types.transform[prosperon.DOC].rotate = `Rotate this transform by an axis+angle. - -:param axis: [ax, ay, az] the axis of rotation. -:param angle: The angle in turns or radians (depending on usage). -:return: None -`; - -prosperon.c_types.transform[prosperon.DOC].angle = `Return the transform's rotation about a specified axis (x, y, or z). -For example, angle([1,0,0]) returns the roll about the X-axis. - -:param axis: Which axis [1,0,0] or [0,1,0] or [0,0,1]. -:return: The numeric angle in 'turns' or radians, depending on usage. -`; - -prosperon.c_types.transform[prosperon.DOC].lookat = `Rotate this transform so it looks toward the given world position. - -:param target: [x, y, z] position in world coords. -:return: None -`; - -prosperon.c_types.transform[prosperon.DOC].direction = `Rotate a vector by this transform's rotation, effectively "transforming" -a direction from local space to world space. - -:param localDir: [dx, dy, dz] in local transform coordinates. -:return: [dx', dy', dz'] direction in world space. -`; - -prosperon.c_types.transform[prosperon.DOC].unit = `Reset position, rotation, and scale to [0,0,0], identity rotation, and [1,1,1]. - -:return: None -`; - -prosperon.c_types.transform[prosperon.DOC].rect = `Set this transform's pos and scale from a 2D rect object {x, y, w, h}. - -:param rect: Object with .x, .y, .w, .h -:return: None -`; - -prosperon.c_types.transform[prosperon.DOC].array = `Return this transform's matrix as a 16-element float array in column-major order. - -:return: An array of 16 floats. -`; - -prosperon.c_types.transform[prosperon.DOC].torect = `Convert transform's 2D position/scale to a rect {x, y, w, h}. -Rotation is currently ignored. - -:return: A rect object {x, y, w, h}. -`; - -prosperon.c_types.transform[prosperon.DOC].children = `Return an array of child transforms belonging to this transform. - -:return: An array of transform objects. -`; - - -// -// font -// -prosperon.c_types.font[prosperon.DOC] = {} -prosperon.c_types.font[prosperon.DOC][prosperon.DOC] = `A bitmap or TTF-based font object storing glyph data. -Used for measuring/drawing text. Freed when GC sees no references. -`; - -prosperon.c_types.font[prosperon.DOC].linegap = `Get or set the font's additional line spacing above the built-in metrics. - -:param value: (when setting) The new line gap. -:return: The current line gap (when getting), or None (when setting). -`; - -prosperon.c_types.font[prosperon.DOC].height = `The baseline-to-baseline height in pixels. - -:return: The font's total height in px. -`; - -prosperon.c_types.font[prosperon.DOC].ascent = `How far above the baseline the font extends. - -:return: A scalar float for ascent. -`; - -prosperon.c_types.font[prosperon.DOC].descent = `How far below baseline the font extends. - -:return: A scalar float for descent. -`; - -prosperon.c_types.font[prosperon.DOC].text_size = `Measure a piece of text's width/height when rendered with this font. - -:param text: The string to measure. -:param letterSpacing: Extra spacing between characters. -:param wrap: If nonzero, word-wrap to this maximum width. -:return: [width, height] as a float array. -`; - - -// -// datastream -// -prosperon.c_types.datastream[prosperon.DOC]= {} -prosperon.c_types.datastream[prosperon.DOC][prosperon.DOC] = `A streaming media handle, typically for MPEG video. Freed automatically. -`; - -prosperon.c_types.datastream[prosperon.DOC].time = `Return the current playback time in seconds. - -:return: Current time as a float in seconds. -`; - -prosperon.c_types.datastream[prosperon.DOC].seek = `Seek to the specified time (in seconds). - -:param seconds: The time to jump to in the stream. -:return: None -`; - -prosperon.c_types.datastream[prosperon.DOC].advance = `Advance by a certain number of seconds, decoding video as needed. - -:param seconds: The amount of time to skip forward. -:return: None -`; - -prosperon.c_types.datastream[prosperon.DOC].duration = `Return the total duration of the video stream, in seconds, if known. - -:return: Float seconds duration, or 0 if unknown. -`; - -prosperon.c_types.datastream[prosperon.DOC].framerate = `Return the framerate (FPS) of the stream if known. - -:return: Float frames per second, or 0 if unknown. -`; - -prosperon.c_types.datastream[prosperon.DOC].callback = `A function to call whenever a new frame is decoded. If not set, no callback is invoked. - -:param fn: (when setting) A function that receives (surface). -:return: The existing function or undefined if none. -`; - - -// -// timer -// -prosperon.c_types.timer[prosperon.DOC] = {} -prosperon.c_types.timer[prosperon.DOC][prosperon.DOC] = `A scheduled callback or countdown. Freed automatically once no longer referenced -or once it completes. -`; - -prosperon.c_types.timer[prosperon.DOC].remain = `Get or set how many seconds remain before the timer triggers. - -:param value: (when setting) A float specifying new time remaining. -:return: The current time left (when getting), or None (when setting). -`; - -prosperon.c_types.timer[prosperon.DOC].fn = `Get or set the function called when the timer expires. - -:param value: (when setting) The function. -:return: The function or undefined if none is set. -`; - - -// -// rtree -// -prosperon.c_types.rtree[prosperon.DOC] = {} -prosperon.c_types.rtree[prosperon.DOC][prosperon.DOC] = `An R-tree for spatial lookups. Insert bounding boxes, query by bounding box, etc. -`; - -prosperon.c_types.rtree[prosperon.DOC].add = `Insert an object that has a 'rect' property {x, y, w, h} into the tree. - -:param obj: The object to add (must have rectAtom). -:return: None -`; - -prosperon.c_types.rtree[prosperon.DOC].delete = `Remove an object from the tree. Must match the same rect as used when adding. - -:param obj: The object to remove. -:return: None -`; - -prosperon.c_types.rtree[prosperon.DOC].query = `Return an array of objects whose bounding boxes intersect the given rect. - -:param rect: {x, y, w, h} bounding region to query. -:return: Array of objects that overlap that region. -`; - -prosperon.c_types.rtree[prosperon.DOC].size = `Indicates how many items are stored in the rtree. - -:return: Integer count of items in the tree. -`; - -prosperon.c_types.rtree[prosperon.DOC].forEach = `Call a function for every item in the rtree. - -:param callback: A function called with no arguments, or possibly (item). -:return: None -`; - -prosperon.c_types.rtree[prosperon.DOC].has = `Return true if the specified object is in the tree, false otherwise. - -:param obj: The object to check. -:return: True if found, else false. -`; - -prosperon.c_types.rtree[prosperon.DOC].values = `Return an array of all items currently in the rtree. - -:return: Array of all stored objects. -`; - - -// -// PHYSFS_File -// -prosperon.c_types.PHYSFS_File[prosperon.DOC] = {} -prosperon.c_types.PHYSFS_File[prosperon.DOC][prosperon.DOC] = `A file handle opened via PhysFS for writing or reading. Freed automatically when references go away. -`; - -prosperon.c_types.PHYSFS_File[prosperon.DOC].close = `Close this file handle. Throws on error. - -:return: None -`; - -prosperon.c_types.PHYSFS_File[prosperon.DOC].write = `Write data (string or ArrayBuffer) to the file. Throws on error. - -:param data: The data to write (string or ArrayBuffer). -:return: None -`; - -prosperon.c_types.PHYSFS_File[prosperon.DOC].buffer = `Enable an internal write buffer of the given size on this file. - -:param size: Size in bytes of the buffer. -:return: None -`; - -prosperon.c_types.PHYSFS_File[prosperon.DOC].tell = `Return the current position in the file. - -:return: A numeric offset. -`; - -prosperon.c_types.PHYSFS_File[prosperon.DOC].eof = `Return whether the file pointer is at end-of-file. - -:return: True if at EOF, false otherwise. -`; - - -// -// SDL_Camera -// -prosperon.c_types.SDL_Camera[prosperon.DOC] = {} -prosperon.c_types.SDL_Camera[prosperon.DOC][prosperon.DOC] = `A handle to a physical camera device. Freed when references drop or camera is closed. -`; - -prosperon.c_types.SDL_Camera[prosperon.DOC].frame = `Acquire the latest camera frame (as an SDL_Surface). Returns undefined if no -new frame is available yet. Throws on error. - -:return: SDL_Surface or undefined. -`; - -prosperon.c_types.SDL_Camera[prosperon.DOC].release_frame = `Release a frame surface previously acquired via camera.frame(). Must be -done for each acquired frame. - -:param surface: The surface to release. -:return: None -`; - - -// -// SDL_Cursor -// -prosperon.c_types.SDL_Cursor[prosperon.DOC] = {} -prosperon.c_types.SDL_Cursor[prosperon.DOC][prosperon.DOC] = `An SDL cursor handle. Freed automatically on GC. No direct methods. -`; - - -// -// SDL_Thread -// -prosperon.c_types.SDL_Thread[prosperon.DOC] = {} -prosperon.c_types.SDL_Thread[prosperon.DOC][prosperon.DOC] = `A handle to an SDL-created thread. Freed on GC after join. - -Note: The engine generally doesn't expose custom usage for threads. -`; - -prosperon.c_types.SDL_Thread[prosperon.DOC].wait = `Block until this thread terminates. - -:return: None -`; - - -// -// SDL_Window -// -prosperon.c_types.SDL_Window[prosperon.DOC] = {} -prosperon.c_types.SDL_Window[prosperon.DOC][prosperon.DOC] = `An application window, created via prosperon.engine_start or SDL calls. Freed on GC. -`; - -prosperon.c_types.SDL_Window[prosperon.DOC].fullscreen = `Toggle fullscreen mode for this window (SDL_WINDOW_FULLSCREEN). - -:return: None -`; - -prosperon.c_types.SDL_Window[prosperon.DOC].make_renderer = `Create an SDL_Renderer for 2D rendering tied to this window. - -:param name: The renderer driver name, e.g. "opengl" (may be optional). -:return: An SDL_Renderer object. -`; - -prosperon.c_types.SDL_Window[prosperon.DOC].make_gpu = `Create an SDL_GPUDevice for low-level GPU rendering on this window. - -:param debug: If true, enable debugging in the GPU device. -:param driverName: The GPU back-end driver, e.g. "opengl". -:return: An SDL_GPUDevice. -`; - -prosperon.c_types.SDL_Window[prosperon.DOC].keyboard_shown = `Return whether the on-screen keyboard is visible (mobile/tablet). - -:return: True if shown, false otherwise. -`; - -prosperon.c_types.SDL_Window[prosperon.DOC].theme = `Currently returns undefined. Placeholder for retrieving OS window theme info. - -:return: undefined -`; - -prosperon.c_types.SDL_Window[prosperon.DOC].safe_area = `Return a rect describing any OS-specific "safe" region for UI, e.g. on iPhone with a notch. - -:return: A rect object {x, y, w, h}. -`; - -prosperon.c_types.SDL_Window[prosperon.DOC].bordered = `Enable or disable window borders. - -:param flag: True to show borders, false to hide. -:return: None -`; - -prosperon.c_types.SDL_Window[prosperon.DOC].set_icon = `Set the window's icon from an SDL_Surface. - -:param surface: An SDL_Surface holding the icon. -:return: None -`; - -prosperon.c_types.SDL_Window[prosperon.DOC].mouse_grab = `Grab or ungrab the mouse for this window (so the pointer won't leave). - -:param flag: True to grab mouse input, false to release. -:return: None -`; - -prosperon.c_types.SDL_Window[prosperon.DOC].title = `Get or set the window's title text in the title bar. - -:param newTitle: (when setting) A string title. -:return: The current title if getting, or None if setting. -`; - -prosperon.c_types.SDL_Window[prosperon.DOC].size = `Get or set the window's size as [width, height]. - -:param newSize: (when setting) e.g. [640, 480] -:return: The current [width, height] or None if setting. -`; - - -// -// SDL_Renderer -// -prosperon.c_types.SDL_Renderer[prosperon.DOC] = {} -prosperon.c_types.SDL_Renderer[prosperon.DOC][prosperon.DOC] = `A 2D rendering context using the SDL renderer API. Freed automatically. -`; - -prosperon.c_types.SDL_Renderer[prosperon.DOC].draw_color = `Set the render draw color for subsequent primitive calls (rect, line, etc.). - -:param color: [r, g, b, a] in 0..1. -:return: None -`; - -prosperon.c_types.SDL_Renderer[prosperon.DOC].present = `Display whatever has been rendered (swap buffers). Must be called each frame. - -:return: None -`; - -prosperon.c_types.SDL_Renderer[prosperon.DOC].clear = `Clear the current render target with the renderer's draw color. - -:return: None -`; - -prosperon.c_types.SDL_Renderer[prosperon.DOC].rect = `Draw one or more outlines of rectangles. - -:param rectOrArray: A single rect {x,y,w,h} or an array of rects. -:param color: Optional [r,g,b,a]. If provided, overrides current draw color. -:return: None -`; - -prosperon.c_types.SDL_Renderer[prosperon.DOC].fillrect = `Fill one or more rectangles with the renderer's current color or an optional override. - -:param rectOrArray: A single rect {x,y,w,h} or an array of rects. -:param color: Optional [r,g,b,a]. -:return: None -`; - -prosperon.c_types.SDL_Renderer[prosperon.DOC].line = `Draw a sequence of lines connecting points in an array. - -:param points: An array of [x,y] points. Lines connect consecutive points. -:param color: Optional [r,g,b,a]. -:return: None -`; - -prosperon.c_types.SDL_Renderer[prosperon.DOC].point = `Draw a list of points (pixels). - -:param points: An array of [x,y] positions. -:param color: Optional [r,g,b,a]. -:return: None -`; - -prosperon.c_types.SDL_Renderer[prosperon.DOC].load_texture = `Create an SDL_Texture from a given SDL_Surface for use with this renderer. - -:param surface: An SDL_Surface. -:return: An SDL_Texture object. -`; - -prosperon.c_types.SDL_Renderer[prosperon.DOC].texture = `Draw a texture onto the render target. - -:param tex: The SDL_Texture to draw. -:param dstRect: The destination rect {x, y, w, h}. -:param srcRect: Optional portion of the texture to draw {x, y, w, h}. -:param color: Optional color mod [r,g,b,a]. -:return: None -`; - -prosperon.c_types.SDL_Renderer[prosperon.DOC].slice9 = `Draw a texture with 9-slice scaling. The argument includes edges {l, r, t, b} -for the corners/borders that remain unscaled. The rest is tiled or stretched. - -:param tex: The SDL_Texture. -:param dstRect: Destination region {x, y, w, h}. -:param edges: {l, r, t, b} for corner sizes in pixels. -:param srcRect: Optional portion in the texture. -:return: None -`; - -prosperon.c_types.SDL_Renderer[prosperon.DOC].tile = `Tile a texture repeatedly within the specified region. Optionally use a srcRect. - -:param tex: The SDL_Texture to tile. -:param dstRect: The region to fill {x, y, w, h}. -:param srcRect: Optional portion of texture. -:param scale: A float scale factor for each tile. -:return: None -`; - -prosperon.c_types.SDL_Renderer[prosperon.DOC].get_image = `Read back the rendered pixels into a new SDL_Surface. If rect is undefined, capture entire output. - -:param rect: Optional {x,y,w,h}. -:return: An SDL_Surface with the requested region's pixels. -`; - -prosperon.c_types.SDL_Renderer[prosperon.DOC].fasttext = `Draw debug text using an internal fast path. Typically used for quick debugging overlays. - -:param text: The string to draw. -:param pos: The [x, y] position to draw text. -:param color: Optional [r,g,b,a]. -:return: None -`; - -prosperon.c_types.SDL_Renderer[prosperon.DOC].geometry = `Render custom geometry from a mesh object {pos, uv, color, indices, count} with an optional texture. - -:param texture: The SDL_Texture or undefined. -:param meshObject: The geometry data with typed arrays. -:return: None -`; - -prosperon.c_types.SDL_Renderer[prosperon.DOC].scale = `Set a scaling factor for all subsequent rendering on this renderer. - -:param scaleVec2: [sx, sy] scaling factors. -:return: None -`; - -prosperon.c_types.SDL_Renderer[prosperon.DOC].logical_size = `Set a "logical" size that the renderer will scale to. -For example, (320, 240) can auto-scale up to the window resolution. - -:param size: [width, height]. -:return: None -`; - -prosperon.c_types.SDL_Renderer[prosperon.DOC].viewport = `Set the clipping viewport for rendering. Pass undefined to use the full render target. - -:param rect: {x, y, w, h}, or undefined. -:return: None -`; - -prosperon.c_types.SDL_Renderer[prosperon.DOC].clip = `Set or clear the clipping rectangle for drawing. Pass undefined to clear. - -:param rect: {x, y, w, h} or undefined. -:return: None -`; - -prosperon.c_types.SDL_Renderer[prosperon.DOC].vsync = `Enable or disable vertical sync. This may have no effect depending on the driver. - -:param flag: True or false. -:return: None -`; - -prosperon.c_types.SDL_Renderer[prosperon.DOC].coords = `Convert window coordinates to this renderer's coordinate space. - -:param pos: [x, y] in window space. -:return: [x, y] in renderer coordinate space. -`; - -prosperon.c_types.SDL_Renderer[prosperon.DOC].camera = `Set up a basic 2D camera matrix from a given transform. If 'centered' is true, -the origin is the center of the viewport, else top-left. - -:param cameraTransform: The transform whose pos is used. -:param centered: Boolean true or false. -:return: None -`; - -prosperon.c_types.SDL_Renderer[prosperon.DOC].get_viewport = `Return the current viewport rect. - -:return: {x, y, w, h} -`; - -prosperon.c_types.SDL_Renderer[prosperon.DOC].screen2world = `Convert a screen coordinate to world space based on the current camera transform. - -:param pos: [x, y] screen coords -:return: [wx, wy] in world space -`; - -prosperon.c_types.SDL_Renderer[prosperon.DOC].target = `Set or clear the current render target texture. Pass undefined to reset to the default/window. - -:param texture: An SDL_Texture or undefined -:return: None -`; - -prosperon.c_types.SDL_Renderer[prosperon.DOC].make_sprite_mesh = `Generate a mesh from an array of sprite objects, combining their positions, UVs, -and colors into a single geometry block. - -:param sprites: An array of sprite-like objects. -:return: A 'mesh' object with pos, uv, color, indices, etc. -`; - - -// -// SDL_Texture -// -prosperon.c_types.SDL_Texture[prosperon.DOC] = {} -prosperon.c_types.SDL_Texture[prosperon.DOC][prosperon.DOC] = `A 2D GPU-accelerated texture for rendering with SDL_Renderer. Freed automatically. -`; - -prosperon.c_types.SDL_Texture[prosperon.DOC].mode = `Set texture scale mode or filtering mode (nearest/linear). - -:param mode: A string or numeric mode to set (e.g., 'linear'). -:return: None -`; - -// -// SDL_Surface -// -prosperon.c_types.SDL_Surface[prosperon.DOC] = {} -prosperon.c_types.SDL_Surface[prosperon.DOC][prosperon.DOC] = `A software (CPU) image in memory. Freed when references vanish. Typically converted -to SDL_Texture for drawing, or used as raw pixel data. -`; - -prosperon.c_types.SDL_Surface[prosperon.DOC].blit = `Blit (copy) another surface onto this surface, scaling if needed. - -:param dstRect: Destination {x, y, w, h} -:param srcSurface: The source SDL_Surface -:param srcRect: {x, y, w, h} portion from source -:return: None -`; - -prosperon.c_types.SDL_Surface[prosperon.DOC].scale = `Return a new SDL_Surface scaled to [width, height] using linear filtering. - -:param newSize: [width, height] -:return: A new SDL_Surface with the scaled result. -`; - -prosperon.c_types.SDL_Surface[prosperon.DOC].fill = `Fill the entire surface with a single color. - -:param color: [r, g, b, a] in 0..1 -:return: None -`; - -prosperon.c_types.SDL_Surface[prosperon.DOC].rect = `Fill a sub-rectangle of the surface with a color. - -:param rect: {x, y, w, h} -:param color: [r, g, b, a] -:return: None -`; - -prosperon.c_types.SDL_Surface[prosperon.DOC].dup = `Make a copy of this surface in RGBA format. - -:return: A new SDL_Surface copy. -`; - - -// -// SDL_GPUDevice -// -prosperon.c_types.SDL_GPUDevice[prosperon.DOC] = {} -prosperon.c_types.SDL_GPUDevice[prosperon.DOC][prosperon.DOC] = `A handle for low-level GPU operations via SDL GPU. Freed on GC. -`; - -prosperon.c_types.SDL_GPUDevice[prosperon.DOC].claim_window = `Claim an existing SDL_Window so this GPU device can render to it. - -:param window: The SDL_Window to attach. -:return: None -`; - -prosperon.c_types.SDL_GPUDevice[prosperon.DOC].make_pipeline = `Create a new graphics pipeline from a descriptor object specifying shaders, -blend states, vertex format, etc. - -:param pipelineDesc: An object containing pipeline fields (vertexShader, blend, etc.). -:return: A SDL_GPUGraphicsPipeline handle. -`; - -prosperon.c_types.SDL_GPUDevice[prosperon.DOC].compute_pipeline = `Create a compute pipeline from a descriptor (shader code, threadgroup sizes, etc.). - -:param desc: An object with shader code, thread counts, etc. -:return: SDL_GPUComputePipeline handle. -`; - -prosperon.c_types.SDL_GPUDevice[prosperon.DOC].set_swapchain = `Specify how the swapchain (final rendered image) is composed, e.g. 'sdr', 'hdr', -and present mode like 'vsync' or 'immediate'. - -:param composition: E.g. 'sdr', 'linear', or 'hdr'. -:param presentMode: E.g. 'vsync', 'immediate', 'mailbox'. -:return: None -`; - -prosperon.c_types.SDL_GPUDevice[prosperon.DOC].sort_sprite = `A comparator function used for sorting sprite objects by layer, y, and texture. -Usually used internally. - -:param a: A sprite object. -:param b: Another sprite object. -:return: <0, 0, or >0 for sort ordering. -`; - -prosperon.c_types.SDL_GPUDevice[prosperon.DOC].make_sampler = `Create a sampler object specifying filtering, wrapping, anisotropy, etc. - -:param samplerDesc: An object with min_filter, mag_filter, etc. -:return: SDL_GPUSampler handle. -`; - -prosperon.c_types.SDL_GPUDevice[prosperon.DOC].load_texture = `Upload an SDL_Surface into a GPU texture, optionally compressing with DXT. Freed automatically. - -:param surface: An SDL_Surface. -:param compressionLevel: 0=none, 1=DXT1 or DXT5, 2=high quality, etc. -:return: SDL_GPUTexture -`; - -prosperon.c_types.SDL_GPUDevice[prosperon.DOC].texture = `Create a GPU texture with the specified format usage. - -:param desc: Object with {width, height, layers, type, format, usage, etc.} -:return: SDL_GPUTexture -`; - -prosperon.c_types.SDL_GPUDevice[prosperon.DOC].make_quad = `Return a simple 2-triangle quad geometry covering [0,1]x[0,1]. -Useful for post-processing passes. - -:return: A mesh {pos, uv, color, indices}. -`; - -prosperon.c_types.SDL_GPUDevice[prosperon.DOC].driver = `Return the name of the underlying GPU driver in use (e.g. 'OpenGL'). - -:return: A string with driver name. -`; - -prosperon.c_types.SDL_GPUDevice[prosperon.DOC].make_shader = `Compile raw shader code (vertex or fragment) in e.g. SPIR-V, MSL, or DXIL format. - -:param desc: {code:ArrayBuffer, stage:'vertex'|'fragment', format:'spv'|..., entrypoint:'main', ...} -:return: SDL_GPUShader object -`; - -prosperon.c_types.SDL_GPUDevice[prosperon.DOC].acquire_cmd_buffer = `Obtain a new command buffer for recording GPU commands. Must be submitted or canceled. - -:return: SDL_GPUCommandBuffer handle -`; - -prosperon.c_types.SDL_GPUDevice[prosperon.DOC].upload = `Upload CPU data into a list of GPU buffers, optionally reusing or returning a -transfer buffer. Typically you provide (cmdBuf, arrayOfTypedArrays, [transferBuffer]). - -:param cmdBuffer: The command buffer in which to record copy commands. -:param buffers: An array of typed-array data to upload, each must have a 'gpu' property or so. -:param transferBuffer: Optional existing GPU transfer buffer to reuse. -:return: The transfer buffer used or newly created. -`; - -prosperon.c_types.SDL_GPUDevice[prosperon.DOC].wait_for_fences = `Wait on an array of GPU fence objects, optionally requiring all or any. - -:param fences: An array of SDL_GPUFence objects. -:param waitAll: Boolean, true to wait for all fences, false for any. -:return: True if fences signaled, false on timeout or error. -`; - -prosperon.c_types.SDL_GPUDevice[prosperon.DOC].query_fence = `Check if the given fence has been signaled yet. Non-blocking. - -:param fence: SDL_GPUFence handle -:return: True if signaled, false if still pending -`; - -prosperon.c_types.SDL_GPUDevice[prosperon.DOC].shader_format = `Return an array of supported GPU shader binary formats (like 'spv', 'dxbc', etc.). - -:return: Array of strings naming supported formats. -`; - -prosperon.c_types.SDL_GPUDevice[prosperon.DOC].slice9 = `Generate a 9-slice tiling geometry in one shot. For advanced usage with GPU pipeline. - -:param texture: An SDL_GPUTexture -:param dstRect: The rectangle {x, y, w, h} -:param edges: {l, r, t, b} edge sizes -:return: A mesh object -`; - -prosperon.c_types.SDL_GPUDevice[prosperon.DOC].tile = `Generate geometry to tile a texture portion inside a dest rect. -Often used for repeating backgrounds. - -:param texture: The SDL_GPUTexture -:param srcRect: The portion to tile in pixels -:param dstRect: Where to fill -:param tileInfo: e.g. {repeat_x:true, repeat_y:true} -:return: A mesh object -`; - - -// -// SDL_GPUCommandBuffer -// -prosperon.c_types.SDL_GPUCommandBuffer[prosperon.DOC] = {} -prosperon.c_types.SDL_GPUCommandBuffer[prosperon.DOC][prosperon.DOC] = `A command buffer that accumulates rendering, copy, and compute operations. Freed after submission or GC. -`; - -prosperon.c_types.SDL_GPUCommandBuffer[prosperon.DOC].render_pass = `Begin a render pass with color/depth attachments. Provide an object with -'color_targets' and optional 'depth_stencil'. Returns an SDL_GPURenderPass handle. - -:param passDesc: {color_targets:[...], depth_stencil:...} -:return: SDL_GPURenderPass -`; - -prosperon.c_types.SDL_GPUCommandBuffer[prosperon.DOC].compute_pass = `Begin a compute pass reading/writing given arrays of textures and buffers. - -:param storageTextures: array of read/write textures -:param storageBuffers: array of read/write buffers -:return: SDL_GPUComputePass -`; - -prosperon.c_types.SDL_GPUCommandBuffer[prosperon.DOC].swapchain_pass = `Begin a render pass that directly targets the swapchain (the window). Clears -with the specified color. - -:param clearColor: [r,g,b,a] -:return: SDL_GPURenderPass -`; - -prosperon.c_types.SDL_GPUCommandBuffer[prosperon.DOC].acquire_swapchain = `Acquire the current swapchain texture from the window. Internal usage. - -:return: SDL_GPUTexture handle -`; - -prosperon.c_types.SDL_GPUCommandBuffer[prosperon.DOC].bind_vertex_buffer = `Bind a GPU buffer as the vertex buffer at a given slot. - -:param slot: Integer slot index. -:param buffer: The SDL_GPUBuffer. -:return: None -`; - -prosperon.c_types.SDL_GPUCommandBuffer[prosperon.DOC].bind_index_buffer = `Bind a GPU buffer as the index buffer (16-bit or 32-bit). - -:param buffer: The SDL_GPUBuffer. -:param offset: Optional offset in bytes. -:return: None -`; - -prosperon.c_types.SDL_GPUCommandBuffer[prosperon.DOC].bind_fragment_sampler = `Bind a texture+sampler pair to a particular fragment shader slot. - -:param slot: Index of the sampler binding. -:param texture: The SDL_GPUTexture -:param sampler: The SDL_GPUSampler -:return: None -`; - -prosperon.c_types.SDL_GPUCommandBuffer[prosperon.DOC].push_vertex_uniform_data = `Push raw data to a vertex shader uniform block. - -:param slot: The uniform buffer slot. -:param data: An ArrayBuffer with the data to upload. -:return: None -`; - -prosperon.c_types.SDL_GPUCommandBuffer[prosperon.DOC].push_fragment_uniform_data = `Push raw data to a fragment shader uniform block. - -:param slot: The uniform buffer slot index. -:param data: An ArrayBuffer with uniform data. -:return: None -`; - -prosperon.c_types.SDL_GPUCommandBuffer[prosperon.DOC].push_compute_uniform_data = `Push raw data to a compute shader uniform buffer. - -:param slot: The uniform buffer slot. -:param data: An ArrayBuffer with the data. -:return: None -`; - -prosperon.c_types.SDL_GPUCommandBuffer[prosperon.DOC].submit = `Submit this command buffer to the GPU and return a fence for synchronization. - -:return: An SDL_GPUFence -`; - -prosperon.c_types.SDL_GPUCommandBuffer[prosperon.DOC].cancel = `Cancel (discard) this command buffer without submitting. - -:return: None -`; - -prosperon.c_types.SDL_GPUCommandBuffer[prosperon.DOC].camera = `Write a camera transform (projection/view) to a uniform slot for 3D or 2D usage. - -:param cameraTransform: A camera object or transform with .pos, fov, etc. -:param uniformSlot: The integer uniform buffer slot to which data is pushed. -:return: None -`; - -prosperon.c_types.SDL_GPUCommandBuffer[prosperon.DOC].hud = `Write an orthographic full-screen "HUD" matrix to a uniform slot. Typically used -for 2D overlays. - -:param sizeVec2: [width, height] of the viewport area. -:param uniformSlot: The integer uniform buffer slot. -:return: None -`; - -prosperon.c_types.SDL_GPUCommandBuffer[prosperon.DOC].push_debug_group = `Push a named debug group marker onto the GPU command list (for debuggers/profilers). - -:param name: The debug label string. -:return: None -`; - -prosperon.c_types.SDL_GPUCommandBuffer[prosperon.DOC].pop_debug_group = `Pop the most recent debug group marker. - -:return: None -`; - -prosperon.c_types.SDL_GPUCommandBuffer[prosperon.DOC].debug_label = `Insert a one-off debug label at the current spot in the command list. - -:param label: The debug label string -:return: None -`; - -prosperon.c_types.SDL_GPUCommandBuffer[prosperon.DOC].blit = `Blit one GPU texture to another with optional flip mode, filter, and clear operations. - -:param blitDesc: { src:{texture,mip_level, etc}, dst:{texture,...}, load_op, flip, filter, clear_color:[r,g,b,a] } -:return: None -`; - - -// -// SDL_GPURenderPass -// -prosperon.c_types.SDL_GPURenderPass[prosperon.DOC] = {} -prosperon.c_types.SDL_GPURenderPass[prosperon.DOC][prosperon.DOC] = `A single pass of drawing commands with color/depth attachments. Freed after end() or GC. -`; - -prosperon.c_types.SDL_GPURenderPass[prosperon.DOC].bind_pipeline = `Bind a previously created graphics pipeline (shaders, states, vertex layouts, etc.). - -:param pipeline: The SDL_GPUGraphicsPipeline -:return: None -`; - -prosperon.c_types.SDL_GPURenderPass[prosperon.DOC].viewport = `Set the viewport for clipping or scaling draws, in pass-local coordinates. - -:param rect: {x,y,w,h} -:return: None -`; - -prosperon.c_types.SDL_GPURenderPass[prosperon.DOC].scissor = `Set a scissor rectangle for discarding pixels outside it. - -:param rect: {x,y,w,h} -:return: None -`; - -prosperon.c_types.SDL_GPURenderPass[prosperon.DOC].draw = `Issue a non-indexed draw call. - -:param primitiveType: e.g. SDL_GPU_PRIMITIVETYPE_TRIANGLELIST -:param baseVertex: Starting vertex offset. -:param firstVertex: The first vertex to draw. -:param vertexCount: How many vertices to draw. -:return: None -`; - -prosperon.c_types.SDL_GPURenderPass[prosperon.DOC].draw_indexed = `Issue an indexed draw call from the bound index buffer. - -:param primitiveType: The primitive type constant. -:param baseVertex: Offset in the vertex buffer. -:param firstIndex: Which index to start from. -:param indexCount: Number of indices to draw. -:param instanceCount: For instanced drawing, or 1 if normal. -:return: None -`; - -prosperon.c_types.SDL_GPURenderPass[prosperon.DOC].end = `End this render pass, finalizing the draw operations. - -:return: None -`; - -prosperon.c_types.SDL_GPURenderPass[prosperon.DOC].bind_index_buffer = `Bind an index buffer inside this pass, possibly overriding the global one. - -:param buffer: The SDL_GPUBuffer -:param elementSize16bit: If 2, uses 16-bit indices; if 4, uses 32-bit indices -:return: None -`; - -prosperon.c_types.SDL_GPURenderPass[prosperon.DOC].bind_buffers = `Bind multiple vertex buffers at consecutive slots. - -:param firstSlot: The starting vertex buffer slot. -:param arrayOfBuffers: An array of GPUBuffer objects -:return: None -`; - -prosperon.c_types.SDL_GPURenderPass[prosperon.DOC].bind_samplers = `Bind multiple texture/sampler pairs to either vertex or fragment slots. - -:param vertexOrFragment: Boolean, true for vertex stage, false for fragment. -:param firstSlot: The first sampler slot to bind. -:param samplerBindings: An array of {texture, sampler}. -:return: None -`; - -prosperon.c_types.SDL_GPURenderPass[prosperon.DOC].bind_storage_buffers = `Bind one or more storage buffers for read/write in the pipeline. - -:param firstSlot: Starting buffer slot index. -:param buffers: An array of SDL_GPUBuffer objects. -:return: None -`; - -prosperon.c_types.SDL_GPURenderPass[prosperon.DOC].bind_storage_textures = `Bind one or more storage textures for read/write in the pipeline. - -:param firstSlot: Starting texture slot index. -:param textures: An array of SDL_GPUTexture objects. -:return: None -`; - -// -// SDL_GPUComputePass -// -prosperon.c_types.SDL_GPUComputePass[prosperon.DOC] = {} -prosperon.c_types.SDL_GPUComputePass[prosperon.DOC][prosperon.DOC] = `A compute pass for dispatching compute pipelines. Freed after end() or GC. -`; - -prosperon.c_types.SDL_GPUComputePass[prosperon.DOC].dispatch = `Dispatch the compute pipeline with the specified threadgroup counts. - -:param x: Number of groups in X dimension -:param y: Number of groups in Y dimension -:param z: Number of groups in Z dimension -:return: None -`; - -prosperon.c_types.SDL_GPUComputePass[prosperon.DOC].end = `End this compute pass. - -:return: None -`; - -prosperon.c_types.SDL_GPUComputePass[prosperon.DOC].pipeline = `Bind a compute pipeline in this pass. - -:param computePipeline: The SDL_GPUComputePipeline -:return: None -`; - -prosperon.c_types.SDL_GPUComputePass[prosperon.DOC].samplers = `Bind a set of texture/sampler pairs for compute usage. - -:param arrayOfSamplerBindings: e.g. [ {texture, sampler}, ...] -:param firstSlot: The starting sampler slot. -:return: None -`; - -prosperon.c_types.SDL_GPUComputePass[prosperon.DOC].storage_buffers = `Bind an array of storage buffers for the compute shader. - -:param arrayOfBuffers: The buffers -:param firstSlot: Starting binding slot. -:return: None -`; - -prosperon.c_types.SDL_GPUComputePass[prosperon.DOC].storage_textures = `Bind an array of storage textures for the compute shader. - -:param arrayOfTextures: The textures -:param firstSlot: Starting binding slot -:return: None -`; - - -// -// SDL_GPUCopyPass -// -prosperon.c_types.SDL_GPUCopyPass[prosperon.DOC] = {} -prosperon.c_types.SDL_GPUCopyPass[prosperon.DOC][prosperon.DOC] = `A pass for CPU<->GPU or GPU<->GPU copy operations. No direct JS API besides internal usage. -`; - -// -// SDL_GPUFence -// -prosperon.c_types.SDL_GPUFence[prosperon.DOC] = {} -prosperon.c_types.SDL_GPUFence[prosperon.DOC][prosperon.DOC] = `A GPU fence for synchronization. Created upon commandBuffer.submit(). -Wait or query it with device.wait_for_fences or device.query_fence. -`; - -// -// SDL_GPUTransferBuffer -// -prosperon.c_types.SDL_GPUTransferBuffer[prosperon.DOC] = {} -prosperon.c_types.SDL_GPUTransferBuffer[prosperon.DOC][prosperon.DOC] = `A staging buffer used for copying data to or from GPU buffers/textures. Typically -allocated/used internally by device.upload(...). -`; - -// -// SDL_GPUShader -// -prosperon.c_types.SDL_GPUShader[prosperon.DOC] = {} -prosperon.c_types.SDL_GPUShader[prosperon.DOC][prosperon.DOC] = `A single compiled shader (vertex or fragment) in a GPU-friendly format -(e.g., SPIR-V, MSL). Combined into a pipeline for drawing. -`; - -// -// SDL_GPUSampler -// -prosperon.c_types.SDL_GPUSampler[prosperon.DOC] = {} -prosperon.c_types.SDL_GPUSampler[prosperon.DOC][prosperon.DOC] = `Defines how a texture is sampled (filter mode, address mode, anisotropy, compare op, etc.). -`; - -// -// SDL_GPUGraphicsPipeline -// -prosperon.c_types.SDL_GPUGraphicsPipeline[prosperon.DOC] = {} -prosperon.c_types.SDL_GPUGraphicsPipeline[prosperon.DOC][prosperon.DOC] = `Encapsulates vertex+fragment shaders, blend/cull states, and vertex attribute layouts. -Created via device.make_pipeline(...). -`; - -// -// SDL_GPUComputePipeline -// -prosperon.c_types.SDL_GPUComputePipeline[prosperon.DOC] = {} -prosperon.c_types.SDL_GPUComputePipeline[prosperon.DOC][prosperon.DOC] = `Encapsulates a compute shader program plus associated resource layouts. -Created via device.compute_pipeline(...). -`; - - var listeners = new Map() prosperon.on = function(type, callback) { @@ -1224,7 +93,7 @@ var script_fn = function script_fn(path) { } var content = io.slurp(file) - var parsed = parse_file(content) + var parsed = parse_file(content, file) var module_name = file.name() parsed.module_ret = bare_load(path) parsed.module_ret ??= {} @@ -1306,10 +175,14 @@ console.log = function(msg) { pprint(msg, 2) } console.error = function(e) { - if (!e) e = new Error() + if (!e) + e = new Error() - pprint(`${e.name} : ${e.message} + if (e instanceof Error) + pprint(`${e.name} : ${e.message} ${e.stack}`, 4) + else + pprint(e,4) } console.panic = function(e) { pprint(e, 5) @@ -1400,11 +273,9 @@ globalThis.use = function use(file) { return use_cache[file] } -//use[prosperon.DOC] = 'Return the value from the provided path to a module'. - globalThis.json = use('json') -function parse_file(content) { +function parse_file(content, file) { if (!content) return {} var parts = content.split(/\n\s*---\s*\n/) if (parts.length === 1) { @@ -1414,19 +285,22 @@ function parse_file(content) { return { program: part } } var module = parts[0] - if (!module.match(/return\s+[^;]+;?\s*$/)) - throw new Error("Module section must end with a return statement") + if (!/\breturn\b/.test(module)) + throw new Error(`Malformed file: ${file}. Module section must end with a return statement.`); - var pad = '\n'.repeat(module.split('\n').length+2) + try { + new Function(module)() + } catch (e) { + throw new Error(`Malformed file: ${file}. Module section must end with a return statement.\n` + e.message); + } + + var pad = '\n'.repeat(module.split('\n').length+4) return { module, program: pad+parts[1] } } -////////////////// -// REGISTRANT -///////////////// globalThis.Register = { registries: [], @@ -1526,7 +400,7 @@ function cant_kill() { actor.toString = function() { return this[FILE] } actor.spawn = function spawn(script, config, callback) { - if (this[DEAD]) throw Error("Attempting to spawn on a dead actor") + if (this[DEAD]) throw new Error("Attempting to spawn on a dead actor") var prog if (!script) { prog = {} @@ -1629,6 +503,7 @@ actor.kill = function kill() { actor.kill.doc = `Remove this actor and all its underlings from existence.` actor.delay = function(fn, seconds) { + if (this[DEAD]) return add_timer(this, fn, seconds) } actor.delay.doc = `Call 'fn' after 'seconds' with 'this' set to the actor.` @@ -1638,47 +513,12 @@ actor[UNDERLINGS] = new Set() globalThis.mixin("color") +var DOCPATH = 'scripts/core/doc.js' +var script = io.slurp(DOCPATH) +var fnname = "doc" +script = `(function ${fnname}() { ${script}; })` +js.eval(DOCPATH, script)() + use('cmd')(prosperon.argv) -// --------------------------------------------------------------------------- -// Documentation blocks following the style shown in time.js -// --------------------------------------------------------------------------- - -// Document the main prosperon object -prosperon[prosperon.DOC] = { - doc: `The main prosperon object providing event dispatch, signal handling, and engine management.`, - DOC: `Symbol used to store documentation references on objects.`, - on: `Register a callback function for a given event type. Returns a function to remove the callback.`, - dispatch: `Dispatch an event of the given type, calling all registered callbacks with the provided data.`, - PATH: `Array of directory paths that Prosperon will search to find scripts or modules.`, - c_types: `Prototype objects for all present defined c-types (like sprite, transform, etc)` -} - -// Document the actor object/prototype -actor[prosperon.DOC] = { - doc: `The actor object/prototype, serving as a base for all game actors or entities.`, - spawn: `Create a new actor from a script, optionally applying a config object, then call the new actor's 'awake' method.`, - kill: `Destroy this actor, removing it from the game along with all underlings. Frees resources and triggers garbage if defined.`, - clear: `Remove all child (underling) actors by calling kill on each.`, - delay: `Schedule a function to be called after a specified delay (in seconds) on this actor.`, - toString: `Return the script filename associated with this actor instance.` -} - -// Expand console.doc to document the console object and missing methods -console[prosperon.DOC] = {} -console[prosperon.DOC][prosperon.DOC] = `The console object provides various logging, debugging, and output methods.` -console[prosperon.DOC].spam = `Output a spam-level message for very verbose logging.` -console[prosperon.DOC].debug = `Output a debug-level message.` -console[prosperon.DOC].panic = `Output a panic-level message and exit the program.` -console[prosperon.DOC].assert = `If the condition is false, print an error and panic.` - -// Document the Register object -Register[prosperon.DOC] = { - doc: `Factory for creating and managing event registries (e.g. update, draw, etc.) within Prosperon.`, - add_cb: `Create or retrieve a registry for an event type, exposing a 'register' method for callbacks.`, - pull_registers: `Gather the names of all recognized event methods implemented by an object.`, - register_obj: `Bind an object's event method to the relevant registry. The unregistration handle goes in the actor's timers.`, - check_registers: `Automatically register recognized events (like 'update', 'gui', etc.) on an object.`, -} - })() diff --git a/scripts/modules/graphics.js b/scripts/modules/graphics.js index 77eaca02..b5db4151 100644 --- a/scripts/modules/graphics.js +++ b/scripts/modules/graphics.js @@ -18,40 +18,60 @@ Internally loads image data from disk and prepares a GPU texture. Used by graphi Not intended for direct user calls. */ function create_image(path) { - var data = io.slurpbytes(path) - var newimg - switch (path.ext()) { - case 'gif': - newimg = graphics.make_gif(data) - if (newimg.surface) - newimg.texture = prosperon.gpu.load_texture(newimg.surface) - else - for (var frame of newimg.frames) - frame.texture = prosperon.gpu.load_texture(frame.surface) - break - case 'ase': - case 'aseprite': - newimg = graphics.make_aseprite(data) - if (newimg.surface) - newimg.texture = prosperon.gpu.load_texture(newimg.surface) - else { - for (var anim in newimg) { - var a = newimg[anim] - for (var frame of a.frames) - frame.texture = prosperon.gpu.load_texture(frame.surface) + try { + var data = io.slurpbytes(path); + var newimg; + + switch (path.ext()) { + case 'gif': + newimg = graphics.make_gif(data); + if (newimg.surface) { + newimg.texture = prosperon.gpu.load_texture(newimg.surface); + } else { + for (var frame of newimg.frames) { + frame.texture = prosperon.gpu.load_texture(frame.surface); + } } - } - break - default: - newimg = { - surface: graphics.make_texture(data) - } - newimg.texture = prosperon.gpu.load_texture(newimg.surface) - break + break; + + case 'ase': + case 'aseprite': + newimg = graphics.make_aseprite(data); + if (newimg.surface) { + newimg.texture = prosperon.gpu.load_texture(newimg.surface); + } else { + for (var anim in newimg) { + var a = newimg[anim]; + for (var frame of a.frames) { + frame.texture = prosperon.gpu.load_texture(frame.surface); + } + } + } + break; + + default: + newimg = { + surface: graphics.make_texture(data) + }; + newimg.texture = prosperon.gpu.load_texture(newimg.surface); + break; + } + + return newimg; + + } catch (e) { + // Add the path to the error message for better debugging + console.error(`Error loading image from path: ${path}`); + console.error(e.message); + if (e.stack) { + console.error(e.stack); + } + // Optionally, you can throw the error again to let it propagate + throw e; } - return newimg } + var image = {} image.dimensions = function() { return [this.texture.width, this.texture.height].scale([this.rect[2], this.rect[3]]) diff --git a/scripts/modules/resources.js b/scripts/modules/resources.js index e17de0ed..d2614e96 100644 --- a/scripts/modules/resources.js +++ b/scripts/modules/resources.js @@ -41,8 +41,6 @@ function isRecognizedExtension(ext) { return false } -// Attempt to find file with or without extension from the current PATH -// (From the original resources.js, unchanged except for code style) function find_in_path(filename, exts = []) { if (filename.includes('.')) { for (var dir of prosperon.PATH) { @@ -53,10 +51,15 @@ function find_in_path(filename, exts = []) { } for (var dir of prosperon.PATH) { - var candidate = dir + filename - if (io.exists(candidate) && !io.is_directory(candidate)) return candidate - for (var ext of exts) { - candidate = dir + filename + '.' + ext + // Only check extensions if exts is provided and not empty + if (exts.length > 0) { + for (var ext of exts) { + var candidate = dir + filename + '.' + ext + if (io.exists(candidate) && !io.is_directory(candidate)) return candidate + } + } else { + // Fallback to extensionless file only if no extensions are specified + var candidate = dir + filename if (io.exists(candidate) && !io.is_directory(candidate)) return candidate } } diff --git a/source/qjs_soloud.c b/source/qjs_soloud.c index d826faa6..aa8d894e 100644 --- a/source/qjs_soloud.c +++ b/source/qjs_soloud.c @@ -62,8 +62,14 @@ typedef unsigned int voice; static Soloud *soloud; +void voice_free(unsigned int *voice) +{ + Soloud_stop(soloud, *voice); + free(voice); +} + JSCLASS(Wav, Wav_destroy) -JSCLASS(voice, free) +JSCLASS(voice, voice_free) JSCLASS(Bus, Bus_destroy) static JSValue js_soloud_make(JSContext *js, JSValue self, int argc, JSValue *argv)