Goblin3D
Graphics engine for rendering 3D wireframe on monochromatic displays and TFT LCDs without any dependency required for Arduino platform.
|
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... | |
Header file for 3D object rendering using the Goblin3D library.
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:
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.
goblin3d_free
. 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.
x1 | The X-coordinate of the starting point of the line. |
y1 | The Y-coordinate of the starting point of the line. |
x2 | The X-coordinate of the ending point of the line. |
y2 | The Y-coordinate of the ending point of the line. |
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.
obj | Pointer to the goblin3d_obj_t structure to free. |
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
.
obj | Pointer to the goblin3d_obj_t structure to initialize. |
point_count | The number of points (vertices) in the 3D object. |
edge_count | The number of edges connecting the points in the 3D object. |
true
if initialization is successful, false
otherwise. 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.
The rotation matrices for the X, Y, and Z axes are as follows:
\[ R_x(\theta) = \begin{pmatrix} 1 & 0 & 0 \\ 0 & \cos\theta & -\sin\theta \\ 0 & \sin\theta & \cos\theta \end{pmatrix} \]
\[ R_y(\theta) = \begin{pmatrix} \cos\theta & 0 & \sin\theta \\ 0 & 1 & 0 \\ -\sin\theta & 0 & \cos\theta \end{pmatrix} \]
\[ 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.
obj | Pointer to the goblin3d_obj_t structure containing the 3D object data. |
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.
obj | Pointer to the goblin3d_obj_t structure containing the 3D object data. |
draw | A callback function used to draw lines between the points on the 2D plane. |