Render 3D meshes in ASCII on the command line. It runs on the standard C library.
+==
++======
+============
==================
========================
+===========================..
||+=====================.......
||+=================..........
+||||===========...............
+||||||==+.....................
+||||||........................
+||||||.......................
+||||||~.......................
+||||||....................~.%
|||||...............~.
||||~..........~..
||.........
||....~
In human language, the graphics are rendered more or less by the following algorithm:
rows <- terminal's height
columns <- terminal's width
// a face (surface) is a plane segment (x, y, z) restricted within 4 cube vertices
initialise a cube (6 faces)
for (r in rows):
for (c in columns):
z_rendered <- +inf
have_intersection <- false
pixel_to_draw <- (c, r)
color_to_draw <- background
for (surface in cube's faces):
// from equation ax + by + cz + d = 0
z <- surface.z(c, r)
if (z < z_rendered) and ((c, r, z) in surface):
z_rendered <- z
color_to_draw <- surface.color
draw(pixel_to_draw, color_to_draw)
Currenctly there is no Windows support. You only need gcc and make:
- gcc
- make
The naming convention follows the one of stb.
Source files are found in src and headers in include.
When compiling the from project from a clean state, you need to specify where the mesh files
(those that specify how shapes are rendereed) shall be stored. You can do this by setting the
PREFIX variable to your directory of choice, e.g.:
make PREFIX=~/.config/retrocube
You can run the binary with (a list of command line arguments is provided in the next section):
./cube
You can delete the binary and object files with:
make clean
Several demos that showcase various usages of the libraries are found in the demos directory.
These are compiled independently from their own file. To compile them you need to set the PREFIX
once again:
cd demos
make PREFIX=~/.config/retrocube
# then you will see some binaries and run the binary of your choice
The Makefile includes an installation command. The binary will be installed at /usr/bin/cube as:
sudo make install
Similarly, you can uninstall it from /usr/bin as:
sudo make uninstall
On Nix (with flakes enabled) you don't need to install it and you can directly run it with:
nix run github:leonmavr/retrocube
Credits for the Nix packaging @pmarreck and @Quantenzitrone.
By default the program runs forever so you can stop it with Ctr+C. Below are the command line arguments it accepts.
| Short specifier | Long specifier | Argument type | Default | Description |
|---|---|---|---|---|
-sx |
--speedx |
float | 0.7 | Rotational speed around the x axis (-1 to 1). If set, disables random rotations. |
-sy |
--speedy |
float | 0.4 | Rotational speed around the y axis (-1 to 1). If set, disables random rotations. |
-sz |
--speedz |
float | 0.6 | Rotational speed around the z axis (-1 to 1). If set, disables random rotations. |
-f |
--fps |
int | 40 | Throttle the fps at which the graphics can be rendered (lower it if high CPU usage or if flicker) |
-r |
--random |
no argument | On | Rotate the shape randomly and sinusoidally. |
-cx |
--cx |
int | 0 | x-coordinate of the shapes's center in pixels |
-cy |
--cy |
int | 0 | y-coordinate of the shapes's center in pixels |
-cz |
--cz |
int | 0 | z-coordinate of the shapes's center in pixels |
-wi |
--width |
int | 60 | Width of shape in pixels |
-he |
--height |
int | 60 | Height of shape in pixels |
-de |
--depth |
int | 60 | Depth of shape in pixels |
-ff |
--from-file |
string | ./mesh_files/cube.scl |
The filepath to the mesh file to render. See mesh_files directory. |
-mi |
--maximum-iterations |
int | Inf/ty | How many frames to run the program for |
-up |
--use-perspective |
no argument | Off | Whether or not to use pinhole camera's perspective transform on rendered pixels |
-be |
--bounce-every |
int | 0 | If non-zero (-be N or --bounce-every N), changes moving direction every N frames |
-mx |
--movex |
int | 2 | Move the object by this many pixels along x axis per frame if bounce (-b/--bounce) is enabled. |
-my |
--movey |
int | 1 | Move the object by this many pixels along y axis per frame if bounce (-b/--bounce) is enabled. |
-mz |
--movez |
int | 1 | Move the object by this many pixels along z axis per frame if bounce (-b/--bounce) is enabled. |
Below are two examples of running the demo binary ./cube:
./cube |
./cube -b 100 -cz 300 -my -1 -mz 1 -up |
|---|---|
 |
 |
- If the CPU usage is too high (it was low on my ancient laptop), you can reduce the fps e.g. to 15 by:
./cube -f 15or./cube --fps 15.
If you'd like to contribute, please follow the codiing guidelines (section 3.1) and make sure that it builds and runs. I'll be happy to merge new changes.
Kudos to:
- @pmarreck - Nix packaging
- @Quantenzitrone - Fixing and competing nix packaging, including the mesh text files properly, tidying up the make build
- @IchikaZou - porting to Gentoo
- Anyone else who opened an issue for helping me make this project more robust.