TGFX: a compact C++ 2D rendering library for modern GPUs

TGFX's target workload and platform boundaries

TGFX addresses applications that need to compose two-dimensional text, raster images, shapes, paths, and other vector content while delegating rendering to a modern GPU. Its intended users are C++ developers building native desktop or mobile applications, cross-platform graphics components, and WebAssembly targets. The library originated as the default graphics engine for PAG from version 4.0, and the README also names Hippy, Tencent Docs, and video-editing applications as users. Those examples indicate a focus on content-heavy graphics rather than general-purpose compute or scientific rendering.

The documented operating-system coverage includes iOS 15.0 and later, Android 5.0 and later, HarmonyOS 5.0 and later, macOS 12.0 and later, Windows 7.0 and later, Linux without a specified minimum version, Chrome 69.0 and later, and Safari 15.0 and later. Those minimums define where TGFX claims support, but they do not guarantee that every renderer or optional codec is available in every environment. Android's Vulkan option adds a separate restriction: the README requires Android 7.0, API level 24, or later.

The graphics API list gives adopters several possible paths. Desktop OpenGL starts at 3.2, mobile OpenGL ES starts at 3.0, and the Web target lists WebGL 2.0. TGFX also lists Vulkan 1.1 and WebGPU 1.0, while Metal 1.1 and later is explicitly marked as in progress. This distinction matters for Apple-platform planning. The repository contains native `ios/` and `mac/` directories, but the backend documentation does not claim completed Metal support.

TGFX rendering surfaces and API choices

TGFX presents a shared 2D drawing model while allowing the application to select a GPU backend appropriate to its platform. The documented choices are OpenGL 3.2, OpenGL ES 3.0, WebGL 2.0, Vulkan 1.1, WebGPU 1.0, and an in-progress Metal path. This architecture is useful for products that need the same drawing layer on Android, desktop, and the Web, although the README does not claim that every backend has identical feature coverage.

The repository layout gives the clearest available view of the implementation. Public headers are under `include/`, source code is under `src/`, and platform integrations are separated into directories such as `android/`, `ios/`, `linux/`, `mac/`, `ohos/`, `qt/`, `web/`, and `win/`. Tests are under `test/`, while runnable demonstration cases are associated with `drawers/`. This separation suggests that core graphics code and platform glue are not confined to a single application folder.

The README does not document the internal scene graph, command recording sequence, texture upload path, glyph cache, blend-state handling, or synchronization model. It also does not present a minimal drawing snippet. Consequently, an adopter cannot confirm from the README alone how a bitmap or glyph becomes a GPU resource. The repository's `test/` examples are identified as the intended API reference, while `drawers/` supplies visible rendering cases. Those directories are more useful starting points than assumptions about Skia-compatible behavior.

Building TGFX dependencies and opening the first demo

TGFX requires a C++17 toolchain and uses the `depsync` utility to synchronize third-party sources. On macOS, the documented dependency setup runs from the repository root:

./sync_deps.sh

The script installs the required tools and synchronizes third-party repositories. On other platforms, the README first calls for the current Node.js, then installs `depsync` globally:

npm install -g depsync

Run the installed dependency tool in the repository root:

depsync

The documentation warns that Git account credentials may be requested and refers to the `git-credential-store` for later automatic synchronization from `CMakeLists.txt`. That requirement introduces an operational dependency and may complicate clean CI environments.

For a first native demo, the iOS path is explicit. After prerequisites and dependencies are available, generate a device project with:

./gen_ios

The resulting Xcode workspace is `ios/Hello2D.xcworkspace`. Open it, build, and launch the demo. The README says the demo renders cases from `drawers/`, including shapes, images, and basic text, and that touching the screen switches cases. That gives an integration check based on visible output rather than an unconfirmed API sequence.

Generating iOS simulator projects and optional codecs

The iOS build scripts expose a smaller set of choices than a full CMake build command. To generate a simulator project for the Mac's native architecture, run:

./gen_simulator

The README gives `arm64` for Apple Silicon Macs and `x64` for Intel Macs as examples of simulator architectures. A specific architecture can be requested with the script's `-a` option:

./gen_simulator -a x64

The same scripts accept CMake options through `-D`. The documented WebP encoding example is:

./gen_ios -DTGFX_USE_WEBP_ENCODE=ON

This demonstrates how an optional encoding feature is selected, but the README does not enumerate every available `TGFX_USE_*` option or explain their runtime dependencies. An integrator should inspect `CMakeLists.txt` and the relevant platform project rather than infer flags from the naming pattern.

Android uses a different path through Gradle. The `android/` directory can be opened in Android Studio, which can download the NDK during Gradle synchronization. The recommended NDK is `25.2.9519653`. The demo defaults to OpenGL ES. To select Vulkan during an Android debug build, run this command from `android/`:

./gradlew assembleDebug -PcmakeArgs="-DTGFX_USE_VULKAN=ON"

The resulting application must meet the documented Android 7.0 minimum for Vulkan. This backend choice is more than a build preference because older supported Android installations may only follow the OpenGL ES route.

C++17 build requirements and integration constraints

The stated minimum tools are Xcode 13.0 or later, GCC 9.0 or later, Visual Studio 2019 or later, Node.js 14.14.0 or later, Ninja 1.9.0 or later, CMake 3.13.0 or later, Qt 6.2.0 or later, NDK 25 or later with `25.2.9519653` recommended, and Emscripten 4.0.15 for the Web toolchain. Visual Studio also requires the `Desktop development with C++` and `Universal Windows Platform development` components. The README recommends a current CMake release because older versions may contain platform-specific bugs.

This is a source-oriented integration rather than a conventional package-manager installation. The repository exposes `CMakeLists.txt`, a `build_tgfx` entry, platform build directories, `vendor.json`, and dependency scripts. No command for installing a prebuilt TGFX package into an arbitrary CMake application appears in the README. The documented path therefore starts with obtaining the repository, synchronizing dependencies, and generating or building a target demo.

That choice gives source-level control but places more responsibility on the adopter. Toolchain versions, credential configuration, CMake options, and platform SDKs must remain aligned with the checked-out revision. The README's branch policy also separates development from stability: `main` contains current features and fixes, while `release/{version}` branches receive milestone testing and only high-priority fixes. Teams that value a stable release line need to select that branch deliberately rather than tracking `main` implicitly.

TGFX versus Skia and the cost of a smaller binary

The README positions TGFX as an alternative to Skia with a much smaller binary size. That is a concrete architectural motivation, but the documentation provides no binary measurements, test conditions, or feature-by-feature comparison. The smaller-size claim should therefore guide investigation rather than serve as an accepted performance result.

Skia and TGFX are described at the same broad category level, but the adoption questions differ. TGFX emphasizes a lighter footprint, C++17, several platform wrappers, and GPU backends that include WebGPU and Vulkan. Skia is the incumbent against which the project defines its target. A team already has Skia infrastructure may need to assess font handling, text shaping, image formats, path semantics, custom shaders, PDF or SVG-related workflows, backend stability, and debugging facilities before replacing or sharing code with TGFX. The TGFX README names text, images, PDF, and SVG among repository topics, but it does not provide parity claims for every corresponding Skia feature.

TGFX may be the better fit when binary size constrains application delivery and the required drawing features match its demos and tests. It may be the wrong choice when an application depends on undocumented API behavior, requires completed Metal support, or expects a drop-in Skia replacement. The repository's origins in PAG give TGFX a concrete graphics-engine use case, yet the README does not state that its public API is Skia-compatible. That missing compatibility contract is a major integration boundary.

TGFX maintenance, releases, and license verification

The repository is not archived, and its last push was on 2026-10-15. The README identifies `main` as the active development branch and says stable milestone branches are created under `release/{version}` after the main branch passes its testing process. Recent release records include `v2.1.1` on 2025-09-26, `v2.1.0` on 2025-08-18, and `v2.0.1` on 2025-04-24. These records show published milestones, but the README does not publish a formal support window for any release.

Upgrade planning should account for more than copying a library binary. A source integration follows the repository's third-party synchronization process, depends on a C++17 toolchain, and may include platform-specific generated projects. Changes to CMake options, dependencies, or platform directories can therefore affect the build environment. Teams should inspect the selected `release/{version}` branch and compare its dependency state before moving an existing integration.

License metadata requires direct verification. The repository metadata classifies the license as `Other` because GitHub could not place it in a standard category, while the README badge says `BSD-3-Clause` and links to `LICENSE.txt`. The actual text of `LICENSE.txt` should control any compliance review. This is not legal advice, and the repository documentation does not state whether third-party dependencies introduce different terms. License and dependency review must remain separate from the library's technical evaluation.

Editorial conclusion

TGFX fits C++ teams that need cross-platform text, image, and vector rendering with a comparatively small binary footprint, especially applications built around OpenGL ES or WebGL 2. Teams that require documented Metal support, a package-manager installation path, or an immediately clear API model should first inspect the platform examples in `test/`, the `CMakeLists.txt`, and the exact contents of `LICENSE.txt`. A project already standardized on Skia should compare binary size and required rendering features before accepting TGFX's integration cost.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. Tencent/tgfx on GitHub