123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940 |
- /*
- * Copyright 2012 Google Inc.
- *
- * Use of this source code is governed by a BSD-style license that can be
- * found in the LICENSE file.
- */
- #ifndef SkSurface_DEFINED
- #define SkSurface_DEFINED
- #include "include/core/SkImage.h"
- #include "include/core/SkRefCnt.h"
- #include "include/core/SkSurfaceProps.h"
- #include "include/gpu/GrTypes.h"
- #if defined(SK_BUILD_FOR_ANDROID) && __ANDROID_API__ >= 26
- #include <android/hardware_buffer.h>
- #endif
- class SkCanvas;
- class SkDeferredDisplayList;
- class SkPaint;
- class SkSurfaceCharacterization;
- class GrBackendRenderTarget;
- class GrBackendSemaphore;
- class GrBackendTexture;
- class GrContext;
- class GrRecordingContext;
- class GrRenderTarget;
- /** \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, 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 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);
- /** 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 not zero, subsequent images returned by makeImageSnapshot()
- have the same rowBytes.
- @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;
- /** User function called when supplied render target may be deleted. */
- typedef void (*RenderTargetReleaseProc)(ReleaseContext releaseContext);
- /** User function called when supplied texture may be deleted. */
- typedef void (*TextureReleaseProc)(ReleaseContext releaseContext);
- /** 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.
- 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.
- If SK_SUPPORT_GPU is defined as zero, has no effect and returns nullptr.
- @param context GPU context
- @param backendTexture texture residing on GPU
- @param origin one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin
- @param sampleCnt samples per pixel, or 0 to disable full scene anti-aliasing
- @param colorType one of:
- kUnknown_SkColorType, kAlpha_8_SkColorType, kRGB_565_SkColorType,
- kARGB_4444_SkColorType, kRGBA_8888_SkColorType,
- kRGB_888x_SkColorType, kBGRA_8888_SkColorType,
- kRGBA_1010102_SkColorType, kRGB_101010x_SkColorType,
- kGray_8_SkColorType, kRGBA_F16_SkColorType
- @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(GrContext* 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.
- If SK_SUPPORT_GPU is defined as zero, has no effect and returns nullptr.
- @param context GPU context
- @param backendRenderTarget GPU intermediate memory buffer
- @param origin one of:
- kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin
- @param colorType one of:
- kUnknown_SkColorType, kAlpha_8_SkColorType,
- kRGB_565_SkColorType,
- kARGB_4444_SkColorType, kRGBA_8888_SkColorType,
- kRGB_888x_SkColorType, kBGRA_8888_SkColorType,
- kRGBA_1010102_SkColorType, kRGB_101010x_SkColorType,
- kGray_8_SkColorType, kRGBA_F16_SkColorType
- @param colorSpace range of colors
- @param surfaceProps LCD striping orientation and setting for device independent
- fonts; may be nullptr
- @param releaseProc 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> MakeFromBackendRenderTarget(GrContext* context,
- const GrBackendRenderTarget& backendRenderTarget,
- GrSurfaceOrigin origin,
- SkColorType colorType,
- sk_sp<SkColorSpace> colorSpace,
- const SkSurfaceProps* surfaceProps,
- RenderTargetReleaseProc releaseProc = nullptr,
- ReleaseContext releaseContext = nullptr);
- /** Wraps a GPU-backed texture into SkSurface. Caller must ensure backendTexture is
- valid for the lifetime of returned SkSurface. If sampleCnt greater than zero,
- creates an intermediate MSAA SkSurface which is used for drawing backendTexture.
- 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.
- Returned SkSurface is available only for drawing into, and cannot generate an
- SkImage.
- If SK_SUPPORT_GPU is defined as zero, has no effect and returns nullptr.
- @param context GPU context
- @param backendTexture texture residing on GPU
- @param origin one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin
- @param sampleCnt samples per pixel, or 0 to disable full scene anti-aliasing
- @param colorType one of:
- kUnknown_SkColorType, kAlpha_8_SkColorType, kRGB_565_SkColorType,
- kARGB_4444_SkColorType, kRGBA_8888_SkColorType,
- kRGB_888x_SkColorType, kBGRA_8888_SkColorType,
- kRGBA_1010102_SkColorType, kRGB_101010x_SkColorType,
- kGray_8_SkColorType, kRGBA_F16_SkColorType
- @param colorSpace range of colors; 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> MakeFromBackendTextureAsRenderTarget(GrContext* context,
- const GrBackendTexture& backendTexture,
- GrSurfaceOrigin origin,
- int sampleCnt,
- SkColorType colorType,
- sk_sp<SkColorSpace> colorSpace,
- const SkSurfaceProps* surfaceProps);
- #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 workds 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 origin one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin
- @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> MakeFromAHardwareBuffer(GrContext* context,
- AHardwareBuffer* hardwareBuffer,
- GrSurfaceOrigin origin,
- sk_sp<SkColorSpace> colorSpace,
- const SkSurfaceProps* surfaceProps);
- #endif
- /** 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 SK_SUPPORT_GPU is defined as zero, has no effect and returns nullptr.
- @param context GPU context
- @param budgeted one of: SkBudgeted::kNo, SkBudgeted::kYes
- @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 surfaceOrigin one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin
- @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(GrContext* context, SkBudgeted 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 budgeted one of: SkBudgeted::kNo, SkBudgeted::kYes
- @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(GrContext* context, SkBudgeted budgeted,
- const SkImageInfo& imageInfo, int sampleCount,
- const SkSurfaceProps* surfaceProps) {
- return MakeRenderTarget(context, budgeted, imageInfo, sampleCount,
- kBottomLeft_GrSurfaceOrigin, surfaceProps);
- }
- /** 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.
- SkSurface bottom-left corner is pinned to the origin.
- @param context GPU context
- @param budgeted one of: SkBudgeted::kNo, SkBudgeted::kYes
- @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(GrContext* context, SkBudgeted budgeted,
- const SkImageInfo& imageInfo) {
- if (!imageInfo.width() || !imageInfo.height()) {
- return nullptr;
- }
- return MakeRenderTarget(context, budgeted, imageInfo, 0, kBottomLeft_GrSurfaceOrigin,
- nullptr);
- }
- /** Returns SkSurface on GPU indicated by context that is compatible with the provided
- characterization. budgeted selects whether allocation for pixels is tracked by context.
- @param context GPU context
- @param characterization description of the desired SkSurface
- @param budgeted one of: SkBudgeted::kNo, SkBudgeted::kYes
- @return SkSurface if all parameters are valid; otherwise, nullptr
- */
- static sk_sp<SkSurface> MakeRenderTarget(GrRecordingContext* context,
- const SkSurfaceCharacterization& characterization,
- SkBudgeted budgeted);
- /** Wraps a backend texture in an SkSurface - setting up the surface to match the provided
- characterization. The caller must ensure the texture is valid for the lifetime of
- returned SkSurface.
- If the backend texture and surface characterization are incompatible then null will
- be returned.
- Usually, the GrContext::createBackendTexture variant that takes a surface characterization
- should be used to create the backend texture. If not,
- SkSurfaceCharacterization::isCompatible can be used to determine if a given backend texture
- is compatible with a specific surface characterization.
- @param context GPU context
- @param characterization characterization of the desired surface
- @param backendTexture texture residing on GPU
- @param textureReleaseProc function called when texture can be released
- @param releaseContext state passed to textureReleaseProc
- @return SkSurface if all parameters are compatible; otherwise, nullptr
- */
- static sk_sp<SkSurface> MakeFromBackendTexture(GrContext* context,
- const SkSurfaceCharacterization& characterzation,
- const GrBackendTexture& backendTexture,
- TextureReleaseProc textureReleaseProc = nullptr,
- ReleaseContext releaseContext = nullptr);
- /** 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.
- @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
- */
- static sk_sp<SkSurface> MakeNull(int width, int height);
- /** Returns pixel count in each row; may be zero or greater.
- @return number of pixel columns
- */
- int width() const { return fWidth; }
- /** Returns pixel row count; may be zero or greater.
- @return number of pixel rows
- */
- int height() const { return fHeight; }
- /** Returns an ImageInfo describing the surface.
- */
- SkImageInfo imageInfo();
- /** Returns unique value identifying the content of SkSurface. Returned value changes
- each time the content changes. Content is changed by drawing, or by calling
- notifyContentWillChange().
- @return unique content identifier
- */
- uint32_t generationID();
- /** \enum SkSurface::ContentChangeMode
- ContentChangeMode members are parameters to notifyContentWillChange().
- */
- enum ContentChangeMode {
- kDiscard_ContentChangeMode, //!< discards surface on change
- kRetain_ContentChangeMode, //!< preserves surface on change
- };
- /** Notifies that SkSurface contents will be changed by code outside of Skia.
- Subsequent calls to generationID() return a different value.
- TODO: Can kRetain_ContentChangeMode be deprecated?
- @param mode one of: kDiscard_ContentChangeMode, kRetain_ContentChangeMode
- */
- void notifyContentWillChange(ContentChangeMode mode);
- 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;
- /** 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.
- @param backendHandleAccess one of: kFlushRead_BackendHandleAccess,
- kFlushWrite_BackendHandleAccess,
- kDiscardWrite_BackendHandleAccess
- @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.
- The returned GrBackendRenderTarget should be discarded if the SkSurface is drawn to
- or deleted.
- @param backendHandleAccess one of: kFlushRead_BackendHandleAccess,
- kFlushWrite_BackendHandleAccess,
- kDiscardWrite_BackendHandleAccess
- @return GPU render target reference; invalid on failure
- */
- GrBackendRenderTarget getBackendRenderTarget(BackendHandleAccess backendHandleAccess);
- /** 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
- copied into the new texture. SkCanvas state is preserved. The original sample count is
- used. The GrBackendFormat and dimensions of replacement texture must match that of
- the original.
- @param backendTexture the new backing texture for the surface.
- @param origin one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin
- @param textureReleaseProc function called when texture can be released
- @param releaseContext state passed to textureReleaseProc
- */
- bool replaceBackendTexture(const GrBackendTexture& backendTexture,
- GrSurfaceOrigin origin,
- TextureReleaseProc textureReleaseProc = nullptr,
- ReleaseContext releaseContext = nullptr);
- /** 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
- is deleted.
- @return drawing SkCanvas for SkSurface
- */
- SkCanvas* getCanvas();
- /** Returns a compatible SkSurface, or nullptr. Returned SkSurface contains
- the same raster, GPU, or null properties as the original. Returned SkSurface
- does not share the same pixels.
- Returns nullptr if imageInfo width or height are zero, or if imageInfo
- is incompatible with SkSurface.
- @param imageInfo width, height, SkColorType, SkAlphaType, SkColorSpace,
- of SkSurface; width and height must be greater than zero
- @return compatible SkSurface or nullptr
- */
- sk_sp<SkSurface> makeSurface(const SkImageInfo& imageInfo);
- /** Calls makeSurface(ImageInfo) with the same ImageInfo as this surface, but with the
- * specified width and height.
- */
- sk_sp<SkSurface> makeSurface(int width, int height);
- /** Returns SkImage capturing SkSurface contents. Subsequent drawing to SkSurface contents
- are not captured. SkImage allocation is accounted for if SkSurface was created with
- SkBudgeted::kYes.
- @return SkImage initialized with SkSurface contents
- */
- sk_sp<SkImage> makeImageSnapshot();
- /**
- * Like the no-parameter version, this returns an image of the current surface contents.
- * This variant takes a rectangle specifying the subset of the surface that is of interest.
- * These bounds will be sanitized before being used.
- * - If bounds extends beyond the surface, it will be trimmed to just the intersection of
- * it and the surface.
- * - If bounds does not intersect the surface, then this returns nullptr.
- * - If bounds == the surface, then this is the same as calling the no-parameter variant.
- */
- sk_sp<SkImage> makeImageSnapshot(const SkIRect& bounds);
- /** Draws SkSurface contents to canvas, with its top-left corner at (x, y).
- If SkPaint paint is not nullptr, apply SkColorFilter, alpha, SkImageFilter,
- SkBlendMode, and SkDrawLooper.
- @param canvas SkCanvas drawn into
- @param x horizontal offset in SkCanvas
- @param y vertical offset in SkCanvas
- @param paint SkPaint containing SkBlendMode, SkColorFilter, SkImageFilter,
- and so on; or nullptr
- */
- void draw(SkCanvas* canvas, SkScalar x, SkScalar y, const SkPaint* paint);
- /** Copies SkSurface pixel address, row bytes, and SkImageInfo to SkPixmap, if address
- is available, and returns true. If pixel address is not available, return
- false and leave SkPixmap unchanged.
- pixmap contents become invalid on any future change to SkSurface.
- @param pixmap storage for pixel state if pixels are readable; otherwise, ignored
- @return true if SkSurface has direct access to pixels
- */
- bool peekPixels(SkPixmap* pixmap);
- /** Copies SkRect of pixels to dst.
- Source SkRect corners are (srcX, srcY) and SkSurface (width(), height()).
- Destination SkRect corners are (0, 0) and (dst.width(), dst.height()).
- Copies each readable pixel intersecting both rectangles, without scaling,
- converting to dst.colorType() and dst.alphaType() if required.
- Pixels are readable when SkSurface is raster, or backed by a GPU.
- 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. dst 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.
- - SkPixmap pixels could not be allocated.
- - dst.rowBytes() is too small to contain one row of pixels.
- @param dst storage for pixels copied from SkSurface
- @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 SkPixmap& dst, int srcX, int srcY);
- /** Copies SkRect of pixels from SkCanvas into dstPixels.
- Source SkRect corners are (srcX, srcY) and SkSurface (width(), 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 SkSurface is raster, or backed by a GPU.
- 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.
- - SkSurface pixels could not be converted to dstInfo.colorType() or dstInfo.alphaType().
- - 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 SkSurface into bitmap.
- Source SkRect corners are (srcX, srcY) and SkSurface (width(), 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 SkSurface is raster, or backed by a GPU.
- 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. dst 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.
- - SkSurface pixels could not be converted to dst.colorType() or dst.alphaType().
- - dst pixels could not be allocated.
- - dst.rowBytes() is too small to contain one row of pixels.
- @param dst storage for pixels copied from SkSurface
- @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 SkBitmap& dst, int srcX, int srcY);
- /** Makes pixel data available to caller, possibly asynchronously. Can perform rescaling.
- Currently asynchronous reads are only supported on the GPU backend and only when the
- underlying 3D API supports transfer buffers and CPU/GPU synchronization primitives. In all
- other cases this operates synchronously.
- Data is read from the source rectangle, is optionally converted to a linear gamma, is
- rescaled to the size indicated by 'info', is then converted to the color space, color type,
- and alpha type of 'info'.
- When the pixel data is ready the caller's ReadPixelsCallback is called with a pointer to
- the data in the requested color type, alpha type, and color space. The data pointer is
- only valid for the duration of the callback.
- Upon failure the the callback is called with nullptr as the data pointer.
- If the src rectangle is not contained by the bounds of the surface then failure occurs.
- Failure is indicated by calling callback with a nullptr for 'data'.
- @param info info of the requested pixels
- @param srcRect subrectangle of surface to read
- @param rescaleGamma controls whether rescaling is done in the surface's gamma or whether
- the source data is transformed to a linear gamma before rescaling.
- @param rescaleQuality controls the quality (and cost) of the rescaling
- @param callback function to call with result of the read
- @param context passed to callback
- */
- using ReadPixelsContext = void*;
- using ReadPixelsCallback = void(ReadPixelsContext, const void* data, size_t rowBytes);
- enum RescaleGamma : bool { kSrc, kLinear };
- void asyncRescaleAndReadPixels(const SkImageInfo& info, const SkIRect& srcRect,
- RescaleGamma rescaleGamma, SkFilterQuality rescaleQuality,
- ReadPixelsCallback callback, ReadPixelsContext context);
- /**
- Similar to asyncRescaleAndReadPixels but performs an additional conversion to YUV. The
- RGB->YUV conversion is controlled by 'yuvColorSpace'. The YUV data is returned as three
- planes ordered y, u, v. The u and v planes are half the width and height of the resized
- rectangle. Currently this fails if dstW or dstH are not even.
- On failure the callback is called with a null data pointer array. Fails if srcRect is not
- contained in the surface bounds.
- @param yuvColorSpace The transformation from RGB to YUV. Applied to the resized image
- after it is converted to dstColorSpace.
- @param dstColorSpace The color space to convert the resized image to, after rescaling.
- @param srcRect The portion of the surface to rescale and convert to YUV planes.
- @param dstW The width to rescale srcRect to
- @param dstH The height to rescale srcRect to
- @param rescaleGamma controls whether rescaling is done in the surface's gamma or whether
- the source data is transformed to a linear gamma before rescaling.
- @param rescaleQuality controls the quality (and cost) of the rescaling
- @param callback function to call with the planar read result
- @param context passed to callback
- */
- using ReadPixelsCallbackYUV420 = void(ReadPixelsContext, const void* data[3],
- size_t rowBytes[3]);
- void asyncRescaleAndReadPixelsYUV420(SkYUVColorSpace yuvColorSpace,
- sk_sp<SkColorSpace> dstColorSpace, const SkIRect& srcRect,
- int dstW, int dstH, RescaleGamma rescaleGamma,
- SkFilterQuality rescaleQuality,
- ReadPixelsCallbackYUV420 callback, ReadPixelsContext);
- /** Copies SkRect of pixels from the src SkPixmap to the SkSurface.
- Source SkRect corners are (0, 0) and (src.width(), src.height()).
- Destination SkRect corners are (dstX, dstY) and
- (dstX + Surface width(), dstY + Surface height()).
- Copies each readable pixel intersecting both rectangles, without scaling,
- converting to SkSurface colorType() and SkSurface alphaType() if required.
- @param src storage for pixels to copy to SkSurface
- @param dstX x-axis position relative to SkSurface to begin copy; may be negative
- @param dstY y-axis position relative to SkSurface to begin copy; may be negative
- */
- void writePixels(const SkPixmap& src, int dstX, int dstY);
- /** Copies SkRect of pixels from the src SkBitmap to the SkSurface.
- Source SkRect corners are (0, 0) and (src.width(), src.height()).
- Destination SkRect corners are (dstX, dstY) and
- (dstX + Surface width(), dstY + Surface height()).
- Copies each readable pixel intersecting both rectangles, without scaling,
- converting to SkSurface colorType() and SkSurface alphaType() if required.
- @param src storage for pixels to copy to SkSurface
- @param dstX x-axis position relative to SkSurface to begin copy; may be negative
- @param dstY y-axis position relative to SkSurface to begin copy; may be negative
- */
- void writePixels(const SkBitmap& src, int dstX, int dstY);
- /** Returns SkSurfaceProps for surface.
- @return LCD striping orientation and setting for device independent fonts
- */
- const SkSurfaceProps& props() const { return fProps; }
- /** Issues pending SkSurface commands to the GPU-backed API and resolves any SkSurface MSAA.
- Skia flushes as needed, so it is not necessary to call this if Skia manages
- drawing and object lifetime. Call when interleaving Skia calls with native
- GPU calls.
- */
- void flush();
- enum class BackendSurfaceAccess {
- kNoAccess, //!< back-end object will not be used by client
- kPresent, //!< back-end surface will be used for presenting to screen
- };
- /** Issues pending SkSurface commands to the GPU-backed API and resolves any SkSurface MSAA.
- 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 GrSemaphoresSubmitted::kNo is returned, the GPU back-end did not create or
- add any semaphores to signal on the GPU; the caller should not instruct the GPU
- to wait on any of the semaphores passed in the GrFlushInfo.
- 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
- @return one of: GrSemaphoresSubmitted::kYes, GrSemaphoresSubmitted::kNo
- */
- GrSemaphoresSubmitted flush(BackendSurfaceAccess access, const GrFlushInfo& info);
- /** Deprecated
- */
- GrSemaphoresSubmitted flush(BackendSurfaceAccess access, GrFlushFlags flags,
- int numSemaphores, GrBackendSemaphore signalSemaphores[],
- GrGpuFinishedProc finishedProc = nullptr,
- GrGpuFinishedContext finishedContext = nullptr);
- /** The below enum and flush call are deprecated
- */
- enum FlushFlags {
- kNone_FlushFlags = 0,
- // flush will wait till all submitted GPU work is finished before returning.
- kSyncCpu_FlushFlag = 0x1,
- };
- GrSemaphoresSubmitted flush(BackendSurfaceAccess access, FlushFlags flags,
- int numSemaphores, GrBackendSemaphore signalSemaphores[]);
- /** Deprecated.
- */
- GrSemaphoresSubmitted flushAndSignalSemaphores(int numSemaphores,
- GrBackendSemaphore signalSemaphores[]);
- /** 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. Skia will take ownership of the
- underlying semaphores and delete them once they have been signaled and waited on.
- If this call returns false, then the GPU back-end will not wait on any passed in semaphores,
- and the client will still own the semaphores.
- @param numSemaphores size of waitSemaphores array
- @param waitSemaphores array of semaphore containers
- @return true if GPU is waiting on semaphores
- */
- bool wait(int numSemaphores, const GrBackendSemaphore* waitSemaphores);
- /** Initializes SkSurfaceCharacterization 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
- for each tile.
- Return true if SkSurface supports characterization. raster surface returns false.
- @param characterization properties for parallel drawing
- @return true if supported
- */
- bool characterize(SkSurfaceCharacterization* characterization) const;
- /** Draws deferred display list created using SkDeferredDisplayListRecorder.
- Has no effect and returns false if SkSurfaceCharacterization stored in
- deferredDisplayList is not compatible with SkSurface.
- raster surface returns false.
- @param deferredDisplayList drawing commands
- @return false if deferredDisplayList is not compatible
- */
- bool draw(SkDeferredDisplayList* deferredDisplayList);
- protected:
- SkSurface(int width, int height, const SkSurfaceProps* surfaceProps);
- SkSurface(const SkImageInfo& imageInfo, const SkSurfaceProps* surfaceProps);
- // called by subclass if their contents have changed
- void dirtyGenerationID() {
- fGenerationID = 0;
- }
- private:
- const SkSurfaceProps fProps;
- const int fWidth;
- const int fHeight;
- uint32_t fGenerationID;
- typedef SkRefCnt INHERITED;
- };
- #endif
|