SET WORKSTATION VIEWPORT(3P) — SUNPHIGS LIBRARY

NAME

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

SYNOPSIS

C Syntax

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

FORTRAN Syntax

SUBROUTINE pswkv ( WKID, XMIN, XMAX, YMIN, YMAX )
INTEGERWKIDworkstation identifier
REALXMIN, XMAX, YMIN, YMAX workstation viewport limits (DC)

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, 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 of workstation’s physical display surface. The workstation window defines what within NPC space will be displayed; the workstation viewport defines where the image will be 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 {
Pfloatxmin;/∗ x minimum ∗/
Pfloatxmax;/∗ x maximum ∗/
Pfloatymin;/∗ y minimum ∗/
Pfloatymax;/∗ y maximum ∗/
} Plimit;

FORTRAN Input Parameters

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

XMINThe x minimum value in DC for the 2D workstation viewport.

XMAX
The x maximum value in DC for the 2D workstation viewport.

YMINThe y minimum value in DC for the 2D workstation viewport.

YMAX
The y maximum value in DC for the 2D workstation viewport.

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 range for each viewport limit is [0,1]; in addition, x minimum must be less than x maximum, and y minimum must be less than y maximum.

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:

1.
The workstation’s ‘display update state’ allows update.

2.
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”.

3.
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 possible area of the workstation viewport such that

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

•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] x [0,1] x [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, YMIN ≥ YMAX, or ZMIN > ZMAX

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

Museum