Functions | |
void | Set_Camera_Up_Vector (double x, double y, double z) |
void | DSet_Camera_Up_Vector (double x, double y, double z) |
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.
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. |
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.)
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.
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.
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. |