PMRect Class Reference

#include <PMRect.h>

Public Types
enum	PointIndex {   kInvalidPoint = -1, kFirstPoint = 0, kMiddleTop = 0, kLeftMiddle = 1,   kMiddleBottom = 2, kRightMiddle = 3, kLeftTop = 4, kRightTop = 5,   kRightBottom = 6, kLeftBottom = 7, kCenter = 8, kLastPoint = kCenter }
typedef base_type	data_type

Public Member Functions
constexpr	PMRect () noexcept
	PMRect (const PMPoint &point) noexcept
	PMRect (const PMPoint &one_corner, const PMPoint &opposing_corner) noexcept
	PMRect (const PMReal &l, const PMReal &t, const PMReal &r, const PMReal &b) noexcept
	PMRect (const SysRect &r) noexcept
	PMRect (const dvacore::geom::RectT< float > &r) noexcept
constexpr	PMRect (const PMRect &) noexcept=default
constexpr	PMRect (PMRect &&) noexcept=default
PMRect &	operator= (const PMRect &) noexcept=default
PMRect &	operator= (PMRect &&) noexcept=default
bool16	IsEmpty () const noexcept
bool16	IsCorner (PointIndex whichPoint) const noexcept
bool16	IsMiddle (PointIndex whichPoint) const noexcept
bool16	PointIn (const PMPoint &pt) const noexcept
bool16	ContainsPoint (const PMPoint &pt) const noexcept
bool16	RectIn (const PMRect &r) const noexcept
bool16	ContainsRect (const PMRect &r) const noexcept
bool16	ContainsRect (const PMRect &r, const PMMatrix &r_to_this_xform) const
PMReal	AspectRatio () const
PMReal	DistanceTo (const PMPoint &pt) const
const PMReal &	Left () const noexcept
PMReal &	Left () noexcept
void	Left (const PMReal &c) noexcept
const PMReal &	Top () const noexcept
PMReal &	Top () noexcept
void	Top (const PMReal &c) noexcept
const PMReal &	Right () const noexcept
PMReal &	Right () noexcept
void	Right (const PMReal &c) noexcept
const PMReal &	Bottom () const noexcept
PMReal &	Bottom () noexcept
void	Bottom (const PMReal &c) noexcept
PMPoint	LeftTop (void) const noexcept
void	LeftTop (const PMPoint &pt) noexcept
PMPoint	RightBottom (void) const noexcept
void	RightBottom (const PMPoint &pt) noexcept
PMPoint	RightTop (void) const noexcept
void	RightTop (const PMPoint &pt) noexcept
PMPoint	LeftBottom (void) const noexcept
void	LeftBottom (const PMPoint &pt) noexcept
PMReal	Height () const noexcept
PMReal	Width () const noexcept
PMPoint	Dimensions () const noexcept
void	SetHeight (const PMReal &height)
void	SetWidth (const PMReal &width)
void	SetDimensions (const PMReal &width, const PMReal &height)
PMReal	GetHCenter () const
PMReal	GetVCenter () const
PMPoint	GetCenter () const
PMPoint	GetPoint (PointIndex whichPoint) const
PointIndex	GetPointIndex (const PMPoint &aPoint) const
PMPoint	GetOppositePoint (PointIndex whichPoint) const
PointIndex	GetOppositePointIndex (PointIndex whichPoint) const
PMRect &	SetEmpty () noexcept
bool16	Normalize () noexcept
PMRect &	Round ()
PointIndex	MovePointTo (PointIndex whichPoint, const PMPoint &toPt)
PMRect &	MoveRel (const PMReal &dx, const PMReal &dy)
PMRect &	MoveRel (const PMPoint &point)
PMRect &	MoveTo (const PMReal &dx, const PMReal &dy)
PMRect &	MoveTo (const PMPoint &point)
PMRect &	CenterOn (const PMReal &dx, const PMReal &dy)
PMRect &	CenterOn (const PMPoint &point)
PMRect &	Inset (const PMReal &dx, const PMReal &dy)
bool16	ConstrainTo (PMRect &constrainedRect)
void	Union (const PMRect &rhs)
void	Expand (const PMPoint &pt)
void	ReadWrite (IPMStream *iPMStream)

Static Public Member Functions
static int32	PointIndexToIndex (PMRect::PointIndex ptIndex)
static PMRect::PointIndex	IndexToPointIndex (int32 index)

Friends
SysRect	ToSys (const PMRect &r)
dvacore::geom::RectT< float >	ToRectF32_ (const PMRect &r)
Int32Rect	ToInt32Rect_ (const PMRect &r)
bool16	Intersect (const PMRect &r1, const PMRect &r2)
bool16	Intersect_exact (const PMRect &r1, const PMRect &r2)
bool16	Intersect (const PMRect &r1, const PMMatrix &xform, const PMRect &r2)
PMRect	MakeIntersect (const PMRect &r1, const PMMatrix &xform, const PMRect &r2)
bool16	IntersectOrAbut (const PMRect &r1, const PMRect &r2)
bool16	IntersectOrAbut_exact (const PMRect &r1, const PMRect &r2)
bool16	IntersectOrAbut (const PMRect &r1, const PMMatrix &xform, const PMRect &r2)
PMRect	MakeIntersectOrAbut (const PMRect &r1, const PMMatrix &xform, const PMRect &r2)
PMRect	Intersection (const PMRect &r1, const PMRect &r2, const PMRect &emptyRect)
PMRect	IntersectionOrAbut (const PMRect &r1, const PMRect &r2, const PMRect &emptyRect)
PMRect	Union (const PMRect &r1, const PMRect &r2)
bool16	UnionIsRect (const PMRect &r1, const PMRect &r2)
bool16	operator== (const PMRect &a, const PMRect &b) noexcept
bool16	operator!= (const PMRect &a, const PMRect &b) noexcept
bool16	Intersect_ (const PMRect &r1, const PMMatrix &r1_to_r2_xform, const PMRect &r2, PMPoint *p)
bool16	IntersectOrAbut_ (const PMRect &r1, const PMMatrix &r1_to_r2_xform, const PMRect &r2, PMPoint *p)

Detailed Description

Simple rectangle type

See Also

PMReal

PMPoint

Member Enumeration Documentation

enum PMRect::PointIndex

Point types in a PMRect

Enumerator
kInvalidPoint	An invalid point index.
kFirstPoint	The first valid point index.
kMiddleTop	The point at the middle of the rectangle's top segment.
kLeftMiddle	The point at the middle of the rectangle's left segment.
kMiddleBottom	The point at the middle of the rectangle's bottom segment.
kRightMiddle	The point at the middle of the rectangle's right segment.
kLeftTop	The left-top corner point.
kRightTop	The right-top corner point.
kRightBottom	The right-bottom corner point.
kLeftBottom	The left-bottom corner point.
kCenter	The point at the center of the rectangle.
kLastPoint	The last valid point index.

Constructor & Destructor Documentation

constexpr PMRect::PMRect ( )

inlinenoexcept

Constructs an empty PMRect situated at origin. The resulting rectangle has its components all set to zero and has zero width and height.

PMRect::PMRect ( const PMPoint &  point )

explicitnoexcept

Constructs an empty PMRect situated at the specified point. The rectangle's left and right are set to point's X component, and its top and bottom are set to point's Y component.

Parameters

point

IN The point at which the rectangle is situated

PMRect::PMRect ( const PMPoint &  one_corner, const PMPoint &  opposing_corner  )

noexcept

Constructs a PMRect with the specified opposing corners.

Parameters

one_corner	IN One corner of the rectangle
opposing_corner	IN The corner of the rectangle opposite one_corner

PMRect::PMRect ( const PMReal &  l, const PMReal &  t, const PMReal &  r, const PMReal &  b  )

noexcept

Constructs a PMRect with the specified top-left and bottom-right. Note since the constructed rectangle is normalized, l and r can be passed in swapped, as can t and b.

Parameters

l	IN The left component for the rectangle
t	IN The top component for the rectangle
r	IN The right component for the rectangle
b	IN The bottom component for the rectangle

PMRect::PMRect ( const SysRect &  r )

noexcept

Constructs a PMRect based on the specified system rectangle.

Parameters

r	IN The system rectangle on which the rectangle is based

PMRect::PMRect ( const dvacore::geom::RectT< float > &  r )

explicitnoexcept

Constructs a PMRect based on the drover rectangle.

Parameters

r	IN The drover rectangle on which the rectangle is based

Member Function Documentation

PMReal PMRect::AspectRatio

(

)

const

Calculates the aspect ratio for the rectangle. The aspect ratio is calculated as the ratio of the rectangle's height to its width. If the rectangle is empty, zero is returned.

Returns

The aspect ratio for the rectangle

const PMReal & PMRect::Bottom ( ) const

inlinenoexcept

Returns a const reference to the rectangle's bottom component.

Returns

The rectangle's bottom component

PMReal & PMRect::Bottom ( )

inlinenoexcept

Returns a reference to the rectangle's bottom component.

Returns

The rectangle's bottom component

void PMRect::Bottom ( const PMReal &  c )

inlinenoexcept

Sets the rectangle's bottom component.

Parameters

c	IN The rectangle's new bottom component

bool16 PMRect::ConstrainTo

(

PMRect &

constrainedRect

)

Constrains the specified rectangle to the bounds of this rectangle.

Parameters

constrainedRect

IN/OUT The rectangle to be constrained

Returns

kTrue if any of the input rectangle's components were changed, else kFalse if it was already constrained

bool16 PMRect::ContainsPoint ( const PMPoint &  pt ) const

inlinenoexcept

Determines whether the specified point falls within this rectangle or on its border. Unlike PointIn, ContainsPoint uses exact machine double comparisons, not fuzzy PMReal comparisons.

Parameters

pt	IN The point to test

Returns

kTrue if the point falls within the rectangle, else kFalse

bool16 PMRect::ContainsRect ( const PMRect &  r ) const

inlinenoexcept

Determines whether the passed in rectangle r is contained with 'this' rectangle. Unlike RectIn, ContainsRect uses exact machine double comparisons, not fuzzy PMReal comparisons.

Parameters

r	IN The rectangle to test

Returns

kTrue if the rectangle r is contained with this rectangle, else kFalse

bool16 PMRect::ContainsRect	(	const PMRect &	r,
		const PMMatrix &	r_to_this_xform
	)		const

Determines whether the passed in rectangle r when transformed by r_to_this_xform is contained with 'this' rectangle.

Parameters

r	IN The rectangle to test
r_to_this_xform	IN the matrix that brings r into the coordinate space of this

Returns

kTrue if the rectangle r is contained with this rectangle, else kFalse

PMPoint PMRect::Dimensions ( ) const

inlinenoexcept

Returns the dimensions of the rectangle as a PMPoint.

NOTE: This assumes the rect is normalized.

Returns

The dimensions of the rectangle

PMReal PMRect::DistanceTo

(

const PMPoint &

pt

)

const

Calculates the distance from the specified point to one of the rectangle's edges.

Parameters

pt	IN The point to test

Returns

The distance from the specified point to the rectangle

void PMRect::Expand

(

const PMPoint &

pt

)

Expands this rectangle so that it is large enough to contain the specified point. Identical to Union with a rectangle that encompasses the point.

Parameters

pt	IN The point used in the expansion

PMPoint PMRect::GetCenter

(

)

const

Returns the center of the rectangle.

Returns

The center of the rectangle

PMReal PMRect::GetHCenter

(

)

const

Returns the horizontal center of the rectangle.

Returns

The horizontal center of the rectangle

PMPoint PMRect::GetOppositePoint ( PointIndex  whichPoint ) const

inline

Retrieves the point opposite to the specified point in the rectangle.

Returns

The point opposite the specified point

PMRect::PointIndex PMRect::GetOppositePointIndex ( PointIndex  whichPoint ) const

inline

Retrieves the index of the point opposite the specified point in the rectangle.

Parameters

whichPoint

IN The index of the point whose opposite is to be returned

Returns

The index of the point opposite the specified point index

PMPoint PMRect::GetPoint

(

PointIndex

whichPoint

)

const

Retrieves the specified point in the rectangle.

Returns

The specified point

PointIndex PMRect::GetPointIndex

(

const PMPoint &

aPoint

)

const

Retrieves the point index for the specified point. If the point does not correspond to any of enumerated points, kInvalidPoint is returned.

Parameters

aPoint

IN The point to test

Returns

The index of the point, or kInvalidPoint if the point doesn't match any of the enumerated indices

PMReal PMRect::GetVCenter

(

)

const

Returns the vertical center of the rectangle.

Returns

The vertical center of the rectangle

PMReal PMRect::Height ( ) const

inlinenoexcept

Returns the height of the rectangle.

NOTE: This assumes the rect is normalized.

Returns

The height of the rectangle

static PMRect::PointIndex PMRect::IndexToPointIndex ( int32  index )

static

Converts an integer into a PointIndex. Used internally in some hit-testing code. Probably not useful for third-party developers.

Parameters

index

IN The integer value to convert

Returns

The integer as a point index

PMRect & PMRect::Inset ( const PMReal &  dx, const PMReal &  dy  )

inline

Contracts the rectangle by (dx, dy) on all sides. Positive values contract the rectangle, negative values enlarge it.

Parameters

dx	IN The amount by which the left and right components are adjusted
dy	IN The amount by which the top and bottom components are adjusted

Returns

A reference to this rectangle

bool16 PMRect::IsCorner ( PointIndex  whichPoint ) const

inlinenoexcept

Determines whether specified point index identifies a corner point.

Parameters

whichPoint

IN The point index to test

bool16 PMRect::IsEmpty ( void  ) const

inlinenoexcept

Determines whether rectangle is empty. A rectangle is empty if its left and right or top and bottom components are equal.

Returns

kTrue if the rectangle is empty, else kFalse

bool16 PMRect::IsMiddle ( PointIndex  whichPoint ) const

inlinenoexcept

Determines whether specified point index identifies a middle point.

Parameters

whichPoint

IN The point index to test

const PMReal & PMRect::Left ( ) const

inlinenoexcept

Returns a const reference to the rectangle's left component.

Returns

The rectangle's left component

PMReal & PMRect::Left ( )

inlinenoexcept

Returns a reference to the rectangle's left component.

Returns

The rectangle's left component

void PMRect::Left ( const PMReal &  c )

inlinenoexcept

Sets the rectangle's left component.

Parameters

c	IN The rectangle's new left component

PMPoint PMRect::LeftBottom ( void  ) const

inlinenoexcept

Returns the rectangle's bottom-left point.

Returns

The rectangle's bottom-left point

void PMRect::LeftBottom ( const PMPoint &  pt )

inlinenoexcept

Sets the rectangle's bottom-left point.

Parameters

pt	IN The rectangle's new bottom-left point

PMPoint PMRect::LeftTop ( void  ) const

inlinenoexcept

Returns the rectangle's top-left point.

Returns

The rectangle's top-left point

void PMRect::LeftTop ( const PMPoint &  pt )

inlinenoexcept

Sets the rectangle's top-left point.

Parameters

pt	IN The rectangle's new top-left point

PointIndex PMRect::MovePointTo	(	PointIndex	whichPoint,
		const PMPoint &	toPt
	)

Moves the given point to the new location and returns the (possibly changed) index of the moved point.

NOTE: MidPoints will only move perpendicular to their side of the rectangle. Only the height or width will change, not both.

Parameters

whichPoint	IN The index of the point to move
toPt	IN The new location for the specified point

Returns

The index of the moved point

bool16 PMRect::Normalize ( )

noexcept

Normalizes this rectangle so that its right component is greater than its left, and its bottom greater than its top.

Returns

kTrue if the components of the rectangle were adjusted during normalization, else kFalse if it was already normalized

bool16 PMRect::PointIn ( const PMPoint &  pt ) const

inlinenoexcept

Determines whether the specified point falls within this rectangle

Parameters

pt	IN The point to test

Returns

kTrue if the point falls within the rectangle, else kFalse

static int32 PMRect::PointIndexToIndex ( PMRect::PointIndex  ptIndex )

static

Converts a PointIndex into an integer. Used internally in some hit-testing code. Probably not useful for third-party developers.

Parameters

ptIndex

IN The point index to convert

Returns

The point index as an integer value

void PMRect::ReadWrite

(

IPMStream *

iPMStream

)

Persists this rectangle to the specified stream

Parameters

iPMStream

IN The stream to which the rectangle's components are written

bool16 PMRect::RectIn ( const PMRect &  r ) const

inlinenoexcept

Determines whether the passed in rectangle r is contained with 'this' rectangle.

Parameters

r	IN The rectangle to test

Returns

kTrue if the rectangle r is contained with this rectangle, else kFalse

const PMReal & PMRect::Right ( ) const

inlinenoexcept

Returns a const reference to the rectangle's right component.

Returns

The rectangle's right component

PMReal & PMRect::Right ( )

inlinenoexcept

Returns a reference to the rectangle's right component.

Returns

The rectangle's right component

void PMRect::Right ( const PMReal &  c )

inlinenoexcept

Sets the rectangle's right component.

Parameters

c	IN The rectangle's new right component

PMPoint PMRect::RightBottom ( void  ) const

inlinenoexcept

Returns the rectangle's bottom-right point.

Returns

The rectangle's bottom-right point

void PMRect::RightBottom ( const PMPoint &  pt )

inlinenoexcept

Sets the rectangle's bottom-right point.

Parameters

pt	IN The rectangle's new bottom-right point

PMPoint PMRect::RightTop ( void  ) const

inlinenoexcept

Returns the rectangle's top-right point.

Returns

The rectangle's top-right point

void PMRect::RightTop ( const PMPoint &  pt )

inlinenoexcept

Sets the rectangle's top-right point.

Parameters

pt	IN The rectangle's new top-right point

PMRect& PMRect::Round

(

)

Adjusts the components of the rectangle by rounding them to the nearest integer value.

Returns

A reference to this rectangle

void PMRect::SetDimensions	(	const PMReal &	width,
		const PMReal &	height
	)

Sets the dimensions of the rectangle by adjusting its bottom and right components. The width and height are assumed to be positive.

Parameters

width	IN The new width for the rectangle
height	IN The new height for the rectangle

PMRect & PMRect::SetEmpty ( void  )

inlinenoexcept

Makes the rectangle empty by setting its right and bottom components equal to its left and top components, respectively.

Returns

A reference to this rectangle

void PMRect::SetHeight

(

const PMReal &

height

)

Sets the height of the rectangle by adjusting its bottom component. The height is assumed to be positive.

Parameters

height

IN The new height for the rectangle

void PMRect::SetWidth

(

const PMReal &

width

)

Sets the width of the rectangle by adjusting its right component. The width is assumed to be positive.

Parameters

width

IN The new width for the rectangle

const PMReal & PMRect::Top ( ) const

inlinenoexcept

Returns a const reference to the rectangle's top component.

Returns

The rectangle's top component

PMReal & PMRect::Top ( )

inlinenoexcept

Returns a reference to the rectangle's top component.

Returns

The rectangle's top component

void PMRect::Top ( const PMReal &  c )

inlinenoexcept

Sets the rectangle's top component.

Parameters

c	IN The rectangle's new top component

void PMRect::Union

(

const PMRect &

rhs

)

Unions this rectangle with another. Note this member function differs from the friend Union(r1, r2) declared below in the behavior of rectangles with zero-area (those for which IsEmpty() returns true). This member function deliberately ignores any contribution from zero-area rectangles. So if rhs.IsEmpty(), then Union returns immediately with *this not modified. Otherwise if this->IsEmpty(), then rhs is copied to *this. Otherwise *this is extended to be the smallest rectangle enclosing rhs and the current value of *this. Contrast this with the quite different behavior toward zero-area rectangles used by the friend function described below. Consider the following example: PMRect justOrigin(); //left == top == right == bottom == 0 PMRect justSegment(1,-1,3,-1); //just a line segment from (1,-1) to (3,-1) PMRect someArea(1,1,2,2); //a square someArea.Union(justSegment); someArea.Union(justOrigin); Here someArea would not have changed from its constructed value. Contrast that with the example for the friend function.

Parameters

rhs	IN The rectangle with which this one is unioned

PMReal PMRect::Width ( ) const

inlinenoexcept

Returns the width of the rectangle.

NOTE: This assumes the rect is normalized.

Returns

The width of the rectangle

Friends And Related Function Documentation

bool16 Intersect ( const PMRect &  r1, const PMRect &  r2  )

friend

Determines if two rectangles intersect. True if rectangles intersect in both x and y directions, but false if only a side is shared (ie., rectangles must strictly intersect).

Parameters

r1	IN The first rectangle to test
r2	IN The second rectangle to test

Returns

kTrue if the two rectangles strictly intersect, else kFalse

PMRect Intersection ( const PMRect &  r1, const PMRect &  r2, const PMRect &  emptyRect  )

friend

Calculates the intersection of two rectangles. If the rectangles do not strictly intersect, the specified empty rectangle is returned.

Parameters

r1	IN The first rectangle to intersect
r2	IN The second rectangle to intersect
emptyRect	IN Used as return value if rectangles do not intersect

Returns

The intersection of the two rectangles, or an empty rectangle

PMRect IntersectionOrAbut ( const PMRect &  r1, const PMRect &  r2, const PMRect &  emptyRect  )

friend

Calculates the intersection of two rectangles. The rectangles do not need to strictly intersect, but may abut. If the two rectangles do not intersect or abut, the specified empty rectangle is returned.

Parameters

r1	IN The first rectangle to intersect
r2	IN The second rectangle to intersect
emptyRect	IN Used as return value if rectangles do not intersect or abut

Returns

The intersection of the two rectangles, or an empty rectangle

bool16 IntersectOrAbut ( const PMRect &  r1, const PMRect &  r2  )

friend

Determines if two rectangles intersect or abut. True if rectangles intersect in both x and y directions or if they share a side.

Parameters

r1	IN The first rectangle to test
r2	IN The second rectangle to test

Returns

kTrue if the two rectangles intersect or abut, else kFalse

bool16 operator!= ( const PMRect &  a, const PMRect &  b  )

friend

Compares two rectangles for inequality.

Note: This implicitly uses an epsilon comparison.

Parameters

a	IN The first rectangle to compare
b	IN The second rectangle to compare

Returns

kTrue if any of the components of the two rectangles do not match, else kFalse

bool16 operator== ( const PMRect &  a, const PMRect &  b  )

friend

Compares two rectangles for equality. All four components must match.

Note: This implicitly uses an epsilon comparison.

Parameters

a	IN The first rectangle to compare
b	IN The second rectangle to compare

Returns

kTrue if the components of the two rectangles match, else kFalse

Int32Rect ToInt32Rect_ ( const PMRect &  r )

friend

Converts a PMRect to a Int32Rect rectangle

Parameters

r	IN The PMRect to convert

Returns

The equivalent Int32Rect rectangle

dvacore::geom::RectT<float> ToRectF32_ ( const PMRect &  r )

friend

Converts a PMRect to a drover rectangle

Parameters

r	IN The PMRect to convert

Returns

The equivalent drover rectangle

SysRect ToSys ( const PMRect &  r )

friend

Converts a PMRect to a system rectangle

Parameters

r	IN The PMRect to convert

Returns

The equivalent system rectangle

PMRect Union ( const PMRect &  r1, const PMRect &  r2  )

friend

Union two rectangles together, returning the resulting rectangle. Note this friend function differs from the member Union(rhs) declared above in the behavior of rectangles with zero-area (those for which IsEmpty() returns true). In partcular, r1 and r2 are never considered empty–even if they enclose zero-area. So be careful. Consider the following example: PMRect justOrigin(); //left == top == right == bottom == 0 PMRect justSegment(1,-1,3,-1); //just a line segment from (1,-1) to (3,-1) PMRect someArea(1,1,2,2); //a square PMRect result = Union( Union(someArea, justSegment), justOrigin); Here result would be left == 0, top == -1, right == 3, bottom == 2. Contrast that with the example for the member function.

Parameters

r1	IN The first rectangle to union
r2	IN The second rectangle to union

Returns

The union of the two rectangles