@shopify/react-native-skia 0.1.158 → 0.1.159

package/cpp/skia/include/gpu/MutableTextureState.h

@@ -0,0 +1,122 @@
+/*
+ * Copyright 2022 Google LLC.
+ *
+ * Use of this source code is governed by a BSD-style license that can be
+ * found in the LICENSE file.
+ */
+
+#ifndef skgpu_MutableTextureState_DEFINED
+#define skgpu_MutableTextureState_DEFINED
+
+#include "include/gpu/GpuTypes.h"
+
+#ifdef SK_VULKAN
+#include "include/private/gpu/vk/VulkanTypesPriv.h"
+#endif
+
+#include <new>
+
+class GrVkGpu;
+
+namespace skgpu {
+
+/**
+ * Since Skia and clients can both modify gpu textures and their connected state, Skia needs a way
+ * for clients to inform us if they have modifiend any of this state. In order to not need setters
+ * for every single API and state, we use this class to be a generic wrapper around all the mutable
+ * state. This class is used for calls that inform Skia of these texture/image state changes by the
+ * client as well as for requesting state changes to be done by Skia. The backend specific state
+ * that is wrapped by this class are:
+ *
+ * Vulkan: VkImageLayout and QueueFamilyIndex
+ */
+class SK_API MutableTextureState {
+public:
+    MutableTextureState() {}
+
+#ifdef SK_VULKAN
+    MutableTextureState(VkImageLayout layout, uint32_t queueFamilyIndex)
+            : fVkState(layout, queueFamilyIndex)
+            , fBackend(BackendApi::kVulkan)
+            , fIsValid(true) {}
+#endif
+
+    MutableTextureState(const MutableTextureState& that)
+            : fBackend(that.fBackend), fIsValid(that.fIsValid) {
+        if (!fIsValid) {
+            return;
+        }
+        switch (fBackend) {
+            case BackendApi::kVulkan:
+    #ifdef SK_VULKAN
+                SkASSERT(that.fBackend == BackendApi::kVulkan);
+                fVkState = that.fVkState;
+    #endif
+                break;
+            default:
+                (void)that;
+                SkUNREACHABLE;
+        }
+    }
+
+    MutableTextureState& operator=(const MutableTextureState& that) {
+        if (this != &that) {
+            this->~MutableTextureState();
+            new (this) MutableTextureState(that);
+        }
+        return *this;
+    }
+
+#ifdef SK_VULKAN
+    // If this class is not Vulkan backed it will return value of VK_IMAGE_LAYOUT_UNDEFINED.
+    // Otherwise it will return the VkImageLayout.
+    VkImageLayout getVkImageLayout() const {
+        if (this->isValid() && fBackend != BackendApi::kVulkan) {
+            return VK_IMAGE_LAYOUT_UNDEFINED;
+        }
+        return fVkState.getImageLayout();
+    }
+
+    // If this class is not Vulkan backed it will return value of VK_QUEUE_FAMILY_IGNORED.
+    // Otherwise it will return the VkImageLayout.
+    uint32_t getQueueFamilyIndex() const {
+        if (this->isValid() && fBackend != BackendApi::kVulkan) {
+            return VK_QUEUE_FAMILY_IGNORED;
+        }
+        return fVkState.getQueueFamilyIndex();
+    }
+#endif
+
+    BackendApi backend() const { return fBackend; }
+
+    // Returns true if the backend mutable state has been initialized.
+    bool isValid() const { return fIsValid; }
+
+private:
+    friend class MutableTextureStateRef;
+    friend class ::GrVkGpu;
+
+#ifdef SK_VULKAN
+    void setVulkanState(VkImageLayout layout, uint32_t queueFamilyIndex) {
+        SkASSERT(!this->isValid() || fBackend == BackendApi::kVulkan);
+        fVkState.setImageLayout(layout);
+        fVkState.setQueueFamilyIndex(queueFamilyIndex);
+        fBackend = BackendApi::kVulkan;
+        fIsValid = true;
+    }
+#endif
+
+    union {
+        char fPlaceholder;
+#ifdef SK_VULKAN
+        VulkanMutableTextureState fVkState;
+#endif
+    };
+
+    BackendApi fBackend = BackendApi::kMock;
+    bool fIsValid = false;
+};
+
+} // namespace skgpu
+
+#endif // skgpu_MutableTextureState_DEFINED

package/cpp/skia/include/gpu/gl/GrGLFunctions.h

@@ -47,6 +47,7 @@ using GrGLColorMaskFn = GrGLvoid GR_GL_FUNCTION_TYPE(GrGLboolean red, GrGLboolea
 using GrGLCompileShaderFn = GrGLvoid GR_GL_FUNCTION_TYPE(GrGLuint shader);
 using GrGLCompressedTexImage2DFn = GrGLvoid GR_GL_FUNCTION_TYPE(GrGLenum target, GrGLint level, GrGLenum internalformat, GrGLsizei width, GrGLsizei height, GrGLint border, GrGLsizei imageSize, const GrGLvoid* data);
 using GrGLCompressedTexSubImage2DFn = GrGLvoid GR_GL_FUNCTION_TYPE(GrGLenum target, GrGLint level, GrGLint xoffset, GrGLint yoffset, GrGLsizei width, GrGLsizei height, GrGLenum format, GrGLsizei imageSize, const GrGLvoid* data);
+using GrGLCopyBufferSubDataFn = GrGLvoid GR_GL_FUNCTION_TYPE(GrGLenum readTargt, GrGLenum writeTarget, GrGLintptr readOffset, GrGLintptr writeOffset, GrGLsizeiptr size);
 using GrGLCopyTexSubImage2DFn = GrGLvoid GR_GL_FUNCTION_TYPE(GrGLenum target, GrGLint level, GrGLint xoffset, GrGLint yoffset, GrGLint x, GrGLint y, GrGLsizei width, GrGLsizei height);
 using GrGLCreateProgramFn = GrGLuint GR_GL_FUNCTION_TYPE();
 using GrGLCreateShaderFn = GrGLuint GR_GL_FUNCTION_TYPE(GrGLenum type);

package/cpp/skia/include/gpu/gl/GrGLInterface.h

@@ -119,6 +119,7 @@ public:
         GrGLFunction<GrGLCompileShaderFn> fCompileShader;
         GrGLFunction<GrGLCompressedTexImage2DFn> fCompressedTexImage2D;
         GrGLFunction<GrGLCompressedTexSubImage2DFn> fCompressedTexSubImage2D;
+        GrGLFunction<GrGLCopyBufferSubDataFn> fCopyBufferSubData;
         GrGLFunction<GrGLCopyTexSubImage2DFn> fCopyTexSubImage2D;
         GrGLFunction<GrGLCreateProgramFn> fCreateProgram;
         GrGLFunction<GrGLCreateShaderFn> fCreateShader;

package/cpp/skia/include/gpu/graphite/BackendTexture.h

@@ -16,6 +16,10 @@
 #include "include/gpu/graphite/mtl/MtlTypes.h"
 #endif
 
+#ifdef SK_VULKAN
+#include "include/private/gpu/vk/SkiaVulkan.h"
+#endif
+
 namespace skgpu::graphite {
 
 class BackendTexture {
@@ -54,6 +58,9 @@ private:
     union {
 #ifdef SK_METAL
         MtlHandle fMtlTexture;
+#endif
+#ifdef SK_VULKAN
+        VkImage fVkImage;
 #endif
     };
 };

package/cpp/skia/include/gpu/graphite/CombinationBuilder.h

@@ -0,0 +1,195 @@
+/*
+ * Copyright 2022 Google LLC
+ *
+ * Use of this source code is governed by a BSD-style license that can be
+ * found in the LICENSE file.
+ */
+
+#ifndef skgpu_graphite_CombinationBuilder_DEFINED
+#define skgpu_graphite_CombinationBuilder_DEFINED
+
+#include "include/core/SkTypes.h"
+
+#ifdef SK_ENABLE_PRECOMPILE
+
+#include <functional>
+#include <memory>
+#include <vector>
+#include "include/core/SkBlendMode.h"
+#include "include/core/SkSpan.h"
+#include "include/core/SkTileMode.h"
+#include "include/private/SkTArray.h"
+#include "include/private/SkTHash.h"
+
+class SkArenaAllocWithReset;
+class SkKeyContext;
+class SkPaintParamsKeyBuilder;
+class SkShaderCodeDictionary;
+class SkUniquePaintParamsID;
+
+namespace skgpu::graphite {
+
+class CombinationBuilder;
+class CombinationBuilderTestAccess;
+class Context;
+class Option;
+
+enum class ShaderType : uint32_t {
+    kSolidColor,
+
+    kLinearGradient,
+    kRadialGradient,
+    kSweepGradient,
+    kConicalGradient,
+
+    kLocalMatrix,
+    kImage,
+    kPorterDuffBlendShader,
+    kBlendShader,
+
+    kLast          = kBlendShader
+};
+
+static constexpr int kShaderTypeCount = static_cast<int>(ShaderType::kLast) + 1;
+
+struct TileModePair {
+    SkTileMode fX;
+    SkTileMode fY;
+
+    bool operator==(const TileModePair& other) const { return fX == other.fX && fY == other.fY; }
+    bool operator!=(const TileModePair& other) const { return !(*this == other); }
+};
+
+// TODO: add ShaderID and ColorFilterID too
+class BlenderID {
+public:
+    BlenderID() : fID(0) {}  // 0 is an invalid blender ID
+    BlenderID(const BlenderID& src) : fID(src.fID) {}
+
+    bool isValid() const { return fID > 0; }
+
+    bool operator==(const BlenderID& other) const { return fID == other.fID; }
+
+    BlenderID& operator=(const BlenderID& src) {
+        fID = src.fID;
+        return *this;
+    }
+
+private:
+    friend class ::SkShaderCodeDictionary;   // for ctor and asUInt access
+    friend class CombinationBuilder;         // for asUInt access
+
+    BlenderID(uint32_t id) : fID(id) {}
+
+    uint32_t asUInt() const { return fID; }
+
+    uint32_t fID;
+};
+
+// When combination options are added to the combination builder an CombinationOption
+// object is frequently returned. This allows options to be added, recursively, to the
+// previously added options.
+// Note: CombinationOptions are stable memory-wise so, once returned, they are valid
+// until CombinationBuilder::reset is called.
+class CombinationOption {
+public:
+    CombinationOption addChildOption(int childIndex, ShaderType);
+
+    CombinationOption addChildOption(int childIndex, ShaderType,
+                                     int minNumStops, int maxNumStops);
+
+    CombinationOption addChildOption(int childIndex, ShaderType,
+                                     SkSpan<TileModePair> tileModes);
+
+    bool isValid() const { return fDataInArena; }
+
+private:
+    friend class CombinationBuilder; // for ctor
+    friend class CombinationBuilderTestAccess;
+
+    CombinationOption(CombinationBuilder* builder, Option* dataInArena)
+            : fBuilder(builder)
+            , fDataInArena(dataInArena) {}
+
+    ShaderType type() const;
+    int numChildSlots() const;
+    SkDEBUGCODE(int epoch() const;)
+
+    CombinationBuilder* fBuilder;
+    Option* fDataInArena;
+};
+
+class CombinationBuilder {
+public:
+    enum class BlendModeGroup {
+        kPorterDuff,         // [ kClear .. kScreen ]
+        kAdvanced,           // [ kOverlay .. kMultiply ]
+        kColorAware,         // [ kHue .. kLuminosity ]
+        kAll
+    };
+
+    CombinationBuilder(SkShaderCodeDictionary*);
+    ~CombinationBuilder();
+
+    // Blend Modes
+    void addOption(SkBlendMode);
+    void addOption(SkBlendMode rangeStart, SkBlendMode rangeEnd); // inclusive
+    void addOption(BlendModeGroup);
+
+    // TODO: have this variant return an CombinationOption object
+    void addOption(BlenderID);
+
+    // Shaders
+    CombinationOption addOption(ShaderType);
+    CombinationOption addOption(ShaderType, int minNumStops, int maxNumStops);  // inclusive
+    CombinationOption addOption(ShaderType, SkSpan<TileModePair> tileModes);
+
+    void reset();
+
+private:
+    friend class Context;                        // for access to 'buildCombinations'
+    friend class CombinationOption;              // for 'addOptionInternal' and 'arena'
+    friend class CombinationBuilderTestAccess;   // for 'num*Combinations' and 'epoch'
+
+    int numShaderCombinations() const;
+    int numBlendModeCombinations() const;
+    int numCombinations() {
+        return this->numShaderCombinations() * this->numBlendModeCombinations();
+    }
+
+    // 'desiredCombination' must be less than numCombinations
+    void createKey(const SkKeyContext&, int desiredCombination, SkPaintParamsKeyBuilder*);
+
+#ifdef SK_DEBUG
+    void dump() const;
+    int epoch() const { return fEpoch; }
+#endif
+
+    SkArenaAllocWithReset* arena() { return fArena.get(); }
+
+    template<typename T, typename... Args>
+    Option* allocInArena(Args&&... args);
+
+    Option* addOptionInternal(ShaderType);
+    Option* addOptionInternal(ShaderType, int minNumStops, int maxNumStops);
+    Option* addOptionInternal(ShaderType, SkSpan<TileModePair> tileModes);
+
+    void buildCombinations(SkShaderCodeDictionary*,
+                           const std::function<void(SkUniquePaintParamsID)>&);
+
+    SkShaderCodeDictionary* fDictionary;
+    std::unique_ptr<SkArenaAllocWithReset> fArena;
+    SkTArray<Option*> fShaderOptions;
+
+    uint32_t fBlendModes;
+    // TODO: store the SkBlender-based blenders in the arena
+    SkTHashSet<BlenderID> fBlenders;
+
+    SkDEBUGCODE(int fEpoch = 0;)
+};
+
+} // namespace skgpu::graphite
+
+#endif // SK_ENABLE_PRECOMPILE
+
+#endif // skgpu_graphite_CombinationBuilder_DEFINED

package/cpp/skia/include/gpu/graphite/Context.h

@@ -8,53 +8,38 @@
 #ifndef skgpu_graphite_Context_DEFINED
 #define skgpu_graphite_Context_DEFINED
 
-#include <vector>
-#include "include/core/SkBlendMode.h"
 #include "include/core/SkRefCnt.h"
 #include "include/core/SkShader.h"
-#include "include/core/SkTileMode.h"
-#include "include/private/SkNoncopyable.h"
-
+#include "include/gpu/graphite/ContextOptions.h"
 #include "include/gpu/graphite/GraphiteTypes.h"
+#include "include/gpu/graphite/Recorder.h"
+#include "include/private/SingleOwner.h"
+
+#include <memory>
+
+class SkRuntimeEffect;
+
+namespace skgpu { struct VulkanBackendContext; }
 
 namespace skgpu::graphite {
 
 class BackendTexture;
-class CommandBuffer;
+class Context;
 class ContextPriv;
+struct DawnBackendContext;
 class GlobalCache;
-class Gpu;
 struct MtlBackendContext;
-class Recorder;
+class QueueManager;
 class Recording;
-class TextureInfo;
-
-struct ShaderCombo {
-    enum class ShaderType {
-        kNone, // does not modify color buffer, e.g. depth and/or stencil only
-        kSolidColor,
-        kLinearGradient,
-        kRadialGradient,
-        kSweepGradient,
-        kConicalGradient
-    };
-
-    ShaderCombo() {}
-    ShaderCombo(std::vector<ShaderType> types,
-                std::vector<SkTileMode> tileModes)
-            : fTypes(std::move(types))
-            , fTileModes(std::move(tileModes)) {
-    }
-    std::vector<ShaderType> fTypes;
-    std::vector<SkTileMode> fTileModes;
-};
+class ResourceProvider;
+class SharedContext;
 
-struct PaintCombo {
-    std::vector<ShaderCombo> fShaders;
-    std::vector<SkBlendMode> fBlendModes;
-};
+#ifdef SK_ENABLE_PRECOMPILE
+class BlenderID;
+class CombinationBuilder;
+#endif
 
-class Context final {
+class SK_API Context final {
 public:
     Context(const Context&) = delete;
     Context(Context&&) = delete;
@@ -63,13 +48,20 @@ public:
 
     ~Context();
 
+#ifdef SK_DAWN
+    static std::unique_ptr<Context> MakeDawn(const DawnBackendContext&, const ContextOptions&);
+#endif
 #ifdef SK_METAL
-    static std::unique_ptr<Context> MakeMetal(const skgpu::graphite::MtlBackendContext&);
+    static std::unique_ptr<Context> MakeMetal(const MtlBackendContext&, const ContextOptions&);
 #endif
 
-    BackendApi backend() const { return fBackend; }
+#ifdef SK_VULKAN
+    static std::unique_ptr<Context> MakeVulkan(const VulkanBackendContext&, const ContextOptions&);
+#endif
+
+    BackendApi backend() const;
 
-    std::unique_ptr<Recorder> makeRecorder();
+    std::unique_ptr<Recorder> makeRecorder(const RecorderOptions& = {});
 
     void insertRecording(const InsertRecordingInfo&);
     void submit(SyncToCpu = SyncToCpu::kNo);
@@ -79,23 +71,19 @@ public:
      */
     void checkAsyncWorkCompletion();
 
-    void preCompile(const PaintCombo&);
+#ifdef SK_ENABLE_PRECOMPILE
+    // TODO: add "ShaderID addUserDefinedShader(sk_sp<SkRuntimeEffect>)" here
+    // TODO: add "ColorFilterID addUserDefinedColorFilter(sk_sp<SkRuntimeEffect>)" here
+    BlenderID addUserDefinedBlender(sk_sp<SkRuntimeEffect>);
 
-    /**
-     * Creates a new backend gpu texture matching the dimensinos and TextureInfo. If an invalid
-     * TextureInfo or a TextureInfo Skia can't support is passed in, this will return an invalid
-     * BackendTexture. Thus the client should check isValid on the returned BackendTexture to know
-     * if it succeeded or not.
-     *
-     * If this does return a valid BackendTexture, the caller is required to use
-     * Context::deleteBackendTexture to delete that texture.
-     */
-    BackendTexture createBackendTexture(SkISize dimensions, const TextureInfo&);
+    void precompile(CombinationBuilder*);
+#endif
 
     /**
      * Called to delete the passed in BackendTexture. This should only be called if the
-     * BackendTexture was created by calling Context::createBackendTexture. If the BackendTexture is
-     * not valid or does not match the BackendApi of the Context then nothing happens.
+     * BackendTexture was created by calling Recorder::createBackendTexture on a Recorder created
+     * from this Context. If the BackendTexture is not valid or does not match the BackendApi of the
+     * Context then nothing happens.
      *
      * Otherwise this will delete/release the backend object that is wrapped in the BackendTexture.
      * The BackendTexture will be reset to an invalid state and should not be used again.
@@ -107,16 +95,20 @@ public:
     const ContextPriv priv() const;  // NOLINT(readability-const-return-type)
 
 protected:
-    Context(sk_sp<Gpu>, BackendApi);
+    Context(sk_sp<SharedContext>, std::unique_ptr<QueueManager>);
 
 private:
     friend class ContextPriv;
 
-    sk_sp<CommandBuffer> fCurrentCommandBuffer;
+    SingleOwner* singleOwner() const { return &fSingleOwner; }
+
+    sk_sp<SharedContext> fSharedContext;
+    std::unique_ptr<ResourceProvider> fResourceProvider;
+    std::unique_ptr<QueueManager> fQueueManager;
 
-    sk_sp<Gpu> fGpu;
-    sk_sp<GlobalCache> fGlobalCache;
-    BackendApi fBackend;
+    // In debug builds we guard against improper thread handling. This guard is passed to the
+    // ResourceCache for the Context.
+    mutable SingleOwner fSingleOwner;
 };
 
 } // namespace skgpu::graphite

package/cpp/skia/include/gpu/graphite/ContextOptions.h

@@ -0,0 +1,85 @@
+/*
+ * Copyright 2022 Google LLC
+ *
+ * Use of this source code is governed by a BSD-style license that can be
+ * found in the LICENSE file.
+ */
+
+#ifndef skgpu_graphite_ContextOptions_DEFINED
+#define skgpu_graphite_ContextOptions_DEFINED
+
+namespace skgpu { class ShaderErrorHandler; }
+
+namespace skgpu::graphite {
+
+struct SK_API ContextOptions {
+    ContextOptions() {}
+
+    /**
+     * If present, use this object to report shader compilation failures. If not, report failures
+     * via SkDebugf and assert.
+     */
+    skgpu::ShaderErrorHandler* fShaderErrorHandler = nullptr;
+
+    /**
+     * Will the client make sure to only ever be executing one thread that uses the Context and all
+     * derived classes (e.g. Recorders, Recordings, etc.) at a time. If so we can possibly make some
+     * objects (e.g. VulkanMemoryAllocator) not thread safe to improve single thread performance.
+     */
+    bool fClientWillExternallySynchronizeAllThreads = false;
+
+    /**
+     * The maximum size of cache textures used for Skia's Glyph cache.
+     */
+    size_t fGlyphCacheTextureMaximumBytes = 2048 * 1024 * 4;
+
+    /**
+     * Below this threshold size in device space distance field fonts won't be used. Distance field
+     * fonts don't support hinting which is more important at smaller sizes.
+     */
+    float fMinDistanceFieldFontSize = 18;
+
+    /**
+     * Above this threshold size in device space glyphs are drawn as individual paths.
+     */
+#if defined(SK_BUILD_FOR_ANDROID)
+    float fGlyphsAsPathsFontSize = 384;
+#elif defined(SK_BUILD_FOR_MAC)
+    float fGlyphsAsPathsFontSize = 256;
+#else
+    float fGlyphsAsPathsFontSize = 324;
+#endif
+
+    /**
+     * Can the glyph atlas use multiple textures. If allowed, the each texture's size is bound by
+     * fGlypheCacheTextureMaximumBytes.
+     */
+    bool fAllowMultipleGlyphCacheTextures = true;
+
+    /**
+     * If true, then add 1 pixel padding to all glyph masks in the atlas to support bi-lerp
+     * rendering of all glyphs. This must be set to true to use Slugs.
+     */
+    #if defined(SK_EXPERIMENTAL_SIMULATE_DRAWGLYPHRUNLIST_WITH_SLUG) || \
+        defined(SK_EXPERIMENTAL_SIMULATE_DRAWGLYPHRUNLIST_WITH_SLUG_SERIALIZE) || \
+        defined(SK_EXPERIMENTAL_SIMULATE_DRAWGLYPHRUNLIST_WITH_SLUG_STRIKE_SERIALIZE)
+    bool fSupportBilerpFromGlyphAtlas = true;
+    #else
+    bool fSupportBilerpFromGlyphAtlas = false;
+    #endif
+
+#if GRAPHITE_TEST_UTILS
+    /**
+     * Private options that are only meant for testing within Skia's tools.
+     */
+
+    /**
+     * Maximum width and height of internal texture atlases.
+     */
+    int  fMaxTextureAtlasSize = 2048;
+#endif
+};
+
+}  // namespace skgpu::graphite
+
+#endif  // skgpu_graphite_ContextOptions

package/cpp/skia/include/gpu/graphite/GraphiteTypes.h

@@ -42,26 +42,10 @@ enum class SyncToCpu : bool {
     kNo = false
 };
 
-/**
- * Possible 3D APIs that may be used by Graphite.
- */
-enum class BackendApi : unsigned {
-    kMetal,
-    kMock,
-};
-
 /**
  * Is the texture mipmapped or not
  */
-enum class Mipmapped: bool {
-    kNo = false,
-    kYes = true,
-};
-
-/**
- * Is the data protected on the GPU or not.
- */
-enum class Protected : bool {
+enum class Mipmapped : bool {
     kNo = false,
     kYes = true,
 };

package/cpp/skia/include/gpu/graphite/ImageProvider.h

@@ -0,0 +1,61 @@
+/*
+ * Copyright 2022 Google LLC
+ *
+ * Use of this source code is governed by a BSD-style license that can be
+ * found in the LICENSE file.
+ */
+
+#ifndef skgpu_graphite_ImageProvider_DEFINED
+#define skgpu_graphite_ImageProvider_DEFINED
+
+#include "include/core/SkImage.h"
+#include "include/core/SkRefCnt.h"
+
+namespace skgpu::graphite {
+
+enum class Mipmapped : bool;
+class Recorder;
+
+/*
+ * This class provides a centralized location for clients to perform any caching of images
+ * they desire. Whenever Graphite encounters an SkImage which is not Graphite-backed
+ * it will call ImageProvider::findOrCreate. The client's derived version of this class should
+ * return a Graphite-backed version of the provided SkImage that meets the specified
+ * requirements.
+ *
+ * Skia requires that 'findOrCreate' return a Graphite-backed image that preserves the dimensions,
+ * number of channels and alpha type of the original image. The bit depth of the
+ * individual channels can change (e.g., 4444 -> 8888 is allowed).
+ * Wrt mipmapping, the returned image can have different mipmap settings than requested. If
+ * mipmapping was requested but not returned, the sampling level will be reduced to linear.
+ * If the requirements are not met by the returned image (modulo the flexibility wrt mipmapping)
+ * Graphite will drop the draw.
+ *
+ * Note: by default, Graphite will not perform any caching of images
+ *
+ * Threading concerns:
+ *   If the same ImageProvider is given to multiple Recorders it is up to the
+ *   client to handle any required thread synchronization. This is not limited to just
+ *   restricting access to whatever map a derived class may have but extends to ensuring
+ *   that an image created on one Recorder has had its creation work submitted before it
+ *   is used by any work submitted by another Recording. Please note, this requirement
+ *   (re the submission of creation work and image usage on different threads) is common to all
+ *   graphite SkImages and isn't unique to SkImages returned by the ImageProvider.
+ *
+ * TODO(b/240996632): add documentation re shutdown order.
+ * TODO(b/240997067): add unit tests
+ */
+class SK_API ImageProvider : public SkRefCnt {
+public:
+    // If the client's derived class already has a Graphite-backed image that has the same
+    // contents as 'image' and meets the requirements, then it can be returned.
+    // makeTextureImage can always be called to create an acceptable Graphite-backed image
+    // which could then be cached.
+    virtual sk_sp<SkImage> findOrCreate(Recorder* recorder,
+                                        const SkImage* image,
+                                        SkImage::RequiredImageProperties) = 0;
+};
+
+} // namespace skgpu::graphite
+
+#endif // skgpu_graphite_ImageProvider_DEFINED