Advanced Data
We have been putting vertex data, indices and constants into buffers since Hello Triangle, nearly always the same way: fill the memory once, at creation, and never touch it again. This chapter looks at the other ways to get data into a buffer and move it around, and at one more way to arrange vertex attributes. LearnOpenGL's chapter on the subject has no program of its own; ours does, a patch of water whose surface is recomputed on the CPU every frame.
What a buffer is
A buffer is a block of memory the GPU can read, and on its own nothing more. In OpenGL a buffer gets its meaning from the target it is bound to: the same buffer object is vertex data while bound to GL_ARRAY_BUFFER and indices while bound to GL_ELEMENT_ARRAY_BUFFER. Direct3D asks the question up front instead. When we create a buffer we say, in its BindFlags, every way it may ever be bound (D3D11_BIND_VERTEX_BUFFER, D3D11_BIND_INDEX_BUFFER, D3D11_BIND_CONSTANT_BUFFER, and a few more), and binding it any other way later is an error.
We also say, in its Usage, who will write to it and how often. This is the part that matters for this chapter. There are four choices:
| Usage | GPU | CPU | Typical use |
|---|---|---|---|
| D3D11_USAGE_IMMUTABLE | reads | nothing; the data is given at creation | meshes that never change |
| D3D11_USAGE_DEFAULT | reads and writes | occasional updates through | data that changes now and then; render targets |
| D3D11_USAGE_DYNAMIC | reads | writes through | data rewritten every frame |
| D3D11_USAGE_STAGING | nothing; only copies to and from it | reads and writes through | reading GPU results back |
OpenGL's GL_STATIC_DRAW and GL_DYNAMIC_DRAW are hints that a driver is free to ignore. Direct3D's usages are contracts: an immutable buffer cannot be written, a dynamic one cannot be written with
Filling a buffer
So far every vertex buffer has been immutable, filled by passing the data straight to NULL pointer,
OpenGL's next tool is
// write sizeof(data) bytes at byte 24 of a DEFAULT buffer
D3D11_BOX box = { 24, 0, 0, 24 + sizeof(data), 1, 1 };
context->UpdateSubresource(buffer, 0, &box, &data, 0, 0);
Our texture loading,
vcall(context, ID3D11DeviceContextVtbl.UpdateSubresource, load_texture_texture, 0, 0, load_texture_image.pixels, rax, 0)
The 0 after the subresource index is the box: no box means the whole subresource, here mip level 0. rax holds the row pitch, the width times four bytes, worked out just before the call.
The third way, and the one this chapter's program uses, is to ask for a pointer to the buffer's memory and write into it ourselves. OpenGL calls it
update_buffer_mapped: D3D11_MAPPED_SUBRESOURCE = {}
; rcx: buffer, rdx: data, r8: size
;
; WRITE_DISCARD hands back fresh memory each time, so the GPU never waits on
; the CPU, and a draw already recorded keeps the values it saw.
update_buffer: proc(buffer: *ID3D11Buffer, data: *const void, size: u64) = {
push rbx
push rsi
push rdi
sub rsp, 48 ; Map takes 6: 32 + 16; entry 8 + three pushes 24 + 48 lands on 16
mov rbx, rcx ; buffer
mov rsi, rdx ; data
mov rdi, r8 ; size
vcall(context, ID3D11DeviceContextVtbl.Map, rbx, 0, D3D11_MAP.D3D11_MAP_WRITE_DISCARD, 0, update_buffer_mapped&)
assert_hr()
invoke(mem_copy, update_buffer_mapped.pData, rsi, rdi)
vcall(context, ID3D11DeviceContextVtbl.Unmap, rbx, 0)
add rsp, 48
pop rdi
pop rsi
pop rbx
ret
}
rcx to r9 for its own. (
The other write mode for buffers, D3D11_MAP_WRITE_NO_OVERWRITE, is a promise in the opposite direction: we will only write parts of the buffer that no pending draw is using, so the driver can give us the existing memory without waiting. Together they make the classic pattern for streaming many small pieces of geometry: append with no-overwrite until the buffer is full, then discard and start again at the beginning.
A buffer rewritten every frame
The program draws a square of water 8 units wide, as a grid of 96 by 96 points. The height of each point is a sum of three sine waves running in different directions at different speeds:
\[ h(x, z, t) = 0.25 \sin(1.3x + 1.7t) + 0.15 \sin(2.1z - 1.1t) + 0.08 \sin(3.7(x + z) + 2.3t) \]
In assembly that is a procedure taking its three floats in xmm0, xmm1 and xmm2, and returning the height in xmm0. An SSE instruction has no immediate operands, so a float literal such as 1.3 is a constant that rasm keeps in read-only memory, and mulss xmm0, 1.3 multiplies by it there; here is the first wave of the three:
wave_height_x: f32 = 0.0
wave_height_z: f32 = 0.0
wave_height_time: f32 = 0.0
wave_height_sum: f32 = 0.0
; xmm0: x, xmm1: z, xmm2: time -> xmm0: the water's height there, three waves summed
;
; 0.25 sin(1.3 x + 1.7 t) + 0.15 sin(2.1 z - 1.1 t) + 0.08 sin(3.7 (x + z) + 2.3 t)
wave_height: proc(x: f32, z: f32, time: f32) -> f32 = {
; sinf keeps its float in its shadow space, so even this proc, which saves
; nothing, reserves one: 32, and 8 to put rsp back on 16.
sub rsp, 40
movss wave_height_x, xmm0
movss wave_height_z, xmm1
movss wave_height_time, xmm2
mulss xmm0, 1.3
movss xmm1, xmm2
mulss xmm1, 1.7
addss xmm0, xmm1
call sinf
mulss xmm0, 0.25
movss wave_height_sum, xmm0
; ...
The arguments are saved first, in globals named after the proc, because xmm register below xmm6. A vertex shader could compute this itself. We do it on the CPU on purpose, as a stand-in for all the cases where vertex data really does come from the CPU every frame: cloth or physics simulations, particles, text, debug lines. The positions therefore go into a dynamic buffer, made with no initial data and with CPU write access:
; GRID points along each side; two triangles, six indices, to each square of
; four points
#define GRID 96
#define GRID_POINTS (GRID * GRID)
#define INDEX_COUNT ((GRID - 1) * (GRID - 1) * 6)
; Positions: DYNAMIC, so the CPU may write them; nothing to start with.
position_desc: const D3D11_BUFFER_DESC = {
.ByteWidth = sizeof(vec3) * GRID_POINTS,
.Usage = D3D11_USAGE.D3D11_USAGE_DYNAMIC,
.BindFlags = D3D11_BIND_FLAG.D3D11_BIND_VERTEX_BUFFER,
.CPUAccessFlags = D3D11_CPU_ACCESS_FLAG.D3D11_CPU_ACCESS_WRITE,
}
vcall(device, ID3D11DeviceVtbl.CreateBuffer, position_desc&, 0, position_buffer&)
It is the same recipe as const, never written, and its ByteWidth is a constant expression, which C works out when it compiles the initialiser: GRID_POINTS is a #define. Every frame, before drawing, we recompute all 9216 positions into an array in our own memory, two nested loops with r12d counting rows and r13d columns, and copy the lot in with the same
; this frame's water: every point's height, then the whole buffer rewritten
lea rsi, positions
xor r12d, r12d ; z
heights_rows:
xor r13d, r13d ; x
heights_columns:
cvtsi2ss xmm0, r13d
call grid_coordinate
movss wx, xmm0
movss [rsi].vec3.x, xmm0
cvtsi2ss xmm0, r12d
call grid_coordinate
movss [rsi].vec3.z, xmm0
movaps xmm1, xmm0 ; z
movss xmm0, wx ; x
movss xmm2, current_frame ; time
call wave_height
movss [rsi].vec3.y, xmm0
add rsi, sizeof(vec3)
inc r13d
cmp r13d, GRID
jb heights_columns
inc r12d
cmp r12d, GRID
jb heights_rows
invoke(update_buffer, position_buffer, positions&, sizeof(positions))
positions: [GRID_POINTS]vec3 = {} ; rewritten every frame
colors: [GRID_POINTS]vec3 = {}
indices: [INDEX_COUNT]u32 = {}
An array's count is one number or one name, which is why the products are #defines, and sizeof(positions) is the whole array's size in bytes. Since we write every byte, discarding is exactly right. The points are joined into triangles by an index buffer, built once at startup, two triangles per grid square, and that never changes: an immutable buffer. So is the water's colour, and that brings us to the second topic.
Batching vertex attributes
Every vertex buffer so far has been 123123123. Another option is to keep each attribute in a block of its own, all positions, then all normals, then all uvs: 111222333. Data loaded from files often comes this way, one array per attribute, and keeping it so saves interleaving it ourselves.
LearnOpenGL does it by writing the three arrays one after another into a single buffer with
For our water there is a good reason to split them beyond convenience: the positions change every frame, and the colours never do. In one interleaved buffer, the unchanging colours would have to be rewritten every frame along with the positions. In two buffers, we only rewrite what changes. The input layout says which slot each attribute comes from, in the fourth field of each element:
; Positions from slot 0, colours from slot 1.
water_layout: [2]const D3D11_INPUT_ELEMENT_DESC = {
{ .SemanticName = "POSITION", .Format = DXGI_FORMAT.DXGI_FORMAT_R32G32B32_FLOAT, .InputSlot = 0 },
{ .SemanticName = "COLOR", .Format = DXGI_FORMAT.DXGI_FORMAT_R32G32B32_FLOAT, .InputSlot = 1 },
}
The fields left out are zero, and zero is what they should be: both attributes start at byte 0 of their vertex (AlignedByteOffset), since each slot holds only one attribute, and both are per-vertex data, D3D11_INPUT_PER_VERTEX_DATA being 0. A string literal in an initialiser is the address of the string, which is what SemanticName holds. The colours, a blue that brightens toward the near edge of the water, are computed once and go into an immutable buffer like any mesh:
; colours and indices: immutable
invoke(create_buffer, D3D11_BIND_FLAG.D3D11_BIND_VERTEX_BUFFER, colors&, sizeof(colors))
mov color_buffer, rax
invoke(create_buffer, D3D11_BIND_FLAG.D3D11_BIND_INDEX_BUFFER, indices&, sizeof(indices))
mov index_buffer, rax
At draw time, water_buffers[1], is fine, unlike one indexed by a register, and it counts elements: the second pointer, 8 bytes in.
water_buffers: [2]*ID3D11Buffer = {} ; slot 0, slot 1
water_strides: [2]u32 = { 12, 12 }
water_offsets: [2]u32 = { 0, 0 }
mov rax, position_buffer
mov water_buffers[0], rax
mov rax, color_buffer
mov water_buffers[1], rax
; positions from slot 0, colours from slot 1
vcall(context, ID3D11DeviceContextVtbl.IASetPrimitiveTopology, D3D11_PRIMITIVE_TOPOLOGY.D3D11_PRIMITIVE_TOPOLOGY_TRIANGLELIST)
vcall(context, ID3D11DeviceContextVtbl.IASetVertexBuffers, 0, 2, water_buffers&, water_strides&, water_offsets&)
vcall(context, ID3D11DeviceContextVtbl.IASetIndexBuffer, index_buffer, DXGI_FORMAT.DXGI_FORMAT_R32_UINT, 0)
vcall(context, ID3D11DeviceContextVtbl.RSSetState, wire_state)
vcall(context, ID3D11DeviceContextVtbl.DrawIndexed, INDEX_COUNT, 0, 0)
vcall(context, ID3D11DeviceContextVtbl.RSSetState, raster_state)
this, so two of them go on the stack, and sub rsp, 56, 32 bytes of shadow space and 16 for the two, with its four pushes counted in the alignment.
An index of 517 fetches position 517 from slot 0 and colour 517 from slot 1. The vertex shader cannot tell that its inputs came from two places; the input layout put them back together:
// POSITION comes from vertex buffer slot 0 and COLOR from slot 1; the
// shader cannot tell, the input layout joins them.
water_vertex vs_main(float3 position : POSITION, float3 color : COLOR)
{
water_vertex o;
o.position = mul(projection, mul(view, float4(position, 1.0)));
// Crests a little brighter, so the motion reads even in wireframe.
o.color = color * (0.8 + position.y);
return o;
}
The water is drawn in wireframe, with a rasterizer state like the one in Hello Triangle, because a flat-coloured surface with no lighting would hide the waves; the grid lines show them. For the same reason the vertex shader scales the colour by the height, brighter on the crests and darker in the troughs.
LearnOpenGL's layout, three blocks in one buffer, also works in Direct3D: bind the same buffer to three slots, with offsets of 0, the size of the positions, and the size of the positions plus normals, and give each slot its own stride. Which arrangement is faster depends on the hardware; interleaved data is the usual default, since a vertex shader invocation then finds all its inputs next to each other in memory. Split buffers win when, as here, some attributes change and others do not, or when some passes need only some attributes: a depth-only pass that reads only positions touches only the position buffer.
Copying buffers
Once data is on the GPU, we may want to copy it into another buffer without bringing it back to the CPU. OpenGL's
CopyResource (destination, source) copies a whole resource into another of the same size and type.CopySubresourceRegion copies part of one: for buffers, a D3D11_BOX gives the source byte range, and an x coordinate the destination offset.
// copy 8 floats from the start of vb1 to the start of vb2
D3D11_BOX box = { 0, 0, 0, 8 * sizeof(float), 1, 1 };
context->CopySubresourceRegion(vb2, 0, 0, 0, 0, vb1, 0, &box);
Copies run on the GPU, in order with the draws around them, so a copy issued after a draw sees what that draw left behind. The destination may not be immutable, and the two resources must be compatible: a buffer to a buffer, a texture to a texture of the same format family. Copying into a staging buffer and mapping it for reading is how data computed on the GPU is brought back to the CPU, though the map then has to wait for the GPU to catch up; window.rasm's --shot.
With these, buffers become more than places to park meshes. The next chapter puts a constant buffer to work across many shaders at once, and Instancing uses a second vertex slot for data that advances once per object instead of once per vertex.
The full program is here, and its shader here.
Additional resources
- D3D11_USAGE: the four usages and what each allows.
- How to: use dynamic resources:
Map with discard and no-overwrite. - CopySubresourceRegion: copying parts of buffers and textures.
- LearnOpenGL's Advanced Data: the OpenGL version of this chapter.
Exercises
- Change the program to keep positions and colours interleaved in one dynamic buffer, 24 bytes per vertex. What does the input layout become, and how much more data is copied per frame?
- Make the colour buffer D3D11_USAGE_DEFAULT and, when a key is pressed, give the water a new colour with
UpdateSubresource . - Move the wave computation into the vertex shader: send a flat grid once, pass the time in a constant buffer, and compute the height from
position.xandposition.z. The dynamic buffer is then no longer needed at all.