CC3Camera represents the camera viewing the 3D world. More...
#import <CC3Camera.h>
Public Member Functions | |
| (void) | - buildPerspective |
| (void) | - close |
| (void) | - markProjectionDirty |
| (void) | - open |
| (CC3Vector) | - projectLocation: |
| (CC3Vector) | - projectNode: |
| (CC3Ray) | - unprojectPoint: |
| (CC3Vector4) | - unprojectPoint:ontoPlane: |
Properties | |
| GLfloat | farClippingPlane |
| GLfloat | fieldOfView |
| CC3Frustum * | frustum |
| BOOL | isUsingParallelProjection |
| CC3GLMatrix * | modelviewMatrix |
| GLfloat | nearClippingPlane |
| CC3GLMatrix * | projectionMatrix |
| CC3World * | world |
Detailed Description
CC3Camera represents the camera viewing the 3D world.
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.
The camera can be configured for either perspective or parallel projection, using the isUsingParallelProjection property. By default, the camera will use perspective projection.
You can use the projectLocation: and projectNode: methods to project global locations within the 3D world into 2D view coordinates, indicating where on the screen a 3D object appears.
You can use the unprojectPoint: and unprojectPoint:ontoPlane: methods to project a 2D screen position into either a ray (a line) in the 3D world, or into a specific intersection location on a 3D plane.
Scaling a camera is a null operation because it scales everything, including the size of objects, but also the distance from the camera to those objects. The effects cancel out, and visually it appears that nothing has changed.
Therefore, for cameras, the scale and uniformScale properties are not applied to the transform matrix. Instead, the uniformScale property acts as a zoom factor (as if the camera lens is zoomed in or out), and influences the fieldOfView property accordingly. See the description of the fieldOfView property for more information about zooming.
If you find that objects in the periphery of your view appear elongated, you can adjust the fieldOfView and/or uniformScale properties to reduce this "fish-eye" effect. See the notes of the fieldOfView property for more on this.
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) markProjectionDirty |
Indicates that the projection matrix is dirty and needs to be recalculated.
This method is invoked automatically as needed. 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 global 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.
The specified location should be in global coordinates. If you are invoking this method to project the location of a CC3Node, you should use the globalLocation property of the node. For objects that are moving, the updated globalLocation is available in the updateAfterTransform: method of your customized CC3World.
The Z-component of the returned location indicates the distance from the camera to the specified location, with a positive value indicating that the specified location is in front of the camera, and a negative value indicating that the specified location is behind the camera.
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. If you are only interested in the case when the specified location is in front of the camera (potentially visible to the camera), check that the Z-component of the returned location is positive.
This method takes into account the orientation of the device (portrait, landscape).
Projects the globalLocation of the specified node onto a 2D position in the viewport coordinate space, by invoking the projectLocation: method of this camera, passing the node's globalLocation.
See the notes of the projectLocation: method for more info about the content of the returned vector.
During any frame update, for objects that are moving, the updated globalLocation is available in the updateAfterTransform: method of your customized CC3World.
In addition to returning the projected 2D location, this method also sets that value into the projectedLocation property of the node, for future access.
| - (CC3Ray) unprojectPoint: | (CGPoint) | cc2Point |
Projects a 2D point, which is specified in the local coordinates of the CC3Layer, into a ray extending from the camera into the 3D world.
The returned ray contains a starting location and a direction.
If this camera is using perspective projection, the ray will start at the globalLocation of this camera and extend in a direction that passes through the specified point as it is mampped to a global location on the near clipping plane.
If this camera is using parallel projection, the ray will start at the specified point as it is mampped to a global location on the near clipping plane, and will be directed straight out from the camera, in the same direction as the camera's forwardDirection.
This method is the compliment to the projectLocation: method. You can use this method to map touch events to the 3D world space for activities such as dropping objects into the 3D world at a location under user finger touch control.
Any object that lies anywhere along the ray in 3D space will appear at the specified 2D point on the view. If you are trying to place an object at a 3D location corresponding to the 2D view point (eg- a finger touch point), you need to choose a specific location on the returned ray.
For example, you might determine where that ray intersects a particular plane, and place the object there. Or you might choose a location a certain distance from the camera, and place the object there.
| - (CC3Vector4) unprojectPoint: | (CGPoint) | cc2Point | |
| ontoPlane: | (CC3Plane) | plane | |
Projects a 2D point, which is specified in the local coordinates of the CC3Layer, to a 3D location on the specified plane.
You can use this method to map touch events to the plane in the 3D world space for activities such as dropping objects onto the plane at a location under user finger touch control.
The returned result is a 4D vector, where the x, y & z components give the intersection location in 3D space, and the w component gives the distance from the camera to the intersection location. If the w component is negative, the intersection point is behind the camera, which is an indication that the camera is looking away from the plane.
If the ray from the camera through the specified point is parallel to the plane, no intersection occurs, and the returned 4D vector will be zeroed (equal to kCC3Vector4Zero).
You should therefore test the w component value to make sure it is positive and non-zero before proceeding with an activity such as dropping an object on the plane. If the plane has bounds in your world, you should also check whether the returned intersection is within those bounds.
Property Documentation
- (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.
The initial value of this property is 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).
Like real-world cameras, larger values for fieldOfView can sometimes result in a "fish-eye" effect, where objects at the periphery of the view can appear elongated. To reduce this effect, lower the value of fieldOfView property, or increase the value of the uniformScale property. In doing so, you may need to move your camera further away from the scene, so that your view will continue to include the same objects.
- (CC3Frustum *) frustum [read, write, retain] |
The frustum of the camera.
- (BOOL) isUsingParallelProjection [read, write, assign] |
Indicates whether this camera uses parallel projection.
If this value is set to NO, the projection matrix will be configured for perspective projection, which is typical for 3D worlds. If this value is set to YES, the projection matrix will be configured for parallel/isometric/orthographic projection.
The initial value of this property is NO, indicating that perspective projection will be used.
- (CC3GLMatrix *) modelviewMatrix [read, assign] |
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 from the viewportManager of the CC3World, 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, assign] |
The projection matrix that takes the camera's modelview and projects it to the viewport.
- (CC3World *) world [read, write, assign] |
The documentation for this class was generated from the following file:
