NAME

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

SYNOPSIS

C Syntax

void
pset_ws_vp ( ws, viewport )
Pintws;workstation id
Plimit∗viewport;workstation viewport limits

Required PHIGS Operating States

(PHOP, WSOP, ∗, ∗)

DESCRIPTION

Purpose

SET WORKSTATION VIEWPORT defines a 2D area in Device Coordinate (DC) space, at a constant z value.  The abstract image within the workstation window, defined in Normalized Projection Coordinate (NPC) space, is mapped to this viewport. 

Together, the workstation window and the workstation viewport define the workstation transformation that converts the image from NPC to DC of workstation’s physical display surface.  The workstation window defines what within NPC space is 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 DC limits for the 2D workstation viewport, defined as follows:

typedef struct  {
Pfloatx_min;/∗ x minimum ∗/
Pfloatx_max;/∗ x maximum ∗/
Pfloaty_min;/∗ y minimum ∗/
Pfloaty_max;/∗ y maximum ∗/
} Plimit;

Execution

The current workstation viewport defines the area in Device Coordinates in which the abstract image within the current workstation window is displayed.  The workstation window is defined in Normalized Projection Coordinates.  Together, the workstation window and the workstation viewport define the 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 and y minimum must be non-negative and less than y 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 sets the x and y components of the requested workstation viewport in the specified workstation’s state list to the values specified.  The z component of the requested workstation viewport and current workstation viewport are not changed.  The effect of calling SET WORKSTATION VIEWPORT 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 preserves the proportions of the image by mapping the workstation window to the largest possible area of 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 is mapped to the lower left hand corner of the 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 plane, [0,1] × [0,1] × [0,1], onto the largest square area in the workstation display space including the display’s lower left corner. 

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 or YMIN ≥ YMAX. 

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

SEE ALSO

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

September 02, 1992