react-native-tgfx 0.0.0 → 0.0.2-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ritesh Shukla
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,141 @@
+react-native-tgfx
+Copyright (c) 2026 Ritesh Shukla
+
+This product is licensed under the MIT License (see LICENSE) and includes or
+builds against the third-party software listed below. Each component remains
+under its own license; the terms below are reproduced or referenced as those
+licenses require.
+
+================================================================================
+1. tgfx — BSD 3-Clause License
+================================================================================
+
+Distributed in this package at: cpp/third_party/tgfx/
+Source: https://github.com/Tencent/tgfx
+
+Tencent is pleased to support the open source community by making tgfx
+available.
+
+Copyright (C) 2025 Tencent. All rights reserved. The below software in this
+distribution may have been modified by Tencent ("Tencent Modifications"). All
+Tencent Modifications are Copyright (C) Tencent.
+
+The patches in patches/ are modifications to tgfx and are subject to the same
+license.
+
+The complete upstream notice, including tgfx's own third-party inventory, is
+preserved verbatim at cpp/third_party/tgfx/LICENSE.txt.
+
+Terms of the BSD 3-Clause License:
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+   may be used to endorse or promote products derived from this software
+   without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+================================================================================
+2. Components vendored by tgfx
+================================================================================
+
+This package ships no prebuilt binaries. tgfx and the components below are
+distributed as source and are compiled into the tgfx static library by the
+consuming app's own iOS or Android build.
+
+2a. Fetched by tgfx's DEPS
+
+cpp/third_party/tgfx/DEPS lists 21 repositories, which tgfx checks out into
+cpp/third_party/tgfx/third_party/. Nothing under that directory is tracked by
+git, so these sources are present in this package only when it is packed from
+a checkout in which the DEPS sync has run.
+
+  freetype                 The FreeType Project License (FTL) / GPLv2
+  libpng                   libpng License
+  zlib                     zlib License
+  libwebp                  BSD 3-Clause — Copyright (c) 2010 Google Inc.
+  libjpeg-turbo            IJG License / BSD 3-Clause / zlib
+  harfbuzz                 "Old MIT" License
+  libexpat                 MIT — Thai Open Source Software Center Ltd, et al.
+  pathkit                  BSD 3-Clause — Copyright (c) 2011 Google Inc.
+  skcms                    BSD 3-Clause — Copyright 2018 Google Inc.
+  highway                  Apache License 2.0 OR BSD 3-Clause — The Highway
+                           Project Authors
+  concurrentqueue          BSD 2-Clause — Copyright (c) 2013-2016 Cameron Desrochers
+  volk                     MIT — Copyright (c) 2018-2024 Arseny Kapoulkine
+  VulkanMemoryAllocator    MIT — Copyright (c) 2017-2025 Advanced Micro Devices, Inc.
+                           (tgfx's own LICENSE.txt summarises this as 2017-2024;
+                           the year here is from the pinned component's own file,
+                           which is the notice that must travel with what ships.)
+  Vulkan-Headers           Apache License 2.0 — The Khronos Group Inc.
+  shaderc                  Apache License 2.0 — The Shaderc Authors
+  SPIRV-Cross              Apache License 2.0 — The Khronos Group Inc.
+  tint                     Apache License 2.0 — The Dawn/Tint Authors
+  abseil-cpp               Apache License 2.0 — The Abseil Authors
+  nlohmann/json            MIT — Copyright (c) 2013-2021 Niels Lohmann
+  googletest               BSD 3-Clause — Copyright 2008 Google Inc. (tests only)
+  vendor_tools             MIT — Copyright (c) 2021-present, Dom Chen (build
+                           tooling only)
+
+2b. Present in tgfx's source tree but NOT distributed
+
+swiftshader and angle are committed under cpp/third_party/tgfx/vendor/, but that
+directory is outside this package's files allowlist, so neither is published.
+They are listed here only because tgfx's own LICENSE.txt covers them; this
+package ships no part of either.
+
+  swiftshader              Apache License 2.0 (not shipped)
+  angle                    BSD 3-Clause — The ANGLE Project Authors (not shipped)
+
+cpp/third_party/tgfx/LICENSE.txt reproduces the license terms for 18 of the
+above: freetype, libpng, libwebp, pathkit, skcms, highway, libjpeg-turbo, zlib,
+harfbuzz, libexpat, volk, VulkanMemoryAllocator, swiftshader, Vulkan-Headers,
+shaderc, SPIRV-Cross, angle and concurrentqueue. For the remaining five —
+vendor_tools, googletest, nlohmann/json, tint and abseil-cpp — the license file
+shipped in each component's own source tree applies.
+
+================================================================================
+3. Nitro Modules — MIT License
+================================================================================
+
+The sources under nitrogen/generated/ are produced by Nitrogen, part of
+react-native-nitro-modules.
+
+Copyright © Marc Rousavy @ Margelo
+Source: https://github.com/mrousavy/nitro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NitroTgfx.podspec

@@ -0,0 +1,69 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "NitroTgfx"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = package["homepage"]
+  # :text, not :file — acknowledgements render one blob, and NOTICE belongs in it.
+  s.license      = { :type => package["license"], :text => ["LICENSE", "NOTICE"].map { |f| File.read(File.join(__dir__, f), encoding: "UTF-8") }.join("\n") }
+  s.authors      = package["author"]
+
+  s.platforms    = { :ios => min_ios_version_supported }
+  s.source       = { :git => "https://github.com/riteshshukla04/react-native-tgfx.git", :tag => "#{s.version}" }
+  s.preserve_paths = ["LICENSE", "NOTICE"]
+
+  # IMPORTANT: only our own sources — NOT cpp/third_party/tgfx (built separately
+  # into a static lib by scripts/build-tgfx-ios.sh and linked via vendored_libraries).
+  s.source_files = [
+    # Implementation (Swift)
+    "ios/**/*.{swift}",
+    # Objective-C(++) view + bridging header
+    "ios/**/*.{h,m,mm}",
+    # Shared C++ engine (top-level cpp/ only)
+    "cpp/*.{hpp,cpp}",
+  ]
+
+  tgfx_dir = "$(PODS_TARGET_SRCROOT)/cpp/third_party/tgfx"
+
+  # Export contract for other native packages (see cpp/TgfxFrameSink.hpp): a pod
+  # that declares `s.dependency "NitroTgfx"` links this pod's objects into the
+  # same binary, so `tgfxrn::setFrame` resolves and there is exactly one
+  # ImageRegistry. The header reaches it as <NitroTgfx/TgfxFrameSink.hpp> from
+  # CocoaPods' per-pod header dir; the consumer adds the search path, because
+  # making cpp/*.hpp public here would drag C++ into this pod's Obj-C umbrella
+  # and break the Swift side. Android's equivalent is the prefab in
+  # android/build.gradle.
+  #
+  # The Obj-C(++) view header is exposed through the module umbrella (NOT a Swift
+  # bridging header — those are unsupported for framework/module pod targets), so
+  # the Swift HybridTgfxView can see TgfxMetalView in-module. Its C++ guts stay
+  # in the .mm; the header itself is pure Obj-C.
+  s.public_header_files = "ios/TgfxMetalView.h"
+
+  s.pod_target_xcconfig = {
+    "CLANG_CXX_LANGUAGE_STANDARD" => "c++20",
+    "HEADER_SEARCH_PATHS" => [
+      "\"#{tgfx_dir}/include\"",
+      "\"#{tgfx_dir}/third_party/json/single_include\"",
+      "\"$(PODS_TARGET_SRCROOT)/cpp\"",
+    ].join(" "),
+    "OTHER_LDFLAGS" => "-lc++",
+  }
+
+  # Prebuilt tgfx (+ vendored deps) static library, device + simulator slices.
+  # Build it first with:
+  #   bash packages/react-native-tgfx/scripts/build-tgfx-ios.sh
+  s.vendored_frameworks = "ios/libs/libtgfx.xcframework"
+
+  s.frameworks = "Metal", "QuartzCore", "CoreText", "CoreGraphics", "UIKit", "Foundation"
+
+  load 'nitrogen/generated/ios/NitroTgfx+autolinking.rb'
+  add_nitrogen_files(s)
+
+  s.dependency 'React-jsi'
+  s.dependency 'React-callinvoker'
+  install_modules_dependencies(s)
+end

package/README.md

@@ -1,5 +1,150 @@
 # react-native-tgfx
 
-Declarative [tgfx](https://github.com/Tencent/tgfx) GPU canvas for React Native, backed by Nitro Modules.
+A **declarative, Skia-style GPU 2D canvas** for React Native, backed by Tencent's
+[**tgfx**](https://github.com/Tencent/tgfx) and built with
+[**Nitro Modules**](https://nitro.margelo.com).
 
-Placeholder release — the implementation is in progress. Watch https://github.com/riteshshukla04/Tgfx.
+Render shapes, strokes, paths, gradients, images and text through a React
+component tree that compiles to a single native draw-program and runs on the GPU
+(Metal on iOS, OpenGL on Android).
+
+```tsx
+import { Canvas, Rect, Circle, Path, Image, Text, LinearGradient, useImage } from 'react-native-tgfx'
+
+function Hello() {
+  const img = useImage(require('./cat.png'))
+  return (
+    <Canvas style={{ flex: 1 }}>
+      <Rect x={0} y={0} width={120} height={80} color="lightblue" />
+
+      <Circle cx={160} cy={120} r={40} color="red" style="stroke" strokeWidth={6} strokeCap="round" />
+
+      <Path path="M0 200 q40 -60 80 0 t80 0" color="#5856D6" style="stroke" strokeWidth={5} />
+
+      <Rect x={0} y={260} width={160} height={70}>
+        <LinearGradient start={{ x: 0, y: 260 }} end={{ x: 160, y: 330 }} colors={['#FF6CAB', '#7366FF']} />
+      </Rect>
+
+      {img && <Image x={180} y={260} width={96} height={96} image={img} fit="cover" />}
+
+      <Text x={0} y={380} text="Hello tgfx" fontSize={24} color="#111" />
+    </Canvas>
+  )
+}
+```
+
+## How it works
+
+```
+<Canvas> children
+   │  (custom react-reconciler, persistence mode)
+   ▼
+immutable node tree ──► JSON draw-program (compiler) ──► `scene` prop
+   │
+   ▼  Nitro HybridView (TgfxView)
+Swift / Kotlin view shell (CAMetalLayer / TextureView)
+   │
+   ▼  shared C++ engine (nlohmann::json → tgfx::Canvas)
+tgfx ──► Metal (iOS) / OpenGL (Android) ──► GPU
+```
+
+- A dedicated **react-reconciler** turns the component tree into an immutable
+  scene and compiles it to a compact JSON program on every change.
+- A single Nitro **`TgfxView`** receives that program via its `scene` string prop.
+  The Swift/Kotlin shell only hosts the GPU surface; all drawing is shared C++.
+- Drawing happens on the platform's display-link / choreographer thread.
+
+## Components
+
+| Component | Key props |
+|---|---|
+| `Canvas` | `style`, `children` |
+| `Group` | `transform`, `origin`, `opacity` + inherited paint |
+| `Rect` / `Oval` | `x`, `y`, `width`, `height` |
+| `RoundedRect` | `x`, `y`, `width`, `height`, `r` (or `rx`/`ry`) |
+| `Circle` | `cx`, `cy`, `r` |
+| `Line` | `x1`, `y1`, `x2`, `y2` |
+| `Path` | `path` (SVG path data) |
+| `Image` | `x`, `y`, `width`, `height`, `image` (a `useImage` handle), `fit`, `sampling`, `rect` |
+| `Text` | `x`, `y`, `text`, `fontSize`, `fontFamily` |
+| `Paint` | paint as a child of a shape/group |
+| `LinearGradient` / `RadialGradient` | shader as a child of a shape/`Paint` |
+
+**Paint props** (on any drawing component, `Group`, or `Paint`): `color`,
+`style` (`'fill'` \| `'stroke'`), `strokeWidth`, `strokeCap`, `strokeJoin`,
+`opacity`, `antiAlias`.
+
+Colors accept hex (`'#rrggbb'`, `'#rgba'`), `rgb()/rgba()`, common names, or a
+packed `0xAARRGGBB` number.
+
+## Hooks
+
+- `useImageState(source)` — the same load as `useImage`, returning `{ data, error, loading }` so a slow load can be told from a failed one
+- `useImage(source)` — loads a `require()` asset, URL, `data:` URI, or base64
+  string into a native `TgfxImage` handle. Local files are decoded natively and
+  their bytes never enter JS; nothing is base64-encoded on the JS thread.
+- `setImageCacheLimit(bytes)` — byte budget for decoded images (64 MB). A
+  decoded image is resident twice, as CPU pixels and as the GPU texture uploaded
+  from them, so this is applied to both the pixel cache and tgfx's context cache.
+
+## Requirements
+
+- React Native **0.78+** with the **New Architecture** (Nitro Views are Fabric-only)
+- iOS: Xcode 16.4+, Metal; Android: NDK 27+, `compileSdk` 34+, OpenGL
+
+## Install (monorepo / local)
+
+tgfx is a git submodule built from source.
+
+```bash
+git submodule update --init --recursive
+# fetch tgfx's third_party (depsync) — see scripts/
+cd packages/react-native-tgfx/cpp/third_party/tgfx && depsync
+```
+
+Android builds tgfx automatically via CMake. For iOS, build the tgfx static lib
+once before `pod install`:
+
+```bash
+bash packages/react-native-tgfx/scripts/build-tgfx-ios.sh   # SIMULATORARM64 by default
+```
+
+## On-device rendering tests
+
+Rendering is verified with [React Native Harness][harness] image snapshots,
+which mount a real `<Canvas>` in the example app and screenshot it — no app
+navigation and no UI selectors.
+
+```bash
+cd apps/example
+npx react-native run-android          # rebuild once after adding @react-native-harness/ui
+npx react-native-harness --harnessRunner android-emulator
+```
+
+Tests live in `apps/example/src/*.harness.tsx`; baselines land in
+`apps/example/src/__image_snapshots__/<runner>/`. Runners are declared in
+`apps/example/rn-harness.config.mjs`.
+
+**`android-emulator` is the authoritative runner.** It targets the
+`Pixel_8_API_35` AVD, which anyone can recreate, so a diff there is a rendering
+change rather than a different phone. Review that set as the source of truth.
+
+The `android` runner (motorola moto g35 5G) is **advisory**: real GPU and real
+driver, but its baselines only ever match that one phone. GPU, density and
+anti-aliasing all move pixels, so a diff there on another device is not a
+regression — check the emulator before believing it.
+
+**Never delete a baseline to "fix" a failure.** A missing baseline is written on
+the spot and reported as a pass, so a checkout with no baselines passes without
+comparing anything. Regenerate deliberately: delete the file, re-run, then open
+the new PNG and confirm it is actually correct before committing it.
+
+Snapshot targets must use `composite="texture"`: a screenshot draws the view
+tree into a bitmap, and a `composite="layer"` canvas lives on its own
+compositor layer where nothing can see it.
+
+[harness]: https://react-native-harness.dev
+
+## License
+
+MIT — wraps tgfx (BSD-3-Clause) and Nitro (MIT).

package/android/CMakeLists.txt

@@ -0,0 +1,122 @@
+project(NitroTgfx)
+cmake_minimum_required(VERSION 3.18.0)
+
+set(PACKAGE_NAME NitroTgfx)
+set(CMAKE_VERBOSE_MAKEFILE ON)
+set(CMAKE_CXX_STANDARD 20)
+
+set(TGFX_DIR "${CMAKE_SOURCE_DIR}/../cpp/third_party/tgfx")
+
+# --- Build tgfx from source (OpenGL ES backend for Android) ---
+# tgfx's CMake unconditionally tries to git-sync shaderc's sub-deps, but shaderc
+# is only compiled for the Metal/Vulkan/WebGPU backends. The OpenGL backend used
+# here never needs it, so satisfy the existence check to skip the (offline-
+# failing) sync step.
+file(MAKE_DIRECTORY "${TGFX_DIR}/third_party/shaderc/third_party/glslang")
+
+# vendor_tools' vendor-build guesses its source dir from argv[1], which breaks
+# under the workspace symlink (node_modules/react-native-tgfx -> packages/...).
+# Force `-s ${CONFIG_DIR}` so it finds vendor.json at the tgfx root. Not a patch:
+# tgfx gitignores third_party/, which depsync re-fetches, so nothing is tracked.
+set(_vendor_cml "${TGFX_DIR}/third_party/vendor_tools/vendor.cmake")
+if (EXISTS "${_vendor_cml}")
+  file(READ "${_vendor_cml}" _vendor_cml_content)
+  if (NOT _vendor_cml_content MATCHES "vendor-build -s ")
+    string(REPLACE
+      "node \${VENDOR_TOOLS_DIR}/vendor-build "
+      "node \${VENDOR_TOOLS_DIR}/vendor-build -s \${CONFIG_DIR} "
+      _vendor_cml_content "${_vendor_cml_content}")
+    file(WRITE "${_vendor_cml}" "${_vendor_cml_content}")
+  endif ()
+endif ()
+
+set(TGFX_USE_OPENGL ON CACHE BOOL "" FORCE)
+set(TGFX_USE_METAL OFF CACHE BOOL "" FORCE)
+set(TGFX_USE_VULKAN OFF CACHE BOOL "" FORCE)
+set(TGFX_USE_WEBGPU OFF CACHE BOOL "" FORCE)
+set(TGFX_USE_QT OFF CACHE BOOL "" FORCE)
+set(TGFX_BUILD_LAYERS OFF CACHE BOOL "" FORCE)
+set(TGFX_BUILD_SVG OFF CACHE BOOL "" FORCE)
+set(TGFX_BUILD_PDF OFF CACHE BOOL "" FORCE)
+set(TGFX_BUILD_HELLO2D OFF CACHE BOOL "" FORCE)
+# tgfx only declares its embedded codec options for desktop targets (its
+# CMakeLists gates them on `NOT ANDROID AND NOT OHOS`), because Android normally
+# decodes through android.graphics.Bitmap. There is no matching platform
+# *encoder* behind ImageCodec::Encode, so Canvas.snapshot()/save() need the
+# embedded ones turned on explicitly — otherwise Encode returns null at runtime.
+# Setting the cache entries here still works: the `if (TGFX_USE_*_ENCODE)`
+# checks read them whether or not `option()` declared them.
+set(TGFX_USE_PNG_ENCODE ON CACHE BOOL "" FORCE)
+set(TGFX_USE_JPEG_ENCODE ON CACHE BOOL "" FORCE)
+set(TGFX_USE_WEBP_ENCODE ON CACHE BOOL "" FORCE)
+# The decoders, for the same reason and one more. Android's default is
+# BitmapFactory through JNI, which reads EXIF orientation only if
+# androidx.exifinterface is on the classpath — a photo shot in portrait
+# otherwise draws sideways. The embedded codecs parse the EXIF marker
+# themselves (JpegCodec::MakeFromData, WebpCodec), decode in-process with no JNI
+# round trip, and are the same code the host tests exercise, so the behaviour
+# can be tested at all. PNG was already on, but only incidentally, via
+# `if (TGFX_USE_FREETYPE) set(TGFX_USE_PNG_DECODE ON)`.
+# Nearly free: libjpeg-turbo and libwebp are already linked for the encoders
+# above, and only tgfx's own read paths are added — 1.4 KB of arm64 libNitroTgfx,
+# measured. Formats neither library covers (HEIF, AVIF) still take the platform
+# decoder, which is why androidx.exifinterface is a dependency too.
+set(TGFX_USE_PNG_DECODE ON CACHE BOOL "" FORCE)
+set(TGFX_USE_JPEG_DECODE ON CACHE BOOL "" FORCE)
+set(TGFX_USE_WEBP_DECODE ON CACHE BOOL "" FORCE)
+add_subdirectory(${TGFX_DIR} ${CMAKE_BINARY_DIR}/tgfx)
+
+# `set(... FORCE)` above only sets a cache entry; what decides whether a codec is
+# compiled in is the define reaching tgfx. tgfx re-exports its define list to the
+# parent scope, so assert against that rather than against our own input —
+# upstream renaming an option, or gating it differently, would otherwise fall
+# back to the platform decoder silently.
+foreach (_codec TGFX_USE_PNG_DECODE TGFX_USE_JPEG_DECODE TGFX_USE_WEBP_DECODE)
+  if (NOT "${_codec}" IN_LIST TGFX_DEFINES)
+    message(FATAL_ERROR
+      "${_codec} did not reach tgfx: image decoding would fall back to \
+BitmapFactory, which drops EXIF orientation. Check how tgfx's CMakeLists \
+consumes the codec options.")
+  endif ()
+endforeach ()
+
+# --- Our shared C++ engine + JNI bridge ---
+add_library(${PACKAGE_NAME} SHARED
+        src/main/cpp/cpp-adapter.cpp
+        src/main/cpp/TgfxAndroid.cpp
+        ../cpp/TgfxScene.cpp
+        ../cpp/SvgPath.cpp
+        ../cpp/TgfxRenderer.cpp
+        ../cpp/ImageRegistry.cpp
+        ../cpp/TgfxFrameSink.cpp
+        ../cpp/HybridTgfxImageFactory.cpp
+        ../cpp/FontRegistry.cpp
+        ../cpp/TextLayout.cpp
+        ../cpp/HybridTgfxFonts.cpp
+)
+
+# Add Nitrogen specs :)
+include(${CMAKE_SOURCE_DIR}/../nitrogen/generated/android/NitroTgfx+autolinking.cmake)
+
+# Set up includes (local, shared engine, tgfx, nlohmann/json)
+target_include_directories(${PACKAGE_NAME} PRIVATE
+        "src/main/cpp"
+        "../cpp"
+        "${TGFX_DIR}/include"
+        "${TGFX_DIR}/third_party/json/single_include"
+)
+
+find_library(LOG_LIB log)
+find_library(ANDROID_LIB android)
+find_library(EGL_LIB EGL)
+find_library(GLES_LIB GLESv2)
+
+# Link all libraries together
+target_link_libraries(
+        ${PACKAGE_NAME}
+        ${LOG_LIB}
+        ${ANDROID_LIB}
+        ${EGL_LIB}
+        ${GLES_LIB}
+        tgfx                                      # <-- tgfx static lib
+)

package/android/build.gradle

@@ -0,0 +1,172 @@
+buildscript {
+  repositories {
+    google()
+    mavenCentral()
+  }
+
+  dependencies {
+    classpath "com.android.tools.build:gradle:9.2.1"
+  }
+}
+
+def reactNativeArchitectures() {
+  def value = rootProject.getProperties().get("reactNativeArchitectures")
+  return value ? value.split(",") : ["armeabi-v7a", "x86", "x86_64", "arm64-v8a"]
+}
+
+def isNewArchitectureEnabled() {
+  return rootProject.hasProperty("newArchEnabled") && rootProject.getProperty("newArchEnabled") == "true"
+}
+
+apply plugin: "com.android.library"
+apply plugin: 'org.jetbrains.kotlin.android'
+apply from: '../nitrogen/generated/android/NitroTgfx+autolinking.gradle'
+apply from: "./fix-prefab.gradle"
+
+if (isNewArchitectureEnabled()) {
+  apply plugin: "com.facebook.react"
+}
+
+def getExtOrDefault(name) {
+  return rootProject.ext.has(name) ? rootProject.ext.get(name) : project.properties["NitroTgfx_" + name]
+}
+
+def getExtOrIntegerDefault(name) {
+  return rootProject.ext.has(name) ? rootProject.ext.get(name) : (project.properties["NitroTgfx_" + name]).toInteger()
+}
+
+android {
+  namespace "com.margelo.nitro.tgfx"
+
+  ndkVersion getExtOrDefault("ndkVersion")
+  compileSdkVersion getExtOrIntegerDefault("compileSdkVersion")
+
+  defaultConfig {
+    minSdkVersion getExtOrIntegerDefault("minSdkVersion")
+    targetSdkVersion getExtOrIntegerDefault("targetSdkVersion")
+    buildConfigField "boolean", "IS_NEW_ARCHITECTURE_ENABLED", isNewArchitectureEnabled().toString()
+    // ExifInterface is only ever reached through JNI, so R8 would drop it.
+    consumerProguardFiles "consumer-rules.pro"
+
+    externalNativeBuild {
+      cmake {
+        cppFlags "-frtti -fexceptions -Wall -Wextra -fstack-protector-all"
+        arguments "-DANDROID_STL=c++_shared", "-DANDROID_SUPPORT_FLEXIBLE_PAGE_SIZES=ON"
+        abiFilters (*reactNativeArchitectures())
+
+        buildTypes {
+          debug {
+            cppFlags "-O1 -g"
+          }
+          release {
+            cppFlags "-O2"
+          }
+        }
+      }
+    }
+  }
+
+  externalNativeBuild {
+    cmake {
+      path "CMakeLists.txt"
+    }
+  }
+
+  packagingOptions {
+    excludes = [
+            "META-INF",
+            "META-INF/**",
+            "**/libc++_shared.so",
+            "**/libNitroModules.so",
+            "**/libfbjni.so",
+            "**/libjsi.so",
+            "**/libfolly_json.so",
+            "**/libfolly_runtime.so",
+            "**/libglog.so",
+            "**/libhermes.so",
+            "**/libhermes-executor-debug.so",
+            "**/libhermes_executor.so",
+            "**/libreactnative.so",
+            "**/libreactnativejni.so",
+            "**/libturbomodulejsijni.so",
+            "**/libreact_nativemodule_core.so",
+            "**/libjscexecutor.so"
+    ]
+  }
+
+  buildFeatures {
+    buildConfig true
+    prefab true
+    // Publishes libNitroTgfx.so plus the headers copied by `prepareHeaders`
+    // below, so another native package can link the *same* ImageRegistry
+    // instead of compiling a second copy of it. See cpp/TgfxFrameSink.hpp.
+    prefabPublishing true
+  }
+
+  prefab {
+    NitroTgfx {
+      headers "${project.buildDir}/headers/nitrotgfx/"
+    }
+  }
+
+  buildTypes {
+    release {
+      minifyEnabled false
+    }
+  }
+
+  lintOptions {
+    disable "GradleCompatible"
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_1_8
+    targetCompatibility JavaVersion.VERSION_1_8
+  }
+
+  sourceSets {
+    main {
+      if (isNewArchitectureEnabled()) {
+        java.srcDirs += [
+          // React Codegen files
+          "${project.buildDir}/generated/source/codegen/java"
+        ]
+      }
+    }
+  }
+}
+
+repositories {
+  mavenCentral()
+  google()
+}
+
+
+dependencies {
+  // For < 0.71, this will be from the local maven repo
+  // For > 0.71, this will be replaced by `com.facebook.react:react-android:$version` by react gradle plugin
+  //noinspection GradleDynamicVersion
+  implementation "com.facebook.react:react-native:+"
+
+  // Add a dependency on NitroModules
+  implementation project(":react-native-nitro-modules")
+
+  // tgfx's Android NativeCodec looks this class up by name and discards EXIF
+  // orientation when it is missing. PNG, JPEG and WebP no longer go through it
+  // (see android/CMakeLists.txt), but every other format still does — a HEIF
+  // photo, which only the platform can decode, would otherwise draw sideways.
+  implementation "androidx.exifinterface:exifinterface:1.4.1"
+}
+
+// The prefab header payload. Exactly one file: TgfxFrameSink.hpp is the export
+// contract, and everything else under cpp/ stays unpublished on purpose — not
+// because including it would break anything (the symbols are exported with
+// default visibility either way), but because a header nobody can reach is a
+// header nobody depends on.
+tasks.register('prepareHeaders', Copy) {
+  from file('../cpp/TgfxFrameSink.hpp')
+  into "${project.buildDir}/headers/nitrotgfx/NitroTgfx/"
+}
+
+preBuild.dependsOn(prepareHeaders)
+