#Topic Image #Alias Image_Reference ## #Class SkImage Image describes a two dimensional array of pixels to draw. The pixels may be decoded in a Raster_Bitmap, encoded in a Picture or compressed data stream, or located in GPU memory as a GPU_Texture. Image cannot be modified after it is created. Image may allocate additional storage as needed; for instance, an encoded Image may decode when drawn. Image width and height are greater than zero. Creating an Image with zero width or height returns Image equal to nullptr. Image may be created from Bitmap, Pixmap, Surface, Picture, encoded streams, GPU_Texture, YUV_ColorSpace data, or hardware buffer. Encoded streams supported include BMP, GIF, HEIF, ICO, JPEG, PNG, WBMP, WebP. Supported encoding details vary with platform. #Subtopic Raster_Image #Alias Raster_Image ## #Line # pixels decoded in Raster_Bitmap ## Raster_Image pixels are decoded in a Raster_Bitmap. These pixels may be read directly and in most cases written to, although edited pixels may not be drawn if Image has been copied internally. ## #Subtopic Texture_Image #Line # pixels located on GPU ## Texture_Image are located on GPU and pixels are not accessible. Texture_Image are allocated optimally for best performance. Raster_Image may be drawn to GPU_Surface, but pixels are uploaded from CPU to GPU downgrading performance. ## #Subtopic Lazy_Image #Line # deferred pixel buffer ## Lazy_Image defer allocating buffer for Image pixels and decoding stream until Image is drawn. Lazy_Image caches result if possible to speed up repeated drawing. ## #Subtopic Overview #Populate ## #Subtopic Related_Function #Populate ## #Subtopic Constructor #Populate ## #Subtopic Member_Function #Populate ## # ------------------------------------------------------------------------------ #Method static sk_sp MakeRasterCopy(const SkPixmap& pixmap) #In Constructor #Line # creates Image from Pixmap and copied pixels ## Creates Image from Pixmap and copy of pixels. Since pixels are copied, Pixmap pixels may be modified or deleted without affecting Image. Image is returned if Pixmap is valid. Valid Pixmap parameters include: dimensions are greater than zero; each dimension fits in 29 bits; Color_Type and Alpha_Type are valid, and Color_Type is not kUnknown_SkColorType; row bytes are large enough to hold one row of pixels; pixel address is not nullptr. #Param pixmap Image_Info, pixel address, and row bytes ## #Return copy of Pixmap pixels, or nullptr ## #Example #Height 50 #Description Draw a five by five bitmap, and draw a copy in an Image. Editing the pixmap alters the bitmap draw, but does not alter the Image draw since the Image contains a copy of the pixels. ## uint8_t storage[][5] = {{ 0xCA, 0xDA, 0xCA, 0xC9, 0xA3 }, { 0xAC, 0xA8, 0x89, 0xA7, 0x87 }, { 0x9B, 0xB5, 0xE5, 0x95, 0x46 }, { 0x90, 0x81, 0xC5, 0x71, 0x33 }, { 0x75, 0x55, 0x44, 0x40, 0x30 }}; SkImageInfo imageInfo = SkImageInfo::Make(5, 5, kGray_8_SkColorType, kOpaque_SkAlphaType); SkPixmap pixmap(imageInfo, storage[0], sizeof(storage) / 5); SkBitmap bitmap; bitmap.installPixels(pixmap); sk_sp image = SkImage::MakeRasterCopy(pixmap); *pixmap.writable_addr8(2, 2) = 0x00; canvas->scale(10, 10); canvas->drawBitmap(bitmap, 0, 0); canvas->drawImage(image, 10, 0); ## #SeeAlso MakeRasterData MakeFromGenerator #Method ## # ------------------------------------------------------------------------------ #Method static sk_sp MakeRasterData(const SkImageInfo& info, sk_sp pixels, size_t rowBytes) #In Constructor #Line # creates Image from Image_Info and shared pixels ## Creates Image from Image_Info, sharing pixels. Image is returned if Image_Info is valid. Valid Image_Info parameters include: dimensions are greater than zero; each dimension fits in 29 bits; Color_Type and Alpha_Type are valid, and Color_Type is not kUnknown_SkColorType; rowBytes are large enough to hold one row of pixels; pixels is not nullptr, and contains enough data for Image. #Param info contains width, height, Alpha_Type, Color_Type, Color_Space ## #Param pixels address or pixel storage ## #Param rowBytes size of pixel row or larger ## #Return Image sharing pixels, or nullptr ## #Example #Image 3 size_t rowBytes = image->width() * SkColorTypeBytesPerPixel(kRGBA_8888_SkColorType); sk_sp data = SkData::MakeUninitialized(rowBytes * image->height()); SkImageInfo dstInfo = SkImageInfo::MakeN32(image->width(), image->height(), kPremul_SkAlphaType); image->readPixels(dstInfo, data->writable_data(), rowBytes, 0, 0, SkImage::kAllow_CachingHint); sk_sp raw = SkImage::MakeRasterData(dstInfo.makeColorType(kRGBA_8888_SkColorType), data, rowBytes); canvas->drawImage(image, 0, 0); canvas->drawImage(raw.get(), 128, 0); ## #SeeAlso MakeRasterCopy MakeFromGenerator #Method ## # ------------------------------------------------------------------------------ #Typedef void* ReleaseContext #Line # parameter type for MakeFromRaster ## #Code typedef void* ReleaseContext; ## Caller data passed to RasterReleaseProc; may be nullptr. #SeeAlso MakeFromRaster RasterReleaseProc ## #Typedef void (*RasterReleaseProc)(const void* pixels, ReleaseContext) #Line # parameter type for MakeFromRaster ## #Code typedef void (*RasterReleaseProc)(const void* pixels, ReleaseContext); ## Function called when Image no longer shares pixels. ReleaseContext is provided by caller when Image is created, and may be nullptr. #SeeAlso ReleaseContext MakeFromRaster ## #Method static sk_sp MakeFromRaster(const SkPixmap& pixmap, RasterReleaseProc rasterReleaseProc, ReleaseContext releaseContext) #In Constructor #Line # creates Image from Pixmap, with release ## Creates Image from pixmap, sharing Pixmap pixels. Pixels must remain valid and unchanged until rasterReleaseProc is called. rasterReleaseProc is passed releaseContext when Image is deleted or no longer refers to pixmap pixels. Pass nullptr for rasterReleaseProc to share Pixmap without requiring a callback when Image is released. Pass nullptr for releaseContext if rasterReleaseProc does not require state. Image is returned if pixmap is valid. Valid Pixmap parameters include: dimensions are greater than zero; each dimension fits in 29 bits; Color_Type and Alpha_Type are valid, and Color_Type is not kUnknown_SkColorType; row bytes are large enough to hold one row of pixels; pixel address is not nullptr. #Param pixmap Image_Info, pixel address, and row bytes ## #Param rasterReleaseProc function called when pixels can be released; or nullptr ## #Param releaseContext state passed to rasterReleaseProc; or nullptr ## #Return Image sharing pixmap ## #Example #Function static void releaseProc(const void* pixels, SkImage::ReleaseContext context) { int* countPtr = static_cast(context); *countPtr += 1; } ## void draw(SkCanvas* canvas) { SkColor color = 0; SkPixmap pixmap(SkImageInfo::MakeN32(1, 1, kPremul_SkAlphaType), &color, 4); int releaseCount = 0; sk_sp image(SkImage::MakeFromRaster(pixmap, releaseProc, &releaseCount)); SkDebugf("before reset: %d\n", releaseCount); image.reset(); SkDebugf("after reset: %d\n", releaseCount); } #StdOut before reset: 0 after reset: 1 ## ## #SeeAlso MakeRasterCopy MakeRasterData MakeFromGenerator RasterReleaseProc ReleaseContext #Method ## # ------------------------------------------------------------------------------ #Method static sk_sp MakeFromBitmap(const SkBitmap& bitmap) #In Constructor #Line # creates Image from Bitmap, sharing or copying pixels ## Creates Image from bitmap, sharing or copying bitmap pixels. If the bitmap is marked immutable, and its pixel memory is shareable, it may be shared instead of copied. Image is returned if bitmap is valid. Valid Bitmap parameters include: dimensions are greater than zero; each dimension fits in 29 bits; Color_Type and Alpha_Type are valid, and Color_Type is not kUnknown_SkColorType; row bytes are large enough to hold one row of pixels; pixel address is not nullptr. #Param bitmap Image_Info, row bytes, and pixels ## #Return created Image, or nullptr ## #Example #Description The first Bitmap is shared; writing to the pixel memory changes the first Image. The second Bitmap is marked immutable, and is copied; writing to the pixel memory does not alter the second Image. ## #Height 50 uint8_t storage[][5] = {{ 0xCA, 0xDA, 0xCA, 0xC9, 0xA3 }, { 0xAC, 0xA8, 0x89, 0xA7, 0x87 }, { 0x9B, 0xB5, 0xE5, 0x95, 0x46 }, { 0x90, 0x81, 0xC5, 0x71, 0x33 }, { 0x75, 0x55, 0x44, 0x40, 0x30 }}; SkImageInfo imageInfo = SkImageInfo::Make(5, 5, kGray_8_SkColorType, kOpaque_SkAlphaType); SkPixmap pixmap(imageInfo, storage[0], sizeof(storage) / 5); SkBitmap bitmap; bitmap.installPixels(pixmap); sk_sp image1 = SkImage::MakeFromBitmap(bitmap); bitmap.setImmutable(); sk_sp image2 = SkImage::MakeFromBitmap(bitmap); *pixmap.writable_addr8(2, 2) = 0x00; canvas->scale(10, 10); canvas->drawImage(image1, 0, 0); canvas->drawImage(image2, 10, 0); ## #SeeAlso MakeFromRaster MakeRasterCopy MakeFromGenerator MakeRasterData #Method ## # ------------------------------------------------------------------------------ #Method static sk_sp MakeFromGenerator(std::unique_ptr imageGenerator, const SkIRect* subset = nullptr) #In Constructor #Line # creates Image from a stream of data ## Creates Image from data returned by imageGenerator. Generated data is owned by Image and may not be shared or accessed. subset allows selecting a portion of the full image. Pass nullptr to select the entire image; otherwise, subset must be contained by image bounds. Image is returned if generator data is valid. Valid data parameters vary by type of data and platform. imageGenerator may wrap Picture data, codec data, or custom data. #Param imageGenerator stock or custom routines to retrieve Image ## #Param subset bounds of returned Image; may be nullptr ## #Return created Image, or nullptr ## #Example #Height 128 #Description The generator returning Picture cannot be shared; std::move transfers ownership to generated Image. ## SkPictureRecorder recorder; recorder.beginRecording(100, 100)->drawColor(SK_ColorRED); auto picture = recorder.finishRecordingAsPicture(); auto gen = SkImageGenerator::MakeFromPicture({100, 100}, picture, nullptr, nullptr, SkImage::BitDepth::kU8, SkColorSpace::MakeSRGB()); sk_sp image = SkImage::MakeFromGenerator(std::move(gen)); canvas->drawImage(image, 0, 0); ## #SeeAlso MakeFromEncoded #Method ## # ------------------------------------------------------------------------------ #Method static sk_sp MakeFromEncoded(sk_sp encoded, const SkIRect* subset = nullptr) #In Constructor #Line # creates Image from encoded data ## Creates Image from encoded data. subset allows selecting a portion of the full image. Pass nullptr to select the entire image; otherwise, subset must be contained by image bounds. Image is returned if format of the encoded data is recognized and supported. Recognized formats vary by platform. #Param encoded data of Image to decode ## #Param subset bounds of returned Image; may be nullptr ## #Return created Image, or nullptr ## #Example #Image 3 int x = 0; for (int quality : { 100, 50, 10, 1} ) { sk_sp encodedData = image->encodeToData(SkEncodedImageFormat::kJPEG, quality); sk_sp image = SkImage::MakeFromEncoded(encodedData); canvas->drawImage(image, x, 0); x += 64; } ## #SeeAlso MakeFromGenerator #Method ## # ------------------------------------------------------------------------------ #Typedef void (*TextureReleaseProc)(ReleaseContext releaseContext) #Line # parameter type for MakeFromTexture ## #Code typedef void (*TextureReleaseProc)(ReleaseContext releaseContext); ## User function called when supplied texture may be deleted. #SeeAlso MakeFromTexture ## #Method static sk_sp MakeFromTexture(GrContext* context, const GrBackendTexture& backendTexture, GrSurfaceOrigin origin, SkColorType colorType, SkAlphaType alphaType, sk_sp colorSpace) #In Constructor #Line # creates Image from GPU_Texture ## Creates Image from GPU_Texture associated with context. Caller is responsible for managing the lifetime of GPU_Texture. Image is returned if format of backendTexture is recognized and supported. Recognized formats vary by GPU back-end. #Param context GPU_Context ## #Param backendTexture texture residing on GPU ## #Param origin one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin ## #Param colorType one of: #list_of_color_types# ## #Param alphaType one of: #list_of_alpha_types# ## #Param colorSpace range of colors; may be nullptr ## #Return created Image, or nullptr ## #Example #Image 3 #Platform gpu #Height 128 #Description A back-end texture has been created and uploaded to the GPU outside of this example. ## GrContext* context = canvas->getGrContext(); if (!context) { return; } canvas->scale(.25f, .25f); int x = 0; for (auto origin : { kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin } ) { sk_sp image = SkImage::MakeFromTexture(context, backEndTexture, origin, kRGBA_8888_SkColorType, kOpaque_SkAlphaType, nullptr); canvas->drawImage(image, x, 0); x += 512; } ## #SeeAlso MakeFromAdoptedTexture SkSurface::MakeFromBackendTexture #Method ## # ------------------------------------------------------------------------------ #Method static sk_sp MakeFromTexture(GrContext* context, const GrBackendTexture& backendTexture, GrSurfaceOrigin origin, SkColorType colorType, SkAlphaType alphaType, sk_sp colorSpace, TextureReleaseProc textureReleaseProc, ReleaseContext releaseContext) Creates Image from GPU_Texture associated with context. GPU_Texture must stay valid and unchanged until textureReleaseProc is called. textureReleaseProc is passed releaseContext when Image is deleted or no longer refers to texture. Image is returned if format of backendTexture is recognized and supported. Recognized formats vary by GPU back-end. #Param context GPU_Context ## #Param backendTexture texture residing on GPU ## #Param origin one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin ## #Param colorType one of: #list_of_color_types# ## #Param alphaType one of: #list_of_alpha_types# ## #Param colorSpace range of colors; may be nullptr ## #Param textureReleaseProc function called when texture can be released ## #Param releaseContext state passed to textureReleaseProc ## #Return created Image, or nullptr ## #ToDo This doesn't do anything clever with TextureReleaseProc because it may not get called fwithin the lifetime of the example ## #Example #Platform gpu #Image 4 GrContext* context = canvas->getGrContext(); if (!context) { return; } auto debugster = [](SkImage::ReleaseContext releaseContext) -> void { *((int *) releaseContext) += 128; }; int x = 0; for (auto origin : { kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin } ) { sk_sp image = SkImage::MakeFromTexture(context, backEndTexture, origin, kRGBA_8888_SkColorType, kOpaque_SkAlphaType, nullptr, debugster, &x); canvas->drawImage(image, x, 0); x += 128; } ## #SeeAlso MakeFromAdoptedTexture SkSurface::MakeFromBackendTexture #Method ## # ------------------------------------------------------------------------------ #Method static sk_sp MakeCrossContextFromEncoded(GrContext* context, sk_sp data, bool buildMips, SkColorSpace* dstColorSpace, bool limitToMaxTextureSize = false) #In Constructor #Line # creates Image from encoded data, and uploads to GPU ## Creates Image from encoded data. Image is uploaded to GPU back-end using context. Created Image is available to other GPU contexts, and is available across thread boundaries. All contexts must be in the same GPU_Share_Group, or otherwise share resources. When Image is no longer referenced, context releases texture memory asynchronously. Texture decoded from data is uploaded to match Surface created with dstColorSpace. Color_Space of Image is determined by encoded data. Image is returned if format of data is recognized and supported, and if context supports moving resources. Recognized formats vary by platform and GPU back-end. Image is returned using MakeFromEncoded if context is nullptr or does not support moving resources between contexts. #Param context GPU_Context ## #Param data Image to decode ## #Param buildMips create Image as Mip_Map if true ## #Param dstColorSpace range of colors of matching Surface on GPU ## #Param limitToMaxTextureSize downscale image to GPU maximum texture size, if necessary ## #Return created Image, or nullptr ## #Example #Image 4 #Height 64 GrContext* context = canvas->getGrContext(); sk_sp encodedData = image->encodeToData(SkEncodedImageFormat::kJPEG, 100); sk_sp image = SkImage::MakeCrossContextFromEncoded(context, encodedData, false, nullptr); canvas->drawImage(image, 0, 0); ## #SeeAlso MakeCrossContextFromPixmap #Method ## # ------------------------------------------------------------------------------ #Method static sk_sp MakeCrossContextFromPixmap(GrContext* context, const SkPixmap& pixmap, bool buildMips, SkColorSpace* dstColorSpace, bool limitToMaxTextureSize = false) #In Constructor #Line # creates Image from Pixmap, and uploads to GPU ## Creates Image from pixmap. Image is uploaded to GPU back-end using context. Created Image is available to other GPU contexts, and is available across thread boundaries. All contexts must be in the same GPU_Share_Group, or otherwise share resources. When Image is no longer referenced, context releases texture memory asynchronously. Texture created from pixmap is uploaded to match Surface created with dstColorSpace. Color_Space of Image is determined by pixmap.colorSpace(). Image is returned referring to GPU back-end if context is not nullptr, format of data is recognized and supported, and if context supports moving resources between contexts. Otherwise, pixmap pixel data is copied and Image as returned in raster format if possible; nullptr may be returned. Recognized GPU formats vary by platform and GPU back-end. #Param context GPU_Context ## #Param pixmap Image_Info, pixel address, and row bytes ## #Param buildMips create Image as Mip_Map if true ## #Param dstColorSpace range of colors of matching Surface on GPU ## #Param limitToMaxTextureSize downscale image to GPU maximum texture size, if necessary ## #Return created Image, or nullptr ## #Example #Image 4 #Height 64 GrContext* context = canvas->getGrContext(); SkPixmap pixmap; if (source.peekPixels(&pixmap)) { sk_sp image = SkImage::MakeCrossContextFromPixmap(context, pixmap, false, nullptr); canvas->drawImage(image, 0, 0); } ## #SeeAlso MakeCrossContextFromEncoded #Method ## # ------------------------------------------------------------------------------ #Method static sk_sp MakeFromAdoptedTexture(GrContext* context, const GrBackendTexture& backendTexture, GrSurfaceOrigin surfaceOrigin, SkColorType colorType, SkAlphaType alphaType = kPremul_SkAlphaType, sk_sp colorSpace = nullptr) #In Constructor #Line # creates Image from GPU_Texture, managed internally ## Creates Image from backendTexture associated with context. backendTexture and returned Image are managed internally, and are released when no longer needed. Image is returned if format of backendTexture is recognized and supported. Recognized formats vary by GPU back-end. #Param context GPU_Context ## #Param backendTexture texture residing on GPU ## #Param surfaceOrigin one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin ## #Param colorType one of: #list_of_color_types# ## #Param alphaType one of: #list_of_alpha_types# ## #Param colorSpace range of colors; may be nullptr ## #Return created Image, or nullptr ## #Example #Image 5 #Platform gpu if (!canvas->getGrContext()) { return; } canvas->scale(.5f, .5f); canvas->clear(0x7f3f5f7f); int x = 0, y = 0; for (auto origin : { kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin } ) { for (auto alpha : { kOpaque_SkAlphaType, kPremul_SkAlphaType, kUnpremul_SkAlphaType } ) { sk_sp image = SkImage::MakeFromAdoptedTexture(canvas->getGrContext(), backEndTexture, origin, kRGBA_8888_SkColorType, alpha); canvas->drawImage(image, x, y); x += 160; } x -= 160 * 3; y += 256; } ## #SeeAlso MakeFromTexture MakeFromYUVTexturesCopy #Method ## # ------------------------------------------------------------------------------ #Method static sk_sp MakeFromYUVTexturesCopy(GrContext* context, SkYUVColorSpace yuvColorSpace, const GrBackendTexture yuvTextures[3], GrSurfaceOrigin surfaceOrigin, sk_sp colorSpace = nullptr) #In Constructor #Line # creates Image from YUV_ColorSpace data in three planes ## Creates Image from copy of yuvTextures, an array of textures on GPU. yuvTextures contain pixels for YUV planes of Image. Returned Image has the dimensions yuvTextures[0]. yuvColorSpace describes how YUV colors convert to RGB colors. #Param context GPU_Context ## #Param yuvColorSpace one of: kJPEG_SkYUVColorSpace, kRec601_SkYUVColorSpace, kRec709_SkYUVColorSpace ## #Param yuvTextures array of YUV textures on GPU ## #Param surfaceOrigin one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin ## #Param colorSpace range of colors; may be nullptr ## #Return created Image, or nullptr ## # seems too complicated to create an example for this #ToDo should this be moved to chrome only? ## #NoExample ## #SeeAlso MakeFromNV12TexturesCopy #Method ## # ------------------------------------------------------------------------------ #Method static sk_sp MakeFromNV12TexturesCopy(GrContext* context, SkYUVColorSpace yuvColorSpace, const GrBackendTexture nv12Textures[2], GrSurfaceOrigin surfaceOrigin, sk_sp colorSpace = nullptr) #In Constructor #Line # creates Image from YUV_ColorSpace data in three planes ## Creates Image from copy of nv12Textures, an array of textures on GPU. nv12Textures[0] contains pixels for YUV_Component_Y plane. nv12Textures[1] contains pixels for YUV_Component_U plane, followed by pixels for YUV_Component_V plane. Returned Image has the dimensions nv12Textures[2]. yuvColorSpace describes how YUV colors convert to RGB colors. #Param context GPU_Context ## #Param yuvColorSpace one of: kJPEG_SkYUVColorSpace, kRec601_SkYUVColorSpace, kRec709_SkYUVColorSpace ## #Param nv12Textures array of YUV textures on GPU ## #Param surfaceOrigin one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin ## #Param colorSpace range of colors; may be nullptr ## #Return created Image, or nullptr ## # seems too complicated to create an example for this #ToDo should this be moved to chrome only? ## #NoExample ## #SeeAlso MakeFromYUVTexturesCopy #Method ## # ------------------------------------------------------------------------------ # currently uncalled by any test or client ## #Bug 7424 #EnumClass BitDepth #Line # options for MakeFromPicture ## #Code enum class BitDepth { kU8, kF16, }; ## #Const kU8 0 #Line # uses 8-bit unsigned int per Color component ## Use 8 bits per ARGB component using unsigned integer format. ## #Const kF16 1 #Line # uses 16-bit float per Color component ## Use 16 bits per ARGB component using half-precision floating point format. ## #NoExample ## #SeeAlso MakeFromPicture #EnumClass ## # ------------------------------------------------------------------------------ #Method static sk_sp MakeFromPicture(sk_sp picture, const SkISize& dimensions, const SkMatrix* matrix, const SkPaint* paint, BitDepth bitDepth, sk_sp colorSpace) #In Constructor #Line # creates Image from Picture ## Creates Image from picture. Returned Image width and height are set by dimensions. Image draws picture with matrix and paint, set to bitDepth and colorSpace. If matrix is nullptr, draws with identity Matrix. If paint is nullptr, draws with default Paint. colorSpace may be nullptr. #Param picture stream of drawing commands ## #Param dimensions width and height ## #Param matrix Matrix to rotate, scale, translate, and so on; may be nullptr ## #Param paint Paint to apply transparency, filtering, and so on; may be nullptr ## #Param bitDepth 8-bit integer or 16-bit float: per component ## #Param colorSpace range of colors; may be nullptr ## #Return created Image, or nullptr ## #Example SkPaint paint; SkPictureRecorder recorder; SkCanvas* recordingCanvas = recorder.beginRecording(50, 50); for (auto color : { SK_ColorRED, SK_ColorBLUE, 0xff007f00 } ) { paint.setColor(color); recordingCanvas->drawRect({10, 10, 30, 40}, paint); recordingCanvas->translate(10, 10); recordingCanvas->scale(1.2f, 1.4f); } sk_sp playback = recorder.finishRecordingAsPicture(); int x = 0, y = 0; for (auto alpha : { 70, 140, 210 } ) { paint.setAlpha(alpha); auto srgbColorSpace = SkColorSpace::MakeSRGB(); sk_sp image = SkImage::MakeFromPicture(playback, {50, 50}, nullptr, &paint, SkImage::BitDepth::kU8, srgbColorSpace); canvas->drawImage(image, x, y); x += 70; y += 70; } ## #SeeAlso SkCanvas::drawPicture #Method ## # ------------------------------------------------------------------------------ #Method static sk_sp MakeFromAHardwareBuffer(AHardwareBuffer* hardwareBuffer, SkAlphaType alphaType = kPremul_SkAlphaType, sk_sp colorSpace = nullptr) #In Constructor #Line # creates Image from Android hardware buffer ## #Bug 7447 Creates Image from Android hardware buffer. Returned Image takes a reference on the buffer. Only available on Android, when __ANDROID_API__ is defined to be 26 or greater. #Param hardwareBuffer AHardwareBuffer Android hardware buffer ## #Param alphaType one of: #list_of_alpha_types# ## #Param colorSpace range of colors; may be nullptr ## #Return created Image, or nullptr ## #NoExample ## #SeeAlso MakeFromRaster #Method ## # ------------------------------------------------------------------------------ #Subtopic Property #Populate #Line # values and attributes ## ## #Method int width() const #In Property #Line # returns pixel column count ## Returns pixel count in each row. #Return pixel width in Image ## #Example #Image 4 #Height 96 canvas->translate(10, 10); canvas->drawImage(image, 0, 0); canvas->translate(0, image->height()); SkPaint paint; paint.setTextAlign(SkPaint::kCenter_Align); canvas->drawLine(0, 10, image->width(), 10, paint); canvas->drawString("width", image->width() / 2, 25, paint); ## #SeeAlso dimensions() height() #Method ## # ------------------------------------------------------------------------------ #Method int height() const #In Property #Line # returns pixel row count ## Returns pixel row count. #Return pixel height in Image ## #Example #Image 4 #Height 96 canvas->translate(10, 10); canvas->drawImage(image, 0, 0); canvas->translate(image->width(), 0); SkPaint paint; paint.setTextAlign(SkPaint::kCenter_Align); paint.setVerticalText(true); canvas->drawLine(10, 0, 10, image->height(), paint); canvas->drawString("height", 25, image->height() / 2, paint); ## #SeeAlso dimensions() width() #Method ## # ------------------------------------------------------------------------------ #Method SkISize dimensions() const #In Property #Line # returns width() and height() ## Returns ISize { width(), height() }. #Return integral size of width() and height() ## #Example #Image 4 SkISize dimensions = image->dimensions(); SkIRect bounds = image->bounds(); SkIRect dimensionsAsBounds = SkIRect::MakeSize(dimensions); SkDebugf("dimensionsAsBounds %c= bounds\n", dimensionsAsBounds == bounds ? '=' : '!'); #StdOut dimensionsAsBounds == bounds ## ## #SeeAlso height() width() bounds() #Method ## # ------------------------------------------------------------------------------ #Method SkIRect bounds() const #In Property #Line # returns width() and height() as Rectangle ## Returns IRect { 0, 0, width(), height() }. #Return integral rectangle from origin to width() and height() ## #Example #Height 128 #Image 4 SkIRect bounds = image->bounds(); for (int x : { 0, bounds.width() } ) { for (int y : { 0, bounds.height() } ) { canvas->drawImage(image, x, y); } } ## #SeeAlso dimensions() #Method ## # ------------------------------------------------------------------------------ #Method uint32_t uniqueID() const #In Property #Line # returns identifier for Image ## Returns value unique to image. Image contents cannot change after Image is created. Any operation to create a new Image will receive generate a new unique number. #Return unique identifier ## #Example #Image 5 #Height 156 sk_sp subset = image->makeSubset({10, 20, 90, 100}); canvas->drawImage(image, 0, 0); canvas->drawImage(subset, 128, 0); SkPaint paint; SkString s; s.printf("original id: %d", image->uniqueID()); canvas->drawString(s, 20, image->height() + 20, paint); s.printf("subset id: %d", subset->uniqueID()); canvas->drawString(s, 148, subset->height() + 20, paint); ## #SeeAlso isLazyGenerated #Method ## # ------------------------------------------------------------------------------ #Method SkAlphaType alphaType() const #In Property #Line # returns Alpha_Type ## Returns Alpha_Type, one of: #list_of_alpha_types#. Alpha_Type returned was a parameter to an Image constructor, or was parsed from encoded data. #Return Alpha_Type in Image ## #Example #Image 4 #Height 96 const char* alphaTypeStr[] = { "Unknown", "Opaque", "Premul", "Unpremul" }; SkAlphaType alphaType = image->alphaType(); canvas->drawImage(image, 16, 0); canvas->drawString(alphaTypeStr[(int) alphaType], 20, image->height() + 20, SkPaint()); ## #SeeAlso SkImageInfo::alphaType #Method ## # ------------------------------------------------------------------------------ #Method SkColorType colorType() const #In Property #Line # returns Color_Type ## Returns Color_Type if known; otherwise, returns kUnknown_SkColorType. #Return Color_Type of Image ## #Example #Image 4 #Height 96 const char* colors[] = { "Unknown", "Alpha_8", "RGB_565", "ARGB_4444", "RGBA_8888", "RGB_888x", "BGRA_8888", "RGBA_1010102", "RGB_101010x", "Gray_8", "RGBA_F16" }; SkColorType colorType = image->colorType(); canvas->drawImage(image, 16, 0); canvas->drawString(colors[(int) colorType], 20, image->height() + 20, SkPaint()); ## #SeeAlso SkImageInfo::colorType #Method ## # ------------------------------------------------------------------------------ #Method SkColorSpace* colorSpace() const #In Property #Line # returns Color_Space ## Returns Color_Space, the range of colors, associated with Image. The reference count of Color_Space is unchanged. The returned Color_Space is immutable. Color_Space returned was passed to an Image constructor, or was parsed from encoded data. Color_Space returned may be ignored when Image is drawn, depending on the capabilities of the Surface receiving the drawing. #Return Color_Space in Image, or nullptr ## #Example #Image 3 #Set sRGB SkPixmap pixmap; source.peekPixels(&pixmap); canvas->scale(.25f, .25f); int y = 0; for (auto gamma : { SkColorSpace::kLinear_RenderTargetGamma, SkColorSpace::kSRGB_RenderTargetGamma } ) { int x = 0; sk_sp colorSpace = SkColorSpace::MakeRGB(gamma, SkColorSpace::kSRGB_Gamut); for (int index = 0; index < 2; ++index) { pixmap.setColorSpace(colorSpace); sk_sp image = SkImage::MakeRasterCopy(pixmap); canvas->drawImage(image, x, y); colorSpace = image->colorSpace()->makeColorSpin(); x += 512; } y += 512; } ## #SeeAlso refColorSpace makeColorSpace #Method ## # ------------------------------------------------------------------------------ #Method sk_sp refColorSpace() const #In Property #Line # returns Image_Info Color_Space ## Returns a smart pointer to Color_Space, the range of colors, associated with Image. The smart pointer tracks the number of objects sharing this SkColorSpace reference so the memory is released when the owners destruct. The returned SkColorSpace is immutable. Color_Space returned was passed to an Image constructor, or was parsed from encoded data. Color_Space returned may be ignored when Image is drawn, depending on the capabilities of the Surface receiving the drawing. #Return Color_Space in Image, or nullptr, wrapped in a smart pointer ## #Example #Image 3 #Set sRGB SkPixmap pixmap; source.peekPixels(&pixmap); canvas->scale(.25f, .25f); int y = 0; for (auto gamma : { SkColorSpace::kLinear_RenderTargetGamma, SkColorSpace::kSRGB_RenderTargetGamma } ) { int x = 0; sk_sp colorSpace = SkColorSpace::MakeRGB(gamma, SkColorSpace::kSRGB_Gamut); for (int index = 0; index < 2; ++index) { pixmap.setColorSpace(colorSpace); sk_sp image = SkImage::MakeRasterCopy(pixmap); canvas->drawImage(image, x, y); colorSpace = image->refColorSpace()->makeColorSpin(); x += 512; } y += 512; } ## #SeeAlso colorSpace makeColorSpace #Method ## # ------------------------------------------------------------------------------ #Method bool isAlphaOnly() const #In Property #Line # returns if pixels represent a transparency mask ## Returns true if Image pixels represent transparency only. If true, each pixel is packed in 8 bits as defined by kAlpha_8_SkColorType. #Return true if pixels represent a transparency mask ## #Example uint8_t pmColors = 0; sk_sp image = SkImage::MakeRasterCopy({SkImageInfo::MakeA8(1, 1), &pmColors, 1}); SkDebugf("alphaOnly = %s\n", image->isAlphaOnly() ? "true" : "false"); #StdOut alphaOnly = true ## ## #SeeAlso alphaType isOpaque #Method ## # ------------------------------------------------------------------------------ #Method bool isOpaque() const #In Property #Line # returns if Alpha_Type is kOpaque_SkAlphaType ## Returns true if pixels ignore their Alpha value and are treated as fully opaque. #Return true if Alpha_Type is kOpaque_SkAlphaType ## #Example auto check_isopaque = [](const SkImageInfo& imageInfo) -> void { auto surface(SkSurface::MakeRaster(imageInfo)); auto image(surface->makeImageSnapshot()); SkDebugf("isOpaque = %s\n", image->isOpaque() ? "true" : "false"); }; check_isopaque(SkImageInfo::MakeN32Premul(5, 5)); check_isopaque(SkImageInfo::MakeN32(5, 5, kOpaque_SkAlphaType)); #StdOut isOpaque = false isOpaque = true ## ## #SeeAlso alphaType isAlphaOnly #Method ## # ------------------------------------------------------------------------------ #Method sk_sp makeShader(SkShader::TileMode tileMode1, SkShader::TileMode tileMode2, const SkMatrix* localMatrix = nullptr) const #In Constructor #Line # creates Shader, Paint element that can tile Image ## Creates Shader from Image. Shader dimensions are taken from Image. Shader uses SkShader::TileMode rules to fill drawn area outside Image. localMatrix permits transforming Image before Canvas_Matrix is applied. #Param tileMode1 tiling on x-axis, one of: SkShader::kClamp_TileMode, SkShader::kRepeat_TileMode, SkShader::kMirror_TileMode ## #Param tileMode2 tiling on y-axis, one of: SkShader::kClamp_TileMode, SkShader::kRepeat_TileMode, SkShader::kMirror_TileMode ## #Param localMatrix Image transformation, or nullptr ## #Return Shader containing Image ## #Example #Image 4 SkMatrix matrix; matrix.setRotate(45); SkPaint paint; paint.setShader(image->makeShader(SkShader::kRepeat_TileMode, SkShader::kMirror_TileMode, &matrix)); canvas->drawPaint(paint); ## #SeeAlso scalePixels #Method ## # ------------------------------------------------------------------------------ #Method sk_sp makeShader(const SkMatrix* localMatrix = nullptr) const Creates Shader from Image. Shader dimensions are taken from Image. Shader uses SkShader::kClamp_TileMode to fill drawn area outside Image. localMatrix permits transforming Image before Canvas_Matrix is applied. #Param localMatrix Image transformation, or nullptr ## #Return Shader containing Image ## #Example #Image 5 SkMatrix matrix; matrix.setRotate(45); matrix.postTranslate(125, 30); SkPaint paint; paint.setShader(image->makeShader(&matrix)); canvas->drawPaint(paint); ## #SeeAlso scalePixels #Method ## # ------------------------------------------------------------------------------ #Subtopic Pixels #Populate #Line # read and write pixel values ## ## #Method bool peekPixels(SkPixmap* pixmap) const #In Pixels #Line # returns Pixmap if possible ## Copies Image pixel address, row bytes, and Image_Info to pixmap, if address is available, and returns true. If pixel address is not available, return false and leave pixmap unchanged. #Param pixmap storage for pixel state if pixels are readable; otherwise, ignored ## #Return true if Image has direct access to pixels ## #Example SkBitmap bitmap; bitmap.allocPixels(SkImageInfo::MakeN32Premul(12, 11)); SkCanvas offscreen(bitmap); offscreen.clear(SK_ColorWHITE); SkPaint paint; offscreen.drawString("%", 1, 10, paint); sk_sp image = SkImage::MakeFromBitmap(bitmap); SkPixmap pixmap; if (image->peekPixels(&pixmap)) { const SkPMColor* pixels = pixmap.addr32(); SkPMColor pmWhite = pixels[0]; for (int y = 0; y < image->height(); ++y) { for (int x = 0; x < image->width(); ++x) { SkDebugf("%c", *pixels++ == pmWhite ? '-' : 'x'); } SkDebugf("\n"); } } #StdOut ------------ --xx----x--- -x--x--x---- -x--x--x---- -x--x-x----- --xx-xx-xx-- -----x-x--x- ----x--x--x- ----x--x--x- ---x----xx-- ------------ ## ## #SeeAlso readPixels #Method ## # ------------------------------------------------------------------------------ #Method GrTexture* getTexture() const #Deprecated #Method ## # ------------------------------------------------------------------------------ #Method bool isTextureBacked() const #In Property #Line # returns if Image was created from GPU_Texture ## Returns true the contents of Image was created on or uploaded to GPU memory, and is available as a GPU_Texture. #Return true if Image is a GPU_Texture ## #Example #Image 5 #Platform gpu auto drawImage = [=](sk_sp image, const char* label) -> void { if (nullptr == image) { return; } SkPaint paint; paint.setAntiAlias(true); paint.setTextAlign(SkPaint::kCenter_Align); canvas->drawImage(image, 0, 0); canvas->drawString(label, image->width() / 2, image->height() / 4, paint); canvas->drawString(image->isTextureBacked() ? "is GPU texture" : "not GPU texture", image->width() / 2, image->height() * 3 / 4, paint); }; sk_sp bitmapImage(SkImage::MakeFromBitmap(source)); sk_sp textureImage(SkImage::MakeFromTexture(canvas->getGrContext(), backEndTexture, kTopLeft_GrSurfaceOrigin, kRGBA_8888_SkColorType, kOpaque_SkAlphaType, nullptr)); drawImage(image, "image"); canvas->translate(image->width(), 0); drawImage(bitmapImage, "source"); canvas->translate(-image->width(), image->height()); drawImage(textureImage, "backEndTexture"); ## #SeeAlso MakeFromTexture isValid #Method ## # ------------------------------------------------------------------------------ #Method bool isValid(GrContext* context) const #In Property #Line # returns if Image can draw to Raster_Surface or GPU_Context ## Returns true if Image can be drawn on either Raster_Surface or GPU_Surface. If context is nullptr, tests if Image draws on Raster_Surface; otherwise, tests if Image draws on GPU_Surface associated with context. Image backed by GPU_Texture may become invalid if associated GrContext is invalid. Lazy_Image may be invalid and may not draw to Raster_Surface or GPU_Surface or both. #Param context GPU_Context ## #Return true if Image can be drawn ## #Example #Image 5 #Platform gpu auto drawImage = [=](sk_sp image, const char* label) -> void { if (nullptr == image) { return; } SkPaint paint; paint.setAntiAlias(true); paint.setTextAlign(SkPaint::kCenter_Align); canvas->drawImage(image, 0, 0); canvas->drawString(label, image->width() / 2, image->height() / 4, paint); if (canvas->getGrContext()) { canvas->drawString(image->isValid(canvas->getGrContext()) ? "is valid on GPU" : "not valid on GPU", image->width() / 2, image->height() * 5 / 8, paint); } canvas->drawString(image->isValid(nullptr) ? "is valid on CPU" : "not valid on CPU", image->width() / 2, image->height() * 7 / 8, paint); }; sk_sp bitmapImage(SkImage::MakeFromBitmap(source)); sk_sp textureImage(SkImage::MakeFromTexture(canvas->getGrContext(), backEndTexture, kTopLeft_GrSurfaceOrigin, kRGBA_8888_SkColorType, kOpaque_SkAlphaType, nullptr)); drawImage(image, "image"); canvas->translate(image->width(), 0); drawImage(bitmapImage, "source"); canvas->translate(-image->width(), image->height()); drawImage(textureImage, "backEndTexture"); ## #SeeAlso isTextureBacked isLazyGenerated #Method ## # ------------------------------------------------------------------------------ #Method GrBackendTexture getBackendTexture(bool flushPendingGrContextIO, GrSurfaceOrigin* origin = nullptr) const #In Property #Line # returns GPU reference to Image as texture ## Retrieves the back-end texture. If Image has no back-end texture, an invalid object is returned. Call GrBackendTexture::isValid to determine if the result is valid. If flushPendingGrContextIO is true, completes deferred I/O operations. If origin in not nullptr, copies location of content drawn into Image. #Param flushPendingGrContextIO flag to flush outstanding requests ## #Param origin storage for one of: kTopLeft_GrSurfaceOrigin, kBottomLeft_GrSurfaceOrigin; or nullptr ## #Return back-end API texture handle; invalid on failure ## #Example #Image 3 #Platform gpu GrContext* grContext = canvas->getGrContext(); if (!grContext) { canvas->drawString("GPU only!", 20, 40, SkPaint()); return; } sk_sp imageFromBackend = SkImage::MakeFromAdoptedTexture(grContext, backEndTexture, kBottomLeft_GrSurfaceOrigin, kRGBA_8888_SkColorType, kOpaque_SkAlphaType); GrBackendTexture textureFromImage = imageFromBackend->getBackendTexture(false); if (!textureFromImage.isValid()) { return; } sk_sp imageFromTexture = SkImage::MakeFromAdoptedTexture(grContext, textureFromImage, kTopLeft_GrSurfaceOrigin, kRGBA_8888_SkColorType, kOpaque_SkAlphaType); canvas->drawImage(imageFromTexture, 0, 0); canvas->drawImage(imageFromBackend, 128, 128); ## #SeeAlso MakeFromTexture isTextureBacked #Method ## # ------------------------------------------------------------------------------ #Enum CachingHint #Line # options for readPixels and scalePixels ## #Code enum CachingHint { kAllow_CachingHint, kDisallow_CachingHint, }; ## CachingHint selects whether Skia may internally cache Bitmaps generated by decoding Image, or by copying Image from GPU to CPU. The default behavior allows caching Bitmaps. Choose kDisallow_CachingHint if Image pixels are to be used only once, or if Image pixels reside in a cache outside of Skia, or to reduce memory pressure. Choosing kAllow_CachingHint does not ensure that pixels will be cached. Image pixels may not be cached if memory requirements are too large or pixels are not accessible. #Const kAllow_CachingHint 0 #Line # allows internally caching decoded and copied pixels ## ## #Const kDisallow_CachingHint 1 #Line # disallows internally caching decoded and copied pixels ## ## #NoExample ## #SeeAlso readPixels scalePixels #Enum ## # ------------------------------------------------------------------------------ #Method bool readPixels(const SkImageInfo& dstInfo, void* dstPixels, size_t dstRowBytes, int srcX, int srcY, CachingHint cachingHint = kAllow_CachingHint) const #In Pixels #Line # copies and converts pixels ## Copies Rect of pixels from Image to dstPixels. Copy starts at offset (srcX, srcY), and does not exceed Image (width(), height()). dstInfo specifies width, height, Color_Type, Alpha_Type, and Color_Space of destination. dstRowBytes specifics the gap from one destination row to the next. Returns true if pixels are copied. Returns false if: #List # dstInfo.addr() equals nullptr ## # dstRowBytes is less than dstInfo.minRowBytes ## # Pixel_Ref is nullptr ## ## Pixels are copied only if pixel conversion is possible. If Image Color_Type is kGray_8_SkColorType, or kAlpha_8_SkColorType; dstInfo.colorType must match. If Image Color_Type is kGray_8_SkColorType, dstInfo.colorSpace must match. If Image Alpha_Type is kOpaque_SkAlphaType, dstInfo.alphaType must match. If Image Color_Space is nullptr, dstInfo.colorSpace must match. Returns false if pixel conversion is not possible. srcX and srcY may be negative to copy only top or left of source. Returns false if width() or height() is zero or negative. Returns false if #Formula abs(srcX) >= Image width() ## , or if #Formula abs(srcY) >= Image height() ## . If cachingHint is kAllow_CachingHint, pixels may be retained locally. If cachingHint is kDisallow_CachingHint, pixels are not added to the local cache. #Param dstInfo destination width, height, Color_Type, Alpha_Type, Color_Space ## #Param dstPixels destination pixel storage ## #Param dstRowBytes destination row length ## #Param srcX column index whose absolute value is less than width() ## #Param srcY row index whose absolute value is less than height() ## #Param cachingHint one of: kAllow_CachingHint, kDisallow_CachingHint ## #Return true if pixels are copied to dstPixels ## #Example #Image 3 canvas->scale(.5f, .5f); const int width = 32; const int height = 32; std::vector dstPixels; dstPixels.resize(height * width * 4); SkImageInfo info = SkImageInfo::MakeN32Premul(width, height); for (int y = 0; y < 512; y += height ) { for (int x = 0; x < 512; x += width ) { if (image->readPixels(info, &dstPixels.front(), width * 4, x, y)) { SkPixmap dstPixmap(info, &dstPixels.front(), width * 4); SkBitmap bitmap; bitmap.installPixels(dstPixmap); canvas->drawBitmap(bitmap, 0, 0); } canvas->translate(48, 0); } canvas->translate(-16 * 48, 48); } ## #SeeAlso scalePixels SkBitmap::readPixels SkPixmap::readPixels SkCanvas::readPixels SkSurface::readPixels #Method ## # ------------------------------------------------------------------------------ #Method bool readPixels(const SkPixmap& dst, int srcX, int srcY, CachingHint cachingHint = kAllow_CachingHint) const Copies a Rect of pixels from Image to dst. Copy starts at (srcX, srcY), and does not exceed Image (width(), height()). dst specifies width, height, Color_Type, Alpha_Type, Color_Space, pixel storage, and row bytes of destination. dst.rowBytes specifics the gap from one destination row to the next. Returns true if pixels are copied. Returns false if: #List # dst pixel storage equals nullptr ## # dst.rowBytes is less than SkImageInfo::minRowBytes ## # Pixel_Ref is nullptr ## ## Pixels are copied only if pixel conversion is possible. If Image Color_Type is kGray_8_SkColorType, or kAlpha_8_SkColorType; dst.colorType must match. If Image Color_Type is kGray_8_SkColorType, dst.colorSpace must match. If Image Alpha_Type is kOpaque_SkAlphaType, dst.alphaType must match. If Image Color_Space is nullptr, dst.colorSpace must match. Returns false if pixel conversion is not possible. srcX and srcY may be negative to copy only top or left of source. Returns false if width() or height() is zero or negative. Returns false if #Formula abs(srcX) >= Image width() ## , or if #Formula abs(srcY) >= Image height() ## . If cachingHint is kAllow_CachingHint, pixels may be retained locally. If cachingHint is kDisallow_CachingHint, pixels are not added to the local cache. #Param dst destination Pixmap: Image_Info, pixels, row bytes ## #Param srcX column index whose absolute value is less than width() ## #Param srcY row index whose absolute value is less than height() ## #Param cachingHint one of: kAllow_CachingHint, kDisallow_CachingHint ## #Return true if pixels are copied to dst ## #Example #Image 3 std::vector srcPixels; int rowBytes = image->width() * 4; int quarterWidth = image->width() / 4; int quarterHeight = image->height() / 4; srcPixels.resize(image->height() * rowBytes); for (int y = 0; y < 4; ++y) { for (int x = 0; x < 4; ++x) { SkPixmap pixmap(SkImageInfo::MakeN32Premul(quarterWidth, quarterHeight), &srcPixels.front() + x * image->height() * quarterWidth + y * quarterWidth, rowBytes); image->readPixels(pixmap, x * quarterWidth, y * quarterHeight); } } canvas->scale(.5f, .5f); SkBitmap bitmap; bitmap.installPixels(SkImageInfo::MakeN32Premul(image->width(), image->height()), &srcPixels.front(), rowBytes); canvas->drawBitmap(bitmap, 0, 0); ## #SeeAlso scalePixels SkBitmap::readPixels SkPixmap::readPixels SkCanvas::readPixels SkSurface::readPixels #Method ## # ------------------------------------------------------------------------------ #Method bool scalePixels(const SkPixmap& dst, SkFilterQuality filterQuality, CachingHint cachingHint = kAllow_CachingHint) const #In Pixels #Line # scales and converts one Image to another ## Copies Image to dst, scaling pixels to fit dst.width() and dst.height(), and converting pixels to match dst.colorType and dst.alphaType. Returns true if pixels are copied. Returns false if dst.addr() is nullptr, or dst.rowBytes is less than dst SkImageInfo::minRowBytes. Pixels are copied only if pixel conversion is possible. If Image Color_Type is kGray_8_SkColorType, or kAlpha_8_SkColorType; dst.colorType must match. If Image Color_Type is kGray_8_SkColorType, dst.colorSpace must match. If Image Alpha_Type is kOpaque_SkAlphaType, dst.alphaType must match. If Image Color_Space is nullptr, dst.colorSpace must match. Returns false if pixel conversion is not possible. Scales the image, with filterQuality, to match dst.width() and dst.height(). filterQuality kNone_SkFilterQuality is fastest, typically implemented with Filter_Quality_Nearest_Neighbor. kLow_SkFilterQuality is typically implemented with Filter_Quality_Bilerp. kMedium_SkFilterQuality is typically implemented with Filter_Quality_Bilerp, and Filter_Quality_MipMap when size is reduced. kHigh_SkFilterQuality is slowest, typically implemented with Filter_Quality_BiCubic. If cachingHint is kAllow_CachingHint, pixels may be retained locally. If cachingHint is kDisallow_CachingHint, pixels are not added to the local cache. #Param dst destination Pixmap: Image_Info, pixels, row bytes ## #Param filterQuality one of: kNone_SkFilterQuality, kLow_SkFilterQuality, kMedium_SkFilterQuality, kHigh_SkFilterQuality ## #Param cachingHint one of: kAllow_CachingHint, kDisallow_CachingHint ## #Return true if pixels are scaled to fit dst ## #Example #Image 3 #Height 128 std::vector srcPixels; int quarterWidth = image->width() / 16; int rowBytes = quarterWidth * 4; int quarterHeight = image->height() / 16; srcPixels.resize(quarterHeight * rowBytes); SkPixmap pixmap(SkImageInfo::MakeN32Premul(quarterWidth, quarterHeight), &srcPixels.front(), rowBytes); canvas->scale(4, 4); SkFilterQuality qualities[] = { kNone_SkFilterQuality, kLow_SkFilterQuality, kMedium_SkFilterQuality, kHigh_SkFilterQuality }; for (unsigned index = 0; index < SK_ARRAY_COUNT(qualities); ++index) { image->scalePixels(pixmap, qualities[index]); sk_sp filtered = SkImage::MakeFromRaster(pixmap, nullptr, nullptr); canvas->drawImage(filtered, 16 * index, 0); } ## #SeeAlso SkCanvas::drawImage readPixels SkPixmap::scalePixels #Method ## # ------------------------------------------------------------------------------ #Method sk_sp encodeToData(SkEncodedImageFormat encodedImageFormat, int quality) const #In Utility #Line # returns encoded Image as SkData ## Encodes Image pixels, returning result as SkData. Returns nullptr if encoding fails, or if encodedImageFormat is not supported. Image encoding in a format requires both building with one or more of: SK_HAS_JPEG_LIBRARY, SK_HAS_PNG_LIBRARY, SK_HAS_WEBP_LIBRARY; and platform support for the encoded format. If SK_BUILD_FOR_MAC or SK_BUILD_FOR_IOS is defined, encodedImageFormat can additionally be one of: SkEncodedImageFormat::kICO, SkEncodedImageFormat::kBMP, SkEncodedImageFormat::kGIF. quality is a platform and format specific metric trading off size and encoding error. When used, quality equaling 100 encodes with the least error. quality may be ignored by the encoder. #Param encodedImageFormat one of: SkEncodedImageFormat::kJPEG, SkEncodedImageFormat::kPNG, SkEncodedImageFormat::kWEBP ## #Param quality encoder specific metric with 100 equaling best ## #Return encoded Image, or nullptr ## #Example #Image 3 canvas->scale(4, 4); SkIRect subset = {0, 0, 16, 64}; int x = 0; for (int quality : { 0, 10, 50, 100 } ) { sk_sp data(image->encodeToData(SkEncodedImageFormat::kJPEG, quality)); sk_sp filtered = SkImage::MakeFromEncoded(data, &subset); canvas->drawImage(filtered, x, 0); x += 16; } ## #SeeAlso refEncodedData MakeFromEncoded #Method ## # ------------------------------------------------------------------------------ #Method sk_sp encodeToData() const Encodes Image pixels, returning result as SkData. Returns existing encoded data if present; otherwise, Image is encoded with SkEncodedImageFormat::kPNG. Skia must be built with SK_HAS_PNG_LIBRARY to encode Image. Returns nullptr if existing encoded data is missing or invalid, and encoding fails. #Return encoded Image, or nullptr ## #Example #Image 3 canvas->scale(4, 4); SkIRect subset = {136, 32, 200, 96}; sk_sp data(image->encodeToData()); sk_sp eye = SkImage::MakeFromEncoded(data, &subset); canvas->drawImage(eye, 0, 0); ## #SeeAlso refEncodedData MakeFromEncoded #Method ## # ------------------------------------------------------------------------------ #Method sk_sp refEncodedData() const #In Utility #Line # returns Image encoded in SkData if present ## Returns encoded Image pixels as SkData, if Image was created from supported encoded stream format. Platform support for formats vary and may require building with one or more of: SK_HAS_JPEG_LIBRARY, SK_HAS_PNG_LIBRARY, SK_HAS_WEBP_LIBRARY. Returns nullptr if Image contents are not encoded. #Return encoded Image, or nullptr ## #Example #Image 3 #Platform gpu struct { const char* name; sk_sp image; } tests[] = { { "image", image }, { "bitmap", SkImage::MakeFromBitmap(source) }, { "texture", SkImage::MakeFromTexture(canvas->getGrContext(), backEndTexture, kTopLeft_GrSurfaceOrigin, kRGBA_8888_SkColorType, kOpaque_SkAlphaType, nullptr) } }; SkString string; SkPaint paint; for (const auto& test : tests ) { if (!test.image) { string.printf("no %s", test.name); } else { string.printf("%s" "encoded %s", test.image->refEncodedData() ? "" : "no ", test.name); } canvas->drawString(string, 10, 20, paint); canvas->translate(0, 20); } ## #SeeAlso encodeToData MakeFromEncoded #Method ## # ------------------------------------------------------------------------------ #Subtopic Utility #Populate #Line # rarely called management functions ## ## #Method sk_sp makeSubset(const SkIRect& subset) const #In Constructor #Line # creates Image containing part of original ## Returns subset of Image. subset must be fully contained by Image dimensions(). The implementation may share pixels, or may copy them. Returns nullptr if subset is empty, or subset is not contained by bounds, or pixels in Image could not be read or copied. #Param subset bounds of returned Image ## #Return partial or full Image, or nullptr ## #Example #Image 3 canvas->scale(.5f, .5f); const int width = 64; const int height = 64; for (int y = 0; y < 512; y += height ) { for (int x = 0; x < 512; x += width ) { sk_sp subset(image->makeSubset({x, y, x + width, y + height})); canvas->drawImage(subset, x * 3 / 2, y * 3 / 2); } } ## #SeeAlso MakeFromEncoded #Method ## # ------------------------------------------------------------------------------ #Method sk_sp makeTextureImage(GrContext* context, SkColorSpace* dstColorSpace, GrMipMapped mipMapped = GrMipMapped::kNo) const #In Constructor #Line # creates Image matching Color_Space if possible ## Returns Image backed by GPU_Texture associated with context. Returned Image is compatible with Surface created with dstColorSpace. The returned Image respects mipMapped setting; if mipMapped equals GrMipMapped::kYes, the backing texture allocates Mip_Map levels. Returns original Image if context and dstColorSpace match and mipMapped is compatible with backing GPU_Texture. Returns nullptr if context is nullptr, or if Image was created with another GrContext. #Param context GPU_Context ## #Param dstColorSpace range of colors of matching Surface on GPU ## #Param mipMapped whether created Image texture must allocate Mip_Map levels ## #Return created Image, or nullptr ## #Example #Platform gpu #Image 5 auto drawImage = [=](sk_sp image, GrContext* context, const char* label) -> void { if (nullptr == image || nullptr == context) { return; } SkPaint paint; paint.setAntiAlias(true); paint.setTextAlign(SkPaint::kCenter_Align); sk_sp texture(image->makeTextureImage(context, nullptr)); canvas->drawImage(texture, 0, 0); canvas->drawString(label, texture->width() / 2, texture->height() / 4, paint); }; sk_sp bitmapImage(SkImage::MakeFromBitmap(source)); GrContext* context = canvas->getGrContext(); sk_sp textureImage(SkImage::MakeFromTexture(context, backEndTexture, kTopLeft_GrSurfaceOrigin, kRGBA_8888_SkColorType, kOpaque_SkAlphaType, nullptr)); drawImage(image, context, "image"); canvas->translate(image->width(), 0); drawImage(bitmapImage, context, "source"); canvas->translate(-image->width(), image->height()); drawImage(textureImage, context, "backEndTexture"); ## #SeeAlso MakeFromTexture #Method ## # ------------------------------------------------------------------------------ #Method sk_sp makeNonTextureImage() const #In Constructor #Line # creates Image without dependency on GPU_Texture ## Returns Raster_Image or Lazy_Image. Copies Image backed by GPU_Texture into CPU memory if needed. Returns original Image if decoded in Raster_Bitmap, or if encoded in a stream. Returns nullptr if backed by GPU_Texture and copy fails. #Return Raster_Image, Lazy_Image, or nullptr ## #Example #Image 5 #Platform gpu auto drawImage = [=](sk_sp image, const char* label) -> void { if (nullptr == image) { return; } SkPaint paint; paint.setAntiAlias(true); paint.setTextAlign(SkPaint::kCenter_Align); sk_sp nonTexture(image->makeNonTextureImage()); canvas->drawImage(nonTexture, 0, 0); canvas->drawString(label, nonTexture->width() / 2, nonTexture->height() / 4, paint); }; sk_sp bitmapImage(SkImage::MakeFromBitmap(source)); sk_sp textureImage(SkImage::MakeFromTexture(canvas->getGrContext(), backEndTexture, kTopLeft_GrSurfaceOrigin, kRGBA_8888_SkColorType, kOpaque_SkAlphaType, nullptr)); drawImage(image, "image"); canvas->translate(image->width(), 0); drawImage(bitmapImage, "source"); canvas->translate(-image->width(), image->height()); drawImage(textureImage, "backEndTexture"); ## #SeeAlso makeTextureImage makeRasterImage MakeBackendTextureFromSkImage #Method ## # ------------------------------------------------------------------------------ #Method sk_sp makeRasterImage() const #In Constructor #Line # creates Image compatible with Raster_Surface if possible ## Returns Raster_Image. Copies Image backed by GPU_Texture into CPU memory, or decodes Image from Lazy_Image. Returns original Image if decoded in Raster_Bitmap. Returns nullptr if copy, decode, or pixel read fails. #Return Raster_Image, or nullptr ## #Bug 7479 #Example #Image 5 #Platform gpu auto drawImage = [=](sk_sp image, const char* label) -> void { if (nullptr == image) { return; } SkPaint paint; paint.setAntiAlias(true); paint.setTextAlign(SkPaint::kCenter_Align); sk_sp raster(image->makeRasterImage()); canvas->drawImage(raster, 0, 0); canvas->drawString(label, raster->width() / 2, raster->height() / 4, paint); }; sk_sp bitmapImage(SkImage::MakeFromBitmap(source)); sk_sp textureImage(SkImage::MakeFromTexture(canvas->getGrContext(), backEndTexture, kTopLeft_GrSurfaceOrigin, kRGBA_8888_SkColorType, kOpaque_SkAlphaType, nullptr)); drawImage(image, "image"); canvas->translate(image->width(), 0); drawImage(bitmapImage, "source"); canvas->translate(-image->width(), image->height()); drawImage(textureImage, "backEndTexture"); ## #SeeAlso isTextureBacked isLazyGenerated MakeFromRaster #Method ## # ------------------------------------------------------------------------------ #Method sk_sp makeWithFilter(const SkImageFilter* filter, const SkIRect& subset, const SkIRect& clipBounds, SkIRect* outSubset, SkIPoint* offset) const #In Constructor #Line # creates filtered, clipped Image ## Creates filtered Image. filter processes original Image, potentially changing color, position, and size. subset is the bounds of original Image processed by filter. clipBounds is the expected bounds of the filtered Image. outSubset is required storage for the actual bounds of the filtered Image. offset is required storage for translation of returned Image. Returns nullptr if Image could not be created. If nullptr is returned, outSubset and offset are undefined. Useful for animation of SkImageFilter that varies size from frame to frame. Returned Image is created larger than required by filter so that GPU_Texture can be reused with different sized effects. outSubset describes the valid bounds of GPU_Texture returned. offset translates the returned Image to keep subsequent animation frames aligned with respect to each other. #Param filter how Image is sampled when transformed ## #Param subset bounds of Image processed by filter ## #Param clipBounds expected bounds of filtered Image ## #Param outSubset storage for returned Image bounds ## #Param offset storage for returned Image translation ## #Return filtered Image, or nullptr ## #Example #Description In each frame of the animation, filtered Image is drawn in a different location. By translating canvas by returned offset, Image appears stationary. ## #Image 5 #Platform gpu #Duration 5 sk_sp shadowFilter = SkDropShadowImageFilter::Make( -10.0f * frame, 5.0f * frame, 3.0f, 3.0f, SK_ColorBLUE, SkDropShadowImageFilter::kDrawShadowAndForeground_ShadowMode, nullptr); sk_sp offsetFilter = SkOffsetImageFilter::Make(40, 40, shadowFilter, nullptr); SkIRect subset = image->bounds(); SkIRect clipBounds = image->bounds(); clipBounds.outset(60, 60); SkIRect outSubset; SkIPoint offset; sk_sp filtered(image->makeWithFilter(offsetFilter.get(), subset, clipBounds, &outSubset, &offset)); SkPaint paint; paint.setAntiAlias(true); paint.setStyle(SkPaint::kStroke_Style); canvas->drawLine(0, 0, offset.fX, offset.fY, paint); canvas->translate(offset.fX, offset.fY); canvas->drawImage(filtered, 0, 0); canvas->drawRect(SkRect::Make(outSubset), paint); ## #SeeAlso makeShader SkPaint::setImageFilter #Method ## # ------------------------------------------------------------------------------ #Typedef std::function BackendTextureReleaseProc #Line # parameter type for MakeBackendTextureFromSkImage ## #Code typedef std::function BackendTextureReleaseProc; ## Defines a callback function, taking one parameter of type GrBackendTexture with no return value. Function is called when back-end texture is to be released. ## # ------------------------------------------------------------------------------ #Method static bool MakeBackendTextureFromSkImage(GrContext* context, sk_sp image, GrBackendTexture* backendTexture, BackendTextureReleaseProc* backendTextureReleaseProc) #In Constructor #Line # creates GPU_Texture from Image ## Creates a GrBackendTexture from the provided SkImage. Returns true and stores result in backendTexture and backendTextureReleaseProc if texture is created; otherwise, returns false and leaves backendTexture and backendTextureReleaseProc unmodified. Call backendTextureReleaseProc after deleting backendTexture. backendTextureReleaseProc cleans up auxiliary data related to returned backendTexture. The caller must delete returned backendTexture after use. If Image is both texture backed and singly referenced, image is returned in backendTexture without conversion or making a copy. Image is singly referenced if its was transferred solely using std::move(). If Image is not texture backed, returns texture with Image contents. #Param context GPU_Context ## #Param image Image used for texture ## #Param backendTexture storage for back-end texture ## #Param backendTextureReleaseProc storage for clean up function ## #Return true if back-end texture was created ## #Example #Platform gpu #Height 64 #Function static sk_sp create_gpu_image(GrContext* grContext) { const SkImageInfo info = SkImageInfo::MakeN32(20, 20, kOpaque_SkAlphaType); auto surface(SkSurface::MakeRenderTarget(grContext, SkBudgeted::kNo, info)); SkCanvas* canvas = surface->getCanvas(); canvas->clear(SK_ColorWHITE); SkPaint paint; paint.setColor(SK_ColorBLACK); canvas->drawRect(SkRect::MakeXYWH(5, 5, 10, 10), paint); return surface->makeImageSnapshot(); } ## void draw(SkCanvas* canvas) { GrContext* grContext = canvas->getGrContext(); if (!grContext) { return; } sk_sp backEndImage = create_gpu_image(grContext); canvas->drawImage(backEndImage, 0, 0); GrBackendTexture texture; SkImage::BackendTextureReleaseProc proc; if (!SkImage::MakeBackendTextureFromSkImage(grContext, std::move(backEndImage), &texture, &proc)) { return; } sk_sp i2 = SkImage::MakeFromTexture(grContext, texture, kTopLeft_GrSurfaceOrigin, kN32_SkColorType, kOpaque_SkAlphaType, nullptr); canvas->drawImage(i2, 30, 30); } ## #SeeAlso MakeFromTexture makeTextureImage #Method ## # ------------------------------------------------------------------------------ #Enum LegacyBitmapMode #Deprecated soon #Code enum LegacyBitmapMode { kRO_LegacyBitmapMode, }; ## #Const kRO_LegacyBitmapMode 0 #Line # returned bitmap is read-only and immutable ## ## #Enum ## # ------------------------------------------------------------------------------ #Method bool asLegacyBitmap(SkBitmap* bitmap, LegacyBitmapMode legacyBitmapMode = kRO_LegacyBitmapMode) const #In Constructor #Line # returns as Raster_Bitmap ## Creates raster Bitmap with same pixels as Image. If legacyBitmapMode is kRO_LegacyBitmapMode, returned bitmap is read-only and immutable. Returns true if Bitmap is stored in bitmap. Returns false and resets bitmap if Bitmap write did not succeed. #Param bitmap storage for legacy Bitmap ## #Param legacyBitmapMode to be deprecated ## #Return true if Bitmap was created ## #Example #Image 4 #Platform gpu SkBitmap bitImage; if (image->asLegacyBitmap(&bitImage, SkImage::kRO_LegacyBitmapMode)) { canvas->drawBitmap(bitImage, 0, 0); } GrContext* grContext = canvas->getGrContext(); if (!grContext) { return; } sk_sp textureImage(SkImage::MakeFromTexture(grContext, backEndTexture, kTopLeft_GrSurfaceOrigin, kRGBA_8888_SkColorType, kOpaque_SkAlphaType, nullptr)); canvas->drawImage(textureImage, 45, 45); if (textureImage->asLegacyBitmap(&bitImage, SkImage::kRO_LegacyBitmapMode)) { canvas->drawBitmap(bitImage, 90, 90); } ## #SeeAlso MakeRasterData makeRasterImage makeNonTextureImage #Method ## # ------------------------------------------------------------------------------ #Method bool isLazyGenerated() const #In Property #Line # returns if Image is created as needed ## Returns true if Image is backed by an image-generator or other service that creates and caches its pixels or texture on-demand. #Return true if Image is created as needed ## #Example #Height 80 #Function class TestImageGenerator : public SkImageGenerator { public: TestImageGenerator() : SkImageGenerator(SkImageInfo::MakeN32Premul(10, 10)) {} ~TestImageGenerator() override {} protected: bool onGetPixels(const SkImageInfo& info, void* pixelPtr, size_t rowBytes, const Options& options) override { SkPMColor* pixels = static_cast(pixelPtr); for (int y = 0; y < info.height(); ++y) { for (int x = 0; x < info.width(); ++x) { pixels[y * info.width() + x] = 0xff223344 + y * 0x000C0811; } } return true; } }; ## void draw(SkCanvas* canvas) { auto gen = std::unique_ptr(new TestImageGenerator()); sk_sp image(SkImage::MakeFromGenerator(std::move(gen))); SkString lazy(image->isLazyGenerated() ? "is lazy" : "not lazy"); canvas->scale(8, 8); canvas->drawImage(image, 0, 0, nullptr); SkPaint paint; paint.setTextSize(4); canvas->drawString(lazy, 2, 5, paint); } ## #Example #Image 5 #Platform gpu void draw(SkCanvas* canvas) { auto drawImage = [=](sk_sp image, const char* label) -> void { if (nullptr == image) { return; } SkPaint paint; paint.setAntiAlias(true); paint.setTextAlign(SkPaint::kCenter_Align); canvas->drawImage(image, 0, 0); canvas->drawString(label, image->width() / 2, image->height() / 4, paint); canvas->drawString( image->isLazyGenerated() ? "is lazily generated" : "not lazily generated", image->width() / 2, image->height() * 3 / 4, paint); }; sk_sp bitmapImage(SkImage::MakeFromBitmap(source)); sk_sp textureImage(SkImage::MakeFromTexture(canvas->getGrContext(), backEndTexture, kTopLeft_GrSurfaceOrigin, kRGBA_8888_SkColorType, kOpaque_SkAlphaType, nullptr)); drawImage(image, "image"); canvas->translate(image->width(), 0); drawImage(bitmapImage, "source"); canvas->translate(-image->width(), image->height()); drawImage(textureImage, "backEndTexture"); } ## #SeeAlso isTextureBacked MakeNonTextureImage #Method ## # ------------------------------------------------------------------------------ #Method sk_sp makeColorSpace(sk_sp target) const #In Constructor #Line # creates Image matching Color_Space if possible ## Creates Image in target Color_Space. Returns nullptr if Image could not be created. Returns original Image if it is in target Color_Space. Otherwise, converts pixels from Image Color_Space to target Color_Space. If Image colorSpace returns nullptr, Image Color_Space is assumed to be sRGB. #Param target Color_Space describing color range of returned Image ## #Return created Image in target Color_Space ## #Example #Image 5 #Set sRGB sk_sp normalColorSpace = SkColorSpace::MakeRGB( SkColorSpace::kSRGB_RenderTargetGamma, SkColorSpace::kSRGB_Gamut); sk_sp wackyColorSpace = normalColorSpace->makeColorSpin(); for (auto colorSpace : { normalColorSpace, wackyColorSpace } ) { sk_sp colorSpaced = image->makeColorSpace(colorSpace); canvas->drawImage(colorSpaced, 0, 0); canvas->translate(128, 0); } ## #SeeAlso MakeFromPixture MakeFromTexture #Method ## #Class SkImage ## #Topic Image ##