refresh public includes
Update includes to fix minor edits
and bookmaker bugs.
Also update SkPoint.h for the first
time to see if that sticks.
TBR=reed@google.com
Bug: skia:6898
Change-Id: I7d11dea45482602248e2d15b05699bb4c86ea4c6
Reviewed-on: https://skia-review.googlesource.com/90541
Commit-Queue: Cary Clark <caryclark@skia.org>
Reviewed-by: Cary Clark <caryclark@skia.org>
diff --git a/include/core/SkPoint.h b/include/core/SkPoint.h
index 57f0fd7d..3ccc33e 100644
--- a/include/core/SkPoint.h
+++ b/include/core/SkPoint.h
@@ -12,20 +12,41 @@
#include "SkScalar.h"
/** \struct SkIPoint16
-
SkIPoint holds two 16 bit integer coordinates
*/
struct SkIPoint16 {
- int16_t fX;
- int16_t fY;
+ int16_t fX; //!< x-axis value used by SkIPoint16.
+ int16_t fY; //!< y-axis value used by SkIPoint16.
+
+ /** Sets fX to x, fY to y. If SK_DEBUG is defined, asserts
+ if x or y does not fit in 16 bits.
+
+ @param x integer x-axis value of constructed SkIPoint
+ @param y integer y-axis value of constructed SkIPoint
+ @return SkIPoint16 (x, y)
+ */
static constexpr SkIPoint16 Make(int x, int y) {
return {SkToS16(x), SkToS16(y)};
}
+ /** Returns x-axis value of SkIPoint16.
+
+ @return fX
+ */
int16_t x() const { return fX; }
+
+ /** Returns y-axis value of SkIPoint.
+
+ @return fY
+ */
int16_t y() const { return fY; }
+ /** Sets fX to x and fY to y.
+
+ @param x new value for fX
+ @param y new value for fY
+ */
void set(int x, int y) {
fX = SkToS16(x);
fY = SkToS16(y);
@@ -36,71 +57,127 @@
typedef SkIPoint SkIVector;
/** \struct SkIPoint
-
SkIPoint holds two 32 bit integer coordinates
*/
struct SkIPoint {
- int32_t fX;
- int32_t fY;
+ int32_t fX; //!< x-axis value used by SkIPoint.
+ int32_t fY; //!< y-axis value used by SkIPoint.
+
+ /** Sets fX to x, fY to y.
+
+ @param x integer x-axis value of constructed SkIPoint
+ @param y integer y-axis value of constructed SkIPoint
+ @return SkIPoint (x, y)
+ */
static constexpr SkIPoint Make(int32_t x, int32_t y) {
return {x, y};
}
+ /** Returns x-axis value of SkIPoint.
+
+ @return fX
+ */
int32_t x() const { return fX; }
+
+ /** Returns y-axis value of SkIPoint.
+
+ @return fY
+ */
int32_t y() const { return fY; }
- /**
- * Returns true iff fX and fY are both zero.
- */
+ /** Returns true if fX and fY are both zero.
+
+ @return true if fX is zero and fY is zero
+ */
bool isZero() const { return (fX | fY) == 0; }
- /** Set the x and y values of the point. */
+ /** Sets fX to x and fY to y.
+
+ @param x new value for fX
+ @param y new value for fY
+ */
void set(int32_t x, int32_t y) {
fX = x;
fY = y;
}
- /** Return a new point whose X and Y coordinates are the negative of the
- original point's
+ /** Returns SkIPoint changing the signs of fX and fY.
+
+ @return SkIPoint as (-fX, -fY)
*/
SkIPoint operator-() const {
return {-fX, -fY};
}
- /** Add v's coordinates to this point's */
+ /** Offsets SkIPoint by ivector v. Sets SkIPoint to (fX + v.fX, fY + v.fY).
+
+ @param v ivector to add
+ */
void operator+=(const SkIVector& v) {
fX += v.fX;
fY += v.fY;
}
- /** Subtract v's coordinates from this point's */
+ /** Subtracts ivector v from SkIPoint. Sets SkIPoint to: (fX - v.fX, fY - v.fY).
+
+ @param v ivector to subtract
+ */
void operator-=(const SkIVector& v) {
fX -= v.fX;
fY -= v.fY;
}
- /** Returns true if the point's coordinates equal (x,y) */
+ /** Returns true if SkIPoint is equivalent to SkIPoint constructed from (x, y).
+
+ @param x value compared with fX
+ @param y value compared with fY
+ @return true if SkIPoint equals (x, y)
+ */
bool equals(int32_t x, int32_t y) const {
return fX == x && fY == y;
}
+ /** Returns true if a is equivalent to b.
+
+ @param a SkIPoint to compare
+ @param b SkIPoint to compare
+ @return true if a.fX == b.fX and a.fY == b.fY
+ */
friend bool operator==(const SkIPoint& a, const SkIPoint& b) {
return a.fX == b.fX && a.fY == b.fY;
}
+ /** Returns true if a is not equivalent to b.
+
+ @param a SkIPoint to compare
+ @param b SkIPoint to compare
+ @return true if a.fX != b.fX or a.fY != b.fY
+ */
friend bool operator!=(const SkIPoint& a, const SkIPoint& b) {
return a.fX != b.fX || a.fY != b.fY;
}
- /** Returns a new point whose coordinates are the difference between
- a and b (i.e. a - b)
+ /** Returns ivector from b to a; computed as (a.fX - b.fX, a.fY - b.fY).
+
+ Can also be used to subtract ivector from ivector, returning ivector.
+
+ @param a SkIPoint or ivector to subtract from
+ @param b ivector to subtract
+ @return ivector from b to a
*/
friend SkIVector operator-(const SkIPoint& a, const SkIPoint& b) {
return {a.fX - b.fX, a.fY - b.fY};
}
- /** Returns a new point whose coordinates are the sum of a and b (a + b)
+ /** Returns SkIPoint resulting from SkIPoint a offset by ivector b, computed as: (a.fX + b.fX, a.fY + b.fY).
+
+ Can also be used to offset SkIPoint b by ivector a, returning SkIPoint.
+ Can also be used to add ivector to ivector, returning ivector.
+
+ @param a SkIPoint or ivector to add to
+ @param b SkIPoint or ivector to add
+ @return SkIPoint equal to a offset by b
*/
friend SkIPoint operator+(const SkIPoint& a, const SkIVector& b) {
return {a.fX + b.fX, a.fY + b.fY};
@@ -110,143 +187,255 @@
struct SkPoint;
typedef SkPoint SkVector;
+/** \struct SkPoint
+*/
struct SK_API SkPoint {
- SkScalar fX;
- SkScalar fY;
+ /** x-axis value used by both SkPoint and vector. May contain any value, including
+ infinities and NaN.
+ */
+ SkScalar fX;
+
+ /** y-axis value used by both SkPoint and vector. May contain any value, including
+ infinities and NaN.
+ */
+ SkScalar fY;
+
+ /** Sets fX to x, fY to y. Used both to set SkPoint and vector.
+
+ @param x SkScalar x-axis value of constructed SkPoint or vector
+ @param y SkScalar y-axis value of constructed SkPoint or vector
+ @return SkPoint (x, y)
+ */
static constexpr SkPoint Make(SkScalar x, SkScalar y) {
return {x, y};
}
+ /** Returns x-axis value of SkPoint or vector.
+
+ @return fX
+ */
SkScalar x() const { return fX; }
+
+ /** Returns y-axis value of SkPoint or vector.
+
+ @return fY
+ */
SkScalar y() const { return fY; }
- /**
- * Returns true iff fX and fY are both zero.
- */
+ /** Returns true if fX and fY are both zero.
+
+ @return true if fX is zero and fY is zero
+ */
bool isZero() const { return (0 == fX) & (0 == fY); }
- /** Set the point's X and Y coordinates */
+ /** Sets fX to x and fY to y.
+
+ @param x new value for fX
+ @param y new value for fY
+ */
void set(SkScalar x, SkScalar y) {
fX = x;
fY = y;
}
- /** Set the point's X and Y coordinates by automatically promoting (x,y) to
- SkScalar values.
+ /** Sets fX to x and fY to y, promoting integers to SkScalar values.
+
+ Assigning a large integer value directly to fX or fY may cause a compiler
+ error, triggered by narrowing conversion of int to SkScalar. This safely
+ casts x and y to avoid the error.
+
+ @param x new value for fX
+ @param y new value for fY
*/
void iset(int32_t x, int32_t y) {
fX = SkIntToScalar(x);
fY = SkIntToScalar(y);
}
- /** Set the point's X and Y coordinates by automatically promoting p's
- coordinates to SkScalar values.
+ /** Sets fX to p.fX and fY to p.fY, promoting integers to SkScalar values.
+
+ Assigning an SkIPoint containing a large integer value directly to fX or fY may
+ cause a compiler error, triggered by narrowing conversion of int to SkScalar.
+ This safely casts p.fX and p.fY to avoid the error.
+
+ @param p SkIPoint members promoted to SkScalar
*/
void iset(const SkIPoint& p) {
fX = SkIntToScalar(p.fX);
fY = SkIntToScalar(p.fY);
}
+ /** Sets fX to absolute value of pt.fX; and fY to absolute value of pt.fY.
+
+ @param pt members providing magnitude for fX and fY
+ */
void setAbs(const SkPoint& pt) {
fX = SkScalarAbs(pt.fX);
fY = SkScalarAbs(pt.fY);
}
+ /** Adds offset to each SkPoint in points array with count entries.
+
+ @param points SkPoint array
+ @param count entries in array
+ @param offset vector added to points
+ */
static void Offset(SkPoint points[], int count, const SkVector& offset) {
Offset(points, count, offset.fX, offset.fY);
}
+ /** Adds offset (dx, dy) to each SkPoint in points array of length count.
+
+ @param points SkPoint array
+ @param count entries in array
+ @param dx added to fX in points
+ @param dy added to fY in points
+ */
static void Offset(SkPoint points[], int count, SkScalar dx, SkScalar dy) {
for (int i = 0; i < count; ++i) {
points[i].offset(dx, dy);
}
}
+ /** Adds offset (dx, dy) to SkPoint.
+
+ @param dx added to fX
+ @param dy added to fY
+ */
void offset(SkScalar dx, SkScalar dy) {
fX += dx;
fY += dy;
}
- /** Return the euclidian distance from (0,0) to the point
+ /** Returns the Euclidean_Distance from origin, computed as:
+
+ sqrt(fX * fX + fY * fY)
+
+ .
+
+ @return straight-line distance to origin
*/
SkScalar length() const { return SkPoint::Length(fX, fY); }
+
+ /** Returns the Euclidean_Distance from origin, computed as:
+
+ sqrt(fX * fX + fY * fY)
+
+ .
+
+ @return straight-line distance to origin
+ */
SkScalar distanceToOrigin() const { return this->length(); }
- /** Set the point (vector) to be unit-length in the same direction as it
- already points. If the point has a degenerate length (i.e. nearly 0)
- then set it to (0,0) and return false; otherwise return true.
+ /** Scales (fX, fY) so that length() returns one, while preserving ratio of fX to fY,
+ if possible. If prior length is nearly zero, sets vector to (0, 0) and returns
+ false; otherwise returns true.
+
+ @return true if former length is not zero or nearly zero
*/
bool normalize();
- /** Set the point (vector) to be unit-length in the same direction as the
- x,y params. If the vector (x,y) has a degenerate length (i.e. nearly 0)
- then set it to (0,0) and return false, otherwise return true.
+ /** Sets vector to (x, y) scaled so length() returns one, and so that
+ (fX, fY) is proportional to (x, y). If (x, y) length is nearly zero,
+ sets vector to (0, 0) and returns false; otherwise returns true.
+
+ @param x proportional value for fX
+ @param y proportional value for fY
+ @return true if (x, y) length is not zero or nearly zero
*/
bool setNormalize(SkScalar x, SkScalar y);
- /** Scale the point (vector) to have the specified length, and return that
- length. If the original length is degenerately small (nearly zero),
- set it to (0,0) and return false, otherwise return true.
+ /** Scales vector so that distanceToOrigin() returns length, if possible. If former
+ length is nearly zero, sets vector to (0, 0) and return false; otherwise returns
+ true.
+
+ @param length straight-line distance to origin
+ @return true if former length is not zero or nearly zero
*/
bool setLength(SkScalar length);
- /** Set the point (vector) to have the specified length in the same
- direction as (x,y). If the vector (x,y) has a degenerate length
- (i.e. nearly 0) then set it to (0,0) and return false, otherwise return true.
+ /** Sets vector to (x, y) scaled to length, if possible. If former
+ length is nearly zero, sets vector to (0, 0) and return false; otherwise returns
+ true.
+
+ @param x proportional value for fX
+ @param y proportional value for fY
+ @param length straight-line distance to origin
+ @return true if (x, y) length is not zero or nearly zero
*/
bool setLength(SkScalar x, SkScalar y, SkScalar length);
- /** Scale the point's coordinates by scale, writing the answer into dst.
- It is legal for dst == this.
+ /** Sets dst to SkPoint times scale. dst may be SkPoint to modify SkPoint in place.
+
+ @param scale factor to multiply SkPoint by
+ @param dst storage for scaled SkPoint
*/
void scale(SkScalar scale, SkPoint* dst) const;
- /** Scale the point's coordinates by scale, writing the answer back into
- the point.
+ /** Scales SkPoint in place by scale.
+
+ @param value factor to multiply SkPoint by
*/
void scale(SkScalar value) { this->scale(value, this); }
- /** Negate the point's coordinates
+ /** Changes the sign of fX and fY.
*/
void negate() {
fX = -fX;
fY = -fY;
}
- /** Returns a new point whose coordinates are the negative of the point's
+ /** Returns SkPoint changing the signs of fX and fY.
+
+ @return SkPoint as (-fX, -fY)
*/
SkPoint operator-() const {
return {-fX, -fY};
}
- /** Add v's coordinates to the point's
+ /** Adds vector v to SkPoint. Sets SkPoint to: (fX + v.fX, fY + v.fY).
+
+ @param v vector to add
*/
void operator+=(const SkVector& v) {
fX += v.fX;
fY += v.fY;
}
- /** Subtract v's coordinates from the point's
+ /** Subtracts vector v from SkPoint. Sets SkPoint to: (fX - v.fX, fY - v.fY).
+
+ @param v vector to subtract
*/
void operator-=(const SkVector& v) {
fX -= v.fX;
fY -= v.fY;
}
+ /** Returns SkPoint multiplied by scale.
+
+ @param scale scalar to multiply by
+ @return SkPoint as (fX * scale, fY * scale)
+ */
SkPoint operator*(SkScalar scale) const {
return {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
+ */
SkPoint& operator*=(SkScalar scale) {
fX *= scale;
fY *= scale;
return *this;
}
- /**
- * Returns true if both X and Y are finite (not infinity or NaN)
- */
+ /** Returns true if both fX and fY are measurable values.
+
+ @return true for values other than infinities and NaN
+ */
bool isFinite() const {
SkScalar accum = 0;
accum *= fX;
@@ -260,71 +449,139 @@
return !SkScalarIsNaN(accum);
}
- /**
- * Returns true if the point's coordinates equal (x,y)
- */
+ /** Returns true if SkPoint is equivalent to SkPoint constructed from (x, y).
+
+ @param x value compared with fX
+ @param y value compared with fY
+ @return true if SkPoint equals (x, y)
+ */
bool equals(SkScalar x, SkScalar y) const {
return fX == x && fY == y;
}
+ /** Returns true if a is equivalent to b.
+
+ @param a SkPoint to compare
+ @param b SkPoint to compare
+ @return true if a.fX == b.fX and a.fY == b.fY
+ */
friend bool operator==(const SkPoint& a, const SkPoint& b) {
return a.fX == b.fX && a.fY == b.fY;
}
+ /** Returns true if a is not equivalent to b.
+
+ @param a SkPoint to compare
+ @param b SkPoint to compare
+ @return true if a.fX != b.fX or a.fY != b.fY
+ */
friend bool operator!=(const SkPoint& a, const SkPoint& b) {
return a.fX != b.fX || a.fY != b.fY;
}
- /** Returns a new point whose coordinates are the difference between
- a's and b's (a - b)
+ /** Returns vector from b to a, computed as (a.fX - b.fX, a.fY - b.fY).
+
+ Can also be used to subtract vector from SkPoint, returning SkPoint.
+ Can also be used to subtract vector from vector, returning vector.
+
+ @param a SkPoint to subtract from
+ @param b SkPoint to subtract
+ @return vector from b to a
*/
friend SkVector operator-(const SkPoint& a, const SkPoint& b) {
return {a.fX - b.fX, a.fY - b.fY};
}
- /** Returns a new point whose coordinates are the sum of a's and b's (a + b)
+ /** Returns SkPoint resulting from SkPoint a offset by vector b, computed as: (a.fX + b.fX, a.fY + b.fY).
+
+ Can also be used to offset SkPoint b by vector a, returning SkPoint.
+ Can also be used to add vector to vector, returning vector.
+
+ @param a SkPoint or vector to add to
+ @param b SkPoint or vector to add
+ @return SkPoint equal to a offset by b
*/
friend SkPoint operator+(const SkPoint& a, const SkVector& b) {
return {a.fX + b.fX, a.fY + b.fY};
}
- /** Returns the euclidian distance from (0,0) to (x,y)
+ /** Returns the Euclidean_Distance from origin, computed as:
+
+ sqrt(x * x + y * y)
+
+ .
+
+ @param x component of length
+ @param y component of length
+ @return straight-line distance to origin
*/
static SkScalar Length(SkScalar x, SkScalar y);
- /** Normalize pt, returning its previous length. If the prev length is too
- small (degenerate), set pt to (0,0) and return 0. This uses the same
- tolerance as CanNormalize.
+ /** Scales (vec->fX, vec->fY) so that length() returns one, while preserving ratio of vec->fX to vec->fY,
+ if possible. If original length is nearly zero, sets vec to (0, 0) and returns zero;
+ otherwise, returns length of vec before vec is scaled.
- Note that this method may be significantly more expensive than
- the non-static normalize(), because it has to return the previous length
- of the point. If you don't need the previous length, call the
- non-static normalize() method instead.
- */
+ Returned prior length may be SK_ScalarInfinity if it can not be represented by SkScalar.
+
+ Note that normalize() is faster if prior length is not required.
+
+ @param vec normalized to unit length
+ @return original vec length
+ */
static SkScalar Normalize(SkVector* vec);
- /** Returns the euclidian distance between a and b
+ /** Returns the Euclidean_Distance between a and b.
+
+ @param a line end point
+ @param b line end point
+ @return straight-line distance from a to b
*/
static SkScalar Distance(const SkPoint& a, const SkPoint& b) {
return Length(a.fX - b.fX, a.fY - b.fY);
}
- /** Returns the dot product of a and b, treating them as 2D vectors
+ /** Returns the dot product of vector a and vector b.
+
+ @param a left side of dot product
+ @param b right side of dot product
+ @return product of input magnitudes and cosine of the angle between them
*/
static SkScalar DotProduct(const SkVector& a, const SkVector& b) {
return a.fX * b.fX + a.fY * b.fY;
}
- /** Returns the cross product of a and b, treating them as 2D vectors
+ /** Returns the cross product of vector a and vector b.
+
+ a and b form three-dimensional vectors with z equal to zero. The cross product
+ is a three-dimensional vector with x and y equal to zero. The cross product z
+ term equals the returned value.
+
+ @param a left side of cross product
+ @param b right side of cross product
+ @return area spanned by vectors signed by angle direction
*/
static SkScalar CrossProduct(const SkVector& a, const SkVector& b) {
return a.fX * b.fY - a.fY * b.fX;
}
+ /** Returns the cross product of vector and vec.
+
+ Vector and vec form three-dimensional vectors with z equal to zero. The
+ cross product is a three-dimensional vector with x and y equal to zero.
+ The cross product z term equals the returned value.
+
+ @param vec right side of cross product
+ @return area spanned by vectors signed by angle direction
+ */
SkScalar cross(const SkVector& vec) const {
return CrossProduct(*this, vec);
}
+ /** Returns the dot product of vector and vector vec.
+
+ @param vec right side of dot product
+ @return product of input magnitudes and cosine of the angle between them
+ */
SkScalar dot(const SkVector& vec) const {
return DotProduct(*this, vec);
}