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 asmain, 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
formatin bytes, or 0 for an unknown format.
pub fn texel_size(format: u32) -> u32
mip_level_count
Function · Source
How many mipmap levels a
widthbyheighttexture 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
levelof a texturesizetexels 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
sizebytes, initially zero, usable in the waysusagecombines (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
dataintobufferatoffset. 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
bufferfromoffsetintoout, 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
sizebytes ofbufferfromoffsetback 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
dataintoregionoftexture, rowsbytes_per_rowapart, 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, ordatais 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
regionintoout, rowsbytes_per_rowapart, 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
regionback to the CPU, rowsbytes_per_rowapart, 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
leveltakes, 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
colorwith the depth bufferdepth, 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
textureafter 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
sizebytes 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, startingoffsetbytes in with rowsbytes_per_rowapart, intoregionofdestination. 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
regionofsourceintodestination, startingoffsetbytes in with rowsbytes_per_rowapart.
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
buffertoslot.
pub fn set_buffer(&mut self, slot: u32, buffer: &Buffer)
ComputePass.set_buffer_range
Function · Source
Bind
sizebytes ofbufferfromoffset, a multiple of BINDING_ALIGNMENT, toslot.
pub fn set_buffer_range(&mut self, slot: u32, buffer: &Buffer, offset: u64, size: u64)
ComputePass.set_texture
Function · Source
Bind
texture, read throughsampler, toslot.
pub fn set_texture(&mut self, slot: u32, texture: &Texture, sampler: &Sampler)
ComputePass.set_storage_texture
Function · Source
Bind
texturefor reading and writing single texels toslot.
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
slotof the pipeline frombuffer, startingoffsetbytes 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) frombuffer, startingoffsetbytes 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_countvertices fromfirst_vertex,instance_counttimes fromfirst_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_countindices of the index buffer fromfirst_index, addingbase_vertexto 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
valuesin 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
valuesto 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,widthbyheightpixels, 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
widthbyheightpixels, 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