OPEN WORKSTATION(3P) — SUNPHIGS LIBRARY

NAME

OPEN WORKSTATION − open a workstation

SYNOPSIS

C Syntax

void
popenws ( wsid, conn_id, ws_type )
Pintwsid;workstation identifier
Pconnidconn_id;connection identifier
Pwstypews_type;workstation type

FORTRAN Syntax

SUBROUTINE popwk ( WKID, CONID, WTYPE )
INTEGERWKIDworkstation identifier
INTEGERCONIDconnection identifier
INTEGERWTYPEworkstation type

Required PHIGS Operating States

(PHOP, ∗, ∗, ∗)

DESCRIPTION

Purpose

OPEN WORKSTATION opens a workstation of the specified workstation type. The workstation state list is initialized to conform as nearly as possible to the workstation type’s workstation description table.

SunPHIGS supports three workstation types, Sun Tool, Sun Canvas, and CGM Output. Their characteristics are described below. Sun Tool and Sun Canvas types cannot be used simultaneously; the decision of which one to use must be made when the application is linked.

If the workstation is opened successfully, a new, specific workstation type is created and associated with the open workstation. This new type contains the actual workstation description table of the workstation, with all fields indicating the actual capabilities of the workstation. This specific type can be retrieved with INQUIRE WORKSTATION CONNECTION AND TYPE.

The workstation state variable is set to WSOP.

C Input Parameters

wsidThe workstation identifier to be associated with this workstation. This value is used to identify the workstation in subsequent PHIGS function calls.

conn_id
The connection identifier of the workstation. The type of value to use depends on the workstation type:

Sun Tool
The connection id is not used.

Sun Canvas
The connection id is a valid SunView Canvas handle of an open canvas.

CGM Output
The connection id is a file name. The file should not be open and the application should not attempt to access the file while the workstation is open. The CGM will be incomplete until the workstation is closed, at which time the file will also be closed.

ws_type
The type of workstation to open. Recognized types are described fully in the Available Workstation Types section below. They are declared in phigs.h. A short summary is listed here:

phigs_ws_type_sun_tool
A Sun Tool workstation type, which is a new SunView Frame with subwindows.

phigs_ws_type_sun_canvas
A Sun Canvas workstation type: For use by SunView applications. A SunView Canvas is created by the SunView application and passed to PHIGS as the connection identifier.

phigs_ws_type_cgm_out
A CGM Output workstation type. PHIGS creates a CGM file, with the name given by the connection identifier, and writes attributes and projected and clipped output primitives.

FORTRAN Input Parameters

WKIDThe workstation identifier to be associated with this workstation. This value is used to identify the workstation in subsequent PHIGS function calls.

CONID
The connection identifier of the workstation. The type of value to use depends on the workstation type:

Sun Tool
The connection id is not used.

Sun Canvas
The connection id is a valid and open SunView Canvas handle.

CGM Output
The logical unit number (LUN) of the file to create. This LUN must either be associated with an opened and named file or not be assoicated with any file. (It cannot be the LUN associated with standard output for instance.) If the LUN is associated with an open and named file, PHIGS will first close the file and then reopen it if the call to OPEN WORKSTATION is successful. If the logical unit number is not associated with an open file, OPEN WORKSTATION will create a file named fort.lun, where lun is the specified logical unit number.

Neither the application nor the operator should attempt to interact with this logical unit number while the workstation is open. The file is closed when the workstation is closed. The CGM will be incomplete until the workstation is closed.

WTYPE
The type of workstation to open. Recognized types are described fully in the Available Workstation Types section below. They are defined in phigs77.h, which must be included by a SunPHIGS FORTRAN program. A short summary is listed here:

phigswsttool
A Sun Tool workstation type: A new SunView Frame with subwindows. No connection identifier is used.

phigswstcanvas
A Sun Canvas workstation type: For use by SunView applications. A SunView Canvas is created by the SunView application and passed to PHIGS as the connection identifier.

phigswstcgmout
A CGM Output workstation type. PHIGS creates a CGM file and writes attributes and projected and clipped output primitives.

Execution

OPEN WORKSTATION opens a workstation of the specified type and associates it with the specified workstation identifier.

When a SunPHIGS application opens a workstation, SunPHIGS creates a copy of the workstation type used and binds it to the opened workstation. This copy is called the specific workstation type. The description table values of this specific type are checked for validity with respect to the device’s capabilities. If the values cannot be realized on the device SunPHIGS is using, SunPHIGS will change the description table values of this specific type to the realized values. For example, if 32 colors are requested for a monochrome frame buffer, SunPHIGS will adjust the description table accordingly. The workstation type used in the call to OPEN WORKSTATION is not modified, only the specific workstation type is (possibly) modified. This specific type is the one returned from INQUIRE WORKSTATION CONNECTION AND TYPE.

Many of a workstation type’s workstation description table values can be changed prior to opening a workstation of that type. See WORKSTATION TYPE CREATE and WORKSTATION TYPE SET for more information.

Available Workstation Types

Sun Tool

The default category of this workstation type is OUTIN but can be changed to OUTPUT using WORKSTATION TYPE SET. The connection id is not used.

Sun Tool workstations appear as a SunView frame with three subwindows: a graphics window, an optional message window and a VALUATOR device window. All output primitives are displayed in the graphics window. Messages from the MESSAGE function appear in the message window. This message window is also used as the STRING device for workstations of category OUTIN. The valuator window contains the workstation’s VALUATOR devices, and is only visible if a VALUATOR device is active. See INITIALIZE VALUATOR for more information.

Many of the characteristics of Sun Tool and Sun Canvas workstations can be set prior to opening them. Some of these modifiable characteristics are size and location, color table size, window label and icon, and device space limits, which can specify non-square workstation aspect ratios. See WORKSTATION TYPE CREATE and WORKSTATION TYPE SET for a list of the modifiable attributes and their default values.

Sun Canvas

The default category of this workstation type is OUTIN but can be changed to OUTPUT using WORKSTATION TYPE SET. The connection id is a valid SunView Canvas handle.

Sun Canvas workstations are similar to Sun Tool workstations, but rather than creating a new frame, SunPHIGS uses an application-created SunView canvas. The application creates a frame with a canvas and passes the canvas to OPEN WORKSTATION.

Sun Canvas workstations can only be used by SunView applications. See the SunView Programmer’s Guide for more information.

Sun Canvas workstation types do not support REQUEST mode input; they do, however support SunView style event notification input. See ESCAPE to see how to register an input event call-back function for PHIGS input events.

Many of the characteristics of Sun Canvas and Sun Tool workstations can be set prior to opening them. Some of these modifiable characteristics are color table size, workstation category, and device space limits, which can specify non-square workstation aspect ratios. See WORKSTATION TYPE CREATE and WORKSTATION TYPE SET for a list of the modifiable attributes and their default values.

CGM Output

A Computer Graphics Metafile conforming to the CGM Standard ANSI X3.122-1986. The category of this workstation type is OUTPUT. The connection id is the file identification of the CGM file to create.

SunPHIGS creates the CGM file and writes the metafile header and descriptor when the workstation is opened. Graphical CGM elements (primitives and attributes) are generated when PHIGS performs a traversal of the structures posted to the CGM workstation. The default deferral state for CGM output workstation types is WAIT, NIVE; therefore, traversal is deferred until the application explicitly initiates a traversal (such as by REDRAW ALL STRUCTURES). A new CGM picture element is generated for each PHIGS traversal. BEGIN PICTURE is written at the start of each traversal and END PICTURE is written when each traversal ends.

The default device space for SunPHIGS CGM workstations is [0,1] in all dimensions. The addressable units of the CGM device are [0, 32767] in the x and y dimensions and 0 in the z dimension. Consequently all SunPHIGS primitives are clipped in 3D and projected to two dimensions prior to writing them to the CGM file. (CGM is a 2D Standard.) Only integer CGM coordinate values are generated and no hidden line or hidden surface removal is applied.

SunPHIGS TEXT elements are written to the CGM as CGM polyline or polygon elements. These elements are the result of rotating the text to the specified text plane, applying the attributes and rendering the text, with clipping; i.e., the text is written to the CGM as it would appear on a Sun Canvas or Sun Tool workstation.

C binding users specify a file name as the connection identifier, FORTRAN users specify an logical unit number (LUN). When a SunPHIGS CGM workstation is opened, the specified file is truncated if it exists or created if it does not.

The default encoding for the CGM file is binary. This, as well as other characteristics of the workstation, can be changed with WORKSTATION TYPE CREATE and WORKSTATION TYPE SET. See the manual pages for these function for a list of the modifiable attributes and their default values.

ERRORS

002Ignoring function, function requires state (PHOP, ∗, ∗, ∗)

053Ignoring function, workstation identifier already is in use

050Ignoring function, connection identifier not recognized by the implementation

052Ignoring function, workstation type not recognized by the implementation

055Ignoring function, workstation cannot be opened for an implementation dependent reason

063Ignoring function, opening this workstation would exceed the maximum number of simultaneously open workstations

Museum