NAME

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

SYNOPSIS

C Syntax

void
pevalviewmappingmatrix ( mapping, error_ind, matrix )
Pviewmapping∗mapping;view mapping
Pint∗error_ind;OUT error indicator
Pmatrixmatrix;OUT view mapping matrix

FORTRAN Syntax

SUBROUTINE pevmm ( VWWNLM, PJVPLM, ERRIND, VWMPMT )
REALVWWNLM(4)window limits (VRC)
REALPJVPLM(4)projection viewport limits (NPC)
INTEGERERRINDOUT error indicator
REALVWMPMT(3, 3)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

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

typedef struct {
Plimitwindow;/∗ window limits ∗/
Plimitviewport;/∗ viewport limits ∗/
} Pviewmapping;

window 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 {
Pfloatxmin;/∗ x minimum ∗/
Pfloatxmax;/∗ x maximum ∗/
Pfloatymin;/∗ y minimum ∗/
Pfloatymax;/∗ y maximum ∗/
} Plimit;

The fields in Plimit define the VRC window as follows:

Plimit.xmin = minimum u coordinate value
Plimit.xmax = maximum u coordinate value
Plimit.ymin = minimum v coordinate value
Plimit.ymax = maximum v coordinate value

viewport 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.

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

typedef Pfloat Pmatrix[3][3];

FORTRAN Input Parameters

VWWNLM
A four element array containing u and v VRC values defining the window limits.  The array positions correspond to the window definition as follows:

VWWNLM(1) = minimum u coordinate value
VWWNLM(2) = maximum u coordinate value
VWWNLM(3) = minimum v coordinate value
VWWNLM(4) = maximum v coordinate value

PJVPLM
A four element array containing the definition of the NPC viewport.  The array positions correspond to the viewport definition as follows:

PJVPLM(1)= minimum x NPC coordinate value
PJVPLM(2)= maximum x NPC coordinate value
PJVPLM(3)= minimum y NPC coordinate value
PJVPLM(4)= maximum y NPC coordinate value

FORTRAN Output Parameters

ERRIND
The error number of any error detected by this function.

VWMPMT
The 2D (3 x 3) transformation matrix that performs the specified view mapping. 

Execution

If the input parameters are properly defined, EVALUATE VIEW MAPPING MATRIX returns a 2D (3 x 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 viewport definition:

u minimum < u maximum
v minimum < v maximum

The following restrictions apply to the window 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, YMIN ≥ YMAX, or ZMIN > ZMAX

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

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

Sun Release 4.0  —  Last change: 31 July 1989