API referencestd/gpu

std/gpu

Public declarations, types, methods, and source contracts for std/gpu.

On this page

Library guide · API index and notation

This page is generated from the bundled library in this checkout. Signatures and adjacent source comments are reproduced below; the linked guide explains usage, storage, failures, and platform support.

import "std/gpu"

Names used in signatures

Unqualified names denote this package’s types (including other source files in the same package), language built-ins, or generic parameters such as T. Qualified names use the import aliases below. These aliases belong to the library source; import a dependency yourself to use its alias in your program.

Alias Package Source file
ascii core/ascii gpu.dodo
hal std/gpu/hal gpu.dodo
handle std/window/handle gpu.dodo
mem core/mem gpu.dodo
native_hal std/gpu/hal/native gpu.dodo
opengl_hal std/gpu/hal/opengl gpu.dodo
ptr core/ptr gpu.dodo
vulkan_hal std/gpu/hal/vulkan gpu.dodo

Error

Type alias · Source

pub type Error = hal.Error

Api

Type alias · Source

pub type Api = hal.Api

Limits

Type alias · Source

pub type Limits = hal.Limits

TextureDescriptor

Type alias · Source

pub type TextureDescriptor = hal.TextureDescriptor

SamplerDescriptor

Type alias · Source

pub type SamplerDescriptor = hal.SamplerDescriptor

Region

Type alias · Source

pub type Region = hal.Region

ShaderSource

Type alias · Source

pub type ShaderSource = hal.ShaderSource

BindingLayout

Type alias · Source

pub type BindingLayout = hal.BindingLayout

VertexAttribute

Type alias · Source

pub type VertexAttribute = hal.VertexAttribute

VertexBufferLayout

Type alias · Source

pub type VertexBufferLayout = hal.VertexBufferLayout

ComputePipelineDescriptor

Type alias · Source

pub type ComputePipelineDescriptor = hal.ComputePipelineDescriptor

RenderPipelineDescriptor

Type alias · Source

pub type RenderPipelineDescriptor = hal.RenderPipelineDescriptor

Blend

Type alias · Source

pub type Blend = hal.Blend

ColorTarget

Type alias · Source

pub type ColorTarget = hal.ColorTarget

wgsl

Function · Source

A shader written once in WGSL, translated when the program is compiled into SPIR-V for Vulkan, Metal Shading Language for Metal and GLSL 4.50 for OpenGL. The argument is one or more string literals, joined with line breaks; a mistake in the shader is a compile error pointing into them. The result borrows static storage, so a function declared -> gpu.ShaderSource from(static) may return it.

Bindings follow std/gpu’s slots: slot N is @group(0) @binding(N) for buffers, sampled textures and storage textures, and the sampler read with the sampled texture in slot N is @group(1) @binding(N). Vertex attribute location N is @location(N). Entry points keep their WGSL names on every backend, so pass those names to the pipeline descriptors; a name Metal reserves, such as main, is rejected. Clip space and depth are as WGSL defines them, as everywhere in std/gpu. Immediate data (push constants) is not available.

@compiler(wgsl)
pub fn wgsl(source: &str) -> ShaderSource

error_name

Function · Source

pub fn error_name(error: Error) -> &str from(static)

api_name

Function · Source

pub fn api_name(api: &Api) -> &str from(static)

BUFFER_COPY_SRC

Constant · Source

Buffer usages, combined with |. A buffer can only be used in the ways it was created for. The source of copies, and readable with read_buffer.

pub const BUFFER_COPY_SRC: u32 = 1

BUFFER_COPY_DST

Constant · Source

The destination of copies, and writable with write_buffer.

pub const BUFFER_COPY_DST: u32 = 2

BUFFER_INDEX

Constant · Source

pub const BUFFER_INDEX: u32 = 4

BUFFER_VERTEX

Constant · Source

pub const BUFFER_VERTEX: u32 = 8

BUFFER_UNIFORM

Constant · Source

pub const BUFFER_UNIFORM: u32 = 16

BUFFER_STORAGE

Constant · Source

pub const BUFFER_STORAGE: u32 = 32

TEXTURE_COPY_SRC

Constant · Source

Texture usages, combined with |. The source of copies, and readable with read_texture.

pub const TEXTURE_COPY_SRC: u32 = 1

TEXTURE_COPY_DST

Constant · Source

The destination of copies, and writable with write_texture.

pub const TEXTURE_COPY_DST: u32 = 2

TEXTURE_SAMPLED

Constant · Source

pub const TEXTURE_SAMPLED: u32 = 4

TEXTURE_STORAGE

Constant · Source

pub const TEXTURE_STORAGE: u32 = 8

TEXTURE_RENDER

Constant · Source

A render pass attachment.

pub const TEXTURE_RENDER: u32 = 16

FORMAT_NONE

Constant · Source

Texture formats.

pub const FORMAT_NONE: u32 = 0

FORMAT_R8_UNORM

Constant · Source

pub const FORMAT_R8_UNORM: u32 = 1

FORMAT_RG8_UNORM

Constant · Source

pub const FORMAT_RG8_UNORM: u32 = 2

FORMAT_RGBA8_UNORM

Constant · Source

pub const FORMAT_RGBA8_UNORM: u32 = 3

FORMAT_RGBA8_UNORM_SRGB

Constant · Source

pub const FORMAT_RGBA8_UNORM_SRGB: u32 = 4

FORMAT_BGRA8_UNORM

Constant · Source

pub const FORMAT_BGRA8_UNORM: u32 = 5

FORMAT_BGRA8_UNORM_SRGB

Constant · Source

pub const FORMAT_BGRA8_UNORM_SRGB: u32 = 6

FORMAT_R16_FLOAT

Constant · Source

pub const FORMAT_R16_FLOAT: u32 = 7

FORMAT_RG16_FLOAT

Constant · Source

pub const FORMAT_RG16_FLOAT: u32 = 8

FORMAT_RGBA16_FLOAT

Constant · Source

pub const FORMAT_RGBA16_FLOAT: u32 = 9

FORMAT_R32_FLOAT

Constant · Source

pub const FORMAT_R32_FLOAT: u32 = 10

FORMAT_RG32_FLOAT

Constant · Source

pub const FORMAT_RG32_FLOAT: u32 = 11

FORMAT_RGBA32_FLOAT

Constant · Source

pub const FORMAT_RGBA32_FLOAT: u32 = 12

FORMAT_R32_UINT

Constant · Source

pub const FORMAT_R32_UINT: u32 = 13

FORMAT_R32_SINT

Constant · Source

pub const FORMAT_R32_SINT: u32 = 14

FORMAT_RGBA32_UINT

Constant · Source

pub const FORMAT_RGBA32_UINT: u32 = 15

FORMAT_DEPTH32_FLOAT

Constant · Source

pub const FORMAT_DEPTH32_FLOAT: u32 = 16

texel_size

Function · Source

The size of one texel of format in bytes, or 0 for an unknown format.

pub fn texel_size(format: u32) -> u32

mip_level_count

Function · Source

How many mipmap levels a width by height texture has at most, down to one texel; TextureDescriptor.mipmapped uses it.

pub fn mip_level_count(width: u32, height: u32) -> u32

level_size

Function · Source

The width (or height) of mipmap level of a texture size texels wide.

pub fn level_size(size: u32, level: u32) -> u32

MULTISAMPLE_COUNT

Constant · Source

Samples per pixel of a multisampled texture: 4 on every backend.

pub const MULTISAMPLE_COUNT: u32 = 4

STAGE_VERTEX

Constant · Source

Shader stages that use a binding, combined with |.

pub const STAGE_VERTEX: u32 = 1

STAGE_FRAGMENT

Constant · Source

pub const STAGE_FRAGMENT: u32 = 2

STAGE_COMPUTE

Constant · Source

pub const STAGE_COMPUTE: u32 = 4

VERTEX_FLOAT32

Constant · Source

Vertex attribute formats.

pub const VERTEX_FLOAT32: u32 = 1

VERTEX_FLOAT32X2

Constant · Source

pub const VERTEX_FLOAT32X2: u32 = 2

VERTEX_FLOAT32X3

Constant · Source

pub const VERTEX_FLOAT32X3: u32 = 3

VERTEX_FLOAT32X4

Constant · Source

pub const VERTEX_FLOAT32X4: u32 = 4

VERTEX_UINT32

Constant · Source

pub const VERTEX_UINT32: u32 = 5

VERTEX_UINT32X2

Constant · Source

pub const VERTEX_UINT32X2: u32 = 6

VERTEX_UINT32X3

Constant · Source

pub const VERTEX_UINT32X3: u32 = 7

VERTEX_UINT32X4

Constant · Source

pub const VERTEX_UINT32X4: u32 = 8

VERTEX_SINT32

Constant · Source

pub const VERTEX_SINT32: u32 = 9

VERTEX_SINT32X2

Constant · Source

pub const VERTEX_SINT32X2: u32 = 10

VERTEX_SINT32X3

Constant · Source

pub const VERTEX_SINT32X3: u32 = 11

VERTEX_SINT32X4

Constant · Source

pub const VERTEX_SINT32X4: u32 = 12

VERTEX_UNORM8X4

Constant · Source

pub const VERTEX_UNORM8X4: u32 = 13

TOPOLOGY_TRIANGLE_LIST

Constant · Source

pub const TOPOLOGY_TRIANGLE_LIST: u32 = 0

TOPOLOGY_TRIANGLE_STRIP

Constant · Source

pub const TOPOLOGY_TRIANGLE_STRIP: u32 = 1

TOPOLOGY_LINE_LIST

Constant · Source

pub const TOPOLOGY_LINE_LIST: u32 = 2

TOPOLOGY_LINE_STRIP

Constant · Source

pub const TOPOLOGY_LINE_STRIP: u32 = 3

TOPOLOGY_POINT_LIST

Constant · Source

pub const TOPOLOGY_POINT_LIST: u32 = 4

CULL_NONE

Constant · Source

pub const CULL_NONE: u32 = 0

CULL_FRONT

Constant · Source

pub const CULL_FRONT: u32 = 1

CULL_BACK

Constant · Source

pub const CULL_BACK: u32 = 2

FRONT_CCW

Constant · Source

The winding of front faces, seen with y pointing up in clip space.

pub const FRONT_CCW: u32 = 0

FRONT_CW

Constant · Source

pub const FRONT_CW: u32 = 1

INDEX_UINT16

Constant · Source

pub const INDEX_UINT16: u32 = 1

INDEX_UINT32

Constant · Source

pub const INDEX_UINT32: u32 = 2

BLEND_REPLACE

Constant · Source

Blending presets for RenderPipelineDescriptor.blend: none, straight alpha, premultiplied alpha, additive.

pub const BLEND_REPLACE: u32 = 0

BLEND_ALPHA

Constant · Source

pub const BLEND_ALPHA: u32 = 1

BLEND_PREMULTIPLIED

Constant · Source

pub const BLEND_PREMULTIPLIED: u32 = 2

BLEND_ADDITIVE

Constant · Source

pub const BLEND_ADDITIVE: u32 = 3

BLEND_FACTOR_ZERO

Constant · Source

Blend factors for Blend: what the shader’s output (source) and the attachment’s value (destination) are multiplied by. CONSTANT reads the pass’s blend constant.

pub const BLEND_FACTOR_ZERO: u32 = 0

BLEND_FACTOR_ONE

Constant · Source

pub const BLEND_FACTOR_ONE: u32 = 1

BLEND_FACTOR_SRC

Constant · Source

pub const BLEND_FACTOR_SRC: u32 = 2

BLEND_FACTOR_ONE_MINUS_SRC

Constant · Source

pub const BLEND_FACTOR_ONE_MINUS_SRC: u32 = 3

BLEND_FACTOR_SRC_ALPHA

Constant · Source

pub const BLEND_FACTOR_SRC_ALPHA: u32 = 4

BLEND_FACTOR_ONE_MINUS_SRC_ALPHA

Constant · Source

pub const BLEND_FACTOR_ONE_MINUS_SRC_ALPHA: u32 = 5

BLEND_FACTOR_DST

Constant · Source

pub const BLEND_FACTOR_DST: u32 = 6

BLEND_FACTOR_ONE_MINUS_DST

Constant · Source

pub const BLEND_FACTOR_ONE_MINUS_DST: u32 = 7

BLEND_FACTOR_DST_ALPHA

Constant · Source

pub const BLEND_FACTOR_DST_ALPHA: u32 = 8

BLEND_FACTOR_ONE_MINUS_DST_ALPHA

Constant · Source

pub const BLEND_FACTOR_ONE_MINUS_DST_ALPHA: u32 = 9

BLEND_FACTOR_SRC_ALPHA_SATURATED

Constant · Source

pub const BLEND_FACTOR_SRC_ALPHA_SATURATED: u32 = 10

BLEND_FACTOR_CONSTANT

Constant · Source

pub const BLEND_FACTOR_CONSTANT: u32 = 11

BLEND_FACTOR_ONE_MINUS_CONSTANT

Constant · Source

pub const BLEND_FACTOR_ONE_MINUS_CONSTANT: u32 = 12

BLEND_OP_ADD

Constant · Source

Blend operations. MIN and MAX ignore the factors.

pub const BLEND_OP_ADD: u32 = 0

BLEND_OP_SUBTRACT

Constant · Source

pub const BLEND_OP_SUBTRACT: u32 = 1

BLEND_OP_REVERSE_SUBTRACT

Constant · Source

pub const BLEND_OP_REVERSE_SUBTRACT: u32 = 2

BLEND_OP_MIN

Constant · Source

pub const BLEND_OP_MIN: u32 = 3

BLEND_OP_MAX

Constant · Source

pub const BLEND_OP_MAX: u32 = 4

COLOR_WRITE_RED

Constant · Source

The channels a color target writes, combined with |.

pub const COLOR_WRITE_RED: u32 = 1

COLOR_WRITE_GREEN

Constant · Source

pub const COLOR_WRITE_GREEN: u32 = 2

COLOR_WRITE_BLUE

Constant · Source

pub const COLOR_WRITE_BLUE: u32 = 4

COLOR_WRITE_ALPHA

Constant · Source

pub const COLOR_WRITE_ALPHA: u32 = 8

COLOR_WRITE_ALL

Constant · Source

pub const COLOR_WRITE_ALL: u32 = 15

COMPARE_NONE

Constant · Source

Depth comparisons, for depth tests and comparison samplers. COMPARE_NONE marks a sampler that does not compare.

pub const COMPARE_NONE: u32 = 0

COMPARE_NEVER

Constant · Source

pub const COMPARE_NEVER: u32 = 1

COMPARE_LESS

Constant · Source

pub const COMPARE_LESS: u32 = 2

COMPARE_EQUAL

Constant · Source

pub const COMPARE_EQUAL: u32 = 3

COMPARE_LESS_EQUAL

Constant · Source

pub const COMPARE_LESS_EQUAL: u32 = 4

COMPARE_GREATER

Constant · Source

pub const COMPARE_GREATER: u32 = 5

COMPARE_NOT_EQUAL

Constant · Source

pub const COMPARE_NOT_EQUAL: u32 = 6

COMPARE_GREATER_EQUAL

Constant · Source

pub const COMPARE_GREATER_EQUAL: u32 = 7

COMPARE_ALWAYS

Constant · Source

pub const COMPARE_ALWAYS: u32 = 8

FILTER_NEAREST

Constant · Source

pub const FILTER_NEAREST: u32 = 0

FILTER_LINEAR

Constant · Source

pub const FILTER_LINEAR: u32 = 1

ADDRESS_CLAMP

Constant · Source

pub const ADDRESS_CLAMP: u32 = 0

ADDRESS_REPEAT

Constant · Source

pub const ADDRESS_REPEAT: u32 = 1

ADDRESS_MIRROR

Constant · Source

pub const ADDRESS_MIRROR: u32 = 2

ADDRESS_BORDER

Constant · Source

pub const ADDRESS_BORDER: u32 = 3

BORDER_TRANSPARENT_BLACK

Constant · Source

The color a sampler reads outside the texture with ADDRESS_BORDER.

pub const BORDER_TRANSPARENT_BLACK: u32 = 0

BORDER_OPAQUE_BLACK

Constant · Source

pub const BORDER_OPAQUE_BLACK: u32 = 1

BORDER_OPAQUE_WHITE

Constant · Source

pub const BORDER_OPAQUE_WHITE: u32 = 2

LOAD_CLEAR

Constant · Source

pub const LOAD_CLEAR: u32 = 0

LOAD_KEEP

Constant · Source

pub const LOAD_KEEP: u32 = 1

MAX_SLOTS

Constant · Source

Binding slots per pipeline, numbered from 0.

pub const MAX_SLOTS: u32 = 16

MAX_VERTEX_BUFFERS

Constant · Source

pub const MAX_VERTEX_BUFFERS: u32 = 8

MAX_VERTEX_ATTRIBUTES

Constant · Source

pub const MAX_VERTEX_ATTRIBUTES: u32 = 16

MAX_COLOR_ATTACHMENTS

Constant · Source

Color attachments of a render pass at most; limits().max_color_attachments says how many the device takes (at least 4).

pub const MAX_COLOR_ATTACHMENTS: u32 = 8

BINDING_ALIGNMENT

Constant · Source

Buffer offsets bound to a slot are multiples of this.

pub const BINDING_ALIGNMENT: u64 = 256

Preference

Enum · Source

Which backend Device.open tries.

pub enum Preference {
    // The operating system's own API (Metal on macOS), then Vulkan, then
    // OpenGL.
    Auto,
    Vulkan,
    Metal,
    OpenGl
}

Options

Struct · Source

pub struct Options {
    pub backend: Preference
    // Turn on the API's validation where it exists: the Khronos validation
    // layer for Vulkan when installed, a debug context for OpenGL.
    pub debug: bool
}

Options.default

Function · Source

pub fn default() -> Options

Options.with_backend

Function · Source

pub fn with_backend(backend: Preference) -> Options

Device

Struct · Source

A GPU and the queue its work runs on.

pub struct Device {
    // Private implementation fields omitted.
}

Device.open

Function · Source

Open a device. With Preference.Auto, tries the operating system’s own API, then Vulkan, then OpenGL. Fails with NoBackend when no backend could be used and Unsupported when the requested one lacks what std/gpu needs, such as Vulkan before 1.2 or OpenGL before 4.5.

pub fn open(options: Options) -> Device!Error

Device.open_for_window

Function · Source

Open a device that can present to a window, for a Surface. OpenGL devices draw with the window’s own context, so only this window can have a Surface on them; Vulkan prefers a GPU that can present to it. Fails like open().

pub fn open_for_window(native: &handle.NativeHandle, options: Options) -> Device!Error

Device.api

Function · Source

The API this device uses.

pub fn api(&self) -> Api

Device.name

Function · Source

The GPU’s name as the driver reports it, such as “Apple M2” or “llvmpipe (LLVM 19.1.7, 256 bits)”.

pub fn name(&self) -> &str from(self)

Device.limits

Function · Source

pub fn limits(&self) -> Limits

Device.create_buffer

Function · Source

A buffer of size bytes, initially zero, usable in the ways usage combines (BUFFER_*). Fails with InvalidInput for a zero size, one above limits().max_buffer_size or an empty or unknown usage.

pub fn create_buffer(&self, size: u64, usage: u32) -> Buffer!Error from(self)

Device.create_buffer_with_data

Function · Source

A buffer holding a copy of data, which must not be empty. The usage needs no BUFFER_COPY_DST for this first write.

pub fn create_buffer_with_data(&self, data: &[u8], usage: u32) -> Buffer!Error from(self)

Device.write_buffer

Function · Source

Copy data into buffer at offset. The write happens after every submission made before it and before every later one, as if it were a command of its own. Needs BUFFER_COPY_DST; fails with InvalidInput when the range does not fit.

pub fn write_buffer(&self, buffer: &Buffer, offset: u64, data: &[u8]) -> void!Error

Device.read_buffer

Function · Source

Copy bytes of buffer from offset into out, after waiting for every submission made so far that uses it. Needs BUFFER_COPY_SRC; fails with InvalidInput when the range does not fit.

pub fn read_buffer(&self, buffer: &Buffer, offset: u64, out: &mut[u8]) -> void!Error

Device.start_read_buffer

Function · Source

Start copying size bytes of buffer from offset back to the CPU without waiting for the GPU: collect them with Readback.read() once ready() says so (or earlier, which waits). The copy is ordered like a submission made now. Needs BUFFER_COPY_SRC; fails with InvalidInput when the range does not fit or is empty.

pub fn start_read_buffer(&self, buffer: &Buffer, offset: u64, size: u64) -> Readback!Error from(self)

Device.create_texture

Function · Source

A two-dimensional texture. Fails with InvalidInput for a zero size, one above limits().max_texture_size, an unknown format, a usage the format does not allow, or a bad mip level or sample count: depth formats can only be rendered to, sampled and copied from; TEXTURE_STORAGE needs one of the formats every backend can store to (rgba8unorm, rgba16float, r32float, rg32float, rgba32float, r32uint, r32sint, rgba32uint); mip_levels runs from 1 to mip_level_count(); and a multisampled texture (samples MULTISAMPLE_COUNT rather than 1) has one level, a format other than an integer one, and usage TEXTURE_RENDER alone. Fails with Unsupported when the GPU lacks the combination.

pub fn create_texture(&self, descriptor: TextureDescriptor) -> Texture!Error from(self)

Device.write_texture

Function · Source

Copy texels from data into region of texture, rows bytes_per_row apart, top row first. Ordered like write_buffer. Needs TEXTURE_COPY_DST; fails with InvalidInput when the region is outside the texture, a row is shorter than the region or not a multiple of the texel size, or data is too short.

pub fn write_texture(&self, texture: &Texture, region: Region, data: &[u8], bytes_per_row: u32) -> void!Error

Device.read_texture

Function · Source

Copy texels of region into out, rows bytes_per_row apart, top row first, after waiting for every submission made so far. Needs TEXTURE_COPY_SRC; fails like write_texture.

pub fn read_texture(&self, texture: &Texture, region: Region, out: &mut[u8], bytes_per_row: u32) -> void!Error

Device.start_read_texture

Function · Source

Start copying texels of region back to the CPU, rows bytes_per_row apart, without waiting for the GPU, as start_read_buffer does. Needs TEXTURE_COPY_SRC; fails with InvalidInput like read_texture, and for an empty region.

pub fn start_read_texture(&self, texture: &Texture, region: Region, bytes_per_row: u32) -> Readback!Error from(self)

Device.create_sampler

Function · Source

A sampler. Fails with InvalidInput for an unknown filter, address mode, border color or comparison, a level range that is negative or runs backwards, or max_anisotropy outside 1 to 16 or above 1 with a nearest filter. A sampler with a comparison only reads depth textures in BindingLayout.comparison_texture slots, and only those.

pub fn create_sampler(&self, descriptor: SamplerDescriptor) -> Sampler!Error from(self)

Device.create_compute_pipeline

Function · Source

A compute pipeline. Fails with MissingShader when the source has no code for this device’s API, InvalidShader when it does not compile or lacks the entry point, and InvalidInput for a bad binding layout or a workgroup size outside the limits.

pub fn create_compute_pipeline(&self, descriptor: ComputePipelineDescriptor) -> ComputePipeline!Error from(self)

Device.create_render_pipeline

Function · Source

A render pipeline. Fails like create_compute_pipeline, and with InvalidInput for vertex layouts beyond MAX_VERTEX_BUFFERS or MAX_VERTEX_ATTRIBUTES, a repeated location, an attribute outside its stride; color targets given both ways, more than limits().max_color_attachments of them, with a format that cannot be rendered to (or blended, with blending on) or an unknown blend factor, operation or write mask; color targets without a fragment stage, or neither color targets nor depth; a depth format that is not one; samples other than 1 and MULTISAMPLE_COUNT, multisampled integer targets or alpha_to_coverage without multisampling; or a depth bias that is not finite or is set for lines or points. Fails with Unsupported when the GPU cannot blend targets differently, or clamp depth bias, and the pipeline asks for it.

pub fn create_render_pipeline(&self, descriptor: RenderPipelineDescriptor) -> RenderPipeline!Error from(self)

Device.encoder

Function · Source

Start recording commands.

pub fn encoder(&self) -> CommandEncoder!Error from(self)

Device.wait

Function · Source

Wait until the GPU has finished everything submitted so far, including writes not yet followed by a submission.

pub fn wait(&self) -> void!Error

Device.poll

Function · Source

Destroy dropped objects the GPU has finished with, and start staged writes not yet followed by a submission. submit() and wait() do this too; call it in programs that drop objects and then submit nothing for a while.

pub fn poll(&self)

Buffer

Struct · Source

GPU memory. Dropping it frees the memory once the GPU has finished every submission that may use it.

pub struct Buffer {
    // Private implementation fields omitted.
}

Buffer.size

Function · Source

pub fn size(&self) -> u64

Buffer.usage

Function · Source

pub fn usage(&self) -> u32

Readback

Struct · Source

Bytes on their way back from the GPU, from Device.start_read_buffer or start_read_texture. Dropping it discards them.

pub struct Readback {
    // Private implementation fields omitted.
}

Readback.size

Function · Source

pub fn size(&self) -> u64

Readback.ready

Function · Source

Whether the GPU has made the copy, so that read() returns at once.

pub fn ready(&self) -> bool

Readback.read

Function · Source

Copy the bytes into out, which holds size() bytes, after waiting for the GPU to copy them if it has not yet. For a texture, rows are the bytes_per_row apart that the read started with.

pub fn read(&self, out: &mut[u8]) -> void!Error

Texture

Struct · Source

A two-dimensional image on the GPU, with one or more mipmap levels.

pub struct Texture {
    // Private implementation fields omitted.
}

Texture.width

Function · Source

pub fn width(&self) -> u32

Texture.height

Function · Source

pub fn height(&self) -> u32

Texture.format

Function · Source

pub fn format(&self) -> u32

Texture.usage

Function · Source

pub fn usage(&self) -> u32

Texture.mip_levels

Function · Source

pub fn mip_levels(&self) -> u32

Texture.samples

Function · Source

pub fn samples(&self) -> u32

Texture.bytes_per_row

Function · Source

The bytes one row of the first level takes, tightly packed.

pub fn bytes_per_row(&self) -> u32

Texture.level_bytes_per_row

Function · Source

The bytes one row of mipmap level takes, tightly packed.

pub fn level_bytes_per_row(&self, level: u32) -> u32

Texture.region

Function · Source

The region covering the whole first level.

pub fn region(&self) -> Region

Texture.level_region

Function · Source

The region covering all of mipmap level.

pub fn level_region(&self, level: u32) -> Region

Sampler

Struct · Source

pub struct Sampler {
    // Private implementation fields omitted.
}

Sampler.compares

Function · Source

Whether the sampler compares, for BindingLayout.comparison_texture.

pub fn compares(&self) -> bool

ComputePipeline

Struct · Source

pub struct ComputePipeline {
    // Private implementation fields omitted.
}

RenderPipeline

Struct · Source

pub struct RenderPipeline {
    // Private implementation fields omitted.
}

ColorAttachment

Struct · Source

A color attachment of a render pass. LOAD_CLEAR fills it with the clear color first; LOAD_KEEP draws over what it holds. A multisampled attachment can resolve into a texture of the same size and format with one sample (with_resolve): the average of each pixel’s samples is written there when the pass ends.

pub struct ColorAttachment {
    pub texture: &Texture
    pub load: u32
    pub red: f64
    pub green: f64
    pub blue: f64
    pub alpha: f64
    // Keep what the pass drew (true), or let the GPU drop it, leaving the
    // contents undefined, which saves memory traffic for multisampled
    // attachments that are only resolved.
    pub store: bool
    pub resolve: &Texture
    pub has_resolve: bool
}

ColorAttachment.clear

Function · Source

pub fn clear(texture: &Texture, red: f64, green: f64, blue: f64, alpha: f64) -> ColorAttachment from(texture)

ColorAttachment.keep

Function · Source

pub fn keep(texture: &Texture) -> ColorAttachment from(texture)

ColorAttachment.with_resolve

Function · Source

Resolve this multisampled attachment into target (TEXTURE_RENDER).

pub fn with_resolve(self, target: &Texture) -> ColorAttachment from(self, target)

ColorAttachment.discard

Function · Source

Drop the attachment’s contents after the pass (after resolving).

pub fn discard(self) -> ColorAttachment from(self)

DepthAttachment

Struct · Source

The depth attachment of a render pass.

pub struct DepthAttachment {
    pub texture: &Texture
    pub load: u32
    pub depth: f32
    // Keep the depths after the pass (true), or let the GPU drop them.
    pub store: bool
}

DepthAttachment.clear

Function · Source

pub fn clear(texture: &Texture, depth: f32) -> DepthAttachment from(texture)

DepthAttachment.keep

Function · Source

pub fn keep(texture: &Texture) -> DepthAttachment from(texture)

DepthAttachment.discard

Function · Source

Drop the depths after the pass: they were only needed for its tests.

pub fn discard(self) -> DepthAttachment from(self)

CommandEncoder

Struct · Source

Records commands for the GPU. Nothing runs until submit(); dropping an encoder without submitting discards its commands.

pub struct CommandEncoder {
    // Private implementation fields omitted.
}

CommandEncoder.compute_pass

Function · Source

Record a compute pass. The encoder is busy until the pass ends.

pub fn compute_pass(&mut self) -> ComputePass from(self)

CommandEncoder.render_pass

Function · Source

Record a render pass drawing into color. It needs TEXTURE_RENDER and a color format.

pub fn render_pass(&mut self, color: ColorAttachment) -> RenderPass from(self)

CommandEncoder.render_pass_with_depth

Function · Source

Record a render pass drawing into color with the depth buffer depth, a TEXTURE_RENDER depth texture of the same size.

pub fn render_pass_with_depth(&mut self, color: ColorAttachment, depth: DepthAttachment) -> RenderPass from(self)

CommandEncoder.render_pass_targets

Function · Source

Record a render pass drawing into several color attachments (at most limits().max_color_attachments) of one size and sample count: attachment N takes the fragment shader’s output at @location(N).

pub fn render_pass_targets(&mut self, colors: &[ColorAttachment]) -> RenderPass from(self)

CommandEncoder.render_pass_targets_with_depth

Function · Source

pub fn render_pass_targets_with_depth(&mut self, colors: &[ColorAttachment], depth: DepthAttachment) -> RenderPass from(self)

CommandEncoder.depth_pass

Function · Source

Record a render pass that only writes depth, drawn with depth-only pipelines (RenderPipelineDescriptor.depth_only), such as a shadow map.

pub fn depth_pass(&mut self, depth: DepthAttachment) -> RenderPass from(self)

CommandEncoder.generate_mipmaps

Function · Source

Fill every mipmap level of texture after the first by filtering down the one before it, as for a texture whose first level was just written or rendered. It needs a filterable color format (8-bit and 16-bit float ones); with one level it does nothing.

pub fn generate_mipmaps(&mut self, texture: &Texture)

CommandEncoder.copy_buffer

Function · Source

Copy size bytes between buffers. Offsets and size are multiples of 4, the source has BUFFER_COPY_SRC, the destination BUFFER_COPY_DST, and copies within one buffer do not overlap.

pub fn copy_buffer(&mut self, source: &Buffer, source_offset: u64, destination: &Buffer, destination_offset: u64, size: u64)

CommandEncoder.copy_buffer_to_texture

Function · Source

Copy texels from source, starting offset bytes in with rows bytes_per_row apart, into region of destination. The offset is a multiple of 4 and of the texel size; the rest follows write_texture.

pub fn copy_buffer_to_texture(&mut self, source: &Buffer, offset: u64, bytes_per_row: u32, destination: &Texture, region: Region)

CommandEncoder.copy_texture_to_buffer

Function · Source

Copy texels of region of source into destination, starting offset bytes in with rows bytes_per_row apart.

pub fn copy_texture_to_buffer(&mut self, source: &Texture, region: Region, destination: &Buffer, offset: u64, bytes_per_row: u32)

CommandEncoder.submit

Function · Source

Run the recorded commands after everything submitted before, and after the writes made with write_buffer and write_texture so far.

pub fn submit(self) -> void!Error

ComputePass

Struct · Source

A compute pass. It ends when dropped or with end().

pub struct ComputePass {
    // Private implementation fields omitted.
}

ComputePass.set_pipeline

Function · Source

pub fn set_pipeline(&mut self, pipeline: &ComputePipeline)

ComputePass.set_buffer

Function · Source

Bind all of buffer to slot.

pub fn set_buffer(&mut self, slot: u32, buffer: &Buffer)

ComputePass.set_buffer_range

Function · Source

Bind size bytes of buffer from offset, a multiple of BINDING_ALIGNMENT, to slot.

pub fn set_buffer_range(&mut self, slot: u32, buffer: &Buffer, offset: u64, size: u64)

ComputePass.set_texture

Function · Source

Bind texture, read through sampler, to slot.

pub fn set_texture(&mut self, slot: u32, texture: &Texture, sampler: &Sampler)

ComputePass.set_storage_texture

Function · Source

Bind texture for reading and writing single texels to slot.

pub fn set_storage_texture(&mut self, slot: u32, texture: &Texture)

ComputePass.dispatch

Function · Source

Run x * y * z workgroups of the pipeline’s workgroup size. Each dispatch sees the writes of the ones before it.

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

ComputePass.end

Function · Source

pub fn end(self)

RenderPass

Struct · Source

A render pass. It ends when dropped or with end(). The viewport and scissor start out covering the whole attachment.

pub struct RenderPass {
    // Private implementation fields omitted.
}

RenderPass.set_pipeline

Function · Source

pub fn set_pipeline(&mut self, pipeline: &RenderPipeline)

RenderPass.set_buffer

Function · Source

pub fn set_buffer(&mut self, slot: u32, buffer: &Buffer)

RenderPass.set_buffer_range

Function · Source

pub fn set_buffer_range(&mut self, slot: u32, buffer: &Buffer, offset: u64, size: u64)

RenderPass.set_texture

Function · Source

pub fn set_texture(&mut self, slot: u32, texture: &Texture, sampler: &Sampler)

RenderPass.set_storage_texture

Function · Source

pub fn set_storage_texture(&mut self, slot: u32, texture: &Texture)

RenderPass.set_vertex_buffer

Function · Source

Read vertex buffer slot of the pipeline from buffer, starting offset bytes in. It needs BUFFER_VERTEX.

pub fn set_vertex_buffer(&mut self, slot: u32, buffer: &Buffer, offset: u64)

RenderPass.set_index_buffer

Function · Source

Read indices of format (INDEX_UINT16 or INDEX_UINT32) from buffer, starting offset bytes in. It needs BUFFER_INDEX.

pub fn set_index_buffer(&mut self, buffer: &Buffer, format: u32, offset: u64)

RenderPass.set_viewport

Function · Source

Draw into this part of the attachment, in pixels from its top-left corner, with depths mapped to min_depth..max_depth (0.0 to 1.0).

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

RenderPass.set_blend_constant

Function · Source

The color BLEND_FACTOR_CONSTANT reads, until the pass ends; each pass starts with transparent black.

pub fn set_blend_constant(&mut self, red: f64, green: f64, blue: f64, alpha: f64)

RenderPass.set_scissor

Function · Source

Discard pixels outside this rectangle.

pub fn set_scissor(&mut self, x: u32, y: u32, width: u32, height: u32)

RenderPass.draw

Function · Source

Draw vertex_count vertices from first_vertex, instance_count times from first_instance. Every vertex buffer the pipeline reads must be set and long enough.

pub fn draw(&mut self, vertex_count: u32, instance_count: u32, first_vertex: u32, first_instance: u32)

RenderPass.draw_indexed

Function · Source

Draw index_count indices of the index buffer from first_index, adding base_vertex to each. Index values are not checked against the vertex buffers: an index past their end reads undefined values.

pub fn draw_indexed(&mut self, index_count: u32, instance_count: u32, first_index: u32, base_vertex: i32, first_instance: u32)

RenderPass.end

Function · Source

pub fn end(self)

f32_bytes

Function · Source

The bytes of values in native byte order, for write_buffer.

pub fn f32_bytes(values: &[f32]) -> &[u8] from(values)

u32_bytes

Function · Source

pub fn u32_bytes(values: &[u32]) -> &[u8] from(values)

i32_bytes

Function · Source

pub fn i32_bytes(values: &[i32]) -> &[u8] from(values)

u16_bytes

Function · Source

pub fn u16_bytes(values: &[u16]) -> &[u8] from(values)

f32_bytes_mut

Function · Source

The bytes of values to fill with read_buffer. Any bytes make valid numbers of these types.

pub fn f32_bytes_mut(values: &mut[f32]) -> &mut[u8] from(values)

u32_bytes_mut

Function · Source

pub fn u32_bytes_mut(values: &mut[u32]) -> &mut[u8] from(values)

i32_bytes_mut

Function · Source

pub fn i32_bytes_mut(values: &mut[i32]) -> &mut[u8] from(values)

SurfaceOptions

Struct · Source

How a Surface presents. Surface.create uses the defaults: vsync on, two frames in flight.

pub struct SurfaceOptions {
    // Wait for the display's refresh to show each frame (no tearing).
    pub vsync: bool
    // How many frames the CPU may record before the GPU has finished the
    // oldest: 2 or 3. More hides GPU latency, fewer cuts input lag.
    pub frames_in_flight: u32
}

SurfaceOptions.default

Function · Source

pub fn default() -> SurfaceOptions

Surface

Struct · Source

The images a window shows. Each frame, acquire() a Frame, render into its texture() and present() it.

On Vulkan the surface is a swapchain (VK_KHR_xcb_surface on Linux, VK_KHR_win32_surface on Windows), on Metal the view’s CAMetalLayer (the one Window.metal_layer() made, or a new one), and on OpenGL a texture copied into the window by the window’s own context, which needs a device from Device.open_for_window. The images have format(), an 8-bit sRGB format, and usages TEXTURE_RENDER, TEXTURE_COPY_SRC and TEXTURE_COPY_DST.

Call resize() with the window’s size in pixels whenever it changes (window.Event.Resize). The window must stay open while the surface exists; use both from the thread that opened the window.

pub struct Surface {
    // Private implementation fields omitted.
}

Surface.create

Function · Source

A surface for native’s window, width by height pixels, with the default SurfaceOptions. Fails with Unsupported when the device cannot present to this window, as an OpenGL device not opened for it with Device.open_for_window, or a Vulkan device on macOS (use Metal).

pub fn create(device: &Device, native: &handle.NativeHandle, width: u32, height: u32) -> Surface!Error from(device)

Surface.create_with

Function · Source

pub fn create_with(device: &Device, native: &handle.NativeHandle, width: u32, height: u32, options: SurfaceOptions) -> Surface!Error from(device)

Surface.format

Function · Source

The format of the images: FORMAT_BGRA8_UNORM_SRGB or FORMAT_RGBA8_UNORM_SRGB. Render pipelines drawing into them use it.

pub fn format(&self) -> u32

Surface.width

Function · Source

The images’ size in pixels, which can differ from the one asked for where the window system decides.

pub fn width(&self) -> u32

Surface.height

Function · Source

pub fn height(&self) -> u32

Surface.resize

Function · Source

Make the images width by height pixels, the window’s new size. A size of 0, as for a minimized window, makes acquire() fail with Outdated until the next resize.

pub fn resize(&mut self, width: u32, height: u32) -> void!Error

Surface.set_vsync

Function · Source

pub fn set_vsync(&mut self, vsync: bool) -> void!Error

Surface.acquire

Function · Source

Wait for the next image, at most frames_in_flight frames after the oldest one the GPU is still working on. Fails with Outdated when the window’s size changed in a way the surface could not follow by itself; resize() it then.

pub fn acquire(&mut self) -> Frame!Error from(self)

Frame

Struct · Source

One image of a Surface, to render into and present. Dropping a frame without present() presents it anyway.

pub struct Frame {
    // Private implementation fields omitted.
}

Frame.texture

Function · Source

The image: a color attachment or copy destination of the surface’s format and size.

pub fn texture(&self) -> &Texture from(self)

Frame.present

Function · Source

Show the image once every submission so far has finished drawing it.

pub fn present(self) -> void!Error

Search every guide, reference page, and API declaration.