NAME

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

SYNOPSIS

C Syntax

void
peval_view_map_matrix ( map, error_ind, m )
Pview_map∗map;view mapping
Pint∗error_ind;OUT error indicator
Pmatrixm;OUT view mapping matrix

Required PHIGS Operating States

(PHOP, ∗, ∗, ∗)

DESCRIPTION

Purpose

Use EVALUATE VIEW MAPPING MATRIX to calculate the viewing transformation matrix that transforms a specified window in View Reference Coordinates (VRC) to a specified viewport in Normalized Projection Coordinates (NPC). 

The view mapping matrix returned by this function may be used as an argument to the SET VIEW REPRESENTATION function to specify the mapping from VRC to NPC.  See the descriptions for the functions SET VIEW REPRESENTATION and EVALUATE VIEW ORIENTATION MATRIX in this function reference for more information. 

C Input Parameters

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

typedef struct {
Plimitwin;/∗ window limits ∗/
Plimitproj_vp;/∗ viewport limits ∗/
} Pview_map;

win is a Plimit structure containing u and v VRC values defining the window to be mapped to NPC.  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 Plimit structure containing the definition of the NPC viewport. 

C Output Parameters

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

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

typedef Pfloat Pmatrix[3][3];

Execution

If the input parameters are properly defined, EVALUATE VIEW MAPPING MATRIX returns a 2D (3 × 3) 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 following restrictions apply to the VRC window definition:

u minimum < u maximum
v minimum < v maximum

The following restrictions apply to the viewport definition:

0 <= x minimum < x maximum <= 1
0 <= y minimum < y maximum <= 1

Where zero and 1 are the NPC limits. 

The range of VRC coordinate units is determined by the view orientation transformation. 

The window to be mapped is specified in VRC by the window input parameter.  It is a rectangle located on the n = 0 plane whose sides are parallel to the u and v axes.  The rectangle is defined by minimum u and v values at the lower left hand corner and by the maximum u and v values at the upper right hand corner. 

The viewport to which the window is mapped is specified in NPC by the viewport input parameter.  It is a rectangle located in NPC space on the z = 0 plane whose sides are parallel to the xand yaxes. The rectangle is defined by the x and ycoordinates of the lower left corner and by the xand ycoordinates of the upper right corner.  The coordinate values must be within the closed unit square range of NPC space, [0,1] x [0,1]. 

ERRORS

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

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

152Ignoring function, invalid viewport; XMIN ≥ XMAX or YMIN ≥ YMAX. 

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

September 02, 1992