Textures

In the last chapter we coloured a triangle by giving each vertex a colour and letting the rasterizer blend them. That only goes so far. To draw something with real detail, a wooden crate or a brick wall, we would need a vertex wherever the colour changes, which means a huge number of vertices, each carrying its own colour.

The usual answer is a texture: an image that we stretch over the surface of our geometry, like a printed sticker on a box. A single image can hold as much detail as we like, and the geometry under it can stay simple. Textures can hold other kinds of data too, as later chapters will show, but here they are just pictures.

To put an image on a shape, each vertex has to say which point of the image it corresponds to. That point is the vertex's texture coordinate. The rasterizer interpolates texture coordinates across the triangle like any other vertex output, so every pixel ends up with its own coordinate, and the pixel shader looks up the image's colour there. Looking up a texture's colour at a coordinate is called sampling.

Texture coordinates

Texture coordinates run from 0 to 1 along each axis of the image, whatever its size in pixels. They are usually called \(u\) (across) and \(v\) (down), and in Direct3D they start at the image's top-left corner: \((0, 0)\) is the top-left, \((1, 0)\) the top-right, \((0, 1)\) the bottom-left and \((1, 1)\) the bottom-right.

F u v (0, 0)(1, 0) (0, 1)(1, 1) the image, as stored: top row first F (-0.5, 0.5)uv (0, 0) (0.5, 0.5)uv (1, 0) (-0.5, -0.5)uv (0, 1) (0.5, -0.5)uv (1, 1) our rectangle's vertices

This is the opposite of OpenGL, where \((0, 0)\) is the bottom-left of a texture, and it is the one convention in this chapter that differs. Image files store their top row first; Direct3D puts the first row it is given at \(v = 0\), and so the two agree, and an image loaded straight from a file is the right way up. OpenGL puts the first row at the bottom, which is why LearnOpenGL has to flip images while loading them. We don't, ever.

This lesson textures the rectangle from Hello Triangle. Each vertex now has a position followed by its texture coordinate, five floats in all:

; x, y, z, then u, v. D3D's texture coordinate (0, 0) is the image's
; top-left, where GL's is its bottom-left, so nothing is flipped on load.
rectangle_vertices: [20]const f32 = {
    -0.5, -0.5, 0.0,   0.0, 1.0,
     0.5, -0.5, 0.0,   1.0, 1.0,
     0.5,  0.5, 0.0,   1.0, 0.0,
    -0.5,  0.5, 0.0,   0.0, 0.0,
}

The top corners of the rectangle (positive \(y\)) take \(v = 0\), the top of the image, and the bottom corners take \(v = 1\). The four corners of the image land on the four corners of the rectangle, and everything between is filled in by interpolation.

That describes which point of the image each pixel wants. How the image is read there is a separate question, and it has several possible answers. In Direct3D they are collected into a separate object, the sampler, whose settings are the subject of the next three sections.

Texture wrapping

Nothing stops a texture coordinate from going below 0 or above 1. What the sampler does then is its address mode. Direct3D's main modes, with OpenGL's names for comparison:

Here they are along one axis, with the image in the middle (from 0 to 1, dashed) and a copy's width either side:

F F F WRAP F F F MIRROR F CLAMP F BORDER

The mode is set separately for each axis, in the sampler description's AddressU, AddressV and AddressW (the last is for 3D textures). This lesson wraps on all three; none of its coordinates leave 0..1 yet, but the exercises change that.

Texture filtering

A texture coordinate is a pair of real numbers, but an image is a grid of pixels. To avoid confusion with the pixels on screen, a texture's pixels are called texels. A coordinate almost never lands exactly on the centre of a texel, so the sampler has to decide what colour to return for the point in between. That is texture filtering, and there are two basic choices.

Point filtering (OpenGL's GL_NEAREST) returns the texel whose centre is nearest to the coordinate. In LearnOpenGL's diagram the cross marks the coordinate, and the top-left texel wins:

Point filtering: the texel whose centre is nearest the sample point is returned (LearnOpenGL's diagram)

Linear filtering (GL_LINEAR) blends the four texels around the coordinate, each weighted by how close the coordinate is to its centre. The result is a colour in between them:

Linear filtering: the four nearest texels are blended by distance (LearnOpenGL's diagram)

The difference shows when a small texture is stretched over a large area, so that each texel covers many pixels on screen. Point filtering then shows the texels as hard-edged blocks, the look of old pixel-art games. Linear filtering gives a smooth, slightly blurry image without visible blocks, which is what we want most of the time.

The filter can be chosen separately for magnification, when the texture is drawn larger than its real size, and minification, when it is drawn smaller. OpenGL sets each with its own parameter. Direct3D has one Filter field, whose values name every combination: D3D11_FILTER_MIN_MAG_MIP_POINT uses point filtering throughout, D3D11_FILTER_MIN_MAG_MIP_LINEAR linear throughout, and in between are values such as D3D11_FILTER_MIN_LINEAR_MAG_MIP_POINT. The third word in those names, MIP, needs one more idea.

Mipmaps

Picture a long floor covered in one tiled texture. Near the camera, a texel covers a few screen pixels. Far away, a single screen pixel covers dozens of texels. Sampling just one or four of those texels picks an essentially random colour out of the many the pixel covers, and as the camera moves, which texels get picked changes from frame to frame. Distant surfaces shimmer and sparkle. Reading a large texture to draw a few pixels is also slow, because it uses the GPU's memory caches badly.

The fix is to prepare smaller copies of the texture in advance, each half the width and height of the one before, down to a single texel. These are mipmaps, and together they form the texture's mip chain:

A texture and its mipmaps, each half the size of the previous one (LearnOpenGL's diagram)

When sampling, the GPU estimates how many texels one screen pixel covers and reads from the level where that is about one. Distant surfaces read small, pre-averaged levels, which is both stable and fast. The whole chain costs only a third more memory than the full-size image. The level with the full image is level 0; a 512 by 512 texture, like the crate in this lesson, has ten levels, ending at 1 by 1.

The sampler then has one more choice to make: whether to use the single nearest level (point) or to blend between the two nearest levels (linear), which hides the visible seam where one level gives way to the next. That is the MIP part of the filter names. D3D11_FILTER_MIN_MAG_MIP_LINEAR, linear within each level and between levels, is often called trilinear filtering, and corresponds to OpenGL's GL_LINEAR_MIPMAP_LINEAR with a GL_LINEAR magnification filter.

LearnOpenGL warns against giving OpenGL a mipmap filter for magnification, which is an error there. Direct3D's single Filter value can't be wrong in that way: mip levels only ever come into play when a texture is minified, and when it is magnified, level 0 is used whatever the filter says.

Our sampler

The lesson creates one sampler at startup and binds it:

; A sampler: how textures are filtered and what happens past their edges.
; Anisotropic filtering stays sharp on surfaces seen at a slant; wrap
; repeats the image.
invoke(create_sampler, D3D11_FILTER.D3D11_FILTER_ANISOTROPIC, D3D11_TEXTURE_ADDRESS_MODE.D3D11_TEXTURE_ADDRESS_WRAP)
mov sampler, rax
vcall(context, ID3D11DeviceContextVtbl.PSSetSamplers, 0, 1, sampler&)

create_sampler is in learn/gpu.rasm, since every later lesson needs a sampler or two. It takes the filter and one address mode for all three axes:

; create_sampler's
create_sampler_desc: D3D11_SAMPLER_DESC = {
    .MaxAnisotropy = 8,
    .ComparisonFunc = D3D11_COMPARISON_FUNC.D3D11_COMPARISON_NEVER,
    .MaxLOD = D3D11_FLOAT32_MAX,
}
create_sampler_out: *ID3D11SamplerState = {}

; ecx: filter, edx: address mode -> rax: ID3D11SamplerState
;
; How textures are filtered, and what happens past their edges.
create_sampler: proc(filter: D3D11_FILTER, address: D3D11_TEXTURE_ADDRESS_MODE) -> *ID3D11SamplerState = {
    sub rsp, 40                            ; 32 shadow, and rsp back on 16
    mov create_sampler_desc.Filter, ecx
    mov create_sampler_desc.AddressU, edx
    mov create_sampler_desc.AddressV, edx
    mov create_sampler_desc.AddressW, edx
    vcall(device, ID3D11DeviceVtbl.CreateSamplerState, create_sampler_desc&, create_sampler_out&)
    assert_hr()
    mov rax, create_sampler_out
    add rsp, 40
    ret
}

The filter is a step beyond trilinear. Anisotropic filtering is for surfaces seen at a slant, like that long floor, where a screen pixel covers a long thin strip of texels rather than a square patch. Trilinear filtering has to pick a mip level small enough for the strip's length, which blurs it across its width. Anisotropic filtering instead takes several samples along the strip, here up to MaxAnisotropy = 8 of them, and keeps the surface sharp. On a rectangle facing the camera squarely, as ours does, it gives the same result as trilinear.

What never changes between samplers is in the initialiser, and the procedure stores only the filter and the address modes. MaxLOD is the highest mip level the sampler may use (LOD, level of detail, is another name for the mip level). Setting it to the largest float means "no limit", and the initialiser can say so by name: D3D11_FLOAT32_MAX is the header's own #define, 3.402823466e+38f, and an initialiser is a C constant expression, folded by the C compiler when the data file is built. ComparisonFunc only matters for the comparison samplers of Shadow Mapping; it is set to a valid value here so the description holds no zero that means nothing. The parameters are typed with their enums, filter: D3D11_FILTER, which is documentation like every parameter list; the values arrive as 32 bits in ecx and edx, the size of the fields they are stored into.

Don't leave MaxLOD at zero. Every field an initialiser does not name is zero, but for this field zero means "use no level past level 0", which switches mipmapping off without any error: distant textures simply shimmer. The address modes must not be left at zero either, since zero is not a valid mode, and creating the sampler then fails.

Samplers are bound to sampler slots of a shader stage, as constant buffers are bound to theirs, here slot 0 of the pixel shader. The binding stays until it is replaced, so this lesson binds its only sampler once, before the render loop, and never again. OpenGL stores filtering and wrapping on each texture object; Direct3D keeps them apart, so any texture can be read with any sampler, and one sampler serves every texture that wants the same treatment.

Loading and creating textures

Before we can use an image we have to get its pixels out of a file. Image formats are complicated, each in its own way: PNG compresses losslessly, JPEG approximates the image with frequency components, and both have many variants. Writing a loader for even one of them is a project. LearnOpenGL uses stb_image.h, a popular single-file C library. We don't need a library at all: Windows comes with the Windows Imaging Component, WIC, which decodes PNG, JPEG, BMP, GIF, TIFF and more. Our includes/image.rasm wraps it in one procedure.

image.rasm

WIC is a COM API like Direct3D. Its starting point is an imaging factory, created once:

; The WIC factory, and the arena, on first use.
image_init: proc() = {
    sub rsp, 40                            ; CoCreateInstance takes 5: 32 + 8, and rsp lands on 16
    cmp image_wic, 0
    jne done
    cmp arena.base, 0
    jne have_arena
    invoke(arenaInit, arena&)
  have_arena:
    invoke(CoInitializeEx, 0, COINIT.COINIT_MULTITHREADED)
    invoke(CoCreateInstance, CLSID_WICImagingFactory2&, 0, CLSCTX.CLSCTX_INPROC_SERVER, IID_IWICImagingFactory&, image_wic&)
    assert_hr()
  done:
    add rsp, 40
    ret
}

CoInitializeEx starts COM for the program, and CoCreateInstance creates an object by its class ID, here the factory. (Direct3D didn't need this step because D3D11CreateDeviceAndSwapChain creates its objects itself.) The class ID is CLSID_WICImagingFactory2, which is what the header's CLSID_WICImagingFactory stands for today; it and the interface's ID are GUIDs from windowscodecs.lib and dxguid.lib, passed by address. The procedure also makes sure the program's arena exists, the one large block of memory from saha.rasm that file contents and images are taken from. image_load then asks the factory for a decoder for the file, takes its first frame (a GIF can have several; our images have one), and converts it:

vcall(image_wic, IWICImagingFactoryVtbl.CreateFormatConverter, image_load_converter&)
; Whatever the file holds, convert it to 8-bit RGBA. The fifth argument
; past `this`, alphaThresholdPercent, is a double on the stack; 0 as 64
; bits is 0.0.
vcall(image_load_converter, IWICFormatConverterVtbl.Initialize, image_load_frame, GUID_WICPixelFormat32bppRGBA&,
      WICBitmapDitherType.WICBitmapDitherTypeNone, 0, 0, WICBitmapPaletteType.WICBitmapPaletteTypeCustom)
vcall(image_load_converter, IWICFormatConverterVtbl.GetSize, image_load_w&, image_load_h&)
mov eax, image_load_w
mul image_load_h
shl rax, 2
mov image_load_bytes, rax
invoke(arenaPush, arena&, rax, 16)
mov [rbx].image.pixels, rax
mov eax, image_load_w
mov [rbx].image.width, eax
mov eax, image_load_h
mov [rbx].image.height, eax
mov eax, image_load_w
shl eax, 2                             ; the stride
vcall(image_load_converter, IWICFormatConverterVtbl.CopyPixels, 0, rax, image_load_bytes, [rbx].image.pixels)

One argument deserves a look first. The fifth argument of Initialize after the object is a double, the alpha threshold. A float argument goes in the xmm register of its position, but only the first four positions have registers, and the object takes one of them; from the fifth on, every argument, float or not, is eight bytes on the stack. And 0.0 is all zero bits, so a plain 0 passes it. With three stack arguments, image_load's frame is 32 + 24, as its comment says.

The format converter turns whatever the file contains (three channels for a JPEG, possibly a palette or 16-bit channels for a PNG) into one fixed layout: 32 bits per pixel, red, green, blue and alpha, one byte each. CopyPixels writes them, top row first, into memory pushed onto the arena with arenaPush, which lives as long as the program (so there is no counterpart of stbi_image_free to call). The size is the width times the height times four bytes: mul image_load_h multiplies eax by that 32-bit global into edx:eax, and shl rax, 2 multiplies by four. The decoder, the frame, the converter and the sizes are globals named after the procedure, image_load_converter and so on. The result goes into a small structure that the caller passes by address, and which image_load keeps in rbx:

image: struct = {
    pixels: *u8                            ; RGBA8, width * height * 4 bytes (image_load_hdr: 4 floats a pixel)
    width: u32
    height: u32
}

Always converting to four channels spares us a detail LearnOpenGL has to handle: telling GL_RGB images from GL_RGBA ones. Direct3D has no 8-bit three-channel texture format anyway, so even a JPEG with no alpha becomes RGBA, with alpha 255.

Generating a texture

With the pixels in memory, load_texture creates a texture from them. It plays the part of LearnOpenGL's loadTexture function, and lives in learn/gpu.rasm, where every later lesson finds it. Most of the texture's description is the same for every image, so it is a global with an initialiser:

; load_texture's
load_texture_image: image = {}
load_texture_desc: D3D11_TEXTURE2D_DESC = {
    .MipLevels = 0,                        ; the whole chain
    .ArraySize = 1,
    .SampleDesc = { .Count = 1 },
    ; Generating mips draws into the texture, so it is a render target too.
    .BindFlags = D3D11_BIND_FLAG.D3D11_BIND_SHADER_RESOURCE | D3D11_BIND_FLAG.D3D11_BIND_RENDER_TARGET,
    .MiscFlags = D3D11_RESOURCE_MISC_FLAG.D3D11_RESOURCE_MISC_GENERATE_MIPS,
}
load_texture_texture: *ID3D11Texture2D = {}
load_texture_srv: *ID3D11ShaderResourceView = {}

and the procedure stores only the size and the format:

; rcx: path, edx: 1 for colour data -> rax: ID3D11ShaderResourceView
; ...
load_texture: proc(path: *const c8, srgb: b32) -> *ID3D11ShaderResourceView = {
    push rbx
    push rsi
    sub rsp, 56                            ; UpdateSubresource takes 7: 32 + 24; entry 8 + 16 + 56 lands on 16
    mov rbx, rcx                           ; path
    mov esi, edx                           ; srgb
    invoke(image_load, load_texture_image&, rbx)
    test rax, rax
    jnz loaded
    invoke(print, "Texture failed to load at path: %s\n", rbx)
    invoke(ExitProcess, 1)
  loaded:
    mov eax, load_texture_image.width
    mov load_texture_desc.Width, eax
    mov eax, load_texture_image.height
    mov load_texture_desc.Height, eax
    mov load_texture_desc.Format, DXGI_FORMAT.DXGI_FORMAT_R8G8B8A8_UNORM
    test esi, esi
    jz linear
    mov load_texture_desc.Format, DXGI_FORMAT.DXGI_FORMAT_R8G8B8A8_UNORM_SRGB
  linear:
    vcall(device, ID3D11DeviceVtbl.CreateTexture2D, load_texture_desc&, 0, load_texture_texture&)
    assert_hr()
    vcall(device, ID3D11DeviceVtbl.CreateShaderResourceView, load_texture_texture, 0, load_texture_srv&)
    mov eax, load_texture_image.width
    shl eax, 2                             ; the row pitch
    vcall(context, ID3D11DeviceContextVtbl.UpdateSubresource, load_texture_texture, 0, 0, load_texture_image.pixels, rax, 0)
    vcall(context, ID3D11DeviceContextVtbl.GenerateMips, load_texture_srv)
    release(load_texture_texture)          ; the view keeps it alive
    mov rax, load_texture_srv
    add rsp, 56
    pop rsi
    pop rbx
    ret
}

This is the longest description so far, so let's take it field by field.

The Usage field is not named, so it is zero, which is D3D11_USAGE_DEFAULT: memory the GPU reads and writes, which the CPU can only update through the context. With the description complete, four calls finish the job:

  1. CreateTexture2D creates the texture. We pass no initial data, the 0: initial data has to cover every mip level, and we only have level 0.
  2. CreateShaderResourceView creates the view a shader reads the texture through. With no view description it covers the whole texture, all its levels.
  3. UpdateSubresource copies our pixels into subresource 0, which for this texture is mip level 0. The 0 after the subresource is the box to update, and none means the whole level; after the pixels comes the row pitch, the number of bytes from the start of one row to the next: four bytes per texel, times the width, worked out with a shift by two. The pitch is the fifth argument after the object, a stack argument, so rax can carry it.
  4. GenerateMips fills in every other level from level 0, the counterpart of glGenerateMipmap. It takes the shader resource view, and generates all the levels the view covers.

The procedure returns the view. That is all the rest of the program needs: shaders read textures through views, never through the texture object itself. So the procedure's own pointer to the texture is released: the view holds a reference of its own, which keeps the texture alive as long as the view is.

The lesson loads two textures this way, a wooden crate and a smiling face, both from resources/textures:

invoke(filesystem_path, "resources/textures/container.jpg")
invoke(load_texture, rax, 0)
mov textures[0], rax
invoke(filesystem_path, "resources/textures/awesomeface.png")
invoke(load_texture, rax, 0)
mov textures[1], rax                   ; an index counts elements, not bytes: textures[1] is 8 bytes in

textures is an array of two pointers in the data section, textures: [2]*ID3D11ShaderResourceView = {}. An index on a typed global counts elements, as in C, so the second pointer is textures[1], and rasm works out that it is 8 bytes in. The path that filesystem_path returns in rax is passed straight on: rax is safe as any argument of invoke.

Applying textures

The vertices have a texture coordinate now, so the input layout describes it, right after the position:

vertex_layout: [2]const D3D11_INPUT_ELEMENT_DESC = {
    { .SemanticName = "POSITION", .Format = DXGI_FORMAT.DXGI_FORMAT_R32G32B32_FLOAT, .AlignedByteOffset = 0 },
    { .SemanticName = "TEXCOORD", .Format = DXGI_FORMAT.DXGI_FORMAT_R32G32_FLOAT, .AlignedByteOffset = 12 },
}

DXGI_FORMAT_R32G32_FLOAT is two floats, \(u\) and \(v\), starting 12 bytes into the vertex. A vertex is five floats, so the stride we bind the vertex buffer with is 20 bytes, stride: u32 = 20. The rectangle is drawn with the same index buffer as in Hello Triangle, two triangles from four vertices.

The vertex shader passes the coordinate through to the pixel shader, so that it is interpolated across the rectangle:

struct vs_out
{
    float4 position : SV_Position;
    float2 uv : TEXCOORD;
};

vs_out vs_main(float3 position : POSITION, float2 uv : TEXCOORD)
{
    vs_out o;
    o.position = float4(position, 1.0);
    o.uv = uv;
    return o;
}

The inputs are plain parameters this time, each with its semantic, rather than a struct: HLSL accepts either. The pixel shader needs the textures and the sampler, and they are declared at the top of the file:

Texture2D crate : register(t0);
Texture2D face : register(t1);
SamplerState linear_wrap : register(s0);

A Texture2D is a 2D texture the shader reads, through a view bound to a texture slot: register(t0) is slot 0, t1 slot 1. A SamplerState is a sampler, in sampler slot s0. GLSL combines both into one sampler2D variable; HLSL keeps them apart, matching Direct3D's separate objects. Sampling then takes both, in method-call form:

float4 ps_main(vs_out p) : SV_Target
{
    return lerp(crate.Sample(linear_wrap, p.uv), face.Sample(linear_wrap, p.uv), 0.2);
}

crate.Sample(linear_wrap, p.uv) reads the crate texture at the pixel's interpolated coordinate, filtered and addressed as the sampler says, and returns a float4 colour. GLSL writes texture(sampler, uv). The face is sampled the same way, with the same sampler, and the two are blended with lerp, HLSL's name for GLSL's mix: lerp(a, b, t) is \(a + (b - a)\,t\), so with \(t = 0.2\) we get 80% crate and 20% face.

Texture units

OpenGL has texture units: we activate a unit, bind a texture to it, and tell each sampler2D uniform which unit to read with glUniform1i. Direct3D's texture slots play the same role, and the shader states which slot each texture lives in, as we saw with register(t0) and register(t1), so there is nothing to tell it from the program. All that remains is to bind the two views to those slots, which one call does, since slots are consecutive:

; the two textures, in registers t0 and t1
vcall(context, ID3D11DeviceContextVtbl.PSSetShaderResources, 0, 2, textures&)

Starting at slot 0, bind two views from the array: the crate to t0 and the face to t1. Each stage has 128 texture slots and 16 sampler slots, which is more than enough. Then the usual drawing calls follow, and this is the result:

The crate texture on the rectangle, with the smiling face blended faintly over it

One happy crate, the right way up, without flipping anything. The image looks stretched sideways because the rectangle spans half the window in each direction, and the window is wider than it is tall. That gets fixed when we add a projection matrix in Coordinate Systems.

The full program is here, its shaders here, the image loader here, and load_texture and create_sampler here.

Additional resources

Exercises

  1. Change only the pixel shader so that the face looks the other way, while the crate stays as it is.
  2. Change the texture coordinates to run from 0 to 2 instead of 0 to 1, so the face appears four times. Then try each address mode on the sampler. Finally, make the crate clamp while the face still repeats: you'll need a second sampler from create_sampler, with D3D11_TEXTURE_ADDRESS_CLAMP, bound to slot s1 and used for one of the two textures.
  3. Choose texture coordinates that show only a small area in the middle of the textures, so that each texel covers many pixels. Set the filter to D3D11_FILTER_MIN_MAG_MIP_POINT and compare it with linear filtering.
  4. Put the 0.2 blend amount in a constant buffer, as in the Shaders chapter, and change it with the up and down arrow keys while they are held (invoke(key_down, VK_UP) and VK_DOWN, from learn/window.rasm).
Credit: this chapter follows LearnOpenGL's Textures 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.