/*

 * Copyright 2006 The Android Open Source Project

 *

 * Use of this source code is governed by a BSD-style license that can be

 * found in the LICENSE file.

 */

#ifndef SkCanvas_DEFINED

#define SkCanvas_DEFINED

#include "include/core/SkArc.h"

#include "include/core/SkBlendMode.h"

#include "include/core/SkClipOp.h"

#include "include/core/SkColor.h"

#include "include/core/SkFontTypes.h"

#include "include/core/SkImageFilter.h"

#include "include/core/SkImageInfo.h"

#include "include/core/SkM44.h"

#include "include/core/SkMatrix.h"

#include "include/core/SkPaint.h"

#include "include/core/SkPoint.h"

#include "include/core/SkRasterHandleAllocator.h"

#include "include/core/SkRect.h"

#include "include/core/SkRefCnt.h"

#include "include/core/SkSamplingOptions.h"

#include "include/core/SkScalar.h"

#include "include/core/SkSize.h"

#include "include/core/SkSpan.h"

#include "include/core/SkString.h"

#include "include/core/SkSurfaceProps.h"

#include "include/core/SkTypes.h"

#include "include/private/base/SkCPUTypes.h"

#include "include/private/base/SkDeque.h"

#include "include/private/base/SkTArray.h"

#include <cstdint>

#include <cstring>

#include <memory>

#include <optional>

#ifndef SK_SUPPORT_LEGACY_GETTOTALMATRIX

#define SK_SUPPORT_LEGACY_GETTOTALMATRIX

#endif

namespace sktext {

class GlyphRunBuilder;

class GlyphRunList;

}

class AutoLayerForImageFilter;

class GrRecordingContext;

class SkBitmap;

class SkBlender;

class SkColorSpace;

class SkData;

class SkDevice;

class SkDrawable;

class SkFont;

class SkImage;

class SkMesh;

class SkPaintFilterCanvas;

class SkPath;

class SkPicture;

class SkPixmap;

class SkRRect;

class SkRegion;

class SkShader;

class SkSpecialImage;

class SkSurface;

class SkSurface_Base;

class SkTextBlob;

class SkVertices;

struct SkDrawShadowRec;

struct SkRSXform;

template<typename E>

class SkEnumBitMask;

namespace skgpu::graphite { class Recorder; }

namespace sktext::gpu { class Slug; }

namespace SkRecords { class Draw; }

namespace skiatest {

template <typename Key>

class TestCanvas;// IWYU pragma: keep

}

/** \class SkCanvas

    SkCanvas provides an interface for drawing, and how the drawing is clipped and transformed.

    SkCanvas contains a stack of SkMatrix and clip values.

    SkCanvas and SkPaint together provide the state to draw into SkSurface or SkDevice.

    Each SkCanvas draw call transforms the geometry of the object by the concatenation of all

    SkMatrix values in the stack. The transformed geometry is clipped by the intersection

    of all of clip values in the stack. The SkCanvas draw calls use SkPaint to supply drawing

    state such as color, SkTypeface, text size, stroke width, SkShader and so on.

    To draw to a pixel-based destination, create raster surface or GPU surface.

    Request SkCanvas from SkSurface to obtain the interface to draw.

    SkCanvas generated by raster surface draws to memory visible to the CPU.

    SkCanvas generated by GPU surface uses Vulkan or OpenGL to draw to the GPU.

    To draw to a document, obtain SkCanvas from SVG canvas, document PDF, or SkPictureRecorder.

    SkDocument based SkCanvas and other SkCanvas subclasses reference SkDevice describing the

    destination.

    SkCanvas can be constructed to draw to SkBitmap without first creating raster surface.

    This approach may be deprecated in the future.

*/

class SK_API SkCanvas {

public:

    /** Allocates raster SkCanvas that will draw directly into pixels.

        SkCanvas is returned if all parameters are valid.

        Valid parameters include:

        info dimensions are zero or positive;

        info contains SkColorType and SkAlphaType supported by raster surface;

        pixels is not nullptr;

        rowBytes is zero or large enough to contain info width pixels of SkColorType.

        Pass zero for rowBytes to compute rowBytes from info width and size of pixel.

        If rowBytes is greater than zero, it must be equal to or greater than

        info width times bytes required for 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 info      width, height, SkColorType, SkAlphaType, SkColorSpace, of raster surface;

                         width, or height, or both, may be zero

        @param pixels    pointer to destination pixels buffer

        @param rowBytes  interval from one SkSurface row to the next, or zero

        @param props     LCD striping orientation and setting for device independent fonts;

                         may be nullptr

        @return          SkCanvas if all parameters are valid; otherwise, nullptr

    */

    static std::unique_ptr<SkCanvas> MakeRasterDirect(const SkImageInfo& info, void* pixels,

                                                      size_t rowBytes,

                                                      const SkSurfaceProps* props = nullptr);

    /** Allocates raster SkCanvas specified by inline image specification. Subsequent SkCanvas

        calls draw into pixels.

        SkColorType is set to kN32_SkColorType.

        SkAlphaType is set to kPremul_SkAlphaType.

        To access pixels after drawing, call flush() or peekPixels().

        SkCanvas is returned if all parameters are valid.

        Valid parameters include:

        width and height are zero or positive;

        pixels is not nullptr;

        rowBytes is zero or large enough to contain width pixels of kN32_SkColorType.

        Pass zero for rowBytes to compute rowBytes from width and size of pixel.

        If rowBytes is greater than zero, it must be equal to or greater than

        width times bytes required for SkColorType.

        Pixel buffer size should be height times rowBytes.

        @param width     pixel column count on raster surface created; must be zero or greater

        @param height    pixel row count on raster surface created; must be zero or greater

        @param pixels    pointer to destination pixels buffer; buffer size should be height

                         times rowBytes

        @param rowBytes  interval from one SkSurface row to the next, or zero

        @return          SkCanvas if all parameters are valid; otherwise, nullptr

    */

    static std::unique_ptr<SkCanvas> MakeRasterDirectN32(int width, int height, SkPMColor* pixels,

                                                         size_t rowBytes) {

        return MakeRasterDirect(SkImageInfo::MakeN32Premul(width, height), pixels, rowBytes);

    }

    /** Creates an empty SkCanvas with no backing device or pixels, with

        a width and height of zero.

        @return  empty SkCanvas

        example: https://fiddle.skia.org/c/@Canvas_empty_constructor

    */

    SkCanvas();

    /** Creates SkCanvas of the specified dimensions without a SkSurface.

        Used by subclasses with custom implementations for draw member functions.

        If props equals nullptr, SkSurfaceProps are created with

        SkSurfaceProps::InitType settings, which choose the pixel striping

        direction and order. Since a platform may dynamically change its direction when

        the device is rotated, and since a platform may have multiple monitors with

        different characteristics, it is best not to rely on this legacy behavior.

        @param width   zero or greater

        @param height  zero or greater

        @param props   LCD striping orientation and setting for device independent fonts;

                       may be nullptr

        @return        SkCanvas placeholder with dimensions

        example: https://fiddle.skia.org/c/@Canvas_int_int_const_SkSurfaceProps_star

    */

    SkCanvas(int width, int height, const SkSurfaceProps* props = nullptr);

    /** Private. For internal use only.

    */

    explicit SkCanvas(sk_sp<SkDevice> device);

    /** Constructs a canvas that draws into bitmap.

        Sets kUnknown_SkPixelGeometry in constructed SkSurface.

        SkBitmap is copied so that subsequently editing bitmap will not affect

        constructed SkCanvas.

        May be deprecated in the future.

        @param bitmap  width, height, SkColorType, SkAlphaType, and pixel

                       storage of raster surface

        @return        SkCanvas that can be used to draw into bitmap

        example: https://fiddle.skia.org/c/@Canvas_copy_const_SkBitmap

    */

    explicit SkCanvas(const SkBitmap& bitmap);

#ifdef SK_BUILD_FOR_ANDROID_FRAMEWORK

    /** Private.

     */

    enum class ColorBehavior {

        kLegacy, //!< placeholder

    };

    /** Private. For use by Android framework only.

        @param bitmap    specifies a bitmap for the canvas to draw into

        @param behavior  specializes this constructor; value is unused

        @return          SkCanvas that can be used to draw into bitmap

    */

    SkCanvas(const SkBitmap& bitmap, ColorBehavior behavior);

#endif

    /** Constructs a canvas that draws into bitmap.

        Use props to match the device characteristics, like LCD striping.

        bitmap is copied so that subsequently editing bitmap will not affect

        constructed SkCanvas.

        @param bitmap  width, height, SkColorType, SkAlphaType,

                       and pixel storage of raster surface

        @param props   order and orientation of RGB striping; and whether to use

                       device independent fonts

        @return        SkCanvas that can be used to draw into bitmap

        example: https://fiddle.skia.org/c/@Canvas_const_SkBitmap_const_SkSurfaceProps

    */

    SkCanvas(const SkBitmap& bitmap, const SkSurfaceProps& props);

    /** Draws saved layers, if any.

        Frees up resources used by SkCanvas.

        example: https://fiddle.skia.org/c/@Canvas_destructor

    */

    virtual ~SkCanvas();

    /** Returns SkImageInfo for SkCanvas. If SkCanvas is not associated with raster surface or

        GPU surface, returned SkColorType is set to kUnknown_SkColorType.

        @return  dimensions and SkColorType of SkCanvas

        example: https://fiddle.skia.org/c/@Canvas_imageInfo

    */

    SkImageInfo imageInfo() const;

    /** Copies SkSurfaceProps, if SkCanvas is associated with raster surface or

        GPU surface, and returns true. Otherwise, returns false and leave props unchanged.

        @param props  storage for writable SkSurfaceProps

        @return       true if SkSurfaceProps was copied

        DEPRECATED: Replace usage with getBaseProps() or getTopProps()

        example: https://fiddle.skia.org/c/@Canvas_getProps

    */

    bool getProps(SkSurfaceProps* props) const;

    /** Returns the SkSurfaceProps associated with the canvas (i.e., at the base of the layer

        stack).

        @return  base SkSurfaceProps

    */

    SkSurfaceProps getBaseProps() const;

    /** Returns the SkSurfaceProps associated with the canvas that are currently active (i.e., at

        the top of the layer stack). This can differ from getBaseProps depending on the flags

        passed to saveLayer (see SaveLayerFlagsSet).

        @return  SkSurfaceProps active in the current/top layer

    */

    SkSurfaceProps getTopProps() const;

    /** Gets the size of the base or root layer in global canvas coordinates. The

        origin of the base layer is always (0,0). The area available for drawing may be

        smaller (due to clipping or saveLayer).

        @return  integral width and height of base layer

        example: https://fiddle.skia.org/c/@Canvas_getBaseLayerSize

    */

    virtual SkISize getBaseLayerSize() const;

    /** Creates SkSurface matching info and props, and associates it with SkCanvas.

        Returns nullptr if no match found.

        If props is nullptr, matches SkSurfaceProps in SkCanvas. If props is nullptr and SkCanvas

        does not have SkSurfaceProps, creates SkSurface with default SkSurfaceProps.

        @param info   width, height, SkColorType, SkAlphaType, and SkColorSpace

        @param props  SkSurfaceProps to match; may be nullptr to match SkCanvas

        @return       SkSurface matching info and props, or nullptr if no match is available

        example: https://fiddle.skia.org/c/@Canvas_makeSurface

    */

    sk_sp<SkSurface> makeSurface(const SkImageInfo& info, const SkSurfaceProps* props = nullptr);

    /** Returns Ganesh context of the GPU surface associated with SkCanvas.

        @return  GPU context, if available; nullptr otherwise

        example: https://fiddle.skia.org/c/@Canvas_recordingContext

     */

    virtual GrRecordingContext* recordingContext() const;

    /** Returns Recorder for the GPU surface associated with SkCanvas.

        @return  Recorder, if available; nullptr otherwise

     */

    virtual skgpu::graphite::Recorder* recorder() const;

    /** Sometimes a canvas is owned by a surface. If it is, getSurface() will return a bare

     *  pointer to that surface, else this will return nullptr.

     */

    SkSurface* getSurface() const;

    /** Returns the pixel base address, SkImageInfo, rowBytes, and origin if the pixels

        can be read directly. The returned address is only valid

        while SkCanvas is in scope and unchanged. Any SkCanvas call or SkSurface call

        may invalidate the returned address and other returned values.

        If pixels are inaccessible, info, rowBytes, and origin are unchanged.

        @param info      storage for writable pixels' SkImageInfo; may be nullptr

        @param rowBytes  storage for writable pixels' row bytes; may be nullptr

        @param origin    storage for SkCanvas top layer origin, its top-left corner;

                         may be nullptr

        @return          address of pixels, or nullptr if inaccessible

        example: https://fiddle.skia.org/c/@Canvas_accessTopLayerPixels_a

        example: https://fiddle.skia.org/c/@Canvas_accessTopLayerPixels_b

    */

    void* accessTopLayerPixels(SkImageInfo* info, size_t* rowBytes, SkIPoint* origin = nullptr);

    /** Returns custom context that tracks the SkMatrix and clip.

        Use SkRasterHandleAllocator to blend Skia drawing with custom drawing, typically performed

        by the host platform user interface. The custom context returned is generated by

        SkRasterHandleAllocator::MakeCanvas, which creates a custom canvas with raster storage for

        the drawing destination.

        @return  context of custom allocation

        example: https://fiddle.skia.org/c/@Canvas_accessTopRasterHandle

    */

    SkRasterHandleAllocator::Handle accessTopRasterHandle() const;

    /** Returns true if SkCanvas has direct access to its pixels.

        Pixels are readable when SkDevice is raster. Pixels are not readable when SkCanvas

        is returned from GPU surface, returned by SkDocument::beginPage, returned by

        SkPictureRecorder::beginRecording, or SkCanvas is the base of a utility class

        like DebugCanvas.

        pixmap is valid only while SkCanvas is in scope and unchanged. Any

        SkCanvas or SkSurface call may invalidate the pixmap values.

        @param pixmap  storage for pixel state if pixels are readable; otherwise, ignored

        @return        true if SkCanvas has direct access to pixels

        example: https://fiddle.skia.org/c/@Canvas_peekPixels

    */

    bool peekPixels(SkPixmap* pixmap);

    /** Copies SkRect of pixels from SkCanvas into dstPixels. SkMatrix and clip are

        ignored.

        Source SkRect corners are (srcX, srcY) and (imageInfo().width(), imageInfo().height()).

        Destination SkRect corners are (0, 0) and (dstInfo.width(), dstInfo.height()).

        Copies each readable pixel intersecting both rectangles, without scaling,

        converting to dstInfo.colorType() and dstInfo.alphaType() if required.

        Pixels are readable when SkDevice is raster, or backed by a GPU.

        Pixels are not readable when SkCanvas is returned by SkDocument::beginPage,

        returned by SkPictureRecorder::beginRecording, or SkCanvas is the base of a utility

        class like DebugCanvas.

        The destination pixel storage must be allocated by the caller.

        Pixel values are converted only if SkColorType and SkAlphaType

        do not match. Only pixels within both source and destination rectangles

        are copied. dstPixels contents outside SkRect intersection are unchanged.

        Pass negative values for srcX or srcY to offset pixels across or down destination.

        Does not copy, and returns false if:

        - Source and destination rectangles do not intersect.

        - SkCanvas pixels could not be converted to dstInfo.colorType() or dstInfo.alphaType().

        - SkCanvas pixels are not readable; for instance, SkCanvas is document-based.

        - dstRowBytes is too small to contain one row of pixels.

        @param dstInfo      width, height, SkColorType, and SkAlphaType of dstPixels

        @param dstPixels    storage for pixels; dstInfo.height() times dstRowBytes, or larger

        @param dstRowBytes  size of one destination row; dstInfo.width() times pixel size, or larger

        @param srcX         offset into readable pixels on x-axis; may be negative

        @param srcY         offset into readable pixels on y-axis; may be negative

        @return             true if pixels were copied

    */

    bool readPixels(const SkImageInfo& dstInfo, void* dstPixels, size_t dstRowBytes,

                    int srcX, int srcY);

    /** Copies SkRect of pixels from SkCanvas into pixmap. SkMatrix and clip are

        ignored.

        Source SkRect corners are (srcX, srcY) and (imageInfo().width(), imageInfo().height()).

        Destination SkRect corners are (0, 0) and (pixmap.width(), pixmap.height()).

        Copies each readable pixel intersecting both rectangles, without scaling,

        converting to pixmap.colorType() and pixmap.alphaType() if required.

        Pixels are readable when SkDevice is raster, or backed by a GPU.

        Pixels are not readable when SkCanvas is returned by SkDocument::beginPage,

        returned by SkPictureRecorder::beginRecording, or SkCanvas is the base of a utility

        class like DebugCanvas.

        Caller must allocate pixel storage in pixmap if needed.

        Pixel values are converted only if SkColorType and SkAlphaType

        do not match. Only pixels within both source and destination SkRect

        are copied. pixmap pixels contents outside SkRect intersection are unchanged.

        Pass negative values for srcX or srcY to offset pixels across or down pixmap.

        Does not copy, and returns false if:

        - Source and destination rectangles do not intersect.

        - SkCanvas pixels could not be converted to pixmap.colorType() or pixmap.alphaType().

        - SkCanvas pixels are not readable; for instance, SkCanvas is document-based.

        - SkPixmap pixels could not be allocated.

        - pixmap.rowBytes() is too small to contain one row of pixels.

        @param pixmap  storage for pixels copied from SkCanvas

        @param srcX    offset into readable pixels on x-axis; may be negative

        @param srcY    offset into readable pixels on y-axis; may be negative

        @return        true if pixels were copied

        example: https://fiddle.skia.org/c/@Canvas_readPixels_2

    */

    bool readPixels(const SkPixmap& pixmap, int srcX, int srcY);

    /** Copies SkRect of pixels from SkCanvas into bitmap. SkMatrix and clip are

        ignored.

        Source SkRect corners are (srcX, srcY) and (imageInfo().width(), imageInfo().height()).

        Destination SkRect corners are (0, 0) and (bitmap.width(), bitmap.height()).

        Copies each readable pixel intersecting both rectangles, without scaling,

        converting to bitmap.colorType() and bitmap.alphaType() if required.

        Pixels are readable when SkDevice is raster, or backed by a GPU.

        Pixels are not readable when SkCanvas is returned by SkDocument::beginPage,

        returned by SkPictureRecorder::beginRecording, or SkCanvas is the base of a utility

        class like DebugCanvas.

        Caller must allocate pixel storage in bitmap if needed.

        SkBitmap values are converted only if SkColorType and SkAlphaType

        do not match. Only pixels within both source and destination rectangles

        are copied. SkBitmap pixels outside SkRect intersection are unchanged.

        Pass negative values for srcX or srcY to offset pixels across or down bitmap.

        Does not copy, and returns false if:

        - Source and destination rectangles do not intersect.

        - SkCanvas pixels could not be converted to bitmap.colorType() or bitmap.alphaType().

        - SkCanvas pixels are not readable; for instance, SkCanvas is document-based.

        - bitmap pixels could not be allocated.

        - bitmap.rowBytes() is too small to contain one row of pixels.

        @param bitmap  storage for pixels copied from SkCanvas

        @param srcX    offset into readable pixels on x-axis; may be negative

        @param srcY    offset into readable pixels on y-axis; may be negative

        @return        true if pixels were copied

        example: https://fiddle.skia.org/c/@Canvas_readPixels_3

    */

    bool readPixels(const SkBitmap& bitmap, int srcX, int srcY);

    /** Copies SkRect from pixels to SkCanvas. SkMatrix and clip are ignored.

        Source SkRect corners are (0, 0) and (info.width(), info.height()).

        Destination SkRect corners are (x, y) and

        (imageInfo().width(), imageInfo().height()).

        Copies each readable pixel intersecting both rectangles, without scaling,

        converting to imageInfo().colorType() and imageInfo().alphaType() if required.

        Pixels are writable when SkDevice is raster, or backed by a GPU.

        Pixels are not writable when SkCanvas is returned by SkDocument::beginPage,

        returned by SkPictureRecorder::beginRecording, or SkCanvas is the base of a utility

        class like DebugCanvas.

        Pixel values are converted only if SkColorType and SkAlphaType

        do not match. Only pixels within both source and destination rectangles

        are copied. SkCanvas pixels outside SkRect intersection are unchanged.

        Pass negative values for x or y to offset pixels to the left or

        above SkCanvas pixels.

        Does not copy, and returns false if:

        - Source and destination rectangles do not intersect.

        - pixels could not be converted to SkCanvas imageInfo().colorType() or

        imageInfo().alphaType().

        - SkCanvas pixels are not writable; for instance, SkCanvas is document-based.

        - rowBytes is too small to contain one row of pixels.

        @param info      width, height, SkColorType, and SkAlphaType of pixels

        @param pixels    pixels to copy, of size info.height() times rowBytes, or larger

        @param rowBytes  size of one row of pixels; info.width() times pixel size, or larger

        @param x         offset into SkCanvas writable pixels on x-axis; may be negative

        @param y         offset into SkCanvas writable pixels on y-axis; may be negative

        @return          true if pixels were written to SkCanvas

        example: https://fiddle.skia.org/c/@Canvas_writePixels

    */

    bool writePixels(const SkImageInfo& info, const void* pixels, size_t rowBytes, int x, int y);

    /** Copies SkRect from pixels to SkCanvas. SkMatrix and clip are ignored.

        Source SkRect corners are (0, 0) and (bitmap.width(), bitmap.height()).

        Destination SkRect corners are (x, y) and

        (imageInfo().width(), imageInfo().height()).

        Copies each readable pixel intersecting both rectangles, without scaling,

        converting to imageInfo().colorType() and imageInfo().alphaType() if required.

        Pixels are writable when SkDevice is raster, or backed by a GPU.

        Pixels are not writable when SkCanvas is returned by SkDocument::beginPage,

        returned by SkPictureRecorder::beginRecording, or SkCanvas is the base of a utility

        class like DebugCanvas.

        Pixel values are converted only if SkColorType and SkAlphaType

        do not match. Only pixels within both source and destination rectangles

        are copied. SkCanvas pixels outside SkRect intersection are unchanged.

        Pass negative values for x or y to offset pixels to the left or

        above SkCanvas pixels.

        Does not copy, and returns false if:

        - Source and destination rectangles do not intersect.

        - bitmap does not have allocated pixels.

        - bitmap pixels could not be converted to SkCanvas imageInfo().colorType() or

        imageInfo().alphaType().

        - SkCanvas pixels are not writable; for instance, SkCanvas is document based.

        - bitmap pixels are inaccessible; for instance, bitmap wraps a texture.

        @param bitmap  contains pixels copied to SkCanvas

        @param x       offset into SkCanvas writable pixels on x-axis; may be negative

        @param y       offset into SkCanvas writable pixels on y-axis; may be negative

        @return        true if pixels were written to SkCanvas

        example: https://fiddle.skia.org/c/@Canvas_writePixels_2

        example: https://fiddle.skia.org/c/@State_Stack_a

        example: https://fiddle.skia.org/c/@State_Stack_b

    */

    bool writePixels(const SkBitmap& bitmap, int x, int y);

    /** Saves SkMatrix and clip.

        Calling restore() discards changes to SkMatrix and clip,

        restoring the SkMatrix and clip to their state when save() was called.

        SkMatrix may be changed by translate(), scale(), rotate(), skew(), concat(), setMatrix(),

        and resetMatrix(). Clip may be changed by clipRect(), clipRRect(), clipPath(), clipRegion().

        Saved SkCanvas state is put on a stack; multiple calls to save() should be balance

        by an equal number of calls to restore().

        Call restoreToCount() with result to restore this and subsequent saves.

        @return  depth of saved stack

        example: https://fiddle.skia.org/c/@Canvas_save

    */

    int save();

    /** Saves SkMatrix and clip, and allocates a SkSurface for subsequent drawing.

        Calling restore() discards changes to SkMatrix and clip, and draws the SkSurface.

        SkMatrix may be changed by translate(), scale(), rotate(), skew(), concat(),

        setMatrix(), and resetMatrix(). Clip may be changed by clipRect(), clipRRect(),

        clipPath(), clipRegion().

        SkRect bounds suggests but does not define the SkSurface size. To clip drawing to

        a specific rectangle, use clipRect().

        Optional SkPaint paint applies alpha, SkColorFilter, SkImageFilter, and

        SkBlendMode when restore() is called.

        Call restoreToCount() with returned value to restore this and subsequent saves.

        @param bounds  hint to limit the size of the layer; may be nullptr

        @param paint   graphics state for layer; may be nullptr

        @return        depth of saved stack

        example: https://fiddle.skia.org/c/@Canvas_saveLayer

        example: https://fiddle.skia.org/c/@Canvas_saveLayer_4

    */

    int saveLayer(const SkRect* bounds, const SkPaint* paint);

    /** Saves SkMatrix and clip, and allocates a SkSurface for subsequent drawing.

        Calling restore() discards changes to SkMatrix and clip, and draws the SkSurface.

        SkMatrix may be changed by translate(), scale(), rotate(), skew(), concat(),

        setMatrix(), and resetMatrix(). Clip may be changed by clipRect(), clipRRect(),

        clipPath(), clipRegion().

        SkRect bounds suggests but does not define the layer size. To clip drawing to

        a specific rectangle, use clipRect().

        Optional SkPaint paint applies alpha, SkColorFilter, SkImageFilter, and

        SkBlendMode when restore() is called.

        Call restoreToCount() with returned value to restore this and subsequent saves.

        @param bounds  hint to limit the size of layer; may be nullptr

        @param paint   graphics state for layer; may be nullptr

        @return        depth of saved stack

    */

    int saveLayer(const SkRect& bounds, const SkPaint* paint) {

        return this->saveLayer(&bounds, paint);

    }

    /** Saves SkMatrix and clip, and allocates SkSurface for subsequent drawing.

        Calling restore() discards changes to SkMatrix and clip,

        and blends layer with alpha opacity onto prior layer.

        SkMatrix may be changed by translate(), scale(), rotate(), skew(), concat(),

        setMatrix(), and resetMatrix(). Clip may be changed by clipRect(), clipRRect(),

        clipPath(), clipRegion().

        SkRect bounds suggests but does not define layer size. To clip drawing to

        a specific rectangle, use clipRect().

        alpha of zero is fully transparent, 1.0f is fully opaque.

        Call restoreToCount() with returned value to restore this and subsequent saves.

        @param bounds  hint to limit the size of layer; may be nullptr

        @param alpha   opacity of layer

        @return        depth of saved stack

        example: https://fiddle.skia.org/c/@Canvas_saveLayerAlpha

    */

    int saveLayerAlphaf(const SkRect* bounds, float alpha);

    // Helper that accepts an int between 0 and 255, and divides it by 255.0

    int saveLayerAlpha(const SkRect* bounds, U8CPU alpha) {

        return this->saveLayerAlphaf(bounds, alpha * (1.0f / 255));

    }

    /** \enum SkCanvas::SaveLayerFlagsSet

        SaveLayerFlags provides options that may be used in any combination in SaveLayerRec,

        defining how layer allocated by saveLayer() operates. It may be set to zero,

        kPreserveLCDText_SaveLayerFlag, kInitWithPrevious_SaveLayerFlag, or both flags.

    */

    enum SaveLayerFlagsSet {

        kPreserveLCDText_SaveLayerFlag  = 1 << 1,

        kInitWithPrevious_SaveLayerFlag = 1 << 2, //!< initializes with previous contents

        // instead of matching previous layer's colortype, use F16

        kF16ColorType                   = 1 << 4,

    };

    using SaveLayerFlags = uint32_t;

    using FilterSpan = SkSpan<sk_sp<SkImageFilter>>;

    static constexpr int kMaxFiltersPerLayer = 16;

    /** \struct SkCanvas::SaveLayerRec

        SaveLayerRec contains the state used to create the layer.

    */

    struct SaveLayerRec {

        /** Sets fBounds, fPaint, and fBackdrop to nullptr. Clears fSaveLayerFlags.

            @return  empty SaveLayerRec

        */

        SaveLayerRec() {}

        /** Sets fBounds, fPaint, and fSaveLayerFlags; sets fBackdrop to nullptr.

            @param bounds          layer dimensions; may be nullptr

            @param paint           applied to layer when overlaying prior layer; may be nullptr

            @param saveLayerFlags  SaveLayerRec options to modify layer

            @return                SaveLayerRec with empty fBackdrop

        */

        SaveLayerRec(const SkRect* bounds, const SkPaint* paint, SaveLayerFlags saveLayerFlags = 0)

            : SaveLayerRec(bounds, paint, nullptr, nullptr, 1.f, saveLayerFlags, /*filters=*/{}) {}

        /** Sets fBounds, fPaint, fBackdrop, and fSaveLayerFlags.

            @param bounds          layer dimensions; may be nullptr

            @param paint           applied to layer when overlaying prior layer;

                                   may be nullptr

            @param backdrop        If not null, this causes the current layer to be filtered by

                                   backdrop, and then drawn into the new layer

                                   (respecting the current clip).

                                   If null, the new layer is initialized with transparent-black.

            @param saveLayerFlags  SaveLayerRec options to modify layer

            @return                SaveLayerRec fully specified

        */

        SaveLayerRec(const SkRect* bounds, const SkPaint* paint, const SkImageFilter* backdrop,

                     SaveLayerFlags saveLayerFlags)

            : SaveLayerRec(bounds, paint, backdrop, nullptr, 1.f, saveLayerFlags, /*filters=*/{}) {}

        /** Sets fBounds, fColorSpace, and fSaveLayerFlags.

            @param bounds          layer dimensions; may be nullptr

            @param paint           applied to layer when overlaying prior layer;

                                   may be nullptr

            @param backdrop        If not null, this causes the current layer to be filtered by

                                   backdrop, and then drawn into the new layer

                                   (respecting the current clip).

                                   If null, the new layer is initialized with transparent-black.

            @param colorSpace      If not null, when the layer is restored, a color space

                                   conversion will be applied from this color space to the

                                   parent's color space. The restore paint and backdrop filters will

                                   be applied in this color space.

                                   If null, the new layer will inherit the color space from its

                                   parent.

            @param saveLayerFlags  SaveLayerRec options to modify layer

            @return                SaveLayerRec fully specified

        */

        SaveLayerRec(const SkRect* bounds, const SkPaint* paint, const SkImageFilter* backdrop,

                     const SkColorSpace* colorSpace, SaveLayerFlags saveLayerFlags)

            : SaveLayerRec(bounds, paint, backdrop, colorSpace, 1.f, saveLayerFlags, /*filters=*/{}) {}

        /** hints at layer size limit */

        const SkRect*        fBounds         = nullptr;

        /** modifies overlay */

        const SkPaint*       fPaint          = nullptr;

        FilterSpan           fFilters        = {};

        /**

         *  If not null, this triggers the same initialization behavior as setting

         *  kInitWithPrevious_SaveLayerFlag on fSaveLayerFlags: the current layer is copied into

         *  the new layer, rather than initializing the new layer with transparent-black.

         *  This is then filtered by fBackdrop (respecting the current clip).

         */

        const SkImageFilter* fBackdrop       = nullptr;

        /**

         * If not null, this triggers a color space conversion when the layer is restored. It

         * will be as if the layer's contents are drawn in this color space. Filters from

         * fBackdrop and fPaint will be applied in this color space.

         */

        const SkColorSpace* fColorSpace      = nullptr;

        /** preserves LCD text, creates with prior layer contents */

        SaveLayerFlags       fSaveLayerFlags = 0;

    private:

        friend class SkCanvas;

        friend class SkCanvasPriv;

        SaveLayerRec(const SkRect* bounds,

                     const SkPaint* paint,

                     const SkImageFilter* backdrop,

                     const SkColorSpace* colorSpace,

                     SkScalar backdropScale,

                     SaveLayerFlags saveLayerFlags,

                     FilterSpan filters)

                : fBounds(bounds)

                , fPaint(paint)

                , fFilters(filters)

                , fBackdrop(backdrop)

                , fColorSpace(colorSpace)

                , fSaveLayerFlags(saveLayerFlags)

                , fExperimentalBackdropScale(backdropScale) {

            // We only allow the paint's image filter or the side-car list of filters -- not both.

            SkASSERT(fFilters.empty() || !paint || !paint->getImageFilter());

            // To keep things reasonable (during deserialization), we limit filter list size.

            SkASSERT(fFilters.size() <= kMaxFiltersPerLayer);

        }

        // Relative scale factor that the image content used to initialize the layer when the

        // kInitFromPrevious flag or a backdrop filter is used.

        SkScalar             fExperimentalBackdropScale = 1.f;

    };

    /** Saves SkMatrix and clip, and allocates SkSurface for subsequent drawing.

        Calling restore() discards changes to SkMatrix and clip,

        and blends SkSurface with alpha opacity onto the prior layer.

        SkMatrix may be changed by translate(), scale(), rotate(), skew(), concat(),

        setMatrix(), and resetMatrix(). Clip may be changed by clipRect(), clipRRect(),

        clipPath(), clipRegion().

        SaveLayerRec contains the state used to create the layer.

        Call restoreToCount() with returned value to restore this and subsequent saves.

        @param layerRec  layer state

        @return          depth of save state stack before this call was made.

        example: https://fiddle.skia.org/c/@Canvas_saveLayer_3

    */

    int saveLayer(const SaveLayerRec& layerRec);

    /** Removes changes to SkMatrix and clip since SkCanvas state was

        last saved. The state is removed from the stack.

        Does nothing if the stack is empty.

        example: https://fiddle.skia.org/c/@AutoCanvasRestore_restore

        example: https://fiddle.skia.org/c/@Canvas_restore

    */

    void restore();

    /** Returns the number of saved states, each containing: SkMatrix and clip.

        Equals the number of save() calls less the number of restore() calls plus one.

        The save count of a new canvas is one.

        @return  depth of save state stack

        example: https://fiddle.skia.org/c/@Canvas_getSaveCount

    */

    int getSaveCount() const;

    /** Restores state to SkMatrix and clip values when save(), saveLayer(),

        saveLayerPreserveLCDTextRequests(), or saveLayerAlpha() returned saveCount.

        Does nothing if saveCount is greater than state stack count.

        Restores state to initial values if saveCount is less than or equal to one.

        @param saveCount  depth of state stack to restore

        example: https://fiddle.skia.org/c/@Canvas_restoreToCount

    */

    void restoreToCount(int saveCount);

    /** Translates SkMatrix by dx along the x-axis and dy along the y-axis.

        Mathematically, replaces SkMatrix with a translation matrix

        premultiplied with SkMatrix.

        This has the effect of moving the drawing by (dx, dy) before transforming

        the result with SkMatrix.

        @param dx  distance to translate on x-axis

        @param dy  distance to translate on y-axis

        example: https://fiddle.skia.org/c/@Canvas_translate

    */

    void translate(SkScalar dx, SkScalar dy);

    /** Scales SkMatrix by sx on the x-axis and sy on the y-axis.

        Mathematically, replaces SkMatrix with a scale matrix

        premultiplied with SkMatrix.

        This has the effect of scaling the drawing by (sx, sy) before transforming

        the result with SkMatrix.

        @param sx  amount to scale on x-axis

        @param sy  amount to scale on y-axis

        example: https://fiddle.skia.org/c/@Canvas_scale

    */

    void scale(SkScalar sx, SkScalar sy);

    /** Rotates SkMatrix by degrees. Positive degrees rotates clockwise.

        Mathematically, replaces SkMatrix with a rotation matrix

        premultiplied with SkMatrix.

        This has the effect of rotating the drawing by degrees before transforming

        the result with SkMatrix.

        @param degrees  amount to rotate, in degrees

        example: https://fiddle.skia.org/c/@Canvas_rotate

    */

    void rotate(SkScalar degrees);

    /** Rotates SkMatrix by degrees about a point at (px, py). Positive degrees rotates

        clockwise.

        Mathematically, constructs a rotation matrix; premultiplies the rotation matrix by

        a translation matrix; then replaces SkMatrix with the resulting matrix

        premultiplied with SkMatrix.

        This has the effect of rotating the drawing about a given point before

        transforming the result with SkMatrix.

        @param degrees  amount to rotate, in degrees

        @param px       x-axis value of the point to rotate about

        @param py       y-axis value of the point to rotate about

        example: https://fiddle.skia.org/c/@Canvas_rotate_2

    */

    void rotate(SkScalar degrees, SkScalar px, SkScalar py);

    /** Skews SkMatrix by sx on the x-axis and sy on the y-axis. A positive value of sx

        skews the drawing right as y-axis values increase; a positive value of sy skews

        the drawing down as x-axis values increase.

        Mathematically, replaces SkMatrix with a skew matrix premultiplied with SkMatrix.

        This has the effect of skewing the drawing by (sx, sy) before transforming

        the result with SkMatrix.

        @param sx  amount to skew on x-axis

        @param sy  amount to skew on y-axis

        example: https://fiddle.skia.org/c/@Canvas_skew

    */

    void skew(SkScalar sx, SkScalar sy);

    /** Replaces SkMatrix with matrix premultiplied with existing SkMatrix.

        This has the effect of transforming the drawn geometry by matrix, before

        transforming the result with existing SkMatrix.

        @param matrix  matrix to premultiply with existing SkMatrix

        example: https://fiddle.skia.org/c/@Canvas_concat

    */

    void concat(const SkMatrix& matrix);

    void concat(const SkM44&);

    /** Replaces SkMatrix with matrix.

        Unlike concat(), any prior matrix state is overwritten.

        @param matrix  matrix to copy, replacing existing SkMatrix

        example: https://fiddle.skia.org/c/@Canvas_setMatrix

    */

    void setMatrix(const SkM44& matrix);

    // DEPRECATED -- use SkM44 version

    void setMatrix(const SkMatrix& matrix);

    /** Sets SkMatrix to the identity matrix.

        Any prior matrix state is overwritten.

        example: https://fiddle.skia.org/c/@Canvas_resetMatrix

    */

    void resetMatrix();

    /** Replaces clip with the intersection or difference of clip and rect,

        with an aliased or anti-aliased clip edge. rect is transformed by SkMatrix

        before it is combined with clip.

        @param rect         SkRect to combine with clip

        @param op           SkClipOp to apply to clip

        @param doAntiAlias  true if clip is to be anti-aliased

        example: https://fiddle.skia.org/c/@Canvas_clipRect

    */

    void clipRect(const SkRect& rect, SkClipOp op, bool doAntiAlias);

    /** Replaces clip with the intersection or difference of clip and rect.

        Resulting clip is aliased; pixels are fully contained by the clip.

        rect is transformed by SkMatrix before it is combined with clip.

        @param rect  SkRect to combine with clip

        @param op    SkClipOp to apply to clip

    */

    void clipRect(const SkRect& rect, SkClipOp op) {

        this->clipRect(rect, op, false);

    }

    /** Replaces clip with the intersection of clip and rect.

        Resulting clip is aliased; pixels are fully contained by the clip.

        rect is transformed by SkMatrix

        before it is combined with clip.

        @param rect         SkRect to combine with clip

        @param doAntiAlias  true if clip is to be anti-aliased

    */

    void clipRect(const SkRect& rect, bool doAntiAlias = false) {

        this->clipRect(rect, SkClipOp::kIntersect, doAntiAlias);

    }

    void clipIRect(const SkIRect& irect, SkClipOp op = SkClipOp::kIntersect) {

        this->clipRect(SkRect::Make(irect), op, false);

    }

    /** Sets the maximum clip rectangle, which can be set by clipRect(), clipRRect() and

        clipPath() and intersect the current clip with the specified rect.

        The maximum clip affects only future clipping operations; it is not retroactive.

        The clip restriction is not recorded in pictures.

        Pass an empty rect to disable maximum clip.

        This private API is for use by Android framework only.

        DEPRECATED: Replace usage with SkAndroidFrameworkUtils::replaceClip()

        @param rect  maximum allowed clip in device coordinates

    */

    void androidFramework_setDeviceClipRestriction(const SkIRect& rect);

    /** Replaces clip with the intersection or difference of clip and rrect,

        with an aliased or anti-aliased clip edge.

        rrect is transformed by SkMatrix

        before it is combined with clip.

        @param rrect        SkRRect to combine with clip

        @param op           SkClipOp to apply to clip

        @param doAntiAlias  true if clip is to be anti-aliased

        example: https://fiddle.skia.org/c/@Canvas_clipRRect

    */

    void clipRRect(const SkRRect& rrect, SkClipOp op, bool doAntiAlias);

    /** Replaces clip with the intersection or difference of clip and rrect.

        Resulting clip is aliased; pixels are fully contained by the clip.

        rrect is transformed by SkMatrix before it is combined with clip.

        @param rrect  SkRRect to combine with clip

        @param op     SkClipOp to apply to clip

    */

    void clipRRect(const SkRRect& rrect, SkClipOp op) {

        this->clipRRect(rrect, op, false);

    }

    /** Replaces clip with the intersection of clip and rrect,

        with an aliased or anti-aliased clip edge.

        rrect is transformed by SkMatrix before it is combined with clip.

        @param rrect        SkRRect to combine with clip

        @param doAntiAlias  true if clip is to be anti-aliased

    */

    void clipRRect(const SkRRect& rrect, bool doAntiAlias = false) {

        this->clipRRect(rrect, SkClipOp::kIntersect, doAntiAlias);

    }

    /** Replaces clip with the intersection or difference of clip and path,

        with an aliased or anti-aliased clip edge. SkPath::FillType determines if path

        describes the area inside or outside its contours; and if path contour overlaps

        itself or another path contour, whether the overlaps form part of the area.

        path is transformed by SkMatrix before it is combined with clip.

        @param path         SkPath to combine with clip

        @param op           SkClipOp to apply to clip

        @param doAntiAlias  true if clip is to be anti-aliased

        example: https://fiddle.skia.org/c/@Canvas_clipPath

    */

    void clipPath(const SkPath& path, SkClipOp op, bool doAntiAlias);

    /** Replaces clip with the intersection or difference of clip and path.

        Resulting clip is aliased; pixels are fully contained by the clip.

        SkPath::FillType determines if path

        describes the area inside or outside its contours; and if path contour overlaps

        itself or another path contour, whether the overlaps form part of the area.

        path is transformed by SkMatrix

        before it is combined with clip.

        @param path  SkPath to combine with clip

        @param op    SkClipOp to apply to clip

    */

    void clipPath(const SkPath& path, SkClipOp op) {

        this->clipPath(path, op, false);

    }

    /** Replaces clip with the intersection of clip and path.

        Resulting clip is aliased; pixels are fully contained by the clip.

        SkPath::FillType determines if path

        describes the area inside or outside its contours; and if path contour overlaps

        itself or another path contour, whether the overlaps form part of the area.

        path is transformed by SkMatrix before it is combined with clip.

        @param path         SkPath to combine with clip

        @param doAntiAlias  true if clip is to be anti-aliased

    */

    void clipPath(const SkPath& path, bool doAntiAlias = false) {

        this->clipPath(path, SkClipOp::kIntersect, doAntiAlias);

    }

    void clipShader(sk_sp<SkShader>, SkClipOp = SkClipOp::kIntersect);

    /** Replaces clip with the intersection or difference of clip and SkRegion deviceRgn.

        Resulting clip is aliased; pixels are fully contained by the clip.

        deviceRgn is unaffected by SkMatrix.

        @param deviceRgn  SkRegion to combine with clip

        @param op         SkClipOp to apply to clip

        example: https://fiddle.skia.org/c/@Canvas_clipRegion

    */

    void clipRegion(const SkRegion& deviceRgn, SkClipOp op = SkClipOp::kIntersect);

    /** Returns true if SkRect rect, transformed by SkMatrix, can be quickly determined to be

        outside of clip. May return false even though rect is outside of clip.

        Use to check if an area to be drawn is clipped out, to skip subsequent draw calls.

        @param rect  SkRect to compare with clip

        @return      true if rect, transformed by SkMatrix, does not intersect clip

        example: https://fiddle.skia.org/c/@Canvas_quickReject

    */

    bool quickReject(const SkRect& rect) const;

    /** Returns true if path, transformed by SkMatrix, can be quickly determined to be

        outside of clip. May return false even though path is outside of clip.

        Use to check if an area to be drawn is clipped out, to skip subsequent draw calls.

        @param path  SkPath to compare with clip

        @return      true if path, transformed by SkMatrix, does not intersect clip

        example: https://fiddle.skia.org/c/@Canvas_quickReject_2

    */

    bool quickReject(const SkPath& path) const;

    /** Returns bounds of clip, transformed by inverse of SkMatrix. If clip is empty,

        return SkRect::MakeEmpty, where all SkRect sides equal zero.

        SkRect returned is outset by one to account for partial pixel coverage if clip

        is anti-aliased.