Skip to main content

Crate dream_soft_render

Crate dream_soft_render 

Source
Expand description

A CPU rasterizer that turns 2D triangles into RGBA8 bytes, and does it the same way every time.

There is no GPU here, no window, no swapchain, and no driver to have opinions about your blend state. You hand dream-soft-render rectangles, textured rectangles, and triangle meshes; it writes premultiplied pixels into a buffer you own. What happens to the buffer afterwards (a Linux framebuffer, a PNG, a golden-test hash) is your business.

It exists because egui on a handheld with no usable GPU still has to draw something, and the CPU in those handhelds is a small ARM core that notices every wasted instruction. The hot paths recognize what they are drawing (solid rectangles, glyph quads, triangle fans) instead of treating everything as anonymous triangles, and the AArch64 NEON paths are held byte-for-byte to the portable code by tests.

§Drawing a Frame

use dream_soft_render::{ClipRect, Color, Mesh, Rect, SoftwareRenderer, Vertex};

let mut renderer = SoftwareRenderer::default();
let checkerboard = renderer.create_texture(2, 2, &[
    255, 255, 255, 255, 0, 0, 0, 255,
    0, 0, 0, 255, 255, 255, 255, 255,
])?;

let mut frame = renderer.begin_frame(64, 48)?;
frame.clear(Color::from_rgb(17, 20, 28));
frame.fill_rect(
    Rect::from_min_size([4.0, 4.0], [24.0, 12.0]),
    Color::from_rgba_unmultiplied(80, 160, 255, 192),
    ClipRect::ALL,
)?;
frame.textured_rect(
    Rect::from_min_size([32.0, 4.0], [16.0, 16.0]),
    Rect::FULL_UV,
    checkerboard,
    Color::WHITE,
    ClipRect::ALL,
)?;

let warning = Color::from_rgb(220, 40, 40);
frame.mesh(
    Mesh {
        vertices: &[
            Vertex::new([8.0, 40.0], [0.0, 0.0], warning),
            Vertex::new([24.0, 24.0], [0.0, 0.0], warning),
            Vertex::new([40.0, 40.0], [0.0, 0.0], warning),
        ],
        indices: &[0, 1, 2],
        texture: None,
    },
    ClipRect::ALL,
)?;

let rgba = &frame.surface().pixels; // 64 * 48 * 4 bytes, top row first

Draw calls rasterize immediately, in the order you make them. There is no command list to flush and no deferred state that can disagree with what you asked for.

egui applications do not build meshes by hand. With the egui feature they call SoftwareRenderer::render_egui with a UI closure; see the egui_adapter module. Both paths write the same surface, share the same textures, and produce identical pixels for identical geometry.

§Features

  • egui (off by default): the egui adapter. Without it the crate has no egui dependency at all; the rasterizer and the drawing API above never needed one.

§The Rules

Every drawing path follows these, egui frames included. If the code and this list ever disagree, the code is wrong.

  • Surface. Row-major RGBA8, top row first, exactly width * height * 4 bytes, at most MAX_SURFACE_PIXELS pixels and 65535 on a side. It is an opaque framebuffer: every blended pixel is written with alpha 255, so the alpha channel does not carry coverage. A new or resized surface starts transparent black. Otherwise a frame draws over whatever the last one left, until you call Frame::clear. Nothing clears behind your back.
  • Coordinates. Surface pixels. Origin at the top-left corner, x to the right, y down. Pixel (x, y) covers [x, x + 1) x [y, y + 1) and is sampled at its center, (x + 0.5, y + 0.5).
  • Triangle coverage. A triangle covers the pixels whose centers it contains. A center exactly on an edge goes to one side by a fixed tie-break, so two triangles sharing that edge never both blend the pixel.
  • Rectangle coverage. A rectangle covers the pixels whose centers satisfy min < center <= max on both axes. max <= min on either axis covers nothing.
  • Clipping. ClipRect is integer pixels, half-open, and clamped to the surface.
  • Color. Color is premultiplied RGBA8, and so are texture pixels. Vertex colors interpolate linearly across a triangle and multiply the sampled texel per channel as round(a * b / 255).
  • Blending. Premultiplied source-over, onto an opaque destination: dst = src + round(dst * (255 - src_alpha) / 255), saturating, alpha written as 255. Fully transparent source pixels leave the destination alone.
  • Sampling. Nearest texel. UV (0, 0) is the texture’s top-left and (1, 1) its bottom-right; coordinates clamp to that range, and the texel on each axis is round(uv * (size - 1)). Untextured meshes sample opaque white.
  • Determinism. Output is a function of the draw calls. Same calls, same bytes, on every platform, with or without NEON.

§Limits and Failures

A surface holds at most MAX_SURFACE_PIXELS (1280x720) and one renderer’s textures at most MAX_TEXTURE_BYTES (8 MiB). Both limits exist to catch accidents on small machines, not because the rasterizer falls over past them. A surface side is also at most 65535 pixels and a texture side at most 65536 texels, and those limits are the rasterizer’s: its pixel and texel coordinates stop there.

Malformed input is an Error: a mesh index past the end of its vertices, pixel data of the wrong length, a NaN rectangle, a freed texture. The renderer does not clip bad input into something drawable and carry on. Code that feeds it garbage has a bug, and a quietly wrong frame would only hide where.

Modules§

egui_adapteregui
Drawing egui frames with a SoftwareRenderer. Requires the egui feature.

Structs§

ClipRect
A clip rectangle in integer surface pixels, half-open: it keeps pixels with min_x <= x < max_x and min_y <= y < max_y.
Color
An RGBA8 color with premultiplied alpha.
Frame
One frame of drawing into a SoftwareRenderer’s surface, from SoftwareRenderer::begin_frame.
Mesh
Triangles to draw with Frame::mesh.
Rect
An axis-aligned rectangle in floating-point surface pixels (for positions) or normalized texture coordinates (for UV ranges).
SoftwareRenderer
A CPU rasterizer that owns an RGBA8 SoftwareSurface and a texture store.
SoftwareSurface
Row-major RGBA8 pixel buffer the renderer draws into.
TextureId
A texture owned by a SoftwareRenderer, returned by create_texture.
Vertex
A mesh vertex: a position in surface pixels, a normalized texture coordinate, and a premultiplied color that multiplies the sampled texel.

Enums§

Error
Why a renderer call was rejected. Invalid input fails loudly rather than being clipped or skipped.
VertexField
The part of a Vertex an Error::NonFiniteVertex refers to.

Constants§

MAX_SURFACE_PIXELS
The largest surface, in pixels (1280x720): enough for 640x480 and 1280x720 handheld framebuffers while rejecting accidental desktop-sized ones.
MAX_TEXTURE_BYTES
Total bytes of texture pixels one renderer may hold (8 MiB): egui’s font atlas and textures together with those made by SoftwareRenderer::create_texture.