diff options
| -rw-r--r-- | include/core/SkCanvas.h | 326 | ||||
| -rw-r--r-- | include/core/SkPaint.h | 95 | ||||
| -rw-r--r-- | include/core/SkPath.h | 120 | ||||
| -rw-r--r-- | include/core/SkPixmap.h | 624 |
4 files changed, 942 insertions, 223 deletions
diff --git a/include/core/SkCanvas.h b/include/core/SkCanvas.h index 09d2ed5bb0..f2a271c5ef 100644 --- a/include/core/SkCanvas.h +++ b/include/core/SkCanvas.h @@ -86,7 +86,7 @@ public: Pixel buffer size should be info height times computed rowBytes. - @param info width, height, SkColorType, SkAlphaType, color space, of raster surface; + @param info width, height, SkColorType, SkAlphaType, SkColorSpace, of raster surface; width, or height, or both, may be zero @param pixels pointer to destination pixels buffer @param rowBytes interval from one SkSurface row to the next, or zero @@ -125,21 +125,21 @@ public: return MakeRasterDirect(SkImageInfo::MakeN32Premul(width, height), pixels, rowBytes); } - /** Creates an empty canvas with no backing device or pixels, with + /** Creates an empty SkCanvas with no backing device or pixels, with a width and height of zero. - @return empty canvas + @return empty SkCanvas */ SkCanvas(); /** Creates SkCanvas of the specified dimensions without a SkSurface. Used by Subclasses with custom implementations for draw methods. - If props equals nullptr, SkSurfaceProps are created with SkSurfaceProps::InitType settings, - which choose the pixel striping direction and order. Since a platform may dynamically - change its direction when the device is rotated, and since a platform may have - multiple monitors with different characteristics, it's best not to rely on this - legacy behavior. + If props equals nullptr, SkSurfaceProps are created with + SkSurfaceProps::InitType settings, which choose the pixel striping + direction and order. Since a platform may dynamically change its direction when + the device is rotated, and since a platform may have multiple monitors with + different characteristics, it is best not to rely on this legacy behavior. @param width zero or greater @param height zero or greater @@ -199,7 +199,7 @@ public: */ SkCanvas(const SkBitmap& bitmap, const SkSurfaceProps& props); - /** Draw saved SkCanvas::_anonymous, if any. + /** Draw saved layer, if any. Free up resources used by SkCanvas. */ virtual ~SkCanvas(); @@ -232,11 +232,11 @@ public: */ void flush(); - /** Gets the size of the base or root SkCanvas::_anonymous in global canvas coordinates. The - origin of the base SkCanvas::_anonymous is always (0,0). The area available for drawing may be + /** Gets the size of the base or root layer in global canvas coordinates. The + origin of the base layer is always (0,0). The area available for drawing may be smaller (due to clipping or saveLayer). - @return integral width and height of base SkCanvas::_anonymous + @return integral width and height of base layer */ virtual SkISize getBaseLayerSize() const; @@ -246,7 +246,7 @@ public: If props is nullptr, matches SkSurfaceProps in SkCanvas. If props is nullptr and SkCanvas does not have SkSurfaceProps, creates SkSurface with default SkSurfaceProps. - @param info width, height, SkColorType, SkAlphaType, and color space + @param info width, height, SkColorType, SkAlphaType, and SkColorSpace @param props SkSurfaceProps to match; may be nullptr to match SkCanvas @return SkSurface matching info and props, or nullptr if no match is available */ @@ -267,7 +267,7 @@ public: @param info storage for writable pixels' SkImageInfo; may be nullptr @param rowBytes storage for writable pixels' row bytes; may be nullptr - @param origin storage for SkCanvas top SkCanvas::_anonymous origin, its top left corner; + @param origin storage for SkCanvas top layer origin, its top left corner; may be nullptr @return address of pixels, or nullptr if inaccessible */ @@ -302,6 +302,30 @@ public: /** Copies rectangle of pixels from SkCanvas into dstPixels. SkMatrix and clip are ignored. Source rectangle corners are (srcX, srcY) and + (this->imageInfo.width(), this->imageInfo.height()). + + Destination rectangle corners are (0, 0) and (bitmap.width(), bitmap.height()). + Copies each readable pixel intersecting both rectangles, without scaling, + converting to dstInfo.colorType() and dstInfo.alphaType() if required. + + Pixels are readable when SkBaseDevice is raster, or backed by a GPU. + Pixels are not readable when SkCanvas is returned by SkDocument::beginPage, + returned by SkPictureRecorder::beginRecording, or SkCanvas is the base of a utility + class like SkDumpCanvas. + + 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 the rectangle 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. + - SkCanvas pixels could not be converted to dstInfo.colorType() or dstInfo.alphaType(). + - SkCanvas pixels are not readable; for instance, SkCanvas is document-based. + - 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 @@ -315,6 +339,31 @@ public: /** Copies rectangle of pixels from SkCanvas into pixmap. SkMatrix and clip are ignored. Source rectangle corners are (srcX, srcY) and + (this->imageInfo.width(), this->imageInfo.height()). + + Destination rectangle corners are (0, 0) and (bitmap.width(), bitmap.height()). + Copies each readable pixel intersecting both rectangles, without scaling, + converting to pixmap.colorType() and pixmap.alphaType() if required. + + Pixels are readable when SkBaseDevice is raster, or backed by a GPU. + Pixels are not readable when SkCanvas is returned by SkDocument::beginPage, + returned by SkPictureRecorder::beginRecording, or SkCanvas is the base of a utility + class like SkDumpCanvas. + + 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 rectangles + are copied. pixmap pixels contents outside the rectangle intersection are unchanged. + + Pass negative values for srcX or srcY to offset pixels across or down pixmap. + + Does not copy, and returns false if: + - Source and destination rectangles do not intersect. + - SkCanvas pixels could not be converted to pixmap.colorType() or pixmap.alphaType(). + - SkCanvas pixels are not readable; for instance, SkCanvas is document-based. + - SkPixmap pixels could not be allocated. + - pixmap.rowBytes() is too small to contain one row of pixels. @param pixmap storage for pixels copied from SkCanvas @param srcX offset into readable pixels in x; may be negative @@ -325,6 +374,31 @@ public: /** Copies rectangle of pixels from SkCanvas into bitmap. SkMatrix and clip are ignored. Source rectangle corners are (srcX, srcY) and + (this->imageInfo.width(), this->imageInfo.height()). + + Destination rectangle 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 SkBaseDevice is raster, or backed by a GPU. + Pixels are not readable when SkCanvas is returned by SkDocument::beginPage, + returned by SkPictureRecorder::beginRecording, or SkCanvas is the base of a utility + class like SkDumpCanvas. + + Caller must allocate pixel storage in bitmap if needed. + + SkBitmap values are converted only if SkColorType and SkAlphaType + do not match. Only pixels within both source and destination rectangles + are copied. SkBitmap pixels outside the rectangle intersection are unchanged. + + Pass negative values for srcX or srcY to offset pixels across or down bitmap. + + Does not copy, and returns false if: + - Source and destination rectangles do not intersect. + - SkCanvas pixels could not be converted to bitmap.colorType() or bitmap.alphaType(). + - SkCanvas pixels are not readable; for instance, SkCanvas is document-based. + - bitmap pixels could not be allocated. + - bitmap.rowBytes() is too small to contain one row of pixels. @param bitmap storage for pixels copied from SkCanvas @param srcX offset into readable pixels in x; may be negative @@ -336,10 +410,35 @@ public: /** Copies rectangle from pixels to SkCanvas. SkMatrix and clip are ignored. Source rectangle corners are (0, 0) and (info.width(), info.height()). Destination rectangle corners are (x, y) and + (this->imageInfo.width(), this->imageInfo.height()). + + Copies each readable pixel intersecting both rectangles, without scaling, + converting to + this->imageInfo.colorType()and + this->imageInfo.alphaType()if required. + + Pixels are writable when SkBaseDevice is raster, or backed by a GPU. + Pixels are not writable when SkCanvas is returned by SkDocument::beginPage, + returned by SkPictureRecorder::beginRecording, or SkCanvas is the base of a utility + class like SkDumpCanvas. + + Pixel values are converted only if SkColorType and SkAlphaType + do not match. Only pixels within both source and destination rectangles + are copied. SkCanvas pixels outside the rectangle intersection are unchanged. + + Pass negative values for x or y to offset pixels to the left or + above SkCanvas pixels. + + 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(). + - SkCanvas pixels are not writable; for instance, SkCanvas is document-based. + - rowBytes is too small to contain one row of pixels. @param info width, height, SkColorType, and SkAlphaType of pixels @param pixels pixels to copy, of size info.height() times rowBytes, or larger - @param rowBytes size of one pixels row; info.width() times pixel size, or larger + @param rowBytes size of one row of pixels; info.width() times pixel size, or larger @param x offset into SkCanvas writable pixels in x; may be negative @param y offset into SkCanvas writable pixels in y; may be negative @return true if pixels were written to SkCanvas @@ -347,7 +446,35 @@ public: bool writePixels(const SkImageInfo& info, const void* pixels, size_t rowBytes, int x, int y); /** Copies rectangle from pixels to SkCanvas. SkMatrix and clip are ignored. - Source rectangle corners are (0, 0) and + Source rectangle corners are (0, 0) and (bitmap.width(), bitmap.height()). + + Destination rectangle corners are (x, y) and + (this->imageInfo.width(), this->imageInfo.height()). + + Copies each readable pixel intersecting both rectangles, without scaling, + converting to + this->imageInfo.colorType()and + this->imageInfo.alphaType()if required. + + Pixels are writable when SkBaseDevice is raster, or backed by a GPU. + Pixels are not writable when SkCanvas is returned by SkDocument::beginPage, + returned by SkPictureRecorder::beginRecording, or SkCanvas is the base of a utility + class like SkDumpCanvas. + + Pixel values are converted only if SkColorType and SkAlphaType + do not match. Only pixels within both source and destination rectangles + are copied. SkCanvas pixels outside the rectangle intersection are unchanged. + + Pass negative values for x or y to offset pixels to the left or + above SkCanvas pixels. + + 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(). + - SkCanvas pixels are not writable; for instance, SkCanvas is document based. + - bitmap pixels are inaccessible; for instance, bitmap wraps a texture. @param bitmap contains pixels copied to SkCanvas @param x offset into SkCanvas writable pixels in x; may be negative @@ -389,8 +516,8 @@ public: Call restoreToCount() with returned value to restore this and subsequent saves. - @param bounds hint to limit the size of the SkCanvas::_anonymous; may be nullptr - @param paint graphics state for SkCanvas::_anonymous; may be nullptr + @param bounds hint to limit the size of the layer; may be nullptr + @param paint graphics state for layer; may be nullptr @return depth of saved stack */ int saveLayer(const SkRect* bounds, const SkPaint* paint); @@ -404,7 +531,7 @@ public: setMatrix(), and resetMatrix(). Clip may be changed by clipRect(), clipRRect(), clipPath(), clipRegion(). - SkRect bounds suggests but does not define the SkCanvas::_anonymous size. To clip drawing to + SkRect bounds suggests but does not define the layer size. To clip drawing to a specific rectangle, use clipRect(). Optional SkPaint paint applies color alpha, SkColorFilter, SkImageFilter, and @@ -412,8 +539,8 @@ public: Call restoreToCount() with returned value to restore this and subsequent saves. - @param bounds hint to limit the size of SkCanvas::_anonymous; may be nullptr - @param paint graphics state for SkCanvas::_anonymous; may be nullptr + @param bounds hint to limit the size of layer; may be nullptr + @param paint graphics state for layer; may be nullptr @return depth of saved stack */ int saveLayer(const SkRect& bounds, const SkPaint* paint) { @@ -422,16 +549,16 @@ public: /** Saves SkMatrix, clip, and SkDrawFilter (Draw_Filter deprecated on most platforms), and allocates a SkBitmap for subsequent drawing. - lcd text is preserved when the SkCanvas::_anonymous is drawn to the prior SkCanvas::_anonymous. + lcd text is preserved when the layer is drawn to the prior layer. Calling restore() discards changes to SkMatrix, clip, and SkDrawFilter, - and draws SkCanvas::_anonymous. + and draws layer. SkMatrix may be changed by translate(), scale(), rotate(), skew(), concat(), setMatrix(), and resetMatrix(). Clip may be changed by clipRect(), clipRRect(), clipPath(), clipRegion(). - SkRect bounds suggests but does not define the SkCanvas::_anonymous size. To clip drawing to + SkRect bounds suggests but does not define the layer size. To clip drawing to a specific rectangle, use clipRect(). Optional SkPaint paint applies color alpha, SkColorFilter, SkImageFilter, and @@ -440,11 +567,11 @@ 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 SkCanvas::_anonymous. lcd text drawn on a background with transparency may result in - incorrect banding. + prior layer. lcd text drawn on a background with transparency may result in + incorrect blending. - @param bounds hint to limit the size of SkCanvas::_anonymous; may be nullptr - @param paint graphics state for SkCanvas::_anonymous; may be nullptr + @param bounds hint to limit the size of layer; may be nullptr + @param paint graphics state for layer; may be nullptr @return depth of saved stack */ int saveLayerPreserveLCDTextRequests(const SkRect* bounds, const SkPaint* paint); @@ -453,41 +580,41 @@ public: and allocates SkBitmap for subsequent drawing. Calling restore() discards changes to SkMatrix, clip, and SkDrawFilter, - and blends SkCanvas::_anonymous with alpha opacity onto prior SkCanvas::_anonymous. + and blends layer with alpha opacity onto prior layer. SkMatrix may be changed by translate(), scale(), rotate(), skew(), concat(), setMatrix(), and resetMatrix(). Clip may be changed by clipRect(), clipRRect(), clipPath(), clipRegion(). - SkRect bounds suggests but does not define SkCanvas::_anonymous size. To clip drawing to + SkRect bounds suggests but does not define layer size. To clip drawing to a specific rectangle, use clipRect(). alpha of zero is fully transparent, 255 is fully opaque. Call restoreToCount() with returned value to restore this and subsequent saves. - @param bounds hint to limit the size of SkCanvas::_anonymous; may be nullptr - @param alpha opacity of SkCanvas::_anonymous + @param bounds hint to limit the size of layer; may be nullptr + @param alpha opacity of layer @return depth of saved stack */ int saveLayerAlpha(const SkRect* bounds, U8CPU alpha); /** \enum SaveLayerFlags provides options that may be used in any combination in SaveLayerRec, - defining how _anonymous allocated by saveLayer() operates. + defining how layer allocated by saveLayer() operates. */ enum { - /** Creates _anonymous without transparency. Flag is ignored if _anonymous SkPaint contains + /** Creates layer without transparency. Flag is ignored if layer SkPaint contains SkImageFilter or SkColorFilter. */ kIsOpaque_SaveLayerFlag = 1 << 0, - /** Creates _anonymous for LCD text. Flag is ignored if _anonymous SkPaint contains + /** Creates layer for LCD text. Flag is ignored if layer SkPaint contains SkImageFilter or SkColorFilter. */ kPreserveLCDText_SaveLayerFlag = 1 << 1, - /** Initializes _anonymous with the contents of the previous _anonymous. */ + /** Initializes layer with the contents of the previous layer. */ kInitWithPrevious_SaveLayerFlag = 1 << 2, #ifdef SK_SUPPORT_LEGACY_CLIPTOLAYERFLAG @@ -499,7 +626,6 @@ public: typedef uint32_t SaveLayerFlags; /** \struct SkCanvas::SaveLayerRec - SaveLayerRec contains the state used to create the SkCanvas::_anonymous. */ struct SaveLayerRec { @@ -511,9 +637,9 @@ public: /** Sets fBounds, fPaint, and fSaveLayerFlags; sets fBackdrop to nullptr. - @param bounds SkCanvas::_anonymous dimensions; may be nullptr - @param paint applied to SkCanvas::_anonymous when overlaying prior SkCanvas::_anonymous; may be nullptr - @param saveLayerFlags SaveLayerRec options to modify SkCanvas::_anonymous + @param bounds layer dimensions; may be nullptr + @param paint applied to layer when overlaying prior layer; may be nullptr + @param saveLayerFlags SaveLayerRec options to modify layer @return SaveLayerRec with empty backdrop */ SaveLayerRec(const SkRect* bounds, const SkPaint* paint, SaveLayerFlags saveLayerFlags = 0) @@ -524,11 +650,11 @@ public: /** Sets fBounds, fPaint, fBackdrop, and fSaveLayerFlags. - @param bounds SkCanvas::_anonymous dimensions; may be nullptr - @param paint applied to SkCanvas::_anonymous when overlaying prior SkCanvas::_anonymous; + @param bounds layer dimensions; may be nullptr + @param paint applied to layer when overlaying prior layer; may be nullptr - @param backdrop prior SkCanvas::_anonymous copied with SkImageFilter; may be nullptr - @param saveLayerFlags SaveLayerRec options to modify SkCanvas::_anonymous + @param backdrop prior layer copied with SkImageFilter; may be nullptr + @param saveLayerFlags SaveLayerRec options to modify layer @return SaveLayerRec fully specified */ SaveLayerRec(const SkRect* bounds, const SkPaint* paint, const SkImageFilter* backdrop, @@ -542,19 +668,19 @@ public: /** EXPERIMENTAL: Not ready for general use. Sets fBounds, fPaint, fBackdrop, fClipMask, fClipMatrix, and fSaveLayerFlags. clipMatrix uses color alpha channel of image, transformed by clipMatrix, to clip - SkCanvas::_anonymous when drawn to SkCanvas. + layer when drawn to SkCanvas. Implementation is incomplete; has no effect if SkBaseDevice is GPU-backed. - @param bounds SkCanvas::_anonymous dimensions; may be nullptr - @param paint graphics state applied to SkCanvas::_anonymous when overlaying prior - SkCanvas::_anonymous; may be nullptr - @param backdrop prior SkCanvas::_anonymous copied with SkImageFilter; + @param bounds layer dimensions; may be nullptr + @param paint graphics state applied to layer when overlaying prior + layer; may be nullptr + @param backdrop prior layer copied with SkImageFilter; may be nullptr - @param clipMask clip applied to SkCanvas::_anonymous; may be nullptr + @param clipMask clip applied to layer; may be nullptr @param clipMatrix matrix applied to clipMask; may be nullptr to use identity matrix - @param saveLayerFlags SaveLayerRec options to modify SkCanvas::_anonymous + @param saveLayerFlags SaveLayerRec options to modify layer @return SaveLayerRec fully specified */ SaveLayerRec(const SkRect* bounds, const SkPaint* paint, const SkImageFilter* backdrop, @@ -568,38 +694,38 @@ public: , fSaveLayerFlags(saveLayerFlags) {} - /** fBounds is used as a hint to limit the size of SkCanvas::_anonymous; may be nullptr. - fBounds suggests but does not define SkCanvas::_anonymous size. To clip drawing to + /** fBounds is used as a hint to limit the size of layer; may be nullptr. + fBounds suggests but does not define layer size. To clip drawing to a specific rectangle, use clipRect(). */ const SkRect* fBounds = nullptr; - /** fPaint modifies how SkCanvas::_anonymous overlays the prior SkCanvas::_anonymous; may be nullptr. + /** fPaint modifies how layer overlays the prior layer; may be nullptr. color alpha, SkBlendMode, SkColorFilter, SkDrawLooper, SkImageFilter, and - SkMaskFilter affect SkCanvas::_anonymous draw. + SkMaskFilter affect layer draw. */ const SkPaint* fPaint = nullptr; - /** fBackdrop applies SkImageFilter to the prior SkCanvas::_anonymous when copying to the SkCanvas::_anonymous; + /** fBackdrop applies SkImageFilter to the prior layer when copying to the layer; may be nullptr. Use kInitWithPrevious_SaveLayerFlag to copy the - prior SkCanvas::_anonymous without an SkImageFilter. + prior layer without an SkImageFilter. */ const SkImageFilter* fBackdrop = nullptr; - /** restore() clips SkCanvas::_anonymous by the color alpha channel of fClipMask when - SkCanvas::_anonymous is copied to SkBaseDevice. fClipMask may be nullptr. . + /** restore() clips layer by the color alpha channel of fClipMask when + layer is copied to SkBaseDevice. fClipMask may be nullptr. . */ const SkImage* fClipMask = nullptr; - /** fClipMatrix transforms fClipMask before it clips SkCanvas::_anonymous. If + /** fClipMatrix transforms fClipMask before it clips layer. If fClipMask describes a translucent gradient, it may be scaled and rotated without introducing artifacts. fClipMatrix may be nullptr. */ const SkMatrix* fClipMatrix = nullptr; - /** fSaveLayerFlags are used to create SkCanvas::_anonymous without transparency, - create SkCanvas::_anonymous for LCD text, and to create SkCanvas::_anonymous with the - contents of the previous SkCanvas::_anonymous. + /** fSaveLayerFlags are used to create layer without transparency, + create layer for LCD text, and to create layer with the + contents of the previous layer. */ SaveLayerFlags fSaveLayerFlags = 0; @@ -609,17 +735,17 @@ public: and allocates SkBitmap for subsequent drawing. Calling restore() discards changes to SkMatrix, clip, and SkDrawFilter, - and blends SkBitmap with color alpha opacity onto the prior SkCanvas::_anonymous. + and blends SkBitmap with color alpha opacity onto the prior layer. SkMatrix may be changed by translate(), scale(), rotate(), skew(), concat(), setMatrix(), and resetMatrix(). Clip may be changed by clipRect(), clipRRect(), clipPath(), clipRegion(). - SaveLayerRec contains the state used to create the SkCanvas::_anonymous. + SaveLayerRec contains the state used to create the layer. Call restoreToCount() with returned value to restore this and subsequent saves. - @param layerRec SkCanvas::_anonymous state + @param layerRec layer state @return depth of save state stack */ int saveLayer(const SaveLayerRec& layerRec); @@ -687,15 +813,19 @@ public: */ void rotate(SkScalar degrees); - /** Rotate SkMatrix by degrees. Positive degrees rotates clockwise. + /** Rotate SkMatrix by degrees about a point at (px, py). Positive degrees rotates + clockwise. - Mathematically, replace SkMatrix with a rotation matrix + Mathematically, construct a rotation matrix. Premultiply the rotation matrix by + a translation matrix, then replace SkMatrix with the resulting matrix premultiplied with SkMatrix. - This has the effect of rotating the drawing by degrees before transforming - the result with SkMatrix. + This has the effect of rotating the drawing about a given point before + transforming the result with SkMatrix. @param degrees amount to rotate, in degrees + @param px x-coordinate of the point to rotate about + @param py y-coordinate of the point to rotate about */ void rotate(SkScalar degrees, SkScalar px, SkScalar py); @@ -938,7 +1068,7 @@ public: /** Fill clip with color color. mode determines how ARGB is combined with destination. - @param color Unpremultiplied ARGB + @param color unpremultiplied ARGB @param mode SkBlendMode used to combine source color and destination */ void drawColor(SkColor color, SkBlendMode mode = SkBlendMode::kSrcOver); @@ -946,7 +1076,7 @@ public: /** Fill clip with color color using SkBlendMode::kSrc. This has the effect of replacing all pixels contained by clip with color. - @param color Unpremultiplied ARGB + @param color unpremultiplied ARGB */ void clear(SkColor color) { this->drawColor(color, SkBlendMode::kSrc); @@ -1148,8 +1278,8 @@ public: In paint: SkPaint::Style determines if circle is stroked or filled; if stroked, SkPaint stroke width describes the line thickness. - @param cx Circle center on the x-axis - @param cy Circle center on the y-axis + @param cx circle center on the x-axis + @param cy circle center on the y-axis @param radius half the diameter of circle @param paint SkPaint stroke or fill, blend, color, and so on, used to draw */ @@ -1160,7 +1290,7 @@ public: In paint: SkPaint::Style determines if circle is stroked or filled; if stroked, SkPaint stroke width describes the line thickness. - @param center Circle center + @param center circle center @param radius half the diameter of circle @param paint SkPaint stroke or fill, blend, color, and so on, used to draw */ @@ -1443,7 +1573,7 @@ public: this->drawImageRect(image.get(), dst, paint, constraint); } - /** Draw SkImage image stretched differentially to fit into SkRect dst. + /** Draw SkImage image stretched proportionally to fit into SkRect dst. SkIRect center divides the image into nine sections: four sides, four corners, and the center. Corners are unmodified or scaled down proportionately if their sides are larger than dst; center and four sides are scaled to fit remaining space, if any. @@ -1467,7 +1597,7 @@ public: void drawImageNine(const SkImage* image, const SkIRect& center, const SkRect& dst, const SkPaint* paint = nullptr); - /** Draw SkImage image stretched differentially to fit into SkRect dst. + /** Draw SkImage image stretched proportionally to fit into SkRect dst. SkIRect center divides the image into nine sections: four sides, four corners, and the center. Corners are not scaled, or scaled down proportionately if their sides are larger than dst; center and four sides are scaled to fit remaining space, if any. @@ -1595,7 +1725,7 @@ public: void drawBitmapRect(const SkBitmap& bitmap, const SkRect& dst, const SkPaint* paint, SrcRectConstraint constraint = kStrict_SrcRectConstraint); - /** Draw SkBitmap bitmap stretched differentially to fit into SkRect dst. + /** Draw SkBitmap bitmap stretched proportionally to fit into SkRect dst. SkIRect center divides the bitmap into nine sections: four sides, four corners, and the center. Corners are not scaled, or scaled down proportionately if their sides are larger than dst; center and four sides are scaled to fit remaining @@ -1622,6 +1752,13 @@ public: const SkPaint* paint = nullptr); /** \struct SkCanvas::Lattice + 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 + entries are proportionately scaled down to fit. + The grid entries not on even columns and rows are scaled to fit the + remaining space, if any. */ struct Lattice { @@ -1651,6 +1788,7 @@ public: /** Optional array of flags, one per rectangular grid entry: array length must be (fXCount + 1) * (fYCount + 1). + Array entries correspond to the rectangular grid entries, ascending left to right and then top to bottom. */ @@ -1673,7 +1811,7 @@ public: }; - /** Draw SkBitmap bitmap stretched differentially to fit into SkRect dst. + /** Draw SkBitmap bitmap stretched proportionally to fit into SkRect dst. Lattice lattice divides bitmap into a rectangular grid. Each intersection of an even-numbered row and column is fixed; like the corners @@ -1701,7 +1839,7 @@ public: void drawBitmapLattice(const SkBitmap& bitmap, const Lattice& lattice, const SkRect& dst, const SkPaint* paint = nullptr); - /** Draw SkImage image stretched differentially to fit into SkRect dst. + /** Draw SkImage image stretched proportionally to fit into SkRect dst. Lattice lattice divides image into a rectangular grid. Each intersection of an even-numbered row and column is fixed; like the corners @@ -1941,7 +2079,7 @@ public: Elements of paint: SkPathEffect, SkRasterizer, SkMaskFilter, SkShader, SkColorFilter, SkImageFilter, and SkDrawLooper; apply to blob. - @param blob Glyphs, positions, and their paints' text size, typeface, and so on + @param blob glyphs, positions, and their paints' text size, typeface, and so on @param x horizontal offset applied to blob @param y vertical offset applied to blob @param paint blend, color, stroking, and so on, used to draw @@ -1959,7 +2097,7 @@ public: Elements of paint: SkPathEffect, SkRasterizer, SkMaskFilter, SkShader, SkColorFilter, SkImageFilter, and SkDrawLooper; apply to blob. - @param blob Glyphs, positions, and their paints' text size, typeface, and so on + @param blob glyphs, positions, and their paints' text size, typeface, and so on @param x horizontal offset applied to blob @param y vertical offset applied to blob @param paint blend, color, stroking, and so on, used to draw @@ -2059,7 +2197,7 @@ public: corners in top left, top right, bottom right, bottom left order. @param cubics SkPath cubic array, sharing common points - @param colors Color array, one for each corner + @param colors color array, one for each corner @param texCoords SkPoint array of texture coordinates, mapping SkShader to corners; may be nullptr @param mode SkBlendMode for colors, and for SkShader if paint has one @@ -2087,7 +2225,7 @@ public: corners in top left, top right, bottom right, bottom left order. @param cubics SkPath cubic array, sharing common points - @param colors Color array, one for each corner + @param colors color array, one for each corner @param texCoords SkPoint array of texture coordinates, mapping SkShader to corners; may be nullptr @param paint SkShader, SkColorFilter, SkBlendMode, used to draw @@ -2110,11 +2248,11 @@ public: @param atlas SkImage containing sprites @param xform SkRSXform mappings for sprites in atlas @param tex SkRect locations of sprites in atlas - @param colors Color, one per sprite, blended with sprite using SkBlendMode; may be nullptr + @param colors one per sprite, blended with sprite using SkBlendMode; may be nullptr @param count number of sprites to draw @param mode SkBlendMode combining colors and sprites - @param cullRect SkRect bounds of transformed sprites for efficient clipping; may be nullptr - @param paint SkPaint SkColorFilter, SkImageFilter, SkBlendMode, and so on; may be nullptr + @param cullRect bounds of transformed sprites for efficient clipping; may be nullptr + @param paint SkColorFilter, SkImageFilter, SkBlendMode, and so on; may be nullptr */ void drawAtlas(const SkImage* atlas, const SkRSXform xform[], const SkRect tex[], const SkColor colors[], int count, SkBlendMode mode, const SkRect* cullRect, @@ -2133,11 +2271,11 @@ public: @param atlas SkImage containing sprites @param xform SkRSXform mappings for sprites in atlas @param tex SkRect locations of sprites in atlas - @param colors Color, one per sprite, blended with sprite using SkBlendMode; may be nullptr + @param colors one per sprite, blended with sprite using SkBlendMode; may be nullptr @param count number of sprites to draw @param mode SkBlendMode combining colors and sprites - @param cullRect SkRect bounds of transformed sprites for efficient clipping; may be nullptr - @param paint SkPaint SkColorFilter, SkImageFilter, SkBlendMode, and so on; may be nullptr + @param cullRect bounds of transformed sprites for efficient clipping; may be nullptr + @param paint SkColorFilter, SkImageFilter, SkBlendMode, and so on; may be nullptr */ void drawAtlas(const sk_sp<SkImage>& atlas, const SkRSXform xform[], const SkRect tex[], const SkColor colors[], int count, SkBlendMode mode, const SkRect* cullRect, @@ -2158,8 +2296,8 @@ public: @param xform SkRSXform mappings for sprites in atlas @param tex SkRect locations of sprites in atlas @param count number of sprites to draw - @param cullRect SkRect bounds of transformed sprites for efficient clipping; may be nullptr - @param paint SkPaint SkColorFilter, SkImageFilter, SkBlendMode, and so on; may be nullptr + @param cullRect bounds of transformed sprites for efficient clipping; may be nullptr + @param paint SkColorFilter, SkImageFilter, SkBlendMode, and so on; may be nullptr */ void drawAtlas(const SkImage* atlas, const SkRSXform xform[], const SkRect tex[], int count, const SkRect* cullRect, const SkPaint* paint) { @@ -2179,8 +2317,8 @@ public: @param xform SkRSXform mappings for sprites in atlas @param tex SkRect locations of sprites in atlas @param count number of sprites to draw - @param cullRect SkRect bounds of transformed sprites for efficient clipping; may be nullptr - @param paint SkPaint SkColorFilter, SkImageFilter, SkBlendMode, and so on; may be nullptr + @param cullRect bounds of transformed sprites for efficient clipping; may be nullptr + @param paint SkColorFilter, SkImageFilter, SkBlendMode, and so on; may be nullptr */ void drawAtlas(const sk_sp<SkImage>& atlas, const SkRSXform xform[], const SkRect tex[], int count, const SkRect* cullRect, const SkPaint* paint) { diff --git a/include/core/SkPaint.h b/include/core/SkPaint.h index 98e3cb2b39..39e4f65ab2 100644 --- a/include/core/SkPaint.h +++ b/include/core/SkPaint.h @@ -87,7 +87,7 @@ public: */ SkPaint(const SkPaint& paint); - /** Implements a move constructor to avoid incrementing the reference counts + /** Implements a move constructor to avoid increasing the reference counts of objects referenced by the paint. After the call, paint is undefined, and can be safely destructed. @@ -115,7 +115,7 @@ public: */ SkPaint& operator=(const SkPaint& paint); - /** Moves the paint to avoid incrementing the reference counts + /** Moves the paint to avoid increasing the reference counts of objects referenced by the paint parameter. Objects containing SkRefCnt in the prior destination are decreased by one; those objects are deleted if the resulting count is zero. @@ -567,20 +567,20 @@ public: Use helpers SkColorGetA(), SkColorGetR(), SkColorGetG(), and SkColorGetB() to extract a color component. - @return Unpremultiplied ARGB + @return unpremultiplied ARGB */ SkColor getColor() const { return fColor; } /** Sets alpha and RGB used when stroking and filling. The color is a 32-bit value, unpremultiplied, packing 8-bit components for alpha, red, blue, and green. - @param color Unpremultiplied ARGB + @param color unpremultiplied ARGB */ void setColor(SkColor color); /** Retrieves alpha from the color used when stroking and filling. - @return Alpha ranging from zero, fully transparent, to 255, fully opaque + @return alpha ranging from zero, fully transparent, to 255, fully opaque */ uint8_t getAlpha() const { return SkToU8(SkColorGetA(fColor)); } @@ -590,7 +590,7 @@ public: a set to zero makes color fully transparent; a set to 255 makes color fully opaque. - @param a Alpha component of color + @param a alpha component of color */ void setAlpha(U8CPU a); @@ -760,8 +760,8 @@ public: /** Optional colors used when filling a path, such as a gradient. - Sets SkShader to shader, decrementing SkRefCnt of the previous SkShader. - Does not alter shader SkRefCnt. + Sets SkShader to shader, decreasing SkRefCnt of the previous SkShader. + Increments shader SkRefCnt by one. @param shader how geometry is filled with color; if nullptr, color is used instead */ @@ -781,9 +781,10 @@ public: */ sk_sp<SkColorFilter> refColorFilter() const; - /** Sets SkColorFilter to filter, decrementing SkRefCnt of the previous SkColorFilter. - Pass nullptr to clear SkColorFilter. - Does not alter filter SkRefCnt. + /** Sets SkColorFilter to filter, decreasing SkRefCnt of the previous + SkColorFilter. Pass nullptr to clear SkColorFilter. + + Increments filter SkRefCnt by one. @param colorFilter SkColorFilter to apply to subsequent draw */ @@ -823,10 +824,10 @@ public: */ sk_sp<SkPathEffect> refPathEffect() const; - /** Sets SkPathEffect to pathEffect, - decrementing SkRefCnt of the previous SkPathEffect. - Pass nullptr to leave the path geometry unaltered. - Does not alter pathEffect SkRefCnt. + /** Sets SkPathEffect to pathEffect, decreasing SkRefCnt of the previous + SkPathEffect. Pass nullptr to leave the path geometry unaltered. + + Increments pathEffect SkRefCnt by one. @param pathEffect replace SkPath with a modification when drawn */ @@ -840,24 +841,26 @@ public: SkMaskFilter* getMaskFilter() const { return fMaskFilter.get(); } /** Returns SkMaskFilter if set, or nullptr. + Increases SkMaskFilter SkRefCnt by one. @return SkMaskFilter if previously set, nullptr otherwise */ sk_sp<SkMaskFilter> refMaskFilter() const; - /** Sets SkMaskFilter to maskFilter, - decrementing SkRefCnt of the previous SkMaskFilter. - Pass nullptr to clear SkMaskFilter and leave SkMaskFilter effect on mask alpha unaltered. + /** Sets SkMaskFilter to maskFilter, decreasing SkRefCnt of the previous + SkMaskFilter. Pass nullptr to clear SkMaskFilter and leave SkMaskFilter effect on + mask alpha unaltered. + Does not affect SkRasterizer. - Does not alter maskFilter SkRefCnt. + Increments maskFilter SkRefCnt by one. @param maskFilter modifies clipping mask generated from drawn geometry */ void setMaskFilter(sk_sp<SkMaskFilter> maskFilter); /** Returns SkTypeface if set, or nullptr. - Does not alter SkTypeface SkRefCnt. + Increments SkTypeface SkRefCnt by one. @return SkTypeface if previously set, nullptr otherwise */ @@ -869,10 +872,9 @@ public: */ sk_sp<SkTypeface> refTypeface() const; - /** Sets SkTypeface to typeface, - decrementing SkRefCnt of the previous SkTypeface. - Pass nullptr to clear SkTypeface and use the default typeface. - Does not alter typeface SkRefCnt. + /** Sets SkTypeface to typeface, decreasing SkRefCnt of the previous SkTypeface. + Pass nullptr to clear SkTypeface and use the default typeface. Increments + typeface SkRefCnt by one. @param typeface font and style used to draw text */ @@ -892,11 +894,12 @@ public: */ sk_sp<SkRasterizer> refRasterizer() const; - /** Sets SkRasterizer to rasterizer, - decrementing SkRefCnt of the previous SkRasterizer. - Pass nullptr to clear SkRasterizer and leave SkRasterizer effect on mask alpha unaltered. + /** Sets SkRasterizer to rasterizer, decreasing SkRefCnt of the previous + SkRasterizer. Pass nullptr to clear SkRasterizer and leave SkRasterizer effect on + mask alpha unaltered. + Does not affect SkMaskFilter. - Does not alter rasterizer SkRefCnt. + Increments rasterizer SkRefCnt by one. @param rasterizer how geometry is converted to mask alpha */ @@ -916,12 +919,12 @@ public: */ sk_sp<SkImageFilter> refImageFilter() const; - /** Sets SkImageFilter to imageFilter, - decrementing SkRefCnt of the previous SkImageFilter. - Pass nullptr to clear SkImageFilter, and remove SkImageFilter effect + /** Sets SkImageFilter to imageFilter, decreasing SkRefCnt of the previous + SkImageFilter. Pass nullptr to clear SkImageFilter, and remove SkImageFilter effect on drawing. + Does not affect SkRasterizer or SkMaskFilter. - Does not alter imageFilter SkRefCnt. + Increments imageFilter SkRefCnt by one. @param imageFilter how SkImage is sampled when transformed */ @@ -948,10 +951,11 @@ public: */ SkDrawLooper* getLooper() const { return fDrawLooper.get(); } - /** Sets SkDrawLooper to drawLooper, - decrementing SkRefCnt of the previous drawLooper. - Pass nullptr to clear SkDrawLooper and leave SkDrawLooper effect on drawing unaltered. - Does not alter drawLooper SkRefCnt. + /** Sets SkDrawLooper to drawLooper, decreasing SkRefCnt of the previous + drawLooper. Pass nullptr to clear SkDrawLooper and leave SkDrawLooper effect on + drawing unaltered. + + Increments drawLooper SkRefCnt by one. @param drawLooper iterates through drawing one or more time, altering SkPaint */ @@ -1057,14 +1061,12 @@ public: void setTextSkewX(SkScalar skewX); /** \enum SkPaint::TextEncoding - TextEncoding determines whether text specifies character codes and their encoded size, - or glyph indices. Character codes use the encoding specified by the Unicode standard . + TextEncoding determines whether text specifies character codes and their encoded + size, or glyph indices. Character codes use the encoding specified by the Unicode standard. + Character codes encoded size are specified by UTF-8, UTF-16, or UTF-32. - All character encoding are able to represent all of Unicode, differing only - in the total storage required. UTF-8 (RFC 3629) is made up of 8-bit bytes, - and is a superset of ASCII. UTF-16 (RFC 2781) is made up of 16-bit words, - and is a superset of Unicode ranges 0x0000 to 0xD7FF and 0xE000 to 0xFFFF. UTF-32 is - made up of 32-bit words, and is a superset of Unicode. + All character encodings are able to represent all of Unicode, differing only + in the total storage required. UTF-8 (RFC 3629) encodes each character as one or more 8-bit bytes. UTF-16 (RFC 2781) encodes each character as one or two 16-bit words. UTF-32 encodes each character as one 32-bit word. font manager uses font data to convert character code points into glyph indices. A glyph index is a 16-bit word. @@ -1110,11 +1112,6 @@ public: */ struct FontMetrics { - /** \enum SkPaint::FontMetrics::FontMetricsFlags - FontMetricsFlags are set in fFlags when underline and strikeout metrics are valid; - the underline or strikeout metric may be valid and zero. - Fonts with embedded bitmaps may not have valid underline or strikeout metrics. - */ enum FontMetricsFlags { kUnderlineThicknessIsValid_Flag = 1 << 0, //!< Set if fUnderlineThickness is valid. kUnderlinePositionIsValid_Flag = 1 << 1, //!< Set if fUnderlinePosition is valid. @@ -1540,7 +1537,7 @@ public: intervals are cached to improve performance for multiple calls. - @param blob Glyphs, positions, and text paint attributes + @param blob glyphs, positions, and text paint attributes @param bounds lower and upper line parallel to the advance @param intervals returned intersections; may be nullptr @return number of intersections; may be zero diff --git a/include/core/SkPath.h b/include/core/SkPath.h index dd77ef425f..7f52f07740 100644 --- a/include/core/SkPath.h +++ b/include/core/SkPath.h @@ -17,6 +17,22 @@ class SkRRect; class SkWStream; /** \class SkPath + SkPath contain geometry. SkPath may be empty, or contain one or more SkPath::Verb 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. + 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 + closed. + + When used to draw a filled area, SkPath describes whether the fill is inside or + outside the geometry. SkPath also describes the winding rule used to fill + overlapping contours. + + Internally, SkPath lazily computes metrics likes bounds and convexity. Call + SkPath::updateBoundsCache to make SkPath thread safe. */ class SK_API SkPath { public: @@ -112,6 +128,15 @@ enum Direction { Copy verb array and weights to out, and set out SkPoint arrays to a weighted average of this SkPoint arrays and ending SkPoint arrays, using the formula: + (this->points * weight) + ending->points * (1 - weight) + + weight is most useful when between zero (ending SkPoint arrays) and + one (this Point_Array); will work with values outside of this + range. + + interpolate() returns false and leaves out unchanged if SkPoint arrays is not + the same size as ending SkPoint arrays. Call isInterpolatable() to check SkPath + compatibility prior to calling interpolate(). @param ending SkPoint arrays averaged with this SkPoint arrays @param weight contribution of ending SkPoint arrays, and @@ -406,9 +431,9 @@ enum Direction { Quad with no length or that moves a very short distance is degenerate; it is treated as a point. - @param p1 Quad start point - @param p2 Quad control point - @param p3 Quad end point + @param p1 quad start point + @param p2 quad control point + @param p3 quad end point @param exact if true, returns true only if p1, p2, and p3 are equal; if false, returns true if p1, p2, and p3 are equal or nearly equal @return true if quad is degenerate; its length is effectively zero @@ -423,10 +448,10 @@ enum Direction { Cubic with no length or that moves a very short distance is degenerate; it is treated as a point. - @param p1 Cubic start point - @param p2 Cubic control point 1 - @param p3 Cubic control point 2 - @param p4 Cubic end point + @param p1 cubic start point + @param p2 cubic control point 1 + @param p3 cubic control point 2 + @param p4 cubic end point @param exact if true, returns true only if p1, p2, p3, and p4 are equal; if false, returns true if p1, p2, p3, and p4 are equal or nearly equal @return true if cubic is degenerate; its length is effectively zero @@ -918,6 +943,19 @@ enum Direction { /** Append arc to SkPath, relative to last SkPath SkPoint. Arc is implemented by one or more conic, weighted to describe part of oval with radii (rx, ry) rotated by xAxisRotate degrees. Arc curves from last SkPath SkPoint (x0, y0) to end SkPoint + (x0 + dx, y0 + dy), choosing one of four possible routes: clockwise or + counterclockwise, and smaller or larger. If SkPath is empty, the start arc SkPoint + is (0, 0). + + Arc sweep is always less than 360 degrees. arcTo() appends line to end SkPoint + if either radii are zero, or if last SkPath SkPoint equals end SkPoint. + arcTo() scales radii (rx, ry) to fit last SkPath SkPoint and end SkPoint if both are + greater than zero but too small to describe an arc. + + arcTo() appends up to four conic curves. + arcTo() implements the functionality of svg arc, although SVG "sweep-flag" value is + opposite the integer value of sweep; SVG "sweep-flag" uses 1 for clockwise, while + kCW_Direction cast to int is zero. @param rx radius in x before x-axis rotation @param ry radius in y before x-axis rotation @@ -976,13 +1014,24 @@ enum Direction { Maximum quad count is 2 to the pow2. Every third point in array shares last SkPoint of previous quad and first SkPoint of next quad. Maximum pts storage size is given by: + (1 + 2 * (1 << pow2)) * sizeof(SkPoint) + + ConvertConicToQuads returns quad count used the approximation, which may be smaller + than the number requested. - @param p0 Conic start SkPoint - @param p1 Conic control SkPoint - @param p2 Conic end SkPoint - @param w Conic weight + conic weight determines the amount of influence conic control point has on the curve. + w less than one represents an elliptical section. w greater than one represents + a hyperbolic section. w equal to one represents a parabolic section. + + Two quad curves are sufficient to approximate an elliptical conic with a sweep + of up to 90 degrees; in this case, set pow2 to one. + + @param p0 conic start SkPoint + @param p1 conic control SkPoint + @param p2 conic end SkPoint + @param w conic weight @param pts storage for quad array - @param pow2 Quad count, as power of two, normally 0 to 5 (1 to 32 quad curves) + @param pow2 quad count, as power of two, normally 0 to 5 (1 to 32 quad curves) @return number of quad curves written to pts */ static int ConvertConicToQuads(const SkPoint& p0, const SkPoint& p1, const SkPoint& p2, @@ -1076,6 +1125,10 @@ enum Direction { /** Add circle centered at (x, y) of size radius to SkPath, appending kMove_Verb, four kConic_Verb, and kClose_Verb. Circle begins at + (x + radius, y), continuing clockwise if dir is kCW_Direction, and counterclockwise if dir is + kCCW_Direction. + + Has no effect if radius is zero or negative. @param x center of circle @param y center of circle @@ -1153,7 +1206,13 @@ enum Direction { */ void addRRect(const SkRRect& rrect, Direction dir, unsigned start); - /** Add contour created from line array, adding + /** Add contour created from line array, adding (count - 1) line segments. + Contour added starts at pts[0], then adds a line for every additional SkPoint + in pts array. If close is true,appends kClose_Verb to SkPath, connecting + pts[count - 1] and pts[0]. + + If count is zero, append kMove_Verb to path. + Has no effect if count is less than one. @param pts array of line sharing end and start SkPoint @param count length of SkPoint array @@ -1235,12 +1294,10 @@ enum Direction { */ void offset(SkScalar dx, SkScalar dy, SkPath* dst) const; - /** Offset SkPoint arrays by (dx, dy). Offset SkPath replaces dst. - If dst is nullptr, SkPath is replaced by offset data. + /** Offset SkPoint arrays by (dx, dy). SkPath is replaced by offset data. - @param dx offset added to SkPoint arrays x coordinates - @param dy offset added to SkPoint arrays y coordinates - @param dst overwritten, translated copy of SkPath; may be nullptr + @param dx offset added to SkPoint arrays x coordinates + @param dy offset added to SkPoint arrays y coordinates */ void offset(SkScalar dx, SkScalar dy) { this->offset(dx, dy, this); @@ -1258,11 +1315,9 @@ enum Direction { /** Transform verb array, SkPoint arrays, and weight by matrix. transform may change SkPath::Verb and increase their number. - Transformed SkPath replaces dst; if dst is nullptr, original data - is replaced. + SkPath is replaced by transformed data. @param matrix SkMatrix to apply to SkPath - @param dst overwritten, transformed copy of SkPath; may be nullptr */ void transform(const SkMatrix& matrix) { this->transform(matrix, this); @@ -1352,6 +1407,9 @@ enum Direction { }; /** \class SkPath::Iter + Iterates through verb array, and associated SkPoint arrays and conic weight. + Provides options to treat open contours as closed, and to ignore + degenerate data. */ class SK_API Iter { @@ -1360,7 +1418,7 @@ enum Direction { /** Initializes iter with an empty SkPath. next() on iter returns kDone_Verb. Call setPath to initialize iter at a later time. - @return Iter of empty SkPath + @return iter of empty SkPath */ Iter(); @@ -1370,7 +1428,7 @@ enum Direction { @param path SkPath to iterate @param forceClose true if open contours generate kClose_Verb - @return Iter of path + @return iter of path */ Iter(const SkPath& path, bool forceClose); @@ -1454,6 +1512,8 @@ enum Direction { }; /** \class SkPath::RawIter + Iterates through verb array, and associated SkPoint arrays and conic weight. + verb array, SkPoint arrays, and conic weight are returned unaltered. */ class SK_API RawIter { @@ -1539,14 +1599,10 @@ enum Direction { */ void dump(SkWStream* stream, bool forceClose, bool dumpAsHex) const; - /** Writes text representation of SkPath to stream. If stream is nullptr, dump() writes to - standard output. Set forceClose to true to get - edges used to fill SkPath. Set dumpAsHex true to get exact binary representations - of floating point numbers used in SkPoint arrays and conic weights. - - @param stream writable SkFlattenable receiving SkPath text representation; may be nullptr - @param forceClose true if missing kClose_Verb is output - @param dumpAsHex true if SkScalar values are written as hexadecimal + /** Writes text representation of SkPath to standard output. The representation may be + directly compiled as C++ code. Floating point values are written + with limited precision; it may not be possible to reconstruct original SkPath + from output. */ void dump() const; @@ -1617,7 +1673,7 @@ enum Direction { array dimensions. @return true if SkPath data is consistent - */ + */ bool isValid() const { return this->isValidImpl() && fPathRef->isValid(); } #else bool isValid() const { return this->isValidImpl(); } diff --git a/include/core/SkPixmap.h b/include/core/SkPixmap.h index 3688298ac1..aa43b3441f 100644 --- a/include/core/SkPixmap.h +++ b/include/core/SkPixmap.h @@ -15,193 +15,721 @@ class SkData; struct SkMask; -/** - * Pairs SkImageInfo with actual pixels and rowbytes. This class does not try to manage the - * lifetime of the pixel memory (nor the colortable if provided). - */ +/** \class SkPixmap + SkPixmap provides a utility to pair SkImageInfo with pixels and row bytes. + SkPixmap is a low level class which provides convenience functions to access + raster destinations. SkCanvas can not draw SkPixmap, nor does SkPixmap provide + a direct drawing destination. + + Use SkBitmap to draw pixels referenced by SkPixmap; use SkSurface to draw into + pixels referenced by SkPixmap. + + SkPixmap does not try to manage the lifetime of the pixel memory. Use PixelRef + to manage pixel memory; PixelRef is safe across threads. +*/ class SK_API SkPixmap { public: + + /** Creates an empty SkPixmap without pixels, with kUnknown_SkColorType, with + kUnknown_SkAlphaType, and with a width and height of zero. Use + reset() to associate pixels, SkColorType, SkAlphaType, width, and height + after SkPixmap has been created. + + @return empty SkPixmap + */ SkPixmap() : fPixels(nullptr), fRowBytes(0), fInfo(SkImageInfo::MakeUnknown(0, 0)) {} + /** Creates SkPixmap from info width, height, SkAlphaType, and SkColorType. + addr points to pixels, or nullptr. rowBytes should be info.width() times + info.bytesPerPixel(), or larger. + + No parameter checking is performed; it is up to the caller to ensure that + addr and rowBytes agree with info. + + The memory lifetime of pixels is managed by the caller. When SkPixmap goes + out of scope, addr is unaffected. + + SkPixmap may be later modified by reset() to change its size, pixel type, or + storage. + + @param info width, height, SkAlphaType, SkColorType of SkImageInfo + @param addr pointer to pixels allocated by caller; may be nullptr + @param rowBytes size of one row of addr; width times pixel size, or larger + @return initialized SkPixmap + */ SkPixmap(const SkImageInfo& info, const void* addr, size_t rowBytes) : fPixels(addr), fRowBytes(rowBytes), fInfo(info) {} + /** Sets width, height, row bytes to zero; pixel address to nullptr; SkColorType to + kUnknown_SkColorType; and SkAlphaType to kUnknown_SkAlphaType. + + The prior pixels are unaffected; it is up to the caller to release pixels + memory if desired. + */ void reset(); + + /** Sets width, height, SkAlphaType, and SkColorType from info. + Sets pixel address from addr, which may be nullptr. + Sets row bytes from rowBytes, which should be info.width() times + info.bytesPerPixel(), or larger. + + Does not check addr. Asserts if built with SK_DEBUG defined and if rowBytes is + too small to hold one row of pixels. + + The memory lifetime pixels are managed by the caller. When SkPixmap goes + out of scope, addr is unaffected. + + @param info width, height, SkAlphaType, SkColorType of SkImageInfo + @param addr pointer to pixels allocated by caller; may be nullptr + @param rowBytes size of one row of addr; width times pixel size, or larger + */ void reset(const SkImageInfo& info, const void* addr, size_t rowBytes); - // overrides the colorspace in the SkImageInfo of the pixmap + /** Changes SkColorSpace in SkImageInfo; preserves width, height, SkAlphaType, and + SkColorType in SkImage, and leaves pixel address and row bytes unchanged. + SkColorSpace reference count is incremented. + + @param colorSpace SkColorSpace moved to SkImageInfo + */ void setColorSpace(sk_sp<SkColorSpace> colorSpace); - /** - * If supported, set this pixmap to point to the pixels in the specified mask and return true. - * On failure, return false and set this pixmap to empty. - */ + /** 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 + */ bool SK_WARN_UNUSED_RESULT reset(const SkMask& mask); - /** - * Computes the intersection of area and this pixmap. If that intersection is non-empty, - * set subset to that intersection and return true. - * - * On failure, return false and ignore the subset parameter. - */ + /** Sets subset width, height, pixel address to intersection of SkPixmap with area, + if intersection is not empty; and return true. Otherwise, leave subset unchanged + and return false. + + Failing to read the return value generates a compile time warning. + + @param subset storage for width, height, pixel address of intersection + @param area bounds to intersect with SkPixmap + @return true if intersection of SkPixmap and area is not empty + */ bool SK_WARN_UNUSED_RESULT extractSubset(SkPixmap* subset, const SkIRect& area) const; + /** Returns width, height, SkAlphaType, SkColorType, and SkColorSpace. + + @return reference to ImageInfo + */ const SkImageInfo& info() const { return fInfo; } + + /** Returns row bytes, the interval from one pixel row to the next. Row bytes + is at least as large as + width() * info().bytesPerPixel(). + + It is up to the SkPixmap creator to ensure that row bytes is a useful value. + + @return byte length of pixel row + */ size_t rowBytes() const { return fRowBytes; } + + /** Returns pixel address, the base address corresponding to the pixel origin. + + It is up to the SkPixmap creator to ensure that pixel address is a useful value. + + @return pixel address + */ const void* addr() const { return fPixels; } + /** Returns pixel count in each pixel row. Should be equal or less than: + rowBytes() / info.bytesPerPixel(). + + @return pixel width in SkImageInfo + */ int width() const { return fInfo.width(); } + + /** Returns pixel row count. + + @return pixel height in SkImageInfo + */ int height() const { return fInfo.height(); } + + /** 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. + + @return SkColorType in SkImageInfo + */ SkColorType colorType() const { return fInfo.colorType(); } + + /** Returns SkAlphaType, one of: kUnknown_SkAlphaType, kOpaque_SkAlphaType, + kPremul_SkAlphaType, kUnpremul_SkAlphaType. + + @return SkAlphaType in SkImageInfo + */ SkAlphaType alphaType() const { return fInfo.alphaType(); } + + /** Returns SkColorSpace associated with SkImageInfo. + + @return SkColorSpace in SkImageInfo + */ SkColorSpace* colorSpace() const { return fInfo.colorSpace(); } + + /** Returns true if SkAlphaType is kOpaque_SkAlphaType. + Does not check if SkColorType allows alpha, or alpha in pixel values. + + @return true if SkImageInfo has opaque SkAlphaType + */ bool isOpaque() const { return fInfo.isOpaque(); } + /** Returns SkIRect + { 0, 0, width(), height() }. + + @return integral rectangle from origin to width() and height() + */ SkIRect bounds() const { return SkIRect::MakeWH(this->width(), this->height()); } - /** - * Return the rowbytes expressed as a number of pixels (like width and height). - */ + /** Returns number of pixels that fit on row. Should be greater than or equal to + width(). + + @return maximum pixels per row + */ int rowBytesAsPixels() const { return int(fRowBytes >> this->shiftPerPixel()); } - /** - * Return the shift amount per pixel (i.e. 0 for 1-byte per pixel, 1 for 2-bytes per pixel - * colortypes, 2 for 4-bytes per pixel colortypes). Return 0 for kUnknown_SkColorType. - */ + /** Returns bit shift converting row bytes to row pixels. + Returns zero for kUnknown_SkColorType. + + @return one of: 0, 1, 2, 3; left shift to convert pixels to bytes + */ int shiftPerPixel() const { return fInfo.shiftPerPixel(); } + /** Returns conservative memory required for pixel storage. + Includes unused memory on last row when rowBytesAsPixels() exceeds width(). + + @return conservative pixel storage size + */ uint64_t getSize64() const { return sk_64_mul(fInfo.height(), fRowBytes); } + + /** Returns minimum memory required for pixel storage. + Does not include unused memory on last row when rowBytesAsPixels() exceeds width(). + + @return exact pixel storage size + */ uint64_t getSafeSize64() const { return fInfo.getSafeSize64(fRowBytes); } + + /** Returns minimum memory required for pixel storage. + Does not include unused memory on last row when rowBytesAsPixels() exceeds width(). + Returns zero if value is does not fit in a signed 32-bit integer. + The largest value than can be returned is 2,147,483,647. + + @return exact pixel storage size if size fits in signed 32 bits + */ size_t getSafeSize() const { return fInfo.getSafeSize(fRowBytes); } - /** - * This will brute-force return true if all of the pixels in the pixmap - * are opaque. If there are no pixels, or encounters an error, returns false. - */ + /** 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 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 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 all pixels have opaque values or SkColorType is opaque + */ bool computeIsOpaque() const; - /** - * Converts the pixel at the specified coordinate to an unpremultiplied - * SkColor. Note: this ignores any SkColorSpace information, and may return - * lower precision data than is actually in the pixel. Alpha only - * colortypes (e.g. kAlpha_8_SkColorType) return black with the appropriate - * alpha set. The value is undefined for kUnknown_SkColorType or if x or y - * are out of bounds, or if the pixtap does not have any pixels. - */ + /** Returns pixel at (x, y) as unpremultiplied color. + 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 SkColorType is kUnknown_SkColorType or + pixel address is nullptr. + + SkColorSpace in SkImageInfo is ignored. Some color precision may be lost in the + conversion to unpremultiplied color; original pixel data may have additional + precision. + + @param x column index, zero or greater, and less than width() + @param y row index, zero or greater, and less than height() + @return pixel converted to unpremultiplied color + */ SkColor getColor(int x, int y) const; + /** Returns readable 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 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() + @return readable generic pointer to pixel + */ const void* addr(int x, int y) const { return (const char*)fPixels + fInfo.computeOffset(x, y, fRowBytes); } + + /** Returns readable base pixel address. Result is addressable as unsigned 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. + + @return readable unsigned 8-bit pointer to pixels + */ const uint8_t* addr8() const { SkASSERT(1 == SkColorTypeBytesPerPixel(fInfo.colorType())); return reinterpret_cast<const uint8_t*>(fPixels); } + + /** Returns readable base pixel address. Result is addressable as unsigned 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. + + @return readable unsigned 16-bit pointer to pixels + */ const uint16_t* addr16() const { SkASSERT(2 == SkColorTypeBytesPerPixel(fInfo.colorType())); return reinterpret_cast<const uint16_t*>(fPixels); } + + /** Returns readable base pixel address. Result is addressable as unsigned 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. + + One word corresponds to one pixel. + + @return readable unsigned 32-bit pointer to pixels + */ const uint32_t* addr32() const { SkASSERT(4 == SkColorTypeBytesPerPixel(fInfo.colorType())); return reinterpret_cast<const uint32_t*>(fPixels); } + + /** Returns readable base pixel address. Result is addressable as unsigned 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. + + @return readable unsigned 64-bit pointer to pixels + */ const uint64_t* addr64() const { SkASSERT(8 == SkColorTypeBytesPerPixel(fInfo.colorType())); return reinterpret_cast<const uint64_t*>(fPixels); } + + /** Returns readable base pixel address. Result is addressable as unsigned 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. + Four words correspond to one pixel. + + @return readable unsigned 16-bit pointer to first component of pixels + */ const uint16_t* addrF16() const { SkASSERT(8 == SkColorTypeBytesPerPixel(fInfo.colorType())); SkASSERT(kRGBA_F16_SkColorType == fInfo.colorType()); return reinterpret_cast<const uint16_t*>(fPixels); } - // Offset by the specified x,y coordinates + /** Returns readable 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. + + 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() + @param y row index, zero or greater, and less than height() + @return readable unsigned 8-bit pointer to pixel at (x, y) + */ const uint8_t* addr8(int x, int y) const { SkASSERT((unsigned)x < (unsigned)fInfo.width()); SkASSERT((unsigned)y < (unsigned)fInfo.height()); return (const uint8_t*)((const char*)this->addr8() + y * fRowBytes + (x << 0)); } + + /** Returns readable 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. + + 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() + @param y row index, zero or greater, and less than height() + @return readable unsigned 16-bit pointer to pixel at (x, y) + */ const uint16_t* addr16(int x, int y) const { SkASSERT((unsigned)x < (unsigned)fInfo.width()); SkASSERT((unsigned)y < (unsigned)fInfo.height()); return (const uint16_t*)((const char*)this->addr16() + y * fRowBytes + (x << 1)); } + + /** Returns readable 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. + + 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() + @param y row index, zero or greater, and less than height() + @return readable unsigned 32-bit pointer to pixel at (x, y) + */ const uint32_t* addr32(int x, int y) const { SkASSERT((unsigned)x < (unsigned)fInfo.width()); SkASSERT((unsigned)y < (unsigned)fInfo.height()); return (const uint32_t*)((const char*)this->addr32() + y * fRowBytes + (x << 2)); } + + /** Returns readable 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. + + 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() + @param y row index, zero or greater, and less than height() + @return readable unsigned 64-bit pointer to pixel at (x, y) + */ const uint64_t* addr64(int x, int y) const { SkASSERT((unsigned)x < (unsigned)fInfo.width()); SkASSERT((unsigned)y < (unsigned)fInfo.height()); return (const uint64_t*)((const char*)this->addr64() + y * fRowBytes + (x << 3)); } + + /** Returns readable 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. + + 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. + Four words correspond to one pixel. + + @param x column index, zero or greater, and less than width() + @param y row index, zero or greater, and less than height() + @return readable unsigned 16-bit pointer to pixel component at (x, y) + */ const uint16_t* addrF16(int x, int y) const { SkASSERT(kRGBA_F16_SkColorType == fInfo.colorType()); return reinterpret_cast<const uint16_t*>(this->addr64(x, y)); } - // Writable versions + /** Returns writable base pixel address. + @return writable generic base pointer to pixels + */ void* writable_addr() const { return const_cast<void*>(fPixels); } + + /** 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 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() + @return writable generic pointer to pixel + */ void* writable_addr(int x, int y) const { return const_cast<void*>(this->addr(x, y)); } + + /** Returns writable pixel address at (x, y). Result is addressable as unsigned + 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. + + @param x column index, zero or greater, and less than width() + @param y row index, zero or greater, and less than height() + @return writable unsigned 8-bit pointer to pixels + */ uint8_t* writable_addr8(int x, int y) const { return const_cast<uint8_t*>(this->addr8(x, y)); } + + /** Returns writable_addr pixel address at (x, y). Result is addressable as unsigned + 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. + + @param x column index, zero or greater, and less than width() + @param y row index, zero or greater, and less than height() + @return writable unsigned 16-bit pointer to pixel + */ uint16_t* writable_addr16(int x, int y) const { return const_cast<uint16_t*>(this->addr16(x, y)); } + + /** Returns writable pixel address at (x, y). Result is addressable as unsigned + 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. + + One word corresponds to one pixel. + + @param x column index, zero or greater, and less than width() + @param y row index, zero or greater, and less than height() + @return writable unsigned 32-bit pointer to pixel + */ uint32_t* writable_addr32(int x, int y) const { return const_cast<uint32_t*>(this->addr32(x, y)); } + + /** Returns writable pixel address at (x, y). Result is addressable as unsigned + 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. + + @param x column index, zero or greater, and less than width() + @param y row index, zero or greater, and less than height() + @return writable unsigned 64-bit pointer to pixel + */ uint64_t* writable_addr64(int x, int y) const { return const_cast<uint64_t*>(this->addr64(x, y)); } + + /** Returns writable pixel address at (x, y). Result is addressable as unsigned + 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. + Four words correspond to one pixel. + + @param x column index, zero or greater, and less than width() + @param y row index, zero or greater, and less than height() + @return writable unsigned 16-bit pointer to first component of pixel + */ uint16_t* writable_addrF16(int x, int y) const { return reinterpret_cast<uint16_t*>(writable_addr64(x, y)); } - // copy methods + /** Copies a SkRect of pixels to dstPixels. Copy starts at (srcX, srcY), and does not exceed + (this->width(), this->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, or dstRowBytes is less than dstInfo.minRowBytes(). + + Pixels are copied only if pixel conversion is possible. If this->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 + 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(). + + 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 their encoding. + + @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 behavior one of: SkTransferFunctionBehavior::kRespect, + SkTransferFunctionBehavior::kIgnore + @return true if pixels are copied to dstPixels + */ 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 (0, 0), and does not + exceed + (this->width(), this->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, or dstRowBytes is less than dstInfo.minRowBytes(). + + Pixels are copied only if pixel conversion is possible. If this->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 + false if pixel conversion is not possible. + + Returns false if this->width() or this->height() is zero or negative. + + @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 + */ bool readPixels(const SkImageInfo& dstInfo, void* dstPixels, size_t dstRowBytes) const { return this->readPixels(dstInfo, dstPixels, dstRowBytes, 0, 0); } + + /** Copies a SkRect of pixels to dstPixels. Copy starts at (srcX, srcY), and does not + exceed + (this->width(), this->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, or dstRowBytes is less than dstInfo.minRowBytes(). + + Pixels are copied only if pixel conversion is possible. If this->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 + 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(). + + @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() + @return true if pixels are copied to dstPixels + */ bool readPixels(const SkImageInfo& dstInfo, void* dstPixels, size_t dstRowBytes, int srcX, int srcY) const { return this->readPixels(dstInfo, dstPixels, dstRowBytes, srcX, srcY, SkTransferFunctionBehavior::kRespect); } + + /** Copies a SkRect of pixels to dst. Copy starts at (srcX, srcY), and does not + exceed (this->width(), this->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 + 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 + 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(). + + @param dst SkImageInfo and pixel address to write to + @param srcX column index whose absolute value is less than width() + @param srcY row index whose absolute value is less than height() + @return true if pixels are copied to dst + */ bool readPixels(const SkPixmap& dst, int srcX, int srcY) const { return this->readPixels(dst.info(), dst.writable_addr(), dst.rowBytes(), srcX, srcY); } + + /** 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 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 + false if pixel conversion is not possible. + + Returns false if this->width() or this->height() is zero or negative. + + @param dst SkImageInfo and pixel address to write to + @return true if pixels are copied to dst + */ bool readPixels(const SkPixmap& dst) const { return this->readPixels(dst.info(), dst.writable_addr(), dst.rowBytes(), 0, 0); } - /** - * Copy the pixels from this pixmap 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 this 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 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 + false if pixel conversion is not possible. + + Returns false if this->width() or this->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 + 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. + + @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 + */ bool scalePixels(const SkPixmap& dst, SkFilterQuality filterQuality) const; - /** - * Returns true if pixels were written to (e.g. if colorType is kUnknown_SkColorType, this - * will return false). If subset does not intersect the bounds of this pixmap, returns false. - */ + /** Writes color to pixels bounded by subset; returns true on success. + Returns false if colorType() is kUnknown_SkColorType, or if subset does + not intersect bounds(). + + @param color unpremultiplied color to write + @param subset bounding integer SkRect of written pixels + @return true if pixels are changed + */ bool erase(SkColor color, const SkIRect& subset) const; + /** Writes color to pixels inside bounds(); returns true on success. + Returns false if colorType() is kUnknown_SkColorType, or if bounds() + is empty. + + @param color unpremultiplied color to write + @return true if pixels are changed + */ bool erase(SkColor color) const { return this->erase(color, this->bounds()); } + + /** Writes color to pixels bounded by subset; returns true on success. + if subset is nullptr, writes colors pixels inside bounds(). Returns false if + colorType() is kUnknown_SkColorType, if subset is not nullptr and does + not intersect bounds(), or if subset is nullptr and bounds() is empty. + + @param color unpremultiplied color to write + @param subset bounding integer SkRect of pixels to write; may be nullptr + @return true if pixels are changed + */ bool erase(const SkColor4f& color, const SkIRect* subset = nullptr) const; private: |