update bookmaker to ToT
more image docs, still not done
add ability to comment out non-working examples easily
start work on additional self-checks
clean up use of this-> in docs
TBR=reed@google.com
Docs-Preview: https://skia.org/?cl=91720
Bug: skia:6898
Change-Id: I706ab8145290e53ab67d3f509ccf4e1225adb3c3
Reviewed-on: https://skia-review.googlesource.com/91720
Commit-Queue: Cary Clark <caryclark@skia.org>
Reviewed-by: Cary Clark <caryclark@skia.org>
diff --git a/docs/SkBitmap_Reference.bmh b/docs/SkBitmap_Reference.bmh
index 5eba984..e9755bf 100644
--- a/docs/SkBitmap_Reference.bmh
+++ b/docs/SkBitmap_Reference.bmh
@@ -453,7 +453,7 @@
Returns a constant reference to the Pixmap holding the Bitmap pixel
address, row bytes, and Image_Info.
-#Return reference to Pixmap describing this Bitmap. ##
+#Return reference to Pixmap describing this Bitmap ##
#Example
SkBitmap bitmap;
@@ -2791,8 +2791,8 @@
#Method bool readPixels(const SkImageInfo& dstInfo, void* dstPixels, size_t dstRowBytes,
int srcX, int srcY, SkTransferFunctionBehavior behavior) const
-Copies a Rect of pixels to dstPixels. Copy starts at (srcX, srcY), and does not exceed
-(this->width(), this->height()).
+Copies Rect of pixels from Bitmap pixels to dstPixels. Copy starts at (srcX, srcY),
+and does not exceed Bitmap (width(), height()).
dstInfo specifies width, height, Color_Type, Alpha_Type, and
Color_Space of destination. dstRowBytes specifics the gap from one destination
@@ -2803,22 +2803,22 @@
# Pixel_Ref is nullptr ##
##
-Pixels are copied only if pixel conversion is possible. If this->colorType is
+Pixels are copied only if pixel conversion is possible. If Bitmap colorType is
kGray_8_SkColorType, or kAlpha_8_SkColorType; dstInfo.colorType must match.
-If this->colorType is kGray_8_SkColorType, dstInfo.colorSpace must match.
-If this->alphaType is kOpaque_SkAlphaType, dstInfo.alphaType must
-match. If this->colorSpace is nullptr, dstInfo.colorSpace must match. Returns
+If Bitmap colorType is kGray_8_SkColorType, dstInfo.colorSpace must match.
+If Bitmap alphaType is kOpaque_SkAlphaType, dstInfo.alphaType must
+match. If Bitmap colorSpace 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) >= this->width()
+abs(srcX) >= Bitmap width()
##
, or if
#Formula
-abs(srcY) >= this->height()
+abs(srcY) >= Bitmap height()
##
.
@@ -2876,34 +2876,34 @@
#Method bool readPixels(const SkImageInfo& dstInfo, void* dstPixels, size_t dstRowBytes,
int srcX, int srcY) const
-Copies a Rect of pixels to dstPixels. Copy starts at (srcX, srcY), and does not exceed
-(this->width(), this->height()).
+Copies a Rect of pixels from Bitmap to dstPixels. Copy starts at (srcX, srcY),
+and does not exceed Bitmap (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:
+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 this->colorType is
+Pixels are copied only if pixel conversion is possible. If Bitmap colorType is
kGray_8_SkColorType, or kAlpha_8_SkColorType; dstInfo.colorType must match.
-If this->colorType is kGray_8_SkColorType, dstInfo.colorSpace must match.
-If this->alphaType is kOpaque_SkAlphaType, dstInfo.alphaType must
-match. If this->colorSpace is nullptr, dstInfo.colorSpace must match. Returns
+If Bitmap colorType is kGray_8_SkColorType, dstInfo.colorSpace must match.
+If Bitmap alphaType is kOpaque_SkAlphaType, dstInfo.alphaType must
+match. If Bitmap colorSpace 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) >= this->width()
+abs(srcX) >= Bitmap width()
##
, or if
#Formula
-abs(srcY) >= this->height()
+abs(srcY) >= Bitmap height()
##
.
@@ -2951,8 +2951,8 @@
#Method bool readPixels(const SkPixmap& dst, int srcX, int srcY) const
-Copies a Rect of pixels to dst. Copy starts at (srcX, srcY), and does not exceed
-(this->width(), this->height()).
+Copies a Rect of pixels from Bitmap to dst. Copy starts at (srcX, srcY), and
+does not exceed Bitmap (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
@@ -2963,22 +2963,22 @@
# Pixel_Ref is nullptr ##
##
-Pixels are copied only if pixel conversion is possible. If this->colorType is
+Pixels are copied only if pixel conversion is possible. If Bitmap colorType is
kGray_8_SkColorType, or kAlpha_8_SkColorType; dst Color_Type must match.
-If this->colorType is kGray_8_SkColorType, dst Color_Space must match.
-If this->alphaType is kOpaque_SkAlphaType, dst Alpha_Type must
-match. If this->colorSpace is nullptr, dst Color_Space must match. Returns
+If Bitmap colorType is kGray_8_SkColorType, dst Color_Space must match.
+If Bitmap alphaType is kOpaque_SkAlphaType, dst Alpha_Type must
+match. If Bitmap colorSpace is nullptr, dst Color_Space 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) >= this->width()
+abs(srcX) >= Bitmap width()
##
, or if
#Formula
-abs(srcY) >= this->height()
+abs(srcY) >= Bitmap height()
##
.
@@ -3015,8 +3015,8 @@
#Method bool readPixels(const SkPixmap& dst) const
-Copies a Rect of pixels to dst. Copy starts at (0, 0), and does not exceed
-(this->width(), this->height()).
+Copies a Rect of pixels from Bitmap to dst. Copy starts at (0, 0), and
+does not exceed Bitmap (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
@@ -3027,11 +3027,11 @@
# Pixel_Ref is nullptr ##
##
-Pixels are copied only if pixel conversion is possible. If this->colorType is
+Pixels are copied only if pixel conversion is possible. If Bitmap colorType is
kGray_8_SkColorType, or kAlpha_8_SkColorType; dst Color_Type must match.
-If this->colorType is kGray_8_SkColorType, dst Color_Space must match.
-If this->alphaType is kOpaque_SkAlphaType, dst Alpha_Type must
-match. If this->colorSpace is nullptr, dst Color_Space must match. Returns
+If Bitmap colorType is kGray_8_SkColorType, dst Color_Space must match.
+If Bitmap alphaType is kOpaque_SkAlphaType, dst Alpha_Type must
+match. If Bitmap colorSpace is nullptr, dst Color_Space must match. Returns
false if pixel conversion is not possible.
#Param dst destination Pixmap: Image_Info, pixels, row bytes ##
@@ -3076,22 +3076,22 @@
# Pixel_Ref is nullptr ##
##
-Pixels are copied only if pixel conversion is possible. If this->colorType is
+Pixels are copied only if pixel conversion is possible. If Bitmap colorType is
kGray_8_SkColorType, or kAlpha_8_SkColorType; src Color_Type must match.
-If this->colorType is kGray_8_SkColorType, src Color_Space must match.
-If this->alphaType is kOpaque_SkAlphaType, src Alpha_Type must
-match. If this->colorSpace is nullptr, src Color_Space must match. Returns
+If Bitmap colorType is kGray_8_SkColorType, src Color_Space must match.
+If Bitmap alphaType is kOpaque_SkAlphaType, src Alpha_Type must
+match. If Bitmap colorSpace is nullptr, src Color_Space must match. Returns
false if pixel conversion is not possible.
dstX and dstY 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(dstX) >= this->width()
+abs(dstX) >= Bitmap width()
##
, or if
#Formula
-abs(dstY) >= this->height()
+abs(dstY) >= Bitmap height()
##
.
@@ -3143,11 +3143,11 @@
# Pixel_Ref is nullptr ##
##
-Pixels are copied only if pixel conversion is possible. If this->colorType is
+Pixels are copied only if pixel conversion is possible. If Bitmap colorType is
kGray_8_SkColorType, or kAlpha_8_SkColorType; src Color_Type must match.
-If this->colorType is kGray_8_SkColorType, src Color_Space must match.
-If this->alphaType is kOpaque_SkAlphaType, src Alpha_Type must
-match. If this->colorSpace is nullptr, src Color_Space must match. Returns
+If Bitmap colorType is kGray_8_SkColorType, src Color_Space must match.
+If Bitmap alphaType is kOpaque_SkAlphaType, src Alpha_Type must
+match. If Bitmap colorSpace is nullptr, src Color_Space must match. Returns
false if pixel conversion is not possible.
#Param src source Pixmap: Image_Info, pixels, row bytes ##
@@ -3186,11 +3186,11 @@
# Pixel_Ref is nullptr ##
##
-Pixels are copied only if pixel conversion is possible. If this->colorType is
+Pixels are copied only if pixel conversion is possible. If Bitmap colorType is
kGray_8_SkColorType, or kAlpha_8_SkColorType; src Color_Type must match.
-If this->colorType is kGray_8_SkColorType, src Color_Space must match.
-If this->alphaType is kOpaque_SkAlphaType, src Alpha_Type must
-match. If this->colorSpace is nullptr, src Color_Space must match. Returns
+If Bitmap colorType is kGray_8_SkColorType, src Color_Space must match.
+If Bitmap alphaType is kOpaque_SkAlphaType, src Alpha_Type must
+match. If Bitmap colorSpace is nullptr, src Color_Space must match. Returns
false if pixel conversion is not possible. Returns false if width() or height()
is zero or negative.
@@ -3477,7 +3477,7 @@
macro expands to: void toString(SkString* str) const;
##
-Creates string representation. The representation is read by
+Creates string representation of Bitmap. The representation is read by
internal debugging tools. The interface and implementation may be
suppressed by defining SK_IGNORE_TO_STRING.
diff --git a/docs/SkCanvas_Reference.bmh b/docs/SkCanvas_Reference.bmh
index 2f08ca0..437c2802 100644
--- a/docs/SkCanvas_Reference.bmh
+++ b/docs/SkCanvas_Reference.bmh
@@ -1249,8 +1249,8 @@
#List
# Source and destination rectangles do not intersect. ##
-# pixels could not be converted to this->imageInfo().colorType() or
-this->imageInfo().alphaType(). ##
+# pixels could not be converted to Canvas imageInfo().colorType() or
+ imageInfo().alphaType(). ##
# Canvas pixels are not writable; for instance, Canvas is document-based. ##
# rowBytes is too small to contain one row of pixels. ##
##
@@ -1308,8 +1308,8 @@
#List
# Source and destination rectangles do not intersect. ##
# bitmap does not have allocated pixels. ##
-# bitmap pixels could not be converted to this->imageInfo().colorType() or
-this->imageInfo().alphaType(). ##
+# bitmap pixels could not be converted to Canvas imageInfo().colorType() or
+ imageInfo().alphaType(). ##
# Canvas pixels are not writable; for instance, Canvas is document based. ##
# bitmap pixels are inaccessible; for instance, bitmap wraps a texture. ##
##
diff --git a/docs/SkIRect_Reference.bmh b/docs/SkIRect_Reference.bmh
index a1b62b0..708ac56 100644
--- a/docs/SkIRect_Reference.bmh
+++ b/docs/SkIRect_Reference.bmh
@@ -434,7 +434,9 @@
#Return fRight minus fLeft cast to int64_t ##
-#Example
+#Bug 7489 ##
+# width64 is not yet visible to fiddle
+#NoExample
SkIRect large = { -2147483647, 1, 2147483644, 2 };
SkDebugf("width: %d wdith64: %lld\n", large.width(), large.width64());
#StdOut
@@ -480,7 +482,9 @@
#Return fBottom minus fTop cast to int64_t ##
-#Example
+#Bug 7489 ##
+# height64 not yet visible to fiddle
+#NoExample
SkIRect large = { 1, -2147483647, 2, 2147483644 };
SkDebugf("height: %d height64: %lld\n", large.height(), large.height64());
#StdOut
@@ -620,7 +624,9 @@
#Return true if width64() or height64() are zero or negative ##
-#Example
+#Bug 7489 ##
+# isEmpty64 not yet visible to fiddle
+#NoExample
SkIRect tests[] = {{20, 40, 10, 50}, {20, 40, 20, 50}};
for (auto rect : tests) {
SkDebugf("rect: {%d, %d, %d, %d} is" "%s empty\n", rect.left(), rect.top(), rect.right(),
@@ -1643,6 +1649,11 @@
#Deprecated
##
+Returns constructed SkIRect setting left and top to most negative value, and
+setting right and bottom to most positive value.
+
+#Return bounds (SK_MinS32, SK_MinS32, SK_MaxS32, SK_MaxS32) ##
+
##
#Struct SkIRect ##
diff --git a/docs/SkImage_Reference.bmh b/docs/SkImage_Reference.bmh
index 0d9c98b..ffcd6fe 100644
--- a/docs/SkImage_Reference.bmh
+++ b/docs/SkImage_Reference.bmh
@@ -331,6 +331,7 @@
#Return created Image, or nullptr ##
#Example
+#Height 128
#Description
The generator returning Picture cannot be shared; std::move transfers ownership to generated Image.
##
@@ -390,7 +391,9 @@
SkAlphaType alphaType,
sk_sp<SkColorSpace> colorSpace)
+#Deprecated
Deprecated.
+##
#Param context GPU_Context ##
#Param backendTexture texture residing on GPU ##
@@ -402,11 +405,6 @@
#Return created Image, or nullptr ##
-#NoExample
-##
-
-#SeeAlso MakeFromAdoptedTexture SkSurface::MakeFromBackendTexture
-
#Method ##
# ------------------------------------------------------------------------------
@@ -419,7 +417,9 @@
TextureReleaseProc textureReleaseProc,
ReleaseContext releaseContext)
+#Deprecated
Deprecated.
+##
#Param context GPU_Context ##
#Param backendTexture texture residing on GPU ##
@@ -433,11 +433,6 @@
#Return created Image, or nullptr ##
-#NoExample
-##
-
-#SeeAlso MakeFromAdoptedTexture SkSurface::MakeFromBackendTexture
-
#Method ##
# ------------------------------------------------------------------------------
@@ -484,7 +479,7 @@
canvas->scale(.25f, .25f);
int x = 0;
for (auto origin : { kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin } ) {
- sk_sp<SkImage> image = SkImage::MakeFromTexture(canvas->getGrContext(), backEndTexture,
+ sk_sp<SkImage> image = SkImage::MakeFromTexture(context, backEndTexture,
origin, kOpaque_SkAlphaType, nullptr);
canvas->drawImage(image, x, 0);
x += 512;
@@ -536,16 +531,18 @@
##
#Example
+#Platform gpu
+#Image 4
GrContext* context = canvas->getGrContext();
if (!context) {
return;
}
-auto debugster = [](SkImage::ReleaseContext context) -> void {
- *((int *) context) += 128;
+auto debugster = [](SkImage::ReleaseContext releaseContext) -> void {
+ *((int *) releaseContext) += 128;
};
int x = 0;
for (auto origin : { kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin } ) {
- sk_sp<SkImage> image = SkImage::MakeFromTexture(canvas->getGrContext(), backEndTexture,
+ sk_sp<SkImage> image = SkImage::MakeFromTexture(context, backEndTexture,
origin, kRGBA_8888_SkColorType, kOpaque_SkAlphaType, nullptr, debugster, &x);
canvas->drawImage(image, x, 0);
x += 128;
@@ -589,7 +586,7 @@
#Example
#Image 4
-#Height 128
+#Height 64
GrContext* context = canvas->getGrContext();
sk_sp<SkData> encodedData = image->encodeToData(SkEncodedImageFormat::kJPEG, 100);
sk_sp<SkImage> image = SkImage::MakeCrossContextFromEncoded(context,
@@ -634,7 +631,7 @@
#Example
#Image 4
-#Height 128
+#Height 64
GrContext* context = canvas->getGrContext();
SkPixmap pixmap;
if (source.peekPixels(&pixmap)) {
@@ -706,6 +703,8 @@
#Return created Image, or nullptr ##
#Example
+#Image 5
+#Platform gpu
if (!canvas->getGrContext()) {
return;
}
@@ -998,7 +997,7 @@
#Example
#Image 4
-#Height 168
+#Height 96
canvas->translate(10, 10);
canvas->drawImage(image, 0, 0);
canvas->translate(0, image->height());
@@ -1022,7 +1021,7 @@
#Example
#Image 4
-#Height 148
+#Height 96
canvas->translate(10, 10);
canvas->drawImage(image, 0, 0);
canvas->translate(image->width(), 0);
@@ -1030,7 +1029,8 @@
paint.setTextAlign(SkPaint::kCenter_Align);
paint.setVerticalText(true);
canvas->drawLine(10, 0, 10, image->height(), paint);
- canvas->drawString("height", 25, image->height() / 2, paint);##
+ canvas->drawString("height", 25, image->height() / 2, paint);
+##
#SeeAlso dimensions() width()
@@ -1067,10 +1067,9 @@
#Example
#Height 128
#Image 4
- canvas->scale(.5f, .5f);
SkIRect bounds = image->bounds();
- for (int x : { 0, image->width() } ) {
- for (int y : { 0, image->height() } ) {
+ for (int x : { 0, bounds.width() } ) {
+ for (int y : { 0, bounds.height() } ) {
canvas->drawImage(image, x, y);
}
}
@@ -1122,10 +1121,10 @@
#Example
#Image 4
-#Height 156
+#Height 96
const char* alphaTypeStr[] = { "Unknown", "Opaque", "Premul", "Unpremul" };
SkAlphaType alphaType = image->alphaType();
- canvas->drawImage(image, 0, 0);
+ canvas->drawImage(image, 16, 0);
SkPaint paint;
canvas->drawString(alphaTypeStr[(int) alphaType], 20, image->height() + 20, paint);
##
@@ -1491,10 +1490,10 @@
kBottomLeft_GrSurfaceOrigin; or nullptr
##
-#Return back-end API texture handle ##
+#Return back-end API texture handle, or nullptr ##
#Example
-#Image 3
+#Image 4
#Platform gpu
GrContext* context = canvas->getGrContext();
if (!context) {
@@ -1503,20 +1502,45 @@
SkPaint paint;
paint.setAntiAlias(true);
SkString str;
-int y = 0;
+int y = -10;
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("readBackHandle: 0x%x", readBackHandle);
+ canvas->drawString(str, 5, y += 30, paint);
+ canvas->drawImage(srcImage, 80, y += 10);
str.printf("origin: k%s_GrSurfaceOrigin", readBackOrigin ? "BottomLeft" : "TopLeft");
- canvas->drawString(str, 5, y += 20, paint);
+ canvas->drawString(str, 5, y += srcImage->height() + 10, paint);
}
##
-#SeeAlso incomplete
+#Example
+#Image 5
+#Platform gpu
+ auto drawImage = [=](sk_sp<SkImage> image, const char* label) -> void {
+ if (nullptr == image) {
+ return;
+ }
+ SkPaint paint;
+ paint.setAntiAlias(true);
+ paint.setTextAlign(SkPaint::kCenter_Align);
+ canvas->drawImage(image, 0, image->height() / 4);
+ canvas->drawString(label, image->width() / 2, image->height() / 8, paint);
+ GrSurfaceOrigin readBackOrigin;
+ GrBackendObject readBackHandle = image->getTextureHandle(false, &readBackOrigin);
+ canvas->drawString(readBackHandle ? "has readBackHandle" : "no readBackHandle",
+ image->width() / 2, image->height() * 11 / 8, paint);
+ };
+ drawImage(image, "image");
+ canvas->translate(image->width(), 0);
+ sk_sp<SkImage> textureImage(SkImage::MakeFromTexture(canvas->getGrContext(), backEndTexture,
+ kTopLeft_GrSurfaceOrigin, kOpaque_SkAlphaType, nullptr));
+ drawImage(textureImage, "backEndTexture");
+##
+
+#SeeAlso MakeFromTexture isTextureBacked
#Method ##
@@ -1531,20 +1555,28 @@
};
##
-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.
+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
+Allows Skia to internally cache decoded and copied pixels.
##
#Const kDisallow_CachingHint 1
+Disallows Skia from internally caching decoded and copied pixels.
##
-#Example
-// incomplete
+#NoExample
##
-#SeeAlso incomplete
+#SeeAlso readPixels scalePixels
#Enum ##
@@ -1553,37 +1585,72 @@
#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());
+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 ##
##
-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.
+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.
-#Param dstInfo incomplete ##
-#Param dstPixels incomplete ##
-#Param dstRowBytes incomplete ##
-#Param srcX incomplete ##
-#Param srcY incomplete ##
-#Param cachingHint incomplete ##
+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()
+##
+.
-#Return incomplete ##
+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
-// incomplete
+#Image 3
+ canvas->scale(.5f, .5f);
+ const int width = 32;
+ const int height = 32;
+ std::vector<int32_t> 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 incomplete
+#SeeAlso scalePixels SkBitmap::readPixels SkPixmap::readPixels SkCanvas::readPixels SkSurface::readPixels
#Method ##
@@ -1592,18 +1659,70 @@
#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 ##
+Copies a Rect of pixels from Image to dst. Copy starts at (srcX, srcY), and
+does not exceed Image (width(), height()).
-#Return incomplete ##
-
-#Example
-// incomplete
+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 ##
##
-#SeeAlso incomplete
+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<int32_t> 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 ##
@@ -1612,22 +1731,57 @@
#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.
+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.
-#Param dst incomplete ##
-#Param filterQuality incomplete ##
-#Param cachingHint incomplete ##
+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.
-#Return incomplete ##
+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
-// incomplete
+#Image 3
+#Height 128
+ std::vector<int32_t> 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<SkImage> filtered = SkImage::MakeFromRaster(pixmap, nullptr, nullptr);
+ canvas->drawImage(filtered, 16 * index, 0);
+ }
##
-#SeeAlso incomplete
+#SeeAlso SkCanvas::drawImage readPixels SkPixmap::scalePixels
#Method ##
@@ -1635,20 +1789,43 @@
#Method sk_sp<SkData> encodeToData(SkEncodedImageFormat encodedImageFormat, int quality) const
-Encodes Image pixels, returning result as SkData.
+Encodes Image pixels, returning result as SkData.
-Returns nullptr if encoding fails, or encodedImageFormat is not supported.
+Returns nullptr if encoding fails, or if encodedImageFormat is not supported.
-#Param encodedImageFormat incomplete ##
-#Param quality incomplete ##
+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
-// incomplete
+#Image 3
+ canvas->scale(4, 4);
+ SkIRect subset = {0, 0, 16, 64};
+ int x = 0;
+ for (int quality : { 0, 10, 50, 100 } ) {
+ sk_sp<SkData> data(image->encodeToData(SkEncodedImageFormat::kJPEG, quality));
+ sk_sp<SkImage> filtered = SkImage::MakeFromEncoded(data, &subset);
+ canvas->drawImage(filtered, x, 0);
+ x += 16;
+ }
##
-#SeeAlso incomplete
+#SeeAlso refEncodedData MakeFromEncoded
#Method ##
@@ -1656,20 +1833,25 @@
#Method sk_sp<SkData> encodeToData() const
-Encodes Image and returns result as SkData. Will reuse existing encoded data
-if present, as returned by refEncodedData. If encoded data is missing or invalid,
-Image is encoded as PNG.
+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
+Returns nullptr if existing encoded data is missing or invalid, and
encoding fails.
-#Return incomplete ##
+#Return encoded Image, or nullptr ##
#Example
-// incomplete
+#Image 3
+ canvas->scale(4, 4);
+ SkIRect subset = {136, 32, 200, 96};
+ sk_sp<SkData> data(image->encodeToData());
+ sk_sp<SkImage> eye = SkImage::MakeFromEncoded(data, &subset);
+ canvas->drawImage(eye, 0, 0);
##
-#SeeAlso incomplete
+#SeeAlso refEncodedData MakeFromEncoded
#Method ##
@@ -1677,18 +1859,37 @@
#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.
+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.
-To force the image to return its contents as encoded data, call encodeToData.
+Returns nullptr if Image contents are not encoded.
-#Return incomplete ##
+#Return encoded Image, or nullptr ##
#Example
-// incomplete
+#Image 3
+#Platform gpu
+ struct {
+ const char* name;
+ sk_sp<SkImage> image;
+ } tests[] = { { "image", image }, { "bitmap", SkImage::MakeFromBitmap(source) },
+ { "texture", SkImage::MakeFromTexture(canvas->getGrContext(), backEndTexture,
+ kTopLeft_GrSurfaceOrigin, 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 incomplete
+#SeeAlso encodeToData MakeFromEncoded
#Method ##
@@ -1696,15 +1897,32 @@
#Method const char* toString(SkString* string) const
-#Param string incomplete ##
+Appends Image description to string, including unique ID, width, height, and
+whether the image is opaque.
-#Return incomplete ##
+#Param string storage for description; existing content is preserved ##
+
+#Return string appended with Image description ##
#Example
-// incomplete
+#Image 4
+ struct {
+ const char* name;
+ sk_sp<SkImage> image;
+ } tests[] = { { "image", image }, { "bitmap", SkImage::MakeFromBitmap(source) },
+ { "texture", SkImage::MakeFromTexture(canvas->getGrContext(), backEndTexture,
+ kTopLeft_GrSurfaceOrigin, kOpaque_SkAlphaType, nullptr) } };
+ SkString string;
+ SkPaint paint;
+ for (const auto& test : tests ) {
+ string.printf("%s: ", test.name);
+ test.image ? (void) test.image->toString(&string) : string.append("no image");
+ canvas->drawString(string, 10, 20, paint);
+ canvas->translate(0, 20);
+ }
##
-#SeeAlso incomplete
+#SeeAlso SkPaint::toString
#Method ##
@@ -1712,20 +1930,30 @@
#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.
+Returns subset of Image. subset must be fully contained by Image dimensions().
+The implementation may share pixels, or may copy them.
-#Param subset incomplete ##
+Returns nullptr if subset is empty, or subset is not contained by bounds, or
+pixels in Image could not be read or copied.
-#Return incomplete ##
+#Param subset bounds of returned Image ##
+
+#Return partial or full Image, or nullptr ##
#Example
-// incomplete
+#Image 3
+ canvas->scale(.5f, .5f);
+ const int width = 32;
+ const int height = 32;
+ for (int y = 0; y < 512; y += height ) {
+ for (int x = 0; x < 512; x += width ) {
+ sk_sp<SkImage> subset(image->makeSubset({x, y, x + width, y + height}));
+ canvas->drawImage(subset, x * 3 / 2, y * 3 / 2);
+ }
+ }
##
-#SeeAlso incomplete
+#SeeAlso MakeFromEncoded
#Method ##
@@ -1733,21 +1961,44 @@
#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.
+Returns Image backed by GPU_Texture associated with context. Returned Image is
+compatible with Surface created with dstColorSpace. Returns original
+Image if context and dstColorSpace match.
+
+Returns nullptr if context is nullptr, or if Image was created with another
+GrContext.
#Param context GPU_Context ##
-#Param dstColorSpace incomplete ##
+#Param dstColorSpace range of colors of matching Surface on GPU ##
-#Return incomplete ##
+#Return created Image, or nullptr ##
#Example
-// incomplete
+#Platform gpu
+#Image 5
+ auto drawImage = [=](sk_sp<SkImage> 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<SkImage> texture(image->makeTextureImage(context, nullptr));
+ canvas->drawImage(texture, 0, 0);
+ canvas->drawString(label, texture->width() / 2, texture->height() / 4, paint);
+ };
+ sk_sp<SkImage> bitmapImage(SkImage::MakeFromBitmap(source));
+ GrContext* context = canvas->getGrContext();
+ sk_sp<SkImage> textureImage(SkImage::MakeFromTexture(context, backEndTexture,
+ kTopLeft_GrSurfaceOrigin, 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 incomplete
+#SeeAlso MakeFromTexture
#Method ##
@@ -1755,13 +2006,36 @@
#Method sk_sp<SkImage> makeNonTextureImage() const
-Creates raster Image if Image contains GPU_Texture and raster Image , this will make a raster copy of it (or nullptr if reading back
-the pixels fails). Otherwise, it returns the original image.
+Returns Raster_Image or Lazy_Image. Copies Image backed by GPU_Texture into
+CPU memory if needed. Returns original Image if unencoded in Raster_Bitmap,
+or if encoded in a stream.
-#Return incomplete ##
+Returns nullptr if backed by GPU_Texture and copy fails.
+
+#Return Raster_Image, Lazy_Image, or nullptr ##
#Example
-// incomplete
+#Image 5
+#Platform gpu
+ auto drawImage = [=](sk_sp<SkImage> image, const char* label) -> void {
+ if (nullptr == image) {
+ return;
+ }
+ SkPaint paint;
+ paint.setAntiAlias(true);
+ paint.setTextAlign(SkPaint::kCenter_Align);
+ sk_sp<SkImage> nonTexture(image->makeNonTextureImage());
+ canvas->drawImage(nonTexture, 0, 0);
+ canvas->drawString(label, nonTexture->width() / 2, nonTexture->height() / 4, paint);
+ };
+ sk_sp<SkImage> bitmapImage(SkImage::MakeFromBitmap(source));
+ sk_sp<SkImage> textureImage(SkImage::MakeFromTexture(canvas->getGrContext(), backEndTexture,
+ kTopLeft_GrSurfaceOrigin, kOpaque_SkAlphaType, nullptr));
+ drawImage(image, "image");
+ canvas->translate(image->width(), 0);
+ drawImage(bitmapImage, "source");
+ canvas->translate(-image->width(), image->height());
+ drawImage(textureImage, "backEndTexture");
##
#SeeAlso incomplete
@@ -1772,16 +2046,40 @@
#Method sk_sp<SkImage> makeRasterImage() 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.
+Returns Raster_Image. Copies Image backed by GPU_Texture into CPU memory,
+or decodes Image from Lazy_Image. Returns original Image if unencoded in
+Raster_Bitmap.
-#Return incomplete ##
+Returns nullptr if copy, decode, or pixel read fails.
+#Return Raster_Image, or nullptr ##
+
+#Bug 7479 ##
#Example
-// incomplete
+#Image 5
+#Platform gpu
+ auto drawImage = [=](sk_sp<SkImage> image, const char* label) -> void {
+ if (nullptr == image) {
+ return;
+ }
+ SkPaint paint;
+ paint.setAntiAlias(true);
+ paint.setTextAlign(SkPaint::kCenter_Align);
+ sk_sp<SkImage> raster(image->makeRasterImage());
+ canvas->drawImage(raster, 0, 0);
+ canvas->drawString(label, raster->width() / 2, raster->height() / 4, paint);
+ };
+ sk_sp<SkImage> bitmapImage(SkImage::MakeFromBitmap(source));
+ sk_sp<SkImage> textureImage(SkImage::MakeFromTexture(canvas->getGrContext(), backEndTexture,
+ kTopLeft_GrSurfaceOrigin, kOpaque_SkAlphaType, nullptr));
+ drawImage(image, "image");
+ canvas->translate(image->width(), 0);
+ drawImage(bitmapImage, "source");
+ canvas->translate(-image->width(), image->height());
+ drawImage(textureImage, "backEndTexture");
##
-#SeeAlso incomplete
+#SeeAlso isTextureBacked isLazyGenerated MakeFromRaster
#Method ##
@@ -1791,29 +2089,61 @@
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.
+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.
-#Param filter incomplete ##
+Returns nullptr if Image could not be created. If nullptr is returned, outSubset
+and offset are undefined.
+
+makeWithFilter is optimized to support Image backed by GPU_Texture drawn in an
+animation with SkImageFilter that vary in size from one frame to the next. The
+created Image is drawn at an increased size so that GPU_Texture can be reused
+with different sized effects. outSubset describes the valid bounds of GPU_Texture
+returned. The returned Image may be much larger than required for the filter.
+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 incomplete ##
#Param clipBounds incomplete ##
#Param outSubset incomplete ##
#Param offset incomplete ##
-#Return incomplete ##
+#Return filtered Image, or nullptr ##
#Example
-// incomplete
+#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<SkImageFilter> shadowFilter = SkDropShadowImageFilter::Make(
+ -10.0f * frame, 5.0f * frame, 3.0f, 3.0f, SK_ColorBLUE,
+ SkDropShadowImageFilter::kDrawShadowAndForeground_ShadowMode,
+ nullptr);
+ sk_sp<SkImageFilter> 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<SkImage> 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::MakeFromIRect(outSubset), paint);
##
-#SeeAlso incomplete
+#SeeAlso SkPaint::setImageFilter
#Method ##
@@ -1821,6 +2151,8 @@
#Struct DeferredTextureImageUsageParams
+Used only by Chrome; to be deprecated.
+
#Code
struct DeferredTextureImageUsageParams {
DeferredTextureImageUsageParams(const SkMatrix matrix, const SkFilterQuality quality,
@@ -1872,6 +2204,8 @@
SkColorSpace* dstColorSpace = nullptr,
SkColorType dstColorType = kN32_SkColorType) const
+Used only by Chrome; to be deprecated.
+
This method allows clients to capture the data necessary to turn a SkImage into a texture-
backed image. If the original image is codec-backed this will decode into a format optimized
for the context represented by the proxy. This method is thread safe with respect to the
@@ -1891,35 +2225,55 @@
provided buffer (assuming this is an appropriate candidate image and the buffer is
appropriately aligned). Upon success the size written is returned, otherwise 0.
-dstColorSpace is the color space of the surface where this texture will ultimately be used.
+dstColorSpace is the Color_Space of the surface where this texture will ultimately be used.
If the method determines that mip-maps are needed, this helps determine the correct strategy
for building them (gamma-correct or not).
dstColorType is the color type of the surface where this texture will ultimately be used.
This determines the format with which the image will be uploaded to the GPU. If dstColorType
-does not support color spaces (low bit depth types such as kARGB_4444_SkColorType),
+does not support Color_Space (low bit depth types such as kARGB_4444_SkColorType),
then dstColorSpace must be null.
-#Param contextThreadSafeProxy incomplete ##
-#Param deferredTextureImageUsageParams incomplete ##
-#Param paramCnt incomplete ##
-#Param buffer incomplete ##
-#Param dstColorSpace incomplete ##
-#Param dstColorType incomplete ##
+#Param contextThreadSafeProxy thread safe GPU context ##
+#Param deferredTextureImageUsageParams array of Image transformations ##
+#Param paramCnt entries in deferredTextureImageUsageParams array ##
+#Param buffer storage for GPU_Texture data, or nullptr ##
+#Param dstColorSpace Surface Color_Space, or nullptr ##
+#Param dstColorType Surface Color_Type ##
-#Return incomplete ##
+#Return size of storage for GPU_Texture data ##
#Example
-// incomplete
+#Image 5
+#Platform gpu
+ GrContext* context = canvas->getGrContext();
+ if (!context) {
+ return;
+ }
+ sk_sp<GrContextThreadSafeProxy> proxy(context->threadSafeProxy());
+ auto params = SkImage::DeferredTextureImageUsageParams(SkMatrix::MakeScale(2, 2),
+ kNone_SkFilterQuality, 0);
+ SkColorSpace* colorSpace = canvas->imageInfo().colorSpace();
+ size_t requiredMemoryInBytes = image->getDeferredTextureImageData(
+ *proxy, ¶ms, 1, nullptr, colorSpace);
+ std::vector<uint8_t> memory;
+ memory.resize(requiredMemoryInBytes);
+ image->getDeferredTextureImageData(*proxy, ¶ms, 1, memory.data(), colorSpace);
+ sk_sp<SkImage> uploadedEncodedImage = SkImage::MakeFromDeferredTextureImageData(
+ context, memory.data(), SkBudgeted::kNo);
+ canvas->scale(2, 2);
+ canvas->drawImage(uploadedEncodedImage, 10, 10);
##
-#SeeAlso incomplete
+#SeeAlso MakeFromDeferredTextureImageData
##
#Method static sk_sp<SkImage> MakeFromDeferredTextureImageData(GrContext* context, const void* data,
SkBudgeted budgeted)
+Used only by Chrome; to be deprecated.
+
Returns a texture-backed image from data produced in SkImage::getDeferredTextureImageData.
The context must be the context that provided the proxy passed to
getDeferredTextureImageData.
@@ -2010,10 +2364,10 @@
#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.
+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 ##
@@ -2097,7 +2451,7 @@
}
##
-#SeeAlso incomplete
+#SeeAlso isTextureBacked MakeNonTextureImage
#Method ##
@@ -2106,29 +2460,48 @@
#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.
+Creates Image in target Color_Space.
+Returns nullptr if Image could not be created.
-If premulBehavior is SkTransferFunctionBehavior::kRespect: converts Image
-pixels to a linear space before converting to match destination Color_Type
+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.
+
+SkTransferFunctionBehavior is to be deprecated.
+
+Set premulBehavior to SkTransferFunctionBehavior::kRespect to convert Image
+pixels to a linear space, before converting to 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 ##
+Set premulBehavior to SkTransferFunctionBehavior::kIgnore to treat Image
+pixels as linear, when converting to destination Color_Type
+and Color_Space, ignoring pixel encoding.
-#Return incomplete ##
-
-#Example
-// incomplete
+#Param target Color_Space describing color range of returned Image ##
+#Param premulBehavior one of: SkTransferFunctionBehavior::kRespect,
+ SkTransferFunctionBehavior::kIgnore
##
-#SeeAlso incomplete
+#Return created Image in target Color_Space ##
+
+#Example
+#Image 5
+#Set sRGB
+ sk_sp<SkColorSpace> normalColorSpace = SkColorSpace::MakeRGB(
+ SkColorSpace::kSRGB_RenderTargetGamma, SkColorSpace::kSRGB_Gamut);
+ sk_sp<SkColorSpace> wackyColorSpace = normalColorSpace->makeColorSpin();
+ for (auto colorSpace : { normalColorSpace, wackyColorSpace } ) {
+ for (auto transfer : { SkTransferFunctionBehavior::kRespect,
+ SkTransferFunctionBehavior::kIgnore } ) {
+ sk_sp<SkImage> colorSpaced = image->makeColorSpace(colorSpace, transfer);
+ canvas->drawImage(colorSpaced, 0, 0);
+ canvas->translate(128, 0);
+ }
+ canvas->translate(-256, 128);
+ }
+##
+
+#SeeAlso MakeFromPixture MakeFromTexture
#Method ##
diff --git a/docs/SkPath_Reference.bmh b/docs/SkPath_Reference.bmh
index 2626726..7f77b8b 100644
--- a/docs/SkPath_Reference.bmh
+++ b/docs/SkPath_Reference.bmh
@@ -740,7 +740,7 @@
Copy Verb_Array and Weights to out, and set out Point_Array to a weighted
average of this Point_Array and ending Point_Array, using the formula:
#Formula
-(this->points * weight) + ending->points * (1 - weight)
+(Path Point * weight) + ending Point * (1 - weight)
##
.
diff --git a/docs/SkPixmap_Reference.bmh b/docs/SkPixmap_Reference.bmh
index e06f7090..c2b9866 100644
--- a/docs/SkPixmap_Reference.bmh
+++ b/docs/SkPixmap_Reference.bmh
@@ -1511,29 +1511,29 @@
int srcX, int srcY, SkTransferFunctionBehavior behavior) const
Copies a Rect of pixels to dstPixels. Copy starts at (srcX, srcY), and does not
-exceed (this->width(), this->height()).
+exceed Pixmap (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
dstInfo.addr() equals nullptr, or dstRowBytes is less than dstInfo.minRowBytes.
-Pixels are copied only if pixel conversion is possible. If this->colorType is
+Pixels are copied only if pixel conversion is possible. If Pixmap colorType is
kGray_8_SkColorType, or kAlpha_8_SkColorType; dstInfo.colorType must match.
-If this->colorType is kGray_8_SkColorType, dstInfo.colorSpace must match.
-If this->alphaType is kOpaque_SkAlphaType, dstInfo.alphaType must
-match. If this->colorSpace is nullptr, dstInfo.colorSpace must match. Returns
+If Pixmap colorType is kGray_8_SkColorType, dstInfo.colorSpace must match.
+If Pixmap alphaType is kOpaque_SkAlphaType, dstInfo.alphaType must
+match. If Pixmap colorSpace 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) >= this->width()
+abs(srcX) >= Pixmap width()
##
, or if
#Formula
-abs(srcY) >= this->height()
+abs(srcY) >= Pixmap height()
##
.
@@ -1589,21 +1589,21 @@
#Method bool readPixels(const SkImageInfo& dstInfo, void* dstPixels, size_t dstRowBytes) const
Copies a Rect of pixels to dstPixels. Copy starts at (0, 0), and does not
-exceed (this->width(), this->height()).
+exceed Pixmap (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
dstInfo.addr() equals nullptr, or dstRowBytes is less than dstInfo.minRowBytes.
-Pixels are copied only if pixel conversion is possible. If this->colorType is
+Pixels are copied only if pixel conversion is possible. If Pixmap colorType is
kGray_8_SkColorType, or kAlpha_8_SkColorType; dstInfo.colorType must match.
-If this->colorType is kGray_8_SkColorType, dstInfo.colorSpace must match.
-If this->alphaType is kOpaque_SkAlphaType, dstInfo.alphaType must
-match. If this->colorSpace is nullptr, dstInfo.colorSpace must match. Returns
+If Pixmap colorType is kGray_8_SkColorType, dstInfo.colorSpace must match.
+If Pixmap alphaType is kOpaque_SkAlphaType, dstInfo.alphaType must
+match. If Pixmap colorSpace is nullptr, dstInfo.colorSpace must match. Returns
false if pixel conversion is not possible.
-Returns false if this->width() or this->height() is zero or negative.
+Returns false if Pixmap width() or height() is zero or negative.
#Param dstInfo destination width, height, Color_Type, Alpha_Type, Color_Space ##
#Param dstPixels destination pixel storage ##
@@ -1652,29 +1652,29 @@
int srcY) const
Copies a Rect of pixels to dstPixels. Copy starts at (srcX, srcY), and does not
-exceed (this->width(), this->height()).
+exceed Pixmap (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
dstInfo.addr() equals nullptr, or dstRowBytes is less than dstInfo.minRowBytes.
-Pixels are copied only if pixel conversion is possible. If this->colorType is
+Pixels are copied only if pixel conversion is possible. If Pixmap colorType is
kGray_8_SkColorType, or kAlpha_8_SkColorType; dstInfo.colorType must match.
-If this->colorType is kGray_8_SkColorType, dstInfo.colorSpace must match.
-If this->alphaType is kOpaque_SkAlphaType, dstInfo.alphaType must
-match. If this->colorSpace is nullptr, dstInfo.colorSpace must match. Returns
+If Pixmap colorType is kGray_8_SkColorType, dstInfo.colorSpace must match.
+If Pixmap alphaType is kOpaque_SkAlphaType, dstInfo.alphaType must
+match. If Pixmap colorSpace 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 this->width() or this->height() is zero or negative. Returns false if:
+false if Pixmap width() or height() is zero or negative. Returns false if:
#Formula
-abs(srcX) >= this->width()
+abs(srcX) >= Pixmap width()
##
, or if
#Formula
-abs(srcY) >= this->height()
+abs(srcY) >= Pixmap height()
##
.
@@ -1717,27 +1717,27 @@
#Method bool readPixels(const SkPixmap& dst, int srcX, int srcY) const
Copies a Rect of pixels to dst. Copy starts at (srcX, srcY), and does not
-exceed (this->width(), this->height()). dst specifies width, height, Color_Type,
+exceed Pixmap (width(), height()). dst specifies width, height, Color_Type,
Alpha_Type, and Color_Space of destination. Returns true if pixels are copied.
Returns false if dst.addr() equals nullptr, or dst.rowBytes is less than
dst SkImageInfo::minRowBytes.
-Pixels are copied only if pixel conversion is possible. If this->colorType is
+Pixels are copied only if pixel conversion is possible. If Pixmap colorType is
kGray_8_SkColorType, or kAlpha_8_SkColorType; dst.info().colorType must match.
-If this->colorType is kGray_8_SkColorType, dst.info().colorSpace must match.
-If this->alphaType is kOpaque_SkAlphaType, dst.info().alphaType must
-match. If this->colorSpace is nullptr, dst.info().colorSpace must match. Returns
+If Pixmap colorType is kGray_8_SkColorType, dst.info().colorSpace must match.
+If Pixmap alphaType is kOpaque_SkAlphaType, dst.info().alphaType must
+match. If Pixmap colorSpace is nullptr, dst.info().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 this->width() or this->height() is zero or negative. Returns false if:
+false Pixmap width() or height() is zero or negative. Returns false if:
#Formula
-abs(srcX) >= this->width()
+abs(srcX) >= Pixmap width()
##
, or if
#Formula
-abs(srcY) >= this->height()
+abs(srcY) >= Pixmap height()
##
.
@@ -1782,14 +1782,14 @@
Returns false if dst.addr() equals nullptr, or dst.rowBytes is less than
dst SkImageInfo::minRowBytes.
-Pixels are copied only if pixel conversion is possible. If this->colorType is
+Pixels are copied only if pixel conversion is possible. If Pixmap colorType is
kGray_8_SkColorType, or kAlpha_8_SkColorType; dst Color_Type must match.
-If this->colorType is kGray_8_SkColorType, dst Color_Space must match.
-If this->alphaType is kOpaque_SkAlphaType, dst Alpha_Type must
-match. If this->colorSpace is nullptr, dst Color_Space must match. Returns
+If Pixmap colorType is kGray_8_SkColorType, dst Color_Space must match.
+If Pixmap alphaType is kOpaque_SkAlphaType, dst Alpha_Type must
+match. If Pixmap colorSpace is nullptr, dst Color_Space must match. Returns
false if pixel conversion is not possible.
-Returns false if this->width() or this->height() is zero or negative.
+Returns false if Pixmap width() or height() is zero or negative.
#Param dst Image_Info and pixel address to write to ##
@@ -1825,19 +1825,19 @@
#Method bool scalePixels(const SkPixmap& dst, SkFilterQuality filterQuality) const
-Copies this to dst, scaling pixels to fit dst.width() and dst.height(), and
+Copies Bitmap 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 this->colorType is
+Pixels are copied only if pixel conversion is possible. If Pixmap colorType is
kGray_8_SkColorType, or kAlpha_8_SkColorType; dst Color_Type must match.
-If this->colorType is kGray_8_SkColorType, dst Color_Space must match.
-If this->alphaType is kOpaque_SkAlphaType, dst Alpha_Type must
-match. If this->colorSpace is nullptr, dst Color_Space must match. Returns
+If Pixmap colorType is kGray_8_SkColorType, dst Color_Space must match.
+If Pixmap alphaType is kOpaque_SkAlphaType, dst Alpha_Type must
+match. If Pixmap colorSpace is nullptr, dst Color_Space must match. Returns
false if pixel conversion is not possible.
-Returns false if this->width() or this->height() is zero or negative.
+Returns false if Bitmap width() or height() is zero or negative.
Scales the image, with filterQuality, to match dst.width() and dst.height().
filterQuality kNone_SkFilterQuality is fastest, typically implemented with
@@ -1851,7 +1851,7 @@
kMedium_SkFilterQuality, kHigh_SkFilterQuality
##
-#Return true if pixels are copied to dst ##
+#Return true if pixels are scaled to fit dst ##
#Example
#Image 3
diff --git a/docs/SkRect_Reference.bmh b/docs/SkRect_Reference.bmh
index ddebdb1..7aeb90e 100644
--- a/docs/SkRect_Reference.bmh
+++ b/docs/SkRect_Reference.bmh
@@ -2131,6 +2131,11 @@
#Deprecated
##
+Returns constructed SkRect setting left and top to most negative finite value, and
+setting right and bottom to most positive finite value.
+
+#Return bounds (SK_ScalarMin, SK_ScalarMin, SK_ScalarMax, SK_ScalarMax) ##
+
##
#Struct SkRect ##
diff --git a/docs/SkSurface_Reference.bmh b/docs/SkSurface_Reference.bmh
index 1721507..3ab33c7 100644
--- a/docs/SkSurface_Reference.bmh
+++ b/docs/SkSurface_Reference.bmh
@@ -1392,7 +1392,7 @@
Copies Rect of pixels to dst.
-Source Rect corners are (srcX, srcY) and (this->width(), this->height()).
+Source Rect corners are (srcX, srcY) and Surface (width(), height()).
Destination Rect corners are (0, 0) and (dst.width(), dst.height()).
Copies each readable pixel intersecting both rectangles, without scaling,
converting to dst.colorType() and dst.alphaType() if required.
@@ -1451,7 +1451,7 @@
Copies Rect of pixels from Canvas into dstPixels.
-Source Rect corners are (srcX, srcY) and (this->width(), this->height()).
+Source Rect corners are (srcX, srcY) and Surface (width(), height()).
Destination Rect corners are (0, 0) and (dstInfo.width(), dstInfo.height()).
Copies each readable pixel intersecting both rectangles, without scaling,
converting to dstInfo.colorType() and dstInfo.alphaType() if required.
@@ -1516,7 +1516,7 @@
Copies Rect of pixels from Surface into bitmap.
-Source Rect corners are (srcX, srcY) and (this->width(), this->height()).
+Source Rect corners are (srcX, srcY) and Surface (width(), height()).
Destination Rect corners are (0, 0) and (bitmap.width(), bitmap.height()).
Copies each readable pixel intersecting both rectangles, without scaling,
converting to bitmap.colorType() and bitmap.alphaType() if required.
diff --git a/docs/undocumented.bmh b/docs/undocumented.bmh
index 6aff887..20b9252 100644
--- a/docs/undocumented.bmh
+++ b/docs/undocumented.bmh
@@ -26,8 +26,13 @@
SK_USE_FREETYPE_EMBOLDEN # ditto
SK_SUPPORT_LEGACY_PAINT_TEXTDECORATION # ditto
SK_BUILD_FOR_ANDROID_FRAMEWORK # ditto
+ SK_BUILD_FOR_MAC # ditto
+ SK_BUILD_FOR_IOS # ditto
SK_IGNORE_TO_STRING # ditto
SK_SUPPORT_GPU # ditto
+ SK_HAS_JPEG_LIBRARY # ditto
+ SK_HAS_PNG_LIBRARY # ditto
+ SK_HAS_WEBP_LIBRARY # ditto
# FreeType related
FT_LOAD_TARGET_LIGHT
@@ -243,6 +248,37 @@
##
#Topic ##
+#Topic Encoded_Image_Format
+#EnumClass SkEncodedImageFormat
+ #Const kUnknown 0
+ ##
+ #Const kBMP 1
+ ##
+ #Const kGIF 2
+ ##
+ #Const kICO 3
+ ##
+ #Const kJPEG 4
+ ##
+ #Const kPNG 5
+ ##
+ #Const kWBMP 6
+ ##
+ #Const kWEBP 7
+ ##
+ #Const kPKM 8
+ ##
+ #Const kKTX 9
+ ##
+ #Const kASTC 10
+ ##
+ #Const kDNG 11
+ ##
+ #Const kHEIF 12
+ ##
+##
+#Topic ##
+
#Topic Filter_Quality
#Enum SkFilterQuality
#Const kNone_SkFilterQuality 0
diff --git a/docs/usingBookmaker.bmh b/docs/usingBookmaker.bmh
index 170a5a7..d123bc7 100644
--- a/docs/usingBookmaker.bmh
+++ b/docs/usingBookmaker.bmh
@@ -11,6 +11,8 @@
#Topic Bookmaker
+How to use the Bookmaker utility.
+
#Subtopic Broken_Build
If the
@@ -24,6 +26,20 @@
For instance, if the change was made to SkIRect, edit docs/SkIRect_Reference.bmh.
Checking in the edited docs/SkIRect_Reference.bmh will fix the bot.
+If the interface is deprecated, but still present in the interface, mark-up the
+documentation to be deprecated as well.
+
+#Code
+###$
+#Method void someMethodThatIsNowDeprecated()
+
+#Deprecated
+##
+
+##
+$$$#
+##
+
To regenerate the documentation, follow the Installing and Regenerate steps below.
If the
@@ -71,7 +87,25 @@
#Subtopic Editing_Comments ##
-How to use the Bookmaker utility.
+#Subtopic Broken_Example
+
+An example may cause Bookmaker or a bot running Bookmaker to fail if it can't
+be compiled by fiddle. If the example cannot be fixed, it can be commented out
+by changing
+###$
+$Code
+$Literal
+#Example
+$Code $$
+to
+$Code
+#NoExample
+$Code $$
+$$$#
+. The disabled example can contain additional markup,
+which will be ignored.
+
+#Subtopic Broken_Example ##
#Subtopic Installing