Functions | |
HC_BOOLEAN | Compute_Transform (const char *segment, const char *in_system, const char *out_system, float *matrix) |
HC_BOOLEAN | Compute_Transform_By_Path (int count, const HC_KEY *keys, const char *in_system, const char *out_system, float *matrix) |
HC_BOOLEAN Compute_Transform | ( | const char * | segment, |
const char * | in_system, | ||
const char * | out_system, | ||
float * | matrix | ||
) |
Converts positions back and forth among the various coordinate systems.
segment | - The name of a segment that provides the Window, Camera, and/or Driver attributes for the conversion. |
in_system | - Special constants for the input and output coordinate spaces---(see below). |
out_system | - Special constants for the input and output coordinate spaces---(see below). |
matrix | - The transformation matrix necessary to take points from in_system to out_system. Passed by reference in all languages. May need to be transposed in languages other than C (unless immediately passed back into HOOPS.) Returned to user. |
This routine examines the attributes present on segment and its owners, returns a matrix suitable for converting points or planes from in_system coordinates to out_system coordinates. The matrix will often be passed directly to Compute_Transformed_Points() or Compute_Transformed_Plane() .
If you have just one or a couple of points to transform it might be more efficient to call Compute_Coordinates() , the sister routine of Compute_Transform() . Also, if you are going to call Compute_Transformed_Plane() for a number of planes, check the note on efficiency at the bottom of Compute_(Vectors_and_Matrices).
The in_system and out_system parameters to Compute_Coordinates() is a comma-separated list of options which can include the following:
local window
The value is in terms of the local window for segment. (The Z coordinate is usually zero.)
outer window
The value is in terms of the outermost window for segment. ("Outermost" refers to the first segment going up from segment which has a Driver attribute.)
local pixels
The value is measured in screen pixels within the local window on segment. The upper-left of the window is pixel (0, 0); they descend going down and to the right. (The Z coordinate is usually zero.)
outer pixels
The value is in terms of pixels within the outermost window on segment.
viewpoint
The value is in viewpoint coordinate system, which is based on the position of the observer (camera). The origin is at the camera position. The viewing direction is the Z axis and the camera up vector is the Y axis.
world
The value is in normal world coordinates (the coordinate system in which the camera is positioned; the coordinates of geometry after modelling matrices have been applied, but before projecting through a camera into a window.) A window Z value of zero maps to the current camera "target" plane.
camera
The coordinate system used in calls to Set_Camera_Position() , etc. A synonym for world coordinates.
object
The value is in the coordinate system that real geometry lives in (such as "world" coordinates, but does not include the Modelling Matrices, if any).
If a conversion is ambiguous (one of the matrices is singular), the system chooses arbitrarily among the valid possibilities. If a conversion is impossible (e.g., the camera is singular), a false function status returns and matrix will be unchanged.
If your transform doesn't include a perspective transform---if it doesn't include going from world or camera space to a perspective window space---the fourth column of the returned matrix is guaranteed to be zero-zero-zero-one.
If the fourth column of a matrix is not zero-zero-zero-nonzero, that matrix can't be used in a call to Set or Append Modelling Matrix.
If the in_system specification matches the out_system specification, the routine immediately returns true with an identity matrix. In the interest of speed, no error checking is conducted.
The Compute_XXX() routines that require information about display drivers, do not work if they are called from an included segment. Display information must be associated with a window to return information about the display.
Calling Compute_XXX() routines to obtain data associated with a display generates an update. On most devices, this poses no problem. However, for hardcopy devices such as Postscript or CGM, this can generate a blank page. To avoid this problem, applications often open a temporary driver subsegment, call the compute routine, retain the computed information, and then discard the temporary driver subsegment.
HC_BOOLEAN Compute_Transform_By_Path | ( | int | count, |
const HC_KEY * | keys, | ||
const char * | in_system, | ||
const char * | out_system, | ||
float * | matrix | ||
) |
Similar to Compute_Transform(), but concatenates the matrices along a segment path rather than the currently open segment.
count | - The size of the keys array |
keys | - The array of keys starting with the owning segment and following all the way back to the root segment or other desired segment. |
in_system | - Special constants for the input and output coordinate spaces---(see below). |
out_system | - Special constants for the input and output coordinate spaces---(see below). |
matrix | - The transformation matrix necessary to take points from in_system to out_system. Passed by reference in all languages. May need to be transposed in languages other than C (unless immediately passed back into HOOPS.) Returned to user. |
No additional details. See Compute_Transform()