Struct WebGpuRenderer

Source

pub struct WebGpuRenderer { /* private fields */ }

Expand description

A WebGPU rendering backend wrapping the GPU device, queue, and canvas context for GPU-accelerated rendering on the web.

Created asynchronously via WebGpuRenderer::init because adapter and device acquisition returns JavaScript Promises that must be awaited. Once initialized, the renderer provides methods to create GPU resources (buffers, shader modules, command encoders) and execute render passes.

WebGPU types are stored as JsValue to avoid feature-gated import issues with web_sys. Method calls are performed via Reflect and JsCast.

Implementations§

Source §

impl WebGpuRenderer

Implements async initialization and GPU resource creation for WebGpuRenderer.

Source

pub fn is_available() -> bool

Returns true if navigator.gpu is exposed on the current origin.

This is the synchronous half of the canonical WebGPU capability probe used by Three.js (examples/jsm/capabilities/WebGPU.js): it only checks that the browser surfaces the GPU interface at all. It does not request an adapter — a present navigator.gpu does not guarantee that a usable GPU adapter is reachable (Linux software-rendered sessions, headless browsers, GPU-blacklisted devices and sandboxed iframes all expose navigator.gpu while requestAdapter() resolves to null or hangs forever).

Use this as the cheapest pre-flight check before showing a “needs HTTPS or localhost” prompt. For a definitive answer use Self::probe which also awaits requestAdapter().

§Returns

bool - true when navigator.gpu is a non-null, non-undefined object; false otherwise (including the “no window” runtime case, which web_sys::window() returns None for).

Source

pub async fn probe() -> bool

Probes whether a WebGPU adapter can actually be acquired.

Mirrors Three.js’ canonical capability probe exactly:

isAvailable = (navigator.gpu !== undefined)
if (isAvailable) {
    isAvailable = Boolean(await navigator.gpu.requestAdapter())
}

Wraps the adapter request in the same Promise.race timeout used by Self::init so that browsers which leave the adapter promise permanently pending (headless, sandboxed, device-lost) do not stall the UI forever. The timeout itself uses the INIT_PROMISE_TIMEOUT_MILLIS constant; on timeout, probe returns false rather than an error so callers can treat it the same as “no adapter”.

§Returns

bool - true only when both navigator.gpu is present and requestAdapter() resolves to a non-null adapter within the timeout window. false covers every other case (no window, missing navigator.gpu, reflect exception, adapter promise rejected or timed out, adapter resolved to null/undefined).

Source

pub async fn init( config: &RenderConfig, ) -> Result<WebGpuRenderer, WebGpuInitError>

Asynchronously initializes a WebGPU renderer from the given render configuration.

Requests a GPU adapter and device, obtains the WebGPU canvas context, and configures it with the preferred texture format. Returns Err if WebGPU is not supported, the adapter/device request fails, the canvas element is not found, or the adapter/device request hangs beyond INIT_PROMISE_TIMEOUT_MILLIS (a defensive timeout for browser GPU states that leave the WebGPU promises permanently pending).

The engine no longer logs diagnostic output internally; instead each failure mode is returned as a distinct WebGpuInitError variant so the caller can decide how to surface it (typically via Console::error or by falling back to the Canvas 2D backend).

§Arguments

&RenderConfig - The rendering configuration.

§Returns

Result<WebGpuRenderer, WebGpuInitError> - The initialized renderer, or a typed error describing the specific failure.

Source

pub fn resize(&mut self, physical_width: u32, physical_height: u32) -> bool

Resizes the canvas backing store and reconfigures the swap chain.

WebGPU’s GpuCanvasContext.configure is sticky: it sets the texture format and device once, but the swap chain tracks the canvas’s width/height attributes. When the CSS layout size changes (a window resize, a panel toggle, a DPR change) the canvas keeps its old physical dimensions unless we explicitly update width/height and call configure again. Without this, subsequent getCurrentTexture() calls return a texture that no longer matches the visible region and the frame either stretches or freezes.

Re-configureing with the same device + format is the spec-defined way to swap in a fresh swap chain bound to the new backing-store size.

§Arguments

u32 - The new physical pixel width (already multiplied by DPR).
u32 - The new physical pixel height.

§Returns

bool - true on success, false if the swap chain or canvas handles were missing or configure failed.

Source

pub fn sync_to_current_canvas(&mut self) -> bool

Resizes the canvas backing store to match the canvas element’s current CSS-rendered size in physical pixels (DPR applied).

This is the right entry point when the render loop does not know the desired logical size ahead of time and wants to follow the element’s actual layout box. It is also useful as a defensive recovery when the canvas was created while hidden (zero-sized parent) and is later shown at its real size.

Reads client_width / client_height from the canvas element, multiplies by detect_dpr(), and forwards to Self::resize.

§Returns

bool - true if the resize succeeded, false if the canvas was zero-sized (nothing to render to), detached (CSS layout box collapses to 0), or the underlying resize rejected.

Source

pub fn begin_render_pass_full( &mut self, encoder: &JsValue, color: &mut RenderPassColorAttachment, depth: Option<&RenderPassDepthStencilAttachment>, ) -> JsValue

Begins a render pass with full control over attachments, load/store ops, MSAA resolve targets, and an optional depth-stencil attachment.

This is the “complete” render-pass API used by the rest of the engine. All other render-pass entry points (including the legacy begin_render_pass(clear_color) wrapper) funnel through here.

The color attachment’s view is filled in lazily when None: if antialias == true and the multisample intermediate is available (or can be allocated), the pass draws into the MSAA view and resolves into the swap chain; otherwise it draws directly into the swap chain. The resolve_target is filled in with the swap-chain view when MSAA is active and the caller did not provide one.

§Arguments

encoder - The GpuCommandEncoder to begin the pass on.
color - The color attachment descriptor. color.view and color.resolve_target may be None; they are filled in with the renderer’s defaults.
depth - An optional depth-stencil attachment. Some(...) adds a depthStencilAttachment field to the pass descriptor; None omits it entirely.

§Returns

JsValue - The active GpuRenderPassEncoder as a JavaScript value, suitable for the existing set_pipeline / draw / end_render_pass calls.

Source

pub fn create_render_pipeline<S>(&self, shader_code: S) -> JsValue
where S: AsRef<str>,

Creates a simple render pipeline from a single WGSL shader source.

The shader must contain @vertex fn vs_main(...) and @fragment fn fs_main(...) entry points. No vertex buffers are used; vertex positions should be derived from @builtin(vertex_index) in the shader. The pipeline uses auto-layout (layout: null), which works when the shader has no bind groups.

This is the legacy “trivial” wrapper. For pipelines that need vertex buffers, custom entry-point names, or a depth-stencil state, use WebGpuRenderer::create_render_pipeline_full.

§Arguments

S: AsRef<str> - The WGSL shader source code.

§Returns

JsValue - The created render pipeline as a JavaScript value.

Source

pub fn create_render_pipeline_full<S>( &self, shader_code: S, vertex_buffer_layouts: &[VertexBufferLayout], vertex_entry: &str, fragment_entry: &str, depth_format: Option<&str>, ) -> JsValue
where S: AsRef<str>,

Creates a render pipeline with full control over vertex buffer layouts, shader entry-point names, and an optional depth-stencil state.

The vertex_buffer_layouts slice is forwarded as the vertex.buffers array of the pipeline descriptor; the i-th element matches setVertexBuffer(i, ...) calls. Pass &[] for the legacy “use @builtin(vertex_index)” path.

The depth_format argument, when Some, sets depthStencil.format on the descriptor; the rest of the depth state (depthWriteEnabled, depthCompare) is left at the WebGPU defaults (true / less). Callers that need different depth state can pass the descriptor’s name string and rely on the default depth-write/-compare behavior; for non-default compare/write, prefer using RenderConfig and a custom shader that performs the test explicitly.

§Arguments

shader_code - The WGSL shader source code.
vertex_buffer_layouts - The list of vertex buffer layouts for the pipeline’s vertex state.
vertex_entry - The vertex shader entry-point name (e.g. "vs_main").
fragment_entry - The fragment shader entry-point name (e.g. "fs_main").
depth_format - An optional depth-stencil format (e.g. "depth24plus-stencil8"). None omits the depthStencil field from the descriptor.

§Returns

JsValue - The created render pipeline as a JavaScript value.

Source

pub fn create_uniform_buffer(&self, data: &[f32]) -> JsValue

Creates a GPU uniform buffer and initializes it with the given floats.

The buffer is created with UNIFORM | COPY_DST usage so it can be bound in a bind group and refreshed per frame via WebGpuRenderer::update_uniform_buffer. The allocation size is rounded up to a multiple of 16 bytes because WebGPU requires uniform buffer bindings to be 16-byte aligned in size (a bare vec2<f32> uniform is only 8 bytes).

§Arguments

&[f32] - The initial uniform contents (e.g. [x, y] for a vec2<f32> uniform).

§Returns

JsValue - The created GpuBuffer.

Source

pub fn update_uniform_buffer(&self, buffer: &JsValue, data: &[f32])

Uploads float data into an existing uniform buffer via queue.writeBuffer.

§Arguments

&JsValue - The GpuBuffer previously created by WebGpuRenderer::create_uniform_buffer.
&[f32] - The new uniform contents.

Source

pub fn create_compute_pipeline<S>( &self, shader_code: S, entry_point: &str, ) -> JsValue
where S: AsRef<str>,

Creates a compute pipeline from a WGSL shader.

The shader must contain exactly one @compute fn <name>(...) entry point whose name matches entry_point. The pipeline uses auto-layout, so any @group(N) binding it declares is wired through getBindGroupLayout(N).

§Arguments

shader_code - The WGSL source code.
entry_point - The compute entry-point name (e.g. "cs_main").

§Returns

JsValue - The created GpuComputePipeline, or JsValue::UNDEFINED on failure.

Source

pub fn begin_compute_pass(&self, encoder: &JsValue) -> JsValue

Begins a compute pass on the given command encoder.

The returned JsValue is a GpuComputePassEncoder that supports setPipeline / setBindGroup / dispatchWorkgroups / dispatchWorkgroupsIndirect / end. The pass must be ended (via end()) before the command encoder is finished.

§Arguments

encoder - The GpuCommandEncoder to begin the pass on.

§Returns

JsValue - The active GpuComputePassEncoder.

Source

pub fn dispatch(&self, pass: &JsValue, x: u32, y: u32, z: u32)

Issues a dispatchWorkgroups(x, y, z) on a compute pass encoder.

x/y/z are the workgroup counts in each dimension. WebGPU limits each to 65535; callers that need larger grids must split them across multiple dispatches or encode a loop inside the shader.

§Arguments

pass - The active GpuComputePassEncoder.
x/y/z - Workgroup counts (each 1..=65535).

Source

pub fn push_error_scope(&self, filter: &str)

Pushes a GpuErrorScope with the given filter.

Pairs with WebGpuRenderer::pop_error_sync (or the JS device.popErrorScope() promise). All create_* / write_* operations issued while a scope is pushed accumulate their validation errors into the most recent scope; pop to consume them. The renderer does NOT auto-pop scopes; callers that push a scope must pop it. The renderer pushes a "validation" scope around create_bind_group; if you push your own scope at the same time, the inner one is consumed first.

filter is one of "validation", "out-of-memory", or "internal" (use the WEBGPU_ERROR_FILTER_* constants).

§Arguments

filter - The WebGPU error filter name.

Source

pub fn pop_error_sync(&self) -> Option<JsValue>

Pops the most recent error scope and asynchronously captures the result into the renderer’s shared pending_error slot.

WebGPU’s popErrorScope() returns a Promise<GPUError?>; because create_bind_group (and the rest of the renderer’s hot path) cannot be async, we cannot .await the promise in place. Instead this method:

Calls device.popErrorScope() to obtain the promise.
Spawns a local future that awaits the promise with wasm_bindgen_futures::JsFuture and writes the resolved value (a GPUError?, or undefined on success) into self.pending_error.
Returns None immediately. The actual error becomes visible via WebGpuRenderer::take_last_error on a later call (typically the next submit tick).

Callers that want a synchronous error report should push their own scope right before a create_* call, pop it right after, and then poll take_last_error() from the next frame’s render loop.

Returns None when the pop call itself failed (e.g. the device is lost).

§Arguments

self - the renderer; the call borrows immutably because the Rc<PendingErrorCell> slot lets the spawned future mutate the inner value without an exclusive borrow.

Source

pub fn take_last_error(&self) -> Option<JsValue>

Drains the renderer’s pending error-scope slot, returning the most recent popped error, if any.

Call this on the render loop (after submit, before the next create_* call) to surface validation errors that were captured by WebGpuRenderer::pop_error_sync. Returns None if no error was reported since the last take_last_error call (or since the renderer was constructed).

Source

pub fn begin_render_pass_to_texture( &mut self, encoder: &JsValue, color_view: &JsValue, clear_color: Option<(f64, f64, f64, f64)>, depth_view: Option<&JsValue>, depth_clear: Option<f32>, ) -> JsValue

Begins a render pass that targets a user-supplied offscreen texture view instead of the swap chain.

This is the “render-to-texture” entry point used for post-processing chains, mipmap generation, shadow maps, and any time the pass should not appear on screen.

The view must be a GpuTextureView (not the texture itself); the texture should have been created with RENDER_ATTACHMENT usage.

§Arguments

encoder - The GpuCommandEncoder to begin the pass on.
color_view - The offscreen color attachment view.
clear_color - The clear color (or None to "load").
depth_view - An optional depth-stencil view to bind as the depth attachment. Pass None to skip depth.
depth_clear - An optional depth clear value. Ignored when depth_view is None.

§Returns

JsValue - The active GpuRenderPassEncoder.

Source

pub fn copy_texture_to_buffer( &self, source: &JsValue, destination: &JsValue, bytes_per_row: u32, width: u32, height: u32, )

Copies a texture’s contents to a buffer for CPU readback.

The buffer must be created with COPY_DST | MAP_READ usage. The bytes are not available to the CPU until map_async is awaited and the mapped range is read.

§Arguments

source - The GpuTexture to copy from.
destination - The destination GpuBuffer.
bytes_per_row - The number of bytes per row of the texture (i.e. width * bytes_per_pixel, padded to 256 for non-power-of-two widths).
width/height - The texture subregion to copy.

Source

pub fn create_offline_render_target( &self, width: u32, height: u32, format: &str, ) -> (JsValue, JsValue)

Creates a standalone offscreen render target (texture + view) with the given size and format.

The returned tuple is (texture, view). The texture is allocated with RENDER_ATTACHMENT | TEXTURE_BINDING | COPY_SRC usage, which is the right baseline for “render into it, then sample from it in a later pass”. Callers that need STORAGE_BINDING or COPY_DST should use WebGpuRenderer::create_texture_2d directly.

§Arguments

width/height - The texture dimensions in pixels.
format - The WGSL texture format (e.g. "rgba8unorm").

§Returns

(JsValue, JsValue) - The offscreen texture and its default view. Either may be UNDEFINED on failure.

Source

pub fn create_texture_view(&self, texture: &JsValue) -> JsValue

Creates a default-view for the given texture.

Used by WebGpuRenderer::create_offline_render_target; the texture must have been created with the right usage flags.

Source

pub fn on_device_lost(&mut self, callback: Function)

Registers a closure to be invoked when the GPU device is lost.

The closure is called with a single JsValue argument (the GPUDeviceLostInfo object) when the device is lost. The renderer keeps a Closure alive for as long as the renderer itself is alive; calling dispose() releases it.

The device.lost promise resolves with a reason of "destroyed" when the user calls device.destroy(), or "undefined" for any other GPU-level loss. The closure is invoked from a JS microtask, so it should be cheap and non-blocking.

§Arguments

callback - The function to invoke. The renderer wraps it in a Closure and forgets the wrapper.

Source

pub fn create_buffer(&self, size: u64, usage: u32) -> JsValue

Low-level buffer allocator. Creates a GpuBuffer with the given size (in bytes) and usage bitmask (see WEBGPU_BUFFER_USAGE_*).

This is the foundation for the typed helpers (WebGpuRenderer::create_vertex_buffer, WebGpuRenderer::create_index_buffer, WebGpuRenderer::create_uniform_buffer); prefer those unless you need full control over the usage flags.

The returned value is JsValue::UNDEFINED (not an Err) when the allocation fails, to match the convention used by the other create_* helpers in this renderer. Callers should test for JsValue::UNDEFINED before use.

§Arguments

size - The buffer size in bytes. Must be > 0.
usage - The WebGPU buffer usage bitmask (e.g. WEBGPU_BUFFER_USAGE_VERTEX | WEBGPU_BUFFER_USAGE_COPY_DST).

§Returns

JsValue - The new GpuBuffer, or JsValue::UNDEFINED on allocation failure.

Source

pub fn create_vertex_buffer(&self, data: &[u8]) -> JsValue

Creates a vertex buffer pre-populated with the given bytes and uploads the data via queue.writeBuffer in the same call.

The buffer is allocated with VERTEX | COPY_DST usage. The data is uploaded at offset 0; for partial updates use WebGpuRenderer::write_buffer after creation.

§Arguments

data - The raw bytes that will be interpreted as a packed vertex array by the pipeline’s vertex buffer layout.

§Returns

JsValue - The new GpuBuffer, or JsValue::UNDEFINED on allocation failure.

Source

pub fn create_index_buffer(&self, data: &[u8]) -> JsValue

Creates an index buffer pre-populated with the given bytes.

The buffer is allocated with INDEX | COPY_DST usage. The format of the index data must be passed to the render pipeline layout (indexFormat: "uint16" for 16-bit indices, "uint32" for 32-bit).

§Arguments

data - The raw bytes of the index list (e.g. [0u8, 1u8, 2u8] for a single uint16 triangle, packed little-endian).

§Returns

JsValue - The new GpuBuffer, or JsValue::UNDEFINED on allocation failure.

Source

pub fn write_buffer(&self, buffer: &JsValue, offset: u64, data: &[u8])

Uploads raw bytes into an existing buffer at the given offset via queue.writeBuffer.

This is the byte-level counterpart to WebGpuRenderer::update_uniform_buffer. It is a no-op when data is empty; otherwise the GPU queue is invoked synchronously (the call is non-blocking on the JS side; the actual upload is ordered relative to the next submit).

§Arguments

buffer - The GpuBuffer to write into.
offset - The byte offset into the buffer where the upload starts.
data - The bytes to upload.

Source

pub fn create_depth_texture(&mut self) -> Option<JsValue>

Creates a depth-stencil texture matching the canvas’s swap chain physical dimensions and caches it on the renderer.

The format defaults to "depth24plus-stencil8", which is universally supported across browsers and matches what WebGpuRenderer::create_render_pipeline expects when the caller asks for depth testing. The texture is allocated with RENDER_ATTACHMENT usage so it can be bound as the depthStencilAttachment of a render pass.

If a depth texture already exists, this method is a no-op (returns None and keeps the existing allocation). Callers that need to force a re-allocation (e.g. after a resize) should call self.set_depth_texture(None) first.

§Returns

Option<JsValue> - The depth texture’s default GpuTextureView on success, None on allocation failure.

Source

pub fn create_texture_2d(&self, descriptor: &Texture2DDescriptor) -> JsValue

Creates a 2D texture from a Texture2DDescriptor.

The returned value is the GpuTexture itself; the caller is expected to create views via texture.createView() (or use the result as a RENDER_ATTACHMENT view in a render pass descriptor).

§Arguments

descriptor - The texture descriptor.

§Returns

JsValue - The new GpuTexture, or JsValue::UNDEFINED on allocation failure (including width == 0 or height == 0).

Source

pub fn create_sampler(&self, descriptor: &GpuSamplerDescriptor) -> JsValue

Creates a GpuSampler from a GpuSamplerDescriptor.

The returned value is a sampler suitable for binding via BindGroupEntry::Sampler (see Self::create_bind_group).

§Arguments

descriptor - The sampler descriptor.

§Returns

JsValue - The new GpuSampler, or JsValue::UNDEFINED on allocation failure.

Source

pub fn create_uniform_bind_group( &self, pipeline: &JsValue, buffer: &JsValue, ) -> JsValue

Creates a bind group for @group(0) of the given pipeline, binding the given uniform buffer at @binding(0).

The pipeline must have been created with layout: "auto" (the default for WebGpuRenderer::create_render_pipeline) and its WGSL shader must Creates a bind group for a single uniform buffer at @group(0) @binding(0).

Thin convenience wrapper around WebGpuRenderer::create_bind_group that takes the single uniform buffer directly. For pipelines with multiple bindings (uniform + texture + sampler, or several uniform slots) use the slice form with explicit BindGroupEntry values.

§Arguments

&JsValue - The render or compute pipeline that owns the bind group layout.
&JsValue - The uniform GpuBuffer to bind.

§Returns

JsValue - The created GpuBindGroup.

Source

pub fn create_bind_group( &self, pipeline: &JsValue, index: u32, entries: &[BindGroupEntry], ) -> JsValue

Creates a bind group from a list of BindGroupEntry values.

The index selects which auto-derived bind group layout to use (matches @group(N) in the shader); the entries slice describes every binding entry to populate. Each entry’s binding slot is forwarded as-is, so the caller is responsible for keeping them consistent with the shader’s @binding(...) declarations.

The device.createBindGroup call is wrapped in a pushErrorScope("validation") / popErrorScope() pair so creation failures surface as Err(WebGpuError::CreateBindGroup) instead of being silently lost. See Self::pop_error_sync for the full pop semantics.

§Arguments

pipeline - The render/compute pipeline whose bind group layout to use.
index - The bind group index (the @group(N) slot in the shader; typically 0).
entries - The list of bindings to attach. Pass an empty slice to allocate an empty bind group (rare, but legal).

§Returns

JsValue - The created GpuBindGroup. The value is JsValue::UNDEFINED when the device rejects the call; callers should compare against UNDEFINED before using it.

Source

pub fn render_frame( &mut self, pipeline: &JsValue, clear_color: (f64, f64, f64, f64), vertex_count: u32, )

Renders a complete frame with a pipeline and animated clear color.

This is a convenience method that creates a command encoder, begins a render pass with the given clear color, sets the pipeline, draws the specified number of vertices, ends the pass, finishes the encoder, and submits the command buffer.

§Arguments

&JsValue - The render pipeline to use.
(f64, f64, f64, f64) - The clear color as (r, g, b, a) in 0.0–1.0 range.
u32 - The number of vertices to draw.

Source

pub fn render_frame_with_bind_group( &mut self, pipeline: &JsValue, bind_group: &JsValue, clear_color: (f64, f64, f64, f64), vertex_count: u32, )

Renders a complete frame like WebGpuRenderer::render_frame, but additionally binds a uniform bind group at @group(0) before drawing.

Used by shaders that read per-frame data (pointer position, rotation angles, …) from a uniform buffer. The bind group should be created once via WebGpuRenderer::create_uniform_bind_group and its buffer refreshed each frame via WebGpuRenderer::update_uniform_buffer.

§Arguments

&JsValue - The render pipeline to use.
&JsValue - The bind group for @group(0).
(f64, f64, f64, f64) - The clear color as (r, g, b, a) in 0.0–1.0 range.
u32 - The number of vertices to draw.

Source

pub fn dispose(&self)

Releases all GPU resources held by this renderer.

The teardown order matters per the WebGPU spec:

GpuCanvasContext.unconfigure() - releases the swap chain so the DOM canvas can be GCed.
GpuDevice.destroy() - releases all child resources (buffers, textures, pipelines) and the device itself.

Callers should run this from a use_cleanup callback whenever the host component is being torn down (e.g. on a match arm switch). Without it the previous GPU device lingers until GC, and a fresh init() may either reuse the dead device (silent black canvas) or fail to acquire a new one until the old device is collected.

Reflect::get failures and JS exceptions are swallowed - this is a best-effort cleanup path, and the engine must not panic during teardown.

Source

pub fn set_viewport( &self, pass: &JsValue, x: f32, y: f32, width: f32, height: f32, min_depth: f32, max_depth: f32, )

Sets the viewport for all subsequent draw calls on the given render pass.

The viewport maps NDC [-1, 1] to the given pixel rectangle. min_depth and max_depth (both in [0, 1]) clamp the depth range; the defaults of 0.0 and 1.0 cover the whole depth buffer. This call must be issued between beginRenderPass() and pass.end().

§Arguments

&JsValue - The active GpuRenderPassEncoder.
f32 - X coordinate of the viewport’s top-left in pixels.
f32 - Y coordinate of the viewport’s top-left in pixels.
f32 - Viewport width in pixels.
f32 - Viewport height in pixels.
f32 - Minimum depth, clamped to [0, 1]. Pass 0.0 to disable.
f32 - Maximum depth, clamped to [0, 1]. Pass 1.0 to disable.

Source

pub fn set_scissor_rect( &self, pass: &JsValue, x: u32, y: u32, width: u32, height: u32, )

Sets the scissor rectangle for all subsequent draw calls on the given render pass.

Fragments outside the rectangle are discarded. The scissor is applied after the viewport, so coordinates are in the same pixel space as WebGpuRenderer::set_viewport. A scissor that extends outside the render target is clamped to the target bounds by the GPU.

§Arguments

&JsValue - The active GpuRenderPassEncoder.
u32 - X coordinate of the scissor origin in pixels.
u32 - Y coordinate of the scissor origin in pixels.
u32 - Scissor width in pixels.
u32 - Scissor height in pixels.

Source

pub fn set_blend_constant(&self, pass: &JsValue, r: f32, g: f32, b: f32, a: f32)

Sets the blend constant used by "constant" / "one-minus-constant" blend factors.

Affects all subsequent draw calls on the given render pass. The constant is a linear-space RGBA color in [0, 1] per component.

§Arguments

&JsValue - The active GpuRenderPassEncoder.
f32 - Red component.
f32 - Green component.
f32 - Blue component.
f32 - Alpha component.

Source

pub fn set_stencil_reference(&self, pass: &JsValue, reference: u32)

Sets the stencil reference value used by stencil tests.

The reference is the value the GPU compares against when the shader pipeline was built with a stencil state using "always", "less", "equal", etc. compare ops. This call must be issued between beginRenderPass() and pass.end().

§Arguments

&JsValue - The active GpuRenderPassEncoder.
u32 - The stencil reference value (8-bit, [0, 255]).

Source

pub fn set_bind_group_with_dynamic_offsets( &self, pass: &JsValue, index: u32, group: &JsValue, dynamic_offsets: &[u32], )

Sets a bind group on a render pass with dynamic offsets.

Use this overload of set_bind_group when the bind-group layout was built with hasDynamicOffset: true for one or more buffer bindings. Each value in dynamic_offsets is added to the corresponding @group(N) @binding(M) buffer’s base offset before the draw call. For non-dynamic bind groups, prefer the simpler set_bind_group (3-arg) overload exposed via the pub(crate) API.

§Arguments

&JsValue - The active GpuRenderPassEncoder.
u32 - Bind-group slot index.
&JsValue - The GpuBindGroup to bind.
&[u32] - Dynamic offsets, one per dynamic-offset binding.

Source

pub fn set_bind_group_compute_with_dynamic_offsets( &self, pass: &JsValue, index: u32, group: &JsValue, dynamic_offsets: &[u32], )

Sets a bind group on a compute pass with optional dynamic offsets.

Same semantics as WebGpuRenderer::set_bind_group_with_dynamic_offsets but on a GpuComputePassEncoder. The setBindGroup method name is the same on both encoder types; this method wraps it for the compute pass to give callers a typed entry point.

§Arguments

&JsValue - The active GpuComputePassEncoder.
u32 - Bind-group slot index.
&JsValue - The GpuBindGroup to bind.
&[u32] - Dynamic offsets for dynamic-offset bindings.

Source

pub fn create_view( &self, texture: &JsValue, descriptor: Option<&TextureViewDescriptor>, ) -> JsValue

Creates a GpuTextureView for the given texture with full descriptor control.

Pass None for a default view (full 2D, all mips, all aspects) — this is the cheap view that is implicitly created by bind-group creation. Pass Some(&descriptor) to sub-select mip levels, array slices, or the depth-only aspect of a depth-stencil texture.

§Arguments

&JsValue - The GpuTexture to view.
Option<&TextureViewDescriptor> - Optional descriptor.

§Returns

JsValue - The GpuTextureView. Returns JsValue::UNDEFINED if the call fails (e.g. invalid mip range); check for undefined before using the result.

Source

pub fn generate_mipmaps(&self, texture: &JsValue)

Generates the full mipmap chain for the given texture.

Equivalent to repeatedly calling copyTextureToTexture from level i to level i+1 with the appropriate mip dimensions, but in one GPU command. The texture must have been created with RENDER_ATTACHMENT | TEXTURE_BINDING | COPY_DST | COPY_SRC usage and mipLevelCount > 1. Requires the mipmap WebGPU feature, or a GPU that supports it unconditionally (most desktop GPUs do).

§Arguments

&JsValue - The GpuTexture whose mips will be generated.

Source

pub fn write_texture(&self, descriptor: &TextureWriteDescriptor)

Uploads CPU-side pixel data directly to a texture via queue.writeTexture.

Use this instead of create_buffer + write_buffer + copyBufferToTexture for one-shot uploads (ImGui font atlases, sprite sheets, procedural noise). The queue is acquired internally via the cached device.queue handle, so this is the preferred path for textures that are written once and sampled many times.

bytes_per_row must be a multiple of 256. The data layout must match the texture’s format; the engine does not perform swizzling.

§Arguments

&TextureWriteDescriptor - The write descriptor.

Source

pub fn create_shader_module_with_label( &self, wgsl_source: &str, label: &str, ) -> JsValue

Creates a GpuShaderModule from a WGSL source string with a debug label.

Equivalent to the pub(crate) fn create_shader_module overload but attaches a label to the module so it shows up under that name in browser devtools (e.g. Chrome’s chrome://gpu-internals and the WebGPU Inspector panel). The label has no runtime effect; it is purely a developer-experience aid when many shader modules coexist.

§Arguments

&str - WGSL source.
&str - Debug label shown in browser devtools.

§Returns

JsValue - The GpuShaderModule, or JsValue::UNDEFINED if the call fails.

Source

pub async fn read_buffer( &self, buffer: &JsValue, offset: u64, size: u64, ) -> Option<Vec<u8>>

Reads back the contents of a buffer via mapAsync + getMappedRange + unmap.

This is an async fn, NOT a synchronous wrapper. It must be await-ed by the caller. Use it from inside another wasm_bindgen_futures future (e.g. a frame loop) — do not call it from synchronous code, since the awaiter must be driven by the executor. The buffer must have been created with MAP_READ usage, and the read must be preceded by a GPU submission that finished writing to the buffer (i.e. queue.submit([encoder.finish()]) followed by device.lost / a fence).