{"id":19965643,"url":"https://github.com/tencent/tgfx","last_synced_at":"2025-05-14T18:01:52.446Z","repository":{"id":201140253,"uuid":"707007021","full_name":"Tencent/tgfx","owner":"Tencent","description":"A lightweight 2D graphics library for rendering texts, geometries, and images with high-performance APIs that work across various platforms.","archived":false,"fork":false,"pushed_at":"2025-05-13T03:38:41.000Z","size":6833,"stargazers_count":1250,"open_issues_count":2,"forks_count":85,"subscribers_count":20,"default_branch":"main","last_synced_at":"2025-05-13T04:22:54.627Z","etag":null,"topics":["2d","filter","gpu","graphics","image","rendering","shape","text","tgfx"],"latest_commit_sha":null,"homepage":"https://tgfx.org","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Tencent.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-10-19T03:21:16.000Z","updated_at":"2025-05-12T13:25:16.000Z","dependencies_parsed_at":"2023-11-03T06:24:21.272Z","dependency_job_id":"af34c6b6-24b0-495b-b59d-2e176af1dcfa","html_url":"https://github.com/Tencent/tgfx","commit_stats":null,"previous_names":["libpag/tgfx","tencent/tgfx"],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tencent%2Ftgfx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tencent%2Ftgfx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tencent%2Ftgfx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tencent%2Ftgfx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Tencent","download_url":"https://codeload.github.com/Tencent/tgfx/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254198452,"owners_count":22030964,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["2d","filter","gpu","graphics","image","rendering","shape","text","tgfx"],"created_at":"2024-11-13T02:29:57.297Z","updated_at":"2025-05-14T18:01:47.429Z","avatar_url":"https://github.com/Tencent.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg src=\"resources/readme/TGFX.jpg\" alt=\"TGFX Logo\" width=\"992\"/\u003e\n\n[![license](https://img.shields.io/badge/license-BSD--3--Clause-blue)](https://github.com/Tencent/tgfx/blob/master/LICENSE.txt)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/Tencent/tgfx/pulls)\n[![codecov](https://codecov.io/gh/Tencent/tgfx/branch/main/graph/badge.svg)](https://codecov.io/gh/Tencent/tgfx)\n[![autotest](https://github.com/Tencent/tgfx/actions/workflows/autotest.yml/badge.svg?branch=main)](https://github.com/Tencent/tgfx/actions/workflows/autotest.yml)\n[![build](https://github.com/Tencent/tgfx/actions/workflows/build.yml/badge.svg?branch=main)](https://github.com/Tencent/tgfx/actions/workflows/build.yml)\n[![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/Tencent/tgfx)](https://github.com/Tencent/tgfx/releases)\n\n## Introduction\n\nTGFX (Tencent Graphics) is a lightweight 2D graphics library for rendering text, shapes, and images. \nIt offers high-performance APIs compatible with various GPU hardware and software platforms, including\niOS, Android, macOS, Windows, Linux, OpenHarmony, and the Web. Initially developed as the default \ngraphics engine for the [PAG](https://pag.io) project starting from version 4.0, TGFX aims to be a \ncompelling alternative to the Skia graphics library while maintaining a much smaller binary size.\nOver time, it has found its way into many other products, such as [Hippy](https://github.com/Tencent/Hippy), [Tencent Docs](https://docs.qq.com) \nand various video-editing apps.\n\n## Platform Support\n\n- iOS 9.0 or later\n- Android 4.4 or later\n- macOS 10.15 or later\n- Windows 7.0 or later\n- Chrome 69.0 or later (Web)\n- Safari 11.3 or later (Web)\n\n## Backing Renderers\n\n| Vector Backend |  GPU Backend   |      Target Platforms        |    Status     |\n|:--------------:|:--------------:|:----------------------------:|:-------------:|\n|    FreeType    |  OpenGL        |  All                         |   complete    |\n|  CoreGraphics  |  OpenGL        |  iOS, macOS                  |   complete    |\n|    Canvas2D    |  WebGL         |  Web                         |   complete    |\n|  CoreGraphics  |  Metal         |  iOS, macOS                  |  in progress  |\n|    FreeType    |  Vulkan        |  Android, Linux              |    planned    |\n\n\n## Branch Management\n\n- The `main` branch is our active development branch, containing the latest features and bug fixes.\n- The branches under `release/` are our stable milestone branches, which are fully tested. We \n  periodically create a `release/{version}` branch from the `main` branch. Once a `release/{version}` \n  branch is created, only high-priority fixes are checked into it.\n\n## Build Prerequisites\n\nTGFX uses **C++17** features. Here are the minimum tools needed to build TGFX on different platforms:\n\n- Xcode 11.0+\n- GCC 9.0+\n- Visual Studio 2019+\n- NodeJS 14.14.0+\n- Ninja 1.9.0+\n- CMake 3.13.0+\n- QT 5.13.0+\n- NDK 19.2+ (**19.2.5345600 recommended**)\n- Emscripten 3.1.58+ \n\n\nPlease note the following additional notices:\n\n- Ensure you have installed the **[Desktop development with C++]** and **[Universal Windows Platform development]** components for VS2019.\n- It is **highly recommended** to use the **latest version of CMake**. Many older versions of CMake may have various bugs across different platforms.\n\n## Dependencies\n\nTGFX uses the [**depsync**](https://github.com/domchen/depsync) tool to manage third-party dependencies.\n\n**For macOS platform：**\n\nRun this script from the root of the project:\n\n```\n./sync_deps.sh\n```\n\nThis script will automatically install the necessary tools and sync all third-party repositories.\n\n**For other platforms:**\n\nFirst, ensure you have the latest version of Node.js installed (you may need to restart your computer afterward). \nThen, run the following command to install the depsync tool:\n\n```\nnpm install -g depsync\n```\n\nThen, run `depsync` in the project's root directory.\n\n```\ndepsync\n```\n\nYou might need to enter your Git account and password during synchronization. Make sure you’ve \nenabled the `git-credential-store` so that `CMakeLists.txt` can automatically trigger synchronization \nnext time.\n\n\n## Getting Started\n\nWe provide concise demos for various platforms to help you integrate the tgfx library into your \nproject. After building the project, you'll have a simple app that renders different test cases from\nthe `drawers/` directory. These test cases include rendering shapes, images, and basic text. You can\nswitch between test cases with a simple touch on the screen. For more guidance on API usage, check \nout the test cases in the `test/` directories, which can offer valuable insights and assistance.\n\nBefore building the demo projects, please carefully follow the instructions in the \n[**Build Prerequisites**](#build-prerequisites) and [**Dependencies**](#dependencies) sections. \nThese will guide you through the necessary steps to set up your development environment.\n\n### Android\n\nThe Android demo project requires the **Android NDK**. We recommend using version **19.2.5345600**,\nwhich has been fully tested with the TGFX library. If you open the project with Android Studio, it\nwill automatically download the NDK during Gradle synchronization. Alternatively, you can download \nit from the [NDK Downloads](https://developer.android.com/ndk/downloads) page.\n\nIf you choose to manually download the Android NDK, please extract it to the default location.\nOn macOS, this would be:\n\n```\n/Users/yourname/Library/Android/sdk/ndk/19.2.5345600\n```\n\nOn Windows, it would be：\n\n```\nC:\\Users\\yourname\\AppData\\Local\\Android\\Sdk\\ndk\\19.2.5345600\n```\n\nAlternatively, you can set one of the following environment variables to help tgfx locate the NDK:\n\n```\n[\"ANDROID_NDK_HOME\", \"ANDROID_NDK_ROOT\", \"ANDROID_NDK\", \"NDK_HOME\", \"NDK_ROOT\", \"NDK_PATH\"]\n```\n\nTo get started, open the `android/` directory in Android Studio. If you encounter any issues during \nGradle synchronization, make sure you haven't accidentally clicked on any pop-up hints for Gradle \nversion upgrades. If you have, undo the changes and try synchronizing again. If the issue is related\nto your IDE configuration, search for a solution on Google. If you believe the problem is with the \nproject configuration, you can open an [Issue](https://github.com/Tencent/tgfx/issues/new/choose) to\naddress it.\n\n### iOS\n\nIn the `ios/` directory, run the following command or double-click it:\n\n```\n./gen_ios\n```\n\nThis will generate an Xcode project for iPhone devices. To generate a project for simulators instead,\nuse the following command:\n\n```\n./gen_simulator\n```\n\nThis will generate a simulator project for the native architecture, such as `arm64` for Apple Silicon\nMacs and `x64` for Intel Macs. If you want to generate a project for a specific architecture, use \nthe `-a` option:\n\n```\n./gen_simulator -a x64\n```\n\nYou can also pass CMake options using the `-D` flag. For example, to enable WebP encoding support, run:\n\n```\n./gen_ios -DTGFX_USE_WEBP_ENCODE=ON\n```\n\nFinally, open Xcode and launch the `ios/Hello2D.xcworkspace` to build and run the demo project.\n\n### macOS\n\n\nIn the `mac/` directory, run the following command or double-click it:\n\n```\n./gen_mac\n```\n\nThis will generate a project for the native architecture, such as `arm64` for Apple Silicon Macs or \n`x64` for Intel Macs. If you want to generate a project for a specific architecture, use the `-a` \noption, for example:\n\n```\n./gen_mac -a x64\n```\n\nYou can also pass CMake options using the `-D` flag. For example, to enable FreeType support, run:\n\n```\n./gen_mac -DTGFX_USE_FREETYPE=ON\n```\n\nFinally, open Xcode and launch the `mac/Hello2D.xcworkspace`. You are all set!\n\n### Web\n\nTo run the web demo, you need the **Emscripten SDK**. You can download and install it from the \n[official website](https://emscripten.org/). We recommend using the latest version. If you’re on \nmacOS, you can also install it using the following script:\n\n```\nbrew install emscripten\n```\n\nTo get started, go to the `web/` directory and run the following command to install the necessary\nnode modules:\n\n```\nnpm install\n```\n\nThen, in the `web/` directory, run the following command to build the demo project:\n\n```\nnpm run build\n```\n\nThis will generate the `hello2d.js` and `hello2d.wasm` files in the `web/demo/wasm` directory.\nNext, you can start an HTTP server by running the following command:\n\n```\nnpm run server\n```\n\nThis will open [http://localhost:8081/web/demo/index.html](http://localhost:8081/web/demo/index.html) \nin your default browser. You can also open it manually to view the demo.\n\nTo debug the C++ code, install the browser plugin:\n[**C/C++ DevTools Support (DWARF)**](https://chromewebstore.google.com/detail/cc++-devtools-support-dwa/pdcpmagijalfljmkmjngeonclgbbannb).\nThen, open Chrome DevTools, go to Settings \u003e Experiments, and enable the option\n**WebAssembly Debugging: Enable DWARF support**.\n\nNext, replace the previous build command with:\n\n```\nnpm run build:debug\n```\n\nWith these steps completed, you can debug C++ files directly in Chrome DevTools.\n\nThe above commands build and run a multithreaded version. To build a single-threaded version,\njust add the suffix \":st\" to each command. For example:\n\n```\nnpm run build:st\nnpm run build:st:debug\nnpm run serser:st\n``` \n\nTo build the demo project in CLion, open the `Settings` panel and go to `Build, Execution, Deployment` \u003e `CMake`.\nCreate a new build target and set the `CMake options` to:\n\n```\nDCMAKE_TOOLCHAIN_FILE=\"path/to/emscripten/emscripten/version/cmake/Modules/Platform/Emscripten.cmake\"\n```\n\nAfter creating the build target, adjust the `Configurations` to match the new build target. This will \nallow you to build the tgfx library in CLion.\n\nAdditionally, when using `ESModule` for your project, you need to manually include the generated \n`.wasm` file in the final web program. Common packing tools often ignore the `.wasm` file. Also, \nmake sure to upload the `.wasm` file to a server so users can access it.\n\n### Linux\n\nOn Linux, systems often lack GPU hardware support. To address this, we use the [**SwiftShader**](https://github.com/google/swiftshader) \nlibrary to emulate a GPU rendering environment. Since SwiftShader depends on certain X11 header files,\nyou need to install the following packages before building the demo project:\n\n```\nyum install libX11-devel --nogpg\n```\n\nNext, run the following commands in the `linux/` directory:\n\n```\ncmake -B ./build -DCMAKE_BUILD_TYPE=Release\ncmake --build ./build -- -j 12\n```\n\nThe demo executable will be located in the build directory. You can also open the `linux/` directory\nin CLion and build the demo project directly in the IDE.\n\n### Windows\n\nTo get started, open the `win/` directory in CLion. Then, go to `File-\u003eSettings` and navigate to\n`Build, Execution, Deployment-\u003eToolChains`. Set the toolchain to `Visual Studio` with either `amd64`\n(recommended) or `x86` architecture. It's also recommended to use the `Ninja` generator for CMake to\nspeed up the build process. You can set this in `Build, Execution, Deployment-\u003eCMake` by choosing \n`Ninja` in the `Generator` row. Once done, you'll be able to build and run the `Hello2D` target.\n\nIf you prefer using Visual Studio IDE, open the `x64 Native Tools Command Prompt for VS 2019` and \nrun the following command in the `win/` directory:\n\n```\ncmake -G \"Visual Studio 16 2019\" -A x64 -DCMAKE_CONFIGURATION_TYPES=\"Debug\" -B ./Debug-x64\n```\n\nThis will generate a project for the `x64` architecture with the `Debug` configuration. To generate \na project for the `x86` architecture with the `Release` configuration, open the \n`x86 Native Tools Command Prompt for VS 2019` and run the following command:\n\n```\ncmake -G \"Visual Studio 16 2019\" -A Win32 -DCMAKE_CONFIGURATION_TYPES=\"Release\" -B ./Release-x86\n```\n\nFinally, open the `Hello2D.sln` file in the `Debug-x64/` or `Release-x86/` directory, and you’re all\nset!\n\n### QT\n\nFor **macOS** users, open the `qt/` directory in CLion. Then, go to the `qt/QTCMAKE.cfg` file and\nupdate the QT path to your local QT installation path. After that, you can build and run the \n`Hello2D` target.\n\nFor **Windows** users, make sure the ToolChain in CLion is set to `Visual Studio` with the `amd64` \narchitecture. Then, go to the `qt/` folder in CLion and find the `qt/QTCMAKE.cfg` file. Update the \nQT path to your local QT installation path. Next, in the configuration panel of the `Hello2D` target\nin CLion, set the local QT DLL library path in the `Environment Variables` field, \ne.g., `PATH=C:\\Qt\\6.6.1\\msvc2019_64\\bin`. Finally, you can build and run the `Hello2D` target.\n\n\n### OpenHarmony\n\nThe OpenHarmony demo project requires the **[DevEco](https://developer.huawei.com/consumer/cn/deveco-studio/)**\nIDE, which comes with the OpenHarmony SDK pre-installed. To get started, open the `ohos/` directory\nin DevEco. Then, go to `Preferences` \u003e `Build, Execution, Deployment` \u003e `Build Tools` \u003e `Hvigor` and\nuncheck the `Execute tasks in parallel mode (may require larger heap size)` option to avoid issues\nwith building third-party libraries.\n\nAlternatively, you can manually build the third-party libraries by running the following command in\nthe root directory:\n\n```\nnode build_vendor -p ohos\n```\n\nThis command will build the third-party libraries for the OpenHarmony platform and cache them in\nthe `third_party/out/` directory.\n\nFinally, connect your OpenHarmony device or start the simulator, then build and run the `hello2d`\ntarget in DevEco. You're all set!\n\n\n## Build Library\n\nAside from directly integrating the source code of tgfx into your project, you also have the option\nof linking with the precompiled libraries. TGFX uses the [**vendor\\_tools**](https://github.com/libpag/vendor_tools) \nproject as its build system, providing a unified way to build the tgfx library across all platforms.\n\nTo get started quickly, run the following command in the root directory:\n\n```\nnode build_tgfx\n```\n\nThis command builds the release version of the tgfx library for the native platform. After running\nit, you will find the compiled tgfx libraries in the `out/release` directory. To target a specific \nplatform, use the `-p [--platform]` option. Supported platforms are: `win`, `mac`, `ios`, `linux`, \n`android`, `web`, `ohos`.\n\n```\nnode build_tgfx -p ios\n```\n\nFor Apple platforms, you have the convenient `-x [--xcframework]` option available. This option \nenables you to effortlessly create xcframeworks:\n\n```\nnode build_tgfx -p mac -x\n```\n\nAfter running the command, you will find the `tgfx.xcframework` in the `out/release/mac` directory.\n\nYou can also pass CMake options using the `-D` prefix. For example, to build tgfx with FreeType \nsupport enabled, run:\n\n```\nnode build_tgfx -DTGFX_USE_FREETYPE=ON\n```\n\nFor more details and options, run the command with the `-h` or `--help` flag:\n\n```\nnode build_tgfx -h\n```\n\n\n## Contribution\n\nIf you have any ideas or suggestions to improve TGFX, feel free to start a \n[discussion](https://github.com/Tencent/tgfx/discussions/new/choose), open an [issue](https://github.com/Tencent/tgfx/issues/new/choose), \nor submit a [pull request](https://github.com/Tencent/tgfx/pulls). Before doing so, please read our\n[Contributing Guide](./CONTRIBUTING.md).\n\n## Support Us\n\nIf you find TGFX helpful, please give us a **Star**. We really appreciate your support :)\n\n[![Star History Chart](https://api.star-history.com/svg?repos=Tencent/tgfx\u0026type=Date)](https://star-history.com/#Tencent/tgfx\u0026Date)\n\n## License\n\nTGFX is licensed under the [BSD-3-Clause License](./LICENSE.txt)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftencent%2Ftgfx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftencent%2Ftgfx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftencent%2Ftgfx/lists"}