diff options
| -rw-r--r-- | include/core/SkBitmap.h | 16 | ||||
| -rw-r--r-- | include/core/SkBlendMode.h | 97 | ||||
| -rw-r--r-- | include/core/SkCanvas.h | 205 | ||||
| -rw-r--r-- | include/core/SkImage.h | 5 | ||||
| -rw-r--r-- | include/core/SkImageInfo.h | 4 | ||||
| -rw-r--r-- | include/core/SkMatrix.h | 4 | ||||
| -rw-r--r-- | include/core/SkPaint.h | 67 | ||||
| -rw-r--r-- | include/core/SkPath.h | 94 | ||||
| -rw-r--r-- | include/core/SkPicture.h | 125 | ||||
| -rw-r--r-- | include/core/SkPoint.h | 4 | ||||
| -rw-r--r-- | include/core/SkRRect.h | 487 | ||||
| -rw-r--r-- | include/core/SkRect.h | 6 | ||||
| -rw-r--r-- | include/core/SkSurface.h | 4 |
13 files changed, 698 insertions, 420 deletions
diff --git a/include/core/SkBitmap.h b/include/core/SkBitmap.h index bc29151a24..521bb77ac8 100644 --- a/include/core/SkBitmap.h +++ b/include/core/SkBitmap.h @@ -6,7 +6,7 @@ */ /* Generated by tools/bookmaker from include/core/SkBitmap.h and docs/SkBitmap_Reference.bmh - on 2018-06-08 11:48:28. Additional documentation and examples can be found at: + on 2018-07-13 08:15:10. Additional documentation and examples can be found at: https://skia.org/user/api/SkBitmap_Reference You may edit either file directly. Structural changes to public interfaces require @@ -125,7 +125,7 @@ public: /** Returns pixel count in each row. Should be equal or less than: rowBytes() / info().bytesPerPixel(). - Maybe be less than pixelRef().width(). Will not exceed pixelRef().width() less + May be less than pixelRef().width(). Will not exceed pixelRef().width() less pixelRefOrigin().fX. @return pixel width in SkImageInfo @@ -207,7 +207,7 @@ public: */ bool empty() const { return fPixmap.info().isEmpty(); } - /** Return true if SkPixelRef is nullptr. + /** Returns true if SkPixelRef is nullptr. Does not check if width() or height() are zero; call drawsNothing() to check width(), height(), and SkPixelRef. @@ -216,7 +216,7 @@ public: */ bool isNull() const { return nullptr == fPixelRef; } - /** Return true if width() or height() are zero, or if SkPixelRef is nullptr. + /** Returns true if width() or height() are zero, or if SkPixelRef is nullptr. If true, SkBitmap has no effect when drawn or drawn into. @return true if drawing has no effect @@ -310,8 +310,8 @@ public: return SkAlphaTypeIsOpaque(this->alphaType()); } - /** If true, provides a hint to caller that pixels should not - be cached. Only true if setIsVolatile() has been called to mark as volatile. + /** Provides a hint to caller that pixels should not be cached. Only true if + setIsVolatile() has been called to mark as volatile. Volatile state is not shared by other bitmaps sharing the same SkPixelRef. @@ -1134,7 +1134,7 @@ public: bool writePixels(const SkPixmap& src, int x, int y, SkTransferFunctionBehavior behavior); #ifdef SK_BUILD_FOR_ANDROID_FRAMEWORK - /** Android framework only. + /** For use by Android framework only. @return true if setHasHardwareMipMap() has been called with true */ @@ -1142,7 +1142,7 @@ public: return (fFlags & kHasHardwareMipMap_Flag) != 0; } - /** Android framework only. + /** For use by Android framework only. @param hasHardwareMipMap sets state */ diff --git a/include/core/SkBlendMode.h b/include/core/SkBlendMode.h index 5b161f2d94..cf1cfb29e5 100644 --- a/include/core/SkBlendMode.h +++ b/include/core/SkBlendMode.h @@ -5,54 +5,71 @@ * found in the LICENSE file. */ +/* Generated by tools/bookmaker from include/core/SkBlendMode.h and docs/SkBlendMode_Reference.bmh + on 2018-07-13 08:15:10. Additional documentation and examples can be found at: + https://skia.org/user/api/SkBlendMode_Reference + + You may edit either file directly. Structural changes to public interfaces require + editing both files. After editing docs/SkBlendMode_Reference.bmh, run: + bookmaker -b docs -i include/core/SkBlendMode.h -p + to create an updated version of this file. + */ + #ifndef SkBlendMode_DEFINED #define SkBlendMode_DEFINED #include "SkTypes.h" enum class SkBlendMode { - kClear, //!< [0, 0] - kSrc, //!< [Sa, Sc] - kDst, //!< [Da, Dc] - kSrcOver, //!< [Sa + Da * (1 - Sa), Sc + Dc * (1 - Sa)] - kDstOver, //!< [Da + Sa * (1 - Da), Dc + Sc * (1 - Da)] - kSrcIn, //!< [Sa * Da, Sc * Da] - kDstIn, //!< [Da * Sa, Dc * Sa] - kSrcOut, //!< [Sa * (1 - Da), Sc * (1 - Da)] - kDstOut, //!< [Da * (1 - Sa), Dc * (1 - Sa)] - kSrcATop, //!< [Da, Sc * Da + Dc * (1 - Sa)] - kDstATop, //!< [Sa, Dc * Sa + Sc * (1 - Da)] - kXor, //!< [Sa + Da - 2 * Sa * Da, Sc * (1 - Da) + Dc * (1 - Sa)] - kPlus, //!< [Sa + Da, Sc + Dc] - kModulate, // multiplies all components (= alpha and color) - - // Following blend modes are defined in the CSS Compositing standard: - // https://dvcs.w3.org/hg/FXTF/rawfile/tip/compositing/index.html#blending - kScreen, - kLastCoeffMode = kScreen, - - kOverlay, - kDarken, - kLighten, - kColorDodge, - kColorBurn, - kHardLight, - kSoftLight, - kDifference, - kExclusion, - kMultiply, - kLastSeparableMode = kMultiply, - - kHue, - kSaturation, - kColor, - kLuminosity, - kLastMode = kLuminosity, + kClear, //!< replaces destination with zero: fully transparent + kSrc, //!< replaces destination + kDst, //!< preserves destination + kSrcOver, //!< source over destination + kDstOver, //!< destination over source + kSrcIn, //!< source trimmed inside destination + kDstIn, //!< destination trimmed by source + kSrcOut, //!< source trimmed outside destination + kDstOut, //!< destination trimmed outside source + kSrcATop, //!< source inside destination blended with destination + kDstATop, //!< destination inside source blended with source + kXor, //!< each of source and destination trimmed outside the other + kPlus, //!< sum of colors + kModulate, //!< product of premultiplied colors; darkens destination + kScreen, //!< multiply inverse of pixels, inverting result; brightens destination + kLastCoeffMode = kScreen, //!< last porter duff blend mode + kOverlay, //!< multiply or screen, depending on destination + kDarken, //!< darker of source and destination + kLighten, //!< lighter of source and destination + kColorDodge, //!< brighten destination to reflect source + kColorBurn, //!< darken destination to reflect source + kHardLight, //!< multiply or screen, depending on source + kSoftLight, //!< lighten or darken, depending on source + kDifference, //!< subtract darker from lighter with higher contrast + kExclusion, //!< subtract darker from lighter with lower contrast + kMultiply, //!< multiply source with destination, darkening image + kLastSeparableMode = kMultiply, //!< last blend mode operating separately on components + kHue, //!< hue of source with saturation and luminosity of destination + kSaturation, //!< saturation of source with hue and luminosity of destination + kColor, //!< hue and saturation of source with luminosity of destination + kLuminosity, //!< luminosity of source with hue and saturation of destination + kLastMode = kLuminosity, //!< last valid value }; -/** - * Return the (c-string) name of the blendmode. - */ +/** Returns name of blendMode as null-terminated C string. + + @param blendMode one of: + SkBlendMode::kClear, SkBlendMode::kSrc, SkBlendMode::kDst, SkBlendMode::kSrcOver, + SkBlendMode::kDstOver, SkBlendMode::kSrcIn, SkBlendMode::kDstIn, + SkBlendMode::kSrcOut, SkBlendMode::kDstOut, SkBlendMode::kSrcATop, + SkBlendMode::kDstATop, SkBlendMode::kXor, SkBlendMode::kPlus, + SkBlendMode::kModulate, SkBlendMode::kScreen, SkBlendMode::kOverlay, + SkBlendMode::kDarken, SkBlendMode::kLighten, SkBlendMode::kColorDodge, + SkBlendMode::kColorBurn, SkBlendMode::kHardLight, SkBlendMode::kSoftLight, + SkBlendMode::kDifference, SkBlendMode::kExclusion, SkBlendMode::kMultiply, + SkBlendMode::kHue, SkBlendMode::kSaturation, SkBlendMode::kColor, + SkBlendMode::kLuminosity + @return C string +*/ SK_API const char* SkBlendMode_Name(SkBlendMode blendMode); #endif diff --git a/include/core/SkCanvas.h b/include/core/SkCanvas.h index bd9591117e..d89dd52547 100644 --- a/include/core/SkCanvas.h +++ b/include/core/SkCanvas.h @@ -6,7 +6,7 @@ */ /* Generated by tools/bookmaker from include/core/SkCanvas.h and docs/SkCanvas_Reference.bmh - on 2018-07-03 11:34:22. Additional documentation and examples can be found at: + on 2018-07-13 08:15:10. Additional documentation and examples can be found at: https://skia.org/user/api/SkCanvas_Reference You may edit either file directly. Structural changes to public interfaces require @@ -168,7 +168,7 @@ public: */ explicit SkCanvas(sk_sp<SkBaseDevice> device); - /** Construct a canvas that draws into bitmap. + /** Constructs a canvas that draws into bitmap. Sets SkSurfaceProps::kLegacyFontHost_InitType in constructed SkSurface. SkBitmap is copied so that subsequently editing bitmap will not affect @@ -187,7 +187,7 @@ public: kLegacy, //!< placeholder }; - /** Android framework only. + /** For use by Android framework only. @param bitmap specifies a bitmap for the canvas to draw into @param behavior specializes this constructor; value is unused @@ -196,7 +196,7 @@ public: SkCanvas(const SkBitmap& bitmap, ColorBehavior behavior); #endif - /** Construct a canvas that draws into bitmap. + /** Constructs a canvas that draws into bitmap. Use props to match the device characteristics, like LCD striping. bitmap is copied so that subsequently editing bitmap will not affect @@ -229,9 +229,8 @@ public: */ SkImageInfo imageInfo() const; - /** If SkCanvas is associated with raster surface or - GPU surface, copies SkSurfaceProps and returns true. Otherwise, - return false and leave props unchanged. + /** Copies SkSurfaceProps, if SkCanvas is associated with raster surface or + GPU surface, and returns true. Otherwise, returns false and leave props unchanged. @param props storage for writable SkSurfaceProps @return true if SkSurfaceProps was copied @@ -492,8 +491,8 @@ public: bool writePixels(const SkBitmap& bitmap, int x, int y); /** Saves SkMatrix and clip. - Calling restore() discards changes to SkMatrix and clip, restoring the SkMatrix and clip to - their state when save() was called. + Calling restore() discards changes to SkMatrix and clip, + restoring the SkMatrix and clip to their state when save() was called. SkMatrix may be changed by translate(), scale(), rotate(), skew(), concat(), setMatrix(), and resetMatrix(). Clip may be changed by clipRect(), clipRRect(), clipPath(), clipRegion(). @@ -580,8 +579,8 @@ public: /** Saves SkMatrix and clip, and allocates SkBitmap for subsequent drawing. - Calling restore() discards changes to SkMatrix and clip, and blends layer with alpha opacity - onto prior layer. + Calling restore() discards changes to SkMatrix and clip, + 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(), @@ -726,8 +725,8 @@ public: */ int saveLayer(const SaveLayerRec& layerRec); - /** Removes changes to SkMatrix and clip since SkCanvas state was last saved. - The state is removed from the stack. + /** Removes changes to SkMatrix and clip since SkCanvas state was + last saved. The state is removed from the stack. Does nothing if the stack is empty. */ @@ -751,9 +750,9 @@ public: */ void restoreToCount(int saveCount); - /** Translate SkMatrix by dx along the x-axis and dy along the y-axis. + /** Translates SkMatrix by dx along the x-axis and dy along the y-axis. - Mathematically, replace SkMatrix with a translation matrix + Mathematically, replaces SkMatrix with a translation matrix premultiplied with SkMatrix. This has the effect of moving the drawing by (dx, dy) before transforming @@ -764,9 +763,9 @@ public: */ void translate(SkScalar dx, SkScalar dy); - /** Scale SkMatrix by sx on the x-axis and sy on the y-axis. + /** Scales SkMatrix by sx on the x-axis and sy on the y-axis. - Mathematically, replace SkMatrix with a scale matrix + Mathematically, replaces SkMatrix with a scale matrix premultiplied with SkMatrix. This has the effect of scaling the drawing by (sx, sy) before transforming @@ -777,9 +776,9 @@ public: */ void scale(SkScalar sx, SkScalar sy); - /** Rotate SkMatrix by degrees. Positive degrees rotates clockwise. + /** Rotates SkMatrix by degrees. Positive degrees rotates clockwise. - Mathematically, replace SkMatrix with a rotation matrix + Mathematically, replaces SkMatrix with a rotation matrix premultiplied with SkMatrix. This has the effect of rotating the drawing by degrees before transforming @@ -789,11 +788,11 @@ public: */ void rotate(SkScalar degrees); - /** Rotate SkMatrix by degrees about a point at (px, py). Positive degrees rotates + /** Rotates SkMatrix by degrees about a point at (px, py). Positive degrees rotates clockwise. - Mathematically, construct a rotation matrix. Premultiply the rotation matrix by - a translation matrix, then replace SkMatrix with the resulting matrix + Mathematically, constructs a rotation matrix; premultiplies the rotation matrix by + a translation matrix; then replaces SkMatrix with the resulting matrix premultiplied with SkMatrix. This has the effect of rotating the drawing about a given point before @@ -805,11 +804,11 @@ public: */ void rotate(SkScalar degrees, SkScalar px, SkScalar py); - /** Skew SkMatrix by sx on the x-axis and sy on the y-axis. A positive value of sx + /** Skews SkMatrix by sx on the x-axis and sy on the y-axis. A positive value of sx skews the drawing right as y-axis values increase; a positive value of sy skews the drawing down as x-axis values increase. - Mathematically, replace SkMatrix with a skew matrix premultiplied with SkMatrix. + Mathematically, replaces SkMatrix with a skew matrix premultiplied with SkMatrix. This has the effect of skewing the drawing by (sx, sy) before transforming the result with SkMatrix. @@ -819,7 +818,7 @@ public: */ void skew(SkScalar sx, SkScalar sy); - /** Replace SkMatrix with matrix premultiplied with existing SkMatrix. + /** Replaces SkMatrix with matrix premultiplied with existing SkMatrix. This has the effect of transforming the drawn geometry by matrix, before transforming the result with existing SkMatrix. @@ -828,7 +827,7 @@ public: */ void concat(const SkMatrix& matrix); - /** Replace SkMatrix with matrix. + /** Replaces SkMatrix with matrix. Unlike concat(), any prior matrix state is overwritten. @param matrix matrix to copy, replacing existing SkMatrix @@ -840,7 +839,7 @@ public: */ void resetMatrix(); - /** Replace clip with the intersection or difference of clip and rect, + /** Replaces clip with the intersection or difference of clip and rect, with an aliased or anti-aliased clip edge. rect is transformed by SkMatrix before it is combined with clip. @@ -850,7 +849,7 @@ public: */ void clipRect(const SkRect& rect, SkClipOp op, bool doAntiAlias); - /** Replace clip with the intersection or difference of clip and rect. + /** Replaces clip with the intersection or difference of clip and rect. Resulting clip is aliased; pixels are fully contained by the clip. rect is transformed by SkMatrix before it is combined with clip. @@ -861,7 +860,7 @@ public: this->clipRect(rect, op, false); } - /** Replace clip with the intersection of clip and rect. + /** Replaces clip with the intersection of clip and rect. Resulting clip is aliased; pixels are fully contained by the clip. rect is transformed by SkMatrix before it is combined with clip. @@ -885,7 +884,7 @@ public: */ void androidFramework_setDeviceClipRestriction(const SkIRect& rect); - /** Replace clip with the intersection or difference of clip and rrect, + /** Replaces clip with the intersection or difference of clip and rrect, with an aliased or anti-aliased clip edge. rrect is transformed by SkMatrix before it is combined with clip. @@ -896,7 +895,7 @@ public: */ void clipRRect(const SkRRect& rrect, SkClipOp op, bool doAntiAlias); - /** Replace clip with the intersection or difference of clip and rrect. + /** Replaces clip with the intersection or difference of clip and rrect. Resulting clip is aliased; pixels are fully contained by the clip. rrect is transformed by SkMatrix before it is combined with clip. @@ -907,7 +906,7 @@ public: this->clipRRect(rrect, op, false); } - /** Replace clip with the intersection of clip and rrect, + /** Replaces clip with the intersection of clip and rrect, with an aliased or anti-aliased clip edge. rrect is transformed by SkMatrix before it is combined with clip. @@ -918,7 +917,7 @@ public: this->clipRRect(rrect, SkClipOp::kIntersect, doAntiAlias); } - /** Replace clip with the intersection or difference of clip and path, + /** Replaces clip with the intersection or difference of clip and path, with an aliased or anti-aliased clip edge. SkPath::FillType determines if path describes the area inside or outside its contours; and if path contour overlaps itself or another path contour, whether the overlaps form part of the area. @@ -930,7 +929,7 @@ public: */ void clipPath(const SkPath& path, SkClipOp op, bool doAntiAlias); - /** Replace clip with the intersection or difference of clip and path. + /** Replaces clip with the intersection or difference of clip and path. Resulting clip is aliased; pixels are fully contained by the clip. SkPath::FillType determines if path describes the area inside or outside its contours; and if path contour overlaps @@ -945,7 +944,7 @@ public: this->clipPath(path, op, false); } - /** Replace clip with the intersection of clip and path. + /** Replaces clip with the intersection of clip and path. Resulting clip is aliased; pixels are fully contained by the clip. SkPath::FillType determines if path describes the area inside or outside its contours; and if path contour overlaps @@ -966,7 +965,7 @@ public: fAllowSimplifyClip = allow; } - /** Replace clip with the intersection or difference of clip and SkRegion deviceRgn. + /** Replaces clip with the intersection or difference of clip and SkRegion deviceRgn. Resulting clip is aliased; pixels are fully contained by the clip. deviceRgn is unaffected by SkMatrix. @@ -975,7 +974,7 @@ public: */ void clipRegion(const SkRegion& deviceRgn, SkClipOp op = SkClipOp::kIntersect); - /** Return true if SkRect rect, transformed by SkMatrix, can be quickly determined to be + /** Returns true if SkRect rect, transformed by SkMatrix, can be quickly determined to be outside of clip. May return false even though rect is outside of clip. Use to check if an area to be drawn is clipped out, to skip subsequent draw calls. @@ -985,7 +984,7 @@ public: */ bool quickReject(const SkRect& rect) const; - /** Return true if path, transformed by SkMatrix, can be quickly determined to be + /** Returns true if path, transformed by SkMatrix, can be quickly determined to be outside of clip. May return false even though path is outside of clip. Use to check if an area to be drawn is clipped out, to skip subsequent draw calls. @@ -995,7 +994,7 @@ public: */ bool quickReject(const SkPath& path) const; - /** Return bounds of clip, transformed by inverse of SkMatrix. If clip is empty, + /** Returns bounds of clip, transformed by inverse of SkMatrix. If clip is empty, return SkRect::MakeEmpty, where all SkRect sides equal zero. SkRect returned is outset by one to account for partial pixel coverage if clip @@ -1005,7 +1004,7 @@ public: */ SkRect getLocalClipBounds() const; - /** Return bounds of clip, transformed by inverse of SkMatrix. If clip is empty, + /** Returns bounds of clip, transformed by inverse of SkMatrix. If clip is empty, return false, and set bounds to SkRect::MakeEmpty, where all SkRect sides equal zero. bounds is outset by one to account for partial pixel coverage if clip @@ -1019,7 +1018,7 @@ public: return !bounds->isEmpty(); } - /** Return SkIRect bounds of clip, unaffected by SkMatrix. If clip is empty, + /** Returns SkIRect bounds of clip, unaffected by SkMatrix. If clip is empty, return SkRect::MakeEmpty, where all SkRect sides equal zero. Unlike getLocalClipBounds(), returned SkIRect is not outset. @@ -1028,7 +1027,7 @@ public: */ SkIRect getDeviceClipBounds() const; - /** Return SkIRect bounds of clip, unaffected by SkMatrix. If clip is empty, + /** Returns SkIRect bounds of clip, unaffected by SkMatrix. If clip is empty, return false, and set bounds to SkRect::MakeEmpty, where all SkRect sides equal zero. Unlike getLocalClipBounds(), bounds is not outset. @@ -1041,7 +1040,7 @@ public: return !bounds->isEmpty(); } - /** Fill clip with color color. + /** Fills clip with color color. mode determines how ARGB is combined with destination. @param color unpremultiplied ARGB @@ -1049,7 +1048,7 @@ public: */ void drawColor(SkColor color, SkBlendMode mode = SkBlendMode::kSrcOver); - /** Fill clip with color color using SkBlendMode::kSrc. + /** Fills clip with color color using SkBlendMode::kSrc. This has the effect of replacing all pixels contained by clip with color. @param color unpremultiplied ARGB @@ -1058,7 +1057,7 @@ public: this->drawColor(color, SkBlendMode::kSrc); } - /** Make SkCanvas contents undefined. Subsequent calls that read SkCanvas pixels, + /** Makes SkCanvas contents undefined. Subsequent calls that read SkCanvas pixels, such as drawing with SkBlendMode, return undefined results. discard() does not change clip or SkMatrix. @@ -1072,7 +1071,7 @@ public: */ void discard() { this->onDiscard(); } - /** Fill clip with SkPaint paint. SkPaint components SkMaskFilter, SkShader, + /** Fills clip with SkPaint paint. SkPaint components SkMaskFilter, SkShader, SkColorFilter, SkImageFilter, and SkBlendMode affect drawing; SkPathEffect in paint is ignored. @@ -1090,7 +1089,7 @@ public: kPolygon_PointMode, //!< draw the array of points as a open polygon }; - /** Draw pts using clip, SkMatrix and SkPaint paint. + /** Draws pts using clip, SkMatrix and SkPaint paint. count is the number of points; if count is less than one, has no effect. mode may be one of: kPoints_PointMode, kLines_PointMode, or kPolygon_PointMode. @@ -1121,7 +1120,7 @@ public: */ void drawPoints(PointMode mode, size_t count, const SkPoint pts[], const SkPaint& paint); - /** Draw point at (x, y) using clip, SkMatrix and SkPaint paint. + /** Draws point at (x, y) using clip, SkMatrix and SkPaint paint. The shape of point drawn depends on paint SkPaint::Cap. If paint is set to SkPaint::kRound_Cap, draw a circle of diameter @@ -1135,7 +1134,7 @@ public: */ void drawPoint(SkScalar x, SkScalar y, const SkPaint& paint); - /** Draw point p using clip, SkMatrix and SkPaint paint. + /** Draws point p using clip, SkMatrix and SkPaint paint. The shape of point drawn depends on paint SkPaint::Cap. If paint is set to SkPaint::kRound_Cap, draw a circle of diameter @@ -1176,7 +1175,7 @@ public: this->drawLine(p0.x(), p0.y(), p1.x(), p1.y(), paint); } - /** Draw SkRect rect using clip, SkMatrix, and SkPaint paint. + /** Draws SkRect rect using clip, SkMatrix, and SkPaint paint. In paint: SkPaint::Style determines if rectangle is stroked or filled; if stroked, SkPaint stroke width describes the line thickness, and SkPaint::Join draws the corners rounded or square. @@ -1186,7 +1185,7 @@ public: */ void drawRect(const SkRect& rect, const SkPaint& paint); - /** Draw SkIRect rect using clip, SkMatrix, and SkPaint paint. + /** Draws SkIRect rect using clip, SkMatrix, and SkPaint paint. In paint: SkPaint::Style determines if rectangle is stroked or filled; if stroked, SkPaint stroke width describes the line thickness, and SkPaint::Join draws the corners rounded or square. @@ -1200,7 +1199,7 @@ public: this->drawRect(r, paint); } - /** Draw SkRegion region using clip, SkMatrix, and SkPaint paint. + /** Draws SkRegion region using clip, SkMatrix, and SkPaint paint. In paint: SkPaint::Style determines if rectangle is stroked or filled; if stroked, SkPaint stroke width describes the line thickness, and SkPaint::Join draws the corners rounded or square. @@ -1210,7 +1209,7 @@ public: */ void drawRegion(const SkRegion& region, const SkPaint& paint); - /** Draw oval oval using clip, SkMatrix, and SkPaint. + /** Draws oval oval using clip, SkMatrix, and SkPaint. In paint: SkPaint::Style determines if oval is stroked or filled; if stroked, SkPaint stroke width describes the line thickness. @@ -1219,7 +1218,7 @@ public: */ void drawOval(const SkRect& oval, const SkPaint& paint); - /** Draw SkRRect rrect using clip, SkMatrix, and SkPaint paint. + /** Draws SkRRect rrect using clip, SkMatrix, and SkPaint paint. In paint: SkPaint::Style determines if rrect is stroked or filled; if stroked, SkPaint stroke width describes the line thickness. @@ -1231,7 +1230,7 @@ public: */ void drawRRect(const SkRRect& rrect, const SkPaint& paint); - /** Draw SkRRect outer and inner + /** Draws SkRRect outer and inner using clip, SkMatrix, and SkPaint paint. outer must contain inner or the drawing is undefined. In paint: SkPaint::Style determines if SkRRect is stroked or filled; @@ -1249,7 +1248,7 @@ public: */ void drawDRRect(const SkRRect& outer, const SkRRect& inner, const SkPaint& paint); - /** Draw circle at (cx, cy) with radius using clip, SkMatrix, and SkPaint paint. + /** Draws circle at (cx, cy) with radius using clip, SkMatrix, and SkPaint paint. If radius is zero or less, nothing is drawn. In paint: SkPaint::Style determines if circle is stroked or filled; if stroked, SkPaint stroke width describes the line thickness. @@ -1261,7 +1260,7 @@ public: */ void drawCircle(SkScalar cx, SkScalar cy, SkScalar radius, const SkPaint& paint); - /** Draw circle at center with radius using clip, SkMatrix, and SkPaint paint. + /** Draws circle at center with radius using clip, SkMatrix, and SkPaint paint. If radius is zero or less, nothing is drawn. In paint: SkPaint::Style determines if circle is stroked or filled; if stroked, SkPaint stroke width describes the line thickness. @@ -1274,7 +1273,7 @@ public: this->drawCircle(center.x(), center.y(), radius, paint); } - /** Draw arc using clip, SkMatrix, and SkPaint paint. + /** Draws arc using clip, SkMatrix, and SkPaint paint. Arc is part of oval bounded by oval, sweeping from startAngle to startAngle plus sweepAngle. startAngle and sweepAngle are in degrees. @@ -1297,7 +1296,7 @@ public: void drawArc(const SkRect& oval, SkScalar startAngle, SkScalar sweepAngle, bool useCenter, const SkPaint& paint); - /** Draw SkRRect bounded by SkRect rect, with corner radii (rx, ry) using clip, + /** Draws SkRRect bounded by SkRect rect, with corner radii (rx, ry) using clip, SkMatrix, and SkPaint paint. In paint: SkPaint::Style determines if SkRRect is stroked or filled; @@ -1314,7 +1313,7 @@ public: */ void drawRoundRect(const SkRect& rect, SkScalar rx, SkScalar ry, const SkPaint& paint); - /** Draw SkPath path using clip, SkMatrix, and SkPaint paint. + /** Draws SkPath path using clip, SkMatrix, and SkPaint paint. SkPath contains an array of path contour, each of which may be open or closed. In paint: SkPaint::Style determines if SkRRect is stroked or filled: @@ -1328,7 +1327,7 @@ public: */ void drawPath(const SkPath& path, const SkPaint& paint); - /** Draw SkImage image, with its top-left corner at (left, top), + /** Draws SkImage image, with its top-left corner at (left, top), using clip, SkMatrix, and optional SkPaint paint. If paint is supplied, apply SkColorFilter, alpha, SkImageFilter, SkBlendMode, @@ -1347,7 +1346,7 @@ public: void drawImage(const SkImage* image, SkScalar left, SkScalar top, const SkPaint* paint = nullptr); - /** Draw SkImage image, with its top-left corner at (left, top), + /** Draws SkImage image, with its top-left corner at (left, top), using clip, SkMatrix, and optional SkPaint paint. If SkPaint paint is supplied, apply SkColorFilter, alpha, SkImageFilter, @@ -1383,7 +1382,7 @@ public: kFast_SrcRectConstraint, //!< sample outside bounds; faster }; - /** Draw SkRect src of SkImage image, scaled and translated to fill SkRect dst. + /** Draws 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, alpha, SkImageFilter, @@ -1409,7 +1408,7 @@ public: const SkPaint* paint, SrcRectConstraint constraint = kStrict_SrcRectConstraint); - /** Draw SkIRect isrc of SkImage image, scaled and translated to fill SkRect dst. + /** Draws SkIRect isrc of SkImage image, scaled and translated to fill SkRect dst. Note that isrc is on integer pixel boundaries; dst may include fractional boundaries. Additionally transform draw using clip, SkMatrix, and optional SkPaint paint. @@ -1437,7 +1436,7 @@ public: const SkPaint* paint, SrcRectConstraint constraint = kStrict_SrcRectConstraint); - /** Draw SkImage image, scaled and translated to fill SkRect dst, using clip, SkMatrix, + /** Draws SkImage image, scaled and translated to fill SkRect dst, using clip, SkMatrix, and optional SkPaint paint. If SkPaint paint is supplied, apply SkColorFilter, alpha, SkImageFilter, @@ -1461,7 +1460,7 @@ public: void drawImageRect(const SkImage* image, const SkRect& dst, const SkPaint* paint, SrcRectConstraint constraint = kStrict_SrcRectConstraint); - /** Draw SkRect src of SkImage image, scaled and translated to fill SkRect dst. + /** Draws 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, alpha, SkImageFilter, @@ -1489,7 +1488,7 @@ public: this->drawImageRect(image.get(), src, dst, paint, constraint); } - /** Draw SkIRect isrc of SkImage image, scaled and translated to fill SkRect dst. + /** Draws SkIRect isrc of SkImage image, scaled and translated to fill SkRect dst. isrc is on integer pixel boundaries; dst may include fractional boundaries. Additionally transform draw using clip, SkMatrix, and optional SkPaint paint. @@ -1518,7 +1517,7 @@ public: this->drawImageRect(image.get(), isrc, dst, paint, constraint); } - /** Draw SkImage image, scaled and translated to fill SkRect dst, + /** Draws SkImage image, scaled and translated to fill SkRect dst, using clip, SkMatrix, and optional SkPaint paint. If SkPaint paint is supplied, apply SkColorFilter, alpha, SkImageFilter, @@ -1544,7 +1543,7 @@ public: this->drawImageRect(image.get(), dst, paint, constraint); } - /** Draw SkImage image stretched proportionally to fit into SkRect dst. + /** Draws 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. @@ -1571,7 +1570,7 @@ public: void drawImageNine(const SkImage* image, const SkIRect& center, const SkRect& dst, const SkPaint* paint = nullptr); - /** Draw SkImage image stretched proportionally to fit into SkRect dst. + /** Draws 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. @@ -1600,7 +1599,7 @@ public: this->drawImageNine(image.get(), center, dst, paint); } - /** Draw SkBitmap bitmap, with its top-left corner at (left, top), + /** Draws 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, alpha, SkImageFilter, @@ -1621,7 +1620,7 @@ public: void drawBitmap(const SkBitmap& bitmap, SkScalar left, SkScalar top, const SkPaint* paint = nullptr); - /** Draw SkRect src of SkBitmap bitmap, scaled and translated to fill SkRect dst. + /** Draws 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, alpha, SkImageFilter, @@ -1648,7 +1647,7 @@ public: const SkPaint* paint, SrcRectConstraint constraint = kStrict_SrcRectConstraint); - /** Draw SkIRect isrc of SkBitmap bitmap, scaled and translated to fill SkRect dst. + /** Draws SkIRect isrc of SkBitmap bitmap, scaled and translated to fill SkRect dst. isrc is on integer pixel boundaries; dst may include fractional boundaries. Additionally transform draw using clip, SkMatrix, and optional SkPaint paint. @@ -1676,7 +1675,7 @@ public: const SkPaint* paint, SrcRectConstraint constraint = kStrict_SrcRectConstraint); - /** Draw SkBitmap bitmap, scaled and translated to fill SkRect dst. + /** Draws SkBitmap bitmap, scaled and translated to fill SkRect dst. bitmap bounds is on integer pixel boundaries; dst may include fractional boundaries. Additionally transform draw using clip, SkMatrix, and optional SkPaint paint. @@ -1702,7 +1701,7 @@ public: void drawBitmapRect(const SkBitmap& bitmap, const SkRect& dst, const SkPaint* paint, SrcRectConstraint constraint = kStrict_SrcRectConstraint); - /** Draw SkBitmap bitmap stretched proportionally to fit into SkRect dst. + /** Draws 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 @@ -1761,7 +1760,7 @@ public: const SkColor* fColors; //!< array of colors }; - /** Draw SkBitmap bitmap stretched proportionally to fit into SkRect dst. + /** Draws SkBitmap bitmap stretched proportionally to fit into SkRect dst. SkCanvas::Lattice lattice divides bitmap into a rectangular grid. Each intersection of an even-numbered row and column is fixed; like the corners @@ -1792,7 +1791,7 @@ public: void drawBitmapLattice(const SkBitmap& bitmap, const Lattice& lattice, const SkRect& dst, const SkPaint* paint = nullptr); - /** Draw SkImage image stretched proportionally to fit into SkRect dst. + /** Draws SkImage image stretched proportionally to fit into SkRect dst. SkCanvas::Lattice lattice divides image into a rectangular grid. Each intersection of an even-numbered row and column is fixed; like the corners @@ -1823,7 +1822,7 @@ public: void drawImageLattice(const SkImage* image, const Lattice& lattice, const SkRect& dst, const SkPaint* paint = nullptr); - /** Draw text, with origin at (x, y), using clip, SkMatrix, and SkPaint paint. + /** Draws text, with origin at (x, y), using clip, SkMatrix, and SkPaint paint. text meaning depends on SkPaint::TextEncoding; by default, text is encoded as UTF-8. @@ -1873,7 +1872,7 @@ public: this->drawText(string, strlen(string), x, y, paint); } - /** Draw null terminated string, with origin at (x, y), using clip, SkMatrix, and + /** 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 @@ -1896,7 +1895,7 @@ public: */ void drawString(const SkString& string, SkScalar x, SkScalar y, const SkPaint& paint); - /** Draw each glyph in text with the origin in pos array, using clip, SkMatrix, and + /** Draws each glyph in text with the origin in pos array, using clip, SkMatrix, and SkPaint paint. The number of entries in pos array must match the number of glyphs described by byteLength of text. @@ -1920,7 +1919,7 @@ public: void drawPosText(const void* text, size_t byteLength, const SkPoint pos[], const SkPaint& paint); - /** Draw each glyph in text with its (x, y) origin composed from xpos array and + /** Draws each glyph in text with its (x, y) origin composed from xpos array and constY, using clip, SkMatrix, and SkPaint paint. The number of entries in xpos array must match the number of glyphs described by byteLength of text. @@ -1947,7 +1946,7 @@ public: void drawPosTextH(const void* text, size_t byteLength, const SkScalar xpos[], SkScalar constY, const SkPaint& paint); - /** Draw text on SkPath path, using clip, SkMatrix, and SkPaint paint. + /** Draws text on SkPath path, using clip, SkMatrix, and SkPaint paint. Origin of text is at distance hOffset along the path, offset by a perpendicular vector of length vOffset. If the path section corresponding the glyph advance is @@ -1974,7 +1973,7 @@ public: void drawTextOnPathHV(const void* text, size_t byteLength, const SkPath& path, SkScalar hOffset, SkScalar vOffset, const SkPaint& paint); - /** Draw text on SkPath path, using clip, SkMatrix, and SkPaint paint. + /** Draws text on SkPath path, using clip, SkMatrix, and SkPaint paint. 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 @@ -2004,7 +2003,7 @@ public: void drawTextOnPath(const void* text, size_t byteLength, const SkPath& path, const SkMatrix* matrix, const SkPaint& paint); - /** Draw text, transforming each glyph by the corresponding SkRSXform, + /** Draws text, transforming each glyph by the corresponding SkRSXform, using clip, SkMatrix, and SkPaint paint. SkRSXform xform array specifies a separate square scale, rotation, and translation @@ -2026,7 +2025,7 @@ public: void drawTextRSXform(const void* text, size_t byteLength, const SkRSXform xform[], const SkRect* cullRect, const SkPaint& paint); - /** Draw SkTextBlob blob at (x, y), using clip, SkMatrix, and SkPaint paint. + /** Draws SkTextBlob blob at (x, y), using clip, SkMatrix, and SkPaint paint. blob contains glyphs, their positions, and paint attributes specific to text: SkTypeface, SkPaint text size, SkPaint text scale x, SkPaint text skew x, @@ -2046,7 +2045,7 @@ public: */ void drawTextBlob(const SkTextBlob* blob, SkScalar x, SkScalar y, const SkPaint& paint); - /** Draw SkTextBlob blob at (x, y), using clip, SkMatrix, and SkPaint paint. + /** Draws SkTextBlob blob at (x, y), using clip, SkMatrix, and SkPaint paint. blob contains glyphs, their positions, and paint attributes specific to text: SkTypeface, SkPaint text size, SkPaint text scale x, SkPaint text skew x, @@ -2068,7 +2067,7 @@ public: this->drawTextBlob(blob.get(), x, y, paint); } - /** Draw SkPicture picture, using clip and SkMatrix. + /** Draws SkPicture picture, using clip and SkMatrix. Clip and SkMatrix are unchanged by picture contents, as if save() was called before and restore() was called after drawPicture(). @@ -2080,7 +2079,7 @@ public: this->drawPicture(picture, nullptr, nullptr); } - /** Draw SkPicture picture, using clip and SkMatrix. + /** Draws SkPicture picture, using clip and SkMatrix. Clip and SkMatrix are unchanged by picture contents, as if save() was called before and restore() was called after drawPicture(). @@ -2092,7 +2091,7 @@ public: this->drawPicture(picture.get()); } - /** Draw SkPicture picture, using clip and SkMatrix; transforming picture with + /** Draws SkPicture picture, using clip and SkMatrix; transforming picture with SkMatrix matrix, if provided; and use SkPaint paint alpha, SkColorFilter, SkImageFilter, and SkBlendMode, if provided. @@ -2105,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 + /** Draws SkPicture picture, using clip and SkMatrix; transforming picture with SkMatrix matrix, if provided; and use SkPaint paint alpha, SkColorFilter, SkImageFilter, and SkBlendMode, if provided. @@ -2120,7 +2119,7 @@ public: this->drawPicture(picture.get(), matrix, paint); } - /** Draw SkVertices vertices, a triangle mesh, using clip and SkMatrix. + /** Draws 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. @@ -2130,7 +2129,7 @@ public: */ void drawVertices(const SkVertices* vertices, SkBlendMode mode, const SkPaint& paint); - /** Draw SkVertices vertices, a triangle mesh, using clip and SkMatrix. + /** Draws 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. @@ -2140,7 +2139,7 @@ public: */ void drawVertices(const sk_sp<SkVertices>& vertices, SkBlendMode mode, const SkPaint& paint); - /** Draw SkVertices vertices, a triangle mesh, using clip and SkMatrix. Bone data is used to + /** Draws SkVertices vertices, a triangle mesh, using clip and SkMatrix. Bone data is used to deform vertices with bone weights. If vertices texs and vertices colors are defined in vertices, and SkPaint paint contains SkShader, SkBlendMode mode combines vertices colors with SkShader. @@ -2158,7 +2157,7 @@ public: void drawVertices(const SkVertices* vertices, const SkMatrix* bones, int boneCount, SkBlendMode mode, const SkPaint& paint); - /** Draw SkVertices vertices, a triangle mesh, using clip and SkMatrix. Bone data is used to + /** Draws SkVertices vertices, a triangle mesh, using clip and SkMatrix. Bone data is used to deform vertices with bone weights. If vertices texs and vertices colors are defined in vertices, and SkPaint paint contains SkShader, SkBlendMode mode combines vertices colors with SkShader. @@ -2233,7 +2232,7 @@ public: this->drawPatch(cubics, colors, texCoords, SkBlendMode::kModulate, paint); } - /** Draw a set of sprites from atlas, using clip, SkMatrix, and optional SkPaint paint. + /** Draws a set of sprites from atlas, using clip, SkMatrix, and optional SkPaint paint. 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. @@ -2257,7 +2256,7 @@ public: const SkColor colors[], int count, SkBlendMode mode, const SkRect* cullRect, const SkPaint* paint); - /** Draw a set of sprites from atlas, using clip, SkMatrix, and optional SkPaint paint. + /** Draws a set of sprites from atlas, using clip, SkMatrix, and optional SkPaint paint. 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 +2281,7 @@ public: this->drawAtlas(atlas.get(), xform, tex, colors, count, mode, cullRect, paint); } - /** Draw a set of sprites from atlas, using clip, SkMatrix, and optional SkPaint paint. + /** Draws a set of sprites from atlas, using clip, SkMatrix, and optional SkPaint paint. 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. @@ -2303,7 +2302,7 @@ public: this->drawAtlas(atlas, xform, tex, nullptr, count, SkBlendMode::kDst, cullRect, paint); } - /** Draw a set of sprites from atlas, using clip, SkMatrix, and optional SkPaint paint. + /** Draws a set of sprites from atlas, using clip, SkMatrix, and optional SkPaint paint. 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. @@ -2325,7 +2324,7 @@ public: cullRect, paint); } - /** Draw SkDrawable drawable using clip and SkMatrix, concatenated with + /** Draws SkDrawable drawable using clip and SkMatrix, concatenated with optional matrix. If SkCanvas has an asynchronous implementation, as is the case @@ -2338,7 +2337,7 @@ public: */ void drawDrawable(SkDrawable* drawable, const SkMatrix* matrix = nullptr); - /** Draw SkDrawable drawable using clip and SkMatrix, offset by (x, y). + /** Draws SkDrawable drawable using clip and SkMatrix, offset by (x, y). If SkCanvas has an asynchronous implementation, as is the case when it is recording into SkPicture, then drawable will be referenced, @@ -2351,7 +2350,7 @@ public: */ void drawDrawable(SkDrawable* drawable, SkScalar x, SkScalar y); - /** Associate SkRect on SkCanvas with an annotation; a key-value pair, where the key is + /** Associates SkRect on SkCanvas with an annotation; a key-value pair, where the key is a null-terminated utf8 string, and optional value is stored as SkData. Only some canvas implementations, such as recording to SkPicture, or drawing to @@ -2363,7 +2362,7 @@ public: */ void drawAnnotation(const SkRect& rect, const char key[], SkData* value); - /** Associate SkRect on SkCanvas when an annotation; a key-value pair, where the key is + /** Associates SkRect on SkCanvas when an annotation; a key-value pair, where the key is a null-terminated utf8 string, and optional value is stored as SkData. Only some canvas implementations, such as recording to SkPicture, or drawing to @@ -2377,8 +2376,6 @@ public: this->drawAnnotation(rect, key, value.get()); } - ////////////////////////////////////////////////////////////////////////// - /** Returns true if clip is empty; that is, nothing will draw. May do work when called; it should not be called diff --git a/include/core/SkImage.h b/include/core/SkImage.h index f04dd45c78..7e477ec8d3 100644 --- a/include/core/SkImage.h +++ b/include/core/SkImage.h @@ -6,7 +6,7 @@ */ /* Generated by tools/bookmaker from include/core/SkImage.h and docs/SkImage_Reference.bmh - on 2018-06-14 13:13:34. Additional documentation and examples can be found at: + on 2018-07-13 08:15:11. Additional documentation and examples can be found at: https://skia.org/user/api/SkImage_Reference You may edit either file directly. Structural changes to public interfaces require @@ -870,7 +870,8 @@ public: Set premulBehavior to SkTransferFunctionBehavior::kIgnore to treat SkImage pixels as linear, when converting to destination SkColorType - and SkColorSpace, ignoring pixel encoding. + and SkColorSpace, ignoring pixel encoding. premulBehavior is + SkTransferFunctionBehavior::kIgnore by default. @param target SkColorSpace describing color range of returned SkImage @param premulBehavior one of: SkTransferFunctionBehavior::kRespect, diff --git a/include/core/SkImageInfo.h b/include/core/SkImageInfo.h index 33dd8ca1ed..19990e7384 100644 --- a/include/core/SkImageInfo.h +++ b/include/core/SkImageInfo.h @@ -6,7 +6,7 @@ */ /* Generated by tools/bookmaker from include/core/SkImageInfo.h and docs/SkImageInfo_Reference.bmh - on 2018-06-14 13:13:34. Additional documentation and examples can be found at: + on 2018-07-13 08:15:11. Additional documentation and examples can be found at: https://skia.org/user/api/SkImageInfo_Reference You may edit either file directly. Structural changes to public interfaces require @@ -93,7 +93,7 @@ enum SkColorType { 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 - kRGBA_F32_SkColorType, //!< pixel with single floats for red, green, blue, alpha + kRGBA_F32_SkColorType, //!< pixel using C float for red, green, blue, alpha; in 128-bit word kLastEnum_SkColorType = kRGBA_F32_SkColorType,//!< last valid value #if SK_PMCOLOR_BYTE_ORDER(B,G,R,A) diff --git a/include/core/SkMatrix.h b/include/core/SkMatrix.h index 6a67de9b8c..fb1cef2662 100644 --- a/include/core/SkMatrix.h +++ b/include/core/SkMatrix.h @@ -6,7 +6,7 @@ */ /* Generated by tools/bookmaker from include/core/SkMatrix.h and docs/SkMatrix_Reference.bmh - on 2018-06-14 13:13:34. Additional documentation and examples can be found at: + on 2018-07-13 08:15:11. Additional documentation and examples can be found at: https://skia.org/user/api/SkMatrix_Reference You may edit either file directly. Structural changes to public interfaces require @@ -1609,7 +1609,7 @@ public: are nearly zero. On success - Matrix = scale * Remaining + Matrix = scale * Remaining. @param scale axes scaling factors; may be nullptr @param remaining SkMatrix without scaling; may be nullptr diff --git a/include/core/SkPaint.h b/include/core/SkPaint.h index 38795629cc..0664cdd360 100644 --- a/include/core/SkPaint.h +++ b/include/core/SkPaint.h @@ -6,7 +6,7 @@ */ /* Generated by tools/bookmaker from include/core/SkPaint.h and docs/SkPaint_Reference.bmh - on 2018-06-14 13:13:33. Additional documentation and examples can be found at: + on 2018-07-13 08:15:10. Additional documentation and examples can be found at: https://skia.org/user/api/SkPaint_Reference You may edit either file directly. Structural changes to public interfaces require @@ -245,7 +245,7 @@ public: */ void setFlags(uint32_t flags); - /** If true, pixels on the active edges of SkPath may be drawn with partial transparency. + /** Returns true if pixels on the active edges of SkPath may be drawn with partial transparency. Equivalent to getFlags() masked with kAntiAlias_Flag. @@ -265,7 +265,7 @@ public: */ void setAntiAlias(bool aa); - /** If true, color error may be distributed to smooth color transition. + /** Returns true if color error may be distributed to smooth color transition. Equivalent to getFlags() masked with kDither_Flag. @@ -284,7 +284,7 @@ public: */ void setDither(bool dither); - /** If true, text is converted to SkPath before drawing and measuring. + /** Returns true if text is converted to SkPath before drawing and measuring. Equivalent to getFlags() masked with kLinearText_Flag. @@ -294,7 +294,7 @@ public: return SkToBool(this->getFlags() & kLinearText_Flag); } - /** If true, text is converted to SkPath before drawing and measuring. + /** Returns true if text is converted to SkPath before drawing and measuring. By default, kLinearText_Flag is clear. Sets kLinearText_Flag if linearText is true. @@ -304,7 +304,7 @@ public: */ void setLinearText(bool linearText); - /** If true, glyphs at different sub-pixel positions may differ on pixel edge coverage. + /** Returns true if glyphs at different sub-pixel positions may differ on pixel edge coverage. Equivalent to getFlags() masked with kSubpixelText_Flag. @@ -323,7 +323,7 @@ public: */ void setSubpixelText(bool subpixelText); - /** If true, glyphs may use LCD striping to improve glyph edges. + /** Returns true if glyphs may use LCD striping to improve glyph edges. Returns true if SkPaint::Flags kLCDRenderText_Flag is set. @@ -342,7 +342,7 @@ public: */ void setLCDRenderText(bool lcdText); - /** If true, font engine may return glyphs from font bitmaps instead of from outlines. + /** Returns true if font engine may return glyphs from font bitmaps instead of from outlines. Equivalent to getFlags() masked with kEmbeddedBitmapText_Flag. @@ -361,9 +361,9 @@ public: */ void setEmbeddedBitmapText(bool useEmbeddedBitmapText); - /** If true, and if SkPaint::Hinting is set to kNormal_Hinting or kFull_Hinting, and if - platform uses FreeType as the font manager, instruct the font manager to always hint - glyphs. + /** Returns true if SkPaint::Hinting is set to kNormal_Hinting or kFull_Hinting, and if + platform uses FreeType as the font manager. If true, instructs + the font manager to always hint glyphs. Equivalent to getFlags() masked with kAutoHinting_Flag. @@ -373,8 +373,9 @@ public: return SkToBool(this->getFlags() & kAutoHinting_Flag); } - /** If SkPaint::Hinting is set to kNormal_Hinting or kFull_Hinting and useAutohinter is set, - instruct the font manager to always hint glyphs. + /** Sets whether to always hint glyphs. + If SkPaint::Hinting is set to kNormal_Hinting or kFull_Hinting and useAutohinter is set, + instructs the font manager to always hint glyphs. auto-hinting has no effect if SkPaint::Hinting is set to kNo_Hinting or kSlight_Hinting. @@ -387,7 +388,7 @@ public: */ void setAutohinted(bool useAutohinter); - /** If true, glyphs are drawn top to bottom instead of left to right. + /** Returns true if glyphs are drawn top to bottom instead of left to right. Equivalent to getFlags() masked with kVerticalText_Flag. @@ -397,7 +398,7 @@ public: return SkToBool(this->getFlags() & kVerticalText_Flag); } - /** If true, text advance positions the next glyph below the previous glyph instead of to the + /** Returns true if text advance positions the next glyph below the previous glyph instead of to the right of previous glyph. Sets kVerticalText_Flag if vertical is true. @@ -407,7 +408,7 @@ public: */ void setVerticalText(bool verticalText); - /** If true, approximate bold by increasing the stroke width when creating glyph bitmaps + /** Returns true if approximate bold by increasing the stroke width when creating glyph bitmaps from outlines. Equivalent to getFlags() masked with kFakeBoldText_Flag. @@ -418,7 +419,7 @@ public: return SkToBool(this->getFlags() & kFakeBoldText_Flag); } - /** Use increased stroke width when creating glyph bitmaps to approximate a bold typeface. + /** Increases stroke width when creating glyph bitmaps to approximate a bold typeface. Sets kFakeBoldText_Flag if fakeBoldText is true. Clears kFakeBoldText_Flag if fakeBoldText is false. @@ -472,7 +473,7 @@ public: */ static constexpr int kStyleCount = kStrokeAndFill_Style + 1; - /** Whether the geometry is filled, stroked, or filled and stroked. + /** Returns whether the geometry is filled, stroked, or filled and stroked. @return one of:kFill_Style, kStroke_Style, kStrokeAndFill_Style */ @@ -541,13 +542,13 @@ public: */ void setStrokeWidth(SkScalar width); - /** The limit at which a sharp corner is drawn beveled. + /** Returns the limit at which a sharp corner is drawn beveled. @return zero and greater miter limit */ SkScalar getStrokeMiter() const { return fMiterLimit; } - /** The limit at which a sharp corner is drawn beveled. + /** Sets the limit at which a sharp corner is drawn beveled. Valid values are zero and greater. Has no effect if miter is less than zero. @@ -595,33 +596,33 @@ public: */ static constexpr int kJoinCount = kLast_Join + 1; - /** The geometry drawn at the beginning and end of strokes. + /** Returns the geometry drawn at the beginning and end of strokes. @return one of: kButt_Cap, kRound_Cap, kSquare_Cap */ Cap getStrokeCap() const { return (Cap)fBitfields.fCapType; } - /** The geometry drawn at the beginning and end of strokes. + /** Sets the geometry drawn at the beginning and end of strokes. @param cap one of: kButt_Cap, kRound_Cap, kSquare_Cap; has no effect if cap is not valid */ void setStrokeCap(Cap cap); - /** The geometry drawn at the corners of strokes. + /** Returns the geometry drawn at the corners of strokes. @return one of: kMiter_Join, kRound_Join, kBevel_Join */ Join getStrokeJoin() const { return (Join)fBitfields.fJoinType; } - /** The geometry drawn at the corners of strokes. + /** Sets the geometry drawn at the corners of strokes. @param join one of: kMiter_Join, kRound_Join, kBevel_Join; otherwise, has no effect */ void setStrokeJoin(Join join); - /** The filled equivalent of the stroked path. + /** Returns the filled equivalent of the stroked path. @param src SkPath read to create a filled version @param dst resulting SkPath; may be the same as src, but may not be nullptr @@ -633,7 +634,7 @@ public: bool getFillPath(const SkPath& src, SkPath* dst, const SkRect* cullRect, SkScalar resScale = 1) const; - /** The filled equivalent of the stroked path. + /** Returns the filled equivalent of the stroked path. Replaces dst with the src path modified by SkPathEffect and style stroke. SkPathEffect, if any, is not culled. stroke width is created with default precision. @@ -646,7 +647,7 @@ public: return this->getFillPath(src, dst, nullptr, 1); } - /** Optional colors used when filling a path, such as a gradient. + /** Returns optional colors used when filling a path, such as a gradient. Does not alter SkShader SkRefCnt. @@ -654,7 +655,7 @@ public: */ SkShader* getShader() const { return fShader.get(); } - /** Optional colors used when filling a path, such as a gradient. + /** Returns optional colors used when filling a path, such as a gradient. Increases SkShader SkRefCnt by one. @@ -662,7 +663,7 @@ public: */ sk_sp<SkShader> refShader() const; - /** Optional colors used when filling a path, such as a gradient. + /** Sets optional colors used when filling a path, such as a gradient. Sets SkShader to shader, decreasing SkRefCnt of the previous SkShader. Increments shader SkRefCnt by one. @@ -1015,7 +1016,7 @@ public: SkScalar fStrikeoutThickness; //!< strikeout thickness SkScalar fStrikeoutPosition; //!< strikeout position relative to baseline - /** If SkPaint::FontMetrics has a valid underline thickness, return true, and set + /** Returns true if SkPaint::FontMetrics has a valid underline thickness, and sets thickness to that value. If the underline thickness is not valid, return false, and ignore thickness. @@ -1030,7 +1031,7 @@ public: return false; } - /** If SkPaint::FontMetrics has a valid underline position, return true, and set + /** Returns true if SkPaint::FontMetrics has a valid underline position, and sets position to that value. If the underline position is not valid, return false, and ignore position. @@ -1045,7 +1046,7 @@ public: return false; } - /** If SkPaint::FontMetrics has a valid strikeout thickness, return true, and set + /** Returns true if SkPaint::FontMetrics has a valid strikeout thickness, and sets thickness to that value. If the underline thickness is not valid, return false, and ignore thickness. @@ -1060,7 +1061,7 @@ public: return false; } - /** If SkPaint::FontMetrics has a valid strikeout position, return true, and set + /** Returns true if SkPaint::FontMetrics has a valid strikeout position, and sets position to that value. If the underline position is not valid, return false, and ignore position. diff --git a/include/core/SkPath.h b/include/core/SkPath.h index 85f22b5cab..ef8f912d3d 100644 --- a/include/core/SkPath.h +++ b/include/core/SkPath.h @@ -6,7 +6,7 @@ */ /* Generated by tools/bookmaker from include/core/SkPath.h and docs/SkPath_Reference.bmh - on 2018-06-14 13:13:34. Additional documentation and examples can be found at: + on 2018-07-13 08:15:11. Additional documentation and examples can be found at: https://skia.org/user/api/SkPath_Reference You may edit either file directly. Structural changes to public interfaces require @@ -66,14 +66,15 @@ public: kCCW_Direction, //!< contour travels counterclockwise }; - /** By default, SkPath has no verbs, no SkPoint, and no weights. + /** Constucts an empty path. By default, SkPath has no verbs, no SkPoint, and no weights. SkPath::FillType is set to kWinding_FillType. @return empty SkPath */ SkPath(); - /** Copy constructor makes two paths identical by value. Internally, path and + /** Constructs a copy of an existing path. + Copy constructor makes two paths identical by value. Internally, path and the returned result share pointer values. The underlying verb array, SkPoint array and weights are copied when modified. @@ -90,7 +91,8 @@ public: */ ~SkPath(); - /** SkPath assignment makes two paths identical by value. Internally, assignment + /** Constructs a copy of an existing path. + SkPath assignment makes two paths identical by value. Internally, assignment shares pointer values. The underlying verb array, SkPoint array and weights are copied when modified. @@ -123,7 +125,7 @@ public: return !(a == b); } - /** Return true if SkPath contain equal verbs and equal weights. + /** Returns true if SkPath contain equal verbs and equal weights. If SkPath contain one or more conics, the weights must match. conicTo() may add different verbs depending on conic weight, so it is not @@ -135,7 +137,7 @@ public: */ bool isInterpolatable(const SkPath& compare) const; - /** Interpolate between SkPath with SkPoint array of equal size. + /** Interpolates between SkPath with SkPoint array of equal size. Copy verb array and weights to out, and set out SkPoint array to a weighted average of this SkPoint array and ending SkPoint array, using the formula: (Path Point * weight) + ending Point * (1 - weight). @@ -203,7 +205,7 @@ public: */ bool isInverseFillType() const { return IsInverseFillType((FillType)fFillType); } - /** Replace FillType with its inverse. The inverse of FillType describes the area + /** Replaces FillType with its inverse. The inverse of FillType describes the area unmodified by the original FillType. */ void toggleInverseFillType() { @@ -310,7 +312,8 @@ public: */ void rewind(); - /** Empty SkPath may have FillType but has no SkPoint, SkPath::Verb, or conic weight. + /** Returns if SkPath is empty. + Empty SkPath may have FillType but has no SkPoint, SkPath::Verb, or conic weight. SkPath() constructs empty SkPath; reset() and (rewind) make SkPath empty. @return true if the path contains no SkPath::Verb array @@ -320,7 +323,8 @@ public: return 0 == fPathRef->countVerbs(); } - /** Contour is closed if SkPath SkPath::Verb array was last modified by close(). When stroked, + /** Returns if contour is closed. + Contour is closed if SkPath SkPath::Verb array was last modified by close(). When stroked, closed contour draws SkPaint::Join instead of SkPaint::Cap at first and last SkPoint. @return true if the last contour ends with a kClose_Verb @@ -349,7 +353,7 @@ public: return SkToBool(fIsVolatile); } - /** Specify whether SkPath is volatile; whether it will be altered or discarded + /** Specifies whether SkPath is volatile; whether it will be altered or discarded by the caller after it is drawn. SkPath by default have volatile set false, allowing SkBaseDevice to attach a cache of data which speeds repeated drawing. @@ -368,7 +372,7 @@ public: fIsVolatile = isVolatile; } - /** Test if line between SkPoint pair is degenerate. + /** Tests if line between SkPoint pair is degenerate. Line with no length or that moves a very short distance is degenerate; it is treated as a point. @@ -382,7 +386,7 @@ public: */ static bool IsLineDegenerate(const SkPoint& p1, const SkPoint& p2, bool exact); - /** Test if quad is degenerate. + /** Tests if quad is degenerate. Quad with no length or that moves a very short distance is degenerate; it is treated as a point. @@ -396,7 +400,7 @@ public: static bool IsQuadDegenerate(const SkPoint& p1, const SkPoint& p2, const SkPoint& p3, bool exact); - /** Test if cubic is degenerate. + /** Tests if cubic is degenerate. Cubic with no length or that moves a very short distance is degenerate; it is treated as a point. @@ -489,7 +493,7 @@ public: return fPathRef->getBounds(); } - /** Update internal bounds so that subsequent calls to getBounds() are instantaneous. + /** Updates internal bounds so that subsequent calls to getBounds() are instantaneous. Unaltered copies of SkPath may also access cached bounds through getBounds(). For now, identical to calling getBounds() and ignoring the returned value. @@ -532,7 +536,7 @@ public: */ bool conservativelyContainsRect(const SkRect& rect) const; - /** grows SkPath verb array and SkPoint array to contain extraPtCount additional SkPoint. + /** Grows SkPath verb array and SkPoint array to contain extraPtCount additional SkPoint. May improve performance and use less memory by reducing the number and size of allocations when creating SkPath. @@ -779,7 +783,7 @@ public: void rCubicTo(SkScalar x1, SkScalar y1, SkScalar x2, SkScalar y2, SkScalar x3, SkScalar y3); - /** Append arc to SkPath. Arc added is part of ellipse + /** Appends arc to SkPath. Arc added is part of ellipse bounded by oval, from startAngle through sweepAngle. Both startAngle and sweepAngle are measured in degrees, where zero degrees is aligned with the positive x-axis, and positive sweeps extends arc clockwise. @@ -795,7 +799,7 @@ public: */ void arcTo(const SkRect& oval, SkScalar startAngle, SkScalar sweepAngle, bool forceMoveTo); - /** Append arc to SkPath, after appending line if needed. Arc is implemented by conic + /** Appends arc to SkPath, after appending line if needed. Arc is implemented by conic weighted to describe part of circle. Arc is contained by tangent from last SkPath point (x0, y0) to (x1, y1), and tangent from (x1, y1) to (x2, y2). Arc is part of circle sized to radius, positioned so it touches both tangent lines. @@ -808,7 +812,7 @@ public: */ void arcTo(SkScalar x1, SkScalar y1, SkScalar x2, SkScalar y2, SkScalar radius); - /** Append arc to SkPath, after appending line if needed. Arc is implemented by conic + /** Appends arc to SkPath, after appending line if needed. Arc is implemented by conic weighted to describe part of circle. Arc is contained by tangent from last SkPath point to p1, and tangent from p1 to p2. Arc is part of circle sized to radius, positioned so it touches both tangent lines. @@ -839,7 +843,7 @@ public: kLarge_ArcSize, //!< larger of arc pair }; - /** Append arc to SkPath. Arc is implemented by one or more conics weighted to + /** Appends arc to SkPath. Arc is implemented by one or more conics weighted to describe part of oval with radii (rx, ry) rotated by xAxisRotate degrees. Arc curves from last SkPath SkPoint to (x, y), choosing one of four possible routes: clockwise or counterclockwise, and smaller or larger. @@ -865,7 +869,7 @@ public: void arcTo(SkScalar rx, SkScalar ry, SkScalar xAxisRotate, ArcSize largeArc, Direction sweep, SkScalar x, SkScalar y); - /** Append arc to SkPath. Arc is implemented by one or more conic weighted to describe part of oval + /** Appends arc to SkPath. Arc is implemented by one or more conic weighted to describe part of oval with radii (r.fX, r.fY) rotated by xAxisRotate degrees. Arc curves from last SkPath SkPoint to (xy.fX, xy.fY), choosing one of four possible routes: clockwise or counterclockwise, and smaller or larger. @@ -890,7 +894,7 @@ public: this->arcTo(r.fX, r.fY, xAxisRotate, largeArc, sweep, xy.fX, xy.fY); } - /** Append arc to SkPath, relative to last SkPath SkPoint. Arc is implemented by one or + /** Appends 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 @@ -918,7 +922,7 @@ public: void rArcTo(SkScalar rx, SkScalar ry, SkScalar xAxisRotate, ArcSize largeArc, Direction sweep, SkScalar dx, SkScalar dy); - /** Append kClose_Verb to SkPath. A closed contour connects the first and last SkPoint + /** Appends kClose_Verb to SkPath. A closed contour connects the first and last SkPoint with line, forming a continuous loop. Open and closed contour draw the same with SkPaint::kFill_Style. With SkPaint::kStroke_Style, open contour draws SkPaint::Cap at contour start and end; closed contour draws @@ -1013,7 +1017,7 @@ public: */ bool isNestedFillRects(SkRect rect[2], Direction dirs[2] = nullptr) const; - /** Add SkRect to SkPath, appending kMove_Verb, three kLine_Verb, and kClose_Verb, + /** Adds SkRect to SkPath, appending kMove_Verb, three kLine_Verb, and kClose_Verb, starting with top-left corner of SkRect; followed by top-right, bottom-right, and bottom-left if dir is kCW_Direction; or followed by bottom-left, bottom-right, and top-right if dir is kCCW_Direction. @@ -1023,7 +1027,7 @@ public: */ void addRect(const SkRect& rect, Direction dir = kCW_Direction); - /** Add SkRect to SkPath, appending kMove_Verb, three kLine_Verb, and kClose_Verb. + /** Adds SkRect to SkPath, appending kMove_Verb, three kLine_Verb, and kClose_Verb. If dir is kCW_Direction, SkRect corners are added clockwise; if dir is kCCW_Direction, SkRect corners are added counterclockwise. start determines the first corner added. @@ -1034,7 +1038,7 @@ public: */ void addRect(const SkRect& rect, Direction dir, unsigned start); - /** Add SkRect (left, top, right, bottom) to SkPath, + /** Adds SkRect (left, top, right, bottom) to SkPath, appending kMove_Verb, three kLine_Verb, and kClose_Verb, starting with top-left corner of SkRect; followed by top-right, bottom-right, and bottom-left if dir is kCW_Direction; or followed by bottom-left, @@ -1049,7 +1053,7 @@ public: void addRect(SkScalar left, SkScalar top, SkScalar right, SkScalar bottom, Direction dir = kCW_Direction); - /** Add oval to path, appending kMove_Verb, four kConic_Verb, and kClose_Verb. + /** Adds oval to path, appending kMove_Verb, four kConic_Verb, and kClose_Verb. Oval is upright ellipse bounded by SkRect oval with radii equal to half oval width and half oval height. Oval begins at (oval.fRight, oval.centerY()) and continues clockwise if dir is kCW_Direction, counterclockwise if dir is kCCW_Direction. @@ -1059,7 +1063,7 @@ public: */ void addOval(const SkRect& oval, Direction dir = kCW_Direction); - /** Add oval to SkPath, appending kMove_Verb, four kConic_Verb, and kClose_Verb. + /** Adds oval to SkPath, appending kMove_Verb, four kConic_Verb, and kClose_Verb. Oval is upright ellipse bounded by SkRect oval with radii equal to half oval width and half oval height. Oval begins at start and continues clockwise if dir is kCW_Direction, counterclockwise if dir is kCCW_Direction. @@ -1070,7 +1074,7 @@ public: */ void addOval(const SkRect& oval, Direction dir, unsigned start); - /** Add circle centered at (x, y) of size radius to SkPath, appending kMove_Verb, + /** Adds 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. @@ -1084,7 +1088,7 @@ public: void addCircle(SkScalar x, SkScalar y, SkScalar radius, Direction dir = kCW_Direction); - /** Append arc to SkPath, as the start of new contour. Arc added is part of ellipse + /** Appends arc to SkPath, as the start of new contour. Arc added is part of ellipse bounded by oval, from startAngle through sweepAngle. Both startAngle and sweepAngle are measured in degrees, where zero degrees is aligned with the positive x-axis, and positive sweeps extends arc clockwise. @@ -1099,7 +1103,7 @@ public: */ void addArc(const SkRect& oval, SkScalar startAngle, SkScalar sweepAngle); - /** Append SkRRect to SkPath, creating a new closed contour. SkRRect has bounds + /** Appends SkRRect to SkPath, creating a new closed contour. SkRRect has bounds equal to rect; each corner is 90 degrees of an ellipse with radii (rx, ry). If dir is kCW_Direction, SkRRect starts at top-left of the lower-left corner and winds clockwise. If dir is kCCW_Direction, SkRRect starts at the bottom-left @@ -1119,7 +1123,7 @@ public: void addRoundRect(const SkRect& rect, SkScalar rx, SkScalar ry, Direction dir = kCW_Direction); - /** Append SkRRect to SkPath, creating a new closed contour. SkRRect has bounds + /** Appends SkRRect to SkPath, creating a new closed contour. SkRRect has bounds equal to rect; each corner is 90 degrees of an ellipse with radii from the array. @@ -1130,7 +1134,7 @@ public: void addRoundRect(const SkRect& rect, const SkScalar radii[], Direction dir = kCW_Direction); - /** Add rrect to SkPath, creating a new closed contour. If + /** Adds rrect to SkPath, creating a new closed contour. If dir is kCW_Direction, rrect starts at top-left of the lower-left corner and winds clockwise. If dir is kCCW_Direction, rrect starts at the bottom-left of the upper-left corner and winds counterclockwise. @@ -1142,7 +1146,7 @@ public: */ void addRRect(const SkRRect& rrect, Direction dir = kCW_Direction); - /** Add rrect to SkPath, creating a new closed contour. If dir is kCW_Direction, rrect + /** Adds rrect to SkPath, creating a new closed contour. If dir is kCW_Direction, rrect winds clockwise; if dir is kCCW_Direction, rrect winds counterclockwise. start determines the first point of rrect to add. @@ -1152,7 +1156,7 @@ public: */ void addRRect(const SkRRect& rrect, Direction dir, unsigned start); - /** Add contour created from line array, adding (count - 1) line segments. + /** Adds 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]. @@ -1175,7 +1179,7 @@ public: kExtend_AddPathMode, //!< add line if prior contour is not closed }; - /** Append src to SkPath, offset by (dx, dy). + /** Appends src to SkPath, offset by (dx, dy). If mode is kAppend_AddPathMode, src verb array, SkPoint array, and conic weights are added unaltered. If mode is kExtend_AddPathMode, add line before appending @@ -1189,7 +1193,7 @@ public: void addPath(const SkPath& src, SkScalar dx, SkScalar dy, AddPathMode mode = kAppend_AddPathMode); - /** Append src to SkPath. + /** Appends src to SkPath. If mode is kAppend_AddPathMode, src verb array, SkPoint array, and conic weights are added unaltered. If mode is kExtend_AddPathMode, add line before appending @@ -1204,7 +1208,7 @@ public: this->addPath(src, m, mode); } - /** Append src to SkPath, transformed by matrix. Transformed curves may have different + /** Appends src to SkPath, transformed by matrix. Transformed curves may have different verbs, SkPoint, and conic weights. If mode is kAppend_AddPathMode, src verb array, SkPoint array, and conic weights are @@ -1217,14 +1221,14 @@ public: */ void addPath(const SkPath& src, const SkMatrix& matrix, AddPathMode mode = kAppend_AddPathMode); - /** Append src to SkPath, from back to front. + /** Appends src to SkPath, from back to front. Reversed src always appends a new contour to SkPath. @param src SkPath verbs, SkPoint, and conic weights to add */ void reverseAddPath(const SkPath& src); - /** Offset SkPoint array by (dx, dy). Offset SkPath replaces dst. + /** Offsets SkPoint array by (dx, dy). Offset SkPath replaces dst. If dst is nullptr, SkPath is replaced by offset data. @param dx offset added to SkPoint array x-axis coordinates @@ -1233,7 +1237,7 @@ public: */ void offset(SkScalar dx, SkScalar dy, SkPath* dst) const; - /** Offset SkPoint array by (dx, dy). SkPath is replaced by offset data. + /** Offsets SkPoint array by (dx, dy). SkPath is replaced by offset data. @param dx offset added to SkPoint array x-axis coordinates @param dy offset added to SkPoint array y-axis coordinates @@ -1242,7 +1246,7 @@ public: this->offset(dx, dy, this); } - /** Transform verb array, SkPoint array, and weight by matrix. + /** Transforms verb array, SkPoint array, and weight by matrix. transform may change verbs and increase their number. Transformed SkPath replaces dst; if dst is nullptr, original data is replaced. @@ -1252,7 +1256,7 @@ public: */ void transform(const SkMatrix& matrix, SkPath* dst) const; - /** Transform verb array, SkPoint array, and weight by matrix. + /** Transforms verb array, SkPoint array, and weight by matrix. transform may change verbs and increase their number. SkPath is replaced by transformed data. @@ -1270,7 +1274,7 @@ public: */ bool getLastPt(SkPoint* lastPt) const; - /** Set last point to (x, y). If SkPoint array is empty, append kMove_Verb to + /** Sets last point to (x, y). If SkPoint array is empty, append kMove_Verb to verb array and append (x, y) to SkPoint array. @param x set x-axis value of last point @@ -1278,7 +1282,7 @@ public: */ void setLastPt(SkScalar x, SkScalar y); - /** Set the last point on the path. If SkPoint array is empty, append kMove_Verb to + /** Sets the last point on the path. If SkPoint array is empty, append kMove_Verb to verb array and append p to SkPoint array. @param p set value of last point @@ -1551,7 +1555,7 @@ public: */ size_t writeToMemory(void* buffer) const; - /** Write SkPath to buffer, returning the buffer written to, wrapped in SkData. + /** Writes SkPath to buffer, returning the buffer written to, wrapped in SkData. serialize() writes SkPath::FillType, verb array, SkPoint array, conic weight, and additionally writes computed information like SkPath::Convexity and bounds. diff --git a/include/core/SkPicture.h b/include/core/SkPicture.h index 1a9fe04f5c..a88c101eda 100644 --- a/include/core/SkPicture.h +++ b/include/core/SkPicture.h @@ -5,6 +5,16 @@ * found in the LICENSE file. */ +/* Generated by tools/bookmaker from include/core/SkPicture.h and docs/SkPicture_Reference.bmh + on 2018-07-13 08:15:11. Additional documentation and examples can be found at: + https://skia.org/user/api/SkPicture_Reference + + You may edit either file directly. Structural changes to public interfaces require + editing both files. After editing docs/SkPicture_Reference.bmh, run: + bookmaker -b docs -i include/core/SkPicture.h -p + to create an updated version of this file. + */ + #ifndef SkPicture_DEFINED #define SkPicture_DEFINED @@ -21,37 +31,68 @@ class SkStream; class SkWStream; /** \class SkPicture - An SkPicture records drawing commands made to a canvas to be played back at a later time. This base class handles serialization and a few other miscellany. */ class SK_API SkPicture : public SkRefCnt { public: - /** - * Recreate a picture that was serialized into a stream or data. - */ + /** Recreates a picture that was serialized into a stream. + + @param stream container for serial data + @param procs custom serial data decoders; may be nullptr + @return SkPicture constructed from stream data + */ static sk_sp<SkPicture> MakeFromStream(SkStream* stream, const SkDeserialProcs* procs = nullptr); + + /** Recreates a picture that was serialized into data. + + @param data container for serial data + @param procs custom serial data decoders; may be nullptr + @return SkPicture constructed from data + */ static sk_sp<SkPicture> MakeFromData(const SkData* data, const SkDeserialProcs* procs = nullptr); + + /** + + @param data pointer to serial data + @param size size of data + @param procs custom serial data decoders; may be nullptr + @return SkPicture constructed from data + */ static sk_sp<SkPicture> MakeFromData(const void* data, size_t size, const SkDeserialProcs* procs = nullptr); - /** - * Subclasses of this can be passed to playback(). During the playback - * of the picture, this callback will periodically be invoked. If its - * abort() returns true, then picture playback will be interrupted. - * - * The resulting drawing is undefined, as there is no guarantee how often the - * callback will be invoked. If the abort happens inside some level of nested - * calls to save(), restore will automatically be called to return the state - * to the same level it was before the playback call was made. + /** \class SkPicture::AbortCallback + Subclasses of this can be passed to playback(). During the playback + of the picture, this callback will periodically be invoked. If its + abort() returns true, then picture playback will be interrupted. + The resulting drawing is undefined, as there is no guarantee how often the + callback will be invoked. If the abort happens inside some level of nested + calls to save(), restore will automatically be called to return the state + to the same level it was before the playback call was made. */ class SK_API AbortCallback { public: + + /** Has no effect. + + @return abstract class cannot be instantiated + */ AbortCallback() {} + + /** Has no effect. + */ virtual ~AbortCallback() {} + + /** Stops SkPicture playback when some condition is met. A subclass of + AbortCallback provides an override for abort() that can stop playback() from + drawing the entire picture. + + @return true to stop playback + */ virtual bool abort() = 0; }; @@ -59,38 +100,62 @@ public: this has the effect of unfurling this picture into the destination canvas. Using the SkCanvas::drawPicture entry point gives the destination canvas the option of just taking a ref. - @param canvas the canvas receiving the drawing commands. - @param callback a callback that allows interruption of playback + + @param canvas receiver of drawing commands + @param callback allows interruption of playback */ virtual void playback(SkCanvas* canvas, AbortCallback* callback = nullptr) const = 0; - /** Return a cull rect for this picture. + /** Returns cull SkRect for this picture. Ops recorded into this picture that attempt to draw outside the cull might not be drawn. - */ + + @return bounds passed when SkPicture was created + */ virtual SkRect cullRect() const = 0; - /** Returns a non-zero value unique among all pictures. */ + /** Returns a non-zero value unique among all pictures. + + @return identifier for SkPicture + */ uint32_t uniqueID() const; + /** Returns storage containing data describing SkPicture, using optional custom encoders. + + @param procs custom serial data encoders; may be nullptr + @return storage containing serialized SkPicture + */ sk_sp<SkData> serialize(const SkSerialProcs* procs = nullptr) const; + + /** Writes picture to stream, using optional custom encoders. + + @param stream writable serial data stream + @param procs custom serial data encoders; may be nullptr + */ void serialize(SkWStream* stream, const SkSerialProcs* procs = nullptr) const; - /** - * Return a placeholder SkPicture. - * This placeholder does not draw anything itself. It has a distinct uniqueID() - * (just like all SkPictures) and will always be visible to SkSerialProcs. - * @param cull the placeholder's dimensions - */ + /** Returns a placeholder SkPicture. + This placeholder does not draw anything itself. It has a distinct uniqueID() + (just like all SkPicture) and will always be visible to SkSerialProcs. + + @param cull placeholder dimensions + @return placeholder with unique identifier + */ static sk_sp<SkPicture> MakePlaceholder(SkRect cull); - /** Return the approximate number of operations in this picture. This - * number may be greater or less than the number of SkCanvas calls - * recorded: some calls may be recorded as more than one operation, or some - * calls may be optimized away. - */ + /** Returns the approximate number of operations in this picture. This + number may be greater or less than the number of SkCanvas calls + recorded: some calls may be recorded as more than one operation, or some + calls may be optimized away. + + @return approximate operation count + */ virtual int approximateOpCount() const = 0; - /** Returns the approximate byte size of this picture, not including large ref'd objects. */ + /** Returns the approximate byte size of SkPicture. Does not include large objects + referenced SkPicture. + + @return approximate size + */ virtual size_t approximateBytesUsed() const = 0; private: diff --git a/include/core/SkPoint.h b/include/core/SkPoint.h index 75451da71c..76a3bf3d5f 100644 --- a/include/core/SkPoint.h +++ b/include/core/SkPoint.h @@ -6,7 +6,7 @@ */ /* Generated by tools/bookmaker from include/core/SkPoint.h and docs/SkPoint_Reference.bmh - on 2018-06-14 13:13:34. Additional documentation and examples can be found at: + on 2018-07-13 08:15:11. Additional documentation and examples can be found at: https://skia.org/user/api/SkPoint_Reference You may edit either file directly. Structural changes to public interfaces require @@ -390,7 +390,7 @@ struct SK_API SkPoint { return {fX * scale, fY * scale}; } - /** Multiplies SkPoint by scale. Sets SkPoint to: (fX * scale, fY * scale) + /** Multiplies SkPoint by scale. Sets SkPoint to: (fX * scale, fY * scale). @param scale scalar to multiply by @return reference to SkPoint diff --git a/include/core/SkRRect.h b/include/core/SkRRect.h index dae5a0cdde..140e1dac2c 100644 --- a/include/core/SkRRect.h +++ b/include/core/SkRRect.h @@ -5,6 +5,16 @@ * found in the LICENSE file. */ +/* Generated by tools/bookmaker from include/core/SkRRect.h and docs/SkRRect_Reference.bmh + on 2018-07-13 08:15:10. Additional documentation and examples can be found at: + https://skia.org/user/api/SkRRect_Reference + + You may edit either file directly. Structural changes to public interfaces require + editing both files. After editing docs/SkRRect_Reference.bmh, run: + bookmaker -b docs -i include/core/SkRRect.h -p + to create an updated version of this file. + */ + #ifndef SkRRect_DEFINED #define SkRRect_DEFINED @@ -14,89 +24,77 @@ class SkPath; class SkMatrix; -// Path forward: -// core work -// add contains(SkRect&) - for clip stack -// add contains(SkRRect&) - for clip stack -// add heart rect computation (max rect inside RR) -// add 9patch rect computation -// add growToInclude(SkPath&) -// analysis -// use growToInclude to fit skp round rects & generate stats (RRs vs. real paths) -// check on # of rectorus's the RRs could handle -// rendering work -// update SkPath.addRRect() to only use quads -// add GM and bench -// further out -// detect and triangulate RRectorii rather than falling back to SW in Ganesh -// - /** \class SkRRect + SkRRect describes a rounded rectangle with a bounds and a pair of radii for each corner. + The bounds and radii can be set so that SkRRect describes a rectangle with sharp corners, + a circle, an oval, or a rectangle with one or more rounded corners. - The SkRRect class represents a rounded rect with a potentially different - radii for each corner. It does not have a constructor so must be - initialized with one of the initialization functions (e.g., setEmpty, - setRectRadii, etc.) + SkRRect allows implementing CSS properties that describe rounded corners. + SkRRect may have up to eight different radii, one for each axis on each of its four + corners. - This class is intended to roughly match CSS' border-*-*-radius capabilities. - This means: - If either of a corner's radii are 0 the corner will be square. - Negative radii are not allowed (they are clamped to zero). - If the corner curves overlap they will be proportionally reduced to fit. + SkRRect may modify the provided parameters when initializing bounds and radii. + If either axis radii is zero or less, radii are stored as zero; corner is square. + If corner curves overlap, radii are proportionally reduced to fit within bounds. */ class SK_API SkRRect { public: - /** Default initialized to a rrect at the origin with zero width and height. */ + + /** Initializes bounds at (0, 0), the origin, with zero width and height. + Initializes corner radii to (0, 0), and sets type of kEmpty_Type. + + @return empty SkRRect + */ SkRRect() = default; + /** Initializes to copy of rrect bounds and corner radii. + + @param rrect bounds and corner to copy + @return copy of rrect + */ SkRRect(const SkRRect& rrect) = default; + + /** Copies rrect bounds and corner radii. + + @param rrect bounds and corner to copy + @return copy of rrect + */ SkRRect& operator=(const SkRRect& rrect) = default; - /** - * Enum to capture the various possible subtypes of RR. Accessed - * by type(). The subtypes become progressively less restrictive. - */ + /** \enum SkRRect::Type + Type describes possible specializations of SkRRect. Each Type is + exclusive; a SkRRect may only have one type. + + Type members become progressively less restrictive; larger values of + Type have more degrees of freedom than smaller values. + */ enum Type { - // !< The RR has zero width and/or zero height. All radii are zero. - kEmpty_Type, - - //!< The RR is actually a (non-empty) rect (i.e., at least one radius - //!< at each corner is zero) - kRect_Type, - - //!< The RR is actually a (non-empty) oval (i.e., all x radii are equal - //!< and >= width/2 and all the y radii are equal and >= height/2 - kOval_Type, - - //!< The RR is non-empty and all the x radii are equal & all y radii - //!< are equal but it is not an oval (i.e., there are lines between - //!< the curves) nor a rect (i.e., both radii are non-zero) - kSimple_Type, - - //!< The RR is non-empty and the two left x radii are equal, the two top - //!< y radii are equal, and the same for the right and bottom but it is - //!< neither an rect, oval, nor a simple RR. It is called "nine patch" - //!< because the centers of the corner ellipses form an axis aligned - //!< rect with edges that divide the RR into an 9 rectangular patches: - //!< an interior patch, four edge patches, and four corner patches. - kNinePatch_Type, - - //!< A fully general (non-empty) RR. Some of the x and/or y radii are - //!< different from the others and there must be one corner where - //!< both radii are non-zero. - kComplex_Type, - - kLastType = kComplex_Type, + kEmpty_Type, //!< zero width or height + kRect_Type, //!< non-zero width and height, and zeroed radii + kOval_Type, //!< non-zero width and height filled with radii + kSimple_Type, //!< non-zero width and height with equal radii + kNinePatch_Type, //!< non-zero width and height with axis-aligned radii + kComplex_Type, //!< non-zero width and height with arbitrary radii + kLastType = kComplex_Type, //!< largest Type value }; - /** - * Returns the RR's sub type. - */ + /** Returns SkRRect::Type, one of: + kEmpty_Type, kRect_Type, kOval_Type, kSimple_Type, kNinePatch_Type, + kComplex_Type. + + @return SkRRect::Type + */ Type getType() const { SkASSERT(this->isValid()); return static_cast<Type>(fType); } + /** Returns SkRRect::Type, one of: + kEmpty_Type, kRect_Type, kOval_Type, kSimple_Type, kNinePatch_Type, + kComplex_Type. + + @return SkRRect::Type + */ Type type() const { return this->getType(); } inline bool isEmpty() const { return kEmpty_Type == this->getType(); } @@ -106,26 +104,42 @@ public: inline bool isNinePatch() const { return kNinePatch_Type == this->getType(); } inline bool isComplex() const { return kComplex_Type == this->getType(); } + /** Returns span on the x-axis. This does not check if result fits in 32-bit float; + result may be infinity. + + @return bounds().fRight minus bounds().fLeft + */ SkScalar width() const { return fRect.width(); } + + /** Returns span on the y-axis. This does not check if result fits in 32-bit float; + result may be infinity. + + @return bounds().fBottom minus bounds().fTop + */ SkScalar height() const { return fRect.height(); } - /** - * kSimple means that all corners have the same x,y radii. This returns the top/left - * corner's radii as representative of all corners. If the RRect is kComplex, then - * this still returns that corner's radii, but it is not indicative of the other corners. - */ + /** Returns top-left corner x-radii. If type() returns kEmpty_Type, kRect_Type, + kOval_Type, or kSimple_Type, returns a value representative of all corner radii. + If type() returns kNinePatch_Type or kComplex_Type, at least one of the + remaining three corners has a different value. + + @return corner radii for simple types + */ SkVector getSimpleRadii() const { return fRadii[0]; } - /** - * Same as default initialized - zero width and height at the origin. - */ + /** Sets bounds to zero width and height at (0, 0), the origin. Sets + corner radii to zero and sets type to kEmpty_Type. + */ void setEmpty() { *this = SkRRect(); } - /** - * Set this RR to match the supplied rect. All radii will be 0. - */ + /** Sets bounds to sorted rect, and sets corner radii to zero. + If set bounds has width and height, and sets type to kRect_Type; + otherwise, sets type to kEmpty_Type. + + @param rect bounds to set + */ void setRect(const SkRect& rect) { if (!this->initializeRect(rect)) { return; @@ -137,31 +151,61 @@ public: SkASSERT(this->isValid()); } - /** Makes an empty rrect at the origin with zero width and height. */ + /** Initializes bounds at (0, 0), the origin, with zero width and height. + Initializes corner radii to (0, 0), and sets type of kEmpty_Type. + + @return empty SkRRect + */ static SkRRect MakeEmpty() { return SkRRect(); } + /** Initializes to copy of r bounds and zeroes corner radii. + + @param r bounds to copy + @return copy of r + */ static SkRRect MakeRect(const SkRect& r) { SkRRect rr; rr.setRect(r); return rr; } + /** Sets bounds to oval, x-axis radii to half oval.width(), and all y-axis radii + to half oval.height(). If oval bounds is empty, sets to kEmpty_Type. + Otherwise, sets to kOval_Type. + + @param oval bounds of oval + @return oval + */ static SkRRect MakeOval(const SkRect& oval) { SkRRect rr; rr.setOval(oval); return rr; } + /** Sets to rounded rectangle with the same radii for all four corners. + If rect is empty, sets to kEmpty_Type. + Otherwise, if xRad and yRad are zero, sets to kRect_Type. + Otherwise, if xRad is at least half rect.width() and yRad is at least half + rect.height(), sets to kOval_Type. + Otherwise, sets to kSimple_Type. + + @param rect bounds of rounded rectangle + @param xRad x-axis radius of corners + @param yRad y-axis radius of corners + @return rounded rectangle + */ static SkRRect MakeRectXY(const SkRect& rect, SkScalar xRad, SkScalar yRad) { SkRRect rr; rr.setRectXY(rect, xRad, yRad); return rr; } - /** - * Set this RR to match the supplied oval. All x radii will equal half the - * width and all y radii will equal half the height. - */ + /** Sets bounds to oval, x-axis radii to half oval.width(), and all y-axis radii + to half oval.height(). If oval bounds is empty, sets to kEmpty_Type. + Otherwise, sets to kOval_Type. + + @param oval bounds of oval + */ void setOval(const SkRect& oval) { if (!this->initializeRect(oval)) { return; @@ -178,131 +222,278 @@ public: SkASSERT(this->isValid()); } - /** - * Initialize the RR with the same radii for all four corners. - */ + /** Sets to rounded rectangle with the same radii for all four corners. + If rect is empty, sets to kEmpty_Type. + Otherwise, if xRad or yRad is zero, sets to kRect_Type. + Otherwise, if xRad is at least half rect.width() and yRad is at least half + rect.height(), sets to kOval_Type. + Otherwise, sets to kSimple_Type. + + @param rect bounds of rounded rectangle + @param xRad x-axis radius of corners + @param yRad y-axis radius of corners + */ void setRectXY(const SkRect& rect, SkScalar xRad, SkScalar yRad); - /** - * Initialize the rr with one radius per-side. - */ + /** Sets bounds to rect. Sets radii to (leftRad, topRad), (rightRad, topRad), + (rightRad, bottomRad), (leftRad, bottomRad). + + If rect is empty, sets to kEmpty_Type. + Otherwise, if leftRad and rightRad are zero, sets to kRect_Type. + Otherwise, if topRad and bottomRad are zero, sets to kRect_Type. + Otherwise, if leftRad and rightRad are equal and at least half rect.width(), and + topRad and bottomRad are equal at least half rect.height(), sets to kOval_Type. + Otherwise, if leftRad and rightRad are equal, and topRad and bottomRad are equal, + sets to kSimple_Type. Otherwise, sets to kNinePatch_Type. + + Nine patch refers to the nine parts defined by the radii: one center rectangle, + four edge patches, and four corner patches. + + @param rect bounds of rounded rectangle + @param leftRad left-top and left-bottom x-axis radius + @param topRad left-top and right-top y-axis radius + @param rightRad right-top and right-bottom x-axis radius + @param bottomRad left-bottom and right-bottom y-axis radius + */ void setNinePatch(const SkRect& rect, SkScalar leftRad, SkScalar topRad, SkScalar rightRad, SkScalar bottomRad); - /** - * Initialize the RR with potentially different radii for all four corners. - */ + /** Sets bounds to rect. Sets radii array for individual control of all for corners. + + If rect is empty, sets to kEmpty_Type. + Otherwise, if one of each corner radii are zero, sets to kRect_Type. + Otherwise, if all x-axis radii are equal and at least half rect.width(), and + all y-axis radii are equal at least half rect.height(), sets to kOval_Type. + Otherwise, if all x-axis radii are equal, and all y-axis radii are equal, + sets to kSimple_Type. Otherwise, sets to kNinePatch_Type. + + @param rect bounds of rounded rectangle + @param radii corner x-axis and y-axis radii + */ void setRectRadii(const SkRect& rect, const SkVector radii[4]); - // The radii are stored in UL, UR, LR, LL order. + /** \enum SkRRect::Corner + The radii are stored: top-left, top-right, bottom-right, bottom-left. + */ enum Corner { - kUpperLeft_Corner, - kUpperRight_Corner, - kLowerRight_Corner, - kLowerLeft_Corner, + kUpperLeft_Corner, //!< index of top-left corner radii + kUpperRight_Corner, //!< index of top-right corner radii + kLowerRight_Corner, //!< index of bottom-right corner radii + kLowerLeft_Corner, //!< index of bottom-left corner radii }; + /** Returns bounds. Bounds may have zero width or zero height. Bounds right is + greater than or equal to left; bounds bottom is greater than or equal to top. + Result is identical to getBounds(). + + @return bounding box + */ const SkRect& rect() const { return fRect; } + + /** Returns scalar pair for radius of curve on x-axis and y-axis for one corner. + Both radii may be zero. If not zero, both are positive and finite. + + @param corner one of: kUpperLeft_Corner, kUpperRight_Corner, + kLowerRight_Corner, kLowerLeft_Corner + @return x-axis and y-axis radii for one corner + */ SkVector radii(Corner corner) const { return fRadii[corner]; } + + /** Returns bounds. Bounds may have zero width or zero height. Bounds right is + greater than or equal to left; bounds bottom is greater than or equal to top. + Result is identical to rect(). + + @return bounding box + */ const SkRect& getBounds() const { return fRect; } + /** Returns true if bounds and radii in a are equal to bounds and radii in b. + + a and b are not equal if either contain NaN. a and b are equal if members + contain zeroes width different signs. + + @param a SkRect bounds and radii to compare + @param b SkRect bounds and radii to compare + @return true if members are equal + */ friend bool operator==(const SkRRect& a, const SkRRect& b) { return a.fRect == b.fRect && SkScalarsEqual(&a.fRadii[0].fX, &b.fRadii[0].fX, 8); } + /** Returns true if bounds and radii in a are not equal to bounds and radii in b. + + a and b are not equal if either contain NaN. a and b are equal if members + contain zeroes width different signs. + + @param a SkRect bounds and radii to compare + @param b SkRect bounds and radii to compare + @return true if members are not equal + */ friend bool operator!=(const SkRRect& a, const SkRRect& b) { return a.fRect != b.fRect || !SkScalarsEqual(&a.fRadii[0].fX, &b.fRadii[0].fX, 8); } - /** - * Call inset on the bounds, and adjust the radii to reflect what happens - * in stroking: If the corner is sharp (no curvature), leave it alone, - * otherwise we grow/shrink the radii by the amount of the inset. If a - * given radius becomes negative, it is pinned to 0. - * - * If the inset amount is larger than the width/height then the rrect collapses to - * a degenerate line or point. - * - * If the inset is sufficiently negative to cause the bounds to become infinite then - * the result is a default initialized rrect. - * - * It is valid for dst == this. - */ + /** Copies SkRRect to dst, then insets dst bounds by dx and dy, and adjusts dst + radii by dx and dy. dx and dy may be positive, negative, or zero. dst may be + SkRRect. + + If either corner radius is zero, the corner has no curvature and is unchanged. + Otherwise, if adjusted radius becomes negative, pins radius to zero. + If dx exceeds half dst bounds width, dst bounds left and right are set to + bounds x-axis center. If dy exceeds half dst bounds height, dst bounds top and + bottom are set to bounds y-axis center. + + If dx or dy cause the bounds to become infinite, dst bounds is zeroed. + + @param dx added to rect().fLeft, and subtracted from rect().fRight + @param dy added to rect().fTop, and subtracted from rect().fBottom + @param dst insets bounds and radii + */ void inset(SkScalar dx, SkScalar dy, SkRRect* dst) const; + /** Insets bounds by dx and dy, and adjusts radii by dx and dy. dx and dy may be + positive, negative, or zero. + + If either corner radius is zero, the corner has no curvature and is unchanged. + Otherwise, if adjusted radius becomes negative, pins radius to zero. + If dx exceeds half bounds width, bounds left and right are set to + bounds x-axis center. If dy exceeds half bounds height, bounds top and + bottom are set to bounds y-axis center. + + If dx or dy cause the bounds to become infinite, bounds is zeroed. + + @param dx added to rect().fLeft, and subtracted from rect().fRight + @param dy added to rect().fTop, and subtracted from rect().fBottom + */ void inset(SkScalar dx, SkScalar dy) { this->inset(dx, dy, this); } - /** - * Call outset on the bounds, and adjust the radii to reflect what happens - * in stroking: If the corner is sharp (no curvature), leave it alone, - * otherwise we grow/shrink the radii by the amount of the inset. If a - * given radius becomes negative, it is pinned to 0. - * - * It is valid for dst == this. - */ + /** Outsets dst bounds by dx and dy, and adjusts radii by dx and dy. dx and dy may be + positive, negative, or zero. + + If either corner radius is zero, the corner has no curvature and is unchanged. + Otherwise, if adjusted radius becomes negative, pins radius to zero. + If dx exceeds half dst bounds width, dst bounds left and right are set to + bounds x-axis center. If dy exceeds half dst bounds height, dst bounds top and + bottom are set to bounds y-axis center. + + If dx or dy cause the bounds to become infinite, dst bounds is zeroed. + + @param dx subtracted from rect().fLeft, and added to rect().fRight + @param dy subtracted from rect().fTop, and added to rect().fBottom + @param dst outset bounds and radii + */ void outset(SkScalar dx, SkScalar dy, SkRRect* dst) const { this->inset(-dx, -dy, dst); } + + /** Outsets bounds by dx and dy, and adjusts radii by dx and dy. dx and dy may be + positive, negative, or zero. + + If either corner radius is zero, the corner has no curvature and is unchanged. + Otherwise, if adjusted radius becomes negative, pins radius to zero. + If dx exceeds half bounds width, bounds left and right are set to + bounds x-axis center. If dy exceeds half bounds height, bounds top and + bottom are set to bounds y-axis center. + + If dx or dy cause the bounds to become infinite, bounds is zeroed. + + @param dx subtracted from rect().fLeft, and added to rect().fRight + @param dy subtracted from rect().fTop, and added to rect().fBottom + */ void outset(SkScalar dx, SkScalar dy) { this->inset(-dx, -dy, this); } - /** - * Translate the rrect by (dx, dy). - */ + /** Translates SkRRect by (dx, dy). + + @param dx offset added to rect().fLeft and rect().fRight + @param dy offset added to rect().fTop and rect().fBottom + */ void offset(SkScalar dx, SkScalar dy) { fRect.offset(dx, dy); } + /** Returns SkRRect translated by (dx, dy). + + @param dx offset added to rect().fLeft and rect().fRight + @param dy offset added to rect().fTop and rect().fBottom + @return SkRRect bounds offset by (dx, dy), with unchanged corner radii + */ SkRRect SK_WARN_UNUSED_RESULT makeOffset(SkScalar dx, SkScalar dy) const { return SkRRect(fRect.makeOffset(dx, dy), fRadii, fType); } - /** - * Returns true if 'rect' is wholy inside the RR, and both - * are not empty. - */ + /** Returns true if rect is inside the bounds and corner radii, and if + SkRRect and rect are not empty. + + @param rect area tested for containment + @return true if SkRRect contains rect + */ bool contains(const SkRect& rect) const; + /** Returns true if bounds and radii values are finite and describe a SkRRect + SkRRect::Type that matches getType(). All SkRRect methods construct valid types, + even if the input values are not valid. Invalid SkRRect data can only + be generated by corrupting memory. + + @return true if bounds and radii match type() + */ bool isValid() const; static constexpr size_t kSizeInMemory = 12 * sizeof(SkScalar); - /** - * Write the rrect into the specified buffer. This is guaranteed to always - * write kSizeInMemory bytes, and that value is guaranteed to always be - * a multiple of 4. Return kSizeInMemory. - */ + /** Writes SkRRect to buffer. Writes kSizeInMemory bytes, and returns + kSizeInMemory, the number of bytes written. + + @param buffer storage for SkRRect + @return bytes written, kSizeInMemory + */ size_t writeToMemory(void* buffer) const; - /** - * Reads the rrect from the specified buffer - * - * If the specified buffer is large enough, this will read kSizeInMemory bytes, - * and that value is guaranteed to always be a multiple of 4. - * - * @param buffer Memory to read from - * @param length Amount of memory available in the buffer - * @return number of bytes read (must be a multiple of 4) or - * 0 if there was not enough memory available - */ + /** Reads SkRRect from buffer, reading kSizeInMemory bytes. + Returns kSizeInMemory, bytes read if length is at least kSizeInMemory. + Otherwise, returns zero. + + @param buffer memory to read from + @param length size of buffer + @return bytes read, or 0 if length is less than kSizeInMemory + */ size_t readFromMemory(const void* buffer, size_t length); - /** - * Transform by the specified matrix, and put the result in dst. - * - * @param matrix SkMatrix specifying the transform. Must only contain - * scale and/or translate, or this call will fail. - * @param dst SkRRect to store the result. It is an error to use this, - * which would make this function no longer const. - * @return true on success, false on failure. - */ + /** Transforms by SkRRect by matrix, storing result in dst. + Returns true if SkRRect transformed can be represented by another SkRRect. + Returns false if matrix contains transformations other than scale and translate. + + Asserts in debug builds if SkRRect equals dst. + + @param matrix SkMatrix specifying the transform + @param dst SkRRect to store the result + @return true if transformation succeeded. + */ bool transform(const SkMatrix& matrix, SkRRect* dst) const; + /** Writes text representation of SkRRect to standard output. + Set asHex true to generate exact binary representations + of floating point numbers. + + @param asHex true if SkScalar values are written as hexadecimal + */ void dump(bool asHex) const; + + /** Writes text representation of SkRRect 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 + SkRRect from output. + */ void dump() const { this->dump(false); } + + /** Writes text representation of SkRRect to standard output. The representation + may be directly compiled as C++ code. Floating point values are written + in hexadecimal to preserve their exact bit pattern. The output reconstructs the + original SkRRect. + */ void dumpHex() const { this->dump(true); } private: diff --git a/include/core/SkRect.h b/include/core/SkRect.h index ed0e599ad9..2ba6b2234a 100644 --- a/include/core/SkRect.h +++ b/include/core/SkRect.h @@ -6,7 +6,7 @@ */ /* Generated by tools/bookmaker from include/core/SkRect.h and docs/SkRect_Reference.bmh - on 2018-06-14 13:13:34. Additional documentation and examples can be found at: + on 2018-07-13 08:15:11. Additional documentation and examples can be found at: https://skia.org/user/api/SkRect_Reference You may edit either file directly. Structural changes to public interfaces require @@ -904,7 +904,7 @@ struct SK_API SkRect { */ SkScalar width() const { return fRight - fLeft; } - /** Returns span on the y-axis. This does not check if SkIRect is sorted, or if + /** Returns span on the y-axis. This does not check if SkRect is sorted, or if result fits in 32-bit float; result may be negative or infinity. @return fBottom minus fTop @@ -922,7 +922,7 @@ struct SK_API SkRect { } /** Returns average of top edge and bottom edge. Result does not change if SkRect - is sorted. Result may overflow to infinity if SkRect is far from the origin. + is sorted. @return midpoint in y */ diff --git a/include/core/SkSurface.h b/include/core/SkSurface.h index 37a3b98d23..9d3c816732 100644 --- a/include/core/SkSurface.h +++ b/include/core/SkSurface.h @@ -6,7 +6,7 @@ */ /* Generated by tools/bookmaker from include/core/SkSurface.h and docs/SkSurface_Reference.bmh - on 2018-06-14 13:13:34. Additional documentation and examples can be found at: + on 2018-07-13 08:15:11. Additional documentation and examples can be found at: https://skia.org/user/api/SkSurface_Reference You may edit either file directly. Structural changes to public interfaces require @@ -609,6 +609,7 @@ public: Source SkRect corners are (0, 0) and (src.width(), src.height()). Destination SkRect corners are (dstX, dstY) and (dstX + Surface width(), dstY + Surface height()). + Copies each readable pixel intersecting both rectangles, without scaling, converting to SkSurface colorType() and SkSurface alphaType() if required. @@ -622,6 +623,7 @@ public: Source SkRect corners are (0, 0) and (src.width(), src.height()). Destination SkRect corners are (dstX, dstY) and (dstX + Surface width(), dstY + Surface height()). + Copies each readable pixel intersecting both rectangles, without scaling, converting to SkSurface colorType() and SkSurface alphaType() if required. |