Name

peval_view_map_matrix3 − Returns a view mapping matrix. 

Operating States: PHOP, ∗, ∗, ∗
PHIGS standard function

Syntax

void peval_view_map_matrix3 (
  const Pview_map3  ∗mapping,    /∗ (I) View mapping ∗/
  Pint              ∗error_ind,  /∗ (O) Error indicator ∗/
  Pmatrix3           matrix      /∗ (O) View mapping matrix ∗/
)

Data Structures

typedef struct {
    Plimit      win;            /∗ window limits ∗/
    Plimit3     proj_vp;        /∗ projection viewport limits ∗/
    Pproj_type  proj_type;      /∗ projection type ∗/
    Ppoint3     proj_ref_point; /∗ projection reference point ∗/
    Pfloat      view_plane;     /∗ view plane distance ∗/
    Pfloat      back_plane;     /∗ back plane distance ∗/
    Pfloat      front_plane;    /∗ front plane distance ∗/
} Pview_map3;
    typedef struct {
        Pfloat   x_min;    /∗ x minimum ∗/
        Pfloat   x_max;    /∗ x maximum ∗/
        Pfloat   y_min;    /∗ y minimum ∗/
        Pfloat   y_max;    /∗ y maximum ∗/
    } Plimit;
    typedef struct {
        Pfloat   x_min;    /∗ x minimum ∗/
        Pfloat   x_max;    /∗ x maximum ∗/
        Pfloat   y_min;    /∗ y minimum ∗/
        Pfloat   y_max;    /∗ y maximum ∗/
        Pfloat   z_min;    /∗ z minimum ∗/
        Pfloat   z_max;    /∗ z maximum ∗/
    } Plimit3;
    typedef enum {
        PTYPE_PARAL,     /∗ parallel projection ∗/
        PTYPE_PERSPECT   /∗ perspective projection ∗/
    } Pproj_type;
    typedef struct {
        Pfloat    x;    /∗ x coordinate ∗/
        Pfloat    y;    /∗ y coordinate ∗/
        Pfloat    z;    /∗ z coordinate ∗/
    } Ppoint3;
typedef Pfloat Pmatrix3[4][4];

Description

peval_view_map_matrix3 returns a view mapping matrix, which can be passed as input to the pset_view_rep3 function.  The view mapping matrix in the view representation transforms the PHIGS coordinate system from view reference coordinate points to normalized projection coordinate points. 

To create the view mapping matrix, use the following procedure:
 

•Specify window limits (view window) within view reference coordinate space in the order UMIN, UMAX, VMIN, VMAX. 

The following restrictions apply:

UMIN < UMAX

VMIN < VMAX

The resulting view window is a rectangular region on the view plane with sides parallel to the u- and v-axes. 

The formation of the u- and v-axes in the view reference coordinate system is described in Getting Started with DEC PHIGS. 

•Specify projection viewport limits (view clipping limits) within normalized projection coordinate space in the order XMIN, XMAX, YMIN, YMAX, ZMIN, ZMAX. 

The following restrictions apply:

XMIN < XMAX

YMIN < YMAX

ZMIN <= ZMAX

XMIN, XMAX, YMIN, and YMAX must be in the range [0,1], inclusive. 

ZMIN and ZMAX must be in the range [0,1], inclusive. 

The view clipping limits form a rectangular parallelepiped in normalized projection coordinate space with its edges parallel to the normalized projection coordinate axes.  Although the normalized projection coordinate system conceptually extends beyond [0,1] x [0,1] x [0,1], the view clipping limits are located in the closed unit cube [0,1] x [0,1] x [0,1] in normalized projection coordinate space. 

The view, back, and front planes are parallel to the uv-plane of the view reference coordinate system.  They are specified as n coordinate values in the three plane arguments to this function. 

The front- and back-plane values specify the front and back of the view volume.  Conceptually, the view reference coordinate system is oriented to the view reference point, because the view reference coordinate points result from the view orientation transformation. (See the peval_view_ori_matrix3 function.)  Therefore, the front plane should not be positioned behind the back plane. 

The following restrictions apply to the view, front, and back planes:

•Back-plane distance < front-plane distance

•Back-plane distance = front-plane distance, if ZMIN = ZMAX

•The n coordinate of the projection reference point not equal to view plane distance

•For projection type = PERSPECTIVE,
  the n coordinate of the projection reference point is either > front-plane distance or < back-plane distance

Projection and the coordinate systems are described in Getting Started with DEC PHIGS. 

If the view mapping parameters are consistent and well defined (that is, if they conform to the specified rules and restrictions), a call to this function returns the 4 x 4 view mapping matrix.  Otherwise, a nonzero error indicator is returned. 

See Also

peval_view_ori_matrix3
pinq_view_facs
pe_inq_ext_view_rep3
pset_view_ind
pset_view_rep3