aboutsummaryrefslogtreecommitdiffhomepage
path: root/include
diff options
context:
space:
mode:
authorGravatar Cary Clark <caryclark@skia.org>2018-02-27 10:22:04 -0500
committerGravatar Skia Commit-Bot <skia-commit-bot@chromium.org>2018-02-27 16:37:39 +0000
commit75959391681495896570e7bf8d7f9effdd1306f3 (patch)
tree594062af925906eafd1fd84f788c37fba7e82ac2 /include
parent1991f5502edef073a005d6efbbc710d8c72f1a8a (diff)
updated includes
update includes to latest bookmaker docs TBR=reed@google.com Bug: skia:6898 Change-Id: If42ab25f98a0f0d8b410ae30ca1cd641e19ce89f Reviewed-on: https://skia-review.googlesource.com/107021 Commit-Queue: Cary Clark <caryclark@skia.org> Reviewed-by: Cary Clark <caryclark@skia.org>
Diffstat (limited to 'include')
-rw-r--r--include/core/SkBitmap.h120
-rw-r--r--include/core/SkCanvas.h84
-rw-r--r--include/core/SkImage.h1031
-rw-r--r--include/core/SkMatrix.h58
-rw-r--r--include/core/SkPaint.h25
-rw-r--r--include/core/SkPath.h151
-rw-r--r--include/core/SkPixmap.h179
-rw-r--r--include/core/SkPoint.h21
-rw-r--r--include/core/SkRect.h191
-rw-r--r--include/core/SkSurface.h852
10 files changed, 1699 insertions, 1013 deletions
diff --git a/include/core/SkBitmap.h b/include/core/SkBitmap.h
index 1ab9bf2984..b7471e5bc7 100644
--- a/include/core/SkBitmap.h
+++ b/include/core/SkBitmap.h
@@ -102,7 +102,7 @@ public:
/** Returns a constant reference to the SkPixmap holding the SkBitmap pixel
address, row bytes, and SkImageInfo.
- @return reference to SkPixmap describing this SkBitmap.
+ @return reference to SkPixmap describing this SkBitmap
*/
const SkPixmap& pixmap() const { return fPixmap; }
@@ -638,17 +638,7 @@ public:
*/
bool installPixels(const SkPixmap& pixmap);
- /** Sets SkImageInfo to mask width, mask height, kAlpha_8_SkColorType, and
- kPremul_SkAlphaType. Sets SkPixelRef to mask image and mask rowBytes().
-
- Returns false and calls reset() if mask format is not SkMask::kA8_Format,
- or if mask width or mask height is negative, or if mask rowBytes() is less
- than mask width.
-
- Caller must ensure that mask is valid for the lifetime of SkBitmap and SkPixelRef.
-
- @param mask alpha 8-bit bitmap
- @return true if SkImageInfo and SkPixelRef refer to mask
+ /** To be deprecated soon.
*/
bool installMaskPixels(const SkMask& mask);
@@ -691,7 +681,7 @@ public:
The allocation size is determined by SkImageInfo width, height, and SkColorType.
If allocator is nullptr, use HeapAllocator instead.
- Returns false if allocator allocPixelRef return false.
+ Returns false if Allocator::allocPixelRef return false.
@param allocator instance of SkBitmap::Allocator instantiation
@return true if custom allocator reports success
@@ -702,7 +692,7 @@ public:
The allocation size is determined by SkImageInfo width, height, and SkColorType.
If allocator is nullptr, use HeapAllocator instead.
- Aborts if allocator allocPixelRef return false. Abort steps may be provided by
+ Aborts if Allocator::allocPixelRef return false. Abort steps may be provided by
the user at compile time by defining SK_ABORT.
@param allocator instance of SkBitmap::Allocator instantiation
@@ -818,7 +808,7 @@ public:
*/
void erase(SkColor c, const SkIRect& area) const;
- /** Legacy call to be deprecated.
+ /** Deprecated.
*/
void eraseArea(const SkIRect& area, SkColor c) const {
this->erase(c, area);
@@ -921,8 +911,8 @@ public:
*/
bool extractSubset(SkBitmap* dst, const SkIRect& subset) const;
- /** Copies a SkRect of pixels to dstPixels. Copy starts at (srcX, srcY), and does not exceed
- (this->width(), this->height()).
+ /** Copies SkRect of pixels from SkBitmap pixels to dstPixels. Copy starts at (srcX, srcY),
+ and does not exceed SkBitmap (width(), height()).
dstInfo specifies width, height, SkColorType, SkAlphaType, and
SkColorSpace of destination. dstRowBytes specifics the gap from one destination
@@ -931,16 +921,16 @@ public:
- dstRowBytes is less than dstInfo.minRowBytes()
- SkPixelRef 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 SkBitmap 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 SkBitmap colorType() is kGray_8_SkColorType, dstInfo.colorSpace() must match.
+ If SkBitmap alphaType() is kOpaque_SkAlphaType, dstInfo.alphaType() must
+ match. If SkBitmap 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 abs(srcX) >= this->width(), or if abs(srcY) >= this->height().
+ Returns false if abs(srcX) >= Bitmap width(), or if abs(srcY) >= Bitmap height().
If behavior is SkTransferFunctionBehavior::kRespect: converts source
pixels to a linear space before converting to dstInfo.
@@ -959,26 +949,26 @@ public:
bool readPixels(const SkImageInfo& dstInfo, void* dstPixels, size_t dstRowBytes,
int srcX, int srcY, SkTransferFunctionBehavior behavior) const;
- /** Copies a SkRect of pixels to dstPixels. Copy starts at (srcX, srcY), and does not exceed
- (this->width(), this->height()).
+ /** Copies a SkRect of pixels from SkBitmap to dstPixels. Copy starts at (srcX, srcY),
+ and does not exceed SkBitmap (width(), height()).
- dstInfo specifies width, height, SkColorType, SkAlphaType, and
- SkColorSpace 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, SkColorType, SkAlphaType, and SkColorSpace 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
- dstRowBytes is less than dstInfo.minRowBytes()
- SkPixelRef 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 SkBitmap 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 SkBitmap colorType() is kGray_8_SkColorType, dstInfo.colorSpace() must match.
+ If SkBitmap alphaType() is kOpaque_SkAlphaType, dstInfo.alphaType() must
+ match. If SkBitmap 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 abs(srcX) >= this->width(), or if abs(srcY) >= this->height().
+ Returns false if abs(srcX) >= Bitmap width(), or if abs(srcY) >= Bitmap height().
@param dstInfo destination width, height, SkColorType, SkAlphaType, SkColorSpace
@param dstPixels destination pixel storage
@@ -993,8 +983,8 @@ public:
SkTransferFunctionBehavior::kRespect);
}
- /** Copies a SkRect of pixels to dst. Copy starts at (srcX, srcY), and does not exceed
- (this->width(), this->height()).
+ /** Copies a SkRect of pixels from SkBitmap to dst. Copy starts at (srcX, srcY), and
+ does not exceed SkBitmap (width(), height()).
dst specifies width, height, SkColorType, SkAlphaType, SkColorSpace, pixel storage,
and row bytes of destination. dst.rowBytes() specifics the gap from one destination
@@ -1003,16 +993,16 @@ public:
- dst.rowBytes is less than SkImageInfo::minRowBytes
- SkPixelRef 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 SkBitmap colorType() is
kGray_8_SkColorType, or kAlpha_8_SkColorType; dst SkColorType must match.
- If this->colorType() is kGray_8_SkColorType, dst SkColorSpace must match.
- If this->alphaType() is kOpaque_SkAlphaType, dst SkAlphaType must
- match. If this->colorSpace() is nullptr, dst SkColorSpace must match. Returns
+ If SkBitmap colorType() is kGray_8_SkColorType, dst SkColorSpace must match.
+ If SkBitmap alphaType() is kOpaque_SkAlphaType, dst SkAlphaType must
+ match. If SkBitmap colorSpace() is nullptr, dst SkColorSpace 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 abs(srcX) >= this->width(), or if abs(srcY) >= this->height().
+ Returns false if abs(srcX) >= Bitmap width(), or if abs(srcY) >= Bitmap height().
@param dst destination SkPixmap: SkImageInfo, pixels, row bytes
@param srcX column index whose absolute value is less than width()
@@ -1021,8 +1011,8 @@ public:
*/
bool readPixels(const SkPixmap& dst, int srcX, int srcY) const;
- /** Copies a SkRect of pixels to dst. Copy starts at (0, 0), and does not exceed
- (this->width(), this->height()).
+ /** Copies a SkRect of pixels from SkBitmap to dst. Copy starts at (0, 0), and
+ does not exceed SkBitmap (width(), height()).
dst specifies width, height, SkColorType, SkAlphaType, SkColorSpace, pixel storage,
and row bytes of destination. dst.rowBytes() specifics the gap from one destination
@@ -1031,11 +1021,11 @@ public:
- dst.rowBytes is less than SkImageInfo::minRowBytes
- SkPixelRef 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 SkBitmap colorType() is
kGray_8_SkColorType, or kAlpha_8_SkColorType; dst SkColorType must match.
- If this->colorType() is kGray_8_SkColorType, dst SkColorSpace must match.
- If this->alphaType() is kOpaque_SkAlphaType, dst SkAlphaType must
- match. If this->colorSpace() is nullptr, dst SkColorSpace must match. Returns
+ If SkBitmap colorType() is kGray_8_SkColorType, dst SkColorSpace must match.
+ If SkBitmap alphaType() is kOpaque_SkAlphaType, dst SkAlphaType must
+ match. If SkBitmap colorSpace() is nullptr, dst SkColorSpace must match. Returns
false if pixel conversion is not possible.
@param dst destination SkPixmap: SkImageInfo, pixels, row bytes
@@ -1055,16 +1045,16 @@ public:
- src.rowBytes is less than SkImageInfo::minRowBytes
- SkPixelRef 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 SkBitmap colorType() is
kGray_8_SkColorType, or kAlpha_8_SkColorType; src SkColorType must match.
- If this->colorType() is kGray_8_SkColorType, src SkColorSpace must match.
- If this->alphaType() is kOpaque_SkAlphaType, src SkAlphaType must
- match. If this->colorSpace() is nullptr, src SkColorSpace must match. Returns
+ If SkBitmap colorType() is kGray_8_SkColorType, src SkColorSpace must match.
+ If SkBitmap alphaType() is kOpaque_SkAlphaType, src SkAlphaType must
+ match. If SkBitmap colorSpace() is nullptr, src SkColorSpace 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 abs(dstX) >= this->width(), or if abs(dstY) >= this->height().
+ Returns false if abs(dstX) >= Bitmap width(), or if abs(dstY) >= Bitmap height().
@param src source SkPixmap: SkImageInfo, pixels, row bytes
@param dstX column index whose absolute value is less than width()
@@ -1085,11 +1075,11 @@ public:
- src.rowBytes is less than SkImageInfo::minRowBytes
- SkPixelRef 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 SkBitmap colorType() is
kGray_8_SkColorType, or kAlpha_8_SkColorType; src SkColorType must match.
- If this->colorType() is kGray_8_SkColorType, src SkColorSpace must match.
- If this->alphaType() is kOpaque_SkAlphaType, src SkAlphaType must
- match. If this->colorSpace() is nullptr, src SkColorSpace must match. Returns
+ If SkBitmap colorType() is kGray_8_SkColorType, src SkColorSpace must match.
+ If SkBitmap alphaType() is kOpaque_SkAlphaType, src SkAlphaType must
+ match. If SkBitmap colorSpace() is nullptr, src SkColorSpace must match. Returns
false if pixel conversion is not possible.
@param src source SkPixmap: SkImageInfo, pixels, row bytes
@@ -1109,11 +1099,11 @@ public:
- src.rowBytes is less than SkImageInfo::minRowBytes
- SkPixelRef 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 SkBitmap colorType() is
kGray_8_SkColorType, or kAlpha_8_SkColorType; src SkColorType must match.
- If this->colorType() is kGray_8_SkColorType, src SkColorSpace must match.
- If this->alphaType() is kOpaque_SkAlphaType, src SkAlphaType must
- match. If this->colorSpace() is nullptr, src SkColorSpace must match. Returns
+ If SkBitmap colorType() is kGray_8_SkColorType, src SkColorSpace must match.
+ If SkBitmap alphaType() is kOpaque_SkAlphaType, src SkAlphaType must
+ match. If SkBitmap colorSpace() is nullptr, src SkColorSpace must match. Returns
false if pixel conversion is not possible. Returns false if width() or height()
is zero or negative.
@@ -1168,7 +1158,7 @@ public:
/** Sets dst to alpha described by pixels. Returns false if dst cannot be written to
or dst pixels cannot be allocated.
- If paint is not nullptr and contains SkMaskFilter, SkMaskFilter::filterMask
+ If paint is not nullptr and contains SkMaskFilter, SkMaskFilter
generates mask alpha from SkBitmap. Uses HeapAllocator to reserve memory for dst
SkPixelRef. Sets offset to top-left position for dst for alignment with SkBitmap;
(0, 0) unless SkMaskFilter generates mask.
@@ -1186,7 +1176,7 @@ public:
/** Sets dst to alpha described by pixels. Returns false if dst cannot be written to
or dst pixels cannot be allocated.
- If paint is not nullptr and contains SkMaskFilter, SkMaskFilter::filterMask
+ If paint is not nullptr and contains SkMaskFilter, SkMaskFilter
generates mask alpha from SkBitmap. allocator may reference a custom allocation
class or be set to nullptr to use HeapAllocator. Sets offset to top-left
position for dst for alignment with SkBitmap; (0, 0) unless SkMaskFilter generates
@@ -1224,7 +1214,7 @@ public:
public:
/** Allocates the pixel memory for the bitmap, given its dimensions and
- color type. Returns true on success, where success means either setPixels()
+ SkColorType. Returns true on success, where success means either setPixels()
or setPixelRef() was called.
@param bitmap SkBitmap containing SkImageInfo as input, and SkPixelRef as output
@@ -1236,15 +1226,15 @@ public:
};
/** \class SkBitmap::HeapAllocator
- Subclass of allocator that returns a SkPixelRef that allocates its pixel
- memory from the heap. This is the default allocator invoked by
+ Subclass of SkBitmap::Allocator that returns a SkPixelRef that allocates its pixel
+ memory from the heap. This is the default SkBitmap::Allocator invoked by
allocPixels().
*/
class HeapAllocator : public Allocator {
public:
/** Allocates the pixel memory for the bitmap, given its dimensions and
- color type. Returns true on success, where success means either setPixels()
+ SkColorType. Returns true on success, where success means either setPixels()
or setPixelRef() was called.
@param bitmap SkBitmap containing SkImageInfo as input, and SkPixelRef as output
@@ -1254,7 +1244,7 @@ public:
};
/** macro expands to: void toString(SkString* str) const;
- Creates string representation. The representation is read by
+ Creates string representation of SkBitmap. The representation is read by
internal debugging tools. The interface and implementation may be
suppressed by defining SK_IGNORE_TO_STRING.
diff --git a/include/core/SkCanvas.h b/include/core/SkCanvas.h
index 9ac328291c..793f4abd90 100644
--- a/include/core/SkCanvas.h
+++ b/include/core/SkCanvas.h
@@ -153,11 +153,7 @@ public:
*/
SkCanvas(int width, int height, const SkSurfaceProps* props = nullptr);
- /** Construct a canvas that draws into device.
- Used by child classes of SkCanvas.
-
- @param device specifies a device for the canvas to draw into
- @return SkCanvas that can be used to draw into device
+ /** To be deprecated soon.
*/
explicit SkCanvas(SkBaseDevice* device);
@@ -203,8 +199,8 @@ public:
*/
SkCanvas(const SkBitmap& bitmap, const SkSurfaceProps& props);
- /** Draw saved layers, if any.
- Free up resources used by SkCanvas.
+ /** Draws saved layer, if any.
+ Frees up resources used by SkCanvas.
*/
virtual ~SkCanvas();
@@ -358,7 +354,7 @@ public:
Caller must allocate pixel storage in pixmap if needed.
Pixel values are converted only if SkColorType and SkAlphaType
- do not match. Only pixels within both source and destination rects
+ do not match. Only pixels within both source and destination SkRect
are copied. pixmap pixels contents outside SkRect intersection are unchanged.
Pass negative values for srcX or srcY to offset pixels across or down pixmap.
@@ -434,8 +430,8 @@ public:
Does not copy, and returns false if:
- 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 SkCanvas imageInfo().colorType() or
+ imageInfo().alphaType().
- SkCanvas pixels are not writable; for instance, SkCanvas is document-based.
- rowBytes is too small to contain one row of pixels.
@@ -472,8 +468,8 @@ public:
Does not copy, and returns false if:
- 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 SkCanvas imageInfo().colorType() or
+ imageInfo().alphaType().
- SkCanvas pixels are not writable; for instance, SkCanvas is document based.
- bitmap pixels are inaccessible; for instance, bitmap wraps a texture.
@@ -484,7 +480,7 @@ public:
*/
bool writePixels(const SkBitmap& bitmap, int x, int y);
- /** Saves SkMatrix, clip, and SkDrawFilter (Draw_Filter deprecated on most platforms).
+ /** Saves SkMatrix, clip, and SkDrawFilter (SkDrawFilter deprecated on most platforms).
Calling restore() discards changes to SkMatrix, clip, and SkDrawFilter,
restoring the SkMatrix, clip, and SkDrawFilter to their state when save() was called.
@@ -500,7 +496,7 @@ public:
*/
int save();
- /** Saves SkMatrix, clip, and SkDrawFilter (Draw_Filter deprecated on most platforms),
+ /** Saves SkMatrix, clip, and SkDrawFilter (SkDrawFilter deprecated on most platforms),
and allocates a SkBitmap for subsequent drawing.
Calling restore() discards changes to SkMatrix, clip, and SkDrawFilter,
and draws the SkBitmap.
@@ -523,7 +519,7 @@ public:
*/
int saveLayer(const SkRect* bounds, const SkPaint* paint);
- /** Saves SkMatrix, clip, and SkDrawFilter (Draw_Filter deprecated on most platforms),
+ /** Saves SkMatrix, clip, and SkDrawFilter (SkDrawFilter deprecated on most platforms),
and allocates a SkBitmap for subsequent drawing.
Calling restore() discards changes to SkMatrix, clip, and SkDrawFilter,
and draws the SkBitmap.
@@ -548,9 +544,9 @@ public:
return this->saveLayer(&bounds, paint);
}
- /** Saves SkMatrix, clip, and SkDrawFilter (Draw_Filter deprecated on most platforms),
+ /** Saves SkMatrix, clip, and SkDrawFilter (SkDrawFilter deprecated on most platforms),
and allocates a SkBitmap for subsequent drawing.
- lcd text is preserved when the layer is drawn to the prior layer.
+ LCD text is preserved when the layer is drawn to the prior layer.
Calling restore() discards changes to SkMatrix, clip, and SkDrawFilter,
and draws layer.
@@ -567,8 +563,8 @@ public:
Call restoreToCount() with returned value to restore this and subsequent saves.
- Draw text on an opaque background so that lcd text blends correctly with the
- prior layer. lcd text drawn on a background with transparency may result in
+ Draw text on an opaque background so that LCD text blends correctly with the
+ prior layer. LCD text drawn on a background with transparency may result in
incorrect blending.
@param bounds hint to limit the size of layer; may be nullptr
@@ -577,7 +573,7 @@ public:
*/
int saveLayerPreserveLCDTextRequests(const SkRect* bounds, const SkPaint* paint);
- /** Saves SkMatrix, clip, and SkDrawFilter (Draw_Filter deprecated on most platforms),
+ /** Saves SkMatrix, clip, and SkDrawFilter (SkDrawFilter deprecated on most platforms),
and allocates SkBitmap for subsequent drawing.
Calling restore() discards changes to SkMatrix, clip, and SkDrawFilter,
@@ -614,7 +610,7 @@ public:
kInitWithPrevious_SaveLayerFlag = 1 << 2,
#ifdef SK_SUPPORT_LEGACY_CLIPTOLAYERFLAG
- /** to be deprecated: bug.skia.org/2440 */
+ /** To be deprecated soon. */
kDontClipToLayer_Legacy_SaveLayerFlag = kDontClipToLayer_PrivateSaveLayerFlag,
#endif
};
@@ -728,7 +724,7 @@ public:
};
- /** Saves SkMatrix, clip, and SkDrawFilter (Draw_Filter deprecated on most platforms),
+ /** Saves SkMatrix, clip, and SkDrawFilter (SkDrawFilter deprecated on most platforms),
and allocates SkBitmap for subsequent drawing.
Calling restore() discards changes to SkMatrix, clip, and SkDrawFilter,
@@ -1749,7 +1745,7 @@ public:
const SkPaint* paint = nullptr);
/** \struct SkCanvas::Lattice
- Lattice divides SkBitmap or SkImage into a rectangular grid.
+ SkCanvas::Lattice divides SkBitmap or SkImage into a rectangular grid.
Grid entries on even columns and even rows are fixed; these entries are
always drawn at their original size if the destination is large enough.
If the destination side is too small to hold the fixed entries, all fixed
@@ -1822,7 +1818,7 @@ public:
/** Draw SkBitmap bitmap stretched proportionally to fit into SkRect dst.
- Lattice lattice divides bitmap into a rectangular grid.
+ SkCanvas::Lattice lattice divides bitmap into a rectangular grid.
Each intersection of an even-numbered row and column is fixed; like the corners
of drawBitmapNine(), fixed lattice elements never scale larger than their initial
size and shrink proportionately when all fixed elements exceed the bitmap
@@ -1850,7 +1846,7 @@ public:
/** Draw SkImage image stretched proportionally to fit into SkRect dst.
- Lattice lattice divides image into a rectangular grid.
+ SkCanvas::Lattice lattice divides image into a rectangular grid.
Each intersection of an even-numbered row and column is fixed; like the corners
of drawBitmapNine(), fixed lattice elements never scale larger than their initial
size and shrink proportionately when all fixed elements exceed the bitmap
@@ -2081,9 +2077,9 @@ public:
blob contains glyphs, their positions, and paint attributes specific to text:
SkTypeface, SkPaint text size, SkPaint text scale x, SkPaint text skew x,
- SkPaint::Align, SkPaint::Hinting, anti-alias, SkPaint fake bold,
- font embedded bitmaps, full hinting spacing, lcd text, linear text,
- subpixel text, and SkPaint vertical text.
+ SkPaint::Align, SkPaint::Hinting, SkPaint anti-alias, SkPaint fake bold,
+ SkPaint font embedded bitmaps, SkPaint full hinting spacing, LCD text, SkPaint linear text,
+ SkPaint subpixel text, and SkPaint vertical text.
SkPaint::TextEncoding must be set to SkPaint::kGlyphID_TextEncoding.
@@ -2101,9 +2097,9 @@ public:
blob contains glyphs, their positions, and paint attributes specific to text:
SkTypeface, SkPaint text size, SkPaint text scale x, SkPaint text skew x,
- SkPaint::Align, SkPaint::Hinting, anti-alias, SkPaint fake bold,
- font embedded bitmaps, full hinting spacing, lcd text, linear text,
- subpixel text, and SkPaint vertical text.
+ SkPaint::Align, SkPaint::Hinting, SkPaint anti-alias, SkPaint fake bold,
+ SkPaint font embedded bitmaps, SkPaint full hinting spacing, LCD text, SkPaint linear text,
+ SkPaint subpixel text, and SkPaint vertical text.
SkPaint::TextEncoding must be set to SkPaint::kGlyphID_TextEncoding.
@@ -2199,8 +2195,8 @@ public:
as Coons_Patch texture; SkBlendMode mode combines color colors and SkShader if
both are provided.
- SkPoint array cubics specifies four cubics starting at the top-left corner,
- in clockwise order, sharing every fourth point. The last cubic ends at the
+ SkPoint array cubics specifies four SkPath cubic starting at the top-left corner,
+ in clockwise order, sharing every fourth point. The last SkPath cubic ends at the
first point.
Color array color associates colors with corners in top-left, top-right,
@@ -2219,7 +2215,7 @@ public:
void drawPatch(const SkPoint cubics[12], const SkColor colors[4],
const SkPoint texCoords[4], SkBlendMode mode, const SkPaint& paint);
- /** Draws cubic Coons_Patch: the interpolation of four cubics with shared corners,
+ /** Draws SkPath cubic Coons_Patch: the interpolation of four cubics with shared corners,
associating a color, and optionally a texture coordinate, with each corner.
Coons_Patch uses clip and SkMatrix, paint SkShader, SkColorFilter,
@@ -2227,8 +2223,8 @@ public:
as Coons_Patch texture; SkBlendMode mode combines color colors and SkShader if
both are provided.
- SkPoint array cubics specifies four cubics starting at the top-left corner,
- in clockwise order, sharing every fourth point. The last cubic ends at the
+ SkPoint array cubics specifies four SkPath cubic starting at the top-left corner,
+ in clockwise order, sharing every fourth point. The last SkPath cubic ends at the
first point.
Color array color associates colors with corners in top-left, top-right,
@@ -2249,7 +2245,7 @@ public:
}
/** Draw a set of sprites from atlas, using clip, SkMatrix, and optional SkPaint paint.
- paint uses anti-alias, color alpha, SkColorFilter, SkImageFilter, and SkBlendMode
+ paint uses SkPaint anti-alias, color alpha, SkColorFilter, SkImageFilter, and SkBlendMode
to draw, if present. For each entry in the array, SkRect tex locates sprite in
atlas, and SkRSXform xform transforms it into destination space.
@@ -2272,7 +2268,7 @@ public:
const SkPaint* paint);
/** Draw a set of sprites from atlas, using clip, SkMatrix, and optional SkPaint paint.
- paint uses anti-alias, color alpha, SkColorFilter, SkImageFilter, and SkBlendMode
+ paint uses SkPaint anti-alias, color alpha, SkColorFilter, SkImageFilter, and SkBlendMode
to draw, if present. For each entry in the array, SkRect tex locates sprite in
atlas, and SkRSXform xform transforms it into destination space.
@@ -2297,7 +2293,7 @@ public:
}
/** Draw a set of sprites from atlas, using clip, SkMatrix, and optional SkPaint paint.
- paint uses anti-alias, color alpha, SkColorFilter, SkImageFilter, and SkBlendMode
+ paint uses SkPaint anti-alias, color alpha, SkColorFilter, SkImageFilter, and SkBlendMode
to draw, if present. For each entry in the array, SkRect tex locates sprite in
atlas, and SkRSXform xform transforms it into destination space.
@@ -2318,7 +2314,7 @@ public:
}
/** Draw a set of sprites from atlas, using clip, SkMatrix, and optional SkPaint paint.
- paint uses anti-alias, color alpha, SkColorFilter, SkImageFilter, and SkBlendMode
+ paint uses SkPaint anti-alias, color alpha, SkColorFilter, SkImageFilter, and SkBlendMode
to draw, if present. For each entry in the array, SkRect tex locates sprite in
atlas, and SkRSXform xform transforms it into destination space.
@@ -2365,7 +2361,7 @@ public:
*/
void drawDrawable(SkDrawable* drawable, SkScalar x, SkScalar y);
- /** Associate SkRect on SkCanvas when an annotation; a key-value pair, where the key is
+ /** Associate SkRect on SkCanvas with an annotation; a key-value pair, where the key is
a null-terminated utf8 string, and optional value is stored as SkData.
Only some canvas implementations, such as recording to SkPicture, or drawing to
@@ -2394,11 +2390,11 @@ public:
//////////////////////////////////////////////////////////////////////////
#ifdef SK_SUPPORT_LEGACY_DRAWFILTER
- /** Legacy call to be deprecated.
+ /** To be deprecated soon.
*/
SkDrawFilter* getDrawFilter() const;
- /** Legacy call to be deprecated.
+ /** To be deprecated soon.
*/
virtual SkDrawFilter* setDrawFilter(SkDrawFilter* filter);
#endif
@@ -2774,7 +2770,7 @@ private:
class SkAutoCanvasRestore : SkNoncopyable {
public:
- /** Preserves SkCanvas save count. Optionally saves SkCanvas clip and SkMatrix.
+ /** Preserves SkCanvas save count. Optionally saves SkCanvas clip and SkCanvas matrix.
@param canvas SkCanvas to guard
@param doSave call SkCanvas::save()
diff --git a/include/core/SkImage.h b/include/core/SkImage.h
index e1a43a97c7..30637a6d34 100644
--- a/include/core/SkImage.h
+++ b/include/core/SkImage.h
@@ -33,75 +33,135 @@ class GrContext;
class GrContextThreadSafeProxy;
class GrTexture;
-/**
- * SkImage is an abstraction for drawing a rectagle of pixels, though the
- * particular type of image could be actually storing its data on the GPU, or
- * as drawing commands (picture or PDF or otherwise), ready to be played back
- * into another canvas.
- *
- * The content of SkImage is always immutable, though the actual storage may
- * change, if for example that image can be re-created via encoded data or
- * other means.
- *
- * SkImage always has a non-zero dimensions. If there is a request to create a new image, either
- * directly or via SkSurface, and either of the requested dimensions are zero, then NULL will be
- * returned.
- */
+/** \class SkImage
+ SkImage describes a two dimensional array of pixels to draw. The pixels may be
+ decoded in a raster bitmap, encoded in a SkPicture or compressed data stream,
+ or located in GPU memory as a GPU texture.
+
+ SkImage cannot be modified after it is created. SkImage may allocate additional
+ storage as needed; for instance, an encoded SkImage may decode when drawn.
+
+ SkImage width and height are greater than zero. Creating an SkImage with zero width
+ or height returns SkImage equal to nullptr.
+
+ SkImage may be created from SkBitmap, SkPixmap, SkSurface, SkPicture, encoded streams,
+ GPU texture, YUV_ColorSpace data, or hardware buffer. Encoded streams supported
+ include BMP, GIF, HEIF, ICO, JPEG, PNG, WBMP, WebP. Supported encoding details
+ vary with platform.
+*/
class SK_API SkImage : public SkRefCnt {
public:
typedef SkImageInfo Info;
typedef void* ReleaseContext;
+ /** Creates SkImage from SkPixmap and copy of pixels. Since pixels are copied, SkPixmap
+ pixels may be modified or deleted without affecting SkImage.
+
+ SkImage is returned if SkPixmap is valid. Valid SkPixmap parameters include:
+ dimensions are greater than zero;
+ each dimension fits in 29 bits;
+ SkColorType and SkAlphaType are valid, and SkColorType is not kUnknown_SkColorType;
+ row bytes are large enough to hold one row of pixels;
+ pixel address is not nullptr.
+
+ @param pixmap SkImageInfo, pixel address, and row bytes
+ @return copy of SkPixmap pixels, or nullptr
+ */
static sk_sp<SkImage> MakeRasterCopy(const SkPixmap& pixmap);
+
+ /** Creates SkImage from SkImageInfo, sharing pixels.
+
+ SkImage is returned if SkImageInfo is valid. Valid SkImageInfo parameters include:
+ dimensions are greater than zero;
+ each dimension fits in 29 bits;
+ SkColorType and SkAlphaType are valid, and SkColorType is not kUnknown_SkColorType;
+ rowBytes are large enough to hold one row of pixels;
+ pixels is not nullptr, and contains enough data for SkImage.
+
+ @param info contains width, height, SkAlphaType, SkColorType, SkColorSpace
+ @param pixels address or pixel storage
+ @param rowBytes size of pixel row or larger
+ @return SkImage sharing pixels, or nullptr
+ */
static sk_sp<SkImage> MakeRasterData(const Info& info, sk_sp<SkData> pixels, size_t rowBytes);
typedef void (*RasterReleaseProc)(const void* pixels, ReleaseContext);
- /**
- * Return a new Image referencing the specified pixels. These must remain valid and unchanged
- * until the specified release-proc is called, indicating that Skia no longer has a reference
- * to the pixels.
- *
- * Returns NULL if the requested pixmap info is unsupported.
- */
+ /** Creates SkImage from pixmap, sharing SkPixmap pixels. Pixels must remain valid and
+ unchanged until rasterReleaseProc is called. rasterReleaseProc is passed
+ releaseContext when SkImage is deleted or no longer refers to pixmap pixels.
+
+ Pass nullptr for rasterReleaseProc to share SkPixmap without requiring a callback
+ when SkImage is released. Pass nullptr for releaseContext if rasterReleaseProc
+ does not require state.
+
+ SkImage is returned if pixmap is valid. Valid SkPixmap parameters include:
+ dimensions are greater than zero;
+ each dimension fits in 29 bits;
+ SkColorType and SkAlphaType are valid, and SkColorType is not kUnknown_SkColorType;
+ row bytes are large enough to hold one row of pixels;
+ pixel address is not nullptr.
+
+ @param pixmap SkImageInfo, 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 SkImage sharing pixmap
+ */
static sk_sp<SkImage> MakeFromRaster(const SkPixmap& pixmap,
RasterReleaseProc rasterReleaseProc,
ReleaseContext releaseContext);
- /**
- * Construct a new image from the specified bitmap. If the bitmap is marked immutable, and
- * its pixel memory is shareable, it may be shared instead of copied.
- */
+ /** Creates SkImage 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.
+
+ SkImage is returned if bitmap is valid. Valid SkBitmap parameters include:
+ dimensions are greater than zero;
+ each dimension fits in 29 bits;
+ SkColorType and SkAlphaType are valid, and SkColorType is not kUnknown_SkColorType;
+ row bytes are large enough to hold one row of pixels;
+ pixel address is not nullptr.
+
+ @param bitmap SkImageInfo, row bytes, and pixels
+ @return created SkImage, or nullptr
+ */
static sk_sp<SkImage> MakeFromBitmap(const SkBitmap& bitmap);
- /**
- * Construct a new SkImage based on the given ImageGenerator. Returns NULL on error.
- * This function will always take ownership of the passed generator.
- *
- * If a subset is specified, it must be contained within the generator's bounds.
- */
+ /** Creates SkImage from data returned by imageGenerator. Generated data is owned by SkImage 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.
+
+ SkImage is returned if generator data is valid. Valid data parameters vary by type of data
+ and platform.
+
+ imageGenerator may wrap SkPicture data, codec data, or custom data.
+
+ @param imageGenerator stock or custom routines to retrieve SkImage
+ @param subset bounds of returned SkImage; may be nullptr
+ @return created SkImage, or nullptr
+ */
static sk_sp<SkImage> MakeFromGenerator(std::unique_ptr<SkImageGenerator> imageGenerator,
const SkIRect* subset = nullptr);
- /**
- * Construct a new SkImage based on the specified encoded data. Returns NULL on failure,
- * which can mean that the format of the encoded data was not recognized/supported.
- *
- * If a subset is specified, it must be contained within the encoded data's bounds.
- */
+ /** Creates SkImage 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.
+
+ SkImage is returned if format of the encoded data is recognized and supported.
+ Recognized formats vary by platform.
+
+ @param encoded data of SkImage to decode
+ @param subset bounds of returned SkImage; may be nullptr
+ @return created SkImage, or nullptr
+ */
static sk_sp<SkImage> MakeFromEncoded(sk_sp<SkData> encoded, const SkIRect* subset = nullptr);
typedef void (*TextureReleaseProc)(ReleaseContext releaseContext);
- /**
- * Create a new image from the specified descriptor. Note - the caller is responsible for
- * managing the lifetime of the underlying platform texture.
- *
- * Will return NULL if the specified backend texture is unsupported.
- *
- * DEPRECATED: This factory is deprecated and clients should use the factory below which takes
- * an SkColorType.
- */
+ /** Deprecated.
+ */
static sk_sp<SkImage> MakeFromTexture(GrContext* context,
const GrBackendTexture& backendTexture,
GrSurfaceOrigin origin,
@@ -111,16 +171,8 @@ public:
nullptr);
}
- /**
- * Create a new image from the GrBackendTexture. The underlying platform texture must stay
- * valid and unaltered until the specified release-proc is invoked, indicating that Skia
- * no longer is holding a reference to it.
- *
- * Will return NULL if the specified backend texture is unsupported.
- *
- * DEPRECATED: This factory is deprecated and clients should use the factory below which takes
- * an SkColorType.
- */
+ /** Deprecated.
+ */
static sk_sp<SkImage> MakeFromTexture(GrContext* context,
const GrBackendTexture& backendTexture,
GrSurfaceOrigin origin,
@@ -129,16 +181,24 @@ public:
TextureReleaseProc textureReleaseProc,
ReleaseContext releaseContext);
- /**
- * Create a new image from the specified descriptor. Note - the caller is responsible for
- * managing the lifetime of the underlying platform texture.
- *
- * The GrBackendTexture must have a valid backend format supplied (GrGLTextureInfo::fFormat,
- * GrVkImageInfo::fFormat, etc.) in it. The passed in SkColorType informs skia how it should
- * interpret the backend format supplied by the GrBackendTexture. If the format in the
- * GrBackendTexture is not compitable with the SkColorType, SkAlphaType, and SkColorSpace we
- * will return nullptr.
- */
+ /** Creates SkImage from GPU texture associated with context. Caller is responsible for
+ managing the lifetime of GPU texture.
+
+ SkImage is returned if format of backendTexture is recognized and supported.
+ Recognized formats vary by GPU back-end.
+
+ @param context GPU context
+ @param backendTexture texture residing on GPU
+ @param origin one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin
+ @param colorType one of: kUnknown_SkColorType, kAlpha_8_SkColorType,
+ kRGB_565_SkColorType, kARGB_4444_SkColorType,
+ kRGBA_8888_SkColorType, kBGRA_8888_SkColorType,
+ kGray_8_SkColorType, kRGBA_F16_SkColorType
+ @param alphaType one of: kUnknown_SkAlphaType, kOpaque_SkAlphaType,
+ kPremul_SkAlphaType, kUnpremul_SkAlphaType
+ @param colorSpace range of colors; may be nullptr
+ @return created SkImage, or nullptr
+ */
static sk_sp<SkImage> MakeFromTexture(GrContext* context,
const GrBackendTexture& backendTexture,
GrSurfaceOrigin origin,
@@ -149,17 +209,27 @@ public:
nullptr, nullptr);
}
- /**
- * Create a new image from the GrBackendTexture. The underlying platform texture must stay
- * valid and unaltered until the specified release-proc is invoked, indicating that Skia
- * no longer is holding a reference to it.
- *
- * The GrBackendTexture must have a valid backend format supplied (GrGLTextureInfo::fFormat,
- * GrVkImageInfo::fFormat, etc.) in it. The passed in SkColorType informs skia how it should
- * interpret the backend format supplied by the GrBackendTexture. If the format in the
- * GrBackendTexture is not compitable with the SkColorType, SkAlphaType, and SkColorSpace we
- * will return nullptr.
- */
+ /** Creates SkImage from GPU texture associated with context. GPU texture must stay
+ valid and unchanged until textureReleaseProc is called. textureReleaseProc is
+ passed releaseContext when SkImage is deleted or no longer refers to texture.
+
+ SkImage is returned if format of backendTexture is recognized and supported.
+ Recognized formats vary by GPU back-end.
+
+ @param context GPU context
+ @param backendTexture texture residing on GPU
+ @param origin one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin
+ @param colorType one of: kUnknown_SkColorType, kAlpha_8_SkColorType,
+ kRGB_565_SkColorType, kARGB_4444_SkColorType,
+ kRGBA_8888_SkColorType, kBGRA_8888_SkColorType,
+ kGray_8_SkColorType, kRGBA_F16_SkColorType
+ @param alphaType one of: kUnknown_SkAlphaType, kOpaque_SkAlphaType,
+ kPremul_SkAlphaType, kUnpremul_SkAlphaType
+ @param colorSpace range of colors; may be nullptr
+ @param textureReleaseProc function called when texture can be released
+ @param releaseContext state passed to textureReleaseProc
+ @return created SkImage, or nullptr
+ */
static sk_sp<SkImage> MakeFromTexture(GrContext* context,
const GrBackendTexture& backendTexture,
GrSurfaceOrigin origin,
@@ -169,71 +239,86 @@ public:
TextureReleaseProc textureReleaseProc,
ReleaseContext releaseContext);
- /**
- * Decodes and uploads the encoded data to a GPU backed image using the supplied GrContext.
- * That image can be safely used by other GrContexts, across thread boundaries. The GrContext
- * used here, and the ones used to draw this image later must be in the same GL share group,
- * or use the same Vulkan VkDevice and VkQueue, or otherwise be able to share resources.
- *
- * When the image's ref count reaches zero, the original GrContext will destroy the texture,
- * asynchronously.
- *
- * The texture will be decoded and uploaded to be suitable for use with surfaces that have the
- * supplied destination color space. The color space of the image itself will be determined
- * from the encoded data.
- */
+ /** Creates SkImage from encoded data. SkImage is uploaded to GPU back-end using context.
+
+ Created SkImage 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 SkImage is no longer referenced, context releases texture memory
+ asynchronously.
+
+ GrBackendTexture decoded from data is uploaded to match SkSurface created with
+ dstColorSpace. SkColorSpace of SkImage is determined by encoded data.
+
+ SkImage 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.
+
+ SkImage is returned using MakeFromEncoded() if context is nullptr or does not support
+ moving resources between contexts.
+
+ @param context GPU context
+ @param data SkImage to decode
+ @param buildMips create SkImage as Mip_Map if true
+ @param dstColorSpace range of colors of matching SkSurface on GPU
+ @return created SkImage, or nullptr
+ */
static sk_sp<SkImage> MakeCrossContextFromEncoded(GrContext* context, sk_sp<SkData> data,
bool buildMips, SkColorSpace* dstColorSpace);
- /**
- * Uploads the pixmap to a GPU backed image using the supplied GrContext.
- * That image can be safely used by other GrContexts, across thread boundaries. The GrContext
- * used here, and the ones used to draw this image later must be in the same GL share group,
- * or use the same Vulkan VkDevice and VkQueue, or otherwise be able to share resources.
- *
- * When the image's ref count reaches zero, the original GrContext will destroy the texture,
- * asynchronously.
- *
- * The texture will be processed to be suitable for use with surfaces that have the
- * supplied destination color space. The color space of the image itself will be determined
- * from the pixmap.
- */
+ /** Creates SkImage from pixmap. SkImage is uploaded to GPU back-end using context.
+
+ Created SkImage 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 SkImage is no longer referenced, context releases texture memory
+ asynchronously.
+
+ GrBackendTexture created from pixmap is uploaded to match SkSurface created with
+ dstColorSpace. SkColorSpace of SkImage is determined by pixmap.colorSpace().
+
+ SkImage is returned referring to GPU back-end if context is not nullptr,
+ format of data is recognized and supported, and if context supports moving
+ resources between contexts. Otherwise, pixmap pixel data is copied and SkImage
+ 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 SkImageInfo, pixel address, and row bytes
+ @param buildMips create SkImage as Mip_Map if true
+ @param dstColorSpace range of colors of matching SkSurface on GPU
+ @return created SkImage, or nullptr
+ */
static sk_sp<SkImage> MakeCrossContextFromPixmap(GrContext* context, const SkPixmap& pixmap,
bool buildMips, SkColorSpace* dstColorSpace);
- /**
- * Create a new image from the specified descriptor. Note - Skia will delete or recycle the
- * texture when the image is released.
- *
- * Will return NULL if the specified backend texture is unsupported.
- *
- * This is not supported if the GrContext was obtained from a deferred display list canvas
- * since if the SkImage never gets used and flushed to a real GrContext, we have no way to be
- * able to delete the underlying backend texture.
- *
- * DEPRECATED: This factory is deprecated and clients should use the factory below which takes
- * an SkColorType.
- */
+ /** Deprecated.
+ */
static sk_sp<SkImage> MakeFromAdoptedTexture(GrContext* context,
const GrBackendTexture& backendTexture,
GrSurfaceOrigin surfaceOrigin,
SkAlphaType alphaType = kPremul_SkAlphaType,
sk_sp<SkColorSpace> colorSpace = nullptr);
- /**
- * Create a new image from the specified descriptor. Note - Skia will delete or recycle the
- * texture when the image is released.
- *
- * The GrBackendTexture must have a valid backend format supplied (GrGLTextureInfo::fFormat,
- * GrVkImageInfo::fFormat, etc.) in it. The passed in SkColorType informs skia how it should
- * interpret the backend format supplied by the GrBackendTexture. If the format in the
- * GrBackendTexture is not compitable with the SkColorType, SkAlphaType, and SkColorSpace we
- * will return nullptr.
- *
- * This is not supported if the GrContext was obtained from a deferred display list canvas
- * since if the SkImage never gets used and flushed to a real GrContext, we have no way to be
- * able to delete the underlying backend texture.
- */
+ /** Creates SkImage from backendTexture associated with context. backendTexture and
+ returned SkImage are managed internally, and are released when no longer needed.
+
+ SkImage is returned if format of backendTexture is recognized and supported.
+ Recognized formats vary by GPU back-end.
+
+ @param context GPU context
+ @param backendTexture texture residing on GPU
+ @param surfaceOrigin one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin
+ @param colorType one of: kUnknown_SkColorType, kAlpha_8_SkColorType,
+ kRGB_565_SkColorType, kARGB_4444_SkColorType,
+ kRGBA_8888_SkColorType, kBGRA_8888_SkColorType,
+ kGray_8_SkColorType, kRGBA_F16_SkColorType
+ @param alphaType one of: kUnknown_SkAlphaType, kOpaque_SkAlphaType,
+ kPremul_SkAlphaType, kUnpremul_SkAlphaType
+ @param colorSpace range of colors; may be nullptr
+ @return created SkImage, or nullptr
+ */
static sk_sp<SkImage> MakeFromAdoptedTexture(GrContext* context,
const GrBackendTexture& backendTexture,
GrSurfaceOrigin surfaceOrigin,
@@ -241,22 +326,44 @@ public:
SkAlphaType alphaType = kPremul_SkAlphaType,
sk_sp<SkColorSpace> colorSpace = nullptr);
- /**
- * Create a new image by copying the pixels from the specified y, u, v textures. The data
- * from the textures is immediately ingested into the image and the textures can be modified or
- * deleted after the function returns. The image will have the dimensions of the y texture.
- */
+ /** Creates SkImage from copy of yuvTextureHandles, an array of textures on GPU.
+ yuvTextureHandles contain pixels for YUV planes of SkImage.
+ yuvSizes contain dimensions for each pixel plane. Dimensions must be greater than
+ zero but may differ from plane to plane. Returned SkImage has the dimensions
+ yuvSizes[0]. yuvColorSpace describes how YUV colors convert to RGB colors.
+
+ @param context GPU context
+ @param yuvColorSpace one of: kJPEG_SkYUVColorSpace, kRec601_SkYUVColorSpace,
+ kRec709_SkYUVColorSpace
+ @param yuvTextureHandles array of YUV textures on GPU
+ @param yuvSizes dimensions of YUV textures
+ @param surfaceOrigin one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin
+ @param colorSpace range of colors; may be nullptr
+ @return created SkImage, or nullptr
+ */
static sk_sp<SkImage> MakeFromYUVTexturesCopy(GrContext* context, SkYUVColorSpace yuvColorSpace,
const GrBackendObject yuvTextureHandles[3],
const SkISize yuvSizes[3],
GrSurfaceOrigin surfaceOrigin,
sk_sp<SkColorSpace> colorSpace = nullptr);
- /**
- * Create a new image by copying the pixels from the specified y and uv textures. The data
- * from the textures is immediately ingested into the image and the textures can be modified or
- * deleted after the function returns. The image will have the dimensions of the y texture.
- */
+ /** Creates SkImage from copy of nv12TextureHandles, an array of textures on GPU.
+ nv12TextureHandles[0] contains pixels for YUV_Component_Y plane.
+ nv12TextureHandles[1] contains pixels for YUV_Component_U plane,
+ followed by pixels for YUV_Component_V plane.
+ nv12Sizes contain dimensions for each pixel plane. Dimensions must be greater than
+ zero but may differ from plane to plane. Returned SkImage has the dimensions
+ nv12Sizes[0]. yuvColorSpace describes how YUV colors convert to RGB colors.
+
+ @param context GPU context
+ @param yuvColorSpace one of: kJPEG_SkYUVColorSpace, kRec601_SkYUVColorSpace,
+ kRec709_SkYUVColorSpace
+ @param nv12TextureHandles array of YUV textures on GPU
+ @param nv12Sizes dimensions of YUV textures
+ @param surfaceOrigin one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin
+ @param colorSpace range of colors; may be nullptr
+ @return created SkImage, or nullptr
+ */
static sk_sp<SkImage> MakeFromNV12TexturesCopy(GrContext* context,
SkYUVColorSpace yuvColorSpace,
const GrBackendObject nv12TextureHandles[2],
@@ -264,22 +371,44 @@ public:
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.
- */
+ /** Creates SkImage from copy of yuvTextureHandles, an array of textures on GPU.
+ yuvTextureHandles contain pixels for YUV planes of SkImage.
+ yuvSizes contain dimensions for each pixel plane. Dimensions must be greater than
+ zero but may differ from plane to plane. Returned SkImage has the dimensions
+ yuvSizes[0]. yuvColorSpace describes how YUV colors convert to RGB colors.
+
+ @param context GPU context
+ @param yuvColorSpace one of: kJPEG_SkYUVColorSpace, kRec601_SkYUVColorSpace,
+ kRec709_SkYUVColorSpace
+ @param yuvTextureHandles array of YUV textures on GPU
+ @param yuvSizes dimensions of YUV textures
+ @param surfaceOrigin one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin
+ @param colorSpace range of colors; may be nullptr
+ @return created SkImage, or nullptr
+ */
static sk_sp<SkImage> MakeFromYUVTexturesCopy(GrContext* context, SkYUVColorSpace yuvColorSpace,
const GrBackendTexture yuvTextureHandles[3],
const SkISize yuvSizes[3],
GrSurfaceOrigin surfaceOrigin,
sk_sp<SkColorSpace> colorSpace = nullptr);
- /**
- * Create a new image by copying the pixels from the specified y and uv textures. The data
- * from the textures is immediately ingested into the image and the textures can be modified or
- * deleted after the function returns. The image will have the dimensions of the y texture.
- */
+ /** Creates SkImage from copy of nv12TextureHandles, an array of textures on GPU.
+ nv12TextureHandles[0] contains pixels for YUV_Component_Y plane.
+ nv12TextureHandles[1] contains pixels for YUV_Component_U plane,
+ followed by pixels for YUV_Component_V plane.
+ nv12Sizes contain dimensions for each pixel plane. Dimensions must be greater than
+ zero but may differ from plane to plane. Returned SkImage has the dimensions
+ nv12Sizes[0]. yuvColorSpace describes how YUV colors convert to RGB colors.
+
+ @param context GPU context
+ @param yuvColorSpace one of: kJPEG_SkYUVColorSpace, kRec601_SkYUVColorSpace,
+ kRec709_SkYUVColorSpace
+ @param nv12TextureHandles array of YUV textures on GPU
+ @param nv12Sizes dimensions of YUV textures
+ @param surfaceOrigin one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin
+ @param colorSpace range of colors; may be nullptr
+ @return created SkImage, or nullptr
+ */
static sk_sp<SkImage> MakeFromNV12TexturesCopy(GrContext* context,
SkYUVColorSpace yuvColorSpace,
const GrBackendTexture nv12TextureHandles[2],
@@ -288,283 +417,511 @@ public:
sk_sp<SkColorSpace> colorSpace = nullptr);
enum class BitDepth {
- kU8,
- kF16,
+ kU8, //!< Use 8 bits per ARGB component using unsigned integer format.
+ kF16, //!< Use 16 bits per ARGB component using half-precision floating point format.
};
- /**
- * Create a new image from the specified picture.
- * On creation of the SkImage, snap the SkPicture to a particular BitDepth and SkColorSpace.
- */
+ /** Creates SkImage from picture. Returned SkImage width and height are set by dimensions.
+ SkImage draws picture with matrix and paint, set to bitDepth and colorSpace.
+
+ If matrix is nullptr, draws with identity SkMatrix. If paint is nullptr, draws
+ with default SkPaint. colorSpace may be nullptr.
+
+ @param picture stream of drawing commands
+ @param dimensions width and height
+ @param matrix SkMatrix to rotate, scale, translate, and so on; may be nullptr
+ @param paint SkPaint to apply transparency, filtering, and so on; may be nullptr
+ @param bitDepth 8 bit integer or 16 bit float: per component
+ @param colorSpace range of colors; may be nullptr
+ @return created SkImage, or nullptr
+ */
static sk_sp<SkImage> MakeFromPicture(sk_sp<SkPicture> picture, const SkISize& dimensions,
const SkMatrix* matrix, const SkPaint* paint,
BitDepth bitDepth,
sk_sp<SkColorSpace> colorSpace);
#if defined(SK_BUILD_FOR_ANDROID) && __ANDROID_API__ >= 26
- /**
- * Create a new image from the an Android hardware buffer.
- * The new image takes a reference on the buffer.
- */
+ /** (see skbug.com/7447)
+ Creates SkImage from Android hardware buffer.
+ Returned SkImage takes a reference on the buffer.
+
+ Only available on Android, when __ANDROID_API__ is defined to be 26 or greater.
+
+ @param hardwareBuffer AHardwareBuffer Android hardware buffer
+ @param alphaType one of: kUnknown_SkAlphaType, kOpaque_SkAlphaType,
+ kPremul_SkAlphaType, kUnpremul_SkAlphaType
+ @param colorSpace range of colors; may be nullptr
+ @return created SkImage, or nullptr
+ */
static sk_sp<SkImage> MakeFromAHardwareBuffer(AHardwareBuffer* hardwareBuffer,
SkAlphaType alphaType = kPremul_SkAlphaType,
sk_sp<SkColorSpace> colorSpace = nullptr);
#endif
- ///////////////////////////////////////////////////////////////////////////////////////////////
+ /** Returns pixel count in each row.
+ @return pixel width in SkImage
+ */
int width() const { return fWidth; }
+
+ /** Returns pixel row count.
+
+ @return pixel height in SkImage
+ */
int height() const { return fHeight; }
+
+ /** Returns SkISize { width(), height() }.
+
+ @return integral size of width() and height()
+ */
SkISize dimensions() const { return SkISize::Make(fWidth, fHeight); }
+
+ /** Returns SkIRect { 0, 0, width(), height() }.
+
+ @return integral rectangle from origin to width() and height()
+ */
SkIRect bounds() const { return SkIRect::MakeWH(fWidth, fHeight); }
+
+ /** Returns value unique to image. SkImage contents cannot change after SkImage is
+ created. Any operation to create a new SkImage will receive generate a new
+ unique number.
+
+ @return unique identifier
+ */
uint32_t uniqueID() const { return fUniqueID; }
+
+ /** Returns SkAlphaType, one of: kUnknown_SkAlphaType, kOpaque_SkAlphaType,
+ kPremul_SkAlphaType, kUnpremul_SkAlphaType.
+
+ SkAlphaType returned was a parameter to an SkImage constructor,
+ or was parsed from encoded data.
+
+ @return SkAlphaType in SkImage
+ */
SkAlphaType alphaType() const;
- /**
- * Returns the color space of the SkImage.
- *
- * This is the color space that was supplied on creation of the SkImage or a color
- * space that was parsed from encoded data. This color space is not guaranteed to be
- * renderable. Can return nullptr if the SkImage was created without a color space.
- */
+ /** Returns SkColorSpace, the range of colors, associated with SkImage. The
+ reference count of SkColorSpace is unchanged. The returned SkColorSpace is
+ immutable.
+
+ SkColorSpace returned was passed to an SkImage constructor,
+ or was parsed from encoded data. SkColorSpace returned may be ignored when SkImage
+ is drawn, depending on the capabilities of the SkSurface receiving the drawing.
+
+ @return SkColorSpace in SkImage, or nullptr
+ */
SkColorSpace* colorSpace() const;
+
+ /** Returns a smart pointer to SkColorSpace, the range of colors, associated with
+ SkImage. The smart pointer tracks the number of objects sharing this
+ SkColorSpace reference so the memory is released when the owners destruct.
+
+ The returned SkColorSpace is immutable.
+
+ SkColorSpace returned was passed to an SkImage constructor,
+ or was parsed from encoded data. SkColorSpace returned may be ignored when SkImage
+ is drawn, depending on the capabilities of the SkSurface receiving the drawing.
+
+ @return SkColorSpace in SkImage, or nullptr, wrapped in a smart pointer
+ */
sk_sp<SkColorSpace> refColorSpace() const;
- /**
- * Returns true fi the image will be drawn as a mask, with no intrinsic color of its own.
- */
+ /** Returns true if SkImage 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
+ */
bool isAlphaOnly() const;
+
+ /** Returns true if pixels ignore their alpha value and are treated as fully opaque.
+
+ @return true if SkAlphaType is kOpaque_SkAlphaType
+ */
bool isOpaque() const { return SkAlphaTypeIsOpaque(this->alphaType()); }
+ /** Creates SkShader from SkImage. SkShader dimensions are taken from SkImage. SkShader uses
+ SkShader::TileMode rules to fill drawn area outside SkImage. localMatrix permits
+ transforming SkImage before SkCanvas matrix is applied.
+
+ @param tileMode1 tiling in x, one of: SkShader::kClamp_TileMode, SkShader::kRepeat_TileMode,
+ SkShader::kMirror_TileMode
+ @param tileMode2 tiling in y, one of: SkShader::kClamp_TileMode, SkShader::kRepeat_TileMode,
+ SkShader::kMirror_TileMode
+ @param localMatrix SkImage transformation, or nullptr
+ @return SkShader containing SkImage
+ */
sk_sp<SkShader> makeShader(SkShader::TileMode tileMode1, SkShader::TileMode tileMode2,
const SkMatrix* localMatrix = nullptr) const;
- /**
- * Helper version of makeShader() that specifies Clamp tilemode.
- */
+
+ /** Creates SkShader from SkImage. SkShader dimensions are taken from SkImage. SkShader uses
+ SkShader::kClamp_TileMode to fill drawn area outside SkImage. localMatrix permits
+ transforming SkImage before SkCanvas matrix is applied.
+
+ @param localMatrix SkImage transformation, or nullptr
+ @return SkShader containing SkImage
+ */
sk_sp<SkShader> makeShader(const SkMatrix* localMatrix = nullptr) const {
return this->makeShader(SkShader::kClamp_TileMode, SkShader::kClamp_TileMode, localMatrix);
}
- /**
- * If the image has direct access to its pixels (i.e. they are in local RAM)
- * return true, and if not null, return in the pixmap parameter the info about the
- * images pixels.
- *
- * On failure, return false and ignore the pixmap parameter.
- */
+ /** Copies SkImage pixel address, row bytes, and SkImageInfo to pixmap, if address
+ is available, and returns true. If pixel address is not available, return
+ false and leave pixmap unchanged.
+
+ @param pixmap storage for pixel state if pixels are readable; otherwise, ignored
+ @return true if SkImage has direct access to pixels
+ */
bool peekPixels(SkPixmap* pixmap) const;
- // DEPRECATED - currently used by Canvas2DLayerBridge in Chromium.
+ /** Deprecated.
+ */
GrTexture* getTexture() const;
- /**
- * Returns true if the image is texture backed.
- */
+ /** Returns true the contents of SkImage was created on or uploaded to GPU memory,
+ and is available as a GPU texture.
+
+ @return true if SkImage is a GPU texture
+ */
bool isTextureBacked() const;
- /**
- * Returns true if the image is able to be drawn to a particular type of device. If context
- * is nullptr, tests for drawability to CPU devices. Otherwise, tests for drawability to a GPU
- * device backed by context.
- *
- * Texture-backed images may become invalid if their underlying GrContext is abandoned. Some
- * generator-backed images may be invalid for CPU and/or GPU.
- */
+ /** Returns true if SkImage can be drawn on either raster surface or GPU surface.
+ If context is nullptr, tests if SkImage draws on raster surface;
+ otherwise, tests if SkImage draws on GPU surface associated with context.
+
+ SkImage backed by GPU texture may become invalid if associated GrContext is
+ invalid. lazy image may be invalid and may not draw to raster surface or
+ GPU surface or both.
+
+ @param context GPU context
+ @return true if SkImage can be drawn
+ */
bool isValid(GrContext* context) const;
- /**
- * Retrieves the backend API handle of the texture. If flushPendingGrContextIO then the
- * GrContext will issue to the backend API any deferred IO operations on the texture before
- * returning.
- * If 'origin' is supplied it will be filled in with the origin of the content drawn
- * into the image.
- */
+ /** 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 SkImage.
+
+ @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, or nullptr
+ */
GrBackendObject getTextureHandle(bool flushPendingGrContextIO,
GrSurfaceOrigin* origin = nullptr) const;
- /**
- * Hints to image calls where the system might cache computed intermediates (e.g. the results
- * of decoding or a read-back from the GPU. Passing kAllow signals that the system's default
- * behavior is fine. Passing kDisallow signals that caching should be avoided.
- */
- enum CachingHint {
- kAllow_CachingHint,
+ /** \enum SkImage::CachingHint
+ CachingHint selects whether Skia may internally cache SkBitmap generated by
+ decoding SkImage, or by copying SkImage from GPU to CPU. The default behavior
+ allows caching SkBitmap.
+
+ Choose kDisallow_CachingHint if SkImage pixels are to be used only once, or
+ if SkImage pixels reside in a cache outside of Skia, or to reduce memory pressure.
+
+ Choosing kAllow_CachingHint does not ensure that pixels will be cached.
+ SkImage pixels may not be cached if memory requirements are too large or
+ pixels are not accessible.
+ */
+ enum CachingHint {
+ kAllow_CachingHint, //!< Allows Skia to internally cache decoded and copied pixels.
+
+ /** Disallows Skia from internally caching decoded and copied pixels. */
kDisallow_CachingHint,
};
- /**
- * Copy the pixels from the image into the specified buffer (pixels + rowBytes),
- * converting them into the requested format (dstInfo). The image pixels are read
- * starting at the specified (srcX,srcY) location.
- *
- * The specified ImageInfo and (srcX,srcY) offset specifies a source rectangle
- *
- * srcR.setXYWH(srcX, srcY, dstInfo.width(), dstInfo.height());
- *
- * srcR is intersected with the bounds of the image. If this intersection is not empty,
- * then we have two sets of pixels (of equal size). Replace the dst pixels with the
- * corresponding src pixels, performing any colortype/alphatype transformations needed
- * (in the case where the src and dst have different colortypes or alphatypes).
- *
- * This call can fail, returning false, for several reasons:
- * - If srcR does not intersect the image bounds.
- * - If the requested colortype/alphatype cannot be converted from the image's types.
- */
+ /** Copies SkRect of pixels from SkImage to dstPixels. Copy starts at offset (srcX, srcY),
+ and does not exceed SkImage (width(), height()).
+
+ dstInfo specifies width, height, SkColorType, SkAlphaType, and SkColorSpace 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
+ - dstRowBytes is less than dstInfo.minRowBytes()
+ - SkPixelRef is nullptr
+
+ Pixels are copied only if pixel conversion is possible. If SkImage SkColorType is
+ kGray_8_SkColorType, or kAlpha_8_SkColorType; dstInfo.colorType() must match.
+ If SkImage SkColorType is kGray_8_SkColorType, dstInfo.colorSpace() must match.
+ If SkImage SkAlphaType is kOpaque_SkAlphaType, dstInfo.alphaType() must
+ match. If SkImage SkColorSpace 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 abs(srcX) >= Image width(), or if abs(srcY) >= Image height().
+
+ If cachingHint is kAllow_CachingHint, pixels may be retained locally.
+ If cachingHint is kDisallow_CachingHint, pixels are not added to the local cache.
+
+ @param dstInfo destination width, height, SkColorType, SkAlphaType, SkColorSpace
+ @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
+ */
bool readPixels(const SkImageInfo& dstInfo, void* dstPixels, size_t dstRowBytes,
int srcX, int srcY, CachingHint cachingHint = kAllow_CachingHint) const;
+ /** Copies a SkRect of pixels from SkImage to dst. Copy starts at (srcX, srcY), and
+ does not exceed SkImage (width(), height()).
+
+ dst specifies width, height, SkColorType, SkAlphaType, SkColorSpace, 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:
+ - dst pixel storage equals nullptr
+ - dst.rowBytes is less than SkImageInfo::minRowBytes
+ - SkPixelRef is nullptr
+
+ Pixels are copied only if pixel conversion is possible. If SkImage SkColorType is
+ kGray_8_SkColorType, or kAlpha_8_SkColorType; dst.colorType() must match.
+ If SkImage SkColorType is kGray_8_SkColorType, dst.colorSpace() must match.
+ If SkImage SkAlphaType is kOpaque_SkAlphaType, dst.alphaType() must
+ match. If SkImage SkColorSpace 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 abs(srcX) >= Image width(), or if 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 SkPixmap: SkImageInfo, 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
+ */
bool readPixels(const SkPixmap& dst, int srcX, int srcY,
CachingHint cachingHint = kAllow_CachingHint) const;
- /**
- * Copy the pixels from this image into the dst pixmap, converting as needed into dst's
- * colortype/alphatype. If the conversion cannot be performed, false is returned.
- *
- * If dst's dimensions differ from the src dimension, the image will be scaled, applying the
- * specified filter-quality.
- */
+ /** Copies SkImage 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 SkImage SkColorType is
+ kGray_8_SkColorType, or kAlpha_8_SkColorType; dst.colorType() must match.
+ If SkImage SkColorType is kGray_8_SkColorType, dst.colorSpace() must match.
+ If SkImage SkAlphaType is kOpaque_SkAlphaType, dst.alphaType() must
+ match. If SkImage SkColorSpace is nullptr, dst.colorSpace() must match. Returns
+ false if pixel conversion is not possible.
+
+ Scales the image, with filterQuality, to match dst.width() and dst.height().
+ filterQuality kNone_SkFilterQuality is fastest, typically implemented with
+ nearest neighbor filter. kLow_SkFilterQuality is typically implemented with
+ bilerp filter. kMedium_SkFilterQuality is typically implemented with
+ bilerp filter, 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 SkPixmap: SkImageInfo, 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
+ */
bool scalePixels(const SkPixmap& dst, SkFilterQuality filterQuality,
CachingHint cachingHint = kAllow_CachingHint) const;
- /**
- * Encode the image's pixels and return the result as SkData. This will ignore any possible
- * existing encoded data (see refEncodedData()), and will always attempt to encode the
- * image using the specified encoded image format.
- *
- * If the image type cannot be encoded, or the requested encoder format is
- * not supported, this will return nullptr.
- */
+ /** Encodes SkImage pixels, returning result as SkData.
+
+ Returns nullptr if encoding fails, or if encodedImageFormat is not supported.
+
+ SkImage 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 SkImage, or nullptr
+ */
sk_sp<SkData> encodeToData(SkEncodedImageFormat encodedImageFormat, int quality) const;
- /**
- * Encode the image and return the result as SkData. This will attempt to reuse existing
- * encoded data (as returned by refEncodedData). If there is no eisting data, the image
- * will be encoded using PNG. On an error, this returns nullptr.
- */
+ /** Encodes SkImage pixels, returning result as SkData. Returns existing encoded data
+ if present; otherwise, SkImage is encoded with SkEncodedImageFormat::kPNG. Skia
+ must be built with SK_HAS_PNG_LIBRARY to encode SkImage.
+
+ Returns nullptr if existing encoded data is missing or invalid, and
+ encoding fails.
+
+ @return encoded SkImage, or nullptr
+ */
sk_sp<SkData> encodeToData() const;
- /**
- * If the image already has its contents in encoded form (e.g. PNG or JPEG), return that
- * as SkData. If the image does not already has its contents in encoded form, return NULL.
- *
- * Note: to force the image to return its contents as encoded data, use encodeToData(...).
- */
+ /** Returns encoded SkImage pixels as SkData, if SkImage was created from supported
+ encoded stream format. Platform support for formats vary and may require building
+ with one or more of: SK_HAS_JPEG_LIBRARY, SK_HAS_PNG_LIBRARY, SK_HAS_WEBP_LIBRARY.
+
+ Returns nullptr if SkImage contents are not encoded.
+
+ @return encoded SkImage, or nullptr
+ */
sk_sp<SkData> refEncodedData() const;
+ /** Appends SkImage description to string, including unique ID, width, height, and
+ whether the image is opaque.
+
+ @param string storage for description; existing content is preserved
+ @return string appended with SkImage description
+ */
const char* toString(SkString* string) const;
- /**
- * Return a new image that is a subset of this image. The underlying implementation may
- * share the pixels, or it may make a copy.
- *
- * If subset does not intersect the bounds of this image, or the copy/share cannot be made,
- * NULL will be returned.
- */
+ /** Returns subset of SkImage. subset must be fully contained by SkImage dimensions().
+ The implementation may share pixels, or may copy them.
+
+ Returns nullptr if subset is empty, or subset is not contained by bounds, or
+ pixels in SkImage could not be read or copied.
+
+ @param subset bounds of returned SkImage
+ @return partial or full SkImage, or nullptr
+ */
sk_sp<SkImage> makeSubset(const SkIRect& subset) const;
- /**
- * Ensures that an image is backed by a texture (when GrContext is non-null), suitable for use
- * with surfaces that have the supplied destination color space. If no transformation is
- * required, the returned image may be the same as this image. If this image is from a
- * different GrContext, this will fail.
- */
+ /** Returns SkImage backed by GPU texture associated with context. Returned SkImage is
+ compatible with SkSurface created with dstColorSpace. Returns original
+ SkImage if context and dstColorSpace match.
+
+ Returns nullptr if context is nullptr, or if SkImage was created with another
+ GrContext.
+
+ @param context GPU context
+ @param dstColorSpace range of colors of matching SkSurface on GPU
+ @return created SkImage, or nullptr
+ */
sk_sp<SkImage> makeTextureImage(GrContext* context, SkColorSpace* dstColorSpace) const;
- /**
- * If the image is texture-backed this will make a raster copy of it (or nullptr if reading back
- * the pixels fails). Otherwise, it returns the original image.
- */
+ /** Returns raster image or lazy image. Copies SkImage backed by GPU texture into
+ CPU memory if needed. Returns original SkImage if decoded in raster bitmap,
+ or if encoded in a stream.
+
+ Returns nullptr if backed by GPU texture and copy fails.
+
+ @return raster image, lazy image, or nullptr
+ */
sk_sp<SkImage> makeNonTextureImage() const;
- /**
- * If this image is already backed by raster (i.e. peekPixels would succeed), then this just
- * returns itself. If not, this attempts to create a raster version of this image and returns
- * that, or nullptr if that fails.
- */
+ /** Returns raster image. Copies SkImage backed by GPU texture into CPU memory,
+ or decodes SkImage from lazy image. Returns original SkImage if decoded in
+ raster bitmap.
+
+ Returns nullptr if copy, decode, or pixel read fails.
+
+ @return raster image, or nullptr
+ */
sk_sp<SkImage> makeRasterImage() const;
- /**
- * Apply a given image filter to this image, and return the filtered result.
- *
- * The subset represents the active portion of this image. The return value is similarly an
- * SkImage, with an active subset (outSubset). This is usually used with texture-backed
- * images, where the texture may be approx-match and thus larger than the required size.
- *
- * clipBounds constrains the device-space extent of the image which may be produced to the
- * given rect.
- *
- * offset is the amount to translate the resulting image relative to the src when it is drawn.
- * This is an out-param.
- *
- * If the result image cannot be created, or the result would be transparent black, null
- * is returned, in which case the offset and outSubset parameters should be ignored by the
- * caller.
- */
+ /** Creates filtered SkImage. filter processes original SkImage, potentially changing
+ color, position, and size. subset is the bounds of original SkImage processed
+ by filter. clipBounds is the expected bounds of the filtered SkImage. outSubset
+ is required storage for the actual bounds of the filtered SkImage. offset is
+ required storage for translation of returned SkImage.
+
+ Returns nullptr if SkImage could not be created. If nullptr is returned, outSubset
+ and offset are undefined.
+
+ Useful for animation of SkImageFilter that varies size from frame to frame.
+ Returned SkImage is created larger than required by filter so that GPU texture
+ can be reused with different sized effects. outSubset describes the valid bounds
+ of GPU texture returned. offset translates the returned SkImage to keep subsequent
+ animation frames aligned with respect to each other.
+
+ @param filter how SkImage is sampled when transformed
+ @param subset bounds of SkImage processed by filter
+ @param clipBounds expected bounds of filtered SkImage
+ @param outSubset storage for returned SkImage bounds
+ @param offset storage for returned SkImage translation
+ @return filtered SkImage, or nullptr
+ */
sk_sp<SkImage> makeWithFilter(const SkImageFilter* filter, const SkIRect& subset,
const SkIRect& clipBounds, SkIRect* outSubset,
SkIPoint* offset) const;
typedef std::function<void(GrBackendTexture)> BackendTextureReleaseProc;
- /**
- * Creates a GrBackendTexture from the provided SkImage. Returns true on success. The
- * GrBackendTexture and BackendTextureReleaseProc are populated on success. It is the callers
- * responsibility to call the BackendTextureReleaseProc once they have deleted the texture.
- *
- * Note that the BackendTextureReleaseProc allows Skia to clean up auxiliary data related
- * to the GrBackendTexture, and is not a substitute for the client deleting the GrBackendTexture
- * themselves.
- *
- * Note that if the SkImage is both texture backed and unowned (the only reference is
- * std::moved into this function), Skia can return the texture directly, avoiding any
- * conversions or copies.
- *
- * If the SkImage is not texture backed, this function will generate a texture with the image's
- * contents and return that.
- */
+ /** Creates a GrBackendTexture from the provided SkImage. Returns true and
+ stores result in backendTexture and backendTextureReleaseProc if
+ texture is created; otherwise, returns false and leaves
+ backendTexture and backendTextureReleaseProc unmodified.
+
+ Call backendTextureReleaseProc after deleting backendTexture.
+ backendTextureReleaseProc cleans up auxiliary data related to returned
+ backendTexture. The caller must delete returned backendTexture after use.
+
+ If SkImage is both texture backed and singly referenced, image is returned in
+ backendTexture without conversion or making a copy. SkImage is singly referenced
+ if its was transferred solely using std::move().
+
+ If SkImage is not texture backed, returns texture with SkImage contents.
+
+ @param context GPU context
+ @param image SkImage used for texture
+ @param backendTexture storage for backend texture
+ @param backendTextureReleaseProc storage for clean up function
+ @return true if backend texture was created
+ */
static bool MakeBackendTextureFromSkImage(GrContext* context,
sk_sp<SkImage> image,
GrBackendTexture* backendTexture,
BackendTextureReleaseProc* backendTextureReleaseProc);
-
- // Helper functions to convert to SkBitmap
- // TODO: enum LegacyBitmapMode to be deprecated; keeping enum until callers are revised to omit
- // parameter
enum LegacyBitmapMode {
- kRO_LegacyBitmapMode,
+ kRO_LegacyBitmapMode, //!< Returned bitmap is read-only and immutable.
};
- /**
- * Attempt to create a bitmap with the same pixels as the image. The result will always be
- * a raster-backed bitmap (texture-backed bitmaps are DEPRECATED, and not supported here).
- *
- * The resulting bitmap will be marked as immutable.
- *
- * On succcess, returns true. On failure, returns false and the bitmap parameter will be reset
- * to empty.
- */
+ /** Creates raster SkBitmap with same pixels as SkImage. If legacyBitmapMode is
+ kRO_LegacyBitmapMode, returned bitmap is read-only and immutable.
+ Returns true if SkBitmap is stored in bitmap. Returns false and resets bitmap if
+ SkBitmap write did not succeed.
+
+ @param bitmap storage for legacy SkBitmap
+ @param legacyBitmapMode to be deprecated
+ @return true if SkBitmap was created
+ */
bool asLegacyBitmap(SkBitmap* bitmap, LegacyBitmapMode legacyBitmapMode = kRO_LegacyBitmapMode) const;
- /**
- * Returns true if the image is backed by an image-generator or other src that creates
- * (and caches) its pixels / texture on-demand.
- */
+ /** Returns true if SkImage is backed by an image-generator or other service that creates
+ and caches its pixels or texture on-demand.
+
+ @return true if SkImage is created as needed
+ */
bool isLazyGenerated() const;
- /**
- * If |target| is supported, returns an SkImage in the |target| color space.
- * Otherwise, returns nullptr.
- *
- * This will leave the image as is if it already in the |target| color space.
- * Otherwise, it will convert the pixels from the src color space to the |target|
- * color space. If this->colorSpace() is nullptr, the src color space will be
- * treated as sRGB.
- *
- * If |premulBehavior| is kIgnore, any premultiplication or unpremultiplication will
- * be performed in the gamma encoded space. If it is kRespect, premultiplication is
- * assumed to be linear.
- */
+ /** Creates SkImage in target SkColorSpace.
+ Returns nullptr if SkImage could not be created.
+
+ Returns original SkImage if it is in target SkColorSpace.
+ Otherwise, converts pixels from SkImage SkColorSpace to target SkColorSpace.
+ If SkImage colorSpace() returns nullptr, SkImage SkColorSpace is assumed to be sRGB.
+
+ SkTransferFunctionBehavior is to be deprecated.
+
+ Set premulBehavior to SkTransferFunctionBehavior::kRespect to convert SkImage
+ pixels to a linear space, before converting to destination SkColorType
+ and SkColorSpace.
+
+ Set premulBehavior to SkTransferFunctionBehavior::kIgnore to treat SkImage
+ pixels as linear, when converting to destination SkColorType
+ and SkColorSpace, ignoring pixel encoding.
+
+ @param target SkColorSpace describing color range of returned SkImage
+ @param premulBehavior one of: SkTransferFunctionBehavior::kRespect,
+ SkTransferFunctionBehavior::kIgnore
+ @return created SkImage in target SkColorSpace
+ */
sk_sp<SkImage> makeColorSpace(sk_sp<SkColorSpace> target,
SkTransferFunctionBehavior premulBehavior) const;
diff --git a/include/core/SkMatrix.h b/include/core/SkMatrix.h
index edbfedd5b0..333bcbf487 100644
--- a/include/core/SkMatrix.h
+++ b/include/core/SkMatrix.h
@@ -17,7 +17,7 @@ class SkString;
/** \class SkMatrix
SkMatrix holds a 3x3 matrix for transforming coordinates. This allows mapping
- points and vectors with translation, scaling, skewing, rotation, and
+ SkPoint and vectors with translation, scaling, skewing, rotation, and
perspective.
SkMatrix elements are in row major order. SkMatrix does not have a constructor,
@@ -317,44 +317,44 @@ public:
}
/** Returns scale factor multiplied by x input, contributing to x output.
- With mapPoints(), scales points along the x-axis.
+ With mapPoints(), scales SkPoint along the x-axis.
@return horizontal scale factor
*/
SkScalar getScaleX() const { return fMat[kMScaleX]; }
/** Returns scale factor multiplied by y input, contributing to y output.
- With mapPoints(), scales points along the y-axis.
+ With mapPoints(), scales SkPoint along the y-axis.
@return vertical scale factor
*/
SkScalar getScaleY() const { return fMat[kMScaleY]; }
/** Returns scale factor multiplied by x input, contributing to y output.
- With mapPoints(), skews points along the y-axis.
- Skew x and y together can rotate points.
+ With mapPoints(), skews SkPoint along the y-axis.
+ Skew x and y together can rotate SkPoint.
@return vertical skew factor
*/
SkScalar getSkewY() const { return fMat[kMSkewY]; }
/** Returns scale factor multiplied by y input, contributing to x output.
- With mapPoints(), skews points along the x-axis.
- Skew x and y together can rotate points.
+ With mapPoints(), skews SkPoint along the x-axis.
+ Skew x and y together can rotate SkPoint.
@return horizontal scale factor
*/
SkScalar getSkewX() const { return fMat[kMSkewX]; }
/** Returns translation contributing to x output.
- With mapPoints(), moves points along the x-axis.
+ With mapPoints(), moves SkPoint along the x-axis.
@return horizontal translation factor
*/
SkScalar getTranslateX() const { return fMat[kMTransX]; }
/** Returns translation contributing to y output.
- With mapPoints(), moves points along the y-axis.
+ With mapPoints(), moves SkPoint along the y-axis.
@return vertical translation factor
*/
@@ -510,7 +510,7 @@ public:
*/
void set9(const SkScalar buffer[9]);
- /** Sets SkMatrix to identity; which has no effect on mapped points. Sets SkMatrix to:
+ /** Sets SkMatrix to identity; which has no effect on mapped SkPoint. Sets SkMatrix to:
| 1 0 0 |
| 0 1 0 |
@@ -521,7 +521,7 @@ public:
*/
void reset();
- /** Sets SkMatrix to identity; which has no effect on mapped points. Sets SkMatrix to:
+ /** Sets SkMatrix to identity; which has no effect on mapped SkPoint. Sets SkMatrix to:
| 1 0 0 |
| 0 1 0 |
@@ -1142,13 +1142,13 @@ public:
If count is zero, sets SkMatrix to identity and returns true.
If count is one, sets SkMatrix to translate and returns true.
- If count is two or more, sets SkMatrix to map points if possible; returns false
+ If count is two or more, sets SkMatrix to map SkPoint if possible; returns false
if SkMatrix cannot be constructed. If count is four, SkMatrix may include
perspective.
- @param src points to map from
- @param dst points to map to
- @param count number of points in src and dst
+ @param src SkPoint to map from
+ @param dst SkPoint to map to
+ @param count number of SkPoint in src and dst
@return true if SkMatrix was constructed successfully
*/
bool setPolyToPoly(const SkPoint src[], const SkPoint dst[], int count);
@@ -1213,7 +1213,7 @@ public:
void setAffine(const SkScalar affine[6]);
/** Maps src SkPoint array of length count to dst SkPoint array of equal or greater
- length. Points are mapped by multiplying each SkPoint by SkMatrix. Given:
+ length. SkPoint are mapped by multiplying each SkPoint by SkMatrix. Given:
| A B C | | x |
Matrix = | D E F |, pt = | y |
@@ -1234,9 +1234,9 @@ public:
src and dst may point to the same storage.
- @param dst storage for mapped points
- @param src points to transform
- @param count number of points to transform
+ @param dst storage for mapped SkPoint
+ @param src SkPoint to transform
+ @param count number of SkPoint to transform
*/
void mapPoints(SkPoint dst[], const SkPoint src[], int count) const {
SkASSERT((dst && src && count > 0) || 0 == count);
@@ -1245,7 +1245,7 @@ public:
this->getMapPtsProc()(*this, dst, src, count);
}
- /** Maps pts SkPoint array of length count in place. Points are mapped by multiplying
+ /** Maps pts SkPoint array of length count in place. SkPoint are mapped by multiplying
each SkPoint by SkMatrix. Given:
| A B C | | x |
@@ -1265,8 +1265,8 @@ public:
Matrix * pt = |D E F| |y| = |Ax+By+C Dx+Ey+F Gx+Hy+I| = ------- , -------
|G H I| |1| Gx+Hy+I Gx+Hy+I
- @param pts storage for mapped points
- @param count number of points to transform
+ @param pts storage for mapped SkPoint
+ @param count number of SkPoint to transform
*/
void mapPoints(SkPoint pts[], int count) const {
this->mapPoints(pts, pts, count);
@@ -1440,7 +1440,7 @@ public:
Returned value is the same as calling rectStaysRect().
- @param dst storage for bounds of mapped points
+ @param dst storage for bounds of mapped SkPoint
@param src SkRect to map
@return true if dst is equivalent to mapped src
*/
@@ -1458,7 +1458,7 @@ public:
return this->mapRect(rect, *rect);
}
- /** Maps four corners of rect to dst. Points are mapped by multiplying each
+ /** Maps four corners of rect to dst. SkPoint are mapped by multiplying each
rect corner by SkMatrix. rect corner is processed in this order:
(rect.fLeft, rect.fTop), (rect.fRight, rect.fTop), (rect.fRight, rect.fBottom),
(rect.fLeft, rect.fBottom).
@@ -1480,7 +1480,7 @@ public:
Matrix * pt = |D E F| |y| = |Ax+By+C Dx+Ey+F Gx+Hy+I| = ------- , -------
|G H I| |1| Gx+Hy+I Gx+Hy+I
- @param dst storage for mapped corner points
+ @param dst storage for mapped corner SkPoint
@param rect SkRect to map
*/
void mapRectToQuad(SkPoint dst[4], const SkRect& rect) const {
@@ -1493,7 +1493,7 @@ public:
elements other than scale or translate: asserts if SK_DEBUG is defined;
otherwise, results are undefined.
- @param dst storage for bounds of mapped points
+ @param dst storage for bounds of mapped SkPoint
@param src SkRect to map
*/
void mapRectScaleTranslate(SkRect* dst, const SkRect& src) const;
@@ -1532,7 +1532,7 @@ public:
Returns false when the sign of zero values is the different; when one
matrix has positive zero value and the other has negative zero value.
- Returns true even when both matrices contain NaN.
+ Returns true even when both SkMatrix contain NaN.
NaN never equals any value, including itself. To improve performance, NaN values
are treated as bit patterns that are equal if their bit patterns are equal.
@@ -1550,7 +1550,7 @@ public:
@param a SkMatrix to compare
@param b SkMatrix to compare
- @return true if m and SkMatrix are numerically equal
+ @return true if SkMatrix a and SkMatrix b are numerically equal
*/
friend SK_API bool operator==(const SkMatrix& a, const SkMatrix& b);
@@ -1560,7 +1560,7 @@ public:
@param a SkMatrix to compare
@param b SkMatrix to compare
- @return true if m and SkMatrix are numerically not equal
+ @return true if SkMatrix a and SkMatrix b are numerically not equal
*/
friend SK_API bool operator!=(const SkMatrix& a, const SkMatrix& b) {
return !(a == b);
diff --git a/include/core/SkPaint.h b/include/core/SkPaint.h
index 407eab1eef..829388bc24 100644
--- a/include/core/SkPaint.h
+++ b/include/core/SkPaint.h
@@ -175,8 +175,7 @@ public:
by the client.
@param buffer serialized data describing SkPaint content
- @return false if the buffer contained invalid data to initialize the paint, in which case
- the paint will be reset().
+ @return false if the buffer contains invalid data
*/
bool unflatten(SkReadBuffer& buffer);
@@ -255,7 +254,7 @@ public:
kLinearText_Flag = 0x40, //!< mask for setting linear text
kSubpixelText_Flag = 0x80, //!< mask for setting subpixel text
kDevKernText_Flag = 0x100, //!< mask for setting full hinting spacing
- kLCDRenderText_Flag = 0x200, //!< mask for setting lcd text
+ kLCDRenderText_Flag = 0x200, //!< mask for setting LCD text
kEmbeddedBitmapText_Flag = 0x400, //!< mask for setting font embedded bitmaps
kAutoHinting_Flag = 0x800, //!< mask for setting auto-hinting
kVerticalText_Flag = 0x1000, //!< mask for setting vertical text
@@ -269,8 +268,8 @@ public:
#ifdef SK_BUILD_FOR_ANDROID_FRAMEWORK
enum ReserveFlags {
- kUnderlineText_ReserveFlag = 0x08, //!< mask for underline text
- kStrikeThruText_ReserveFlag = 0x10, //!< mask for strike-thru text
+ kUnderlineText_ReserveFlag = 0x08, //!< deprecated
+ kStrikeThruText_ReserveFlag = 0x10, //!< deprecated
};
#endif
@@ -657,6 +656,8 @@ public:
kDefault_Cap = kButt_Cap,
};
+ /** The number of different SkPaint::Cap values defined.
+ May be used to verify that SkPaint::Cap is a legal value.*/
static constexpr int kCapCount = kLast_Cap + 1;
/** \enum SkPaint::Join
@@ -689,6 +690,8 @@ public:
kDefault_Join = kMiter_Join,
};
+ /** The number of different SkPaint::Join values defined.
+ May be used to verify that SkPaint::Join is a legal value.*/
static constexpr int kJoinCount = kLast_Join + 1;
/** The geometry drawn at the beginning and end of strokes.
@@ -852,6 +855,8 @@ public:
SkMaskFilter. Pass nullptr to clear SkMaskFilter and leave SkMaskFilter effect on
mask alpha unaltered.
+ Increments maskFilter SkRefCnt by one.
+
@param maskFilter modifies clipping mask generated from drawn geometry
*/
void setMaskFilter(sk_sp<SkMaskFilter> maskFilter);
@@ -895,6 +900,8 @@ public:
SkImageFilter. Pass nullptr to clear SkImageFilter, and remove SkImageFilter effect
on drawing.
+ Increments imageFilter SkRefCnt by one.
+
@param imageFilter how SkImage is sampled when transformed
*/
void setImageFilter(sk_sp<SkImageFilter> imageFilter);
@@ -914,9 +921,7 @@ public:
sk_sp<SkDrawLooper> refDrawLooper() const;
/** Deprecated.
- (see bug.skia.org/6259)
-
- @return SkDrawLooper if previously set, nullptr otherwise
+ (see skbug.com/6259)
*/
SkDrawLooper* getLooper() const { return fDrawLooper.get(); }
@@ -931,9 +936,7 @@ public:
void setDrawLooper(sk_sp<SkDrawLooper> drawLooper);
/** Deprecated.
- (see bug.skia.org/6259)
-
- @param drawLooper sets SkDrawLooper to drawLooper
+ (see skbug.com/6259)
*/
void setLooper(sk_sp<SkDrawLooper> drawLooper);
diff --git a/include/core/SkPath.h b/include/core/SkPath.h
index f3d7953391..1586f2bf60 100644
--- a/include/core/SkPath.h
+++ b/include/core/SkPath.h
@@ -17,11 +17,11 @@ class SkRRect;
class SkWStream;
/** \class SkPath
- Paths contain geometry. Paths may be empty, or contain one or more verbs that
+ SkPath contain geometry. SkPath may be empty, or contain one or more verbs that
outline a figure. SkPath always starts with a move verb to a Cartesian_Coordinate,
and may be followed by additional verbs that add lines or curves.
Adding a close verb makes the geometry into a continuous loop, a closed contour.
- Paths may contain any number of contours, each beginning with a move verb.
+ SkPath may contain any number of contours, each beginning with a move verb.
SkPath contours may contain only a move verb, or may also contain lines,
quadratic beziers, conics, and cubic beziers. SkPath contours may be open or
@@ -55,7 +55,7 @@ public:
kCCW_Direction, //!< Contour travels in a counterclockwise direction
};
- /** By default, SkPath has no verbs, no points, and no weights.
+ /** By default, SkPath has no verbs, no SkPoint, and no weights.
SkPath::FillType is set to kWinding_FillType.
@return empty SkPath
@@ -67,7 +67,7 @@ public:
and weights are copied when modified.
Creating a SkPath copy is very efficient and never allocates memory.
- Paths are always copied by value from the interface; the underlying shared
+ SkPath are always copied by value from the interface; the underlying shared
pointers are not exposed.
@param path SkPath to copy by value
@@ -83,8 +83,8 @@ public:
shares pointer values. The underlying verb array, SkPoint array and weights
are copied when modified.
- Copying paths by assignment is very efficient and never allocates memory.
- Paths are always copied by value from the interface; the underlying shared
+ Copying SkPath by assignment is very efficient and never allocates memory.
+ SkPath are always copied by value from the interface; the underlying shared
pointers are not exposed.
@param path verb array, SkPoint array, weights, and SkPath::FillType to copy
@@ -112,21 +112,21 @@ public:
return !(a == b);
}
- /** Return true if paths contain equal verbs and equal weights.
- If paths contain one or more conics, the weights must match.
+ /** Return true if SkPath contain equal verbs and equal weights.
+ If SkPath contain one or more conics, the weights must match.
conicTo() may add different verbs depending on conic weight, so it is not
- trivial to interpolate a pair of paths containing conics with different
+ trivial to interpolate a pair of SkPath containing conics with different
conic weight values.
@param compare SkPath to compare
- @return true if paths verb array and weights are equivalent
+ @return true if SkPath verb array and weights are equivalent
*/
bool isInterpolatable(const SkPath& compare) const;
- /** Interpolate between paths with SkPoint array of equal size.
+ /** Interpolate between SkPath with SkPoint array of equal size.
Copy verb array and weights to out, and set out SkPoint array to a weighted
- average of this SkPoint array and ending SkPoint array, using the formula: (this->points * weight) + ending->points * (1 - weight).
+ average of this SkPoint array and ending SkPoint array, using the formula: (Path Point * weight) + ending Point * (1 - weight).
weight is most useful when between zero (ending SkPoint array) and
one (this Point_Array); will work with values outside of this
@@ -140,14 +140,13 @@ public:
@param weight contribution of this SkPoint array, and
one minus contribution of ending SkPoint array
@param out SkPath replaced by interpolated averages
- @return true if paths contain same number of points
+ @return true if SkPath contain same number of SkPoint
*/
bool interpolate(const SkPath& ending, SkScalar weight, SkPath* out) const;
#ifdef SK_BUILD_FOR_ANDROID_FRAMEWORK
- /** To be deprecated; only valid for Android framework.
-
- @return true if SkPath has one owner
+ /** To be deprecated soon.
+ Only valid for Android framework.
*/
bool unique() const { return fPathRef->unique(); }
#endif
@@ -272,22 +271,26 @@ public:
return kConvex_Convexity == this->getConvexity();
}
- /**
- * Returns true if this path is recognized as an oval or circle.
- *
- * @param bounds If this returns true and bounds is not null, then it is set to the
- * bounds of the oval that matches this path. If this returns false,
- * then this parameter is ignored.
- */
+ /** Returns true if this path is recognized as an oval or circle.
+
+ bounds receives bounds of oval.
+
+ bounds is unmodified if oval is not found.
+
+ @param bounds storage for bounding SkRect of oval; may be nullptr
+ @return true if SkPath is recognized as an oval or circle
+ */
bool isOval(SkRect* bounds) const;
- /**
- * Returns true if this path is recognized as a SkRRect (but not an oval/circle or rect).
- *
- * @param rrect If this returns true and rrect is not null, then it is set to the
- * SkRRect that matches this path. If this returns false, then this parameter
- * is ignored.
- */
+ /** Returns true if this path is recognized as a SkRRect (but not an oval/circle or rect).
+
+ rrect receives bounds of SkRRect.
+
+ rrect is unmodified if SkRRect is not found.
+
+ @param rrect storage for bounding SkRect of SkRRect; may be nullptr
+ @return true if SkPath contains only SkRRect
+ */
bool isRRect(SkRRect* rrect) const;
/** Sets SkPath to its initial state.
@@ -334,7 +337,7 @@ public:
}
/** Returns true if the path is volatile; it will not be altered or discarded
- by the caller after it is drawn. Paths by default have volatile set false, allowing
+ by the caller after it is drawn. SkPath by default have volatile set false, allowing
SkSurface to attach a cache of data which speeds repeated drawing. If true, SkSurface
may not speed repeated drawing.
@@ -345,7 +348,7 @@ public:
}
/** Specify whether SkPath is volatile; whether it will be altered or discarded
- by the caller after it is drawn. Paths by default have volatile set false, allowing
+ by the caller after it is drawn. SkPath by default have volatile set false, allowing
SkBaseDevice to attach a cache of data which speeds repeated drawing.
Mark temporary paths, discarded or modified after use, as volatile
@@ -464,7 +467,7 @@ public:
it is lightweight and does not allocate memory.
swap() usage has largely been replaced by operator=(const SkPath& path).
- Paths do not copy their content on assignment until they are written to,
+ SkPath do not copy their content on assignment until they are written to,
making assignment as efficient as swap().
@param other SkPath exchanged by value
@@ -475,10 +478,10 @@ public:
Returns (0, 0, 0, 0) if SkPath contains no points. Returned bounds width and height may
be larger or smaller than area affected when SkPath is drawn.
- SkRect returned includes all points added to SkPath, including points associated with
+ SkRect returned includes all SkPoint added to SkPath, including SkPoint associated with
kMove_Verb that define empty contours.
- @return bounds of all points in SkPoint array
+ @return bounds of all SkPoint in SkPoint array
*/
const SkRect& getBounds() const {
return fPathRef->getBounds();
@@ -502,7 +505,7 @@ public:
Returned bounds width and height may be larger or smaller than area affected
when SkPath is drawn.
- Includes points associated with kMove_Verb that define empty
+ Includes SkPoint associated with kMove_Verb that define empty
contours.
Behaves identically to getBounds() when SkPath contains
@@ -527,11 +530,11 @@ public:
*/
bool conservativelyContainsRect(const SkRect& rect) const;
- /** grows SkPath verb array and SkPoint array to contain extraPtCount additional points.
+ /** grows SkPath verb array and SkPoint array to contain extraPtCount additional SkPoint.
May improve performance and use less memory by
reducing the number and size of allocations when creating SkPath.
- @param extraPtCount number of additional points to allocate
+ @param extraPtCount number of additional SkPoint to allocate
*/
void incReserve(unsigned extraPtCount);
@@ -616,7 +619,7 @@ public:
before adding quad.
Appends kMove_Verb to verb array and (0, 0) to SkPoint array, if needed;
- then appends kQuad_Verb to verb array; and points p1, p2
+ then appends kQuad_Verb to verb array; and SkPoint p1, p2
to SkPoint array.
@param p1 control SkPoint of added quad
@@ -675,13 +678,13 @@ public:
Appends kMove_Verb to verb array and (0, 0) to SkPoint array, if needed.
If w is finite and not one, appends kConic_Verb to verb array;
- and points p1, p2 to SkPoint array; and w to conic weights.
+ and SkPoint p1, p2 to SkPoint array; and w to conic weights.
- If w is one, appends kQuad_Verb to verb array, and points p1, p2
+ If w is one, appends kQuad_Verb to verb array, and SkPoint p1, p2
to SkPoint array.
If w is not finite, appends kLine_Verb twice to verb array, and
- points p1, p2 to SkPoint array.
+ SkPoint p1, p2 to SkPoint array.
@param p1 control SkPoint of added conic
@param p2 end SkPoint of added conic
@@ -703,7 +706,7 @@ public:
kQuad_Verb to verb array; or if w is not finite, appends kLine_Verb
twice to verb array.
- In all cases appends points control and end to SkPoint array.
+ In all cases appends SkPoint control and end to SkPoint array.
control is last point plus vector (dx1, dy1).
end is last point plus vector (dx2, dy2).
@@ -741,7 +744,7 @@ public:
(0, 0) before adding cubic.
Appends kMove_Verb to verb array and (0, 0) to SkPoint array, if needed;
- then appends kCubic_Verb to verb array; and points p1, p2, p3
+ then appends kCubic_Verb to verb array; and SkPoint p1, p2, p3
to SkPoint array.
@param p1 first control SkPoint of cubic
@@ -1174,7 +1177,7 @@ public:
kAppend_AddPathMode,
/** is not empty, add line from last point to added SkPath first SkPoint. Skip added
- SkPath initial kMove_Verb, then append remining verbs, points, and conic weights.
+ SkPath initial kMove_Verb, then append remining verbs, SkPoint, and conic weights.
*/
kExtend_AddPathMode,
};
@@ -1183,9 +1186,9 @@ public:
If mode is kAppend_AddPathMode, src verb array, SkPoint array, and conic weights are
added unaltered. If mode is kExtend_AddPathMode, add line before appending
- verbs, points, and conic weights.
+ verbs, SkPoint, and conic weights.
- @param src SkPath verbs, points, and conic weights to add
+ @param src SkPath verbs, SkPoint, and conic weights to add
@param dx offset added to src SkPoint array x coordinates
@param dy offset added to src SkPoint array y coordinates
@param mode kAppend_AddPathMode or kExtend_AddPathMode
@@ -1197,9 +1200,9 @@ public:
If mode is kAppend_AddPathMode, src verb array, SkPoint array, and conic weights are
added unaltered. If mode is kExtend_AddPathMode, add line before appending
- verbs, points, and conic weights.
+ verbs, SkPoint, and conic weights.
- @param src SkPath verbs, points, and conic weights to add
+ @param src SkPath verbs, SkPoint, and conic weights to add
@param mode kAppend_AddPathMode or kExtend_AddPathMode
*/
void addPath(const SkPath& src, AddPathMode mode = kAppend_AddPathMode) {
@@ -1209,13 +1212,13 @@ public:
}
/** Append src to SkPath, transformed by matrix. Transformed curves may have different
- verbs, points, and conic weights.
+ verbs, SkPoint, and conic weights.
If mode is kAppend_AddPathMode, src verb array, SkPoint array, and conic weights are
added unaltered. If mode is kExtend_AddPathMode, add line before appending
- verbs, points, and conic weights.
+ verbs, SkPoint, and conic weights.
- @param src SkPath verbs, points, and conic weights to add
+ @param src SkPath verbs, SkPoint, and conic weights to add
@param matrix transform applied to src
@param mode kAppend_AddPathMode or kExtend_AddPathMode
*/
@@ -1224,7 +1227,7 @@ public:
/** Append src to SkPath, from back to front.
Reversed src always appends a new contour to SkPath.
- @param src SkPath verbs, points, and conic weights to add
+ @param src SkPath verbs, SkPoint, and conic weights to add
*/
void reverseAddPath(const SkPath& src);
@@ -1270,7 +1273,7 @@ public:
storing (0, 0) if lastPt is not nullptr.
@param lastPt storage for final SkPoint in SkPoint array; may be nullptr
- @return true if SkPoint array contains one or more points
+ @return true if SkPoint array contains one or more SkPoint
*/
bool getLastPt(SkPoint* lastPt) const;
@@ -1340,7 +1343,7 @@ public:
*/
kConic_Verb,
- /** Adds cubic from last point, using two control points, and end SkPoint.
+ /** Adds cubic from last point, using two control SkPoint, and end SkPoint.
Cubic is a third-order Bezier_Curve section within tangents from last point
to first control SkPoint, and from second control SkPoint to end SkPoint.
*/
@@ -1354,25 +1357,25 @@ public:
class SK_API Iter {
public:
- /** Initializes iter with an empty SkPath. next() on iter returns kDone_Verb.
- Call setPath to initialize iter at a later time.
+ /** Initializes SkPath::Iter with an empty SkPath. next() on SkPath::Iter returns kDone_Verb.
+ Call setPath to initialize SkPath::Iter at a later time.
- @return iter of empty SkPath
+ @return SkPath::Iter of empty SkPath
*/
Iter();
- /** Sets iter to return elements of verb array, SkPoint array, and conic weight in path.
- If forceClose is true, iter will add kLine_Verb and kClose_Verb after each
+ /** Sets SkPath::Iter to return elements of verb array, SkPoint array, and conic weight in path.
+ If forceClose is true, SkPath::Iter will add kLine_Verb and kClose_Verb after each
open contour. path is not altered.
@param path SkPath to iterate
@param forceClose true if open contours generate kClose_Verb
- @return iter of path
+ @return SkPath::Iter of path
*/
Iter(const SkPath& path, bool forceClose);
- /** Sets iter to return elements of verb array, SkPoint array, and conic weight in path.
- If forceClose is true, iter will add kLine_Verb and kClose_Verb after each
+ /** Sets SkPath::Iter to return elements of verb array, SkPoint array, and conic weight in path.
+ If forceClose is true, SkPath::Iter will add kLine_Verb and kClose_Verb after each
open contour. path is not altered.
@param path SkPath to iterate
@@ -1380,10 +1383,10 @@ public:
*/
void setPath(const SkPath& path, bool forceClose);
- /** Returns next SkPath::Verb in verb array, and advances iter.
+ /** Returns next SkPath::Verb in verb array, and advances SkPath::Iter.
When verb array is exhausted, returns kDone_Verb.
- Zero to four points are stored in pts, depending on the returned SkPath::Verb.
+ Zero to four SkPoint are stored in pts, depending on the returned SkPath::Verb.
If doConsumeDegenerates is true, skip consecutive kMove_Verb entries, returning
only the last in the series; and skip very small lines, quads, and conics; and
@@ -1408,7 +1411,7 @@ public:
If next() has not been called, or next() did not return kConic_Verb,
result is undefined.
- @return conic weight for conic points returned by next()
+ @return conic weight for conic SkPoint returned by next()
*/
SkScalar conicWeight() const { return *fConicWeights; }
@@ -1424,8 +1427,8 @@ public:
bool isCloseLine() const { return SkToBool(fCloseLine); }
/** Returns true if subsequent calls to next() return kClose_Verb before returning
- kMove_Verb. if true, contour iter is processing may end with kClose_Verb, or
- iter may have been initialized with force close set to true.
+ kMove_Verb. if true, contour SkPath::Iter is processing may end with kClose_Verb, or
+ SkPath::Iter may have been initialized with force close set to true.
@return true if contour is closed
*/
@@ -1456,7 +1459,7 @@ public:
public:
/** Initializes RawIter with an empty SkPath. next() on RawIter returns kDone_Verb.
- Call setPath to initialize iter at a later time.
+ Call setPath to initialize SkPath::Iter at a later time.
@return RawIter of empty SkPath
*/
@@ -1471,7 +1474,7 @@ public:
setPath(path);
}
- /** Sets iter to return elements of verb array, SkPoint array, and conic weight in path.
+ /** Sets SkPath::Iter to return elements of verb array, SkPoint array, and conic weight in path.
@param path SkPath to iterate
*/
@@ -1481,7 +1484,7 @@ public:
/** Returns next SkPath::Verb in verb array, and advances RawIter.
When verb array is exhausted, returns kDone_Verb.
- Zero to four points are stored in pts, depending on the returned SkPath::Verb.
+ Zero to four SkPoint are stored in pts, depending on the returned SkPath::Verb.
@param pts storage for SkPoint data describing returned SkPath::Verb
@return next SkPath::Verb from verb array
@@ -1503,7 +1506,7 @@ public:
If next() has not been called, or next() did not return kConic_Verb,
result is undefined.
- @return conic weight for conic points returned by next()
+ @return conic weight for conic SkPoint returned by next()
*/
SkScalar conicWeight() const {
return fRawIter.conicWeight();
@@ -1592,12 +1595,14 @@ public:
*/
size_t readFromMemory(const void* buffer, size_t length);
- /** Returns a non-zero, globally unique value. A different value is returned
+ /** (see skbug.com/1762)
+ Returns a non-zero, globally unique value. A different value is returned
if verb array, SkPoint array, or conic weight changes.
Setting SkPath::FillType does not change generation id.
Each time the path is modified, a different generation id will be returned.
+ SkPath::FillType does affect generation id on Android framework.
@return non-zero, globally unique value
*/
diff --git a/include/core/SkPixmap.h b/include/core/SkPixmap.h
index c8b83004f0..1d53d2adc0 100644
--- a/include/core/SkPixmap.h
+++ b/include/core/SkPixmap.h
@@ -96,15 +96,7 @@ public:
*/
void setColorSpace(sk_sp<SkColorSpace> colorSpace);
- /** Sets width, height, pixel address, and row bytes to SkMask properties, if SkMask
- format is SkMask::kA8_Format; and returns true. Otherwise sets width, height,
- row bytes to zero; pixel address to nullptr; SkColorType to kUnknown_SkColorType;
- and SkAlphaType to kUnknown_SkAlphaType; and returns false.
-
- Failing to read the return value generates a compile time warning.
-
- @param mask SkMask containing pixels and dimensions
- @return true if set to SkMask properties
+ /** To be deprecated soon.
*/
bool SK_WARN_UNUSED_RESULT reset(const SkMask& mask);
@@ -120,7 +112,7 @@ public:
*/
bool SK_WARN_UNUSED_RESULT extractSubset(SkPixmap* subset, const SkIRect& area) const;
- /** Returns width, height, alpha type, color type, and SkColorSpace.
+ /** Returns width, height, SkAlphaType, SkColorType, and SkColorSpace.
@return reference to ImageInfo
*/
@@ -157,18 +149,19 @@ public:
*/
int height() const { return fInfo.height(); }
- /** Returns color type, one of: kUnknown_SkColorType, kAlpha_8_SkColorType,
+ /** Returns SkColorType, one of: kUnknown_SkColorType, kAlpha_8_SkColorType,
kRGB_565_SkColorType, kARGB_4444_SkColorType, kRGBA_8888_SkColorType,
- kBGRA_8888_SkColorType, kGray_8_SkColorType, kRGBA_F16_SkColorType.
+ kRGB_888x_SkColorType, kBGRA_8888_SkColorType, kRGBA_1010102_SkColorType,
+ kRGB_101010x_SkColorType, kGray_8_SkColorType, kRGBA_F16_SkColorType.
- @return color type in SkImageInfo
+ @return SkColorType in SkImageInfo
*/
SkColorType colorType() const { return fInfo.colorType(); }
- /** Returns alpha type, one of: kUnknown_SkAlphaType, kOpaque_SkAlphaType,
+ /** Returns SkAlphaType, one of: kUnknown_SkAlphaType, kOpaque_SkAlphaType,
kPremul_SkAlphaType, kUnpremul_SkAlphaType.
- @return alpha type in SkImageInfo
+ @return SkAlphaType in SkImageInfo
*/
SkAlphaType alphaType() const { return fInfo.alphaType(); }
@@ -180,11 +173,11 @@ public:
*/
SkColorSpace* colorSpace() const { return fInfo.colorSpace(); }
- /** Returns true if alpha type is kOpaque_SkAlphaType.
- Does not check if color type allows alpha, or if any pixel value has
+ /** Returns true if SkAlphaType is kOpaque_SkAlphaType.
+ Does not check if SkColorType allows alpha, or if any pixel value has
transparency.
- @return true if SkImageInfo has opaque alpha type
+ @return true if SkImageInfo has opaque SkAlphaType
*/
bool isOpaque() const { return fInfo.isOpaque(); }
@@ -218,30 +211,30 @@ public:
*/
size_t computeByteSize() const { return fInfo.computeByteSize(fRowBytes); }
- /** Returns true if all pixels are opaque. color type determines how pixels
- are encoded, and whether pixel describes alpha. Returns true for color types
- without alpha in each pixel; for other color types, returns true if all
+ /** Returns true if all pixels are opaque. SkColorType determines how pixels
+ are encoded, and whether pixel describes alpha. Returns true for SkColorType
+ without alpha in each pixel; for other SkColorType, returns true if all
pixels have alpha values equivalent to 1.0 or greater.
- For color types kRGB_565_SkColorType or kGray_8_SkColorType: always
- returns true. For color types kAlpha_8_SkColorType, kBGRA_8888_SkColorType,
+ For SkColorType kRGB_565_SkColorType or kGray_8_SkColorType: always
+ returns true. For SkColorType kAlpha_8_SkColorType, kBGRA_8888_SkColorType,
kRGBA_8888_SkColorType: returns true if all pixel alpha values are 255.
- For color type kARGB_4444_SkColorType: returns true if all pixel alpha values are 15.
+ For SkColorType kARGB_4444_SkColorType: returns true if all pixel alpha values are 15.
For kRGBA_F16_SkColorType: returns true if all pixel alpha values are 1.0 or
greater.
Returns false for kUnknown_SkColorType.
- @return true if all pixels have opaque values or color type is opaque
+ @return true if all pixels have opaque values or SkColorType is opaque
*/
bool computeIsOpaque() const;
/** Returns pixel at (x, y) as unpremultiplied color.
- Returns black with alpha if color type is kAlpha_8_SkColorType.
+ Returns black with alpha if SkColorType is kAlpha_8_SkColorType.
Input is not validated: out of bounds values of x or y trigger an assert() if
built with SK_DEBUG defined; and returns undefined values or may crash if
- SK_RELEASE is defined. Fails if color type is kUnknown_SkColorType or
+ SK_RELEASE is defined. Fails if SkColorType is kUnknown_SkColorType or
pixel address is nullptr.
SkColorSpace in SkImageInfo is ignored. Some color precision may be lost in the
@@ -257,7 +250,7 @@ public:
/** Returns readable pixel address at (x, y). Returns nullptr if SkPixelRef is nullptr.
Input is not validated: out of bounds values of x or y trigger an assert() if
- built with SK_DEBUG defined. Returns nullptr if color type is kUnknown_SkColorType.
+ built with SK_DEBUG defined. Returns nullptr if SkColorType is kUnknown_SkColorType.
Performs a lookup of pixel size; for better performance, call
one of: addr8, addr16, addr32, addr64, or addrF16().
@@ -271,7 +264,7 @@ public:
}
/** Returns readable base pixel address. Result is addressable as unsigned 8-bit bytes.
- Will trigger an assert() if color type is not kAlpha_8_SkColorType or
+ Will trigger an assert() if SkColorType is not kAlpha_8_SkColorType or
kGray_8_SkColorType, and is built with SK_DEBUG defined.
One byte corresponds to one pixel.
@@ -284,7 +277,7 @@ public:
}
/** Returns readable base pixel address. Result is addressable as unsigned 16-bit words.
- Will trigger an assert() if color type is not kRGB_565_SkColorType or
+ Will trigger an assert() if SkColorType is not kRGB_565_SkColorType or
kARGB_4444_SkColorType, and is built with SK_DEBUG defined.
One word corresponds to one pixel.
@@ -297,7 +290,7 @@ public:
}
/** Returns readable base pixel address. Result is addressable as unsigned 32-bit words.
- Will trigger an assert() if color type is not kRGBA_8888_SkColorType or
+ Will trigger an assert() if SkColorType is not kRGBA_8888_SkColorType or
kBGRA_8888_SkColorType, and is built with SK_DEBUG defined.
One word corresponds to one pixel.
@@ -310,7 +303,7 @@ public:
}
/** Returns readable base pixel address. Result is addressable as unsigned 64-bit words.
- Will trigger an assert() if color type is not kRGBA_F16_SkColorType and is built
+ Will trigger an assert() if SkColorType is not kRGBA_F16_SkColorType and is built
with SK_DEBUG defined.
One word corresponds to one pixel.
@@ -323,7 +316,7 @@ public:
}
/** Returns readable base pixel address. Result is addressable as unsigned 16-bit words.
- Will trigger an assert() if color type is not kRGBA_F16_SkColorType and is built
+ Will trigger an assert() if SkColorType is not kRGBA_F16_SkColorType and is built
with SK_DEBUG defined.
Each word represents one color component encoded as a half float.
@@ -342,7 +335,7 @@ public:
Input is not validated: out of bounds values of x or y trigger an assert() if
built with SK_DEBUG defined.
- Will trigger an assert() if color type is not kAlpha_8_SkColorType or
+ Will trigger an assert() if SkColorType is not kAlpha_8_SkColorType or
kGray_8_SkColorType, and is built with SK_DEBUG defined.
@param x column index, zero or greater, and less than width()
@@ -360,7 +353,7 @@ public:
Input is not validated: out of bounds values of x or y trigger an assert() if
built with SK_DEBUG defined.
- Will trigger an assert() if color type is not kRGB_565_SkColorType or
+ Will trigger an assert() if SkColorType is not kRGB_565_SkColorType or
kARGB_4444_SkColorType, and is built with SK_DEBUG defined.
@param x column index, zero or greater, and less than width()
@@ -378,7 +371,7 @@ public:
Input is not validated: out of bounds values of x or y trigger an assert() if
built with SK_DEBUG defined.
- Will trigger an assert() if color type is not kRGBA_8888_SkColorType or
+ Will trigger an assert() if SkColorType is not kRGBA_8888_SkColorType or
kBGRA_8888_SkColorType, and is built with SK_DEBUG defined.
@param x column index, zero or greater, and less than width()
@@ -396,7 +389,7 @@ public:
Input is not validated: out of bounds values of x or y trigger an assert() if
built with SK_DEBUG defined.
- Will trigger an assert() if color type is not kRGBA_F16_SkColorType and is built
+ Will trigger an assert() if SkColorType is not kRGBA_F16_SkColorType and is built
with SK_DEBUG defined.
@param x column index, zero or greater, and less than width()
@@ -414,7 +407,7 @@ public:
Input is not validated: out of bounds values of x or y trigger an assert() if
built with SK_DEBUG defined.
- Will trigger an assert() if color type is not kRGBA_F16_SkColorType and is built
+ Will trigger an assert() if SkColorType is not kRGBA_F16_SkColorType and is built
with SK_DEBUG defined.
Each unsigned 16-bit word represents one color component encoded as a half float.
@@ -438,7 +431,7 @@ public:
/** Returns writable pixel address at (x, y).
Input is not validated: out of bounds values of x or y trigger an assert() if
- built with SK_DEBUG defined. Returns zero if color type is kUnknown_SkColorType.
+ built with SK_DEBUG defined. Returns zero if SkColorType is kUnknown_SkColorType.
@param x column index, zero or greater, and less than width()
@param y row index, zero or greater, and less than height()
@@ -449,7 +442,7 @@ public:
}
/** Returns writable pixel address at (x, y). Result is addressable as unsigned
- 8-bit bytes. Will trigger an assert() if color type is not kAlpha_8_SkColorType
+ 8-bit bytes. Will trigger an assert() if SkColorType is not kAlpha_8_SkColorType
or kGray_8_SkColorType, and is built with SK_DEBUG defined.
One byte corresponds to one pixel.
@@ -463,7 +456,7 @@ public:
}
/** Returns writable_addr pixel address at (x, y). Result is addressable as unsigned
- 16-bit words. Will trigger an assert() if color type is not kRGB_565_SkColorType
+ 16-bit words. Will trigger an assert() if SkColorType is not kRGB_565_SkColorType
or kARGB_4444_SkColorType, and is built with SK_DEBUG defined.
One word corresponds to one pixel.
@@ -477,7 +470,7 @@ public:
}
/** Returns writable pixel address at (x, y). Result is addressable as unsigned
- 32-bit words. Will trigger an assert() if color type is not
+ 32-bit words. Will trigger an assert() if SkColorType is not
kRGBA_8888_SkColorType or kBGRA_8888_SkColorType, and is built with SK_DEBUG
defined.
@@ -492,7 +485,7 @@ public:
}
/** Returns writable pixel address at (x, y). Result is addressable as unsigned
- 64-bit words. Will trigger an assert() if color type is not
+ 64-bit words. Will trigger an assert() if SkColorType is not
kRGBA_F16_SkColorType and is built with SK_DEBUG defined.
One word corresponds to one pixel.
@@ -506,7 +499,7 @@ public:
}
/** Returns writable pixel address at (x, y). Result is addressable as unsigned
- 16-bit words. Will trigger an assert() if color type is not
+ 16-bit words. Will trigger an assert() if SkColorType is not
kRGBA_F16_SkColorType and is built with SK_DEBUG defined.
Each word represents one color component encoded as a half float.
@@ -521,30 +514,30 @@ public:
}
/** Copies a SkRect of pixels to dstPixels. Copy starts at (srcX, srcY), and does not
- exceed (this->width(), this->height()).
+ exceed SkPixmap (width(), height()).
- dstInfo specifies width, height, color type, alpha type, and
+ dstInfo specifies width, height, SkColorType, SkAlphaType, and
SkColorSpace 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 SkPixmap 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 SkPixmap colorType() is kGray_8_SkColorType, dstInfo.colorSpace() must match.
+ If SkPixmap alphaType() is kOpaque_SkAlphaType, dstInfo.alphaType() must
+ match. If SkPixmap 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:
- abs(srcX) >= this->width(), or if abs(srcY) >= this->height().
+ abs(srcX) >= Pixmap width(), or if abs(srcY) >= Pixmap height().
If behavior is SkTransferFunctionBehavior::kRespect: converts source
pixels to a linear space before converting to dstInfo.
If behavior is SkTransferFunctionBehavior::kIgnore: source
pixels are treated as if they are linear, regardless of how they are encoded.
- @param dstInfo destination width, height, color type, alpha type, SkColorSpace
+ @param dstInfo destination width, height, SkColorType, SkAlphaType, SkColorSpace
@param dstPixels destination pixel storage
@param dstRowBytes destination row length
@param srcX column index whose absolute value is less than width()
@@ -557,23 +550,23 @@ public:
int srcX, int srcY, SkTransferFunctionBehavior behavior) const;
/** Copies a SkRect of pixels to dstPixels. Copy starts at (0, 0), and does not
- exceed (this->width(), this->height()).
+ exceed SkPixmap (width(), height()).
- dstInfo specifies width, height, color type, alpha type, and
+ dstInfo specifies width, height, SkColorType, SkAlphaType, and
SkColorSpace 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 SkPixmap 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 SkPixmap colorType() is kGray_8_SkColorType, dstInfo.colorSpace() must match.
+ If SkPixmap alphaType() is kOpaque_SkAlphaType, dstInfo.alphaType() must
+ match. If SkPixmap 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 SkPixmap width() or height() is zero or negative.
- @param dstInfo destination width, height, color type, alpha type, SkColorSpace
+ @param dstInfo destination width, height, SkColorType, SkAlphaType, SkColorSpace
@param dstPixels destination pixel storage
@param dstRowBytes destination row length
@return true if pixels are copied to dstPixels
@@ -583,25 +576,25 @@ public:
}
/** Copies a SkRect of pixels to dstPixels. Copy starts at (srcX, srcY), and does not
- exceed (this->width(), this->height()).
+ exceed SkPixmap (width(), height()).
- dstInfo specifies width, height, color type, alpha type, and
+ dstInfo specifies width, height, SkColorType, SkAlphaType, and
SkColorSpace 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 SkPixmap 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 SkPixmap colorType() is kGray_8_SkColorType, dstInfo.colorSpace() must match.
+ If SkPixmap alphaType() is kOpaque_SkAlphaType, dstInfo.alphaType() must
+ match. If SkPixmap 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:
- abs(srcX) >= this->width(), or if abs(srcY) >= this->height().
+ false if SkPixmap width() or height() is zero or negative. Returns false if:
+ abs(srcX) >= Pixmap width(), or if abs(srcY) >= Pixmap height().
- @param dstInfo destination width, height, color type, alpha type, SkColorSpace
+ @param dstInfo destination width, height, SkColorType, SkAlphaType, SkColorSpace
@param dstPixels destination pixel storage
@param dstRowBytes destination row length
@param srcX column index whose absolute value is less than width()
@@ -615,21 +608,21 @@ public:
}
/** Copies a SkRect of pixels to dst. Copy starts at (srcX, srcY), and does not
- exceed (this->width(), this->height()). dst specifies width, height, color type,
- alpha type, and SkColorSpace of destination. Returns true if pixels are copied.
+ exceed SkPixmap (width(), height()). dst specifies width, height, SkColorType,
+ SkAlphaType, and SkColorSpace 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 SkPixmap 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 SkPixmap colorType() is kGray_8_SkColorType, dst.info().colorSpace must match.
+ If SkPixmap alphaType() is kOpaque_SkAlphaType, dst.info().alphaType must
+ match. If SkPixmap 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:
- abs(srcX) >= this->width(), or if abs(srcY) >= this->height().
+ false SkPixmap width() or height() is zero or negative. Returns false if:
+ abs(srcX) >= Pixmap width(), or if abs(srcY) >= Pixmap height().
@param dst SkImageInfo and pixel address to write to
@param srcX column index whose absolute value is less than width()
@@ -640,19 +633,19 @@ public:
return this->readPixels(dst.info(), dst.writable_addr(), dst.rowBytes(), srcX, srcY);
}
- /** Copies pixels inside bounds() to dst. dst specifies width, height, color type,
- alpha type, and SkColorSpace of destination. Returns true if pixels are copied.
+ /** Copies pixels inside bounds() to dst. dst specifies width, height, SkColorType,
+ SkAlphaType, and SkColorSpace 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
- kGray_8_SkColorType, or kAlpha_8_SkColorType; dst color type must match.
- If this->colorType() is kGray_8_SkColorType, dst SkColorSpace must match.
- If this->alphaType() is kOpaque_SkAlphaType, dst alpha type must
- match. If this->colorSpace() is nullptr, dst SkColorSpace must match. Returns
+ Pixels are copied only if pixel conversion is possible. If SkPixmap colorType() is
+ kGray_8_SkColorType, or kAlpha_8_SkColorType; dst SkColorType must match.
+ If SkPixmap colorType() is kGray_8_SkColorType, dst SkColorSpace must match.
+ If SkPixmap alphaType() is kOpaque_SkAlphaType, dst SkAlphaType must
+ match. If SkPixmap colorSpace() is nullptr, dst SkColorSpace 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 SkPixmap width() or height() is zero or negative.
@param dst SkImageInfo and pixel address to write to
@return true if pixels are copied to dst
@@ -661,19 +654,19 @@ public:
return this->readPixels(dst.info(), dst.writable_addr(), dst.rowBytes(), 0, 0);
}
- /** Copies this to dst, scaling pixels to fit dst.width() and dst.height(), and
+ /** Copies SkBitmap 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
- kGray_8_SkColorType, or kAlpha_8_SkColorType; dst color type must match.
- If this->colorType() is kGray_8_SkColorType, dst SkColorSpace must match.
- If this->alphaType() is kOpaque_SkAlphaType, dst alpha type must
- match. If this->colorSpace() is nullptr, dst SkColorSpace must match. Returns
+ Pixels are copied only if pixel conversion is possible. If SkPixmap colorType() is
+ kGray_8_SkColorType, or kAlpha_8_SkColorType; dst SkColorType must match.
+ If SkPixmap colorType() is kGray_8_SkColorType, dst SkColorSpace must match.
+ If SkPixmap alphaType() is kOpaque_SkAlphaType, dst SkAlphaType must
+ match. If SkPixmap colorSpace() is nullptr, dst SkColorSpace 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 SkBitmap 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
@@ -685,7 +678,7 @@ public:
@param dst SkImageInfo and pixel address to write to
@param filterQuality one of: kNone_SkFilterQuality, kLow_SkFilterQuality,
kMedium_SkFilterQuality, kHigh_SkFilterQuality
- @return true if pixels are copied to dst
+ @return true if pixels are scaled to fit dst
*/
bool scalePixels(const SkPixmap& dst, SkFilterQuality filterQuality) const;
diff --git a/include/core/SkPoint.h b/include/core/SkPoint.h
index 2d3a938693..f05a08c99d 100644
--- a/include/core/SkPoint.h
+++ b/include/core/SkPoint.h
@@ -13,12 +13,12 @@
#include "../private/SkSafe32.h"
/** \struct SkIPoint16
- SkIPoint holds two 16 bit integer coordinates
+ SkIPoint16 holds two 16 bit integer coordinates.
*/
struct SkIPoint16 {
- int16_t fX; //!< x-axis value used by SkIPoint16.
+ int16_t fX; //!< x-axis value used by SkIPoint16
- int16_t fY; //!< y-axis value used by SkIPoint16.
+ int16_t fY; //!< y-axis value used by SkIPoint16
/** Sets fX to x, fY to y. If SK_DEBUG is defined, asserts
if x or y does not fit in 16 bits.
@@ -58,7 +58,7 @@ struct SkIPoint;
typedef SkIPoint SkIVector;
/** \struct SkIPoint
- SkIPoint holds two 32 bit integer coordinates
+ SkIPoint holds two 32 bit integer coordinates.
*/
struct SkIPoint {
int32_t fX; //!< x-axis value used by SkIPoint.
@@ -189,6 +189,7 @@ struct SkPoint;
typedef SkPoint SkVector;
/** \struct SkPoint
+ SkPoint holds two 32 bit floating point coordinates.
*/
struct SK_API SkPoint {
@@ -553,9 +554,9 @@ struct SK_API SkPoint {
/** Returns the cross product of vector a and vector b.
- a and b form three-dimensional vectors with z equal to zero. The cross product
- is a three-dimensional vector with x and y equal to zero. The cross product z
- term equals the returned value.
+ a and b form three-dimensional vectors with z-axis value equal to zero. The
+ cross product is a three-dimensional vector with x-axis and y-axis values equal
+ to zero. The cross product z-axis component is returned.
@param a left side of cross product
@param b right side of cross product
@@ -567,9 +568,9 @@ struct SK_API SkPoint {
/** Returns the cross product of vector and vec.
- Vector and vec form three-dimensional vectors with z equal to zero. The
- cross product is a three-dimensional vector with x and y equal to zero.
- The cross product z term equals the returned value.
+ Vector and vec form three-dimensional vectors with z-axis value equal to zero.
+ The cross product is a three-dimensional vector with x-axis and y-axis values
+ equal to zero. The cross product z-axis component is returned.
@param vec right side of cross product
@return area spanned by vectors signed by angle direction
diff --git a/include/core/SkRect.h b/include/core/SkRect.h
index 7f1eff0690..f9a5bff4ff 100644
--- a/include/core/SkRect.h
+++ b/include/core/SkRect.h
@@ -56,10 +56,7 @@ struct SK_API SkIRect {
}
#ifdef SK_SUPPORT_LEGACY_RECTMAKELARGEST
- /** 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)
+ /** Deprecated.
*/
static SkIRect SK_WARN_UNUSED_RESULT MakeLargest() {
return { SK_MinS32, SK_MinS32, SK_MaxS32, SK_MaxS32 };
@@ -69,8 +66,8 @@ struct SK_API SkIRect {
/** Returns constructed SkIRect set to (0, 0, w, h). Does not validate input; w or h
may be negative.
- @param w width of constructed SkRect
- @param h height of constructed SkRect
+ @param w width of constructed SkIRect
+ @param h height of constructed SkIRect
@return bounds (0, 0, w, h)
*/
static constexpr SkIRect SK_WARN_UNUSED_RESULT MakeWH(int32_t w, int32_t h) {
@@ -80,14 +77,14 @@ struct SK_API SkIRect {
/** Returns constructed SkIRect set to (0, 0, size.width(), size.height()).
Does not validate input; size.width() or size.height() may be negative.
- @param size values for SkRect width and height
+ @param size values for SkIRect width and height
@return bounds (0, 0, size.width(), size.height())
*/
static constexpr SkIRect SK_WARN_UNUSED_RESULT MakeSize(const SkISize& size) {
return SkIRect{0, 0, size.fWidth, size.fHeight};
}
- /** Returns constructed SkIRect set to (l, t, r, b). Does not sort input; SkRect may
+ /** Returns constructed SkIRect set to (l, t, r, b). Does not sort input; SkIRect may
result in fLeft greater than fRight, or fTop greater than fBottom.
@param l integer stored in fLeft
@@ -178,8 +175,8 @@ struct SK_API SkIRect {
*/
SkISize size() const { return SkISize::Make(this->width(), this->height()); }
- /** Returns average of left edge and right edge. Result does not change if SkRect
- is sorted. Result may be incorrect if SkRect is far from the origin.
+ /** Returns average of left edge and right edge. Result does not change if SkIRect
+ is sorted. Result may be incorrect if SkIRect is far from the origin.
Result is rounded down.
@@ -187,8 +184,8 @@ struct SK_API SkIRect {
*/
int32_t centerX() const { return SkToS32(((int64_t)fRight + fLeft) >> 1); }
- /** Returns average of top edge and bottom edge. Result does not change if SkRect
- is sorted. Result may be incorrect if SkRect is far from the origin.
+ /** Returns average of top edge and bottom edge. Result does not change if SkIRect
+ is sorted. Result may be incorrect if SkIRect is far from the origin.
Result is rounded down.
@@ -196,18 +193,34 @@ struct SK_API SkIRect {
*/
int32_t centerY() const { return SkToS32(((int64_t)fBottom + fTop) >> 1); }
+ /** Returns span on the x-axis. This does not check if SkIRect is sorted, so the
+ result may be negative. This is safer than calling width() since width() might
+ overflow in its calculation.
+
+ @return fRight minus fLeft cast to int64_t
+ */
int64_t width64() const { return (int64_t)fRight - (int64_t)fLeft; }
+
+ /** Returns span on the y-axis. This does not check if SkIRect is sorted, so the
+ result may be negative. This is safer than calling height() since height() might
+ overflow in its calculation.
+
+ @return fBottom minus fTop cast to int64_t
+ */
int64_t height64() const { return (int64_t)fBottom - (int64_t)fTop; }
- /** Returns true if the rectangle's dimensions are non-positive.
- * Unlike isEmpty(), this does not worry about the size of the width or height, which could
- * exceed int32_t but still be logically non-empty.
- */
+ /** Returns true if fLeft is equal to or greater than fRight, or if fTop is equal
+ to or greater than fBottom. Call sort() to reverse rectangles with negative
+ width64() or height64().
+
+ @return true if width64() or height64() are zero or negative
+ */
bool isEmpty64() const { return fRight <= fLeft || fBottom <= fTop; }
- /** Returns true if the rectangle's dimensions are non-positive or if either its width or hieght
- * exceeds int32_t.
- */
+ /** Returns true if width() or height() .
+
+ @return true if width() or height() are zero or negative
+ */
bool isEmpty() const {
int64_t w = this->width64();
int64_t h = this->height64();
@@ -311,7 +324,7 @@ struct SK_API SkIRect {
@param dx offset added to fLeft and fRight
@param dy offset added to fTop and fBottom
- @return SkRect offset in x or y, with original width and height
+ @return SkIRect offset in x or y, with original width and height
*/
SkIRect makeOffset(int32_t dx, int32_t dy) const {
return {
@@ -329,7 +342,7 @@ struct SK_API SkIRect {
@param dx offset added to fLeft and subtracted from fRight
@param dy offset added to fTop and subtracted from fBottom
- @return SkRect inset symmetrically left and right, top and bottom
+ @return SkIRect inset symmetrically left and right, top and bottom
*/
SkIRect makeInset(int32_t dx, int32_t dy) const {
return {
@@ -347,7 +360,7 @@ struct SK_API SkIRect {
@param dx offset subtracted to fLeft and added from fRight
@param dy offset subtracted to fTop and added from fBottom
- @return SkRect outset symmetrically left and right, top and bottom
+ @return SkIRect outset symmetrically left and right, top and bottom
*/
SkIRect makeOutset(int32_t dx, int32_t dy) const {
return {
@@ -419,10 +432,10 @@ struct SK_API SkIRect {
/** Outsets SkIRect by (dx, dy).
- If dx is positive, makes SkRect wider.
- If dx is negative, makes SkRect narrower.
- If dy is positive, makes SkRect taller.
- If dy is negative, makes SkRect shorter.
+ If dx is positive, makes SkIRect wider.
+ If dx is negative, makes SkIRect narrower.
+ If dy is positive, makes SkIRect taller.
+ If dy is negative, makes SkIRect shorter.
@param dx subtracted to fLeft and added from fRight
@param dy subtracted to fTop and added from fBottom
@@ -435,10 +448,10 @@ struct SK_API SkIRect {
Is implemented with short circuit logic so that true can be returned after
a single compare.
- @param l x minimum of constructed SkRect
- @param t y minimum of constructed SkRect
- @param r x maximum of constructed SkRect
- @param b y maximum of constructed SkRect
+ @param l x minimum of constructed SkIRect
+ @param t y minimum of constructed SkIRect
+ @param r x maximum of constructed SkIRect
+ @param b y maximum of constructed SkIRect
@return true if construction and SkIRect have no area in common
*/
bool quickReject(int l, int t, int r, int b) const {
@@ -446,29 +459,29 @@ struct SK_API SkIRect {
}
/** Returns true if: fLeft <= x < fRight && fTop <= y < fBottom.
- Returns false if SkRect is empty.
+ Returns false if SkIRect is empty.
Considers input to describe constructed SkIRect: (x, y, x + 1, y + 1) and
returns true if constructed area is completely enclosed by SkIRect area.
- @param x test SkPoint x-coordinate
- @param y test SkPoint y-coordinate
+ @param x test SkIPoint x-coordinate
+ @param y test SkIPoint y-coordinate
@return true if (x, y) is inside SkIRect
*/
bool contains(int32_t x, int32_t y) const {
return x >= fLeft && x < fRight && y >= fTop && y < fBottom;
}
- /** Constructs SkRect to intersect from (left, top, right, bottom). Does not sort
+ /** Constructs SkIRect to intersect from (left, top, right, bottom). Does not sort
construction.
- Returns true if SkRect contains construction.
- Returns false if SkRect is empty or construction is empty.
+ Returns true if SkIRect contains construction.
+ Returns false if SkIRect is empty or construction is empty.
- @param left x minimum of constructed SkRect
- @param top y minimum of constructed SkRect
- @param right x maximum of constructed SkRect
- @param bottom y maximum of constructed SkRect
+ @param left x minimum of constructed SkIRect
+ @param top y minimum of constructed SkIRect
+ @param right x maximum of constructed SkIRect
+ @param bottom y maximum of constructed SkIRect
@return true if all sides of SkIRect are outside construction
*/
bool contains(int32_t left, int32_t top, int32_t right, int32_t bottom) const {
@@ -477,10 +490,10 @@ struct SK_API SkIRect {
fRight >= right && fBottom >= bottom;
}
- /** Returns true if SkRect contains r.
- Returns false if SkRect is empty or r is empty.
+ /** Returns true if SkIRect contains r.
+ Returns false if SkIRect is empty or r is empty.
- SkRect contains r when SkRect area completely includes r area.
+ SkIRect contains r when SkIRect area completely includes r area.
@param r SkIRect contained
@return true if all sides of SkIRect are outside r
@@ -491,10 +504,10 @@ struct SK_API SkIRect {
fRight >= r.fRight && fBottom >= r.fBottom;
}
- /** Returns true if SkRect contains r.
- Returns false if SkRect is empty or r is empty.
+ /** Returns true if SkIRect contains r.
+ Returns false if SkIRect is empty or r is empty.
- SkRect contains r when SkRect area completely includes r area.
+ SkIRect contains r when SkIRect area completely includes r area.
@param r SkRect contained
@return true if all sides of SkIRect are outside r
@@ -504,15 +517,15 @@ struct SK_API SkIRect {
/** Constructs SkIRect from (left, top, right, bottom). Does not sort
construction.
- Returns true if SkRect contains construction.
+ Returns true if SkIRect contains construction.
Asserts if SkIRect is empty or construction is empty, and if SK_DEBUG is defined.
- Return is undefined if SkRect is empty or construction is empty.
+ Return is undefined if SkIRect is empty or construction is empty.
- @param left x minimum of constructed SkRect
- @param top y minimum of constructed SkRect
- @param right x maximum of constructed SkRect
- @param bottom y maximum of constructed SkRect
+ @param left x minimum of constructed SkIRect
+ @param top y minimum of constructed SkIRect
+ @param right x maximum of constructed SkIRect
+ @param bottom y maximum of constructed SkIRect
@return true if all sides of SkIRect are outside construction
*/
bool containsNoEmptyCheck(int32_t left, int32_t top,
@@ -524,12 +537,12 @@ struct SK_API SkIRect {
fRight >= right && fBottom >= bottom;
}
- /** Returns true if SkRect contains construction.
+ /** Returns true if SkIRect contains construction.
Asserts if SkIRect is empty or construction is empty, and if SK_DEBUG is defined.
- Return is undefined if SkRect is empty or construction is empty.
+ Return is undefined if SkIRect is empty or construction is empty.
- @param r SkRect contained
+ @param r SkIRect contained
@return true if all sides of SkIRect are outside r
*/
bool containsNoEmptyCheck(const SkIRect& r) const {
@@ -542,7 +555,7 @@ struct SK_API SkIRect {
Returns false if either r or SkIRect is empty, leaving SkIRect unchanged.
@param r limit of result
- @return true if r and SkRect have area in common
+ @return true if r and SkIRect have area in common
*/
bool intersect(const SkIRect& r) {
return this->intersect(*this, r);
@@ -573,14 +586,14 @@ struct SK_API SkIRect {
}
/** Returns true if a intersects b, and sets SkIRect to intersection.
- Returns false if a does not intersect b, and leaves SkIRect unchanged.
+ Returns false if a does not intersect b, and leaves SkIRect unchanged.
- Returns false if either a or b is empty, leaving SkIRect unchanged.
+ Returns false if either a or b is empty, leaving SkIRect unchanged.
- @param a SkIRect to intersect
- @param b SkIRect to intersect
- @return true if a and b have area in common
- */
+ @param a SkIRect to intersect
+ @param b SkIRect to intersect
+ @return true if a and b have area in common
+ */
bool SK_WARN_UNUSED_RESULT intersect(const SkIRect& a, const SkIRect& b) {
if (a.isEmpty64() || b.isEmpty64()) {
return false;
@@ -630,26 +643,26 @@ struct SK_API SkIRect {
return dummy.intersectNoEmptyCheck(a, b);
}
- /** Constructs SkRect to intersect from (left, top, right, bottom). Does not sort
+ /** Constructs SkIRect to intersect from (left, top, right, bottom). Does not sort
construction.
- Sets SkRect to the union of itself and the construction.
+ Sets SkIRect to the union of itself and the construction.
- Has no effect if construction is empty. Otherwise, if SkRect is empty, sets
- SkRect to construction.
+ Has no effect if construction is empty. Otherwise, if SkIRect is empty, sets
+ SkIRect to construction.
- @param left x minimum of constructed SkRect
- @param top y minimum of constructed SkRect
- @param right x maximum of constructed SkRect
- @param bottom y maximum of constructed SkRect
+ @param left x minimum of constructed SkIRect
+ @param top y minimum of constructed SkIRect
+ @param right x maximum of constructed SkIRect
+ @param bottom y maximum of constructed SkIRect
*/
void join(int32_t left, int32_t top, int32_t right, int32_t bottom);
- /** Sets SkRect to the union of itself and r.
+ /** Sets SkIRect to the union of itself and r.
- Has no effect if r is empty. Otherwise, if SkRect is empty, sets SkRect to r.
+ Has no effect if r is empty. Otherwise, if SkIRect is empty, sets SkIRect to r.
- @param r expansion SkRect
+ @param r expansion SkIRect
*/
void join(const SkIRect& r) {
this->join(r.fLeft, r.fTop, r.fRight, r.fBottom);
@@ -668,7 +681,7 @@ struct SK_API SkIRect {
}
}
- /** Returns SkRect with fLeft and fRight swapped if fLeft is greater than fRight; and
+ /** Returns SkIRect with fLeft and fRight swapped if fLeft is greater than fRight; and
with fTop and fBottom swapped if fTop is greater than fBottom. Result may be empty;
and width() and height() will be zero or positive.
@@ -730,10 +743,7 @@ struct SK_API SkRect {
}
#ifdef SK_SUPPORT_LEGACY_RECTMAKELARGEST
- /** 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)
+ /** Deprecated.
*/
static SkRect SK_WARN_UNUSED_RESULT MakeLargest() {
return { SK_ScalarMin, SK_ScalarMin, SK_ScalarMax, SK_ScalarMax };
@@ -808,9 +818,6 @@ struct SK_API SkRect {
}
/** Deprecated.
-
- @param irect integer rect
- @return irect as SkRect
*/
SK_ATTR_DEPRECATED("use Make()")
static SkRect SK_WARN_UNUSED_RESULT MakeFromIRect(const SkIRect& irect) {
@@ -849,13 +856,11 @@ struct SK_API SkRect {
}
/** Returns true if fLeft is equal to or greater than fRight, or if fTop is equal
- * to or greater than fBottom. Call sort() to reverse rectangles with negative
- * width() or height().
- *
- * This function also returns true if any of the values are NaN.
- *
- * @return true if width() or height() are zero or negative
- */
+ to or greater than fBottom. Call sort() to reverse rectangles with negative
+ width() or height().
+
+ @return true if width() or height() are zero or negative
+ */
bool isEmpty() const {
// We write it as the NOT of a non-empty rect, so we will return true if any values
// are NaN.
@@ -1117,7 +1122,7 @@ struct SK_API SkRect {
*/
bool setBoundsCheck(const SkPoint pts[], int count);
- /** Sets bounds to the smallest SkRect enclosing points p0 and p1. The result is
+ /** Sets bounds to the smallest SkRect enclosing SkPoint p0 and p1. The result is
sorted and may be empty. Does not check to see if values are finite.
@param p0 corner to include
@@ -1477,7 +1482,7 @@ public:
}
/** Sets SkIRect by discarding the fractional portion of fLeft and fTop; and
- rounding up fRight and fbottom, using (SkScalarFloorToInt(fLeft), SkScalarFloorToInt(fTop),
+ rounding up fRight and fBottom, using (SkScalarFloorToInt(fLeft), SkScalarFloorToInt(fTop),
SkScalarCeilToInt(fRight), SkScalarCeilToInt(fBottom)).
@param dst storage for SkIRect
@@ -1489,7 +1494,7 @@ public:
}
/** Sets SkRect by discarding the fractional portion of fLeft and fTop; and
- rounding up fRight and fbottom, using (SkScalarFloorToInt(fLeft), SkScalarFloorToInt(fTop),
+ rounding up fRight and fBottom, using (SkScalarFloorToInt(fLeft), SkScalarFloorToInt(fTop),
SkScalarCeilToInt(fRight), SkScalarCeilToInt(fBottom)).
@param dst storage for SkRect
@@ -1502,7 +1507,7 @@ public:
}
/** Sets SkRect by rounding up fLeft and fTop; and
- discarding the fractional portion of fRight and fbottom, using
+ discarding the fractional portion of fRight and fBottom, using
(SkScalarCeilToInt(fLeft), SkScalarCeilToInt(fTop),
SkScalarFloorToInt(fRight), SkScalarFloorToInt(fBottom)).
@@ -1527,7 +1532,7 @@ public:
}
/** Sets SkIRect by discarding the fractional portion of fLeft and fTop; and
- rounding up fRight and fbottom, using (SkScalarFloorToInt(fLeft), SkScalarFloorToInt(fTop),
+ rounding up fRight and fBottom, using (SkScalarFloorToInt(fLeft), SkScalarFloorToInt(fTop),
SkScalarCeilToInt(fRight), SkScalarCeilToInt(fBottom)).
@return rounded SkIRect
diff --git a/include/core/SkSurface.h b/include/core/SkSurface.h
index a4a62d0621..5a3887ef02 100644
--- a/include/core/SkSurface.h
+++ b/include/core/SkSurface.h
@@ -23,94 +23,193 @@ class GrBackendSemaphore;
class GrContext;
class GrRenderTarget;
-/**
- * SkSurface is responsible for managing the pixels that a canvas draws into. The pixels can be
- * allocated either in CPU memory (a Raster surface) or on the GPU (a RenderTarget surface).
- *
- * SkSurface takes care of allocating a SkCanvas that will draw into the surface. Call
- * surface->getCanvas() to use that canvas (but don't delete it, it is owned by the surface).
- *
- * SkSurface always has non-zero dimensions. If there is a request for a new surface, and either
- * of the requested dimensions are zero, then NULL will be returned.
- */
+/** \class SkSurface
+ SkSurface is responsible for managing the pixels that a canvas draws into. The pixels can be
+ allocated either in CPU memory (a raster surface) or on the GPU (a GrRenderTarget surface).
+ SkSurface takes care of allocating a SkCanvas that will draw into the surface. Call
+ surface->getCanvas() to use that canvas (but don't delete it, it is owned by the surface).
+ SkSurface always has non-zero dimensions. If there is a request for a new surface, and either
+ of the requested dimensions are zero, then nullptr will be returned.
+*/
class SK_API SkSurface : public SkRefCnt {
public:
- /**
- * Create a new surface, using the specified pixels/rowbytes as its
- * backend.
- *
- * If the requested surface cannot be created, or the request is not a
- * supported configuration, NULL will be returned.
- *
- * Callers are responsible for initialiazing the surface pixels.
- */
+
+ /** Allocates raster SkSurface. SkCanvas returned by SkSurface draws directly into pixels.
+
+ SkSurface is returned if all parameters are valid.
+ Valid parameters include:
+ info dimensions are greater than zero;
+ info contains SkColorType and SkAlphaType supported by raster surface;
+ pixels is not nullptr;
+ rowBytes is large enough to contain info width pixels of SkColorType.
+
+ Pixel buffer size should be info height times computed rowBytes.
+ Pixels are not initialized.
+ To access pixels after drawing, call flush() or peekPixels().
+
+ @param imageInfo width, height, SkColorType, SkAlphaType, SkColorSpace,
+ of raster surface; width and height must be greater than zero
+ @param pixels pointer to destination pixels buffer
+ @param rowBytes interval from one SkSurface row to the next
+ @param surfaceProps LCD striping orientation and setting for device independent fonts;
+ may be nullptr
+ @return SkSurface if all parameters are valid; otherwise, nullptr
+ */
static sk_sp<SkSurface> MakeRasterDirect(const SkImageInfo& imageInfo, void* pixels,
size_t rowBytes,
const SkSurfaceProps* surfaceProps = nullptr);
- /**
- * The same as NewRasterDirect, but also accepts a call-back routine, which is invoked
- * when the surface is deleted, and is passed the pixel memory and the specified context.
- */
+ /** Allocates raster SkSurface. SkCanvas returned by SkSurface draws directly into pixels.
+ releaseProc is called with pixels and context when SkSurface is deleted.
+
+ SkSurface is returned if all parameters are valid.
+ Valid parameters include:
+ info dimensions are greater than zero;
+ info contains SkColorType and SkAlphaType supported by raster surface;
+ pixels is not nullptr;
+ rowBytes is large enough to contain info width pixels of SkColorType.
+
+ Pixel buffer size should be info height times computed rowBytes.
+ Pixels are not initialized.
+ To access pixels after drawing, call flush() or peekPixels().
+
+ @param imageInfo width, height, SkColorType, SkAlphaType, SkColorSpace,
+ of raster surface; width and height must be greater than zero
+ @param pixels pointer to destination pixels buffer
+ @param rowBytes interval from one SkSurface row to the next
+ @param releaseProc called when SkSurface is deleted; may be nullptr
+ @param context passed to releaseProc; may be nullptr
+ @param surfaceProps LCD striping orientation and setting for device independent fonts;
+ may be nullptr
+ @return SkSurface if all parameters are valid; otherwise, nullptr
+ */
static sk_sp<SkSurface> MakeRasterDirectReleaseProc(const SkImageInfo& imageInfo, void* pixels,
size_t rowBytes,
void (*releaseProc)(void* pixels, void* context),
void* context, const SkSurfaceProps* surfaceProps = nullptr);
- /**
- * Return a new surface, with the memory for the pixels automatically allocated and
- * zero-initialized, but respecting the specified rowBytes. If rowBytes==0, then a default
- * value will be chosen. If a non-zero rowBytes is specified, then any images snapped off of
- * this surface (via makeImageSnapshot()) are guaranteed to have the same rowBytes.
- *
- * If the requested surface cannot be created, or the request is not a
- * supported configuration, NULL will be returned.
- */
+ /** Allocates raster SkSurface. SkCanvas returned by SkSurface draws directly into pixels.
+ Allocates and zeroes pixel memory. Pixel memory size is imageInfo.height() times
+ rowBytes, or times imageInfo.minRowBytes() if rowBytes is zero.
+ Pixel memory is deleted when SkSurface is deleted.
+
+ SkSurface is returned if all parameters are valid.
+ Valid parameters include:
+ info dimensions are greater than zero;
+ info contains SkColorType and SkAlphaType supported by raster surface;
+ rowBytes is large enough to contain info width pixels of SkColorType, or is zero.
+
+ If rowBytes is not zero, subsequent images returned by makeImageSnapshot()
+ have the same rowBytes.
+
+ @param imageInfo width, height, SkColorType, SkAlphaType, SkColorSpace,
+ of raster surface; width and height must be greater than zero
+ @param rowBytes interval from one SkSurface row to the next; may be zero
+ @param surfaceProps LCD striping orientation and setting for device independent fonts;
+ may be nullptr
+ @return SkSurface if all parameters are valid; otherwise, nullptr
+ */
static sk_sp<SkSurface> MakeRaster(const SkImageInfo& imageInfo, size_t rowBytes,
const SkSurfaceProps* surfaceProps);
- /**
- * Allocate a new surface, automatically computing the rowBytes.
- */
+ /** Allocates raster SkSurface. SkCanvas returned by SkSurface draws directly into pixels.
+ Allocates and zeroes pixel memory. Pixel memory size is imageInfo.height() times
+ imageInfo.minRowBytes().
+ Pixel memory is deleted when SkSurface is deleted.
+
+ SkSurface is returned if all parameters are valid.
+ Valid parameters include:
+ info dimensions are greater than zero;
+ info contains SkColorType and SkAlphaType supported by raster surface.
+
+ @param imageInfo width, height, SkColorType, SkAlphaType, SkColorSpace,
+ of raster surface; width and height must be greater than zero
+ @param props LCD striping orientation and setting for device independent fonts;
+ may be nullptr
+ @return SkSurface if all parameters are valid; otherwise, nullptr
+ */
static sk_sp<SkSurface> MakeRaster(const SkImageInfo& imageInfo,
const SkSurfaceProps* props = nullptr) {
return MakeRaster(imageInfo, 0, props);
}
- /**
- * Helper version of NewRaster. It creates a SkImageInfo with the
- * specified width and height, and populates the rest of info to match
- * pixels in SkPMColor format.
- */
+ /** Allocates raster SkSurface. SkCanvas returned by SkSurface draws directly into pixels.
+ Allocates and zeroes pixel memory. Pixel memory size is height times width times
+ four. Pixel memory is deleted when SkSurface is deleted.
+
+ Internally, sets SkImageInfo to width, height, native SkColorType, and
+ kPremul_SkAlphaType.
+
+ SkSurface is returned if width and height are greater than zero.
+
+ Use to create SkSurface that matches SkPMColor, the native pixel arrangement on
+ the platform. SkSurface drawn to output device skips converting its pixel format.
+
+ @param width pixel column count; must be greater than zero
+ @param height pixel row count; must be greater than zero
+ @param surfaceProps LCD striping orientation and setting for device independent
+ fonts; may be nullptr
+ @return SkSurface if all parameters are valid; otherwise, nullptr
+ */
static sk_sp<SkSurface> MakeRasterN32Premul(int width, int height,
const SkSurfaceProps* surfaceProps = nullptr) {
return MakeRaster(SkImageInfo::MakeN32Premul(width, height), surfaceProps);
}
- /**
- * Used to wrap a pre-existing backend 3D API texture as a SkSurface. Skia will not assume
- * ownership of the texture and the client must ensure the texture is valid for the lifetime
- * of the SkSurface. If sampleCnt > 1, then we will create an intermediate mssa surface which
- * we will use for rendering. We then resolve into the passed in texture.
- */
+ /** Wraps a GPU-backed texture into SkSurface. Caller must ensure the texture is
+ valid for the lifetime of returned SkSurface. If sampleCnt greater than zero,
+ creates an intermediate MSAA SkSurface which is used for drawing backendTexture.
+
+ SkSurface is returned if all parameters are valid. backendTexture is valid if
+ its pixel configuration agrees with colorSpace and context; for instance, if
+ backendTexture has an sRGB configuration, then context must support sRGB,
+ and colorSpace must be present. Further, backendTexture width and height must
+ not exceed context capabilities, and the context must be able to support
+ back-end textures.
+
+ If SK_SUPPORT_GPU is defined as zero, has no effect and returns nullptr.
+
+ @param context GPU context
+ @param backendTexture texture residing on GPU
+ @param origin one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin
+ @param sampleCnt samples per pixel, or 0 to disable full scene anti-aliasing
+ @param colorSpace range of colors
+ @param surfaceProps LCD striping orientation and setting for device independent
+ fonts; may be nullptr
+ @return SkSurface if all parameters are valid; otherwise, nullptr
+ */
static sk_sp<SkSurface> MakeFromBackendTexture(GrContext* context,
const GrBackendTexture& backendTexture,
GrSurfaceOrigin origin, int sampleCnt,
sk_sp<SkColorSpace> colorSpace,
const SkSurfaceProps* surfaceProps);
- /**
- * Used to wrap a pre-existing backend 3D API texture as a SkSurface. Skia will not assume
- * ownership of the texture and the client must ensure the texture is valid for the lifetime
- * of the SkSurface. If sampleCnt > 1, then we will create an intermediate mssa surface which
- * we will use for rendering. We then resolve into the passed in texture.
- *
- * The GrBackendTexture must have a valid backend format supplied (GrGLTextureInfo::fFormat,
- * GrVkImageInfo::fFormat, etc.) in it. The passed in SkColorType informs skia how it should
- * interpret the backend format supplied by the GrBackendTexture. If the format in the
- * GrBackendTexture is not compatible with the sampleCnt, SkColorType, and SkColorSpace we
- * will return nullptr.
- */
+ /** Wraps a GPU-backed texture into SkSurface. Caller must ensure the texture is
+ valid for the lifetime of returned SkSurface. If sampleCnt greater than zero,
+ creates an intermediate MSAA SkSurface which is used for drawing backendTexture.
+
+ SkSurface is returned if all parameters are valid. backendTexture is valid if
+ its pixel configuration agrees with colorSpace and context; for instance, if
+ backendTexture has an sRGB configuration, then context must support sRGB,
+ and colorSpace must be present. Further, backendTexture width and height must
+ not exceed context capabilities, and the context must be able to support
+ back-end textures.
+
+ If SK_SUPPORT_GPU is defined as zero, has no effect and returns nullptr.
+
+ @param context GPU context
+ @param backendTexture texture residing on GPU
+ @param origin one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin
+ @param sampleCnt samples per pixel, or 0 to disable full scene anti-aliasing
+ @param colorType one of: kUnknown_SkColorType, kAlpha_8_SkColorType,
+ kRGB_565_SkColorType, kARGB_4444_SkColorType,
+ kRGBA_8888_SkColorType, kBGRA_8888_SkColorType,
+ kGray_8_SkColorType, kRGBA_F16_SkColorType
+ @param colorSpace range of colors
+ @param surfaceProps LCD striping orientation and setting for device independent
+ fonts; may be nullptr
+ @return SkSurface if all parameters are valid; otherwise, nullptr
+ */
static sk_sp<SkSurface> MakeFromBackendTexture(GrContext* context,
const GrBackendTexture& backendTexture,
GrSurfaceOrigin origin, int sampleCnt,
@@ -118,19 +217,56 @@ public:
sk_sp<SkColorSpace> colorSpace,
const SkSurfaceProps* surfaceProps);
+ /** Wraps a GPU-backed buffer into SkSurface. Caller must ensure render target is
+ valid for the lifetime of returned SkSurface.
+
+ SkSurface is returned if all parameters are valid. backendRenderTarget is valid if
+ its pixel configuration agrees with colorSpace and context; for instance, if
+ backendRenderTarget has an sRGB configuration, then context must support sRGB,
+ and colorSpace must be present. Further, backendRenderTarget width and height must
+ not exceed context capabilities, and the context must be able to support
+ back-end render targets.
+
+ If SK_SUPPORT_GPU is defined as zero, has no effect and returns nullptr.
+
+ @param context GPU context
+ @param backendRenderTarget GPU intermediate memory buffer
+ @param origin one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin
+ @param colorSpace range of colors
+ @param surfaceProps LCD striping orientation and setting for device independent
+ fonts; may be nullptr
+ @return SkSurface if all parameters are valid; otherwise, nullptr
+ */
static sk_sp<SkSurface> MakeFromBackendRenderTarget(GrContext* context,
const GrBackendRenderTarget& backendRenderTarget,
GrSurfaceOrigin origin,
sk_sp<SkColorSpace> colorSpace,
const SkSurfaceProps* surfaceProps);
- /**
- * The GrBackendRenderTarget must have a valid backend format set (GrGLTextureInfo::fFormat,
- * GrVkImageInfo::fFormat, etc.) in it. The passed in SkColorType informs skia how it should
- * interpret the backend format supplied by the GrBackendRenderTarget. If the format in the
- * GrBackendRenderTarget is not compatible with the sampleCnt, SkColorType, and SkColorSpace
- * we will return nullptr.
- */
+ /** Wraps a GPU-backed buffer into SkSurface. Caller must ensure render target is
+ valid for the lifetime of returned SkSurface.
+
+ SkSurface is returned if all parameters are valid. backendRenderTarget is valid if
+ its pixel configuration agrees with colorSpace and context; for instance, if
+ backendRenderTarget has an sRGB configuration, then context must support sRGB,
+ and colorSpace must be present. Further, backendRenderTarget width and height must
+ not exceed context capabilities, and the context must be able to support
+ back-end render targets.
+
+ If SK_SUPPORT_GPU is defined as zero, has no effect and returns nullptr.
+
+ @param context GPU context
+ @param backendRenderTarget GPU intermediate memory buffer
+ @param origin one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin
+ @param colorType one of: kUnknown_SkColorType, kAlpha_8_SkColorType,
+ kRGB_565_SkColorType, kARGB_4444_SkColorType,
+ kRGBA_8888_SkColorType, kBGRA_8888_SkColorType,
+ kGray_8_SkColorType, kRGBA_F16_SkColorType
+ @param colorSpace range of colors
+ @param surfaceProps LCD striping orientation and setting for device independent
+ fonts; may be nullptr
+ @return SkSurface if all parameters are valid; otherwise, nullptr
+ */
static sk_sp<SkSurface> MakeFromBackendRenderTarget(GrContext* context,
const GrBackendRenderTarget& backendRenderTarget,
GrSurfaceOrigin origin,
@@ -138,13 +274,23 @@ public:
sk_sp<SkColorSpace> colorSpace,
const SkSurfaceProps* surfaceProps);
- /**
- * Used to wrap a pre-existing 3D API texture as a SkSurface. Skia will treat the texture as
- * a rendering target only, but unlike NewFromBackendRenderTarget, Skia will manage and own
- * the associated render target objects (but not the provided texture). Skia will not assume
- * ownership of the texture and the client must ensure the texture is valid for the lifetime
- * of the SkSurface.
- */
+ /** Used to wrap a GPU-backed texture as a SkSurface. Skia will treat the texture as
+ a rendering target only, but unlike NewFromBackendRenderTarget, Skia will manage and own
+ the associated render target objects (but not the provided texture). Skia will not assume
+ ownership of the texture and the client must ensure the texture is valid for the lifetime
+ of the SkSurface.
+
+ If SK_SUPPORT_GPU is defined as zero, has no effect and returns nullptr.
+
+ @param context GPU context
+ @param backendTexture texture residing on GPU
+ @param origin one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin
+ @param sampleCnt samples per pixel, or 0 to disable full scene anti-aliasing
+ @param colorSpace range of colors
+ @param surfaceProps LCD striping orientation and setting for device independent
+ fonts; may be nullptr
+ @return SkSurface if all parameters are valid; otherwise, nullptr
+ */
static sk_sp<SkSurface> MakeFromBackendTextureAsRenderTarget(GrContext* context,
const GrBackendTexture& backendTexture,
GrSurfaceOrigin origin,
@@ -152,19 +298,27 @@ public:
sk_sp<SkColorSpace> colorSpace,
const SkSurfaceProps* surfaceProps);
- /**
- * Used to wrap a pre-existing 3D API texture as a SkSurface. Skia will treat the texture as
- * a rendering target only, but unlike NewFromBackendRenderTarget, Skia will manage and own
- * the associated render target objects (but not the provided texture). Skia will not assume
- * ownership of the texture and the client must ensure the texture is valid for the lifetime
- * of the SkSurface.
- *
- * The GrBackendTexture must have a valid backend format supplied (GrGLTextureInfo::fFormat,
- * GrVkImageInfo::fFormat, etc.) in it. The passed in SkColorType informs skia how it should
- * interpret the backend format supplied by the GrBackendTexture. If the format in the
- * GrBackendTexture is not compatible with the sampleCnt, SkColorType, and SkColorSpace we
- * will return nullptr.
- */
+ /** Used to wrap a GPU-backed texture as a SkSurface. Skia will treat the texture as
+ a rendering target only, but unlike NewFromBackendRenderTarget, Skia will manage and own
+ the associated render target objects (but not the provided texture). Skia will not assume
+ ownership of the texture and the client must ensure the texture is valid for the lifetime
+ of the SkSurface.
+
+ If SK_SUPPORT_GPU is defined as zero, has no effect and returns nullptr.
+
+ @param context GPU context
+ @param backendTexture texture residing on GPU
+ @param origin one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin
+ @param sampleCnt samples per pixel, or 0 to disable full scene anti-aliasing
+ @param colorType one of: kUnknown_SkColorType, kAlpha_8_SkColorType,
+ kRGB_565_SkColorType, kARGB_4444_SkColorType,
+ kRGBA_8888_SkColorType, kBGRA_8888_SkColorType,
+ kGray_8_SkColorType, kRGBA_F16_SkColorType
+ @param colorSpace range of colors
+ @param surfaceProps LCD striping orientation and setting for device independent
+ fonts; may be nullptr
+ @return SkSurface if all parameters are valid; otherwise, nullptr
+ */
static sk_sp<SkSurface> MakeFromBackendTextureAsRenderTarget(GrContext* context,
const GrBackendTexture& backendTexture,
GrSurfaceOrigin origin,
@@ -173,18 +327,62 @@ public:
sk_sp<SkColorSpace> colorSpace,
const SkSurfaceProps* surfaceProps);
- /**
- * Return a new surface whose contents will be drawn to an offscreen
- * render target, allocated by the surface. The optional shouldCreateWithMips flag is a hint
- * that this surface may be snapped to an SkImage which will be used with mip maps so we should
- * create the backend gpu RenderTarget with mips to avoid a copy later on.
- */
+ /** Returns SkSurface on GPU indicated by context. Allocates memory for
+ pixels, based on the width, height, and SkColorType in ImageInfo. budgeted
+ selects whether allocation for pixels is tracked by context. imageInfo
+ describes the pixel format in SkColorType, and transparency in
+ SkAlphaType, and color matching in SkColorSpace.
+
+ sampleCount requests the number of samples per pixel.
+ Pass zero to disable Multi_Sample_Anti_Aliasing. The request is rounded
+ up to the next supported count, or rounded down if it is larger than the
+ maximum supported count.
+
+ surfaceOrigin pins either the top-left or the bottom-left corner to the origin.
+
+ shouldCreateWithMips hints that SkImage returned by makeImageSnapshot() is Mip_Map.
+
+ If SK_SUPPORT_GPU is defined as zero, has no effect and returns nullptr.
+
+ @param context GPU context
+ @param budgeted one of: SkBudgeted::kNo, SkBudgeted::kYes
+ @param imageInfo width, height, SkColorType, SkAlphaType, SkColorSpace;
+ width, or height, or both, may be zero
+ @param sampleCount samples per pixel, or 0 to disable full scene anti-aliasing
+ @param surfaceOrigin one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin
+ @param surfaceProps LCD striping orientation and setting for device independent
+ fonts; may be nullptr
+ @param shouldCreateWithMips hint that SkSurface will host Mip_Map images
+ @return SkSurface if all parameters are valid; otherwise, nullptr
+ */
static sk_sp<SkSurface> MakeRenderTarget(GrContext* context, SkBudgeted budgeted,
const SkImageInfo& imageInfo,
int sampleCount, GrSurfaceOrigin surfaceOrigin,
const SkSurfaceProps* surfaceProps,
bool shouldCreateWithMips = false);
+ /** Returns SkSurface on GPU indicated by context. Allocates memory for
+ pixels, based on the width, height, and SkColorType in ImageInfo. budgeted
+ selects whether allocation for pixels is tracked by context. imageInfo
+ describes the pixel format in SkColorType, and transparency in
+ SkAlphaType, and color matching in SkColorSpace.
+
+ sampleCount requests the number of samples per pixel.
+ Pass zero to disable Multi_Sample_Anti_Aliasing. The request is rounded
+ up to the next supported count, or rounded down if it is larger than the
+ maximum supported count.
+
+ SkSurface bottom-left corner is pinned to the origin.
+
+ @param context GPU context
+ @param budgeted one of: SkBudgeted::kNo, SkBudgeted::kYes
+ @param imageInfo width, height, SkColorType, SkAlphaType, SkColorSpace,
+ of raster surface; width, or height, or both, may be zero
+ @param sampleCount samples per pixel, or 0 to disable Multi_Sample_Anti_Aliasing
+ @param props LCD striping orientation and setting for device independent
+ fonts; may be nullptr
+ @return SkSurface if all parameters are valid; otherwise, nullptr
+ */
static sk_sp<SkSurface> MakeRenderTarget(GrContext* context, SkBudgeted budgeted,
const SkImageInfo& imageInfo, int sampleCount,
const SkSurfaceProps* props) {
@@ -192,6 +390,20 @@ public:
kBottomLeft_GrSurfaceOrigin, props);
}
+ /** Returns SkSurface on GPU indicated by context. Allocates memory for
+ pixels, based on the width, height, and SkColorType in ImageInfo. budgeted
+ selects whether allocation for pixels is tracked by context. imageInfo
+ describes the pixel format in SkColorType, and transparency in
+ SkAlphaType, and color matching in SkColorSpace.
+
+ SkSurface bottom-left corner is pinned to the origin.
+
+ @param context GPU context
+ @param budgeted one of: SkBudgeted::kNo, SkBudgeted::kYes
+ @param imageInfo width, height, SkColorType, SkAlphaType, SkColorSpace,
+ of raster surface; width, or height, or both, may be zero
+ @return SkSurface if all parameters are valid; otherwise, nullptr
+ */
static sk_sp<SkSurface> MakeRenderTarget(GrContext* context, SkBudgeted budgeted,
const SkImageInfo& imageInfo) {
if (!imageInfo.width() || !imageInfo.height()) {
@@ -201,234 +413,358 @@ public:
nullptr);
}
- /**
- * Returns a surface that stores no pixels. It can be drawn to via its canvas, but that
- * canvas does not draw anything. Calling makeImageSnapshot() will return nullptr.
- */
+ /** Returns SkSurface without backing pixels. Drawing to SkCanvas returned from SkSurface
+ has no effect. Calling makeImageSnapshot() on returned SkSurface returns nullptr.
+
+ @param width one or greater
+ @param height one or greater
+ @return SkSurface if width and height are positive; otherwise, nullptr
+ */
static sk_sp<SkSurface> MakeNull(int width, int height);
+ /** Returns pixel count in each row; may be zero or greater.
+
+ @return number of pixel columns
+ */
int width() const { return fWidth; }
+
+ /** Returns pixel row count; may be zero or greater.
+
+ @return number of pixel rows
+ */
int height() const { return fHeight; }
- /**
- * Returns a unique non-zero, unique value identifying the content of this
- * surface. Each time the content is changed changed, either by drawing
- * into this surface, or explicitly calling notifyContentChanged()) this
- * method will return a new value.
- *
- * If this surface is empty (i.e. has a zero-dimention), this will return
- * 0.
- */
+ /** Returns unique value identifying the content of SkSurface. Returned value changes
+ each time the content changes. Content is changed by drawing, or by calling
+ notifyContentWillChange().
+
+ @return unique content identifier
+ */
uint32_t generationID();
- /**
- * Modes that can be passed to notifyContentWillChange
- */
+ /** \enum SkSurface::ContentChangeMode
+ ContentChangeMode members are parameters to notifyContentWillChange().
+ */
enum ContentChangeMode {
- /**
- * Use this mode if it is known that the upcoming content changes will
- * clear or overwrite prior contents, thus making them discardable.
- */
- kDiscard_ContentChangeMode,
- /**
- * Use this mode if prior surface contents need to be preserved or
- * if in doubt.
- */
+ kDiscard_ContentChangeMode, //!< the surface is cleared or overwritten.
+
+ /** If a snapshot has been generated, this copies the SkSurface contents. */
kRetain_ContentChangeMode,
};
- /**
- * Call this if the contents are about to change. This will (lazily) force a new
- * value to be returned from generationID() when it is called next.
- *
- * CAN WE DEPRECATE THIS?
- */
+ /** Notifies that SkSurface contents will be changed by code outside of Skia.
+ Subsequent calls to generationID() return a different value.
+
+ mode is normally passed as kRetain_ContentChangeMode.
+ CAN WE DEPRECATE THIS?
+
+ @param mode one of: kDiscard_ContentChangeMode, kRetain_ContentChangeMode
+ */
void notifyContentWillChange(ContentChangeMode mode);
enum BackendHandleAccess {
- kFlushRead_BackendHandleAccess, //!< caller may read from the backend object
- kFlushWrite_BackendHandleAccess, //!< caller may write to the backend object
- kDiscardWrite_BackendHandleAccess, //!< caller must over-write the entire backend object
+ kFlushRead_BackendHandleAccess, //!< Caller may read from the back-end object.
+ kFlushWrite_BackendHandleAccess, //!< Caller may write to the back-end object.
+ kDiscardWrite_BackendHandleAccess, //!< Caller must overwrite the entire back-end object.
};
- /*
- * These are legacy aliases which will be removed soon
- */
+ /** Deprecated.
+ */
static const BackendHandleAccess kFlushRead_TextureHandleAccess =
kFlushRead_BackendHandleAccess;
+
+ /** Deprecated.
+ */
static const BackendHandleAccess kFlushWrite_TextureHandleAccess =
kFlushWrite_BackendHandleAccess;
+
+ /** Deprecated.
+ */
static const BackendHandleAccess kDiscardWrite_TextureHandleAccess =
kDiscardWrite_BackendHandleAccess;
+ /** Returns the GPU back-end reference of the texture used by SkSurface, or zero
+ if SkSurface is not backed by a GPU texture.
+
+ The returned texture handle is only valid until the next draw into SkSurface,
+ or when SkSurface is deleted.
- /**
- * Retrieves the backend API handle of the texture used by this surface, or 0 if the surface
- * is not backed by a GPU texture.
- *
- * The returned texture-handle is only valid until the next draw-call into the surface,
- * or the surface is deleted.
- */
+ @param backendHandleAccess one of: kFlushRead_BackendHandleAccess,
+ kFlushWrite_BackendHandleAccess, kDiscardWrite_BackendHandleAccess
+ @return GPU texture reference
+ */
GrBackendObject getTextureHandle(BackendHandleAccess backendHandleAccess);
- /**
- * Retrieves the backend API handle of the RenderTarget backing this surface. Callers must
- * ensure this function returns 'true' or else the GrBackendObject will be invalid
- *
- * In OpenGL this will return the FramebufferObject ID.
- */
+ /** Returns true and stores the GPU back-end reference of the render target used
+ by SkSurface in backendObject.
+
+ Return false if SkSurface is not backed by a GPU render target, and leaves
+ backendObject unchanged.
+
+ The returned render target handle is only valid until the next draw into SkSurface,
+ or when SkSurface is deleted.
+
+ In OpenGL this returns the frame buffer object ID.
+
+ @param backendObject GPU intermediate memory buffer
+ @param backendHandleAccess one of: kFlushRead_BackendHandleAccess,
+ kFlushWrite_BackendHandleAccess, kDiscardWrite_BackendHandleAccess
+ @return true if SkSurface is backed by GPU texture
+ */
bool getRenderTargetHandle(GrBackendObject* backendObject,
BackendHandleAccess backendHandleAccess);
- /**
- * Return a canvas that will draw into this surface. This will always
- * return the same canvas for a given surface, and is manged/owned by the
- * surface. It should not be used when its parent surface has gone out of
- * scope.
- */
+ /** Returns SkCanvas that draws into SkSurface. Subsequent calls return the same SkCanvas.
+ SkCanvas returned is managed and owned by SkSurface, and is deleted when SkSurface
+ is deleted.
+
+ @return drawing SkCanvas for SkSurface
+ */
SkCanvas* getCanvas();
- /**
- * Return a new surface that is "compatible" with this one, in that it will
- * efficiently be able to be drawn into this surface. Typical calling
- * pattern:
- *
- * SkSurface* A = SkSurface::New...();
- * SkCanvas* canvasA = surfaceA->newCanvas();
- * ...
- * SkSurface* surfaceB = surfaceA->newSurface(...);
- * SkCanvas* canvasB = surfaceB->newCanvas();
- * ... // draw using canvasB
- * canvasA->drawSurface(surfaceB); // <--- this will always be optimal!
- */
+ /** Returns a compatible SkSurface, or nullptr. Returned SkSurface contains
+ the same raster, GPU, or null properties as the original. Returned SkSurface
+ does not share the same pixels.
+
+ Returns nullptr if imageInfo width or height are zero, or if imageInfo
+ is incompatible with SkSurface.
+
+ @param imageInfo width, height, SkColorType, SkAlphaType, SkColorSpace,
+ of SkSurface; width and height must be greater than zero
+ @return compatible SkSurface or nullptr
+ */
sk_sp<SkSurface> makeSurface(const SkImageInfo& imageInfo);
- /**
- * Returns an image of the current state of the surface pixels up to this
- * point. Subsequent changes to the surface (by drawing into its canvas)
- * will not be reflected in this image. For the GPU-backend, the budgeting
- * decision for the snapped image will match that of the surface.
- */
+ /** Returns SkImage capturing SkSurface contents. Subsequent drawing to SkSurface contents
+ are not captured. SkImage allocation is accounted for if SkSurface was created with
+ SkBudgeted::kYes.
+
+ @return SkImage initialized with SkSurface contents
+ */
sk_sp<SkImage> makeImageSnapshot();
- /**
- * Though the caller could get a snapshot image explicitly, and draw that,
- * it seems that directly drawing a surface into another canvas might be
- * a common pattern, and that we could possibly be more efficient, since
- * we'd know that the "snapshot" need only live until we've handed it off
- * to the canvas.
- */
+ /** Draws SkSurface contents to canvas, with its top-left corner at (x, y).
+
+ If SkPaint paint is not nullptr, apply SkColorFilter, color alpha, SkImageFilter,
+ SkBlendMode, and SkDrawLooper.
+
+ @param canvas SkCanvas drawn into
+ @param x horizontal offset in SkCanvas
+ @param y vertical offset in SkCanvas
+ @param paint SkPaint containing SkBlendMode, SkColorFilter, SkImageFilter,
+ and so on; or nullptr
+ */
void draw(SkCanvas* canvas, SkScalar x, SkScalar y, const SkPaint* paint);
- /**
- * If the surface has direct access to its pixels (i.e. they are in local
- * RAM) return true, and if not null, set the pixmap parameter to point to the information
- * about the surface's pixels. The pixel address in the pixmap is only valid while
- * the surface object is in scope, and no API call is made on the surface
- * or its canvas.
- *
- * On failure, returns false and the pixmap parameter is ignored.
- */
+ /** Copies SkSurface pixel address, row bytes, and SkImageInfo to SkPixmap, if address
+ is available, and returns true. If pixel address is not available, return
+ false and leave SkPixmap unchanged.
+
+ pixmap contents become invalid on any future change to SkSurface.
+
+ @param pixmap storage for pixel state if pixels are readable; otherwise, ignored
+ @return true if SkSurface has direct access to pixels
+ */
bool peekPixels(SkPixmap* pixmap);
- /**
- * Copy the pixels from the surface into the specified pixmap,
- * converting them into the pixmap's format. The surface pixels are read
- * starting at the specified (srcX,srcY) location.
- *
- * The pixmap and (srcX,srcY) offset specifies a source rectangle
- *
- * srcR.setXYWH(srcX, srcY, pixmap.width(), pixmap.height());
- *
- * srcR is intersected with the bounds of the base-layer. If this intersection is not empty,
- * then we have two sets of pixels (of equal size). Replace the dst pixels with the
- * corresponding src pixels, performing any colortype/alphatype transformations needed
- * (in the case where the src and dst have different colortypes or alphatypes).
- *
- * This call can fail, returning false, for several reasons:
- * - If srcR does not intersect the surface bounds.
- * - If the requested colortype/alphatype cannot be converted from the surface's types.
- */
+ /** Copies SkRect of pixels to dst.
+
+ Source SkRect corners are (srcX, srcY) and SkSurface (width(), height()).
+ Destination SkRect corners are (0, 0) and (dst.width(), dst.height()).
+ Copies each readable pixel intersecting both rectangles, without scaling,
+ converting to dst.colorType() and dst.alphaType() if required.
+
+ Pixels are readable when SkSurface is raster, or backed by a GPU.
+
+ The destination pixel storage must be allocated by the caller.
+
+ Pixel values are converted only if SkColorType and SkAlphaType
+ do not match. Only pixels within both source and destination rectangles
+ are copied. dst contents outside SkRect intersection are unchanged.
+
+ Pass negative values for srcX or srcY to offset pixels across or down destination.
+
+ Does not copy, and returns false if:
+ - Source and destination rectangles do not intersect.
+ - SkPixmap pixels could not be allocated.
+ - dst.rowBytes() is too small to contain one row of pixels.
+
+ @param dst storage for pixels copied from SkSurface
+ @param srcX offset into readable pixels in x; may be negative
+ @param srcY offset into readable pixels in y; may be negative
+ @return true if pixels were copied
+ */
bool readPixels(const SkPixmap& dst, int srcX, int srcY);
+
+ /** Copies SkRect of pixels from SkCanvas into dstPixels.
+
+ Source SkRect corners are (srcX, srcY) and SkSurface (width(), height()).
+ Destination SkRect corners are (0, 0) and (dstInfo.width(), dstInfo.height()).
+ Copies each readable pixel intersecting both rectangles, without scaling,
+ converting to dstInfo.colorType() and dstInfo.alphaType() if required.
+
+ Pixels are readable when SkSurface is raster, or backed by a GPU.
+
+ The destination pixel storage must be allocated by the caller.
+
+ Pixel values are converted only if SkColorType and SkAlphaType
+ do not match. Only pixels within both source and destination rectangles
+ are copied. dstPixels contents outside SkRect intersection are unchanged.
+
+ Pass negative values for srcX or srcY to offset pixels across or down destination.
+
+ Does not copy, and returns false if:
+ - Source and destination rectangles do not intersect.
+ - SkSurface pixels could not be converted to dstInfo.colorType() or dstInfo.alphaType().
+ - dstRowBytes is too small to contain one row of pixels.
+
+ @param dstInfo width, height, SkColorType, and SkAlphaType of dstPixels
+ @param dstPixels storage for pixels; dstInfo.height() times dstRowBytes, or larger
+ @param dstRowBytes size of one destination row; dstInfo.width() times pixel size, or larger
+ @param srcX offset into readable pixels in x; may be negative
+ @param srcY offset into readable pixels in y; may be negative
+ @return true if pixels were copied
+ */
bool readPixels(const SkImageInfo& dstInfo, void* dstPixels, size_t dstRowBytes,
int srcX, int srcY);
+
+ /** Copies SkRect of pixels from SkSurface into bitmap.
+
+ Source SkRect corners are (srcX, srcY) and SkSurface (width(), height()).
+ Destination SkRect corners are (0, 0) and (bitmap.width(), bitmap.height()).
+ Copies each readable pixel intersecting both rectangles, without scaling,
+ converting to bitmap.colorType() and bitmap.alphaType() if required.
+
+ Pixels are readable when SkSurface is raster, or backed by a GPU.
+
+ The destination pixel storage must be allocated by the caller.
+
+ Pixel values are converted only if SkColorType and SkAlphaType
+ do not match. Only pixels within both source and destination rectangles
+ are copied. dst contents outside SkRect intersection are unchanged.
+
+ Pass negative values for srcX or srcY to offset pixels across or down destination.
+
+ Does not copy, and returns false if:
+ - Source and destination rectangles do not intersect.
+ - SkSurface pixels could not be converted to dst.colorType() or dst.alphaType().
+ - dst pixels could not be allocated.
+ - dst.rowBytes() is too small to contain one row of pixels.
+
+ @param dst storage for pixels copied from SkSurface
+ @param srcX offset into readable pixels in x; may be negative
+ @param srcY offset into readable pixels in y; may be negative
+ @return true if pixels were copied
+ */
bool readPixels(const SkBitmap& dst, int srcX, int srcY);
- /**
- * Special version of drawing a pixmap to the surface (without going through the canvas).
- * - the implied blendmode is kSrc (overwrite the surface pixel values)
- * - any settings on the surface's canvas are ignored: matrix, clipping, etc.
- */
+ /** Copies SkRect of pixels from the src SkPixmap to the SkSurface.
+
+ Source SkRect corners are (0, 0) and (src.width(), src.height()).
+ Destination SkRect corners are (dstX, dstY) and (dstX + Surface width(), dstY + Surface height()).
+ Copies each readable pixel intersecting both rectangles, without scaling,
+ converting to SkSurface colorType() and SkSurface alphaType() if required.
+
+ @param src storage for pixels to copy to SkSurface
+ @param dstX x position relative to SkSurface to begin copy; may be negative
+ @param dstY x position relative to SkSurface to begin copy; may be negative
+ */
void writePixels(const SkPixmap& src, int dstX, int dstY);
- /**
- * Helper that extracts the pixmap from the bitmap (if possible), and then calls writePixels
- * with that pixmap.
- */
+ /** Copies SkRect of pixels from the src SkBitmap to the SkSurface.
+
+ Source SkRect corners are (0, 0) and (src.width(), src.height()).
+ Destination SkRect corners are (dstX, dstY) and (dstX + Surface width(), dstY + Surface height()).
+ Copies each readable pixel intersecting both rectangles, without scaling,
+ converting to SkSurface colorType() and SkSurface alphaType() if required.
+
+ @param src storage for pixels to copy to SkSurface
+ @param dstX x position relative to SkSurface to begin copy; may be negative
+ @param dstY x position relative to SkSurface to begin copy; may be negative
+ */
void writePixels(const SkBitmap& src, int dstX, int dstY);
+ /** Returns SkSurfaceProps for surface.
+
+ @return LCD striping orientation and setting for device independent fonts
+ */
const SkSurfaceProps& props() const { return fProps; }
- /**
- * Issue any pending surface IO to the current backend 3D API and resolve any surface MSAA.
- *
- * The flush calls below are the new preferred way to flush calls to a surface, and this call
- * will eventually be removed.
- */
+ /** To be deprecated soon.
+ */
void prepareForExternalIO();
- /**
- * Issue any pending surface IO to the current backend 3D API
- */
+ /** Issues pending SkSurface commands to the GPU-backed API and resolves any SkSurface MSAA.
+
+ Skia flushes as needed, so it is not necessary to call this if Skia manages
+ drawing and object lifetime. Call when interleaving Skia calls with native
+ GPU calls.
+ */
void flush();
- /**
- * Issue any pending surface IO to the current backend 3D API. After issuing all commands,
- * numSemaphore semaphores will be signaled by the gpu. The client passes in an array of
- * numSemaphores GrBackendSemaphores. In general these GrBackendSemaphore's can be either
- * initialized or not. If they are initialized, the backend uses the passed in semaphore.
- * If it is not initialized, a new semaphore is created and the GrBackendSemaphore object
- * is initialized with that semaphore.
- *
- * The client will own and be responsible for deleting the underlying semaphores that are stored
- * and returned in initialized GrBackendSemaphore objects. The GrBackendSemaphore objects
- * themselves can be deleted as soon as this function returns.
- *
- * If the backend API is OpenGL only uninitialized GrBackendSemaphores are supported.
- * If the backend API is Vulkan either initialized or unitialized semaphores are supported.
- * If unitialized, the semaphores which are created will be valid for use only with the VkDevice
- * with which they were created.
- *
- * If this call returns GrSemaphoresSubmited::kNo, the GPU backend will not have created or
- * added any semaphores to signal on the GPU. Thus the client should not have the GPU wait on
- * any of the semaphores. However, any pending surface IO will still be flushed.
- */
+ /** Issues pending SkSurface commands to the GPU-backed API and resolves any SkSurface MSAA.
+ After issuing all commands, signalSemaphores of count numSemaphores semaphores
+ are signaled by the GPU.
+
+ For each GrBackendSemaphore in signalSemaphores:
+ if GrBackendSemaphore is initialized, the GPU back-end uses the semaphore as is;
+ otherwise, a new semaphore is created and initializes GrBackendSemaphore.
+
+ The caller must delete the semaphores created and returned in signalSemaphores.
+ GrBackendSemaphore can be deleted as soon as this function returns.
+
+ If the back-end API is OpenGL only uninitialized backend semaphores are supported.
+
+ If the back-end API is Vulkan semaphores may be initialized or uninitialized.
+ If uninitialized, created semaphores are valid only with the VkDevice
+ with which they were created.
+
+ If GrSemaphoresSubmitted::kNo is returned, the GPU back-end did not create or
+ add any semaphores to signal on the GPU; the caller should not instruct the GPU
+ to wait on any of the semaphores.
+
+ Pending surface commands are flushed regardless of the return result.
+
+ @param numSemaphores size of signalSemaphores array
+ @param signalSemaphores array of semaphore containers
+ @return one of: GrSemaphoresSubmitted::kYes, GrSemaphoresSubmitted::kNo
+ */
GrSemaphoresSubmitted flushAndSignalSemaphores(int numSemaphores,
GrBackendSemaphore signalSemaphores[]);
- /**
- * Inserts a list of GPU semaphores that the current backend 3D API must wait on before
- * executing any more commands on the GPU for this surface. Skia will take ownership of the
- * underlying semaphores and delete them once they have been signaled and waited on.
- *
- * If this call returns false, then the GPU backend will not wait on any passed in semaphores,
- * and the client will still own the semaphores.
- */
+ /** Inserts a list of GPU semaphores that the current GPU-backed API must wait on before
+ executing any more commands on the GPU for this surface. Skia will take ownership of the
+ underlying semaphores and delete them once they have been signaled and waited on.
+ If this call returns false, then the GPU back-end will not wait on any passed in semaphores,
+ and the client will still own the semaphores.
+
+ @param numSemaphores size of waitSemaphores array
+ @param waitSemaphores array of semaphore containers
+ @return true if GPU is waiting on semaphores
+ */
bool wait(int numSemaphores, const GrBackendSemaphore* waitSemaphores);
- /**
- * This creates a characterization of this SkSurface's properties that can
- * be used to perform gpu-backend preprocessing in a separate thread (via
- * the SkDeferredDisplayListRecorder).
- * It will return false on failure (e.g., if the SkSurface is cpu-backed).
- */
+ /** Initializes SkSurfaceCharacterization that can be used to perform GPU back-end
+ processing in a separate thread. Typically this is used to divide drawing
+ into multiple tiles. DeferredDisplayListRecorder records the drawing commands
+ for each tile.
+
+ Return true if SkSurface supports characterization. raster surface returns false.
+
+ @param characterization properties for parallel drawing
+ @return true if supported
+ */
bool characterize(SkSurfaceCharacterization* characterization) const;
- /**
- * Draw a deferred display list (created via SkDeferredDisplayListRecorder).
- * The draw will be skipped if the characterization stored in the display list
- * isn't compatible with this surface.
- */
+ /** Draws deferred display list created using SkDeferredDisplayListRecorder.
+ Has no effect and returns false if SkSurfaceCharacterization stored in
+ deferredDisplayList is not compatible with SkSurface.
+
+ raster surface returns false.
+
+ @param deferredDisplayList drawing commands
+ @return false if deferredDisplayList is not compatible
+ */
bool draw(SkDeferredDisplayList* deferredDisplayList);
protected:
generated by cgit v1.2.3 (git 2.39.1) at 2024-06-15 21:45:32 +0000