CONTENTS Title Page Copyright Page Preface 1 Introduction to DEC GKS 1.1 GKS Function Categories 1.2 GKS Levels 1.3 Function Presentation Format 1.3.1 Function Header 1.3.2 Function Operating States 1.3.3 Function Syntax 1.3.4 Constants 1.3.5 Function Description 1.3.6 See Also Section 2 VMS Programming Considerations 2.1 Including Definition Files 2.2 Compiling, Linking, and Running Your Programs 2.3 Opening a Workstation 2.3.1 Specifying the Connection Identifier 2.3.2 Specifying the Workstation Type 2.4 DEC GKS Logical Names 2.5 Defining Logical Names 2.6 Types of Logical Names 2.6.1 General Logical Names 2.7 Error Handling 2.7.1 Error Codes 2.7.2 Error Files 3 ULTRIX Programming Considerations 3.1 Including Definition Files 3.2 Compiling, Linking, and Running Your Programs 3.2.1 Linking DEC FORTRAN Programs on ULTRIX Systems with RISC Processors 3.2.2 Linking FORTRAN Programs on ULTRIX Systems with RISC Processors 3.3 Opening a Workstation 3.3.1 Specifying the Connection Identifier 3.3.2 Specifying the Workstation Type 3.4 DEC GKS Environment Variables 3.5 Defining Environment Variables 3.6 The Default Environment Variable File 3.7 Environment Variable Types 3.7.1 General Environment Variables 3.8 Error Handling 3.8.1 Error Codes 3.8.2 Error Files 3.9 Configuration Files 3.9.1 Customizing the Configuration File at System Level 3.9.2 Customizing the Configuration File at User Level 4 Control Functions 4.1 The Kernel, Graphics Handlers, and Description Tables 4.1.1 Workstations 4.1.2 Operating States and State Lists 4.2 Controlling the Workstation Display Surface 4.2.1 Output Deferral 4.2.2 Implicit Surface Regenerations 4.2.3 Workstation Surface State List Entries 4.3 Control Inquiries 4.4 Function Descriptions ACTIVATE WORKSTATION CLEAR WORKSTATION CLOSE GKS CLOSE WORKSTATION DEACTIVATE WORKSTATION ESCAPE 4.4.1 FORTRAN Escapes MESSAGE MESSAGE (FORTRAN-77 Subset) OPEN GKS OPEN WORKSTATION REDRAW ALL SEGMENTS ON WORKSTATION SET DEFERRAL STATE UPDATE WORKSTATION 4.5 Program Examples 5 Output Functions 5.1 Output and the DEC GKS Operating State 5.2 Output Attributes 5.3 Transformations and the DEC GKS Coordinate Systems 5.4 Output Deferral 5.5 Output Inquiries 5.6 Function Descriptions CELL ARRAY CELL ARRAY 3 FILL AREA FILL AREA 3 FILL AREA SET FILL AREA SET 3 GENERALIZED DRAWING PRIMITIVE GENERALIZED DRAWING PRIMITIVE 3 POLYLINE POLYLINE 3 POLYMARKER POLYMARKER 3 TEXT TEXT (FORTRAN-77 Subset) TEXT 3 TEXT 3 (FORTRAN-77 Subset) 5.7 Program Examples 6 Attribute Functions 6.1 Types of Attributes 6.2 Individual and Bundled Attribute Values 6.2.1 Aspect Source Flags (ASFs) 6.2.2 Dynamic Changes and Implicit Regeneration 6.3 Foreground and Background Colors 6.4 Attribute Inquiries 6.5 Function Descriptions SET ASPECT SOURCE FLAGS SET ASPECT SOURCE FLAGS 3 SET CHARACTER EXPANSION FACTOR SET CHARACTER HEIGHT SET CHARACTER SPACING SET CHARACTER UP VECTOR SET COLOUR MODEL SET COLOUR REPRESENTATION SET EDGE COLOUR INDEX SET EDGE FLAG SET EDGE INDEX SET EDGE REPRESENTATION SET EDGETYPE SET EDGEWIDTH SCALE FACTOR SET FILL AREA COLOUR INDEX SET FILL AREA INDEX SET FILL AREA INTERIOR STYLE SET FILL AREA REPRESENTATION SET FILL AREA STYLE INDEX SET HLHSR IDENTIFIER SET HLHSR MODE SET LINETYPE SET LINEWIDTH SCALE FACTOR SET MARKER SIZE SCALE FACTOR SET MARKER TYPE SET PATTERN REFERENCE POINT SET PATTERN REFERENCE POINT AND VECTORS SET PATTERN REPRESENTATION SET PATTERN SIZE SET PICK IDENTIFIER SET POLYLINE COLOUR INDEX SET POLYLINE INDEX SET POLYLINE REPRESENTATION SET POLYMARKER COLOUR INDEX SET POLYMARKER INDEX SET POLYMARKER REPRESENTATION SET TEXT ALIGNMENT SET TEXT COLOUR INDEX SET TEXT FONT AND PRECISION SET TEXT INDEX SET TEXT PATH SET TEXT REPRESENTATION 6.6 Program Examples 7 Transformation Functions 7.1 World Coordinates and Normalization Transformations 7.1.1 The Normalized Device Coordinate System 7.1.2 Overlapping Viewports 7.2 View Transformations 7.3 Device Transformations 7.4 Transformation Inquiries 7.5 Function Descriptions ACCUMULATE TRANSFORMATION MATRIX ACCUMULATE TRANSFORMATION MATRIX 3 EVALUATE TRANSFORMATION MATRIX EVALUATE TRANSFORMATION MATRIX 3 EVALUATE VIEW MAPPING MATRIX 3 EVALUATE VIEW ORIENTATION MATRIX 3 SELECT NORMALIZATION TRANSFORMATION SET CLIPPING INDICATOR SET VIEW INDEX SET VIEW REPRESENTATION 3 SET VIEW TRANSFORMATION INPUT PRIORITY SET VIEWPORT SET VIEWPORT 3 SET VIEWPORT INPUT PRIORITY SET WINDOW SET WINDOW 3 SET WORKSTATION VIEWPORT SET WORKSTATION VIEWPORT 3 SET WORKSTATION WINDOW SET WORKSTATION WINDOW 3 7.6 Program Examples 8 Segment Functions 8.1 Creating, Using, and Deleting Segments 8.1.1 Pick Identification 8.2 Workstations and Segment Storage 8.3 Segments and Surface Update 8.4 Segment Attributes 8.4.1 Detectability 8.4.2 Highlighting 8.4.3 Priority 8.4.4 Transformation 8.4.4.1 Normalization and Segment Transformations, and Clipping 8.4.5 Visibility 8.5 Segment Inquiries 8.6 Function Descriptions ASSOCIATE SEGMENT WITH WORKSTATION CLOSE SEGMENT COPY SEGMENT TO WORKSTATION CREATE SEGMENT DELETE SEGMENT DELETE SEGMENT FROM WORKSTATION INSERT SEGMENT INSERT SEGMENT 3 RENAME SEGMENT SET DETECTABILITY SET HIGHLIGHTING SET SEGMENT PRIORITY SET SEGMENT TRANSFORMATION SET SEGMENT TRANSFORMATION 3 SET VISIBILITY 8.7 Program Examples 9 Input Functions 9.1 Physical Input Devices 9.2 Logical Input Devices 9.2.1 Identifying a Logical Input Device 9.2.2 Controlling the Appearance of the Logical Input Device 9.2.3 Activating and Deactivating a Logical Input Device 9.2.4 Initializing a Logical Input Device 9.2.5 Obtaining Measures from a Logical Input Device 9.2.6 The Input Class 9.3 Prompt and Echo Types 9.3.1 DEC GKS Prompt and Echo Types 9.3.1.1 Choice-Class Prompt and Echo Types 9.3.1.2 Locator-Class Prompt and Echo Types 9.3.1.3 Pick-Class Prompt and Echo Types 9.3.1.4 String-Class Prompt and Echo Type 9.3.1.5 Stroke-Class Prompt and Echo Types 9.3.1.6 Valuator-Class Prompt and Echo Types 9.3.2 Input Data Records 9.3.2.1 Choice Class 9.3.2.2 Locator Class 9.3.2.3 Pick Class 9.3.2.4 String Class 9.3.2.5 Stroke Class 9.3.2.6 Valuator Class 9.4 Initializing Input 9.5 Input Operating Modes 9.5.1 Request Mode 9.5.2 Sample Mode 9.5.3 Event Mode 9.5.3.1 Event Input Queue Overflow 9.6 Overlapping Viewports 9.7 Input Inquiries 9.7.1 Default and Current Input Values 9.7.2 Device-Independent Programming 9.8 Function Descriptions AWAIT EVENT FLUSH DEVICE EVENTS GET CHOICE GET LOCATOR GET LOCATOR 3 GET PICK GET STRING GET STRING (FORTRAN-77 Subset) GET STROKE GET STROKE 3 GET VALUATOR INITIALIZE CHOICE INITIALIZE CHOICE 3 INITIALIZE LOCATOR INITIALIZE LOCATOR 3 INITIALIZE PICK INITIALIZE PICK 3 INITIALIZE STRING INITIALIZE STRING (FORTRAN-77 Subset) INITIALIZE STRING 3 INITIALIZE STRING 3 (FORTRAN-77 Subset) INITIALIZE STROKE INITIALIZE STROKE 3 INITIALIZE VALUATOR INITIALIZE VALUATOR 3 PACK DATA RECORD PACK DATA RECORD (FORTRAN-77 Subset) REQUEST CHOICE REQUEST LOCATOR REQUEST LOCATOR 3 REQUEST PICK REQUEST STRING REQUEST STRING (FORTRAN-77 Subset) REQUEST STROKE REQUEST STROKE 3 REQUEST VALUATOR SAMPLE CHOICE SAMPLE LOCATOR SAMPLE LOCATOR 3 SAMPLE PICK SAMPLE STRING SAMPLE STRING (FORTRAN-77 Subset) SAMPLE STROKE SAMPLE STROKE 3 SAMPLE VALUATOR SET CHOICE MODE SET LOCATOR MODE SET PICK MODE SET STRING MODE SET STROKE MODE SET VALUATOR MODE UNPACK DATA RECORD UNPACK DATA RECORD (FORTRAN-77 Subset) 9.9 Program Examples 10 Metafile Functions 10.1 Creating a GKSM or GKS3 Metafile 10.2 Creating a CGM 10.3 Reading a GKSM or GKS3 Metafile 10.4 Metafile Inquiries 10.5 Function Descriptions GET ITEM TYPE FROM GKSM INTERPRET ITEM READ ITEM FROM GKSM WRITE ITEM TO GKSM 11 Inquiry Functions 11.1 Using the Inquiry Functions 11.1.1 The Error Status Argument 11.1.2 The Value Type Argument 11.2 Function Descriptions INQUIRE ASPECT SOURCE FLAGS INQUIRE ASPECT SOURCE FLAGS 3 INQUIRE CHARACTER BASE VECTOR INQUIRE CHARACTER EXPANSION FACTOR INQUIRE CHARACTER HEIGHT INQUIRE CHARACTER SPACING INQUIRE CHARACTER UP VECTOR INQUIRE CHARACTER WIDTH INQUIRE CHOICE DEVICE STATE INQUIRE CHOICE DEVICE STATE 3 INQUIRE CLIPPING INQUIRE CLIPPING 3 INQUIRE COLOUR FACILITIES INQUIRE COLOUR MODEL INQUIRE COLOUR MODEL FACILITIES INQUIRE COLOUR REPRESENTATION INQUIRE CURRENT EDGE COLOUR INDEX INQUIRE CURRENT EDGE FLAG INQUIRE CURRENT EDGE INDEX INQUIRE CURRENT EDGETYPE INQUIRE CURRENT EDGEWIDTH SCALE FACTOR INQUIRE CURRENT HLHSR IDENTIFIER VALUE INQUIRE CURRENT NORMALIZATION TRANSFORMATION NUMBER INQUIRE CURRENT PATTERN REFERENCE POINT AND VECTORS INQUIRE CURRENT PICK IDENTIFIER VALUE INQUIRE CURRENT VIEW INDEX INQUIRE DEFAULT CHOICE DEVICE DATA INQUIRE DEFAULT CHOICE DEVICE DATA 3 INQUIRE DEFAULT DEFERRAL STATE VALUES INQUIRE DEFAULT LOCATOR DEVICE DATA INQUIRE DEFAULT LOCATOR DEVICE DATA 3 INQUIRE DEFAULT PICK DEVICE DATA INQUIRE DEFAULT PICK DEVICE DATA 3 INQUIRE DEFAULT STRING DEVICE DATA INQUIRE DEFAULT STRING DEVICE DATA 3 INQUIRE DEFAULT STROKE DEVICE DATA INQUIRE DEFAULT STROKE DEVICE DATA 3 INQUIRE DEFAULT VALUATOR DEVICE DATA INQUIRE DEFAULT VALUATOR DEVICE DATA 3 INQUIRE DISPLAY SPACE SIZE INQUIRE DISPLAY SPACE SIZE 3 INQUIRE DYNAMIC MODIFICATION OF SEGMENT ATTRIBUTES INQUIRE DYNAMIC MODIFICATION OF WORKSTATION ATTRIBUTES INQUIRE DYNAMIC MODIFICATION OF WORKSTATION ATTRIBUTES 3 INQUIRE EDGE FACILITIES INQUIRE EDGE REPRESENTATION INQUIRE FILL AREA COLOUR INDEX INQUIRE FILL AREA FACILITIES INQUIRE FILL AREA INDEX INQUIRE FILL AREA INTERIOR STYLE INQUIRE FILL AREA REPRESENTATION INQUIRE FILL AREA STYLE INDEX INQUIRE GENERALIZED DRAWING PRIMITIVE INQUIRE GENERALIZED DRAWING PRIMITIVE 3 INQUIRE HLHSR FACILITIES INQUIRE HLHSR MODE INQUIRE INPUT QUEUE OVERFLOW INQUIRE LEVEL OF GKS INQUIRE LINETYPE INQUIRE LINEWIDTH SCALE FACTOR INQUIRE LIST OF AVAILABLE GENERALIZED DRAWING PRIMITIVES INQUIRE LIST OF AVAILABLE GENERALIZED DRAWING PRIMITIVES 3 INQUIRE LIST OF AVAILABLE WORKSTATION TYPES INQUIRE LIST OF COLOUR INDICES INQUIRE LIST OF EDGE INDICES INQUIRE LIST OF FILL AREA INDICES INQUIRE LIST OF NORMALIZATION TRANSFORMATION NUMBERS INQUIRE LIST OF PATTERN INDICES INQUIRE LIST OF POLYLINE INDICES INQUIRE LIST OF POLYMARKER INDICES INQUIRE LIST OF TEXT INDICES INQUIRE LIST OF VIEW INDICES INQUIRE LOCATOR DEVICE STATE INQUIRE LOCATOR DEVICE STATE 3 INQUIRE MARKER SIZE SCALE FACTOR INQUIRE MARKER TYPE INQUIRE MAXIMUM LENGTH OF WORKSTATION STATE TABLES INQUIRE MAXIMUM LENGTH OF WORKSTATION STATE TABLES 3 INQUIRE MAXIMUM NORMALIZATION TRANSFORMATION NUMBER INQUIRE MORE SIMULTANEOUS EVENTS INQUIRE NAME OF OPEN SEGMENT INQUIRE NORMALIZATION TRANSFORMATION INQUIRE NORMALIZATION TRANSFORMATION 3 INQUIRE NUMBER OF AVAILABLE LOGICAL INPUT DEVICES INQUIRE NUMBER OF SEGMENT PRIORITIES SUPPORTED INQUIRE OPERATING STATE VALUE INQUIRE PATTERN FACILITIES INQUIRE PATTERN REFERENCE POINT INQUIRE PATTERN REPRESENTATION INQUIRE PATTERN SIZE INQUIRE PICK DEVICE STATE INQUIRE PICK DEVICE STATE 3 INQUIRE PIXEL INQUIRE PIXEL ARRAY INQUIRE PIXEL ARRAY DIMENSIONS INQUIRE POLYLINE COLOUR INDEX INQUIRE POLYLINE FACILITIES INQUIRE POLYLINE INDEX INQUIRE POLYLINE REPRESENTATION INQUIRE POLYMARKER COLOUR INDEX INQUIRE POLYMARKER FACILITIES INQUIRE POLYMARKER INDEX INQUIRE POLYMARKER REPRESENTATION INQUIRE PREDEFINED COLOUR REPRESENTATION INQUIRE PREDEFINED EDGE REPRESENTATION INQUIRE PREDEFINED FILL AREA REPRESENTATION INQUIRE PREDEFINED PATTERN REPRESENTATION INQUIRE PREDEFINED POLYLINE REPRESENTATION INQUIRE PREDEFINED POLYMARKER REPRESENTATION INQUIRE PREDEFINED TEXT REPRESENTATION INQUIRE PREDEFINED VIEW REPRESENTATION INQUIRE SEGMENT ATTRIBUTES INQUIRE SEGMENT ATTRIBUTES 3 INQUIRE SET OF ACTIVE WORKSTATIONS INQUIRE SET OF ASSOCIATED WORKSTATIONS INQUIRE SET OF OPEN WORKSTATIONS INQUIRE SET OF SEGMENT NAMES IN USE INQUIRE SET OF SEGMENT NAMES ON WORKSTATION INQUIRE STRING DEVICE STATE INQUIRE STRING DEVICE STATE (FORTRAN-77 Subset) INQUIRE STRING DEVICE STATE 3 INQUIRE STRING DEVICE STATE 3 (FORTRAN-77 Subset) INQUIRE STROKE DEVICE STATE INQUIRE STROKE DEVICE STATE 3 INQUIRE TEXT ALIGNMENT INQUIRE TEXT COLOUR INDEX INQUIRE TEXT EXTENT INQUIRE TEXT EXTENT (FORTRAN-77 Subset) INQUIRE TEXT EXTENT 3 INQUIRE TEXT EXTENT 3 (FORTRAN-77 Subset) INQUIRE TEXT FACILITIES INQUIRE TEXT FONT AND PRECISION INQUIRE TEXT INDEX INQUIRE TEXT PATH INQUIRE TEXT REPRESENTATION INQUIRE VALUATOR DEVICE STATE INQUIRE VALUATOR DEVICE STATE 3 INQUIRE VIEW FACILITIES INQUIRE VIEW REPRESENTATION 3 INQUIRE WORKSTATION CATEGORY INQUIRE WORKSTATION CLASSIFICATION INQUIRE WORKSTATION CONNECTION AND TYPE INQUIRE WORKSTATION DEFERRAL AND UPDATE STATES INQUIRE WORKSTATION MAXIMUM NUMBERS INQUIRE WORKSTATION STATE INQUIRE WORKSTATION TRANSFORMATION INQUIRE WORKSTATION TRANSFORMATION 3 12 Error-Handling Functions 12.1 Function Descriptions EMERGENCY CLOSE GKS ERROR HANDLING ERROR LOGGING 12.2 Program Example A DEC GKS Error Messages A.1 Operating State Errors A.2 Workstation Errors A.3 Transformation Function Errors A.4 Attribute Function Errors A.5 Output Function Errors A.6 Segment Function Errors A.7 Input Function Errors A.8 Metafile Function Errors A.9 Escape Function Errors A.10 Miscellaneous Errors A.11 System Errors A.12 FORTRAN Binding Errors A.13 Implementation-Specific Errors A.14 Fatal Errors B Constants C Program Example D Function Identifiers E Initial Attribute Values E.1 Initial Polyline Attributes E.2 Initial Polymarker Attributes E.3 Initial Text Attributes E.4 Initial Fill Area Attributes E.5 Initial Fill Area Set Attributes E.6 Initial Segment Attributes E.7 Initial Normalization Transformation Settings F Differences in GKS Implementations F.1 Global Differences EXAMPLES 4-1 CLEAR WORKSTATION and the GKS Control Functions 4-2 Supported Escapes Program 4-3 VAXstation Output for Escape Program 4-4 Using the FORTRAN Escape Function 5-1 Cell Array Output 5-2 Generalized Drawing Primitive Output 6-1 SET COLOUR REPRESENTATION Function 6-2 SET FILL AREA REPRESENTATION Function 6-3 SET LINETYPE Function 6-4 SET TEXT ALIGNMENT Function 7-1 Showing the Cumulative Effect of ACCUMULATE TRANSFORMATION MATRIX 7-2 The Effects of a Segment Transformation 7-3 Controlling Clipping at the World Viewport 7-4 Establishing a Workstation Viewport 8-1 Comparing ASSOCIATE SEGMENT WITH WORKSTATION and COPY SEGMENT TO WORKSTATION 8-2 Inserting a Segment's Primitives into Another Segment 8-3 Highlighting a Segment 9-1 Using a Locator-Class Logical Input Device in Event Mode 9-2 Using a Pick-Class Logical Input Device in Sample Mode 9-3 Using a String-Class Logical Input Device in Request Mode 9-4 Using a Valuator-Class Logical Input Device in Sample Mode 12-1 Creating an Error Handler FIGURES 1-1 DEC GKS Output Primitives 1-2 Functionality by GKS Levels 4-1 CLEAR WORKSTATION and the GKS Control Functions 5-1 Cell Array Output 5-2 Generalized Drawing Primitive Output 6-1 SET COLOUR REPRESENTATION Output 6-2 SET FILL AREA REPRESENTATION Output 6-3 SET LINETYPE Output 6-4 SET TEXT ALIGNMENT Output 7-1 The DEC GKS Two-Dimensional Transformation Pipeline 7-2 The DEC In ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ r