Goblin3D
Graphics engine for rendering 3D wireframe on monochromatic displays and TFT LCDs without any dependency required for Arduino platform.
goblin3d.h File Reference

Header file for 3D object rendering using the Goblin3D library. More...

#include <stdbool.h>
#include <stdint.h>

Go to the source code of this file.

Classes

struct  goblin3d_obj_t
 Structure representing a 3D object for rendering using the Goblin3D library. More...
 

Typedefs

typedef void(* goblin3d_obj_draw_fn) (uint16_t x1, uint16_t y1, uint16_t x2, uint16_t y2)
 Type definition for a callback function used to draw lines between points. More...
 

Functions

bool goblin3d_init (goblin3d_obj_t *obj, uint8_t point_count, uint8_t edge_count)
 Initializes a 3D object structure. More...
 
void goblin3d_free (goblin3d_obj_t *obj)
 Frees the memory associated with a 3D object structure. More...
 
void goblin3d_precalculate (goblin3d_obj_t *obj)
 Precalculates the rotated and projected points for a 3D object. More...
 
void goblin3d_render (goblin3d_obj_t *obj, goblin3d_obj_draw_fn draw)
 Renders the 3D object by drawing its edges on a 2D plane. More...
 

Detailed Description

Header file for 3D object rendering using the Goblin3D library.

Author
Nathanne Isip

This file contains the function declarations and data structures necessary for initializing, manipulating, and rendering 3D objects in a 2D space using the Goblin3D library. The library supports basic 3D transformations, including translation, rotation, and scaling. It is designed to work with microcontrollers and low-level graphical libraries.

The Goblin3D library provides functionalities to:

  • Initialize and free 3D objects.
  • Pre-calculate the 3D coordinates based on rotation angles.
  • Render the 3D objects onto a 2D surface.

Usage Example

goblin3d_init(&cube, 8, 12);
// Set up cube vertices and edges...
goblin3d_render(&cube, draw_function);
void goblin3d_free(goblin3d_obj_t *obj)
Frees the memory associated with a 3D object structure.
Definition: goblin3d.cpp:97
void goblin3d_precalculate(goblin3d_obj_t *obj)
Precalculates the rotated and projected points for a 3D object.
Definition: goblin3d.cpp:126
bool goblin3d_init(goblin3d_obj_t *obj, uint8_t point_count, uint8_t edge_count)
Initializes a 3D object structure.
Definition: goblin3d.cpp:27
void goblin3d_render(goblin3d_obj_t *obj, goblin3d_obj_draw_fn draw)
Renders the 3D object by drawing its edges on a 2D plane.
Definition: goblin3d.cpp:166
Structure representing a 3D object for rendering using the Goblin3D library.
Definition: goblin3d.h:72

The library supports simple perspective projection by translating the 3D coordinates into 2D screen space. It is lightweight and suitable for embedded systems with limited resources.

The library assumes that the Z-axis is pointing out of the screen, with positive values moving towards the viewer. The perspective transformation is performed by dividing the X and Y coordinates by the Z-coordinate.

Note
The library does not handle memory management for the content of the arrays used for points and edges. The user is responsible for providing valid data and ensuring that resources are correctly freed using goblin3d_free.

Typedef Documentation

◆ goblin3d_obj_draw_fn

typedef void(* goblin3d_obj_draw_fn) (uint16_t x1, uint16_t y1, uint16_t x2, uint16_t y2)

Type definition for a callback function used to draw lines between points.

This function type is used in the goblin3d_render function to draw lines between the projected 2D points of the 3D object.

Parameters
x1The X-coordinate of the starting point of the line.
y1The Y-coordinate of the starting point of the line.
x2The X-coordinate of the ending point of the line.
y2The Y-coordinate of the ending point of the line.

Function Documentation

◆ goblin3d_free()

void goblin3d_free ( goblin3d_obj_t obj)

Frees the memory associated with a 3D object structure.

This function deallocates the memory used for storing the points, edges, and other data in the goblin3d_obj_t structure.

Parameters
objPointer to the goblin3d_obj_t structure to free.

◆ goblin3d_init()

bool goblin3d_init ( goblin3d_obj_t obj,
uint8_t  point_count,
uint8_t  edge_count 
)

Initializes a 3D object structure.

This function allocates memory for the points and edges of the 3D object and sets up initial values for the rotation angles and offsets. If any memory allocation fails, the function will free any previously allocated memory and return false.

Parameters
objPointer to the goblin3d_obj_t structure to initialize.
point_countThe number of points (vertices) in the 3D object.
edge_countThe number of edges connecting the points in the 3D object.
Returns
true if initialization is successful, false otherwise.

◆ goblin3d_precalculate()

void goblin3d_precalculate ( goblin3d_obj_t obj)

Precalculates the rotated and projected points for a 3D object.

This function applies rotation transformations to the original 3D points and projects them onto a 2D plane. The rotation is applied in the order: X-axis, Y-axis, and Z-axis. The projected points are then scaled and offset based on the object's parameters.

Mathematical Representation

The rotation matrices for the X, Y, and Z axes are as follows:

  • Rotation around the X-axis:

    \[ R_x(\theta) = \begin{pmatrix} 1 & 0 & 0 \\ 0 & \cos\theta & -\sin\theta \\ 0 & \sin\theta & \cos\theta \end{pmatrix} \]

  • Rotation around the Y-axis:

    \[ R_y(\theta) = \begin{pmatrix} \cos\theta & 0 & \sin\theta \\ 0 & 1 & 0 \\ -\sin\theta & 0 & \cos\theta \end{pmatrix} \]

  • Rotation around the Z-axis:

    \[ R_z(\theta) = \begin{pmatrix} \cos\theta & -\sin\theta & 0 \\ \sin\theta & \cos\theta & 0 \\ 0 & 0 & 1 \end{pmatrix} \]

Given a point \((x, y, z)\), the rotated point is calculated as:

\[ \begin{pmatrix} x' \\ y' \\ z' \end{pmatrix} = R_z(\theta_z) \times R_y(\theta_y) \times R_x(\theta_x) \times \begin{pmatrix} x \\ y \\ z \end{pmatrix} \]

After applying the rotations, the 3D point is projected onto a 2D plane using the formula:

\[ x_{\text{proj}} = \frac{x'}{z'} \times scale_\text{size} + x_\text{offset} \]

\[ y_{\text{proj}} = \frac{y'}{z'} \times scale_\text{size} + y_\text{offset} \]

The z-coordinate is clamped to a minimum value to avoid division by zero or very small values, which could cause large distortions.

Parameters
objPointer to the goblin3d_obj_t structure containing the 3D object data.

◆ goblin3d_render()

void goblin3d_render ( goblin3d_obj_t obj,
goblin3d_obj_draw_fn  draw 
)

Renders the 3D object by drawing its edges on a 2D plane.

This function uses the pre-calculated 2D points to draw lines representing the edges of the 3D object. A callback function is used to perform the actual drawing, allowing for flexibility in the rendering method.

Parameters
objPointer to the goblin3d_obj_t structure containing the 3D object data.
drawA callback function used to draw lines between the points on the 2D plane.