cinder.render

cinder.render #

Source: cinder/render/__init__.mojo

Renderer: cameras, meshes, materials, textures, the frame graph and the forward+ pipeline. Everything here talks to the GPU only through cinder.gfx.

cinder.render.camera #

Source: cinder/render/camera.mojo

Cameras and frustum culling. Right-handed, Y up, camera looks down -Z. Projection is reverse-Z with an infinite far plane, so the frustum has five planes. cull_spheres tests four spheres at a time with SIMD.

• comptime F4 = SIMD[DType.float32, 4] — Four float32 lanes: one coordinate of four spheres in Frustum.cull_spheres_into.

struct Plane #

struct Plane(ImplicitlyCopyable, RegisterPassable)

normal . p + d >= 0 is the inside half-space.

Fields:

• normal: Vec3

• d: Float32

• from_row from_row(v: Vec4) -> Plane
  Plane from a clip-space row combination, scaled so normal has unit length.

• distance distance(self, p: Vec3) -> Float32
  Signed distance from p to the plane (positive inside), in the units of p.

struct Frustum #

struct Frustum(Copyable, Movable)

Left, right, bottom, top, near planes extracted from a view-projection matrix (Gribb/Hartmann). Reverse-Z with infinite far: the near plane is row3 - row2 (clip z <= w); no far plane.

Fields:

• planes: Array[Plane, 5]

• __init__ __init__(out self, view_proj: Mat4)

• contains_sphere contains_sphere(self, centre: Vec3, radius: Float32) -> Bool
  True unless the sphere lies entirely behind one of the five planes. Conservative: a sphere near a frustum edge or corner may pass without intersecting it.

• contains_point contains_point(self, p: Vec3) -> Bool
  True when p is on the inside of all five planes (near, left, right, bottom, top).

• cull_spheres_into cull_spheres_into(self, spheres: List[Vec4], mut out: List[Bool])
  Visibility per sphere (xyz centre, w radius), four spheres per SIMD step, written into a list supplied by the caller (cleared first, capacity kept).

• cull_spheres cull_spheres(self, spheres: List[Vec4]) -> List[Bool]
  Visibility per sphere (xyz centre, w radius); allocates the result list. Use cull_spheres_into in per-frame code to reuse a scratch list.

struct Camera #

struct Camera(ImplicitlyCopyable, Movable)

A perspective camera. near is the only clip distance (infinite far).

Fields:

• position: Vec3

• rotation: Quat

• fov_y: Float32

• aspect: Float32

• near: Float32

• __init__ __init__( out self, position: Vec3, rotation: Quat, fov_y: Float32 = 1.0471976, aspect: Float32 = 16.0 / 9.0, near: Float32 = 0.05, )

• look_at look_at( eye: Vec3, target: Vec3, up: Vec3 = Vec3.unit_y(), fov_y: Float32 = 1.0471976, aspect: Float32 = 16.0 / 9.0, near: Float32 = 0.05, ) -> Camera
  A camera at eye looking at target, with its rotation taken from Mat4.look_at. up only orients the camera (the stored up() is re-orthogonalised); fov_y is the vertical field of view in radians, near the near clip distance in metres.

• forward forward(self) -> Vec3
  World-space view direction: Vec3.forward() (-Z) rotated by rotation, unit length.

• right right(self) -> Vec3
  World-space right axis: +X rotated by rotation.

• up up(self) -> Vec3
  World-space up axis: +Y rotated by rotation.

• view view(self) -> Mat4
  World-to-view matrix (right-handed, looking down -Z), column-major.

• projection projection(self) -> Mat4
  Reverse-Z perspective with an infinite far plane: depth 1 at near, 0 at infinity.

• view_projection view_projection(self) -> Mat4
projection() * view(): world space to clip space.

• frustum frustum(self) -> Frustum
  The five-plane culling frustum of view_projection() (no heap allocation).

• set_viewport set_viewport(mut self, width: Int, height: Int)
  Sets aspect to width / height in pixels; ignored when height is not positive.

cinder.render.frame_graph #

Source: cinder/render/frame_graph.mojo

Frame graph: declared passes, transient textures with lifetimes and aliasing, automatic ordering. The graph is rebuilt every frame (cheap: a few passes). compile orders passes by their read/write dependencies, culls passes that contribute nothing to an exported resource, computes each transient's lifetime as a pass-index interval and assigns physical textures so that transients with compatible descriptions and disjoint lifetimes share one allocation. Physical textures persist in a pool across frames and are dropped when their description stops being requested (resize). The renderer executes the compiled order itself (order) and looks up each transient's view with view_of; the graph never calls back into user code (no closures cross the GPU layer). to_graphviz renders the compiled graph for the debug UI.

struct TransientDesc #

struct TransientDesc(Equatable, ImplicitlyCopyable, Movable)

Size in pixels, format, WGPUTextureUsage bits, sample and mip count of a transient. Transients share one pooled physical texture only when their descriptions are equal.

Fields:

• width: UInt32
• height: UInt32
• format: WGPUTextureFormat
• usage: UInt64
• sample_count: UInt32
• mip_levels: UInt32

struct FrameGraph #

struct FrameGraph(Movable)

One frame's passes and resources, compiled into an execution order and pooled textures. Per frame: reset, declare resources (create, import_view, create_external) and passes (add_pass, read, write), export what must survive, compile, then walk order and look up views with view_of. Physical textures are owned by the graph and freed by release (or when a compile no longer requests them); declaration and compile do not allocate in steady state.

Fields:

• resources: List[_Resource]

• passes: List[_Pass]

• order: List[Int] — Pass indices in execution order (set by compile).

• physicals: List[_Physical]

• compiled: Bool

• culled_count: Int

• __init__ __init__(out self)

• reset reset(mut self)
  Starts a new frame's declaration. Physical textures stay pooled; pass records keep their read/write list capacity for reuse.

• create create(mut self, name: String, desc: TransientDesc) -> Int
  Declares a transient texture and returns its resource index (valid until reset). The physical texture is assigned by compile, possibly shared with other transients.

• import_view import_view( mut self, name: String, view: TextureViewHandle, desc: TransientDesc ) -> Int
  A view the caller keeps alive (swapchain, persistent target). Never aliased.

• create_external create_external(mut self, name: String) -> Int
  A buffer-backed resource (no texture): passes writing it are ordered before readers and kept alive by them, but no physical texture is allocated.

• export export(mut self, resource: Int)
  Marks a resource as needed outside the graph; passes feeding it are kept.

• add_pass add_pass(mut self, name: String) -> Int
  Declares a pass and returns its index; reuses a spare pass record when there is one.

• read read(mut self, pass_: Int, resource: Int)
  Declares that pass_ reads resource (ordered after the resource's producer).

• write write(mut self, pass_: Int, resource: Int)
  Declares that pass_ writes resource; writers of a resource keep declaration order.

• compile compile(mut self, mut res: Resources) raises
  Orders, culls, computes lifetimes and assigns physical textures.

• release release(mut self, mut res: Resources) raises
  Destroys every pooled physical texture and its view; raises on a Resources error.

• view_of view_of(self, resource: Int) raises -> TextureViewHandle
  View of resource after compile: the imported view or its physical texture's view. Raises for an external (buffer-backed) resource and for one with no physical texture (unused, culled or not compiled).

• texture_of texture_of(self, resource: Int) raises -> TextureHandle
  Physical texture behind a transient after compile. Raises for imported and external resources and for transients without a physical texture.

• find find(self, name: String) -> Int
  Index of the resource with this name, or -1.

• physical_count physical_count(self) -> Int
  Pooled physical textures after the last compile (FrameStats.transient_textures).

• is_culled is_culled(self, pass_: Int) -> Bool
  True when the last compile culled the pass (it feeds no exported resource).

• lifetime lifetime(self, resource: Int) -> Tuple[Int, Int]
  (first, last) execution-order indices using the resource; (-1, -1) if no kept pass does.

• to_graphviz to_graphviz(self) -> String
  DOT text: passes as boxes in execution order, resources as ellipses, edges for reads/writes.

cinder.render.lights #

Source: cinder/render/lights.mojo

Lights and the clustered-culling configuration shared with shaders/common.wgsl.

• comptime CLUSTER_X = 16 — Cluster grid columns across the screen; mirrors CLUSTER_X in common.wgsl.
• comptime CLUSTER_Y = 9 — Cluster grid rows across the screen; mirrors CLUSTER_Y in common.wgsl.
• comptime CLUSTER_Z = 24 — Logarithmic depth slices of the cluster grid; mirrors CLUSTER_Z in common.wgsl.
• comptime CLUSTER_COUNT = CLUSTER_X * CLUSTER_Y * CLUSTER_Z — Total clusters (16 x 9 x 24); sizes the cluster_grid count buffer (one u32 each).
• comptime CLUSTER_MAX_LIGHTS = 32 — Light indices stored per cluster; lights beyond this are dropped by clusters.wgsl.
• comptime LIGHT_BYTES = 64 — Bytes per packed light: the size of Light in common.wgsl.
• comptime MAX_LIGHTS = 1024 — Most local lights the renderer uploads per frame; extra lights are dropped.

struct LightKind #

struct LightKind(Equatable, ImplicitlyCopyable, RegisterPassable)

Light type tag; values mirror LIGHT_* in common.wgsl (0 directional, 1 point, 2 spot).

Fields:

• value: UInt32

• directional directional() -> LightKind
  Sun-like light at infinity; only its direction matters.

• point point() -> LightKind
  Omnidirectional light at a position, attenuated to zero at range.

• spot spot() -> LightKind
  Cone light at a position along direction, attenuated to zero at range.

struct Light #

struct Light(ImplicitlyCopyable, Movable)

A light. Directional: direction (travel direction), color * intensity in lux. Point and spot: position, range (metres), intensity in watts, spot cone angles in radians.

Fields:

• kind: LightKind

• position: Vec3

• direction: Vec3

• color: Vec3

• intensity: Float32

• range: Float32

• inner_angle: Float32

• outer_angle: Float32

• cast_shadows: Bool

• __init__ __init__( out self, kind: LightKind, position: Vec3 = Vec3.zero(), direction: Vec3 = Vec3(0.0, -1.0, 0.0), color: Vec3 = Vec3.one(), intensity: Float32 = 1.0, range: Float32 = 10.0, inner_angle: Float32 = 0.4, outer_angle: Float32 = 0.6, cast_shadows: Bool = False, )

• sun sun( direction: Vec3, color: Vec3 = Vec3.one(), lux: Float32 = 3.0, cast_shadows: Bool = True, ) -> Light
  Directional light travelling along direction (normalised), with lux illuminance. Position, range and cone angles are zero; shadows default to on (cascaded shadow maps).

• point_light point_light( position: Vec3, color: Vec3, watts: Float32, range: Float32, cast_shadows: Bool = False, ) -> Light
  Point light at position (metres) emitting watts, reaching zero at range metres.

• spot_light spot_light( position: Vec3, direction: Vec3, color: Vec3, watts: Float32, range: Float32, inner: Float32, outer: Float32, cast_shadows: Bool = False, ) -> Light
  Spot light along direction (normalised) emitting watts with a range in metres. inner and outer are cone half-angles in radians from the axis: full intensity inside inner, fading to zero at outer.

• bounding_sphere bounding_sphere(self) -> Vec4
  Influence sphere: xyz position, w range in metres (meaningless for directional lights).

• pack pack(self, mut w: ByteWriter, shadow_view: Int)
  64 bytes matching Light in common.wgsl.

def pack_lights_into #

def pack_lights_into( mut w: ByteWriter, lights: List[Light], shadow_views: List[Int] )

Appends the GPU light array (at least one zeroed entry) to w.

def pack_lights #

def pack_lights(lights: List[Light], shadow_views: List[Int]) -> List[UInt8]

pack_lights_into into a new byte list (allocates; at least one zeroed 64-byte entry). shadow_views[i] is light i's first shadow-view index (-1 or missing: no shadow).

struct ClusterParams #

struct ClusterParams(ImplicitlyCopyable, Movable)

Logarithmic z slicing: slice = log2(z) * scale + bias between near and far.

Fields:

• scale: Float32

• bias: Float32

• far: Float32

• compute compute(near: Float32, far: Float32) -> ClusterParams
  Slice parameters mapping near to slice 0 and far to CLUSTER_Z (metres).

• slice_of slice_of(self, view_z: Float32) -> Int
  Z slice for a positive view-space distance in metres, clamped to [0, CLUSTER_Z - 1]. Mirrors cluster_z_slice in common.wgsl.

cinder.render.material #

Source: cinder/render/material.mojo

glTF 2.0 metallic-roughness materials and their GPU bind groups. Uniform layout (96 bytes, 16-byte aligned fields, mirrored by shaders/material.wgsl): 0 base_color: vec4 16 emissive.rgb, emissive_strength 32 metallic, roughness, normal_scale, occlusion_strength 48 alpha_cutoff, alpha_mode (0 opaque, 1 mask, 2 blend), double_sided, texture_flags 64 uv_scale.xy, uv_offset.xy (KHR_texture_transform, applied to every map) 80 uv_rotation, texcoord_bits (3 bits per map: base, mr, normal, occlusion, emissive), pad, pad

• comptime MATERIAL_UNIFORM_SIZE = 96 — Bytes in the material uniform (group 2, binding 0); see the module docstring for the layout.

struct AlphaMode #

struct AlphaMode(Equatable, ImplicitlyCopyable, RegisterPassable)

How alpha is used; packed into the material uniform and mirrored in WGSL.

Fields:

• value: UInt32

• opaque opaque() -> AlphaMode
  Alpha is ignored; the surface is fully opaque.

• mask mask() -> AlphaMode
  Alpha-tested: fragments with alpha below alpha_cutoff are discarded.

• blend blend() -> AlphaMode
  Alpha-blended; drawn after opaque batches, sorted back to front.

• comptime TEX_BASE_COLOR = 0 — Slot of the base colour map in Material.textures, texcoords and texture_flags.

• comptime TEX_METALLIC_ROUGHNESS = 1 — Slot of the metallic-roughness map in Material.textures, texcoords and texture_flags.

• comptime TEX_NORMAL = 2 — Slot of the normal map in Material.textures, texcoords and texture_flags.

• comptime TEX_OCCLUSION = 3 — Slot of the occlusion map in Material.textures, texcoords and texture_flags.

• comptime TEX_EMISSIVE = 4 — Slot of the emissive map in Material.textures, texcoords and texture_flags.

struct Material #

struct Material(Copyable, Movable)

CPU description. Texture views are null when a map is absent (defaults are bound instead).

Fields:

• name: String

• base_color: Vec4

• metallic: Float32

• roughness: Float32

• emissive: Vec3

• emissive_strength: Float32

• normal_scale: Float32

• occlusion_strength: Float32

• alpha_mode: AlphaMode

• alpha_cutoff: Float32

• double_sided: Bool

• uv_scale: Vec2

• uv_offset: Vec2

• uv_rotation: Float32

• textures: Array[TextureViewHandle, 5]

• texcoords: Array[UInt8, 5]

• sampler: SamplerHandle

• __init__ __init__(out self, name: String = String("material"))

• texture_flags texture_flags(self) -> UInt32
  Bit i set when map slot i (TEX_*) has a texture view.

• texcoord_bits texcoord_bits(self) -> UInt32
  Texture coordinate set per map, 3 bits per TEX_* slot (the shader takes uv1 for 1).

• pack_uniform pack_uniform(self) -> List[UInt8]
  The 96-byte uniform laid out as in the module docstring, in a new list (allocates).

def material_bind_group_layout #

def material_bind_group_layout( mut res: Resources, ) raises -> BindGroupLayoutHandle

Creates the group-2 material layout matching shaders/material.wgsl; raises on a GPU error. Binding 0 is the uniform (vertex and fragment), 1 the sampler, 2..6 the maps in TEX_* order.

struct GpuMaterial #

struct GpuMaterial(ImplicitlyCopyable, Movable)

Uniform buffer and bind group of an uploaded material. alpha_mode and double_sided are copied from the Material to select its pipeline.

Fields:

• uniform: BufferHandle
• bind_group: BindGroupHandle
• alpha_mode: AlphaMode
• double_sided: Bool

def upload_material #

def upload_material( mut res: Resources, layout: BindGroupLayoutHandle, defaults: DefaultTextures, material: Material, ) raises -> GpuMaterial

Creates the material's uniform buffer and group-2 bind group; raises on a GPU error. Absent maps bind the defaults (white base colour, metallic-roughness and occlusion, flat normal, black emissive) and a null sampler binds sampler_linear_repeat. The texture views stay owned by the caller; the returned buffer and bind group are new allocations.

def update_material #

def update_material( mut res: Resources, gpu: GpuMaterial, material: Material ) raises

Re-uploads the parameters (textures are fixed per bind group).

cinder.render.mesh #

Source: cinder/render/mesh.mojo

Mesh data on the CPU, GPU meshes, the engine vertex format and procedural primitives. Vertex stream (56 bytes): position f32x3 @0, normal f32x3 @12, tangent f32x4 @24 (w = handedness), uv0 f32x2 @40, uv1 f32x2 @48. Skinning attributes live in a second stream (SkinVertex, 24 bytes): joints u16x4 @0, weights f32x4 @8. Indices are u32.

• comptime VERTEX_STRIDE = 56 — Bytes per vertex in the static stream (slot 0); layout in the module docstring.
• comptime SKIN_VERTEX_STRIDE = 24 — Bytes per vertex in the skinning stream (slot 1): u16x4 joints, f32x4 weights.
• comptime PI = Float32(3.14159265358979) — Pi as Float32, for the procedural primitives.

def vertex_layout #

def vertex_layout() -> VertexLayout

Slot 0: the static vertex stream. Locations 0..4.

def skin_vertex_layout #

def skin_vertex_layout() -> VertexLayout

Slot 1: joints and weights. Locations 5 and 6.

struct Bounds #

struct Bounds(ImplicitlyCopyable, Movable)

Axis-aligned bounding box in mesh space (metres).

Fields:

• min: Vec3

• max: Vec3

• centre centre(self) -> Vec3
  Midpoint of the box.

• radius radius(self) -> Float32
  Half the box diagonal: the radius of the bounding sphere around centre().

• sphere sphere(self) -> Vec4
  Bounding sphere: xyz centre, w radius (the input of Frustum.cull_spheres_into).

• empty empty() -> Bounds
  Inverted box (min +3.4e38, max -3.4e38); the first include collapses it to a point.

• include include(mut self, p: Vec3)
  Grows the box to contain p.

struct MorphTarget #

struct MorphTarget(Copyable, Movable)

Per-vertex position and normal deltas of one morph target (normals may be empty).

Fields:

• positions: List[Vec3]
• normals: List[Vec3]

struct MeshLod #

struct MeshLod(ImplicitlyCopyable, Movable)

An index range of the combined index buffer and the simplification error it carries.

Fields:

• first_index: UInt32
• index_count: UInt32
• error: Float32

struct MeshData #

struct MeshData(Copyable, Movable)

CPU-side triangle mesh. Parallel per-vertex arrays; tangents, uv1, joints and weights may be empty and are filled with defaults at upload.

Fields:

• positions: List[Vec3]

• normals: List[Vec3]

• tangents: List[Vec4]

• uv0: List[Vec2]

• uv1: List[Vec2]

• joints: List[SIMD[DType.uint16, 4]]

• weights: List[Vec4]

• indices: List[UInt32]

• morph_targets: List[MorphTarget]

• __init__ __init__(out self)

• vertex_count vertex_count(self) -> Int
  Number of vertices (len(positions)).

• triangle_count triangle_count(self) -> Int
  Number of triangles (len(indices) // 3).

• has_skin has_skin(self) -> Bool
  True when every vertex has joint indices and weights (joints and weights both match positions, non-empty), which is what pack_skin_vertices reads.

• bounds bounds(self) -> Bounds
  Bounds of positions; a zero box at the origin when the mesh has no vertices.

• validate validate(self) raises
  Raises when the arrays are inconsistent. Checks that normals and uv0 match the vertex count, that tangents and uv1 are empty or match it, that joints and weights are either both empty or both match it (a skin needs one of each per vertex), that the index count is a multiple of 3 and that every index is in range. Morph targets are not checked (missing deltas pack as zero).

• compute_normals compute_normals(mut self)
  Area-weighted face normals accumulated per vertex.

• compute_tangents compute_tangents(mut self, lib: NativePtr) raises
  MikkTSpace tangents through the shim (requires normals and uv0).

• pack_vertices pack_vertices(self) -> List[UInt8]
  The 56-byte-per-vertex static stream as a new byte list (allocates). Missing tangents become (1, 0, 0, 1) and missing uv1 repeats uv0. Expects normals and uv0 for every vertex (see validate).

• pack_skin_vertices pack_skin_vertices(self) -> List[UInt8]
  The 24-byte-per-vertex skin stream: little-endian u16x4 joints, then f32x4 weights. Allocates; expects joints and weights for every vertex.

• pack_indices pack_indices(self) -> List[UInt8]
indices as little-endian u32 bytes in a new list (allocates).

• pack_morph_deltas pack_morph_deltas(self) -> List[UInt8]
  Per target, per vertex: position delta (vec4) then normal delta (vec4), as common.wgsl reads.

• build_lods build_lods( self, lib: NativePtr, levels: Int = 4 ) raises -> List[List[UInt32]]
  LOD index lists (level 0 is the original, vertex-cache optimised) via meshoptimizer. Each level targets half the triangles of the previous one with a relative error bound of 2%; a level that cannot be simplified further ends the chain.

struct GpuMesh #

struct GpuMesh(Copyable, Movable)

Buffers for one mesh. skin_vertices is null when the mesh is not skinned, morph_buffer when it has no morph targets. lods[0] is the full-detail index range. index_count is the full-detail index count (lods[0].index_count, 0 without LODs), the same for upload_mesh_lods and upload_mesh_bytes; the index buffer holds every LOD range, so its total length is the sum over lods.

Fields:

• vertices: BufferHandle

• skin_vertices: BufferHandle

• indices: BufferHandle

• index_count: UInt32

• vertex_count: UInt32

• bounds: Bounds

• lods: List[MeshLod]

• morph_buffer: BufferHandle

• morph_target_count: UInt32

• __init__ __init__( out self, vertices: BufferHandle, skin_vertices: BufferHandle, indices: BufferHandle, index_count: UInt32, vertex_count: UInt32, bounds: Bounds, var lods: List[MeshLod], morph_buffer: BufferHandle, morph_target_count: UInt32, )

• select_lod select_lod( self, projected_diameter_px: Float32, screen_height_px: Float32 ) -> Int
  Smaller on screen -> coarser LOD. Level 1 below 1/4 of the screen height, level 2 below 1/8, level 3 below 1/16 (resolution independent).

def upload_mesh #

def upload_mesh( mut res: Resources, label: String, data: MeshData ) raises -> GpuMesh

Uploads with a single LOD.

def upload_mesh_lods #

def upload_mesh_lods( mut res: Resources, label: String, data: MeshData, lod_indices: List[List[UInt32]], ) raises -> GpuMesh

Uploads vertex streams plus one combined index buffer holding every LOD range.

def upload_mesh_bytes #

def upload_mesh_bytes( mut res: Resources, label: String, vertex_count: UInt32, vertex_bytes: List[UInt8], skin_bytes: List[UInt8], index_bytes: List[UInt8], var lods: List[MeshLod], bounds: Bounds, morph_target_count: UInt32, morph_bytes: List[UInt8], ) raises -> GpuMesh

Uploads streams that are already in GPU layout (cooked meshes).

def destroy_mesh #

def destroy_mesh(mut res: Resources, mesh: GpuMesh) raises

Destroys the mesh's vertex and index buffers, and its skin and morph buffers when present. The handles in mesh are left as they are; raises on a Resources error.

def cube #

def cube(half: Float32 = 0.5) -> MeshData

24-vertex cube with per-face normals, CCW winding seen from outside.

def uv_sphere #

def uv_sphere( radius: Float32 = 0.5, rings: Int = 16, segments: Int = 32 ) -> MeshData

UV sphere centred at the origin, poles on +Y and -Y; radius in metres. (rings + 1) * (segments + 1) vertices (the seam is duplicated), counter-clockwise seen from outside. u runs around the sphere from +X towards +Z, v from the top pole (0) to the bottom (1); tangents point along increasing u.

def plane #

def plane(half: Float32 = 0.5, subdivisions: Int = 1) -> MeshData

An XZ plane facing +Y.

cinder.render.renderer #

Source: cinder/render/renderer.mojo

The forward+ renderer: shadows, depth prepass, GTAO, clustered lights, PBR, sky, bloom, tonemap. Renderer.render(scene, target) builds the frame graph for the current settings, compiles it (ordering, transient aliasing), fills the GPU buffers from the scene and records every pass into one command buffer. CPU work per frame: frustum culling (SIMD), LOD selection, batching by (mesh, material, skinning), cascade fitting, light packing. Nothing here waits on the GPU.

• comptime FRAME_UNIFORM_SIZE = 720 — Bytes in the frame uniform: the size of Frame in common.wgsl (checked each frame).
• comptime PASS_UNIFORM_STRIDE = 256 — Bytes per view-projection slot in pass_uniforms, the dynamic-offset alignment.
• comptime MAX_PASS_VIEWS = 128 — Slots in pass_uniforms: four cascades, the atlas views, then the camera.
• comptime INSTANCE_BYTES = 144 — Bytes per instance in the instances buffer: model, normal matrix, u32x4 params.
• comptime MORPH_WEIGHTS_BYTES = 32 — Bytes of morph weights bound per morphed instance: eight f32 weights.
• comptime POST_UNIFORM_STRIDE = 256 — Bytes per slot in post_uniforms (and per morph-weight slot), the dynamic-offset alignment.
• comptime MAX_CACHED_POST_GROUPS = 64 — Post bind groups kept across frames before the cache is rebuilt.
• comptime MAX_POST_PASSES = 32 — Slots in post_uniforms per frame.
• comptime INITIAL_MORPH_SLOTS = 32 — Initial slots in the morph-weight buffer; it doubles when a frame has more morphed instances.
• comptime BLOOM_MIPS = 6 — Levels in the bloom chain; level 0 is half the output resolution.
• comptime ENV_SIZE = 256 — Face size in pixels of the baked environment cube (RGBA16F, full mip chain).
• comptime PREFILTER_SIZE = 128 — Face size in pixels of the prefiltered specular cube.
• comptime PREFILTER_MIPS = 6 — Mips of the prefiltered cube; mip m holds roughness m / (PREFILTER_MIPS - 1).
• comptime IRRADIANCE_SIZE = 32 — Face size in pixels of the diffuse irradiance cube.
• comptime BRDF_LUT_SIZE = 256 — Size in pixels of the split-sum BRDF lookup texture.
• comptime SHADER_DIR = "cinder/render/shaders" — Directory of the renderer's WGSL files, relative to the working directory.

struct Tonemapper #

struct Tonemapper(Equatable, ImplicitlyCopyable, RegisterPassable)

Tone curve of the tonemap pass; values mirror post.settings.z in post.wgsl.

Fields:

• value: UInt32

• agx agx() -> Tonemapper
  AgX (the default).

• aces aces() -> Tonemapper
  ACES filmic curve.

• none none() -> Tonemapper
  No curve: the exposed colour is clamped to [0, 1]; also used for debug views.

struct DebugMode #

struct DebugMode(Equatable, ImplicitlyCopyable, RegisterPassable)

Mirrors DEBUG_* in common.wgsl.

Fields:

• value: UInt32

• none none() -> DebugMode
  Normal lit output.

• normals normals() -> DebugMode
  World-space normals mapped to colour (n * 0.5 + 0.5).

• cascades cascades() -> DebugMode
  Colour per sun shadow cascade, shaded by the sun angle.

• clusters clusters() -> DebugMode
  Heat map of the light count in each fragment's cluster (full scale at 16 lights).

• overdraw overdraw() -> DebugMode
  Overdraw count: forward pipelines blend additively with the depth test off, so every rasterised fragment (hidden or not, opaque or blended) adds 0.1 grey; brightness is the fragment count / 10 (white at 10 or more) and empty sky is black.

• lod lod() -> DebugMode
  Colour per instance from its LOD index (bits 8..15 of the instance flags), skinned and morphed instances included.

• albedo albedo() -> DebugMode
  Unlit base colour (material factor times the base colour map).

• ao ao() -> DebugMode
  The ambient occlusion term as greyscale.

struct RenderSettings #

struct RenderSettings(ImplicitlyCopyable, Movable)

Quality knobs, read at the start of every render (change them between frames). cascade_resolution, atlas_size and atlas_tile are read at construction only.

Fields:

• msaa: UInt32 — 1 or 4.

• bloom: Bool

• bloom_strength: Float32

• bloom_threshold: Float32

• tonemapper: Tonemapper

• exposure: Float32

• fxaa: Bool

• ao: Bool

• shadows: Bool

• shadow_distance: Float32

• cascade_resolution: Int

• atlas_size: Int

• atlas_tile: Int

• ibl_intensity: Float32

• debug: DebugMode

• wireframe: Bool

• cull: Bool

• __init__ __init__(out self)

struct Environment #

struct Environment(ImplicitlyCopyable, Movable)

Procedural sky by default; equirect (an RGBA16F 2D texture view) replaces it when set.

Fields:

• zenith: Vec3

• ground: Vec3

• sun_intensity: Float32

• equirect: TextureViewHandle

• __init__ __init__(out self)

struct RenderInstance #

struct RenderInstance(Copyable, Movable)

One drawn object: mesh and material indices into the renderer's registries.

Fields:

• mesh: Int

• material: Int

• transform: Mat4

• joint_offset: Int — Index of the first joint matrix in RenderScene.joints (skinned meshes), else -1.

• morph_weights: List[Float32]

• cast_shadows: Bool

• __init__ __init__( out self, mesh: Int, material: Int, transform: Mat4, joint_offset: Int = -1, cast_shadows: Bool = True, )

struct RenderScene #

struct RenderScene(Movable)

Everything one render call draws; owned by the caller and only read by the renderer.

Fields:

• camera: Camera

• lights: List[Light]

• instances: List[RenderInstance]

• joints: List[Mat4] — Skinning matrices (joint world * inverse bind), referenced by instances.

• environment: Environment

• __init__ __init__(out self, camera: Camera)

struct FrameStats #

struct FrameStats(ImplicitlyCopyable, Movable)

Counters of the last render, in Renderer.stats.

Fields:

• instances_submitted: Int
• instances_drawn: Int
• draw_calls: Int — Forward (lit) draws, opaque and blended.
• prepass_draw_calls: Int
• shadow_draw_calls: Int
• lights: Int
• shadow_views: Int
• passes: Int
• transient_textures: Int

struct Renderer #

struct Renderer(Movable)

The forward+ renderer; render draws a RenderScene into a target view. Owns the pipelines, persistent GPU buffers and textures, the mesh and material registries, the frame graph, the shader library and per-frame scratch (steady-state frames do not allocate). Holds raw pointers to Gfx and Resources, which must outlive it.

Fields:

• gfx: Pointer[Gfx, MutUntrackedOrigin]

• res: Pointer[Resources, MutUntrackedOrigin]

• lib: NativePtr

• shaders: ShaderManager

• library: ShaderLibrary

• settings: RenderSettings

• defaults: DefaultTextures

• graph: FrameGraph

• stats: FrameStats

• frame_index: Int

• graphviz: String — DOT text of the last compiled frame graph; refreshed by graph_dot() on demand.

• morph_groups: List[BindGroupHandle] — Object groups binding a morphed mesh's delta buffer, one per morph buffer in use; batches of meshes without morph targets use object_group.

• morph_group_keys: List[SIMD[DType.int64, 2]] — (index, generation) of the morph buffer each entry of morph_groups binds.

• post_group_keys: List[SIMD[DType.int64, 4]] — (input index, input generation, bloom index, bloom generation) per cached post group.

• alloc_marks: Bool — Print the Mojo allocation counter after each render phase (needs the counter library).

• gtao_groups: List[BindGroupHandle]

• gtao_group_keys: List[SIMD[DType.int64, 4]]

• meshes: List[GpuMesh]

• materials: List[GpuMaterial]

• material_params: List[Material]

• forward_shader: ShaderHandle

• depth_shader: ShaderHandle

• clusters_shader: ShaderHandle

• sky_shader: ShaderHandle

• ibl_shader: ShaderHandle

• post_shader: ShaderHandle

• gtao_shader: ShaderHandle

• gtao_msaa_shader: ShaderHandle

• frame_layout: BindGroupLayoutHandle

• object_layout: BindGroupLayoutHandle

• material_layout: BindGroupLayoutHandle

• pass_layout: BindGroupLayoutHandle

• cluster_out_layout: BindGroupLayoutHandle

• gtao_layout: BindGroupLayoutHandle

• gtao_msaa_layout: BindGroupLayoutHandle

• ibl_layout: BindGroupLayoutHandle

• post_layout: BindGroupLayoutHandle

• scene_pipeline_layout: PipelineLayoutHandle

• cluster_pipeline_layout: PipelineLayoutHandle

• gtao_pipeline_layout: PipelineLayoutHandle

• gtao_msaa_pipeline_layout: PipelineLayoutHandle

• ibl_pipeline_layout: PipelineLayoutHandle

• post_pipeline_layout: PipelineLayoutHandle

• frame_uniform: BufferHandle

• pass_uniforms: BufferHandle

• post_uniforms: BufferHandle

• lights_buffer: BufferHandle

• shadow_views_buffer: BufferHandle

• cluster_grid: BufferHandle

• cluster_indices: BufferHandle

• instances_buffer: BufferHandle

• instances_capacity: Int

• joints_buffer: BufferHandle

• joints_capacity: Int

• morph_weights_buffer: BufferHandle

• morph_slot_capacity: Int — Morph-weight slots (POST_UNIFORM_STRIDE bytes each) in morph_weights_buffer.

• empty_morph_buffer: BufferHandle

• cascade_texture: TextureHandle

• cascade_array_view: TextureViewHandle

• cascade_layer_views: List[TextureViewHandle]

• atlas_texture: TextureHandle

• atlas_view: TextureViewHandle

• env_texture: TextureHandle

• env_cube_view: TextureViewHandle

• prefiltered_texture: TextureHandle

• prefiltered_view: TextureViewHandle

• irradiance_texture: TextureHandle

• irradiance_view: TextureViewHandle

• brdf_texture: TextureHandle

• brdf_view: TextureViewHandle

• shadow_sampler: SamplerHandle

• env_sampler: SamplerHandle

• post_sampler: SamplerHandle

• nearest_sampler: SamplerHandle

• env_baked: Bool

• env_key: String

• frame_group: BindGroupHandle

• frame_group_ao_view: TextureViewHandle

• shadow_frame_group: BindGroupHandle

• cluster_frame_group: BindGroupHandle — Frame group variant for the cluster pass: the cluster buffers it writes are replaced by a dummy.

• dummy_cluster_buffer: BufferHandle — Frame group variant for shadow passes: the shadow maps being written are replaced by dummies.

• dummy_depth_array: TextureHandle

• dummy_depth_2d: TextureHandle

• object_group: BindGroupHandle

• object_group_key: String

• pass_group: BindGroupHandle

• cluster_out_group: BindGroupHandle

• pipelines: List[_CachedPipeline]

• sky_pipeline: RenderPipelineHandle

• sky_pipeline_msaa: UInt32

• cluster_pipeline: ComputePipelineHandle

• gtao_pipeline: ComputePipelineHandle

• gtao_blur_pipeline: ComputePipelineHandle

• gtao_msaa_pipeline: ComputePipelineHandle

• gtao_msaa_blur_pipeline: ComputePipelineHandle

• ibl_env_pipeline: ComputePipelineHandle

• ibl_prefilter_pipeline: ComputePipelineHandle

• ibl_irradiance_pipeline: ComputePipelineHandle

• ibl_brdf_pipeline: ComputePipelineHandle

• bloom_down_pipeline: RenderPipelineHandle

• bloom_up_pipeline: RenderPipelineHandle

• tonemap_pipeline: RenderPipelineHandle

• fxaa_pipeline: RenderPipelineHandle

• blit_pipeline: RenderPipelineHandle

• post_target_format: WGPUTextureFormat

• atlas: ShadowAtlas

• batches: List[_Batch]

• blend_batches: List[_Batch]

• instance_bytes: ByteWriter

• post_groups: List[BindGroupHandle]

• cluster_params: ClusterParams

• __init__ __init__( out self, gfx: Pointer[Gfx, MutUntrackedOrigin], res: Pointer[Resources, MutUntrackedOrigin], lib: NativePtr, settings: RenderSettings, target_format: WGPUTextureFormat, ) raises

• add_mesh add_mesh( mut self, label: String, data: MeshData, lods: Bool = True ) raises -> Int
  Uploads data and returns its index in meshes; raises if validation or upload fails. With lods and more than 64 triangles, up to four LODs are built with meshoptimizer; otherwise the mesh has one. Always appends (removed slots are only reused by add_cooked_mesh).

• add_cooked_mesh add_cooked_mesh( mut self, label: String, cooked: CookedMesh ) raises -> Int
  Registers a cooked mesh (streams already in GPU layout). Reuses a removed slot if any.

• replace_cooked_mesh replace_cooked_mesh( mut self, index: Int, label: String, cooked: CookedMesh ) raises
  Hot reload: swaps the GPU buffers behind index; instances keep their mesh index.

• remove_mesh remove_mesh(mut self, index: Int) raises
  Frees the GPU buffers; the slot is reused by the next add_cooked_mesh. Instances that still reference it are the caller's error (rendering them raises on the invalid handle).

• add_material add_material(mut self, material: Material) raises -> Int
  Uploads material and returns its index in materials; raises on a GPU error. A copy of the parameters is kept in material_params; texture views stay the caller's.

• replace_material replace_material(mut self, index: Int, material: Material) raises
  Hot reload: uploads material into slot index (instances keep their material index) and frees the uniform buffer and bind group of the version it replaces. The new version is uploaded before anything is freed, so a failed upload raises and leaves the slot as it was. Replacing a removed slot makes it live again. material_params[index] becomes a copy of material. Texture views and samplers are the caller's: the old ones are not destroyed (destroy them after this call if nothing else uses them). Raises when index is out of range.

• remove_material remove_material(mut self, index: Int) raises
  Frees the uniform buffer and bind group of slot index and leaves the slot empty (null handles); removing an empty slot does nothing. Indices stay stable: add_material always appends, so a removed slot is never handed out again (only replace_material on the same index revives it). render raises if a visible instance still uses a removed material. Texture views and samplers are the caller's, and material_params[index] keeps the last parameters. Raises when index is out of range.

• material_is_live material_is_live(self, index: Int) -> Bool
  True when slot index exists and has not been removed.

• mesh_lod_count mesh_lod_count(self, mesh: Int) -> Int
  Number of LOD index ranges of mesh mesh; level 0 is full detail.

• reload_shaders reload_shaders(mut self) raises -> Int
  Hot reload: recompiles changed programs and rebuilds every pipeline on success. Pipelines keep their handles; a failed compile keeps the last good module and pipelines.

• render render( mut self, scene: RenderScene, target: TextureViewHandle, width: Int, height: Int, ) raises
  Renders scene into target (format given at construction). Raises GfxError on device loss.

• graph_dot graph_dot(mut self) -> String
  DOT text of the last frame's graph (built on demand: debug UI, docs).

• release release(mut self) raises
  Frees the frame graph's pooled textures (everything else dies with Resources).

cinder.render.shader_library #

Source: cinder/render/shader_library.mojo

Shader programs assembled from WGSL files with #include "file.wgsl" lines, with hot reload. WGSL has no preprocessor, so includes are resolved here (relative to the shader directory, once per program, in order of first appearance). Error locations reported by naga refer to the assembled text; ShaderLibrary maps them back to the file and line they came from before raising.

struct AssembledShader #

struct AssembledShader(Copyable, Movable)

WGSL text with every include spliced in, mapped back to its source files. chunks locate each assembled line in its file; files lists every file read (directory/name), in order of first inclusion.

Fields:

• text: String

• chunks: List[_Chunk]

• files: List[String]

• __init__ __init__(out self)

• locate locate(self, assembled_line: Int) -> Tuple[String, Int]
  File and file line for a line of the assembled text.

def assemble #

def assemble(directory: String, entry: String) raises -> AssembledShader

Reads entry and splices every #include "x" (each file at most once) into one text.

struct ShaderLibrary #

struct ShaderLibrary(Movable)

Loads directory/<entry>.wgsl programs with includes; check_for_changes hot reloads.

Fields:

• gfx: Pointer[Gfx, MutUntrackedOrigin]

• res: Pointer[Resources, MutUntrackedOrigin]

• shaders: Pointer[ShaderManager, MutUntrackedOrigin]

• directory: String

• programs: List[_Program]

• diagnostics: List[LogRecord]

• reloaded: List[ShaderHandle] — Handles whose module changed in the last check_for_changes (pipelines must be rebuilt).

• __init__ __init__( out self, gfx: Pointer[Gfx, MutUntrackedOrigin], res: Pointer[Resources, MutUntrackedOrigin], shaders: Pointer[ShaderManager, MutUntrackedOrigin], directory: String, )

• compile compile(mut self, entry: String) raises -> WGPUShaderModule
  Assembles and compiles without registering (used for one-off modules and by load).

• load load(mut self, entry: String) raises -> ShaderHandle
  Assembles, compiles and registers entry (a file in directory) for hot reload. Returns the handle Resources holds the module under. Raises on a missing include or a compile error, with locations mapped to the source files.

• check_for_changes check_for_changes(mut self) -> Int
  Recompiles programs whose files changed. Returns how many modules were replaced; failures keep the last good module and add an error diagnostic naming file:line:column.

• take_diagnostics take_diagnostics(mut self) -> List[LogRecord]
  Returns and clears the reload records from check_for_changes (info or error).

cinder.render.shadows #

Source: cinder/render/shadows.mojo

Cascaded shadow maps for the sun and an atlas for spot and point lights (CPU-side maths). Cascade fitting: each cascade covers a slice of the camera frustum (practical split scheme, lambda 0.75). The orthographic projection is fitted to the slice's bounding sphere so it has a constant size while the camera rotates, and its origin is snapped to whole shadow texels in light space so edges do not shimmer when the camera moves.

• comptime CASCADE_COUNT = 4 — Sun shadow cascades; matches the four-entry cascade arrays of Frame in common.wgsl.
• comptime SHADOW_VIEW_BYTES = 96 — Bytes per packed ShadowView: the size of ShadowView in common.wgsl.

struct Cascade #

struct Cascade(ImplicitlyCopyable, Movable)

One fitted sun cascade: an orthographic reverse-Z light view-projection (world to clip).

Fields:

• view_proj: Mat4
• split_end: Float32 — View-space distance where this cascade ends.
• texel_world: Float32 — World-space size of one shadow texel in this cascade.

def cascade_splits_into #

def cascade_splits_into( mut out: Array[Float32, CASCADE_COUNT], near: Float32, shadow_distance: Float32, lambda_: Float32 = 0.75, )

End distances of the four cascades (practical split: blend of log and uniform) into a stack array (no allocation).

def cascade_splits #

def cascade_splits( near: Float32, shadow_distance: Float32, lambda_: Float32 = 0.75 ) -> List[Float32]

End distances of the four cascades (practical split: blend of log and uniform).

def fit_cascade #

def fit_cascade( camera: Camera, light_dir: Vec3, z0: Float32, z1: Float32, resolution: Int ) -> Cascade

Orthographic light view-projection for one slice with texel snapping. light_dir is the direction light travels. Depth range is the sphere diameter plus a generous margin behind the slice so casters outside the camera frustum still cast.

def fit_cascades_into #

def fit_cascades_into( mut out: List[Cascade], camera: Camera, light_dir: Vec3, shadow_distance: Float32, resolution: Int, )

fit_cascades into a list supplied by the caller (cleared first, capacity kept).

def fit_cascades #

def fit_cascades( camera: Camera, light_dir: Vec3, shadow_distance: Float32, resolution: Int ) -> List[Cascade]

fit_cascades_into into a new list (allocates); per-frame code uses the _into variant.

struct ShadowView #

struct ShadowView(ImplicitlyCopyable, Movable)

One atlas tile: a light-space view-projection and its uv rectangle (matches common.wgsl).

Fields:

• view_proj: Mat4

• uv_origin_x: Float32

• uv_origin_y: Float32

• uv_size: Float32

• texel_uv: Float32

• near: Float32

• far: Float32

• pack pack(self, mut w: ByteWriter)
  Appends the 96-byte GPU form (ShadowView in common.wgsl). view_proj, then the uv rectangle (origin x, origin y, size, size), then the texel size in uv, near, far and a zero pad.

struct ShadowAtlas #

struct ShadowAtlas(Movable)

Fixed grid of square tiles in one depth texture. Spot lights take one tile, point lights six.

Fields:

• size: Int

• tile_size: Int

• tiles_per_row: Int

• next_tile: Int

• views: List[ShadowView]

• __init__ __init__(out self, size: Int = 4096, tile_size: Int = 512)

• capacity capacity(self) -> Int
  Number of tiles in the atlas (tiles_per_row squared).

• reset reset(mut self)
  Frees every tile and clears views (capacity kept); called at the start of each frame.

• tile_pixel_origin tile_pixel_origin(self, view_index: Int) -> Tuple[Int, Int]
  Top-left pixel of the tile used by shadow view view_index (views fill tiles in order).

• allocate allocate(mut self, light: Light) -> Int
  Adds the light's shadow views; returns the first view index or -1 when the atlas is full.

• pack_views_into pack_views_into(self, mut w: ByteWriter)
  Appends the GPU shadow-view array (at least one zeroed entry) to w.

• pack_views pack_views(self) -> List[UInt8]
pack_views_into into a new byte list (allocates; at least one zeroed entry).

cinder.render.textures #

Source: cinder/render/textures.mojo

GPU textures from CPU images: CPU box-filter mip chains, sRGB or linear formats, defaults.

struct GpuTexture #

struct GpuTexture(ImplicitlyCopyable, Movable)

An uploaded 2D texture and a view of all its mips; width and height are mip 0 in pixels. The texture and view are owned by whoever uploaded them and freed through Resources.

Fields:

• texture: TextureHandle
• view: TextureViewHandle
• width: UInt32
• height: UInt32
• mip_levels: UInt32

def mip_count #

def mip_count(width: Int, height: Int) -> Int

Levels in a full mip chain down to 1x1 (floor(log2(max(width, height))) + 1).

def downsample #

def downsample(img: Image) -> Image

2x2 box filter (edge pixels of odd sizes are clamped), in the image's own encoding.

def upload_image #

def upload_image( mut res: Resources, label: String, img: Image, srgb: Bool, mips: Bool = True ) raises -> GpuTexture

Uploads an RGBA8 image as a 2D texture with a CPU box-filtered mip chain. srgb selects RGBA8UnormSrgb (colour data) over RGBA8Unorm (linear data); mips = False uploads level 0 only. The caller owns the result; raises on a GPU error.

def solid_image #

def solid_image(r: UInt8, g: UInt8, b: UInt8, a: UInt8) -> Image

1x1 RGBA8 image of one colour (used for the default textures).

struct DefaultTextures #

struct DefaultTextures(ImplicitlyCopyable, Movable)

1x1 fallbacks: white (base colour, occlusion, metallic-roughness), flat normal, black emissive.

Fields:

• white: GpuTexture

• normal: GpuTexture

• black: GpuTexture

• sampler_linear_repeat: SamplerHandle

• sampler_nearest_clamp: SamplerHandle

• __init__ __init__(out self, mut res: Resources) raises