ryukazou / retrocube Goto Github PK

Spinning cube animation via very basic ray tracing on the terminal. Rendered in ASCII.

                    +==
                ++======
             +============
          ==================
      ========================
   +===========================..
   ||+=====================.......
    ||+=================..........
    +||||===========...............
     +||||||==+.....................
      +||||||........................
       +||||||.......................
       +||||||~.......................
        +||||||....................~.%
           |||||...............~.
            ||||~..........~..
               ||.........
                ||....~

In human language, the graphics are rendered 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 <- (0, 0)
        for (surface in cube's faces):
            // from equation ax + by + cz + d = 0
            find surface.z(c, r)
            if (z < z_rendered) and ((c, r, z) in surface):
                z_rendered <- z
                have_intersection <- true
                pixel_to_draw <- (c, r) 
        if (have_intersection):
            draw(pixel_to_draw)

Currenctly there is no Windows support. You'll need the following Linux packages:

1. ncurses
   On Debian-based systems it's installed with:

apt-get install libncurses-dev

On Arch-based systems it's installed with:

pacman -S ncurses

2. gcc
3. make

The naming convention follows the one of stb.
Source files are found in src and headers in include.

You can compile the project with:

make

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

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 to Peter Marreck (pmarreck).

By default the program runs forever so you can stop it with Ctr+C. Below are the command line arguments it accepts.

Some terminal emulators have been found not to render the drawing. If so, you can switch to a working one.

Terminal	Support
alacritty
termite
urxtv
xterm

If everyhing works, this is what it looks like on the command line:

random speed	constant speed

1. If the animation flickers too much, you can reduce the maximum fps. 15-20 is a relatively flicker-free range. You can do this by: ./cube -f 15 or ./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.

List of contributors:

• pmarreck - Nix packaging