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
pevalviewmappingmatrix3 ( mapping, error_ind, matrix )
Pviewmapping3∗mapping; view mapping
Pint∗error_ind;OUT error indicator
Pmatrix3matrix;OUT view mapping matrix

FORTRAN Syntax

SUBROUTINE pevmm3 ( VWWNLM, PJVPLM, PJTYPE, PJRX, PJRY, PJRZ, VPLD, BPLD, FPLD,
    ERRIND, VWMPMT )
REALVWWNLM(4)window limits (VRC)
REALPJVPLM(6)projection viewport limits (NPC)
INTEGERPJTYPEprojection type (PPARL, PPERS)
REALPJRX, PJRY, PJRZprojection reference point (VRC)
REALVPLDview plane distance (VRC)
REALBPLDback plane distance (VRC)
REALFPLDfront plane distance (VRC)
INTEGERERRINDOUT error indicator
REALVWMPMT(4, 4)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

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

typedef struct {
Plimitwindow;/∗ window limits ∗/
Plimit3viewport;/∗ viewport limits ∗/
Pprojtypeproj;/∗ projection type ∗/
Ppoint3prp;/∗ projection reference point ∗/
Pfloatview_plane;/∗ view plane distance ∗/
Pfloatback_plane;/∗ back plane distance ∗/
Pfloatfront_plane;/∗ front plane distance ∗/
} Pviewmapping3;

window is a Plimit structure containing u and v VRC values defining the window limits.  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 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 {
Pfloatxmin;/∗ x minimum ∗/
Pfloatxmax;/∗ x maximum ∗/
Pfloatymin;/∗ y minimum ∗/
Pfloatymax;/∗ y maximum ∗/
Pfloatzmin;/∗ z minimum ∗/
Pfloatzmax;/∗ z maximum ∗/
} Plimit3;

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

•  PPARALLEL
•  PPERSPECTIVE

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

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

typedef Pfloat Pmatrix3[4][4];

FORTRAN Input Parameters

VWWNLM
A four element array containing the 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 six 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
PJVPLM(5)= minimum z NPC coordinate value
PJVPLM(6)= maximum z NPC coordinate value

Minimum and maximum correspond to the front lower left and back upper right coordinates of the viewport volume, respectively. 

PJTYPE
The projection type. Valid values as defined in phigs77.h are:

•  PPARLParallel
•  PPERSPerspective

PJRX, PJRY, PJRZ
The Projection Reference Point coordinates, defined in VRC. 

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

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

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

FORTRAN Output Parameters

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

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

Execution

If the input parameters are properly defined, EVALUATE VIEW MAPPING MATRIX 3 returns a 3D (4 x 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 along 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, YMIN ≥ YMAX, or ZMIN > ZMAX

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

Sun Release 4.0  —  Last change: 2 August 1989