Class: TGBox3D

Declaration: Geometry3D.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

None.

Inherited By:

None.

Purpose:

TGBox3D is an axis-aligned rectangular prism: Each side of the box is parallel to the x-, y-, or z-axis. TGBox3D is analogous to TGRect, the 2-D class representing a rectangle. Like TGRect, TGBox3D is usable either as a general-purpose bounding box or as an object to be rendered by the drawing port. The box is defined by six coordinates: a minimum x, y, and z, and a maximum x, y, and z. The box's minimum point is (Xmin, Ymin, Zmin), and its maximum point is (Xmax, Ymax, Zmax). As long as the six coordinates defining the box are set appropriately, the minimum point lies at the lower-left, backmost corner of the box, and the maximum point lies at the top-right, frontmost corner. If, however, Xmax <= Xmin, Ymax <= Ymin, or Ymax <= Ymin, the TGBox3D is considered to be empty. Empty TGBox3DÕs do not fill, and are ignored by TGBox3D::ExtendTo and TGBox3D::Intersection. You can sort a box's coordinates by invoking TGBox3D::OrderPoints. Doing so ensures that the box is not degenerate (for example, Xmax will not be less than Xmin); but the box might still be empty (for example, Xmax might equal Xmin). To find out if a box is empty, call TGBox3D::IsEmpty--do not test for equality with kZeroBox3D, because kZeroBox3D is just a specific case out of an infinite number of empty boxes. (kZeroBox3D is an infinitesimal box at the origin.)

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

None. Do not create derived classes.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TGBox3D::TGBox3D

TGBox3D ()
TGBox3D (const TGPoint3D & minPt, const TGPoint3D & maxPt)
TGBox3D (const TGBox3D & box3D)

Interface Category:

API.

Purpose:

Default constructor.
Creates a box whose coordinates are determined by the parameters.
Copy constructor.

Calling Context:

Called by the stream-in operators. You can also call this constructor directly.
Call this directly to create a fully specified box.
Called to copy an object.

Parameters:

Takes no parameters.
const TGPoint3D & minPt -A point defined to be the lower-left, backmost corner of the new box.
const TGPoint3D & maxPt -A point defined to be the upper-right, frontmost corner of the new box.
const TGBox3D & box3D -The box to be copied.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

No testing is done to ensure that minPt's coordinates are greater than those of maxPt. If they are not, the box is considered empty.

Member Function: TGBox3D::~TGBox3D

~ TGBox3D ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Called to destroy an object.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGBox3D::Contains

bool Contains (const TGPoint3D & p) const
bool Contains (const TGBox3D & g) const

Interface Category:

API.

Purpose:

Specifies whether the box encloses the specified point. To be contained, the point can lie on one of the three faces that meet at the box's minimum point, but it cannot lie on a face that meets the maximum point.
Specifies whether the box encloses the specified box. The contained box's minimum point can lie on any of the outer box's three faces that meet at the outer box's minimum point. However, if the inner box's maximum point touches any of the outer box's other three faces, it is not considered contained.

Calling Context:

Call this function directly.
Call this function directly.

Parameters:

const TGPoint3D & p -The point tested for containment in the box.
const TGBox3D & g -The point tested for containment in the box.

Return Value:

Returns true if the passed-in box is contained in this box.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGBox3D::EqualSize

bool EqualSize (const TGBox3D & g) const

Interface Category:

API.

Purpose:

Tests whether two boxes have the same size. This member function does not compare volumes; instead, it compares the two boxes' heights, widths, and depths to see if they all match. In other words, not only must the volumes of the two boxes be identical, but also their shapes and orientations. (Their locations are irrelevant.)

Calling Context:

Call this function directly.

Parameters:

const TGBox3D & g -The box to be compared to this box.

Return Value:

Returns true if the two boxes are equal in size.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGBox3D::ExtendTo

void ExtendTo (const TGPoint3D & p)
void ExtendTo (const TGBox3D & b)

Interface Category:

API.

Purpose:

If the specified point is not within the box, the box is expanded until the specified point lies on a face of the box. The box does not expand outward in all directions, only in the necessary direction(s); thus, if it is expanded, its center changes.
If the specified box is not within this box, this box is expanded until all faces of the specified box are contained within, or lie upon a face of, this box. This box does not expand outward in all directions, only in the necessary direction(s); thus, if it is expanded, its center changes.

Calling Context:

Call this function directly.
Call this function directly.

Parameters:

const TGPoint3D & p -The point to which the box should extend.
const TGBox3D & b -The box that this box should include.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The test is less strict than the test for TGBox3D::Contains. A point or face that lies upon any face of the outer box is considered to be contained for purposes of ExtendTo, whereas Contains does not allow this case for faces of the outer box that meet at fMaxPt.

Member Function: TGBox3D::GetCenter

TGPoint3D GetCenter () const

Interface Category:

API.

Purpose:

Retrieves the center point of the box.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns a TGPoint3D located at the box's center.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGBox3D::GetSize

TGPoint3D GetSize () const

Interface Category:

API.

Purpose:

Returns a point specifying the three dimensions of the box. Think of this point as the maximum point of a box that has the same height, width, and depth as this box, but whose minimum point is at the origin.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns a point whose x-coordinate specifies the box's width, whose y-coordinate specifies the box's height, and whose z-coordinate specifies the box's depth.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGBox3D::GetMinPoint

TGPoint3D GetMinPoint () const

Interface Category:

API.

Purpose:

Returns the point defined to be the lower-left, backmost corner. In the normal case, this point's coordinates are all less than the corresponding coordinates of the maximum point. However, any point can be defined as the minimum point, regardless of the maximum point's position. Thus, the minimum point might not actually be at the lower-left, backmost corner, in which case the box is considered empty.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the point that is defined as the minimum point.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGBox3D::GetMaxPoint

TGPoint3D GetMaxPoint () const

Interface Category:

API.

Purpose:

Returns the point defined to be the upper-right, front corner. In the normal case, this point's coordinates are all greater than the corresponding coordinates of the minimum point. However, any point can be defined as the maximum point, regardless of the minimum point's position. Thus, the maximum point might not actually be at the upper-right, front corner, in which case the box is considered empty.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the point that is defined as the maximum point.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGBox3D::Inset

void Inset (const TGPoint3D & point)

Interface Category:

API.

Purpose:

Moves opposite sides of the box inwards towards its center or outwards from its center. The amount to move each side is specified by the parameter's x-, y-, and z-coordinates.

Calling Context:

Call this function directly.

Parameters:

const TGPoint3D & point -A point whose three coordinates specify the amount to move each pair of opposite sides. For example, the x-coordinate specifies how much to move the right face towards the left, as well as how much to move the left face towards the right. Thus, the box's total shrinkage in width is twice the value of the parameter's x-coordinate. Positive values move the sides inwards, creating an inset. Negative values move the sides outwards. All values are permissible, even ones which cause opposite faces to swap sides (possibly making the box become empty).

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGBox3D::IntersectWith

void IntersectWith (const TGBox3D & box)

Interface Category:

API.

Purpose:

Finds the intersection of this box with the parameter and replaces this box with the intersection. If the two boxes do not intersect, this box is set to an infinitesimal box at the origin.

Calling Context:

Call this function directly.

Parameters:

const TGBox3D & box -The box to intersect with this box.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGBox3D::IsEmpty

bool IsEmpty () const

Interface Category:

API.

Purpose:

Determines whether the box encloses any space. A box encloses space if its minimum and maximum points are defined so that all of the minimum point's coordinates are less than the corresponding coordinates of the maximum point. In this case, the minimum point is at the lower-left, backmost corner, and the maximum point is at the upper-right, frontmost corner.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if the box is empty, meaning that at least one of the minimum point's coordinates is greater than or equal to the corresponding coordinate of the maximum point.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGBox3D::Offset

void Offset (const TGPoint3D & point)

Interface Category:

API.

Purpose:

Moves this box by the specified vector.

Calling Context:

Call this function directly.

Parameters:

const TGPoint3D & point -The vector to add to this box's points.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGBox3D::OrderPoints

void OrderPoints ()

Interface Category:

API.

Purpose:

Sorts the box's coordinates. For each of the three dimensions, the minimum point's coordinate is swapped with that of the maximum point if the minimum point's coordinate is greater. This makes the box non-empty, unless any pair of coordinates are equal.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGBox3D::Pin

void Pin (TGPoint3D & point) const

Interface Category:

API.

Purpose:

Moves the given point, if it is outside the box, to the nearest face of the box. For each dimension, the point's coordinate is compared to the minimum and maximum point's coordinates. If one coordinate is out of this range, the point is moved perpendicularly to the nearest face. If two coordinates are out of range, it is moved perpendicularly to the nearest edge, and if all three are out of range, it is moved to the nearest corner.

Calling Context:

Call this function directly.

Parameters:

TGPoint3D & point -The point to be pinned to the box.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGBox3D::SetCenter

void SetCenter (const TGPoint3D & center)

Interface Category:

API.

Purpose:

Moves the box so that it is centered at the given point.

Calling Context:

Call this function directly.

Parameters:

const TGPoint3D & center -The new center of the box.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGBox3D::SetSize

void SetSize (const TGPoint3D & size)

Interface Category:

API.

Purpose:

Resizes the box, keeping its center at the same location. Each dimension of the box is set to the corresponding value of the TGPoint3D parameter; thus, the shape of the box can change.

Calling Context:

Call this function directly.

Parameters:

const TGPoint3D & size -A vector whose x-, y-, and z-coordinates specify the new x-, y-, and z-dimensions of the box.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGBox3D::SetMinPoint

void SetMinPoint (const TGPoint3D & size)

Interface Category:

API.

Purpose:

Sets the minimum point, which is ostensibly the lower-left, backmost corner. However, the ordering of this point with respect to the maximum point is not enforced. If its three coordinates are not less than those of the maximum point, the box is considered empty.

Calling Context:

Call this function directly.

Parameters:

const TGPoint3D & size-The new minimum point.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGBox3D::SetMaxPoint

void SetMaxPoint (const TGPoint3D & size)

Interface Category:

API.

Purpose:

Sets the maximum point, which is ostensibly the upper-right, frontmost corner. However, the ordering of this point with respect to the minimum point is not enforced. If its three coordinates are not greater than those of the minimum point, the box is considered empty.

Calling Context:

Call this function directly.

Parameters:

const TGPoint3D & size-The new maximum point.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGBox3D::operator<<=

TStream & operator <<= (TStream & fromwhere)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in data.

Parameters:

TStream & fromwhere -The stream from which the object's data is streamed in.

Return Value:

Returns a reference to the stream the object streams itself in from.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGBox3D::operator>>=

TStream & operator >>=(TStream & towhere) const

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called to stream out data.

Parameters:

TStream & towhere -The stream to which the object's data is streamed out.

Return Value:

Returns a reference to the stream the object streams itself out to.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGBox3D::operator=

TGBox3D & operator =(const TGBox3D & Src)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TGBox3D & Src -The box whose value is copied.

Return Value:

A non-const reference to the left-hand side object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGBox3D::operator==

bool operator ==(const TGBox3D & Src) const

Interface Category:

API.

Purpose:

Tests two boxes for equality.

Calling Context:

Call this function by using the operator in an expression.

Parameters:

const TGBox3D & Src -The box to be compared to this box.

Return Value:

Returns true if the minimum and maximum points of one box are equal to the corresponding points of the other box.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGBox3D::operator!=

bool operator != (const TGBox3D & Src) const

Interface Category:

API.

Purpose:

Tests two boxes for inequality.

Calling Context:

Call this function by using the operator in an expression.

Parameters:

const TGBox3D & Src -The box to be compared to this box.

Return Value:

Returns true if the minimum or maximum point of one box does not match that of the other box.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Click the icon to mail questions or corrections about this material to Taligent personnel.