Brief Index      Full Index      Events Index      I.M. Reference

Set_Camera_Up_Vector

Functions

void Set_Camera_Up_Vector (double x, double y, double z)
void DSet_Camera_Up_Vector (double x, double y, double z)

Function Documentation

void Set_Camera_Up_Vector ( double  x,
double  y,
double  z 
)

Given a "camera" position and target, which define a line of sight, the "up vector" defines how much the camera is tilted.

Parameters:
x- x component, in object-space coordinates, of a vector that defines the direction the top of the camera should face.
y- y component, in object-space coordinates, of a vector that defines the direction the top of the camera should face.
z- z component, in object-space coordinates, of a vector that defines the direction the top of the camera should face.

DETAILS

The "camera up vector" is a vector pointing out the top of the virtual viewing camera, perpendicular to the line of sight. It represents how much "tilt" there is on the camera. Usually you're not interested, but if you are, you can want to make a relative adjustment to the tilt with Roll_Camera() . On rare occasions you might need to give it an absolute setting

Warning: what follows is obscure!

It would be nice to represent the "tilt" as an angle with respect to something, but there's no good choice available. So the tilt has to be a generic vector instead---the "up vector".

When moving the camera to and fro, the system tries to keep it oriented in a "reasonable" direction around the line of sight. The user normally makes relative adjustments to it by calling Roll_Camera() . In unusual cases, you may feel an urge to orient the camera in some absolute direction. Set_Camera_Up_Vector() does this for you.

In particular, on many camera changes---a left-right pan, orbit, or dolly, or a set field, for example---the up vector is untouched. But on many other operations---for example, a set position or set target---it might not be possible to leave it unchanged and have it still be perpendicular to the line of sight. So the system has to make it perpendicular once again. The convention in this case is to figure a new up vector that lies at the same angle to the plane of motion as the old one did.

So, if you want to make sure that you're getting the up vector you want, you should call Set_Camera_Up_Vector() after each series of camera changes.

For example, to keep the camera oriented as much as possible towards the positive Y direction, you would have to call Set_Camera_Up_Vector() with parameters of (0.0, 1.0, 0.0) after each and every series of calls to Set Position, Set Target, or Dolly. (Be aware that if the camera ends up looking dead along the Y -axis, and the up vector is (0.0, 1.0, 0.0), the system won't know what to do and you'll get an error at Update time.)

NOTES

If no camera previously existed in the specified segment, then a complete default camera will be provided, without regard to any camera specifications that there may have been in the higher-up segments.

If the requested Up Vector is not perpendicular to the current line of sight, the system converts it into the nearest vector that is.

If it can't be converted because it's colinear with the line of sight, the system accepts it anyhow in the hope that you're about to call Set Camera Position or Set Camera Target. If it's still not legitimate when Update is called, you get an error.

If the requested Up Vector is all zeroes, you get an error too---right away.

RESTRICTIONS

See also:
Set_Camera or Set_Camera_By_Volume, Set_Camera_Field, Set_Camera_Position, Set_Camera_Projection, Set_Camera_Target, Zoom_Camera, Orbit_Camera, Pan_Camera, Dolly_Camera, Roll_Camera, Set_Window, Translate_Object, Rotate_Object.
void DSet_Camera_Up_Vector ( double  x,
double  y,
double  z 
)

Similar to Set_Camera_Up_Vector(). This command should be used in conjunction with other double-precision Set_Camera functions.

Parameters:
x- x component, in object-space coordinates, of a vector that defines the direction the top of the camera should face.
y- y component, in object-space coordinates, of a vector that defines the direction the top of the camera should face.
z- z component, in object-space coordinates, of a vector that defines the direction the top of the camera should face.

DETAILS

No additional details. See Set_Camera_Up_Vector()

Brief Index      Full Index      Events Index      I.M. Reference