skia2/site/user/api/SkPoint_Reference.md
Cary Clark 09d80c0337 docs with more pop
Replace a hunk of documentation in docs/*.bmh
with #Populate, which instructs bookmaker to
retrieve the documentation from include/core.

Check spelling for all documentation retrieved
from include/core against Skia declarations
and a list of words in spelling.txt.

TBR=caryclark@google.com
Docs-Preview: https://skia.org/?cl=163491
Bug: skia:
Change-Id: If057c3a1336e312ad59c084a3a130f0276802496
Reviewed-on: https://skia-review.googlesource.com/c/163491
Commit-Queue: Cary Clark <caryclark@skia.org>
Reviewed-by: Cary Clark <caryclark@skia.org>
Auto-Submit: Cary Clark <caryclark@skia.org>
2018-10-31 16:45:32 +00:00

51 KiB

SkPoint Reference


struct SkPoint {
    SkScalar fX;
    SkScalar fY;

    static constexpr SkPoint Make(SkScalar x, SkScalar y);
    SkScalar x() const;
    SkScalar y() const;
    bool isZero() const;
    void set(SkScalar x, SkScalar y);
    void iset(int32_t x, int32_t y);
    void iset(const SkIPoint& p);
    void setAbs(const SkPoint& pt);
    static void Offset(SkPoint points[], int count, const SkVector& offset);
    static void Offset(SkPoint points[], int count, SkScalar dx, SkScalar dy);
    void offset(SkScalar dx, SkScalar dy);
    SkScalar length() const;
    SkScalar distanceToOrigin() const;
    bool normalize();
    bool setNormalize(SkScalar x, SkScalar y);
    bool setLength(SkScalar length);
    bool setLength(SkScalar x, SkScalar y, SkScalar length);
    void scale(SkScalar scale, SkPoint* dst) const;
    void scale(SkScalar value);
    void negate();
    SkPoint operator-()_const;
    void operator+=(const SkVector& v);
    void operator-=(const SkVector& v);
    SkPoint operator*(SkScalar scale)_const;
    SkPoint& operator*=(SkScalar scale);
    bool isFinite() const;
    bool equals(SkScalar x, SkScalar y) const;
    friend bool operator==(const SkPoint& a, const SkPoint& b);
    friend bool operator!=(const SkPoint& a, const SkPoint& b);
    friend SkVector operator-(const SkPoint& a, const SkPoint& b);
    friend SkPoint operator+(const SkPoint& a, const SkVector& b);
    static SkScalar Length(SkScalar x, SkScalar y);
    static SkScalar Normalize(SkVector* vec);
    static SkScalar Distance(const SkPoint& a, const SkPoint& b);
    static SkScalar DotProduct(const SkVector& a, const SkVector& b);
    static SkScalar CrossProduct(const SkVector& a, const SkVector& b);
    SkScalar cross(const SkVector& vec) const;
    SkScalar dot(const SkVector& vec) const;
};

SkPoint holds two 32-bit floating point coordinates.

Type Member Description
SkScalar fX x-axis value used by both Point and Vector. May contain any value, including infinities and NaN.
SkScalar fY y-axis value used by both Point and Vector. May contain any value, including infinities and NaN.


static constexpr SkPoint Make(SkScalar x, SkScalar y)

Sets fX to x, fY to y. Used both to set SkPoint and vector.

Parameters

x SkScalar x-axis value of constructed SkPoint or vector
y SkScalar y-axis value of constructed SkPoint or vector

Return Value

SkPoint (x, y)

Example

Example Output

all equal

See Also

set() iset[2]() SkIPoint::Make


SkScalar x() const

Returns x-axis value of SkPoint or vector.

Return Value

fX

Example

Example Output

pt1.fX == pt1.x()

See Also

y() SkIPoint::x()


SkScalar y() const

Returns y-axis value of SkPoint or vector.

Return Value

fY

Example

Example Output

pt1.fY == pt1.y()

See Also

x() SkIPoint::y()


bool isZero() const

Returns true if fX and fY are both zero.

Return Value

true if fX is zero and fY is zero

Example

Example Output

pt.fX=+0 pt.fY=-0
pt.isZero() == true

See Also

isFinite SkIPoint::isZero


void set(SkScalar x, SkScalar y)

Sets fX to x and fY to y.

Parameters

x new value for fX
y new value for fY

Example

Example Output

pt1 == pt2

See Also

iset[2]() Make


void iset(int32_t x, int32_t y)

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.

Parameters

x new value for fX
y new value for fY

Example

See Also

set Make SkIPoint::set


void iset(const SkIPoint& p)

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.

Parameters

p SkIPoint members promoted to SkScalar

Example

Example Output

iPt: -2147483647, 2147483647
fPt: -2.14748e+09, 2.14748e+09

See Also

set Make SkIPoint::set


void setAbs(const SkPoint& pt)

Sets fX to absolute value of pt.fX; and fY to absolute value of pt.fY.

Parameters

pt members providing magnitude for fX and fY

Example

Example Output

pt: 0, -0  abs: 0, 0
pt: -1, -2  abs: 1, 2
pt: inf, -inf  abs: inf, inf
pt: nan, -nan  abs: nan, nan

See Also

set Make negate


static void Offset(SkPoint points[], int count, const SkVector& offset)

Adds offset to each SkPoint in points array with count entries.

Parameters

points SkPoint array
count entries in array
offset vector added to points

Example

See Also

offset operator+=(const SkVector& v)


static void Offset(SkPoint points[], int count, SkScalar dx, SkScalar dy)

Adds offset (dx, dy) to each SkPoint in points array of length count.

Parameters

points SkPoint array
count entries in array
dx added to fX in points
dy added to fY in points

Example

See Also

offset operator+=(const SkVector& v)


void offset(SkScalar dx, SkScalar dy)

Adds offset (dx, dy) to SkPoint.

Parameters

dx added to fX
dy added to fY

Example

See Also

Offset[2] operator+=(const SkVector& v)


SkScalar length() const

Returns the Euclidean distance from origin, computed as:

sqrt(fX * fX + fY * fY)

.

Return Value

straight-line distance to origin

Example

See Also

distanceToOrigin Length setLength[2] Distance


SkScalar distanceToOrigin() const

Returns the Euclidean distance from origin, computed as:

sqrt(fX * fX + fY * fY)

.

Return Value

straight-line distance to origin

Example

See Also

length Length setLength[2] Distance


bool normalize()

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 Value

true if former length is not zero or nearly zero

Example

See Also

Normalize setLength[2] length Length


bool setNormalize(SkScalar x, SkScalar y)

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.

Parameters

x proportional value for fX
y proportional value for fY

Return Value

true if (x, y) length is not zero or nearly zero

Example

See Also

normalize setLength[2]


bool setLength(SkScalar length)

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.

Parameters

length straight-line distance to origin

Return Value

true if former length is not zero or nearly zero

Example

See Also

length Length setNormalize setAbs


bool setLength(SkScalar x, SkScalar y, SkScalar length)

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.

Parameters

x proportional value for fX
y proportional value for fY
length straight-line distance to origin

Return Value

true if (x, y) length is not zero or nearly zero

Example

See Also

length Length setNormalize setAbs


void scale(SkScalar scale, SkPoint* dst) const

Sets dst to SkPoint times scale. dst may be SkPoint to modify SkPoint in place.

Parameters

scale factor to multiply SkPoint by
dst storage for scaled SkPoint

Example

See Also

operator*(SkScalar scale) const operator*=(SkScalar scale) setLength[2]


void scale(SkScalar value)

Scales SkPoint in place by scale.

Parameters

value factor to multiply SkPoint by

Example

See Also

operator*(SkScalar scale) const operator*=(SkScalar scale) setLength[2]


void negate()

Changes the sign of fX and fY.

Example

Example Output

pt: 0, -0  negate: -0, 0
pt: -1, -2  negate: 1, 2
pt: inf, -inf  negate: -inf, inf
pt: nan, -nan  negate: -nan, nan

See Also

operator-() const setAbs


SkPoint operator-() const

Returns SkPoint changing the signs of fX and fY.

Return Value

SkPoint as (-fX, -fY)

Example

Example Output

pt: 0, -0  negate: -0, 0
pt: -1, -2  negate: 1, 2
pt: inf, -inf  negate: -inf, inf
pt: nan, -nan  negate: -nan, nan

See Also

negate operator-(const SkPoint& a, const SkPoint& b) operator-=(const SkVector& v) SkIPoint::operator-() const


void operator+=(const SkVector& v)

Adds Vector v to Point. Sets Point to: (fX + v.fX, fY + v.fY).

Parameters

v Vector to add

Example

See Also

offset() operator+(const SkPoint& a, const SkVector& b) SkIPoint::operator+=(const SkIVector& v)


void operator-=(const SkVector& v)

Subtracts Vector v from Point. Sets Point to: (fX - v.fX, fY - v.fY).

Parameters

v Vector to subtract

Example

See Also

offset() operator-(const SkPoint& a, const SkPoint& b) SkIPoint::operator-=(const SkIVector& v)


SkPoint operator*(SkScalar scale) const

Returns SkPoint multiplied by scale.

Parameters

scale scalar to multiply by

Return Value

SkPoint as (fX * scale, fY * scale)

Example

See Also

operator*=(SkScalar scale) scale[2]() setLength[2] setNormalize


SkPoint& operator*=(SkScalar scale)

Multiplies Point by scale. Sets Point to: (fX * scale, fY * scale).

Parameters

scale Scalar to multiply by

Return Value

reference to Point

Example

See Also

operator*(SkScalar scale) const scale[2]() setLength[2] setNormalize


bool isFinite() const

Returns true if both fX and fY are measurable values.

Return Value

true for values other than infinities and NaN

Example

Example Output

pt: 0, -0  finite: true
pt: -1, -2  finite: true
pt: inf, 1  finite: false
pt: nan, -1  finite: false

See Also

SkRect::isFinite SkPath::isFinite


bool equals(SkScalar x, SkScalar y) const

Returns true if SkPoint is equivalent to SkPoint constructed from (x, y).

Parameters

x value compared with fX
y value compared with fY

Return Value

true if SkPoint equals (x, y)

Example

Example Output

pt: 0, -0  == pt
pt: -1, -2  == pt
pt: inf, 1  == pt
pt: nan, -1  != pt

See Also

operator==(const SkPoint& a, const SkPoint& b)


bool operator==(const SkPoint& a, const SkPoint& b)

Returns true if a is equivalent to b.

Parameters

a SkPoint to compare
b SkPoint to compare

Return Value

true if a.fX == b.fX and a.fY == b.fY

Example

Example Output

pt: 0, -0  == pt
pt: -1, -2  == pt
pt: inf, 1  == pt
pt: nan, -1  != pt

See Also

equals() operator!=(const SkPoint& a, const SkPoint& b)


bool operator!=(const SkPoint& a, const SkPoint& b)

Returns true if a is not equivalent to b.

Parameters

a SkPoint to compare
b SkPoint to compare

Return Value

true if a.fX != b.fX or a.fY != b.fY

Example

Example Output

pt: 0, -0  == pt
pt: -1, -2  == pt
pt: inf, 1  == pt
pt: nan, -1  != pt

See Also

operator==(const SkPoint& a, const SkPoint& b) equals()


SkVector operator-(const SkPoint& a, const SkPoint& 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 Point, returning Point. Can also be used to subtract Vector from Vector, returning Vector.

Parameters

a Point to subtract from
b Point to subtract

Return Value

Vector from b to a

Example

See Also

operator-=(const SkVector& v) offset()


SkPoint operator+(const SkPoint& a, const SkVector& b)

Returns Point resulting from Point a offset by Vector b, computed as: (a.fX + b.fX, a.fY + b.fY).

Can also be used to offset Point b by Vector a, returning Point. Can also be used to add Vector to Vector, returning Vector.

Parameters

a Point or Vector to add to
b Point or Vector to add

Return Value

Point equal to a offset by b

Example

See Also

operator+=(const SkVector& v) offset()


static SkScalar Length(SkScalar x, SkScalar y)

Returns the Euclidean distance from origin, computed as:

sqrt(x * x + y * y)

.

Parameters

x component of length
y component of length

Return Value

straight-line distance to origin

Example

See Also

length() Distance setLength[2]


static SkScalar Normalize(SkVector* vec)

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.

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.

Parameters

vec normalized to unit length

Return Value

original vec length

Example

See Also

normalize() setLength[2] Length


static SkScalar Distance(const SkPoint& a, const SkPoint& b)

Returns the Euclidean distance between a and b.

Parameters

a line end point
b line end point

Return Value

straight-line distance from a to b

Example

See Also

length() setLength[2]


static SkScalar DotProduct(const SkVector& a, const SkVector& b)

Returns the dot product of vector a and vector b.

Parameters

a left side of dot product
b right side of dot product

Return Value

product of input magnitudes and cosine of the angle between them

Example

See Also

dot CrossProduct


static SkScalar CrossProduct(const SkVector& a, const SkVector& b)

Returns the cross product of vector a and vector b.

a and b form three-dimensional vectors with z-axis value equal to zero. The cross product is a three-dimensional vector with x-axis and y-axis values equal to zero. The cross product z-axis component is returned.

Parameters

a left side of cross product
b right side of cross product

Return Value

area spanned by vectors signed by angle direction

Example

See Also

cross DotProduct


SkScalar cross(const SkVector& vec) const

Returns the cross product of vector and vec.

Vector and vec form three-dimensional vectors with z-axis value equal to zero. The cross product is a three-dimensional vector with x-axis and y-axis values equal to zero. The cross product z-axis component is returned.

Parameters

vec right side of cross product

Return Value

area spanned by vectors signed by angle direction

Example

See Also

CrossProduct dot


SkScalar dot(const SkVector& vec) const

Returns the dot product of vector and vector vec.

Parameters

vec right side of dot product

Return Value

product of input magnitudes and cosine of the angle between them

Example

See Also

DotProduct cross


    typedef SkPoint SkVector;

SkVector provides an alternative name for SkPoint. SkVector and SkPoint can be used interchangeably for all purposes.