soft3d

Documentation

Overview

Package soft3d is a minimal, dependency-free software 3D rasterizer.

It implements just enough linear algebra and triangle rasterization to render a rotating, flat-shaded, perspective-projected, z-buffered cube directly into a caller-supplied BGRA byte buffer. The buffer layout matches go-virtio/gpu's VIRTIO_GPU_FORMAT_B8G8R8A8_UNORM: for a pixel (x, y) in a w×h image the byte offset is (y*w+x)*4, with

pix[off+0] = B
pix[off+1] = G
pix[off+2] = R
pix[off+3] = A  (always 0xFF, fully opaque)

soft3d imports nothing outside the Go standard library (in fact only math): it is pure math plus rasterization. It does NOT depend on go-virtio/common or go-virtio/gpu, so it can be reused anywhere a BGRA framebuffer is available.

Typical wiring against go-virtio/gpu (illustrative, not executed here):

vg, _ := gpu.OpenVirtioGPU(t); fb, _ := vg.SetupFramebuffer(0, 640, 480)
soft3d.RenderCube(fb.Pix, 640, 480, angle); _ = fb.Flush()

Index

• func Clear(pix []byte, w, h int, c Color)
• func RenderCube(pix []byte, w, h int, angleRad float64)
• type Color
• type Mat4
  • func Identity() Mat4
  • func Perspective(fovYRad, aspect, near, far float64) Mat4
  • func RotateX(rad float64) Mat4
  • func RotateY(rad float64) Mat4
  • func Translate(x, y, z float64) Mat4
  • func (m Mat4) Mul(n Mat4) Mat4
  • func (m Mat4) MulVec4(x, y, z, w float64) (ox, oy, oz, ow float64)
• type Vec3
  • func (a Vec3) Add(b Vec3) Vec3
  • func (a Vec3) Cross(b Vec3) Vec3
  • func (a Vec3) Dot(b Vec3) float64
  • func (a Vec3) Length() float64
  • func (a Vec3) Normalize() Vec3
  • func (a Vec3) Scale(f float64) Vec3
  • func (a Vec3) Sub(b Vec3) Vec3

Functions

func Clear

func Clear(pix []byte, w, h int, c Color)

Clear fills the whole w×h BGRA buffer with color c (opaque).

func RenderCube

func RenderCube(pix []byte, w, h int, angleRad float64)

RenderCube renders a rotating unit cube ([-1,1]^3) into the w×h BGRA buffer pix. The cube is rotated by RotateY(angleRad)·RotateX(angleRad*0.5), translated to z = -4 (camera at the origin looking down -Z), and perspective-projected. Visible faces are backface-culled (faces whose screen-space signed area indicates they point away from the camera are skipped) and flat-shaded by (face-normal · light) with a fixed light direction. The z-buffer is reset on every call.

Types

type Color

type Color struct {
	R, G, B uint8
}

Color is an opaque RGB color; the alpha channel is always written as 0xFF.

type Mat4

type Mat4 [16]float64

Mat4 is a 4×4 matrix stored row-major: element (row r, column c) lives at index r*4+c. A vector is treated as a column and transformed as M·v, so Translate puts the translation in the last column (indices 3, 7, 11).

func Identity

func Identity() Mat4

Identity returns the 4×4 identity matrix.

func Perspective

func Perspective(fovYRad, aspect, near, far float64) Mat4

Perspective returns a right-handed perspective projection matrix.

fovYRad is the vertical field of view in radians, aspect is width/height, and near/far are positive distances along -Z. Points in front of the camera have negative Z (the camera looks down -Z); after projection and the perspective divide by w (= -Z), such points map into the canonical view volume with -1 at the near plane and +1 at the far plane.

func RotateX

func RotateX(rad float64) Mat4

RotateX returns a rotation of rad radians about the X axis.

func RotateY

func RotateY(rad float64) Mat4

RotateY returns a rotation of rad radians about the Y axis.

func Translate

func Translate(x, y, z float64) Mat4

Translate returns a translation by (x, y, z).

func (Mat4) Mul

func (m Mat4) Mul(n Mat4) Mat4

Mul returns the matrix product m·n (row-major).

func (Mat4) MulVec4

func (m Mat4) MulVec4(x, y, z, w float64) (ox, oy, oz, ow float64)

MulVec4 transforms the homogeneous column vector (x, y, z, w) by m and returns the result (ox, oy, oz, ow).

type Vec3

type Vec3 struct {
	X, Y, Z float64
}

Vec3 is a 3-component vector of float64.

func (Vec3) Add

func (a Vec3) Add(b Vec3) Vec3

Add returns a + b.

func (Vec3) Cross

func (a Vec3) Cross(b Vec3) Vec3

Cross returns the cross product a × b.

func (Vec3) Dot

func (a Vec3) Dot(b Vec3) float64

Dot returns the dot product a · b.

func (Vec3) Length

func (a Vec3) Length() float64

Length returns the Euclidean length of a.

func (Vec3) Normalize

func (a Vec3) Normalize() Vec3

Normalize returns a unit vector in the direction of a. The zero vector normalizes to the zero vector (rather than producing NaNs).

func (Vec3) Scale

func (a Vec3) Scale(f float64) Vec3

Scale returns a scaled by f.

func (Vec3) Sub

func (a Vec3) Sub(b Vec3) Vec3

Sub returns a - b.