Struct SoftwareRenderer 

pub struct SoftwareRenderer { /* private fields */ }

CPU rasterizer implementing the Renderer trait.

All drawing operations write into an internal RGBA8 framebuffer. The framebuffer can be read back via framebuffer() or into_framebuffer().

Implementations

impl SoftwareRenderer

pub fn new(width: u32, height: u32) -> Self

Creates a software renderer with the given framebuffer dimensions.

pub fn with_color(width: u32, height: u32, color: [f32; 4]) -> Self

Creates a software renderer with a solid background color.

pub fn framebuffer(&self) -> &Framebuffer

Returns a reference to the internal framebuffer.

pub fn width(&self) -> u32

Returns the width of the framebuffer.

pub fn height(&self) -> u32

Returns the height of the framebuffer.

Trait Implementations

impl ElapsedTime for SoftwareRenderer

fn elapsed_time(&self) -> f32

Returns the cumulative time since the renderer started in seconds.

fn delta_time(&self) -> f32

Returns the time elapsed since the last frame in seconds.

impl Renderer for SoftwareRenderer

fn measure_text(&mut self, text: &str, size: f32) -> (f32, f32)

Measures text dimensions using a fast, deterministic monospace estimation.

fn shape_rich_text( &mut self, spans: &[TextSpan], max_width: Option<f32>, align: TextAlign, overflow: TextOverflow, ) -> Option<ShapedText>

Shapes rich text spans using the Runic text layout engine. Returns None if the “text” feature is disabled.

fn draw_shaped_text(&mut self, _text: &ShapedText, _x: f32, _y: f32)

Renders pre-shaped text layout. (Stubbed out for software renderer fallback).

fn fill_rect(&mut self, rect: Rect, color: [f32; 4])

fn fill_rounded_rect(&mut self, rect: Rect, radius: f32, color: [f32; 4])

fn fill_ellipse(&mut self, rect: Rect, color: [f32; 4])

Fill an ellipse/circle that fits inside rect.

fn fill_glass_rect(&mut self, rect: Rect, radius: f32, blur_radius: f32)

Fill a rounded rect with glass material for frosted backdrop effect. This is the proper way to render glass cards for macOS Tahoe-style blur. The blur_radius controls the intensity of the backdrop blur.

fn fill_glass_rect_with_intensity( &mut self, rect: Rect, radius: f32, blur_radius: f32, glass_intensity: f32, )

Fill a rounded rect with glass material with explicit intensity control. glass_intensity ranges from 0.0 (solid) to 1.0 (full glass). Default: 1.0.

fn stroke_rect(&mut self, rect: Rect, color: [f32; 4], stroke_width: f32)

fn stroke_rounded_rect( &mut self, rect: Rect, radius: f32, color: [f32; 4], stroke_width: f32, )

fn stroke_ellipse(&mut self, rect: Rect, color: [f32; 4], stroke_width: f32)

Stroke an ellipse/circle that fits inside rect.

fn draw_line( &mut self, x1: f32, y1: f32, x2: f32, y2: f32, color: [f32; 4], stroke_width: f32, )

Draw a straight line from (x1,y1) to (x2,y2).

fn draw_focus_ring( &mut self, rect: Rect, radius: f32, offset: f32, width: f32, color: [f32; 4], )

Draw a focus ring around a rect (for keyboard navigation accessibility). offset is the gap between the rect and the ring, width is the ring thickness.

fn draw_linear_gradient( &mut self, rect: Rect, start_color: [f32; 4], end_color: [f32; 4], _angle: f32, )

Draw a linear gradient between two colors at the specified angle.

fn draw_texture(&mut self, texture_id: u32, _rect: Rect)

Draw a texture (GPU-side) at the specified rect.

fn draw_image(&mut self, image_name: &str, _rect: Rect)

Draw an image asset by name or path.

fn draw_svg(&mut self, name: &str, _rect: Rect)

Draw a pre-loaded SVG model.

fn draw_mesh(&mut self, _mesh: &Mesh, _color: [f32; 4], _transform: Mat4)

Draw a 3D mesh.

fn draw_mesh_3d( &mut self, _mesh: &Mesh, _material: &Material3D, _transform: &Transform3D, )

Draw a 3D mesh with full material and transform support.

fn fill_glass_rect_with_pressure( &mut self, _rect: Rect, _radius: f32, _blur_radius: f32, _pressure: f32, )

Fill a rounded rect with glass material, modulated by touch pressure. pressure ranges from 0.0 (no touch) to 1.0 (full pressure). When pressure > 0, refraction distortion is scaled by pressure amount. Desktop stub: pressure is always 1.0 for mouse clicks, 0.0 otherwise.

fn draw_hologram(&mut self, _rect: Rect, hologram_id: &str, _time: f32)

Draws a volumetric hologram into the specified bounding rectangle.

fn memoize( &mut self, id: u64, data_hash: u64, render_fn: &dyn Fn(&mut dyn Renderer), )

Execute a render function with memoization. If the renderer supports caching and the id + data_hash match a previous run, it may replay cached commands instead of executing the function.

fn request_redraw(&mut self)

Requests that the renderer redraws as soon as possible. Used for continuous animations.

fn is_over_budget(&self) -> bool

Returns true if the current frame is over the time budget. This can be used to skip expensive visual effects.

fn draw_background_image(&mut self, image_name: &str, rect: Rect)

Draw a background image that fills the entire rect. This is a convenience wrapper around draw_image for the common case of a full-rect background. The image must have been pre-warmed via prewarm_vram before the first frame.

fn fill_glass_rect_with_tint( &mut self, rect: Rect, radius: f32, blur_radius: f32, tint_color: [f32; 4], glass_intensity: f32, )

Fill a rounded rect with glass material with explicit tint color and intensity. tint_color is the glass fill color (RGBA). glass_intensity ranges from 0.0 (solid) to 1.0 (full glass).

fn fill_squircle(&mut self, rect: Rect, _n: f32, color: [f32; 4])

Fill a squircle (superellipse) for Apple-style icon silhouettes. n controls the squareness: 2.0 = rounded rect, 4.0 = classic squircle, higher = more square.

fn stroke_squircle( &mut self, rect: Rect, _n: f32, color: [f32; 4], stroke_width: f32, )

Stroke a squircle (superellipse) outline.

fn draw_3d_cube(&mut self, _rect: Rect, _color: [f32; 4], _rotation: [f32; 3])

Draw a high-fidelity 3D cube inside the given rectangle using specialized shader logic. rotation is [pitch, yaw, roll] in radians.

fn fill_polygon(&mut self, _vertices: &[[f32; 2]], _color: [f32; 4])

Fill a polygon defined by a set of vertices.

fn stroke_polygon( &mut self, _vertices: &[[f32; 2]], _color: [f32; 4], _stroke_width: f32, )

Stroke a polygon defined by a set of vertices.

fn draw_text( &mut self, text: &str, rect: &Rect, size: f32, color: [f32; 4], h_align: TextHAlign, v_align: TextVAlign, )

Draw text aligned within a bounding box. This is the primary method — callers should use this for proper vertical and horizontal alignment within their layout rects.

fn draw_text_raw( &mut self, text: &str, x: f32, y: f32, size: f32, color: [f32; 4], )

Draw text at a raw baseline position (x = left, y = baseline). Use this when you need precise control over baseline positioning.

fn draw_text_centered( &mut self, text: &str, rect: &Rect, size: f32, color: [f32; 4], )

Draw text centered within a bounding box (convenience).

fn measure_text_baseline(&mut self, text: &str, size: f32) -> f32

Return the baseline offset (ascent) for the given text and size. This is the distance from the text origin (y in draw_text) to the baseline. Default returns 0.0; override in renderers that support text shaping.

fn text_scale_factor(&self) -> f32

Scale factor used by text measurement helpers.

fn load_image(&mut self, _name: &str, _data: &[u8])

Load an image asset from memory.

fn prewarm_vram(&mut self, _assets: Vec<(String, Vec<u8>)>)

Pre-warm the renderer with assets. Implementations can use this to populate texture atlases or warm up shader caches.

fn get_pointer_position(&self) -> [f32; 2]

Get the current pointer (mouse/touch) position.

fn upload_data_texture( &mut self, _id: &str, _data: &[f32], _width: u32, _height: u32, )

Upload raw float data as a GPU texture for heatmap rendering.

fn draw_heatmap(&mut self, _texture_id: &str, _rect: Rect, _palette: &str)

Draw a heatmap using a previously uploaded data texture.

fn set_camera_3d(&mut self, _camera: &Camera3D)

Set the 3D camera for perspective/orthographic projection. If not called, rendering defaults to the 2D orthographic projection.

fn push_transform_3d(&mut self, _transform: &Transform3D)

Push a 3D transform onto the transform stack. All subsequent drawing is affected until pop_transform_3d.

fn pop_transform_3d(&mut self)

Pop the most recently pushed 3D transform.

fn render_scene_node_3d( &mut self, _position: [f32; 3], _rotation: [f32; 4], _scale: [f32; 3], _color: [f32; 4], _meshes: &[Mesh], )

Render a 3D scene graph node. Reads position_3d, rotation_3d, scale_3d from the node and emits the appropriate draw call. Default implementation is a no-op; 3D renderers override this.

fn draw_radial_gradient( &mut self, _rect: Rect, _inner_color: [f32; 4], _outer_color: [f32; 4], )

Draw a radial gradient between two colors.

fn draw_linear_gradient_multi( &mut self, _rect: Rect, _stops: &[[f32; 4]], _angle: f32, )

Draw a multi-stop linear gradient (GPU-accelerated). stops: array of [R, G, B, position] where position is 0.0-1.0. angle: gradient angle in radians.

fn draw_radial_gradient_multi(&mut self, _rect: Rect, _stops: &[[f32; 4]])

Draw a multi-stop radial gradient (GPU-accelerated). stops: array of [R, G, B, position] where position is 0.0-1.0.

fn draw_drop_shadow( &mut self, _rect: Rect, _radius: f32, _color: [f32; 4], _blur: f32, _spread: f32, )

Draw a high-fidelity drop shadow for a rounded rectangle.

fn stroke_dashed_rounded_rect( &mut self, _rect: Rect, _radius: f32, _color: [f32; 4], _width: f32, _dash: f32, _gap: f32, )

Draw a dashed border for a rounded rectangle.

fn draw_9slice( &mut self, _image_name: &str, _rect: Rect, _left: f32, _top: f32, _right: f32, _bottom: f32, )

Draw a 9-slice / patch scaled image.

fn push_clip_rect(&mut self, _rect: Rect)

Push a clip rectangle. All subsequent drawing is clipped to rect. Implementations that do not support clipping may ignore this call.

fn pop_clip_rect(&mut self)

Pop the most recently pushed clip rectangle.

fn current_clip_rect(&self) -> Rect

Get the current clip rectangle in screen coordinates. Returns a rect covering the entire screen if no clip is active.

fn push_opacity(&mut self, _opacity: f32)

Set a global opacity multiplier applied to all subsequent draw calls until pop_opacity is called. opacity is in [0.0, 1.0].

fn pop_opacity(&mut self)

Restore the previous opacity level.

fn set_theme(&mut self, _theme: ColorTheme)

fn set_rage(&mut self, _rage: f32)

fn set_berserker_mode(&mut self, _state: RenderIntensityMode)

fn trigger_shatter_event(&mut self, _origin: [f32; 2], _force: f32)

fn set_fireball_pos(&mut self, _pos: [f32; 2])

Set the fireball position for dynamic glass specular highlights.

fn set_scene(&mut self, _scene: &str)

Set the desktop scene preset (Aurora, Void, Nebula, Glitch, Yggdrasil).

fn set_scene_by_name(&mut self, name: &str)

Set the desktop scene by name. Case-insensitive. Supports: “aurora”, “void”, “nebula”, “glitch”, “yggdrasil”. Aliases: “empty”, “none”, “blank” → Void.

fn capture_png(&mut self) -> Vec<u8>

Capture the current frame as a PNG byte buffer.

fn print(&mut self)

Trigger a native print dialog or spooling operation.

fn set_scene_preset(&mut self, _preset: u32)

fn bifrost(&mut self, _rect: Rect, _blur: f32, _saturation: f32, _opacity: f32)

Apply a Bifrost (Frosted Glass) effect to the specified rect.

fn gungnir( &mut self, _rect: Rect, _color: [f32; 4], _radius: f32, _intensity: f32, )

Apply a Gungnir (Neon Glow) effect to the specified rect.

fn gungnir_soft( &mut self, _rect: Rect, _color: [f32; 4], _radius: f32, _intensity: f32, )

Soft glow variant – half the intensity of gungnir(). Use for hover highlights.

fn set_default_background_color(&mut self, _color: [f32; 4])

Set the default background color for the canvas (RGBA). Used when the app does not draw its own background.

fn mani_glow(&mut self, _rect: Rect, _color: [f32; 4], _radius: f32)

Apply a ManiGlow (Lunar Illuminator) effect.

fn push_mjolnir_slice(&mut self, _angle: f32, _offset: f32)

Push a Mjolnir Slice (geometric clipping).

fn pop_mjolnir_slice(&mut self)

fn snapshot_render_state(&self) -> RenderStateSnapshot

Capture current renderer stack depths for later panic recovery. The default implementation returns RenderStateSnapshot::default(), which is safe but does nothing useful – backends with stack state must override this to record their actual depths.

fn restore_render_state(&mut self, _snap: RenderStateSnapshot)

Restore renderer stack state by popping items pushed beyond the snapshot point. Used by ErrorBoundary to recover from mid-render panics so sibling views don’t inherit leaked clip/opacity/transform state. Idempotent: a no-op if stacks are already at or below the snapshot depths. Default implementation is a no-op for backends that have no stack state.

fn mjolnir_shatter( &mut self, _rect: Rect, _pieces: u32, _force: f32, _color: [f32; 4], )

Apply a Mjolnir Shatter effect (fragmentation) to the specified rect.

fn mjolnir_fluid_shatter( &mut self, _rect: Rect, _pieces: u32, _force: f32, _color: [f32; 4], )

fn draw_mjolnir_bolt( &mut self, _from: [f32; 2], _to: [f32; 2], _color: [f32; 4], )

fn dispatch_particles( &mut self, _origin: [f32; 2], _count: u32, _effect_type: &str, _color: [f32; 4], )

Dispatches a burst of GPU particles (e.g. fireworks, data streams).

fn set_aria_role(&mut self, _role: &str)

fn set_aria_label(&mut self, _label: &str)

fn set_aria_valuemin(&mut self, _min: f32)

fn set_aria_valuemax(&mut self, _max: f32)

fn set_aria_valuenow(&mut self, _now: f32)

fn register_a11y(&mut self, role: &str, label: &str)

Convenience method: register aria role and label in one call. Components with both role and label props should call this.

fn push_focus_trap(&mut self, _element_id: &str) -> u64

Push a focus trap onto the stack. While active, keyboard focus is trapped within the specified element and its children. Returns a trap ID that must be passed to pop_focus_trap.

fn pop_focus_trap(&mut self, _trap_id: u64)

Pop the most recently pushed focus trap.

fn register_shared_element(&mut self, _id: &str, _rect: Rect)

Register a shared element for Bifrost Bridge transitions.

fn set_key(&mut self, _key: &str)

Set a unique key for the current VDOM node to ensure stable identity during diffing.

fn get_telemetry(&self) -> TelemetryData

Get real-time performance telemetry.

fn push_shadow(&mut self, _radius: f32, _color: [f32; 4], _offset: [f32; 2])

Push a shadow state to the stack. All following draw calls will have this shadow.

fn pop_shadow(&mut self)

Pop the last shadow state from the stack.

fn push_vnode(&mut self, _rect: Rect, _name: &'static str)

Push a Virtual DOM node onto the stack for hierarchy tracking.

fn push_vnode_with_companions( &mut self, rect: Rect, name: &'static str, _companions: Vec<Box<dyn Companion>>, )

Push a Virtual DOM node with companion state auto-initialization. Default implementation ignores companions and delegates to push_vnode.

fn pop_vnode(&mut self)

Pop the current Virtual DOM node from the stack.

fn register_handler( &mut self, _event_type: &str, _handler: Arc<dyn Fn(Event) + Send + Sync>, )

Register an event handler for the current VDOM node.

fn current_companion(&self) -> Option<&(dyn Companion + 'static)>

Retrieve a companion state for the VNode currently at the top of the stack. Returns None if the companion type is not registered on this node.

fn set_z_index(&mut self, _z: f32)

Set the current Z-index for depth sorting. Higher values appear closer to the viewer.

fn get_z_index(&self) -> f32

Get the current Z-index.

fn load_svg(&mut self, _name: &str, _svg_data: &[u8])

fn draw_svg_with_offset( &mut self, name: &str, rect: Rect, _animation_time_offset: f32, )

Draw a pre-loaded SVG model with a per-instance animation time offset. The offset shifts the animation phase, allowing multiple draws of the same SVG to animate independently. Default delegates to draw_svg (no offset).

fn draw_svg_with_order(&mut self, name: &str, rect: Rect, _draw_order: i32)

Draw a pre-loaded SVG model with explicit draw_order for z-sorting. draw_order=200 renders above UI chrome (draw_order=0).

fn serialize_svg(&mut self, _name: &str) -> Result<String, String>

Serialize a pre-loaded SVG model back to SVG XML markup. Returns the serialized SVG string, or an error if the model is not loaded or serialization is not supported by this renderer.

fn apply_svg_filter( &mut self, _name: &str, _filter_id: &str, _region: Rect, ) -> Result<String, String>

Apply an SVG filter to a pre-loaded SVG model by filter element ID. The filter is evaluated and the result composited back into the SVG. Returns the filtered SVG as XML, or an error if not supported.

fn begin_world_space_panel( &mut self, node_id: u64, transform: &Transform3D, glass: Option<GlassMaterial>, pixels_per_unit: f32, world_size: (f32, f32), )

Called when the traversal enters a VNode with a WorldSpacePanel configured. Redirects subsequent draw calls into an offscreen texture for the panel, similar to push_target.

fn end_world_space_panel(&mut self, node_id: u64)

Called when the traversal exits a VNode with a WorldSpacePanel configured. Ends offscreen redirection and records the panel into the renderer state for 3D compositing later in the frame graph.

fn push_transform( &mut self, _translation: [f32; 2], _scale: [f32; 2], _rotation: f32, )

Push a 2D transform (translation, scale, rotation) onto the stack. This transform should be applied to all subsequent draw calls until popped. Transform-only animations use this to avoid re-triggering the layout engine.

fn push_affine(&mut self, _transform: [f32; 6])

Push a raw 2D affine transform matrix [a, b, c, d, e, f] corresponding to [m11, m12, m21, m22, tx, ty].

fn pop_transform(&mut self)

Pop the last 2D transform from the stack.

fn query_layout(&self, _node_id: KvasirId) -> Option<Rect>

Return the resolved layout bounds for a specific node ID if it exists.

fn set_debug_layout(&mut self, _enabled: bool)

Enable or disable the layout debug overlay (bounds, padding, margin).

fn get_debug_layout(&self) -> bool

Check if the layout debug overlay is currently enabled.

fn set_material(&mut self, _material: DrawMaterial)

Set the active material for subsequent draw calls. Controls which pass a draw call is routed to in the multi-pass pipeline.

fn current_material(&self) -> DrawMaterial

Return the currently active material (defaults to Opaque).

fn mimir_intent(&self) -> [f32; 2]

Compute the user’s velocity/intent vector.

fn magnetic_warp( &self, pointer: [f32; 2], anchor_rect: Rect, strength: f32, ) -> [f32; 2]

Calculate magnetic coordinate warp towards an anchor.

fn mani_glow_intensity( &self, pointer: [f32; 2], bounds: Rect, radius: f32, ) -> f32

Calculate kinematic glow intensity based on proximity.

fn fafnir_evolve(&self, pointer: [f32; 2], bounds: Rect, max_scale: f32) -> f32

Calculate dynamic element attention (scaling/morphing) statelessly per frame.

fn set_sdf_shape(&mut self, _shape: SdfShape)

Sets the precise Vili SDF Shape boundary for hit-testing.

fn push_theme(&mut self, _theme: ColorTheme)

Push a theme override for the current subtree. All child nodes rendered until pop_theme() are drawn with this theme.

fn pop_theme(&mut self)

Pop the theme override and restore the previous theme.

fn current_theme(&self) -> ColorTheme

Return the current theme at the current stack depth. Falls back to the default theme if no theme has been pushed.

fn save_theme(&mut self)

Save theme state for portal inheritance before entering a new buffer. Legacy — prefer using the theme stack (push_theme/pop_theme) instead.

fn restore_theme(&mut self)

Restore the saved theme when exiting a portal buffer. Legacy — prefer using the theme stack (push_theme/pop_theme) instead.

fn enter_portal(&mut self, _z_index: i32)

Begin rendering into the portal root layer instead of the inline tree. All draw calls between enter_portal and exit_portal are collected into a separate buffer that is composited AFTER the main tree.

fn exit_portal(&mut self)

Exit the portal layer and return to inline rendering. The portal content collected since enter_portal is now sealed – no more draw calls will be appended to it.

fn viewport_size(&self) -> Rect

Get the current viewport size in logical pixels. Used by portal content to size itself to the full screen.

fn announce(&mut self, _message: &str, _priority: AnnouncementPriority)

Announce a message to screen readers via the platform accessibility API. This call is non-blocking. The message is queued and the screen reader will speak it at its own pace.

impl RendererErrorHandler for SoftwareRenderer

fn on_render_error(&mut self, error: &CvkgError)

Called when a non-fatal render error occurs during a draw operation. The renderer continues operating. Backends should log and optionally track error counts for health monitoring.

fn on_fatal_error(&mut self, error: &CvkgError)

Called when a fatal error occurs that prevents further rendering. The backend should attempt graceful shutdown.

fn has_error(&self) -> bool

Returns true if the backend is in an error state.