v2.0.2
Instance Methods | Class Methods | Properties | List of all members
CC3BoundingVolume Class Reference

#import <CC3BoundingVolumes.h>

Inheritance diagram for CC3BoundingVolume:
Inheritance graph
[legend]

Instance Methods

(BOOL) - doesIntersect:
 
(BOOL) - doesIntersectConvexHullOf:planes:
 
(BOOL) - doesIntersectConvexHullOf:planes:from:
 
(BOOL) - doesIntersectLocation:
 
(BOOL) - doesIntersectRay:
 
(BOOL) - doesIntersectSphere:
 
(BOOL) - doesIntersectSphere:from:
 
(NSString *) - fullDescription
 
(CC3Vector- globalLocationOfGlobalRayIntesection:
 
(BOOL) - isInFrontOfPlane:
 
(void) - markDirty
 
(void) - populateFrom:
 

Class Methods

(id) + boundingVolume
 

Properties

BOOL isDirty
 
GLuint planeCount
 
CC3Planeplanes
 
BOOL shouldIgnoreRayIntersection
 
BOOL shouldLogIntersectionMisses
 
BOOL shouldLogIntersections
 
GLuint vertexCount
 
CC3Vectorvertices
 

Detailed Description

Bounding volumes define a volume of space.

Through the doesIntersect: method, a bounding volume can indicate whether it intersects another bounding volume. This capability can be used for detecting collisions between objects, or to indicate whether an object is located in a particular volume of space, for example, the frustum of the camera.

Many different shapes of boundaries are available, including points, spheres, bounding boxes, cylinders, frustums, convex hulls, etc, permitting flexible volume definition, and tradeoffs between accuracy and computational processing time when testing intersections.

Method Documentation

+ (id) boundingVolume

Allocates and initializes an autoreleased instance.

Implemented in CC3NodeSphereThenBoxBoundingVolume.

- (BOOL) doesIntersect: (CC3BoundingVolume *)  aBoundingVolume

Returns whether this bounding volume intersects the specfied other bounding volume.

This implementation tests whether the other bounding volume intersects the convex hull of this bounding volume, by double-dispatching to the doesIntersectConvexHullOf:planes:from: method of the other bounding volume, passing this bounding volume's planes property as the planes to test, and passing this bounding volume as the otherBoundingVolume argument to that method.

Subclasses whose bounding volumes are not described in terms of a hull of vertices and planes must override this method to perform some other test. Typically, subclasses that do override will implement this method as the double-dispatch pattern, invoking one of the doesIntersect...:from: methods on the specified other bounding volume, and even potentially adding other such methods in an extension category.

Implemented in CC3NodeNullBoundingVolume, CC3NodeInfiniteBoundingVolume, CC3NodeTighteningBoundingVolumeSequence, CC3NodeSphericalBoundingVolume, and CC3NodeCenterOfGeometryBoundingVolume.

- (BOOL) doesIntersectConvexHullOf: (GLuint)  numOtherPlanes
planes: (CC3Plane *)  otherPlanes 

Returns whether a convex hull composed of the specified global planes intersects this bounding volume.

The planes may be the face planes of a mesh, or they may be the sides of an oriented bounding box (OBB), or frustum, etc.

This implementation delegates to the doesIntersectConvexHullOf:planes:from: method, passing nil as the other bounding volume.

- (BOOL) doesIntersectConvexHullOf: (GLuint)  numOtherPlanes
planes: (CC3Plane *)  otherPlanes
from: (CC3BoundingVolume *)  otherBoundingVolume 

Returns whether a convex hull composed of the specified global planes from the specified other bounding volume intersects this bounding volume.

The planes may be the face planes of a mesh, or they may be the sides of an oriented bounding box (OBB), or frustum, etc.

If all of the vertices of this bounding volume lie outside at least one of the specified planes, then this bounding volume cannot intersect the convex hull defined by those planes, and this method returns NO.

Such a test will not return any false-negative results. When an intersection really does occur, it will always return YES, and will never return NO.

However, a false-positive result is possible with this test and, depending on the relative orientations of the bounding volumes, can occasionally return YES when an intersection has not actually happened.

To compensate, this method also performs the same test from the opposite direction by invoking the doesIntersectConvexHullOf:planes: method of the specified otherBoundingVolume, passing the planes of this bounding volume.

Therefore, with the goal of reducing the occurences of false-positive results, this test is implmented by eliminating intersection failures. Each bounding volume is tested against the planes of the other, and this method returns NO as soon as one of those tests indicates intersection failure. If neither test rejects the intersection, then this method assumes that the intersection has occurred, and return YES.

False-positives are still possible, and this method can still indicate an intersection has occurred when it really hasn't. But, by combining the tests from both directions, the accuracy is improved.

Implemented in CC3NodeNullBoundingVolume, CC3NodeInfiniteBoundingVolume, CC3NodeTighteningBoundingVolumeSequence, CC3NodeSphericalBoundingVolume, and CC3NodeCenterOfGeometryBoundingVolume.

- (BOOL) doesIntersectLocation: (CC3Vector aLocation

Returns whether the specified global location intersects (is inside) this bounding volume.

Returns whether the specified location is contained within the convex hull of this bounding volume, by testing if the specified location is behind all of the planes in the planes property of this bounding volume.

Subclasses whose bounding volumes are not described in terms of a hull of vertices and planes must override this method to perform some other test.

Implemented in CC3NodeNullBoundingVolume, CC3NodeInfiniteBoundingVolume, CC3NodeTighteningBoundingVolumeSequence, CC3NodeSphericalBoundingVolume, and CC3NodeCenterOfGeometryBoundingVolume.

- (BOOL) doesIntersectRay: (CC3Ray aRay

Returns whether the specified global-coordinate ray intersects this bounding volume.

Returns whether the specified ray intersects the convex hull of this bounding volume, by testing if the intesection point of the ray and one of the planes in the planes property of this bounding volume is behind all of the remaining planes of this bounding volume.

The operation of this method is affected by the shouldIgnoreRayIntersection property. If that property is set to YES, this method will always return NO. See the notes of the shouldIgnoreRayIntersection property for more info.

Subclasses whose bounding volumes are not described in terms of a hull of vertices and planes must override this method to perform some other test.

Implemented in CC3NodeNullBoundingVolume, CC3NodeInfiniteBoundingVolume, CC3NodeTighteningBoundingVolumeSequence, CC3NodeSphericalBoundingVolume, and CC3NodeCenterOfGeometryBoundingVolume.

- (BOOL) doesIntersectSphere: (CC3Sphere aSphere

Returns whether the specified sphere intersects this bounding volume.

This implementation delegates to the doesIntersectSphere:from: method, passing nil as the other bounding volume.

- (BOOL) doesIntersectSphere: (CC3Sphere aSphere
from: (CC3BoundingVolume *)  otherBoundingVolume 

Returns whether the specified sphere intersects this bounding volume.

Returns whether the specified sphere intersects the convex hull of this bounding volume.

For the specified sphere to intesect this bounding volume, the center of the sphere must be closer to the convex hull formed by the planes of this bounding volume than the radius of the sphere.

In other words, the sphere will be outside this bounding volume if the center of the sphere lies in front of any one of the planes in the planes property of this bounding volume by more than the radius of the sphere.

This implementation ignores the otherBoundingVolume argument.

Subclasses whose bounding volumes are not described in terms of a hull of vertices and planes must override this method to perform some other test.

Implemented in CC3NodeNullBoundingVolume, CC3NodeInfiniteBoundingVolume, CC3NodeTighteningBoundingVolumeSequence, CC3NodeSphericalBoundingVolume, and CC3NodeCenterOfGeometryBoundingVolume.

- (NSString*) fullDescription

Returns a string containing a more complete description of this bounding volume, including the vertices and planes.

Subclasses whose bounding volumes are not described in terms of a hull of vertices and planes should override this method to return a more appropriate description.

- (CC3Vector) globalLocationOfGlobalRayIntesection: (CC3Ray aRay

Returns the location at which the specified ray intersects this bounding volume, or returns kCC3VectorNull if the ray does not intersect this bounding volume.

The result honours the startLocation of the ray, and will return kCC3VectorNull if this bounding volume is "behind" the startLocation, even if the line projecting back through the startLocation in the negative direction of the ray intersects this bounding volume.

The ray may start inside this bounding volume, in which case, the returned location represents the exit location of the ray.

The operation of this method is affected by the shouldIgnoreRayIntersection property. If that property is set to YES, this method will always return kCC3VectorNull. See the notes of the shouldIgnoreRayIntersection property for more info.

Both the input ray and the returned location are specified in global coordinates.

The returned result can be tested for null using the CC3VectorIsNull function.

- (BOOL) isInFrontOfPlane: (CC3Plane aPlane

Returns whether this bounding volume lies completely in front of the specified normalized global coordinate plane.

This method returns YES if the bounding volume lies completely on the side of the plane from which the plane normal points. It returns NO if this bounding volume intersects the plane or lies completely on the opposite side of the plane.

Returns whether all of the vertices of this bounding volume are on the side of the plane from which the normal points.

Subclasses whose bounding volumes are not described in terms of a hull of vertices and planes must override this method to perform some other test.

Implemented in CC3NodeNullBoundingVolume, CC3NodeInfiniteBoundingVolume, CC3NodeTighteningBoundingVolumeSequence, CC3NodeSphericalBoundingVolume, and CC3NodeCenterOfGeometryBoundingVolume.

- (void) markDirty

Marks this volume as dirty and in need of rebuilding.

The bounding volume will automatically be marked as dirty by changing any of the properties of the bounding volume. However, for subclasses that depend on content managed elsewhere, this method may be used to indicate to this bounding volume that it needs to be rebuilt.

If needed, rebuilding is lazily performed automatically when the bounding volume is tested against another bounding volume, or when a property that depends on the rebuilding is accessed.

- (void) populateFrom: (CC3BoundingVolume *)  another

Template method that populates this instance from the specified other instance.

This method is invoked automatically during object copying via the copy or copyWithZone: method. In most situations, the application should use the copy method, and should never need to invoke this method directly.

Subclasses that add additional instance state (instance variables) should extend copying by overriding this method to copy that additional state. Superclass that override this method should be sure to invoke the superclass implementation to ensure that superclass state is copied as well.

Property Documentation

- (BOOL) isDirty
readnonatomicassign

Indicates whether this volume is dirty and in need of rebuilding.

- (GLuint) planeCount
readnonatomicassign

For bounding volumes that are described in terms of a hull of vertices and planes, this property returns the number of planes in the array returned by the planes property.

Not all bounding volumes are based on vertices and planes, and this abstract implementation returns zero. Subclasses that make use of vertices and planes will allocate the underlying array and override this implementation.

- (CC3Plane*) planes
readnonatomicassign

For bounding volumes that are described in terms of a hull of vertices and planes, this property returns the array of planes that define the boundary surface of this bounding volume.

The planes are defined in the global coordinate system. The number of planes in the array is specified by the planeCount property.

Not all bounding volumes are based on vertices and planes, and this abstract implementation returns the NULL pointer. Subclasses that make use of vertices and planes will allocate the underlying array and override this implementation.

- (BOOL) shouldIgnoreRayIntersection
readwritenonatomicassign

Indicates whether this bounding volume should ignore intersections from rays.

If this property is set to YES, intersections with rays will be ignored, and the doesIntersectRay: method will always return NO.

The initial value of this property is NO, and most of the time this is sufficient.

For some uses, such as the bounding volumes of nodes that should be excluded from puncturing from touch selection rays, such as particle emitters, it might make sense to set this property to YES, so that the bounding volume is not affected by rays from touch events.

- (BOOL) shouldLogIntersectionMisses
readwritenonatomicassign

When this property is set to YES, a log message will be output whenever the doesIntersect: method returns NO (indicating that another bounding volume does not intersect this bounding volume), if the shouldLogIntersectionMisses property of the other bounding volume is also set to YES.

The shouldLogIntersectionMisses property of both bounding volumes must be set to YES for the log message to be output.

The initial value of this property is NO.

This property is useful during development to help trace intersections between bounding volumes, such as collision detection between nodes, or whether a node is within the camera's frustum.

This property is only effective when the LOGGING_ENABLED compiler build setting is defined and set to 1.

- (BOOL) shouldLogIntersections
readwritenonatomicassign

When this property is set to YES, a log message will be output whenever the doesIntersect: method returns YES (indicating that another bounding volume intersects this bounding volume), if the shouldLogIntersections property of the other bounding volume is also set to YES.

The shouldLogIntersections property of both bounding volumes must be set to YES for the log message to be output.

The initial value of this property is NO.

This property is useful during development to help trace intersections between bounding volumes, such as collision detection between nodes, or whether a node is within the camera's frustum.

This property is only effective when the LOGGING_ENABLED compiler build setting is defined and set to 1.

- (GLuint) vertexCount
readnonatomicassign

For bounding volumes that are described in terms of a hull of vertices and planes, this property returns the number of planes in the array returned by the vertices property.

Not all bounding volumes are based on vertices and planes, and this abstract implementation returns zero. Subclasses that make use of vertices and planes will allocate the underlying array and override this implementation.

- (CC3Vector*) vertices
readnonatomicassign

For bounding volumes that are described in terms of a hull of vertices and planes, this property returns the array of vertices at the points where the planes intersect.

The vertices are defined in the global coordinate system. The number of vertices in the array is defined by the vertexCount property.

The returned vertices are not in any defined order.

Not all bounding volumes are based on vertices and planes, and this abstract implementation returns the NULL pointer. Subclasses that make use of vertices and planes will allocate the underlying array and override this implementation.


The documentation for this class was generated from the following file: