NAME

SET VIEW REPRESENTATION 3 − define 3D view representation entry on a workstation

SYNOPSIS

C Syntax

void
pset_view_rep3 ( ws, index, rep )
Pintws;workstation identifier
Pintindex;view index
Pview_rep3∗rep;view representation

Required PHIGS Operating States

(PHOP, WSOP, ∗, ∗)

DESCRIPTION

Purpose

SET VIEW REPRESENTATION 3 defines a view representation entry in the workstation’s view table, using a three-dimensional model.  A view representation defines how the composited objects are to be represented in relation to the viewer. 

A view representation controls the viewing stage of the transformation pipeline, which transforms coordinates in World Coordinates (WC) to Normalized Projection Coordinates (NPC), and optionally clips to the limits of NPC space. 

C Input Parameters

wsThe identifier of the workstation for which the view representation is being defined. 

indexThe view index of the entry being defined. 

repA pointer to a structure containing the values in the 3D view representation, defined as follows:

typedef struct {
Pmatrix3ori_matrix;/∗ orientation matrix ∗/
Pmatrix3map_matrix;/∗ mapping matrix ∗/
Plimit3clip_limit;/∗ clipping limits ∗/
Pclip_indxy_clip;/∗ x-y clipping indicator ∗/
Pclip_indback_clip;/∗ back clipping indicator ∗/
Pclip_indfront_clip;/∗ front clipping indicator ∗/
} Pview_rep3;

Pmatrix3 is defined in phigs.h as follows: typedef  Pfloat  Pmatrix3[4][4];

Plimit3 is defined in phigs.h as follows:

typedef struct {
Pfloatx_min; /∗ x min ∗/
Pfloatx_max; /∗ x max ∗/
Pfloaty_min; /∗ y min ∗/
Pfloaty_max; /∗ y max ∗/
Pfloatz_min; /∗ z min ∗/
Pfloatz_max; /∗ z max ∗/

} Plimit3;

Pclip_ind is defined in phigs.h as follows:

typedef enum {
PIND_NO_CLIP
PIND_CLIP
} Pclip_ind;

The ori_matrix is the 4 × 4 homogeneous view orientation matrix, probably from EVALUATE VIEW ORIENTATION MATRIX 3. 

The map_matrix is the 4 × 4 homogeneous view mapping matrix, probably from EVALUATE VIEW MAPPING MATRIX 3. 

The clip_limit contains the 6 Pfloat clipping limits: xmin, xmax, ymin, ymax, zmin, and zmax. 

The xy_clip contains the x-y clip indicator for the x and y axes. 

The back_clip contains the back clipping indicator, which controls clipping against the back plane, sometimes called the yon plane. 

The front_clip contains the front clipping indicator, which controls clipping against the front plane, sometimes called the fore plane. 

Execution

SET VIEW REPRESENTATION 3 defines a view representation entry in the workstation’s view table using a three-dimensional model. 

The current view index attribute applied to each output primitive at traversal time determines which view representation is used to map the primitive from WC space to NPC space, typically with a parallel or perspective projection. 

This viewing process for each output primitive is accomplished in three stages:

1.The view orientation matrix is applied to orient View Reference Coordinate (VRC) space with regard to WC space.  Use the utility function EVALUATE VIEW ORIENTATION MATRIX 3 to generate this matrix from a view reference point, view plane normal vector, and view up vector specified in WC.  The view reference point becomes the origin of VRC; the view plane normal and the view up vector orient the VRC space (VRC u and y axes) in relation to the WC axes. 

2.The view mapping matrix is applied to map the VRC system to the NPC system. Use the utility function EVALUATE VIEW MAPPING MATRIX 3 to generate this matrix. The utility accepts a specified view volume called a window in VRC space to be mapped onto a specified projection viewport in NPC space.  The projection is established in relation to the projection reference point, also specified in VRC space.  The projection may be perspective or parallel, oblique or non-oblique. 

3.Clipping limits are optionally applied. The view clipping limits define an area of NPC.  When a clipping indicator is set to Clipping, any portion of an object beyond that limit is not displayed. 

Note: These clipping limits are typically identical to the projection viewport provided to EVALUATE VIEW MAPPING MATRIX 3. If the clipping limits differ from the projection viewport, the object portions mapped by the view mapping matrix to be within the clipping limits in NPC are displayed. 

In any case, objects are subject to workstation clipping, which may not be disabled.  The maximum volume of NPC space that may be displayed is from 0 to 1 in all dimensions. 

The immediate visual effect of changing a view representation depends on the workstation’s display update state. When SET VIEW REPRESENTATION is called, the display update state may prohibit immediate updating (that is, regeneration) of the workstation’s display.  In this case, the view index view table entry’s viewing transformation update state is set to PENDING, and the following values for the entry are set to the values being requested by the function invocation:

•Requested view orientation matrix

•Requested view mapping matrix

•Requested view clipping limits

•Requested x-y clipping indicator

•Requested back clipping indicator

•Requested front clipping indicator

The next time the workstation is updated, for any view table entry with the viewing transformation update state set to PENDING, the values stored in the requested entries replace the corresponding current values for that view index, and the view entry’s viewing transformation update state is set to NOTPENDING. Then regeneration proceeds, and the new viewing representations take effect. 

Default Representation

View index 0 is the default for the current view index in the traversal state list.  View table entry 0 is the default view representation, and cannot be changed.  The effect of the default representation is to map the cube [0,1] × [0,1] × [0,1] in VRC space to the cube [0,1] × [0,1] × [0,1] in NPC space, without any scaling, rotation, or translation, and to clip the image in NPC space at the boundaries of the same unit cube.  It contains the following values:

•view orientation matrix Identity Matrix

•view mapping matrixIdentity Matrix

•view clipping limitsXmin = 0 Xmax = 1
                                                 Ymin = 0 Ymax = 1
                                                 Zmin = 0 Zmax = 1

•x-y clipping indicatorPerform Clipping

•back clipping indicatorPerform Clipping

•front clipping indicatorPerform Clipping

ERRORS

003Ignoring function, function requires state (PHOP, WSOP, ∗, ∗)

054Ignoring function, the specified workstation is not open

057Ignoring function, specified workstation is of category MI

115Ignoring function, the view index value is less than one

150Ignoring function, setting this view table entry would exceed the maximum number of entries allowed in the workstation’s view table

153Ignoring function, invalid view clipping limits; XMIN ≥ XMAX, YMIN ≥ YMAX, or ZMIN > ZMAX

154Ignoring function, the view clipping limits are not within NPC range

SEE ALSO

SET VIEW INDEX (3P)
EVALUATE VIEW ORIENTATION MATRIX (3P)
EVALUATE VIEW MAPPING MATRIX (3P)
SET VIEW TRANSFORMATION INPUT PRIORITY (3P)
INQUIRE VIEW REPRESENTATION (3P)
UPDATE WORKSTATION (3P)
SET VIEW REPRESENTATION (3P)

September 02, 1992