std/gpu runs compute shaders and draws on the GPU through one API, whatever
graphics interface the machine has. It follows WebGPU’s model: a device
creates buffers, textures, samplers and pipelines, and a command encoder
records compute passes, render passes and copies that submit() runs in
order. Every call is checked before it reaches the GPU, and objects stay alive
until the GPU has finished with them, so safe code cannot make the GPU read
freed memory or copy outside a buffer. Shaders can be written once in WGSL,
frames go to std/window windows through gpu.Surface, and the
CPU runs ahead of the GPU: writing data never waits for it.
It is written in Dodo on top of the raw bindings, which stay available for everything it does not cover:
| System | Backends, in the order Device.open tries them |
Needs |
|---|---|---|
| macOS (Apple silicon, Intel) | Metal, then Vulkan through MoltenVK | Nothing to install |
| Linux (x86-64, AArch64) | Vulkan, then OpenGL | A Vulkan 1.2 or OpenGL 4.5 driver; Mesa’s lavapipe and llvmpipe run on the CPU |
| Windows (x64) | Vulkan, then OpenGL | Any current GPU driver |
Nothing but Metal is linked. Vulkan and OpenGL are opened when a device is created, so a program starts on any machine and gets an error it can handle when there is no usable GPU.
Quickstart
examples/gpu_compute.dodo
computes y = a * x + y for 1000 values and checks the results:
dodo run examples/gpu_compute.dodo
Metal: Apple M2
1000 of 1000 values correct
compute ok
On Linux the first line reads Vulkan: llvmpipe (LLVM 19.1.7, 128 bits) or
similar. Without a usable GPU it prints NoBackend and exits 2. The heart of
the program, with the WGSL kernel (see Shaders in WGSL)
left out:
fn run(device: &gpu.Device) -> u32!gpu.Error {
xs := [0.0f32; 1000]
ys := [0.0f32; 1000]
for i in 0usize..1000 {
xs[i] = i as f32
ys[i] = 1.0
}
a := [2.5f32]
count := [1000u32]
params := device.create_buffer(16, gpu.BUFFER_UNIFORM | gpu.BUFFER_COPY_DST)?
device.write_buffer(¶ms, 0, gpu.f32_bytes(&a))?
device.write_buffer(¶ms, 4, gpu.u32_bytes(&count))?
x := device.create_buffer_with_data(gpu.f32_bytes(&xs), gpu.BUFFER_STORAGE)?
y := device.create_buffer_with_data(gpu.f32_bytes(&ys), gpu.BUFFER_STORAGE | gpu.BUFFER_COPY_SRC)?
// The kernel, translated from WGSL for every backend.
source := kernel()
bindings := [
gpu.BindingLayout.uniform_buffer(0, gpu.STAGE_COMPUTE),
gpu.BindingLayout.read_only_storage_buffer(1, gpu.STAGE_COMPUTE),
gpu.BindingLayout.storage_buffer(2, gpu.STAGE_COMPUTE),
]
descriptor := gpu.ComputePipelineDescriptor.new(&source, "saxpy", 64, 1, 1)
descriptor.bindings = &bindings
pipeline := device.create_compute_pipeline(descriptor)?
encoder := device.encoder()?
{
pass := encoder.compute_pass()
pass.set_pipeline(&pipeline)
pass.set_buffer(0, ¶ms)
pass.set_buffer(1, &x)
pass.set_buffer(2, &y)
pass.dispatch(16, 1, 1)
}
encoder.submit()?
result := [0.0f32; 1000]
device.read_buffer(&y, 0, gpu.f32_bytes_mut(&mut result))?
// ...
}
examples/gpu_window.dodo
draws a spinning triangle into a std/window window through a
gpu.Surface (see Surfaces), and
examples/gpu_triangle.dodo
does the same by reading each frame back into the window’s canvas.
Devices
gpu.Device.open(gpu.Options.default()) opens the first backend that works,
in the order of the table above. gpu.Options.with_backend(gpu.Preference.Vulkan)
asks for one backend (Vulkan, Metal or OpenGl) and fails if it is not
available. Set debug: true in the options to turn on the API’s own checks:
the Khronos validation layer for Vulkan when it is installed, and a debug
context for OpenGL. For Metal, run with MTL_DEBUG_LAYER=1 instead.
| Call | Returns |
|---|---|
device.api() |
gpu.Api.Vulkan, Metal or OpenGl; gpu.api_name(&api) names it |
device.name() |
The GPU’s name, such as "Apple M2" |
device.limits() |
gpu.Limits: the largest texture, buffer, binding and workgroup, and how many color attachments a pass takes (at least 4) |
device.wait() |
Waits until the GPU has finished everything submitted, and every write |
device.poll() |
Starts pending writes and destroys dropped objects the GPU is done with |
gpu.Device.open_for_window(&native, options) opens a device that can
present to a window, for a Surface: native comes from
std/window’s win.native_handle(). On OpenGL the device then draws with the
window’s own context; Vulkan picks a GPU that can present to the window.
Use a device from the thread that opened it. Everything the device creates borrows it, so it outlives its buffers, textures and pipelines; keep those in a struct that borrows the device, or in the same function.
Buffers
device.create_buffer(size, usage) creates zero-filled GPU memory that can be
used in the ways usage combines:
| Usage | Allows |
|---|---|
BUFFER_COPY_SRC |
Copies from it, and device.read_buffer |
BUFFER_COPY_DST |
Copies into it, and device.write_buffer |
BUFFER_VERTEX, BUFFER_INDEX |
set_vertex_buffer, set_index_buffer |
BUFFER_UNIFORM |
A uniform buffer slot |
BUFFER_STORAGE |
A storage buffer slot |
device.create_buffer_with_data(bytes, usage) creates a buffer holding a copy
of bytes, without needing BUFFER_COPY_DST. gpu.f32_bytes, u32_bytes,
i32_bytes and u16_bytes view number arrays as bytes, and f32_bytes_mut
and friends let read_buffer fill them.
device.write_buffer(&buffer, offset, bytes) happens after every submission
made before it and before every later one, exactly as if it were a command
of its own: a write never changes what an earlier submission sees. It does
not wait for the GPU: a buffer the CPU can map that no submitted work uses
any more is written directly, and otherwise the bytes go into a staging
buffer and the copy runs as part of the next submission (see Staging and
frames in flight). device.read_buffer(&buffer, offset, &mut out) waits for the submissions so far that use the buffer and
then copies. Both fail with InvalidInput when the range does not fit or the
buffer lacks the usage.
device.start_read_buffer(&buffer, offset, size) starts the same copy without
waiting and returns a gpu.Readback: ready() says whether the GPU has made
the copy, and read(&mut out) copies the size() bytes out, waiting first if
it has not. A program that reads results every frame can collect each one a
frame later and never stall on the GPU. device.start_read_texture(&texture, region, bytes_per_row) does the same for texels.
Textures and samplers
Textures are two-dimensional, with one layer and one or more mipmap levels:
texture := device.create_texture(gpu.TextureDescriptor.new(256, 256, gpu.FORMAT_RGBA8_UNORM, gpu.TEXTURE_RENDER | gpu.TEXTURE_COPY_SRC))?
image := device.create_texture(gpu.TextureDescriptor.mipmapped(256, 256, gpu.FORMAT_RGBA8_UNORM, gpu.TEXTURE_SAMPLED | gpu.TEXTURE_COPY_DST))?
samples := device.create_texture(gpu.TextureDescriptor.multisampled(256, 256, gpu.FORMAT_RGBA8_UNORM))?
TextureDescriptor.mipmapped gives a texture every level down to one texel
(gpu.mip_level_count(width, height) of them); set mip_levels for fewer.
Each level is half the size of the one before, rounded down to at least 1
(gpu.level_size). Write the first level and fill the others with
encoder.generate_mipmaps(&texture), which filters each level down from the
one before for 8-bit and 16-bit float color formats, or write each level
yourself. Render passes draw into the first level, and storage bindings
reach only that level too.
TextureDescriptor.multisampled makes a render target with
gpu.MULTISAMPLE_COUNT (4) samples per pixel, which a render pass resolves
into an ordinary texture of the same size and format (see
Commands). Multisampled textures have one level, no integer
format and only the usage TEXTURE_RENDER: nothing copies, samples or
stores them.
| Format | Bytes per texel | Notes |
|---|---|---|
FORMAT_R8_UNORM, FORMAT_RG8_UNORM |
1, 2 | |
FORMAT_RGBA8_UNORM, FORMAT_RGBA8_UNORM_SRGB |
4 | FORMAT_RGBA8_UNORM can be a storage texture |
FORMAT_BGRA8_UNORM, FORMAT_BGRA8_UNORM_SRGB |
4 | The layout of a std/window canvas |
FORMAT_R16_FLOAT, FORMAT_RG16_FLOAT, FORMAT_RGBA16_FLOAT |
2, 4, 8 | FORMAT_RGBA16_FLOAT can be a storage texture |
FORMAT_R32_FLOAT, FORMAT_RG32_FLOAT, FORMAT_RGBA32_FLOAT |
4, 8, 16 | Storage textures; not blendable, and not every GPU filters them linearly |
FORMAT_R32_UINT, FORMAT_R32_SINT, FORMAT_RGBA32_UINT |
4, 4, 16 | Storage textures; read as integers, so neither filtered nor blended |
FORMAT_DEPTH32_FLOAT |
4 | Render, sample and copy from; not written by copies or stores |
Usages are TEXTURE_COPY_SRC, TEXTURE_COPY_DST, TEXTURE_SAMPLED,
TEXTURE_STORAGE and TEXTURE_RENDER. Textures start out zero.
device.write_texture(&texture, region, bytes, bytes_per_row) and
device.read_texture(&texture, region, &mut out, bytes_per_row) copy a
gpu.Region of texels, ordered and staged like the buffer calls. Rows are
bytes_per_row apart, a multiple of the texel size and at least the width of
the region; texture.region() covers the whole first level and
texture.bytes_per_row() is its tight row size, while
texture.level_region(level) and texture.level_bytes_per_row(level) do the
same for any level, and gpu.Region.at_level(level, x, y, width, height)
picks part of one. Rows run top to bottom: row 0 is the top row in memory,
on screen and at texture coordinate v = 0.
device.create_sampler(gpu.SamplerDescriptor.linear()) and nearest()
filter and clamp, and trilinear() filters between texels and mipmap levels
and repeats. A gpu.SamplerDescriptor has these fields:
| Field | Sets |
|---|---|
mag_filter, min_filter |
FILTER_NEAREST or FILTER_LINEAR between texels |
mipmap_filter |
FILTER_NEAREST takes the nearest level, FILTER_LINEAR blends the two nearest |
address_u, address_v |
ADDRESS_CLAMP, ADDRESS_REPEAT, ADDRESS_MIRROR, or ADDRESS_BORDER, which reads border outside the texture |
border |
BORDER_TRANSPARENT_BLACK, BORDER_OPAQUE_BLACK or BORDER_OPAQUE_WHITE |
lod_min, lod_max |
The range of levels sampled, 0 to 32 by default |
max_anisotropy |
Up to 16 samples along the direction a texture is stretched in; a hint, and above 1 it needs every filter linear |
compare |
COMPARE_NONE, or a COMPARE_* that makes a comparison sampler |
A comparison sampler compares a reference depth with the texels of a depth
texture, giving 1.0 where the comparison passes and 0.0 where it fails,
filtered when the filters are linear. SamplerDescriptor.comparison(gpu.COMPARE_LESS_EQUAL)
is the usual one for shadow maps: linear, and passing outside the map, where
it reads an opaque white border. Comparison samplers only work in
comparison_texture slots, which only take them.
Shaders and bindings
A gpu.ShaderSource holds one shader in the language of every backend, and a
backend uses its own: SPIR-V words for Vulkan, Metal Shading Language source
for Metal, GLSL source for OpenGL. Leave out what you do not target; a device
whose language is missing fails with MissingShader. gpu.ShaderSource.new()
with with_spirv, with_msl and with_glsl builds one piece by piece.
Shaders find their resources in numbered slots, 0 to 15, with the same number in every language:
| Binding kind | SPIR-V (GLSL for Vulkan) | Metal | GLSL for OpenGL |
|---|---|---|---|
BindingLayout.uniform_buffer(n, stages) |
layout(binding = n) uniform |
constant T &x [[buffer(n)]] |
layout(std140, binding = n) uniform |
storage_buffer, read_only_storage_buffer |
layout(binding = n) buffer |
device T *x [[buffer(n)]] |
layout(std430, binding = n) buffer |
sampled_texture |
layout(binding = n) uniform sampler2D |
texture2d<float> [[texture(n)]] and sampler [[sampler(n)]] |
layout(binding = n) uniform sampler2D |
comparison_texture |
layout(binding = n) uniform sampler2DShadow |
depth2d<float> [[texture(n)]] and sampler [[sampler(n)]] |
layout(binding = n) uniform sampler2DShadow |
storage_texture(n, stages, format) |
layout(binding = n, r32ui) uniform uimage2D |
texture2d<uint, access::write> [[texture(n)]] |
the same as SPIR-V |
Vertex attribute at location |
layout(location = l) in |
[[attribute(l)]] with [[stage_in]] |
layout(location = l) in |
Vertex buffer n is Metal’s [[buffer(16 + n)]], which [[stage_in]] reads
for you. A pipeline lists its bindings, and every slot it lists must hold a
matching object with the right usage when it draws or dispatches.
The entry point is the function’s name in Metal and in the SPIR-V module.
glslangValidator names it main unless told otherwise; to use one name for
both, compile with
glslangValidator -V -S comp -e saxpy --source-entrypoint main shader.glsl.
GLSL’s entry point is always main, so OpenGL ignores the name. OpenGL
compiles a GLSL source once per stage, with #define VERTEX, #define FRAGMENT or #define COMPUTE inserted after its #version line, so one file
can hold every stage of a pipeline:
#version 450
#ifdef VERTEX
layout(location = 0) in vec2 position;
void main() { gl_Position = vec4(position, 0.0, 1.0); }
#endif
#ifdef FRAGMENT
layout(location = 0) out vec4 color;
void main() { color = vec4(1.0, 0.5, 0.0, 1.0); }
#endif
The same GLSL also compiles for Vulkan, which needs gl_VertexIndex where
OpenGL has gl_VertexID; glslangValidator defines VULKAN to tell them
apart.
Shaders in WGSL
gpu.wgsl takes a shader written once in WGSL
and translates it when the program is compiled, into SPIR-V, Metal Shading
Language and GLSL 4.50, so one source runs on every backend with no tools to
install:
fn kernels() -> gpu.ShaderSource from(static) {
return gpu.wgsl(
"@group(0) @binding(0) var<uniform> a: f32;",
"@group(0) @binding(1) var<storage, read> x: array<f32>;",
"@group(0) @binding(2) var<storage, read_write> y: array<f32>;",
"",
"@compute @workgroup_size(64)",
"fn saxpy(@builtin(global_invocation_id) id: vec3<u32>) {",
" y[id.x] = a * x[id.x] + y[id.x];",
"}"
)
}
The arguments are string literals, one or more, joined with line breaks; a
mistake in the shader is a compile error that points into the literal. The
result is an ordinary ShaderSource whose SPIR-V lives in static storage,
so it can be bound to a local (source := gpu.wgsl(...)) or returned from a
function declared from(static) as above, and passed to pipeline
descriptors like any other. A module may hold many entry points; pass the
WGSL function’s name as the entry point, the same on every backend.
Bindings use std/gpu’s slots:
| WGSL | std/gpu |
|---|---|
@group(0) @binding(n) var<uniform> |
BindingLayout.uniform_buffer(n, stages) |
@group(0) @binding(n) var<storage, read_write> or var<storage, read> |
storage_buffer or read_only_storage_buffer |
@group(0) @binding(n) var t: texture_2d<f32> and @group(1) @binding(n) var s: sampler |
sampled_texture(n, stages), bound with set_texture(n, texture, sampler) |
@group(0) @binding(n) var t: texture_depth_2d and @group(1) @binding(n) var s: sampler_comparison |
comparison_texture(n, stages), bound with a depth texture and a comparison sampler |
@group(0) @binding(n) var t: texture_storage_2d<r32uint, write> |
storage_texture(n, stages, gpu.FORMAT_R32_UINT) |
@location(l) input of a @vertex function |
VertexAttribute.new(l, format, offset) |
@location(n) output of a @fragment function |
Color target n of the pipeline |
So samplers sit in @group(1), at the binding of the texture they are read
with in @group(0); every other resource is in @group(0), at slots 0 to
15. Different entry points of one module may use the same slot for
different resources. Clip space and depth are as WGSL defines them, which is
what std/gpu uses on every backend. The translation is done by
naga, and refuses what
some backend cannot run as std/gpu drives it:
arrayLength(Metal would need buffer sizes std/gpu does not pass): put the length in a uniform buffer.- Immediate data (push constants): use a uniform buffer.
- Entry point names Metal reserves, such as
main, and names that are not ASCII identifiers.
A compiler built without its default wgsl feature reports gpu.wgsl calls
as errors; ShaderSource with hand-written languages keeps working.
Pipelines
descriptor := gpu.ComputePipelineDescriptor.new(&source, "saxpy", 64, 1, 1)
descriptor.bindings = &bindings
pipeline := device.create_compute_pipeline(descriptor)?
The workgroup size must equal the shader’s own (local_size in GLSL); Metal,
whose kernels do not declare one, dispatches with it. A render pipeline names
its vertex and fragment shaders, which may share a source, and its color
format:
positions := [gpu.VertexAttribute.new(0, gpu.VERTEX_FLOAT32X2, 0)]
colors := [gpu.VertexAttribute.new(1, gpu.VERTEX_UNORM8X4, 0)]
layouts := [gpu.VertexBufferLayout.new(8, &positions), gpu.VertexBufferLayout.new(4, &colors)]
descriptor := gpu.RenderPipelineDescriptor.new(&vertex, "turn", &fragment, "paint", gpu.FORMAT_BGRA8_UNORM)
descriptor.vertex_buffers = &layouts
descriptor.cull_mode = gpu.CULL_BACK
pipeline := device.create_render_pipeline(descriptor)?
The other fields default to triangle lists (topology), counterclockwise
front faces (front_face), no blending (blend: BLEND_ALPHA,
BLEND_PREMULTIPLIED or BLEND_ADDITIVE), no depth buffer (depth_format,
with depth_compare and depth_write), no depth bias and one sample per
pixel. VertexBufferLayout.instanced steps a buffer per instance. Point
lists draw points as large as the vertex shader’s gl_PointSize or
[[point_size]].
For several color attachments, or blending beyond the presets, pass
gpu.FORMAT_NONE as the color format and list targets instead; target
n takes the fragment shader’s output at location n:
targets := [
gpu.ColorTarget.new(gpu.FORMAT_RGBA16_FLOAT),
gpu.ColorTarget.blended(gpu.FORMAT_RGBA8_UNORM, gpu.Blend.new(gpu.BLEND_FACTOR_CONSTANT, gpu.BLEND_FACTOR_ONE_MINUS_CONSTANT, gpu.BLEND_OP_ADD)),
]
targets[1].write_mask = gpu.COLOR_WRITE_RED | gpu.COLOR_WRITE_GREEN | gpu.COLOR_WRITE_BLUE
descriptor := gpu.RenderPipelineDescriptor.new(&source, "scene_vertex", &source, "scene_fragment", gpu.FORMAT_NONE)
descriptor.targets = &targets
A gpu.Blend computes source * source factor (op) destination * destination factor,
separately for color and alpha with Blend.separate. The factors are
BLEND_FACTOR_ZERO, ONE, SRC, ONE_MINUS_SRC, SRC_ALPHA,
ONE_MINUS_SRC_ALPHA, DST, ONE_MINUS_DST, DST_ALPHA,
ONE_MINUS_DST_ALPHA, SRC_ALPHA_SATURATED, CONSTANT and
ONE_MINUS_CONSTANT (the pass’s set_blend_constant), and the operations
BLEND_OP_ADD, SUBTRACT, REVERSE_SUBTRACT, MIN and MAX;
Blend.preset(gpu.BLEND_ALPHA) spells out a preset. A pass may have up to
limits().max_color_attachments targets. Vulkan GPUs without the
independentBlend feature, which are rare, need every target blended and
masked alike.
A pipeline that only writes depth, such as one drawing a shadow map, leaves
out the fragment stage and draws in a depth_pass:
descriptor := gpu.RenderPipelineDescriptor.depth_only(&source, "shadow_vertex", gpu.FORMAT_DEPTH32_FLOAT)
descriptor.depth_bias = 2
descriptor.depth_bias_slope_scale = 1.5
depth_bias adds that many of the depth buffer’s smallest steps to each
fragment’s depth, depth_bias_slope_scale scales the triangle’s depth
slope, and depth_bias_clamp, unless 0, limits the sum; it applies to
triangles only. Later passes read the map through a comparison_texture
slot. For multisampling, set samples to gpu.MULTISAMPLE_COUNT on a
pipeline drawing into multisampled attachments; alpha_to_coverage then
covers each pixel’s samples in proportion to the alpha written to location
0, for antialiased cutouts such as foliage.
Clip space is the same on every backend: x right and y up from -1 to 1, depth from 0 to 1, and the top of the image at y = 1. Front faces wind counterclockwise as seen there.
Commands
device.encoder() starts recording. Passes borrow the encoder until they
end, when dropped or with pass.end():
| Command | Does |
|---|---|
encoder.compute_pass() |
set_pipeline, set_buffer, set_buffer_range, set_texture, set_storage_texture, dispatch(x, y, z) |
encoder.render_pass(color) |
The same bindings, plus set_vertex_buffer, set_index_buffer, set_viewport, set_scissor, draw, draw_indexed |
encoder.render_pass_with_depth(color, depth) |
A render pass with a depth buffer |
encoder.render_pass_targets(&colors), render_pass_targets_with_depth(&colors, depth) |
A render pass with several color attachments, one per pipeline target |
encoder.depth_pass(depth) |
A render pass with only a depth buffer, for depth-only pipelines |
pass.set_blend_constant(r, g, b, a) |
The color BLEND_FACTOR_CONSTANT reads, until the pass ends (0 to begin with) |
encoder.generate_mipmaps(&texture) |
Fills every level after the first from the one before |
encoder.copy_buffer, copy_buffer_to_texture, copy_texture_to_buffer |
Copies between objects with the copy usages |
encoder.submit() |
Runs everything recorded, after all earlier submissions |
gpu.ColorAttachment.clear(&texture, r, g, b, a) clears the attachment first
and ColorAttachment.keep(&texture) draws over it; gpu.DepthAttachment does
the same for depth. All attachments of a pass have one size and one sample
count. A multisampled color attachment resolves into a texture with one
sample when the pass ends, and discard() drops what the GPU need not keep
afterwards, leaving it undefined:
color := gpu.ColorAttachment.clear(&samples, 0.0, 0.0, 0.0, 1.0).with_resolve(frame.texture()).discard()
pass := encoder.render_pass_with_depth(color, gpu.DepthAttachment.clear(&depth, 1.0).discard())
Every command sees the results of the commands before it, including
dispatches within one pass. Buffer offsets bound to a slot are multiples of
gpu.BINDING_ALIGNMENT (256).
Dropping an encoder without submitting discards its commands, except on
OpenGL, which has no command buffers: there commands run as they are
recorded, and submit() only flushes them. For the same reason, a write
made on OpenGL while an encoder is open lands after the commands that
encoder recorded so far, not before all of them.
Surfaces
A gpu.Surface shows frames in a std/window window opened
with window.Options.gpu, which has no pixel buffer of its own. Each frame,
acquire() an image, render into frame.texture() and present() it:
native := win.native_handle()!
device := gpu.Device.open_for_window(&native, gpu.Options.default())?
surface := gpu.Surface.create(&device, &native, win.width(), win.height())?
// Pipelines drawing into it use surface.format().
// ... for every window.Event.Frame:
frame := surface.acquire()?
encoder := device.encoder()?
{
pass := encoder.render_pass(gpu.ColorAttachment.clear(frame.texture(), 0.0, 0.0, 0.0, 1.0))
// set_pipeline, draw, ...
}
encoder.submit()?
frame.present()?
// ... and for every window.Event.Resize:
surface.resize(win.width(), win.height())?
The images have an 8-bit sRGB format, FORMAT_BGRA8_UNORM_SRGB or
FORMAT_RGBA8_UNORM_SRGB (surface.format()), the size surface.width()
by surface.height(), and the usages TEXTURE_RENDER, TEXTURE_COPY_SRC
and TEXTURE_COPY_DST, so a program drawing on the CPU can also
write_texture its picture straight into the frame. Presenting waits for
every submission so far, and for writes made before it.
gpu.Surface.create_with takes gpu.SurfaceOptions: vsync (on by
default) ties presenting to the display’s refresh, and frames_in_flight
(2 by default, or 3) is how many frames the CPU may record before the GPU
has finished the oldest; acquire() waits for that. set_vsync changes it
later. A frame dropped without present() is presented anyway.
acquire() fails with Outdated when the window’s size changed in a way
the surface could not follow by itself, or while it has no size, as when the
window is minimized (resize(0, 0)): skip the frame and resize the surface
to the window’s size. Vulkan follows size changes by itself on Linux and
Windows; Metal and OpenGL need resize.
| Backend | Presents through |
|---|---|
| Vulkan | A swapchain on VK_KHR_xcb_surface (Linux) or VK_KHR_win32_surface (Windows), FIFO with vsync and mailbox or immediate without |
| Metal | The view’s CAMetalLayer: the one win.metal_layer() made, or a new one |
| OpenGL | A texture that present() copies into the window’s framebuffer with the window’s context, then swaps; the device must come from open_for_window for that window |
Vulkan surfaces on macOS are not supported; there Preference.Auto picks
Metal. The window must stay open while its surface exists, and both are used
from the thread that opened the window.
Staging and frames in flight
std/gpu keeps the CPU from waiting for the GPU. On Vulkan and Metal,
std/gpu remembers which submissions use each buffer. write_buffer and
create_buffer_with_data write a buffer the CPU can map (every buffer on
Metal) directly when no submitted work uses it any more and no earlier write
to it is still staged. Other writes, and every write_texture, copy the data
into a staging ring buffer in memory the GPU can read and record the copy
into an upload command buffer, which runs first in the same submission as
the next submit(), or on its own before a present(), read or wait().
Nothing waits until the ring is full of copies the GPU has not run yet: it
starts at 4 MiB and doubles up to 64 MiB, and writes of more than 16 MiB get
a staging buffer of their own. Several writes to the same buffer land in the
order they were made. OpenGL’s driver stages such calls itself, so there
they go straight to it. A program that updates a buffer every frame while
earlier frames are in flight can keep one buffer per frame in flight: each
write then finds its buffer idle and costs a memory copy.
Reading back is the only call that waits: read_buffer waits for the
submissions that use the buffer and read_texture for every submission so
far, then they copy; start_read_buffer and start_read_texture wait for
nothing. On Vulkan, buffers live in GPU memory; where the CPU can map that
memory (GPUs with unified memory, or resizable BAR) reads copy from it
directly, and otherwise through a readback buffer in memory the CPU caches.
With a Surface, two or three frames are in flight.
Setting the environment variable DODO_GPU_UNMAPPED makes the Vulkan
backend treat every buffer as unmapped, as on a GPU with memory of its own,
so the copy paths can be tested on any machine.
Synchronization
Commands see the results of the ones before them without any calls from the
program. std/gpu tracks how every command uses each buffer and texture
(vertex input, uniform or storage reads, storage writes, attachments,
copies) and asks the backend for a barrier only where a command depends on
an earlier one of the same encoder, with exactly the stages and accesses
involved: a compute pass writing a buffer that a render pass then reads as
vertices gets one barrier from compute writes to vertex input, and
independent dispatches, copies and passes get none. Each submission starts
after the ones before it have finished.
The Vulkan backend records each render pass’s commands into a list and
replays them into the command buffer when the pass ends, so that the
barriers its draws need can run before the pass;
OpenGL needs glMemoryBarrier only after shader writes to storage buffers
and textures, and Metal tracks hazards itself. Draws of one render pass are
not ordered against each other: a draw cannot read what an earlier draw of
the same pass wrote to a storage buffer or texture.
Object lifetimes
Dropping a buffer, texture, sampler or pipeline that a submitted command or an
open encoder may still use is safe: std/gpu destroys it once the GPU has
finished every such submission. submit(), wait() and poll() destroy what
has become free; call device.poll() in a program that drops objects and then
submits nothing for a while. Any number of objects can wait. On Metal, whose
command buffers keep what they use alive, objects dropped while no encoder is
recording are released at once.
What is checked
Creating objects and copying data return errors. Recording mistakes panic,
as an index out of bounds does, and the report names the line of
std/gpu.dodo whose message describes the mistake:
- usages: every buffer and texture is used only in the ways it was created for
- ranges: copies, bound ranges, texture regions, row sizes and the vertices and indices a draw reads all lie inside their buffers and textures
- pipelines: a draw or dispatch has a pipeline, every slot it lists holds the right kind of object (comparison samplers and depth textures only in comparison slots), storage textures have the layout’s format, and the attachments match the pipeline’s formats and sample count and do not appear as bindings
- passes: attachments share a size and sample count, no texture is attached twice, and resolve targets have one sample and their attachment’s format
- limits: workgroup counts and sizes, texture sizes and binding sizes
- SPIR-V: Vulkan modules are well formed and contain the named entry point of the right stage
The GPU’s side is not checked: what a shader reads or writes, and index
values in an index buffer, are up to the program. Vulkan enables
robustBufferAccess where the GPU offers it, so out-of-bounds accesses
there read zero instead of other memory; run with the APIs’ validation while
developing.
Errors
gpu.Error and gpu.error_name(error):
| Error | When |
|---|---|
NoBackend |
No backend could be used: no Metal GPU, Vulkan loader or OpenGL library, or no GPU behind it |
Unsupported |
The backend is too old (Vulkan before 1.2 or without dynamic rendering and push descriptors, OpenGL before 4.5), lacks a format or sample count, or lacks an optional feature a pipeline uses (independent blending or depth bias clamping on Vulkan, depth bias clamping before OpenGL 4.6) |
InvalidInput |
An argument breaks one of the rules above |
MissingShader |
The shader source has no code for this device’s API |
InvalidShader |
The shader does not compile or link, or lacks the entry point |
OutOfMemory |
The GPU or driver ran out of memory |
DeviceLost |
The GPU stopped responding |
Outdated |
A surface no longer matches its window; resize it |
System |
Another backend call failed |
Backends
| Vulkan | Metal | OpenGL | |
|---|---|---|---|
| Version | 1.2 with dynamic rendering and push descriptors (core in 1.3 and 1.4) | Any Mac GPU | 4.5 core, without a window |
| Memory | Large blocks per memory type, carved into buffers and images | Metal’s own | The driver’s |
| Buffers | Device-local, mapped too on unified memory; staged writes, reads through host-cached memory | Shared storage; staged writes | Buffer objects |
| Textures | Optimal tiling, always in the general layout; mipmaps by blits, resolves at the end of rendering | Private storage, copied through buffers | Immutable storage; resolves by framebuffer blits |
| Synchronization | Barriers from tracked usage, one per submission besides; a timeline semaphore numbers submissions | Metal’s own tracking; a shared event numbers submissions | glMemoryBarrier after shader storage writes |
| Surfaces | Swapchains (Linux, Windows) | CAMetalLayer |
The window’s context |
macOS stops at OpenGL 4.1, so there Preference.OpenGl fails with
Unsupported; Vulkan needs MoltenVK there, as described on the
Vulkan page.
Limits
Textures have one layer (no arrays, cube maps or 3D textures), render passes draw into the first mipmap level, multisampling has 4 samples, and depth attachments do not resolve; there are no push constants, indirect draws, stencil buffers or queries. The raw bindings, std/gpu/vulkan, std/gpu/metal and std/gpu/opengl, cover all of that.
Writing a backend
std/gpu/hal is the interface between std/gpu and its backends. A backend
is a Device struct implementing hal.Backend: it creates objects from
already-checked descriptors and returns them as hal.Handles, four words whose
meaning it defines, and it records commands into an encoder handle. std/gpu
does the checking, keeps each pass’s bindings in a hal.PassState that the
backend applies at each draw or dispatch, and tells the backend when to destroy
objects; a backend whose tracks_resources() is true (Metal) gets no barrier
calls and keeps submitted work’s objects alive itself. Its submit(uploads, encoder) runs std/gpu’s upload encoder, when there is one, first in the
same submission. Each PassState carries dirty bits per slot: the backend
applies those of the slots the pipeline uses and clears exactly those, and
bindings carry over between pipelines of the same layout. Constructors
(open, open_for_window) are called by name, so hal.Backend works as a
&dyn reference, which is how std/gpu calls its backend. A backend whose
staged() is true leaves transfers to std/gpu,
which copies through BUFFER_UPLOAD and BUFFER_READBACK buffers it maps
with mapped(); barrier(encoder, before, after) receives the USE_*
bits of the dependent uses; and create_surface, configure_surface,
acquire and present drive surfaces. std/gpu/hal/native names the
operating system’s own backend, Metal on macOS; on Linux and Windows it
never opens.