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 a C Program 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 MESSAGE 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 FILL AREA GENERALIZED DRAWING PRIMITIVE POLYLINE POLYMARKER TEXT 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 CHARACTER EXPANSION FACTOR SET CHARACTER HEIGHT SET CHARACTER SPACING SET CHARACTER UP VECTOR SET COLOUR REPRESENTATION SET FILL AREA COLOUR INDEX SET FILL AREA INDEX SET FILL AREA INTERIOR STYLE SET FILL AREA REPRESENTATION SET FILL AREA STYLE INDEX SET LINETYPE SET LINEWIDTH SCALE FACTOR SET MARKER SIZE SCALE FACTOR SET MARKER TYPE SET PATTERN REFERENCE POINT 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 Workstation Transformations 7.3 Relative Positioning and Shape 7.4 Transformation Inquiries 7.5 Function Descriptions ACCUMULATE TRANSFORMATION MATRIX EVALUATE TRANSFORMATION MATRIX SELECT NORMALIZATION TRANSFORMATION SET CLIPPING INDICATOR SET VIEWPORT SET VIEWPORT INPUT PRIORITY SET WINDOW SET WORKSTATION VIEWPORT SET WORKSTATION WINDOW 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 RENAME SEGMENT SET DETECTABILITY SET HIGHLIGHTING SET SEGMENT PRIORITY SET SEGMENT TRANSFORMATION 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 PICK GET STRING GET STROKE GET VALUATOR INITIALIZE CHOICE INITIALIZE LOCATOR INITIALIZE PICK INITIALIZE STRING INITIALIZE STROKE INITIALIZE VALUATOR REQUEST CHOICE REQUEST LOCATOR REQUEST PICK REQUEST STRING REQUEST STROKE REQUEST VALUATOR SAMPLE CHOICE SAMPLE LOCATOR SAMPLE PICK SAMPLE STRING SAMPLE STROKE SAMPLE VALUATOR SET CHOICE MODE SET LOCATOR MODE SET PICK MODE SET STRING MODE SET STROKE MODE SET VALUATOR MODE SIZEOF 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 CHOICE DEVICE STATE INQUIRE CLIPPING INQUIRE COLOUR FACILITIES INQUIRE COLOUR REPRESENTATION INQUIRE CURRENT INDIVIDUAL ATTRIBUTE VALUES INQUIRE CURRENT NORMALIZATION TRANSFORMATION NUMBER INQUIRE CURRENT PICK IDENTIFIER VALUE INQUIRE CURRENT PRIMITIVE ATTRIBUTE VALUES INQUIRE DEFAULT CHOICE DEVICE DATA INQUIRE DEFAULT DEFERRAL STATE VALUES INQUIRE DEFAULT LOCATOR DEVICE DATA INQUIRE DEFAULT PICK DEVICE DATA INQUIRE DEFAULT STRING DEVICE DATA INQUIRE DEFAULT STROKE DEVICE DATA INQUIRE DEFAULT VALUATOR DEVICE DATA INQUIRE DISPLAY SPACE SIZE INQUIRE DYNAMIC MODIFICATION OF SEGMENT ATTRIBUTES INQUIRE DYNAMIC MODIFICATION OF WORKSTATION ATTRIBUTES INQUIRE FILL AREA FACILITIES INQUIRE FILL AREA REPRESENTATION INQUIRE GENERALIZED DRAWING PRIMITIVE INQUIRE INPUT QUEUE OVERFLOW INQUIRE LEVEL OF GKS INQUIRE LIST OF AVAILABLE GENERALIZED DRAWING PRIMITIVES INQUIRE LIST OF AVAILABLE WORKSTATION TYPES INQUIRE LIST OF COLOUR 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 LOCATOR DEVICE STATE INQUIRE MAXIMUM LENGTH OF WORKSTATION STATE TABLES INQUIRE MAXIMUM NORMALIZATION TRANSFORMATION INQUIRE MORE SIMULTANEOUS EVENTS INQUIRE NAME OF OPEN SEGMENT INQUIRE NORMALIZATION TRANSFORMATION INQUIRE NUMBER OF AVAILABLE LOGICAL INPUT DEVICES INQUIRE NUMBER OF SEGMENT PRIORITIES SUPPORTED INQUIRE OPERATING STATE VALUE INQUIRE PATTERN FACILITIES INQUIRE PATTERN REPRESENTATION INQUIRE PICK DEVICE STATE INQUIRE PIXEL INQUIRE PIXEL ARRAY INQUIRE PIXEL ARRAY DIMENSIONS INQUIRE POLYLINE FACILITIES INQUIRE POLYLINE REPRESENTATION INQUIRE POLYMARKER FACILITIES INQUIRE POLYMARKER REPRESENTATION INQUIRE PREDEFINED COLOUR REPRESENTATION INQUIRE PREDEFINED FILL AREA REPRESENTATION INQUIRE PREDEFINED PATTERN REPRESENTATION INQUIRE PREDEFINED POLYLINE REPRESENTATION INQUIRE PREDEFINED POLYMARKER REPRESENTATION INQUIRE PREDEFINED TEXT REPRESENTATION INQUIRE SEGMENT ATTRIBUTES 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 STROKE DEVICE STATE INQUIRE TEXT EXTENT INQUIRE TEXT FACILITIES INQUIRE TEXT REPRESENTATION INQUIRE VALUATOR DEVICE STATE 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 12 Error-Handling Functions 12.1 Function Descriptions EMERGENCY CLOSE GKS ERROR HANDLING ERROR LOGGING SET ERROR HANDLER 12.2 Program Examples 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 Implementation-Specific Errors A.13 Fatal Errors B Constants C Program Example D Language-Specific Programming Information D.1 Passing Arguments by Descriptor D.2 Programming in BASIC D.3 Programming in VAX C D.4 Programming in VAX COBOL D.5 Programming in VAX Pascal 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 Segment Attributes E.6 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 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 Output 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 D-1 Macro Subroutine Used to Build Array Descriptors D-2 A Sample COBOL Program Using the Subroutine BUILDESC 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 Clipping Rectangle 7-2 The Entire DEC GKS Transformation Process 7-3 Relative Position and Aspect Ratio 7-4 First Transformation Component of ACCUMULATE TRANSFORMATION MATRIX 7-5 Fourth Transformation Component of ACCUMULATE TRANSFORMATION MATRIX 7-6 Output Prior to Segment Transformation 7-7 Effect of Segment Transformation 7-8 SET CLIPPING INDICATOR with Clipping Enabled 7-9 SET CLIPPING INDICATOR with Clipping Disabled 7-10 Output Using Default Normalization Transformation 7-11 Output After Changes to the Workstation Viewport 8-1 Output with Two Segments 8-2 Output with Associated Segment 8-3 Output of the Original and Inserted Segments 8-4 Output of the Redrawn Segments 8-5 Output Prior to Highlighting 8-6 Effects of SET HIGHLIGHTING 9-1 Visual Interfaces for Logical Input Classes 9-2 Input Prompt Near the Top of the Screen 9-3 Picking the Correct Triangle 9-4 Requesting Input from a String-Class Logical Input Device in Request Mode 9-5 Workstation Surface after Activating a Valuator-Class Logical Input Device in Sample Mode TABLES 2-1 General Logical Names for DEC GKS 3-1 General Environment Variables for DEC GKS 4-1 Workstation Categories 6-1 Geometric and Nongeometric Attributes 8-1 Surface Regeneration from Changes to Segments 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 Implementation-Specific Errors A-13 Fatal Errors B-1 GKS$ Constants C-1 Binding-Specific Code Examples F-1 Global Differences