> Cinder 0.1.0 documentation: cinder.gfx API > Canonical page: https://cinder.ash10.dev/docs/api/gfx/ · Source: `docs/api/gfx.md` in the engine repository (engine commit 47c9352, imported 2026-11-09) > Index of every page for agents: https://cinder.ash10.dev/llms.txt # `cinder.gfx` ## `cinder.gfx` Source: `cinder/gfx/__init__.mojo` Safe, typed layer over wgpu-native. `Gfx` owns the instance, adapter, device and queue and drains the shim's event queue into diagnostics (validation errors, device loss, wgpu log). Resource modules build on it with one distinct handle type per resource kind and ownership through `__deinit__`. ## `cinder.gfx.commands` Source: `cinder/gfx/commands.mojo` Command recording: encoders, render and compute passes, copies, submission and readback. - `comptime NoChain = Optional[Pointer[WGPUChainedStruct, MutUntrackedOrigin]]` — Null `nextInChain` for wgpu descriptors that carry no chained extension struct. ### struct `ColorAttachment` ```mojo struct ColorAttachment(Copyable, Movable) ``` A colour target of a render pass. `view` may be a swapchain view obtained outside Resources; `resolve` is the single-sample target when `view` is multisampled (null otherwise). Fields: - `view`: WGPUTextureView - `clear`: Bool - `clear_color`: WGPUColor - `store`: Bool - `resolve`: WGPUTextureView - **`__init__`** `__init__( out self, view: WGPUTextureView, clear: Bool, var clear_color: WGPUColor, store: Bool, resolve: WGPUTextureView = WGPUTextureView(), )` - **`cleared`** `cleared( view: WGPUTextureView, r: Float64, g: Float64, b: Float64, a: Float64 ) -> ColorAttachment` Clears `view` to (r, g, b, a) at load and stores the result; no resolve target. - **`cleared_resolving`** `cleared_resolving( view: WGPUTextureView, resolve: WGPUTextureView, r: Float64, g: Float64, b: Float64, a: Float64, ) -> ColorAttachment` Clears the multisampled `view` to (r, g, b, a), resolves into `resolve` and discards the multisampled contents (store op Discard). - **`loaded`** `loaded(view: WGPUTextureView) -> ColorAttachment` Keeps the existing contents of `view` (load op Load) and stores the result. - `comptime MAX_COLOR_ATTACHMENTS = 4` — Colour attachments per render pass (wgpu allows 8; the engine uses at most 1 + resolve). ### struct `DepthAttachment` ```mojo struct DepthAttachment(ImplicitlyCopyable, Movable) ``` Depth target. Reverse-Z clears to 0.0 (far). Fields: - `view`: WGPUTextureView - `clear`: Bool - `clear_depth`: Float32 - `store`: Bool - **`none`** `none() -> DepthAttachment` No depth target: `begin_render_pass` then passes no depth-stencil attachment. - **`cleared_reverse_z`** `cleared_reverse_z(view: WGPUTextureView) -> DepthAttachment` Clears `view` to 0.0 (the far plane under reverse-Z) and stores the result. ### struct `RenderPass` ```mojo struct RenderPass(Movable) ``` An open render pass. `end` must be called exactly once. Fields: - `gfx`: Pointer[Gfx, MutUntrackedOrigin] - `res`: Pointer[Resources, MutUntrackedOrigin] - `raw`: WGPURenderPassEncoder - `ended`: Bool - **`__init__`** `__init__( out self, gfx: Pointer[Gfx, MutUntrackedOrigin], res: Pointer[Resources, MutUntrackedOrigin], raw: WGPURenderPassEncoder, )` - **`set_pipeline`** `set_pipeline(self, h: RenderPipelineHandle) raises` Binds the render pipeline; raises if the handle is not live in `Resources`. - **`set_bind_group`** `set_bind_group(self, index: UInt32, h: BindGroupHandle) raises` Binds a bind group at group `index` with no dynamic offsets; raises on an invalid handle. - **`set_bind_group_dynamic`** `set_bind_group_dynamic( self, index: UInt32, h: BindGroupHandle, mut offsets: List[UInt32] ) raises` Binds a bind group at group `index` with one dynamic offset per dynamic binding. `offsets` is read during the call only. Raises on an invalid handle; a wrong offset count or alignment surfaces as a validation diagnostic through `Gfx.pump`. - **`set_vertex_buffer`** `set_vertex_buffer( self, slot: UInt32, h: BufferHandle, offset: UInt64 = 0 ) raises` Binds `h` to vertex slot `slot` from `offset` to the end of the buffer. Raises on an invalid handle or when `offset` is not below the buffer size (nothing is bound then). - **`set_index_buffer`** `set_index_buffer( self, h: BufferHandle, format: WGPUIndexFormat, offset: UInt64 = 0 ) raises` Binds `h` as the index buffer with `format` from `offset` to the end of the buffer. Raises on an invalid handle or when `offset` is not below the buffer size (nothing is bound then). - **`set_viewport`** `set_viewport( self, x: Float32, y: Float32, width: Float32, height: Float32 )` Sets the viewport rectangle in pixels with depth range 0..1. - **`set_scissor`** `set_scissor(self, x: UInt32, y: UInt32, width: UInt32, height: UInt32)` Sets the scissor rectangle in pixels. - **`draw`** `draw( self, vertex_count: UInt32, instance_count: UInt32 = 1, first_vertex: UInt32 = 0, first_instance: UInt32 = 0, )` Draws non-indexed primitives with the bound pipeline and vertex buffers. - **`draw_indexed`** `draw_indexed( self, index_count: UInt32, instance_count: UInt32 = 1, first_index: UInt32 = 0, base_vertex: Int32 = 0, first_instance: UInt32 = 0, )` Draws indexed primitives from the bound index buffer; `base_vertex` is added to each index. - **`end`** `end(mut self)` Ends and releases the pass encoder. Later calls do nothing. A pass dropped without `end` is ended and released by its destructor, which runs right after the pass's last use, so the encoder is never left with an open pass. ### struct `ComputePass` ```mojo struct ComputePass(Movable) ``` An open compute pass from `CommandEncoder.begin_compute_pass`. `end` must be called exactly once. Fields: - `gfx`: Pointer[Gfx, MutUntrackedOrigin] - `res`: Pointer[Resources, MutUntrackedOrigin] - `raw`: WGPUComputePassEncoder - `ended`: Bool - **`__init__`** `__init__( out self, gfx: Pointer[Gfx, MutUntrackedOrigin], res: Pointer[Resources, MutUntrackedOrigin], raw: WGPUComputePassEncoder, )` - **`set_pipeline`** `set_pipeline(self, h: ComputePipelineHandle) raises` Binds the compute pipeline; raises if the handle is not live in `Resources`. - **`set_bind_group`** `set_bind_group(self, index: UInt32, h: BindGroupHandle) raises` Binds a bind group at group `index` with no dynamic offsets; raises on an invalid handle. - **`set_bind_group_dynamic`** `set_bind_group_dynamic( self, index: UInt32, h: BindGroupHandle, mut offsets: List[UInt32] ) raises` Binds a bind group at group `index` with one dynamic offset per dynamic binding. `offsets` is read during the call only. Raises on an invalid handle; a wrong offset count or alignment surfaces as a validation diagnostic through `Gfx.pump`. - **`dispatch`** `dispatch(self, x: UInt32, y: UInt32 = 1, z: UInt32 = 1)` Dispatches an x by y by z grid of workgroups with the bound pipeline. - **`end`** `end(mut self)` Ends and releases the pass encoder. Later calls do nothing. A pass dropped without `end` is ended and released by its destructor, which runs right after the pass's last use, so the encoder is never left with an open pass. ### def `command_encoder_descriptor` ```mojo def command_encoder_descriptor(ref label: String) -> WGPUCommandEncoderDescriptor ``` The descriptor `CommandEncoder` creates its encoder with: no chain, `label` as the label. The view borrows `label`, which must outlive the wgpu call (`keep` it). ### struct `CommandEncoder` ```mojo struct CommandEncoder(Movable) ``` Records one command buffer. `finish_and_submit` consumes it; an encoder dropped without it is released by its destructor and its commands are discarded. Fields: - `gfx`: Pointer[Gfx, MutUntrackedOrigin] - `res`: Pointer[Resources, MutUntrackedOrigin] - `raw`: WGPUCommandEncoder - **`__init__`** `__init__( out self, gfx: Pointer[Gfx, MutUntrackedOrigin], res: Pointer[Resources, MutUntrackedOrigin], label: String, ) raises` - **`begin_render_pass`** `begin_render_pass( self, colors: List[ColorAttachment], depth: DepthAttachment ) raises -> RenderPass` Begins a render pass on the given colour targets and optional depth target. Raises when there are more than `MAX_COLOR_ATTACHMENTS` colours or wgpu returns NULL. The depth attachment is used only when `depth.view` is non-null; stencil is not used. Call `RenderPass.end` before recording anything else on this encoder. - **`begin_compute_pass`** `begin_compute_pass(self) raises -> ComputePass` Begins a compute pass without timestamp writes; raises if wgpu returns NULL. Call `ComputePass.end` before recording anything else on this encoder. - **`copy_buffer_to_buffer`** `copy_buffer_to_buffer( self, src: BufferHandle, src_offset: UInt64, dst: BufferHandle, dst_offset: UInt64, size: UInt64, ) raises` Records a copy of `size` bytes between two buffers. Raises on an invalid handle; range and usage errors surface as validation diagnostics through `Gfx.pump`. - **`copy_texture_to_buffer`** `copy_texture_to_buffer( self, texture: TextureHandle, dst: BufferHandle, bytes_per_row: UInt32, width: UInt32, height: UInt32, ) raises` Copies mip 0, layer 0 of a `Resources` texture into `dst` at offset 0, with `bytes_per_row` stride and `height` rows per image. Raises on an invalid handle. - **`copy_raw_texture_to_buffer`** `copy_raw_texture_to_buffer( self, texture: WGPUTexture, dst: BufferHandle, bytes_per_row: UInt32, width: UInt32, height: UInt32, ) raises` Copies mip 0 of a texture outside `Resources` (a swapchain texture) into `dst`. - **`finish_and_submit`** `finish_and_submit(deinit self) raises` Finishes the encoder, submits the command buffer to the queue and releases both. Raises if `wgpuCommandEncoderFinish` returns NULL (the encoder is still released). Does not wait for the GPU; use `wait_for_queue` for that. ### def `wait_for_queue` ```mojo def wait_for_queue(mut gfx: Gfx) raises GfxError ``` Blocks until all submitted work has completed (tests and shutdown; never in the frame loop). ### def `read_buffer` ```mojo def read_buffer( mut gfx: Gfx, res: Resources, buffer: BufferHandle, size: Int ) raises -> List[UInt8] ``` Maps a MapRead buffer, copies `size` bytes out and unmaps it (tests and tools only). ## `cinder.gfx.debug_draw` Source: `cinder/gfx/debug_draw.mojo` Immediate-mode debug lines: segments, boxes, spheres, axes and grids drawn in one line-list pass. Vertices accumulate on the CPU each frame (`line`, `aabb`, ...) and are uploaded once in `flush`, which records the draw into an open `RenderPass`. The vertex buffer grows by doubling and is never shrunk, so the steady state allocates nothing. Depth testing is reverse-Z when a depth format is given; `depth_format == Undefined` draws on top of everything. - `comptime VERTEX_BYTES = 16` — Float32x3 position + Unorm8x4 colour. - `comptime SHADER = """` — WGSL for debug lines: transforms positions by the camera uniform and passes the vertex colour through unlit. ### struct `Color8` ```mojo struct Color8(Equatable, ImplicitlyCopyable, RegisterPassable) ``` 8-bit RGBA colour. Fields: - `r`: UInt8 - `g`: UInt8 - `b`: UInt8 - `a`: UInt8 - **`red`** `red() -> Color8` Opaque red (255, 0, 0, 255). - **`green`** `green() -> Color8` Opaque green (0, 255, 0, 255). - **`blue`** `blue() -> Color8` Opaque blue (0, 0, 255, 255). - **`white`** `white() -> Color8` Opaque white (255, 255, 255, 255). - **`yellow`** `yellow() -> Color8` Opaque yellow (255, 255, 0, 255). ### struct `DebugDraw` ```mojo struct DebugDraw(Movable) ``` Per-frame line accumulator plus the GPU objects that draw it. Fields: - `gfx`: Pointer[Gfx, MutUntrackedOrigin] - `res`: Pointer[Resources, MutUntrackedOrigin] - `shader`: ShaderHandle - `pipeline`: RenderPipelineHandle - `camera_buffer`: BufferHandle - `camera_group`: BindGroupHandle - `vertex_buffer`: BufferHandle - `vertex_capacity`: Int — Vertices the GPU buffer can hold. - `vertices`: List[UInt8] - `vertex_count`: Int - `grows`: Int — Times the vertex buffer was reallocated (tests check this stays flat in steady state). - **`__init__`** `__init__( out self, gfx: Pointer[Gfx, MutUntrackedOrigin], res: Pointer[Resources, MutUntrackedOrigin], mut shaders: ShaderManager, color_format: WGPUTextureFormat, depth_format: WGPUTextureFormat = WGPUTextureFormat_Undefined, initial_capacity: Int = 4096, ) raises` - **`clear`** `clear(mut self)` Drops this frame's lines (called by `flush`). - **`line`** `line(mut self, a: Vec3, b: Vec3, color: Color8)` Queues one world-space segment from `a` to `b` for this frame (two vertices). Only CPU memory grows here; `upload` enlarges the GPU buffer if needed, `flush` draws and clears. - **`aabb`** `aabb(mut self, min: Vec3, max: Vec3, color: Color8)` The 12 edges of an axis-aligned box. - **`sphere`** `sphere( mut self, centre: Vec3, radius: Float32, color: Color8, segments: Int = 24, )` Three great circles (XY, XZ, YZ). - **`axes`** `axes(mut self, origin: Vec3, length: Float32)` X red, Y green, Z blue. - **`grid`** `grid(mut self, half_extent: Int, spacing: Float32, color: Color8)` An XZ ground grid centred on the origin with `2 * half_extent + 1` lines per axis. - **`upload`** `upload(mut self, view_proj: Mat4) raises` Writes the camera and this frame's vertices to the GPU (before the render pass opens). - **`flush`** `flush(mut self, pass_: RenderPass) raises` Records the draw for the vertices uploaded by `upload`, then clears them. ## `cinder.gfx.device` Source: `cinder/gfx/device.mojo` Gfx: instance, adapter, device and queue, with every wgpu callback pulled from the shim queue. - `comptime EventQueuePtr = Optional[Pointer[CnEventQueue, MutUntrackedOrigin]]` — Nullable pointer to the shim's CnEventQueue that carries every wgpu callback as an event. - `comptime NoChain = Optional[Pointer[WGPUChainedStruct, MutUntrackedOrigin]]` — Null `nextInChain` for wgpu descriptors that carry no chained extension struct. - `comptime DEFAULT_TIMEOUT_NS = 10_000_000_000` — How long `Gfx.await_event` pumps before raising GfxError: 10 seconds. ### struct `GfxError` ```mojo struct GfxError(Copyable, Movable, Writable) ``` A recoverable graphics failure (adapter/device request, timeout, lost device). Fields: - `message`: String - **`write_to`** `write_to(self, mut writer: Some[Writer])` ### struct `Gfx` ```mojo struct Gfx(Movable) ``` Owns one wgpu instance, adapter, device and queue. Callbacks never run in Mojo: `pump` drives wgpu and drains the shim's event queue, turning log lines, uncaptured validation errors and device loss into `diagnostics` (LogRecords for the engine logger) while returning every other event to the caller that awaits it. Fields: - `lib`: NativePtr - `events`: EventQueuePtr - `instance`: WGPUInstance - `adapter`: WGPUAdapter - `device`: WGPUDevice - `queue`: WGPUQueue - `adapter_name`: String - `backend`: UInt32 - `wireframe_supported`: Bool — True when the device was created with wgpu-native's PolygonModeLine feature. - `bc_supported`: Bool — True when the device was created with BC (DXT/BC7) texture compression. - `diagnostics`: List[LogRecord] - `error_count`: Int — Uncaptured validation errors seen since creation. Tests assert this stays zero. - `lost`: Bool - `surface`: WGPUSurface — The window surface when constructed from a `Window`; null for headless devices. - `surface_window`: Optional[Pointer[Window, MutUntrackedOrigin]] - **`__init__`** `__init__( out self, lib: NativePtr, surface: WGPUSurface ) raises GfxError` Creates instance, adapter (compatible with `surface` when given) and device. - **`__init__`** `__init__(out self, lib: NativePtr, ref window: Window) raises GfxError` Creates instance, a surface for `window`, a compatible adapter and device. `Gfx` keeps the surface (`surface` field) and destroys it at teardown. - **`__init__`** `__init__( out self, lib: NativePtr, surface: WGPUSurface, window: Optional[Pointer[Window, MutUntrackedOrigin]], ) raises GfxError` - **`next_request_id`** `next_request_id(mut self) -> UInt64` Returns a fresh id (1, 2, ...) that tags an async shim request so its reply event can be matched by `await_event` / `take_pending`. - **`pump`** `pump(mut self, wait: Bool)` Drives wgpu callbacks and drains the shim queue. Log, error and device-lost events become diagnostics; everything else is held for `await_event` / `take_pending`. - **`await_event`** `await_event( mut self, kind: UInt32, request_id: UInt64, timeout_ns: Int = DEFAULT_TIMEOUT_NS, ) raises GfxError -> CnEvent` Pumps until the event (kind, request id) arrives; raises GfxError on timeout. - **`take_pending`** `take_pending( mut self, kind: UInt32, request_id: UInt64, mut out: List[CnEvent] )` Moves every pending event matching (kind, request id) into `out`, in arrival order. - **`take_diagnostics`** `take_diagnostics(mut self) -> List[LogRecord]` Returns and clears the LogRecords collected by `pump`: wgpu log lines (`wgpu`), uncaptured validation errors (`wgpu.validation`) and device loss (`wgpu.device`). `error_count` and `lost` are not reset. ## `cinder.gfx.pipeline` Source: `cinder/gfx/pipeline.mojo` Typed descriptors for bind group layouts, bind groups, pipeline layouts and pipelines. Each `create_*` builds the wgpu descriptor from engine-side structs, calls wgpu with every pointee kept alive for the call, and adopts the result into `Resources` under a typed handle. - `comptime NoChain = Optional[Pointer[WGPUChainedStruct, MutUntrackedOrigin]]` — Null `nextInChain` for wgpu descriptors that carry no chained extension struct. ### struct `BindingKind` ```mojo struct BindingKind(Equatable, ImplicitlyCopyable, RegisterPassable) ``` What a bind group layout slot holds. Fields: - `value`: UInt8 - **`uniform_buffer`** `uniform_buffer() -> BindingKind` Uniform buffer; `LayoutEntry.dynamic_offset` and `min_binding_size` apply. - **`storage_buffer`** `storage_buffer() -> BindingKind` Read-write storage buffer; `dynamic_offset` and `min_binding_size` apply. - **`readonly_storage_buffer`** `readonly_storage_buffer() -> BindingKind` Read-only storage buffer; `dynamic_offset` and `min_binding_size` apply. - **`texture_2d`** `texture_2d() -> BindingKind` Filterable float texture with a 2D view dimension. - **`sampler`** `sampler() -> BindingKind` Filtering sampler. - **`comparison_sampler`** `comparison_sampler() -> BindingKind` Comparison sampler, as made by `Resources.create_comparison_sampler`. - **`depth_texture_2d`** `depth_texture_2d() -> BindingKind` Depth texture with a 2D view dimension. - **`depth_texture_2d_array`** `depth_texture_2d_array() -> BindingKind` Depth texture with a 2D-array view dimension. - **`texture_cube`** `texture_cube() -> BindingKind` Filterable float texture with a cube view dimension. - **`texture_2d_array`** `texture_2d_array() -> BindingKind` Filterable float texture with a 2D-array view dimension. - **`storage_texture_2d_write`** `storage_texture_2d_write() -> BindingKind` Write-only storage texture; `LayoutEntry.format` names the texel format. - **`storage_texture_2d_array_write`** `storage_texture_2d_array_write() -> BindingKind` Write-only storage texture with a 2D-array view; `LayoutEntry.format` names the texel format. - **`depth_texture_multisampled_2d`** `depth_texture_multisampled_2d() -> BindingKind` Multisampled depth texture with a 2D view dimension. - **`non_filtering_sampler`** `non_filtering_sampler() -> BindingKind` Non-filtering sampler, for use with `texture_2d_unfilterable` textures. - **`texture_2d_unfilterable`** `texture_2d_unfilterable() -> BindingKind` Float texture read with textureLoad or a non-filtering sampler (RGBA32Float). ### struct `LayoutEntry` ```mojo struct LayoutEntry(ImplicitlyCopyable, Movable) ``` One slot of a bind group layout. `format` matters for storage textures only. Fields: - `binding`: UInt32 - `visibility`: UInt64 - `kind`: BindingKind - `dynamic_offset`: Bool - `min_binding_size`: UInt64 - `format`: WGPUTextureFormat - **`__init__`** `__init__( out self, binding: UInt32, visibility: UInt64, kind: BindingKind, dynamic_offset: Bool = False, min_binding_size: UInt64 = 0, format: WGPUTextureFormat = WGPUTextureFormat_Undefined, )` ### struct `BindingResource` ```mojo struct BindingResource(ImplicitlyCopyable, Movable) ``` What to bind in a slot: exactly one of buffer, texture view or sampler is non-null. Fields: - `binding`: UInt32 - `buffer`: BufferHandle - `buffer_offset`: UInt64 - `buffer_size`: UInt64 - `texture_view`: TextureViewHandle - `sampler`: SamplerHandle - **`for_buffer`** `for_buffer( binding: UInt32, buffer: BufferHandle, offset: UInt64, size: UInt64 ) -> BindingResource` Binds `size` bytes of `buffer` from `offset`; a `size` of 0 binds from `offset` to the end of the buffer (resolved in `create_bind_group`). - **`for_texture`** `for_texture( binding: UInt32, view: TextureViewHandle ) -> BindingResource` Binds a texture view from `Resources` (owned or imported). - **`for_sampler`** `for_sampler(binding: UInt32, sampler: SamplerHandle) -> BindingResource` Binds a sampler from `Resources`. ### struct `VertexAttribute` ```mojo struct VertexAttribute(ImplicitlyCopyable, Movable) ``` One vertex attribute: its format, byte offset within the vertex and shader location. Fields: - `format`: WGPUVertexFormat - `offset`: UInt64 - `location`: UInt32 ### struct `VertexLayout` ```mojo struct VertexLayout(Copyable, Movable) ``` One vertex buffer slot: stride, step mode and attributes. Fields: - `stride`: UInt64 - `step_mode`: WGPUVertexStepMode - `attributes`: List[VertexAttribute] - **`__init__`** `__init__( out self, stride: UInt64, var attributes: List[VertexAttribute], step_mode: WGPUVertexStepMode = WGPUVertexStepMode_Vertex, )` ### struct `DepthState` ```mojo struct DepthState(ImplicitlyCopyable, Movable) ``` Depth testing. Reverse-Z means GreaterEqual is the engine's default compare. Fields: - `format`: WGPUTextureFormat - `write`: Bool - `compare`: WGPUCompareFunction - `bias`: Int32 - `bias_slope`: Float32 - `bias_clamp`: Float32 - **`__init__`** `__init__( out self, format: WGPUTextureFormat, write: Bool, compare: WGPUCompareFunction, bias: Int32 = 0, bias_slope: Float32 = 0.0, bias_clamp: Float32 = 0.0, )` - **`none`** `none() -> DepthState` No depth-stencil state: `build_render_pipeline` omits it because the format is Undefined. - **`reverse_z`** `reverse_z(format: WGPUTextureFormat, write: Bool = True) -> DepthState` Reverse-Z depth test (GreaterEqual) on `format`, writing depth unless `write` is False, with no bias. - **`reverse_z_biased`** `reverse_z_biased( format: WGPUTextureFormat, bias: Int32, bias_slope: Float32 ) -> DepthState` Shadow-map depth: reverse-Z, written, with constant and slope bias (negative values push depth away from the light in reverse-Z). ### struct `BlendMode` ```mojo struct BlendMode(Equatable, ImplicitlyCopyable, RegisterPassable) ``` Colour blending preset of a `ColorTarget`, expanded to a WGPUBlendState when a pipeline is built. Any value other than alpha or additive builds as opaque. Fields: - `value`: UInt8 - **`opaque`** `opaque() -> BlendMode` No blending: the source replaces the destination (One, Zero). - **`alpha`** `alpha() -> BlendMode` Premultiplied-free source-over: src * a + dst * (1 - a). - **`additive`** `additive() -> BlendMode` Adds source to destination for colour and alpha (One, One). ### struct `ColorTarget` ```mojo struct ColorTarget(ImplicitlyCopyable, Movable) ``` One colour output of a render pipeline: its texture format and blend mode, written with all channels enabled. Fields: - `format`: WGPUTextureFormat - `blend`: BlendMode ### struct `RenderPipelineDesc` ```mojo struct RenderPipelineDesc(Copyable, Movable) ``` Everything needed for a render pipeline. Entry points name functions in `shader`. Fields: - `label`: String - `layout`: PipelineLayoutHandle - `shader`: ShaderHandle - `vertex_entry`: String - `fragment_entry`: String - `vertex_layouts`: List[VertexLayout] - `color_targets`: List[ColorTarget] - `depth`: DepthState - `topology`: WGPUPrimitiveTopology - `cull_mode`: WGPUCullMode - `sample_count`: UInt32 - `wireframe`: Bool — Line polygon mode (needs the device feature; see `Gfx.wireframe_supported`). - `front_face_cw`: Bool - **`__init__`** `__init__( out self, label: String, layout: PipelineLayoutHandle, shader: ShaderHandle, vertex_entry: String, fragment_entry: String, var vertex_layouts: List[VertexLayout], var color_targets: List[ColorTarget], depth: DepthState = DepthState.none(), topology: WGPUPrimitiveTopology = WGPUPrimitiveTopology_TriangleList, cull_mode: WGPUCullMode = WGPUCullMode_None, sample_count: UInt32 = 1, wireframe: Bool = False, front_face_cw: Bool = False, )` ### def `create_bind_group_layout` ```mojo def create_bind_group_layout( mut res: Resources, label: String, entries: List[LayoutEntry] ) raises -> BindGroupLayoutHandle ``` Creates a WGPUBindGroupLayout from `entries` and adopts it into `res`. Each entry becomes a buffer, sampler, texture or storage-texture layout according to its `BindingKind`; a kind not handled here leaves every binding type unused. Raises if wgpu returns NULL; other validation errors surface through `Gfx.pump` diagnostics. The caller destroys the handle with `Resources.destroy_bind_group_layout`. ### def `create_pipeline_layout` ```mojo def create_pipeline_layout( mut res: Resources, label: String, layouts: List[BindGroupLayoutHandle] ) raises -> PipelineLayoutHandle ``` Creates a WGPUPipelineLayout whose bind group `layouts` are in group order and adopts it. Raises on an invalid layout handle or a NULL result. The caller destroys the handle with `Resources.destroy_pipeline_layout`. ### def `create_bind_group` ```mojo def create_bind_group( mut res: Resources, label: String, layout: BindGroupLayoutHandle, bindings: List[BindingResource], ) raises -> BindGroupHandle ``` Creates a WGPUBindGroup for `layout` from `bindings` and adopts it into `res`. The raw wgpu objects behind the handles are captured at creation time; replacing them behind the same handle later does not update this bind group. Raises on any invalid handle or a NULL result; mismatches with the layout surface through `Gfx.pump` diagnostics. The caller destroys the handle with `Resources.destroy_bind_group`. ### def `build_render_pipeline` ```mojo def build_render_pipeline( res: Resources, desc: RenderPipelineDesc ) raises -> WGPURenderPipeline ``` Creates the raw pipeline object (used by `create_render_pipeline` and by hot reload). Raises on an invalid handle, a NULL result, or a validation error drained right after creation; the invalid object is then released and the error carries wgpu's validation message. The caller owns the returned object. ### def `create_render_pipeline` ```mojo def create_render_pipeline( mut res: Resources, desc: RenderPipelineDesc ) raises -> RenderPipelineHandle ``` Builds a render pipeline with `build_render_pipeline` and adopts it into `res`. Raises if creation fails, including validation errors drained right after creation. The caller destroys the handle with `Resources.destroy_render_pipeline`. ### def `build_compute_pipeline` ```mojo def build_compute_pipeline( res: Resources, label: String, layout: PipelineLayoutHandle, shader: ShaderHandle, entry: String, ) raises -> WGPUComputePipeline ``` Creates the raw compute pipeline object, adopted by `create_compute_pipeline` or passed to `Resources.replace_compute_pipeline` to swap it behind an existing handle. A null `layout` handle passes a null pipeline layout to wgpu. Raises on an invalid handle, a NULL result, or a validation error drained right after creation; the invalid object is then released and the error carries wgpu's validation message. The caller owns the returned object. ### def `create_compute_pipeline` ```mojo def create_compute_pipeline( mut res: Resources, label: String, layout: PipelineLayoutHandle, shader: ShaderHandle, entry: String, ) raises -> ComputePipelineHandle ``` Builds a compute pipeline with `build_compute_pipeline` and adopts it into `res`. The caller destroys the handle with `Resources.destroy_compute_pipeline`. ## `cinder.gfx.resources` Source: `cinder/gfx/resources.mojo` Typed GPU resources: one handle type per kind, pooled records, ownership and leak tracking. Every resource created through `Resources` is tracked in a generational pool for its kind, so a `BufferHandle` cannot be passed where a `TextureHandle` is expected (compile error), stale handles fail validation (raise), and `live_counts()` reports exactly what is still alive. Check `live_counts().total() == 0` before teardown to assert a clean shutdown. `__deinit__` releases everything left and, when anything was left, appends one `gfx.resources` warning LogRecord with those counts to `Gfx.diagnostics` (read it with `Gfx.take_diagnostics`). Ownership rules: a pool owns every object it holds except views wrapped by `import_texture_view`, which are only dropped (`forget_texture_view`), never released. A texture cannot be destroyed while views created from it are alive (`destroy_texture` raises). `adopt_*` and `create_*` take ownership even when they raise: the new object is released if it cannot be stored. - `comptime NoChain = Optional[Pointer[WGPUChainedStruct, MutUntrackedOrigin]]` — Null `nextInChain` for wgpu descriptors that carry no chained extension struct. ### struct `BufferTag` ```mojo struct BufferTag ``` Phantom tag that makes `BufferHandle` a distinct type. Fields: ### struct `TextureTag` ```mojo struct TextureTag ``` Phantom tag that makes `TextureHandle` a distinct type. Fields: ### struct `TextureViewTag` ```mojo struct TextureViewTag ``` Phantom tag that makes `TextureViewHandle` a distinct type. Fields: ### struct `SamplerTag` ```mojo struct SamplerTag ``` Phantom tag that makes `SamplerHandle` a distinct type. Fields: ### struct `ShaderTag` ```mojo struct ShaderTag ``` Phantom tag that makes `ShaderHandle` a distinct type. Fields: ### struct `BindGroupLayoutTag` ```mojo struct BindGroupLayoutTag ``` Phantom tag that makes `BindGroupLayoutHandle` a distinct type. Fields: ### struct `PipelineLayoutTag` ```mojo struct PipelineLayoutTag ``` Phantom tag that makes `PipelineLayoutHandle` a distinct type. Fields: ### struct `BindGroupTag` ```mojo struct BindGroupTag ``` Phantom tag that makes `BindGroupHandle` a distinct type. Fields: ### struct `RenderPipelineTag` ```mojo struct RenderPipelineTag ``` Phantom tag that makes `RenderPipelineHandle` a distinct type. Fields: ### struct `ComputePipelineTag` ```mojo struct ComputePipelineTag ``` Phantom tag that makes `ComputePipelineHandle` a distinct type. Fields: - `comptime BufferHandle = Handle[BufferTag]` — Generational handle to a WGPUBuffer owned by `Resources.buffers`. - `comptime TextureHandle = Handle[TextureTag]` — Generational handle to a WGPUTexture owned by `Resources.textures`. - `comptime TextureViewHandle = Handle[TextureViewTag]` — Generational handle to a WGPUTextureView in `Resources.texture_views` (owned or imported). - `comptime SamplerHandle = Handle[SamplerTag]` — Generational handle to a WGPUSampler owned by `Resources.samplers`. - `comptime ShaderHandle = Handle[ShaderTag]` — Generational handle to a WGPUShaderModule owned by `Resources.shaders`. - `comptime BindGroupLayoutHandle = Handle[BindGroupLayoutTag]` — Generational handle to a WGPUBindGroupLayout owned by `Resources.bind_group_layouts`. - `comptime PipelineLayoutHandle = Handle[PipelineLayoutTag]` — Generational handle to a WGPUPipelineLayout owned by `Resources.pipeline_layouts`. - `comptime BindGroupHandle = Handle[BindGroupTag]` — Generational handle to a WGPUBindGroup owned by `Resources.bind_groups`. - `comptime RenderPipelineHandle = Handle[RenderPipelineTag]` — Generational handle to a WGPURenderPipeline owned by `Resources.render_pipelines`. - `comptime ComputePipelineHandle = Handle[ComputePipelineTag]` — Generational handle to a WGPUComputePipeline owned by `Resources.compute_pipelines`. ### struct `BufferDesc` ```mojo struct BufferDesc(Copyable, Movable) ``` What to create a buffer with. `usage` is a WGPUBufferUsage bit set. Fields: - `label`: String - `size`: UInt64 - `usage`: UInt64 - `mapped_at_creation`: Bool ### struct `TextureDesc` ```mojo struct TextureDesc(Copyable, Movable) ``` A 2D texture (array layers and 3D arrive with the renderer). `usage` is WGPUTextureUsage bits. Fields: - `label`: String - `width`: UInt32 - `height`: UInt32 - `depth_or_layers`: UInt32 - `mip_levels`: UInt32 - `sample_count`: UInt32 - `format`: WGPUTextureFormat - `usage`: UInt64 ### struct `SamplerDesc` ```mojo struct SamplerDesc(Copyable, Movable) ``` Filtering and addressing. `linear` selects trilinear filtering; otherwise nearest. Fields: - `label`: String - `linear`: Bool - `address_mode`: UInt32 - `max_anisotropy`: UInt16 ### struct `BufferRecord` ```mojo struct BufferRecord(Copyable, Movable) ``` Pool entry for a buffer: the WGPUBuffer plus the size and usage it was created with. Copies handed out by `Resources.buffer` share the raw object; only the pool releases it. Fields: - `raw`: WGPUBuffer - `size`: UInt64 - `usage`: UInt64 ### struct `TextureRecord` ```mojo struct TextureRecord(Copyable, Movable) ``` Pool entry for a texture: the WGPUTexture plus the extent, mip count, format and usage it was created with. Copies share the raw object; only the pool releases it. Fields: - `raw`: WGPUTexture - `width`: UInt32 - `height`: UInt32 - `depth_or_layers`: UInt32 - `mip_levels`: UInt32 - `format`: WGPUTextureFormat - `usage`: UInt64 ### struct `TextureViewRecord` ```mojo struct TextureViewRecord(Copyable, Movable) ``` Pool entry for a view: the WGPUTextureView and the texture it views. `texture` is null for views wrapped by `import_texture_view`, whose raw object the caller owns (`is_imported`). Fields: - `raw`: WGPUTextureView - `texture`: TextureHandle - **`is_imported`** `is_imported(self) -> Bool` True for a view wrapped by `import_texture_view`: `Resources` never releases it. ### struct `SamplerRecord` ```mojo struct SamplerRecord(Copyable, Movable) ``` Pool entry for a sampler: the WGPUSampler, released by `Resources.destroy_sampler`. Fields: - `raw`: WGPUSampler ### struct `ShaderRecord` ```mojo struct ShaderRecord(Copyable, Movable) ``` Pool entry for a shader: the WGPUShaderModule and the WGSL path it was compiled from. `ShaderManager` swaps `raw` in place on hot reload, keeping the handle stable. Fields: - `raw`: WGPUShaderModule - `source_path`: String ### struct `BindGroupLayoutRecord` ```mojo struct BindGroupLayoutRecord(Copyable, Movable) ``` Pool entry for a bind group layout: the WGPUBindGroupLayout the pool owns. Fields: - `raw`: WGPUBindGroupLayout ### struct `PipelineLayoutRecord` ```mojo struct PipelineLayoutRecord(Copyable, Movable) ``` Pool entry for a pipeline layout: the WGPUPipelineLayout the pool owns. Fields: - `raw`: WGPUPipelineLayout ### struct `BindGroupRecord` ```mojo struct BindGroupRecord(Copyable, Movable) ``` Pool entry for a bind group: the WGPUBindGroup the pool owns. Fields: - `raw`: WGPUBindGroup ### struct `RenderPipelineRecord` ```mojo struct RenderPipelineRecord(Copyable, Movable) ``` Pool entry for a render pipeline: the WGPURenderPipeline the pool owns. Fields: - `raw`: WGPURenderPipeline ### struct `ComputePipelineRecord` ```mojo struct ComputePipelineRecord(Copyable, Movable) ``` Pool entry for a compute pipeline: the WGPUComputePipeline the pool owns. Fields: - `raw`: WGPUComputePipeline ### struct `LiveCounts` ```mojo struct LiveCounts(ImplicitlyCopyable, Movable, Writable) ``` Resources alive per kind. Fields: - `buffers`: Int - `textures`: Int - `texture_views`: Int - `samplers`: Int - `shaders`: Int - `bind_group_layouts`: Int - `pipeline_layouts`: Int - `bind_groups`: Int - `render_pipelines`: Int - `compute_pipelines`: Int - **`total`** `total(self) -> Int` Sum over every kind; zero means nothing is left to release. - **`write_to`** `write_to(self, mut writer: Some[Writer])` ### struct `Resources` ```mojo struct Resources(Movable) ``` Pools of every GPU resource kind, owning the wgpu objects behind typed handles. Fields: - `gfx`: Pointer[Gfx, MutUntrackedOrigin] - `buffers`: Pool[BufferRecord, BufferTag] - `textures`: Pool[TextureRecord, TextureTag] - `texture_views`: Pool[TextureViewRecord, TextureViewTag] - `samplers`: Pool[SamplerRecord, SamplerTag] - `shaders`: Pool[ShaderRecord, ShaderTag] - `bind_group_layouts`: Pool[BindGroupLayoutRecord, BindGroupLayoutTag] - `pipeline_layouts`: Pool[PipelineLayoutRecord, PipelineLayoutTag] - `bind_groups`: Pool[BindGroupRecord, BindGroupTag] - `render_pipelines`: Pool[RenderPipelineRecord, RenderPipelineTag] - `compute_pipelines`: Pool[ComputePipelineRecord, ComputePipelineTag] - **`__init__`** `__init__( out self, gfx: Pointer[Gfx, MutUntrackedOrigin], capacity: Int = 4096 ) raises` - **`live_counts`** `live_counts(self) -> LiveCounts` Live handles per pool right now. Imported texture views count until they are forgotten. A non-zero `total()` just before teardown is what `__deinit__` reports as left alive. - **`create_buffer`** `create_buffer(mut self, desc: BufferDesc) raises -> BufferHandle` Creates a GPU buffer. Validation failures surface through `Gfx.pump` diagnostics; a NULL object (out of memory) raises, as does a full buffer pool (the new buffer is then released). - **`buffer`** `buffer(self, h: BufferHandle) raises -> BufferRecord` A copy of the buffer's record; raises on a null, stale or foreign handle. - **`destroy_buffer`** `destroy_buffer(mut self, h: BufferHandle) raises` Removes the handle, then destroys and releases the WGPUBuffer. Raises on an invalid handle, in which case nothing is released. - **`write_buffer`** `write_buffer( self, h: BufferHandle, offset: UInt64, data: Span[UInt8, _] ) raises` Uploads `data` through the queue (copied immediately; no mapping). - **`write_texture`** `write_texture( self, h: TextureHandle, mip_level: UInt32, width: UInt32, height: UInt32, layer: UInt32, data: Span[UInt8, _], bytes_per_row: UInt32, rows_per_image: UInt32 = 0, ) raises` Uploads one mip level of one array layer through the queue (copied immediately). `rows_per_image` is the number of rows in `data`; it defaults to `height` and must be the block-row count for block-compressed formats. - **`create_texture`** `create_texture(mut self, desc: TextureDesc) raises -> TextureHandle` Creates a 2D WGPUTexture (`depth_or_layers` array layers) and returns its handle. Validation failures surface through `Gfx.pump` diagnostics; a NULL object raises, as does a full texture pool (the new texture is then released). - **`texture`** `texture(self, h: TextureHandle) raises -> TextureRecord` A copy of the texture's record; raises on a null, stale or foreign handle. - **`texture_view_count`** `texture_view_count(self, h: TextureHandle) raises -> Int` How many live views created through `Resources` view this texture; raises on an invalid handle. - **`destroy_texture`** `destroy_texture(mut self, h: TextureHandle) raises` Removes the handle, then destroys and releases the WGPUTexture. Raises, releasing nothing, on an invalid handle or while views created from the texture are still alive: destroy those views first (`destroy_texture_view`), so no live view handle is left pointing at a destroyed texture. - **`create_texture_view_ex`** `create_texture_view_ex( mut self, texture: TextureHandle, dimension: WGPUTextureViewDimension, base_mip: UInt32, mip_count: UInt32, base_layer: UInt32, layer_count: UInt32, ) raises -> TextureViewHandle` A view of a mip range and layer range with an explicit dimension (2D array, cube, one layer of an array as 2D, one mip as a storage target). - **`create_texture_view`** `create_texture_view( mut self, texture: TextureHandle ) raises -> TextureViewHandle` A view of the whole texture with its own format and dimension. - **`import_texture_view`** `import_texture_view( mut self, raw: WGPUTextureView ) raises -> TextureViewHandle` Wraps a view the caller owns (a swapchain frame) so renderers can target it. Drop it with `forget_texture_view`; the raw view is never released here, not even at teardown, and `destroy_texture_view` refuses it. - **`forget_texture_view`** `forget_texture_view(mut self, h: TextureViewHandle) raises` Drops an imported view without releasing the wgpu object. Raises, dropping nothing, on an invalid handle or on a view created by `Resources` (that one must be released with `destroy_texture_view`, or it would leak). - **`texture_view`** `texture_view(self, h: TextureViewHandle) raises -> TextureViewRecord` A copy of the view's record; raises on a null, stale or foreign handle. - **`destroy_texture_view`** `destroy_texture_view(mut self, h: TextureViewHandle) raises` Removes the handle and releases the WGPUTextureView. Raises, releasing nothing, on an invalid handle or on an imported view (the caller owns that one; drop it with `forget_texture_view`). - **`create_sampler`** `create_sampler(mut self, desc: SamplerDesc) raises -> SamplerHandle` Creates a sampler with the same address mode on u, v and w and LOD clamp 0..32. `linear` picks linear min/mag/mip filtering, otherwise nearest. A NULL object raises; invalid settings surface as validation diagnostics through `Gfx.pump`. - **`create_comparison_sampler`** `create_comparison_sampler( mut self, label: String ) raises -> SamplerHandle` Linear PCF sampler: clamp to edge, compare GreaterEqual (reverse-Z shadow maps). - **`sampler`** `sampler(self, h: SamplerHandle) raises -> SamplerRecord` A copy of the sampler's record; raises on a null, stale or foreign handle. - **`destroy_sampler`** `destroy_sampler(mut self, h: SamplerHandle) raises` Removes the handle and releases the WGPUSampler; raises on an invalid handle. - **`adopt_shader`** `adopt_shader( mut self, raw: WGPUShaderModule, source_path: String ) raises -> ShaderHandle` Takes ownership of a compiled module (from `ShaderManager`) and returns its handle. Raises on a null module. Ownership passes even when this raises: if the pool is full the module is released before the error propagates. - **`shader`** `shader(self, h: ShaderHandle) raises -> ShaderRecord` A copy of the shader's record; raises on a null, stale or foreign handle. - **`destroy_shader`** `destroy_shader(mut self, h: ShaderHandle) raises` Removes the handle and releases the WGPUShaderModule. A `ShaderManager` that loaded it keeps watching the file; a later change then fails to reload and logs an error. - **`adopt_bind_group_layout`** `adopt_bind_group_layout( mut self, raw: WGPUBindGroupLayout ) raises -> BindGroupLayoutHandle` Takes ownership of a WGPUBindGroupLayout built in `pipeline.mojo`. Raises on a null `raw`; a full pool releases `raw` and raises. - **`bind_group_layout`** `bind_group_layout( self, h: BindGroupLayoutHandle ) raises -> BindGroupLayoutRecord` A copy of the layout's record; raises on a null, stale or foreign handle. - **`destroy_bind_group_layout`** `destroy_bind_group_layout(mut self, h: BindGroupLayoutHandle) raises` Removes the handle and releases the WGPUBindGroupLayout; raises on an invalid handle. - **`adopt_pipeline_layout`** `adopt_pipeline_layout( mut self, raw: WGPUPipelineLayout ) raises -> PipelineLayoutHandle` Takes ownership of a WGPUPipelineLayout built in `pipeline.mojo`. Raises on a null `raw`; a full pool releases `raw` and raises. - **`pipeline_layout`** `pipeline_layout( self, h: PipelineLayoutHandle ) raises -> PipelineLayoutRecord` A copy of the layout's record; raises on a null, stale or foreign handle. - **`destroy_pipeline_layout`** `destroy_pipeline_layout(mut self, h: PipelineLayoutHandle) raises` Removes the handle and releases the WGPUPipelineLayout; raises on an invalid handle. - **`adopt_bind_group`** `adopt_bind_group( mut self, raw: WGPUBindGroup ) raises -> BindGroupHandle` Takes ownership of a WGPUBindGroup built in `pipeline.mojo`. Raises on a null `raw`; a full pool releases `raw` and raises. - **`bind_group`** `bind_group(self, h: BindGroupHandle) raises -> BindGroupRecord` A copy of the bind group's record; raises on a null, stale or foreign handle. - **`destroy_bind_group`** `destroy_bind_group(mut self, h: BindGroupHandle) raises` Removes the handle and releases the WGPUBindGroup; raises on an invalid handle. - **`adopt_render_pipeline`** `adopt_render_pipeline( mut self, raw: WGPURenderPipeline ) raises -> RenderPipelineHandle` Takes ownership of a WGPURenderPipeline built in `pipeline.mojo`. Raises on a null `raw`; a full pool releases `raw` and raises. - **`render_pipeline`** `render_pipeline( self, h: RenderPipelineHandle ) raises -> RenderPipelineRecord` A copy of the pipeline's record; raises on a null, stale or foreign handle. - **`replace_render_pipeline`** `replace_render_pipeline( mut self, h: RenderPipelineHandle, raw: WGPURenderPipeline ) raises` Swaps the object behind an existing handle (hot reload), releasing the old one. Takes ownership of `raw` in every case: on a null `raw` or an invalid handle it raises, and a non-null `raw` is released first, so a failed hot reload never leaks. - **`destroy_render_pipeline`** `destroy_render_pipeline(mut self, h: RenderPipelineHandle) raises` Removes the handle and releases the WGPURenderPipeline; raises on an invalid handle. - **`adopt_compute_pipeline`** `adopt_compute_pipeline( mut self, raw: WGPUComputePipeline ) raises -> ComputePipelineHandle` Takes ownership of a WGPUComputePipeline built in `pipeline.mojo`. Raises on a null `raw`; a full pool releases `raw` and raises. - **`compute_pipeline`** `compute_pipeline( self, h: ComputePipelineHandle ) raises -> ComputePipelineRecord` A copy of the pipeline's record; raises on a null, stale or foreign handle. - **`replace_compute_pipeline`** `replace_compute_pipeline( mut self, h: ComputePipelineHandle, raw: WGPUComputePipeline ) raises` Swaps the object behind an existing handle (hot reload), releasing the old one. Takes ownership of `raw` in every case: on a null `raw` or an invalid handle it raises, and a non-null `raw` is released first, so a failed hot reload never leaks. - **`destroy_compute_pipeline`** `destroy_compute_pipeline(mut self, h: ComputePipelineHandle) raises` Removes the handle and releases the WGPUComputePipeline; raises on an invalid handle. ## `cinder.gfx.shaders` Source: `cinder/gfx/shaders.mojo` ShaderManager: WGSL modules from files, compile diagnostics with file:line:column, hot reload. Every loaded shader remembers its path and modification time. `check_for_changes` recompiles files that changed on disk; a successful recompile swaps the module behind the same `ShaderHandle` and reports the handle so pipeline owners rebuild, a failed one keeps the last good module and reports the error. Compile messages come from wgpu's async compilation-info callback through the shim queue. - `comptime NoChain = Optional[Pointer[WGPUChainedStruct, MutUntrackedOrigin]]` — Null `nextInChain` for wgpu descriptors that carry no chained extension struct. ### struct `ShaderMessage` ```mojo struct ShaderMessage(Copyable, Movable, Writable) ``` One compiler diagnostic, already formatted with its source location. Fields: - `path`: String - `line`: Int - `column`: Int - `is_error`: Bool - `text`: String - **`write_to`** `write_to(self, mut writer: Some[Writer])` ### struct `ShaderError` ```mojo struct ShaderError(Copyable, Movable, Writable) ``` Raised when a WGSL file fails to compile. `messages` holds every diagnostic. Fields: - `path`: String - `messages`: List[ShaderMessage] - **`write_to`** `write_to(self, mut writer: Some[Writer])` ### struct `ShaderSource` ```mojo struct ShaderSource(Copyable, Movable) ``` A loaded shader file and its on-disk state. Fields: - `handle`: ShaderHandle - `path`: String - `mtime_ns`: Int - `reload_failures`: Int ### struct `ReloadResult` ```mojo struct ReloadResult(Copyable, Movable) ``` Outcome of `check_for_changes` for one changed file. Fields: - `handle`: ShaderHandle - `path`: String - `success`: Bool ### def `parse_wgsl_report` ```mojo def parse_wgsl_report(path: String, report: String) -> List[ShaderMessage] ``` Turns a naga validation report into messages with locations. naga marks each location as `wgsl:LINE:COLUMN`; every such mark becomes one error message carrying the whole report text. A report with no mark yields one message at line 0. ### struct `ShaderManager` ```mojo struct ShaderManager(Movable) ``` Owns the list of shader files; the modules themselves live in `Resources`. Fields: - `gfx`: Pointer[Gfx, MutUntrackedOrigin] - `resources`: Pointer[Resources, MutUntrackedOrigin] - `sources`: List[ShaderSource] - `diagnostics`: List[LogRecord] - **`__init__`** `__init__( out self, gfx: Pointer[Gfx, MutUntrackedOrigin], resources: Pointer[Resources, MutUntrackedOrigin], )` - **`compile_source`** `compile_source( mut self, path: String, source: String ) raises -> WGPUShaderModule` Compiles WGSL text and returns the module, or raises ShaderError with every diagnostic. wgpu-native 29 does not implement the compilation-info callback, so the module is created inside a validation error scope; naga's report (which names `wgsl:line:column` locations) is popped through the shim queue and parsed into `ShaderMessage`s. - **`load`** `load(mut self, path: String) raises -> ShaderHandle` Loads and compiles a WGSL file, registering it for hot reload. - **`check_for_changes`** `check_for_changes(mut self) -> List[ReloadResult]` Recompiles every registered file whose modification time changed. On success the module behind the handle is replaced (old one released); on failure the last good module stays and an error diagnostic with file:line:column is recorded. - **`take_diagnostics`** `take_diagnostics(mut self) -> List[LogRecord]` Returns and clears the reload LogRecords from `check_for_changes` (info on a successful reload, error with the reason when the last good module was kept). ## `cinder.gfx.swapchain` Source: `cinder/gfx/swapchain.mojo` Swapchain: surface configuration, per-frame texture acquisition and presentation. Handles the three real-world cases a frame loop meets: resize (reconfigure on the next acquire), minimise (zero-sized window; frames are skipped until it is restored) and surface loss/outdated (reconfigure and retry once, then report). Device loss is `Gfx.lost` and is the caller's decision. - `comptime NoChain = Optional[Pointer[WGPUChainedStruct, MutUntrackedOrigin]]` — Null `nextInChain` for wgpu descriptors that carry no chained extension struct. ### struct `SurfaceFrame` ```mojo struct SurfaceFrame(Movable) ``` The acquired swapchain texture for one frame. `present` consumes it. Fields: - `texture`: WGPUTexture - `view`: WGPUTextureView - `suboptimal`: Bool - `width`: UInt32 - `height`: UInt32 ### struct `Swapchain` ```mojo struct Swapchain(Movable) ``` Owns the configuration of a wgpu surface created by `Window.create_surface`. Fields: - `gfx`: Pointer[Gfx, MutUntrackedOrigin] - `surface`: WGPUSurface - `format`: WGPUTextureFormat - `usage`: WGPUTextureUsage - `width`: UInt32 - `height`: UInt32 - `present_mode`: WGPUPresentMode - `configured`: Bool - `needs_reconfigure`: Bool - `frames_skipped`: Int — Frames skipped because the window had no area (minimised). - `reconfigures`: Int — Reconfigurations performed (resize, outdated or lost surfaces). - **`__init__`** `__init__( out self, gfx: Pointer[Gfx, MutUntrackedOrigin], surface: WGPUSurface, width: Int, height: Int, prefer_srgb: Bool = True, readback: Bool = False, ) raises GfxError` Picks a surface format (8-bit BGRA/RGBA, sRGB when `prefer_srgb`) and configures. - **`resize`** `resize(mut self, width: Int, height: Int)` Records a new size; the surface is reconfigured on the next `acquire`. - **`acquire`** `acquire(mut self) raises GfxError -> Optional[SurfaceFrame]` Returns the frame's texture, or None when the window is minimised. Outdated and lost surfaces are reconfigured and retried once; a second failure raises. - **`present`** `present(self, var frame: SurfaceFrame)` Presents the acquired frame and releases its view and texture. - **`discard`** `discard(self, var frame: SurfaceFrame)` Releases an acquired frame without presenting (used when a frame is abandoned). ## `cinder.gfx.util` Source: `cinder/gfx/util.mojo` Small conversions shared by the gfx modules. ### def `string_view` ```mojo def string_view(ref text: String) -> WGPUStringView ``` A non-owning WGPUStringView over `text`. `text` must outlive every use of the view. ### def `empty_string_view` ```mojo def empty_string_view() -> WGPUStringView ``` A WGPUStringView with a null pointer and zero length, for absent labels and strings. ### def `c_message` ```mojo def c_message(ev: CnEvent) -> String ``` The NUL-terminated message of a shim event as a String, decoded as UTF-8 (invalid sequences become U+FFFD). Reads at most the 1000-byte message buffer. ### def `zero_event` ```mojo def zero_event() -> CnEvent ``` An all-zero CnEvent, used as the out-parameter that `cn_event_queue_pop` fills. ### def `ptr_to` ```mojo def ptr_to[ T: AnyType ](ref value: T) -> Optional[Pointer[T, MutUntrackedOrigin]] ``` Raw pointer for a C call. The pointee must stay alive past the call (`keep` it). ### def `opaque_to` ```mojo def opaque_to[ T: AnyType ](ref value: T) -> Optional[OpaquePointer[MutUntrackedOrigin]] ``` `ptr_to` for `void*` parameters. ### def `handle_from` ```mojo def handle_from[ T: AnyType ](address: UInt64) -> Optional[Pointer[T, MutUntrackedOrigin]] ``` Rebuilds a wgpu object handle delivered through a CnEvent.