Index of OpenRM - RM Library


 RMcamera2D * rmCamera2DNew (void)

 No arguments.

A default 2D camera is created and a handle to the requested RMcamera2D is returned. If the 2D camera cannot be created, then a NULL pointer is returned. at jogoscasinoonline.eu.

 librm library source file: rmcamera.c 

 RMenum rmCamera2DCopy (RMcamera2D *dst,
	                const RMcamera2D *src)

 RMcamera2D *dst - a handle to an RMcamera2D object to be modified
    (output). const RMcamera2D *src - a handle to an RMcamera2D object that will be
    copied (input).

Copies all parameters and attributes from one RMcamera2D object to another. Returns RM_CHILL upon success, or RM_WHACKED upon failure. Bonus Fara Depunere

 librm library source file: rmcamera.c 

 void rmCamera2DDelete (RMcamera2D *toDelete)

 RMcamera2D *toDelete - a handle to  RMcamera2D object to delete (modified).

Free the RMcamera2D resources pointed to by c. It is assumed that c points to a valid RMcamera2D previously created with rmCamera2DNew().

 librm library source file: rmcamera.c 

 RMenum rmDefaultCamera2D (RMcamera2D *toModify)

 RMcamera2D *toModify - a handle to a caller supplied RMcamera2D
    object that will be modified by this routine (modified).

This routine assigns a set of default parameters to an RMcamera2D object. All existing settings of the input RMcamera2D object will be overwritten. Returns RM_CHILL upon success, or RM_WHACKED upon failure.

The new values written by this routine are:

1. 2D extents set to: (-1,-1)..(1,1)

2. Aspect ratio set to 1.0.

 librm library source file: rmcamera.c 

 RMenum rmCamera2DSetAspectRatio (RMcamera2D *toModify,
			          float newAspect)

 RMcamera2D *toModify - a handle to the RMcamera2D object that will be
    modified by this routine. float newAspect - a floating point value specifying the new aspect
    ratio for the RMcamera2D object.

Use this routine to set the aspect ratio of a 2D camera. Returns RM_CHILL upon success, or RM_WHACKED upon failure.

The aspect ratio is a fraction that is the width of the field of view divided by the height. It is used to control the stretch and squish of rendering. For example, consider rendering into a window whose width is 400 pixels and height is 300 pixels and using a logically square viewport (0,0..1,1). If the camera aspect ratio is set to 1.0, the resulting image will appear to be stretched along the horizontal axis because the square viewport is being mapped to a rectangular window.

In this example, we would want to set the aspect ratio to 400/300 to avoid stretching. The aspect ratio is applied at the stage when we compute the view transformation matrix.

 librm library source file: rmcamera.c 

 RMenum rmCamera2DResetAspectRatio (RMcamera2D *toModify,
			            const float *vp,
			            int windowWidth,
				    int windowWeight)

 RMcamera2D *toModify - a handle to the RMcamera2D that will be
    modified by this routine. const float *vp - an array of floating point values of length 4. This
    is a viewport specification, ordered {xmin, ymin, xmax, ymax}. The
    viewport coordinates are in the range 0..1, ranging from the lower
    left corner of the display window (0,0) to the upper right corner
    (1,1). int windowWidth, windowWeight - integer values specifying the size in
    pixels of the display window. These values are used in computing a
    new aspect ratio for the RMcamera2D object.

Given viewport and window geometry, compute an aspect ratio that will cause pixels to "remain square." In other words, an aspect ratio will be computed so that there is no stretch or squish in the rendered image: a square in world coordinates will remain square in the rendered image, regardless of viewport or window geometry.

Returns RM_CHILL upon success, or RM_WHACKED upon failure.

 librm library source file: rmcamera.c 

 RMenum rmCamera2DGetAspectRatio (const RMcamera2D *toQuery,
			          float *retValue)

 const RMcamera2D *toQuery - a handle to the RMcamera2D object that
    will be queried by this routine. float *retValue - a handle to a caller-supplied float. The
    RMcamera2D's aspect ratio attribute will be copied into this
    memory location.

Use this routine to query the aspect ratio of an RMcamera2D object. RM_CHILL is returned upon success, otherwise RM_WHACKED is returned.

The aspect ratio is a fraction that is the width of the field of view divided by the height. It is used to control the stretch and squish of rendering. For example, consider rendering into a window whose width is 400 pixels and height is 300 pixels and using a logically square viewport (0,0..1,1). If the camera aspect ratio is set to 1.0, the resulting image will appear to be stretched along the horizontal axis because the square viewport is being mapped to a rectangular window.

In this example, we would want to set the aspect ratio to 400/300 to avoid stretching. The aspect ratio is applied at the stage when we compute the view transformation matrix.

 librm library source file: rmcamera.c 

 RMenum rmCamera2DSetExtents (RMcamera2D *toModify,
		              float xmin,
			      float ymin,
			      float xmax,
			      float ymax)

 RMcamera2D *toModify - a handle to an RMcamera2D object that will be
    modified by this routine. float xmin, ymin, xmax, ymax - floating point values that specify the
    new x/y extents "seen" by the 2D camera. These values are
    specified in world coordinates.

Use this routine to specify the extents for a 2D camera. Returns RM_CHILL upon success, or RM_WHACKED upon failure.

A 2D camera is composed of two parameters in OpenRM: an extents and an aspect ratio. The extents defines a 2D region in world coordinates that will be seen by the 2D camera, these extents are specified with a minimum and maximum coordinate. The aspect ratio defines the relationship between the camera width and height and controls the stretch and squish of rendering, something that is useful if your window is not square.

 librm library source file: rmcamera.c 

 RMenum rmCamera2DGetExtents (const RMcamera2D *toQuery,
		              float *xmin,
			      float *ymin,
			      float *xmax,
			      float *ymax)

 const RMcamera2D *toQuery - a handle to an RMcamera2D object that
    will be queried by this routine. float *xmin, *ymin, *xmax, *ymax - pointers to caller-supplied
    floats. The 2D cameras extents parameters will be written into
    these memory locations.  It is permissible to specify NULL for any
    or all of these parameters - the corresponding 2D camera extents
    parameter will not be reported for NULL return parameters.

Use this routine to query the extents of a 2D camera. Returns RM_CHILL upon success, or RM_WHACKED upon failure.

A 2D camera is composed of two parameters in OpenRM: an extents and an aspect ratio. The extents defines a 2D region in world coordinates that will be seen by the 2D camera, these extents are specified with a minimum and maximum coordinate. The aspect ratio defines the relationship between the camera width and height and controls the stretch and squish of rendering, something that is useful if your window is not square.

 librm library source file: rmcamera.c 

 RMenum rmCamera2DComputeViewMatrix (const RMcamera2D *camera,
			             RMmatrix *matrixReturn)

 const RMcamera2D *camera - a handle to an RMcamera2D object (input). RMmatrix *matrixReturn - a handle to a caller-supplied RMmatrix
    object (result).

Computes the view matrix defined by the 2D input camera, copying the result into caller supplied memory. Upon success, RM_CHILL is returned. Upon failure, RM_WHACKED is returned, and matrixReturn remains undisturbed.

Note that the 2D camera does not produce a projection matrix, unlike the 3D camera.

 librm library source file: rmcamera.c 

 RMenum rmCamera2DComputeViewFromGeometry (RMcamera2D *toModify,
				           const RMnode *source)

 RMcamera2D *toModify - a handle to an RMcamera2D object that will be
    modified by this routine. const RMnode *source - a handle to an RMnode.

Use this routine to automatically compute 2D view parameters from the 2D bounding box of scene graph node. Returns RM_CHILL upon success, or RM_WHACKED upon failure.

The 2D camera's parameters will be set to reflect the min/max extents of the input RMnode's 2D bounding box. The aspect ratio of the 2D camera remains unmodified.

 librm library source file: rmcamera.c 

 RMcamera3D * rmCamera3DNew (void)

 No arguments.

This routine creates a new RMcamera3D object, initializes it to some default values, and returns a handle to the caller. If there is an error (malloc failure), an error message is displayed with rmError and NULL is returned.

For initialization, rmDefaultCamera3D is applied to the newly created RMcamera3D object so that all fields are initialized. See the description of rmDefaultCamera3D for particulars about the default values.

 librm library source file: rmcamera.c 

 RMenum rmCamera3DCopy (RMcamera3D *dst,
	                const RMcamera3D *src)

 RMcamera3D *dst - a handle to an RMcamera3D object to be modified
    (output). const RMcamera3D *src - a handle to an RMcamera3D object that will be
    copied (input).

Copies all parameters and attributes from one RMcamera3D object to another. Returns RM_CHILL upon success, or RM_WHACKED upon failure.

 librm library source file: rmcamera.c 

 void rmCamera3DDelete (RMcamera3D *toDelete)

 RMcamera3D *toDelete - a handle to RMcamera3D object to delete (modified).

Free the RMcamera3D resources pointed to by c. It is assumed that c points to a valid RMcamera3D previously created with rmCamera3DNew().

 librm library source file: rmcamera.c 

 RMenum rmDefaultCamera3D (RMcamera3D *toModify)

 RMcamera3D *toModify - a handle to an RMcamera3D object that will be
    modified by this routine.

Assigns some default parameters to an RMcamera3D object. Returns RM_CHILL upon success, or RM_WHACKED upon failure.

The parameters set by this routine are:

1. Eye point set to (10,10,50). (rmCamera3DSetEye)

2. Lookat point is the origin, (0,0,0). (rmCamera3DSetAt)

3. Up vector is (0,1,0) (rmCamera3DSetUp)

4. Field of view set to 45 degrees (rmCamera3DSetFOV)

5. Monoscopic camera (rmCamera3DSetStereo)

6. Perspective projection (rmCamera3DSetProjection)

7. Front and back clipping planes set to 2.0 and 40.0, respectively. (rmCamera3DSetHither, rmCamera3DSetYon)

Returns RM_CHILL upon success, or RM_WHACKED if the input RMcamera3D object is NULL.

 librm library source file: rmcamera.c 

 RMenum rmCamera3DSetAspectRatio (RMcamera3D *toModify,
		                  const float newAspect)

 RMcamera3D *toModify - a handle to an RMcamera3D object (modified). const float newAspect - a floating point value used to specify the
    new aspect ratio for the RMcamera3D object.

Use this routine to modify the aspect ratio attribute of an RMcamera3D object. Returns RM_CHILL upon success, or RM_WHACKED upon failure.

 librm library source file: rmcamera.c 

 RMenum rmCamera3DResetAspectRatio (RMcamera3D *toModify,
			            const float *vp,
				    int windowWidth,
				    int windowHeight)

 RMcamera3D *toModify - a handle to the RMcamera3D object that will be
    modified by this routine. const float *vp - an array of floating point values of length 4. This
    is a viewport specification, ordered {xmin, ymin, xmax, ymax}. The
    viewport coordinates are in the range 0..1, ranging from the lower
    left corner of the display window (0,0) to the upper right corner
    (1,1). int windowWidth, windowWeight - integer values specifying the size in
    pixels of the display window. These values are used in computing a
    new aspect ratio for the RMcamera3D object.

Given viewport and window geometry, compute an aspect ratio that will cause pixels to "remain square." In other words, an aspect ratio will be computed so that there is no stretch or squish in the rendered image: a square in world coordinates will remain square in the rendered image, regardless of viewport or window geometry.

All other camera parameters are ignored and remain unaffected.

Returns RM_CHILL upon success, or RM_WHACKED upon failure.

 librm library source file: rmcamera.c 

 float rmCamera3DGetAspectRatio (const RMcamera3D *toQuery)

 const RMcamera3D *toQuery - a handle to the RMcamera3D object that
    will be queried by this routine.

Use this routine to query the aspect ratio of an RMcamera3D object. RM_CHILL is returned upon success, otherwise RM_WHACKED is returned.

The aspect ratio is a fraction that is the width of the field of view divided by the height. It is used to control the stretch and squish of rendering. For example, consider rendering into a window whose width is 400 pixels and height is 300 pixels and using a logically square viewport (0,0..1,1). If the camera aspect ratio is set to 1.0, the resulting image will appear to be stretched along the horizontal axis because the square viewport is being mapped to a rectangular window.

In this example, we would want to set the aspect ratio to 400/300 to avoid stretching. The aspect ratio is applied at the stage when we compute the view transformation matrix.

 librm library source file: rmcamera.c 

 RMenum rmCamera3DSetProjection (RMcamera3D *toModify,
                                 RMenum newVal)

 RMcamera3D *toModify - a handle to an RMcamera3D object that will be
    modified by this routine (modified). RMenum newVal - an RMenum value specifying the new projection method
    for the RMcamera3D object. Should be either
    RM_PROJECTION_PERSPECTIVE or RM_PROJECTION_ORTHOGRAPHIC.

Use this routine to assign a projection method to a 3D camera. Returns RM_CHILL upon success, or RM_WHACKED upon failure.

Perspective projections are used to achieve a "perspective foreshortening" effect. This is how humans see in the real world: objects that are further away appear smaller than similarly-sized objects that are closer. In contrast, in orthographics projections size does not diminish as a function of distance to the viewer. This type of projection is often used in CAD systems because it does not distort angles.

 librm library source file: rmcamera.c 

 RMenum rmCamera3DGetProjection (const RMcamera3D *toQuery)

 const RMcamera3D *toQuery - a handle to an RMcamera3D object that
    will be queried by this routine (input).

Use this routine to obtain the projection method attribute of the RMcamera3D object. If successful, either RM_PROJECTION_PERSPECTIVE or RM_PROJECTION_ORTHOGRAPHIC will be returned to the caller. Otherwise, upon failure, RM_WHACKED will be returned.

 librm library source file: rmcamera.c 

 RMenum rmCamera3DSetEye (RMcamera3D *toModify,
		          const RMvertex3D *newEye)

 RMcamera3D *toModify - a handle to the RMcamera3D object that will be
    modified by this routine. const RMvertex3D *newEye - a handle to an RMvertex3D object.

Use this routine to specify a new eye point for a 3D camera. The eye point is the location of the viewer, and is specified in world coordinates. The new eye point is copied from the caller-supplied RMvertex3D object into the RMcamera3D object.

Returns RM_CHILL upon success, or RM_WHACKED upon failure.

 librm library source file: rmcamera.c 

 RMenum rmCamera3DGetEye (const RMcamera3D *toQuery,
		          RMvertex3D *returnEye)

 const RMcamera3D *toQuery - a handle to an RMcamera3D object to be
    queried (input). RMvertex3D *returnEye - a handle to a caller-supplied RMvertex3D
    object (modified).

Use this routine to obtain the 3D eye position of an RMcamera3D object.

Returns RM_CHILL upon success, or RM_WHACKED upon failure.

 librm library source file: rmcamera.c 

 RMenum rmCamera3DSetAt (RMcamera3D *toModify,
		         const RMvertex3D *newAt)

 RMcamera3D *toModify - a handle to an RMcamera3D object (modified). const RMvertex3D *newAt - a handle to an RMvertex3D object containing
    the new look-at point (input).

Use this routine to set the look-at point of a 3D camera. The contents of the caller-supplied newAt RMvertex3D object is copied into the RMcamera3D object's look-at point attribute.

Returns RM_CHILL upon success, or RM_WHACKED upon failure.

 librm library source file: rmcamera.c 

 RMenum rmCamera3DGetAt (const RMcamera3D *toQuery,
		         RMvertex3D *returnAt)

 const RMcamera3D *toQuery - a handle to an RMcamera3D object to be
    queried (input). RMvertex3D *returnAt - a handle to an RMvertex3D object that will
    contain the RMcamera3D's look-at point upon return (modified).

Use this routine to obtain the look-at point of a 3D camera. The RMcamera3D's look-at point is copied into the caller-supplied object.

Returns RM_CHILL upon success, or RM_WHACKED upon failure.

 librm library source file: rmcamera.c 

 RMenum rmCamera3DSetUpVector (RMcamera3D *toModify,
		               const RMvertex3D *newUpVector)

 RMcamera3D *toModify - a handle to the RMcamera3D object to be
    modified (result). const RMvertex3D *newUpVector - a handle to an RMvertex3D object
    supplying the new up vector (input).

Use this routine to set the Up vector attribute of an RMcamera3D object. The contents of the caller-supplied newUpVector is copied to the RMcamera3D object's up vector attribute.

Returns RM_CHILL upon success, or RM_WHACKED upon failure.

 librm library source file: rmcamera.c 

 RMenum rmCamera3DGetUpVector (const RMcamera3D *toQuery,
		               RMvertex3D *returnUpVector)

 const RMcamera3D *toQuery - a handle to the RMcamera3D object to
    query (input). RMvertex3D *returnUpVector - a handle to an RMvertex3D object
    supplied by the caller (modified).

Use this routine to query the Up vector attribute of an RMcamera3D object. The RMcamera3D object's up vector is copied into the caller-supplied memory.

Returns RM_CHILL upon success, or RM_WHACKED upon failure.

 librm library source file: rmcamera.c 

 RMenum rmCamera3DSetFOV (RMcamera3D *toModify,
                          float newFOV)

 RMcamera3D *toModify - a handle to an RMcamera3D object that will be
    modified by this routine (modified). float newFOV - a floating point value, the new FOV parameter (input).

Use this routine to set the FOV parameter at a 3D camera object. If successful, RM_CHILL is returned, otherwise, RM_WHACKED is returned.

FOV in OpenRM refers to the horizontal field of view, not the vertical field of view. Increasing the FOV in a 3D camera will cause more of the scene to be visible along the horizontal axis.

 librm library source file: rmcamera.c 

 float rmCamera3DGetFOV (const RMcamera3D *toQuery)

 const RMcamera3D *toQuery - a handle to an RMcamera3D object that
    will be queried (input).

Use this routine to obtain the FOV parameter from a 3D camera object. A floating point value is returned to the caller.

FOV in OpenRM refers to the horizontal field of view, not the vertical field of view. Increasing the FOV in a 3D camera will cause more of the scene to be visible along the horizontal axis.

 librm library source file: rmcamera.c 

 RMenum rmCamera3DSetHither (RMcamera3D *toModify,
                            float newHither)

 RMcamera3D *toModify - a handle to the RMcamera3D object (modified). float newHither - a floating point value containing the new front
    clip plane value (input).

Used to set the value of the front clip plane attribute of the RMcamera3D object. The front clip plane value is a distance, in world coordinates, from the eye point to the front clip plane. Returns RM_CHILL upon success, or RM_WHACKED upon failure.

 librm library source file: rmcamera.c 

 float rmCamera3DGetHither (const RMcamera3D *toQuery)

 const RMcamera3D *toQuery - a handle to the RMcamera3D object to be
    queried (input).

Returns to the caller the value of the front clip plane attribute of the RMcamera3D object. The front clip plane value is a distance, in world coordinates, from the eye point to the front clip plane.

 librm library source file: rmcamera.c 

 RMenum rmCamera3DSetYon (RMcamera3D *toModify,
                          float newYon)

 RMcamera3D *toModify - a handle to the RMcamera3D object (modified). float newYon - a floating point value containing the new back clip
    plane value (input).

Used to set the value of the back clip plane attribute of the RMcamera3D object. The back clip plane value is a distance, in world coordinates, from the eye point to the back clip plane. Returns RM_CHILL upon success, or RM_WHACKED upon failure.

 librm library source file: rmcamera.c 

 float rmCamera3DGetYon(const RMcamera3D *toQuery)

 const RMcamera3D *toQuery - a handle to the RMcamera3D object to be
    queried (input).

Returns to the caller the value of the clip plane attribute of the RMcamera3D object. The back clip plane value is a distance, in world coordinates, from the eye point to the back clip plane.

 librm library source file: rmcamera.c 

 RMenum rmCamera3DSetStereo (RMcamera3D *toModify,
		             RMenum newBoolValue)

 RMcamera3D *toModify - a handle to an RMcamera3D object (modified). RMenum newBoolValue - a boolean value, either RM_TRUE or RM_FALSE
    (input).

Use this routine to set the stereo attribute of a 3D camera. Returns RM_CHILL upon success or RM_WHACKED upon failure.

A stereo 3D camera in OpenRM defines a binocular viewing geometry. The binocular viewing geometry is a function of eye separation (rmCamera3DSetEyeSeparation) and focal length (rmCamera3DSetFocalDistance).

When the 3D camera is set to be a stereo camera with this routine, the confluence of multipass rendering control and stereo 3D camera parameters are used to internally compute left- and right-eye views used for rendering. If the 3D camera's "is stereo" attribute is set to RM_FALSE, a monocular view will be used during a stereo multipass rendering.

 librm library source file: rmcamera.c 

 RMenum rmCamera3DGetStereo (const RMcamera3D *toQuery)

 const RMcamera3D *toQuery - a handle to an RMcamera3D object that
    will be queried by this routine (input).

Use this routine to obtain the stereo attribute of a 3D camera. Returns RM_WHACKED upon failure, otherwise returns RM_TRUE or RM_FALSE.

A stereo 3D camera in OpenRM defines a binocular viewing geometry. The binocular viewing geometry is a function of eye separation (rmCamera3DSetEyeSeparation) and focal length (rmCamera3DSetFocalDistance).

When the 3D camera is set to be a stereo camera with this routine, the confluence of multipass rendering control and stereo 3D camera parameters are used to internally compute left- and right-eye views used for rendering. If the 3D camera's "is stereo" attribute is set to RM_FALSE, a monocular view will be used during a stereo multipass rendering.

 librm library source file: rmcamera.c 

 RMenum rmCamera3DSetEyeSeparation (RMcamera3D *toModify, float newVal)

 RMcamera3D *toModify - a handle to an RMcamera3D object (modified). float newVal - a floating point value specifying the interocular
    displacement in degrees (input).

Use this routine to modify the interocular separation parameter of a stereo 3D camera. Returns RM_WHACKED upon failure, otherwise returns RM_CHILL.

A stereo 3D camera in OpenRM defines a binocular viewing geometry. The binocular viewing geometry is a function of eye separation (rmCamera3DSetEyeSeparation) and focal length (rmCamera3DSetFocalDistance).

The stereo camera's binocular geometry, specifically the interocular distance, is computed using the 3D camera's eye point, the look-at point, the focal length and the interocular distance. The "real" look at point of a 3D stereo camera is computed as the product of the focal length with the (unitized) eye/look-at vector. The left and right eyes both look at the "real" stereo look-at point (not the one specified by rmCamera3DSetAt). The apex of the triangle formed by the left and right eyes and the "real" stereo look at point will have an angular measure of X degrees, where X is specified as the parameter to the routine rmCamera3DSetEyeSeparation. We have found that values in the range 2.5-3.5 degrees work well for most viewers.

 librm library source file: rmcamera.c 

 RMenum rmCamera3DGetEyeSeparation (RMcamera3D *toQuery)

 const RMcamera3D *toQuery - a handle to an RMcamera3D object that
    will be queried by this routine (input).

Use this routine to query the interocular separation parameter of a stereo 3D camera. Returns a floating point value representing the 3D stereo camera's interocular distance parameter.

A stereo 3D camera in OpenRM defines a binocular viewing geometry. The binocular viewing geometry is a function of eye separation (rmCamera3DSetEyeSeparation) and focal length (rmCamera3DSetFocalDistance).

The stereo camera's binocular geometry, specifically the interocular distance, is computed using the 3D camera's eye point, the look-at point, the focal length and the interocular distance. The "real" look at point of a 3D stereo camera is computed as the product of the focal length with the (unitized) eye/look-at vector. The left and right eyes both look at the "real" stereo look-at point (not the one specified by rmCamera3DSetAt). The apex of the triangle formed by the left and right eyes and the "real" stereo look at point will have an angular measure of X degrees, where X is specified as the parameter to the routine rmCamera3DSetEyeSeparation. We have found that values in the range 2.5-3.5 degrees work well for most viewers.

 librm library source file: rmcamera.c 

 RMenum rmCamera3DSetFocalDistance (RMcamera3D *toModify, float newVal)

 RMcamera3D *toModify - a handle to an RMcamera3D object (modified). float newVal - a floating point value specifying new focal distance
    length (input).

Use this routine to modify the focal distance parameter of a stereo 3D camera. Returns RM_WHACKED upon failure, otherwise returns RM_CHILL.

A stereo 3D camera in OpenRM defines a binocular viewing geometry. The binocular viewing geometry is a function of eye separation (rmCamera3DSetEyeSeparation) and focal length (rmCamera3DSetFocalDistance).

In a binocular view model, the left and right eyes look at a point somewhere in space. This point is computed from the 3D stereo camera parameters: eye point (rmCamera3DSetEye), the look-at point (rmCamera3DSetAt) and the focal distance (rmCamera3DSetFocalDistance). The point is computed as the eye point plus the focal distance times the eye-at vector.

A value of 1.0 for the focal distance places the stereo look-at point at the look-at point specified by rmCamera3DSetAt. A value of, say, 0.707, places the stereo look at point in front of the 3D camera's look-at point, and a value of, say, 1.414, places the stereo look-at point somewhere behind the 3D camera's look at point.

Manipulation of the focal distance and the interocular separation parameters can have a profound effect upon the perceived stereo view.

 librm library source file: rmcamera.c 

 RMenum rmCamera3DGetFocalDistance (const RMcamera3D *toQuery)

 const RMcamera3D *toQuery - a handle to an RMcamera3D object that
    will be queried by this routine (input).

Use this routine to query the focal distance parameter of a stereo 3D camera. A floating point value is returned by this routine.

A stereo 3D camera in OpenRM defines a binocular viewing geometry. The binocular viewing geometry is a function of eye separation (rmCamera3DSetEyeSeparation) and focal length (rmCamera3DSetFocalDistance).

In a binocular view model, the left and right eyes look at a point somewhere in space. This point is computed from the 3D stereo camera parameters: eye point (rmCamera3DSetEye), the look-at point (rmCamera3DSetAt) and the focal distance (rmCamera3DSetFocalDistance). The point is computed as the eye point plus the focal distance times the eye-at vector.

A value of 1.0 for the focal distance places the stereo look-at point at the look-at point specified by rmCamera3DSetAt. A value of, say, 0.707, places the stereo look at point in front of the 3D camera's look-at point, and a value of, say, 1.414, places the stereo look-at point somewhere behind the 3D camera's look at point.

Manipulation of the focal distance and the interocular separation parameters can have a profound effect upon the perceived stereo view.

 librm library source file: rmcamera.c 

 RMenum rmCamera3DComputeViewMatrix (const RMcamera3D *source,
			             RMmatrix *viewReturn,
				     RMmatrix *projectionReturn)

 const RMcamera3D *source - a handle to an RMcamera3D object (input). RMmatrix *viewReturn - a handle to an RMmatrix object (result). RMmatrix *projectionReturn - a handle to an RMmatrix object (result).

Computes a view and projection matrix from an RMcamera3D object, returning the computed matrices in the "viewReturn" and "projectionReturn" parameters, respectively. RM_CHILL is returned upon success, or RM_WHACKED upon failure. Failure can occur if either of the input parameters is NULL, or if there is some type of fatal numerical error caused by bogus 3D camera parameters. These latter problems are detected and reported via rmError().

The view matrix represents the affine transformation that transforms from world coordinates into "eye coordinates," assuming a monocular view. The same matrix is returned regardless of whether or not the input camera is a stereo or mono camera.

The projection matrix represents the transformation from eye space coordinates to NDC coordinates. If the camera uses perspective projection, that transformation will be present in the projectionReturn matrix.

 librm library source file: rmcamera.c 

 RMenum rmCamera3DComputeViewFromGeometry (RMcamera3D *toModify,
			                   const RMnode *source,
					   int windowWidth, 
					   int windowHeight)

 RMcamera3D *toModify - a handle to the RMcamera3D object (modified). const RMnode *source - a handle to an RMnode. the bounding box of
    this RMnode will be used in computing 3D camera parameters
    (input). int windowWidth, windowHeight - int values specifying the width and
    height in pixels of the display window. These values are used in
    computing an aspect ratio for the camera (input).

This routine computes and assigns 3D camera parameters such that a volume defined by the bounding box attribute of the input RMnode will be visible, regardless of box orientation. If present, the scale matrix transformation attribute of the RMnode will be used to enlarge or shrink the bounding box parameter of the RMnode for the purposes of computing new camera parameters.

The 3D camera must be a valid RMcamera3D object allocated by the caller. This routine merely computes new values for an existing camera using the bounding box of an RMnode. It neither creates nor destroys an RMcamera3D.

The 3D camera's FOV parameter is used as part of the computation, and will not be overwritten by this routine. All stereo parameters, if any, are ignored and remain unmodified by this routine.

The new 3D camera parameters are computed thus:

1. The 3D camera's look-at point will be the center of the RMnode's bounding box.

2. The 3D camera's new eye position is the same as the new look-at point, but offset along the Z axis a distance D. The distance D is computed as boxsize/tan(FOV/2) where boxsize is the distance from the bounding box's min vertex to the box's max vertex. The basic idea is to move the eye point away from the look-at point a distance which is sufficient for the entire box to be visible, given the requested FOV.

3. The near and far clip planes are set to a distance F which is computed as D-boxsize*1.4 and D+boxsize*1.4, respectively, where D is the same D computed in (2). Again, the point is to have the entire bounding box within the view frustum regardless of orientation.

Note: 8/16/02 - changed computation of near/far to D-boxsize*2.0, D+boxsize*5.0, respectively. This gives more room to maneuver before the object gets clipped.

4. The aspect ratio for the 3D camera is set using the input values windowWidth and WindowHeight.

 librm library source file: rmcamera.c