SET VIEW REPRESENTATION 3(3P) — SUNPHIGS LIBRARY

NAME

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

SYNOPSIS

C Syntax

void
psetviewrep3 ( ws, index, rep )
Pintws;workstation id
Pintindex;view index
Pviewrep3∗rep;view representation

FORTRAN Syntax

SUBROUTINE psvwr3 ( WKID, VIEWI, VWORMT, VWMPMT, VWCPLM, XYCLPI, BCLIPI, FCLIPI )
INTEGERWKIDworkstation identifier
INTEGERVIEWIview index
REALVWORMT(4, 4)view orientation matrix
REALVWMPMT(4, 4)view mapping matrix
REALVWCPLM(6)view clipping limits (NPC)
INTEGERXYCLPIx-y clipping indicator (PNCLIP, PCLIP)
INTEGERBCLIPIback clipping indicator (PNCLIP, PCLIP)
INTEGERFCLIPIfront clipping indicator (PNCLIP, PCLIP)

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 {
Pmatrix3orientation_matrix;/∗ orientation matrix ∗/
Pmatrix3mapping_matrix;/∗ mapping matrix ∗/
Plimit3clip_limit;/∗ clipping limits ∗/
Pclipclip_xy;/∗ x - y clipping indicator ∗/
Pclipclip_back;/∗ back clipping indicator ∗/
Pclipclip_front;/∗ front clipping indicator ∗/
} Pviewrep3;

rep->orientation_matrix is the 4 × 4 homogeneous view orientation matrix, probably from EVALUATE VIEW ORIENTATION MATRIX 3.

rep->mapping_matrix is the 4 × 4 homogeneous view mapping matrix, probably from EVALUATE VIEW MAPPING MATRIX 3.

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

rep->clip_xy contains the x-y clip indicator for the x and y axes.

rep->clip_back contains the back clipping indicator, which controls clipping against the “yon” plane.

rep->clip_front contains the front clipping indicator, which controls clipping against the “fore” plane.

Valid clipping indicators are one of the enumeration values:

Clip IndicatorMeaning
PCLIP“Perform Clipping”
PNOCLIP“Do not Clip”

FORTRAN Input Parameters

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

VIEWI
The view index of the entry being defined.

VWORMT
An array containing the 4 × 4 homogeneous view orientation matrix, probably from EVALUATE VIEW ORIENTATION MATRIX 3.

VWMPMT
An array containing the 4 × 4 homogeneous view mapping matrix, probably from EVALUATE VIEW MAPPING MATRIX 3.

VWCPLM
An array containing the 6 REAL clipping limits: Xmin, Xmax, Ymin, Ymax, Zmin, and Zmax.

XYCLPI
The x-y clip indicator for the x and y axes.

BCLIPI
The back clipping indicator, which controls clipping against the “yon” plane.

FCLIPI
The front clipping indicator, which controls clipping against the “fore” plane.

Valid clipping indicators are one of the enumeration values:

Clip IndicatorMeaning
PNCLIP“Do not Clip”
PCLIP“Perform Clipping”

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 World Coordinate space to Normalized Projection Coordinate 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 Space to World Coordinate 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 World Coordinates. The view reference point becomes the origin of VRC; the view plane normal and the view up vector orient the View Reference Coordinate Space (VRC u and v axes) in relation to the World Coordinate axes.

2.The view mapping matrix is applied to map the View Reference Coordinate System to the Normalized Projection Coordinate system. Use the utility function EVALUATE VIEW MAPPING MATRIX 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 Perform 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. 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 (i.e., 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 entries 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] x [0,1] x [-1,0] in VRC space to the cube [0,1] x [0,1] x [-1,0] 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 matrix:     identity matrix
view clipping limits:    Xmin = 0 Xmax = 1
                          Ymin = 0 Ymax = 1
                          Zmin = 0 Zmax = 1
x-y clipping indicator:“Perform Clipping”
back clipping indicator: “Perform Clipping”
front clipping indicator: “Perform 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

Museum