NAME

EVALUATE VIEW MAPPING MATRIX 3 − generate a transformation matrix to map a 3D VRC window to a 3D NPC viewport

SYNOPSIS

C Syntax

void
peval_view_map_matrix3 ( map, error_ind, m )
Pview_map3∗map;view mapping
Pint∗error_ind;OUT error indicator
Pmatrix3m;OUT view mapping matrix

Required PHIGS Operating States

(PHOP, ∗, ∗, ∗)

DESCRIPTION

Purpose

Use EVALUATE VIEW MAPPING MATRIX 3 to calculate the viewing transformation matrix that transforms a specified 3D window in View Reference Coordinates (VRC) to a specified 3D viewport in Normalized Projection Coordinates (NPC).  The viewing transformation may be either a parallel or perspective transformation. 

The view mapping matrix returned by this function may be used as an argument to the SET VIEW REPRESENTATION 3 function.  See the descriptions of the functions SET VIEW REPRESENTATION 3 and EVALUATE VIEW ORIENTATION MATRIX 3 for more information. 

C Input Parameters

mapA pointer to a Pview_map3 structure defining the view mapping.  This structure is defined in phigs.h as follows:

typedef struct {
Plimitwin;/∗ window limits ∗/
Plimit3proj_vp;/∗ viewport limits ∗/
Pproj_typeproj_type;/∗ projection type ∗/
Ppoint3proj_ref_point;/∗ projection reference point ∗/
Pfloatview_plane;/∗ view plane distance ∗/
Pfloatback_plane;/∗ back plane distance ∗/
Pfloatfront_plane;/∗ front plane distance ∗/
} Pview_map3;

win is a Plimit structure containing u and v VRC values defining the window limits.  Plimit is defined in phigs.h as follows:

typedef struct {
Pfloatx_min;/∗ x minimum ∗/
Pfloatx_max; /∗ x maximum ∗/
Pfloaty_min;/∗ y minimum ∗/
Pfloaty_max; /∗ y maximum ∗/
} Plimit;

The fields in Plimit define the VRC window as follows:

Plimit.x_min = minimum u coordinate value
Plimit.x_max = maximum u coordinate value
Plimit.y_min = minimum v coordinate value
Plimit.y_max = maximum v coordinate value

proj_vp is a Plimit3 structure containing the NPC viewport limits.  min and max correspond to the back lower left and front upper right coordinates of the viewport volume, respectively.  Plimit3 is defined in phigs.h as follows:

typedef struct {
Pfloatx_min;/∗ x minimum ∗/
Pfloatx_max; /∗ x maximum ∗/
Pfloaty_min;/∗ y minimum ∗/
Pfloaty_max; /∗ y maximum ∗/
Pfloatz_min;/∗ z minimum ∗/
Pfloatz_max; /∗ z maximum ∗/
} Plimit3;

proj_type is an enumerated type that may take the following values:

•  PTYPE_PARAL
•  PTYPE_PERSPECT

proj_ref_point is the Projection Reference Point, defined in VRC.  Ppoint3 is defined in  phigs.h as follows

typedef struct {
Pfloatx;/∗ x coordinate ∗/
Pfloaty;/∗ y coordinate ∗/
Pfloatz;/∗ z coordinate ∗/
} Ppoint3;

view_plane is the VRC location of the view plane on the n axis of the VRC coordinate system. 

back_plane is the VRC location of the back plane on the n axis of the VRC coordinate system. 

front_plane is the VRC location of the front plane on the n axis of the VRC coordinate system. 

C Output Parameters

err_ind
A pointer to the location to store the error number of any error detected by this function.

mA Pmatrix3 structure containing the 3D (4 × 4) transformation matrix that performs the specified mapping.  Pmatrix3 is defined in phigs.h as follows:

typedef Pfloat Pmatrix3[4][4];

Execution

If the input parameters are properly defined, EVALUATE VIEW MAPPING MATRIX 3 returns a 3D (4 × 4) transformation matrix in the output parameter view mapping matrix.  This transformation matrix performs the specified mapping from the VRC window to the NPC viewport. 

The front plane, back plane, and view plane all define planes in VRC space parallel to the uv plane of the VRC system. The location of front and back along the n axis of VRC defines the front and back of the volume of VRC that will be mapped to NPC.  The view plane locates the view window on the VRC n axis, and window defines the size of the view window by specifying maximum and minimum u and v values that establish the edges of the window.  These values taken together establish the volume of VRC space that is mapped into the NPC viewport. 

The type of projection may be parallel or perspective.  The projection reference point orients the projectors defining the surfaces of the view volume.  If the projection type is parallel, the projectors are all parallel to the vector joining the projection reference point and the center of the view window (located on the view plane).  If the projection type is perspective, the projectors all converge at the projection reference point.  Thus, the view volume is a parallelpiped for parallel views, and a portion of a double rectangular cone for perspective views. 

ERRORS

002Ignoring function, function requires state (PHOP, ∗, ∗, ∗)

151Ignoring function, invalid window; XMIN ≥ XMAX or YMIN ≥ YMAX

152Ignoring function, invalid viewport; XMIN ≥ XMAX, YMIN ≥ YMAX, or ZMIN > ZMAX

158Ignoring function, front plane and back plane distances are equal when z-extent of the projection viewport is zero

162Ignoring function, the projection reference point is between the front and back planes

163Ignoring function, the projection reference point cannot be positioned on the view plane

164Ignoring function, the back plane is in front of the front plane

155Ignoring function, the projection viewport limits are not within NPC range

September 02, 1992