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

package/cpp/third_party/tgfx/include/tgfx/gpu/Device.h

@@ -0,0 +1,79 @@
+/////////////////////////////////////////////////////////////////////////////////////////////////
+//
+//  Tencent is pleased to support the open source community by making tgfx available.
+//
+//  Copyright (C) 2023 Tencent. All rights reserved.
+//
+//  Licensed under the BSD 3-Clause License (the "License"); you may not use this file except
+//  in compliance with the License. You may obtain a copy of the License at
+//
+//      https://opensource.org/licenses/BSD-3-Clause
+//
+//  unless required by applicable law or agreed to in writing, software distributed under the
+//  license is distributed on an "as is" basis, without warranties or conditions of any kind,
+//  either express or implied. see the license for the specific language governing permissions
+//  and limitations under the license.
+//
+/////////////////////////////////////////////////////////////////////////////////////////////////
+
+#pragma once
+
+#include <atomic>
+#include <memory>
+#include <mutex>
+
+namespace tgfx {
+class Context;
+class GPU;
+
+/**
+ * The GPU interface for drawing graphics.
+ */
+class Device {
+ public:
+  virtual ~Device();
+
+  /**
+   * Returns a global unique ID for this device.
+   */
+  uint32_t uniqueID() const {
+    return _uniqueID;
+  }
+
+  /**
+   * Locks the rendering context associated with this device. If another thread has already locked
+   * the device by lockContext(), a call to lockContext() will block execution until the device
+   * is available. The returned context can be used to draw graphics. A nullptr is returned if the
+   * context cannot be locked on the calling thread (e.g., the GPU context has been permanently lost
+   * due to a GPU reset), and leaves the device unlocked.
+   */
+  Context* lockContext();
+
+  /**
+   * Unlocks the device. After this method is called all subsequent calls on the previously returned
+   * context will be invalid and may lead to runtime crash.
+   */
+  void unlock();
+
+ protected:
+  std::mutex locker = {};
+  GPU* _gpu = nullptr;
+  Context* context = nullptr;
+  std::weak_ptr<Device> weakThis;
+  /**
+   * A permanent one-way flag indicating the GPU context has been irreversibly lost (e.g., due to a
+   * GPU reset). Once set to true, lockContext() will always return nullptr.
+   */
+  std::atomic<bool> _contextLost{false};
+
+  explicit Device(std::unique_ptr<GPU> gpu);
+  virtual bool onLockContext();
+  virtual void onUnlockContext();
+
+ private:
+  uint32_t _uniqueID = 0;
+  bool contextLocked = false;
+
+  friend class ResourceCache;
+};
+}  // namespace tgfx

package/cpp/third_party/tgfx/include/tgfx/gpu/FilterMode.h

@@ -0,0 +1,36 @@
+/////////////////////////////////////////////////////////////////////////////////////////////////
+//
+//  Tencent is pleased to support the open source community by making tgfx available.
+//
+//  Copyright (C) 2025 Tencent. All rights reserved.
+//
+//  Licensed under the BSD 3-Clause License (the "License"); you may not use this file except
+//  in compliance with the License. You may obtain a copy of the License at
+//
+//      https://opensource.org/licenses/BSD-3-Clause
+//
+//  unless required by applicable law or agreed to in writing, software distributed under the
+//  license is distributed on an "as is" basis, without warranties or conditions of any kind,
+//  either express or implied. see the license for the specific language governing permissions
+//  and limitations under the license.
+//
+/////////////////////////////////////////////////////////////////////////////////////////////////
+
+#pragma once
+
+namespace tgfx {
+/**
+ * FilterMode defines how texture sampling is performed when a texture is minified or magnified.
+ */
+enum class FilterMode {
+  /**
+   * Single sample point (the nearest neighbor)
+   */
+  Nearest,
+
+  /**
+   * Interpolate between 2x2 sample points (bi-linear interpolation)
+   */
+  Linear,
+};
+}  // namespace tgfx

package/cpp/third_party/tgfx/include/tgfx/gpu/GPU.h

@@ -0,0 +1,162 @@
+/////////////////////////////////////////////////////////////////////////////////////////////////
+//
+//  Tencent is pleased to support the open source community by making tgfx available.
+//
+//  Copyright (C) 2023 Tencent. All rights reserved.
+//
+//  Licensed under the BSD 3-Clause License (the "License"); you may not use this file except
+//  in compliance with the License. You may obtain a copy of the License at
+//
+//      https://opensource.org/licenses/BSD-3-Clause
+//
+//  unless required by applicable law or agreed to in writing, software distributed under the
+//  license is distributed on an "as is" basis, without warranties or conditions of any kind,
+//  either express or implied. see the license for the specific language governing permissions
+//  and limitations under the license.
+//
+/////////////////////////////////////////////////////////////////////////////////////////////////
+
+#pragma once
+
+#include <memory>
+#include "tgfx/gpu/Backend.h"
+#include "tgfx/gpu/CommandEncoder.h"
+#include "tgfx/gpu/CommandQueue.h"
+#include "tgfx/gpu/GPUFeatures.h"
+#include "tgfx/gpu/GPUInfo.h"
+#include "tgfx/gpu/GPULimits.h"
+#include "tgfx/gpu/RenderPipeline.h"
+#include "tgfx/gpu/Sampler.h"
+#include "tgfx/gpu/ShaderModule.h"
+#include "tgfx/platform/HardwareBuffer.h"
+
+namespace tgfx {
+/**
+ * This is the main interface for accessing GPU functionality. In Metal, Vulkan, and WebGPU, its
+ * equivalents are MTLDevice, VkDevice, and GPUDevice. For OpenGL, it simply refers to GL functions.
+ */
+class GPU {
+ public:
+  virtual ~GPU() = default;
+
+  /**
+   * Returns a GPUInfo object containing detailed information about this GPU.
+   */
+  virtual const GPUInfo* info() const = 0;
+
+  /**
+   * Returns a GPUFeatures object describing the features supported by this GPU.
+   */
+  virtual const GPUFeatures* features() const = 0;
+
+  /**
+   * Returns a GPULimits object describing the limits of this GPU.
+   */
+  virtual const GPULimits* limits() const = 0;
+
+  /**
+   * Returns the primary CommandQueue associated with this GPU.
+   */
+  virtual CommandQueue* queue() const = 0;
+
+  /**
+   * Creates a GPUBuffer with the specified size and usage flags. The usage flags determine how the
+   * buffer can be used in GPU operations, such as vertex or index buffers.
+   * @param size The size of the buffer in bytes.
+   * @param usage The usage flags for the buffer, defined in GPUBufferUsage.
+   * @return A unique pointer to the created GPUBuffer. The caller is responsible for managing the
+   * lifetime of the buffer. If the creation fails, it returns nullptr.
+   */
+  virtual std::shared_ptr<GPUBuffer> createBuffer(size_t size, uint32_t usage) = 0;
+
+  /**
+   * Returns true if the given pixel format is renderable, meaning it can be used as a render target
+   * in a render pass.
+   */
+  virtual bool isFormatRenderable(PixelFormat pixelFormat) const = 0;
+
+  /**
+   * Finds a supported sample count for a render target with the given format that is greater than
+   * or equal to the requested count, or returns 1 if no such sample count is available.
+   */
+  virtual int getSampleCount(int requestedCount, PixelFormat pixelFormat) const = 0;
+
+  /**
+   * Creates a new texture with the given descriptor. The descriptor specifies the texture's
+   * properties, such as width, height, format, mip levels, sample count and usage flags. Returns
+   * nullptr if the texture cannot be created.
+   */
+  virtual std::shared_ptr<Texture> createTexture(const TextureDescriptor& descriptor) = 0;
+
+  /**
+   * Creates one or more textures from a platform-specific hardware buffer, such as AHardwareBuffer
+   * on Android or CVPixelBufferRef on Apple platforms. Multiple textures may be created from the
+   * same hardwareBuffer, especially for YUV formats.
+   * @param hardwareBuffer The platform-specific hardware buffer to import textures from.
+   * @param usage A bitmask of TextureUsage flags specifying how the textures will be used.
+   * @return An empty vector if the hardwareBuffer is invalid or not supported by the GPU backend.
+   */
+  virtual std::vector<std::shared_ptr<Texture>> importHardwareTextures(
+      HardwareBufferRef hardwareBuffer, uint32_t usage) = 0;
+
+  /**
+   * Creates a new Texture that wraps the specified backend texture.
+   * @param backendTexture The backend texture to be wrapped.
+   * @param usage A bitmask of TextureUsage flags specifying how the texture will be used.
+   * @param adopted If true, the returned Texture takes ownership of the backend texture and will
+   * destroy it when no longer needed. If false, the backend texture must remain valid for the
+   * lifetime of the returned Texture.
+   * @return A unique pointer to the created Texture. Returns nullptr if the backend texture is
+   * invalid or not supported by the GPU backend.
+   */
+  virtual std::shared_ptr<Texture> importBackendTexture(const BackendTexture& backendTexture,
+                                                        uint32_t usage, bool adopted = false) = 0;
+
+  /**
+   * Creates a new Texture that wraps the given backend render target. The caller must ensure the
+   * backend render target is valid for the lifetime of the returned Texture. Returns nullptr if the
+   * backend render target is invalid.
+   */
+  virtual std::shared_ptr<Texture> importBackendRenderTarget(
+      const BackendRenderTarget& backendRenderTarget) = 0;
+
+  /**
+   * Creates a Semaphore that wraps the specified BackendSemaphore. The returned Semaphore takes
+   * ownership of the BackendSemaphore and will destroy it when no longer needed. Returns nullptr
+   * if the BackendSemaphore is invalid or not supported by the GPU backend.
+   */
+  virtual std::shared_ptr<Semaphore> importBackendSemaphore(const BackendSemaphore& semaphore) = 0;
+
+  /**
+   * Transfers ownership of the BackendSemaphore from a uniquely owned Semaphore to the caller.
+   * After this call, the caller is responsible for managing the returned BackendSemaphore. You must
+   * use std::move() to pass the Semaphore, and it will be released during this process. Returns an
+   * empty BackendSemaphore if the Semaphore is nullptr or not uniquely owned.
+   */
+  virtual BackendSemaphore stealBackendSemaphore(std::shared_ptr<Semaphore> semaphore) = 0;
+
+  /**
+   * Creates a GPU sampler with the specified descriptor.
+   */
+  virtual std::shared_ptr<Sampler> createSampler(const SamplerDescriptor& descriptor) = 0;
+
+  /**
+   * Creates a ShaderModule from the provided shader code. The shader code must be valid and
+   * compatible with the GPU backend. Returns nullptr if the shader module creation fails.
+   */
+  virtual std::shared_ptr<ShaderModule> createShaderModule(
+      const ShaderModuleDescriptor& descriptor) = 0;
+
+  /**
+   * Creates a RenderPipeline that manages the vertex and fragment shader stages for use in a
+   * RenderPass. Returns nullptr if pipeline creation fails.
+   */
+  virtual std::shared_ptr<RenderPipeline> createRenderPipeline(
+      const RenderPipelineDescriptor& descriptor) = 0;
+
+  /**
+   * Creates a command encoder that can be used to encode commands to be issued to the GPU.
+   */
+  virtual std::shared_ptr<CommandEncoder> createCommandEncoder() = 0;
+};
+}  // namespace tgfx

package/cpp/third_party/tgfx/include/tgfx/gpu/GPUBuffer.h

@@ -0,0 +1,122 @@
+/////////////////////////////////////////////////////////////////////////////////////////////////
+//
+//  Tencent is pleased to support the open source community by making tgfx available.
+//
+//  Copyright (C) 2023 Tencent. All rights reserved.
+//
+//  Licensed under the BSD 3-Clause License (the "License"); you may not use this file except
+//  in compliance with the License. You may obtain a copy of the License at
+//
+//      https://opensource.org/licenses/BSD-3-Clause
+//
+//  unless required by applicable law or agreed to in writing, software distributed under the
+//  license is distributed on an "as is" basis, without warranties or conditions of any kind,
+//  either express or implied. see the license for the specific language governing permissions
+//  and limitations under the license.
+//
+/////////////////////////////////////////////////////////////////////////////////////////////////
+
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+#include <limits>
+
+namespace tgfx {
+static constexpr size_t GPU_BUFFER_WHOLE_SIZE = std::numeric_limits<size_t>::max();
+
+class GPU;
+
+/**
+ * GPUBufferUsage defines the usage flags for GPU buffers.
+ */
+class GPUBufferUsage {
+ public:
+  /**
+   * The buffer can be used as an index buffer.
+   */
+  static constexpr uint32_t INDEX = 0x10;
+
+  /**
+   * The buffer can be used as a vertex buffer.
+   */
+  static constexpr uint32_t VERTEX = 0x20;
+
+  /**
+   * The buffer can be used as a uniform buffer.
+   */
+  static constexpr uint32_t UNIFORM = 0x40;
+
+  /**
+   * The buffer can be used as a readback buffer, allowing data to be transferred from the GPU back
+   * to the CPU.
+   */
+  static constexpr uint32_t READBACK = 0x800;
+};
+
+/**
+ * GPUBuffer represents a block of GPU memory used to store raw data for GPU operations.
+ */
+class GPUBuffer {
+ public:
+  virtual ~GPUBuffer() = default;
+
+  /**
+   * Returns the size of the buffer in bytes. This size is determined at the time of buffer creation
+   * and cannot be changed later.
+   */
+  size_t size() const {
+    return _size;
+  }
+
+  /**
+   * Returns the bitwise flags that indicate the original usage options set when the GPUBuffer was
+   * created. The returned value is the sum of the decimal values for each flag. See GPUBufferUsage
+   * for more details.
+   */
+  uint32_t usage() const {
+    return _usage;
+  }
+
+  /**
+   * Checks if the GPUBuffer is ready for access. For readback buffers, this means the data transfer
+   * from the GPU to the CPU has finished. For other buffer types, this usually returns true
+   * immediately after creation.
+   */
+  virtual bool isReady() const = 0;
+
+  /**
+   * Requests asynchronous mapping of the buffer for readback. This is used by WebGPU and other
+   * backends that require explicit async operations. For other backends, this is a no-op.
+   * After calling this, poll isReady() until it returns true, then call map() to get the data.
+   */
+  virtual void requestMapAsync() {
+    // Default implementation is a no-op for backends that don't require async mapping
+  }
+
+  /**
+   * Maps a range of the GPUBuffer, allowing the CPU to directly access a specific portion of its
+   * memory for reading or writing. For readback buffers, this method may block until the data
+   * transfer from the GPU to the CPU is complete, if the backend supports blocking. After
+   * finishing, call unmap() to release the mapping and allow the GPU to access the buffer again.
+   * @param offset The byte offset from the start of the buffer where mapping begins.
+   * @param size The number of bytes to map. If set to GPU_BUFFER_WHOLE_SIZE, the mapping will cover
+   * the buffer from the offset to the end.
+   * @return A pointer to the mapped memory region, or nullptr if mapping fails, or if the readback
+   * buffer is not ready and blocking is not supported.
+   */
+  virtual void* map(size_t offset = 0, size_t size = GPU_BUFFER_WHOLE_SIZE) = 0;
+
+  /**
+   * Unmaps the GPUBuffer, making its contents available for use by the GPU again.
+   */
+  virtual void unmap() = 0;
+
+ protected:
+  size_t _size = 0;
+  uint32_t _usage = 0;
+
+  GPUBuffer(size_t size, uint32_t usage) : _size(size), _usage(usage) {
+  }
+};
+}  // namespace tgfx

package/cpp/third_party/tgfx/include/tgfx/gpu/GPUFeatures.h

@@ -0,0 +1,51 @@
+/////////////////////////////////////////////////////////////////////////////////////////////////
+//
+//  Tencent is pleased to support the open source community by making tgfx available.
+//
+//  Copyright (C) 2025 Tencent. All rights reserved.
+//
+//  Licensed under the BSD 3-Clause License (the "License"); you may not use this file except
+//  in compliance with the License. You may obtain a copy of the License at
+//
+//      https://opensource.org/licenses/BSD-3-Clause
+//
+//  unless required by applicable law or agreed to in writing, software distributed under the
+//  license is distributed on an "as is" basis, without warranties or conditions of any kind,
+//  either express or implied. see the license for the specific language governing permissions
+//  and limitations under the license.
+//
+/////////////////////////////////////////////////////////////////////////////////////////////////
+
+#pragma once
+
+namespace tgfx {
+/**
+ * GPUFeatures describes the various optional features supported by the GPU.
+ */
+class GPUFeatures {
+ public:
+  /**
+   * Indicates if the GPU supports semaphore synchronization primitives.
+   */
+  bool semaphore = false;
+
+  /**
+   * Indicates whether the GPU supports the CLAMP_TO_BORDER wrap mode for texture coordinates.
+   */
+  bool clampToBorder = false;
+
+  /**
+   * Indicates whether the GPU supports texture barriers. If true, texture writes are
+   * immediately visible to subsequent texture reads without needing to flush the pipeline.
+   */
+  bool textureBarrier = false;
+
+  /**
+   * Indicates whether the GPU can allocate and render into a stencil attachment (typically
+   * DEPTH24_STENCIL8 or a D32S8 fallback). This is a pure hardware / driver capability bit;
+   * whether any particular renderer chooses to consume it (e.g. the stencil-and-cover path
+   * renderer) is decided by higher-level code, not by this field.
+   */
+  bool stencilAttachmentSupported = false;
+};
+}  // namespace tgfx

package/cpp/third_party/tgfx/include/tgfx/gpu/GPUInfo.h

@@ -0,0 +1,56 @@
+/////////////////////////////////////////////////////////////////////////////////////////////////
+//
+//  Tencent is pleased to support the open source community by making tgfx available.
+//
+//  Copyright (C) 2025 Tencent. All rights reserved.
+//
+//  Licensed under the BSD 3-Clause License (the "License"); you may not use this file except
+//  in compliance with the License. You may obtain a copy of the License at
+//
+//      https://opensource.org/licenses/BSD-3-Clause
+//
+//  unless required by applicable law or agreed to in writing, software distributed under the
+//  license is distributed on an "as is" basis, without warranties or conditions of any kind,
+//  either express or implied. see the license for the specific language governing permissions
+//  and limitations under the license.
+//
+/////////////////////////////////////////////////////////////////////////////////////////////////
+
+#pragma once
+
+#include <string>
+#include <vector>
+#include "tgfx/gpu/Backend.h"
+
+namespace tgfx {
+/**
+ * GPUInfo contains descriptive information about the GPU.
+ */
+class GPUInfo {
+ public:
+  /**
+   * Returns the backend API used by the GPU.
+   */
+  Backend backend = Backend::Unknown;
+
+  /**
+   * Returns the version string of the GPU.
+   */
+  std::string version;
+
+  /**
+   * Returns the renderer string of the GPU.
+   */
+  std::string renderer;
+
+  /**
+   * Returns the vendor string of the GPU.
+   */
+  std::string vendor;
+
+  /**
+   * Returns a list of supported extensions by the GPU.
+   */
+  std::vector<std::string> extensions = {};
+};
+}  // namespace tgfx

package/cpp/third_party/tgfx/include/tgfx/gpu/GPULimits.h

@@ -0,0 +1,55 @@
+/////////////////////////////////////////////////////////////////////////////////////////////////
+//
+//  Tencent is pleased to support the open source community by making tgfx available.
+//
+//  Copyright (C) 2025 Tencent. All rights reserved.
+//
+//  Licensed under the BSD 3-Clause License (the "License"); you may not use this file except
+//  in compliance with the License. You may obtain a copy of the License at
+//
+//      https://opensource.org/licenses/BSD-3-Clause
+//
+//  unless required by applicable law or agreed to in writing, software distributed under the
+//  license is distributed on an "as is" basis, without warranties or conditions of any kind,
+//  either express or implied. see the license for the specific language governing permissions
+//  and limitations under the license.
+//
+/////////////////////////////////////////////////////////////////////////////////////////////////
+
+#pragma once
+
+#include <cinttypes>
+
+namespace tgfx {
+/**
+ * GPULimits describes the various limits of the GPU.
+ */
+class GPULimits {
+ public:
+  /**
+   * Returns the maximum 2D texture dimension supported by the GPU.
+   */
+  int maxTextureDimension2D = 0;
+
+  /**
+   * Returns the maximum number of texture samplers available to a single shader stage.
+   */
+  int maxSamplersPerShaderStage = 0;
+
+  /**
+   * Returns the maximum size in bytes of a uniform buffer binding.
+   */
+  int64_t maxUniformBufferBindingSize = 0;
+
+  /**
+   * Returns the minimum required alignment in bytes for uniform buffer offsets.
+   */
+  int minUniformBufferOffsetAlignment = 0;
+
+  /**
+   * Returns the minimum required alignment in bytes for the bytesPerRow in buffer-texture copy
+   * operations. On WebGPU this is 256, on other backends it is typically 1 (no alignment).
+   */
+  int minBufferCopyRowAlignment = 1;
+};
+}  // namespace tgfx

package/cpp/third_party/tgfx/include/tgfx/gpu/ImageOrigin.h

@@ -0,0 +1,41 @@
+/////////////////////////////////////////////////////////////////////////////////////////////////
+//
+//  Tencent is pleased to support the open source community by making tgfx available.
+//
+//  Copyright (C) 2023 Tencent. All rights reserved.
+//
+//  Licensed under the BSD 3-Clause License (the "License"); you may not use this file except
+//  in compliance with the License. You may obtain a copy of the License at
+//
+//      https://opensource.org/licenses/BSD-3-Clause
+//
+//  unless required by applicable law or agreed to in writing, software distributed under the
+//  license is distributed on an "as is" basis, without warranties or conditions of any kind,
+//  either express or implied. see the license for the specific language governing permissions
+//  and limitations under the license.
+//
+/////////////////////////////////////////////////////////////////////////////////////////////////
+
+#pragma once
+
+namespace tgfx {
+/**
+ * Textures and render targets can be stored such that (0, 0) in texture space may correspond to
+ * either the top-left or bottom-left content pixel.
+ */
+enum class ImageOrigin {
+  /**
+   * The default origin of the native coordinate system in the GPU backend. For example, the
+   * ImageOrigin::TopLeft is actually the bottom-left origin in the OpenGL coordinate system for
+   * textures. Textures newly created by the backend API for off-screen rendering usually have an
+   * ImageOrigin::TopLeft origin.
+   */
+  TopLeft,
+
+  /**
+   * Use this origin to flip the content on the y-axis if the GPU backend has a different origin to
+   * your system views. It is usually used for on-screen rendering.
+   */
+  BottomLeft
+};
+}  // namespace tgfx

package/cpp/third_party/tgfx/include/tgfx/gpu/MipmapMode.h

@@ -0,0 +1,39 @@
+/////////////////////////////////////////////////////////////////////////////////////////////////
+//
+//  Tencent is pleased to support the open source community by making tgfx available.
+//
+//  Copyright (C) 2025 Tencent. All rights reserved.
+//
+//  Licensed under the BSD 3-Clause License (the "License"); you may not use this file except
+//  in compliance with the License. You may obtain a copy of the License at
+//
+//      https://opensource.org/licenses/BSD-3-Clause
+//
+//  unless required by applicable law or agreed to in writing, software distributed under the
+//  license is distributed on an "as is" basis, without warranties or conditions of any kind,
+//  either express or implied. see the license for the specific language governing permissions
+//  and limitations under the license.
+//
+/////////////////////////////////////////////////////////////////////////////////////////////////
+
+#pragma once
+
+namespace tgfx {
+/**
+ * MipmapMode defines how mipmap levels are selected during texture sampling.
+ */
+enum class MipmapMode {
+  /**
+   * Ignore mipmap levels, sample from the "base"
+   */
+  None,
+  /**
+   * Sample from the nearest level
+   */
+  Nearest,
+  /**
+   * Interpolate between the two nearest levels
+   */
+  Linear,
+};
+}  // namespace tgfx