tgx

TGX - A Tiny Graphics Library

Version 1.1.4 highlights

• Optional local point and spot lights for flat and Gouraud 3D shading, with range attenuation, cone falloff and optional local specular highlights.
• New generated 3D primitives: cylinder, cone and truncated cone, with solid, textured and wireframe variants.
• New affine texture mapping path (SHADER_TEXTURE_AFFINE) alongside the existing perspective-correct texture mapper.
• Advanced drawMesh() overloads for sketches that want to restrict compiled shader paths per draw call.
• Teensy 4.x helpers to place selected heavy Renderer3D template paths in flash when RAM1/ITCM is tight.
• New and updated examples for Teensy, ESP32, ESP32-P4, Pico/RP2040/RP2350 and M5Stack boards.
• Reworked 3D tutorial and refreshed TGX tools documentation.

Full documentation is now available at https://vindar.github.io/tgx/

2D and 3D Graphics Library for 32-bit Microcontrollers

This library implements a set of classes that make it easy to draw 2D and 3D graphics onto a memory framebuffer. It is designed and optimized for 32-bit MCUs, yet it is cross-platform and also works on CPUs.

The library has been tested on:

• Teensy 3.5, 3.6, 4.0, 4.1
• ESP32 family
• Raspberry Pico 1/2 (RP2040/RP2350)
• STM32 (STM32F4/STM32H7)
• Desktop CPUs

Warning: The goal of the library is to draw graphics onto a memory framebuffer. As such, it does not provide any hardware or screen support. You will need a screen driver to display the framebuffer on a physical screen. If you are using a Teensy 4.0/4.1 with an ILI9341 screen, consider using my optimized driver.

Here are the main features of the library:

2D Graphics

• Supports multiple color types: RGB565, RGB24, RGB32, RGB64, RGBf, and HSV. Every 2D/3D drawing operation is available for each color type.
• A templated Image class encapsulates a memory framebuffer and enables the creation of sub-images (i.e., views) that share the same buffer. This provides an elegant and efficient way to clip all drawing operations to a specific region.
• API (mostly) compatible with Adafruit's GFX and Bodmer's TFT_eSPI libraries, but with more drawing primitives and usually faster! Primitives include lines, triangles, rectangles, polygons, circles, ellipses, arcs, pies, Bezier curves, splines, and more.
• Methods for blitting sprites with or without a transparent mask, supporting rotation and scaling. High-quality rendering is achieved using bilinear filtering and sub-pixel precision for smooth animations.
• Color type conversion and image resizing.
• Transparency support for all drawing methods. The RGB32 and RGB64 color types include an alpha channel for alpha blending. Types without an alpha channel still support basic blending via an opacity parameter available for most drawing primitives.
• Anti-aliased methods for drawing thick lines and circles.
• Support for Adafruit fonts and PJRC's ILI9341_t3 v1 and v2.3 anti-aliased fonts.
• Graphical and command-line tools to convert images, meshes and fonts into C++ files that can be directly imported into a project.
• Seamless integration with external libraries: OpenFontRender (for TrueType fonts), PNGdec (for PNG), JPEGDEC (for JPEG), AnimatedGIF (for GIF).

3D Graphics

• Heavily optimized pixel-perfect triangle rasterizer with selectable sub-pixel precision (2, 4, 6, or 8 bits).
• Depth buffer testing (16-bit or 32-bit precision).
• Three wireframe drawing paths: fast aliased lines, optimized one-pixel antialiased lines, and a much slower adjustable thickness + AA path.
• Flat and Gouraud shading.
• Phong lighting model with separate ambient, diffuse, and specular components. Supports multiple directional lights and local point/spot lights.
• Per-object material properties.
• Perspective-correct or affine texture mapping with selectable point sampling or bilinear filtering. Wrap modes: repeat (for power-of-two textures) or clamp to edge.
• Perspective and orthographic projection.
• Optional backface culling.
• Tile rasterization: render only part of the viewport at a time to save RAM, using a smaller image and z-buffer.
• Template classes for all required math operations: Vec2, Vec3, Vec4 (vectors), Mat4 (4x4 matrices), and Box2 (2D box).
• Optimized mesh data format: meshes and textures can be read directly from flash memory to save RAM.
• Python tools for easy conversion of texture images, fonts and 3D meshes (in Wavefront .obj format) into C++ files that can be directly imported into an Arduino project.

Note: The recommended way to create new TGX font headers is now tools/tgx_font.py or tools/cli_tools/tgx_font_cli.py. The companion tgx-font repository remains available for older projects and as a collection of plain and anti-aliased fonts.

Using the Library

• Full documentation is available here.
• Examples are located in the /examples/ subfolder of the library and demonstrate how to use most of the library's features.