Introduction
This site walks through modern real-time rendering one small program at a time, from an empty window to image based physically based rendering. It is LearnOpenGL, the tutorial series by Joey de Vries, retold for
It has two twins: Learn D3D11 in rin tells the same story in a small C-like language, and Learn D3D11 in MASM64 in Microsoft's assembler. The programs here follow the MASM64 ones instruction for instruction, and every one of them draws the same picture, pixel for pixel; the shaders are shared unchanged by all three. If you already know LearnOpenGL, you can read this as a translation guide: every chapter links its original, and the maths and techniques carry over unchanged. If you don't, you can read it on its own; nothing here assumes you have seen OpenGL.
Why rasm
rasm is an assembler that keeps the instructions and replaces everything around them. A .rasm file declares its types and data the way rin (and C) does, with real structs, enums, designated initialisers and #defines, and holds bodies of plain Intel-syntax x64 instructions. Nothing is generated: no prologue, no frame, no hidden argument moves. Every instruction the program runs is one written in a .rasm file, in the lesson or in a macro you can read in includes/.
- The
data is typed . A global is declared with its type from the Windows SDK's own headers,buffer_desc: D3D11_BUFFER_DESC = { .Usage = D3D11_USAGE.D3D11_USAGE_IMMUTABLE }, and an operand names its field,mov buffer_desc.ByteWidth, r8d. rasm works out the offset and the size, and the C compiler checks every offset it used against the header. - The
debugger sees the source . Visual Studio (or lldb) steps through the.rasmline by line, and the Watch window shows every global with its type and field names. - The
calls are macros :invoke andvcall are a page of plain macros inincludes/calls.rasm, one definition per argument count, so what a call costs is always on the page.
Prerequisites
Direct3D is an API, not a language, so we need one to call it from. Ours is assembly, with no library underneath beyond Windows itself: the window is Win32, images are decoded by Windows' own codecs, shaders are compiled by
- the
Win64 calling convention : the first four arguments inrcx,rdx,r8andr9, floats in thexmmregister of their position, results inraxorxmm0, and 32 bytes ofshadow space that each proc reserves itself with asub rsp invoke , the macro that loads the arguments and makes the call:invoke(CreateWindowExA, 0, ...)vcall , its twin for a COM method, named by its slot in the interface's table:vcall(device, ID3D11DeviceVtbl.CreateBuffer, ...)
Direct3D's own interfaces are COM objects: a pointer to a table of functions, called with the object as the hidden first argument. The next chapter says more, and the repository's notes on the assembly collect every convention and trap in one place.
We also use some mathematics along the way: vectors, matrices, a little trigonometry, and for PBR a few integrals. Each is introduced when it is needed and explained as far as the chapter needs it, with pointers to fuller treatments. Here the vector and matrix code is SSE, four floats to a register, which turns out to suit it well.
Structure
The menu on the left lists the chapters in order, grouped into sections, the same sections LearnOpenGL has with "Advanced OpenGL" renamed. Read them top to bottom: each one builds on the program and the ideas of the one before. Every chapter explains the theory first, then builds it up in code, ending with a link to the complete program, some exercises, and further reading.
Each chapter is one .rasm file that imports what it uses, with its HLSL shaders in the same folder. The first two lessons write absolutely everything out; after that, what has been explained once moves into includes/, which play the parts LearnOpenGL gives its libraries (GLFW, GLAD, GLM, stb_image) and its helper headers for shaders, the camera and models. All of the source can be read here in the code viewer, linked from each chapter, or on GitHub.
Where LearnOpenGL splits a lesson into several programs (an indexed triangle next to the plain one, a textured PBR scene next to the plain spheres), ours keeps them in one program and switches between them with Tab or the number keys. The chapter says which key does what.
To keep the text easy to scan, a few conventions are used throughout.
Boxes
Code
Code appears in boxes with an amber edge, highlighted, rasm for the programs and HLSL for the shaders. In the assembly, instructions, registers, declarations and the call macros each have their own colour:
; ecx: bind flags, rdx: data, r8d: size -> rax: ID3D11Buffer
;
; An immutable buffer: filled once at creation, never written by the CPU again.
create_buffer: proc(bind: u32, data: *const void, size: u32) -> *ID3D11Buffer = {
sub rsp, 40 ; 32 shadow, and rsp back on 16
mov create_buffer_desc.ByteWidth, r8d
mov create_buffer_desc.BindFlags, ecx
mov create_buffer_init.pSysMem, rdx
vcall(device, ID3D11DeviceVtbl.CreateBuffer, create_buffer_desc&, create_buffer_init&, create_buffer_out&)
The snippets are copied from the real programs, so they always match what you will find in the full source. The button at the top right switches the page between light and dark.
Colour hints
Some words are coloured to show what kind of thing they are:
Definition : green words mark a term being defined, one you will meet again.Program structure : these are functions, procedures and macros, such asD3D11CreateDeviceAndSwapChain .- Variables: these are variables, fields and constants, such as D3D11_USAGE_IMMUTABLE.
Building the lessons
You will need Windows, the Windows SDK, LLVM (clang and lld) and the rin compiler, whose rin asm is the assembler. With those in place, one script builds all 38 programs, each a single rin asm: it writes the code as a .s with a line record per statement and the data as a .c, has clang assemble one and compile the other, and links them into an executable and its debug information.
git clone https://github.com/IbrahimHindawi/rasm-dx11
cd rasm-dx11
python build.py
build\hello_triangle.exe
To step through a lesson, open its executable in Visual Studio (devenv /debugexe build\hello_triangle.exe), open the .rasm, set a breakpoint and press F5. F10 steps a line, a whole invoke(...) being one, and F11 follows a call. 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, the register each argument of a Windows call goes in, and what an instruction does.
Creating a window goes through the setup in detail. Every lesson uses the same controls once there is a camera to move: W, A, S and D with Space and Shift to fly, the right mouse button held down to look around, the mouse wheel to zoom, and Escape to quit.
Credit
The tutorial this follows is Joey de Vries' LearnOpenGL, also available as a book, with its code on GitHub. Its chapters, choice of examples and much of the way each subject is explained come from there, along with the textures, models and HDR environment the lessons load, and the diagrams marked as LearnOpenGL's. LearnOpenGL is licensed CC BY-NC 4.0, and so is everything here. Thank you, Joey: a great many of us learned graphics from your site.
Now that the layout is familiar, head on to Getting started.