CC3Camera represents the camera viewing the 3D world. More...
#import <CC3Camera.h>
Public Member Functions | |
| (void) | - buildPerspective |
| (void) | - close |
| (void) | - open |
| (CC3Vector) | - projectLocation: |
| (CGPoint) | - projectNode: |
| (CGPoint) | - projectToVisiblePoint: |
| (void) | - updateDeviceOrientation: |
Properties | |
| GLfloat | deviceRotation |
| CC3GLMatrix * | deviceRotationMatrix |
| GLfloat | farClippingPlane |
| GLfloat | fieldOfView |
| CC3Frustum * | frustum |
| CC3GLMatrix * | modelviewMatrix |
| GLfloat | nearClippingPlane |
| CC3GLMatrix * | projectionMatrix |
| CC3Projector * | projector |
| CC3Viewport | viewport |
Detailed Description
CC3Camera 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 camera itself can have child nodes. For example, a camera can be mounted on a boom object or truck, and will move along with the parent node. Or the camera node itself might have a light node attached as a child, so that the light will move along with the camera, and point where the camera points.
CC3Camera is also a type of CC3TargettingNode, and can be pointed in a particular direction, or can be made to track a target node as that node moves, or the camera moves.
CC3Camera is also responsible for managing the viewport and handling changes to the view as the physical orientation of the iOS device changes.
Member Function Documentation
| - (void) buildPerspective |
Updates the transformMatrix and modelviewMatrix if the target has moved, builds the projectionMatrix if needed, and updates the frustum if needed.
This method is invoked automatically from the CC3World after all updates have been made to the models in the 3D world. Usually, the application never needs to invoke this method directly.
| - (void) close |
Closes the camera for drawing operations.
This method is called automatically by the CC3World at the end of each frame drawing cycle. Usually, the application never needs to invoke this method directly.
| - (void) open |
Opens the camera for drawing operations.
This method is called automatically by the CC3World at the beginning of each frame drawing cycle. Usually, the application never needs to invoke this method directly.
Projects the specified 3D world location onto a 2D position in the viewport coordinate space, indicating where on the screen this 3D location will be seen.
The 2D position can be read from the X and Y components of the returned 3D location. This method takes into account the orientation of the device (portrait, landscape).
Any 3D world location can be either in front of or behind the camera, and both cases will be projected onto the 2D space of the viewport plane. Generally, you will only be interested in locations in front of the camera (potentially visible to the camera). To accomodate that, the location returned by this method includes a Z component, which will be +1 for 3D world locations that are in front of the camera, or -1 for 3D locations that are behind the camera (invisible to the camera). In most cases, only locations that have a Z component of +1 (in front of the camera) will be of interest.
Another case to be aware of is when the 3D location is actually in front of the camera, but out of view of the camera (off to the side). In this case, the Z component of the returned location will be +1, indicating that the location is in front of the camera, but the X or Y coordinates will be outside the viewport of this camera, and the position will not be visible. In most cases, this result will be acceptable. But if you need to explicitly know whether the point will truly be visible, you should check that the Z component is positive, and that the X and Y components are within the bounds of the viewport of this camera. When doing so, keep in mind that if the point represents the position to which you want to draw a cocos2D artifact, such as a label or health bar, explicit checking of the X and Y components against the viewport of this camera might cause you not to draw an object that is actually just outside and would be partially visible if you simply drew it at the returned position.
| - (CGPoint) projectNode: | (CC3Node *) | aNode |
Projects the globalLocation of the specified node onto a 2D position in the viewport coordinate space, by invoking the projectToVisiblePoint: method of this camera, passing the node's globalLocation.
In addition to returning the projected 2D point, this method also sets that value into the projectedPosition property of the node, for future access.
| - (CGPoint) projectToVisiblePoint: | (CC3Vector) | a3DLocation |
Projects the specified 3D world location onto a 2D position in the viewport coordinate space, indicating where on the screen this 3D location will be seen.
This method takes into account the orientation of the device (portrait, landscape).
This method is similar to projectLocation: (and in fact uses projectLocation:), but it also performs the check to make sure the 3D location is in front of the camera (by checking that the Z-component returned by projectLocation: is positive). If the 3D location is anywhere behind the camera (regardless of where), both the X and Y components of the returned point will be set to -CGFLOAT_MAX. Testing for this is not usually needed, but if you need to know if the 3D location was behind the camera, you can check for this value.
Another case to be aware of is when the 3D location is actually in front of the camera, but out of view of the camera (off to the side). In this case, the X or Y coordinates will be outside the viewport of this camera, and the point will not be visible. In most cases, this result will be acceptable. But if you need to explicitly know whether the point will truly be visible, you should check that the X and Y components are within the viewport of this camera. In doing so, keep in mind that if the point represents the position to which you want to draw a cocos2D artifact, such as a label or health bar, explicit checking of the X and Y components against the viewport of this camera might cause you not to draw an object that is actually just outside and would be partially visible if you simply drew it at the returned point.
| - (void) updateDeviceOrientation: | (ccDeviceOrientation) | deviceOrientation |
Sets the deviceOrientation property on this camera with the appropriate rotation angle, which causes the deviceRotationMatrix to be rebuilt, and also invokes the same method on the contained CC3Projector instance.
This method is invoked by the CC3Layer when it detects that the device orientation has changed, and is configured to automatically adapt the view.
Property Documentation
- (GLfloat) deviceRotation [read, write, assign] |
The angle that the device is currently rotated to, in degrees.
When this property is set, the deviceRotationMatrix is rebuilt. The value of this property is set automatically by the updateDeviceOrientation: method. Typically, the application would not set this value directly.
- (CC3GLMatrix *) deviceRotationMatrix [read, write, retain] |
A rotation matrix to hold the transform required for the current device orientation.
- (GLfloat) farClippingPlane [read, write, assign] |
The distance from the camera to the clipping plane of the camera's frustrum that is farthest from the camera.
Initially set to kCC3DefaultFarClippingPlane.
- (GLfloat) fieldOfView [read, write, assign] |
The nominal field of view of this camera, in degrees.
Initially set to kCC3DefaultFieldOfView.
The effective field of view is influenced by the value of the uniformScale property, which, for cameras, acts as a zoom factor (as if the camera lens is zoomed in or out). Once a nominal field of view has been set in this property, changing the scale or uniformScale properties will change the effective field of view accordingly (although the value of the fieldOfView property remains the same). Scales greater than one zoom in (objects appear larger), and scales between one and zero zoom out (objects appear smaller).
- (CC3Frustum *) frustum [read, write, retain] |
The frustum of the camera.
- (CC3GLMatrix *) modelviewMatrix [read, write, retain] |
The matrix that holds the transform from model space to view space.
This matrix is distinct from the camera's transformMatrix, which, like that of all nodes, reflects the location, rotation and scale of the camera node in the 3D world space.
In contrast, the modelviewMatrix combines the inverse of the camera's transformMatrix (because any movement of the camera in world space has the opposite effect on the view), with the deviceRotationMatrix, to account for the impact of device orientation on the view.
- (GLfloat) nearClippingPlane [read, write, assign] |
The distance from the camera to the clipping plane of the camera's frustrum that is nearest to the camera.
Initially set to kCC3DefaultNearClippingPlane.
- (CC3GLMatrix *) projectionMatrix [read, write, retain] |
The projection matrix that takes the camera's modelview and projects it to the viewport.
- (CC3Projector *) projector [read, write, retain] |
A helper object used to project 3D locations to the 2D viewport coordinate system.
- (CC3Viewport) viewport [read, write, assign] |
The dimensions of the viewport.
The documentation for this class was generated from the following file:
