ASCII Graphics

C++ 3D graphics library that runs in a Linux terminal

About The Project

Ascii-graphics is a basic 3D graphics library designed to run in a linux terminal.

Features

Below shows some key features of the ascii-graphics library.

Custom OBJ Model Loading

Smooth Lighting

Z Buffering

Other Features

• Outline meshes
• Wireframe mode
• Fill entire mesh with single character
• Basic lighting

Installation

1. Clone the repo

   git clone https://github.com/addr0x414b/ascii-graphics.git
   

2. In the cloned folder, create a build directory and cd to it

   mkdir build && cd build
   

3. Run cmake

   cmake ../
   

4. Run make

   make
   

5. Run the program

   ./Ascii-Graphics
   

Usage

Below is the default code the repo comes with:

//ascii-graphics.cpp

int gScreenWidth = 200; // Define the screens width and height
int gScreenHeight = 50;
float gAspect = (float)gScreenWidth / (float)gScreenHeight;

int main() {

	Camera camera(0.0f, 0.0f, 0.0f, gAspect); // Define the scenes camera
	LightD light; // Define the scenes light
	Screen screen(gScreenWidth, gScreenHeight, camera, light); // Define the screen of the scene

	Cube cube; // Library comes with one default mesh
	cube.translate(0.0f, 0.0f, -4.f); // Must translate the mesh away from the camera (-z is into the screen)

	float deg = 0.1f;
	while (1) { // Screen loop
		screen.start(); // Begin calculating the delta time per frame

		cube.rotate(0.0f, deg, deg); // Rotate cube
		deg += 50 * screen.deltaTime; // Increase the degrees of rotation

		screen.shadeMesh(cube); // Print the cube into the buffer

		screen.print(); // Print the buffer
		screen.clear(); // Clear the screen
	}

	return 0;
}

Create Scene

1. Define size of the screen

int gScreenWidth = 200; // Width and height should be no larger than terminal
int gScreenHeight = 50; // Can increase size with decreased terminal font size
float gAspect = (float)gScreenWidth / (float)gScreenHeight;

2. Define camera, light, and screen

Camera camera(0.0f, 0.0f, 0.0f, gAspect); // Constructor uses default projection values
LightD light; // Define the scenes light
Screen screen(gScreenWidth, gScreenHeight, camera, light); // Define the screen

To Load a Custom Mesh

1. Mesh MUST be in OBJ format
2. Mesh MUST be triangulated, with normals
3. OBJ file should be in the same directory as the ascii-graphics.cpp file
4. File path MUST have "../" in front (assuming file is in the same directory as ascii-graphics.cpp)

• Flat Shaded Mesh:

Mesh meshName("../path_to_flat_mesh.obj"); // Load a FLAT SHADED mesh
meshName.translate(0.0f, 0.0f, -4.0f); // Translate the mesh away from the camera

• Smooth Shaded Mesh:

Mesh meshName(1, "../path_to_smooth_mesh.obj") // Load a SMOOTH SHADED mesh
meshName.translate(0.0f, 0.0f, -4.0f); // Translate the mesh away from the camera

Display the Graphics

float deg = 0.1f;
while (1) { // Screen loop
	screen.start(); // Begin calculating the delta time per frame

	cube.rotate(0.0f, deg, deg); // Rotate cube
	deg += 50 * screen.deltaTime; // Increase the degrees of rotation

	screen.shadeMesh(cube); // Print the cube into the buffer

	screen.print(); // Print the buffer
	screen.clear(); // Clear the screen
}

Different Display Methods

• Display a smooth shaded mesh

screen.shadeMeshSmooth(meshName);

• Display a flat shaded mesh

screen.shadeMesh(meshName);

• Fill entire mesh with a single character, no shading

screen.fillMesh(meshName, '*'); // Pick character here

• Show mesh triangles

screen.drawMesh(meshName, '*'); // Pick character here

• Display wireframe of mesh

screen.drawMeshWire(meshName, '*'); // Pick character here

• Can combine different methods

// Results in an outlined cube
screen.drawMesh(cube, '#'); // Draw the triangles of the cube
screen.fillMesh(cube, '*'); // Fill in the cube

License

Distributed under the MIT License. See LICENSE for more information.

Contact

YouTube: https://www.youtube.com/watch?v=X4QSm_p7Cy4

Acknowledgments

Thanks to the following for allowing use of their 3D models:

• Man model by printable_models
• Rocket model by Paul Chen uploaded by nixor
• Cat model by snippysnappets