HC_Compute_Transform

bool HC_Compute_Transform(char const *segment, char const *in_system, char const *out_system, float matrix[])
bool HC_Compute_Transform(char const segment, char const in_system, char const out_system, float matrix)

Converts positions back and forth among the various coordinate systems.

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.

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_Compute_Coordinates, HC_Show_Selection_Position, HC_Show_Polyline, HC_Show_Shell, HC_Show_Marker.

Parameters

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.

out_system: Special constants for the input and output coordinate spaces.

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 Visualize.) Returned to user.

Returns

success