# 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<SHADERS>()` 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/***

<p align="center">
<img src="./tgx.jpg" height="300" />
</p>

<p align="center">
<a href="http://www.youtube.com/watch?feature=player_embedded&v=XxL15cQIPi8" target="_blank"><img src="http://img.youtube.com/vi/XxL15cQIPi8/0.jpg" width="240" height="180" border="10" /></a>
<a href="http://www.youtube.com/watch?feature=player_embedded&v=arJbbU28FEU" target="_blank"><img src="http://img.youtube.com/vi/arJbbU28FEU/0.jpg" width="240" height="180" border="10" /></a>  
<a href="http://www.youtube.com/watch?feature=player_embedded&v=96D0j9J2ILs" target="_blank"><img src="http://img.youtube.com/vi/96D0j9J2ILs/0.jpg" width="240" height="180" border="10" /></a>
</p>

## 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](https://github.com/vindar/ILI9341_T4).

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](https://github.com/adafruit/Adafruit-GFX-Library) and [Bodmer's TFT_eSPI](https://github.com/Bodmer/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](https://github.com/takkaO/OpenFontRender) (for TrueType fonts), [PNGdec](https://github.com/bitbank2/PNGdec) (for PNG), [JPEGDEC](https://github.com/bitbank2/JPEGDEC) (for JPEG), [AnimatedGIF](https://github.com/bitbank2/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 <a href="https://github.com/vindar/tgx-font">tgx-font</a> repository remains available for older projects and as a collection of plain and anti-aliased fonts.

## Using the Library

- Full documentation is available [here](https://vindar.github.io/tgx/).
- Examples are located in the `/examples/` subfolder of the library and demonstrate how to use most of the library's features.
