blob: b0e319291d3bd53228c6275ea16f2ecd73fc437f [file] [log] [blame]
#Topic Image
#Alias Image_Reference
#Class SkImage
SkImage is an abstraction for drawing a rectangle 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 nullptr will be returned.
#Topic Overview
#Subtopic Subtopics
#ToDo manually add subtopics ##
#Table
#Legend
# topics # description ##
#Legend ##
#Table ##
##
#Subtopic Member_Functions
#Table
#Legend
# description # function ##
#Legend ##
# MakeBackendTextureFromSkImage # Creates GPU texture from Image. ##
# MakeCrossContextFromEncoded # Creates Image from encoded data, and uploads to GPU. ##
# MakeFromAHardwareBuffer # Creates Image from Android hardware buffer. ##
# MakeFromAdoptedTexture # Creates Image from GPU texture, managed internally. ##
# MakeFromBitmap # Creates Image from Bitmap, sharing or copying pixels. ##
# MakeFromEncoded # Creates Image from encoded data. ##
# MakeFromGenerator # Creates Image from a stream of data. ##
# MakeFromNV12TexturesCopy # Creates Image from YUV_ColorSpace data in two planes. ##
# MakeFromPicture # Creates Image from Picture. ##
# MakeFromRaster # Creates Image from Pixmap, with release. ##
# MakeFromTexture # Creates Image from GPU texture, managed externally. ##
# MakeFromYUVTexturesCopy # Creates Image from YUV_ColorSpace data in three planes. ##
# MakeRasterCopy # Creates Image from Pixmap and copied pixels. ##
# MakeRasterData # Creates Image from Image_Info and shared pixels. ##
# alphaType # Returns Alpha_Type ##
# asLegacyBitmap # Returns as Raster_Bitmap ##
# bounds() # Returns width() and height() as Rectangle. ##
# colorSpace # Returns Color_Space. ##
# dimensions() # Returns width() and height(). ##
# encodeToData # Returns encoded Image as SkData. ##
# getTexture # Deprecated. ##
# getTextureHandle # Returns GPU reference to Image as texture. ##
# height() # Returns pixel row count. ##
# isAlphaOnly # Returns if pixels represent a transparency mask. ##
# isLazyGenerated # Returns if Image is created as needed. ##
# isOpaque # Returns if Alpha_Type is kOpaque_SkAlphaType. ##
# isTextureBacked # Returns if Image was created from GPU texture. ##
# isValid # Returns if Image can draw to Raster_Surface or GPU_Context. ##
# makeColorSpace # Creates Image matching Color_Space if possible. ##
# makeNonTextureImage # Creates Raster_Image if possible. ##
# makeShader # Creates Shader, Paint element that can tile Image. ##
# makeSubset # Creates Image containing part of original. ##
# makeTextureImage # Creates Image matching Color_Space if possible. ##
# makeWithFilter # Creates filtered, clipped Image. ##
# peekPixels # Returns Pixmap if possible. ##
# readPixels # Copies and converts pixels. ##
# refColorSpace # Returns Image_Info Color_Space. ##
# refEncodedData # Returns Image encoded in SkData if present. ##
# scalePixels # Scales and converts one Image to another. ##
# toString # Converts Image to machine readable form. ##
# uniqueID # Identifier for Image. ##
# width() # Returns pixel column count. ##
#Table ##
#Subtopic ##
#Topic ##
#Typedef SkImageInfo Info
##
# ------------------------------------------------------------------------------
#Method static sk_sp<SkImage> MakeRasterCopy(const SkPixmap& pixmap)
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<SkImage> 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<SkImage> MakeRasterData(const Info& info, sk_sp<SkData> pixels, size_t rowBytes)
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<SkData> 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<SkImage> 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
Caller data passed to RasterReleaseProc; may be nullptr.
#SeeAlso MakeFromRaster RasterReleaseProc
##
#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<SkImage> MakeFromRaster(const SkPixmap& pixmap,
RasterReleaseProc rasterReleaseProc,
ReleaseContext releaseContext)
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<int*>(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<SkImage> 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<SkImage> MakeFromBitmap(const SkBitmap& bitmap)
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<SkImage> image1 = SkImage::MakeFromBitmap(bitmap);
bitmap.setImmutable();
sk_sp<SkImage> 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<SkImage> MakeFromGenerator(std::unique_ptr<SkImageGenerator> imageGenerator,
const SkIRect* subset = nullptr)
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
#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<SkImage> image = SkImage::MakeFromGenerator(std::move(gen));
canvas->drawImage(image, 0, 0);
##
#SeeAlso MakeFromEncoded
#Method ##
# ------------------------------------------------------------------------------
#Method static sk_sp<SkImage> MakeFromEncoded(sk_sp<SkData> encoded, const SkIRect* subset = nullptr)
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 platfrom.
#Param encoded data of Image to decode ##
#Param subset bounds of returned Image; may be nullptr ##
#Return created Image, or nullptr ##
#Bug 7343
Waiting on fiddle to support returning image as SkData
##
#NoExample
##
#SeeAlso MakeFromGenerator
#Method ##
# ------------------------------------------------------------------------------
#Typedef void (*TextureReleaseProc)(ReleaseContext releaseContext)
##
#Method static sk_sp<SkImage> MakeFromTexture(GrContext* context,
const GrBackendTexture& backendTexture,
GrSurfaceOrigin origin,
SkAlphaType alphaType,
sk_sp<SkColorSpace> colorSpace)
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 alphaType one of: kUnknown_SkAlphaType, kOpaque_SkAlphaType,
kPremul_SkAlphaType, kUnpremul_SkAlphaType
##
#Param colorSpace range of colors ##
#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<SkImage> image = SkImage::MakeFromTexture(canvas->getGrContext(), backEndTexture,
origin, kOpaque_SkAlphaType, nullptr);
canvas->drawImage(image, x, 0);
x += 512;
}
##
#SeeAlso MakeFromAdoptedTexture SkSurface::MakeFromBackendTexture
#Method ##
# ------------------------------------------------------------------------------
#Method static sk_sp<SkImage> MakeFromTexture(GrContext* context,
const GrBackendTexture& backendTexture,
GrSurfaceOrigin origin,
SkAlphaType alphaType,
sk_sp<SkColorSpace> 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 alphaType one of: kUnknown_SkAlphaType, kOpaque_SkAlphaType,
kPremul_SkAlphaType, kUnpremul_SkAlphaType
##
#Param colorSpace range of colors ##
#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
within the lifetime of the example
##
#Example
GrContext* context = canvas->getGrContext();
if (!context) {
return;
}
auto debugster = [](SkImage::ReleaseContext context) -> void {
*((int *) context) += 128;
};
int x = 0;
for (auto origin : { kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin } ) {
sk_sp<SkImage> image = SkImage::MakeFromTexture(canvas->getGrContext(), backEndTexture,
origin, kOpaque_SkAlphaType, nullptr, debugster, &x);
canvas->drawImage(image, x, 0);
x += 128;
}
##
#SeeAlso MakeFromAdoptedTexture SkSurface::MakeFromBackendTexture
#Method ##
# ------------------------------------------------------------------------------
#Method static sk_sp<SkImage> MakeCrossContextFromEncoded(GrContext* context, sk_sp<SkData> data,
bool buildMips,
SkColorSpace* dstColorSpace)
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.
#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 ##
#Return created Image, or nullptr ##
#Example
// incomplete
##
#SeeAlso MakeCrossContextFromPixmap
#Method ##
# ------------------------------------------------------------------------------
#Method static sk_sp<SkImage> MakeCrossContextFromPixmap(GrContext* context, const SkPixmap& pixmap,
bool buildMips,
SkColorSpace* dstColorSpace)
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 format of data is recognized and
supported, and if context supports moving resources. 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 ##
#Return created Image, or nullptr ##
#Example
// incomplete
##
#SeeAlso MakeCrossContextFromEncoded
#Method ##
# ------------------------------------------------------------------------------
#Method static sk_sp<SkImage> MakeFromAdoptedTexture(GrContext* context,
const GrBackendTexture& backendTexture,
GrSurfaceOrigin surfaceOrigin,
SkAlphaType alphaType = kPremul_SkAlphaType,
sk_sp<SkColorSpace> colorSpace = nullptr)
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 alphaType one of: kUnknown_SkAlphaType, kOpaque_SkAlphaType,
kPremul_SkAlphaType, kUnpremul_SkAlphaType
##
#Param colorSpace range of colors ##
#Return created Image, or nullptr ##
#Example
// incomplete
##
#SeeAlso incomplete
#Method ##
# ------------------------------------------------------------------------------
#Method 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, 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.
#Param context incomplete ##
#Param yuvColorSpace incomplete ##
#Param yuvTextureHandles incomplete ##
#Param yuvSizes incomplete ##
#Param surfaceOrigin incomplete ##
#Param colorSpace incomplete ##
#Return incomplete ##
#Example
// incomplete
##
#SeeAlso incomplete
#Method ##
# ------------------------------------------------------------------------------
#Method 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 and UV_Mapping. 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.
#Param context incomplete ##
#Param yuvColorSpace incomplete ##
#Param nv12TextureHandles incomplete ##
#Param nv12Sizes incomplete ##
#Param surfaceOrigin incomplete ##
#Param colorSpace incomplete ##
#Return incomplete ##
#Example
// incomplete
##
#SeeAlso incomplete
#Method ##
# ------------------------------------------------------------------------------
#Enum BitDepth
#Code
enum BitDepth {
kU8,
kF16,
};
##
#Const kU8 0
##
#Const kF16 1
##
#Example
// incomplete
##
#SeeAlso incomplete
#Enum ##
# ------------------------------------------------------------------------------
#Method static sk_sp<SkImage> MakeFromPicture(sk_sp<SkPicture> picture, const SkISize& dimensions,
const SkMatrix* matrix, const SkPaint* paint,
BitDepth bitDepth,
sk_sp<SkColorSpace> colorSpace)
Create a new image from the specified picture.
On creation of the SkImage, snap the SkPicture to a particular BitDepth and SkColorSpace.
#Param picture incomplete ##
#Param dimensions incomplete ##
#Param matrix incomplete ##
#Param paint incomplete ##
#Param bitDepth incomplete ##
#Param colorSpace incomplete ##
#Return incomplete ##
#Example
// incomplete
##
#SeeAlso incomplete
#Method ##
# ------------------------------------------------------------------------------
#Method static sk_sp<SkImage> MakeFromAHardwareBuffer(AHardwareBuffer* hardwareBuffer,
SkAlphaType alphaType = kPremul_SkAlphaType,
sk_sp<SkColorSpace> colorSpace = nullptr)
Create a new image from the an Android hardware buffer.
The new image takes a reference on the buffer.
Only available on Android, when __ANDROID_API__ is defined to be 26 or greater.
#Param hardwareBuffer incomplete ##
#Param alphaType incomplete ##
#Param colorSpace incomplete ##
#Return incomplete ##
#Example
// incomplete
##
#SeeAlso incomplete
#Method ##
# ------------------------------------------------------------------------------
#Method static sk_sp<SkImage> MakeFromAHardwareBuffer(AHardwareBuffer* hardwareBuffer,
SkAlphaType alphaType = kPremul_SkAlphaType,
sk_sp<SkColorSpace> colorSpace = nullptr)
Create a new image from the an Android hardware buffer.
The new image takes a reference on the buffer.
#Param hardwareBuffer incomplete ##
#Param alphaType incomplete ##
#Param colorSpace incomplete ##
#Return incomplete ##
#Example
// incomplete
##
#SeeAlso incomplete
#Method ##
# ------------------------------------------------------------------------------
#Method int width() const
#Return incomplete ##
#Example
// incomplete
##
#SeeAlso incomplete
#Method ##
# ------------------------------------------------------------------------------
#Method int height() const
Returns pixel row count.
#Return incomplete ##
#Example
// incomplete
##
#SeeAlso incomplete
#Method ##
# ------------------------------------------------------------------------------
#Method SkISize dimensions() const
Returns ISize { width(), height() }.
#Return integral size of width() and height() ##
#Example
// incomplete
##
#SeeAlso height() width()
#Method ##
# ------------------------------------------------------------------------------
#Method SkIRect bounds() const
Returns IRect { 0, 0, width(), height() }.
#Return integral rectangle from origin to width() and height() ##
#Example
// incomplete
##
#SeeAlso incomplete
#Method ##
# ------------------------------------------------------------------------------
#Method uint32_t uniqueID() const
#Return incomplete ##
#Example
// incomplete
##
#SeeAlso incomplete
#Method ##
# ------------------------------------------------------------------------------
#Method SkAlphaType alphaType() const
#Return incomplete ##
#Example
// incomplete
##
#SeeAlso incomplete
#Method ##
# ------------------------------------------------------------------------------
#Method SkColorSpace* colorSpace() const
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 a parameter to an Image constructor,
or was parsed from encoded data. Color_Space may be ignored when
drawing Image, and when drawing into Surface constructed with Color_Space.
#Return Color_Space in Image, or nullptr ##
#Example
// incomplete
##
#SeeAlso incomplete
#Method ##
# ------------------------------------------------------------------------------
#Method sk_sp<SkColorSpace> refColorSpace() const
#Return incomplete ##
#Example
// incomplete
##
#SeeAlso incomplete
#Method ##
# ------------------------------------------------------------------------------
#Method bool isAlphaOnly() const
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
// incomplete
##
#SeeAlso incomplete
#Method ##
# ------------------------------------------------------------------------------
#Method bool isOpaque() const
Returns if all pixels ignore any Alpha value and are treated as fully opaque.
#Return true if Alpha_Type is kOpaque_SkAlphaType ##
#Example
// incomplete
##
#SeeAlso incomplete
#Method ##
# ------------------------------------------------------------------------------
#Method sk_sp<SkShader> makeShader(SkShader::TileMode tileMode1, SkShader::TileMode tileMode2,
const SkMatrix* localMatrix = nullptr) const
#Param tileMode1 incomplete ##
#Param tileMode2 incomplete ##
#Param localMatrix incomplete ##
#Return incomplete ##
#Example
// incomplete
##
#SeeAlso incomplete
#Method ##
# ------------------------------------------------------------------------------
#Method sk_sp<SkShader> makeShader(const SkMatrix* localMatrix = nullptr) const
Helper version of makeShader() that specifies SkShader::kClamp_TileMode.
#Param localMatrix incomplete ##
#Return incomplete ##
#Example
// incomplete
##
#SeeAlso incomplete
#Method ##
# ------------------------------------------------------------------------------
#Method bool peekPixels(SkPixmap* pixmap) const
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.
#Param pixmap incomplete ##
#Return incomplete ##
#Example
// incomplete
##
#SeeAlso incomplete
#Method ##
# ------------------------------------------------------------------------------
#Method GrTexture* getTexture() const
Deprecated.
#Deprecated
##
#Private
currently used by Canvas2DLayerBridge in Chromium.
##
#Method ##
# ------------------------------------------------------------------------------
#Method bool isTextureBacked() const
Returns true if the image is texture backed.
#Return incomplete ##
#Example
// incomplete
##
#SeeAlso incomplete
#Method ##
# ------------------------------------------------------------------------------
#Method bool isValid(GrContext* context) const
Returns true if Image can be drawn. If context
is nullptr, tests if Image draws on Raster_Surface; Otherwise, tests if Image
draws on GPU_Surface associated with 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.
#Param context incomplete ##
#Return incomplete ##
#Example
// incomplete
##
#SeeAlso incomplete
#Method ##
# ------------------------------------------------------------------------------
#Method GrBackendObject getTextureHandle(bool flushPendingGrContextIO,
GrSurfaceOrigin* origin = nullptr) const
Retrieves the back-end API handle of texture. If flushPendingGrContextIO is true,
complete 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 ##
#Example
#Image 3
#Platform gpu
GrContext* context = canvas->getGrContext();
if (!context) {
return;
}
SkPaint paint;
paint.setAntiAlias(true);
SkString str;
int y = 0;
for (auto origin : { kTopLeft_GrSurfaceOrigin, kBottomLeft_GrSurfaceOrigin } ) {
sk_sp<SkImage> srcImage(SkImage::MakeFromTexture(context,
backEndTexture, origin, kPremul_SkAlphaType, nullptr));
GrSurfaceOrigin readBackOrigin;
GrBackendObject readBackHandle = srcImage->getTextureHandle(false, &readBackOrigin);
str.printf("readBackHandle: %x", readBackHandle);
canvas->drawString(str, 5, y += 20, paint);
str.printf("origin: k%s_GrSurfaceOrigin", readBackOrigin ? "BottomLeft" : "TopLeft");
canvas->drawString(str, 5, y += 20, paint);
}
##
#SeeAlso incomplete
#Method ##
# ------------------------------------------------------------------------------
#Enum CachingHint
#Code
enum CachingHint {
kAllow_CachingHint,
kDisallow_CachingHint,
};
##
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_CachingHint signals that the system's default
behavior is fine. Passing kDisallow_CachingHint signals that caching should be avoided.
#Const kAllow_CachingHint 0
##
#Const kDisallow_CachingHint 1
##
#Example
// incomplete
##
#SeeAlso incomplete
#Enum ##
# ------------------------------------------------------------------------------
#Method bool readPixels(const SkImageInfo& dstInfo, void* dstPixels, size_t dstRowBytes,
int srcX, int srcY, CachingHint cachingHint = kAllow_CachingHint) const
Copy the pixels from the image into the specified buffer (dstPixels + dstRowBytes),
converting them into the requested format (dstInfo). The image pixels are read
starting at the specified (srcX, srcY) location.
dstInfo and (srcX, srcY) offset specifies a source rectangle:
#Code
SkRect srcR;
srcR.setXYWH(srcX, srcY, dstInfo.width(), dstInfo.height());
##
The source rectangle 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 dstPixels with the
corresponding Image pixels, performing any Color_Type/Alpha_Type transformations needed
(in the case where Image and dstInfo have different Color_Types or Alpha_Types).
This call can fail, returning false, for several reasons:
if source rectangle does not intersect the image bounds;
if the requested Color_Type/Alpha_Type cannot be converted from the image's types.
#Param dstInfo incomplete ##
#Param dstPixels incomplete ##
#Param dstRowBytes incomplete ##
#Param srcX incomplete ##
#Param srcY incomplete ##
#Param cachingHint incomplete ##
#Return incomplete ##
#Example
// incomplete
##
#SeeAlso incomplete
#Method ##
# ------------------------------------------------------------------------------
#Method bool readPixels(const SkPixmap& dst, int srcX, int srcY,
CachingHint cachingHint = kAllow_CachingHint) const
#Param dst incomplete ##
#Param srcX incomplete ##
#Param srcY incomplete ##
#Param cachingHint incomplete ##
#Return incomplete ##
#Example
// incomplete
##
#SeeAlso incomplete
#Method ##
# ------------------------------------------------------------------------------
#Method bool scalePixels(const SkPixmap& dst, SkFilterQuality filterQuality,
CachingHint cachingHint = kAllow_CachingHint) const
Copies Image pixels into dst, converting to dst Color_Type and Alpha_Type.
If the conversion cannot be performed, false is returned.
If dst dimensions differ from Image dimensions, Image is scaled, applying
filterQuality.
#Param dst incomplete ##
#Param filterQuality incomplete ##
#Param cachingHint incomplete ##
#Return incomplete ##
#Example
// incomplete
##
#SeeAlso incomplete
#Method ##
# ------------------------------------------------------------------------------
#Method sk_sp<SkData> encodeToData(SkEncodedImageFormat encodedImageFormat, int quality) const
Encodes Image pixels, returning result as SkData.
Returns nullptr if encoding fails, or encodedImageFormat is not supported.
#Param encodedImageFormat incomplete ##
#Param quality incomplete ##
#Return encoded Image, or nullptr ##
#Example
// incomplete
##
#SeeAlso incomplete
#Method ##
# ------------------------------------------------------------------------------
#Method sk_sp<SkData> encodeToData(SkPixelSerializer* pixelSerializer = nullptr) const
Encodes Image and returns result as SkData. Will reuse existing encoded data
if present, as returned by refEncodedData. pixelSerializer validates existing
encoded data, and encodes Image when existing encoded data is missing or
invalid.
Passing nullptr for pixelSerializer selects default serialization which
accepts all data and encodes to PNG.
Returns nullptr if existing encoded data is missing or invalid and
encoding fails.
#Param pixelSerializer incomplete ##
#Return incomplete ##
#Example
// incomplete
##
#SeeAlso incomplete
#Method ##
# ------------------------------------------------------------------------------
#Method sk_sp<SkData> refEncodedData() 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 nullptr.
To force the image to return its contents as encoded data, call encodeToData.
#Return incomplete ##
#Example
// incomplete
##
#SeeAlso incomplete
#Method ##
# ------------------------------------------------------------------------------
#Method const char* toString(SkString* string) const
#Param string incomplete ##
#Return incomplete ##
#Example
// incomplete
##
#SeeAlso incomplete
#Method ##
# ------------------------------------------------------------------------------
#Method sk_sp<SkImage> makeSubset(const SkIRect& subset) 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,
nullptr will be returned.
#Param subset incomplete ##
#Return incomplete ##
#Example
// incomplete
##
#SeeAlso incomplete
#Method ##
# ------------------------------------------------------------------------------
#Method sk_sp<SkImage> makeTextureImage(GrContext* context, SkColorSpace* dstColorSpace) 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.
#Param context incomplete ##
#Param dstColorSpace incomplete ##
#Return incomplete ##
#Example
// incomplete
##
#SeeAlso incomplete
#Method ##
# ------------------------------------------------------------------------------
#Method sk_sp<SkImage> makeNonTextureImage() 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.
#Return incomplete ##
#Example
// incomplete
##
#SeeAlso incomplete
#Method ##
# ------------------------------------------------------------------------------
#Method sk_sp<SkImage> makeWithFilter(const SkImageFilter* filter, const SkIRect& subset,
const SkIRect& clipBounds, SkIRect* outSubset,
SkIPoint* offset) 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, stored in outSubset.
offset is storage, set to the amount to translate the result when drawn.
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.
#Param filter incomplete ##
#Param subset incomplete ##
#Param clipBounds incomplete ##
#Param outSubset incomplete ##
#Param offset incomplete ##
#Return incomplete ##
#Example
// incomplete
##
#SeeAlso incomplete
#Method ##
# ------------------------------------------------------------------------------
#Typedef std::function<void(GrBackendTexture)> BackendTextureReleaseProc
##
# ------------------------------------------------------------------------------
#Method static bool MakeBackendTextureFromSkImage(GrContext* context,
sk_sp<SkImage> image,
GrBackendTexture* backendTexture,
BackendTextureReleaseProc* 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.
If image is both texture backed and singly referenced; that is, its only
reference was transferred using std::move(): image is returned in backendTexture
without conversion or making a copy.
If the SkImage is not texture backed, this function will generate a texture with the image's
contents and return that.
#Param context incomplete ##
#Param image incomplete ##
#Param backendTexture incomplete ##
#Param backendTextureReleaseProc incomplete ##
#Return incomplete ##
#Example
// incomplete
##
#SeeAlso incomplete
#Method ##
# ------------------------------------------------------------------------------
#Enum LegacyBitmapMode
#Code
enum LegacyBitmapMode {
kRO_LegacyBitmapMode,
kRW_LegacyBitmapMode,
};
##
Helper functions to convert to SkBitmap
#Const kRO_LegacyBitmapMode 0
##
#Const kRW_LegacyBitmapMode 1
##
#Example
// incomplete
##
#SeeAlso incomplete
#Enum ##
# ------------------------------------------------------------------------------
#Method bool asLegacyBitmap(SkBitmap* bitmap, LegacyBitmapMode legacyBitmapMode) const
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 one of: kRO_LegacyBitmapMode, kRW_LegacyBitmapMode ##
#Return true if Bitmap was created ##
#Example
// incomplete
##
#SeeAlso incomplete
#Method ##
# ------------------------------------------------------------------------------
#Method bool isLazyGenerated() const
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<SkPMColor*>(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<TestImageGenerator>(new TestImageGenerator());
sk_sp<SkImage> 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);
}
##
#SeeAlso incomplete
#Method ##
# ------------------------------------------------------------------------------
#Method sk_sp<SkImage> makeColorSpace(sk_sp<SkColorSpace> target,
SkTransferFunctionBehavior premulBehavior) const
If target is supported, returns an SkImage in target color space.
Otherwise, returns nullptr.
This will leave the image as is if it already in target color space.
Otherwise, it will convert the pixels from Image color space to target
color space. If this->colorSpace() is nullptr, Image color space will be
treated as sRGB.
If premulBehavior is SkTransferFunctionBehavior::kRespect: converts Image
pixels to a linear space before converting to match destination Color_Type
and Color_Space.
If premulBehavior is SkTransferFunctionBehavior::kIgnore: Image
pixels are treated as if they are linear, regardless of how they are encoded.
#Param target incomplete ##
#Param premulBehavior incomplete ##
#Return incomplete ##
#Example
// incomplete
##
#SeeAlso incomplete
#Method ##
#Class SkImage ##
#Topic Image ##