Table of contents

• About SGL
• Demos and tests
• How to compile SGL (using CMake)
• For developers

About SGL (Software Graphics Library)

SGL is a tiny, light-weight, cross-platform software rasterizer for Windows and Linux-based systems, written in C++. It strictly follows the classic GPU rasterization pipeline specifications and supports skeletal animation. Users can program their own vertex and fragment shaders and attach them to the pipeline to achieve custom effects. The overall design of the rasterization pipeline is shown below.

• Currently, SGL is designed to serve as a graphical backend for retro-style game engines. Rendering something onto the screen with SGL can be very simple: simply provide the vertex positions, texture coordinates, and normals. SGL will then draw the model for you without any help from the dedicated GPU.

• Write your own vertex and fragment shaders for the software rasterizer: SGL supports customized vertex and fragment shaders. The image below shows an example:

  

• Due to the benefit of abstracting the entire rendering operation into multiple render passes, SGL can also easily support hardware acceleration (GPU rendering using OpenGL) to render complex scenes. This feature is currently working in progress.

Demos and tests

Demo or test name	Demo showcase	Description
test_hello_world.cpp		A simple hello world demo. Demonstrating the basic functionalities of the rasterization pipeline (implemented in sgl_pipeline.cpp), including: perspective projection, basic texturing, custom vertex & fragment shaders.
test_skeletal_anim.cpp		Skeletal animation & Assimp md5mesh import demo (model: boblamp, 1027 triangles). Including orthographic / perspective projection.
test_sprite_render.cpp		A simple demo for rendering multiple 2D sprites onto a texture with just a few lines of code. The chess sprites used in this demo were downloaded from here.
test_normal_mapping.cpp		Demonstration of normal mapping techniques and nearest/linear texture sampling.

Performance benchmarking

Demo or test name	Description
test_skeletal_anim.cpp	CPU: Core i7-3770 8 cores 3.4 GHz. Mesh & render info: 1027 triangles with backface culling. OpenMP multi-thread: 1.78 ms per frame in classic 320x240 resolution, 3.69 ms per frame in 800x600 resolution. Single-thread: 2.14ms in classic 320x240 resolution, 8.31ms in 800x600 resolution.

• Now SGL supports multiple internal texture formats (BGRA, RGBA, etc.). Using the native texture format (BGRA8888) can gain an extra 8% in performance (3.69 ms to 3.40 ms).

How to compile SGL (using CMake)

• SGL relies on these external libraries:

Library	Link	Description
SDL2	https://github.com/libsdl-org/SDL	Frame buffer visualization & window message loop handling.
Assimp	https://github.com/assimp/assimp	Open-Asset-Importer-Library for importing model assets.

• Before git clone this repository, you need to manually compile all external libraries and remember the paths of all compiled libraries (*.lib/*.a/*.so) and header files (*.h/*.hpp).
• For convenience, the precompiled binaries for Windows and Linux-based systems are provided below.

For Windows (Visual Studio IDE)

1. If you are using Visual Studio 2017, things will become much more simpler, I have provided the precompiled libraries, include headers, and all external dependencies in here for download.

   Otherwise, you may need to compile all external libraries using your own version of Visual Studio (newer versions might also work, but I have not tested them yet).

2. Using CMake build system (cmake-gui) to generate Visual Studio solutions. Press Configure, select "x64" platform, under the "COMPILER" option list, select "MSVC". Then, CMake will prompt you to specify the path for compiled libraries and the location of include headers (shown below).

   Watch this self-explanatory video for more infomation.

   

   DO NOT add extra "\" after directories to avoid strange include errors when building the project.

   Finally, press Generate, and Open Project to open Visual Studio. In Visual Studio, choose Release or MinSizeRel and compile SGL (if you want to debug SGL on Windows, select "Debug").

   After compiling SGL, you may need to copy all *.dll files and the contents of the assets/ folder to the same location as the generated executables.

For Linux-based systems (g++ & make)

1. Manually compile all external libraries. I have provided the precompiled libraries in here for download.

   All libraries are statically built in "x64" mode using g++ 11.4.0 under Ubuntu 22.04.
   NOTE: If the precompiled libraries are not compatible with your development environment, you will need to compile them manually. Please also note that all libraries should be statically linked if you want to build SGL on Linux.

2. Make sure your g++ compiler supports C++17 language standard. I recommend using ccmake to generate makefiles. Create a new empty directory and cd into it, then use the following command

   ccmake <path_to_CMakeLists.txt>

   to initiate CMake build system and configure the project. ccmake will also prompt you to input the path of those precompiled libraries and include headers. Here are the configurations

   Under the "COMPILER" option list, select "GCC".
   Under the "BUILD_TYPE" option list, select "Release" (if you want to debug SGL on Linux, select "Debug").
   

   Then, ccmake will prompt you to provide the file paths of the precompiled libraries (*.a) and headers (*.h). After filling in all the paths, the final configuration should look like this:

   

   Hit g to generate makefile and ccmake will automatically quit if succeed.

   Finally, make -jN to compile SGL using N threads (such as make -j8) and wait for it to finish.

   After compiling SGL, you may need to copy all the contents of the assets/ folder to the same location as the generated executables.

For developers

Quick start

• After successfully compiling SGL in debug mode, you may want to start with the hello world demo in tests/test_hello_world.cpp, which can help you quickly go through the entire software raterization pipeline.

Before commit

• Code formatting: please make sure all source and header files are indented using 2 spaces (not tabs).

Project structure

• CMakeLists.txt
  • For CMake.
• assets/
  • Contains assets (models, textures, etc.) for running demos.
• demos/
  • All demo outputs (*.png, *.gif), tutorials, and media files.
• include/
  • Header files and inline implementations (*.h).
• src/
  • Source files (*.cpp).
• tests/
  • All CI test cases (*.cpp sources will be compiled and linked as executables).
• doc/
  • Documentations, devlog, tutorials, notes, etc.
• ext/ (not included in this repo)
  • External dependencies, including the source code for all 3rd-party libraries.
• build/ (not included in this repo)
  • Project files generated by CMAKE/CCMAKE under different platforms.
  • For example, build/gcc_x64_static/ stores all the project files generated for 64-bit gcc/g++ compilers, using static linking. build/vs2017/ stores all the project files generated for the Microsoft Visual Studio 2017.
• build_deps/ (not included in this repo)
  • Dependencies for building the project. Which contains:
    • Include headers of 3rd-party libraries.
    • Compiled libraries (.lib/.a) and shared objects / DLLs (.dll/.so).
  • Usually all the files in this folder are collected from ext/. You need to compile all the 3rd-party libraries in ext/ and then copy the generated binaries and include headers to this folder.

Features and TODOs

Features

• Flexible vertex format supoort
• Customized vertex & fragment shader support
• md5 (*.md5mesh, *.md5anim) format import & parsing
• Skeletal animation support
• Wireframe rendering
• Perspective / orthographic projection

TODOs (lots of things...)

• Shadow mapping
• Reflection effect
  • Stencil buffer
  • Alpha blending
• Text rendering
• Phong shading
• Texture baking
  • Ray tracing