NAME

SET WORKSTATION VIEWPORT 3 − set 3D viewport limits for a specified workstation

SYNOPSIS

C Syntax

void
pset_ws_vp3 ( ws, viewport )
Pintws;workstation id
Plimit3∗viewport;workstation viewport limits

Required PHIGS Operating States

(PHOP, WSOP, ∗, ∗)

DESCRIPTION

Purpose

SET WORKSTATION VIEWPORT 3 defines a 3D volume in Device Coordinate (DC) space.  The abstract image within the workstation window, defined in Normalized Projection Coordinate (NPC) space, will be mapped to this viewport. 

Together, the workstation window and the workstation viewport define the workstation transformation that converts the image from NPC to DC on the workstation’s physical display surface.  The workstation window defines what within NPC space will be displayed;  the workstation viewport defines where the image is displayed in DC space. 

Control of the workstation transformation allows you to choose a portion of the abstract image composed in NPC space for display on the workstation, without changing the definition of the image in NPC space. 

C Input Parameters

wsThe identifier of the workstation for which the viewport is to be set. 

viewport
A pointer to a structure containing the six DC workstation viewport limits, defined as follows:

typedef struct  {
Pfloatx_min;/∗ x minimum ∗/
Pfloatx_max;/∗ x maximum ∗/
Pfloaty_min;/∗ y minimum ∗/
Pfloaty_max;/∗ y maximum ∗/
Pfloatz_min;/∗ z minimum ∗/
Pfloatz_max;/∗ z maximum ∗/
} Plimit3;

Execution

The current workstation viewport defines the volume in Device Coordinates in which the abstract image within the current workstation window is displayed.  The workstation window is defined in Normalized Projection Coordinates.  Used together, the workstation window and the workstation viewport define an isotropic workstation transformation that converts the image from NPC to DC of workstation’s physical display surface. 

 The x minimum must be non-negative and less than x maximum, the y minimum must be non-negative and less than y maximum, and the z minimum must be non-negative and less than z maximum.  In addition, all values must be within the workstation’s DC range.  The default PEX-SI workstation DC maximum is 1, but it is selectable by using WORKSTATION TYPE SET (3P). 

SET WORKSTATION VIEWPORT 3 sets the requested workstation viewport in the specified workstation’s state list to the values specified in viewport.  The effect of calling SET WORKSTATION VIEWPORT 3 is visible only after the requested workstation viewport replaces the current workstation viewport.  The time at which this occurs depends on the workstation’s display update state.  This action is performed immediately, and the workstation transformation update state is set to NOTPENDING, if any one of the following is true:

•The workstation’s display update state allows update. 

•The workstation’s modification mode is any value other than No Immediate Visual Effect, and the dynamic modification accepted for workstation transformation entry in the workstation description table is set to IMMEDIATE. 

•The display space empty status in the workstation state list is EMPTY. 

Otherwise, the workstation transformation update state is set to PENDING, and the requested workstation viewport will not replace the current workstation viewport until the next time the workstation is updated.  The workstation transformation update state will be set to NOTPENDING at that time. 

If the current workstation window and viewport do not have the same aspect ratios, the workstation transformation will preserve the proportions of the image by mapping the workstation window to the largest parallelopiped within the workstation viewport so that:

•The aspect ratio of the window in x and y is maintained. 

•The lower left hand corner of the window closest to 0 is mapped to the lower left hand corner of the viewport furthest from the observer. 

•The z extent of the workstation window is mapped to the entire z extent of the workstation viewport. 

If the aspect ratios of the workstation window and viewport are different, there will be unused space along the upper or right-hand edges of the viewport, but not both. 

The default workstation transformation maps the entire NPC view volume, [0,1] × [0,1] × [0,1], onto the largest parallelopiped in the workstation display space including the display’s lower left corner furthest from the observer. 

ERRORS

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

054Ignoring function, the specified workstation is not open

057Ignoring function, specified workstation is of category MI

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

157Ignoring function, the workstation viewport is not within display space

SEE ALSO

SET WORKSTATION WINDOW 3 (3P)
SET WORKSTATION VIEWPORT (3P)

September 02, 1992