This CC3Node displays a 2D cocos2D CCNode at the projectedPosition of this node. More...
#import <CC3Billboard.h>
Public Member Functions | |
| (BOOL) | - doesIntersectViewport: |
| (void) | - faceCamera: |
| (id) | - initWithTag:withName:withBillboard: |
| (void) | - visit2dWithViewport: |
Properties | |
| CCNode * | billboard |
| CGPoint | maximumBillboardScale |
| CGPoint | minimumBillboardScale |
| CGPoint | offsetPosition |
| GLfloat | unityScaleDistance |
Detailed Description
Since the cocos2D node is displayed in 2D, it always appears to face the camera, and it is never occluded by any 3D objects.
CC3Billboards are useful for drawing a label, health-bar, or some other 2D artifact on or near the projected position of a 3D object, and have that 2D artifact apparently move along with the 3D object as it moves through the 3D world.
CC3Billboard is a type of CC3Node, and can therefore participate in a structural node assembly. An instance can be the child of another node, and the billboard itself can have child nodes.
The size of the 2D node can be automatically scaled based on the distance between the 3D billboard node and the 3D camera. Doing so will keep the 2D artifact at the same proportional size to the 3D object, as the 3D object moves toward or away from the camera.
This dyanamic scaling of the 2D artifact is the default behaviour. To fix the 2D artifact to a single static scale, set both the minimumBillboardScale and minimumBillboardScale properties to the same non-zero value.
Generally, CC3Billboards return NO for the hasLocalContent property, and are not drawn along with other nodes that do have local content. Instead, CC3Billboards are drawn by the CC3World after all 3D drawing has been completed. To do this, the CC3World invokes the visit2dWithViewport: method on each CC3Billboard instance.
A CC3Billboard can, and should, have a bounding volume, but the bounding volume must be an instance of a subclass of CC3NodeBoundingArea, because the boundary is tested against the viewport instead of the camera frustum. The default bounding volume is an instance of CC3BillboardBoundingBoxArea, which tests for overlap between the viewport and the boundingBox of the enclosed 2D CCNode instance.
Member Function Documentation
| - (BOOL) doesIntersectViewport: | (CC3Viewport) | aViewport |
Returns whether the local content of this node intersects the given viewport.
This check does not include checking children, only the local content.
This method is called during the drawing operations of each frame to determine whether this node should be culled from the visible nodes and not drawn. A return value of YES will cause the node to be drawn, a return value of NO will cause the node to be culled and not drawn.
Culling nodes that are not visible to the camera is an important performance enhancement. The node should strive to be as accurate as possible in returning whether it intersects the viewport. Incorrectly returning YES will cause wasted processing within the GL engine. Incorrectly returning NO will cause a node that should at least be partially visible to not be drawn.
In this implementation, if this node has a boundingVolume, this method delegates to it. Otherwise, it simply returns YES. Subclasses may override to change this standard behaviour.
The boundingVolume of a CC3Billboard must be an instance of a subclass of CC3NodeBoundingArea.
| - (void) faceCamera: | (CC3Camera *) | camera |
Uses the specified camera to project the 3D location of this node into 2D, sets the position of the 2D artifact in the billboard property to that position, and if dynamic scaling is being used, calculates and sets the scale of the 2D billboard artifact appropriately, based on the distance this node is from the specified camera.
This method is invoked automatically by CC3World during model updating. Usually, the application never needs to invoke this method directly.
| - (id) initWithBillboard: | (CCNode *) | a2DNode |
Initializes this unnamed instance with an automatically generated unique tag value, and the specified 2D node to be drawn.
| - (id) initWithName: | (NSString *) | aName | |
| withBillboard: | (CCNode *) | a2DNode | |
Initializes this instance with an automatically generated unique tag value, and the specified name and 2D node to be drawn.
| - (id) initWithTag: | (GLuint) | aTag | |
| withName: | (NSString *) | aName | |
| withBillboard: | (CCNode *) | a2DNode | |
Initializes this instance with the specified tag, name and 2D node to be drawn.
| + (id) nodeWithBillboard: | (CCNode *) | a2DNode |
Allocates and initializes an autoreleased unnamed instance with an automatically generated unique tag value, and the specified 2D node to be drawn.
| + (id) nodeWithName: | (NSString *) | aName | |
| withBillboard: | (CCNode *) | a2DNode | |
Allocates and initializes an autoreleased instance with an automatically generated unique tag value, and the specified name and 2D node to be drawn.
| - (void) visit2dWithViewport: | (CC3Viewport) | aViewport |
Draws the 2D artifact at the 2D position calculated in the faceCamera: method.
This method is invoked automatically by CC3World at the end of each frame drawing cycle. Usually, the application never needs to invoke this method directly.
Property Documentation
- (CCNode *) billboard [read, write, retain] |
The 2D artifact that this node will display.
This can be any CCNode subclass.
- (CGPoint) maximumBillboardScale [read, write, assign] |
The maximum scale that will be applied to the 2D artifact.
Setting this property to a non-zero value will stop the 2D artifact from growing too large as the 3D object approaches very close to the camera. For example, you may want to keep a name label at a readable size, even if the character it labels comes right up to the camera.
If this property is zero, no maximum will be applied. If this property is non-zero and is equal to the minimumBillboardScale, the 2D artifact will always be displayed at that single scale, regardless of how near or far the 3D object is from the camera.
- (CGPoint) minimumBillboardScale [read, write, assign] |
The minimum scale that will be applied to the 2D artifact.
Setting this property to a non-zero value will stop the 2D artifact from shrinking away to nothing as the 3D object recedes far from the camera. For example, you may want to keep a name label readable, even if the character it labels is far from the camera.
If this property is zero, no minimum will be applied. If this property is non-zero and is equal to the maximumBillboardScale, the 2D artifact will always be displayed at that single scale, regardless of how near or far the 3D object is from the camera.
- (CGPoint) offsetPosition [read, write, assign] |
An offset, measured in 2D display points, at which the 2D billboard should be positioned relative to the 2D projectedPosition of this node.
The initial value is {0, 0}. This property can be useful in helping to center or positionally justify the 2D artifact.
- (GLfloat) unityScaleDistance [read, write, assign] |
The distance from the camera, in 3D space, at which the 2D artifact will be displayed at unity scale (its natural size).
If this node is closer to the camera than this distance, the 2D artifact will be scaled up proportionally. If this node is farther from the camera than this distance, the 2D artifact will be scaled down proportionally.
If the value of this property is zero, the camera's near clip plane distance will be used as the unity scale distance, and therefore the 2D artifact will only ever appear smaller than its natural size. The initial value of this property is zero.
The documentation for this class was generated from the following file:
