Globals: Camera Info

Camera Info

Availability LightWave® 6.0
Component Layout
Header lwrender.h

The camera info global returns functions for getting camera-specific information about any of the cameras in a scene. Use the item info global to get the camera list and for generic item information. The information returned by these functions is read-only, but you can set camera parameters using commands.

Beginning with LightWave® 9, certain portions of a camera's render settings can be re-directed to use settings from a "global" camera. This global camera contains settings for resolution, motion blur, and mask values that can be shared by one or more cameras in the scene. For those settings marked as being controlled by the global camera, the camera info functions will retrieve the global values. Note: in LW9.0 (version 4 of the camera info global), the global value was only returned if the setting was marked as being global, and the camera was the current render camera.

From LightWave® 9 there is a new plugin class to implement arbitrary camera types. Cameras are no longer limited to pinhole perspective. To allow plugins to evaluate the camera projection there is a camera evaluator global. Camera evaluators can be used independently from each other. Each evaluator keeps its own render mode, time, and pass state. When evaluating the camera, the camera state is changed to match the state of the evaluator. Beware that if there are multiple evaluators with different states, there is some time cost in switching between them.

Global Call

   LWCameraInfo *caminfo;
   caminfo = global( LWCAMERAINFO_GLOBAL, GFUSE_TRANSIENT );

The global function returns a pointer to an LWCameraInfo.

   typedef struct st_LWCameraInfo {
      double       (*zoomFactor)           (LWItemID, LWTime);
      double       (*focalLength)          (LWItemID, LWTime);
      double       (*focalDistance)        (LWItemID, LWTime);
      double       (*fStop)                (LWItemID, LWTime);
      double       (*blurLength)           (LWItemID, LWTime);
      void         (*fovAngles)            (LWItemID, LWTime, double *hfov, double *vfov);
      unsigned int (*flags)                (LWItemID);
      void         (*resolution)           (LWItemID, int *w, int *h);
      double       (*pixelAspect)          (LWItemID, LWTime);
      double       (*separation)           (LWItemID, LWTime);
      void         (*regionLimits)         (LWItemID, int *x0, int *y0, int *x1,int *y1);
      void         (*maskLimits)           (LWItemID, int *x0, int *y0, int *x1,int *y1);
      void         (*maskColor)            (LWItemID, LWDVector color);
      unsigned int (*motionBlur)           (LWItemID);
      unsigned int (*fieldRendering)       (LWItemID);
      int          (*irisPos)              (LWItemID, LWTime, int pass, float *irisx, float *irisy);
      int          (*usingGlobalResolution)(LWItemID);
      int          (*usingGlobalBlur)      (LWItemID);
      int          (*usingGlobalMask)      (LWItemID);
      unsigned int (*motionBlurPasses)     (LWItemID, LWTime);
      double       (*shutterEfficiency)    (LWItemID, LWTime);
      unsigned int (*noiseSampler)         (LWItemID);
      void         (*filmSize)             (LWItemID, double *width, double *height);
      unsigned int (*frameTiming)          (LWItemID, LWFrame, LWFrameTimingInfo *timingInfo);
      unsigned int (*antiAliasing)         (LWItemID, LWTime);
      double       (*overSampling)         (LWItemID, LWTime);
      void         (*diaphragm)            (LWItemID, LWTime, int *sides, double *rotation);
   } LWCameraInfo;

zoom = zoomFactor( camera, time )

Returns the zoom factor.

flen = focalLength( camera, time )

Returns the focal length in millimeters.

fdist = focalDistance( camera, time )

Returns the distance from the camera at which objects are in focus.

fstop = fStop( camera, time )

Returns the f-stop number.

blurlen = blurLength( camera, time )

Returns the blur length as a fraction of the frame time.

Note: This setting is controlled by a "Use Global" flag (see usingGlobalBlur). If the camera's "Use Global" flag is enabled for this setting, then the value returned by this function comes instead from the scene's Global Camera.

fovAngles( camera, time, hfov, vfov )

Gets the hfov and vfov (horizontal and vertical field of view) angles, expressed in radians.

f = flags( camera );

Returns flags describing the camera, combined using bitwise-or.

LWCAMF_STEREO: This indicates that the camera has stereo rendering enabled.
LWCAMF_LIMITED_REGION: This indicates that the camera has limited region rendering set.
LWCAMF_MASK: This indicates that masked rendering is enabled for the camera.
LWCAMF_DOF: This indicates that the camera has enabled depth of field.
LWCAMF_PARTICLE_BLUR: This indicates that the camera has enabled particle blurring, which is the simulated trajectory of one-point polygons over time
LWCAMF_LR_NOBORDERS: This indicates that limited region is being used without borders when limited region is enabled
LWCAMF_FIELD: When field rendering is enabled, this indicates which field (0 or 1) is being processed
LWCAMF_USECAMTYPE: Indicates that the camera uses a camera type plugin, instead of the built-in classic type (rev.4+)
LWCAMF_SUPPORTS_DOF: Set when the camera supports Depth of Field rendering. Check LWCAMF_DOF to determine if DOF is enabled or not (rev.5+)
LWCAMF_EYE: When stereo rendering is enabled, this indicates which eye (0 or 1) is being processed (rev.5+)

Note: The LWCAMF_PARTICLE_BLUR and LWCAMF_FIELD flags are controlled by a "Use Global" flag (see usingGlobalResolution and usingGlobalBlur). If the camera's "Use Global" flag is enabled for these settings, then the values for these flags come instead from the scene's Global Camera.

resolution( camera, width, height )

Gets the image size in pixels for the images rendered by the camera.

Note: This setting is controlled by a "Use Global" flag (see usingGlobalResolution). If the camera's "Use Global" flag is enabled for this setting, then the value returned by this function comes instead from the scene's Global Camera.

aspect = pixelAspect( camera, time )

Returns the pixel aspect ratio of images rendered by the camera, expressed as width/height. Values greater than 1.0 mean short wide pixels and values less than 1.0 mean tall thin pixels.

sep = separation( camera, time )

Returns the interocular distance (eye separation) for stereoscopic rendering, in meters.

regionLimits( camera, x0, y0, x1, y1 )

Gets the limited region rectangle for the camera.

maskLimits( camera, x0, y0, x1, y1 )

Gets the mask rectangle for the camera.

Note: This setting is controlled by a "Use Global" flag (see usingGlobalMask). If the camera's "Use Global" flag is enabled for this setting, then the value returned by this function comes instead from the scene's Global Camera.

maskColor( camera, color )

Gets the color that will be rendered in areas of the image outside the mask rectangle.

blur = motionBlur( camera ) (rev.3+)

This retrieves motion blur setting for a camera item. See the LWCAMMB_ defines for possible return values. This value is only valid when a multi-pass anti-aliasing approach is used.

LWCAMMB_OFF
LWCAMMB_NORMAL
LWCAMMB_DITHERED

ff = fieldRendering( camera ) (rev.3+)

Returns the field-rendering state for the specified camera. See the LWCAMFIELDR_ defines for possible return values.

LWCAMFIELDR_OFF
LWCAMFIELDR_EVENFIRST
LWCAMFIELDR_ODDFIRST

havepos = irisPos( camera, time, pass, irisx, irisy ) (rev. 4+)

Get the iris position for the camera at a given time and pass number. The iris position is typically used for depth of field. It represents a sample point on the camera's aperture. The position is normalized, ranging from -1 to 1 over the height of the aperture. The pass number ranges from 0 to sceneinfo->maxSamplesPerPixel-1. Returns 1 if there is a sample point, or 0 otherwise.

using = usingGlobalResolution( camera ) (rev. 4+)

Reports the state of the Camera's "Use Global" redirection flag for resolution settings. A value of 1 means the switch is enabled, and the global resolution settings are used by this camera. A value of 0 means it is off, and the camera's local resolution settings are active.

using = usingGlobalBlur( camera ) (rev. 4+)

Reports the state of the Camera's "Use Global" redirection flag for motion blur settings. A value of 1 means the switch is enabled, and the global motion blur settings are used by this camera. A value of 0 means it is off, and the camera's local motion blur settings are active.

using = usingGlobalMask( camera ) (rev. 4+)

Reports the state of the Camera's "Use Global" redirection flag for mask boundary settings. A value of 1 means the switch is enabled, and the global mask boundary settings are used by this camera. A value of 0 means it is off, and the camera's local mask boundary settings are active. Note: mask boundaries are only regarded if "Use Mask" has been enabled.

passes = motionBlurPasses( camera, time ) (rev.5+)

This retrieves the motion blur passes setting for a camera item.

efficiency = shutterEfficiency( camera, time ) (rev.5+)

Gets the shutter efficiency for a camera item. The efficiency is returned as a fraction, usually between 0.5 and 1.0.

sampler = noiseSampler( camera ) (rev.5+)

Returns the noise sampler setting for the camera.

filmSize( camera, width, height ) (rev.5+)

Gets the width and height of the film frame in metres.

havetiming = frameTiming( camera, frame, frametiming ) (rev.5+)

Fills in the frame timing structure pointed to by the frametiming arguments, for the given camera and frame. The frame timing structure defines the times and durations of the various passes and fields in the frame.

   typedef struct st_LWComponentTimingInfo {
       unsigned int count;
       double offset;
       double duration;
       double stride;
   } LWComponentTimingInfo;

   typedef struct st_LWFrameTimingInfo {
       LWComponentTimingInfo frame;
       LWComponentTimingInfo fields;
       LWComponentTimingInfo steps;
       LWComponentTimingInfo scanlines;
       LWComponentTimingInfo pixels;
   } LWFrameTimingInfo;

A frame is divided into fields, each of which is divided into steps (for motion blur), with each step divided into scanlines, and finally scanlines are split into pixels. The frame timing structure defines the time ranges at which the instances of these component are evaluated.

count: The number of instances of this component within the parent component instance. For example, the number of steps in a field, or the number of pixels in a scanline. For the frame component this will be 1.
offset: The offset of the starting time of the first instance of the component, relative to the starting time of the parent component instance. The value in in seconds. For example, the starting time of the first field in a frame, or the first pixel in a scanline. For the frame, the offset is the actual time of the start of the frame.
duration: The duration of each component instance in seconds. The duration is the length of time over which the instance is sampled. This can be zero, meaning that the component will only be sampled at the starting time. The duration may also exceed the stride (see below).
stride: The step size in seconds from the start of one instance to the start of the next instance. For example, the jump between the start time of the first field and the start of the second field in a frame (if there is more than one field in the frame).

For example, the starting time of the second field in a frame with multiple fields is given by:

  frame.offset + fields.offset + fields.stride

The last time value at which the 16th scanline of the 3rd step of the last field of the frame may be evaluation:

  frame.offset +                                                  // Frame start
    fields.offset + (fields.count - 1) * fields.stride +          // Last field start
    steps.offset + 2 * steps.stride +                             // 3rd step start
    scanlines.offset + 15 * scanlines.stride + scanlines.duration // 16th scanline end

Note that this function uses a frame number as an argument, not time. Returns 1 if the structure was successfully filled in, or 0 otherwise.

aa = antiAliasing( camera, time ) (rev.5+)

Return the antialiasing level for the camera.

os = overSampling( camera, time ) (rev.5+)

Returns the oversampling value for the camera.

diaphragm( camera, time, sides, rotation ) (rev.5+)

Gets the number of sides and rotation of the diaphragm for the camera. If the number of sides is zero, the diaphragm is circular. The rotation is in radians.

Global Call

   LWCameraEvaluationFuncs *camevalfuncs;
   camevalfuncs = global( LWCAMERAEVALUATIONFUNCS_GLOBAL, GFUSE_TRANSIENT );

The global function returns a pointer to an LWCameraEvaluationFuncs. Note that version 1 of this global is no longer supported.

   typedef struct st_LWCameraEvaluationFuncs {
      LWCameraEvaluatorID (*create) (LWItemID camera);
      void    (*destroy)  (LWCameraEvaluatorID);
      LWError (*init)     (LWCameraEvaluatorID, int mode);
      void    (*cleanUp)  (LWCameraEvaluatorID);
      LWError (*newTime)  (LWCameraEvaluatorID, LWFrame frame, LWTime time);
      int     (*preview)  (LWCameraEvaluatorID, double lpx, double lpy, LWDMatrix4 projection);
      LWError (*newFrame) (LWCameraEvaluatorID);
      int     (*evaluate) (LWCameraEvaluatorID, double fpx, double fpy, double lpx, double lpy,
                           double fractime, LWCameraRay* camray);
   } LWCameraEvaluationFuncs;

cameval = create( camera ): Create a new camera evaluator for the given camera.
destroy( cameval ): Destroy a camera evaluator. All created camera evaluators must be destroyed.
error = init( cameval, mode ): Set the mode for the camera evaluator. The mode is either LWINIT_PREVIEW or LWINIT_RENDER.
cleanup( cameval ): Indicate the end of a rendering session.
error = newTime( cameval, frame, time ): Set the frame and time for a camera evaluator.
havepreview = preview( cameval, lpx, lpy, projection ): Obtain the preview projection matrix.
error = newFrame( cameval ): Start evaluating a frame. This must be called at the start of the frame evaluation before using evaluate()
dotrace = evaluate( cameval, fpx, fpy, lpx, lpy, fractime, ray ): Evaluate the camera, filling in the ray structure.

Example

This code fragment collects information about the first camera.

   #include <lwserver.h>
   #include <lwrender.h>

   LWItemInfo *iteminfo;
   LWCameraInfo *caminfo;
   LWItemID id;
   LWTime t = 3.0;          /* seconds */
   double zoom, flen, fdist, fstop, blen, hfov, vfov;

   iteminfo = global( LWITEMINFO_GLOBAL, GFUSE_TRANSIENT );
   caminfo  = global( LWCAMERAINFO_GLOBAL, GFUSE_TRANSIENT );

   if ( iteminfo && caminfo ) {
      id = iteminfo->first( LWI_CAMERA, NULL );
      zoom  = caminfo->zoomFactor( id, t );
      flen  = caminfo->focalLength( id, t );
      fdist = caminfo->focalDistance( id, t );
      fstop = caminfo->fStop( id, t );
      blen  = caminfo->blurLength( id, t );
      fovAngles( id, t, &hfov, &vfov );
   }