Colors

We have been throwing colours around since the first triangle, without ever saying what a colour is. Before we start lighting things, that deserves a proper answer, because lighting is, in the end, nothing but arithmetic on colours. In this chapter we pin down what an object's colour means, and then build the small scene that every lighting chapter after this one works in.

Light in the real world comes in a continuous spread of wavelengths, far more than any screen can show. A monitor gets by with three: it mixes red, green and blue light at different strengths, and our eyes read the mix as a single colour. So in a program a colour is three numbers, one per channel, each running from 0 (none of that channel) to 1 (all of it). We have written colours as float4 in HLSL already; the fourth number, alpha, is about transparency, and in lighting we mostly ignore it. A warm coral colour, for example, is the first of this lesson's colours:

colors: colors_constants = {
    .object_color = { 1.0, 0.5, 0.31 },    ; coral
    .light_color = { 1.0, 1.0, 1.0 },      ; under white light
}

full red, half green, and a little under a third of blue. (The second is the light's colour, white. The struct also has two floats of padding, which we come to below; the initialiser leaves them out, and anything a designated initialiser leaves out is zero.)

Colours are what gets reflected

Here is the part that makes lighting work. The colour we see when we look at an object is not something the object "has" on its own. It is the part of the incoming light that the object sends back towards us. Sunlight looks white because it carries a bit of every visible colour. When it hits a coral toy, the toy swallows most of the blue, a fair amount of the green, and throws back nearly all of the red. What reaches our eye is that leftover mix, and we call it coral.

White light hitting a coral object: most colours are absorbed, the reflected mix is coral (LearnOpenGL's diagram)

LearnOpenGL's diagram above shows the idea: white light arrives with every colour in it, and only the coral part leaves. (The real physics is richer than this, and the PBR chapters come back to it, but this picture carries us a long way.)

That gives us a precise meaning for "the colour of an object": for each of red, green and blue, the fraction of that channel's light the object reflects. And it gives us the rule for computing what we see. Take the light's colour and the object's colour, and multiply them channel by channel:

\[ \text{result} = (L_r \cdot O_r,\; L_g \cdot O_g,\; L_b \cdot O_b) \]

With white light, \(L = (1, 1, 1)\), the result is the object's colour unchanged, \((1.0, 0.5, 0.31)\): coral under white light looks coral, as it should. Now shine a pure green light on the same toy, \(L = (0, 1, 0)\). There is no red or blue arriving, so none can be reflected, and of the green that does arrive the toy sends back half:

light  = (0.0, 1.0, 0.0)
object = (1.0, 0.5, 0.31)
result = (0.0, 0.5, 0.0)     a dark green

The coral toy has turned dark green. Nothing about the object changed; it simply had no red light to give back. One more, with a murky olive light:

light  = (0.33, 0.42, 0.18)
object = (1.0,  0.5,  0.31)
result = (0.33, 0.21, 0.06)  a dull brown

This channel-by-channel product is the core of every lighting model we will write. In HLSL it costs nothing to say: multiplying two float3s with * multiplies them component by component. (That is not the same as mul, which is the matrix product we use for transforms.) SSE has the same operation, mulps, four floats at a time, but the lighting itself all happens in the shaders; the CPU side only hands over the colours.

A lighting scene

To experiment with light we need two things in the world: an object for the light to fall on, and something that shows where the light is. We use the cube from the previous chapters for both. A big one sits at the origin as our subject; a small one, scaled down to a fifth, marks the light's position. On its own a light is just a point in space with no shape at all, so this little light cube (LearnOpenGL calls it the lamp) is there only so we can see where the light is coming from.

The vertex data

The cube's vertex array already carries everything the lighting chapters will need, so it lives in includes/learn/cube.rasm and every lesson from here on imports it unchanged. Every vertex has a position, a normal (a direction pointing straight out of the face; the next chapter explains it) and a texture coordinate, eight floats in all:

#define CUBE_STRIDE 32
#define CUBE_LAYOUT_COUNT 3

cube_vertices: [288]const f32 = {            ; 36 vertices of 8 floats (an array count is one number or name)
    ; position             normal                 uv
    ; right (+x)
     0.5, -0.5,  0.5,     1.0,  0.0,  0.0,     0.0, 1.0,
     0.5, -0.5, -0.5,     1.0,  0.0,  0.0,     1.0, 1.0,
     0.5,  0.5, -0.5,     1.0,  0.0,  0.0,     1.0, 0.0,
; ...
}

Thirty-six vertices of eight floats, 32 bytes each. The size is part of the array's type, 288 floats, so sizeof(cube_vertices) is 1152 bytes wherever it is used, worked out from the declaration; there is no running byte count to keep in step with the table. (The count is written as one number because rin's parser takes one number or one name there, not 36 * 8.) The input layout names the three attributes and where each starts within a vertex, in bytes:

cube_layout: [CUBE_LAYOUT_COUNT]const D3D11_INPUT_ELEMENT_DESC = {
    { .SemanticName = "POSITION", .Format = DXGI_FORMAT.DXGI_FORMAT_R32G32B32_FLOAT, .AlignedByteOffset = 0 },
    { .SemanticName = "NORMAL", .Format = DXGI_FORMAT.DXGI_FORMAT_R32G32B32_FLOAT, .AlignedByteOffset = 12 },
    { .SemanticName = "TEXCOORD", .Format = DXGI_FORMAT.DXGI_FORMAT_R32G32_FLOAT, .AlignedByteOffset = 24 },
}

Each element names only the fields that are not zero. The semantic index, the input slot, the step rate and the classification (D3D11_INPUT_PER_VERTEX_DATA is 0) are all left out, so they are zero; the string literals become pooled strings whose addresses fill SemanticName. The byte offsets are 0, 12 and 24. When the buffer is created and bound, we give the stride, 32 bytes per vertex:

invoke(create_buffer, D3D11_BIND_FLAG.D3D11_BIND_VERTEX_BUFFER, cube_vertices&, sizeof(cube_vertices))
mov cube_vb, rax
stride: u32 = CUBE_STRIDE
offset: u32 = 0
vcall(context, ID3D11DeviceContextVtbl.IASetVertexBuffers, 0, 1, cube_vb&, stride&, offset&)

LearnOpenGL gives the light cube a VAO of its own, so that changing the container's attribute setup later cannot disturb the lamp. In Direct3D that question does not come up. There is no VAO: the input layout belongs to the shader (our shader_create builds one against each vertex shader), and the vertex buffer is bound separately, at draw time. Both cubes draw from the same buffer, each through its own shader's layout.

The light cube's vertex shader, as we will see, reads only POSITION. Creating an input layout with more elements than the shader uses is fine: Direct3D checks that every input the shader does read is supplied, and simply ignores the rest. So one cube_layout serves both shaders.

The transforms, shared by every shader

Each object needs its model matrix, and everybody needs the view and projection. In the earlier chapters a constant buffer carried these three. The lighting lessons extend it with two more members that the coming chapters need, a normal_matrix and the camera's position, view_position. Here is the HLSL side, which every shader in the lesson declares identically:

cbuffer transforms : register(b0)
{
    float4x4 model;
    float4x4 normal_matrix;
    float4x4 view;
    float4x4 projection;
    float3 view_position;
};

and the rasm struct that mirrors it, register for register. Every lesson from here to the end of the site uses it, so it lives in includes/learn/transforms.rasm:

transforms: struct = {
    model: mat4
    normal_matrix: mat4                    ; inverse transpose of model, for normals
    view: mat4
    projection: mat4
    view_position: vec3                    ; the eye, in world space
    pad: f32
}

The trailing pad is there because HLSL thinks of a constant buffer as a row of 16-byte registers, and a buffer's size must be a whole number of them. A float3 fills twelve bytes of its register; we pad the last four ourselves so the two sides agree on the size, and sizeof(transforms) comes out at 272, seventeen registers. (The normal matrix is computed, though the colours lesson does not use it yet; Basic Lighting explains it.)

Since the model matrix changes for every object while the rest stays the same within a frame, the lessons fill the view, projection and eye position once per frame:

; rcx: transforms, rdx: camera
;
; view from the camera, projection with its zoom as the field of view (0.1 to
; 100 units), and where the eye is.
transforms_from_camera: proc(t: *transforms, cam: *const camera) = {
    push rbx
    push rsi
    sub rsp, 40                            ; 32 shadow; entry 8 + two pushes 16 + 40 lands on 16
    mov rbx, rcx                           ; t
    mov rsi, rdx                           ; the camera
    lea rcx, [rbx].transforms.view
    invoke(camera_view, rcx, rsi)
    lea rcx, [rbx].transforms.projection
    invoke(camera_projection, rcx, rsi)
    lea rax, [rsi].camera.position
    v3load(xmm0, rax)
    lea rax, [rbx].transforms.view_position
    v3store(rax, xmm0)
    add rsp, 40
    pop rsi
    pop rbx
    ret
}

The proc writes its own frame, as every proc in these lessons does. Its two arguments have to survive the calls it makes, so they move into rbx and rsi, which a callee must preserve, and the proc pushes those two first to give them back unchanged. Then sub rsp, 40 reserves the 32 bytes of shadow space every call needs and puts rsp back on a multiple of 16: it was 8 off at entry, the pushes add 16, and 40 more makes 64. The comment on the sub says both, and the end undoes it in reverse. A field through a register is [rbx].transforms.view: the struct named, the offset worked out. And a small helper rewrites the buffer before each draw:

; rcx: constant buffer, rdx: transforms, r8: model matrix
;
; The model matrix and its normal matrix, sent; then the 36 vertices of the
; cube already bound. HLSL has no inverse(), so the normal matrix is worked
; out here, for every draw.
draw_cube: proc(buffer: *ID3D11Buffer, t: *transforms, model: *const mat4) = {
    push rbx
    push rsi
    push rdi
    sub rsp, 32                            ; 32 shadow; entry 8 + three pushes 24 + 32 lands on 16
    mov rbx, rcx                           ; buffer
    mov rsi, rdx                           ; t
    mov rdi, r8                            ; model
    m4_copy(rsi, rdi)                      ; t.model is at offset 0
    lea rcx, [rsi].transforms.normal_matrix
    invoke(m4_normal_matrix, rcx, rdi)
    invoke(update_buffer, rbx, rsi, sizeof(transforms))
    vcall(context, ID3D11DeviceContextVtbl.Draw, 36, 0)
    add rsp, 32
    pop rdi
    pop rsi
    pop rbx
    ret
}

m4_copy is a macro from math.rasm, not a call:

m4_copy: macro(dst, src) = {
    movups xmm0, xmmword ptr [src]
    movups xmmword ptr [dst], xmm0
    movups xmm0, xmmword ptr [src + 16]
    movups xmmword ptr [dst + 16], xmm0
    movups xmm0, xmmword ptr [src + 32]
    movups xmmword ptr [dst + 32], xmm0
    movups xmm0, xmmword ptr [src + 48]
    movups xmmword ptr [dst + 48], xmm0
}
The macro's lines are pasted in where it is used, with dst and src replaced by rsi and rdi. The result is four 16-byte copies, one matrix row each, with no counter and no branch. model is the first member of transforms, so the copy goes to offset 0 of t. movups rather than movaps because nothing promises the matrices are 16-byte aligned.

update_buffer, from gpu.rasm, maps the buffer with D3D11_MAP_WRITE_DISCARD, copies the struct in with mem_copy and unmaps it. Discarding means the driver hands us fresh memory each time, so the copy for the second cube never has to wait for the GPU to finish drawing the first.

The lighting shader

The cube we light gets colors.hlsl. Its vertex shader already does more than this chapter needs: it works out the vertex's world position and normal and passes them on, ready for the next chapter. For now the pixel shader ignores them. It needs only two colours, which arrive in a second constant buffer, in register b1:

cbuffer colors : register(b1)
{
    float3 object_color;
    float3 light_color;
};

float4 ps_main(vs_out p) : SV_Target
{
    return float4(light_color * object_color, 1.0);
}

That is the rule from the start of the chapter, in one line. The rasm side of the buffer has a padding float after each colour:

; Mirrors `cbuffer colors` in colors.hlsl: a float3 fills a register only
; with the float after it.
colors_constants: struct = {
    object_color: vec3
    pad0: f32
    light_color: vec3
    pad1: f32
}

Why after object_color too? HLSL's packing rule says a value may not straddle a register boundary. object_color occupies bytes 0 to 11 of the first register; light_color needs twelve bytes, which do not fit in the four left over, so HLSL starts it at byte 16. Our struct must leave the same gap, or the light colour would be read from the wrong place. Getting this wrong produces no error at all, just strange colours, so it is worth checking every time a constant buffer changes.

A float3 followed by a float share one register; a float3 followed by another float3 do not. Whenever you add a member to a cbuffer, add it to the rasm struct in the same place and work out where the padding goes. A rasm struct is laid out as C lays it out, and C knows nothing of HLSL's registers: a vec3 is three floats aligned to 4, so a second one would follow the first at byte 12. Every gap is one you put there.

The initialiser we started the chapter with names the two colours, so it does not depend on where the padding sits, and the two pads it leaves out are zero.

The light cube's shader

In the coming chapters the lighting shader will change a lot: ambient light, highlights, falloff. None of that should touch the light cube, which ought to stay bright whatever we do, since it stands for the light itself. So it has a shader file of its own, light_cube.hlsl, that is never edited:

cbuffer lamp : register(b1)
{
    float4 lamp_color;
};

float4 vs_main(float3 position : POSITION) : SV_Position
{
    return mul(projection, mul(view, mul(model, float4(position, 1.0))));
}

float4 ps_main() : SV_Target
{
    return lamp_color;
}

It declares the same transforms buffer at b0 (left out above) and ignores everything but the model, view and projection. Where LearnOpenGL's lamp shader hard-codes white, ours reads its colour from a buffer of its own, also at b1. That costs one float4, sixteen bytes, and later chapters use it to tint each light cube to match its light. Here it is a constant, in read-only memory:

lamp_color: const vec4 = { 1.0, 1.0, 1.0, 1.0 }

Both shaders are compiled from their files at startup, with the same layout, and each constant buffer is made at the size of the struct it will carry:

invoke(shader_create, lighting_shader&, "src/2.lighting/1.colors/colors.hlsl", cube_layout&, CUBE_LAYOUT_COUNT)
invoke(shader_create, lamp_shader&, "src/2.lighting/1.colors/light_cube.hlsl", cube_layout&, CUBE_LAYOUT_COUNT)
invoke(create_constant_buffer, sizeof(transforms))
mov transforms_buffer, rax
invoke(create_constant_buffer, sizeof(colors_constants))
mov colors_buffer, rax
invoke(create_constant_buffer, sizeof(vec4))
mov lamp_buffer, rax

Registers are shared

Notice that two different buffers, colors and lamp, both live in register b1. That is fine, because a register is just a slot on the pipeline: whatever buffer we bind there before a draw is what that draw's shaders see. The bind_constants helper from gpu.rasm binds a buffer to the same slot of the vertex, geometry and pixel stages at once:

bind_constants_buffer: *ID3D11Buffer = {}  ; the array of one that the Set calls take

; ecx: register (b0, b1, ...), rdx: buffer
;
; The same buffer in the same register for the vertex, geometry and pixel stages.
bind_constants: proc(slot: u32, buffer: *ID3D11Buffer) = {
    push rbx
    sub rsp, 32                            ; 32 shadow; entry 8 + push 8 + 32 lands on 16
    mov ebx, ecx
    mov bind_constants_buffer, rdx
    vcall(context, ID3D11DeviceContextVtbl.VSSetConstantBuffers, rbx, 1, bind_constants_buffer&)
    vcall(context, ID3D11DeviceContextVtbl.GSSetConstantBuffers, rbx, 1, bind_constants_buffer&)
    vcall(context, ID3D11DeviceContextVtbl.PSSetConstantBuffers, rbx, 1, bind_constants_buffer&)
    add rsp, 32
    pop rbx
    ret
}

The Set methods take an array of buffers. Ours is an array of one: bind_constants_buffer, a global named after the proc that uses it, which is where an assembly proc keeps anything it must hand over by address. The slot moves to rbx because vcall loads rcx with this, the context, before the other arguments.

The transforms go to b0 once per frame and stay there for every draw; the lighting lessons keep their own constants at b1 and up. This takes the place of OpenGL's glUniform calls: instead of setting named variables one by one on a program object, we fill a struct and hand the whole thing to a slot.

Drawing it

The light sits at a fixed point in the world, up and to the right of the cube and a little towards the camera:

light_position: const vec3 = { 1.2, 1.0, 2.0 }

Each frame window_begin clears the window to clear_color, a constant array of four floats passed by address, we bind the cube and the transforms, fill in the view and projection, then draw the coral cube with the lighting shader and the small cube with the lamp shader. The light cube's model matrix moves it to the light's position and shrinks it to 0.2 of its size; m4_translate_scale builds translate times scale in one go, so the scale happens first:

clear_color: [4]const f32 = { 0.1, 0.1, 0.1, 1.0 }
invoke(window_begin, clear_color&)
vcall(context, ID3D11DeviceContextVtbl.IASetPrimitiveTopology, D3D11_PRIMITIVE_TOPOLOGY.D3D11_PRIMITIVE_TOPOLOGY_TRIANGLELIST)
vcall(context, ID3D11DeviceContextVtbl.IASetVertexBuffers, 0, 1, cube_vb&, stride&, offset&)
invoke(bind_constants, 0, transforms_buffer)
invoke(transforms_from_camera, t&, cam&)

; the object: coral, under white light
invoke(update_buffer, colors_buffer, colors&, sizeof(colors_constants))
invoke(shader_use, lighting_shader&)
invoke(bind_constants, 1, colors_buffer)
lea rcx, model
call m4_identity
invoke(draw_cube, transforms_buffer, t&, model&)

; the lamp: a small white cube where the light is
invoke(update_buffer, lamp_buffer, lamp_color&, sizeof(vec4))
invoke(shader_use, lamp_shader&)
invoke(bind_constants, 1, lamp_buffer)
lea rcx, model
lea rdx, light_position
movss xmm2, 0.2                        ; the scale, the third argument
call m4_translate_scale
invoke(draw_cube, transforms_buffer, t&, model&)
m4_translate_scale takes a float as its third argument, so the call is made by hand: the two addresses in rcx and rdx, and 0.2 in xmm2, the register of the third position. An SSE register cannot take a float straight from the instruction, so a float literal in rasm is memory: movss xmm2, 0.2 loads a constant the assembler pools in .rdata.

All of this runs inside main, whose frame is set once at the top:

main: proc() -> i32 = {
    sub rsp, 56                            ; IASetVertexBuffers: 5 past `this`, 2 on the stack: 32 + 16; entry 8 + 56 lands on 16

The biggest call it makes decides the size: IASetVertexBuffers takes five arguments after this, so two go on the stack above the shadow space. main ends in invoke(ExitProcess, 0), which does not return, so it has no epilogue.

The camera starts in front of the cube and a little to its left, turned slightly to look at it, so the light cube appears near the right edge of the window. If everything is in place, you get this:

A flat coral cube in the middle of the window, and a small white cube at the top right marking the light

Admittedly not much to look at: a flat coral shape and a white square. Every face of the cube has exactly the same colour, because nothing in our shader yet cares which way a face points or where the light is. That changes in the very next chapter. As before, WASD moves the camera, space and shift move it up and down, and holding the right mouse button lets you look around.

The full program is here, the lighting shader here and the light cube's shader here.

Additional resources

Exercises

  1. Change the light colour in colors to pure green, .light_color = { 0.0, 1.0, 0.0 }, and check that the cube turns the dark green worked out above. Then try the olive light { 0.33, 0.42, 0.18 }.
  2. Make the light cube show the light's colour, by copying colors.light_color into lamp_color before the lamp's buffer is updated, instead of leaving it white. lamp_color is const, in read-only memory, so take the const off first. (v3load_var and v3store_var in math.rasm move a vec3 field; the alpha can stay 1.)
  3. Move pad0 in colors_constants so that it sits after light_color, next to pad1. The initialiser names its fields, so it needs no change; the struct keeps its size, so nothing fails, but the cube changes colour. Work out from the packing rule which bytes the shader now reads as light_color, and explain the colour you see. (Put the padding back afterwards.)
Credit: this chapter follows LearnOpenGL's Colors by Joey de Vries, rewritten for Direct3D 11 and x64 assembly in rasm. LearnOpenGL's text and code are licensed CC BY-NC 4.0, and so is this page; the wording, code and screenshots here are new, and diagrams marked as LearnOpenGL's are its own.