Master of Puppets

Overview

The RHI is a function-pointer table that decouples the viewport core from specific rendering APIs. The viewport calls through MopRhiBackend * — it never calls backend functions directly.

Location

src/rhi/
  rhi.h     — MopRhiBackend struct, opaque handle declarations
  rhi.c     — Backend resolution dispatch

Opaque Handles

Handle	Represents
`MopRhiDevice`	A rendering context (GL context, Vk device, CPU state)
`MopRhiBuffer`	Vertex or index data storage
`MopRhiFramebuffer`	Color + depth + object-ID render targets

Function Table

Every backend must populate every function pointer. NULL entries are invalid.

Function	Signature	Purpose
`device_create`	`() → Device*`	Create rendering context
`device_destroy`	`(Device*) → void`	Destroy context
`buffer_create`	`(Device, BufferDesc) → Buffer*`	Upload vertex/index data
`buffer_destroy`	`(Device, Buffer) → void`	Free buffer
`framebuffer_create`	`(Device, FbDesc) → Fb*`	Create render targets
`framebuffer_destroy`	`(Device, Fb) → void`	Free render targets
`framebuffer_resize`	`(Device, Fb, w, h) → void`	Reallocate at new size
`frame_begin`	`(Device, Fb, ClearColor) → void`	Clear and begin frame
`frame_end`	`(Device, Fb) → void`	Finalize frame
`draw`	`(Device, Fb, DrawCall*) → void`	Rasterize one mesh
`pick_read_id`	`(Device, Fb, x, y) → uint32_t`	Read object ID at pixel
`pick_read_depth`	`(Device, Fb, x, y) → float`	Read depth at pixel
`framebuffer_read_color`	`(Device, Fb, &w, &h) → uint8_t*`	Read RGBA8 color buffer

Draw Call Descriptor

typedef struct MopRhiDrawCall {
    MopRhiBuffer *vertex_buffer;
    MopRhiBuffer *index_buffer;
    uint32_t      vertex_count;
    uint32_t      index_count;
    uint32_t      object_id;
    MopMat4       model, view, projection, mvp;
    MopColor      base_color;
    bool          wireframe, depth_test, backface_cull;
} MopRhiDrawCall;

The viewport precomputes mvp. Backends may use mvp directly (CPU) or upload separate matrices as uniforms (GPU).

Backend Registration

Each backend exposes a factory returning static const MopRhiBackend *:

const MopRhiBackend *mop_rhi_backend_cpu(void);

The dispatcher in rhi.c maps MopBackendType → factory. MOP_BACKEND_AUTO resolves to the platform default.

Implementing a New Backend

See Extension Strategy for the full checklist.

19 FEB 2026