QuesaCamera.h

Discussion

Functions

( TQ3Status ) Q3Camera_GetData (
    TQ3CameraObject camera,
    TQ3CameraData *cameraData
);

Discussion

Get the common state of a camera.

Parameter Descriptions

camera

The camera to query.

cameraData

Receives the common state of the camera.

function result

Success or failure of the operation.

( TQ3Status ) Q3Camera_GetPlacement (
    TQ3CameraObject camera,
    TQ3CameraPlacement *placement
);

Discussion

Get the placement of a camera.

Parameter Descriptions

camera

The camera to query.

placement

Receives the placement of the camera.

function result

Success or failure of the operation.

( TQ3Status ) Q3Camera_GetRange (
    TQ3CameraObject camera,
    TQ3CameraRange *range
);

Discussion

Get the range of a camera.

Parameter Descriptions

camera

The camera to query.

range

Receives the range of the camera.

function result

Success or failure of the operation.

( TQ3ObjectType ) Q3Camera_GetType (
    TQ3CameraObject camera
);

Discussion

Get the type of a camera.

Returns kQ3CameraTypeOrthographic, kQ3CameraTypeViewAngleAspect, or kQ3CameraTypeViewPlane. Returns kQ3ObjectTypeInvalid if the camera type is unknown.

Parameter Descriptions

camera

The camera to query.

function result

The type of the camera object.

( TQ3Status ) Q3Camera_GetViewPort (
    TQ3CameraObject camera,
    TQ3CameraViewPort *viewPort
);

Discussion

Get the view port of a camera.

Parameter Descriptions

camera

The camera to query.

viewPort

Receives the view port of the camera.

function result

Success or failure of the operation.

( TQ3Status ) Q3Camera_GetViewToFrustum (
    TQ3CameraObject camera,
    TQ3Matrix4x4 *viewToFrustum
);

Discussion

Get the view-to-frustum matrix of a camera.

The view-to-frustum matrix transforms the camera coordinate system (as returned by Q3Camera_GetWorldToView) to the viewing frustum coordinate system.

The frustum coordinate system ranges from 0.0 to -1.0 in z, and from -1.0 to +1.0 in both x and y.

Parameter Descriptions

camera

The camera to query.

viewToFrustum

Receives the view-to-frustum matrix of the camera.

function result

Success or failure of the operation.

( TQ3Status ) Q3Camera_GetWorldToFrustum (
    TQ3CameraObject camera,
    TQ3Matrix4x4 *worldToFrustum
);

Discussion

Get the world-to-frustum matrix of a camera.

The world-to-frustum matrix transforms world coordinates to the viewing frustum coordinate system. It is equivalent to multiplying the matrices returned by Q3Camera_GetWorldToView and Q3Camera_GetViewToFrustum. See the documentation of Q3View_GetWorldToFrustumMatrixState for more information.

Parameter Descriptions

camera

The camera to query.

worldToFrustum

Receives the world-to-frustum matrix of the camera.

function result

Success or failure of the operation.

( TQ3Status ) Q3Camera_GetWorldToView (
    TQ3CameraObject camera,
    TQ3Matrix4x4 *worldToView
);

Discussion

Get the world-to-view matrix of a camera.

The world-to-view matrix transforms world coordinates to a coordinate system relative to the camera. The origin of this coordinate system is the camera location, with the camera view pointing down the -z axis and the camera up vector placed along the +y axis.

Parameter Descriptions

camera

The camera to query.

worldToView

Receives the world-to-view matrix of the camera.

function result

Success or failure of the operation.

( TQ3Status ) Q3Camera_SetData (
    TQ3CameraObject camera,
    const TQ3CameraData *cameraData
);

Discussion

Set the common state for a camera.

Parameter Descriptions

camera

The camera to update.

cameraData

The new common state for the camera.

function result

Success or failure of the operation.

( TQ3Status ) Q3Camera_SetPlacement (
    TQ3CameraObject camera,
    const TQ3CameraPlacement *placement
);

Discussion

Set the placement for a camera.

Parameter Descriptions

camera

The camera to update.

placement

The new placement for the camera.

function result

Success or failure of the operation.

( TQ3Status ) Q3Camera_SetRange (
    TQ3CameraObject camera,
    const TQ3CameraRange *range
);

Discussion

Set the range for a camera.

Parameter Descriptions

camera

The camera to update.

range

The new range for the camera.

function result

Success or failure of the operation.

( TQ3Status ) Q3Camera_SetViewPort (
    TQ3CameraObject camera,
    const TQ3CameraViewPort *viewPort
);

Discussion

Set the view port for a camera.

Parameter Descriptions

camera

The camera to update.

viewPort

The new view port for the camera.

function result

Success or failure of the operation.

( TQ3Status ) Q3OrthographicCamera_GetBottom (
    TQ3CameraObject camera,
    float *bottom
);

Discussion

Get the bottom side of the viewing frustum of an orthographic camera.

Parameter Descriptions

camera

The camera to query.

bottom

Receives the bottom side of the camera.

function result

Success or failure of the operation.

( TQ3Status ) Q3OrthographicCamera_GetData (
    TQ3CameraObject camera,
    TQ3OrthographicCameraData *cameraData
);

Discussion

Get the data for an orthographic camera.

Parameter Descriptions

camera

The camera to query.

cameraData

Receives the data of the camera.

function result

Success or failure of the operation.

( TQ3Status ) Q3OrthographicCamera_GetLeft (
    TQ3CameraObject camera,
    float *left
);

Discussion

Get the left side of the viewing frustum of an orthographic camera.

Parameter Descriptions

camera

The camera to query.

left

Receives the left side of the camera.

function result

Success or failure of the operation.

( TQ3Status ) Q3OrthographicCamera_GetRight (
    TQ3CameraObject camera,
    float *right
);

Discussion

Get the right side of the viewing frustum of an orthographic camera.

Parameter Descriptions

camera

The camera to query.

right

Receives the right side of the camera.

function result

Success or failure of the operation.

( TQ3Status ) Q3OrthographicCamera_GetTop (
    TQ3CameraObject camera,
    float *top
);

Discussion

Get the top side of the viewing frustum of an orthographic camera.

Parameter Descriptions

camera

The camera to query.

top

Receives the top side of the camera.

function result

Success or failure of the operation.

( TQ3CameraObject ) Q3OrthographicCamera_New (
    const TQ3OrthographicCameraData *orthographicData
);

Discussion

Create a new orthographic camera object.

Parameter Descriptions

orthographicData

The data for the camera object.

function result

The new camera object.

( TQ3Status ) Q3OrthographicCamera_SetBottom (
    TQ3CameraObject camera,
    float bottom
);

Discussion

Set the bottom side of the viewing frustum of an orthographic camera.

Parameter Descriptions

camera

The camera to update.

bottom

The new bottom side for the camera.

function result

Success or failure of the operation.

( TQ3Status ) Q3OrthographicCamera_SetData (
    TQ3CameraObject camera,
    const TQ3OrthographicCameraData *cameraData
);

Discussion

Set the data for an orthographic camera.

Parameter Descriptions

camera

The camera to update.

cameraData

The new data for the camera.

function result

Success or failure of the operation.

( TQ3Status ) Q3OrthographicCamera_SetLeft (
    TQ3CameraObject camera,
    float left
);

Discussion

Set the left side of the viewing frustum of an orthographic camera.

Parameter Descriptions

camera

The camera to update.

left

The new left side for the camera.

function result

Success or failure of the operation.

( TQ3Status ) Q3OrthographicCamera_SetRight (
    TQ3CameraObject camera,
    float right
);

Discussion

Set the right side of the viewing frustum of an orthographic camera.

Parameter Descriptions

camera

The camera to update.

right

The new right side for the camera.

function result

Success or failure of the operation.

( TQ3Status ) Q3OrthographicCamera_SetTop (
    TQ3CameraObject camera,
    float top
);

Discussion

Set the top side of the viewing frustum of an orthographic camera.

Parameter Descriptions

camera

The camera to update.

top

The new top side for the camera.

function result

Success or failure of the operation.

( TQ3Status ) Q3ViewAngleAspectCamera_GetAspectRatio (
    TQ3CameraObject camera,
    float *aspectRatioXToY
);

Discussion

Get the aspect ratio of a view angle aspect camera.

If the aspect ratio is greater than 1.0, the field of view of the camera is vertical. If it is less than 1.0, the field of view is horizontal.

Parameter Descriptions

camera

The camera to query.

aspectRatioXToY

Receives the horizontal-to-vertical aspect ratio of the camera.

function result

Success or failure of the operation.

( TQ3Status ) Q3ViewAngleAspectCamera_GetData (
    TQ3CameraObject camera,
    TQ3ViewAngleAspectCameraData *cameraData
);

Discussion

Get the data for a view angle aspect camera.

Parameter Descriptions

camera

The camera to query.

cameraData

Receives the data of the camera.

function result

Success or failure of the operation.

( TQ3Status ) Q3ViewAngleAspectCamera_GetFOV (
    TQ3CameraObject camera,
    float *fov
);

Discussion

Get the field of view of a view angle aspect camera.

The field of view is specified in radians.

Parameter Descriptions

camera

The camera to query.

fov

Receives the field of view of the camera.

function result

Success or failure of the operation.

( TQ3CameraObject ) Q3ViewAngleAspectCamera_New (
    const TQ3ViewAngleAspectCameraData *cameraData
);

Discussion

Create a new view angle aspect camera object.

Parameter Descriptions

cameraData

The data for the camera object.

function result

The new camera object.

( TQ3Status ) Q3ViewAngleAspectCamera_SetAspectRatio (
    TQ3CameraObject camera,
    float aspectRatioXToY
);

Discussion

Set the aspect ratio for a view angle aspect camera.

If the aspect ratio is greater than 1.0, the field of view of the camera is vertical. If it is less than 1.0, the field of view is horizontal.

Parameter Descriptions

camera

The camera to update.

aspectRatioXToY

The new horizontal-to-vertical aspect ratio of the camera.

function result

Success or failure of the operation.

( TQ3Status ) Q3ViewAngleAspectCamera_SetData (
    TQ3CameraObject camera,
    const TQ3ViewAngleAspectCameraData *cameraData
);

Discussion

Set the data for a view angle aspect camera.

Parameter Descriptions

camera

The camera to update.

cameraData

The new data for the camera.

function result

Success or failure of the operation.

( TQ3Status ) Q3ViewAngleAspectCamera_SetFOV (
    TQ3CameraObject camera,
    float fov
);

Discussion

Set the field of view for a view angle aspect camera.

The field of view is specified in radians.

Parameter Descriptions

camera

The camera to update.

fov

The new field of view for the camera.

function result

Success or failure of the operation.

( TQ3Status ) Q3ViewPlaneCamera_GetCenterX (
    TQ3CameraObject camera,
    float *centerXOnViewPlane
);

Discussion

Get the x coordinate of the view rectangle center of a view plane camera.

The area of the view plane which will be rendered is a rectangle, whose origin in x is at the returned coordinate.

Parameter Descriptions

camera

The camera to query.

centerXOnViewPlane

Receives the x coordinate of the center of the view rectangle.

function result

Success or failure of the operation.

( TQ3Status ) Q3ViewPlaneCamera_GetCenterY (
    TQ3CameraObject camera,
    float *centerYOnViewPlane
);

Discussion

Get the y coordinate of the view rectangle center of a view plane camera.

The area of the view plane which will be rendered is a rectangle, whose origin in y is at the returned coordinate.

Parameter Descriptions

camera

The camera to query.

centerYOnViewPlane

Receives the y coordinate of the center of the view rectangle.

function result

Success or failure of the operation.

( TQ3Status ) Q3ViewPlaneCamera_GetData (
    TQ3CameraObject camera,
    TQ3ViewPlaneCameraData *cameraData
);

Discussion

Get the data for a view plane camera.

Parameter Descriptions

camera

The camera to query.

cameraData

Receives the data of the camera.

function result

Success or failure of the operation.

( TQ3Status ) Q3ViewPlaneCamera_GetHalfHeight (
    TQ3CameraObject camera,
    float *halfHeightAtViewPlane
);

Discussion

Get the half-height of the view rectangle of a view plane camera.

The area of the view plane which will be rendered is a rectangle, whose height is twice the returned half-height.

Parameter Descriptions

camera

The camera to query.

halfHeightAtViewPlane

Receives the half-height of the view rectangle.

function result

Success or failure of the operation.

( TQ3Status ) Q3ViewPlaneCamera_GetHalfWidth (
    TQ3CameraObject camera,
    float *halfWidthAtViewPlane
);

Discussion

Get the half-width of the view rectangle of a view plane camera.

The area of the view plane which will be rendered is a rectangle, whose width is twice the returned half-width.

Parameter Descriptions

camera

The camera to query.

halfWidthAtViewPlane

Receives the half-width of the view rectangle.

function result

Success or failure of the operation.

( TQ3Status ) Q3ViewPlaneCamera_GetViewPlane (
    TQ3CameraObject camera,
    float *viewPlane
);

Discussion

Get the view plane distance of a view plane camera.

The view plane distance is the distance along the camera view vector from the camera location.

Parameter Descriptions

camera

The camera to query.

viewPlane

Receives the view plane distance of the camera.

function result

Success or failure of the operation.

( TQ3CameraObject ) Q3ViewPlaneCamera_New (
    const TQ3ViewPlaneCameraData *cameraData
);

Discussion

Create a new view plane camera object.

Parameter Descriptions

cameraData

The data for the camera object.

function result

The new camera object.

( TQ3Status ) Q3ViewPlaneCamera_SetCenterX (
    TQ3CameraObject camera,
    float centerXOnViewPlane
);

Discussion

Set the x coordinate of the view rectangle center of a view plane camera.

The area of the view plane which will be rendered is a rectangle, whose origin in x is at the specified coordinate.

Parameter Descriptions

camera

The camera to update.

centerXOnViewPlane

The new x coordinate for the center of the view rectangle.

function result

Success or failure of the operation.

( TQ3Status ) Q3ViewPlaneCamera_SetCenterY (
    TQ3CameraObject camera,
    float centerYOnViewPlane
);

Discussion

Set the y coordinate of the view rectangle center of a view plane camera.

The area of the view plane which will be rendered is a rectangle, whose origin in y is at the specified coordinate.

Parameter Descriptions

camera

The camera to update.

centerYOnViewPlane

The new y coordinate for the center of the view rectangle.

function result

Success or failure of the operation.

( TQ3Status ) Q3ViewPlaneCamera_SetData (
    TQ3CameraObject camera,
    const TQ3ViewPlaneCameraData *cameraData
);

Discussion

Set the data for a view plane camera.

Parameter Descriptions

camera

The camera to update.

cameraData

The new data for the camera.

function result

Success or failure of the operation.

( TQ3Status ) Q3ViewPlaneCamera_SetHalfHeight (
    TQ3CameraObject camera,
    float halfHeightAtViewPlane
);

Discussion

Set the half-height of the view rectangle of a view plane camera.

The area of the view plane which will be rendered is a rectangle, whose height is twice the specified half-height.

Parameter Descriptions

camera

The camera to update.

halfHeightAtViewPlane

The new half-height of the view rectangle.

function result

Success or failure of the operation.

( TQ3Status ) Q3ViewPlaneCamera_SetHalfWidth (
    TQ3CameraObject camera,
    float halfWidthAtViewPlane
);

Discussion

Set the half-width of the view rectangle of a view plane camera.

The area of the view plane which will be rendered is a rectangle, whose width is twice the specified half-width.

Parameter Descriptions

camera

The camera to update.

halfWidthAtViewPlane

The new half-width of the view rectangle.

function result

Success or failure of the operation.

( TQ3Status ) Q3ViewPlaneCamera_SetViewPlane (
    TQ3CameraObject camera,
    float viewPlane
);

Discussion

Set the view plane distance for a view plane camera.

The view plane distance is the distance along the camera view vector from the camera location.

Parameter Descriptions

camera

The camera to update.

viewPlane

The new view plane distance for the camera.

function result

Success or failure of the operation.

Structs

typedef struct TQ3CameraData {
    TQ3CameraPlacement                          placement;
    TQ3CameraRange                              range;
    TQ3CameraViewPort                           viewPort;
} TQ3CameraData;

Discussion

Describes the common state for a camera.

The common camera state includes its position and orientation within the world (placement), the near and far clipping planes (range), and the current viewport.

Field Descriptions

placement

The position and orientation of the camera.

range

The near and far clipping planes of the camera.

viewPort

The viewport for the camera.

typedef struct TQ3CameraPlacement {
    TQ3Point3D                                  cameraLocation;
    TQ3Point3D                                  pointOfInterest;
    TQ3Vector3D                                 upVector;
} TQ3CameraPlacement;

Discussion

Describes the location and orientation of a camera. All points are in world-space coordinates.

Field Descriptions

cameraLocation

The location of the camera.

pointOfInterest

The point at which the camera is aimed.

upVector

The up vector for the camera. This vector must be normalised and perpendicular to the viewing direction of the camera. This vector is transformed to the y axis of the viewing plane.

typedef struct TQ3CameraRange {
    float                                       hither;
    float                                       yon;
} TQ3CameraRange;

Discussion

Objects closer than the hither distance or farther than the yon distance will be clipped, i.e., invisible, so you usually want hither to be closer than any object and yon to be farther than any object.

The hither and yon values, together with the bit depth of your depth buffer, determine how small a difference in depths can be resolved. It is more important to make hither as large as possible than to make yon as small as possible.

Field Descriptions

hither

The distance from the camera to the near clipping plane. This value must always be greater than 0.

yon

The distance from the camera to the far clipping plane. This value must always be greater than the hither field, and is allowed to be INFINITY.

typedef struct TQ3CameraViewPort {
    TQ3Point2D                                  origin;
    float                                       width;
    float                                       height;
} TQ3CameraViewPort;

Discussion

Describes the viewport for a camera.

The camera viewport is the rectangular area of the view plane which is mapped to the rendered area of the current draw context. The default mapping is a square of size 2.0x2.0, with the top left corner anchored at {-1.0, 1.0}.

By adjusting the viewport, it is possible to control which area of the camera's view is rendered (e.g., to divide an image into a series of horizontal strips for printing).

Field Descriptions

origin

The origin for the viewport.

width

The width of the viewport.

height

The width of the viewport.

typedef struct TQ3OrthographicCameraData {
    TQ3CameraData                               cameraData;
    float                                       left;
    float                                       top;
    float                                       right;
    float                                       bottom;
} TQ3OrthographicCameraData;

Discussion

Describes the state for an orthographic camera.

An orthographic camera is defined by four view planes, which form a box aligned with the camera view direction. These planes are defined by distances relative to the coordinate system formed by the camera location and its view direction.

Field Descriptions

cameraData

The common state for the camera.

left

The left side of the view volume.

top

The top side of the view volume.

right

The right side of the view volume.

bottom

The bottom side of the view volume.

typedef struct TQ3ViewAngleAspectCameraData {
    TQ3CameraData                               cameraData;
    float                                       fov;
    float                                       aspectRatioXToY;
} TQ3ViewAngleAspectCameraData;

Discussion

Describes the state for a traditional perspective camera.

A view angle aspect camera is a perspective camera defined by a field of view angle and an aspect ratio.

The field of view angle must be a positive angle in radians. If the aspect ratio is greater than 1.0, the field of view represents the vertical range of visibility, and if the aspect ratio is less than 1.0, the field of view is horizontal. In other words, the field of view is the smaller of the two angles.

Field Descriptions

cameraData

The common state for the camera.

fov

The field of view of the camera, in radians.

aspectRatioXToY

The horizontal-to-vertical aspect ratio of the camera.

typedef struct TQ3ViewPlaneCameraData {
    TQ3CameraData                               cameraData;
    float                                       viewPlane;
    float                                       halfWidthAtViewPlane;
    float                                       halfHeightAtViewPlane;
    float                                       centerXOnViewPlane;
    float                                       centerYOnViewPlane;
} TQ3ViewPlaneCameraData;

Discussion

Describes the state for a view plane camera.

A view plane camera is a perspective camera which allows the specification of an off-center viewing frustum.

The frustum is formed by following the camera view direction for a given distance, then taking the specified rectangle on that plane. The frustum extends from the camera position through the four edges of this rectangle.

Field Descriptions

cameraData

The common state for the camera.

viewPlane

The distance from the camera to the view plane.

halfWidthAtViewPlane

The half-width of the rectangle on the view plane.

halfHeightAtViewPlane

The half-height of the rectangle on the view plane.

centerXOnViewPlane

The x-center of the rectangle on the view plane.

centerYOnViewPlane

The y-center of the rectangle on the view plane.

© 1999-2008 Quesa Developers (Last Updated 5/10/2008)