/* * 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 SkImage_DEFINED #define SkImage_DEFINED #include "SkFilterQuality.h" #include "SkImageInfo.h" #include "SkImageEncoder.h" #include "SkRefCnt.h" #include "SkScalar.h" #include "SkShader.h" #if defined(SK_BUILD_FOR_ANDROID) && __ANDROID_API__ >= 26 #include <android/hardware_buffer.h> #endif class SkData; class SkCanvas; class SkImageFilter; class SkImageGenerator; class SkPaint; class SkPicture; class SkString; class SkSurface; class GrBackendTexture; class GrContext; class GrContextThreadSafeProxy; class GrTexture; /** * SkImage is an abstraction for drawing a rectagle of pixels, though the * particular type of image could be actually storing its data on the GPU, or * as drawing commands (picture or PDF or otherwise), ready to be played back * into another canvas. * * The content of SkImage is always immutable, though the actual storage may * change, if for example that image can be re-created via encoded data or * other means. * * SkImage always has a non-zero dimensions. If there is a request to create a new image, either * directly or via SkSurface, and either of the requested dimensions are zero, then NULL will be * returned. */ class SK_API SkImage : public SkRefCnt { public: typedef SkImageInfo Info; typedef void* ReleaseContext; static sk_sp<SkImage> MakeRasterCopy(const SkPixmap& pixmap); static sk_sp<SkImage> MakeRasterData(const Info& info, sk_sp<SkData> pixels, size_t rowBytes); typedef void (*RasterReleaseProc)(const void* pixels, ReleaseContext); /** * Return a new Image referencing the specified pixels. These must remain valid and unchanged * until the specified release-proc is called, indicating that Skia no longer has a reference * to the pixels. * * Returns NULL if the requested pixmap info is unsupported. */ static sk_sp<SkImage> MakeFromRaster(const SkPixmap& pixmap, RasterReleaseProc rasterReleaseProc, ReleaseContext releaseContext); /** * Construct a new image from the specified bitmap. If the bitmap is marked immutable, and * its pixel memory is shareable, it may be shared instead of copied. */ static sk_sp<SkImage> MakeFromBitmap(const SkBitmap& bitmap); /** * Construct a new SkImage based on the given ImageGenerator. Returns NULL on error. * This function will always take ownership of the passed generator. * * If a subset is specified, it must be contained within the generator's bounds. */ static sk_sp<SkImage> MakeFromGenerator(std::unique_ptr<SkImageGenerator> imageGenerator, const SkIRect* subset = nullptr); /** * Construct a new SkImage based on the specified encoded data. Returns NULL on failure, * which can mean that the format of the encoded data was not recognized/supported. * * If a subset is specified, it must be contained within the encoded data's bounds. */ static sk_sp<SkImage> MakeFromEncoded(sk_sp<SkData> encoded, const SkIRect* subset = nullptr); typedef void (*TextureReleaseProc)(ReleaseContext releaseContext); /** * Create a new image from the specified descriptor. Note - the caller is responsible for * managing the lifetime of the underlying platform texture. * * Will return NULL if the specified backend texture is unsupported. * * DEPRECATED: This factory is deprecated and clients should use the factory below which takes * an SkColorType. */ static sk_sp<SkImage> MakeFromTexture(GrContext* context, const GrBackendTexture& backendTexture, GrSurfaceOrigin origin, SkAlphaType alphaType, sk_sp<SkColorSpace> colorSpace) { return MakeFromTexture(context, backendTexture, origin, alphaType, colorSpace, nullptr, nullptr); } /** * Create a new image from the GrBackendTexture. The underlying platform texture must stay * valid and unaltered until the specified release-proc is invoked, indicating that Skia * no longer is holding a reference to it. * * Will return NULL if the specified backend texture is unsupported. * * DEPRECATED: This factory is deprecated and clients should use the factory below which takes * an SkColorType. */ static sk_sp<SkImage> MakeFromTexture(GrContext* context, const GrBackendTexture& backendTexture, GrSurfaceOrigin origin, SkAlphaType alphaType, sk_sp<SkColorSpace> colorSpace, TextureReleaseProc textureReleaseProc, ReleaseContext releaseContext); /** * Create a new image from the specified descriptor. Note - the caller is responsible for * managing the lifetime of the underlying platform texture. * * The GrBackendTexture must have a valid backend format supplied (GrGLTextureInfo::fFormat, * GrVkImageInfo::fFormat, etc.) in it. The passed in SkColorType informs skia how it should * interpret the backend format supplied by the GrBackendTexture. If the format in the * GrBackendTexture is not compitable with the SkColorType, SkAlphaType, and SkColorSpace we * will return nullptr. */ static sk_sp<SkImage> MakeFromTexture(GrContext* context, const GrBackendTexture& backendTexture, GrSurfaceOrigin origin, SkColorType colorType, SkAlphaType alphaType, sk_sp<SkColorSpace> colorSpace) { return MakeFromTexture(context, backendTexture, origin, colorType, alphaType, colorSpace, nullptr, nullptr); } /** * Create a new image from the GrBackendTexture. The underlying platform texture must stay * valid and unaltered until the specified release-proc is invoked, indicating that Skia * no longer is holding a reference to it. * * The GrBackendTexture must have a valid backend format supplied (GrGLTextureInfo::fFormat, * GrVkImageInfo::fFormat, etc.) in it. The passed in SkColorType informs skia how it should * interpret the backend format supplied by the GrBackendTexture. If the format in the * GrBackendTexture is not compitable with the SkColorType, SkAlphaType, and SkColorSpace we * will return nullptr. */ static sk_sp<SkImage> MakeFromTexture(GrContext* context, const GrBackendTexture& backendTexture, GrSurfaceOrigin origin, SkColorType colorType, SkAlphaType alphaType, sk_sp<SkColorSpace> colorSpace, TextureReleaseProc textureReleaseProc, ReleaseContext releaseContext); /** * Decodes and uploads the encoded data to a GPU backed image using the supplied GrContext. * That image can be safely used by other GrContexts, across thread boundaries. The GrContext * used here, and the ones used to draw this image later must be in the same GL share group, * or use the same Vulkan VkDevice and VkQueue, or otherwise be able to share resources. * * When the image's ref count reaches zero, the original GrContext will destroy the texture, * asynchronously. * * The texture will be decoded and uploaded to be suitable for use with surfaces that have the * supplied destination color space. The color space of the image itself will be determined * from the encoded data. */ static sk_sp<SkImage> MakeCrossContextFromEncoded(GrContext* context, sk_sp<SkData> data, bool buildMips, SkColorSpace* dstColorSpace); /** * Uploads the pixmap to a GPU backed image using the supplied GrContext. * That image can be safely used by other GrContexts, across thread boundaries. The GrContext * used here, and the ones used to draw this image later must be in the same GL share group, * or use the same Vulkan VkDevice and VkQueue, or otherwise be able to share resources. * * When the image's ref count reaches zero, the original GrContext will destroy the texture, * asynchronously. * * The texture will be processed to be suitable for use with surfaces that have the * supplied destination color space. The color space of the image itself will be determined * from the pixmap. */ static sk_sp<SkImage> MakeCrossContextFromPixmap(GrContext* context, const SkPixmap& pixmap, bool buildMips, SkColorSpace* dstColorSpace); /** * Create a new image from the specified descriptor. Note - Skia will delete or recycle the * texture when the image is released. * * Will return NULL if the specified backend texture is unsupported. * * This is not supported if the GrContext was obtained from a deferred display list canvas * since if the SkImage never gets used and flushed to a real GrContext, we have no way to be * able to delete the underlying backend texture. * * DEPRECATED: This factory is deprecated and clients should use the factory below which takes * an SkColorType. */ static sk_sp<SkImage> MakeFromAdoptedTexture(GrContext* context, const GrBackendTexture& backendTexture, GrSurfaceOrigin surfaceOrigin, SkAlphaType alphaType = kPremul_SkAlphaType, sk_sp<SkColorSpace> colorSpace = nullptr); /** * Create a new image from the specified descriptor. Note - Skia will delete or recycle the * texture when the image is released. * * The GrBackendTexture must have a valid backend format supplied (GrGLTextureInfo::fFormat, * GrVkImageInfo::fFormat, etc.) in it. The passed in SkColorType informs skia how it should * interpret the backend format supplied by the GrBackendTexture. If the format in the * GrBackendTexture is not compitable with the SkColorType, SkAlphaType, and SkColorSpace we * will return nullptr. * * This is not supported if the GrContext was obtained from a deferred display list canvas * since if the SkImage never gets used and flushed to a real GrContext, we have no way to be * able to delete the underlying backend texture. */ static sk_sp<SkImage> MakeFromAdoptedTexture(GrContext* context, const GrBackendTexture& backendTexture, GrSurfaceOrigin surfaceOrigin, SkColorType colorType, SkAlphaType alphaType = kPremul_SkAlphaType, sk_sp<SkColorSpace> colorSpace = nullptr); /** * Create a new image by copying the pixels from the specified y, u, v textures. The data * from the textures is immediately ingested into the image and the textures can be modified or * deleted after the function returns. The image will have the dimensions of the y texture. */ static sk_sp<SkImage> MakeFromYUVTexturesCopy(GrContext* context, SkYUVColorSpace yuvColorSpace, const GrBackendObject yuvTextureHandles[3], const SkISize yuvSizes[3], GrSurfaceOrigin surfaceOrigin, sk_sp<SkColorSpace> colorSpace = nullptr); /** * Create a new image by copying the pixels from the specified y and uv textures. The data * from the textures is immediately ingested into the image and the textures can be modified or * deleted after the function returns. The image will have the dimensions of the y texture. */ static sk_sp<SkImage> MakeFromNV12TexturesCopy(GrContext* context, SkYUVColorSpace yuvColorSpace, const GrBackendObject nv12TextureHandles[2], const SkISize nv12Sizes[2], GrSurfaceOrigin surfaceOrigin, sk_sp<SkColorSpace> colorSpace = nullptr); /** * Create a new image by copying the pixels from the specified y, u, v textures. The data * from the textures is immediately ingested into the image and the textures can be modified or * deleted after the function returns. The image will have the dimensions of the y texture. */ static sk_sp<SkImage> MakeFromYUVTexturesCopy(GrContext* context, SkYUVColorSpace yuvColorSpace, const GrBackendTexture yuvTextureHandles[3], const SkISize yuvSizes[3], GrSurfaceOrigin surfaceOrigin, sk_sp<SkColorSpace> colorSpace = nullptr); /** * Create a new image by copying the pixels from the specified y and uv textures. The data * from the textures is immediately ingested into the image and the textures can be modified or * deleted after the function returns. The image will have the dimensions of the y texture. */ static sk_sp<SkImage> MakeFromNV12TexturesCopy(GrContext* context, SkYUVColorSpace yuvColorSpace, const GrBackendTexture nv12TextureHandles[2], const SkISize nv12Sizes[2], GrSurfaceOrigin surfaceOrigin, sk_sp<SkColorSpace> colorSpace = nullptr); enum class BitDepth { kU8, kF16, }; /** * Create a new image from the specified picture. * On creation of the SkImage, snap the SkPicture to a particular BitDepth and SkColorSpace. */ static sk_sp<SkImage> MakeFromPicture(sk_sp<SkPicture> picture, const SkISize& dimensions, const SkMatrix* matrix, const SkPaint* paint, BitDepth bitDepth, sk_sp<SkColorSpace> colorSpace); #if defined(SK_BUILD_FOR_ANDROID) && __ANDROID_API__ >= 26 /** * Create a new image from the an Android hardware buffer. * The new image takes a reference on the buffer. */ static sk_sp<SkImage> MakeFromAHardwareBuffer(AHardwareBuffer* hardwareBuffer, SkAlphaType alphaType = kPremul_SkAlphaType, sk_sp<SkColorSpace> colorSpace = nullptr); #endif /////////////////////////////////////////////////////////////////////////////////////////////// int width() const { return fWidth; } int height() const { return fHeight; } SkISize dimensions() const { return SkISize::Make(fWidth, fHeight); } SkIRect bounds() const { return SkIRect::MakeWH(fWidth, fHeight); } uint32_t uniqueID() const { return fUniqueID; } SkAlphaType alphaType() const; /** * Returns the color space of the SkImage. * * This is the color space that was supplied on creation of the SkImage or a color * space that was parsed from encoded data. This color space is not guaranteed to be * renderable. Can return nullptr if the SkImage was created without a color space. */ SkColorSpace* colorSpace() const; sk_sp<SkColorSpace> refColorSpace() const; /** * Returns true fi the image will be drawn as a mask, with no intrinsic color of its own. */ bool isAlphaOnly() const; bool isOpaque() const { return SkAlphaTypeIsOpaque(this->alphaType()); } sk_sp<SkShader> makeShader(SkShader::TileMode tileMode1, SkShader::TileMode tileMode2, const SkMatrix* localMatrix = nullptr) const; /** * Helper version of makeShader() that specifies Clamp tilemode. */ sk_sp<SkShader> makeShader(const SkMatrix* localMatrix = nullptr) const { return this->makeShader(SkShader::kClamp_TileMode, SkShader::kClamp_TileMode, localMatrix); } /** * If the image has direct access to its pixels (i.e. they are in local RAM) * return true, and if not null, return in the pixmap parameter the info about the * images pixels. * * On failure, return false and ignore the pixmap parameter. */ bool peekPixels(SkPixmap* pixmap) const; // DEPRECATED - currently used by Canvas2DLayerBridge in Chromium. GrTexture* getTexture() const; /** * Returns true if the image is texture backed. */ bool isTextureBacked() const; /** * Returns true if the image is able to be drawn to a particular type of device. If context * is nullptr, tests for drawability to CPU devices. Otherwise, tests for drawability to a GPU * device backed by context. * * Texture-backed images may become invalid if their underlying GrContext is abandoned. Some * generator-backed images may be invalid for CPU and/or GPU. */ bool isValid(GrContext* context) const; /** * Retrieves the backend API handle of the texture. If flushPendingGrContextIO then the * GrContext will issue to the backend API any deferred IO operations on the texture before * returning. * If 'origin' is supplied it will be filled in with the origin of the content drawn * into the image. */ GrBackendObject getTextureHandle(bool flushPendingGrContextIO, GrSurfaceOrigin* origin = nullptr) const; /** * Hints to image calls where the system might cache computed intermediates (e.g. the results * of decoding or a read-back from the GPU. Passing kAllow signals that the system's default * behavior is fine. Passing kDisallow signals that caching should be avoided. */ enum CachingHint { kAllow_CachingHint, kDisallow_CachingHint, }; /** * Copy the pixels from the image into the specified buffer (pixels + rowBytes), * converting them into the requested format (dstInfo). The image pixels are read * starting at the specified (srcX,srcY) location. * * The specified ImageInfo and (srcX,srcY) offset specifies a source rectangle * * srcR.setXYWH(srcX, srcY, dstInfo.width(), dstInfo.height()); * * srcR is intersected with the bounds of the image. If this intersection is not empty, * then we have two sets of pixels (of equal size). Replace the dst pixels with the * corresponding src pixels, performing any colortype/alphatype transformations needed * (in the case where the src and dst have different colortypes or alphatypes). * * This call can fail, returning false, for several reasons: * - If srcR does not intersect the image bounds. * - If the requested colortype/alphatype cannot be converted from the image's types. */ bool readPixels(const SkImageInfo& dstInfo, void* dstPixels, size_t dstRowBytes, int srcX, int srcY, CachingHint cachingHint = kAllow_CachingHint) const; bool readPixels(const SkPixmap& dst, int srcX, int srcY, CachingHint cachingHint = kAllow_CachingHint) const; /** * Copy the pixels from this image into the dst pixmap, converting as needed into dst's * colortype/alphatype. If the conversion cannot be performed, false is returned. * * If dst's dimensions differ from the src dimension, the image will be scaled, applying the * specified filter-quality. */ bool scalePixels(const SkPixmap& dst, SkFilterQuality filterQuality, CachingHint cachingHint = kAllow_CachingHint) const; /** * Encode the image's pixels and return the result as SkData. This will ignore any possible * existing encoded data (see refEncodedData()), and will always attempt to encode the * image using the specified encoded image format. * * If the image type cannot be encoded, or the requested encoder format is * not supported, this will return nullptr. */ sk_sp<SkData> encodeToData(SkEncodedImageFormat encodedImageFormat, int quality) const; /** * Encode the image and return the result as SkData. This will attempt to reuse existing * encoded data (as returned by refEncodedData). If there is no eisting data, the image * will be encoded using PNG. On an error, this returns nullptr. */ sk_sp<SkData> encodeToData() const; /** * If the image already has its contents in encoded form (e.g. PNG or JPEG), return that * as SkData. If the image does not already has its contents in encoded form, return NULL. * * Note: to force the image to return its contents as encoded data, use encodeToData(...). */ sk_sp<SkData> refEncodedData() const; const char* toString(SkString* string) const; /** * Return a new image that is a subset of this image. The underlying implementation may * share the pixels, or it may make a copy. * * If subset does not intersect the bounds of this image, or the copy/share cannot be made, * NULL will be returned. */ sk_sp<SkImage> makeSubset(const SkIRect& subset) const; /** * Ensures that an image is backed by a texture (when GrContext is non-null), suitable for use * with surfaces that have the supplied destination color space. If no transformation is * required, the returned image may be the same as this image. If this image is from a * different GrContext, this will fail. */ sk_sp<SkImage> makeTextureImage(GrContext* context, SkColorSpace* dstColorSpace) const; /** * If the image is texture-backed this will make a raster copy of it (or nullptr if reading back * the pixels fails). Otherwise, it returns the original image. */ sk_sp<SkImage> makeNonTextureImage() const; /** * If this image is already backed by raster (i.e. peekPixels would succeed), then this just * returns itself. If not, this attempts to create a raster version of this image and returns * that, or nullptr if that fails. */ sk_sp<SkImage> makeRasterImage() const; /** * Apply a given image filter to this image, and return the filtered result. * * The subset represents the active portion of this image. The return value is similarly an * SkImage, with an active subset (outSubset). This is usually used with texture-backed * images, where the texture may be approx-match and thus larger than the required size. * * clipBounds constrains the device-space extent of the image which may be produced to the * given rect. * * offset is the amount to translate the resulting image relative to the src when it is drawn. * This is an out-param. * * If the result image cannot be created, or the result would be transparent black, null * is returned, in which case the offset and outSubset parameters should be ignored by the * caller. */ sk_sp<SkImage> makeWithFilter(const SkImageFilter* filter, const SkIRect& subset, const SkIRect& clipBounds, SkIRect* outSubset, SkIPoint* offset) const; /** Drawing params for which a deferred texture image data should be optimized. */ struct DeferredTextureImageUsageParams { DeferredTextureImageUsageParams(const SkMatrix matrix, const SkFilterQuality quality, int preScaleMipLevel) : fMatrix(matrix), fQuality(quality), fPreScaleMipLevel(preScaleMipLevel) {} SkMatrix fMatrix; SkFilterQuality fQuality; int fPreScaleMipLevel; }; /** * This method allows clients to capture the data necessary to turn a SkImage into a texture- * backed image. If the original image is codec-backed this will decode into a format optimized * for the context represented by the proxy. This method is thread safe with respect to the * GrContext whence the proxy came. Clients allocate and manage the storage of the deferred * texture data and control its lifetime. No cleanup is required, thus it is safe to simply free * the memory out from under the data. * * The same method is used both for getting the size necessary for pre-uploaded texture data * and for retrieving the data. The params array represents the set of draws over which to * optimize the pre-upload data. * * When called with a null buffer this returns the size that the client must allocate in order * to create deferred texture data for this image (or zero if this is an inappropriate * candidate). The buffer allocated by the client should be 8 byte aligned. * * When buffer is not null this fills in the deferred texture data for this image in the * provided buffer (assuming this is an appropriate candidate image and the buffer is * appropriately aligned). Upon success the size written is returned, otherwise 0. * * dstColorSpace is the color space of the surface where this texture will ultimately be used. * If the method determines that mip-maps are needed, this helps determine the correct strategy * for building them (gamma-correct or not). * * dstColorType is the color type of the surface where this texture will ultimately be used. * This determines the format with which the image will be uploaded to the GPU. If dstColorType * does not support color spaces (low bit depth types such as ARGB_4444), then dstColorSpace * must be null. */ size_t getDeferredTextureImageData(const GrContextThreadSafeProxy& contextThreadSafeProxy, const DeferredTextureImageUsageParams deferredTextureImageUsageParams[], int paramCnt, void* buffer, SkColorSpace* dstColorSpace = nullptr, SkColorType dstColorType = kN32_SkColorType) const; /** * Returns a texture-backed image from data produced in SkImage::getDeferredTextureImageData. * The context must be the context that provided the proxy passed to * getDeferredTextureImageData. */ static sk_sp<SkImage> MakeFromDeferredTextureImageData(GrContext* context, const void* data, SkBudgeted budgeted); typedef std::function<void(GrBackendTexture)> BackendTextureReleaseProc; /** * Creates a GrBackendTexture from the provided SkImage. Returns true on success. The * GrBackendTexture and BackendTextureReleaseProc are populated on success. It is the callers * responsibility to call the BackendTextureReleaseProc once they have deleted the texture. * * Note that the BackendTextureReleaseProc allows Skia to clean up auxiliary data related * to the GrBackendTexture, and is not a substitute for the client deleting the GrBackendTexture * themselves. * * Note that if the SkImage is both texture backed and unowned (the only reference is * std::moved into this function), Skia can return the texture directly, avoiding any * conversions or copies. * * If the SkImage is not texture backed, this function will generate a texture with the image's * contents and return that. */ static bool MakeBackendTextureFromSkImage(GrContext* context, sk_sp<SkImage> image, GrBackendTexture* backendTexture, BackendTextureReleaseProc* backendTextureReleaseProc); // Helper functions to convert to SkBitmap enum LegacyBitmapMode { kRO_LegacyBitmapMode, kRW_LegacyBitmapMode, }; /** * Attempt to create a bitmap with the same pixels as the image. The result will always be * a raster-backed bitmap (texture-backed bitmaps are DEPRECATED, and not supported here). * * If the mode is kRO (read-only), the resulting bitmap will be marked as immutable. * * On succcess, returns true. On failure, returns false and the bitmap parameter will be reset * to empty. */ bool asLegacyBitmap(SkBitmap* bitmap, LegacyBitmapMode legacyBitmapMode) const; /** * Returns true if the image is backed by an image-generator or other src that creates * (and caches) its pixels / texture on-demand. */ bool isLazyGenerated() const; /** * If |target| is supported, returns an SkImage in the |target| color space. * Otherwise, returns nullptr. * * This will leave the image as is if it already in the |target| color space. * Otherwise, it will convert the pixels from the src color space to the |target| * color space. If this->colorSpace() is nullptr, the src color space will be * treated as sRGB. * * If |premulBehavior| is kIgnore, any premultiplication or unpremultiplication will * be performed in the gamma encoded space. If it is kRespect, premultiplication is * assumed to be linear. */ sk_sp<SkImage> makeColorSpace(sk_sp<SkColorSpace> target, SkTransferFunctionBehavior premulBehavior) const; private: SkImage(int width, int height, uint32_t uniqueID); friend class SkImage_Base; static sk_sp<SkImage> MakeTextureFromMipMap(GrContext*, const SkImageInfo&, const GrMipLevel texels[], int mipLevelCount, SkBudgeted, SkDestinationSurfaceColorMode); const int fWidth; const int fHeight; const uint32_t fUniqueID; typedef SkRefCnt INHERITED; }; #endif