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
levelof a texturesizetexels wide (or high).
pub fn level_size(size: u32, level: u32) -> u32
mip_level_count
Function · Source
How many mipmap levels a
widthbyheighttexture 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_levelsmipmap levels, each half the size of the one before, andsamplessamples 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
filterbetween texels,mipmap_filterbetween levels,addressin 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 FRAGMENTor#define COMPUTEinserted 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, readoffsetbytes 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:
stridebytes per vertex (or instance, for STEP_INSTANCE) holdingattributes.
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_formatis FORMAT_NONE, a depth attachment.The color attachments are either the one of
color_format, blended by theblendpreset, or, for several attachments or custom blending,targets(withcolor_formatFORMAT_NONE): target N takes the fragment shader’s output at @location(N). An emptyfragment_entryleaves 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 & pipeline.slotsand 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 withhas_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_countcolor attachments (none for a depth-only pass), and a depth attachment whenhas_depth, allwidthbyheightwithsamplessamples 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
formatto 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!Erroropens the backend’s preferred GPU, with the API’s validation wheredebugasks for it and it exists, andopen_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)
}