A software rasterizer and raycaster.
This code is intended for educational purposes for those interested in the math behind 3D graphics.
For some math details see:
A modern C++ compiler supporting C++17.
CMake >= 3.17 is used for building.
Tested on the following:
- Linux GCC 9.2.1
- Linux Clang 9.0.0
- Apple Clang 11.0.3
- Visual Studio 2017
To get to the heart of the matter of 3D graphics programming as directly as possible, generally minimizing extraneous details for reduced cognitive complexity in thinking about the math behind 3D graphics and how to implement it.
To make this project easy for most people to compile and run
provided a C++ compiler is availabe (if you are on Linux or
you use the Mac OS brew command then a C++ compiler is
probably already available).
Q: "What does it do?"
- A: "It generates and saves an image file from a textured 3D model."
Q: "Can I use my own models and textures?"
- A: "Yes. See below."
Q: "How do I run it?"
- A: "There are several command line programs that will be generated by the build, you can run those as detailed below."
Q: "How do I build it and does the build work?"
- A: "Yes, anyone with a C++ compiler and CMake should be able to build and run it and see the generated image."
Q: "Which file formats does it support?"
- A: "OBJ models and 24-bit uncompressed TGA textures"
Generate build and run the project.
See the OS specific notes for your OS below.
The ctest command will run the actual compiled
binaries using some default arguments.
mkdir ../cxxray_build
cd ../cxxray_build
cmake -DCMAKE_BUILD_TYPE=Release ../cxxray
cmake --build . --parallel 4
ctest --verbose
Install XCode and the XCode Command Line Tools.
CMake can be installed with.
brew install cmake
Install a compiler and build tools.
sudo apt-get install build-essential g++ make cmake
Install Visual Studio for usage with C++, open a 64-bit
developer tools command prompt and run cmake from here.
Binaries will end up in .\Debug and .\Release folders
respectively and with the .exe file extension.
mkdir ..\cxxray_build
cd ..\cxxray_build
cmake -G"Visual Studio 15 2017 Win64" ..\cxxray
cmake --build . --parallel 4 --config Release
ctest --verbose -C Release
Build 32-bit with
cmake -G"Visual Studio 15 2017" ..\cxxray
cmake --build . --parallel 4 --target draw_raster
This will draw a scene using rasterization and will write the resulting image to an output TGA format image file in the current folder.
./draw_raster
An optional first parameter specifies the 3D model to load and render. OBJ format is supported. See the section about using your own models from Blender. There is more than one model in this project's data folder with which you can test.
./draw_raster ./data/models/icosphere.obj
An optional second parameter specifies the image to use for texturing. Several checker maps are provided in the data folder.
./draw_raster ./data/models/icosphere.obj ./data/tex/UVCheckerMap16-512.tga
cmake --build . --parallel 4 --target draw_raycast
This will draw a sphere using raycasting and will write the resulting image to an output TGA file in the current folder.
./draw_raycast
This can draw triangles too, but a sphere is more interesting.
- Q: "These aren't really tests?"
- A: "They are more like a useful playground in which I can cheaply try things and confirm behavior."
NOTE: The TGA loader supports only 24-bit uncompressed TGA files.
cmake --build . --parallel 4 --target test_tga_loader
The TGA image loader test will read an input file and save it as a separate TGA file. If the result file opens correctly then the TGA code is working.
./test_tga_loader
The first and second arguments if provided specify the input and output files.
./test_tga_loader ./data/tex/UVCheckerMap01-512.tga checker_01_out.tga
The OBJ loader test operates similarly to the TGA loader test.
It will read a default file or a file argument.
If the format is valid and provided the restrictions on model export (see below) are met, the test should pass.
cmake --build . --parallel 4 --target test_obj_loader
./test_obj_loader
./test_obj_loader ./data/models/monkey.obj
cmake --build . --parallel 4 --target test_gamma
The gamma test will generate an image where one half is filled with gamma corrected grey and the other half is filled with a black and white checkerboard pixel panel simulating 50% grey.
./test_gamma
The default gamma value is 2.2, the first parameter if provided will specify the gamma value to use.
./test_gamma 1.8
You can make your own models in Blender and use them here.
Models must be exported to .obj format using the OBJ
exporter found in blender.
Models must export a materials file in the same folder as the model.
Models must consist only of triangles, no quads. Be sure to triangulate your models.
Models must be textured, meaning they must contain UV texture coordinates.
Models must contain one and only one mesh as well as one and only one material.
Export blender models to OBJ as +Y=Forward +Z=Up.