@shopify/react-native-skia 0.1.197 → 0.1.199

package/cpp/skia/include/core/SkSurface.h

@@ -17,523 +17,165 @@
 #include "include/core/SkSurfaceProps.h"
 #include "include/core/SkTypes.h"
 
-#if defined(SK_GANESH)
-#include "include/gpu/GrTypes.h"
-#else
-enum GrSurfaceOrigin: int;
-#endif
-
-#if defined(SK_GRAPHITE)
-#include "include/gpu/GpuTypes.h"
-namespace skgpu::graphite {
-class BackendTexture;
-}
-#endif
-
-#if defined(SK_BUILD_FOR_ANDROID) && __ANDROID_API__ >= 26
-#include <android/hardware_buffer.h>
-class GrDirectContext;
-#endif
-
-#if defined(SK_GANESH) && defined(SK_METAL)
-#include "include/gpu/mtl/GrMtlTypes.h"
-#endif
-
 #include <cstddef>
 #include <cstdint>
 #include <memory>
 
-class GrBackendRenderTarget;
 class GrBackendSemaphore;
 class GrBackendTexture;
 class GrRecordingContext;
+class GrSurfaceCharacterization;
+enum GrSurfaceOrigin : int;
 class SkBitmap;
 class SkCanvas;
 class SkCapabilities;
 class SkColorSpace;
-class SkDeferredDisplayList;
 class SkPaint;
-class SkSurfaceCharacterization;
-enum SkColorType : int;
+class SkSurface;
 struct SkIRect;
 struct SkISize;
 
-namespace skgpu {
-class MutableTextureState;
-enum class Budgeted : bool;
-}
-
 namespace skgpu::graphite {
 class Recorder;
 }
 
-/** \class SkSurface
-    SkSurface is responsible for managing the pixels that a canvas draws into. The pixels can be
-    allocated either in CPU memory (a raster surface) or on the GPU (a GrRenderTarget surface).
-    SkSurface takes care of allocating a SkCanvas that will draw into the surface. Call
-    surface->getCanvas() to use that canvas (but don't delete it, it is owned by the surface).
-    SkSurface always has non-zero dimensions. If there is a request for a new surface, and either
-    of the requested dimensions are zero, then nullptr will be returned.
-*/
-class SK_API SkSurface : public SkRefCnt {
-public:
-
-    /** Allocates raster SkSurface. SkCanvas returned by SkSurface draws directly into pixels.
-
-        SkSurface is returned if all parameters are valid.
-        Valid parameters include:
-        info dimensions are greater than zero;
-        info contains SkColorType and SkAlphaType supported by raster surface;
-        pixels is not nullptr;
-        rowBytes is large enough to contain info width pixels of SkColorType.
-
-        Pixel buffer size should be info height times computed rowBytes.
-        Pixels are not initialized.
-        To access pixels after drawing, peekPixels() or readPixels().
-
-        @param imageInfo     width, height, SkColorType, SkAlphaType, SkColorSpace,
-                             of raster surface; width and height must be greater than zero
-        @param pixels        pointer to destination pixels buffer
-        @param rowBytes      interval from one SkSurface row to the next
-        @param surfaceProps  LCD striping orientation and setting for device independent fonts;
-                             may be nullptr
-        @return              SkSurface if all parameters are valid; otherwise, nullptr
-    */
-    static sk_sp<SkSurface> MakeRasterDirect(const SkImageInfo& imageInfo, void* pixels,
-                                             size_t rowBytes,
-                                             const SkSurfaceProps* surfaceProps = nullptr);
-
-    static sk_sp<SkSurface> MakeRasterDirect(const SkPixmap& pm,
-                                             const SkSurfaceProps* props = nullptr) {
-        return MakeRasterDirect(pm.info(), pm.writable_addr(), pm.rowBytes(), props);
-    }
-
-    /** Allocates raster SkSurface. SkCanvas returned by SkSurface draws directly into pixels.
-        releaseProc is called with pixels and context when SkSurface is deleted.
-
-        SkSurface is returned if all parameters are valid.
-        Valid parameters include:
-        info dimensions are greater than zero;
-        info contains SkColorType and SkAlphaType supported by raster surface;
-        pixels is not nullptr;
-        rowBytes is large enough to contain info width pixels of SkColorType.
-
-        Pixel buffer size should be info height times computed rowBytes.
-        Pixels are not initialized.
-        To access pixels after drawing, call flush() or peekPixels().
-
-        @param imageInfo     width, height, SkColorType, SkAlphaType, SkColorSpace,
-                             of raster surface; width and height must be greater than zero
-        @param pixels        pointer to destination pixels buffer
-        @param rowBytes      interval from one SkSurface row to the next
-        @param releaseProc   called when SkSurface is deleted; may be nullptr
-        @param context       passed to releaseProc; may be nullptr
-        @param surfaceProps  LCD striping orientation and setting for device independent fonts;
-                             may be nullptr
-        @return              SkSurface if all parameters are valid; otherwise, nullptr
-    */
-    static sk_sp<SkSurface> MakeRasterDirectReleaseProc(const SkImageInfo& imageInfo, void* pixels,
-                                    size_t rowBytes,
-                                    void (*releaseProc)(void* pixels, void* context),
-                                    void* context, const SkSurfaceProps* surfaceProps = nullptr);
-
-    /** Allocates raster SkSurface. SkCanvas returned by SkSurface draws directly into pixels.
-        Allocates and zeroes pixel memory. Pixel memory size is imageInfo.height() times
-        rowBytes, or times imageInfo.minRowBytes() if rowBytes is zero.
-        Pixel memory is deleted when SkSurface is deleted.
-
-        SkSurface is returned if all parameters are valid.
-        Valid parameters include:
-        info dimensions are greater than zero;
-        info contains SkColorType and SkAlphaType supported by raster surface;
-        rowBytes is large enough to contain info width pixels of SkColorType, or is zero.
-
-        If rowBytes is zero, a suitable value will be chosen internally.
-
-        @param imageInfo     width, height, SkColorType, SkAlphaType, SkColorSpace,
-                             of raster surface; width and height must be greater than zero
-        @param rowBytes      interval from one SkSurface row to the next; may be zero
-        @param surfaceProps  LCD striping orientation and setting for device independent fonts;
-                             may be nullptr
-        @return              SkSurface if all parameters are valid; otherwise, nullptr
-    */
-    static sk_sp<SkSurface> MakeRaster(const SkImageInfo& imageInfo, size_t rowBytes,
-                                       const SkSurfaceProps* surfaceProps);
-
-    /** Allocates raster SkSurface. SkCanvas returned by SkSurface draws directly into pixels.
-        Allocates and zeroes pixel memory. Pixel memory size is imageInfo.height() times
-        imageInfo.minRowBytes().
-        Pixel memory is deleted when SkSurface is deleted.
-
-        SkSurface is returned if all parameters are valid.
-        Valid parameters include:
-        info dimensions are greater than zero;
-        info contains SkColorType and SkAlphaType supported by raster surface.
-
-        @param imageInfo  width, height, SkColorType, SkAlphaType, SkColorSpace,
-                          of raster surface; width and height must be greater than zero
-        @param props      LCD striping orientation and setting for device independent fonts;
-                          may be nullptr
-        @return           SkSurface if all parameters are valid; otherwise, nullptr
-    */
-    static sk_sp<SkSurface> MakeRaster(const SkImageInfo& imageInfo,
-                                       const SkSurfaceProps* props = nullptr) {
-        return MakeRaster(imageInfo, 0, props);
-    }
-
-    /** Allocates raster SkSurface. SkCanvas returned by SkSurface draws directly into pixels.
-        Allocates and zeroes pixel memory. Pixel memory size is height times width times
-        four. Pixel memory is deleted when SkSurface is deleted.
-
-        Internally, sets SkImageInfo to width, height, native color type, and
-        kPremul_SkAlphaType.
-
-        SkSurface is returned if width and height are greater than zero.
-
-        Use to create SkSurface that matches SkPMColor, the native pixel arrangement on
-        the platform. SkSurface drawn to output device skips converting its pixel format.
-
-        @param width         pixel column count; must be greater than zero
-        @param height        pixel row count; must be greater than zero
-        @param surfaceProps  LCD striping orientation and setting for device independent
-                             fonts; may be nullptr
-        @return              SkSurface if all parameters are valid; otherwise, nullptr
-    */
-    static sk_sp<SkSurface> MakeRasterN32Premul(int width, int height,
-                                                const SkSurfaceProps* surfaceProps = nullptr);
-
-    /** Caller data passed to RenderTarget/TextureReleaseProc; may be nullptr. */
-    typedef void* ReleaseContext;
+#if !defined(SK_DISABLE_LEGACY_SKSURFACE_FLUSH)
+enum class GrSemaphoresSubmitted : bool;
+struct GrFlushInfo;
+namespace skgpu { class MutableTextureState; }
+#endif
 
-    /** User function called when supplied render target may be deleted. */
-    typedef void (*RenderTargetReleaseProc)(ReleaseContext releaseContext);
+namespace SkSurfaces {
 
-    /** User function called when supplied texture may be deleted. */
-    typedef void (*TextureReleaseProc)(ReleaseContext releaseContext);
+enum class BackendSurfaceAccess {
+    kNoAccess,  //!< back-end surface will not be used by client
+    kPresent,   //!< back-end surface will be used for presenting to screen
+};
 
-    /** Wraps a GPU-backed texture into SkSurface. Caller must ensure the texture is
-        valid for the lifetime of returned SkSurface. If sampleCnt greater than zero,
-        creates an intermediate MSAA SkSurface which is used for drawing backendTexture.
+/** Returns SkSurface without backing pixels. Drawing to SkCanvas returned from SkSurface
+    has no effect. Calling makeImageSnapshot() on returned SkSurface returns nullptr.
 
-        SkSurface is returned if all parameters are valid. backendTexture is valid if
-        its pixel configuration agrees with colorSpace and context; for instance, if
-        backendTexture has an sRGB configuration, then context must support sRGB,
-        and colorSpace must be present. Further, backendTexture width and height must
-        not exceed context capabilities, and the context must be able to support
-        back-end textures.
+    @param width   one or greater
+    @param height  one or greater
+    @return        SkSurface if width and height are positive; otherwise, nullptr
 
-        Upon success textureReleaseProc is called when it is safe to delete the texture in the
-        backend API (accounting only for use of the texture by this surface). If SkSurface creation
-        fails textureReleaseProc is called before this function returns.
+    example: https://fiddle.skia.org/c/@Surface_MakeNull
+*/
+SK_API sk_sp<SkSurface> Null(int width, int height);
 
-        If defined(SK_GANESH) is defined as zero, has no effect and returns nullptr.
-
-        @param context             GPU context
-        @param backendTexture      texture residing on GPU
-        @param sampleCnt           samples per pixel, or 0 to disable full scene anti-aliasing
-        @param colorSpace          range of colors; may be nullptr
-        @param surfaceProps        LCD striping orientation and setting for device independent
-                                   fonts; may be nullptr
-        @param textureReleaseProc  function called when texture can be released
-        @param releaseContext      state passed to textureReleaseProc
-        @return                    SkSurface if all parameters are valid; otherwise, nullptr
-    */
-    static sk_sp<SkSurface> MakeFromBackendTexture(GrRecordingContext* context,
-                                                   const GrBackendTexture& backendTexture,
-                                                   GrSurfaceOrigin origin, int sampleCnt,
-                                                   SkColorType colorType,
-                                                   sk_sp<SkColorSpace> colorSpace,
-                                                   const SkSurfaceProps* surfaceProps,
-                                                   TextureReleaseProc textureReleaseProc = nullptr,
-                                                   ReleaseContext releaseContext = nullptr);
-
-    /** Wraps a GPU-backed buffer into SkSurface. Caller must ensure backendRenderTarget
-        is valid for the lifetime of returned SkSurface.
-
-        SkSurface is returned if all parameters are valid. backendRenderTarget is valid if
-        its pixel configuration agrees with colorSpace and context; for instance, if
-        backendRenderTarget has an sRGB configuration, then context must support sRGB,
-        and colorSpace must be present. Further, backendRenderTarget width and height must
-        not exceed context capabilities, and the context must be able to support
-        back-end render targets.
-
-        Upon success releaseProc is called when it is safe to delete the render target in the
-        backend API (accounting only for use of the render target by this surface). If SkSurface
-        creation fails releaseProc is called before this function returns.
-
-        If defined(SK_GANESH) is defined as zero, has no effect and returns nullptr.
-
-        @param context                  GPU context
-        @param backendRenderTarget      GPU intermediate memory buffer
-        @param colorSpace               range of colors
-        @param surfaceProps             LCD striping orientation and setting for device independent
-                                        fonts; may be nullptr
-        @param releaseProc              function called when backendRenderTarget can be released
-        @param releaseContext           state passed to releaseProc
-        @return                         SkSurface if all parameters are valid; otherwise, nullptr
-    */
-    static sk_sp<SkSurface> MakeFromBackendRenderTarget(GrRecordingContext* context,
-                                                const GrBackendRenderTarget& backendRenderTarget,
-                                                GrSurfaceOrigin origin,
-                                                SkColorType colorType,
-                                                sk_sp<SkColorSpace> colorSpace,
-                                                const SkSurfaceProps* surfaceProps,
-                                                RenderTargetReleaseProc releaseProc = nullptr,
-                                                ReleaseContext releaseContext = nullptr);
-
-    /** Returns SkSurface on GPU indicated by context. Allocates memory for
-        pixels, based on the width, height, and SkColorType in SkImageInfo.  budgeted
-        selects whether allocation for pixels is tracked by context. imageInfo
-        describes the pixel format in SkColorType, and transparency in
-        SkAlphaType, and color matching in SkColorSpace.
-
-        sampleCount requests the number of samples per pixel.
-        Pass zero to disable multi-sample anti-aliasing.  The request is rounded
-        up to the next supported count, or rounded down if it is larger than the
-        maximum supported count.
-
-        surfaceOrigin pins either the top-left or the bottom-left corner to the origin.
-
-        shouldCreateWithMips hints that SkImage returned by makeImageSnapshot() is mip map.
-
-        If defined(SK_GANESH) is defined as zero, has no effect and returns nullptr.
-
-        @param context               GPU context
-        @param imageInfo             width, height, SkColorType, SkAlphaType, SkColorSpace;
-                                     width, or height, or both, may be zero
-        @param sampleCount           samples per pixel, or 0 to disable full scene anti-aliasing
-        @param surfaceProps          LCD striping orientation and setting for device independent
-                                     fonts; may be nullptr
-        @param shouldCreateWithMips  hint that SkSurface will host mip map images
-        @return                      SkSurface if all parameters are valid; otherwise, nullptr
-    */
-    static sk_sp<SkSurface> MakeRenderTarget(GrRecordingContext* context,
-                                             skgpu::Budgeted budgeted,
-                                             const SkImageInfo& imageInfo,
-                                             int sampleCount,
-                                             GrSurfaceOrigin surfaceOrigin,
-                                             const SkSurfaceProps* surfaceProps,
-                                             bool shouldCreateWithMips = false);
-
-    /** Returns SkSurface on GPU indicated by context. Allocates memory for
-        pixels, based on the width, height, and SkColorType in SkImageInfo.  budgeted
-        selects whether allocation for pixels is tracked by context. imageInfo
-        describes the pixel format in SkColorType, and transparency in
-        SkAlphaType, and color matching in SkColorSpace.
-
-        sampleCount requests the number of samples per pixel.
-        Pass zero to disable multi-sample anti-aliasing.  The request is rounded
-        up to the next supported count, or rounded down if it is larger than the
-        maximum supported count.
-
-        SkSurface bottom-left corner is pinned to the origin.
-
-        @param context      GPU context
-        @param imageInfo    width, height, SkColorType, SkAlphaType, SkColorSpace,
-                            of raster surface; width, or height, or both, may be zero
-        @param sampleCount  samples per pixel, or 0 to disable multi-sample anti-aliasing
-        @param surfaceProps LCD striping orientation and setting for device independent
-                            fonts; may be nullptr
-        @return             SkSurface if all parameters are valid; otherwise, nullptr
-    */
-    static sk_sp<SkSurface> MakeRenderTarget(GrRecordingContext* context,
-                                             skgpu::Budgeted budgeted,
-                                             const SkImageInfo& imageInfo,
-                                             int sampleCount,
-                                             const SkSurfaceProps* surfaceProps) {
-#if defined(SK_GANESH)
-        return MakeRenderTarget(context, budgeted, imageInfo, sampleCount,
-                                kBottomLeft_GrSurfaceOrigin, surfaceProps);
-#else
-        // TODO(kjlubick, scroggo) Remove this once Android is updated.
-        return nullptr;
-#endif
-    }
+/** Allocates raster SkSurface. SkCanvas returned by SkSurface draws directly into those allocated
+    pixels, which are zeroed before use. Pixel memory size is imageInfo.height() times
+    imageInfo.minRowBytes() or rowBytes, if provided and non-zero.
 
-    /** Returns SkSurface on GPU indicated by context. Allocates memory for
-        pixels, based on the width, height, and SkColorType in SkImageInfo.  budgeted
-        selects whether allocation for pixels is tracked by context. imageInfo
-        describes the pixel format in SkColorType, and transparency in
-        SkAlphaType, and color matching in SkColorSpace.
+    Pixel memory is deleted when SkSurface is deleted.
 
-        SkSurface bottom-left corner is pinned to the origin.
+    Validity constraints include:
+      - info dimensions are greater than zero;
+      - info contains SkColorType and SkAlphaType supported by raster surface.
 
-        @param context    GPU context
-        @param imageInfo  width, height, SkColorType, SkAlphaType, SkColorSpace,
-                          of raster surface; width, or height, or both, may be zero
-        @return           SkSurface if all parameters are valid; otherwise, nullptr
-    */
-    static sk_sp<SkSurface> MakeRenderTarget(GrRecordingContext* context,
-                                             skgpu::Budgeted budgeted,
-                                             const SkImageInfo& imageInfo) {
-#if defined(SK_GANESH)
-        if (!imageInfo.width() || !imageInfo.height()) {
-            return nullptr;
-        }
-        return MakeRenderTarget(context, budgeted, imageInfo, 0, kBottomLeft_GrSurfaceOrigin,
-                                nullptr);
-#else
-        // TODO(kjlubick, scroggo) Remove this once Android is updated.
-        return nullptr;
-#endif
-    }
+    @param imageInfo  width, height, SkColorType, SkAlphaType, SkColorSpace,
+                      of raster surface; width and height must be greater than zero
+    @param rowBytes   interval from one SkSurface row to the next.
+    @param props      LCD striping orientation and setting for device independent fonts;
+                      may be nullptr
+    @return           SkSurface if parameters are valid and memory was allocated, else nullptr.
+*/
+SK_API sk_sp<SkSurface> Raster(const SkImageInfo& imageInfo,
+                               size_t rowBytes,
+                               const SkSurfaceProps* surfaceProps);
+inline sk_sp<SkSurface> Raster(const SkImageInfo& imageInfo,
+                               const SkSurfaceProps* props = nullptr) {
+    return Raster(imageInfo, 0, props);
+}
 
-    /** Returns SkSurface on GPU indicated by context that is compatible with the provided
-        characterization. budgeted selects whether allocation for pixels is tracked by context.
+/** Allocates raster SkSurface. SkCanvas returned by SkSurface draws directly into the
+    provided pixels.
+
+    SkSurface is returned if all parameters are valid.
+    Valid parameters include:
+    info dimensions are greater than zero;
+    info contains SkColorType and SkAlphaType supported by raster surface;
+    pixels is not nullptr;
+    rowBytes is large enough to contain info width pixels of SkColorType.
+
+    Pixel buffer size should be info height times computed rowBytes.
+    Pixels are not initialized.
+    To access pixels after drawing, peekPixels() or readPixels().
+
+    @param imageInfo     width, height, SkColorType, SkAlphaType, SkColorSpace,
+                         of raster surface; width and height must be greater than zero
+    @param pixels        pointer to destination pixels buffer
+    @param rowBytes      interval from one SkSurface row to the next
+    @param surfaceProps  LCD striping orientation and setting for device independent fonts;
+                         may be nullptr
+    @return              SkSurface if all parameters are valid; otherwise, nullptr
+*/
 
-        @param context           GPU context
-        @param characterization  description of the desired SkSurface
-        @return                  SkSurface if all parameters are valid; otherwise, nullptr
-    */
-    static sk_sp<SkSurface> MakeRenderTarget(GrRecordingContext* context,
-                                             const SkSurfaceCharacterization& characterization,
-                                             skgpu::Budgeted budgeted);
-
-#if defined(SK_BUILD_FOR_ANDROID) && __ANDROID_API__ >= 26
-    /** Private.
-        Creates SkSurface from Android hardware buffer.
-        Returned SkSurface takes a reference on the buffer. The ref on the buffer will be released
-        when the SkSurface is destroyed and there is no pending work on the GPU involving the
-        buffer.
-
-        Only available on Android, when __ANDROID_API__ is defined to be 26 or greater.
-
-        Currently this is only supported for buffers that can be textured as well as rendered to.
-        In other words that must have both AHARDWAREBUFFER_USAGE_GPU_COLOR_OUTPUT and
-        AHARDWAREBUFFER_USAGE_GPU_SAMPLED_IMAGE usage bits.
-
-        @param context         GPU context
-        @param hardwareBuffer  AHardwareBuffer Android hardware buffer
-        @param colorSpace      range of colors; may be nullptr
-        @param surfaceProps    LCD striping orientation and setting for device independent
-                               fonts; may be nullptr
-        @param fromWindow      Whether or not the AHardwareBuffer is part of an Android Window.
-                               Currently only used with Vulkan backend.
-        @return                created SkSurface, or nullptr
-    */
-    static sk_sp<SkSurface> MakeFromAHardwareBuffer(GrDirectContext* context,
-                                                    AHardwareBuffer* hardwareBuffer,
-                                                    GrSurfaceOrigin origin,
-                                                    sk_sp<SkColorSpace> colorSpace,
-                                                    const SkSurfaceProps* surfaceProps
-#ifdef SK_BUILD_FOR_ANDROID_FRAMEWORK
-                                                    , bool fromWindow = false
-#endif  // SK_BUILD_FOR_ANDROID_FRAMEWORK
-                                                    );
-#endif
+SK_API sk_sp<SkSurface> WrapPixels(const SkImageInfo& imageInfo,
+                                   void* pixels,
+                                   size_t rowBytes,
+                                   const SkSurfaceProps* surfaceProps = nullptr);
+inline sk_sp<SkSurface> WrapPixels(const SkPixmap& pm, const SkSurfaceProps* props = nullptr) {
+    return WrapPixels(pm.info(), pm.writable_addr(), pm.rowBytes(), props);
+}
 
-#if defined(SK_GRAPHITE)
-    /**
-     * In Graphite, while clients hold a ref on an SkSurface, the backing gpu object does _not_
-     * count against the budget. Once an SkSurface is freed, the backing gpu object may or may
-     * not become a scratch (i.e., reusable) resource but, if it does, it will be counted against
-     * the budget.
-     */
-    static sk_sp<SkSurface> MakeGraphite(
-            skgpu::graphite::Recorder*,
-            const SkImageInfo& imageInfo,
-            skgpu::Mipmapped = skgpu::Mipmapped::kNo,
-            const SkSurfaceProps* surfaceProps = nullptr);
+using PixelsReleaseProc = void(void* pixels, void* context);
+
+/** Allocates raster SkSurface. SkCanvas returned by SkSurface draws directly into the provided
+    pixels. releaseProc is called with pixels and context when SkSurface is deleted.
+
+    SkSurface is returned if all parameters are valid.
+    Valid parameters include:
+    info dimensions are greater than zero;
+    info contains SkColorType and SkAlphaType supported by raster surface;
+    pixels is not nullptr;
+    rowBytes is large enough to contain info width pixels of SkColorType.
+
+    Pixel buffer size should be info height times computed rowBytes.
+    Pixels are not initialized.
+    To access pixels after drawing, call flush() or peekPixels().
+
+    @param imageInfo     width, height, SkColorType, SkAlphaType, SkColorSpace,
+                         of raster surface; width and height must be greater than zero
+    @param pixels        pointer to destination pixels buffer
+    @param rowBytes      interval from one SkSurface row to the next
+    @param releaseProc   called when SkSurface is deleted; may be nullptr
+    @param context       passed to releaseProc; may be nullptr
+    @param surfaceProps  LCD striping orientation and setting for device independent fonts;
+                         may be nullptr
+    @return              SkSurface if all parameters are valid; otherwise, nullptr
+*/
+SK_API sk_sp<SkSurface> WrapPixels(const SkImageInfo& imageInfo,
+                                   void* pixels,
+                                   size_t rowBytes,
+                                   PixelsReleaseProc,
+                                   void* context,
+                                   const SkSurfaceProps* surfaceProps = nullptr);
+}  // namespace SkSurfaces
 
-    /**
-     * Wraps a GPU-backed texture in an SkSurface. Depending on the backend gpu API, the caller may
-     * be required to ensure the texture is valid for the lifetime of the returned SkSurface. The
-     * required lifetimes for the specific apis are:
-     *     Metal: Skia will call retain on the underlying MTLTexture so the caller can drop it once
-     *            this call returns.
-     *
-     * SkSurface is returned if all the parameters are valid. The backendTexture is valid if its
-     * format agrees with colorSpace and recorder; for instance, if backendTexture has an sRGB
-     * configuration, then the recorder must support sRGB, and colorSpace must be present. Further,
-     * backendTexture's width and height must not exceed the recorder's capabilities, and the
-     * recorder must be able to support the back-end texture.
-     */
-    static sk_sp<SkSurface> MakeGraphiteFromBackendTexture(skgpu::graphite::Recorder*,
-                                                           const skgpu::graphite::BackendTexture&,
-                                                           SkColorType colorType,
-                                                           sk_sp<SkColorSpace> colorSpace,
-                                                           const SkSurfaceProps* props);
-
-#endif // SK_GRAPHITE
-
-#if defined(SK_GANESH) && defined(SK_METAL)
-    /** Creates SkSurface from CAMetalLayer.
-        Returned SkSurface takes a reference on the CAMetalLayer. The ref on the layer will be
-        released when the SkSurface is destroyed.
-
-        Only available when Metal API is enabled.
-
-        Will grab the current drawable from the layer and use its texture as a backendRT to
-        create a renderable surface.
-
-        @param context         GPU context
-        @param layer           GrMTLHandle (expected to be a CAMetalLayer*)
-        @param sampleCnt       samples per pixel, or 0 to disable full scene anti-aliasing
-        @param colorSpace      range of colors; may be nullptr
-        @param surfaceProps    LCD striping orientation and setting for device independent
-                               fonts; may be nullptr
-        @param drawable        Pointer to drawable to be filled in when this surface is
-                               instantiated; may not be nullptr
-        @return                created SkSurface, or nullptr
-     */
-    static sk_sp<SkSurface> MakeFromCAMetalLayer(GrRecordingContext* context,
-                                                 GrMTLHandle layer,
-                                                 GrSurfaceOrigin origin,
-                                                 int sampleCnt,
-                                                 SkColorType colorType,
-                                                 sk_sp<SkColorSpace> colorSpace,
-                                                 const SkSurfaceProps* surfaceProps,
-                                                 GrMTLHandle* drawable)
-                                                 SK_API_AVAILABLE_CA_METAL_LAYER;
-
-    /** Creates SkSurface from MTKView.
-        Returned SkSurface takes a reference on the MTKView. The ref on the layer will be
-        released when the SkSurface is destroyed.
-
-        Only available when Metal API is enabled.
-
-        Will grab the current drawable from the layer and use its texture as a backendRT to
-        create a renderable surface.
-
-        @param context         GPU context
-        @param layer           GrMTLHandle (expected to be a MTKView*)
-        @param sampleCnt       samples per pixel, or 0 to disable full scene anti-aliasing
-        @param colorSpace      range of colors; may be nullptr
-        @param surfaceProps    LCD striping orientation and setting for device independent
-                               fonts; may be nullptr
-        @return                created SkSurface, or nullptr
-     */
-    static sk_sp<SkSurface> MakeFromMTKView(GrRecordingContext* context,
-                                            GrMTLHandle mtkView,
-                                            GrSurfaceOrigin origin,
-                                            int sampleCnt,
-                                            SkColorType colorType,
-                                            sk_sp<SkColorSpace> colorSpace,
-                                            const SkSurfaceProps* surfaceProps)
-                                            SK_API_AVAILABLE(macos(10.11), ios(9.0));
-#endif
+/** \class SkSurface
+    SkSurface is responsible for managing the pixels that a canvas draws into. The pixels can be
+    allocated either in CPU memory (a raster surface) or on the GPU (a GrRenderTarget surface).
+    SkSurface takes care of allocating a SkCanvas that will draw into the surface. Call
+    surface->getCanvas() to use that canvas (but don't delete it, it is owned by the surface).
+    SkSurface always has non-zero dimensions. If there is a request for a new surface, and either
+    of the requested dimensions are zero, then nullptr will be returned.
 
+    Clients should *not* subclass SkSurface as there is a lot of internal machinery that is
+    not publicly accessible.
+*/
+class SK_API SkSurface : public SkRefCnt {
+public:
     /** Is this surface compatible with the provided characterization?
 
         This method can be used to determine if an existing SkSurface is a viable destination
-        for an SkDeferredDisplayList.
+        for an GrDeferredDisplayList.
 
         @param characterization  The characterization for which a compatibility check is desired
         @return                  true if this surface is compatible with the characterization;
                                  false otherwise
     */
-    bool isCompatible(const SkSurfaceCharacterization& characterization) const;
-
-    /** Returns SkSurface without backing pixels. Drawing to SkCanvas returned from SkSurface
-        has no effect. Calling makeImageSnapshot() on returned SkSurface returns nullptr.
-
-        @param width   one or greater
-        @param height  one or greater
-        @return        SkSurface if width and height are positive; otherwise, nullptr
-
-        example: https://fiddle.skia.org/c/@Surface_MakeNull
-    */
-    static sk_sp<SkSurface> MakeNull(int width, int height);
+    bool isCompatible(const GrSurfaceCharacterization& characterization) const;
 
     /** Returns pixel count in each row; may be zero or greater.
 
@@ -582,56 +224,37 @@ public:
 
         @return the recording context, if available; nullptr otherwise
      */
-    GrRecordingContext* recordingContext();
+    GrRecordingContext* recordingContext() const;
 
     /** Returns the recorder being used by the SkSurface.
 
         @return the recorder, if available; nullptr otherwise
      */
-    skgpu::graphite::Recorder* recorder();
+    skgpu::graphite::Recorder* recorder() const;
 
-#if defined(SK_GANESH)
-    enum BackendHandleAccess {
-        kFlushRead_BackendHandleAccess,    //!< back-end object is readable
-        kFlushWrite_BackendHandleAccess,   //!< back-end object is writable
-        kDiscardWrite_BackendHandleAccess, //!< back-end object must be overwritten
-    };
-
-    /** Deprecated.
-    */
-    static const BackendHandleAccess kFlushRead_TextureHandleAccess =
-            kFlushRead_BackendHandleAccess;
+    enum class BackendHandleAccess {
+        kFlushRead,     //!< back-end object is readable
+        kFlushWrite,    //!< back-end object is writable
+        kDiscardWrite,  //!< back-end object must be overwritten
 
-    /** Deprecated.
-    */
-    static const BackendHandleAccess kFlushWrite_TextureHandleAccess =
-            kFlushWrite_BackendHandleAccess;
-
-    /** Deprecated.
-    */
-    static const BackendHandleAccess kDiscardWrite_TextureHandleAccess =
-            kDiscardWrite_BackendHandleAccess;
-
-    /** Retrieves the back-end texture. If SkSurface has no back-end texture, an invalid
-        object is returned. Call GrBackendTexture::isValid to determine if the result
-        is valid.
-
-        The returned GrBackendTexture should be discarded if the SkSurface is drawn to or deleted.
-
-        @return                     GPU texture reference; invalid on failure
-    */
-    GrBackendTexture getBackendTexture(BackendHandleAccess backendHandleAccess);
-
-    /** Retrieves the back-end render target. If SkSurface has no back-end render target, an invalid
-        object is returned. Call GrBackendRenderTarget::isValid to determine if the result
-        is valid.
+        // Legacy names, remove when clients are migrated
+        kFlushRead_BackendHandleAccess = kFlushRead,
+        kFlushWrite_BackendHandleAccess = kFlushWrite,
+        kDiscardWrite_BackendHandleAccess = kDiscardWrite,
+    };
 
-        The returned GrBackendRenderTarget should be discarded if the SkSurface is drawn to
-        or deleted.
+    // Legacy names, remove when clients are migrated
+    static constexpr BackendHandleAccess kFlushRead_BackendHandleAccess =
+            BackendHandleAccess::kFlushRead;
+    static constexpr BackendHandleAccess kFlushWrite_BackendHandleAccess =
+            BackendHandleAccess::kFlushWrite;
+    static constexpr BackendHandleAccess kDiscardWrite_BackendHandleAccess =
+            BackendHandleAccess::kDiscardWrite;
 
-        @return                     GPU render target reference; invalid on failure
-    */
-    GrBackendRenderTarget getBackendRenderTarget(BackendHandleAccess backendHandleAccess);
+    /** Caller data passed to TextureReleaseProc; may be nullptr. */
+    using ReleaseContext = void*;
+    /** User function called when supplied texture may be deleted. */
+    using TextureReleaseProc = void (*)(ReleaseContext);
 
     /** If the surface was made via MakeFromBackendTexture then it's backing texture may be
         substituted with a different texture. The contents of the previous backing texture are
@@ -645,15 +268,14 @@ public:
 
         @param backendTexture      the new backing texture for the surface
         @param mode                Retain or discard current Content
-        @param textureReleaseProc  function called when texture can be released
-        @param releaseContext      state passed to textureReleaseProc
+        @param TextureReleaseProc  function called when texture can be released
+        @param ReleaseContext      state passed to textureReleaseProc
      */
-    bool replaceBackendTexture(const GrBackendTexture& backendTexture,
-                               GrSurfaceOrigin origin,
-                               ContentChangeMode mode = kRetain_ContentChangeMode,
-                               TextureReleaseProc textureReleaseProc = nullptr,
-                               ReleaseContext releaseContext = nullptr);
-#endif
+    virtual bool replaceBackendTexture(const GrBackendTexture& backendTexture,
+                                       GrSurfaceOrigin origin,
+                                       ContentChangeMode mode = kRetain_ContentChangeMode,
+                                       TextureReleaseProc = nullptr,
+                                       ReleaseContext = nullptr) = 0;
 
     /** Returns SkCanvas that draws into SkSurface. Subsequent calls return the same SkCanvas.
         SkCanvas returned is managed and owned by SkSurface, and is deleted when SkSurface
@@ -714,34 +336,6 @@ public:
      */
     sk_sp<SkImage> makeImageSnapshot(const SkIRect& bounds);
 
-#if defined(SK_GRAPHITE)
-    /**
-     * The 'asImage' and 'makeImageCopy' API/entry points are currently only available for
-     * Graphite.
-     *
-     * In this API, SkSurface no longer supports copy-on-write behavior. Instead, when creating
-     * an image for a surface, the client must explicitly indicate if a copy should be made.
-     * In both of the below calls the resource backing the surface will never change.
-     *
-     * The 'asImage' entry point has some major ramifications for the mutability of the
-     * returned SkImage. Since the originating surface and the returned image share the
-     * same backing, care must be taken by the client to ensure that the contents of the image
-     * reflect the desired contents when it is consumed by the gpu.
-     * Note: if the backing GPU buffer isn't textureable this method will return null. Graphite
-     * will not attempt to make a copy.
-     * Note: For 'asImage', the mipmapping of the image will match that of the source surface.
-     *
-     * The 'makeImageCopy' entry point allows subsetting and the addition of mipmaps (since
-     * a copy is already being made).
-     *
-     * In Graphite, the legacy API call (i.e., makeImageSnapshot) will just always make a copy.
-     */
-    sk_sp<SkImage> asImage();
-
-    sk_sp<SkImage> makeImageCopy(const SkIRect* subset = nullptr,
-                                 skgpu::Mipmapped mipmapped = skgpu::Mipmapped::kNo);
-#endif
-
     /** Draws SkSurface contents to canvas, with its top-left corner at (x, y).
 
         If SkPaint paint is not nullptr, apply SkColorFilter, alpha, SkImageFilter, and SkBlendMode.
@@ -1001,131 +595,6 @@ public:
     */
     const SkSurfaceProps& props() const { return fProps; }
 
-    /** Call to ensure all reads/writes of the surface have been issued to the underlying 3D API.
-        Skia will correctly order its own draws and pixel operations. This must to be used to ensure
-        correct ordering when the surface backing store is accessed outside Skia (e.g. direct use of
-        the 3D API or a windowing system). GrDirectContext has additional flush and submit methods
-        that apply to all surfaces and images created from a GrDirectContext. This is equivalent to
-        calling SkSurface::flush with a default GrFlushInfo followed by
-        GrDirectContext::submit(syncCpu).
-    */
-    void flushAndSubmit(bool syncCpu = false);
-
-    enum class BackendSurfaceAccess {
-        kNoAccess,  //!< back-end object will not be used by client
-        kPresent,   //!< back-end surface will be used for presenting to screen
-    };
-
-#if defined(SK_GANESH)
-    /** If a surface is GPU texture backed, is being drawn with MSAA, and there is a resolve
-        texture, this call will insert a resolve command into the stream of gpu commands. In order
-        for the resolve to actually have an effect, the work still needs to be flushed and submitted
-        to the GPU after recording the resolve command. If a resolve is not supported or the
-        SkSurface has no dirty work to resolve, then this call is a no-op.
-
-        This call is most useful when the SkSurface is created by wrapping a single sampled gpu
-        texture, but asking Skia to render with MSAA. If the client wants to use the wrapped texture
-        outside of Skia, the only way to trigger a resolve is either to call this command or use
-        SkSurface::flush.
-     */
-    void resolveMSAA();
-
-    /** Issues pending SkSurface commands to the GPU-backed API objects and resolves any SkSurface
-        MSAA. A call to GrDirectContext::submit is always required to ensure work is actually sent
-        to the gpu. Some specific API details:
-            GL: Commands are actually sent to the driver, but glFlush is never called. Thus some
-                sync objects from the flush will not be valid until a submission occurs.
-
-            Vulkan/Metal/D3D/Dawn: Commands are recorded to the backend APIs corresponding command
-                buffer or encoder objects. However, these objects are not sent to the gpu until a
-                submission occurs.
-
-        The work that is submitted to the GPU will be dependent on the BackendSurfaceAccess that is
-        passed in.
-
-        If BackendSurfaceAccess::kNoAccess is passed in all commands will be issued to the GPU.
-
-        If BackendSurfaceAccess::kPresent is passed in and the backend API is not Vulkan, it is
-        treated the same as kNoAccess. If the backend API is Vulkan, the VkImage that backs the
-        SkSurface will be transferred back to its original queue. If the SkSurface was created by
-        wrapping a VkImage, the queue will be set to the queue which was originally passed in on
-        the GrVkImageInfo. Additionally, if the original queue was not external or foreign the
-        layout of the VkImage will be set to VK_IMAGE_LAYOUT_PRESENT_SRC_KHR.
-
-        The GrFlushInfo describes additional options to flush. Please see documentation at
-        GrFlushInfo for more info.
-
-        If the return is GrSemaphoresSubmitted::kYes, only initialized GrBackendSemaphores will be
-        submitted to the gpu during the next submit call (it is possible Skia failed to create a
-        subset of the semaphores). The client should not wait on these semaphores until after submit
-        has been called, but must keep them alive until then. If a submit flag was passed in with
-        the flush these valid semaphores can we waited on immediately. If this call returns
-        GrSemaphoresSubmitted::kNo, the GPU backend will not submit any semaphores to be signaled on
-        the GPU. Thus the client should not have the GPU wait on any of the semaphores passed in
-        with the GrFlushInfo. Regardless of whether semaphores were submitted to the GPU or not, the
-        client is still responsible for deleting any initialized semaphores.
-        Regardless of semaphore submission the context will still be flushed. It should be
-        emphasized that a return value of GrSemaphoresSubmitted::kNo does not mean the flush did not
-        happen. It simply means there were no semaphores submitted to the GPU. A caller should only
-        take this as a failure if they passed in semaphores to be submitted.
-
-        Pending surface commands are flushed regardless of the return result.
-
-        @param access  type of access the call will do on the backend object after flush
-        @param info    flush options
-    */
-    GrSemaphoresSubmitted flush(BackendSurfaceAccess access, const GrFlushInfo& info);
-
-    /** Issues pending SkSurface commands to the GPU-backed API objects and resolves any SkSurface
-        MSAA. A call to GrDirectContext::submit is always required to ensure work is actually sent
-        to the gpu. Some specific API details:
-            GL: Commands are actually sent to the driver, but glFlush is never called. Thus some
-                sync objects from the flush will not be valid until a submission occurs.
-
-            Vulkan/Metal/D3D/Dawn: Commands are recorded to the backend APIs corresponding command
-                buffer or encoder objects. However, these objects are not sent to the gpu until a
-                submission occurs.
-
-        The GrFlushInfo describes additional options to flush. Please see documentation at
-        GrFlushInfo for more info.
-
-        If a skgpu::MutableTextureState is passed in, at the end of the flush we will transition
-        the surface to be in the state requested by the skgpu::MutableTextureState. If the surface
-        (or SkImage or GrBackendSurface wrapping the same backend object) is used again after this
-        flush the state may be changed and no longer match what is requested here. This is often
-        used if the surface will be used for presenting or external use and the client wants backend
-        object to be prepped for that use. A finishedProc or semaphore on the GrFlushInfo will also
-        include the work for any requested state change.
-
-        If the backend API is Vulkan, the caller can set the skgpu::MutableTextureState's
-        VkImageLayout to VK_IMAGE_LAYOUT_UNDEFINED or queueFamilyIndex to VK_QUEUE_FAMILY_IGNORED to
-        tell Skia to not change those respective states.
-
-        If the return is GrSemaphoresSubmitted::kYes, only initialized GrBackendSemaphores will be
-        submitted to the gpu during the next submit call (it is possible Skia failed to create a
-        subset of the semaphores). The client should not wait on these semaphores until after submit
-        has been called, but must keep them alive until then. If a submit flag was passed in with
-        the flush these valid semaphores can we waited on immediately. If this call returns
-        GrSemaphoresSubmitted::kNo, the GPU backend will not submit any semaphores to be signaled on
-        the GPU. Thus the client should not have the GPU wait on any of the semaphores passed in
-        with the GrFlushInfo. Regardless of whether semaphores were submitted to the GPU or not, the
-        client is still responsible for deleting any initialized semaphores.
-        Regardleess of semaphore submission the context will still be flushed. It should be
-        emphasized that a return value of GrSemaphoresSubmitted::kNo does not mean the flush did not
-        happen. It simply means there were no semaphores submitted to the GPU. A caller should only
-        take this as a failure if they passed in semaphores to be submitted.
-
-        Pending surface commands are flushed regardless of the return result.
-
-        @param info    flush options
-        @param access  optional state change request after flush
-    */
-    GrSemaphoresSubmitted flush(const GrFlushInfo& info,
-                                const skgpu::MutableTextureState* newState = nullptr);
-#endif // defined(SK_GANESH)
-
-    void flush();
-
     /** Inserts a list of GPU semaphores that the current GPU-backed API must wait on before
         executing any more commands on the GPU for this surface. If this call returns false, then
         the GPU back-end will not wait on any passed in semaphores, and the client will still own
@@ -1144,9 +613,9 @@ public:
     bool wait(int numSemaphores, const GrBackendSemaphore* waitSemaphores,
               bool deleteSemaphoresAfterWait = true);
 
-    /** Initializes SkSurfaceCharacterization that can be used to perform GPU back-end
+    /** Initializes GrSurfaceCharacterization that can be used to perform GPU back-end
         processing in a separate thread. Typically this is used to divide drawing
-        into multiple tiles. SkDeferredDisplayListRecorder records the drawing commands
+        into multiple tiles. GrDeferredDisplayListRecorder records the drawing commands
         for each tile.
 
         Return true if SkSurface supports characterization. raster surface returns false.
@@ -1156,27 +625,7 @@ public:
 
         example: https://fiddle.skia.org/c/@Surface_characterize
     */
-    bool characterize(SkSurfaceCharacterization* characterization) const;
-
-    /** Draws the deferred display list created via a SkDeferredDisplayListRecorder.
-        If the deferred display list is not compatible with this SkSurface, the draw is skipped
-        and false is return.
-
-        The xOffset and yOffset parameters are experimental and, if not both zero, will cause
-        the draw to be ignored.
-        When implemented, if xOffset or yOffset are non-zero, the DDL will be drawn offset by that
-        amount into the surface.
-
-        @param deferredDisplayList  drawing commands
-        @param xOffset              x-offset at which to draw the DDL
-        @param yOffset              y-offset at which to draw the DDL
-        @return                     false if deferredDisplayList is not compatible
-
-        example: https://fiddle.skia.org/c/@Surface_draw_2
-    */
-    bool draw(sk_sp<const SkDeferredDisplayList> deferredDisplayList,
-              int xOffset = 0,
-              int yOffset = 0);
+    bool characterize(GrSurfaceCharacterization* characterization) const;
 
 protected:
     SkSurface(int width, int height, const SkSurfaceProps* surfaceProps);
@@ -1194,6 +643,25 @@ private:
     uint32_t             fGenerationID;
 
     using INHERITED = SkRefCnt;
+
+public:
+#if !defined(SK_DISABLE_LEGACY_SKSURFACE_FLUSH) && defined(SK_GANESH)
+    using BackendSurfaceAccess = SkSurfaces::BackendSurfaceAccess;
+    GrSemaphoresSubmitted flush(BackendSurfaceAccess access, const GrFlushInfo& info);
+    GrSemaphoresSubmitted flush(const GrFlushInfo& info,
+                                const skgpu::MutableTextureState* newState = nullptr);
+    void resolveMSAA();
+#endif
+
+#if !defined(SK_DISABLE_LEGACY_SKSURFACE_FLUSH)
+    void flushAndSubmit(bool syncCpu = false);
+    void flush();
+#endif
+
+#if !defined(SK_DISABLE_LEGACY_SKSURFACE_AS_IMAGE) && defined(SK_GRAPHITE)
+    sk_sp<SkImage> asImage();
+#endif
+
 };
 
 #endif