API referencestd/gpu

std/gpu/hal

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

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/hal"

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
handle std/window/handle hal.dodo
mem core/mem hal.dodo
ptr core/ptr hal.dodo

Error

Enum · Source

pub enum Error {
    // No GPU API could be used: its library or driver is missing, or it
    // offers no suitable GPU.
    NoBackend,
    // The backend or GPU lacks a version, feature or format the call needs.
    Unsupported,
    // An argument breaks one of std/gpu's documented rules.
    InvalidInput,
    // The shader source has no code for the backend in use.
    MissingShader,
    // The shader code failed to compile or link, or lacks the entry point.
    InvalidShader,
    // The GPU or the driver ran out of memory.
    OutOfMemory,
    // The GPU stopped responding or was removed; the device is unusable.
    DeviceLost,
    // A surface no longer matches its window, which was resized or
    // minimized: resize it to the window's current size.
    Outdated,
    // Another backend call failed.
    System
}

Api

Enum · Source

Which GPU API a device uses.

pub enum Api {
    Vulkan,
    Metal,
    OpenGl
}

Handle

Struct · Source

A backend object: four words whose meaning the backend defines.

pub struct Handle {
    pub a: u64
    pub b: u64
    pub c: u64
    pub d: u64
}

Handle.null

Function · Source

pub fn null() -> Handle

Handle.copy

Function · Source

pub fn copy(&self) -> Handle

OBJECT_BUFFER

Constant · Source

What std/gpu destroys through Backend.destroy.

pub const OBJECT_BUFFER: u32 = 1

OBJECT_TEXTURE

Constant · Source

pub const OBJECT_TEXTURE: u32 = 2

OBJECT_SAMPLER

Constant · Source

pub const OBJECT_SAMPLER: u32 = 3

OBJECT_COMPUTE_PIPELINE

Constant · Source

pub const OBJECT_COMPUTE_PIPELINE: u32 = 4

OBJECT_RENDER_PIPELINE

Constant · Source

pub const OBJECT_RENDER_PIPELINE: u32 = 5

OBJECT_ENCODER

Constant · Source

A submitted or abandoned command encoder.

pub const OBJECT_ENCODER: u32 = 6

MAX_SLOTS

Constant · Source

Binding slots per pipeline, vertex buffers and attributes per render pipeline. Slot N is binding N of descriptor set 0 in SPIR-V, [[buffer(N)]], [[texture(N)]] and [[sampler(N)]] in Metal, and layout(binding = N) in GLSL.

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 per render pass and pipeline, at most; a device may allow fewer (Limits.max_color_attachments, at least 4).

pub const MAX_COLOR_ATTACHMENTS: u32 = 8

MULTISAMPLE_COUNT

Constant · Source

Samples per texel of a multisampled texture: every backend offers 4.

pub const MULTISAMPLE_COUNT: u32 = 4

METAL_VERTEX_BUFFER_BASE

Constant · Source

Metal shares buffer indices between bindings and vertex buffers: vertex buffer N is [[buffer(METAL_VERTEX_BUFFER_BASE + N)]].

pub const METAL_VERTEX_BUFFER_BASE: u32 = 16

BUFFER_COPY_SRC

Constant · Source

Buffer usages, combined with |.

pub const BUFFER_COPY_SRC: u32 = 1

BUFFER_COPY_DST

Constant · Source

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

BUFFER_USAGES

Constant · Source

pub const BUFFER_USAGES: u32 = 63

BUFFER_UPLOAD

Constant · Source

Usages only std/gpu itself asks for, never part of a user’s buffer: a mapped staging buffer the CPU writes and copies read (always mapped), and one copies write and the CPU reads, in memory the CPU caches.

pub const BUFFER_UPLOAD: u32 = 64

BUFFER_READBACK

Constant · Source

pub const BUFFER_READBACK: u32 = 128

TEXTURE_COPY_SRC

Constant · Source

Texture usages, combined with |.

pub const TEXTURE_COPY_SRC: u32 = 1

TEXTURE_COPY_DST

Constant · Source

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

pub const TEXTURE_RENDER: u32 = 16

TEXTURE_USAGES

Constant · Source

pub const TEXTURE_USAGES: u32 = 31

FORMAT_NONE

Constant · Source

Texture formats. FORMAT_NONE marks a missing depth attachment.

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

FORMAT_COUNT

Constant · Source

pub const FORMAT_COUNT: u32 = 17

texel_size

Function · Source

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

pub fn texel_size(format: u32) -> u32

is_depth

Function · Source

pub fn is_depth(format: u32) -> bool

is_integer

Function · Source

Whether shaders read the format as integers, which cannot be filtered or blended.

pub fn is_integer(format: u32) -> bool

is_storage

Function · Source

Whether every backend can use the format as a storage texture.

pub fn is_storage(format: u32) -> bool

is_blendable

Function · Source

Whether blending applies to a color format.

pub fn is_blendable(format: u32) -> bool

is_filterable

Function · Source

Whether every backend filters the format linearly, which generating mipmaps and multisample resolves need: the blendable formats.

pub fn is_filterable(format: u32) -> bool

level_size

Function · Source

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

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

mip_level_count

Function · Source

How many mipmap levels a width by height texture has at most: down to one texel.

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

lowest_bit

Function · Source

The number of the lowest set bit of mask, which is not 0: for walking through the slots a dirty mask names without testing every one.

pub fn lowest_bit(mask: u32) -> u32

Mutable

Struct · Source

A value changed through shared references. std/gpu’s objects borrow their device, so a device and its backend only ever see &self; what they change lives in a Mutable. A device is used from one thread, and the one rule is that no change may start while another of the same Mutable is running: update() must not be called from within an update() of the same value, and a reference from read() must not be used after a change.

pub struct Mutable<T> {
    // Private implementation fields omitted.
}

Mutable.new

Function · Source

pub fn new(value: T) -> Mutable<T>

Mutable.read

Function · Source

pub fn read(&self) -> &T from(self)

Mutable.update

Function · Source

Change the value in change, and return what it returns.

pub fn update<R>(&self, change: &mut dyn fn(&mut T) -> R) -> R

Mutable.get

Function · Source

The value’s address, for reading and writing single fields where a closure would cost too much: on paths run for every draw.

pub unsafe fn get(&self) -> *mut T

Requires an unsafe context. Follow the source safety preconditions and the linked guide before calling this API.

ignore

Function · Source

Ignore the outcome of a call whose failure changes nothing, such as waiting for the GPU while shutting down.

pub fn ignore(result: void!Error)

f32_bits

Function · Source

Bit patterns of numbers, for packing them into handles.

pub fn f32_bits(value: f32) -> u32

f32_from_bits

Function · Source

pub fn f32_from_bits(bits: u32) -> f32

i32_bits

Function · Source

pub fn i32_bits(value: i32) -> u32

i32_from_bits

Function · Source

pub fn i32_from_bits(bits: u32) -> i32

BINDING_NONE

Constant · Source

Binding kinds in a pipeline’s layout.

pub const BINDING_NONE: u32 = 0

BINDING_UNIFORM_BUFFER

Constant · Source

pub const BINDING_UNIFORM_BUFFER: u32 = 1

BINDING_STORAGE_BUFFER

Constant · Source

pub const BINDING_STORAGE_BUFFER: u32 = 2

BINDING_READ_ONLY_STORAGE_BUFFER

Constant · Source

pub const BINDING_READ_ONLY_STORAGE_BUFFER: u32 = 3

BINDING_SAMPLED_TEXTURE

Constant · Source

A texture sampled through a sampler bound with it.

pub const BINDING_SAMPLED_TEXTURE: u32 = 4

BINDING_STORAGE_TEXTURE

Constant · Source

A texture read and written texel by texel, of the layout’s format.

pub const BINDING_STORAGE_TEXTURE: u32 = 5

BINDING_COMPARISON_TEXTURE

Constant · Source

A depth texture sampled through a comparison sampler bound with it (texture_depth_2d with sampler_comparison in WGSL).

pub const BINDING_COMPARISON_TEXTURE: u32 = 6

STAGE_VERTEX

Constant · Source

Shader stages, 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

Four bytes read as floats from 0.0 to 1.0, such as an RGBA color.

pub const VERTEX_UNORM8X4: u32 = 13

vertex_size

Function · Source

The size of a vertex attribute in bytes, or 0 for an unknown format.

pub fn vertex_size(format: u32) -> u32

vertex_components

Function · Source

How many components a vertex attribute has.

pub fn vertex_components(format: u32) -> u32

STEP_VERTEX

Constant · Source

How a vertex buffer advances.

pub const STEP_VERTEX: u32 = 0

STEP_INSTANCE

Constant · Source

pub const STEP_INSTANCE: u32 = 1

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

Which winding faces the viewer, 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

Color blending presets: none, straight alpha, premultiplied alpha, additive. Blend.preset() spells each out.

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: what the shader’s output (source) and the attachment’s current value (destination) are multiplied by. CONSTANT is the pass’s blend constant (RenderPass.set_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

How the two products combine. 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

Which channels of a color attachment a pipeline 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

Blend

Struct · Source

How a color target blends: result = source * source factor (op) destination * destination factor, for the color channels and for alpha.

pub struct Blend {
    pub color_source: u32
    pub color_destination: u32
    pub color_operation: u32
    pub alpha_source: u32
    pub alpha_destination: u32
    pub alpha_operation: u32
}

Blend.replace

Function · Source

No blending: the shader’s output replaces the attachment’s value.

pub fn replace() -> Blend

Blend.new

Function · Source

The same factors and operation for color and alpha.

pub fn new(source: u32, destination: u32, operation: u32) -> Blend

Blend.separate

Function · Source

pub fn separate(color_source: u32, color_destination: u32, color_operation: u32, alpha_source: u32, alpha_destination: u32, alpha_operation: u32) -> Blend

Blend.preset

Function · Source

One of the BLEND_* presets.

pub fn preset(preset: u32) -> Blend

Blend.enabled

Function · Source

Whether this blends at all, rather than replacing.

pub fn enabled(&self) -> bool

Blend.uses_constant

Function · Source

Whether a factor reads the blend constant.

pub fn uses_constant(&self) -> bool

Blend.copy

Function · Source

pub fn copy(&self) -> Blend

Blend.same

Function · Source

pub fn same(&self, other: &Blend) -> bool

ColorTarget

Struct · Source

One color attachment a render pipeline draws into: its format, how the shader’s output at the same @location blends into it, and which channels are written.

pub struct ColorTarget {
    pub format: u32
    pub blend: Blend
    pub write_mask: u32
}

ColorTarget.new

Function · Source

Replacing every channel.

pub fn new(format: u32) -> ColorTarget

ColorTarget.blended

Function · Source

pub fn blended(format: u32, blend: Blend) -> ColorTarget

COMPARE_NONE

Constant · Source

COMPARE_NONE: 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

Outside 0.0 to 1.0 read the sampler’s border color.

pub const ADDRESS_BORDER: u32 = 3

BORDER_TRANSPARENT_BLACK

Constant · Source

Border colors, for 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

What a render pass does with an attachment’s previous contents.

pub const LOAD_CLEAR: u32 = 0

LOAD_KEEP

Constant · Source

pub const LOAD_KEEP: u32 = 1

USE_VERTEX_INPUT

Constant · Source

How a command uses a resource, for barrier(). The bits that write are USE_WRITES; a storage binding that may be written counts as both.

pub const USE_VERTEX_INPUT: u32 = 1

USE_INDEX

Constant · Source

pub const USE_INDEX: u32 = 2

USE_VERTEX_READ

Constant · Source

Uniform, storage, sampled or storage-texture reads by a shader stage.

pub const USE_VERTEX_READ: u32 = 4

USE_FRAGMENT_READ

Constant · Source

pub const USE_FRAGMENT_READ: u32 = 8

USE_COMPUTE_READ

Constant · Source

pub const USE_COMPUTE_READ: u32 = 16

USE_FRAGMENT_WRITE

Constant · Source

Storage buffer or storage texture writes by a shader stage.

pub const USE_FRAGMENT_WRITE: u32 = 32

USE_COMPUTE_WRITE

Constant · Source

pub const USE_COMPUTE_WRITE: u32 = 64

USE_COLOR

Constant · Source

Render pass attachments, which are read (blending, depth tests) and written.

pub const USE_COLOR: u32 = 128

USE_DEPTH

Constant · Source

pub const USE_DEPTH: u32 = 256

USE_COPY_SRC

Constant · Source

pub const USE_COPY_SRC: u32 = 512

USE_COPY_DST

Constant · Source

pub const USE_COPY_DST: u32 = 1024

USE_WRITES

Constant · Source

pub const USE_WRITES: u32 = 32 | 64 | 128 | 256 | 1024

Limits

Struct · Source

What a device can do. Every backend offers at least the minimums listed in std/gpu’s documentation.

pub struct Limits {
    pub max_texture_size: u32
    pub max_buffer_size: u64
    pub max_uniform_binding_size: u64
    pub max_storage_binding_size: u64
    pub max_workgroups: u32
    pub max_workgroup_size_x: u32
    pub max_workgroup_size_y: u32
    pub max_workgroup_size_z: u32
    pub max_workgroup_invocations: u32
    // Color attachments of a render pass, from 4 to MAX_COLOR_ATTACHMENTS.
    pub max_color_attachments: u32
}

Limits.copy

Function · Source

pub fn copy(&self) -> Limits

TextureDescriptor

Struct · Source

A two-dimensional texture with mip_levels mipmap levels, each half the size of the one before, and samples samples per texel (1, or MULTISAMPLE_COUNT for a multisampled render target).

pub struct TextureDescriptor {
    pub width: u32
    pub height: u32
    pub format: u32
    pub usage: u32
    pub mip_levels: u32
    pub samples: u32
}

TextureDescriptor.new

Function · Source

One mipmap level, one sample.

pub fn new(width: u32, height: u32, format: u32, usage: u32) -> TextureDescriptor

TextureDescriptor.mipmapped

Function · Source

Every mipmap level down to one texel.

pub fn mipmapped(width: u32, height: u32, format: u32, usage: u32) -> TextureDescriptor

TextureDescriptor.multisampled

Function · Source

A multisampled render target, resolved into an ordinary texture by render passes (ColorAttachment.with_resolve).

pub fn multisampled(width: u32, height: u32, format: u32) -> TextureDescriptor

TextureDescriptor.copy

Function · Source

pub fn copy(&self) -> TextureDescriptor

SamplerDescriptor

Struct · Source

How a sampler filters, picks mipmap levels and compares, and what it does outside 0.0 to 1.0.

pub struct SamplerDescriptor {
    pub mag_filter: u32
    pub min_filter: u32
    // How levels blend: FILTER_NEAREST takes the nearest level,
    // FILTER_LINEAR blends the two nearest (trilinear filtering).
    pub mipmap_filter: u32
    pub address_u: u32
    pub address_v: u32
    // The color ADDRESS_BORDER reads: BORDER_*.
    pub border: u32
    // The range of mipmap levels sampled, as level numbers.
    pub lod_min: f32
    pub lod_max: f32
    // COMPARE_NONE, or the comparison a comparison sampler makes between a
    // reference and each depth texel (passing gives 1.0, failing 0.0).
    pub compare: u32
    // Anisotropic filtering of up to this many samples (1 to 16), where the
    // GPU offers it; above 1 needs every filter linear.
    pub max_anisotropy: u32
}

SamplerDescriptor.linear

Function · Source

Linear filtering, clamped to the edge, the nearest mipmap level.

pub fn linear() -> SamplerDescriptor

SamplerDescriptor.nearest

Function · Source

Nearest-texel filtering, clamped to the edge.

pub fn nearest() -> SamplerDescriptor

SamplerDescriptor.trilinear

Function · Source

Linear filtering between texels and mipmap levels, repeating.

pub fn trilinear() -> SamplerDescriptor

SamplerDescriptor.comparison

Function · Source

A comparison sampler for shadow maps: linear filtering of the comparison results (percentage-closer filtering), and outside the texture the comparison passes against an opaque white border.

pub fn comparison(compare: u32) -> SamplerDescriptor

SamplerDescriptor.new

Function · Source

filter between texels, mipmap_filter between levels, address in both directions.

pub fn new(filter: u32, mipmap_filter: u32, address: u32) -> SamplerDescriptor

Region

Struct · Source

A rectangle of texels of mipmap level level.

pub struct Region {
    pub x: u32
    pub y: u32
    pub width: u32
    pub height: u32
    pub level: u32
}

Region.new

Function · Source

A rectangle of the first level.

pub fn new(x: u32, y: u32, width: u32, height: u32) -> Region

Region.at_level

Function · Source

pub fn at_level(level: u32, x: u32, y: u32, width: u32, height: u32) -> Region

Region.copy

Function · Source

pub fn copy(&self) -> Region

ShaderSource

Struct · Source

One shader in the languages of every backend. A backend uses its own: Vulkan the SPIR-V words, Metal the Metal Shading Language source and OpenGL the GLSL source. Leave out the ones you do not need.

OpenGL compiles the GLSL source once per stage, with #define VERTEX, #define FRAGMENT or #define COMPUTE inserted after its #version line, so one source can hold every stage of a pipeline.

pub struct ShaderSource {
    pub spirv: &[u32]
    pub msl: &str
    pub glsl: &str
}

ShaderSource.new

Function · Source

A source with no code for any backend; add some with the with_ methods.

pub fn new() -> ShaderSource from(static)

ShaderSource.with_spirv

Function · Source

pub fn with_spirv(self, words: &[u32]) -> ShaderSource from(self, words)

ShaderSource.with_msl

Function · Source

pub fn with_msl(self, source: &str) -> ShaderSource from(self, source)

ShaderSource.with_glsl

Function · Source

pub fn with_glsl(self, source: &str) -> ShaderSource from(self, source)

BindingLayout

Struct · Source

One entry of a pipeline’s binding layout: what the shader expects in slot, and which stages use it.

pub struct BindingLayout {
    pub slot: u32
    pub kind: u32
    pub stages: u32
    // The texel format of a BINDING_STORAGE_TEXTURE; otherwise ignored.
    pub format: u32
}

BindingLayout.uniform_buffer

Function · Source

pub fn uniform_buffer(slot: u32, stages: u32) -> BindingLayout

BindingLayout.storage_buffer

Function · Source

pub fn storage_buffer(slot: u32, stages: u32) -> BindingLayout

BindingLayout.read_only_storage_buffer

Function · Source

pub fn read_only_storage_buffer(slot: u32, stages: u32) -> BindingLayout

BindingLayout.sampled_texture

Function · Source

pub fn sampled_texture(slot: u32, stages: u32) -> BindingLayout

BindingLayout.comparison_texture

Function · Source

pub fn comparison_texture(slot: u32, stages: u32) -> BindingLayout

BindingLayout.storage_texture

Function · Source

pub fn storage_texture(slot: u32, stages: u32, format: u32) -> BindingLayout

VertexAttribute

Struct · Source

One attribute read from a vertex buffer: shader input location, read offset bytes into each vertex.

pub struct VertexAttribute {
    pub location: u32
    pub format: u32
    pub offset: u32
}

VertexAttribute.new

Function · Source

pub fn new(location: u32, format: u32, offset: u32) -> VertexAttribute

VertexBufferLayout

Struct · Source

The layout of one vertex buffer: stride bytes per vertex (or instance, for STEP_INSTANCE) holding attributes.

pub struct VertexBufferLayout {
    pub stride: u32
    pub step: u32
    pub attributes: &[VertexAttribute]
}

VertexBufferLayout.new

Function · Source

pub fn new(stride: u32, attributes: &[VertexAttribute]) -> VertexBufferLayout from(attributes)

VertexBufferLayout.instanced

Function · Source

pub fn instanced(stride: u32, attributes: &[VertexAttribute]) -> VertexBufferLayout from(attributes)

ComputePipelineDescriptor

Struct · Source

A compute pipeline. workgroup_size_* must equal the shader’s own workgroup size (local_size in GLSL); Metal, whose kernels do not declare it, dispatches with it.

pub struct ComputePipelineDescriptor {
    pub source: &ShaderSource
    pub entry: &str
    pub bindings: &[BindingLayout]
    pub workgroup_size_x: u32
    pub workgroup_size_y: u32
    pub workgroup_size_z: u32
}

ComputePipelineDescriptor.new

Function · Source

pub fn new(source: &ShaderSource, entry: &str, workgroup_size_x: u32, workgroup_size_y: u32, workgroup_size_z: u32) -> ComputePipelineDescriptor from(source, entry)

RenderPipelineDescriptor

Struct · Source

A render pipeline drawing into color attachments and, unless depth_format is FORMAT_NONE, a depth attachment.

The color attachments are either the one of color_format, blended by the blend preset, or, for several attachments or custom blending, targets (with color_format FORMAT_NONE): target N takes the fragment shader’s output at @location(N). An empty fragment_entry leaves out the fragment stage, for a pipeline that only writes depth, such as one drawing a shadow map; it then has no color attachments.

pub struct RenderPipelineDescriptor {
    pub vertex: &ShaderSource
    pub vertex_entry: &str
    pub fragment: &ShaderSource
    pub fragment_entry: &str
    pub bindings: &[BindingLayout]
    pub vertex_buffers: &[VertexBufferLayout]
    pub topology: u32
    pub cull_mode: u32
    pub front_face: u32
    pub color_format: u32
    pub blend: u32
    pub targets: &[ColorTarget]
    pub depth_format: u32
    pub depth_compare: u32
    pub depth_write: bool
    // Added to each fragment's depth before the depth test: `depth_bias`
    // units of the smallest depth step, plus `depth_bias_slope_scale` times
    // the triangle's depth slope, limited to `depth_bias_clamp` in size
    // unless that is 0. Triangles only; it keeps shadow maps from shadowing
    // the surfaces they were drawn from.
    pub depth_bias: i32
    pub depth_bias_slope_scale: f32
    pub depth_bias_clamp: f32
    // Samples per pixel of every attachment: 1 or MULTISAMPLE_COUNT.
    pub samples: u32
    // Multisampled pipelines only: cover each pixel's samples in proportion
    // to the alpha the shader writes to @location(0).
    pub alpha_to_coverage: bool
}

RenderPipelineDescriptor.new

Function · Source

Triangle lists without culling, blending, depth or multisampling, and with no bindings or vertex buffers until you set them.

pub fn new(vertex: &ShaderSource, vertex_entry: &str, fragment: &ShaderSource, fragment_entry: &str, color_format: u32) -> RenderPipelineDescriptor from(vertex, vertex_entry, fragment, fragment_entry)

RenderPipelineDescriptor.depth_only

Function · Source

A pipeline without a fragment stage that only writes depth to an attachment of depth_format.

pub fn depth_only(vertex: &ShaderSource, vertex_entry: &str, depth_format: u32) -> RenderPipelineDescriptor from(vertex, vertex_entry)

RenderPipelineDescriptor.has_fragment

Function · Source

Whether the pipeline has a fragment stage.

pub fn has_fragment(&self) -> bool

Pipeline

Struct · Source

A pipeline as std/gpu keeps it: the backend’s handle and the layout the pipeline was created with, which every draw or dispatch is checked against.

pub struct Pipeline {
    pub handle: Handle
    // Bit N: slot N is part of the layout.
    pub slots: u32
    // The binding kind of each slot, BINDING_NONE when unused.
    pub kinds: [16]u32
    pub stages: [16]u32
    // The format each storage texture slot expects.
    pub formats: [16]u32
    // Render pipelines only: the color attachments' formats, the depth
    // attachment's and the samples of each.
    pub topology: u32
    pub color_count: u32
    pub color_formats: [8]u32
    pub depth_format: u32
    pub samples: u32
    pub vertex_buffer_count: u32
    pub strides: [8]u32
    pub steps: [8]u32
    // How many bytes past the start of a vertex its last attribute ends.
    pub extents: [8]u32
    // Compute pipelines only.
    pub workgroup_size_x: u32
    pub workgroup_size_y: u32
    pub workgroup_size_z: u32
}

Pipeline.empty

Function · Source

pub fn empty() -> Pipeline

Pipeline.copy

Function · Source

pub fn copy(&self) -> Pipeline

Pipeline.same_layout

Function · Source

Whether both have the same binding layout: the same kind and stages in every slot. Bindings carry over between pipelines with the same layout (Vulkan pipeline layouts are then compatible).

pub fn same_layout(&self, other: &Pipeline) -> bool

BOUND_NONE

Constant · Source

What is bound to the slots of a pass.

pub const BOUND_NONE: u32 = 0

BOUND_BUFFER

Constant · Source

pub const BOUND_BUFFER: u32 = 1

BOUND_SAMPLED_TEXTURE

Constant · Source

A texture together with a sampler.

pub const BOUND_SAMPLED_TEXTURE: u32 = 2

BOUND_STORAGE_TEXTURE

Constant · Source

pub const BOUND_STORAGE_TEXTURE: u32 = 3

PassState

Struct · Source

The state of a compute or render pass. std/gpu fills it as commands are recorded and hands it to the backend at each draw or dispatch, which applies whatever the dirty masks say changed.

  • pipeline_dirty: the pipeline changed since the last draw or dispatch. Bindings and vertex buffers stay applied across pipeline changes; when the new pipeline’s layout differs (Pipeline.same_layout), std/gpu marks every bound slot dirty again.
  • dirty, vertex_dirty: bit N set when slot N (vertex buffer N) changed. A backend applies the bits of slots the pipeline uses, dirty &amp; pipeline.slots and the first vertex_buffer_count vertex buffers, and clears exactly those: a slot bound before a pipeline that uses it stays dirty until one does. lowest_bit() walks through the set bits.
pub struct PassState {
    pub pipeline: Pipeline
    pub has_pipeline: bool
    pub pipeline_dirty: bool
    pub bound: [16]u32
    // The words of the buffer or texture handle, and the sampler's first.
    pub object_a: [16]u64
    pub object_b: [16]u64
    pub object_c: [16]u64
    pub object_d: [16]u64
    pub sampler: [16]u64
    pub offset: [16]u64
    pub size: [16]u64
    // Bit N: slot N changed since the backend last applied it.
    pub dirty: u32
    // Bit N: slot N holds something.
    pub bound_slots: u32
    pub vertex_a: [8]u64
    pub vertex_offset: [8]u64
    pub vertex_set: u32
    pub vertex_dirty: u32
    pub index_a: u64
    pub index_offset: u64
    pub index_format: u32
    pub index_set: bool
    pub index_dirty: bool
}

PassState.new

Function · Source

pub fn new() -> PassState

Attachment

Struct · Source

One attachment of a render pass: what happens to its contents before (load) and after (store; false leaves them undefined) the pass, and for a multisampled color attachment with has_resolve, the texture its samples are averaged into at the end.

pub struct Attachment {
    pub texture: Handle
    pub format: u32
    pub load: u32
    pub store: bool
    pub clear_red: f64
    pub clear_green: f64
    pub clear_blue: f64
    pub clear_alpha: f64
    pub clear_depth: f32
    pub has_resolve: bool
    pub resolve: Handle
}

Attachment.empty

Function · Source

pub fn empty() -> Attachment

Attachment.copy

Function · Source

pub fn copy(&self) -> Attachment

RenderPassInfo

Struct · Source

The attachments of a render pass: color_count color attachments (none for a depth-only pass), and a depth attachment when has_depth, all width by height with samples samples per pixel.

pub struct RenderPassInfo {
    pub colors: [8]Attachment
    pub color_count: u32
    pub has_depth: bool
    pub depth: Attachment
    pub width: u32
    pub height: u32
    pub samples: u32
}

RenderPassInfo.new

Function · Source

pub fn new(width: u32, height: u32, samples: u32) -> RenderPassInfo

RenderPassInfo.copy

Function · Source

pub fn copy(&self) -> RenderPassInfo

SurfaceConfig

Struct · Source

How a surface presents: the size of its images in pixels, whether presenting waits for the display’s refresh, and how many frames may be in flight (2 or 3). configure_surface sets format to the FORMAT_* of the images it made.

pub struct SurfaceConfig {
    pub width: u32
    pub height: u32
    pub vsync: bool
    pub frames: u32
    pub format: u32
}

Backend

Interface · Source

What std/gpu needs from a backend. Every method except the constructors works on objects this device created; std/gpu destroys an object only once the GPU has finished every submission that used it.

Each backend Device also has two constructors, which std/gpu calls by name so that the interface stays usable as &dyn Backend: open(debug: bool) -> Device!Error opens the backend’s preferred GPU, with the API’s validation where debug asks for it and it exists, and open_for_window(native: &handle.NativeHandle, debug: bool) one that can present to the window (OpenGL makes its context the window’s, which its surface then needs).

pub interface Backend {
    fn api(&self) -> Api
    fn limits(&self) -> Limits
    // Copy the GPU's name into `out`, cut at a character boundary, and
    // return its length.
    fn name(&self, out: &mut[u8]) -> usize

    // Whether std/gpu stages transfers itself (see the top of this file).
    fn staged(&self) -> bool
    // Whether the API tracks hazards between commands and keeps a
    // submitted encoder, and every object its commands use, alive until the
    // GPU has run them (Metal). std/gpu then makes no barrier() calls,
    // destroys encoders as soon as they are submitted and dropped objects
    // as soon as no encoder is recording.
    fn tracks_resources(&self) -> bool
    // The CPU address of a buffer's memory, or 0 when the CPU cannot map
    // it. BUFFER_UPLOAD and BUFFER_READBACK buffers are always mapped; on a
    // GPU with unified memory, ordinary buffers may be too.
    fn mapped(&self, buffer: &Handle) -> usize
    // Make the GPU's writes to a mapped buffer visible to the CPU, after
    // the submission writing them has finished.
    fn invalidate(&self, buffer: &Handle, offset: u64, size: u64)

    // A buffer, initially zero when it is mapped; std/gpu clears unmapped
    // ones with clear_buffer before their first use.
    fn create_buffer(&self, size: u64, usage: u32) -> Handle!Error
    // Copy into or out of a buffer. std/gpu has already waited for every
    // submission that may use it.
    fn write_buffer(&self, buffer: &Handle, offset: u64, data: &[u8]) -> void!Error
    fn read_buffer(&self, buffer: &Handle, offset: u64, out: &mut[u8]) -> void!Error
    // A texture. Staged backends make it usable and zero it with
    // initialize_texture, which std/gpu records before its first use.
    fn create_texture(&self, descriptor: &TextureDescriptor) -> Handle!Error
    // Copy texels in or out, `bytes_per_row` apart in `data`. Writes are
    // ordered after earlier submissions; reads wait for them.
    fn write_texture(&self, texture: &Handle, descriptor: &TextureDescriptor, region: &Region, data: &[u8], bytes_per_row: u32) -> void!Error
    fn read_texture(&self, texture: &Handle, descriptor: &TextureDescriptor, region: &Region, out: &mut[u8], bytes_per_row: u32) -> void!Error
    fn create_sampler(&self, descriptor: &SamplerDescriptor) -> Handle!Error
    fn create_compute_pipeline(&self, descriptor: &ComputePipelineDescriptor) -> Handle!Error
    // std/gpu hands render pipelines over with every color attachment in
    // `targets`; their `color_format` and `blend` are then unused.
    fn create_render_pipeline(&self, descriptor: &RenderPipelineDescriptor) -> Handle!Error
    // Destroy an OBJECT_* that the GPU no longer uses.
    fn destroy(&self, object: u32, handle: &Handle)

    // The number of the last submission the GPU has finished; submissions
    // are numbered from 1 in order.
    fn completed(&self) -> u64
    // Wait until the GPU has finished submission `index` and those before.
    fn wait(&self, index: u64) -> void!Error

    fn begin_encoder(&self) -> Handle!Error
    // Submit an encoder's commands and return the submission's number.
    // `uploads` is std/gpu's upload encoder, whose commands run first, as
    // part of the same submission, or a null Handle (staged backends only).
    // Encoders are destroyed later, once that submission has finished.
    fn submit(&self, uploads: &mut Handle, encoder: &mut Handle) -> u64!Error
    fn begin_compute_pass(&self, encoder: &mut Handle)
    fn end_compute_pass(&self, encoder: &mut Handle)
    fn begin_render_pass(&self, encoder: &mut Handle, pass: &RenderPassInfo)
    fn end_render_pass(&self, encoder: &mut Handle)
    // Viewports and scissors are in pixels from the top-left corner.
    fn set_viewport(&self, encoder: &mut Handle, x: f32, y: f32, width: f32, height: f32, min_depth: f32, max_depth: f32)
    fn set_scissor(&self, encoder: &mut Handle, x: u32, y: u32, width: u32, height: u32)
    // The color BLEND_FACTOR_CONSTANT reads; render passes start with 0.
    fn set_blend_constant(&self, encoder: &mut Handle, red: f64, green: f64, blue: f64, alpha: f64)
    fn dispatch(&self, encoder: &mut Handle, state: &mut PassState, x: u32, y: u32, z: u32)
    fn draw(&self, encoder: &mut Handle, state: &mut PassState, vertex_count: u32, instance_count: u32, first_vertex: u32, first_instance: u32)
    fn draw_indexed(&self, encoder: &mut Handle, state: &mut PassState, index_count: u32, instance_count: u32, first_index: u32, base_vertex: i32, first_instance: u32)
    fn copy_buffer(&self, encoder: &mut Handle, source: &Handle, source_offset: u64, destination: &Handle, destination_offset: u64, size: u64)
    fn copy_buffer_to_texture(&self, encoder: &mut Handle, source: &Handle, offset: u64, bytes_per_row: u32, destination: &Handle, descriptor: &TextureDescriptor, region: &Region)
    fn copy_texture_to_buffer(&self, encoder: &mut Handle, source: &Handle, descriptor: &TextureDescriptor, region: &Region, destination: &Handle, offset: u64, bytes_per_row: u32)
    // Fill every mipmap level after the first from the one before it,
    // filtering linearly. The format is filterable and has more than one
    // level.
    fn generate_mipmaps(&self, encoder: &mut Handle, texture: &Handle, descriptor: &TextureDescriptor)
    // Fill `size` bytes of a buffer from `offset` with zeros; both are
    // multiples of 4.
    fn clear_buffer(&self, encoder: &mut Handle, buffer: &Handle, offset: u64, size: u64)
    fn initialize_texture(&self, encoder: &mut Handle, texture: &Handle, descriptor: &TextureDescriptor)
    // Make the commands recorded next that use resources as `after` says
    // wait for earlier ones that used them as `before` says, and see their
    // writes. Inside a render pass, the barrier applies before the pass:
    // draws of one pass are never ordered against each other.
    fn barrier(&self, encoder: &mut Handle, before: u32, after: u32)

    // A surface presenting to a window, configured with configure_surface
    // before its first acquire.
    fn create_surface(&self, native: &handle.NativeHandle) -> Handle!Error
    // Make (or remake) a surface's images. std/gpu has waited for every
    // submission and holds no acquired image.
    fn configure_surface(&self, surface: &mut Handle, config: &mut SurfaceConfig) -> void!Error
    // Wait for the surface's next image and describe it in `texture`, a
    // texture handle valid until the next configure_surface. Returns the
    // number of a submission the backend made to prepare the image, or 0
    // when it made none (it may fold that work into the next submission).
    // Fails with Outdated when the surface must be configured again.
    fn acquire(&self, surface: &mut Handle, texture: &mut Handle) -> u64!Error
    // Show the acquired image after every submission so far, and return
    // the number of the submission doing so, or 0 when there is none.
    fn present(&self, surface: &mut Handle) -> u64!Error
    fn destroy_surface(&self, surface: &Handle)
}

Search every guide, reference page, and API declaration.