diff options
| author |  Cary Clark <caryclark@skia.org> | 2018-05-30 09:20:29 -0400 |
|---|---|---|
| committer |  Skia Commit-Bot <skia-commit-bot@chromium.org> | 2018-05-30 13:51:43 +0000 |
| commit | 462505f3100f0abc52adfd4506b62719e7151e18 (patch) | |
| tree | a92d1ab71edac014cbcaf67d6572a1b8422a4ad2 /include/core | |
| parent | 6e4d95f804e7edd918791f75ad32e85ddb1c9990 (diff) | |
include refresh
Update the includes to match the bookmaker docs.
All edits are generated; if something looks amiss, I
probably introduced a bug in the generator. Please
let me know.
I was careful to pick up all direct edits to the includes
and add them to their bookmaker counterpart. Please take
a look to see if your favorites are there.
Note that enum and struct members have been shortened
to fit on one line. The intent is to provide more verbose
documentation online. Let me know if this is too terse.
TBR=reed@google.com
Bug: skia:6898
Change-Id: I374673ed884e03e142439d91532efc558deeaccd
Reviewed-on: https://skia-review.googlesource.com/130540
Commit-Queue: Cary Clark <caryclark@skia.org>
Auto-Submit: Cary Clark <caryclark@skia.org>
Reviewed-by: Cary Clark <caryclark@google.com>
Reviewed-by: Cary Clark <caryclark@skia.org>
Diffstat (limited to 'include/core')
| -rw-r--r-- | include/core/SkBitmap.h | 27 | ||||
| -rw-r--r-- | include/core/SkCanvas.h | 285 | ||||
| -rw-r--r-- | include/core/SkImage.h | 20 | ||||
| -rw-r--r-- | include/core/SkImageInfo.h | 143 | ||||
| -rw-r--r-- | include/core/SkMatrix.h | 45 | ||||
| -rw-r--r-- | include/core/SkPaint.h | 294 | ||||
| -rw-r--r-- | include/core/SkPath.h | 90 | ||||
| -rw-r--r-- | include/core/SkPoint.h | 21 | ||||
| -rw-r--r-- | include/core/SkRect.h | 68 | ||||
| -rw-r--r-- | include/core/SkSurface.h | 32 |
10 files changed, 330 insertions, 695 deletions
diff --git a/include/core/SkBitmap.h b/include/core/SkBitmap.h index c4c9dc50a8..df0f0f8dd2 100644 --- a/include/core/SkBitmap.h +++ b/include/core/SkBitmap.h @@ -29,8 +29,8 @@ class SkString; SkImageInfo bounds may be located anywhere fully inside SkPixelRef bounds. SkBitmap can be drawn using SkCanvas. SkBitmap can be a drawing destination for SkCanvas - draw methods. SkBitmap flexibility as a pixel container limits some optimizations - available to the target platform. + draw member functions. SkBitmap flexibility as a pixel container limits some + optimizations available to the target platform. If pixel array is primarily read-only, use SkImage for better performance. If pixel array is primarily written to, use SkSurface for better performance. @@ -288,7 +288,7 @@ public: void setImmutable(); /** Returns true if SkAlphaType is set to hint that all pixels are opaque; their - color alpha value is implicitly or explicitly 1.0. If true, and all pixels are + alpha value is implicitly or explicitly 1.0. If true, and all pixels are not opaque, Skia may draw incorrectly. Does not check if SkColorType allows alpha, or if any pixel value has @@ -419,8 +419,7 @@ public: AllocFlags provides the option to zero pixel memory when allocated. */ enum AllocFlags { - /** Instructs tryAllocPixelsFlags() and allocPixelsFlags() to zero pixel memory. */ - kZeroPixels_AllocFlag = 1 << 0, + kZeroPixels_AllocFlag = 1 << 0, //!< zero pixel memory }; /** Sets SkImageInfo to info following the rules in setInfo() and allocates pixel @@ -542,7 +541,7 @@ public: this->allocPixels(info, info.minRowBytes()); } - /** Sets SkImageInfo to width, height, and native SkColorType; and allocates + /** Sets SkImageInfo to width, height, and native color type; and allocates pixel memory. If isOpaque is true, sets SkImageInfo to kOpaque_SkAlphaType; otherwise, sets to kPremul_SkAlphaType. @@ -565,7 +564,7 @@ public: return this->tryAllocPixels(info); } - /** Sets SkImageInfo to width, height, and the native SkColorType; and allocates + /** Sets SkImageInfo to width, height, and the native color type; and allocates pixel memory. If isOpaque is true, sets SkImageInfo to kPremul_SkAlphaType; otherwise, sets to kOpaque_SkAlphaType. @@ -769,7 +768,7 @@ public: void notifyPixelsChanged() const; /** Replaces pixel values with c. All pixels contained by bounds() are affected. - If the colorType() is kGray_8_SkColorType or k565_SkColorType, then color alpha + If the colorType() is kGray_8_SkColorType or k565_SkColorType, then alpha is ignored; RGB is treated as opaque. If colorType() is kAlpha_8_SkColorType, then RGB is ignored. @@ -783,10 +782,10 @@ public: is ignored; r, g, and b are treated as opaque. If colorType() is kAlpha_8_SkColorType, then r, g, and b are ignored. - @param a amount of color alpha, from fully transparent (0) to fully opaque (255) - @param r amount of color rgb red, from no red (0) to full red (255) - @param g amount of color rgb green, from no green (0) to full green (255) - @param b amount of color rgb blue, from no blue (0) to full blue (255) + @param a amount of alpha, from fully transparent (0) to fully opaque (255) + @param r amount of red, from no red (0) to full red (255) + @param g amount of green, from no green (0) to full green (255) + @param b amount of blue, from no blue (0) to full blue (255) */ void eraseARGB(U8CPU a, U8CPU r, U8CPU g, U8CPU b) const { this->eraseColor(SkColorSetARGB(a, r, g, b)); @@ -802,7 +801,7 @@ public: /** Replaces pixel values inside area with c. If area does not intersect bounds(), call has no effect. - If the colorType() is kGray_8_SkColorType or k565_SkColorType, then color alpha + If the colorType() is kGray_8_SkColorType or k565_SkColorType, then alpha is ignored; RGB is treated as opaque. If colorType() is kAlpha_8_SkColorType, then RGB is ignored. @@ -1187,7 +1186,7 @@ public: @param dst holds SkPixelRef to fill with alpha layer @param paint holds optional SkMaskFilter; may be nullptr - @param allocator method to reserve memory for SkPixelRef; may be nullptr + @param allocator function to reserve memory for SkPixelRef; may be nullptr @param offset top-left position for dst; may be nullptr @return true if alpha layer was constructed in dst SkPixelRef */ diff --git a/include/core/SkCanvas.h b/include/core/SkCanvas.h index 97de70b5f7..4644288bb8 100644 --- a/include/core/SkCanvas.h +++ b/include/core/SkCanvas.h @@ -57,7 +57,7 @@ class SkVertices; SkCanvas generated by GPU surface uses Vulkan or OpenGL to draw to the GPU. To draw to a document, obtain SkCanvas from svg canvas, document pdf, or SkPictureRecorder. - SkDocument based SkCanvas and other SkCanvas Subclasses reference SkBaseDevice describing the + SkDocument based SkCanvas and other SkCanvas subclasses reference SkBaseDevice describing the destination. SkCanvas can be constructed to draw to SkBitmap without first creating raster surface. @@ -137,7 +137,7 @@ public: SkCanvas(); /** Creates SkCanvas of the specified dimensions without a SkSurface. - Used by Subclasses with custom implementations for draw methods. + Used by subclasses with custom implementations for draw member functions. If props equals nullptr, SkSurfaceProps are created with SkSurfaceProps::InitType settings, which choose the pixel striping @@ -173,7 +173,7 @@ public: #ifdef SK_BUILD_FOR_ANDROID_FRAMEWORK enum class ColorBehavior { - kLegacy, //!< Is a placeholder to allow specialized constructor; has no meaning. + kLegacy, //!< placeholder }; /** Android framework only. @@ -199,7 +199,7 @@ public: */ SkCanvas(const SkBitmap& bitmap, const SkSurfaceProps& props); - /** Draws saved layer, if any. + /** Draws saved layers, if any. Frees up resources used by SkCanvas. */ virtual ~SkCanvas(); @@ -508,7 +508,7 @@ public: SkRect bounds suggests but does not define the SkBitmap size. To clip drawing to a specific rectangle, use clipRect(). - Optional SkPaint paint applies color alpha, SkColorFilter, SkImageFilter, and + Optional SkPaint paint applies alpha, SkColorFilter, SkImageFilter, and SkBlendMode when restore() is called. Call restoreToCount() with returned value to restore this and subsequent saves. @@ -531,7 +531,7 @@ public: 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 + Optional SkPaint paint applies alpha, SkColorFilter, SkImageFilter, and SkBlendMode when restore() is called. Call restoreToCount() with returned value to restore this and subsequent saves. @@ -558,7 +558,7 @@ public: 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 + Optional SkPaint paint applies alpha, SkColorFilter, SkImageFilter, and SkBlendMode when restore() is called. Call restoreToCount() with returned value to restore this and subsequent saves. @@ -596,24 +596,20 @@ public: */ int saveLayerAlpha(const SkRect* bounds, U8CPU alpha); - /** \enum SaveLayerFlagsSet + /** \enum SkCanvas::SaveLayerFlagsSet SaveLayerFlags provides options that may be used in any combination in SaveLayerRec, - defining how layer allocated by saveLayer() operates. + defining how layer allocated by saveLayer() operates. It may be set to zero, + kPreserveLCDText_SaveLayerFlag, kInitWithPrevious_SaveLayerFlag, or both flags. */ enum SaveLayerFlagsSet { - /** Creates layer for LCD text. Flag is ignored if layer SkPaint contains - SkImageFilter or SkColorFilter. - */ - kPreserveLCDText_SaveLayerFlag = 1 << 1, - - /** Initializes layer with the contents of the previous layer. */ - kInitWithPrevious_SaveLayerFlag = 1 << 2, - - kMaskAgainstCoverage_EXPERIMENTAL_DONT_USE_SaveLayerFlag = 1 << 3, + kPreserveLCDText_SaveLayerFlag = 1 << 1, //!< creates layer for LCD text + kInitWithPrevious_SaveLayerFlag = 1 << 2, //!< initializes with previous contents + kMaskAgainstCoverage_EXPERIMENTAL_DONT_USE_SaveLayerFlag = + 1 << 3, //!< experimental: do not use #ifdef SK_SUPPORT_LEGACY_CLIPTOLAYERFLAG - /** To be deprecated soon. */ - kDontClipToLayer_Legacy_SaveLayerFlag = kDontClipToLayer_PrivateSaveLayerFlag, + kDontClipToLayer_Legacy_SaveLayerFlag = + kDontClipToLayer_PrivateSaveLayerFlag, //!< to be deprecated soon #endif }; @@ -660,9 +656,9 @@ public: , fSaveLayerFlags(saveLayerFlags) {} - /** EXPERIMENTAL: Not ready for general use. + /** 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 + clipMatrix uses alpha channel of image, transformed by clipMatrix, to clip layer when drawn to SkCanvas. Implementation is not complete; has no effect if SkBaseDevice is GPU-backed. @@ -689,48 +685,30 @@ public: , fSaveLayerFlags(saveLayerFlags) {} - /** 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(). - */ + /** hints at layer size limit */ const SkRect* fBounds = nullptr; - /** fPaint modifies how layer overlays the prior layer; may be nullptr. - color alpha, SkBlendMode, SkColorFilter, SkDrawLooper, SkImageFilter, and - SkMaskFilter affect layer draw. - */ + /** modifies overlay */ const SkPaint* fPaint = nullptr; - /** fBackdrop applies SkImageFilter to the prior layer when copying to the layer; - may be nullptr. Use kInitWithPrevious_SaveLayerFlag to copy the - prior layer without an SkImageFilter. - */ + /** applies SkImageFilter to prior layer */ const SkImageFilter* fBackdrop = nullptr; - /** restore() clips layer by the color alpha channel of fClipMask when - layer is copied to SkBaseDevice. fClipMask may be nullptr. . - */ + /** clips layer with mask alpha */ const SkImage* fClipMask = nullptr; - /** 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. - */ + /** transforms mask alpha used to clip */ const SkMatrix* fClipMatrix = nullptr; - /** fSaveLayerFlags are used to create layer without transparency, - create layer for LCD text, and to create layer with the - contents of the previous layer. - */ + /** preserves LCD text, creates with prior layer contents */ SaveLayerFlags fSaveLayerFlags = 0; - }; /** 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, - and blends SkBitmap with color alpha opacity onto the prior layer. + and blends SkBitmap with 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(), @@ -898,7 +876,7 @@ public: The clip restriction is not recorded in pictures. Pass an empty rect to disable maximum clip. - This is private API to be used only by Android framework. + This private API is for use by Android framework only. @param rect maximum allowed clip in device coordinates */ @@ -978,7 +956,7 @@ public: this->clipPath(path, SkClipOp::kIntersect, doAntiAlias); } - /** EXPERIMENTAL: Only used for testing. + /** Experimental. For testing only. Set to simplify clip stack using PathOps. */ void setAllowSimplifyClip(bool allow) { @@ -1104,9 +1082,9 @@ public: an open polygon. */ enum PointMode { - kPoints_PointMode, //!< Draw each point separately. - kLines_PointMode, //!< Draw each pair of points as a line segment. - kPolygon_PointMode, //!< Draw the array of points as a open polygon. + kPoints_PointMode, //!< draw each point separately + kLines_PointMode, //!< draw each pair of points as a line segment + kPolygon_PointMode, //!< draw the array of points as a open polygon }; /** Draw pts using clip, SkMatrix and SkPaint paint. @@ -1350,7 +1328,7 @@ public: /** Draw SkImage image, with its top-left corner at (left, top), using clip, SkMatrix, and optional SkPaint paint. - If paint is supplied, apply SkColorFilter, color alpha, SkImageFilter, SkBlendMode, + If paint is supplied, apply SkColorFilter, alpha, SkImageFilter, SkBlendMode, and SkDrawLooper. If image is kAlpha_8_SkColorType, apply SkShader. If paint contains SkMaskFilter, generate mask from image bounds. If generated mask extends beyond image bounds, replicate image edge colors, just as SkShader @@ -1369,7 +1347,7 @@ public: /** Draw SkImage image, with its top-left corner at (left, top), using clip, SkMatrix, and optional SkPaint paint. - If SkPaint paint is supplied, apply SkColorFilter, color alpha, SkImageFilter, + If SkPaint paint is supplied, apply SkColorFilter, alpha, SkImageFilter, SkBlendMode, and SkDrawLooper. If image is kAlpha_8_SkColorType, apply SkShader. If paint contains SkMaskFilter, generate mask from image bounds. If generated mask extends beyond image bounds, replicate image edge colors, just as SkShader @@ -1398,19 +1376,14 @@ public: outside source SkRect. */ enum SrcRectConstraint { - /** sampling only inside of its bounds, possibly with a performance penalty. */ - kStrict_SrcRectConstraint, - - /** by half the width of SkImageFilter, permitting it to run faster but with - error at the image edges. - */ - kFast_SrcRectConstraint, + kStrict_SrcRectConstraint, //!< sample only inside bounds; slower + kFast_SrcRectConstraint, //!< sample outside bounds; faster }; /** Draw SkRect src of SkImage image, scaled and translated to fill SkRect dst. Additionally transform draw using clip, SkMatrix, and optional SkPaint paint. - If SkPaint paint is supplied, apply SkColorFilter, color alpha, SkImageFilter, + If SkPaint paint is supplied, apply SkColorFilter, alpha, SkImageFilter, SkBlendMode, and SkDrawLooper. If image is kAlpha_8_SkColorType, apply SkShader. If paint contains SkMaskFilter, generate mask from image bounds. @@ -1438,7 +1411,7 @@ public: boundaries. Additionally transform draw using clip, SkMatrix, and optional SkPaint paint. - If SkPaint paint is supplied, apply SkColorFilter, color alpha, SkImageFilter, + If SkPaint paint is supplied, apply SkColorFilter, alpha, SkImageFilter, SkBlendMode, and SkDrawLooper. If image is kAlpha_8_SkColorType, apply SkShader. If paint contains SkMaskFilter, generate mask from image bounds. @@ -1464,7 +1437,7 @@ public: /** Draw SkImage image, scaled and translated to fill SkRect dst, using clip, SkMatrix, and optional SkPaint paint. - If SkPaint paint is supplied, apply SkColorFilter, color alpha, SkImageFilter, + If SkPaint paint is supplied, apply SkColorFilter, alpha, SkImageFilter, SkBlendMode, and SkDrawLooper. If image is kAlpha_8_SkColorType, apply SkShader. If paint contains SkMaskFilter, generate mask from image bounds. @@ -1488,7 +1461,7 @@ public: /** Draw SkRect src of SkImage image, scaled and translated to fill SkRect dst. Additionally transform draw using clip, SkMatrix, and optional SkPaint paint. - If SkPaint paint is supplied, apply SkColorFilter, color alpha, SkImageFilter, + If SkPaint paint is supplied, apply SkColorFilter, alpha, SkImageFilter, SkBlendMode, and SkDrawLooper. If image is kAlpha_8_SkColorType, apply SkShader. If paint contains SkMaskFilter, generate mask from image bounds. @@ -1517,7 +1490,7 @@ public: isrc is on integer pixel boundaries; dst may include fractional boundaries. Additionally transform draw using clip, SkMatrix, and optional SkPaint paint. - If SkPaint paint is supplied, apply SkColorFilter, color alpha, SkImageFilter, + If SkPaint paint is supplied, apply SkColorFilter, alpha, SkImageFilter, SkBlendMode, and SkDrawLooper. If image is kAlpha_8_SkColorType, apply SkShader. If paint contains SkMaskFilter, generate mask from image bounds. @@ -1545,7 +1518,7 @@ public: /** Draw SkImage image, scaled and translated to fill SkRect dst, using clip, SkMatrix, and optional SkPaint paint. - If SkPaint paint is supplied, apply SkColorFilter, color alpha, SkImageFilter, + If SkPaint paint is supplied, apply SkColorFilter, alpha, SkImageFilter, SkBlendMode, and SkDrawLooper. If image is kAlpha_8_SkColorType, apply SkShader. If paint contains SkMaskFilter, generate mask from image bounds. @@ -1575,9 +1548,12 @@ public: Additionally transform draw using clip, SkMatrix, and optional SkPaint paint. - If SkPaint paint is supplied, apply SkColorFilter, color alpha, SkImageFilter, + If SkPaint paint is supplied, apply SkColorFilter, alpha, SkImageFilter, SkBlendMode, and SkDrawLooper. If image is kAlpha_8_SkColorType, apply SkShader. - If paint contains SkMaskFilter, generate mask from image bounds. + If paint contains SkMaskFilter, generate mask from image bounds. If paint + SkFilterQuality set to kNone_SkFilterQuality, disable pixel filtering. For all + other values of paint SkFilterQuality, use kLow_SkFilterQuality to filter pixels. + Any SkMaskFilter on paint is ignored as is paint anti-aliasing state. If generated mask extends beyond image bounds, replicate image edge colors, just as SkShader made from SkImage::makeShader with SkShader::kClamp_TileMode set @@ -1599,11 +1575,12 @@ public: Additionally transform draw using clip, SkMatrix, and optional SkPaint paint. - If SkPaint paint is supplied, apply SkColorFilter, color alpha, SkImageFilter, + If SkPaint paint is supplied, apply SkColorFilter, alpha, SkImageFilter, SkBlendMode, and SkDrawLooper. If image is kAlpha_8_SkColorType, apply SkShader. - If paint contains SkMaskFilter, generate mask from bitmap bounds. If paint's - SkFilterQuality is higher than kLow_SkFilterQuality, it will be treated as if it - were kLow_SkFilterQuality. + If paint contains SkMaskFilter, generate mask from image bounds. If paint + SkFilterQuality set to kNone_SkFilterQuality, disable pixel filtering. For all + other values of paint SkFilterQuality, use kLow_SkFilterQuality to filter pixels. + Any SkMaskFilter on paint is ignored as is paint anti-aliasing state. If generated mask extends beyond image bounds, replicate image edge colors, just as SkShader made from SkImage::makeShader with SkShader::kClamp_TileMode set @@ -1623,7 +1600,7 @@ public: /** Draw SkBitmap bitmap, with its top-left corner at (left, top), using clip, SkMatrix, and optional SkPaint paint. - If SkPaint paint is not nullptr, apply SkColorFilter, color alpha, SkImageFilter, + If SkPaint paint is not nullptr, apply SkColorFilter, alpha, SkImageFilter, SkBlendMode, and SkDrawLooper. If bitmap is kAlpha_8_SkColorType, apply SkShader. If paint contains SkMaskFilter, generate mask from bitmap bounds. @@ -1644,7 +1621,7 @@ public: /** Draw SkRect src of SkBitmap bitmap, scaled and translated to fill SkRect dst. Additionally transform draw using clip, SkMatrix, and optional SkPaint paint. - If SkPaint paint is supplied, apply SkColorFilter, color alpha, SkImageFilter, + If SkPaint paint is supplied, apply SkColorFilter, alpha, SkImageFilter, SkBlendMode, and SkDrawLooper. If bitmap is kAlpha_8_SkColorType, apply SkShader. If paint contains SkMaskFilter, generate mask from bitmap bounds. @@ -1672,7 +1649,7 @@ public: isrc is on integer pixel boundaries; dst may include fractional boundaries. Additionally transform draw using clip, SkMatrix, and optional SkPaint paint. - If SkPaint paint is supplied, apply SkColorFilter, color alpha, SkImageFilter, + If SkPaint paint is supplied, apply SkColorFilter, alpha, SkImageFilter, SkBlendMode, and SkDrawLooper. If bitmap is kAlpha_8_SkColorType, apply SkShader. If paint contains SkMaskFilter, generate mask from bitmap bounds. @@ -1700,7 +1677,7 @@ public: bitmap bounds is on integer pixel boundaries; dst may include fractional boundaries. Additionally transform draw using clip, SkMatrix, and optional SkPaint paint. - If SkPaint paint is supplied, apply SkColorFilter, color alpha, SkImageFilter, + If SkPaint paint is supplied, apply SkColorFilter, alpha, SkImageFilter, SkBlendMode, and SkDrawLooper. If bitmap is kAlpha_8_SkColorType, apply SkShader. If paint contains SkMaskFilter, generate mask from bitmap bounds. @@ -1730,12 +1707,12 @@ public: Additionally transform draw using clip, SkMatrix, and optional SkPaint paint. - If SkPaint paint is supplied, apply SkColorFilter, color alpha, SkImageFilter, + If SkPaint paint is supplied, apply SkColorFilter, alpha, SkImageFilter, SkBlendMode, and SkDrawLooper. If bitmap is kAlpha_8_SkColorType, apply SkShader. - If paint contains SkMaskFilter, generate mask from bitmap bounds. If paint's - SkFilterQuality is higher than kLow_SkFilterQuality, it will be treated as if it - were kLow_SkFilterQuality. Any SkMaskFilter on the paint is ignored as is the paint's - antialiasing state. + If paint contains SkMaskFilter, generate mask from bitmap bounds. If paint + SkFilterQuality set to kNone_SkFilterQuality, disable pixel filtering. For all + other values of paint SkFilterQuality, use kLow_SkFilterQuality to filter pixels. + Any SkMaskFilter on paint is ignored as is paint anti-aliasing state. If generated mask extends beyond bitmap bounds, replicate bitmap edge colors, just as SkShader made from SkShader::MakeBitmapShader with @@ -1767,60 +1744,18 @@ public: or to fill the grid entry with a color. */ enum RectType : uint8_t { - kDefault = 0, //!< Draws SkBitmap into lattice rectangle. - kTransparent, //!< Skips lattice rectangle by making it transparent. - kFixedColor, //!< Draws one of fColors into lattice rectangle. + kDefault = 0, //!< draws SkBitmap into lattice rectangle + kTransparent, //!< skips lattice rectangle by making it transparent + kFixedColor, //!< draws one of fColors into lattice rectangle }; - /** Array of x-coordinates that divide the bitmap vertically. - Array entries must be unique, increasing, greater than or equal to - fBounds left edge, and less than fBounds right edge. - Set the first element to fBounds left to collapse the left column of - fixed grid entries. - */ - const int* fXDivs; - - /** Array of y-coordinates that divide the bitmap horizontally. - Array entries must be unique, increasing, greater than or equal to - fBounds top edge, and less than fBounds bottom edge. - Set the first element to fBounds top to collapse the top row of fixed - grid entries. - */ - const int* fYDivs; - - /** Optional array of fill types, one per rectangular grid entry: - array length must be (fXCount + 1) * (fYCount + 1). - - Each RectType is one of: kDefault, kTransparent, kFixedColor. - - Array entries correspond to the rectangular grid entries, ascending - left to right and then top to bottom. - */ - const RectType* fRectTypes; - - /** Number of entries in fXDivs array; one less than the number of - horizontal divisions. - */ - int fXCount; - - /** Number of entries in fYDivs array; one less than the number of vertical - divisions. - */ - int fYCount; - - /** Optional subset SkIRect source to draw from. - If nullptr, source bounds is dimensions of SkBitmap or SkImage. - */ - const SkIRect* fBounds; - - /** Optional array of colors, 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, then top to bottom. - */ - const SkColor* fColors; - + const int* fXDivs; //!< x-coordinates dividing bitmap + const int* fYDivs; //!< y-coordinates dividing bitmap + const RectType* fRectTypes; //!< array of fill types + int fXCount; //!< number of x-coordinates + int fYCount; //!< number of y-coordinates + const SkIRect* fBounds; //!< source bounds to draw from + const SkColor* fColors; //!< array of colors }; /** Draw SkBitmap bitmap stretched proportionally to fit into SkRect dst. @@ -1833,12 +1768,12 @@ public: Additionally transform draw using clip, SkMatrix, and optional SkPaint paint. - If SkPaint paint is supplied, apply SkColorFilter, color alpha, SkImageFilter, + If SkPaint paint is supplied, apply SkColorFilter, alpha, SkImageFilter, SkBlendMode, and SkDrawLooper. If bitmap is kAlpha_8_SkColorType, apply SkShader. - If paint contains SkMaskFilter, generate mask from bitmap bounds. If paint's - SkFilterQuality is higher than kLow_SkFilterQuality, it will be treated as if it - were kLow_SkFilterQuality. Any SkMaskFilter on the paint is ignored as is the paint's - antialiasing state. + If paint contains SkMaskFilter, generate mask from bitmap bounds. If paint + SkFilterQuality set to kNone_SkFilterQuality, disable pixel filtering. For all + other values of paint SkFilterQuality, use kLow_SkFilterQuality to filter pixels. + Any SkMaskFilter on paint is ignored as is paint anti-aliasing state. If generated mask extends beyond bitmap bounds, replicate bitmap edge colors, just as SkShader made from SkShader::MakeBitmapShader with @@ -1864,12 +1799,12 @@ public: Additionally transform draw using clip, SkMatrix, and optional SkPaint paint. - If SkPaint paint is supplied, apply SkColorFilter, color alpha, SkImageFilter, - SkBlendMode, and SkDrawLooper. If bitmap is kAlpha_8_SkColorType, apply SkShader. - If paint contains SkMaskFilter, generate mask from bitmap bounds. If paint's - SkFilterQuality is higher than kLow_SkFilterQuality, it will be treated as if it - were kLow_SkFilterQuality. Any SkMaskFilter on the paint is ignored as is the paint's - antialiasing state. + If SkPaint paint is supplied, apply SkColorFilter, alpha, SkImageFilter, + SkBlendMode, and SkDrawLooper. If image is kAlpha_8_SkColorType, apply SkShader. + If paint contains SkMaskFilter, generate mask from image bounds. If paint + SkFilterQuality set to kNone_SkFilterQuality, disable pixel filtering. For all + other values of paint SkFilterQuality, use kLow_SkFilterQuality to filter pixels. + Any SkMaskFilter on paint is ignored as is paint anti-aliasing state. If generated mask extends beyond bitmap bounds, replicate bitmap edge colors, just as SkShader made from SkShader::MakeBitmapShader with @@ -1907,9 +1842,8 @@ public: void drawText(const void* text, size_t byteLength, SkScalar x, SkScalar y, const SkPaint& paint); - /** Draw null terminated string, with origin at (x, y), using clip, SkMatrix, and - SkPaint paint. Note that this per-glyph xform does not affect the shader (if present) - on the paint, just the glyph's geometry. + /** Draws null terminated string, with origin at (x, y), using clip, SkMatrix, and + SkPaint paint. string meaning depends on SkPaint::TextEncoding; by default, strings are encoded as UTF-8. Other values of SkPaint::TextEncoding are unlikely to produce the desired @@ -1964,8 +1898,8 @@ public: described by byteLength of text. text meaning depends on SkPaint::TextEncoding; by default, text is encoded as - UTF-8. pos elements' meaning depends on SkPaint vertical text; - by each glyph left side bearing is positioned at x and its + UTF-8. pos elements meaning depends on SkPaint vertical text; + by default each glyph left side bearing is positioned at x and its baseline is positioned at y. Text size is affected by SkMatrix and SkPaint text size. @@ -1989,8 +1923,8 @@ public: must match the number of glyphs described by byteLength of text. text meaning depends on SkPaint::TextEncoding; by default, text is encoded as - UTF-8. xpos elements' meaning depends SkPaint vertical text; - each glyph left side bearing is positioned at an xpos element and + UTF-8. xpos elements meaning depends on SkPaint vertical text; + by default each glyph left side bearing is positioned at an xpos element and its baseline is positioned at constY. Text size is affected by SkMatrix and SkPaint text size. @@ -2040,16 +1974,19 @@ public: /** Draw text on SkPath path, using clip, SkMatrix, and SkPaint paint. - Origin of text is at beginning of path offset by matrix, if provided, before it - is mapped to path. If the path section corresponding the glyph advance is - curved, the glyph is drawn curved to match; control points in the glyph are - mapped to projected points parallel to the path. If the text advance is larger - than the path length, the excess text is clipped. + Origin of text is at beginning of path offset by matrix, if not nullptr. + matrix transforms text before text is mapped to path. If the path section + corresponding the glyph advance is curved, the glyph is drawn curved to match; + control points in the glyph are mapped to projected points parallel to the path. + If the text advance is larger than the path length, the excess text is clipped. + + matrix does not effect paint SkShader. text meaning depends on SkPaint::TextEncoding; by default, text is encoded as UTF-8. Origin meaning depends on SkPaint::Align and SkPaint vertical text; by default text positions the first glyph left side bearing at origin x and its - baseline at origin y. Text size is affected by SkMatrix and SkPaint text size. + baseline at origin y. Text size is affected by matrix parameter, SkCanvas SkMatrix, + and SkPaint text size. All elements of paint: SkPathEffect, SkMaskFilter, SkShader, SkColorFilter, SkImageFilter, and SkDrawLooper; apply to text. By default, draws @@ -2068,8 +2005,8 @@ public: /** Draw text, transforming each glyph by the corresponding SkRSXform, using clip, SkMatrix, and SkPaint paint. - SkRSXform array specifies a separate square scale, rotation, and translation for - each glyph. + SkRSXform xform array specifies a separate square scale, rotation, and translation + for each glyph. xform does not affect paint SkShader. Optional SkRect cullRect is a conservative bounds of text, taking into account SkRSXform and paint. If cullRect is outside of clip, canvas can skip drawing. @@ -2091,7 +2028,7 @@ 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, SkPaint anti-alias, SkPaint fake bold, + SkPaint::Align, SkPaint::Hinting, 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. @@ -2111,7 +2048,7 @@ 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, SkPaint anti-alias, SkPaint fake bold, + SkPaint::Align, SkPaint::Hinting, 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. @@ -2154,7 +2091,7 @@ public: } /** Draw SkPicture picture, using clip and SkMatrix; transforming picture with - SkMatrix matrix, if provided; and use SkPaint paint color alpha, SkColorFilter, + SkMatrix matrix, if provided; and use SkPaint paint alpha, SkColorFilter, SkImageFilter, and SkBlendMode, if provided. matrix transformation is equivalent to: save(), concat(), drawPicture(), restore(). @@ -2167,7 +2104,7 @@ public: void drawPicture(const SkPicture* picture, const SkMatrix* matrix, const SkPaint* paint); /** Draw SkPicture picture, using clip and SkMatrix; transforming picture with - SkMatrix matrix, if provided; and use SkPaint paint color alpha, SkColorFilter, + SkMatrix matrix, if provided; and use SkPaint paint alpha, SkColorFilter, SkImageFilter, and SkBlendMode, if provided. matrix transformation is equivalent to: save(), concat(), drawPicture(), restore(). @@ -2181,23 +2118,23 @@ public: this->drawPicture(picture.get(), matrix, paint); } - /** Draw vertices vertices, a triangle mesh, using clip and SkMatrix. + /** Draw SkVertices vertices, a triangle mesh, using clip and SkMatrix. If vertices texs and vertices colors are defined in vertices, and SkPaint paint contains SkShader, SkBlendMode mode combines vertices colors with SkShader. @param vertices triangle mesh to draw @param mode combines vertices colors with SkShader, if both are present - @param paint specifies the SkShader, used as vertices texture; may be nullptr + @param paint specifies the SkShader, used as SkVertices texture; may be nullptr */ void drawVertices(const SkVertices* vertices, SkBlendMode mode, const SkPaint& paint); - /** Draw vertices vertices, a triangle mesh, using clip and SkMatrix. + /** Draw SkVertices vertices, a triangle mesh, using clip and SkMatrix. If vertices texs and vertices colors are defined in vertices, and SkPaint paint contains SkShader, SkBlendMode mode combines vertices colors with SkShader. @param vertices triangle mesh to draw @param mode combines vertices colors with SkShader, if both are present - @param paint specifies the SkShader, used as vertices texture, may be nullptr + @param paint specifies the SkShader, used as SkVertices texture, may be nullptr */ void drawVertices(const sk_sp<SkVertices>& vertices, SkBlendMode mode, const SkPaint& paint); @@ -2205,7 +2142,7 @@ public: associating a color, and optionally a texture coordinate, with each corner. Coons_Patch uses clip and SkMatrix, paint SkShader, SkColorFilter, - color alpha, SkImageFilter, and SkBlendMode. If SkShader is provided it is treated + alpha, SkImageFilter, and SkBlendMode. If SkShader is provided it is treated as Coons_Patch texture; SkBlendMode mode combines color colors and SkShader if both are provided. @@ -2233,7 +2170,7 @@ public: associating a color, and optionally a texture coordinate, with each corner. Coons_Patch uses clip and SkMatrix, paint SkShader, SkColorFilter, - color alpha, SkImageFilter, and SkBlendMode. If SkShader is provided it is treated + alpha, SkImageFilter, and SkBlendMode. If SkShader is provided it is treated as Coons_Patch texture; SkBlendMode mode combines color colors and SkShader if both are provided. @@ -2259,7 +2196,7 @@ public: } /** Draw a set of sprites from atlas, using clip, SkMatrix, and optional SkPaint paint. - paint uses SkPaint anti-alias, color alpha, SkColorFilter, SkImageFilter, and SkBlendMode + paint uses anti-alias, 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. @@ -2282,7 +2219,7 @@ public: const SkPaint* paint); /** Draw a set of sprites from atlas, using clip, SkMatrix, and optional SkPaint paint. - paint uses SkPaint anti-alias, color alpha, SkColorFilter, SkImageFilter, and SkBlendMode + paint uses anti-alias, 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. @@ -2307,7 +2244,7 @@ public: } /** Draw a set of sprites from atlas, using clip, SkMatrix, and optional SkPaint paint. - paint uses SkPaint anti-alias, color alpha, SkColorFilter, SkImageFilter, and SkBlendMode + paint uses anti-alias, 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. @@ -2328,7 +2265,7 @@ public: } /** Draw a set of sprites from atlas, using clip, SkMatrix, and optional SkPaint paint. - paint uses SkPaint anti-alias, color alpha, SkColorFilter, SkImageFilter, and SkBlendMode + paint uses anti-alias, 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. diff --git a/include/core/SkImage.h b/include/core/SkImage.h index 7c693900d3..28c1be1a2a 100644 --- a/include/core/SkImage.h +++ b/include/core/SkImage.h @@ -346,8 +346,8 @@ public: sk_sp<SkColorSpace> colorSpace = nullptr); enum class BitDepth { - kU8, //!< Use 8 bits per ARGB component using unsigned integer format. - kF16, //!< Use 16 bits per ARGB component using half-precision floating point format. + kU8, //!< uses 8-bit unsigned int per color component + kF16, //!< uses 16-bit float per color component }; /** Creates SkImage from picture. Returned SkImage width and height are set by dimensions. @@ -360,7 +360,7 @@ public: @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 bitDepth 8-bit integer or 16-bit float: per component @param colorSpace range of colors; may be nullptr @return created SkImage, or nullptr */ @@ -534,7 +534,7 @@ public: */ bool isValid(GrContext* context) const; - /** Retrieves the backend texture. If SkImage has no backend texture, an invalid + /** Retrieves the back-end texture. If SkImage has no back-end texture, an invalid object is returned. Call GrBackendTexture::isValid to determine if the result is valid. @@ -563,10 +563,8 @@ public: 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, + kAllow_CachingHint, //!< allows internally caching decoded and copied pixels + kDisallow_CachingHint, //!< disallows internally caching decoded and copied pixels }; /** Copies SkRect of pixels from SkImage to dstPixels. Copy starts at offset (srcX, srcY), @@ -809,9 +807,9 @@ public: @param context GPU context @param image SkImage used for texture - @param backendTexture storage for backend texture + @param backendTexture storage for back-end texture @param backendTextureReleaseProc storage for clean up function - @return true if backend texture was created + @return true if back-end texture was created */ static bool MakeBackendTextureFromSkImage(GrContext* context, sk_sp<SkImage> image, @@ -819,7 +817,7 @@ public: BackendTextureReleaseProc* backendTextureReleaseProc); enum LegacyBitmapMode { - kRO_LegacyBitmapMode, //!< Returned bitmap is read-only and immutable. + kRO_LegacyBitmapMode, //!< returned bitmap is read-only and immutable }; /** Creates raster SkBitmap with same pixels as SkImage. If legacyBitmapMode is diff --git a/include/core/SkImageInfo.h b/include/core/SkImageInfo.h index eb96f19723..6d1b2a942d 100644 --- a/include/core/SkImageInfo.h +++ b/include/core/SkImageInfo.h @@ -19,47 +19,31 @@ class SkWriteBuffer; /** \enum SkImageInfo::SkAlphaType Describes how to interpret the alpha component of a pixel. A pixel may - be opaque, or color alpha, describing multiple levels of transparency. + be opaque, or alpha, describing multiple levels of transparency. - In simple blending, color alpha weights the draw color and the destination - color to create a new color. If alpha describes a weight from zero to one:In practice alpha is encoded in two or more bits, where 1.0 equals all bits set. + In simple blending, alpha weights the draw color and the destination + color to create a new color. If alpha describes a weight from zero to one: - RGB may have color alpha included in each component value; the stored - value is the original RGB multiplied by color alpha. Premultiplied color + new color = draw color * alpha + destination color * (1 - alpha) + + In practice alpha is encoded in two or more bits, where 1.0 equals all bits set. + + RGB may have alpha included in each component value; the stored + value is the original RGB multiplied by alpha. Premultiplied color components improve performance. */ enum SkAlphaType { - kUnknown_SkAlphaType, //!< SkAlphaType is uninitialized. - - /** Pixels are opaque. The SkColorType must have no explicit alpha - component, or all alpha components must be set to their maximum value. - */ - kOpaque_SkAlphaType, - - /** Pixels have alpha premultiplied into color components. - SkSurface pixels must be premultiplied. - */ - kPremul_SkAlphaType, - - /** Pixel color component values are independent of alpha value. - Images generated from encoded data like PNG do not premultiply pixel color - components. kUnpremul_SkAlphaType is supported for SkImage pixels, but not for - SkSurface pixels. - */ - kUnpremul_SkAlphaType, - - /** Pixel color component values are independent of alpha value. - Images generated from encoded data like PNG do not premultiply pixel color - components. kUnpremul_SkAlphaType is supported for SkImage pixels, but not for - SkSurface pixels. - */ - kLastEnum_SkAlphaType = kUnpremul_SkAlphaType, + kUnknown_SkAlphaType, //!< uninitialized + kOpaque_SkAlphaType, //!< pixel is opaque + kPremul_SkAlphaType, //!< pixel components are premultiplied by alpha + kUnpremul_SkAlphaType, //!< pixel components are independent of alpha + kLastEnum_SkAlphaType = kUnpremul_SkAlphaType, //!< last valid value }; /** Returns true if SkAlphaType equals kOpaque_SkAlphaType. kOpaque_SkAlphaType is a - hint that the SkColorType is opaque, or that all color alpha values are set to + hint that the SkColorType is opaque, or that all alpha values are set to their 1.0 equivalent. If SkAlphaType is kOpaque_SkAlphaType, and SkColorType is not - opaque, then the result of drawing any pixel with a color alpha value less than + opaque, then the result of drawing any pixel with a alpha value less than 1.0 is undefined. @param at one of: @@ -78,7 +62,7 @@ static inline bool SkAlphaTypeIsOpaque(SkAlphaType at) { /** \enum SkImageInfo::SkColorType Describes how pixel bits encode color. A pixel may be an alpha mask, a - gray level, RGB, or ARGB. + grayscale, RGB, or ARGB. kN32_SkColorType selects the native 32-bit ARGB format. On Little_Endian processors, pixels containing 8-bit ARGB components pack into 32-bit @@ -86,54 +70,24 @@ static inline bool SkAlphaTypeIsOpaque(SkAlphaType at) { kRGBA_8888_SkColorType. */ enum SkColorType { - /** SkColorType is uninitialized; encoding format and size is unknown. */ - kUnknown_SkColorType, - - /** Encodes color alpha as alpha 8 pixel in an 8-bit byte. */ - kAlpha_8_SkColorType, - - /** Encodes RGB as bgr 565 pixel in a 16-bit word. */ - kRGB_565_SkColorType, - - /** Encodes ARGB as abgr 4444 pixel in a 16-bit word. */ - kARGB_4444_SkColorType, - - /** Encodes ARGB as rgba 8888 pixel in a 32-bit word. */ - kRGBA_8888_SkColorType, - - /** Encodes RGB as rgb 888x pixel in a 32-bit word. */ - kRGB_888x_SkColorType, - - /** Encodes ARGB as bgra 8888 pixel in a 32-bit word. */ - kBGRA_8888_SkColorType, - - /** Encodes ARGB as rgba 1010102 pixel in a 32-bit word. */ - kRGBA_1010102_SkColorType, - - /** Encodes RGB as rgb 101010x pixel in a 32-bit word. */ - kRGB_101010x_SkColorType, - - /** Encodes color gray as gray 8 in an 8-bit byte. */ - kGray_8_SkColorType, - - /** Encodes ARGB as rgba f16 in a 64-bit word. */ - kRGBA_F16_SkColorType, - - /** Encodes ARGB as rgba f16 in a 64-bit word. */ - kLastEnum_SkColorType = kRGBA_F16_SkColorType, + kUnknown_SkColorType, //!< uninitialized + kAlpha_8_SkColorType, //!< pixel with alpha in 8-bit byte + kRGB_565_SkColorType, //!< pixel with 5 bits red, 6 bits green, 5 bits blue, in 16-bit word + kARGB_4444_SkColorType, //!< pixel with 4 bits for alpha, red, green, blue; in 16-bit word + kRGBA_8888_SkColorType, //!< pixel with 8 bits for red, green, blue, alpha; in 32-bit word + kRGB_888x_SkColorType, //!< pixel with 8 bits each for red, green, blue; in 32-bit word + kBGRA_8888_SkColorType, //!< pixel with 8 bits for blue, green, red, alpha; in 32-bit word + kRGBA_1010102_SkColorType, //!< 10 bits for red, green, blue; 2 bits for alpha; in 32-bit word + kRGB_101010x_SkColorType, //!< pixel with 10 bits each for red, green, blue; in 32-bit word + kGray_8_SkColorType, //!< pixel with grayscale level in 8-bit byte + kRGBA_F16_SkColorType, //!< pixel with half floats for red, green, blue, alpha; in 64-bit word + kLastEnum_SkColorType = kRGBA_F16_SkColorType,//!< last valid value #if SK_PMCOLOR_BYTE_ORDER(B,G,R,A) - /** Encodes ARGB as either rgba 8888 or bgra 8888, whichever - is native to the platform. - */ - kN32_SkColorType = kBGRA_8888_SkColorType, + kN32_SkColorType = kBGRA_8888_SkColorType,//!< native ARGB 32-bit encoding #elif SK_PMCOLOR_BYTE_ORDER(R,G,B,A) - - /** Encodes ARGB as either rgba 8888 or bgra 8888, whichever - is native to the platform. - */ - kN32_SkColorType = kRGBA_8888_SkColorType, + kN32_SkColorType = kRGBA_8888_SkColorType,//!< native ARGB 32-bit encoding #else #error "SK_*32_SHIFT values must correspond to BGRA or RGBA byte order" @@ -152,15 +106,15 @@ enum SkColorType { */ SK_API int SkColorTypeBytesPerPixel(SkColorType ct); -/** Returns true if SkColorType always decodes color alpha to 1.0, making the pixel - fully opaque. If true, SkColorType does not reserve bits to encode color alpha. +/** Returns true if SkColorType always decodes alpha to 1.0, making the pixel + fully opaque. If true, SkColorType does not reserve bits to encode alpha. @param ct one of: kUnknown_SkColorType, kAlpha_8_SkColorType, kRGB_565_SkColorType, kARGB_4444_SkColorType, kRGBA_8888_SkColorType, kRGB_888x_SkColorType, kBGRA_8888_SkColorType, kRGBA_1010102_SkColorType, kRGB_101010x_SkColorType, kGray_8_SkColorType, kRGBA_F16_SkColorType - @return true if color alpha is always set to 1.0 + @return true if alpha is always set to 1.0 */ SK_API bool SkColorTypeIsAlwaysOpaque(SkColorType ct); @@ -206,17 +160,10 @@ SK_API bool SkColorTypeValidateAlphaType(SkColorType colorType, SkAlphaType alph encoding and conversion to RGB are described in YCbCr color space. */ enum SkYUVColorSpace { - /** Describes standard JPEG color space; */ - kJPEG_SkYUVColorSpace, - - /** Describes standard used by SDTV; */ - kRec601_SkYUVColorSpace, - - /** Describes standard used by HDTV; */ - kRec709_SkYUVColorSpace, - - /** Describes standard used by HDTV; */ - kLastEnum_SkYUVColorSpace = kRec709_SkYUVColorSpace, + kJPEG_SkYUVColorSpace, //!< describes full range + kRec601_SkYUVColorSpace, //!< describes SDTV range + kRec709_SkYUVColorSpace, //!< describes HDTV range + kLastEnum_SkYUVColorSpace = kRec709_SkYUVColorSpace, //!< last valid value }; /** \struct SkImageInfo @@ -226,7 +173,7 @@ enum SkYUVColorSpace { implementations may defer pixel depth, so may not completely specify SkImageInfo. SkImageInfo contains dimensions, the pixel integral width and height. It encodes - how pixel bits describe color alpha, transparency; color components red, blue, + how pixel bits describe alpha, transparency; color components red, blue, and green; and SkColorSpace, the range and linearity of colors. */ struct SK_API SkImageInfo { @@ -436,7 +383,7 @@ public: bool isEmpty() const { return fWidth <= 0 || fHeight <= 0; } /** Returns true if SkAlphaType is set to hint that all pixels are opaque; their - color alpha value is implicitly or explicitly 1.0. If true, and all pixels are + alpha value is implicitly or explicitly 1.0. If true, and all pixels are not opaque, Skia may draw incorrectly. Does not check if SkColorType allows alpha, or if any pixel value has @@ -535,8 +482,8 @@ public: int shiftPerPixel() const; /** Returns minimum bytes per row, computed from pixel width() and SkColorType, which - specifies bytesPerPixel(). SkBitmap maximum value for row bytes must be representable - as a positive value in a 32-bit signed integer. + specifies bytesPerPixel(). SkBitmap maximum value for row bytes must fit + in 31 bits. @return width() times bytesPerPixel() as unsigned 64-bit integer */ @@ -545,8 +492,8 @@ public: } /** Returns minimum bytes per row, computed from pixel width() and SkColorType, which - specifies bytesPerPixel(). SkBitmap maximum value for row bytes must be representable - as a positive value in a 32-bit signed integer. + specifies bytesPerPixel(). SkBitmap maximum value for row bytes must fit + in 31 bits. @return width() times bytesPerPixel() as signed 32-bit integer */ @@ -583,7 +530,7 @@ public: } /** Compares SkImageInfo with other, and returns true if width, height, SkColorType, - SkAlphaType, and SkColorSpace are equivalent. + SkAlphaType, and SkColorSpace are not equivalent. @param other SkImageInfo to compare @return true if SkImageInfo is not equal to other diff --git a/include/core/SkMatrix.h b/include/core/SkMatrix.h index 9733590167..a5873b114e 100644 --- a/include/core/SkMatrix.h +++ b/include/core/SkMatrix.h @@ -109,11 +109,11 @@ public: Used to identify the complexity of SkMatrix, to optimize performance. */ enum TypeMask { - kIdentity_Mask = 0, //!< all bits clear if SkMatrix is identity - kTranslate_Mask = 0x01, //!< set if SkMatrix has translation - kScale_Mask = 0x02, //!< set if SkMatrix has x or y scale - kAffine_Mask = 0x04, //!< set if SkMatrix skews or rotates - kPerspective_Mask = 0x08, //!< set if SkMatrix has perspective + kIdentity_Mask = 0, //!< identity SkMatrix; all bits clear + kTranslate_Mask = 0x01, //!< translation SkMatrix + kScale_Mask = 0x02, //!< scale SkMatrix + kAffine_Mask = 0x04, //!< skew or rotate SkMatrix + kPerspective_Mask = 0x08, //!< perspective SkMatrix }; /** Returns a bit field describing the transformations the matrix may @@ -1069,29 +1069,10 @@ public: how SkMatrix maps to the side or center of the destination SkRect. */ enum ScaleToFit { - /** Computes SkMatrix that scales in x and y independently, so that source SkRect is - mapped to completely fill destination SkRect. The aspect ratio of source SkRect - may change. - */ - kFill_ScaleToFit, - - /** Computes SkMatrix that maintains source SkRect aspect ratio, mapping source SkRect - width or height to destination SkRect. Aligns mapping to left and top edges - of destination SkRect. - */ - kStart_ScaleToFit, - - /** Computes SkMatrix that maintains source SkRect aspect ratio, mapping source SkRect - width or height to destination SkRect. Aligns mapping to center of destination - SkRect. - */ - kCenter_ScaleToFit, - - /** Computes SkMatrix that maintains source SkRect aspect ratio, mapping source SkRect - width or height to destination SkRect. Aligns mapping to right and bottom - edges of destination SkRect. - */ - kEnd_ScaleToFit, + kFill_ScaleToFit, //!< scales in x and y to fill destination SkRect + kStart_ScaleToFit, //!< scales and aligns to left and top + kCenter_ScaleToFit, //!< scales and aligns to center + kEnd_ScaleToFit, //!< scales and aligns to right and bottom }; /** Sets SkMatrix to scale and translate src SkRect to dst SkRect. stf selects whether @@ -1452,9 +1433,11 @@ public: return this->mapRect(rect, *rect); } - /** - * Map the rectangle though the matrix, and return the bounds of the transformed points. - */ + /** Returns bounds of src corners mapped by SkMatrix. + + @param src rectangle to map + @return mapped bounds + */ SkRect mapRect(const SkRect& src) const { SkRect dst; (void)this->mapRect(&dst, src); diff --git a/include/core/SkPaint.h b/include/core/SkPaint.h index 6c60fc3587..883e5c610e 100644 --- a/include/core/SkPaint.h +++ b/include/core/SkPaint.h @@ -172,36 +172,10 @@ public: as the font engine. */ enum Hinting { - /** Leaves glyph outlines unchanged from their native representation. - With FreeType, this is equivalent to the FT_LOAD_NO_HINTING - bit-field constant supplied to FT_Load_Glyph, which indicates that the vector - outline being loaded should not be fitted to the pixel grid but simply scaled - to 26.6 fractional pixels. - */ - kNo_Hinting = 0, - - /** Modifies glyph outlines minimally to improve constrast. - With FreeType, this is equivalent in spirit to the - FT_LOAD_TARGET_LIGHT value supplied to FT_Load_Glyph. It chooses a - lighter hinting algorithm for non-monochrome modes. - Generated glyphs may be fuzzy but better resemble their original shape. - */ - kSlight_Hinting = 1, - - /** Modifies glyph outlines to improve constrast. This is the default. - With FreeType, this supplies FT_LOAD_TARGET_NORMAL to FT_Load_Glyph, - choosing the default hinting algorithm, which is optimized for standard - gray-level rendering. - */ - kNormal_Hinting = 2, - - /** Modifies glyph outlines for maxiumum constrast. With FreeType, this selects - FT_LOAD_TARGET_LCD or FT_LOAD_TARGET_LCD_V if kLCDRenderText_Flag is set. - FT_LOAD_TARGET_LCD is a variant of FT_LOAD_TARGET_NORMAL optimized for - horizontally decimated LCD displays; FT_LOAD_TARGET_LCD_V is a - variant of FT_LOAD_TARGET_NORMAL optimized for vertically decimated LCD displays. - */ - kFull_Hinting = 3, + kNo_Hinting = 0, //!< glyph outlines unchanged + kSlight_Hinting = 1, //!< minimal modification to improve constrast + kNormal_Hinting = 2, //!< glyph outlines modified to improve constrast + kFull_Hinting = 3, //!< modifies glyph outlines for maximum constrast }; /** Returns level of glyph outline adjustment. @@ -236,15 +210,13 @@ public: 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 - - /** mask of all Flags, including private flags and flags reserved for future use */ - kAllFlags = 0xFFFF, + kAllFlags = 0xFFFF, //!< mask of all Flags }; #ifdef SK_BUILD_FOR_ANDROID_FRAMEWORK enum ReserveFlags { - kUnderlineText_ReserveFlag = 0x08, //!< deprecated - kStrikeThruText_ReserveFlag = 0x10, //!< deprecated + kUnderlineText_ReserveFlag = 0x08, //!< to be deprecated soon + kStrikeThruText_ReserveFlag = 0x10, //!< to be deprecated soon }; #endif @@ -444,20 +416,11 @@ public: */ void setFakeBoldText(bool fakeBoldText); - /** Returns if character spacing may be adjusted by the hinting difference. - - Equivalent to getFlags() masked with kDevKernText_Flag. - - @return kDevKernText_Flag state + /** Deprecated. */ bool isDevKernText() const { return false; } - /** Requests, but does not require, to use hinting to adjust glyph spacing. - - Sets kDevKernText_Flag if devKernText is true. - Clears kDevKernText_Flag if devKernText is false. - - @param devKernText setting for devKernText + /** Deprecated. */ void setDevKernText(bool) { } @@ -489,34 +452,12 @@ public: a fill draw. */ enum Style { - /** Set to fill geometry. - Applies to SkRect, SkRegion, SkRRect, circles, ovals, SkPath, and text. - SkBitmap, SkImage, patches, SkRegion, sprites, and vertices are painted as if - kFill_Style is set, and ignore the set Style. - The FillType specifies additional rules to fill the area outside the path edge, - and to create an unfilled hole inside the shape. - Style is set to kFill_Style by default. - */ - kFill_Style, - - /** Set to stroke geometry. - Applies to SkRect, SkRegion, SkRRect, arcs, circles, ovals, SkPath, and text. - Arcs, lines, and points, are always drawn as if kStroke_Style is set, - and ignore the set Style. - The stroke construction is unaffected by the FillType. - */ - kStroke_Style, - - /** Set to stroke and fill geometry. - Applies to SkRect, SkRegion, SkRRect, circles, ovals, SkPath, and text. - SkPath is treated as if it is set to SkPath::kWinding_FillType, - and the set FillType is ignored. - */ - kStrokeAndFill_Style, + kFill_Style, //!< set to fill geometry + kStroke_Style, //!< set to stroke geometry + kStrokeAndFill_Style, //!< sets to stroke and fill geometry }; - /** The number of different Style values defined. - May be used to verify that Style is a legal value. + /** May be used to verify that SkPaint::Style is a legal value. */ static constexpr int kStyleCount = kStrokeAndFill_Style + 1; @@ -567,10 +508,10 @@ public: /** Sets color used when drawing solid fills. The color components range from 0 to 255. The color is unpremultiplied; alpha sets the transparency independent of RGB. - @param a amount of color alpha, from fully transparent (0) to fully opaque (255) - @param r amount of color rgb red, from no red (0) to full red (255) - @param g amount of color rgb green, from no green (0) to full green (255) - @param b amount of color rgb blue, from no blue (0) to full blue (255) + @param a amount of alpha, from fully transparent (0) to fully opaque (255) + @param r amount of red, from no red (0) to full red (255) + @param g amount of green, from no green (0) to full green (255) + @param b amount of blue, from no blue (0) to full blue (255) */ void setARGB(U8CPU a, U8CPU r, U8CPU g, U8CPU b); @@ -607,28 +548,15 @@ public: Cap draws at the beginning and end of an open path contour. */ enum Cap { - kButt_Cap, //!< Does not extend the stroke past the beginning or the end. - - /** Adds a circle with a diameter equal to stroke width at the beginning - and end. - */ - kRound_Cap, - - /** Adds a square with sides equal to stroke width at the beginning - and end. The square sides are parallel to the initial and final direction - of the stroke. - */ - kSquare_Cap, - kLast_Cap = kSquare_Cap, //!< Equivalent to the largest value for Cap. - - /** Equivalent to kButt_Cap. - Cap is set to kButt_Cap by default. - */ - kDefault_Cap = kButt_Cap, + kButt_Cap, //!< no stroke extension + kRound_Cap, //!< adds circle + kSquare_Cap, //!< adds square + kLast_Cap = kSquare_Cap, //!< largest Cap value + kDefault_Cap = kButt_Cap, //!< equivalent to kButt_Cap }; - /** The number of different SkPaint::Cap values defined. - May be used to verify that SkPaint::Cap is a legal value.*/ + /** May be used to verify that SkPaint::Cap is a legal value. + */ static constexpr int kCapCount = kLast_Cap + 1; /** \enum SkPaint::Join @@ -645,24 +573,15 @@ public: not necessarily include circles at each connected segment. */ enum Join { - /** Extends the outside corner to the extent allowed by miter limit. - If the extension exceeds miter limit, kBevel_Join is used instead. - */ - kMiter_Join, - - /** Adds a circle with a diameter of stroke width at the sharp corner. */ - kRound_Join, - kBevel_Join, //!< Connects the outside edges of the sharp corner. - kLast_Join = kBevel_Join, //!< Equivalent to the largest value for Join. - - /** Equivalent to kMiter_Join. - Join is set to kMiter_Join by default. - */ - kDefault_Join = kMiter_Join, + kMiter_Join, //!< extends to miter limit + kRound_Join, //!< adds circle + kBevel_Join, //!< connects outside edges + kLast_Join = kBevel_Join, //!< equivalent to the largest value for Join + kDefault_Join = kMiter_Join, //!< equivalent to kMiter_Join }; - /** The number of different SkPaint::Join values defined. - May be used to verify that SkPaint::Join is a legal value.*/ + /** 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. @@ -930,21 +849,14 @@ public: Align defaults to kLeft_Align. */ enum Align { - /** Leaves the glyph at the position computed by the font offset by the text position. */ - kLeft_Align, - - /** Moves the glyph half its width if Flags has kVerticalText_Flag clear, and - half its height if Flags has kVerticalText_Flag set. - */ - kCenter_Align, - - /** Moves the glyph by its width if Flags has kVerticalText_Flag clear, - and by its height if Flags has kVerticalText_Flag set. - */ - kRight_Align, + kLeft_Align, //!< positions glyph by computed font offset + kCenter_Align, //!< centers line of glyphs by its width or height + kRight_Align, //!< moves lines of glyphs by its width or height }; - static constexpr int kAlignCount = 3; //!< The number of different Align values defined. + /** May be used to verify that align is a legal value. + */ + static constexpr int kAlignCount = 3; /** Returns SkPaint::Align. Returns kLeft_Align if SkPaint::Align has not been set. @@ -1021,10 +933,10 @@ public: TextEncoding is set to kUTF8_TextEncoding by default. */ enum TextEncoding { - kUTF8_TextEncoding, //!< Uses bytes to represent UTF-8 or ASCII. - kUTF16_TextEncoding, //!< Uses two byte words to represent most of Unicode. - kUTF32_TextEncoding, //!< Uses four byte words to represent all of Unicode. - kGlyphID_TextEncoding, //!< Uses two byte words to represent glyph indices. + kUTF8_TextEncoding, //!< uses bytes to represent UTF-8 or ASCII + kUTF16_TextEncoding, //!< uses two byte words to represent most of Unicode + kUTF32_TextEncoding, //!< uses four byte words to represent all of Unicode + kGlyphID_TextEncoding, //!< uses two byte words to represent glyph indices }; /** Returns SkPaint::TextEncoding. @@ -1069,95 +981,28 @@ public: 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. - kStrikeoutThicknessIsValid_Flag = 1 << 2, //!< Set if fStrikeoutThickness is valid. - kStrikeoutPositionIsValid_Flag = 1 << 3, //!< Set if fStrikeoutPosition is valid. + kUnderlineThicknessIsValid_Flag = 1 << 0, //!< set if fUnderlineThickness is valid + kUnderlinePositionIsValid_Flag = 1 << 1, //!< set if fUnderlinePosition is valid + kStrikeoutThicknessIsValid_Flag = 1 << 2, //!< set if fStrikeoutThickness is valid + kStrikeoutPositionIsValid_Flag = 1 << 3, //!< set if fStrikeoutPosition is valid }; - uint32_t fFlags; //!< fFlags is set when underline metrics are valid. - - /** Greatest extent above the baseline for any glyph. - Typically less than zero. - */ - SkScalar fTop; - - /** Recommended distance above the baseline to reserve for a line of text. - Typically less than zero. - */ - SkScalar fAscent; - - /** Recommended distance below the baseline to reserve for a line of text. - Typically greater than zero. - */ - SkScalar fDescent; - - /** Greatest extent below the baseline for any glyph. - Typically greater than zero. - */ - SkScalar fBottom; - - /** Recommended distance to add between lines of text. - Typically greater than or equal to zero. - */ - SkScalar fLeading; - - /** Average character width, if it is available. - Zero if no average width is stored in the font. - */ - SkScalar fAvgCharWidth; - - SkScalar fMaxCharWidth; //!< Maximum character width. - - /** Minimum bounding box x value for all glyphs. - Typically less than zero. - */ - SkScalar fXMin; - - /** Maximum bounding box x value for all glyphs. - Typically greater than zero. - */ - SkScalar fXMax; - - /** Height of a lower-case 'x'. - May be zero if no lower-case height is stored in the font. - */ - SkScalar fXHeight; - - /** Height of an upper-case letter. - May be zero if no upper-case height is stored in the font. - */ - SkScalar fCapHeight; - - /** Underline thickness. - - If the metric is valid, the kUnderlineThicknessIsValid_Flag is set in fFlags. - If kUnderlineThicknessIsValid_Flag is clear, fUnderlineThickness is zero. - */ - SkScalar fUnderlineThickness; - - /** Position of the top of the underline stroke relative to the baseline. - Typically positive when valid. - - If the metric is valid, the kUnderlinePositionIsValid_Flag is set in fFlags. - If kUnderlinePositionIsValid_Flag is clear, fUnderlinePosition is zero. - */ - SkScalar fUnderlinePosition; - - /** Strikeout thickness. - - If the metric is valid, the kStrikeoutThicknessIsValid_Flag is set in fFlags. - If kStrikeoutThicknessIsValid_Flag is clear, fStrikeoutThickness is zero. - */ - SkScalar fStrikeoutThickness; - - /** Position of the bottom of the strikeout stroke relative to the baseline. - Typically negative when valid. - - If the metric is valid, the kStrikeoutPositionIsValid_Flag is set in fFlags. - If kStrikeoutPositionIsValid_Flag is clear, fStrikeoutPosition is zero. - */ - SkScalar fStrikeoutPosition; + uint32_t fFlags; //!< is set to FontMetricsFlags when metrics are valid + SkScalar fTop; //!< extent above baseline + SkScalar fAscent; //!< distance to reserve above baseline + SkScalar fDescent; //!< distance to reserve below baseline + SkScalar fBottom; //!< extent below baseline + SkScalar fLeading; //!< distance to add between lines + SkScalar fAvgCharWidth; //!< average character width + SkScalar fMaxCharWidth; //!< maximum character width + SkScalar fXMin; //!< minimum x + SkScalar fXMax; //!< maximum x + SkScalar fXHeight; //!< height of lower-case 'x' + SkScalar fCapHeight; //!< height of an upper-case letter + SkScalar fUnderlineThickness; //!< underline thickness + SkScalar fUnderlinePosition; //!< underline position relative to baseline + SkScalar fStrikeoutThickness; //!< strikeout thickness + SkScalar fStrikeoutPosition; //!< strikeout position relative to baseline /** If SkPaint::FontMetrics has a valid underline thickness, return true, and set thickness to that value. If the underline thickness is not valid, @@ -1515,7 +1360,7 @@ public: /** Returns true if SkPaint prevents all drawing; otherwise, the SkPaint may or may not allow drawing. - Returns true if, for example, SkBlendMode combined with color alpha computes a + Returns true if, for example, SkBlendMode combined with alpha computes a new alpha of zero. @return true if SkPaint prevents all drawing @@ -1542,15 +1387,14 @@ public: should not rely on storage being set to the result, but should always use the returned value. It is legal for orig and storage to be the same SkRect. - e.g. - if (paint.canComputeFastBounds()) { - SkRect r, storage; - path.computeBounds(&r, SkPath::kFast_BoundsType); - const SkRect& fastR = paint.computeFastBounds(r, &storage); - if (canvas->quickReject(fastR, ...)) { - // don't draw the path - } + For example: + if (!path.isInverseFillType() && paint.canComputeFastBounds()) { + SkRect storage; + if (canvas->quickReject(paint.computeFastBounds(path.getBounds(), &storage))) { + return; // do not draw the path + } } + // draw the path @param orig geometry modified by SkPaint when drawn @param storage computed bounds of geometry; may not be nullptr diff --git a/include/core/SkPath.h b/include/core/SkPath.h index 3f1cb97fe9..20bcc5179b 100644 --- a/include/core/SkPath.h +++ b/include/core/SkPath.h @@ -51,8 +51,8 @@ public: travel counterclockwise. */ enum Direction { - kCW_Direction, //!< Contour travels in a clockwise direction - kCCW_Direction, //!< Contour travels in a counterclockwise direction + kCW_Direction, //!< contour travels clockwise + kCCW_Direction, //!< contour travels counterclockwise }; /** By default, SkPath has no verbs, no SkPoint, and no weights. @@ -161,17 +161,10 @@ public: kInverseEvenOdd_FillType fills where the number of contour edges is even. */ enum FillType { - /** Specifies fill as area is enclosed by a non-zero sum of contour directions. */ - kWinding_FillType, - - /** Specifies fill as area enclosed by an odd number of contours. */ - kEvenOdd_FillType, - - /** Specifies fill as area is enclosed by a zero sum of contour directions. */ - kInverseWinding_FillType, - - /** Specifies fill as area enclosed by an even number of contours. */ - kInverseEvenOdd_FillType, + kWinding_FillType, //!< is enclosed by a non-zero sum of contour directions + kEvenOdd_FillType, //!< is enclosed by an odd number of contours + kInverseWinding_FillType, //!< is enclosed by a zero sum of contour directions + kInverseEvenOdd_FillType, //!< is enclosed by an even number of contours }; /** Returns FillType, the rule used to fill SkPath. FillType of a new SkPath is @@ -219,11 +212,9 @@ public: if needed by destination SkSurface. */ enum Convexity : uint8_t { - kUnknown_Convexity, //!< Indicates Convexity has not been determined. - - /** SkPath has one contour made of a simple geometry without indentations. */ - kConvex_Convexity, - kConcave_Convexity, //!< SkPath has more than one contour, or a geometry with indentations. + kUnknown_Convexity, //!< indicates Convexity has not been determined + kConvex_Convexity, //!< one contour made of a simple geometry without indentations + kConcave_Convexity, //!< more than one contour, or a geometry with indentations }; /** Computes SkPath::Convexity if required, and returns stored value. @@ -1169,15 +1160,8 @@ public: the last contour or start a new contour. */ enum AddPathMode { - /** Since SkPath verb array begins with kMove_Verb if src is not empty, this - starts a new contour. - */ - 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, SkPoint, and conic weights. - */ - kExtend_AddPathMode, + kAppend_AddPathMode, //!< appended to destination unaltered + kExtend_AddPathMode, //!< add line if prior contour is not closed }; /** Append src to SkPath, offset by (dx, dy). @@ -1297,12 +1281,10 @@ public: instance, if SkPath only contains lines, only the kLine_SegmentMask bit is set. */ enum SegmentMask { - kLine_SegmentMask = 1 << 0, //!< Set if verb array contains kLine_Verb. - - /** Set if verb array contains kQuad_Verb. Note that conicTo() may add a quad. */ - kQuad_SegmentMask = 1 << 1, - kConic_SegmentMask = 1 << 2, //!< Set if verb array contains kConic_Verb. - kCubic_SegmentMask = 1 << 3, //!< Set if verb array contains kCubic_Verb. + kLine_SegmentMask = 1 << 0, //!< contains one or more lines + kQuad_SegmentMask = 1 << 1, //!< contains one or more quads + kConic_SegmentMask = 1 << 2, //!< contains one or more conics + kCubic_SegmentMask = 1 << 3, //!< contains one or more cubics }; /** Returns a mask, where each set bit corresponds to a SegmentMask constant @@ -1320,37 +1302,19 @@ public: manage contour, and terminate SkPath. */ enum Verb { - kMove_Verb, //!< Starts new contour at next SkPoint. - - /** Adds line from last point to next SkPoint. - Line is a straight segment from SkPoint to SkPoint. - */ - kLine_Verb, - - /** Adds quad from last point, using control SkPoint, and end SkPoint. - Quad is a parabolic section within tangents from last point to control SkPoint, - and control SkPoint to end SkPoint. - */ - kQuad_Verb, - - /** Adds conic from last point, using control SkPoint, end SkPoint, and conic weight. - Conic is a elliptical, parabolic, or hyperbolic section within tangents - from last point to control SkPoint, and control SkPoint to end SkPoint, constrained - by conic weight. conic weight less than one is elliptical; equal to one is - parabolic (and identical to Quad); greater than one hyperbolic. - */ - kConic_Verb, - - /** 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. - */ - kCubic_Verb, - kClose_Verb, //!< Closes contour, connecting last point to kMove_Verb SkPoint. - kDone_Verb, //!< Terminates SkPath. Not in verb array, but returned by SkPath iterator. + kMove_Verb, //!< starts new contour at next SkPoint + kLine_Verb, //!< adds line from last point to next SkPoint + kQuad_Verb, //!< adds quad from last point + kConic_Verb, //!< adds conic from last point + kCubic_Verb, //!< adds cubic from last point + kClose_Verb, //!< closes contour + kDone_Verb, //!< terminates SkPath }; /** \class SkPath::Iter + Iterates through verb array, and associated SkPoint array and conic weight. + Provides options to treat open contours as closed, and to ignore + degenerate data. */ class SK_API Iter { public: @@ -1452,6 +1416,8 @@ public: }; /** \class SkPath::RawIter + Iterates through verb array, and associated SkPoint array and conic weight. + verb array, SkPoint array, and conic weight are returned unaltered. */ class SK_API RawIter { public: @@ -1530,7 +1496,7 @@ public: Set dumpAsHex true to generate exact binary representations of floating point numbers used in SkPoint array and conic weights. - @param stream writable SkStream receiving SkPath text representation; may be nullptr + @param stream writable SkWStream 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 */ diff --git a/include/core/SkPoint.h b/include/core/SkPoint.h index e16d1e3a42..ffb6eef142 100644 --- a/include/core/SkPoint.h +++ b/include/core/SkPoint.h @@ -16,12 +16,11 @@ 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. - - int32_t fY; //!< y-axis value used by SkIPoint. + int32_t fX; //!< x-axis value + int32_t fY; //!< y-axis value /** Sets fX to x, fY to y. @@ -147,19 +146,11 @@ struct SkPoint; typedef SkPoint SkVector; /** \struct SkPoint - SkPoint holds two 32 bit floating point coordinates. + SkPoint holds two 32-bit floating point coordinates. */ struct SK_API SkPoint { - - /** x-axis value used by both SkPoint and vector. May contain any value, including - infinities and NaN. - */ - SkScalar fX; - - /** y-axis value used by both SkPoint and vector. May contain any value, including - infinities and NaN. - */ - SkScalar fY; + SkScalar fX; //!< x-axis value + SkScalar fY; //!< y-axis value /** Sets fX to x, fY to y. Used both to set SkPoint and vector. diff --git a/include/core/SkRect.h b/include/core/SkRect.h index 920572f317..c260dacffd 100644 --- a/include/core/SkRect.h +++ b/include/core/SkRect.h @@ -16,33 +16,17 @@ struct SkRect; /** \struct SkIRect - SkIRect holds four 32 bit integer coordinates describing the upper and + SkIRect holds four 32-bit integer coordinates describing the upper and lower bounds of a rectangle. SkIRect may be created from outer bounds or from position, width, and height. SkIRect describes an area; if its right is less than or equal to its left, or if its bottom is less than or equal to its top, it is considered empty. */ struct SK_API SkIRect { - - /** May contain any value. The smaller of the horizontal values when sorted. - When equal to or greater than fRight, SkIRect is empty. - */ - int32_t fLeft; - - /** May contain any value. The smaller of the horizontal values when sorted. - When equal to or greater than fBottom, SkIRect is empty. - */ - int32_t fTop; - - /** May contain any value. The larger of the vertical values when sorted. - When equal to or less than fLeft, SkIRect is empty. - */ - int32_t fRight; - - /** May contain any value. The larger of the vertical values when sorted. - When equal to or less than fTop, SkIRect is empty. - */ - int32_t fBottom; + int32_t fLeft; //!< smaller x-axis bounds + int32_t fTop; //!< smaller y-axis bounds + int32_t fRight; //!< larger x-axis bounds + int32_t fBottom; //!< larger y-axis bounds /** Returns constructed SkIRect set to (0, 0, 0, 0). Many other rectangles are empty; if left is equal to or greater than right, @@ -414,13 +398,17 @@ struct SK_API SkIRect { */ void outset(int32_t dx, int32_t dy) { this->inset(-dx, -dy); } - /** Adjust SkIRect by adding dL to fLeft, dT to fTop, dR to fRight and fB to fBottom. + /** Adjusts SkIRect by adding dL to fLeft, dT to fTop, dR to fRight, and dB to fBottom. If dL is positive, narrows SkIRect on the left. If negative, widens it on the left. If dT is positive, shrinks SkIRect on the top. If negative, lengthens it on the top. If dR is positive, narrows SkIRect on the right. If negative, widens it on the right. If dB is positive, shrinks SkIRect on the bottom. If negative, lengthens it on the bottom. + The resulting SkIRect is not checked for validity. Thus, if the resulting SkIRect left is + greater than right, the SkIRect will be considered empty. Call sort() after this call + if that is not the desired behavior. + @param dL offset added to fLeft @param dT offset added to fTop @param dR offset added to fRight @@ -685,26 +673,10 @@ struct SK_API SkIRect { its top, it is considered empty. */ struct SK_API SkRect { - - /** May contain any value, including infinities and NaN. The smaller of the - horizontal values when sorted. When equal to or greater than fRight, SkRect is empty. - */ - SkScalar fLeft; - - /** May contain any value, including infinities and NaN. The smaller of the - vertical values when sorted. When equal to or greater than fBottom, SkRect is empty. - */ - SkScalar fTop; - - /** May contain any value, including infinities and NaN. The larger of the - horizontal values when sorted. When equal to or less than fLeft, SkRect is empty. - */ - SkScalar fRight; - - /** May contain any value, including infinities and NaN. The larger of the - vertical values when sorted. When equal to or less than fTop, SkRect is empty. - */ - SkScalar fBottom; + SkScalar fLeft; //!< smaller x-axis bounds + SkScalar fTop; //!< smaller y-axis bounds + SkScalar fRight; //!< larger x-axis bounds + SkScalar fBottom; //!< larger y-axis bounds /** Returns constructed SkRect set to (0, 0, 0, 0). Many other rectangles are empty; if left is equal to or greater than right, @@ -976,7 +948,7 @@ struct SK_API SkRect { /** Returns four points in quad that enclose SkRect ordered as: top-left, top-right, bottom-right, bottom-left. - Consider adding param to control whether quad is CW or CCW. + Consider adding param to control whether quad is clockwise or counterclockwise. @param quad storage for corners of SkRect */ @@ -1103,10 +1075,12 @@ struct SK_API SkRect { */ bool setBoundsCheck(const SkPoint pts[], int count); - /** - * Like setBoundsCheck() but this does not check for finite/nonfinite values. If any of the - * points are nonfinite, then the bounds will also be nonfinite. - */ + /** Sets to bounds of SkPoint pts array with count entries. If any SkPoint in pts + contains infinity or NaN, all SkRect dimensions are set to NaN. + + @param pts SkPoint array + @param count entries in array + */ void setBoundsNoCheck(const SkPoint pts[], int count); /** Sets bounds to the smallest SkRect enclosing SkPoint p0 and p1. The result is diff --git a/include/core/SkSurface.h b/include/core/SkSurface.h index 83a59f14fb..149637413b 100644 --- a/include/core/SkSurface.h +++ b/include/core/SkSurface.h @@ -138,7 +138,7 @@ public: 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 + Internally, sets SkImageInfo to width, height, native color type, and kPremul_SkAlphaType. SkSurface is returned if width and height are greater than zero. @@ -391,26 +391,24 @@ public: ContentChangeMode members are parameters to notifyContentWillChange(). */ enum ContentChangeMode { - kDiscard_ContentChangeMode, //!< the surface is cleared or overwritten. - - /** If a snapshot has been generated, this copies the SkSurface contents. */ - kRetain_ContentChangeMode, + kDiscard_ContentChangeMode, //!< discards surface on change + kRetain_ContentChangeMode, //!< preserves surface on change }; /** 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? + 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 back-end object. - kFlushWrite_BackendHandleAccess, //!< Caller may write to the back-end object. - kDiscardWrite_BackendHandleAccess, //!< Caller must overwrite the entire back-end object. + kFlushRead_BackendHandleAccess, //!< back-end object is readable + kFlushWrite_BackendHandleAccess, //!< back-end object is writable + kDiscardWrite_BackendHandleAccess, //!< back-end object must be overwritten }; /** Deprecated. @@ -428,29 +426,27 @@ public: static const BackendHandleAccess kDiscardWrite_TextureHandleAccess = kDiscardWrite_BackendHandleAccess; - /** Retrieves the backend texture. If Surface has no backend texture, an invalid + /** Retrieves the back-end texture. If SkSurface has no back-end texture, an invalid object is returned. Call GrBackendTexture::isValid to determine if the result is valid. - The returned GrBackendTexture should be discarded if the Surface is drawn to or deleted. + The returned GrBackendTexture should be discarded if the SkSurface is drawn to or deleted. @param backendHandleAccess one of: kFlushRead_BackendHandleAccess, - kFlushWrite_BackendHandleAccess, - kDiscardWrite_BackendHandleAccess + kFlushWrite_BackendHandleAccess, kDiscardWrite_BackendHandleAccess @return GPU texture reference; invalid on failure */ GrBackendTexture getBackendTexture(BackendHandleAccess backendHandleAccess); - /** Retrieves the backend render target. If Surface has no backend render target, an invalid + /** Retrieves the back-end render target. If SkSurface has no back-end render target, an invalid object is returned. Call GrBackendRenderTarget::isValid to determine if the result is valid. - The returned GrBackendRenderTarget should be discarded if the Surface is drawn to + The returned GrBackendRenderTarget should be discarded if the SkSurface is drawn to or deleted. @param backendHandleAccess one of: kFlushRead_BackendHandleAccess, - kFlushWrite_BackendHandleAccess, - kDiscardWrite_BackendHandleAccess + kFlushWrite_BackendHandleAccess, kDiscardWrite_BackendHandleAccess @return GPU render target reference; invalid on failure */ GrBackendRenderTarget getBackendRenderTarget(BackendHandleAccess backendHandleAccess); @@ -486,7 +482,7 @@ public: /** Draws SkSurface contents to canvas, with its top-left corner at (x, y). - If SkPaint paint is not nullptr, apply SkColorFilter, color alpha, SkImageFilter, + If SkPaint paint is not nullptr, apply SkColorFilter, alpha, SkImageFilter, SkBlendMode, and SkDrawLooper. @param canvas SkCanvas drawn into |