Main Page   Modules   Alphabetical List   Data Structures   Data Fields  

RwCamera
[Scene Management]


Functions

RpWorld * RwCameraGetWorld (const RwCamera *camera)
RwCamera * RwCameraForAllSectorsInFrustum (RwCamera *camera, RpWorldSectorCallBack callback, void *data)
RwCamera * RwCameraForAllClumpsInFrustum (RwCamera *camera, void *data)
RwCamera * RwCameraForAllAtomicsInFrustum (RwCamera *camera, RpAtomicCallBack callback, void *data)

Detailed Description

Cameras

RwCamera Overview

Requirements

Overview

The World plugin directly extends the Core Library's Camera API (RwCamera). Additional functionality provided when RpWorld is attached is as follows:

(These functions retain the "RwCamera[METHOD]()" naming convention.)

Further information is available in the Camera chapter of the User Guide.

Function Documentation

RwCamera* RwCameraForAllAtomicsInFrustum (  RwCamera *    camera,
RpAtomicCallBack    callback,
void *    data
) 
 

RwCameraForAllAtomicsInFrustum is used to determine which atomics lie wholly or partially within the specified camera's view frustum and then to execute the specified callback function on each atomic found. The enumeration may be terminated at any time by returning NULL from the atomic callback.

Note:
The view frustum is only defined by the last render, so this function must be called after a scene has been rendered.
The results of calling function can be thought of as equivalent to the following scheme:-

  1. RwCameraForAllSectorsInFrustum to iterate through the current set of frustum sectors
  2. RpWorldSectorForAllAtomics to iterate over all atomics in a sector.
  3. RwCameraFrustumTestSphere to finally check whether the atomic is definitely inside the camera frustum.
  4. Execute the callback function.
The world plugin must be attached before using this function.
Parameters:
camera  Pointer to the camera.
callback  Callback to be called with each atomic.
data  User data pointer to pass to each atomic callback.
Returns:
Returns pointer to the specified camera if successful or NULL if there is an error.
See also:
RwCameraForAllSectorsInFrustum , RpAtomicCallBack , RpWorldPluginAttach

RwCamera* RwCameraForAllClumpsInFrustum (  RwCamera *    camera,
void *    data
) 
 

RwCameraForAllClumpsInFrustum is used to determine which clumps lie wholly or partially within the specified camera's view frustum and then to execute each of those clump's callback function (see RpClumpSetCallBack). The enumeration may be terminated at any time by returning NULL from the clump callback.

Note:
The view frustum is only defined by the last render, so this function must be called after a scene has been rendered.
The results of calling function can be thought of as equivalent to the following scheme:-

  1. RwCameraForAllSectorsInFrustum to iterate through the current set of frustum sectors
  2. RpWorldSectorForAllAtomics to iterate over all atomics in a sector.
  3. RpAtomicGetClump to get the RpClump that contains a particular atomic. At this stage, a quick check can be made that the clump hasn't already been counted.
  4. RwCameraFrustumTestSphere to finally check whether the clump's atomic is definitely inside the camera frustum.
  5. Execute the clump's callback function.
Variations on this scheme may be used for other situations, such as operating just on the atomics contained in the frustum.

The world plugin must be attached before using this function.

Parameters:
camera  Pointer to the camera.
data  User data pointer to pass to each clump callback
Returns:
Returns pointer to the specified camera if successful or NULL if there is an error.
See also:
RwCameraForAllSectorsInFrustum , RpClumpSetCallBack , RpClumpGetCallBack , RpWorldPluginAttach

RwCamera* RwCameraForAllSectorsInFrustum (  RwCamera *    camera,
RpWorldSectorCallBack    callback,
void *    data
) 
 

RwCameraForAllSectorsInFrustum is used to apply the given callback function to all world sectors that lie inside the specified camera's view frustum. World sectors that are only partially inside the camera's frustum will also get a callback. The format of the callback function is: 

   RpWorldSector *(*RpWorldSectorCallBack)(RpWorldSector *sector, void *data);
where data is a user-supplied data pointer to pass to the callback function.

Note:
If any invocation of the callback function returns a failure status the iteration is terminated. However, RwCameraForAllSectorsInFrustum will still return successfully.
Note:
The view frustum is only defined by the last render, so it is recommended that this function is called after the scene has been rendered.
This function is a world plugin extension and the world plugin must be attached before using this function.
Parameters:
camera  Pointer to the camera whose frustum to enumerate world sectors within.
callback  Callback function to call with each world sector.
data  User data pointer to pass to the callback function.
Returns:
Returns pointer to the camera if successful or NULL if there is an error.
See also:
RwCameraForAllClumpsInFrustum , RpWorldSectorForAllAtomics , RpWorldSectorForAllLights

RpWorld* RwCameraGetWorld (  const RwCamera *    camera ) 
 

RwCameraGetWorld is used to determine the world the specified camera belongs to, if any.

This function is a world plugin extension and the world plugin must be attached before using this function.

Parameters:
camera  Pointer to the camera.
Returns:
Returns pointer to the world which contains the camera if successful or NULL if there is an error or if the camera does not belong to any world.
See also:
RpWorldAddCamera , RpWorldRemoveCamera , RwCameraCreate , RpWorldPluginAttach

Criterion Software © 1993-2004 Criterion Software Limited. All rights reserved. Built Thu Feb 12 13:46:55 2004. Send Feedback