B3D

B3D is a minimal software 3D renderer in C99, derived from bootleg3D.

Features

• Triangle rasterization with depth buffering and clipping
• Perspective projection with configurable FOV
• Model transforms (translate, rotate, scale) and camera control
• Zero heap allocations; depends only on <stdbool.h>, <stddef.h>, <stdint.h>, and <string.h>
• Optional 16-bit depth buffer (B3D_DEPTH_16BIT)

Quick Start

#include "b3d.h"

#define W 320
#define H 240

int main(void) {
    static uint32_t pixels[W * H];
    static b3d_depth_t depth[W * H];

    b3d_init(pixels, depth, W, H, 60.0f);
    b3d_set_camera(&(b3d_camera_t){0, 0, -3, 0, 0, 0});

    b3d_clear();
    b3d_tri_t tri = {{{-1, -1, 0}, {1, -1, 0}, {0, 1, 0}}};
    b3d_triangle(&tri, 0xFF0000);  /* red triangle */

    /* pixels[] now contains rendered image */
    return 0;
}

Usage

#include "b3d.h"

Compile-time options:

• B3D_DEPTH_32BIT - Default, 32-bit fixed-point depth (16.16)
• B3D_DEPTH_16BIT - Use 16-bit depth buffer
• B3D_FLOAT_POINT - Use floating-point math for comparisons

Examples

| Example | Description | |---------|-------------| | ball | Bouncing ball demo | | cubes | Benchmark: adds cubes until ~60 fps | | donut | Torus with directional lighting | | fps | First-person treasure hunt | | gears | Interlocking animated gears | | globe | Rotating Earth with Natural Earth country data | | lena3d | Image rendered as 3D heightfield | | lighting | Directional lighting showcase | | microcraft | Minecraft-style voxel terrain with procedural generation | | obj | OBJ viewer with auto-centering | | terrain | Animated sine/cosine heightmap | | voxel | Mesh voxelizer with cube rendering |

Build with make check to validate B3D implementation. Build with make all (requires SDL2). Run headlessly with --snapshot=PATH.

Globe Data Generation

The globe example uses Natural Earth country boundary data (public domain).

pip3 install pyshp requests   # one-time setup
make update-globe-data        # download and process data
make globe                    # build example

API

// Types
typedef struct { float x, y, z; } b3d_point_t;
typedef struct { b3d_point_t v[3]; } b3d_tri_t;
typedef struct { float x, y, z, yaw, pitch, roll; } b3d_camera_t;

// Setup
bool b3d_init(uint32_t *pixels, b3d_depth_t *depth, int w, int h, float fov);
void b3d_clear(void);
size_t b3d_buffer_size(int w, int h, size_t elem_size);  // 0 on overflow

// Transforms (angles in radians)
void b3d_reset(void);
void b3d_translate(float x, float y, float z);
void b3d_rotate_x(float angle);
void b3d_rotate_y(float angle);
void b3d_rotate_z(float angle);
void b3d_scale(float x, float y, float z);

// Matrix stack
bool b3d_push_matrix(void);  // false if stack full
bool b3d_pop_matrix(void);   // false if stack empty

// Direct matrix access (row-major 4x4)
void b3d_get_model_matrix(float out[16]);
void b3d_set_model_matrix(const float m[16]);

// Camera (yaw/pitch/roll in radians, FOV in degrees)
void b3d_set_camera(const b3d_camera_t *cam);
void b3d_get_camera(b3d_camera_t *out);
void b3d_look_at(float x, float y, float z);
void b3d_set_fov(float degrees);
float b3d_get_fov(void);
void b3d_get_view_matrix(float out[16]);
void b3d_get_proj_matrix(float out[16]);

// Rendering (returns false if culled/clipped)
bool b3d_triangle(const b3d_tri_t *tri, uint32_t color);
bool b3d_to_screen(float x, float y, float z, int *sx, int *sy);

// State queries
bool b3d_is_initialized(void);
int b3d_get_width(void);
int b3d_get_height(void);
size_t b3d_get_clip_drop_count(void);

Matrix Conventions

B3D uses DirectX-style matrix conventions, which differ from OpenGL:

| Aspect | B3D | OpenGL | |--------|-----|--------| | Coordinate system | Right-handed, Y-up, +Z forward | Right-handed, Y-up, -Z forward | | Memory layout | Row-major m[row][col] | Column-major m[col][row] | | Vector type | Row vectors | Column vectors | | Multiplication | v * M (vector on left) | M * v (vector on right) | | API multiply order | Post-multiply: M = M * T | Post-multiply: M = M * T | | Effect order | Transforms apply in call order | Transforms apply in reverse call order | | Translation storage | Row 3: m[3][0..2] | Column 3: m[12..14] in flat array |

Transform application order:

// B3D: transforms applied in code order (scale -> rotate -> translate)
b3d_scale(2, 2, 2);
b3d_rotate_y(angle);
b3d_translate(x, y, z);

// OpenGL: same API order, but effects apply in reverse (translate -> rotate -> scale)
// To match B3D's effect order, reverse the calls:
glTranslatef(x, y, z);
glRotatef(angle, 0, 1, 0);
glScalef(2, 2, 2);

Matrix layout comparison:

B3D (row-major):          OpenGL (column-major):
[ Xx Xy Xz 0 ]            [ Xx Yx Zx Tx ]
[ Yx Yy Yz 0 ]            [ Xy Yy Zy Ty ]
[ Zx Zy Zz 0 ]            [ Xz Yz Zz Tz ]
[ Tx Ty Tz 1 ]            [ 0  0  0  1  ]

When porting from OpenGL: transpose matrices and reverse transform order.

Color Format

Colors are 32-bit RGB (alpha channel ignored):

• Format: 0xRRGGBB or 0xAARRGGBB
• Examples: 0xFF0000 (red), 0x00FF00 (green), 0x0000FF (blue)

Per-face control flags use upper bits:

• B3D_DRAW_BACKFACE (bit 31): Disable backface culling for this triangle
• Usage: b3d_triangle(&tri, color | B3D_DRAW_BACKFACE)
• Use case: Double-sided geometry (leaves, flags), skyboxes with outward normals

Coordinate System

| Property | Value | |----------|-------| | Handedness | Right-handed | | Up axis | +Y | | Forward axis | +Z (into screen) | | Screen origin | Top-left (0, 0) | | Winding order | Counter-clockwise = front face | | Near plane | 0.1 units | | Far plane | 100.0 units |

Return Values

| Function | Returns false when | |----------|---------------------| | b3d_init | NULL buffers, invalid size, overflow, or FOV ≤ 0 | | b3d_push_matrix | Stack full (16 levels max) | | b3d_pop_matrix | Stack empty | | b3d_triangle | Triangle culled or fully clipped | | b3d_to_screen | Point behind camera (w < epsilon) |

Note: b3d_look_at updates the view matrix but leaves b3d_get_camera orientation stale. Use b3d_get_view_matrix for accurate view state after b3d_look_at.

Thread Safety

B3D uses global state and is NOT thread-safe. Do not call B3D functions from multiple threads simultaneously. For multi-threaded rendering, serialize all B3D calls or use separate processes.

Performance

• Depth buffer: 16-bit mode (B3D_DEPTH_16BIT) halves memory bandwidth
• Fixed-point: Default Q15.16 is faster on systems without FPU
• Culling: Back-face culling is enabled by default; use B3D_DRAW_BACKFACE per-face for skyboxes/particles, or B3D_NO_CULLING compile-time for all
• Batching: Minimize b3d_push_matrix/b3d_pop_matrix pairs
• Clipping: Use b3d_get_clip_drop_count() to detect buffer overflow

License

B3D is available under a permissive MIT-style license. Use of this source code is governed by a MIT license that can be found in the LICENSE file.