oxiui-render-soft — Pure-Rust software (CPU) render backend for OxiUI

oxiui-render-soft is the Pure-Rust software renderer for OxiUI. It rasterizes a [oxiui_core::paint::DrawList] entirely on the CPU into an in-memory 0xAARRGGBB framebuffer — no GPU, no window, and no display connection required. Every pixel is produced by Rust code in this crate (with png for PNG export and the optional oxiui-text pipeline for glyph rasterization), making it the canonical backend for headless rendering, CI smoke tests, ffi-audit containers, and embedded targets.

The crate is built around a clip-correct [Canvas] that replays draw commands through a [ClipStack], plus a [SoftBackend] that implements [oxiui_core::paint::RenderBackend]. It includes a full 2-D rasterization stack — scanline polygon fill with anti-aliasing, Bézier paths, gradients, box shadows via Gaussian blur, ordered dithering, and a tile iterator for (optionally rayon-parallel) rendering. #![forbid(unsafe_code)] is enforced crate-wide.

Installation

[dependencies]
oxiui-render-soft = "0.2.1"

To build the GPU-free audit configuration explicitly, disable default features:

[dependencies]
oxiui-render-soft = { version = "0.2.1", default-features = false }

Quick Start

Render a scene headlessly and export it as a PNG — no display needed:

use oxiui_core::Color;
use oxiui_render_soft::headless::render_headless_scene;

# fn main() -> Result<(), oxiui_render_soft::SoftRenderError> {
let buffer = render_headless_scene(128, 96, |canvas| {
    canvas.fill_rect(16.0, 16.0, 64.0, 48.0, Color(255, 0, 0, 255));
    canvas.fill_circle(96.0, 48.0, 20.0, Color(0, 128, 255, 255));
});

assert_eq!(buffer.width, 128);
assert!(buffer.has_content());
buffer.save_png(std::path::Path::new("/tmp/scene.png"))?;
# Ok(())
# }

Replaying a DrawList through SoftBackend

use oxiui_core::paint::{DrawList, RenderBackend};
use oxiui_core::{geometry::Rect, Color};
use oxiui_render_soft::{SoftBackend, headless::PixelFormat};

# fn main() -> Result<(), oxiui_core::UiError> {
let mut backend = SoftBackend::with_background(64, 64, Color(26, 27, 38, 255));

let mut list = DrawList::new();
list.push_rect(Rect::new(8.0, 8.0, 48.0, 48.0), Color(255, 255, 255, 255));
backend.execute(&list)?;

// Export the framebuffer in any supported byte layout.
let bytes = backend.to_bytes(PixelFormat::Bgra8);
assert_eq!(bytes.len(), 4 * 64 * 64);
# Ok(())
# }

API Overview

Top-level renderer types

SoftBackend methods

SoftBackend implements [oxiui_core::paint::RenderBackend].

headless module

Display-free rendering helpers for CI / ffi-audit.

framebuffer module

draw module — Canvas

Canvas borrows a Framebuffer and owns a [ClipStack]; all drawing is clipped to the current effective clip with straight-alpha source-over compositing.

Glyph blitting helper: blit_glyph_bitmap(fb, x, y, w, h, pixels, color) (re-exported at crate root).

clip module

scanline module

path module

gradient module

blend module

shadow module

fft_blur module (fft-blur feature)

FFT-accelerated alternative to shadow::gaussian_blur_alpha for large blur kernels (radius ≥ 32px), using oxifft::convolve_mode.

simd_fill module

Pure-Rust SIMD (wide crate) bulk pixel operations behind the simd feature; every function also has a scalar fallback compiled in, so call sites never need to feature-gate.

backend_switch module (wgpu-compat feature)

Runtime CPU/GPU backend switching over the shared DrawList format.

canvas_upload module (canvas-2d feature)

Canvas 2D pixel upload path for wasm32 targets; native builds get no-op stubs that always return Ok(()).

dither module

tile module

Re-exports

When the theme feature is active, [oxiui_theme::ShadowSpec] is re-exported as oxiui_render_soft::ShadowSpec.

Feature Flags

Disable default features (default-features = false) for the GPU- and text-pipeline-free audit build.

Error Variants

SoftRenderError implements std::error::Error and Display.

SoftBackend::execute returns [oxiui_core::UiError] (the shared OxiUI error type).

Related Crates

• oxiui — the OxiUI facade crate.
• oxiui-core — RenderBackend, DrawList, DrawCommand, Color, UiError, geometry types.
• oxiui-render-wgpu — the GPU render path (wgpu) for comparison.
• oxiui-text — the text-shaping pipeline used by the text feature.
• oxiui-theme — design tokens and ShadowSpec used by the theme feature.

License

Apache-2.0 — COOLJAPAN OU (Team Kitasan)