tinyrenderer README

The project's README from github.com/ssloy/tinyrenderer. As one markdown file: README.md.

Software rendering in 500 lines of bare C++

The code itself is of little interest. Check the course notes:

  1. Introduction
  2. Bresenham’s line drawing algorithm
  3. Triangle rasterization
  4. Primer on barycentric coordinates
  5. Hidden faces removal
  6. A crude (but simple) approach to camera handling
  7. Better camera handling
  8. Shading
  9. More data!
  10. Tangent space normal mapping
  11. Shadow mapping
  12. Indirect lighting
  13. Bonus: toon shading
  14. Afterword

In this series of articles, I aim to demonstrate how OpenGL, Vulkan, Metal, and DirectX work by writing a simplified clone from scratch. Surprisingly, many people struggle with the initial hurdle of learning a 3D graphics API. To help with this, I have prepared a short series of lectures, after which my students are able to produce quite capable renderers.

The task is as follows: using no third-party libraries (especially graphics-related ones), we will generate an image like this:

Warning: This is a training material that loosely follows the structure of modern 3D graphics libraries. It is a software renderer. I do not intend to show how to write GPU applications — I want to show how they work. I firmly believe that understanding this is essential for writing efficient applications using 3D libraries.

The starting point

The final code consists of about 500 lines. My students typically require 10 to 20 hours of programming to start producing such renderers. The input is a 3D model composed of a triangulated mesh and textures. The output is a rendering. There is no graphical interface, the program simply generates an image.

To minimize external dependencies, I provide my students with a single class for handling TGA files — one of the simplest formats supporting RGB, RGBA, and grayscale images. This serves as our foundation for image manipulation. At the beginning, the only available functionality (besides loading and saving images) is the ability to set the color of a single pixel.

There are no built-in functions for drawing line segments or triangles — we will implement all of this manually. While I provide my own source code, written alongside my students, I do not recommend using it directly, as doing the work yourself is essential to understanding the concepts. The complete code is available on github, and you can find the initial source code I provide to my students here. Behold, here is the starting point:

#include "tgaimage.h"

constexpr TGAColor white   = {255, 255, 255, 255}; // attention, BGRA order
constexpr TGAColor green   = {  0, 255,   0, 255};
constexpr TGAColor red     = {  0,   0, 255, 255};
constexpr TGAColor blue    = {255, 128,  64, 255};
constexpr TGAColor yellow  = {  0, 200, 255, 255};

int main(int argc, char** argv) {
    constexpr int width  = 64; 
    constexpr int height = 64; 
    TGAImage framebuffer(width, height, TGAImage::RGB);

    int ax =  7, ay =  3;  
    int bx = 12, by = 37; 
    int cx = 62, cy = 53; 

    framebuffer.set(ax, ay, white);
    framebuffer.set(bx, by, white);
    framebuffer.set(cx, cy, white);

    framebuffer.write_tga_file("framebuffer.tga");
    return 0;
}

It produces the 64x64 image framebuffer.tga, here I scaled it for better readability:

Teaser: few examples made with the renderer

Compilation

git clone https://github.com/ssloy/tinyrenderer.git &&
cd tinyrenderer &&
cmake -Bbuild &&
cmake --build build -j &&
build/tinyrenderer obj/diablo3_pose/diablo3_pose.obj obj/floor.obj

The rendered image is saved to framebuffer.tga.

tinyrenderer (ssloy/tinyrenderer)

Searching Database…

24.4K ·GitHub
Tinyrenderer
What is this?This is 'tinyrenderer' — a hands-on computer-graphics course that walks you through writing a software 3D renderer from scratch in about 500 lines of C++, so you understand how OpenGL, Vulkan, Metal, and DirectX actually work under the hood.
Is this a ready-made renderer or a course I follow?It's a teaching project, not a library: you work through 14 short lecture notes and write the renderer's code yourself, using the author's reference code only as a guide rather than something you plug in and run.
How do I get started with the course?You take the minimal starting code the author provides (a single TGA-handling class plus an empty 64x64 framebuffer) and follow the lecture notes step by step, writing your own line drawing, triangle rasterization, shading, and so on in C++.
Do I need any graphics libraries to follow it?No third-party or graphics libraries are used — everything from pixel setting to line and triangle drawing is implemented by hand in plain C++, with only a small built-in TGA class for loading and saving images.
Does it have a window or GUI I can interact with?No, there's no graphical interface at all: each run just computes pixels and writes a static TGA image to disk — there's no live preview or interaction.
Who is this course meant for?It's aimed at programmers who want to understand 3D graphics internals rather than just use an API; the author notes students typically need 10 to 20 hours of coding to produce a working renderer.
What topics does the 14-part course cover?It goes from Bresenham's line algorithm and triangle rasterization through barycentric coordinates, hidden-face removal, camera handling, shading, tangent-space normal mapping, shadow mapping, and indirect/toon lighting.
Why build a software renderer instead of just using OpenGL?The author argues that understanding how rasterization and shading work under the hood is essential for writing efficient real GPU applications later.
What image format does the output use?Images are saved as TGA, which the author picked because it is one of the simplest formats that still supports RGB, RGBA, and grayscale data.
Can I just use the author's provided source code directly?You can, but the author explicitly discourages it — the whole point of the course is for you to write the ~500 lines yourself rather than copy a finished renderer.
What are similar projects?LearnOpenGL, 3d-game-shaders-for-beginners, bgfx, filament, Vulkan, assimp, blender, Hazel
Which topics is it in?rendering-engine, images, shader, 3d-graphics, engine, fun, shaders, opengl, computer-graphics, c-plus-plus, rendering, course
Creator
ssloy
Size
62.5 MB
Stars
24.4K
Updated
CommitJul 29
Age
11y
Commits · 90 Days