From 75959391681495896570e7bf8d7f9effdd1306f3 Mon Sep 17 00:00:00 2001 From: Cary Clark Date: Tue, 27 Feb 2018 10:22:04 -0500 Subject: updated includes update includes to latest bookmaker docs TBR=reed@google.com Bug: skia:6898 Change-Id: If42ab25f98a0f0d8b410ae30ca1cd641e19ce89f Reviewed-on: https://skia-review.googlesource.com/107021 Commit-Queue: Cary Clark Reviewed-by: Cary Clark --- include/core/SkRect.h | 191 ++++++++++++++++++++++++++------------------------ 1 file changed, 98 insertions(+), 93 deletions(-) (limited to 'include/core/SkRect.h') diff --git a/include/core/SkRect.h b/include/core/SkRect.h index 7f1eff0690..f9a5bff4ff 100644 --- a/include/core/SkRect.h +++ b/include/core/SkRect.h @@ -56,10 +56,7 @@ struct SK_API SkIRect { } #ifdef SK_SUPPORT_LEGACY_RECTMAKELARGEST - /** Returns constructed SkIRect setting left and top to most negative value, and - setting right and bottom to most positive value. - - @return bounds (SK_MinS32, SK_MinS32, SK_MaxS32, SK_MaxS32) + /** Deprecated. */ static SkIRect SK_WARN_UNUSED_RESULT MakeLargest() { return { SK_MinS32, SK_MinS32, SK_MaxS32, SK_MaxS32 }; @@ -69,8 +66,8 @@ struct SK_API SkIRect { /** Returns constructed SkIRect set to (0, 0, w, h). Does not validate input; w or h may be negative. - @param w width of constructed SkRect - @param h height of constructed SkRect + @param w width of constructed SkIRect + @param h height of constructed SkIRect @return bounds (0, 0, w, h) */ static constexpr SkIRect SK_WARN_UNUSED_RESULT MakeWH(int32_t w, int32_t h) { @@ -80,14 +77,14 @@ struct SK_API SkIRect { /** Returns constructed SkIRect set to (0, 0, size.width(), size.height()). Does not validate input; size.width() or size.height() may be negative. - @param size values for SkRect width and height + @param size values for SkIRect width and height @return bounds (0, 0, size.width(), size.height()) */ static constexpr SkIRect SK_WARN_UNUSED_RESULT MakeSize(const SkISize& size) { return SkIRect{0, 0, size.fWidth, size.fHeight}; } - /** Returns constructed SkIRect set to (l, t, r, b). Does not sort input; SkRect may + /** Returns constructed SkIRect set to (l, t, r, b). Does not sort input; SkIRect may result in fLeft greater than fRight, or fTop greater than fBottom. @param l integer stored in fLeft @@ -178,8 +175,8 @@ struct SK_API SkIRect { */ SkISize size() const { return SkISize::Make(this->width(), this->height()); } - /** Returns average of left edge and right edge. Result does not change if SkRect - is sorted. Result may be incorrect if SkRect is far from the origin. + /** Returns average of left edge and right edge. Result does not change if SkIRect + is sorted. Result may be incorrect if SkIRect is far from the origin. Result is rounded down. @@ -187,8 +184,8 @@ struct SK_API SkIRect { */ int32_t centerX() const { return SkToS32(((int64_t)fRight + fLeft) >> 1); } - /** Returns average of top edge and bottom edge. Result does not change if SkRect - is sorted. Result may be incorrect if SkRect is far from the origin. + /** Returns average of top edge and bottom edge. Result does not change if SkIRect + is sorted. Result may be incorrect if SkIRect is far from the origin. Result is rounded down. @@ -196,18 +193,34 @@ struct SK_API SkIRect { */ int32_t centerY() const { return SkToS32(((int64_t)fBottom + fTop) >> 1); } + /** Returns span on the x-axis. This does not check if SkIRect is sorted, so the + result may be negative. This is safer than calling width() since width() might + overflow in its calculation. + + @return fRight minus fLeft cast to int64_t + */ int64_t width64() const { return (int64_t)fRight - (int64_t)fLeft; } + + /** Returns span on the y-axis. This does not check if SkIRect is sorted, so the + result may be negative. This is safer than calling height() since height() might + overflow in its calculation. + + @return fBottom minus fTop cast to int64_t + */ int64_t height64() const { return (int64_t)fBottom - (int64_t)fTop; } - /** Returns true if the rectangle's dimensions are non-positive. - * Unlike isEmpty(), this does not worry about the size of the width or height, which could - * exceed int32_t but still be logically non-empty. - */ + /** Returns true if fLeft is equal to or greater than fRight, or if fTop is equal + to or greater than fBottom. Call sort() to reverse rectangles with negative + width64() or height64(). + + @return true if width64() or height64() are zero or negative + */ bool isEmpty64() const { return fRight <= fLeft || fBottom <= fTop; } - /** Returns true if the rectangle's dimensions are non-positive or if either its width or hieght - * exceeds int32_t. - */ + /** Returns true if width() or height() . + + @return true if width() or height() are zero or negative + */ bool isEmpty() const { int64_t w = this->width64(); int64_t h = this->height64(); @@ -311,7 +324,7 @@ struct SK_API SkIRect { @param dx offset added to fLeft and fRight @param dy offset added to fTop and fBottom - @return SkRect offset in x or y, with original width and height + @return SkIRect offset in x or y, with original width and height */ SkIRect makeOffset(int32_t dx, int32_t dy) const { return { @@ -329,7 +342,7 @@ struct SK_API SkIRect { @param dx offset added to fLeft and subtracted from fRight @param dy offset added to fTop and subtracted from fBottom - @return SkRect inset symmetrically left and right, top and bottom + @return SkIRect inset symmetrically left and right, top and bottom */ SkIRect makeInset(int32_t dx, int32_t dy) const { return { @@ -347,7 +360,7 @@ struct SK_API SkIRect { @param dx offset subtracted to fLeft and added from fRight @param dy offset subtracted to fTop and added from fBottom - @return SkRect outset symmetrically left and right, top and bottom + @return SkIRect outset symmetrically left and right, top and bottom */ SkIRect makeOutset(int32_t dx, int32_t dy) const { return { @@ -419,10 +432,10 @@ struct SK_API SkIRect { /** Outsets SkIRect by (dx, dy). - If dx is positive, makes SkRect wider. - If dx is negative, makes SkRect narrower. - If dy is positive, makes SkRect taller. - If dy is negative, makes SkRect shorter. + If dx is positive, makes SkIRect wider. + If dx is negative, makes SkIRect narrower. + If dy is positive, makes SkIRect taller. + If dy is negative, makes SkIRect shorter. @param dx subtracted to fLeft and added from fRight @param dy subtracted to fTop and added from fBottom @@ -435,10 +448,10 @@ struct SK_API SkIRect { Is implemented with short circuit logic so that true can be returned after a single compare. - @param l x minimum of constructed SkRect - @param t y minimum of constructed SkRect - @param r x maximum of constructed SkRect - @param b y maximum of constructed SkRect + @param l x minimum of constructed SkIRect + @param t y minimum of constructed SkIRect + @param r x maximum of constructed SkIRect + @param b y maximum of constructed SkIRect @return true if construction and SkIRect have no area in common */ bool quickReject(int l, int t, int r, int b) const { @@ -446,29 +459,29 @@ struct SK_API SkIRect { } /** Returns true if: fLeft <= x < fRight && fTop <= y < fBottom. - Returns false if SkRect is empty. + Returns false if SkIRect is empty. Considers input to describe constructed SkIRect: (x, y, x + 1, y + 1) and returns true if constructed area is completely enclosed by SkIRect area. - @param x test SkPoint x-coordinate - @param y test SkPoint y-coordinate + @param x test SkIPoint x-coordinate + @param y test SkIPoint y-coordinate @return true if (x, y) is inside SkIRect */ bool contains(int32_t x, int32_t y) const { return x >= fLeft && x < fRight && y >= fTop && y < fBottom; } - /** Constructs SkRect to intersect from (left, top, right, bottom). Does not sort + /** Constructs SkIRect to intersect from (left, top, right, bottom). Does not sort construction. - Returns true if SkRect contains construction. - Returns false if SkRect is empty or construction is empty. + Returns true if SkIRect contains construction. + Returns false if SkIRect is empty or construction is empty. - @param left x minimum of constructed SkRect - @param top y minimum of constructed SkRect - @param right x maximum of constructed SkRect - @param bottom y maximum of constructed SkRect + @param left x minimum of constructed SkIRect + @param top y minimum of constructed SkIRect + @param right x maximum of constructed SkIRect + @param bottom y maximum of constructed SkIRect @return true if all sides of SkIRect are outside construction */ bool contains(int32_t left, int32_t top, int32_t right, int32_t bottom) const { @@ -477,10 +490,10 @@ struct SK_API SkIRect { fRight >= right && fBottom >= bottom; } - /** Returns true if SkRect contains r. - Returns false if SkRect is empty or r is empty. + /** Returns true if SkIRect contains r. + Returns false if SkIRect is empty or r is empty. - SkRect contains r when SkRect area completely includes r area. + SkIRect contains r when SkIRect area completely includes r area. @param r SkIRect contained @return true if all sides of SkIRect are outside r @@ -491,10 +504,10 @@ struct SK_API SkIRect { fRight >= r.fRight && fBottom >= r.fBottom; } - /** Returns true if SkRect contains r. - Returns false if SkRect is empty or r is empty. + /** Returns true if SkIRect contains r. + Returns false if SkIRect is empty or r is empty. - SkRect contains r when SkRect area completely includes r area. + SkIRect contains r when SkIRect area completely includes r area. @param r SkRect contained @return true if all sides of SkIRect are outside r @@ -504,15 +517,15 @@ struct SK_API SkIRect { /** Constructs SkIRect from (left, top, right, bottom). Does not sort construction. - Returns true if SkRect contains construction. + Returns true if SkIRect contains construction. Asserts if SkIRect is empty or construction is empty, and if SK_DEBUG is defined. - Return is undefined if SkRect is empty or construction is empty. + Return is undefined if SkIRect is empty or construction is empty. - @param left x minimum of constructed SkRect - @param top y minimum of constructed SkRect - @param right x maximum of constructed SkRect - @param bottom y maximum of constructed SkRect + @param left x minimum of constructed SkIRect + @param top y minimum of constructed SkIRect + @param right x maximum of constructed SkIRect + @param bottom y maximum of constructed SkIRect @return true if all sides of SkIRect are outside construction */ bool containsNoEmptyCheck(int32_t left, int32_t top, @@ -524,12 +537,12 @@ struct SK_API SkIRect { fRight >= right && fBottom >= bottom; } - /** Returns true if SkRect contains construction. + /** Returns true if SkIRect contains construction. Asserts if SkIRect is empty or construction is empty, and if SK_DEBUG is defined. - Return is undefined if SkRect is empty or construction is empty. + Return is undefined if SkIRect is empty or construction is empty. - @param r SkRect contained + @param r SkIRect contained @return true if all sides of SkIRect are outside r */ bool containsNoEmptyCheck(const SkIRect& r) const { @@ -542,7 +555,7 @@ struct SK_API SkIRect { Returns false if either r or SkIRect is empty, leaving SkIRect unchanged. @param r limit of result - @return true if r and SkRect have area in common + @return true if r and SkIRect have area in common */ bool intersect(const SkIRect& r) { return this->intersect(*this, r); @@ -573,14 +586,14 @@ struct SK_API SkIRect { } /** Returns true if a intersects b, and sets SkIRect to intersection. - Returns false if a does not intersect b, and leaves SkIRect unchanged. + Returns false if a does not intersect b, and leaves SkIRect unchanged. - Returns false if either a or b is empty, leaving SkIRect unchanged. + Returns false if either a or b is empty, leaving SkIRect unchanged. - @param a SkIRect to intersect - @param b SkIRect to intersect - @return true if a and b have area in common - */ + @param a SkIRect to intersect + @param b SkIRect to intersect + @return true if a and b have area in common + */ bool SK_WARN_UNUSED_RESULT intersect(const SkIRect& a, const SkIRect& b) { if (a.isEmpty64() || b.isEmpty64()) { return false; @@ -630,26 +643,26 @@ struct SK_API SkIRect { return dummy.intersectNoEmptyCheck(a, b); } - /** Constructs SkRect to intersect from (left, top, right, bottom). Does not sort + /** Constructs SkIRect to intersect from (left, top, right, bottom). Does not sort construction. - Sets SkRect to the union of itself and the construction. + Sets SkIRect to the union of itself and the construction. - Has no effect if construction is empty. Otherwise, if SkRect is empty, sets - SkRect to construction. + Has no effect if construction is empty. Otherwise, if SkIRect is empty, sets + SkIRect to construction. - @param left x minimum of constructed SkRect - @param top y minimum of constructed SkRect - @param right x maximum of constructed SkRect - @param bottom y maximum of constructed SkRect + @param left x minimum of constructed SkIRect + @param top y minimum of constructed SkIRect + @param right x maximum of constructed SkIRect + @param bottom y maximum of constructed SkIRect */ void join(int32_t left, int32_t top, int32_t right, int32_t bottom); - /** Sets SkRect to the union of itself and r. + /** Sets SkIRect to the union of itself and r. - Has no effect if r is empty. Otherwise, if SkRect is empty, sets SkRect to r. + Has no effect if r is empty. Otherwise, if SkIRect is empty, sets SkIRect to r. - @param r expansion SkRect + @param r expansion SkIRect */ void join(const SkIRect& r) { this->join(r.fLeft, r.fTop, r.fRight, r.fBottom); @@ -668,7 +681,7 @@ struct SK_API SkIRect { } } - /** Returns SkRect with fLeft and fRight swapped if fLeft is greater than fRight; and + /** Returns SkIRect with fLeft and fRight swapped if fLeft is greater than fRight; and with fTop and fBottom swapped if fTop is greater than fBottom. Result may be empty; and width() and height() will be zero or positive. @@ -730,10 +743,7 @@ struct SK_API SkRect { } #ifdef SK_SUPPORT_LEGACY_RECTMAKELARGEST - /** Returns constructed SkRect setting left and top to most negative finite value, and - setting right and bottom to most positive finite value. - - @return bounds (SK_ScalarMin, SK_ScalarMin, SK_ScalarMax, SK_ScalarMax) + /** Deprecated. */ static SkRect SK_WARN_UNUSED_RESULT MakeLargest() { return { SK_ScalarMin, SK_ScalarMin, SK_ScalarMax, SK_ScalarMax }; @@ -808,9 +818,6 @@ struct SK_API SkRect { } /** Deprecated. - - @param irect integer rect - @return irect as SkRect */ SK_ATTR_DEPRECATED("use Make()") static SkRect SK_WARN_UNUSED_RESULT MakeFromIRect(const SkIRect& irect) { @@ -849,13 +856,11 @@ struct SK_API SkRect { } /** Returns true if fLeft is equal to or greater than fRight, or if fTop is equal - * to or greater than fBottom. Call sort() to reverse rectangles with negative - * width() or height(). - * - * This function also returns true if any of the values are NaN. - * - * @return true if width() or height() are zero or negative - */ + to or greater than fBottom. Call sort() to reverse rectangles with negative + width() or height(). + + @return true if width() or height() are zero or negative + */ bool isEmpty() const { // We write it as the NOT of a non-empty rect, so we will return true if any values // are NaN. @@ -1117,7 +1122,7 @@ struct SK_API SkRect { */ bool setBoundsCheck(const SkPoint pts[], int count); - /** Sets bounds to the smallest SkRect enclosing points p0 and p1. The result is + /** Sets bounds to the smallest SkRect enclosing SkPoint p0 and p1. The result is sorted and may be empty. Does not check to see if values are finite. @param p0 corner to include @@ -1477,7 +1482,7 @@ public: } /** Sets SkIRect by discarding the fractional portion of fLeft and fTop; and - rounding up fRight and fbottom, using (SkScalarFloorToInt(fLeft), SkScalarFloorToInt(fTop), + rounding up fRight and fBottom, using (SkScalarFloorToInt(fLeft), SkScalarFloorToInt(fTop), SkScalarCeilToInt(fRight), SkScalarCeilToInt(fBottom)). @param dst storage for SkIRect @@ -1489,7 +1494,7 @@ public: } /** Sets SkRect by discarding the fractional portion of fLeft and fTop; and - rounding up fRight and fbottom, using (SkScalarFloorToInt(fLeft), SkScalarFloorToInt(fTop), + rounding up fRight and fBottom, using (SkScalarFloorToInt(fLeft), SkScalarFloorToInt(fTop), SkScalarCeilToInt(fRight), SkScalarCeilToInt(fBottom)). @param dst storage for SkRect @@ -1502,7 +1507,7 @@ public: } /** Sets SkRect by rounding up fLeft and fTop; and - discarding the fractional portion of fRight and fbottom, using + discarding the fractional portion of fRight and fBottom, using (SkScalarCeilToInt(fLeft), SkScalarCeilToInt(fTop), SkScalarFloorToInt(fRight), SkScalarFloorToInt(fBottom)). @@ -1527,7 +1532,7 @@ public: } /** Sets SkIRect by discarding the fractional portion of fLeft and fTop; and - rounding up fRight and fbottom, using (SkScalarFloorToInt(fLeft), SkScalarFloorToInt(fTop), + rounding up fRight and fBottom, using (SkScalarFloorToInt(fLeft), SkScalarFloorToInt(fTop), SkScalarCeilToInt(fRight), SkScalarCeilToInt(fBottom)). @return rounded SkIRect -- cgit v1.2.3