Creating a window

Before we can draw anything we need two things from the operating system: a window to draw in, and a connection to the GPU that can put pictures into that window. Neither is part of a graphics API's core. OpenGL deliberately leaves windows to the platform, which is why LearnOpenGL starts by installing GLFW, a small library that opens a window and creates an OpenGL context on any desktop system, and GLAD, which fetches OpenGL's functions from the driver.

We are on one platform only, and on Windows both jobs are short. Opening a window takes a handful of Win32 calls, and Direct3D 11 creates its own device and swap chain for that window in one function. So we use no windowing library at all. The first two lessons write that code out themselves, and the next chapter goes through it line by line; from the third lesson on it lives in one include, learn/window.rasm, which plays GLFW's part.

What this chapter covers instead is the part LearnOpenGL spends on building GLFW and setting up a Visual Studio project: the tools that turn our source files into programs, how a lesson is laid out on disk, how a program is debugged at its source lines, and how the programs find their shaders and images when they run.

The toolchain

Our programs are written in x64 assembly, in rasm. A .rasm file has two kinds of thing in it. Its declarations, of types, data, constants and procedures, are written the way rin (or C) writes them: structs, enums, globals with designated initialisers, #defines and imports. The bodies of its procedures are plain Intel-syntax x64 instructions, and nothing else: rasm writes no prologue, no frame and no argument moves of its own. Each tool in the chain does one job:

clang has to be on the PATH, since rin asm runs it by name. The build script finds rin.exe itself: the RIN environment variable if it is set, else the rin repository's build\rin.exe, else rin on the PATH.

Nothing else needs installing. LearnOpenGL's projects depend on GLFW, GLAD, GLM and stb_image. Our equivalents are all either part of Windows (Win32 windows, Direct3D, the shader compiler in d3dcompiler.dll, the image decoders of the Windows Imaging Component) or .rasm files in the repository's includes/ folder. Even the declarations of the Windows API, the part an assembler usually takes from an SDK of its own, are in the repository, generated from the Windows SDK's headers; more on that below.

Building the lessons

Get the lessons from GitHub, open a terminal in the repository's top folder and run

python build.py
build\hello_window.exe

The first command builds every lesson. The second runs the first one, which should open a window filled with a dark teal colour. If it does, every tool is in place. Given an argument, the script builds only the lessons whose file names contain it: python build.py hello builds hello_window and hello_triangle.

build.py

There is no project file and no build system. build.py is a short script, and the heart of it is one list and a loop. Here they are, with the checks around them cut:

LIBS = ["d3d11", "d3dcompiler", "dxguid", "ole32", "windowscodecs"]   # kernel32 and user32 always
...
    lessons = sorted((ROOT / "src").rglob("*.rasm"))
    ...
    for src in lessons:
        ...
        exe = ROOT / "build" / f"{src.stem}.exe"
        cmd = [rin, "asm", str(src.relative_to(ROOT)), "-o", str(exe.relative_to(ROOT))]
        for lib in LIBS:
            cmd += ["-l", lib]
        r = subprocess.run(cmd, cwd=ROOT, capture_output=True, text=True)

The loop visits every .rasm file under src/, thirty-eight of them, one per lesson, and makes each a separate executable named after its file. For each one it runs rin asm once, which for the second lesson is

rin asm src/1.getting_started/2.1.hello_triangle/hello_triangle.rasm -o build/hello_triangle.exe
        -l d3d11 -l d3dcompiler -l dxguid -l ole32 -l windowscodecs

and rin asm in turn writes build/rasm/hello_triangle.s and build/rasm/hello_triangle_data.c, runs clang on each, and has clang link the two objects with lld into build/hello_triangle.exe and its .pdb. The script treats anything rin asm prints besides its "built" line as a failure, so a lesson either builds clean or is reported with every message it produced.

One file, one program

Lessons share no code at link time. Each .rasm is a unity build: it imports what it uses, the includes import what they need, and rin asm reads the lot as one program. That is why there is one .s and one .c per lesson and nothing to link them with but the system's libraries. Every file is read once per program, however many files import it, so nothing needs a guard. A path is relative to the file that imports it:

import "../../../includes/learn/window.rasm"

The line records in the .s refer to the original files and lines, includes and all. Open hello_window.exe in the Visual Studio debugger, or any debugger that reads .pdb files, and breakpoints and single-stepping work on the .rasm source, with the registers in view.

What rin asm writes

The two generated files are worth one look, because they explain everything the debugger will show us. Here is the start of create_buffer from the next-but-one chapter, Hello Triangle, as it is written in hello_triangle.rasm:

create_buffer: proc(bind: u32, data: *const void, size: u32) -> *ID3D11Buffer = {
    sub rsp, 40
    mov buffer_desc.ByteWidth, r8d
    mov buffer_desc.BindFlags, ecx
    mov buffer_init.pSysMem, rdx
    vcall(device, ID3D11DeviceVtbl.CreateBuffer, buffer_desc&, buffer_init&, new_buffer&)

and here is what build/rasm/hello_triangle.s has for it:

"create_buffer":
    .cv_func_id 24
    .cv_loc 24 1 222 0
    sub rsp, 40
    .cv_loc 24 1 223 0
    mov dword ptr [rip + "buffer_desc"], r8d    # buffer_desc.ByteWidth
    .cv_loc 24 1 224 0
    mov dword ptr [rip + "buffer_desc" + 8], ecx    # buffer_desc.BindFlags
    .cv_loc 24 1 225 0
    mov qword ptr [rip + "buffer_init"], rdx    # buffer_init.pSysMem
    .cv_loc 24 1 226 0
    mov rcx, qword ptr [rip + "device"]
    movabs rdx, offset "buffer_desc"
    movabs r8, offset "buffer_init"
    movabs r9, offset "new_buffer"
    ...

The instructions are the ones we wrote. The .cv_loc before each is the line record: file 1, lines 222, 223 and so on of the .rasm. A field written by name, buffer_desc.BindFlags, has become an address and a size, dword ptr [rip + "buffer_desc" + 8], with the field it came from kept as a comment. And the vcall on the last line of the excerpt, a macro we meet in the next chapter, has become the instructions its definition spells out, all of them under one line record, line 226, so the debugger steps over the whole call at once.

The data file has the globals, as C. The same buffer_desc is declared there as

D3D11_BUFFER_DESC buffer_desc = { .Usage = 1 };
...
_Static_assert(offsetof(D3D11_BUFFER_DESC, ByteWidth) == 0, "rasm layout: D3D11_BUFFER_DESC.ByteWidth");
_Static_assert(offsetof(D3D11_BUFFER_DESC, BindFlags) == 8, "rasm layout: D3D11_BUFFER_DESC.BindFlags");

with a check for every field offset the code used. The 8 in [rip + "buffer_desc" + 8] is rasm's idea of where BindFlags sits; the _Static_assert is the C compiler's, from the Windows SDK's own d3d11.h. If the two ever disagree, the build stops with an error naming the field. There is nothing to get wrong by hand here, and nothing to keep in step.

Debugging

The debug information that clang and lld write is ordinary CodeView, as for a C program, so Visual Studio needs no project and no extension to debug a lesson:

devenv /debugexe build\hello_triangle.exe

Open hello_triangle.rasm in it, click in the margin to set a breakpoint and press F5. F10 steps one statement, a whole invoke(...) or vcall(...) being one, and F11 follows a call into the procedure it calls. The Registers window shows rax to r15, and the Watch window shows any global by name with its real type, so swap_desc unfolds into its fields as it would in a C program. lldb works too, with a breakpoint by file and line: b hello_triangle.rasm:222.

When an instruction does not do what you meant, the generated .s is the place to look: it is exactly what clang assembled, one line per instruction, with the field paths as comments. The rasm repository also has syntax colouring for Visual Studio and Neovim, and a language server that shows, on hover, the type, offset and size of any field.

Linking

The LIBS line is the equivalent of the linker settings LearnOpenGL fills in for GLFW and opengl32.lib. Each name is a Windows SDK library, mostly the small import libraries that tell the linker a function lives in a system DLL:

Each program gets a console, where error messages go. The C runtime's start-up code runs first and calls our main as an ordinary procedure; a lesson still ends by calling ExitProcess itself, so main never returns to it.

If you leave a library out, rin asm and clang are perfectly happy, and the link then fails with "undefined symbol" for each function from that library, naming the .rasm file and line that calls it. That error almost always means a missing entry here, or a missing import: a name the assembler does not know is taken to be code that lives somewhere else, and only the linker finds out that it doesn't.

The project layout

The repository follows the layout of LearnOpenGL's own code repository, so that the two can be read side by side:

build.py                      how the lessons are built
src/
  1.getting_started/
    1.1.hello_window/
      hello_window.rasm       the program
    2.1.hello_triangle/
      hello_triangle.rasm     the program
      hello_triangle.hlsl     its shaders: vs_main, ps_main
    ...
  2.lighting/
  ...
includes/
  d3d11.rin                   Win32, COM, D3D11, DXGI, D3DCompiler and WIC: the C headers and their binding
  gen/                        the generated binding, and the script that generates it
  calls.rasm                  invoke and vcall
  macros.rasm                 asserts, release
  cstr.rasm, print.rasm       strings, memory, and print over wsprintfA
  saha.rasm                   the arena allocator
  math.rasm                   vectors and matrices, in SSE
  image.rasm                  .png and .jpg through WIC, Radiance .hdr
  learn/
    window.rasm               the window, the device, input, the clock
    filesystem.rasm           paths under the repository root
    shader.rasm               compile a .hlsl file, create its input layout
    gpu.rasm                  buffers, constants, textures, samplers, render targets
    camera.rasm               the fly camera
    model.rasm                Wavefront .obj models and their textures
    ...
resources/                    textures, models, the HDR environment
build/                        the executables; build/rasm/ the generated .s and .c

Every lesson is one .rasm file, read top to bottom: a comment saying what the lesson is about, its imports, its data, then main: window, device, shaders, buffers, render loop, in the same order as LearnOpenGL's C++ files. Its HLSL file sits beside it and holds all of its shaders, with entry points named vs_main and ps_main (and gs_main where there is a geometry shader).

The includes/ folder plays the part of LearnOpenGL's includes/. d3d11.rin stands in for the GLFW and GLAD headers, math.rasm for GLM, and image.rasm for stb_image. A few files do what the C library would: cstr.rasm has string and memory routines such as mem_zero and mem_copy, and saha.rasm is an arena that stands in for malloc. The learn/ folder holds helpers in the spirit of LearnOpenGL's shader.h, camera.h, model.h and filesystem.h, each introduced in the chapter that first needs it. A lesson imports these by their paths, as Shaders does:

import "../../../includes/d3d11.rin"
import "../../../includes/calls.rasm"
import "../../../includes/math.rasm"
import "../../../includes/learn/window.rasm"
import "../../../includes/learn/shader.rasm"
import "../../../includes/learn/gpu.rasm"

Calling Windows from assembly

LearnOpenGL needs GLAD because most OpenGL functions must be looked up in the driver while the program runs. We have no such step; Direct3D's functions are linked normally. What the assembler needs is to know the names: of the functions, of the constants, and of every structure and its fields, so that swap_desc.BufferDesc.Format means the right bytes. One file provides them, d3d11.rin, written in rin:

cinclude "windows.h"
cinclude "d3d11.h"
cinclude "dxgi.h"
cinclude "d3dcompiler.h"
cinclude "wincodec.h"
import "gen/win32_d3d11.rin"

The cinclude lines are the headers the data file includes, so the C side of every program sees Windows exactly as a C program would. The import is the binding: gen/win32_d3d11.rin, generated by gen/gen_bindings.py with rinbind, which reads the same headers through libclang and writes out, in rin's syntax, every structure with its fields where the C compiler puts them, every enum with its values, every #define that is a constant, every function, and for every COM interface a structure of its methods, ID3D11DeviceVtbl, whose fields are the slots of its table of functions. Nothing in it is written by hand, and the _Static_asserts above check, on every build, that what the code used agrees with C.

A few GUIDs that the headers only declare are listed at the bottom of the same file, so that rasm knows their type; their sixteen bytes come from dxguid.lib and windowscodecs.lib:

IID_ID3D11Texture2D: IID;
GUID_ContainerFormatPng: GUID;
Fields keep their real names. Width, Size, Flags and Type are field names in Windows' structures and nothing special to rasm, so a texture description's width is desc.Width, as in the Microsoft documentation, and a global may be called offset or scale: rasm quotes every symbol it writes into the .s. The one namespace that bites is C's. Every global is a C variable in a file that includes windows.h, so neither C's keywords nor the macros windows.h defines (near, far, min, max, small...) can be names; the lessons say z_near and z_far. The repository's notes on the assembly list this and the other conventions in one place.

Finding resources

The programs read files while they run: their HLSL source, and the textures and models in resources/. LearnOpenGL handles this with a FileSystem::getPath helper whose root is configured when the project is built. Ours, in learn/filesystem.rasm, finds the root when the program starts instead: it takes the executable's own path from GetModuleFileNameA and walks up one folder at a time until it reaches a folder that contains resources.

; rcx: path relative to the repository root -> rax: the full path
filesystem_path: proc(relative: *const c8) -> *c8 = {
    push rbx
    push rsi
    sub rsp, 40                            ; 32 shadow; entry 8 + two pushes 16 + 40 lands on 16
    mov rsi, rcx                           ; the relative path
    cmp filesystem_root[0], 0
    jne have_root
    call filesystem_find_root
  have_root:

A lesson then names every file relative to the top of the repository:

invoke(filesystem_path, "src/1.getting_started/2.1.hello_triangle/hello_triangle.hlsl")
mov shader_path, rax

The executable is in build\, one folder below the root, so the search succeeds after one step. It does not matter which directory you start the program from, so double-clicking it in Explorer works as well as running it from a terminal. If the executable is moved somewhere with no resources folder above it, the program says so and exits.

The first three lines of that procedure are its frame, and every procedure in these lessons writes its own. Win64 says that rbx, rsi, rdi, rbp and r12-r15 must survive a call, so a procedure that uses one pushes it on the way in and pops it on the way out. It also says that a caller reserves 32 bytes of shadow space for the procedure it calls, and calls with rsp on a multiple of 16: at entry rsp is 8 past one (the return address), the two pushes add 16, and sub rsp, 40 adds the 32 and puts it back on 16. The comment on the sub says so, here and everywhere. filesystem_root[0] is the first byte of a global array of bytes, and a string literal as an argument, as in the invoke above, is the address of a copy of the text that rasm places in read-only data.

Since shaders are read and compiled every time a lesson starts, editing a .hlsl file needs no rebuild at all: save it and run the program again. Only changes to .rasm files need python build.py.

That is the whole setup. With LLVM, the Windows SDK and the rin compiler installed and one python build.py behind us, we are ready to look at what the first program actually does to get a window on screen.

Additional resources

Exercises

  1. Run hello_triangle.exe from a different working directory, for example cd build and then hello_triangle.exe, and from somewhere else entirely with its full path. It still finds its files. Now copy it to a folder outside the repository and run it there: what happens, and which line of filesystem.rasm prints the message?
  2. Add a lesson of your own: copy the 1.1.hello_window folder to 1.2.my_window, rename the file inside to my_window.rasm, and run python build.py my_window. Nothing needs registering anywhere: the script builds whatever .rasm files it finds under src/. Look at what appeared in build/rasm/.
  3. Put a typing mistake in hello_triangle.hlsl and run hello_triangle.exe without rebuilding. The program prints the compiler's message, with the file and line, and exits. Then put a mistake in hello_triangle.rasm, say a misspelt register, and run python build.py hello_triangle, and compare where that error is reported, and how rasm reads a register name it does not know. Finally, delete "d3dcompiler" from the LIBS line in build.py and build again: which step fails now, and how does it say so?
Credit: this chapter follows LearnOpenGL's Creating a window 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.