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 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:
rin asm , the assembler inside the rin compiler, reads a lesson and everything it imports and writes two files. Thecode becomes a.sfile of assembly for clang, with a line record before every statement saying which.rasmline it came from. Thedata , every type and global, becomes a.cfile, which includes the Windows SDK's own headers.clang (from LLVM) assembles the.sand compiles the.c, each into an object file, and the C compile carries full debug information for every global: its type, its fields, their names.lld , LLVM's linker, links the two objects into an.exe, resolving each Windows function against its import library, and writes the debug information to a.pdbbeside it.- The
Windows SDK provides those headers and import libraries:kernel32.lib,user32.lib,ole32.lib,d3d11.lib,d3dcompiler.liband the rest. clang targets the Microsoft environment and finds the SDK, and the C runtime libraries of a Visual Studio or Build Tools installation, by itself. Python runs the build script, which is one loop aroundrin asm.
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.
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 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 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.
.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:
kernel32, always linked: files, memory, timers, the command line, and ending the process.user32, always linked: windows, messages and keyboard state, andwsprintfA , which formats our printed messages.ole32: COM start-up andCoCreateInstance , through which we reach the Windows Imaging Component that decodes our.pngand.jpgfiles.d3d11: Direct3D 11, includingD3D11CreateDeviceAndSwapChain , which also creates the DXGI swap chain.d3dcompiler:D3DCompile , which compiles our HLSL shaders while the program starts.dxguidandwindowscodecs: not functions but data, the GUIDs that the headers declare and these libraries define, such as IID_ID3D11Texture2D and the image format GUIDs of WIC.
Each program gets a console, where error messages go. The C runtime's start-up code runs first and calls our
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 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 saha.rasm is an arena that stands in for 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;
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 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.
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 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
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
- rin: the compiler whose
rin asmis our assembler; the rasm language is described in its documentation. - From MASM64 to rasm: the conventions every lesson follows, and the traps that cost time once.
- x64 calling convention: registers, shadow space and stack alignment, which every call in these programs follows.
- clang's MSVC compatibility: what targeting
x86_64-pc-windows-msvcmeans, CodeView debug information included. - Software layers: the Direct3D debug layer, worth turning on while developing.
- LearnOpenGL's Creating a window: the GLFW and GLAD set-up this chapter replaces.
Exercises
- Run
hello_triangle.exefrom a different working directory, for examplecd buildand thenhello_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 offilesystem.rasmprints the message? - Add a lesson of your own: copy the
1.1.hello_windowfolder to1.2.my_window, rename the file inside tomy_window.rasm, and runpython build.py my_window. Nothing needs registering anywhere: the script builds whatever.rasmfiles it finds undersrc/. Look at what appeared inbuild/rasm/. - Put a typing mistake in
hello_triangle.hlsland runhello_triangle.exewithout rebuilding. The program prints the compiler's message, with the file and line, and exits. Then put a mistake inhello_triangle.rasm, say a misspelt register, and runpython 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 inbuild.pyand build again: which step fails now, and how does it say so?