Introduction

TGFX (Tencent Graphics) is a lightweight 2D graphics library designed for modern GPUs. It delivers high-performance, feature-rich rendering of text, images, and vector graphics on all major platforms, including iOS, Android, macOS, Windows, Linux, OpenHarmony, and the Web. Initially developed as the default graphics engine for the PAG project starting from version 4.0, TGFX aims to be a compelling alternative to the Skia graphics library while maintaining a much smaller binary size. Over time, it has found its way into many other products, such as Hippy, Tencent Docs and various video-editing apps.

Platform Support

iOS 9.0+
Android 5.0+
HarmonyOS 5.0+
macOS 10.15+
Windows 7.0+
Linux (No specific version requirement)
Chrome 69.0+ (Web)
Safari 15.0+ (Web)

Rendering Backends

OpenGL 3.2+ (Desktop)
OpenGL ES 3.0+
WebGL 2.0+
Metal 1.1+ (in progress)
Vulkan 1.1+ (in progress)
WebGPU (in progress)

Build Prerequisites

TGFX uses C++17 features. Here are the minimum tools needed to build TGFX on different platforms:

Xcode 11.0+
GCC 9.0+
Visual Studio 2019+
NodeJS 14.14.0+
Ninja 1.9.0+
CMake 3.13.0+
QT 6.2.0+
NDK 20+ (20.1.5948944 recommended)
Emscripten 3.1.58+

Please note the following additional notices:

Ensure you have installed the [Desktop development with C++] and [Universal Windows Platform development] components for VS2019.
It is highly recommended to use the latest version of CMake. Many older versions of CMake may have various bugs across different platforms.

Branch Management

The main branch is our active development branch, containing the latest features and bug fixes.
The branches under release/ are our stable milestone branches, which are fully tested. We periodically create a release/{version} branch from the main branch. Once a release/{version} branch is created, only high-priority fixes are checked into it.

Dependencies

TGFX uses the depsync tool to manage third-party dependencies.

For macOS platform：

Run this script from the root of the project:

./sync_deps.sh

This script will automatically install the necessary tools and sync all third-party repositories.

For other platforms:

First, ensure you have the latest version of Node.js installed (you may need to restart your computer afterward). Then, run the following command to install the depsync tool:

npm install -g depsync

Then, run depsync in the project's root directory.

depsync

You might need to enter your Git account and password during synchronization. Make sure you’ve enabled the git-credential-store so that CMakeLists.txt can automatically trigger synchronization next time.

Getting Started

We provide concise demos for various platforms to help you integrate the tgfx library into your project. After building the project, you'll have a simple app that renders different test cases from the drawers/ directory. These test cases include rendering shapes, images, and basic text. You can switch between test cases with a simple touch on the screen. For more guidance on API usage, check out the test cases in the test/ directories, which can offer valuable insights and assistance.

Before building the demo projects, please carefully follow the instructions in the Build Prerequisites and Dependencies sections. These will guide you through the necessary steps to set up your development environment.

Android

The Android demo project requires the Android NDK. We recommend using version 20.1.5948944, which has been fully tested with the TGFX library. If you open the project with Android Studio, it will automatically download the NDK during Gradle synchronization. Alternatively, you can download it from the NDK Downloads page.

If you choose to manually download the Android NDK, please extract it to the default location. On macOS, this would be:

/Users/yourname/Library/Android/sdk/ndk/20.1.5948944

On Windows, it would be：

C:\Users\yourname\AppData\Local\Android\Sdk\ndk\20.1.5948944

Alternatively, you can set one of the following environment variables to help tgfx locate the NDK:

["ANDROID_NDK_HOME", "ANDROID_NDK_ROOT", "ANDROID_NDK", "NDK_HOME", "NDK_ROOT", "NDK_PATH"]

To get started, open the android/ directory in Android Studio. If you encounter any issues during Gradle synchronization, make sure you haven't accidentally clicked on any pop-up hints for Gradle version upgrades. If you have, undo the changes and try synchronizing again. If the issue is related to your IDE configuration, search for a solution on Google. If you believe the problem is with the project configuration, you can open an Issue to address it.

iOS

In the ios/ directory, run the following command or double-click it:

./gen_ios

This will generate an Xcode project for iPhone devices. To generate a project for simulators instead, use the following command:

./gen_simulator

This will generate a simulator project for the native architecture, such as arm64 for Apple Silicon Macs and x64 for Intel Macs. If you want to generate a project for a specific architecture, use the -a option:

./gen_simulator -a x64

You can also pass CMake options using the -D flag. For example, to enable WebP encoding support, run:

./gen_ios -DTGFX_USE_WEBP_ENCODE=ON

Finally, open Xcode and launch the ios/Hello2D.xcworkspace to build and run the demo project.

macOS

In the mac/ directory, run the following command or double-click it:

./gen_mac

This will generate a project for the native architecture, such as arm64 for Apple Silicon Macs or x64 for Intel Macs. If you want to generate a project for a specific architecture, use the -a option, for example:

./gen_mac -a x64

You can also pass CMake options using the -D flag. For example, to enable FreeType support, run:

./gen_mac -DTGFX_USE_FREETYPE=ON

Finally, open Xcode and launch the mac/Hello2D.xcworkspace. You are all set!

Web

To run the web demo, you need the Emscripten SDK. You can download and install it from the official website. We recommend using the latest version. If you’re on macOS, you can also install it using the following script:

brew install emscripten

To get started, go to the web/ directory and run the following command to install the necessary node modules:

npm install

Then, in the web/ directory, run the following command to build the demo project:

npm run build

This will generate the hello2d.js and hello2d.wasm files in the web/demo/wasm directory. Next, you can start an HTTP server by running the following command:

npm run server

This will open http://localhost:8081/web/demo/index.html in your default browser. You can also open it manually to view the demo.

To debug the C++ code, install the browser plugin: C/C++ DevTools Support (DWARF). Then, open Chrome DevTools, go to Settings > Experiments, and enable the option WebAssembly Debugging: Enable DWARF support.

Next, replace the previous build command with:

npm run build:debug

With these steps completed, you can debug C++ files directly in Chrome DevTools.

The above commands build and run a multithreaded version.

⚠️ In the multithreaded version, if you modify the filename of the compiled output hello2d.js, you need to search for the keyword "hello2d.js" within the hello2d.js file and replace all occurrences of "hello2d.js" with the new filename. Failure to do this will result in the program failing to run. Here's an example of how to modify it:

Before modification:

    // filename: hello2d.js
    var worker = new Worker(new URL("hello2d.js", import.meta.url), {
     type: "module",
     name: "em-pthread"
    });

After modification:

    // filename: hello2d-test.js
    var worker = new Worker(new URL("hello2d-test.js", import.meta.url), {
     type: "module",
     name: "em-pthread"
    });

To build a single-threaded version, just add the suffix ":st" to each command. For example:

npm run build:st
npm run build:st:debug
npm run server:st

To build the demo project in CLion, open the Settings panel and go to Build, Execution, Deployment > CMake. Create a new build target and set the CMake options to:

DCMAKE_TOOLCHAIN_FILE="path/to/emscripten/emscripten/version/cmake/Modules/Platform/Emscripten.cmake"

After creating the build target, adjust the Configurations to match the new build target. This will allow you

Tgfx

Install / Use

README