FIR DIGITAL 0 RESEARCH GEM TM Programmer's Guide Volume 1: VDI COPYRIGHT Copyright (9) 1985 Digital. Research Inc. All rights reserved. No part of this publication may be reproduced, transmitted, transcribed, stored in a retrieval system, or translated into any language or computer Language, in any form or by any means, electronic, mechanical, magnetic, optical, chemical, manual or otherwise, without the prior written permission of Digital Research Inc., 60 Garden Court, P.O. Box DRI, Monterey, California 93942. DISCLAIMER DIGITAL RESEARCH INC. MAKES NO REPRESENTATIONS OR WARRANTIES WITH RESPECT TO THE CONTENTS HEREOF AND SPECIFICALLY DISCLAIMS ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE. Further, Digital Research Inc. reserves the right to revise this publication and to make changes from time to time in the content hereof without ob.Ligation of Digital Research Inc. to notify any person of such revision or changes. NOTICE TO USER From time to time changes are made in the f ilenames and in the files actually included on thedistribution disk. This manual should not be construed as a representation or warranty that such files or facilities exist on the distribution disk or as part of the materials and programs distributed. Most distribution disks include a "README.DOC" file. This file explains variations from the manual which do constitute modification of the manual and the items included therewith. Be sure to read this file before using the software. TRADEMARKS Digital Research and its logo are registered trademarks of Digital Research Inc. Concurrent, GEM, GEM Desktop, GEM Draw, Graphics Environment Manager, and GSX are trademarks of Digital Research Inc. We Make Computers Work is a service mark of Digital Research Inc. IBM is a registered trademark of International Business Machines. Intel is a registered trademark of Intel Corporation. Motorola is a registered trademark of Motorola Inc. Polaroid is a registered trademark of Polaroid Corporation. The GEM" Programmer's Guide, Volume 1: VDI wa5 printed in the United States of America. First. Edition: April 1985 Foreword OBJECTIVE This guide describes the features and operation of the Graphics Environment Manager- (GEM" ) Virtual Device Interface (VDI), the successor to the Digital Researche Graphics System Extension (GSX- ). You can write graphics applications using GEM VDI capabilities. AUDIENCE This guide is intended for microcomputer application programmers with operating system and graphics programming experience. ORGANIZATION This guide contains nine sections, nine appendixes, a glossary, and an index. The detachable reference card at the end of this guide lists the GEM VDI functions by opcode number and gives their respective C binding procedure names. It also lists the section of this guide in which each function is discussed. Section 1 introduces GEM VDI. It describes the GEM VDI architecture, including the Graphics Device operating System (GDOS) and the device drivers. Section 2 describes GEM VDI operating procedures and how to integrate application programs with GEM VDI. Section 3 describes the control functions, which initialize the graphics workstation and set defaults for use with the application. Section 4 describes the output functions, which cause graphics primitives to be displayed on a graphics output device (a screen or plotter, for example). Section 5 describes the attribute functions, which determine qualities of all subsequent output primitives, such as color and style. Section 6 describes the raster functions, which perform logic operations on raster areas (rectangular blocks of bits in memory or pixels on physical devices). Section 7 describes the input functions, which allow the user to interact with the application program. Section 8 describes the inquire functions, which return the current settings for device specific attributes, such as the number of text styles supported. Section 9 describes the escape functions, which allow the application program to access special device capabilities. Appendix A lists and describes the GEM VDI error messages. Appendix B explains the ASSIGN.SYS file contents, which include information the GDOS uses to identify the output device. Appendix C lists and describes the GEM VDI metafile format. Appendix D defines the GEM VDI standard keyboard. Appendix E describes the mapping of GEM VDI to specific microprocessors and the calling procedures needed to perform that mapping. Appendix F includes the system fonts. Appendix G describes the font file format. Appendix H describes the reserved metafile sub opcodes. Appendix I describes the bit image file format. iv Table of Contents I Overview Introduction . . . . . . . . . . . . . . . . . . . . . . 1-1 Features . . . . . . . . . . . . . . . . . . . . . . . . 1-1 Enhancements . . . . . . . . . . . . . . . . . . . . . . 1-1 Architecture . . . . . . . . . . . . . . . . . . . . . . 1-2 Graphics Device Operating System (GDOS) . . . . . . 1-2 Graphics Device Drivers . . . . . . . . . . . . . . 1-3 Device Types . . . . . . . . . . Metafiles . . . . . . . . . . . . . . . . . . . . . 1-3 Multiple Workstations . . . . . . . . . . . . . . . 1-4 Device Handles . . . . . . . . . . . . . . . . . . 1-4 ASSIGN.SYS . . . . . . . . . . . . . . . . . . . . 1-4 Application Programs . . . . . . . . . . . . . . . . . . 1-5 Virtual Device Interface . . . . . . . . . . . . . . . . 1-5 Transforming Points . Transformation Mode . . . . . . . . . . . . . . . . 1-6 Normalized Device Coordinates . . . . . . . . . . . 1-6 Raster Coordinates . . . . . . . . . . . . . . . . 1-7 2 Writing a Graphics Application Introduction . . . . . . . . . . . . . . . . . . . . . . 2-1 GEM VDI Distribution Files . . . . . . . . . . . . . . . 2-1 Writing the Program . . . . . . . . . . . . . . . . . . 2-1 GEM VDI Functions . . . . . . . . . . . . . . . . . 2-9 Opcodes . . . . . . . . . . . . . . . . . . . . . . 2-9 Required Functions for Screens . . . . . . . . . . 2-9 Required Functions for Printers . . . . . . . . . . 2-11 Required Functions for Plotters . . . . . . . . . . 2-13 Required Functions for Metafiles . . . . . . . . . 2-14 Available Opcodes . . . . . . . . . . . . . . . . . 2-16 Format . . . . . . . . . . . . . . . . . . . . . . 2-16 Input Parameters . . . . . . . . . . . . . . . . . 2-16 Output Parameters . . . . . . . . . . . . . . . . . 2-17 v Table of Contents (continued) Calling Conventions . . . . . . . . . . . . . . . . . . 2-17 Registers and Interrupts . . . . . . . . . . . . . 2-18 Running Graphics Applications Under GEM VDI . . . . . . 2-18 Enabling Graphics . . . . . . . . . . . . . . . . . . . 2-19 Disabling Graphics . . . . . . . . . . . . . . . . . . . 2-20 Determining Memory Requirements . . . . . . . . . . . . 2-20 Debugging Graphics Applications under GEM VDI . . . . . 2-20 3 Control Functions Introduction . . . . . . . . . . . . . . . . . . . . . . 3-1 Open Workstation . . . . . . . . . . . . . . . . . . . . 3-1 Close Workstation . . . . . . . . . . . . . . . . . . . 3-9 Open Virtual Screen Workstation . . . . . . . . . . . . 3-10 Close Virtual Screen Workstation . . . . . . . . . . . . 3-13 Clear Workstation . . . . . . . . . . . . . . . . . . . 3-14 Update Workstation . . . . . . . . . . . . . . . . . . . 3-15 Load Fonts . . . . . . . . . . . . . . . . . . . . . . . 3-16 Unload Fonts . . . . . . . . . . . . . . . . . . . . . . 3-17 Set Clipping Rectangle . . . . . . . . . . . . . . . . . 3-19 4 Output Functions Introduction . . . . . . . . . . . . . . . . . . . . . . 4-1 Polyline . . . . . . . . . . . . . . . . . . . . . . . . 4-1 Polymarker . . . . . . . . . . . . . . . . . . . . . . . 4-4 4-6 vi Table of Contents (continued) Filled Area . . . . . . . . . . . . . . . . . . . . . . 4-8 Cell Array . . . . . . . . . . . . . . . . . . . . . . . 4-11 Contour Fill . . . . . . . . . . . . . . . . . . . . . 4-13 Fill Rectangle . . . . . . . . . . . . . . . . . . . . .4-14 Generalized Drawing Primitive (GDP) . . . . . . . . . . 4-15 Bar . . . . . . . . . . . . . . . . . . . . . . . . . . 4-18 Arc & Pie . . . . . . . . . . . . . . . . . . . . . . . 4-19 Circle . . . . . . . . . . . . . . . . . . . . . . . . . 4-21 Elliptical Arc and Pie . . . . . . . . . . . . . . . . . 4-22 Ellipse . . . . . . . . . . . . . . . . . . . . . . . . 4-24 Rounded and Filled Rounded Rectangle . . . . . . . . . . 4-25 Justified Graphics Text . . . . . . . . . . . . . . . . 4-27 5 Attribute Functions Introduction . . . . . . 5-1 Set Writing Mode . . . . . Replace . . . . . . . . . Transparent . . . . . . . XOR . . . . Reverse Transp;r;.t* . . . Set Color Representation . . . Set Polyline Line Type . . . . . . Set User-defined Line Style Pattern . . . . . . Set Polyline Line Width . . . . . . . Set Polyline Color Index Set Polyline End Styles Set Polymarker Type . . . Table of Contents (continued) Set Polymarker Height . . . . . . . . . . . . . . . . . 5-16 Set Polymarker Color Index . . . . . . . . . . . . . . . 5-17 Set Character Height, Absolute Mode . . . . . . . . . . 5-18 Set Character Cell Height, Points Mode . . . . . . . . . 5-20 Set Character Baseline Vector . . . . . . . . . . . . . 5-22 Set Text Face . . . . . . . . . . . . . . . . . . . . . 5-24 Set Graphic Text Color Index . . . . . . . . . . . . . . 5-26 Set Graphic Text Special Effects . . . . . . . . . . . . 5-27 Set Graphic Text Alignment . . . . . . . . . . . . . . . 5-30 Set Fill Interior Style . . . . . . . . . . . . . . . . 5-32 Set Fill Style Index . . . . . . . . . . . . . . . . . . 5-33 Set Fill Color Index . . . . . . . . . . . . . . . . . . 5-35 Set Fill Perimeter Visibility . . . . . . . . . . . . . 5-36 Set User-defined Fill Pattern . . . . . . . . . . . . . 5-37 6 Raster Operations Introduction . . . . . . . . . . . . . . . . . . . . . . 6-1 Memory Form Definition Block . . . . . . . . . . . . . . 6-1 Raster Area Formats . . . . . . . . . . . . . . . . . . 6-2 Coordinate Systems . . . . . . . . . . . . . . . . . . . 6-4 Logic Operations . . . . . . . . . . . . . . . . . . . . 6-6 Copy Raster, Opaque . . . . . . . . . . . . . . . . . . 6-7 Copy Raster, Transparent . . . . . . . . . . . . . . . . 6-9 Replace Mode . . . . . . . . . . . . . . . . . . . 6-9 Transparent Mode . . . . . . . . . . . . . . . . . 6-9 XOR Mode . . . . . . . . . . . . . . . . . . . . . 6-9 Reverse Transparent Mode . . . . . . . . . . . . . 6-10 viii Table of Contents (continued) Transform Form . . . . . . . . . . . . . . . . . . . . . 6-12 Get Pixel . . . . . . . . . . . . . . . . . . . . . . .6-13 7 Input Functions Introduction . . . . . . . . . . . . . . . . . . . . . . 7-1 Set Input Mode . . . . . . . . . . . . . . . . . . . . . 7-1 Input Locator, Request Mode . . . . . . . . . . . . . . 7-3 Input Locator, Sample Mode . . . . . . . . . . . . . . . 7-6 Input Valuator, Request Mode . . . . . . . . . . . . . . 7-9 Input Valuator, Sample Mode . . . . . . . . . . . . . . 7-11 Input Choice, Request Mode . . . . . . . . . . . . . . . 7-13 Input Choice, Sample Mode . . . . . . . . . . . . . . . 7-14 Input String, Request Mode . . . . . . . . . . . . . . . 7-15 Input String, Sample Mode . . . . . . . . . . . . . . . 7-17 Set Mouse Form . . . . . . . . . . . . . . . . . . . . . 7-19 Exchange Timer Interrupt Vector . . . . . . . . . . . . 7-21 Show Cursor . . . . . . . . . . . . . . . . . . . . . . 7-23 Hide Cursor . . . . . . . . . . . . . . . . . . . . . . 7-25 Sample Mouse Button State . . . . . . . . . . . . . . . 7-26 Exchange Button Change Vector . . . . . . . . . . . . . 7-27 Exchange Mouse Movement Vector . . . . . . . . . . . . . 7-29 Exchange Cursor Change Vector . . . . . . . . . . . . .7-31 Sample Keyboard State Information . . . . . . . . . . . 7-33 8 Inquire Functions Introduction . . . . . . . . . . . . . . . . . . . . . . 8-1 Extended Inquire . . . . . . . . . . . . . . . . . . . . 8-1 ix Table of Contents (continued) Inquire Color Representation . . . . . . . . . . . . . . 8-5 Inquire Current Polyline Attributes . . . . . . . . . . 8-7 Inquire Current Polymarker Attributes . . . . . . . . . 8-9 Inquire Current Fill Area Attributes . . . . . . . . . . 8-11 Inquire Current Graphic Text Attributes . . . . . . . . 8-13 Inquire Text Extent . . . . . . . . . . . . . . . . . . 8-15 Inquire Character Cell Width . . . . . . . . . . . . . . 8-17 Inquire Face Name and Index . . . . . . . . . . . . . . B-19 Inquire Current Face Information . . . . . . . . . . . . 8-21 Inquire Cell Array . . . . . . . . . . . . . . . . . . . 8-23 Inquire Input Mode . . . . . . . . . . . . . . . . . . .8-25 Escapes Escape . . . . . . . . . . . . . . . . . . . . . . . . . 9-1 ESCAPE 1: Inquire Addressable Character Cells . . . . . 9-4 ESCAPE 2: Exit Alpha Mode . . . . . . . . . . . . . . . 9-5 ESCAPE 3: Enter Alpha Mode . . . . . . . . . . . . . . 9-6 ESCAPE 4: Alpha Cursor Up . . . . . . . . . . . . . . . 9-7 ESCAPE 5: Alpha Cursor Down . . . . . . . . . . . . . . 9-8 ESCAPE 6: Alpha Cursor Right . . . . . . . . . . . . . 9-9 ESCAPE 7: Alpha Cursor Left . . . . . . . . . . . . . . 9-10 ESCAPE 8: Home Alpha Cursor . . . . . . . . . . . . . . 9-11 ESCAPE 9: Erase to End of Alpha Screen . . . . . . . . 9-12 ESCAPE 10: Erase to End of Alpha Text Line . . . . . . 9-13 ESCAPE 11: Direct Alpha Cursor Address . . . . . . . . 9-14 ESCAPE 12: Output Cursor Addressable Alpha Text . . . . 9-15 ESCAPE 13: Reverse Video On . . . . . . . . . . . . . . 9-16 X Table of Contents (continued) ESCAPE 14: Reverse Video off . . . . . . . . . . . . . 9-17 ESCAPE 15: Inquire Current Alpha Cursor Address . . . . 9-18 ESCAPE 16: Inquire Tablet Status . . . . . . . . . . . 9-19 ESCAPE 17: Hard Copy . . . . . . . . . . . . . . . . . 9-20 ESCAPE 18: Place Graphic Cursor at Location . . . . . . 9-21 ESCAPE 19: Remove Last Graphic Cursor . . . . . . . . . 9-22 ESCAPE 20: Form Advance . . . . . . . . . . . . . . . . 9-23 ESCAPE 21: Output Window . . . . . . . . . . . . . . . 9-24 ESCAPE 22: Clear Display List . . . . . . . . . . . . . 9-26 ESCAPE 23: Output Bit Image File . . . . . . . . . . . 9-27 ESCAPE 60: Select Palette . . . . . . . . . . . . . . . 9-30 Polaroid Palette . . . . . . . . . . . . . . . . . . . . 9-31 Palette Driver . . . . . . . . . . . . . . . . . . 9-31 Error Messages . . . . . . . . . . . . . . . . . . 9-31 ESCAPE 91: Inquire Palette Film Types . . . . . . . . . 9-32 ESCAPE 92: Inquire Palette Driver State . . . . . . . . 9-33 ESCAPE 93: Set Palette Driver State . . . . . . . . . . 9-35 ESCAPE 94: Save Palette Driver State . . . . . . . . . 9-37 ESCAPE 95: Suppress Palette Messages . . . . . . . . . 9-38 ESCAPE 96: Palette Error Inquire . . . . . . . . . . . 9-39 ESCAPE 98: Update Metafile Extents . . . . . . . . . . 9-41 ESCAPE 99: Write Metafile Item . . . . . . . . . . . . 9-43 ESCAPE 100: Change GEM VDI Filename . . . . . . . . . . 9-44 xi Table of Contents (continued) Appendixes A GEN VDI Error Messages . . . . B ASSIGN.SYS File Requirements . . . . . . . . . . . . . . . . . . . . . . B-1 Device Id Numbers . . . . . . . . . . . . . . . . B-1 Device Driver Filename . . . . . . . . . . . . . . B-1 Format . . . . . . . . . . . . . . . . . . . . . . . . . B-1 Sample ASSIGN.SYS . . . . . . . . . . . . . . . . . . . B-2 C GEN VDI Metafile Format Introduction . . . . . . . . . . . . . . . . . . . . . . C-1 Standard Metafile Item Format . . . . . . . . . . . . . C-1 Nonstandard Metafile Items . . . . . . . . . . . . . . . C-2 1 open workstation . . . . . . . . . . . . . . . C-2 2 close workstation . . . . . . . . . . . . . . . C-4 Special Metafile Escapes . . . . . . . . . . . . . . . . C-4 5, 98 update metafile extents . . . . . . . . . . C-4 5, 99 write metafile item escape . . . . . . . . . C-4 5, 100 change GEM VDI filename escape . . . . . . . C-4 Inquiry Functions . . . . . . . . . . . . . . . . . . . C-5 D Standard Keyboard . . . . . . . . . . . . . . . . . . . D-1 E Processor-Specific Data 8086-Specific Data . . . . . . . 68000-Specific Data . . . . . . F Character Sets . . . . . . . . . . . . .. xii Table of Contents (continued) G Font Format Introduction . . . . . . . . . . . . . . . . . . . . . . G-1 Font Data . . . . . . . . . . . . . . . . . . . . . . . G-1 Font Header . . . . . . . . . . . . . . . . . . . . . . G-1 Character Offset Table . . . . . . . . . . . . . . . . . G-4 Horizontal Offset Table . . . . . . . . . . . . . . . . G-4 B Reserved Ketafile Sub-opcodes Metafile Sub-opcodes for Use with GEM Output . . . . . . H-1 Physical Page Size . . . . . . . . . . . . . . . . . . . H-1 Coordinate Window . . . . . . . . . . . . . . . . . . . H-2 Metafile Sub-opcodes for Use with GEM Draw . . . . . . . H-3 Start Group . . . . . . . . . . . . . . . . . . . . . . H-3 End Group . . . . . . . . . . . . . . . . . . . . . . . H-4 Set No Line Style . . . . . . . . . . . . . . . . . . . H-4 Set Attribute Shadow On . . . . . . . . . . . . . . . . H-5 Set Attribute Shadow Off . . . . . . . . . . . . . . . . H-6 Start Draw Area Type Primitive . . . . . . . . . . . . . H-6 End Draw Area Type Primitive . . . . . . . . . . . . . . H-7 I Bit Image File Format Introduction . . . . . . . . . . . . . . . . . . . . . . I-1 Header Format . . . . . . . . . . . . . . . . . . . . . I-1 Data Format . . . . . . . . . . . . . . . . . . . . . . I-1 Run-length Encoding . . . . . . . . . . . . . . . . 1-2 Extended Run-length Encoding . . . . . . . . . . . 1-2 Raster Encoding . . . . . . . . . . . . . . . . . . 1-3 Raster-run Encoding . . . . . . . . . . . . . . . . 1-3 xiii Table of Contents (continued) Glossary . . . . . . . . . . . . . . Tables 1-1. Device Identification Numbers . . . . . . . . . . . . 1-5 2-1. Parameter Block Contents . . . . . . . . . . . . . . 2-18 3-1. Monochrome Screens . . . . . . . . . . . . . . . . . 3-6 3-2. Monochrome Printer/Plotters . . . . . . . . . . . . . 3-6 3-3. Color Screens . . . . . . . . . . . . . . . . . . . . 3-6 3-4. Default Values . . . . . . . . . . . . . . . . . . . 3-7 5-1. Writing Modes . . . . . . . . . . . . . . . . . . . . 5-1 5-2. Terms . . . . . . : , * * * , * * * * * * * , , , * * 5-2 5-3. Attribute Bit Mapping . . . . . . . . . . . . . . . . 5-27 6-1. Pixel Value to Color index Mapping for 8-color Screens . . . . . . . . . . . . . . . . . . 6-3 6-2. Pixel Value to Color Index M;pping for 16-color Screens . . . . . . . . 6-3. Raster Operation Logic Operations 7-1. Sample Mode Status Returned . 8-1. Face Names and Styles . . . . . . . . . . . . . . . . 8-19 9-1. Escape Function Indentifiers . . . . . . . . . . . . 9-1 B-1. Device id Numbers . . . . . . . . . . . . . . . . . . B-1 D-1. GEM VDI Standard Keyboard Assignments G-1. Font Header Format xiv Table of Contents (continued) Figures 1-1. Transformation Modes . . . . . . . . . . . . . . . . 1-8 2-1. output from the Sample Program 4-1. First Point for wide Lines . . . . . . . . . . . . . 4-1 4-2. Angle Specification . . . . . . . . . . . . . . . . . 4-15 5-1. Character Cell Definition . . . . . . . . . . . . . . 5-20 5-2. Angle Specification . . . . . . . . . . . . . . . . . 5-22 5-3. Graphic Text Special Effects . . . . . . . . . . . . 5-28 5-4. Graphic Text Alignment . . . . . . . . . . . . . . . 5-30 5-5. Fill Styles and Indices . . . . . . . . . . . . . . . 5-33 6-1. Memory Form Definition Block . . . . . . . . . . . . 6-2 6-2. Standard Forms . . . . . . . . . . . . . . . . . . . 6-5 6-3. Sample Single Plane Memory Form . . . . . . . . . . . 6-5 8-1. Inquire Text Extent Function . . . . . . . . . . . . 8-15 8-2. Character Cell Definition . . . . . . . . . . . . . . 8-17 8-3. Right and Left Offset . . . . . . . . . . . . . . . . 8-21 B-1. ASSIGN.SYS File Format . . . . . . . . . . . . . . . B-1 F-1. GEM VDI USASCII Character Set . . . . . . * * * I * * F-2 F-2. GEM VDI International Character Set E X tension . . . . F-3 Listings 2-1. Sample Program . . . . . 2-2. Sample Assembly Language Application xv Section 1 Overview INTRODUCTION The GEM VDI provides a dev ice- independent environment in which you can write graphics applications. This section describes GEM VDI and its architecture. Subsequent sections describe writing an application and all the GEM VDI functions. FEATURES The following features of GEM VDI make it possible for you to write graphics applications that run under several microcomputer operating systems: * GEM VDI provides a common graphics programming interface that is compatible with the most widely used operating systems, thus making it easy to port many programs. e GEM VDI provides a dev ice- independent software interface for your application programs. You do not need to rewrite applications for use with different output devices such as screens, printers, and plotters. GEM VDI handles device differences and makes it possible for you to send information to the devices through the application program as if the devices were the same. GEM VDI handles graphics requests and supplies the right driver to run the specific device. ENELANCEMENTS GEM VDI includes enhancements to GSX functions and now includes the following capabilities: • raster functions--functions that affect raster areas, which are rectangular blocks of pixels on physical devices or rectangular blocks of bits in memory • faces--letter styles stored in dynamically loadable files 1-1 GEM VDI Programmer's Guide Architecture ARCHITECTURE GEM VDI provides graphics primitivesfor implementing graphics applications with reduced programming effort. Application programs interface to GEM VDI through a standard calling sequence. Drivers for specific graphics devices translate the standard GEM VDI calls to the unique characteristics of each device. In this way, GEM VDI provides device independence. GEM VDI is composed of two components: Graphics Device Operating System (GDOS) device drivers and face files The GDOS contains the device-independent graphics functions, while the device drivers and face files contain the device-dependent code. GEM VDI is designed in this way to make the principal parts of the GDOS transportable to different hardware configurations. This design also allows applications to run independently of the specific devices connected to the system. Graphics The Graphics Device Operating System (GDOS) Device Operating contains the basic host and device- System (GDOS) independent graphics functions that can be called by your application program. GDOS provides a standard graphics interface that is constant regardless of specific devices or host hardware, just as the disk operating system standardizes disk interfaces. Your application program accesses the GDOS in much the same way that it accesses the operating system. The GDOS performs coordinate scaling so that your application can specify points in a normalized space. It uses device-specific information to transform (map) the coordinates into the corresponding values for a particular graphics device. An application can also specify points in raster coordinate space, in which case no transformation occurs. GEM VDI Programmer's Guide Architecture Graphics The graphics device drivers are similar to Device Drivers any 1/0 system. They contain the device specific code required to interface your particular graphics devices to the GDOS. The device drivers communicate directly with the graphics devices. GEM VDI requires a unique device driver for each graphics device in a system. A single program can use several graphics devices; the GDOS loads only the appropriate device driver file into memory. By referring to devices with a device identification number, an application program can send graphics information to any one of several memory resident device drivers. The device driver outputs the GEM VDI graphics primitives according to the inherent capabilities of a particular graphics device. In some cases, a device driver emulates standard capabilities not provided by the graphics device hardware. For example, some devices require that dashed lines be simulated by a series of short vectors generated in the device driver. The GEM VDI package contains drivers for many of the most popular microcomputer-related graphics devices. DEVICE TYPES You can write a GEM VDI-based graphics application for a variety of devices including screens, plotters, printers, and special cameras. Net-afiles A metafile is the stored generic form of a picture file. Any application can create a GEM VDI metafile that can later be called into another qraphics application. The metafile driver stores a description of a picture in a data file. These files can later be sent to any device or used to exchange a picture between two applications. 1-3 GEM VDI Programmer's Guide Device Types When GEM VDI creates a metafile, it provides the ideal device. Raster Coordinate (RC) and Normalized Device Coordinate (NDC) space are the same (0 to 32767). No transform is applied. Refer to "Transforming Points" later in this section for more information on the coordinate spaces. Refer to Appendix C for information about the file format for metafiles. Multiple The application program specifies the Workstations graphics function to be performed by a device driver with an operation code (opcode) in the control array. "Opcodes" in Section 2 describes the opcodes. Because multiple workstations can be open at the same time, each GEM VDI function must be provided with a unique reference to the desired device. This identification is referred to as the device handle. Device Handles The GDOS assigns the device handle when the Open Workstation function is called by the application program. The Open Workstation call returns the device handle in the array element contrl(6). All subsequent GEM VDI calls need to supply the device handle as an input in element contrl(6). ASSIGN.SYS The ASSIGN.SYS file is a text file, and can be created or edited using any text editor. The file lists the device driver filenames and face filenames, their device numbers, and device specific information. The device numbers are assigned according to their type- Refer to Table 1-1 for device numbers. 1-4 GEM VDI Programmer's Guide Device Types Table 1-1. Device Identification Numbers Device Type Device Number Screen 1-10 Plotter 11-20 Printer 21-30 Metafile 31-40 Camera 41-50 Tablet 51-60 APPLICATION Wit~i appropriate calls to the GDOS, you can PROGRAMS write application programs in assembly language or Ln a high-level language that supports the GEM VDI calling conventions. You can compile or assemble and link programs containing GEM VDI calls in the normal manner. Refer to Section 2 for more information about writing graphics application programs. VIRTUAL DEVICE This guide contains the specification of the INTERFACE GEM Virtual Device Interface (VDI) and defines how applications interface to GEM VDI. The GEM VDI specifies the calling sequence to access device driver functions as well as the necessary calling parameters. Refer to ApPE!ndix E for the main entry into the VDI for your operating system. The main entry point into the VDI is a single subioutine with five arguments, in the form of five arrays: • control array o array of input parameters • array of input point coordinates • array of output parameters • array of output point coordinates GEM VDI Programmer's Guide Virtual Device Interface All array elements are of type INTEGER (2 bytes). All arrays are zero-based; that is, the double-word address of the Parameter Block (PB) points to the first element of the control array, contri(o). The content of the input and output parameter arrays depends on the opcode. Refer to Section 2 for more information about writing graphics applications. TRANSFORMING All computer graphics are displayed using a POINTS coordinate system. GEM VDI makes sure the coordinate system of one device matches the coordinate system of another. For example, with 3EM VDI, the application program produces the same graphics image on a printer as on a screen. The linetypes and fill styles are the same in Normalized Device Coordinates (NDC), which are described below. Character sizes are different. The same number of characters are displayed per line, but a printer's line length is generally greater than a screen's. Transformation The application program can address the Mode display surface using one of two coordinate systems: Normalized Device Coordinates (NDC) Raster Coordinates (RC) The transformation mode, specified at Open Workstation, determines which coordinate system is used. Normalized Device Normalized Device Coordinates (NDC) address Coordinates the graphics display independent of the device coord:.nate size. These units are then mapped to Ranter r-oordinates by the GDOS. The transformation mode set at Open Workstation determines whether the GDOS maps from NDC units to the! Raster Coordinates. GEM VDI Programmer's Guide 'I'ranstorming eoinrs The full scale of NDC space (0-32767) is mapped to the full dimensions of the device on both axes. On a nonsquare display with square pixels, a different scale factor is applied to each axis with this transformation mode. NDC space has its origin at the lower left corier, and its (xmax,ymax) point at the upper right corner. This space is in the first quadrant of the Cartesian coordinate system. When transforming from NDC to Rdster Coordinates (RC), the GDOS assumes a raster coor'dinate at the bottom left edge of a pixel. You should compensate for a boundary condition created at the top edge of NDC space. This problem is best illustrated with an example. Given the display of Figure 1-1 in Transformation Mode 0, the NDC point (32767,32767) maps to the point (0,200) in RCs. But because pixels are addressed at their lower left corner, the NDC point (32766,32766) maps to the point (1,199) in RCs. The application prcgrammer should correct for this boundary error by adding half of the NDC height and width into the coordinate transform to ensure that any roundoff error in the application world-to-NDC transform does not cause the wrong pixel to be addressed. Raster Coordinates Raster Coordinates (RC) are actual device units (fo:~ example, rasters for screens or steps for plotters and printers). Unlike NDCs, RCs have their origin at the upper left corner, and the (xm5,x,ymax) point at the bottom right pixel of the space. Refer to Figure 1-1 for an illustration of this concept. No transformation occurs when the RC system is in affect. The application needs to adjust its transform based on the aspect ratio of pixels on the screen. The raster coordinate system saves the overhead of the GDOS having to perform a transformation on every point. GEM VDI Programmer's Guide Transforming Points (32767,32767) ----------------- -------- (0,0) ------------ (640,200) (0,0) Mode 0 Full NOC mapped to full FIC space (0,0) (0,0) - ---------- ----------- (640,200) (640,200) Mode 2 Application works in RC space Figure 1-1. Transformation Modes End of Section 1 1-8 Section 2 Writing a Graphics Application INTRODUCTION This section explains how to use GEM VDI in your graphics applications. GEM VDI WhEn you receive your GEM VDI distribution DISTRIBUTION dicks, first duplicate them and then store FILES thEm in a safe place. Then, using the duplicate disks, transfer the GEM VDI files to working syEtem disks. Always use the duplicate disks to generate any new copies of GEM VDI. Do not use the distribution disks for routine OPE!rations. WRITING THE YoL. can write your graphics application in PROGRAM one of two ways: * using assembly language o using high-level language bindings (C language bindings are provided.) Thc first method addresses functions by their opcode numbers, the second by procedure name. The C Language bindings provided for each fu,iction allow for portability across implementations. In the C bindings, which appear with each function in sections 3 through 9, WORD declares a 16-bit integer type; BYTE declares an 8-bit integer type. The following figure is produced by the sample C language graphics application in Listing 2-1 that follows the figure. Listing 2-2 is a sariple assembly language graphics program. 2-1 0M Programmer's Guide Writing the Program n I-ft*~ Figuxe 2-1. Output from the Sample Program Listing 2-1. Sample Program /* The following globals must b,~ declared to satisfy the /* external references from the C binding routine. int contrl[12); int intin[128); int ptsin[1281; int intout[1281; int ptsout[128); main int handle, i, pxyarray[12], work-in(Il), work-out[57]; int x,y, term; /* Open the workstation. work in[O] - 1; for -(i - 1; i < 10; i++) work in[i) - 1; work in[101 - 0; /* use NDC coordinates v_opnwk(work_in, &handle, work-out); /* Output a polyline. pxyarray[O] - 12000; /* vertices pxyarrayll) - 12000; pxyarray[2] - 12000; pxyarray[3) - 20000; pxyarray[4] - 14000; pxyarray[51 - 21000; pxyarray[6] - 16000; pxyarray[71 - 20000; pxyarray[B] - 16000; pxyarray[91 - 12000; p.yarray[101 12000; pxyarray(Ill 12000; v_pline(handle, 6, pxyarray); /* output polyline 2-2 GEM Programmer's Guide Writing tne Program Listing 2-1. (continued) /* Pause for viewing. vrq_locator(handle, 1600C, 16000, &x, &y, &term); /* Close the workstation. v-clswk(handle); /* End "main". */ Listing 2-2. Sample Assembly Language Application Sample Assembly language program to interface with GEM VDI To open the workstation, draw a border, and say hello world false equ 0 true equ not false dly equ 05FH ; for delay process, OFFFF is max delay possible W_O equ word ptr 0 W_1 equ word ptr 2 W_2 equ word ptr 4 w_3 equ word ptr 6 W_4 equ word ptr 8 W_5 equ word ptr 10 W_6 equ word ptr 12 W~_7 equ word ptr 14 W_8 equ word ptr 16 W_9 equ word ptr 18 W_10 equ word ptr 20 W_ll equ word ptr 22 W_12 equ word ptr 24 W_13 equ word ptr 26 W 14 equ word ptr 28 14-15 equ word ptr 30 W 16 equ word ptr 32 VC-17 equ word ptr 34 W~18 equ word ptr 36 W 19 equ word ptr 38 W-20 equ word ptr 40 2-3 GEM Programmer's Guide Writing the Program Listing 2-2. (continued) parameter array sizes CONTRI, SIZE equ 11 INTIN -§IZE equ 128 PTSIN SIZE equ 256 INTOUT SIZE equ 128 PTSOUT-SIZE equ 12 start the main body of the c,Dde cseg declare these publics so that the labels appear in the symbol file useful for debugging purposes public entry public opnwk public border public announce public delay public clswk public gemvdi entry: set up the stack as required for all main assembly language programs pushf mov cx1sp mov bx,ss Cli mov ax,seg mystack mov ss,ax mov sp, offset mystack_top sti popf set up the pointers to the geinvdi arrays (contrl_ptr offset:segment of CONTRL) this example does it when the code is loaded opnwk: ; load the CONTRI, and INTIN arrsys for an openworkstation call mov CONTRL + W 0,1 opcod~? for openworkstation mov CONTRI, + 14-1,0 0 ptsin values mov CONTRI, + 14-3,11 11 intin values 2-4 uEm Programmer-s uuiae WZlr-lng ICJIe k'EUqLdM Listing 2-2. (continued) mov INTIN + W 0,1 device id = 1 mov INTIN + W1,1 liretype mov INTIN + W~2,1 lire color mov INTIN + W 3,1 marker type mov, INTIN + W 4,1 marker color mov INTIN + W 5,1 fort mov INTIN + W 6,1 text color mov INTIN + W~7,1 fill interior style mov INTIN + W 8,1 fill style index mov INTIN + W 9,1 fill color index mov INTIN + W-10,2 transformation flag RC system ; call gemvdi call gemvdi ; save the handle returned by openworkstation mov, ax,CONTRL + W_6 this is the handle returned by open and needed mov handle,ax by all other calls to the open workstation ; copy INTOUT and PTSOUT intc open_device, my local copy of the Device Table cld autoincrement the si and di registers push ds prepare es:di to move words to open_device pop es lea di,open_device mov, cx,45 prepare to load 45 words from INTOUT lea si,INTOUT rep movsw mov cx,12 prepare to load 12 words from PTSOUT lea si,PTSOUT rep movsw border: ; load CONTRL and INTIN arrays to draw a border and a diagonal mov, CONTRL + W 0,6 opccde for polyline mov, ax,handle put the handle into CONTRL mov, CONTRL + W 6,ax mov CONTRL + W-1,6 it takes 5 points to enclose the border of the device and one more for the diagonal mov CONTRL + W-3,0 not~ing for INTIN mov PTSIN + W 0,0 poirt I is at (0,0) mov, PTSIN + W~1,0 mov ax,open_device + W-0 ;the max x resolution is the first entry of open_device mov PTSIN + W 2,ax poirt 2 is at (xresmx,O) mov, PTSIN + W-3,0 mov bx,open - device + W-1 ;the max x resolution is the first entry of open_device mov PTSIN + W - 4,ax poirt 3 is at (xresmx,yresmx) mov, PTSIN + W-5,bx mov, PTSIN + W 6,0 poirt 4 is at (O,yresmx) mov PTSIN + W-7,bx 2-5 GEM Programmer's Guide Writing the Program Listing 2-2. (continued) mov PTSIN + W 8,0 point 5 is at (0,0) mov PTSIN + W 9,0 mov PTSIN + W 10,ax point 6 is at (xresmx,yresmx) mov PTSIN + W~11,bx call gemvdi call gemvdi announce: load CONTRI, and INTIN arrays to write "hello world" in the default system face and font, with deftult alignment, at the center of the device mov CONTRL + W-0,8 opcode for text mov ax,handle put the handle into CONTRL mov CONTRL + W-6,ax mov CONTRL + W-1,1 text Iccation vertice mov CONTRL + W-3,length anncmnt ; length of the text string to be sent mov ax,open-device + W-0 ; put tle max x resolution in ax shr ax,l ; divide the max x resolution by two mov bx,open_device + W-1 put tte max y resolution in bx shr bx,l divide the max y resolution by two mov PTSIN + W O,ax put the center point coordinate in PTSIN mov PTSIN + W~l,bx cld autoincrement the si and di registers mov cx,length anncmnt prepare to move the announcment string into INTIN lea si,anncmnt push ds pop es lea di,INTIN xor ah,ah make sure the high byte is clear internalloopl: lodsb transfer a byte from the source, to the accumulator stosw store the accumulator in the destination loop internalloopl do this operation for each byte in the source call gemvdi call gemvdi delay: ; delay for viewing mov cx,dly delayloop3: push cx mov cx,dly delayloop2: push cx mov cx,dly delayloopl: xchg ax,bx loop delayloopl 2-6 Listing 2-2. (continued) pop cx loop delayloop2 pop cx loop delayloop3 clswk: ; load CONTRL array to closeworkstation call mov CONTRI, + W_0,2 opcoJe for close workstation mov ax,handle put the handle into CONTRL mov CONTRL + W 6,ax mov CONTRI, + W 1,0 no input vertices mov CONTRI, + W-3,0 no INTIN values call gemvdi call gemvdi done with the main program, return to the operating system mov ax,4cOOh Xor cx,cx xor dx,dx int 21h ; this is where contrDl returns to the o.s. the gemvdi subroutine call for the main program GDOS EQU OEFH interrupt the os with this interrupt vector for calls tD GEM VDI gemvdi: mov ax, seg contrl_ptr mov ds,ax Lea dx, contrl_ptr DX points to GEM VDI parameter array address Mov cx, 0473h GEM VDI function number into CX Int GDOS Call GODS ret end of the code segment of the sample program begin the data segment for the sample program DATA dseg PUBLIC word DGROUP GROUP DATA declare these publics so that the labels appear in the symbol file useful for debugging purposes public CONTRL public INTIN public PTSIN public INTOUT 2-7 -W%JLQ1U111CL b %3UIUt! wrlEing tne Program Listing 2-2. (continued) public PTSOUT public contrl_ptr public intin ptr public ptsin ptr public intou _ptr public ptsout_ptr public handle public open_device CONTRI, rw CONTRL SIZE INTIN rw INTIN SfZE PTSIN rw PTSIN SIZE INTOUT rw INTOUT SIZE PTSOUT rw PTSOUT-SIZE contrl_ptr dw offset CONTRI, these are fixed when the program is loaded dw seg CONTRI, tc be double word pointers to the arrays intin_ptr dw offset INTIN this is the parameter block to which ds:dx dw seg INTIN pcints when GEM VDI is called ptsin_ptr dw offset PTSIN dw seg PTSIN intout_ptr dw offset INTOUT dw seg INTOUT ptsout_ptr dw offset PTSOUT dw seg PTSOUT handle dw 0 open_device rw INTOUT-SIZE + PTSOUT-SIZE anncmnt db 'Sample Assembly Language Program' end the data segment for the sample program ;begin the stack segment for the sample program STACK sseg PUBLIC word SGROUP GROUP STACK as stated in the VDI programmers guide, the caller must supply at least 128 words of stack for the GEM VDI openworkstation call. the calls to the gemvdi subroutine in the code above require at most 6 points, or 12 words words of stack. assume an o.s overhead of 128 bytes. this means a minimum of 264 words on the stack mystack rw 264 mystack top rw 0 ;push decrements before store end tRe stack segment for the sample program 2-8 rLUkJLQ1LU11CL Z UU~UC U~ 3 Listing 2-2. (continued) end the sample program. Indicate this is main body and code starts at entry end entry GEK VDI Functions The functions are grouped by type, output, and so on. Each device type requires certain functions, lists of which follow. Opcodes Opcodes are numbers assigned to each GEM VDI function. The device drivers recognize all opcodes, whether or not they produce any action. If an opcode is out of range, the driver performs no action. Required Functions Screens require the following functions and for Screens subfunctions: Opcode Definition 1 Open workstation 2 Close workstation 3 Clear workstation 4 Update workstation 5 Escape Id Definition 1 Inquire addressable character cells 2 Exit alpha mode 3 Enter alpha mode 4 Cursor up 5 Cursor down 6 Cursor right 7 Cursor left 8 Home cursor 9 Erase to end of screen 2-9 ULM VDI Programmer's Guide Writing the Program 10 Erase to end of line 11 Direct cursor address 12 Output cursor addressable text 15 Inquire current alpha cursor address 18 Place graphic cursor 19 Remove last graphic cursor 6 Polyline 7 Polymarker 8 Text 9 Filled area 11 Generalized Drawing Primitive (GDP) id Definition 1 Bar 2 Arc 3 Pie 4 Circle 5 Ellipse 6 Elliptical Arc 7 Elliptical Pie 8 Rounded rectangle 9 Filled rounded rectangle 10 Justified graphics text 12 Set character height absolute mode 14 Set color representation 15 Set polyline linetype 17 Set polyline color index 18 Set polymarker type 20 Set polymarker color index 21 Set text face 22 Set text color index 23 Set fill interior style 24 Set fill style index 25 Set fill color index 26 Inquire color representation 28 Input locator 31 Input string 32 Set writing mode 33 Set input mode 35 Inquire current polyline attributes 36 Inquire current polymarker attributes 37 Inquire current fill area attributes 38 Inquire current graphic text attributes 39 Set graphic text alignment loci Open virtual screen workstation 101 Close virtual screen workstation 102 Extended inquire function 2-10 uLm voi erogrammer s kiulae writing tne rrogram 104 Set fill perimeter visibility 106 Set graphic text special effects 107 Set character cell height, points mode 108 Set polyline and styles 109 Copy raster, opaque 110 Transform form 1.11 Set mouse form 1 ' L2 Set user-defined fill pattern 113 Set user-defined linestyle 1 ' L4 Fill rectangle 115 Inquire input mode 116 Inquire text extent 117 Inquire character cell width 1 " L8 Exchange timer interrupt vector 121 Copy raster, transparent 122 Show cursor 123 Hide cursor 124 Sample mouse button state 125 Exchange button change vector 126 Exchange mouse movement vector 127 Exchange cursor change vector 128 Sample keyboard state information 129 Set clipping rectangle 130 Inquire face name and index 131 Inquire current face information Required Functions Printers require the following functions and for Printers subj'unctions: Opcode Definition 1 Open workstation 2 Close workstation 3 Clear workstation 4 Update workstation 5 Escape id Definition 1 Inquire addressable character cells 20 Form advance 21 Output window 22 Clear display list 23 Output bit image file 2-11 ur,m vui Yrogrammer s uulae writing tne iroqram 6 Polyline 7 Polymarker 8 Text 9 Filled area 11 Generalized Drawing Primitive (GDP) id Definition 1 Bar 2 Arc 3 Pie 4 Circle 5 Ellipse 6 Elliptical Arc 7 Elliptical Pie 8 Rounded rectangle 9 Filled rounded rectangle 10 Justified graphics text 12 Set character height absolute mode 15 Set polyline linetype 17 Set polyline color index is Set polymarker type 20 Set polymarker color index 21 Set text face 22 Set text color index 23 Set fill interior style 24 Set fill style index 25 Set fill color index 26 Inquire color representation 32 Set writing mode 35 Inquire current polyline attributes 36 Inquire current polymarker attributes 37 Inquire current fill area attributes 38 Inquire current graphic text attributes 39 Set graphic text alignment 102 Extended inquire function 104 Set fill perimeter visibility 106 Set graphic text special effects 107 Set character height points mode 108 Set polyline end styles 112 Exchange fill pattern 116 Inquire text extent 117 Inquire character cell width 129 Set clipping 130 Inquire face name and index 131 Inquire current face information 2-12 GEM VDI Programmer's GuLde Writing the Program Required Functions Plo--ters require the following functions and for Plotters subEunctions: Opcode Definition .L Open workstation :2 Close workstation .3 Clear workstation Update workstation 15 Escape id Definition 1 Inquire addressable character cells 13 Polyline .7 Polymarker 13 Text 4) Filled area 11 Generalized Drawing Primitive (GDP) id Definition 1 Bar 2 Arc 3 Pie 4 Circle 5 Ellipse 6 Elliptical arc 7 Elliptical pie 8 Rounded rectangle 9 Filled rounded rectangle 10 Justified graphics text 12 Set character height absolute mode 15 Set polyline linetype 1 .7 Set polyline color index 113 Set polymarker type 20 Set polymarker color index 2 ' L Set text face 22 Set text color index 2:3 Set fill interior style 24 Set fill style index 25 Set fill color index 35 Inquire current polyline attributes 313 Inquire current polymarker attributes V Inquire current fill area attributes 313 Inquire current graphic text attributes GEM VDI Programmer's Guide Writing the Program 39 Set graphic text alignment 102 Extended inquire function 104 Set fill perimeter visibility 107 Set character height points mode 108 Set polyline end styles 116 Inquire text extent 117 Inquire character cell width 124 Set clipping 130 Inquire face name and index 131 Inquire current face information Required Functions Because metafiles are transportable to any for Ketafiles device, the required functions are all those commcn to any device you may use. Metafiles support some inquiries by returning the opcode number. Refer to Appendix C for the metafile format of those supported inquires. Metafiles require the following functions and subfunctions: Opcode Definition 1 Open workstation 2 Close workstation 3 Clear workstation 4 Update workstation 5 Escape id Definition 1 Inquire addressable character cells 2 Exit alpha mode 3 Enter alpha mode 20 Form advance 21 Output window 22 Clear display list 23 Output bit image file 98 Update metafile extents 99 Write metafile item 100 Change GEM VDI filename 6 Polyline 7 Polymarker 8 Text 9 Filled area 11 Generalized Drawing Primitive (GDP) 2-14 GEM VDI Programmer's Guide Writing the Program id Definition 1 Bar 2 Arc 3 Pie 4 Circle 5 Ellipse 6 Elliptical arc 7 Elliptical pie 8 Rounded rectangle 9 Filled rounded rectangle 10 Justified graphics text 12 Set character height absolute mode 13 Set character baseline vector 14 Set color representation 15 Set polyline linetype 16 Set polyline line width 17 Set polyline color index 18 Set polymarker type 19 Set polymarker height 20 Set polymarker color index 21 Set text face 22 Set text color index 23 Set fill interior style 24 Set fill style index 25 Set fill color index 26 Inquire color representation 32 Set writing mode 35 Inquire current polyline attributes 36 Inquire current polymarker attributes 37 Inquire current fill area attributes 38 Inquire current graphic text attributes 39 Set graphic text alignment 102 Extended inquire function 103 Contour fill 104 Set fill perimeter visibility 106 Set graphic text special effects 107 Set character height points mode 108 Set polyline end styles 112 Set fill pattern 113 Set user-defined line style pattern 114 Fill rectangle 117 Inquire character cell width 129 Set clipping rectangle 131 Inquire current face information 2-15 GEM VDI Programmer's Guide Writing the Program Available You can determine if a function is available Opcodes in a specific driver in one of the following ways: 9 Check the information about available features returned from the Open Workstation function or the Extended Inquire function. Check the selected value returned from an opcode against the requested value. If the twovalues are not the same, then either the function is not available or the requested value is not available, and GEM VDI selected a best fit value. Format The following is the format for the parameters for a..1 GEM VDI functions. Input Parameters contr:.(O) Opcodenumber for the GEM VDI function. contr.".(l) Number of vertices in the ptsin array. Each vertex consists of an x,y coordinate pair, so the length of the ptsin array is twice the number of specified vertices contr:.(3) Length of integer array intin. contr:.(5) Subfunction identif ication number for a Generalized Drawing Primitive (GDP) or Escape. contrl.(6) Device handle. contrl.(7-n) Opcoae-dependent information. intin Array of integer input parameters. 2-16 GEM VDI Programmer's Guide Writing the Program ptsin A r r a y of i n p u t p o i n t coordinate data. Refer to the Extended Inquire function in Section 8 for information on how to determine the maximum size for the ptsin array. Output Parameters cor.trl(2) Number of vertices in the ptsout array. Each vertex consists of an x,y coordinate pair, so the length of the ptsout array is twice the number of specified vertices. contrl(4) Length of integer array intout. contrl(6) Device handle. coritrl(7-n) Opcode-dependent information. intout Array of integer output point parameters. ptsout A r r a y of output point coordinate data. CALLING Because both input and output coordinates CONVENTIONS may be converted by the GDOS, the calling routine must ensure that the vertex count, corttrl (1) , is set correctly. Contrl (1) must be set. to 0 if no x,y coordinates are being passed to GEM VDI by the application program. In addition, the input integer count, contrl(3), must always be set. The calling routine must set contrl(3) to 0 if no integers are being passed to GEM VDI. Similarly, contrl(2), the output vertex count, and contrl(4), the output int eger count, are always set correctly by GEM VDI. These values contain zeros it no information is being passed back in ptsout and intout, respectively. The double-word addresses of the five parameter ariays are stored in a ten-word data structure re:'erred to as a Parameter Block (PB). 2-17 GEM VDI Programmer's Guide Calling Conventions Registers and Refer to Appendix E for the specific Interrupts registers and interrupts for various operating systems. Table 2-1. Parameter Block Contents Address Contents PB control array (contrl) PB + 4 input parameter array (intin) PB + 8 input point coordinate array (ptsin) PB + 12 output parameter array (intout) PB + 16 output point coordinate array (ptsout) RUNNING GRAPHICS To use the graphics features provided by APPLICATIONS GEM VDI, you must ensure that the following UNDER GEM VDI conditions are met: 1. Yoir application program must conform to the GEM VDI calling convention to access graphics primitives. This process involves the application making a call to the GDOS and using the interrupt for your operating system. Refer to Appendix E for the specific interrupts. The parameter list provides information to GE4 VDI and returns information to the calling program. The details of parameter passing are in the previous section. 2. Enough stack space must be available for GEM VDI operations. This space includes a buffer area for transforming points passed to GEM VDI and some fixed overhead space. The formula to determine the required stack space is discussed under "Determining Memory Requirements" later in this section. 2-18 GEM VDI Programmer's Guide Running Graphics Applications 3. When your program is executed, the required device drivers must be present on the disk specified in the GEM VDI graphics-mode command, or in the current default drive if no drive is specified. The ASSIGN.SYS file must contain the names of your device drivers and a device ID number for each device driver. Refer to "ASSIGN.SYS" in Section 1 for information about creating an NSSIGN.SYS file. 4. kfter successfully compiling or assembling and linking your application program, you -an run it like any program, once GEM VDI is active. You can enable GEM VDI graphics with the GEMVDI graphics-mode command, described under "Enabling Graphics" below. ENABLING GRAPHICS Special commands let you enable graphics functions from the command level of the operating system. To Load GEM VDI and start a non-GEM application that uses the VDI (like a test program or debugger), type the following command: GKK6FDI /FILKNAKE To load GEM VDI and start a GEM application, type the following command: GEK61DI FILENAKE To load GEM VDI and start the GEM Desktop" application, type the following command: GOODI Each command loads GDOS and any drivers declared resident in the ASSIGN.SYS file. ASS":GN.SYS and the driver files must be located in one of the directories in the current search pat',i. Any application to be invoked by a GEMVDI command must also be located in the search pat'"i. GEM VDI Programmer's Guide Disabling Oraphics DISABLING GRAPHICS When the application invoked by the GEMVDI command terminates, GEM VDI relinquishes all system memory space, leaving the maximum memory for nongraphics programs. DETERMINING MEMORY To determine the amount of stack space REQUIREMENTS required to run a given application, make the following calculation: Open workstation call = approximately 128 bytes All other calls = ptsin size + 128 bytes + the overhead requirements of the operating system Ptsin is the point array passed to the device driver from the application program (two words for each point). The stack requirement is the larger of the two resulting values. This stack space must be available in the application program stack area. GEM VDI requires less than 30 kilobytes in memory for a single open driver. This space is allocated when you enter the GEM VDI graphics mode command. DEBUGGING GRAPHICS Graphics programs can be debugged with a APPLICATIONS debugging tool. The default device drivers UNDER GEM VDI and GDOS are loaded after you enter the GEMVDI command. Your graphics application program is loaded in the normal manner for programs on your operating system. End of Section 2 Section 3 Control Functions INTRODUCTION The control functions initialize the graphics wo:'kstation and set defaults for use with the ap],:)lication. OPEN WORKSTATION The Open Workstation function loads a graphics device driver for the application program and returns a device handle. The device is in~Ltialized with the parameters in the input array. Information about the device is returned; a d d i t i o n a 1 deviCe-specific infformation is returned in the Extended Inquire function. If the device is a screen, it is initialized to graphics mode. GEM VDI clears the display sui~face. If the device cannot be opened, GEM VDI returns a 2ero as the device handle in contrl(6). Any noizero value in contrl(6) indicates a successful operation. Input contrl(0) Opcode = 1. contrl(l) Number of input vertices = 0. contrl(3) Length of intin array = 11. intin Initial defaults (for example, linestyle, color, character size). intin(0) Device id number. This value determines which device driver to dynamically load in memory. intin(l) Linetype. int.in(2) Polyline color index. int.in(3) Marker type. int.in(4) Polymarker color index. intin(5) Text face. intin(6) Text color index. intin (7) Fill interior style. int.in(8) Fill style index. int.in(9) Fill color index. 3-1 GEM VDI Programmer's Guide 6pen Workstation intin(10) NDC to RC transformation flag. 0 = Map the full NDC space to the full RC space. 1 = Reserved. 2 = Use the RC system. Output contrI(2) Number of output vertices = 6. contrI(4) Length of intout array = 45. contrI(6) Device handle for this device. intout(O) Maximum addressable width of screen or plotter in rasters or steps, assuming a 0 start point (for example, a resolution of 640 implies an addressable area of 0-639, so intout(O)=639). intout(l) Maximum addressable height of screen or plotter in rasters or steps, assuming a 0 start point (for example, a resolution of 480 implies an addressable area of 0-479, so intout(l)=479). intout(2) Device Coordinate units flag. 0 = D e v i c e c a p a b 1 e of producing precisely scaled image (typically a plotter or a printer). 1 = Device not capable of producing precisely scaled image (typically a film recorder). intout(3) Width of one pixel (plotter step, or aspect ratio for screen) in microns. intout(4) Height of one pixel (plotter step, or aspect ratio for screen) in microns. intout(5) Number of character heights. 0 = Continuous scaling. intout(6) Number of linetypes. intout(7) Number of line widths. 0 = Continuous scaling. intout(8) Number of marker types. 3-2 ULM VVI Gulde Upen Workstation intout(9) Number of marker sizes. 0 = Continuous scaling. int.out(10) Number of faces supported by device (not the highest numbered face index). int.out(ll) Number of patterns. int,out(12) Number of hatch styles. intout(13) Number of predefined colors (2 for monochrome devices). This is the number of colors that can be displayed on the device simultaneously. intout(14) -- Number of Generalized Drawing Primitives (GDPs). intout(15) to intout(24) -- Linear list of the first ten supported GDPs. The number indicates which GDP is supported. A -1 indicates the end of the list of supported GDPs. GEM VDI defines ten GDPs. 1 Bar 2 Arc 3 Pie slice 4 Circle 5 Ellipse 6 Elliptical are 7 Elliptical pie 8 Rounded rectangle 9 Filled rounded rectangle 10 Justified graphics text intout(25) to intout(34) -- Linear list of attribute set associated with each GDP. 0 Polyline 1 Polymarker 2 Text 3 Fill area 4 None intout(35) -- Color capability flag. 0 No 1 Yes 3-3 GEM VDI Programmer*s uuiae Upen "UL&bLCLL~Ull intout(36) Text rotation capability flag. 0 No 1 Yes intout(37) Fill area capability flag. 0 No 1 Yes intout(38) Cell array operation capability flag. 0 No 1 Yes intout.(39) Number of available colors ( total number of colors in color palette). 0 Continuous device (more than 32767 colors) 2 Monochrome (black and white) >2 Number o f c o 1 o r s available intout.(40) Number of locator devices available. 1 Keyboard only 2 Devices with keyboard and other input intoui.(41) Number of valuator devices available. 1 Keyboard 2 If another valuator device is available intoul.(42) Number of choicedevices available. 1 Function keys on keyboard 2 If another button pad is available intoul--(43) Number of string devices available. 1 -- Keyboard 3-4 ~UIIA"~ Upen VVOLKSLdLIOn intout(44) -- Workstation type. 0 Output only 1 Input only 2 Input/output 3 Reserved 4 Metafile output ptEout(O) Minimum character width. ptsout(l) Minimum character height in the y - a x i s in t h e current coordinate system. The minimum and maximum character heights are the actual character body (baseline to top line), not the character extent box, which may include extra space used for interline or intercharacter spacing. ptsout(2) Maximum character width. ptsout(3) Maximum character height in the y - a x i s in t h e current coordinate system. ptsout(4) Minimum line width in the x-axis in current coordinate system. The minimum line width is a nominal device-dependent size. If the minimum line width used is 1 device unit, the line may not be visible on some high resolution devices. ptsout(5) 0. ptsout(6) Maximum line width in the x-axis in the current coordinate system. ptsout(7) 0. ptsout(B) Minimum marker width in x-axis in the current coordinate system. ptsout(9) Minimum marker height in x-axis in the current coordinate system. ptsout(10) Maximum marker width in x-axis in the current coordinate system. ptsout(ll) Maximum marker height in x-axis in the current coordinate system. 3-5 GEM VDI Programmer's Guide Open Workstation Default Color The default color table is set up differently Tables for monochrome and color devices. Table 3-1. Monochrome Screens Index I Color 0 White 1 Black Table 3-2. Monochrome Printer/Plotters Index I Color 0 White I Black Table 3-3. Color Screens Color Inde, 0 White 1 Black 2 Red 3 Green 4 Blue 5 Cyan 6 Yellow 7 Magenta a White 9 Black 10 Light Red 11 Light Green 12 Light Blue 13 Light Cyan 14 Light Yellow 15 Light Magenta 16-n Device-dependent 3-6 GEM VDI Programmer's Guide Open Workstation Other default values set by the driver during initialization are listed in Table 3-4. Table 3-4. Default Values Attribu Default Value Character height Nominal character height Character baseline rctation 0 degrees rotation Text alignment Left baseline Text style Normal intensity Line width Nominal line width Marker height Nominal marker height Polyline end styles Squared Writing mode Replace Input mode Request for all input classes (locator, valuator, choice, string) Fill area perimeter visibility Visible User-defined line style Solid User-defined fill pattern Solid Cursor Hidden Clipping Disabled GEM VDI Programmer's Guide Open Workstation C BINDING Procedure Name v_opn%k( work-in, &handle, work-out Data Types WORD v_opnwk ( ); WORD Aork in[lll, WORD liandfe; WORD %ork-out[573; Input Arguments work-in[01 = intin[03 work-in[l] = intin(l] work-in[101 = intin[lol Output Axguments handlc = contrl[61 work - out[03 = intout[03 work-out[l] = intout[l] w~rk out[443 = intout[441 work-out[451 = ptsout[01 work-out[561 = ptsout[lll --ft, 3-8 GEM VDI Programmer's Guide Close Workstation CLOSE WORKSTATION The Close Workstation function terminates the graphics device properly (returning you to alpha mode) and prevents any further output to the device. If the device is a screen, the alpha device is selected, and the graphics device is deselected. If the device is a pr:.nter, an update occurs if one has not just tal:en place. For a metafile, GEM VDI flushes the buffer and closes the metafile. Note: Close your open virtual workstations before closing the workstation. Input cor.trl(O) Opcode = 2. contrl(l) Number of input vertices = 0. cor.trl(3) Length of intin array = 0. contrl(6) Device handle. Output cor.trl(2) Length of output vertices = 0. cortrl(4) Length of intout array = 0. C BINDING Procedure Name v-clswk( handle Data Types WORD v clswk WORD h-andle; Input Arguments handle = contrIE61 3-9 GEM VDI Programmer's Guide Open Virtual Screen Workstation OPEN VIRTUAL This Eunction allows a single physical screen SCREEN WORKSTATION to ac:t as multiple workstations. Each workstation has access to the entire screen. However, attribute environments for each workstation are maintained separately. For example, the workstation may have different transformation modes, clipping rectangles, and so on. Note. Not all input devices associated with the virtual workstation will work. The input to the Open Virtual Screen Workstation function is the device handle of a currently open physical screen workstation and an environment initialization array (see "Open Workstation"). If the virtual screen workstation can be opened, a new device handle is returned for the virtual workstation. The device capabilities arrays for the physical screen workstations are returned as they are for the Open Workstation function. If the virtual screen workstation cannot be opened, a zero is returned as the device handle to indicate an unsuccessful request. Input contrl(O) Opcode = 100. contrl(l) Number of input vertices = 0. contrl(3) Length of intin = 11. contrl(6) Device handle of a previously opened screen device. intin For a description of the intin parameters required in the i n t i n a r r a y s e e Open Workstation (Opcode 1). 3-10 CEM VDI Programmer's Guide Open Virtual Screen Workstation Output corLtrl(2) Number of output vertices = 6. corLtrl(4) Length of intout = 45. corLtrl(6) The device handle for the Virtual Screen Device just opened. waining: Contrl(6) is an input/output parameter. The value is changed to that of the Virtual Screen Workstation device handle. Note: All output parameters are the s a m e as those of Open Workstation (Opcode 1). 1~ 3-11 GEM VDI Programmer's Guide Open Virtual Screen Workstation C BINDING Procedure Name v_opn,,rwk( work-in, &handle, work-out Data Types WORD i-opnvwk( WORD '-jandle; WORD work in[111, WORD work-out[57]; Input Arguments handLa = contrl[61 work-Ln[O] intin[03 work-Ln[101 intin[lol Output Arguments work-out[01 intout[O] work - :)ut[441 = intout[441 work-out[451 = ptsout[O] work-,:)ut[561 = ptsout[li] 3-12 GEM VDI Programmer's Guide Close Virtual Screen Workstation CLOSE VIRTUAL The Close Virtual Screen Workstation function SCREEN WORKSTATION texminates the virtual device and prevents any fuither output to it. Input contrl(O) Opcode = 101. contrl(l) Number of input vertices 0. contrl(3) Length of intin = 0. contrl(6) Device handle. Output contrl(2) Number of output vertices 0. contrl(4) Length of intout = 0. C BINDING Procedure Name v-clsvwk( handle Data Types WORD v -- clsvwk( WORD handle; Input Arguments handle = contrl[61 3-13 GEM VDI Programmer's Guide uiear worKszaEion CLEAR WORKSTATION The Clear Workstation function erases the screen. GEM VDI sets the screen to the currently selected background color, which is defincd as color index zero. If the device is a plotter without paper advance, GEM VDI prompts the operator to load a new page. if the device is a printer, data in the buffer is erased and a new page occurs. For a metafile, GEM VDI outputs the opcode. No output occurs for any device. Note: With GEM VDI, you do not need to do a Clear Workstation after an Open Workstation because the display is cleared at Open Workstation. Input contr.L(O) Opcode = 3. contrL(l) Number of input vertices 0. contrL(3) Length of intin = 0. contrL(6) Device handle. Output contrL(2) Number of output vertices 0. contrL(4) Length of intout = 0. C BINDING Procedure Name v-clrwk( handle Data Types WORD v - clrwk WORD 'aandle; Input Arguments handle = contrl[63 3-14 GEM VDI Programmer's Gaide Update Workstation UPDATE WORKSTATION The Update Workstation function causes all pending graphics commands to be executed immediately, in the order the commands were stored in the buffer. For printer drivers, you mu3t use this function to start output to the printer. This function has no effect on screens. Plotters execute all the commands in the buffer. When the plotter buffer is empty, it returns from the Update Workstation function. For a metafile, GEM VDI outputs the opcode. Note: The picture is drawn to the printer but no new page occurs. A Clear Workstation causes a new page. Input contri(o) Opcode = 4. contrl(l) Number of input vertices 0. contrl(3) Length of intin 0. contrl(6) Device handle. Output contrl(2) Number in output vertices 0. contrl(4) Length of intout = 0. C BINDING Procedure Name v_tipdwk( handle Data Types WORD v updwk WORD h-a-ndle; Input Arguments handle contrl[61 3-15 GEM VDI Programmer's Guide Load Fonts LOAD FONTS This finction loads the fonts associated with a particular driver in the ASSIGN.SYS file. it then nakes them available to the appropriate progra.m. GEM VDI returns the number of newly generated font identifiers. If the fonts were already available to the workstation, no action occurs, and GEM VDI returns a zero for the number of addit~.onal font identifiers. Aote: You do not need to invoke this function if the default system fonts for a particular driver are sufficient. Input contr]-(0) Opcode = 119. contr:.(l) Number of input vertices = 0. contr:.(3) Length of intin array = 1. contrl.(6) Device handle. intinIO) Reserved for future use = 0. Output contr".L(2) Number of output vertices 0. contr'L(4) Length of output array = intoul:(O) Number of additional font identifiers. C BINDING Procedure Name additional vst-load-fonts( handle, select Data Types WORD irst load-fonts( -~tional: WORD addi WORD handle, WORD ~Belect, Input Arguments handle = contrl[61 select = intin[01 Output Arguments additLonal = intout[03 3-16 GEM VDI Programmer's Gaide Unload Fonts UNLOAD FONTS This function logically dissociates the external fonts loaded by the Load Fonts function from a device and unloads them from memory, if possible. A device handle is passed into the function identifying the device whose external fonts are to be unloaded. If the fonts are being shared by other virtual workstations with the same root device handle, the fonts are not unloaded from memory until one of the following conditions is met: * all workstations that share the fonts are closed * all workstations that share the external ::onts request that the external fonts be Unloaded The default system fonts for the workstation renain loaded and available. Input coritrl(O) Opcode = 120. coritrl(l) Number of input vertices = 0. corLtrl(3) Length of intin array = 1. corttrl(6) Device handle. int.in(O) Reserved for future use. Output cor.trl(2) Number of output vertices = 0. contrl(4) Length of intout array = 0. GEM VDI Programmer's Guide Unload Fonts C BINDING Procedure Name vst-unload-fonts( handle, select ) -"%. Data Types WORD vst unload-fonts( ); WORD handle; WORD select; Input Arguments handle = contrl[61 select = intin[O] 3-18 GEM VDI Programmer's Guide Set Clipping Rectangle SET CLIPPING This function enables or disables clipping of RECTANGLE all output primitives by GEM VDI. Intin (0) is a flag, which if nonzero, enables clipping. The ptsin array contains the rectangle, specified in the current coordinate system, to clip to. If intin(O) is zero, clipping is turned off. The default at Open Workstation is for clipping to be disabled. Input contrl(O) opcode = 129. contrl(l) Number of input vertices = 2. contrl(3) Length of intin array = 1. contrl(6) Device handle. intin(O) Clipping flag. 0 = Turn clipping off. non-zero = Turn clipping on. ptsin(O) x-coordinate of corner of the clipping rectangle in NDC/RC units. ptsin(l) y-coordinate of corner of the clipping rectangle in NDC/RC units. ptsin(2) x-coordinate of corner diagonally across from the corner selected in ptsin(O) of the clipping rectangle in NDC/RC units. ptsin(3) y-coordinate of corner diagonally across from the corner selected in ptsin(l) of the clipping rectangle in NDC/RC units. GEM VDI Programmer's Guide Set Clipping Rectangle C BINDING Prc>cedure Name vs_clip( handle, clip_flag, pxyarray Data Types WORD vs_clipo; WORD handle; WORD clip_flag; WORD pxyarray[41; Input Arguments handle = contrl[61 clip-flag = intin[01 pxyarray[o] = ptsin[01 pxyarray[l] = ptsin[ll pxyarray[21 = ptsin[21 pxyarray[31 = ptsin[31 End of Section 3 I--, 3-20 Section 4 Output Functions INTRODUCTION The output functions display graphics primitives (polyline or circle, for example) on devices. POLYLINE This function displays a polyline on the graphics device. The starting point for the polyline is the first point in the input array. Lines are drawn between subsequent points in the array. GEM VDI displays a zero length line (degenerate case) as a point. GEM VDI will not display a single coordinate pair. Lines are drawn using the following current line attributes: • color • linetype • line width • end style • carrent writing mode For wide lines, the first point (ptsin (0) ptsin(l)) is drawn as shown in Figure 4-1. )Figure 4-1. First Point for Wide Lines GEM VDI Programmer's Guide Polyline Input contrl(O) Opcode = 6. contrl(l) Number of vertices (x,y pairs) in polyline = n. (Maximum number is returned in Extended inquire.) contrl(3) Length of intin array = 0. contrl(6) Device handle. ptsin Array of coordinates of polyline in NDC/RC units. ptsin(O) x-coordinate of first point in NDC/RC units. ptsin(l) y-coordinate of first point in NDC/RC units. ptsin(2) x-coordinate of second point in NDC/RC units. ptsin(3) y-coordinate of second point in NDC/RC units. ptsin(2n-2) x-coordinate of last point in NDC/RC units. ptsin(2n-1) y-coordinate of last point in NDC/RC units. Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 0. 4-2 GEM VDI Programmer's Guide voiyilne C BINDING Procedure Name v-pline( handle, count, pxyarray Data Types WORD v_pline WORD handle; WORD count; WORD pxyarray[2 * count]; Input Arguments handle contrl[6) count contrl[ll pxyarray[O] = ptsin[01 pxyarray[l] = ptsin[l] pxyarray[2n-21 = ptsin[2n-2) pxyarray[2n-1] = ptsin[2n-11 4-3 UEM VDI Programmer's Guide Polymarker POLYMARKER This function draws markers at the points specified in the input array. GEM VDI displays the markers using the current marker attributes: • color • scale • type • writing mode Input contrl(O) Opcode = 7. contrl(l) Number of markers = n. (Maximum number is returned in Extended Inquire.) contrl(3) Length of intin array = 0. contrl(6) Device handle. ptsin Array of coordinates in NDC/RC units. ptsin(O) x-coordinate of first marker in NDC/RC units. ptsin(l) y-coordinate of first marker in NDC/RC units. ptsin(2) x-coordinate of second marker in NDC/RC units. ptsin(3) y-coordinate of second marker in NDC/RC units. ptsin(2n-2) x-coordinate of last marker in NDC/RC units. ptsin(2n-1) y-coordinate of last marker in NDC/RC units. Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 0. 4-4 GEM VDI Programmer's CULde C BINDING Procedure Name v_pinarker( handle, count, PxYarray Data Types WOPJ) v_pmarker WORD handle; WORD count; WORD pxyarray[2 count); Input Arguments handle contrl[61 count contrlilj pxyarray[O] = ptsin[Ol pxyarray[l) = ptsin[l] pxyarray[2n-21 = ptsin[2n-2] pxyarray[2n-l] = ptsin[2n-1) uzm vui Programmer's Guide ext TEXT This function writes graphic text to the display surface. The (x,y) position specified by the application program is the alignment point of the text string. The Set Graphic Text Alignment function establishes the relationship between the starting point of the string and the specified x,y position. The default alignment is the left baseline position of the text string. Refer to the Set Graphic Text Alignment function in Section 5 for an illustration of alignment points. Each word of the intin array contains one character in bits 0-7. Any unsupported character is mapped to a symbol for an undefined character. Input contrl(O) Opcode = 8. contrl(l) Number of input vertices = 1. contrl(3) Length of intin array = n. contrl(6) Device handle. intin Character string as ASCII codes in 16-bit words. The maximum number o f characters equals the size of the intin array. See Extended Inquire. ptsin(O) x-coordinate of alignment point of text in NDC/RC units. ptsin(l) y-coordinate of alignment point of text in NDC/RC units. Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 0. GEM VDI Programmer's (luide TUXL C BINDING Procedure Name v_gtext( handle, x, y, string Data Types WORD v_gtext WORD handle; WORD x; WORD y; BYTE string [ n] Input Arguments handle = contrl[61 x = ptsin[01 y = ptsin[l] string = intin Note: Bytes for the string array are mapped int:) the eight least significant bits of intin. The string must be null-terminated. UEM VDI Programmer's Guide Filled Area FILLED AREA This function fills a complex (for example, self -intersecting) polygon specified by the input array. The area is filled using the following current attributes: fill area color interior style (hollow, solid, pattern, hatch or user-defined) writing mode style index The area is outlined with a solid line of the current fill area color if the fill area perimeter visibility is on, which is the default at Open Workstation. See the Set Fill Perimeter Visibility function in Section 5. If a device does not have area fill capability, GEM VDI outlines the polygon using the current fill area color. The device driver ensures that the fill area is closed by connecting the first point to the last point. GEM VDI displays a polygon with zero area as a dot. If outline isn't turned on, the degenerate case isn't displayed as a dot. GEM VDI does not display a polygon with only one endpoint. The maximum number of filled area vertices may be determined with the Extended Inquire function. 4-8 GEM VDI Programmer's Gulde ril-LUU ftL~a Input contrl(O) Opcode = 9. contrl(l) Number of vertices in polygon n. Maximum number returned in Extended Inquire. contrl(3) Length of intin array = 0. contrl(6) Device handle. ptsin Array of coordinates of polygon in NDC/RC units. ptsin(O) x-coordinate of first point in NDC/RC units. ptsin(l) y-coordinate of first point in NDC/RC units. ptsin(2) x-coordinate of second point in NDC/RC units. ptsin(3) y-coordinate of second point in NDC/RC units. ptsin(2n-2) x-coordinate of last point in NDC/RC units. ptsin(2n-1) y-coordinate of last point in NDC/RC units. Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 0. 1~ GEM VDI Programmer's Guide Filled Area C BINDING Procedure Name v-fillarea( handle, count, pxyarray Data Types WORD v fillarea WORD handle; WORD count; WORD pxyarray[2 count]; Input Arguments handle contrl[61 count contrl[lj pxyarray[O] = ptsin[01 pxyarray[l) = ptsin[l] p;yarray[2n-2] = ptsin[2n-2) pxyarray[2n-11 = ptsin[2n-1) 4-10 MM V51 Programmer's Guide CL&II Arfay CELL ARRAY With the Cell Array function, the device draws a rectangular array defined by the input parameter (x,y) coordinates and the color index a r r a y . The lower left and upper right coordinates define the extent of the rectangle. GEM VDI divides the rectangle into cells based on the number of rows and columns specified as input parameters. The color index array specifies the color for each cell. Each cell of the rectangle is mapped to pixels on the display surface. The pixel takes the color of the cell that covers its center. If the device does not support cell arrays, the device outlines the area with a solid line in the current line color and line width. Note: This function is not required and may not be available on all devices. Input contrl(O) Opcode = 10. contrl(l) Number of input vertices = 2. contrl(3) Length of color index array. contrl(6) Device handle. con trl (7) Length of each row in color index array (size as declared in a high-level language). contrl(8) Number of elements used in each row of color index array. contrl(9) Number of rows in color index array. contrl(10)-- Pixel operation to be performed. (See Set Writing Mode function i n S e c t i o n 5 f o r t h e description of each mode.) intin(O) Color index array, stored by row. ptsin(O) x-coordinate of lower left corner in NDC/RC units. ptsin(l) y-coordinate of lower left corner in NDC/RC units. ptsin(2) x-coordinate of upper right corner in NDC/RC units. ptsin(3) y-coordinate of upper right corner in NDC/RC units. U-1 VLJ1 X LkJkJLC111UUUL b UUJUe cell Array Output contrl(2) Number of output vertices = 0. contrl(4) Length of intin array = 0. .C BINDING Procedure Name v_cellarray( handle, pxyarray, row length, el-used, num-rows, wrt-mode, co-larray Data Types WORD v - cellarray( WORD handle; WORD pxyarray[4); WORD row length; WORD el used; WORD num_rows; WORD wrt mode; WORD colarray[num-rows*el-used]; Input Arguments handle = contrl[61 pxyarray(O] = ptsine[O) pxyarray[l] = ptsin[l) pxyarray[21 = ptsin[21 pxyarray[31 = ptsin[31 row length = contrl[71 el used contrl[S] num_rows contrl[91 wrt mode contrl[10] colarray[O] = intin[O) colarray[n] = intin[n] 4-12 GEM VDI Programmer's Guide Contour Fill CONTOUR FILL This function fills an area until it finds either the edges of the display surf-ace or the color index stated in intin(O). This function is sometimes called a seed fill or a flood fill. If intin(O) is negative, the algorithm searches for any color other than the color of the seed point. GEM VDI fills the area using the current fill area attributes. Note: This function is not required and may not be available on all devices. Input contrl(O) Opcode = 103. contrl(l) Number of input vertices = 1. contrl(3) Length of intin array = 1. contrl(6) Device handle. intin(O) Color index that defines the contour. ptsin(O) x-coordinate of starting point in NDC/RC units. ptsin(l) y-coordinate of starting point in NDC/RC units. Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array 0. C BINDING Procedure Name v-contourfill( handle, x, y, index Data Types WORD v contourfill( WORD handle; WORD x; WORD y; WORD index; Input Arguments handle = contrl[6] x = ptsin[O] y = ptsin[l) index = intin[01 4-13 UL~wl Vul FLUYLciffillIUL -S Uulue Pill Rectangle FILL RECTANGLE This function fills a rectangular area with the pattern defined by the current fill area attributes. The rectangle is filled using all fill area attributes except outline. Input contrl(O) Opcode = 114. contrl(l) Number of input vertices = 2. contrl(3) Length of intin array = 0. contrl(6) Device handle. ptsin(O) x-coordinate of corner of destination rectangle in RC/NDC. ptsin(l) y-coordinate of corner of destination rectangle in RC/NDC. ptsin (2) x-coordinate of corner of destination rectangle in RC/NDC diagonally opposite corner specified in ptsin(O). ptsin(3) y-coordinate of corner of destination rectangle in RC/NDC diagonally opposite corner specified in ptsin(l). Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 0. C BINDING Procedure Name vr-recfl( handle, pxyarray Data Types WORD vr recfl WORD handle; WORD pxyarray[4); Input Arguments handle = contrl[6] pxyarray[O] = ptsin[O) pxyarray[31 = ptsin[3] 4-14 GEM VDI Programmer's Guide LAW GENERALIZED The Generalized Drawing Primitive (GDP) DRAWING PRIMITIVE function allows you to use the predefined (GDP) primitives. The application can draw special elements, such as arcs, circles, and ellipses using this function. The contents of the control and data arrays are different for each GDP. For the arc, pie, elliptical arc, and elliptical pie, the information in the radius, start, and end angle variables defines the GDP. All angle specifications are in tenths of degrees and assume that 0 degrees is 90 degrees to the right of vertical, wi th values increasing in the counterclockwise direction. Arcs are drawn counterclockwise. All radius specifications except for ellipse and elliptical arc, assume an extent (distance) in the x-axis. Ellipse and elliptical arc use both x and y radius values. Refer to Figure 4 2. 900 1800 0 2700 Figure 4-2. Angle Specification Input contrl(O) Opcode = 11. contrl(l) Number of vertices in ptsin. contrl(3) Length of input array intin. contrl(5) Primitive id. 1 BAR: Uses fill area attributes (fill interior style, style index, wr iting mode , color and perimeter style). 4 CIRCLE: Uses fill area attributes (fill interior style, style index, writing mode, fill color and perimeter style). 4-15 GEM VDI Programmer's auide GDP 2 ARC: Uses line attributes (color, linetype, writing mode, width, and end styles). 3 PIE: Uses fill area attributes (interior style, writing mode, fill style, fill color, and perimeter style). 5 ELLIPSE: Uses fill area attributes (fill interior style, writing mode, s t y 1 e i n d e x , c o 1 o r , and perimeter style). 6 ELLIPTICAL ARC: Uses line attributes (color, linetype, writing mode, width, and end styles). 7 ELLIPTICAL PIE: Uses fill area attributes (fill interior style, writing mode, s t y 1 e i n d e x , c o I o r and perimeter style). 8 ROUNDED RECTANGLE: Uses line attributes (color, linetype, writing mode, and width). 9 FILLED ROUNDED RECTANGLE: Uses fill area attributes (fill interior style, writing mode, s t y 1 e i n d e x color , and perimeter style, color, and width). 10 JUSTIFIED GRAPHICS TEXT: Uses text attributes (face, character height, character baseline vector, color index, s p e c i a 1 e f f e c t s , a n d alignment). contrl(6) Device handle. ptsin Array of coordinates for GDPs in NDC/RC units. ptsin(O) x-coordinate of first point in NDC/RC units. ptsin(l) y-coordinate of first point in NDC/RC units. ptsin(2) x-coordinate of second point in NDC/RC units. 4-16 GEM VDI Programmer's Guide GDP ptsin(3) -- y-coordinate of second point in NDC/RC units. ptsin(2n-2) x-coordinate of last point in NDC/RC units. ptsin(2n-1) y-coordinate of last point in NDC/RC units. intin Angle for arcs and pies or characters f o r justified graphics text. 4-17 GEM VDI Programmer's Guide BAR BAR Input contrl(O) Opcode = 11. contrl(l) Number of input vertices = 2. contrl(3) Length of intin array = 0. contrl(5) Primitive id = 1. contrl(6) Device handle. ptsin(O) x-coordinate of corner of bar in NDC/RC units. ptsin(l) y-coordinate of corner of bar in NDC/RC units. ptsin(2) x-coordinate o f corner diagonally opposite the corner selected in ptsin(O) of bar in NDC/RC units. ptsin(3) y-coordinate o f corner diagonally opposite the corner selected in ptsin(l) of bar in NDC/RC units. Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array 0. C BINDING Pr(>cedure Name v-bar( handle, pxyarray Data Types WORD v bar ( ); WORD h-andle; WORD pxyarray[41; Input Arguments handle = contrl[6] pxyarray[O] = ptsin[01 pxyarray[l) = ptsin[l] pxyarray[2) = ptsin[21 pxyarray[31 = ptsin[31 4-18 GEM VDI Programmer's Guide ARC & PIE ARC & PIE These functions are not required and may not be available on all devices. GEM VDI requires the specification of the arc by the angle (intin(O),intin(l)). Input contrl(O) Opcode = 11. contrl(l) Number of input vertices = 4. contrl(3) Length of intin array = 2. contrl(5) Primitive id. 2 = ARC 3 = PIE contrl(6) Device handle. intin(O) Start angle (in tenths of degrees 0-3600), counterclockwise. intin(l) End angle (in tenths of degrees 0-3600) . ptsin(O) x-coordinate of center point of arc in NDC/RC units. ptsin(l) y-coordinate of center point of arc in NDC/RC units. ptsin(2) 0. ptsin(3) 0. ptsin(4) 0. ptsin(5) 0. ptsin(6) Radius in x-coordinate NDC/RC units. ptsin(7) 0. Output contrl(2) Number of output veitices = 0. contrl(4) Length of intout array = 0. 4-19 GEM VDI Programmer's Guide Amf- & rL C BINDING Procedure Name v-arc( handle, x, y, radius, begang, endang v_pieslice( handle, x, y, radius, begang, endang ) Data Types WORD v arc WORD handle; WORD x, y; WORD radius; Input Arguments handle = contrl[61 x = ptsin[O) y = ptsin(l) radius = ptsin[61 begang = intin[01 endang = intinfl] U1JV1 V U I I LUY L U1111iieL 5 k5U I ULT L, i RULL CIRCLE This function is not required and may not be supported on all devices. Input contrl(O) Opcode = 11. contrl(l) NumDer of input vertices = 3. contrl(3) Length of intin array = 0. contrl(5) Primitive id = 4. contrl(6) Device handle. ptsin(O) x-coordinate of center point of circle in NDC/RC units. ptsin(l) y-coordinate of center point of circle in NDC/RC units. ptsin(2) 0. ptsin(3) 0. ptsin(4) Radius in x-coordinate NDC/RC units. ptsin(5) 0. Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 0. C BINDING Procedure Name v-circle( handle, x, y, radius Data Types WORD v circle WORD handle; WORD x, y; WORD radius; Input Arguments handle = contrl[6] x = ptsin[O] y = ptsin[l) radius = ptsin[4] GEM VDI Programmer's Guide ELLIPTICAL ARC and PTE ELLIPTICAL ARC AND PIE Input contrl(O) Opcode = 11. contrl(l) Number of input vertices = 2. contrl(3) Length of intin array = 2. contrl(5) Primitive id. 6 = ELLIPTICAL ARC 7 = ELLIPTICAL PIE SLICE contrl(6) Device handle. intin(O) Start angle (in tenths of degrees 0-3600), counterclockwise. intin(l) End angle (in tenths of degrees 0-3600). ptsin(O) x-coordinate of center point of arc in NDC/RC units. ptsin(l) y-coordinate of center point of arc in NDC/RC units. ptsin(2) Radius of X-axis in NDC/RC units. ptsin(3) Radius of Y-axis in NDC/RC units. Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 0. 4-22 I GEM VDI Programmer's Guide ELLIPTICAL ARC and PIE C BINDING Procedure Name v_ellarc( handle, x, y, xradius, yradius, begang, endang ) v_ellpie( handle, x, y, xradius, yradius, begang, endang Data Types WORD v ellarc WORD v ellpie WORD handle; WORD x, y; WORD xradius; WORD yradius; WORD begang; WORD endang; Input Arguments handle = contrl[6] x = ptsin[Ol y = ptsinfl] xradius = ptsin[21 yradius = ptsin[3] begang = intin[01 endang = intin[l] 4-23 GEM VDI Programmer's Guide ELLIPbE ELLIPSE Input contrl(O) Opcode = 11. contrl(l) Number of input vertices = 2. contrl(3) Length of intin array = 0. contrl(5) Primitive id = 5. contrl(6) Device handle. ptsin(O) x-coordinate of center point of ellipse in NDC/RC units. ptsin(l) y-coordinate of center point of ellipse in NDC/RC units. ptsin(2) Radius of X-axis in NDC/RC units. ptsin(3) Radius of Y-axis in NDC/RC units. Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 0. C BINDING Procedure Name v_ellipse( handle, x, y, xradius, yradius Data Types WORD v ellipse WORD handle; WORD x, y; WORD xradius; WORD yradius; Input Arguments handle = contrl[61 x = ptsin[01 y = ptsinfl] xradius = ptsin[2) yradius = ptsin[31 4-24 GEM VDI Programmer's Guide Rounded and Filled Rounded Rectangle ROUNDED AND FILLED A rectangle with rounded corners iS Output to ROUNDED RECTANGLE the workstation. The rectangle is defined by specifying its lower left and upper right corners. The Rounded Rectangle GDP assumes the attributes of a polyline primitive. The Filled Rounded Rectangle GDP assumes the attributes of a filled area primitive. Input contrl(O) Opcode = 11. contrl(l) Number of input vertices = 2. contrl(3) Length of intin array = 0. contrl(5) Primitive id. 8 = Rounded Rectangle 9 = Filled Rounded Rectangle contrl(6) Device handle. ptsin(O) x-coordinate of corner of rectangle in NDC/RC units. ptsin(l) y-coordinate of corner of rectangle in NDC/RC units. ptsin(2) x-coordinate of corner diagonally opposite corner selected in p t s i n ( 0 ) of rectangle in NDC/RC units. ptsin(3) y-coordinate of corner diagonally opposite corner selected in ptsin (1) of rectangle in NDC/RC units. Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 0. 4-25 GEM VDI Programmer's Guide Rounded and Filled Rounded Rectangle C BINDING Procedure Name v - rbox( handle, xyarray v-rfbox( handle, xyarray) Data Types WORD v rbox WORD v rfbox WORD han'jle; WORD xyarray[4]; Input Arguments handle = contrl[61; attributes = intin[O); xyarray[Ol = ptsin[O); xyarrayfl) = ptsin[l]; xyarray[2) = ptsin[2]; xyarray[31 = ptsin[31; 4-26 I GEM VDI Programmer's Guide Justified Graphics Text JUSTIFIED GRAPHICS This function outputs graphics text to the TEXT workstation display surface and attempts to perform both left and right justification. The text string is aligned at the requested string alignment points passed in, using the current text alignment attributes. Extra spacing may be inserted or deleted by the driver between words or characters (or both) so that the string will have the requested length. Either form of spacing modification (inter character or inter-word) can be suppressed by so specifying in the provided parameter. Input contrl(O) Opcode = 11. contrl(l) Number of input vertices = 2. contrl(3) Length of intin array = 2 + n (characters in string). contrl(5) Primitive id = 10. contrl(6) Device handle. intin(O) Inter-word spacing flag. 0 = Doesn't allow GEM VDI to modify inter-word spacing. nonzero = Allows GEM VDI to modify inter-word spacing. intin(l) Inter-character spacing flag. 0 = Doesn't allow GEM VDI to modify inter-character spacing. nonzero = Allows GEM VDI to modify inter-character spacing. intin(2) First character of text string. intin(n+l) Last char;cter of text string. 4-27 GEM VDI Programmer's Guide Justitlea urapnics IUAL ptsin(O) x-coordinate of the text alignment point, in NDC/RC units. ptsin(l) y-coordinate of the text alignment point, in NDC/RC units. ptsin(2) Requested length of the string, in x-axis NDC/RC units. ptsin(3) 0. Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 0. 4-28 GEM VDI Programmer's Guide Justified Graphics Text C BINDING Procedure Name v_justified(handle, x, y, string, length, word_space, char-space); Data Types WORD v_justifiedo; WORD handle; WORD x, y; WORD length; WORD word space; WORD char space; BYTE string[); Input Arguments handle = contrl[61; x = ptsin[O]; y = ptsin[l]; length = ptsin[2); word_space = intin[01; char-space = intin[l]; string[j] = intin[j+21; Note: Bytes for the string array are mapped into the eight least significant bits of intin words. Note: The string array must be null terminated. End of Section 4 1-11 4-29 110%, Section 5 Attribute Functions INTRODUCTION Attribute functions determine qualities of all subsequent output primitives such as color, type, style, and height. SET WRITING MODE This function selects the writing mode used for subsequent drawing operations. The writing mode specifies the operation performed between the color indices of the current pixel (source) and the existing pixel (destination), thus affecting the way new pixels from lines, markers, filled areas, and text are placed on the display. Four modes exist: replace, transparent, XOR, and reverse transparent. If the requested writing mode is out of range, GEM VDI selects replace mode, 1. Table 5-1 lists the writing modes and their numerical assignments. Table 5-1. Writing Modes Number Mode 1 Replace 2 Transparent 3 XOR 4 Reverse Transparent GEM VDI Programmer's Guide Set Writing Mode For the Boolean expressions of the modes given below, the definitions in Table 5-2 apply. Table 5-2. Terms Term Definition mask line style or fill pattern fore selected color after mapping from GEM VDI back color 0 after mapping from GEM VDI (white is default) old current color value new replacement color value Replace Replace mode is insensitive to the currently displayed image. Any information already displayed is replaced. The following is the Boolean expression for replace mode: new = (fore AND mask) OR (back AND NOT mask) Transparent Transparent mode only affects the pixels where the mask is 1. These are changed to the fore value. The following is the Boolean expression for transparent mode: new = (fore AND mask) OR (old AND NOT mask) XOR XOR mode reverses the bits representing the color. The following is the Boolean expression for XOR mode: new = mask XOR old 5-2 uzm vui erogrammer-s Uuide Set Writing Mode Reverse Reverse transparent mode only affects the Transparent pixels where the mask is 0. These are changed to the fore value. The following is the Boolean expression for reverse transparent mode: new = (old AND mask) OR (fore AND NOT mask) Input contrl(O) Opcode = 32. contrl(l) Number of input vertices = 0. contrl(3) Length of intin array = 1. contrl(6) Device handle. intin(O) Writing mode requested. Output contrl(2) Number of output vertices 0. contrl(4) Length of intout array intout(O) Writing mode selected. C BINDING Procedure Name set-mode = vswr-mode( handle, mode Data Types WORD set mode; WORD vswr-mode WORD handle; WORD mode; Input Arguments handle = contrlE61 mode = intinE03 Output Arguments set-mode = intout[01 GEM VDI Programmer's Guide Zziet t.;O.Lor mepiebtiiit-aL~,. SET COLOR This function associates a color index with REPRESENTATION the color specified in RGB (Red, Green, Blue) units. On a monochrome device, GEM VDI maps any percentage of color to white. GEM VDI maps any color intensity of a value less than 0 to 0 and greater than 1000 to 1000. If the application requests a color index that is out of range, GEM VDI performs no operation. GEM VDI references the background color as color index zero. Note: If no color lookup table exists, GEM VDI performs no operation with this function. The Extended Inquire function returns the availability of the lookup table. Input contrl(O) Opcode = 14. contrl(l) Number of input vertices = 0. contrlM Length of intin array = 4. contrl(6) Device handle. intin(O) Color index. intin(l) Red color intensity (in tenths of percent, 0-1000). intin(2) Green color intensity. intin(3) Blue color intensity. Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 0. GEM VDI Programmer's Guide Set Color Representation C BINDING Procedure Name vs-color( handle, index, rgb_in Data Types WORD vs - color WORD haj~dle; WORD index; WORD rgb_inL3]; Input Arguments handle contrl[61 index intin[01 rgb_in[Ol = intin[l] rgb-in[l] = intin[21 rgb_in[21 = intinE31 5-5 9-s 1~ - apom BUTITIM alq-4 Of)Ul2qD AIPM PUle a-IA-4S allT-[ PTTOS ,e 6uisn auTT pauq)(DTqq eq-4 meap AvM 83TA9P aq4 'Pasn sT qIPT14 9U-El -4TneJ8PuOu 2 ;1 :@%ON -4T 88UT;OP jasn aqq jTjun pTTos oq s-41np;ap uja-4-4pd sTLU -SaUTJaP UOT-4Dunj U-1944Rd 9TA-4S ouTl pauijap-jasrl -49S aq-4 u.Ta-4-4ed aq-4 sasn 'aTA-4s paut;ap-jasn 'UaAaS alA4S 9UT11 quapuadep -paAelds-Ep -aDTAOP U-8 laxid lsji; = ITS 4URDT;TU~Ts Isow 0-[1,4s (paom 1) sqTq 91 PaUT;ap-iasn L OOOTTOOTTOOOTTIT IOP'IOP'qsgP 9 OOOOOOOOITTITTIT qsRp s OOOTTTOOOTTITTTT -40P,qsep t, OOOOOITTOOOOOTTT -40P c OOOOTITTTTTTTTTT qSVP BUOT z ITUTITTITITITIT PTTOS T Usli asw aTA-49 SITE[ 9T *J;0 TaxTd '(9AT431e) UO TOxTd I st pxom uja-4:tled aq-4 uE onlieATOXTCT atu -a-EA-4s 9UTT (T) PTTOS 9'4z)aT9s IGA W30 '96UR-1 jo qno sl 8TX4s OuTT palsenbax aq-4 ;I qsleaT -4,e -4.aoddns sODTAap I-Ele '4nq lquopuadep -aOTAap ST aTqle-[TleAp seTA-4s auTT ;o iaqmnu TU-40-4 aqL -SUOT-4v:xado au-ETATod quanbasqns HdJU 2NIl jo; adA4 auTT a q-4 S-4as uoT-4Dun; STtLL 3MIrUTOd JS9 -4X~ QITT" allTTATOA laq apTnE) s,jammviBoad ICIA W3E) GEM VDI Programmer's Guide Set Polyline Line Type Input contrl(O) Opcode = 15. contrl(l) Number of input vertices = 0. contrl(3) -7 Length of intin array = 1. contrl(6) -- Device handle. intin(O) Requested line style. Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 1. intout(O) Line style selected. C BINDING Procedure Name set_type = vsl_type( handle, style Data Types WORD set_type WORD vsl type WORD handle; WORD style; Input Arguments handle contrl[61 style intin[01 Output Arguments set_type = intout[01 GEM VDI Programmer's Guide Set User-defined Line Style Pattern SET USER-DEFINED This function sets the current user-defined LIKE STYLE PATTERN line style pattern word in the device driver to the value in the specified 16-bit pattern word. The Most Significant Bit (MSB) of the pattern word is the first pixel in the line. This line style is used for subsequent polyline operations when the application selects user defined line style, index 7. Input contri(o) Opcode = 113. contrl(l) Number of input vertices = 0. contrl(3) Length of intin array = 1. contrl(6) Device handle. intin(O) Line style pattern word, 16 bits. Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 0. C BINDING Procedure Name vsl_udsty( handle, pattern Data Types WORD vsl - udsty WORD handle; WORD pattern; Input Arguments handle contrl[61 pattern intin[01 5-8 GEM VDI Programmer's Guide Set Polyline Line Width SET POLYLINE LINE This function sets the width of lines for WIDTH subsequent polyline operations. The available line width closest to but not greater than the requested line width is used. Line widths are odd numbers that begin at three. If you select two in Raster Coordinates, GEM VDI returns one, which is a line one pixel wide. Note: This function is not required and may not be available on all devices. Thickened lines may be rendered on the device using solid line type, rather than a requested line type. Input contrI(O) Opcode = 16. contrl(l) Number of input vertices = 1. contrl(3) Length of intin array = 0. contrl(6) Device handle. ptsin(O) Requested line width in x-axis in NDC/RC units. ptsin(l) 0. Output contrl(2) Number of output vertices = 1. contrl(4) Length of intout array = 0. ptsout(O) Selected line width in x-axis of the NDC/RC units. ptsout(l) 0. 5-9 GEM VDI Programmer's Guice C BINDING Procedure Name set-width = vsl-width( handle, width Data Types WORD set width; WORD vsl width; WORD hanile; WORD width; Input Arguments handle contrl[61 width ptsin[Ol Output Arguments set-width = ptsout[O] 5-10 1 SET POLYLINE This function sets the color index for COLOR INDEX subsequent polyline operations. The Set Color Representation function determines the color the index represents. At least two color indices, 0 and 1, are supported (monochrome). Color indices range from 0 to a device dependent maximum. If the application requests an index that is out of range, GEM VDI selects color index 1. Input contrl(O) Opcode = 17. contri(l) Number of input vertices = 0. contrl(3) Length of intin array = 1. contrl(6) Device handle. intin(O) Requested color index. Output contrl(2) Number of output vertices 0. contrl(4) Length of intout array intout(O) Color index selected. C BINDING Procedure Name set-color vsl-color( handle, color-index Data Types WORD set - color; WORD vsl color WORD han-dle; WORD color-index; Input Arguments handle = contrl[61 color-index = intin[03 Output Arguments set-color = intout[OJ 5-11 GEM VDI Programmer's Guide ru.LYL~11= -"- SET POLYLIKE END This function sets the style for the ends of STYLES a polyline. The style may be any of the following: 0 squared (default) 1 arrow 2 rounded The two ends of a polyline may have different styles. If an invalid style is requested, a squared end style (0) is used. Both the squared style and the arrow style end at the end of the polyline. The rounded style is drawn such that the center of the rounding is at the end of the polyline. Input contrl(O) Opcode = 108. contrl(l) Number of input vertices = 0. contrl(3) Length of intin array = 2. contrl(6) Device handle. intin(O) End style for beginning point of polyline. 0 - squared (default) 1 - arrow 2 - rounded intin(l) -- End style for ending point of polyline. 0 - squared (default) 1 - arrow 2 - rounded Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 0. 5-12 1 -, - ~LUYLZjjjjJ(jteL 6 kujue bet Polyline End Styles C BINDING Procedure Name vsl-ends( handle, beg_style, end_style Data Types WORD vsl endso; WORD handle; WORD beg_style; WORD end-style; Input Arguments handle = contrl[61; beg_style = intinE03; end_style = intin[l]; 5-13 uLm vui Yrogrammer s uuiue SET POLYMARKER This function sets the marker type for TYPE subsequent polymarker functions. The total number of markers available is device dependent, but GEM VDI always defines at least six marker types: I - . Dot 2 - + Plus 3 - * Asterisk 4 - o Square 5 - X Diagonal Cross 6 - <> Diamond 7 n Device-dependent If the requested marker type is out of range, GEM VDI uses an asterisk, type 3. Marker I is the smallest dot GEM VDI displays on the device; it cannot be scaled. Input contrl(O) Opcode = 18. contrl(l) Numbers of input vertices = 0. contrl(3) Length of intin array = 1. contrl(6) Device handle. intin(O) Requested polymarker type. Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 1. intout(O) Polymarker type selected. C BINDING Procedure Name set_type = vsm type( handle, symbol Data Types WORD set_type; WORD vsm type WORD handle; WORD symbol; Input Arguments handle = contrlE61 symbol = intin[O] Output Arguments set_type = intoutE03 5-15 uf.m viii rz.L)9LUUULU:!.L a "U~UC - - - - - . - I SET POLYMARKER This function sets a polymarker height for HEIGHT subsequent polymarker functions. I f the selected height does not exist, GEM VDI selects the next smaller height. The driver returns the actual height selected in the ptsout array. Input contri(o) Opcode = 19. contrl(l) Number of input vertices contrl(3) Length of intin array = 0. contrl(6) Device handle. ptsin(O) 0. ptsin(l) Requested polymarker height in y-axis in NDC/RC units. Output contrl(2) Number of output vertices contrl(4) Length of intout array = 0. ptsout(O) Polymarker width selected in x axis in NDC/RC units. ptsout(l) Polymarker height selected in y axis in NDC/RC units. C BINDING Procedure Name set-height = vsm-height( handle, height Data Types WORD set-height; WORD vsm height WORD han-dle; WORD height; Input Arguments handle = contrl[61 height = ptsin[l] Output Arguments set-height = ptsout[l] 5-16 SET POLYMARKER This function sets the color index for COLOR INDEX subsequent polymarker functions. The Set Color Representation function specifies the value of the index. At least two color indices are always supported (monochrome). If the index is out of range, GEM VDI selects color index 1. Input contrl(O) Opcode = 20. contri(l) Number of input vertices = 0. contrl(3) Length of intin array = 1. contrl(6) Device handle. intin(O) Requested polymarker color index. Output contrl(2) number of output vertices = 0. contrl(4) length of intout array = 1. intout(O) Polymarker color index selected. C BINDING Procedure Name set-color vsm-color( handle, color-index Data Types WORD set - color; WORD vsm color WORD handle; WORD color-index; Input Arguments handle = contrl[61 color-index = intin[01 Output Arguments set-color = intout[01 UrAn VLJ.L rLL)qLat~t=& SET CHARACTER This function sets the current graphic text HEIGHT, character height in NDC/RC units, The ABSOLUTE 140DE specified height is the distance from the character baseline to the top of the character cell, rather than the character cell height. GEM VDI returns the selected height and width information to the application. GEM VDI returns both the distance from the baseline to top line selected and the size of a character cell. (See Figure 5-1 under "Set Character Height, Points Mode.") For fixed (monospaced) faces GEM VDI returns the width of a character and the width of a character cell. For proportional faces, GEM VDI returns the width of the widest character and the width of the widest character cell in the face. If the desired character height does not map exactly to a device size, GEM VDI selects the closest character size that does not exceed the requested size. Input contrl(O) Opcode = 12. contrl(l) Number of input vertices contrl(3) Length of intin array = 0. contrl(6) Device handle. ptsin(O) 0. ptsin(l) Requested character height in NDC/RC units. Output contrl(2) Number of output vertices = 2. contrl(4) Length of intout array = 0. ptsout(O) Character width selected in NDC/RC units. ptsout(l) Character height selected in NDC/RC units. ptsout(2) Character cell width in NDC/RC units. ptsout(3) Character cell height in NDC/RC units. 5-18 I --i - ~iugiammer s Uu1cle Set Character Height, Absolute Mode C BINDING Procedure Name vst-height( handle, height, &char width, &char-height, &cell-width, &ce-ll_height Data Types WORD vst height WORD hanile; WORD height; WORD char width; WORD char height; WORD cell width; WORD cell-height; Input Arguments handle = contrl[6] height = ptsinEll Output Arguments char-width = ptsoutE01 char - height = ptsout[l] cell-width = ptsoutE21 cell-height = ptsoutE31 GEM VDI Programmer's Guide Set Character neignz, roinLb riuue SET CHARACTER CELL This function sets the current graphic text HEIGHT, POINTS character height in printer points. A point MODE is 1/72 of an inch. The specified height is the distance between the baseline of one line of text and the baseline of the next line of text, which is the character cell height. The driver returns the selected point size of the character. Height and width information is returned in NDC/RC units. GEM VDI returns the character height, character width, cell height, and the cell width, as shown in Figure 5-1. For proportional faces, GEM VDI returns the width of the widest character and the widest character cell in the face. If the desired character height does not map exactly to a device size, GEM VDI selects the closest character size not exceeding the requested size. Left Character Right Character Alignment Alignment Delta Delta Character Height Cell Height Character width Cell Width Figure 5-1. Character Cell Definition Input contrl(O) -- Opcode = 107. contrl(l) Number of input vertices = 0. contrl(3) Length of intin array = 1. contrl(6) Device handle. intin(O) Cell height in points. 5-20 Output contrl(2) Number of output vertices = 2. contrl(4) Length of intout array = 1. intout(O) Selected cell height in points. ptsout(O) Character width selected in NDC/RC units. ptsout(l) Character height selected in NDCIRC units. ptsout(2) Character cell width in NDC/RC units. ptsout(3) Character cell height in NDC/RC units. C BINDING Procedure Name set_point vst_point( handle, point, &char-width, &char-height, &cell-width, &cell-height Data Types WORD set_point; WORD vst_point( WORD handle; WORD point; WORD char width; WORD char height; WORD cell width; WORD cell-height; Input Arguments handle contrl[63 point intinE01 Output Arguments set-point( = intoutE01 char-width ptsoutE01 char - height ptsoutEll cell-width ptsoutE21 cell-height ptsoutE31 5-21 GEM VDI Programmer's Guide Set Character Baseline Vector SET CHARACTER This function requests an angle of rotation BASELINE VECTOR specified in tenths of degrees for the character baseline vector, which specifies the baseline for subsequent graphic text. The driver returns the selected baseline vector to the application. The selected baseline vector is a best-fit match to the requested value. See Figure 5-2 for a depiction of how angles are specified to GEM VDI. 900 1800 __ 0 2700 Figure 5-2. Angle Specification Note: This function is not required and may not be supported on all devices. The Extended Inquire function returns the availability of this function. Input contrl(O) Opcode = 13. contrl(l) Number of input vertices = 0. contrl(3) Length of intin array = 1. contrl(6) Device handle. intin(O) Requested angle of rotation of character baseline (in tenths of degrees, 0 - 3600). Output contrl(2) Number of output vertices 0. contrl(4) Length of intout array = intout(O) Angle of rotation of character baseline selected (in tenths of degrees 0-3600). 5-22 GEM vui Programmer's Guide Set Character Baseline Vector C BINDIRG Procedure Name set-baseline = vst-rotation( handle, angle Data Types WORD set baseline; WORD vst rotation WORD handle; WORD angle; Input Arguments handle contrl[61 angle intin[01 Output Arguments set-baseline = intout[03 5-23 SET TEXT FACE This function selects a graphic character face for subsequent graphic text operations. Face 1 is a built-in face. The other faces are external and may be loaded with the Load Face function. Some faces may not be supported on all devices. Face names and indices may be determined by using Inquire Face Name. Input contrl(O) Opcode = 21. contrl(l) Number of input vertices = 0. contrl(3) Length of intin array = 1. contrl(6) Device handle. intin(O) Requested software text face number. I - System face 2 - Swiss 721 3 - Swiss 721 Thin 4 - Swiss 721 Thin Italic 5 - Swiss 721 Light 6 - Swiss 721 Light Italic 7 - Swiss 721 Italic 8 - Swiss 721 Bold 9 - Swiss 721 Bold Italic 10 - Swiss 721 Heavy 11 - Swiss 721 Heavy Italic 12 - Swiss 721 Black 13 - Swiss 721 Black Italic 14 - Dutch 801 Roman 15 - Dutch 801 Italic 16 - Dutch 801 Bold 17 - Dutch 801 Bold Italic Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array intout(O) Text face selected. 5-24 U- V~ 1jUYLdjjUjjej Ei LU.L(JL3 get Text Face C BINDING Prc>cedure Name set-font = vst-font( handle, font Data Types WORD set font; WORD vst font WORD hanile; WORD font; Input Arguments handle = contrlE63 font = intin[01 Output Arguments set-font = intoutE01 5-25 OEM VLJl 11rogfaWkM6f 9 LUlae allL k5LajJ111U ieJLL UUIUL LLIUC-A SET GRAPHIC TEXT This function sets the color index for COLOR INDEX subsequent graphic text operations. The Set Color Representation function determines the color represented by the color index. All devices support at least two color indices, 0 and 1 (monochrome). Color indices range from 0 to a dev ice -dependent maximum. If the requested index is out of range, GEM VDI selects color index 1. Input contrl(O) Opcode = 22. contrl(l) Number of input vertices = 0. contrl(3) Length of intin array = 1. contrl(6) Device handle. intin(O) Requested text color index. Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 1. intout(O) Text color index selected. C BINDING Procedure Name set-color vst-color( handle, color-index Data Types WORD set color; WORD vst color WORD handle; WORD color-index; Input Arguments handle = contrl[61 color-index = intin[01 Output Arguments set-color = intout[01 5-26 ,,.nm vui eragrammer-s uuicie Set Graphic Text Special Effects SET GRAPHIC TEXT This function sets text special effects for SPECIAL EFFECTS subsequently displayed graphic text. The following effects are available: • thickened • light intensity • skewed • underlined • outlined • shadowed • any combination of the above GEM VDI treats the integer in intin (0) as a bit pattern. The attributes set correspond to the setting in the six least significant bits. Table 5-3. Attribute Bit Mapping Value Description Thickened 0 thickened not selected I set style to thickened 1 Intensity 0 normal intensity I light intensity 2 Skewed 0 skewed not selected 1 set style to skewed 3 Underlined 0 do not underline 1 text is underlined 4 Outline 0 no outline 1 outline 5 Shadow 0 no shadow 1 shadow 5-27 GEM VDI Programmer's Guide Set Graphic Text Special Effects For example, if intin(O) = 9 (1001 binary), the text style is set to thickened and underlined. For effects not supported on a device, GEM VDI returns those bits set to 0. Input contrl(O) Opcode = 106. contrl(l) Number of input vertices = 0. contrl(3) Length of intin array = 1. contrl(6) Device handle. intin(O) Special effect word. Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 1. intout(O) Styles actually selected (style word with the appropriate bits set). Normal ABCDE ThickenedABCDE Light Intensity SkewedABCDE UnderlinedABCDE Figure 5-3. Graphic Text Special Effects 5-28 GEM VDI Programmer's Guide Set Graphic Text Special Effects C BINDING Procedure Name set-effect = vst-effects( handle, effect Data Types WORD set - effect; WORD vst effects( WORD handle; WORD effect; Input Arguments handle = contrl[61 effect = intin[01 Output Arguments set-effect = intoutE01 5-29 GEM VDi Programmer's Guide Set Graphic Text Alignment SET GRAPHIC TEXT This function sets horizontal and vertical ALIGN14ENT alignment for graphic text. Horizontal means in the direction of the baseline; vertical is perpendicular to the baseline. This function controls the positioning of the text string in relation to the graphic text position. The default alignment places the left baseline corner of the string at the graphic text position. If the application requests an invalid horizontal alignment, GEM VDI selects the default, left. If the application requests an invalid vertical alignment, GEM VDI selects the default, baseline. Too Line Ascent Line 0 Half Line A] Base Line Descent Line Leading Bottom Line Top Lin Ascent Line Half Line -Base -Line Descent Line Bottom Line Figure 5-4. Graphic Text Alignment 5-30 -- - rLuyLditimei s tuiue ber urapnic 'rext Alignment Input contrl(O) Opcode = 39. contrl(l) Number of input vertices = 0. contrl(3) Length of intin array = 2. contrl(6) Device handle. intin(O) Horizontal alignment requested. 0 = left justified (default) I = center justified 2 = right justified intin(l) Vertical alignment requested. 0 = baseline (default) 1 = half line 2 = ascent line 3 = bottom 4 = descent 5 = top Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 2. intout(O) Horizontal alignment selected. intout(l) Vertical alignment selected. C BINDING Procedure Name vst_alignment( handle, hor-in, vert-in, &hor-out, &vert-out Data Types WORD vst_alignment( WORD handle; WORD hor in; WORD vert in; WORD hor-out; WORD vert-out; Input Arguments handle = contrlE63 hor in = intin[03 ver -in = intin[l] Output Arguments hor_out = intout[O] vert-out = intoutEll - ..A LU9LU1L11UeL 3 Uujue s6t 1 .1 Interior Style SET FILL IMTERIOR This function sets the fill interior style STYLE used in subsequent polygon fill operations. If the application requests an unavailable style, the area is hollow filled. GEM VDI returns the selected style to the application. Hollow style fills the interior with the current background color(index 0). Solid style fills the area with the currently selected fill color. Input contri(o) Opcode = 23. contrl(l) Number of input vertices = 0. contrl(3) Length of intin array = 1. contrl(6) Device handle. intin(O) Requested fill interior style. 0 - hollow 1 - solid 2 - pattern 3 - hatch 4 - user-defined style Output contrl(2) Number of output vertices 0. contrl(4) Length of intout array = intout(O) Fill interior style selected. C BINDIUG Procedure Name set-interior vsf-interior( handle, style Data Types WORD set interior; WORD vsf interior WORD handle, WORD style; Input Arguments handle contrl[61 style intin[01 Output Arguments set-interior = intout[01 5-32 ~U~UC aeL Z111 acyie Lnaex SET FILL STYLE This function selects a fill style based on INDEX the fill interior style. This index has no effect if the interior style is hollow, solid, or user-defined. Indices range from 1 to a device-dependent maximum. If the requested index is not available, GEM VDI uses index style 1. The index references a hatch style if the selected fill interior style is hatch, or a pattern if the selected interior fill style is pattern. Figure 5-5 shows the available fill styles. Under each rectangle in Figure 5-5 are two numbers, separated by a comma. The number to the left of the comma corresponds to the style: Hollow, Pattern, or Hatch. The number to the right of the comma corresponds to the index for the particular pattern or hatch. = = MW 5M zz~ O,n 2,8 2,16 2,24 3,8 = pp;]~ IF., --- I = LK_i_'1:A!7AA 2,1 2,9 2,17 3,1 3,9 2,2 2,10 2,18 3.2 3,10 2,3 2,11 2,19 3,3 3,11 I FI. F11-7-11 [Xy~ M] 2,4 2,12 2,20 3,4 3,12 = = F__~ 7_~ 2,5 2,13 2,21 3,5 = = r_U_U_U_r_T 2,6 2,14 2,22 3,6 = = = L= 2,7 2,15 2,23 3,7 Figure 5-5. Fill Styles and Indices 5-33 umm vvi vrogrammer's Guide Set Fill Style Index Note: l,n (i.e., Style 1, followed by any index) produces the same result as 2,8. For patterns, index 1 maps to the lowest intensity pattern on the device. The pattern is always monochrome and uses the current fill area color for foreground pixels. Input contrl(O) Opcode = 24. contrl(l) Number of input vertices = 0. contrl(3) Length of intin array = 1. contrl(6) Device handle. intin(O) Requested fill style index for pattern or hatch fill. Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 1. intout(O) Fill style index selected for pattern or hatch fill. C BINDING Procedure Name set_style vsf_style( handle, style_index Data Types WORD set_style; WORD vsf_style WORD handle; WORD style_index; Input Arguments handle = contrl[61 style_index = intin[03 Output Arguments set_style = intout[01 5-34 - -11 'U~UL ~[Iuex SET FILL COLOR This function sets the color index for INDEX subsequent polygon fill functions. The Set Color Representation function determines the color represented by the color index. All devices support at least two color indices, 0 and 1 (monochrome). Color indices range from 0 to a dev ice -dependent maximum. If the requested index is out of range, GEM VDI selects color index 1. Input contrl(O) Opcode = 25. contrl(l) Number of input vertices 0. contrl(3) Length of intin array contrl(6) Device handle. intin(o) Requested fill color index. Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 1. intout(O) Fill color index selected. C BINDING Procedure Name set-color vsf-color( handle, color-index Data Types WORD set - color; WORD vsf color WORD handle; WORD color-index; Input Arguments handle = contrl[61 color-index = intin[03 Output Arguments set-color = intout[01 5-35 UZM viii erogrammer-s Guide set Fill perimeter Visibility SET FILL PERIMETER This function turns the outline of a fill VISIBILITY area on or off. When visibility is on (the default at Open Workstation) the border of a fill area is drawn in the current fill area color with a solid line. When visibility is off, no outline is drawn. Any nonzero value of the visibility flag causes the perimeter to be visible. Input contrl(O) Opcode = 104. contri(l) Number of input vertices = 0. contrl(3) Length of intin array = 1. contrl(6) Device handle. intin(O) Visibility flag. zero - invisible nonzero - visible Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array 1. intout(O) Visibility selected. C BINDING Procedure Name set_perimeter vsf_perimeter( handle, per_vis Data Types WORD set_perimeter; WORD vsf_perimeter WORD handle; WORD per_vis; Input Arguments handle contrl[61 per-vis intin[01 Output Arguments set_perimeter = intout[01 5-36 K U43 LUILUIlk- I U UU I Ut_ JLILIUSULIUM11fimu flil 1j1krr6Yn SET USER-DEFINED This function redefines the user-definable FILL PATTERN fill pattern. For the pattern data, bit 15 of word 1 is the upper left bit of the pattern. Bit 0 of word 16 is the lower right bit of the pattern. Bit zero is the Least Significant Bit of the word. Words are stored in the same format as 16-bit integers For a single plane pattern, a bit value of 1 indicates foreground color. A bit value of 0 indicates the background color. The color used for the foreground is determined by the current fill area color index. For a multiple plane pattern, the number of full 16-by-16 planes defined are used in the fill operation: planes = contrl(3) / 16. Any unspecified planes are zeroed. Note that the writing mode must be set to replace (mode 1), when using a multiplane fill pattern. The defined pattern is referenced by the Set Fill Interior Style function as style 4 and by the Fill Rectangle function. Input contri(O) Opcode = 112. contri(l) Number of input vertices = 0. contrl(3) Length of intin array = 16 to n. contrl(6) D@vic@ handl@. intin(O) to intin(15) -- First plane of fill pattern. intin(16) to intin(29) -- Second plane of fill pattern. intin(n-15) to intin(n) Last plane of fill pattern. Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 0. 5-37 U~l U~ LjUYL4!LUJUjeL 5 UUILIE! 3et USer-aeflnea fIll Fatt6rh C BINDING Procedure Name vsf_udpat( handle, pfill_pat, planes Data Types WORD vsf_udpat; WORD handle; WORD pfill_pat[16 x n where n > 01 WORD planes; Input Arguments handle = contrl[61 pfill pfill_pat planes = contrl[3]/16 End of Section 5 5-38 1-9 -9Z7[S PJOM 9ttl jo aTdTjTnw Tie.Tf)9-4uT up sT '4PT4'4 44PTM le 9AV4 pup Axepunoq piom p uo -4iie-4s Ismu va.Tp -Ta-4spj V -asn ain-4nj IOJ PaAJ9SaJ SUOTIRDOT au'09 0 -quepuadep-90-EA9P JO PJPPUP4S ST V8.1V .79-4SPJ a1474 JO -4PUIJOJ 914-4 J9q-4atIM BUT74PO'Pul 5PT; V 0 -paip jaqspj aqq uT saupTcT ;o jaqwnu aqL 9 -aZTS PJOM aq4 Aq P9PTATP IsTaxi:d uT vaje ia-4spi aq-4 jo LI-4pTm atiq 0-4 Tpnba ST anTVA STql -SPJOM Ul U8JP J8:ISP.T 8q-4 JO q-4PTM aLLL 0 -sTaxTd uT PaIP JaISPI aq-4 JO q-4PTm Pule qq5T9q aqL 0 -pajou5i aip sjaqawp-ipd jaq-4o aq-4 pup 'aDTA9p T'2c)-[sAqa P -To; sT sciaw aq,4 'o - .194u.Tod sTq,4 ;o sqTq ZE TTE JI -sja-4ndwooojOTIU P9SPq-9808 -70; -19-4UTod -4uaui5as--4asjjo up ol spuodsajjoo 194UTOd STqj, -PaJL- Ja-4SeJ aLl-4 jo aupld qsjE; aq-4 ;0 J9uJOD -4;9T jaddn aq-4 ;o ssaxppv Xiouiew aq4 o-4 ia:tu-Eod -4Tq-ZE V :squeuoduioo BuTmOTTO; at[4 ;o SISTSUOD 8(jaw uv *(UGaW) XOOTS UOT4TUTjaa XDOqg NOILINT"G wJO,q AJOulaW P Act PauT;aP sl I?aJP la-491el Na0a JLHONHW -SaOTA8P TPz)-!sAqd uo ST8x-cd ;o sXz)oTcL JRTn5uv-408J uo pup Ajoiuaui uT s-4Tq jo sXc)OTq jpTn6up-4oaj UO SUOT-4piado DT~OT mio;jad suo-E-4u-Tado jaqseH moiLonaoaiNi suoijuaadO.lajsUH 9 U0113as UAJLI VLJ.L LLUYLZjjJjJjjeL L3UjULJ Memory Form befinition Block One word (16 bits) Word 1 Memory pointer word 1 Word 2 Memory pointer word 2 Word 3 Form Width in Pixels Word 4 Form Height in Pixels Word 5 Form Width in Words Word 6 Form format flag Word 7 Number of Memory Planes Word 8 Reserved for future use Word 9 Reserved for future use Word 10 Reserved for future use Figure 6-1. Memory Form Definition Block RASTER AREA Two memory formats are associated with raster FORMATS areas: device-specific format well-defined standard format GEM VDI provides a function to transform a raster area from one format to another. You must transform a form before using Copy Raster. The form format flag can have two values: 0 - The form is in device-specific format. 1 - The form is in standard format. The layout of a standard form format is as follows (see also Figure 6-2): 6-2 -xi VLJI rLuyldltullet S tiulue ndsrer Ared ruimars * Plane based - The planes are contiguous blocks of memory, each having the same x,y resolution. A monochrome implementation has a single plane. A color index is mapped to a pixel value with each plane representing one bit in the value. Tables 6-1 and 6-2 define the pix el-value-to-color -index mapping for eight-color and sixteen-color screens, respectively. e Most Significant Bit in a word (16-bit integer) is the leftmost bit in the image. Note that the data is stored in the same format as 16-bit integers. e Words are arranged sequentially along a row with the first word being on the left edge of the row. Table 6-1. Pixel Value to Color Index Mapping for 8-color Screens Pixel Value T Color Index I Color 000 0 white 001 2 red 010 3 green Oil 6 yellow 100 4 blue 101 7 magenta 110 5 cyan ill I black V-9 -E-9 ainbia UT UM0qS ST (S19) pup (1,C) JO sa9uaOD qlTm 8T6uV'409J PO'4q6TTqf)Tq e pup 'sTaxid 8 jo -4q6iaq miol e sTaxTa 91*10 q4PTM maol R qqTm maol Ajouiew OueTd-a-r6UTS aTdMRS V SPMJSAS aZVNj(jHo():) -S90T429A qqbTj jamol pup qjal jaddn SIT JO Sa4RUTP1000 A1x aq-4 Aq pai;Toads ST aTbuRlDal V -e9JV la-4sel aq:l jo uoT-4jod paTJToads P uo suoT-4vlado smOTTV STU -quamn6ie up sle 9T6up-4oal e s951V-4 OsTe J9:ts'2-d Adoo IgaaW aq-4 oq uotjTppe uj -joToo punoifiXopq aiq-4 oq sdpw 0 jo anTRA T9xTd V :8-40M 5[DRTq I TTTT upAo qqbTT ET OTTT RIu96vw 40TT ST TOTT anjq I t1f) T T zi OOTT molleA qqbTj IV T TTOT U9815 jtjbT1 TT OTOT Pal -4t[6TT OT TOOT Aaj6 6 OOOT OlTtlm MOT 8 TTTO UvAo s . OTTO L. -4 U a 6 em L TOTO anTq IV OOTO mOTTaA cl TTOO U98.16 E OTOO pal z TOOO 8-4 T qm 0 0000 JoToo XaPuI JOTOD anTRA T9xTd SuBaIDS IOTOO-91 201 BulddW x9puj joToo oq anTRA T9XTd : Z-9 aTqleL GEM VDI PROgrammer's Guide coorctinate bystems 7 Msb Word 1 Plane 1 Msb Word 1 Lsb Msb Word 1 Plane 2 Msb Word 1 Plane 3 Pixel value of 0,0 F Word 2 Pixel at ~0,O) Raster Coord Raster Space Coordinates Space t - -- - - - t Standard Standard Monochrome Form Color Form (3 Planes) Figure 6-2. Standard Forms (0,0) (15,0) +1 (0,7) (15,7) (3,1) (6,5) Figure 6-3. Sample Single Plane Memory Form 6-5 LOGIC OPERATIONS To provide greatest flexibility, raster operations subject to a logic operation take the operation as an argument rather than using the logic operation associated with vector primitives. In addition, the operations available are greatly expanded to allow more flexibility. Table 6-3 lists the available operations with the following conventions: S = pixel value (0 or 1) of source pixel D = pixel value (0 or 1) of destination pixel e D'= destination pixel value after the logical operation Table 6-3. Raster Operation Logic Operations Mode Definition 0 D'= 0 1 D'= S AND D 2 D'= S AND [NOT D] 3 D'= S Replace mode 4 D'= [NOT S] AND D Erase mode 5 D'= D 6 D'= S XOR D XOR mode 7 D'= S OR D 8 D'= NOT [S OR D] 9 D'= NOT [S XOR DI 10 D'= NOT D 11 D'= S OR [NOT DI 12 D'= NOT S 13 D'= [NOT S] OR D 14 D'= NOT [S AND DI 15 D'= 1 6-6 GEM VDi Programmer's Guide Copy Raster, Opaque COPY RASTER, This function copies a rectangular raster OPAQUE area from source form to destination form using the logic operation the application specifies. If the source and destination forms are the same, and the rectangles overlap, GEM VDI copies so that the source rectangle is not changed until GEM VDI processes the corresponding area in the destination. No rotation or transformation occurs as a result of this function; the copy is pixel for pixel. If the source and destination rectangles are not the same size, GEM VDI uses the destination as a pointer and uses the source for the size. The Extended Inquire function returns scaling ability. The source and destination forms must be in device-specific form; see "Transform Form" later in this section. Input contrl(O) Opcode = 109. contrl(l) Number of input vertices = 4. contrl(3) Length of intin array = 1. contrl(6) Device handle. contrl(7-8)-- Double-word address of the source Memory Form Definition Block. contrl(9-10)- Double-word address of the destination Memory Form Definition Block. intin(0) Logic operation ( refer to "Introduction" i n t h i s section) - ptsin(O) x-coordinate of corner of source rectangle in RC/NDC. ptsin(l) y-coordinate of corner of source rectangle in RC/NDC. ptsin(2) x - c oo r d i na t e o f corner diagonally opposite corner selected in ptsin(O) of source rectangle in RC/NDC. ptsin(3) y-coordinate of corner diagonally opposite corner selected in ptsin(l) of source rectangle in RC/NDC. 6-7 UAA'1 Vul r1UYLd11WiUL 6 UU.LUU L-5PY RAgtdr, LJ15&qu6 ptsin(4) x-coordinate of corner of destination rectangle in RC/NDC. ptsin(5) y-coordinate of corner of destination rectangle in RC/NDC. ptsin(6) x-coordinate of corner of destination rectangle in RC/NDC. ptsin(7) y-coordinate of corner of destination rectangle in RC/NDC. Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array 0. C BINDING Procedure Name vro_cpyfm( handle, wr mode, pxyarray, psrcMFDB, pdesMFD-B Data Types WORD vro_cpyfm WORD handle; WORD wr mode; WORD pxyarray[81; WORD *PsrcMFDB; WORD *pdesMFDB; Input Arguments handle contrl[61 wr mode intin[01 pxyarray[O] = ptsin[01 pxyarray[l] = ptsin[l] p;yarray[71 = ptsin[71 psrcMFDB = contrl[7-81 pdesMFDB = contrl[9-101 6-8 UM Vni Programmer's Culde Copy Raster, Tianspai6ht COPY RASTER, This function copies a monochrome rectangular TRANSPARENT raster area from source form to a color area. A writing mode and color indices for both O's and I's are specified in the intin array. If the source and destination rectangles are not the same size, GEM VDI uses the source rectangle for the size and the upper left corner of the destination rectangle for the initial destination location. Transfer of information from the source to the destination is controlled by the specified writing mode as described below. See Table 5-1 for a binding of the available writing modes. Replace Mode Replace mode will result in a replacement of all pixels in the destination rectangle. The foreground color index specified in intin(l) will be output to all pixels associated with source locations which are set to a one. The background color index specified in intin(2) will be output to all pixels associated with source locations which are set to a zero. Transparent Mode Transparent mode only affects the pixels associated with a source value of one. Those pixels are set to the foreground color whose index is specified in intin(l). The color index specified in intin(2) is not used. XOR Mode In XOR mode, the monochrome raster source area is logically XORed with each plane of the destination. The color indices specified in intin(l) and intin(2) are not used. 6-9 GEM VDI Programmer's Guide Copy Raster, Transparent Reverse Reverse Transparent mode only affects the Transparent pixels associated with a source value of Mode zero. Those pixels are set to the background color whose index is specified in intin(2). The color index specified in intin(l) is not used. Input contri(O) Opcode = 121. contrl(l) Number of input vertices = 4. contrl(3) Length of intin array = 3. contrl(6) Device handle. ' contrl(7-8)-- Double-word address of the source Memory Form Definition Block. contrl(9-10)- Double-word address of the destination Memory Form Definition Block. intin(O) Writing Mode. intin(l) Color index for ls in data. intin(2) Color index for Os in data. ptsin(O) x-coordinate of corner of source rectangle in RC/NDC. ptsin(l) y-coordinate of corner of source rectangle in RC/NDC. ptsin(2) x-coordinate of corner diagonally opposite corner selected in ptsin(O) of source rectangle in RC/NDC. ptsin(3) y-coordinate of corner diagonally opposite corner selected in ptsin(l) of source rectangle in RC/NDC. ptsin(4) x-coordinate of corner of destination rectangle in RC/NDC. ptsin(5) y-coordinate of corner of destination rectangle in RC/NDC. ptsin(6) x-coordinate of corner of destination rectangle in RC/NDC. ptsin(7) -- y-coordinate of corner of destination rectangle in RC/NDC. 6-10 GEM VDI Programmer's Guide Copy Raster, Transparent Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array 0. C BINDING Procedure Name vrt_cpyfm( handle, wr mode, pxyarray, psrcMFDB, pdesMFDii, color-index Data Types WORD vrt-cpyfm WORD handle; WORD wr-mode; WORD pxyarray[81; WORD *psrcMFDB; WORD *PdesMFDB; WORD color-index[2]; Input Arguments handle contrl[61 wr-mode intin[01 pxyarray[O] = ptsin[01 pxyarray[l] = ptsin[l] P;Yarray[71 = ptsin[7] psrcMFDB = contrl[7-8] pdesMFDB = contrl[9-10] color index[01 = intin[l] color-index[l] = intin[21 6-11 GEM VDI Programmer's Guide Transtorm Yorm TRANSFORM FORM This function transforms a raster area from standard format to device-specific format or from device-specific to standard format. The operation is a toggle, changing the current state. The number of planes specified in the source MFDB determines the number transformed. The source format flag is toggled and placed in the destination. The user is required to ensure that the other parameters in the destination MFDB are correct. Input contrl(O) Opcode = 110. contrl(l) Number of input vertices = 0. contrl(3) Length of intin array = 0. contrl(6) Device handle. contrl(7-8) Double-word address of the source MFDB. contrl(9-10) Double-word address of the destination MFDB. Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 0. C BIMING Procedure Name vr-trnfm( handle, psrcMFDB, pdesMFDB Data Types WORD vr trnfm WORD hai~dle; WORD *psrcMFDB; WORD *PdesMFDB; Input Arguments handle ~ contrl[6] psrcMFDB = contrl[7-81 pdesMFDB = contrl[9-101 GET PIXEL This function returns a pixel value and a color index for the pixel specified by ptsin(O) pts in (1) . Note: Color index 0 is the background color. It may or may not map to pixel value 0 in device-specific form. Refer to Tables 6-1 and 6-2 for the colors and values. Standard form always maps color index 0 to pixel value 0. Input contrl(O) Opcode = 105. contrl(l) Number of input vertices = 1. contrl(3) Length of intin array = 0. contrl(6) Device handle. ptsin(O) x-coordinate of pixel in RC/NDC units. ptsin(l) y-coordinate of pixel in RC/NDC units. Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 2. intout(O) Pixel value. intout(l) Color index. 6-13 GEM VDI Programmer's Guide Get Pixel C BINDING Procedure Name v_get_pixel( handle, x, y, pel, index Data Types WORD v-get-pixel( WORD handle; WORD X; WORD y; WORD *pel; WORD *index; Input Arguments handle = contrl[61 x = ptsin[01 y = ptsin[l] Output Arguments pel = intout[O] index = intout[l] End of Section 6 6-14 Section 7 Input Functions INTRODUCTION The input functions allow user interactions with the application program. Many of the input functions support two modes: request and sample. In request mode, the driver waits until an input event occurs before returning. In sample mode, the driver returns the current status or location of the input device without waiting. SET INPUT MODE This function sets the input mode for the following specified logical input devices to request or sample: e locator 9 valuator 9 choice * string Select the input mode in intin(l). Input contri(O) Opcode = 33. contri(l) Number of input vertices = 0. contrl(3) Length of intin array = 2. contrl(6) Device handle. intin(O) Logical input device. 1 = locator 2 = valuator 3 = choice 4 = string intin(l) -- Input mode. I = request 2 = sample 7-1 GEM V5T Programmer's 6ulAe get Input Mode Output contrl(2) Number of output vertices 0. contrl(4) Length of intout array intout(O) Input mode selected. C BIMING Procedure Name vsin-mode( handle, dev-type, mode Data Types WORD vsin mode WORD handle; WORD dev_type; WORD mode; Input Arguments handle = contrl[61 dev_type = intin[01 mode = intinEll 7-2 "~Vl Vul rLUqLa111J11CL z ~.I- J'U%- Ca INPUT IX)CATOR, This function returns the position of the REQUEST MODE specified locator device. Upon entry to the locator routine, the current cursor form is displayed at the initial coordinate. The graphic cursor is tracked with the input device until a terminating event occurs, which can result from the user pressing a key or a button on a mouse. GEM VDI removes the cursor when the terminating event occurs. Typically, the arrow keys move the cursor in large jumps when used without the Shift key and in pixel increments when used with the Shift key. This function always displays a cursor on the screen, even if the cursor is currently obscured or hidden. Note: If both a keyboard and another locator device are available, the cursor is tracked by input from either, giving the user maximum flexibility. Input contrl(O) Opcode = 28. contrl(l) Number of input vertices = 1. contrl(3) Length of intin array = 0. contrl(6) Device handle. ptsin(O) Initial x-coordinate of locator in NDC/RC units. ptsin(l) Initial y-coordinate of locator in NDC/RC units. GEM VDI Programmer's Guide Input Locator, Request Mode Output contrl(2) Number of output vertices = 1. contrl(4) Length of intout array = 1. intout(O) Locator terminator. The low byte contains a character terminator. For keyboard- terminated locator input, this is the ASCII character code of the key struck to terminate input. For nonkeyboard-terminated input (tablet, mouse, and so on), valid locator terminators begin with 20 Hex (space) and increase from there. For instance, if the puck on a tablet has 4 buttons, the first button must generate a 20 Hex as a terminator, the second a 21 Hex, the third a 22 Hex, and the fourth a 23 Hex. ptsout(O) Final x-coordinate of locator in NDC/RC units. ptsout(l) Final y-coordinate of locator in NDC/RC units. 7-4 GEM VDI Programmer's Guide Input Locator, Request Mode C BINDING Procedure Name vrq-locator( handle, x, y, &xout, &Yout, &term ) Data Types WORD vrq locator WORD handle; WORD x, y; WORD xout; WORD yout; WORD term; Input Arguments handle = contrl[6] x = ptsin[O] y = ptsin[l) Output Functions xout = ptsout[o] yout = ptsout[l) term = intout[01 7-5 GEM VDI Programmer's Guide Input Locator, Sample Mode INPUT LOCATOR, This function returns the position in NDCs SAMPLE MODE of the specified locator device. Upon entry to the locator routine, no cursor is displayed. (Use Show Cursor to display the cursor. ) Input is sampled. If the cursor position has changed, GEM VDI returns the cursor position and contrl(2) is set to 1. Contrl(4) is set to 0 . If a terminating event occurred, GEM VDI returns a character and contrl(4) is set to 1. Contrl(2) is set to 0. Note: If both a keyboard and another locator device are available, the input comes from either, giving the user maximum flexibility. Input contri(O) Opcode = 28. contrl(l) Number of input vertices = 1. contrl(3) Length of intin array = 0. contrl(6) Device handle. ptsin(O) Initial x-coordinate of locator in NDC/RC units. ptsin(l) Initial y-coordinate of locator in NDC/RC units. Output contrl(2) Number of output vertices. 1 = coordinate changed 0 = no coordinate changed contrl(4) Length of intout array. 0 = no keypress character I = keypress character returned 7-6 GEM VDI Programmer's Guide Input Locator, Sample Mode Table 7-1. Sample Mode Status Returned Event Control Array 1 (2) (4) Coordinates change. 1 0 Key pressed; coordinates 0 1 not changed from what was pressed. No input. 0 0 Key pressed; coordinates 1 1 changed. intout(O) -- Locator keypress if keypress occurs. This information is the same as for Input Locator, Request Mode function. ptsout(O) New x-coordinate of locator in NDC/RC units. ptsout(l) New y-coordinate of locator in NDC/RC units. 7-7 C BINDING Procedure Name status = vsm locator( handle, x, y, &xout, &yout, &term Data Types WORD status; WORD vsm locator WORD handle, WORD x, y; WORD xout; WORD yout; WORD term; Input Arguments handle = contrl[61 x = ptsin[01 y = ptsin[l) Output Arguments status = contrl[21 I (contrl[41 << 1) xout = Ptsout[01 yout = ptsout[l] term = intout[01 7-8 L'EM Vul lituylallimer 8 6ulue i11PUL Vd1UaLLJ1 , fkek4Ue5L i'luue INPUT VALUATOR, This function returns the value of the REQUEST MODE valuator device. The initial value of the valuator is incremented or decremented until a terminating character is struck. Valuator keys are typically the up-arrow and down-arrow keys. Valuator numbers range from 1 to 100. Typical implementation of the up-arrow and down-arrow keys is as follows: • Pressing the up-arrow key adds ten to the valuator. • Pressing the down-arrow key subtracts ten from the valuator. • Pressing the up-arrow key with the Shift key adds one to the valuator. • Pressing the down-arrow key with the Shift key subtracts one from the valuator. Note: This function is not required and may not be available on all devices. Input contrl(O) Opcode = 29. contrl(l) Number of input vertices 0. contrl(3) Length of intin array contrl(6) Device handle. intin(O) Initial value. Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 2. intout(O) Output value. intout(l) Terminator. GEM VDI Programmer's Guide Input Valuator, Request Mode C BINDING Procedure Name vrq_valuator( handle, valuator in, &valuator-out, &terminator Data Types WORD vrq valuator WORD han'jle; WORD valuator in; WORD valuator out; WORD terminator; Input Arguments handle = contrl[6) valuator-in = intin[01 Output Arguments valuator out = intout[01 terminator = intout[l] ULVI Vul eruyiditillIML S uulue 1111JUL- Va-LUCLLUll ~CLILLJJ~C '.UUC INPUT VALUATOR, This function returns the current value of SAMPLE MODE the valuator device. The valuator device is sampled. If the valuator has changed, GEM VDI increments or decrements the valuator value as required. If a terminating event occurs, GEM VDI returns the value. If nothing happens, GEM VDI returns no value. Valuator numbers range from 1 to 100. The suggested keys are the same as for Input Valuator, Request Mode. Note: This function is not required and may not be available on all devices. Input contrl(O) Opcode = 29. contrI(l) Number of input vertices = 0. contrl(3) Length of intin array = 1. contrl(6) Device handle. intin(O) Initial value. Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array. 0 = nothing happened 1 = valuator changed 2 = keypress character intout(O) New valuator value. intout(l) Keypress, if keypress event occurred. GEM VDI Programmer's Guide Input Valuator, Sample Mode C BINDING Procedure Name vsm-valuator( handle, val-in, &val-out, &term, &status Data Types WORD vsm valuator WORD hanale; WORD val in; WORD val out; WORD term, WORD status; Input Arguments handle = contrl[6] val-in = intin[o) Output Arguments val - out = intout[o] term = intout[l] status = contrl[4] 7-12 k3LJL'l V ~~ L L Uk3 kuuujj~ U .. - ..' .. . . . INPUT CHOICE, This function returns the choice status of REQUEST MODE the selected choice device. Input is sampled until a key is pressed. If it isa valid choice key, GEM VDI returns its value. Otherwise, GEM VDI returns the initial choice number. Choice numbers range from 1 to a device-dependent maximum value. Note: This function is not required and may not be available on all devices. Input contrl(O) Opcode = 30. contrl(l) Number of input vertices = 0. contrl(3) Length of intin array = 1. contrl(6) Device handle. intin(O) Initial choice number. Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array 1. intout(O) Choice number. C BINDING Procedure Name vrq_choice( handle, ch-in, &ch-out Data Types WORD vrq_choice WORD handle; WORD ch in; WORD *ci~_out; Input Arguments handle = contrl[61 ch-in = intin[01 Output Arguments *ch-out = intout[01 7-13 UrAll VLJ.L rLUYLd1tUi11!!L 5 ULA.Lue INPUT CHOICE, This function returns the choice status of SAKPLE MODE the selected choice device. Upon entry to the routine, GEM VDI samples input. If input is available and is a valid choice key, GEM VDI returns it. Choice numbers range from 1 to a device-dependent maximum value. Note: This function is not required and may not be available on all devices. Input contri(O) Opcode = 30. contri(l) Number of input vertices = 0. contrl(3) Length of intin array = 0. contrl(6) Device handle. Output contrl(2) Number of output vertices = 0. contrl(4) Choice status. 0 = nothing happened 1 = sample successful intout(O) Choice number if sample successful, 0 if unsuccessful. C BINDING Procedure Name status = vsm-choice( handle, &choice Data Types WORD status; WORD vsm choice WORD handle; WORD choice; Input Arguments handle = contrlC61 Output Arguments choice = intout[03 status = contrl[41 7-14 INPUT STRING, This function returns a string from the REQUEST MODE specified device. Input is accumulated until GEM VDI encounters a carriage return or the intout array is full. If the application enables echo mode, text will be echoed to the screen with the current text attributes using the vertex passed in the ptsin array as the justification point. If the number in intin(O) is negative, the values in intout will conform to the standard keyboard defined in Appendix D. In this case, the absolute value of intin(O) is used as the maximum intout size. Note. Echoing of input is not required and may not be available on all devices. Input contrI(O) Opcode = 31. contri(l) Number of input vertices = 1. contrl(3) Length of intin array = 2. contrl(6) Device handle. intin(O) Maximum string length. intin(l) Echo mode. 0 = no echo 1 = echo input characters at position specified ptsin(O) x-coordinate of echo area in NDC/RC units. ptsin(l) y-coordinate of echo area in NDC/RC units. Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array. intout Output string returned in ADE. GEM VDI Programmer's Guide Input String, Request Mode C BINDING Procedure Name vrq_string( handle, max - length, echo-mode, echo-xy, &string Data Types WORD vrq_string WORD handle; WORD max - length; WORD echo-mode; WORD echo-xy[21; BYTE string[max_length+ll; Input Arguments handle = contrl(63 max-length intin[01 echo mode intin[l] echo-X,y ptsin[O-11 Output Arguments string = intout Note: The BYTE array elements contain the eight least significant bits of the intout array elements. The array is terminated with a null byte. The length of the output variable string includes an additional byte for the terminating null. 7-16 GEM VDI Programmer's Guide Input String, Sample Mode INPUT STRING, This function returns a string from the SAMPLE MODE specified device. Upon entry to the routine, GEM VDI samples input. If data is available, it is accumulated, and GEM VDI samples the input again. Input is accumulated until one of the following events occurs: • Data is no longer available. • A carriage return is encountered. • The intout buffer is full. Note: If the string will always be terminated with RETURN, use Input String, Request Mode. If the number in intin(O) is negative, the values in intout will conform to the standard keyboard defined in Appendix D. In this case, the absolute value of intin(O) is used as the maximum intout size. Input contri(O) Opcode = 31. contrl(l) Number of input vertices = 1. contrl(3) Length of intin array = 2. contrl(6) Device handle. intin(O) Maximum string length. intin(l) Echo mode. 0 = no echo 1 = echo input characters ptsin(O) x-coordinate of echo area in NDC/RC units. ptsin(l) y-coordinate of echo area in NDC/RC units. Output contrl(2) Number of output vertices = 0. contrl(4) Length of output string. 0 = sample unsuccessful (characters not available) >0 = sample successful (characters available) intout -- Output string, if sample successful. 7-17 k3 "L" V Jj -L L 'L UY 1- U ULLUt- L -J ULA ~Ul C BINDING Procedure Name status = vsm - string( handle, max-length, echo-mode, echo_xy, &string Data Types WORD vsm string WORD hanale; WORD max length; WORD ech7o mode; WORD echo - xy[21; BYTE string[max_length+ll; WORD status; Input Arguments handle = device handle max_length intin[03 echo-mode intin[l] echo-xy ptsin[O-11 Output Arguments string intout status contrl[43 Note: The BYTE array elements contain the eight least significant bits of the intout array elements. The array is terminated with a null byte. The length of the output variable string includes an additional byte for the terminating null. 7-18 SET MOUSE This function redefines the cursor pattern FORM displayed during locator input or at any time the cursor is shown (see the discussion of the Show Cursor function later in this section). For the cursor mask and data, bit 15 of word 1 is the upper left bit of the pattern. Bit 0 of word 16 is the lower right bit of the pattern. Bit zero is the Least Significant Bit of the word. The hot spot is the location of the pixel (relative to the upper left pixel of the mouse form) that lies over the pixel whose address is returned by the input locator function. The mouse form is drawn as follows: 1. The data under the mouse form is saved so that it can be restored when the cursor moves. 2. ls in the mask cause the corresponding pixel to be set to the color index defined in intin(3). 3. ls in the mouse form data cause the corresponding pixel to be set to the color index defined in intin(4). Input Contrl(O) Opcode = 111. Contrl(l) Number of input vertices = 0. Contrl(3) Length of intin array = 37. Contrl(6) Device Handle. intin(o) x-coordinate of hot spot. intin(l) y-coordinate of hot spot. intin(2) Reserved for future use, must be 1. intin(3) Mask color index, normally 0. intin(4) Data color index, normally 1. intin(5-20)- 16 words of 16-bit cursor mask. intin(21-36)- 16 words of 16-bit cursor data. Output Contrl(2) Number of output vertices = 0. Contrl(4) Length of intout array = 0. 7-19 C BINDIING Procedure Name vsc-form( handle, pcur-form Data Types WORD vsc form WORD handle; WORD pcur_form[37]; Input Arguments handle = contrl[61 pcur_form[O] intin[O] pcur-form[361 intin[361 7-20 GEM VDI Programmer's Guide Exchange Timer interrupt vector EXCRANGE TIKER With this function, the application can INTERRUPT VECTOR perform some action each time a timer tick occurs. The input to this function is a two-word pointer in contrl(7) and contrl(8). The pointer indicates the starting address of the code to receive control when a timer tick occurs. The address of the old timer routine is returned in contrl(9) and contrl(10). The app 1 ica t ion -dependent code is invoked with a processor-dependent call instruction. When this is complete, the application should perform a processor -dependent return instruction. It is the responsibility of the application dependent code to save and restore any registers used. When the application code is invoked, interrupts are disabled. The application should not enable interrupts. See Appendix E for processor specific instructions and register names. The number of milliseconds per timer tick is returned in intout(O). Input contrl(O) Opcode = 118. contrl(l) Number of input vertices = 0. contrl(3) Length of intin array = 0. contrl(6) Device handle. contrl(7-8) Address of application timer routine. Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 1. contr 1(9-10 Address of the old timer routine. intout(O) Milliseconds per tick. C BIBMING Procedure Name vex_timv( handle, tim-addr, otim-addr, &tim-conv Data Types WORD vex timv( WORD han7dle; WORD *tim addr; WORD *otim-addr; WORD tim-conv; Input Arguments handle = contrl[61 tim-addr = contrl[7-81 Output Arguments otim - addr = contrl[9-101 tim-conv - intout[ol 7-22 SHOW CURSOR This function displays the current cursor. The cursor moves on the display surface based on information input from a mouse. The Show Cursor function and the Hide Cursor functions are closely related. Once the cursor is visible, a single Hide Cursor causes the cursor to disappear. GEM VDI keeps track of the number of times the Hide Cursor function is called. The Show Cursor function must be called the same number of times for the cursor to reappear. For example, if the Hide Cursor function is called four times, the Show Cursor function must be called four times for the cursor to appear. The Show Cursor function does, however, provide a reset flag in intin(O). If intin(O) is zero, the cursor appears on the screen, regardless of the number of Hide Cursor calls. A nonzero value for intin(O) affects the Show Cursor function as described in the preceding paragraph. Input contrl(O) Opcode = 122. contrl(l) Number of input vertices = 0. contrl(3) Length of intin array = 1. contrl(6) Device handle. intin(O) Reset flag. 0 = ignore number of Hide Cursor calls nonzero = normal Show Cursor functionality Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 0. 7-23 uwi vLj.L rLugLaitunt~L b ~u~ut~ -.1w. -U-L C BINDING Procedure Name v-show-c( handle, reset ) llww~ Data Types WORD v - show - c ( ); WORD handle; WORD reset Input Arguments handle = contrl[6] reset =intinE01 7-24 GEM VDI Programmer's Guide Hide Cursor HIDE CURSOR This function removes the cursor from the display surface. This state is the default condition set at Open Workstation. The cursor can appear in a new position when the application calls the Show Cursor function because GEM VDI updates the position based on information input from a mouse. Refer to the Show Cursor function for a description of how the number of Hide Cursor calls affects the Show Cursor function. Input contrl(O) Opcode = 123. contrl(l) Number of input vertices = 0. contrl(3) Length of intin array = 0. contrl(6) Device handle. Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 0. C BINDING Procedure Name v-hide-c( handle Data Types WORD v -- hide - c WORD handlel Input Arguments handle = contrIE61 7-25 M V131 Programmer's Vulde b&ff~5i6 maun Bur-ron 5r-are SAMPLE MOUSE This function returns the current state of HUTTON STATE the mouse buttons. The leftmost mouse button is returned in the Least Significant Bit of the word. A bit value of 1 indicates the key is currently depressed; a bit value of 0 indicates the key is up. This function also returns the current (x,y) position of the cursor. Input contrl(O) Opcode = 124. contrl(l) Number of input vertices = 0. contrl(3) Length of intin array = 0. contrl(6) Device handle. Output contrl(2) Number of output vertices = 1. contrl(4) Length of intout array = 1. intout(O) Mouse button state. ptsout(O) x position of cursor in NDC/RC units. ptsout(l) y position of cursor in NDC/RC units. C BINDING Prc>cedure Name vq_mouse( handle, &pstatus, &x, &y Data Types WORD vq_mouse WORD handle; WORD pstatus; WORD x, y; Input Arguments handle contrl[61 Output Arguments pstatus intout[03 x = ptsout[o] y = ptsout[l] U1~1'1 Vul r1uYLdiulueL 5 UUlur- EXCHANGE BUTTON This function allows the application to CHANGE VECTOR perform some action each time the state of the mouse buttons changes. The application receives control after the button state is decoded, but before the driver button state changes. The input to this function is a two-word pointer in contrl(7) and contrl(8), which indicates the starting address of the code to receive control when the mouse button state changes. Contrl(9) and contrl(10) return a two-word pointer to the old mouse routine. Control is passed to the specified address whenever the mouse button state changes. The application code is invoked via a processor dependent call instruction with a processor dependent register containing the mouse button keys. Keys are encoded by the same rules that apply to the Sample Mouse Button State function. When complete, the application dependent code should do a processor -dependent return instruction with the mouse button state the driver is to store in the same register. This gives the application the opportunity to alter the buttons before they are used by the driver. It is the responsibility of the application dependent code to save and restore any registers used. When the application code is invoked, interrupts are disabled. The application should not enable interrupts. See Appendix E for processor-specific instructions and register names. Input Contrl(O) Opcode = 125. Contrl(l) Number of input vertices = 0. Contrl(3) Length of intin array = 0. Contrl(6) Device handle. Contrl(7-8) -- Address of application mouse button state change routine. UfA% VLJ1 C1UY1d1MHLt!L 21 %3UIUC Output Contrl(2) Number of output vertices = 0. Contrl(4) Length of intout array 0. Contrl(9-10) - Address of old mouse button state change routine. C Bl"ING Procedure Name vex-butv( handle, pusrcode, psavcode Data Types WORD vex butv WORD han~dle; WORD *pusrcode; WORD *psavcode; Input Arguments handle = contrl[61 pusrcode = contrl[7-83 Output Arguments psavcode = contrl[9-101 7-28 EXCHANGE MOUSE This function allows the application to MOVI94ENT VECTOR perform some action each time the mouse moves to a new location. The applicationreceives control after the x,y address is computed, but before the current mouse position in the driver is updated or the mouse form is actually redrawn on the screen. The input to this function is a two-word pointer in contrl(7) and contrl(8), which indicates the starting address of the code to receive control when the mouse moves. A two word pointer to the address of the old mouse movement routine is returned in contrl(9) and contrl(10). When the mouse moves, the appli cat ion-dependent code is invoked via a processor -dependent call instruction. The new x and y locations are contained in a pair of processor -dependent registers. Upon completion, the application dependent code should do a processor -dependent return instruction with the x,y mouse position the driver is to store in the appropriate hardware registers. This procedure gives the opportunity to alter the x,y position before it is used by the driver. It is the responsibility of the application dependent code to save and restore any registers used. When the application code is invoked, interrupts are disabled. The application should not enable interrupts. See Appendix E for processor-specific instructions and register names. Input Contrl(O) Opcode = 126. Contrl(l) Number of input vertices = 0. Contrl(3) Length of intin array = 0. Contrl(6) Device handle. Contrl(7-8) Address of application mouse movement routine. Output Contrl(2) Number of output vertices = 0. Contrl(4) Length of intout array 0. Contrl(9-10) Address of the old mouse movement routine. C BINDING Procedure Name vex-motv( handle, pusrcode, psavcode Data Types WORD vex motv WORD hanale; WORD *pusrcode; WORD *psavcode; Input Arguments handle = contrl[63 pusrcode = contrl[7-81 Output Arguments psavcode = contrl[9-10] 7-30 GEM VDI Programmer's Guide Exchange Cursor Change Vector EXCHANGE CURSOR This function allows the application to CHANGE VECTOR perform some action each time the cursor is drawn. The application can completely take over drawing the cursor or can perform some action and have GEM VDI draw the cursor. Control is passed to the application whenever the cursor position should be updated. The input to this function is a two-word pointer in contrl(7) and contrl(8), which indicates the starting address of the code to receive control when a cursor is drawn. The address of the old cursor draw routine is returned in contrl(9) and contrl(10). The application-dependent code is invoked with a processor -dependent call instruction. The x,y position at which the cursor should be drawn is contained in a pair of processor dependent registers. If the application dependent code does not draw its own cursor, a processor -dependent call should be performed to the address returned in contrl(9) and contrl(10). This will cause GEM VDI to draw a cursor. When it is done, the application should perform a processor -dependent return instruction. It is the responsibility of the application dependent code to save and restore any registers used. The GEM VDI cursor draw routine preserves the contents of all registers. When the application code is invoked, interrupts are disabled. The application should not enable interrupts. See Appendix E for processor -spec if ic instructions and register names. 7-31 Input contrl(O) Opcode = 127. contrl(l) Number of input vertices = 0. contrl(3) Length of intin array = 0. contrl(6) Device handle. contrl(7-8) Address of application cursor draw routine. Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 0. contrl(9-10) Address of the old cursor draw routine. C BINDING Procedure Name vex-curv( handle, pusrcode, psavcode Data Types WORD vex - curv WORD handle; WORD *pusrcode; WORD *psavcode; Input Arguments handle = contrl[61 pusrcode = contrl[7-81 Output Arguments psavcode = contrl[9-10] 7-32 UW11 VL)1 rLUyLdHUt1eL .5 uu-Luc SAMPLE KEY130ARD This function returns the current state of STATE INFORMATION the keyboard's Control, Shift, and Alt keys. These values are returned as a bit-encoded value in intout(O). The keys are assigned to bits as follows: Bit 0 - right Shift Key Bit 1 - left Shift Key Bit 2 - Control Key Bit 3 - Alt Key Bit 0 is the Least Significant Bit of the word. A bit value of zero indicates the key is up, a bit value of 1 indicates the key is depressed. Input contri(O) Opcode = 128. contrl(l) Number of input vertices = 0. contrl(3) Length of intin array = 0. contrl(6) Device handle. Output contrl(2) Number of output vertices 0. contrl(4) Length of intout array intout(O) Keyboard state. C BINDING Procedure Name vq-key_s( handle, &pstatus Data Types WORD vq_key_s WORD handle; WORD pstatus; Input Arguments handle = contrlE61 Output Arguments pstatus = intoutE01 End of Section 7 7-33 I Section 8 Inquire Functions INTRODUCTION Inquire functions return the current settings for device-specific attributes. EXTENDED INQUIRE This function returns additional device specific information not included in the Open Workstation call. The value of intin(O) determines if GEM VDI returns the values returned at Open Workstation or an extended set of device-specific information. Refer to Section 3, "Control Functions," for more information about intout values for the Open Workstation function. Note that 6 vertices and 45 intouts are always returned, although some values are undefined for the extended device information. Input contrl(O) Opcode ~ 102. contrl(l) Number of input vertices = 0. contrl(3) Length of intin array = 1. contrl(6) Device handle. intin(O) Information type. 0 = Open Workstation values 1 = Extended Inquire values 8-1 GEM VDI Programmer's Guide Extended Inquire Output contrl(2) Number of output vertices = 6. contrl(4) Length of intout array = 45. intout(O) Type of screen. 0 not screen I separate alpha and graphic controllers and separate video screens 2 separate alpha and graphic controllers with a common video screen 3 common alpha and graphic controller with separate image memory 4 common alpha and graphic controller with common image memory intout(l) Number of background colors available in color palette. On some devices this may be different from the number of colors returned from Open Workstation, intout(39). intout(2) Text effects supported. (See "Set Graphic Text Special Effects" in Section 5 for values.) intout(3) Scale rasters. 0 = scaling not possible 1 = scaling possible intout(4) Number of planes. intout(5) Lookup table supported. 0 = table supported 1 = table not supported intout(6) Performance factor, number of 16 x 16 pixel raster ops per second. intout(7) Contour fill capability. intout(8) Character rotation ability. 0 = none 1 = 90-degree increments only 2 = arbitrary angles 8-2 GEM VDI Programmer's Guide Extended Inquire intout(9) -- Number of writing modes available. intout(10)-- Highest level of input mode available. 0 = none 1 = request 2 = sample intout(ll)-- Text alignment capability flag. 0 no 1 yes intout(12)-- Inking capability flag. 0 = device cannot ink 1 = device can ink intout(13)-- Rubberbanding capability flag. 0 = no 1 = capable of rubberband lines 2 = capable of both rubberband lines and rectangles intout(14)-- Maximum vertices for Polyline, Polymarker, or Filled Area. -1 = no maximum intout(15)-- Maximum intin. -1 = no maximum intout(16)-- Number of keys available on the mouse. intout(17)-- styles for wide lines. 0 no 1 yes intout(18)-- Writing modes for wide lines. intout(19-44)- Reserved, contains zeros. ptsout(Q-11) - Reserved, contains zeros. 8-3 C BINDING Procedure Name vq_extnd( handle, owflag, work_out Data Types WORD vq_extnd WORD handle; WORD owflag; WORD work-out[571 Input Arguments handle = contrl[61 owflag = intin[01 Output Arguments work - out[O] intout[01 work out[44] intout[441 work-out[451 ptsout[01 work-out[561 ptsout[lll B-4 INQUIRE COLOR This function returns either the requested or REPRESENTATION the actual value of the specified color index in RGB units. Both the set and realized values are available. If the selected index is out of range, GEM VDI returns -1 in intout(O). Input contrl(O) Opcode = 26. contri(l) Number of input vertices = 0. contrl(3) Length of intin array = 2. contrl(6) Device handle. intin(O) Requested color index. intin(l) Set or realized flag. 0 = set (return color values requested) 1 = realized ( return color values realized on device) Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 4. intout(O) Color index. intout(l) Red intensity (in tenths of percent 0-1000). intout(2) Green intensity. intout(3) Blue intensity. 8-5 C BINDING Procedure Name vq_color( handle, color-index, set-flag, rgb Data Types WORD vq_color WORD handle; WORD color index; WORD set - ffag; WORD rgbC3]; Input Arguments handle = contrl[6] color index = intin[01 set-fEag = intin[l] Output Arguments rgb[01 = intout[l] rgb[l] = intout[21 rgb[21 = intoutE31 8-6 uLm vui Frogrammer s uuiae 111LIUile rLJ.LY1111e MLLL1UULO5 INQUIRE CURRENT This function reports the current setting of POLYLINE all attributes that affect polylines, such as ATTRIBUTES line type, line color, line width, end styles, and writing mode. Input contrl(O) Opcode = 35. contrl(l) Number of input vertices = 0. contrl(3) Length of intin array = 0. contrl(6) Device handle. Output contrl(2) Number of output vertices contrl(4) Length of intout array = 5. intout(O) Current polyline line type. (Refer to Set Polyline Line Type function. ) intout(l) Current polyline line color index. intout(2) Current writing mode. (Refer to the Set Writing Mode function.) intout(3) End style for beginning point of polyline. intout(4) End style for ending point of polyline. ptsout(O) Current line width, in current coordinate system. ptsout(l) 0. 8-7 %or~n vu~ rj.UqLC&1LLU1f=J. Z -U~UV C BINDING Procedure Name vql-attributes( handle, attrib Data Types WORD vql_attributes WORD handle; WORD attrib[41; Input Arguments handle = contrl[61 Output Arguments attribC01 = intout[01 attribEll = intout[l] attrib[21 = intout[21 attrib[31 = ptsout[01 8-8 U "-1 9 U~ L I UY L U111ILL"L ~ ULAXU"- ~IA4U~L~ LU~VIUULM~l INQUIRE CURRENT This function reports the current setting of POLYMARKER all attributes that affect polymarkers, such ATTRIBUTES as marker type, marker color, marker height, and writing mode. Input contrl(O) Opcode = 36. contrl(l) Number of input vertices = 0. contrl(3) Length of intin array = 0. contrl(6) Device handle. Output contrl(2) Number of output vertices = 1. contrl(4) Length of intout array = 3. intout(O) Current polymarker marker type. (Refer to Set Polymarker Type function.) intout(l) Current polymarker marker color index. intout(2) Current writing mode. (Refer to the Set Writing Mode function for description. ) ptsout(O) Current polymarker width, in current coordinate system. ptsout(l) Current polymarker height, in current coordinate system. I--, 8-9 ULU-1 wu~ LLUYIMIwilel a UUIUC -LI144UILC LU.LYUVALFeL JILLILLJULMa C BINDING Procedure Name vqin_attributes( handle, attrib Data Types WORD vqv~__attributes WORD handle; WORD attrib[43; Input Arguments handle = contrl[61 Output Arguments attrib[O] = intout[Ol attrib[l] = intout(l] attrib[2] = intout[21 attrib[31 = ptsout[l] 8-10 INQUIRE CURRENT This function reports the current setting of FILL AREA all attributes that affect fill areas, such ATTRIBUTES as interior style, fill color, fill style index, and writing mode. Input contrl(O) Opcode = 37. contrl(l) Number of input vertices = 0. contrl(3) Length of intin array = 0. contrl(6) Device handle. Output contrl(4) Number of output vertices = 0. contrl(6) Length of intout array = 5. intout(O) Current fill area interior style. (Refer to Set Fill Interior Style function.) intout(l) Current fill area color index. intout(2) Current fill area style index. (Refer to Set Fill Style Index function.) intout(3) Current writing mode. (Refer to the Set Writing Mode function.) intout(4) Current fill perimeter status. 8-11 ur,m viii i-rogrammer s uuiae -LnquiLe ri-L-L Aled PLLL111JULt!b C BINDING Procedure Name vqf-attributes( handle, attrib Data Types WORD vqf attributes( WORD handle; WORD attrib[41; Input Arguments handle = contrl[61 Output Arguments attrib[O] = intout[01 attrib[l] = intout[l] attrib[2] = intout[21 attrib[31 = intout[31 B-12 INQUIRE CURRENT This function returns the current setting of GRAPHIC TEXT all attributes that affect graphic text, such ATTRIBUTES as text size, text color, text face alignment, baseline rotation, and writing mode. Input contrl(O) Opcode = 38. contrl(l) Number of input vertices = 0. contrl(3) Length of intin array = 0. contrl(6) Device handle. Output contrl(2) Number of output vertices = 2. contrl(4) Length of intout = 6. intout(O) Current graphic text face. intout(l) Current graphic text color index. intout(2) Current angle of rotation of text baseline ( in tenths of degrees 0-3600). intout(3) Current horizontal alignment. ( Refer to Set Graphic Text Alignment function.) intout(4) Current vertical alignment. (Refer to Set Graphic Text Alignment function.) intout(5) Current writing mode. (Refer to the Set Writing Mode function.) ptsout(O) Current character width in current coordinate system. ptsout(l) Current character height in current coordinate system. ptsout(2) Current character cell width in current coordinate system. ptsout(3) Current character cell height in current coordinate system. B-13 C BINDING Procedure Name vqt-attributes( handle, attrib Data Types WORD vqt attributes WORD handle; WORD attrib[101; Input Arguments handle = contrl[61 Output Arguments attrib[01 = intout[01 attrib[l] = intout[l] attrib[51 = intout[5] attrib[61 = ptsout[01 attrib[91 = ptsout[31 8-14 ULA-1 VIJ.L ILUYLULIMML 4 Wulut- INQUIRE TEXT This function returns a rectangle that EXTENT encloses the requested string. The coordinates of the vertices are given relativeto a coordinate system defined such that the extent rectangle touches both the x and y axes, and the string is in the first quadrant. All text attributes, including style and baseline rotation, affect the calculation. -3 2 4- X-axis t 1 Y-axis Figure B-1. Inquire Text Extent Function Input contrl(O) Opcode = 116. contri(l) Number of input vertices = 0. contrl(3) Number of words in text. contrl(6) Device handle. intin Character string in current character set. 8-15 Output contrl(2) Number of output vertices = 4. contrl(4) Length of intout array = 0. ptsout(O) delta-x for point 1 of the s t r i n g in the current coordinate system. ptsout(l) delta-y for point 1 of the s t r i n g in the current coordinate system. ptsout(2) delta-x for point 2 of the str ing in the current coordinate system. ptsout(3) delta-y for point 2 of the s t r i n g in the current coordinate system. ptsout(4) delta-x for point 3 of the s t r i n g in t h e current coordinate system. ptsout(5) delta-y for point 3 of the s t r i n g in the current coordinate system. ptsout(6) delta-x for point 4 of the s t r i n g in the current coordinate system. ptsout(7) delta-y for point 4 of the s t r i n g in the current coordinate system. C BINDING Procedure Name vqt-extent( handle, string, extent Data Types WORD vqt_extent( WORD handle; WORD extent[B]; BYTE string[]; Input Arguments handle = contrl[61 string = intin Output Arguments extentE01 = ptsout[01 extent[71 = ptsout[71 B-16 uLm vui Programmer s uuiuu IlIqUiLe VVIULIL INQUIRE CHARACTER This function returns the character cell CELL WIDTH width for a specified character in the current text face. The character cell width is the distance from the left edge of the character to the left edge of the character that follows it in a text string. Special effects and rotation do not apply. GEM VDI returns all values in the current coordinate system. Left Character Right Character Alignment Alignment Delta Delta Character Height -VV Cell Height Character Width C5 Width Figure 8-2. Character Cell Definition Input contrl(O) -- Opcode = 117. contrl(l) Number of input vertices = 0. contrl(3) Length of intin array = 1. contrl(6) Device handle. intin(O) Character value in current character set in ADE format. 8-17 Output contrl(2) Number of output vertices = 3. contrl(4) Length of intout array = 1. intout(O) ADE value of the character being inquired on; -1 if an invalid character (status). ptsout(O) Cell width of the character in the current coordinate system. ptsout(l) 0. ptsout(2) Left character alignment delta. ptsout(3) 0. ptsout(4) Right character alignment delta. ptsout(5) 0. C BINDING Procedure Name status = vqt width( handle, character, &cell-wfdth, &left-delta, &right-delta Data Types WORD status; WORD vqt width( WORD hanale; BYTE character; WORD cell width, WORD left delta; WORD righ-t-delta; Input Arguments handle = contrl[63 character = intin[01 Output Arguments status = intout[03 cell-width = ptsout[01 left ' delta = ptsout[21 righIE-delta = ptsout[41 8-18 INQUIRE FACE NA14E This function returns a 32-character string AND INDEX that describes the face. The face is selected by its element number (1 to the number of faces available). One word of zero in the intin array terminates the string. The string describing the face is returned in ADE form in intout(l ... 32). The face ID to access this face with Set Text Face is returned in intout(l). The first 16 characters name the face. The next 16 characters describe the style and weight. See Table 8-1 for a sample of the possible configurations. Table 8-1. Face Names and Styles Face Name F Styles Swiss 721 Light Swiss 721 Thin Italic Dutch 801 Roman Dutch 801 Bold Italic Input contri(O) Opcode = 130. contrl(l) Number of input vertices 0. contrl(3) Length of intin array = 1. contrl(6) Device handle. intin(O) Element number. Output contrl(2) Number of output vertices 0. contrl(4) Length of intout array = 33. intout(O) ID number. intout(l) to intout(32) - 32 ADE. 8-19 C BINDING Procedure Name index = vqt-name( handle, element-num, name Data Types WORD index; WORD vqt name( WORD handle; WORD element num, BYTE name[32J; Input Arguments handle = contr[61 element-num = intin[01 Output Arguments index = intout[O] name[01 intout[l] n;me[311 intout[321 Note: The BYTE array elements contain the eight least significant bits of the intout array elements. The array is terminated with a null byte. 8-20 ~,XZVI VU1 r L Uk3 L CL11111M L ZD "U~U= INQUIRE CURRENT This function returns size information for FACE INFOR14ATION the current face with the current size and special effects. Because the special effects may change the cell width and extent, a value is returned to allow the use of the width information returned in Inquire Character Cell Width. When the character is skewed, the cell contains left and right offsets as shown in Figure 8-3. Right Offset Left Offset Character Baseline Figure 8-3. Right and Left offset Input contrl(O) Opcode = 131. contrl(l) Number of input vertices 0. contrl(3) Length of intin array = 0. contrl(6) Device handle. Output contrl(2) Number of output vertices 5. contrl(4) Length of output array = 2. intout(O) Minimum ADE (ASCII Decimal Equivalent) the first character in this face. intout(l) Maximum ADE, the last character in this face. ptsout(O) Maximum cell width not including special effects. ptsout(l) Bottom line distance relative to baseline. ptsout(2) Special effects delta x. The c u r r e n t s p e c 1 a 1 effects increase character width by this amount. GEM VDI Programmer's Guide Inquire Current Face Information ptsout(4) Left offset; (see Figure 8-2) positive value relative to position. ptsout(5) Half distance relative to baseline. ptsout(6) Right offset (see Figure 8-2). ptsout(7) Ascent distance relative to baseline. ptsout(8) 0. ptsout(9) Top distance relative to baseline. C BINDING Procedure Name vqt_fontinfo( handle, &minADE, &maxADE, distances, &maxwidth, effects Data Types WORD vqt_fontinfo( WORD handle; WORD minADE; WORD maxADE; WORD distances[51; WORD maxwidth; WORD effects[31, Input Arguments handle = contrl[61 Output Arguments minADE = intout[O] maxADE = intout[l] distances[O] = ptsout[l] distances[l] = ptsout[31 distances[21 = ptsout[5] distances[31 = ptsout[71 distances[41 = ptsout[91 maxwidth = ptsout[O] effects(03 = ptsout[21 effects[l] = ptsout[41 effects[21 = ptsout[61 8-22 GEM VDI Programmer's Guide Inquire Cell Array INQUIRE CELL ARRAY This function returns the cell array definition of the specified pixels. Color indices are returned one row at a time, starting from the top of the rectangular area, proceeding downward. Note: This function is not required and may not be available on all devices. Input contrl(O) Opcode = 27. contrl(l) Number of input vertices = 2. contrl(3) Length of intin array = 0. contrl(6) Device handle. contrl(7) Length of each row in color index array. contrl(8) Number of rows in color index array. ptsin(O) x-coordinate of lower left corner in current coordinate system. ptsin(l) y-coordinate of lower left corner in current coordinate system. ptsin(2) x-coordinate of upper right corner in current coordinate system. ptsin(3) y-coordinate of upper right corner in current coordinate system. Output contrl(2) Number of output vertices = 0. contrl(4) Length of the color index array, same as contrl(3). contrl(9) Number of elements used in each row of color index array. contrl(10) Number of rows used in color index array. contrl(ll) Invalid value flag. 0 if no errors 1 if a color value could not be determined for some pixel 8-23 %ican VLJ.L rkoqLaminel b %julue ~Ilqu.LL"~t:.L.L ^LLay intout Color index array, stored one row at time. -1 -- indicates that a color index could not be determined for that particular pixel C BIMING Procedure Name vq_cellarray( handle, pxyarray, row_length, num-rows, &el-used, &rows-used, &status, colarray ) Data Types WORD vq_cellarray( WORD handle; WORD pxyarray[43; WORD row - length; WORD num_rows; WORD el used; WORD rows-used; WORD status; WORD colarray[n]; Input Arguments handle = contrl[61 pxyarray[O] = ptsin[01 pxyarray[l] = ptsin[l] pxyarray[21 = ptsin[21 pxyarray[31 = ptsin[31 row_length = contrl[71 num-rows contrl[81 Output Arguments el - used contrl[91 rows used = contrl[101 stat-us = contrl[lll colarray[03 = intout[01 colarray[n] = intin[n] 8-24 U1311 I I] I I 1 8 91 011111110 1 0 UM IN 1 5 011L i's 111 8-0 INQUIRE INPUT MODE This function returns the current input mode for the specified logical input device: locator, valuator, choice, and string. Input contrl(O) Opcode = 115. contrl(l) Number of input vertices = 0. contrl(3) Length of intin array = 1. contrl(6) Device handle. intin(O) Logical input device. 1 = locator 2 = valuator 3 = choice 4 = string Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 1. intout(O) Input mode. I = request 2 = sample C BINDING Procedure Name vqin-mode( handle, dev-type, &input_mode Data Types WORD vqin mode( WORD handle; WORD dev-type; WORD input-mode; Input Arguments handle = contrl[6] dev-type = intin[01 Output Arguments input_mode = intout[01 End of Section 8 8-25 ...... Section 9 Escapes ESCAPE The Escape function allows the application program to access the special capabilities of a graphics device. GEM VDI predefines some escape functions; others can be defined for specific devices. The parameters passed depend on the escape function the application requests. Input contrl(O) Opcode = 5. contrl(l) Number of input vertices. contfl(3) Number of input parameters. contrl(5) Function identifier (id). contrl(6) D(-vice handle. Table 9-1. Escape Function Identifiers Number Description 1 INQUIRE ADDRESSABLE ALPHA CHARACTER CELLS 2 EXIT ALPHA MODE 3 ENTER ALPHA MODE 4 ALPHA CURSOR UP 5 ALPHA CURSOR DOWN 6 ALPHA CURSOR RIGHT 7 ALPHA CURSOR LEFT 8 HOME ALPHA CURSOR 9 ERASE TO END OF ALPHA SCREEN 10 ERASE TO END OF ALPHA TEXT LINE 11 DIRECT ALPHA CURSOR ADDRESS 12 OUTPUT CURSOR ADDRESSABLE ALPHA TEXT 13 REVERSE VIDEO 6N 9-1 Table 9-1. (continued) Number Description 14 REVERSE VIDEO OFF 15 INQUIRE CURRENT ALPHA CURSOR ADDRESS 16 INQUIRE TABLET STATUS 17 HARD COPY is PLACE GRAPHIC CURSOR AT LOCATION 19 REMOVE LAST GRAPHIC CURSOR 20 FORM ADVANCE 21 OUTPUT WINDOW 22 CLEAR DISPLAY LIST 23 OUTPUT BIT IMAGE FILE 24-59 UNUSED BUT RESERVED FOR FUTURE EXPANSION 60 SELECT PALETTE 61-90 UNUSED BUT RESERVED FOR FUTURE EXPANSION 91 INQUIRE PALETTE FILM TYPES 92 INQUIRE PALETTE DRIVER STATE 93 SET PALETTE DRIVER STATE 94 SAVE PALETTE DRIVER STATE 95 SUPPRESS PALETTE MESSAGES 96 PALETTE ERROR INQUIRE 98 UPDATE METAFILE EXTENTS 99 WRITE METAFILE ITEM 100 CHANGE GEM VDI FILENAME >100 UNUSED AND AVAILABLE FOR USE 9-2 %~L-I VU.L CLuqLCIUIIIIeL 5 k~ulue z5capes intin Function-dependent information described on following pages. ptsin Array of input coordinates for escape function. Output contrl(2) Number of output vertices. contrl(4) Number of output parameters. intout Array of output parameters. ptsout Array of output coordinates. 9-3 ESCAPE 1: INQUIRE This escape returns information to the ADDRESSABLE ALPHA calling program about the number of vertical CHARACTER CELLS (row) and horizontal (column) positions at which the alpha cursor can be positioned on the screen. Typically, only screens support alpha text. Input contrl(O) Opcode = 5. contrl(l) Number of input vertices = 0. contrl(3) Length of intin array = 0. contri(S) Function A = 1. contrl(6) Device handle. Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 2. intout(O) Number of addressable rows on the screen, (-l indicates cursor addressing not possible). intout(l) Number of addressable columns on the screen, (-l indicates cursor addressing not possible). C BIMING Procedure Name vq_chcells( handle, &rows, &columns Data Types WORD vq_chcells WORD handle; WORD rows; WORD columns; Input Arguments handle = contrl[63 Output Arguments rows = intout[01 columns = intout[l] 9-4 GEM VDI Programmer's Guide Exit Alpha Mode ESCAPE 2: EXIT This escape causes the graphics device to ALPHA MODE enter graphics mode if graphics mode is different from alpha mode. It is used to exit alpha cursor addressing mode explicitly and to make the transition from alpha to graphics mode properly. Input contrl(O) Opcode = 5. contrl(l) Number of input vertices = 0. contrl(3) Length of intin array = 0. contrl(5) Function id = 2. contrl(6) Device handle. Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 0. C BINDING Procedure Name v-exit-cur( handle Data Types WORD v - exit - cur WORD handle; Input Arguments handle = contrl[63 9-5 ESCAPE 3: ENTER This escape causes the graphics device to ALPHA MODE exit graphics mode if graphics mode is different from alpha mode. It is used to enter the alpha cursor addressing mode explicitly and to make the transition from graphics to alpha mode properly. This opcode also returns the cursor to the upper left character cell of the display device. Input contrl(O) Opcode = 5. contrl(l) Number of input vertices = 0. contrl(3) Length of intin array = 0. contrl(5) Function id = 3. contrl(6) Device handle. Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 0. C BINDIM Procedure Name v-enter-cur( handle Data Types WORD v enter cur WORD h~andle; Input Arguments handle = contrl[61 9-6 ESCAPE 4: ALPHA This escape moves the alpha cursor up one row CURSOR UP without altering its horizontal position. if the cursor is already at the top margin, nothing happens. Input contrl(O) Opcode = 5. contrl(l) Number of input vertices = 0. contrl(3) Length of intin array = 0. contrl(5) Function id = 4. contrl(6) Device handle. Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 0. C BINDIISG Procedure Name v_curup( handle Data Types WORD v_curup WORD handle; Input Arguments handle = contrl[61 ESCAPE 5: ALPHA This escape moves the alpha cursor down one CURSOR DOWN row without altering its horizontal position. If the cursor is already at the bottom margin, nothing happens. Input contri(O) Opcode = 5. contrl(l) Number of input vertices = 0. contrl(3) Length of intin array = 0. contrl(5) Function id = 5. contrl(6) Device handle. Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 0. C BIMING Procedure Name v-curdown( handle Data Types WORD v curdown WORD h-andle; Input Arguments handle = contrl[61 9-8 ~ I I ~ L U13 L a 1-1M ~ . - - - -11-- -1 ~ Ij . . I ESCAPE 6: ALPHA The Alpha Cursor Right escape moves the alpha CURSOR RIGHT cursor right one column without altering its vertical position. If the cursor is already at the right margin, nothing happens. Input contri(O) Opcode = 5. contri(l) Number of input vertices = 0. contrl(3) Length of intin array = 0. contrl(5) Function id = 6. contrl(6) Device handle. Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 0. C BINDING Procedure Name v_curright( handle Data Types WORD v curright WORD h~andle; Input Arguments handle = contrl[61 1~ ESCAPE 7: ALPHA The Alpha Cursor Left escape moves the alpha CURSOR LEFT cursor left one column without altering its vertical position. If the'cursor is already at the left margin, nothing happens. Input contrl(O) Opcode = 5. contrl(l) Number of input vertices = 0. contrl(3) Length of intin array = 0. contrl(5) Function id = 7. contrl(6) Device handle. Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 0. C BIMIM Procedure Name v-curleft( handle Data Types WORD v - curleft WORD handle, Input Arguments handle = contrl[6) 9-10 ESCAPE 8: H014E This escape moves the alpha cursor to the ALPHA CURSOR home position, usually the upper left character cell of the display device. Input contrl(O) Opcode = 5. contri(l) Number of input vertices = 0. contrl(3) Length of intin array = 0. contrl(5) Function id = 8. contrl(6) Device handle. Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 0. C BINDING Procedure Name v-curhome( handle Data Types WORD v-curhome WORD handle; Input Arguments handle = contrl[61 -La~= LV ~11U UL ~.Lplla acreen ESCAPE 9: ERASE This escape erases the display surface from TO END OF ALPHA the current alpha cursor position to the end SCREEN of the alpha screen. The current alpha cursor location does not change. Input contrl(O) Opcode = 5. contrl(l) Number of input vertices = 0. contrl(3) Length of intin array = 0. contrl(5) Function id = 9. contrl(6) Device handle. Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 0. C BINDING Procedure Name v-eeos( handle Data Types WORD v eeos WORD h~andle; Input Arguments handle = contrl[61 9-12 - - L~U%JLULIULL~L 0 UU~U~ "Luz~ uu ~Iiu u~ A-VILu ESCAPE 10: ERASE This escape erases the display surface from TO END OF ALPHA the current alpha cursor position to the end TEXT LINE of the current alpha text line. The current alpha cursor location does not change. Input contrl(O) Opcode = 5. contrl(l) Number of input vertices = 0. contrl(3) Length of intin array = 0. contrl(5) Function id = 10. contrl(6) Device handle. Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 0. C BINDING Procedure Name v-eeol( handle Data Types WORD v - eeol WORD handle; Input Arguments handle = contrlE61 9-13 -L~ -P110 'ULbuz -UuLebb ESCAPE 11: DIRECT The Direct Alpha Cursor Address escape moves ALPELA CURSOR the alpha cursor directly to the specified ADDRESS row and column address anywhere on the display surface. Addresses beyond the displayable range of the screen are set to the nearest value that is within the displayable range of the screen. Input contrl(O) Opcode = 5. contrl(l) Number of input vertices = 0. contrl(3) Length of intin array = 2. contrl(5) Function id = 11. contrl(6) Device handle. intin(O) Row number (1 to maximum number of rows). intin(l) Column number (1 to maximum number of columns). Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 0. C BIMING Procedure Name vs-curaddress( handle, row, column Data Types WORD vs ' curaddress WORD hai~dle; WORD row; WORD column; Input Arguments handle = contrl[61 row = intin[O] column = intin[l] 9-14 GEM VDI Programmer's Guide Output Cursor Addressabie Alpha Text ESCAPE 12: OUTPUT This escape displays a string of alpha text CURSOR ADDRESSABLE starting at the current cursor position. ALPHA TEXT The alpha text attributes currently in effect determine alpha text attributes. Input contrl(O) Opcode = 5. contrl(l) Number of input vertices = 0. contrl(3) Number of characters i n character string. contrl(5) Function id = 12. contrl(6) Device handle. intin Text string in ADE. Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 0. C BINDING Procedure Name v-curtext( handle, &string Data Types WORD v-curtext WORD handle; BYTE string[]; Input Arguments handle = contrlE61 string = intin Note: The BYTE values contain the eight least significant bits of the intin array. 9-15 GEM VDI Programmer's Guide Reverse Video On ESCAPE 13: This escape displays all subsequent alpha REVERSE text in reverse video. VIDEO ON Input contrl(O) Opcode = 5. contrl(l) Number of input vertices = 0. contrl(3) Length of intin array = 0. contrl(5) Function id = 13. contrl(6) Device handle. Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 0. C BINDIM Procedure Name v-rvon( handle Data Types WORD r - von ( ); WORD handle; Input Arguments handle = contrl[61 9-16 GEM VDI Programmer's Guide Reverse Video Off ESCAPE 14: This escape displays all subsequent alpha REVERSE text in normal video format. VIDEO OFF Input contrl(O) Opcode = 5. contrl(l) Number of input vertices = 0. contrl(3) Length of intin array = 0. contrl(5) Function id = 14. contrl(6) Device handle. Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 0. C BINDING Procedure Name v-rvoff( handle Data Types WORD v-rvoff WORD handle; Input Arguments handle = contrl(6) L-EA VIJI F1LJY1dUU11U1 b MIUM 11114U11N LULIL111L AIP118 LUL3UL JLUUiq!33 ESCAPE 15: This escape returns the current position of INQUIRE CURRENT the alpha cursor in row, column coordinates. ALPHA CURSOR ADDRESS Input contrl(O) Opcode = 5. contri(l) Number of input vertices = 0. contrl(3) Length of intin array = 0. contrl(5) Function id = 15. contrl(6) Device handle. Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 2. intout(O) Row number (1 to the maximum number of rows). intout(l) Column number (1 to the maximum number of columns). C BI19DING Procedure Name vq_curaddress( handle, &row, &column Data Types WORD vq_curaddress WORD handle; WORD row; WORD handle; Input Arguments handle = contrl[61 Output Arguments row = intout[01 column = intout[l] 9-18 ~1114U.Llt- XUU.LCL ULULUS ESCAPE 16: This escape returns the availability status INQUIRE TABLET of a graphics tablet, mouse, joystick, or STATUS other similar device. Input contrl(O) Opcode = 5. contrl(l) Number of input vertices = 0. contrl(3) Length of intin array = 0. contrl(5) Function id = 16. contrl(6) Device handle. Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 1. intout(O) Tablet status. 0 = tablet not available 1 = tablet available C BINDING Procedure Name status = vq_tabstatus( handle Data Types WORD vq_tabstatus WORD handle; WORD status; Input Arguments handle = contrl[61 Output Arguments status = intout[01 9-19 ESCAPE 17: HARD The device generates a hard copy with this COPY escape. The escape is device-specific and copies the physical screen to a printer or other attached hard copy device. Input contri(O) Opcode - 5. contri(l) Number of input vertices = 0. contrl(3) Length of intin array = 0. contri(S) Function id = 17. contrl(6),-- Device handle. Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 0. C BIMING Procedure Name v-hardcopy( handle Data Types WORD v - hardcopy WORD handle; Input Arguments handle = contrl[61 9-20 U uu~uk_ L-LULt! ULMV111L t~ULSUL aL JjUUciL10r1 ESCAPE 18: PLACE This escape places a graphic cursor at the GRAPHIC CURSOR specified location. The cursor is usually a AT LOCATION cross hair cursor and is of the same type as that used for Input Locator, Request Mode. If sample mode input is supported, the application can use this call to generate the cursor for Input Locator, Sample Mode. In memory-mapped devices, the cursor is drawn in XOR mode so GEM VDI can remove it. Input contrl(O) Opcode = 5. contrl(l) Number of input vertices = 1. contrl(3) Length of intin array = 0. contrl(5) Function id = 18. contrl(6) Device handle. ptsin(O) x-coordinate of location to place cursor in current coordinate system. ptsin(l) y-coordinate of location to place cursor in current coordinate system. Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 0. C BINDING Procedure Name v-dspcur( handle, x, y Data Types WORD v_dspcur WORD handle; WORD x, y; Input Arguments handle = contrl[61 x = ptsin[01 y = ptsin[l] 9-21 ESCAPE 19: REMOVE This escape removes the last graphic cursor 1AST GRAPHIC placed on the screen. CURSOR Input contrl(O) Opcode = 5. contrl(l) Number of input vertices = 0. contrl(3) Length of intin array = 0. contrl(5) Function id = 19. contrl(6) Device handle. Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 0. C BIMING Procedure Name v-rmcur( handle Data Types WORD v - rmcur WORD handle; Input Arguments handle = contrl[61 9-22 --- - ~ ~ ~ I -j ~ ~ 111A- & ru."11 muvdilUe ESCAPE 20: FORM This escape is required only for printers. ADVANCE It advances the printer page. This escape can be used instead of invoking a Clear Workstation function if it is desirable to retain the current printer display list while advancing to the next page. Input contrl(O) Opcode = 5. contrl(l) Number of input vertices = 0. contrl(3) Length of intin array = 0. contrl(5) Function id = 20. contrl(6) Device handle. 0utput contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 0. C BINDING Procedure Name v-form-adv( handle Data Types WORD v form-adv( WORD h-andle, Input Arguments handle = contrl[61 1~ 9-23 ESCAPE 21: OUTPUT This escape is required only for printers. WINDOM It allows the application to request that a particular rectangular window of the picture be output to the printer. This escape is similar to the Update Workstation function, except that the rectangular area must be specified. Note that use of this function does not always guarantee that adjacent pictures will abut. Pictures will abut with a resolution of one printer head height. Input contrl(O) Opcode = 5. contrl(l) Number of input vertices = 2. contrl(3) Length of intin array = 0. contrl(5) Function id = 21. contrl(6) Device handle. ptsin(O) x-coordinate of corner of window to be output in NDC/RC. ptsin(l) y-coordinate of corner of window to be output in NDC/RC. ptsin(2) x-coordinate of corner of window, diagonally opposite corner selected in ptsin(O), in NDC/RC. ptsin(3) y-coordinate of corner of window, diagonally opposite corner selected in ptsin(l in NDC/RC. Output contrl(2) Number of output vertices 0. contrl(4) Length of intout array = 0. 9-24 C BINDING Procedure Name v_output-window( handle, xyarray Data Types WORD v - output_window( WORD handle; WORD xyarray[41; Input Arguments handle = contrl[61 xyarray[O] = ptsin[O] x yarraYE31 = ptsin[31 9-25 ESCAPE 22: CLEAR This escape is required only for printers. DISPLAY LIST It allows the application to request that the printer display list be cleared. It is similar to the Clear Workstation function, but does not cause a form advance on the printer. Input contrl(O) Opcode = 5. contrl(l) Number of input vertices = 0. contrl(3) Length of intin array = 0. contrl(5) Function id = 22. contrl(6) Device handle. Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 0. C BIRDING Procedure Name v-clear-disp_list( handle Data Types WORD v - clear - disp_list( WORD handle; Input Arguments handle = contrl[61 ---1 9-26 ESCAPE 23: OUTPUT This escape is required only for printers. BIT IMAGE FILE It allows the application to request processing of a bit image file (see Appendix I, "Bit Image File Format") . As input parameters, the application provides a filename and information on image transformation and page placement. The application uses thi:ee parameters to control image transformation: • pixel aspect ratio flag • x-axis scaling flag • y-axis scaling flag The application can set the pixel aspect ratio flag to preserve or ignore the pixel aspect ratio def ined in the bit image f ile. Preserving pixel aspect ratio means the printed object will have the same aspect ratio it had on the device on which it was originally drawn. For example, squares remain squares, and circles remain circles. Ignoring pixel aspect ratio means the printed object will not necessarily have the same aspect ratio it had on the original device. The application can set the two axis scaling flags independently of each other. The flags determine if the bit image's x or y axes are to be scaled fractionally or in integer multiples. The upward boundary of this scaling is an application-defined rectangle. If an axis of the bit image is scaled fractionally, it will exactly f it the corzesponding axis of the scaling rectangle, with the exception noted below. If an axis of the bit image is scaled in integer multiples, it might not exactly fit the corresponding axis of the scaling rectangle. If the scaled bit image does not exactly fit the scaling rectangle, the application can use alignment parameters to locate the bit image within the rectangle. These parameters allow any combination of three vertical and three horizontal positions. 9-27 u~ri vui rLUkjLa11U1t"L b "UIU~ UU~L- ~ r- Note: The scaled bit image always resides within the scaling rectangle. If a combination of preserved pixel aspect ratio, scaling, or alignment causes the scaled bit image to extend beyond an edge of the scaling rectangle, GEM VDI clips the bit image to that edge. Input contrl(O) Opcode = 5. contrl(l) Number of input vertices = 2. contrl(3) Length of intin array = length of filename + 5. contrl(5) Function id = 23. contrl(6) Device handle. intin(O) Aspect ratio flag. 0 = ignore aspect ratio 1 = honor pixel aspect ratio intin(l) Scaling for x-axis. 0 = fractional scaling 1 = integer scaling intin(2) Scaling for y-axis. 0 = fractional scaling 1 = integer scaling intin(3) Horizontal alignment. 0 = left 1 = center 2 = right intin(4) Vertical alignment. 0 = top 1 = middle 2 = bottom intin(5) First character of filename. intin(n+4)-- L a s t (nth) character of f ilename. 9-28 _2 11191111111ILL U MUL WIWI gil IMMe; Pile ptsin(O) Upper left x (if specified). ptsin(l) Upper left y (if specified). ptsin(2) Lower right x (if specified). ptsin(3) Lower right y (if specified). Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 0. C BINDING Procedure Name v-bit-image( handle, filename, aspect, x scale, y scale, h align, v-align, xyarray Data Types WORD v bit imageo; BYTE filename[]; WORD handle, aspect, x - scale, y-scale, h align, v align-, WORD xyarray[); Input Arguments handle = contrl[6] filename = intin[2] . . . intin[n + 11 aspect intin[01 x-scale intin[l] y scale intin[21 h align intin[3] v align intin[41 xyarray[01 = ptsin[01 xyarray[l) = ptsin[l] xyarray[21 = ptsin[21 xyarray[31 = ptsin[31 Note: Bytes for the filename array are mapped into the corresponding eight least significant bits of intin. The string must be null terminated. ESCAPE 60: SELECT This escape allows the selection of the PALETTE palette on the IBM6 medium-resolution color screen. Input contrl(O) Opcode = 5. contri(l) Number of input vertices = 0. contrl(3) Length of input array = 1. contrl(5) Function id = 60. contrl(6) Device handle. intin(O) Color selection. 0 = use red, green, brown palette (default) 1 = use cyan, magenta, white palette Output contrl(2) Number of output vertices 0. contrl(4) Length of intout array intout(O) Palette selected. C BINDING Procedure Name selected vs_palette( handle, palette Data Types WORD vs_palette( WORD handle; WORD palette; Input Arguments handle contrl[61 palette intin[03 Output Arguments selected = intout[01 9-30 LU.Ld1U1U rdIULLM POLAROID(D PALETTE Use these escapes to modify the operation of the Polaroid Palette image recorder. While their use is not mandatory, they allow construction of a more efficient user interface. Palette Driver These escapes affect a header in the palette driver. The header contains information on the current state of the driver and the types of films it can use. The palette driver contains exposure tables for five film types. A 25 character string describes each film type, stating its manufacturer and its ASA number. These strings are padded with blanks if the information requires less than 25 characters. Seventy-two colors are defined for each film type. These colors are mapped to an 8 x 9 array with ASCII capitals (A ... H), naming the columns and ASCII digits (I ... 9), numbering the rows. A color is selected by its letter and number. For example, A2 identifies the second color in column A. Numbers also identify the port to which the palette is connected, an f-stop control, and a resolution control for environments where memory size prevents the use of the Palette's full capabilities. The palette driver normally outputs its messages directly to the screen. These messages include error messages and user prompts. Error Messages The palette error messages appear when the application calls GEM VDI with a function other than Open Workstation, Close Workstation,or any of the Escape functions. These messages can be suppressed with Escape 95. The application can then use the code returned from Escape 96 to inform the user of the error condition. 9-31 GEM VDI Programmer's Guide Inquire Palette F1IM -lypes ESCAPE 91: This escape returns five strings that INQUIRE PALETTE describe the films that the driver is FILM TYPES currently capable of exposing. The strings are padded with spaces if they have fewer than 25 characters. The strings are returned as ADE integers in intout. Input contrl(O) Opcode = 5. contrl(l) Number of input vertices = 0. contrl(3) Length of intin array = 0. contrl(5) Function id = 91. contrl(6) Device handle. Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout = 125. intout 5 sets of 25 ADE character strings. C BIMING Procedure Name vqp_films( handle, film-names Data Types WORD vqp_films( WORD handle; WORD film-names[1251; Input Arguments handle = contrl[61 Output Arguments film-names = intout Note: Intout words (ADE) are converted to byte string. 9-32 "~,-i vvL riogrammer s ~juiae inquire eaiette uriver btate ESCAPE 92: This escape returns a block of data that INQUIRE PALETTE describes the current state of the driver. DRIVER STATE The state can be updated by changing this block and returning it to the driver with Escape 93. Input contrl(O) Opcode = 5. contrl(l) Number of input vertices 0. contrl(3) Length of intin = 0. contrl(5) Function id = 92. contrl(6) Device handle. Output contrl(2) Number of output vertices 0. contrl(4) Length of intout array = 20. intout(O) Port number. 0 = first comm port intout(l) Film number (0 $). intout(2) Lightness control (-3 3). Each integer increase represents opening the aperture 1/3 of an f-stop. A -3 results in an exposure half as long as normal, while a 3 doubles the exposure time. intout(3) -- Interlace flag. 0 = noninterlaced I = interlaced A noninterlaced picture requires slightly more than h a 1 f t h e memory of an interlaced picture. intout(4) Planes, a number (1 4) corresponding to number of colors (2 ... 16). intout(5 to 20) Two-character color codes for 8 color indices stored in ADE format. 9-33 Uun Vul FlugidnLUIUL S kjulue 111t4U11LJ rdleLLU U11VULJLdLU C BINDIRG Procedure Name vqp-state( handle, &port, &film - name, &lightness, &interlace, &planes, &indexes ) Data Types WORD vqp-state( WORD handle; WORD port; WORD film name; WORD light~ness; WORD interlace; WORD planes; WORD indexes[8][2]; Input Arguments handle = contrl[61 Output Arguments port = intout[O] film name = intout[l] lightness = intout[2) interlace = intout[31 planes intout[41 indexes intout[5 ... 201 9-34 GEM VDI Programmer's Guide Set Palette Driver State ESCAPE 93: SET This escape moves a block of characteristics PALETTE DRIVER into the driver. Use this function after STATE Escape 92. Input contrl(O) Opcode = 5. contri(l) Number of input vertices = 0. contrl(3) Length of intin array = 20. contrl(5) Function id = 93. contrl(6) Device handle. intin(O) Port number. 0 = first comm port intin(l) Film number (0 4). intin(2) Lightness control (-3 3). Each integer indicates opening the aperture 1/3 an f-stop. A -3 results in an exposure half as long as normal, while a 3 doubles the exposure time. intin(3) Interlace flag. 0 = noninterlaced 1 = interlaced intin(4) P 1 a n e s (1 to 4 number corresponds to number of colors (2 to 16). intin(5 to 20) Color codes for up to 16 colors. 9-35 GEM VDI Programmer's Guide Set Palette Driver State C BINDING Procedure Name vsp-state( handle, port, film - num, lightness, interlace, planes, indexes Data Types WORD vsp_style( WORD handle; WORD port; WORD film num; WORD lightness, WORD interlace; WORD planes; WORD indexes[81[21; Input Arguments handle = contrl[61 port = intin[01 film num intin[l) lighiness intin[21 interlace intinC31 planes intin[41 indexes intin[5-201 9-36 GEM VDI Programmer's Guide Save Palette Driver State ESCAPE 94: SAVE This escape saves the current state of the PALETTE DRIVER driver to disk. The application can change STATE the default film and index mapping with this escape. Input contrl(O) Opcode = 5. contrl(l) Number of input vertices = 0. contrl(3) Length of intin array = 0. contrl(5) Function id = 94. contrl(6) Device handle. Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 0. C BIMING Procedure Name vsp_save( handle Data Types WORD vsp_save( WORD handle; Input Arguments handle = contrl[61 9-37 ESCAPE 95: This escape allows the application to SUPPRESS PALETTE suppress the messages the palette driver MESSAGES normally outputs to the screen. These messages are either error messages or user prompts. Refer to Escape 96 for the messages and their codes. Input contrl(O) Opcode = 5. contrl(l) Number of input vertices = 0. contrl(3) Length of intin array = 0. contrl(5) Function id = 95. contrl(6) Device handle. Output contrl(2) Number of output vertices = 0. contrl(4) Length of output array = 0. C BIMIRG Procedure Name vsp_message( handle Data Types WORD vsp_message( WORD handle; Input Arguments handle = contrl[61 9-38 GLM UJI vyglyl"Ap I unas Palette h1rror Inquire ESCAPE 96: This escape returns an error code so the PKLETTE ERROR application can notify the user of a problem. INQUIRE This escape also returns codes for pending user prompts. The error is not cleared, so a message can be displayed if such messages are not suppressed. Input contrl(O) Opcode = 5. contrl(l) Number of input vertices = 0. contrl(3) Length of intin array = 0. contrl(5) Function id = 96. contrl(6) Device handle. Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 1. intout(O) Error codes and pending user prompts. 0 = no error 1 = open dark slide for print film 2 = no port at location specified in driver 3 = palette not found at specified port 4 = video cable disconnected 5 = operating system does not allow memory allocation 6 = not enough memory to allocate buffer 7 = memory not deallocated 8 = driver file not found 9 = driver file found is not correct type 10= prompt user to process print film 9-39 C BINDING Procedure Name status = vqp_error( handle ) Data Types WORD vqp-error( ); WORD handle, Output Arguments status = intoutE01 Input Arguments handle = contrl[61 9-40 I.r,L-1 VL).L rLUgL~1111111t:!L ~:o UULUt! UpUdLe PleLdllle nxLenLs ESCAPE 98: UPDATE The values passed in the ptsin array are MET"ILE EXTENTS used to update the extents information in the metafile header. The extents information may be used by some applications to provide a quick indication of the minimum rectangle which will bound all primitives output to the metafile. If the Update Metafile Extents escape is not used when outputting to the metafile, zeroes will be written in the extents information portion of the metafile header. Input contrl(O) Opcode = 5. contrl(l) Number of input vertices = 2. contrl(3) Length of intin array = 0. contrl(5) Function id = 98. contrl(6) Device handle. ptsin(O) Minimum x value of the minimum bounding rectangle. ptsin(l) Minimum y value of the minimum bounding rectangle. ptsin(2) Maximum x value of the minimum bounding rectangle. ptsin(3) Maximum y value of the minimum bounding rectangle. Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 0. 9-41 ~ "-I I ~J- L I LPY L a LU Lit UL b UUIUe Upd1clite Metatiie Extents C BINDING Procedure Name v-meta-extents(handle, min_x, min_y, max-x, max_y) Data Types WORD v - meta-extentso; WORD handle, min-x, min-y, max_x, max_y; Input Arguments handle contrl[61; min-x ptsin[o]; min-Y ptsin[l]; max - x ptsin[21; max_y ptsin[31; 9-42 GEM Vol pr8jr3mrig Guim wtitg Mgtgfilg lE41K ESCAPE 99: WRITE The parameters passed in the intin and ptsin 14ETAFILE ITEM arrays are written to the metafile with an opcode defining the item as a user-defined metafile item. Intin(O) should contain a sub opcode that defines what type of user-defined metafile item is being written. Sub-opcodes numbered 0 through 100 are reserved; the sub opcode you use to define your metafile item should be numbered 101 or higher. Input contrl(O) Opcode = 5. contrl(l) Number of input vertices. contrl(3) Length of intin array. contrl(5) Function id = 99. contrl(6) Device handle. intin User-defined information. intin(O) Sub-opcode. ptsin User-defined information. Output contrl(2) Number of output vertices 0. contrl(4) Length of intout array = 0. C BINDING Procedure Name v-write - meta(handle, num-intin, intin, num-ptsin, ptsin) Data Types WORD v_write - metao; WORD handle, num intin, num ptsin; WORD intin[num-intin), ptsin[num-ptsin]; Input Arguments handle = contrl[61; num-intin = contrl[3); num-ptsin = contrl[l]; intin = intin; ptsin = ptsin; 9-43 ESCAPE 100: This escape renames a metafile from CHANGE GEN VDI GEMFILE.GEM to the specified name and FILENANE maintains the file extension GEM. A path name and drive can be specified to locate the file somewhere other than on the current drive and directory. Contrl(3) contains the length of the file specification string. Note: This escape must be called immediately after Open Workstation, or it has no effect. It also closes any open metafiles. Input contrl(O) Opcode = 5. contrl(l) Number of input vertices = 0. contrl(3) Length of intin array = number of significant characters El ... 743. contrl(5) Function id = 100. contrl(6) Device handle. intin(O to n) Path/filename. Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 0. C BINDIAG Procedure Name vm-filename( handle, filename Data Types WORD vm filename( WORD haiidle; BYTE filename[ 1; Input Arguments handle = contrl[61 filename = intin[O-n] Note: The filename must be null-terminated. End of Section 9 9-44 Appendix A GEM VDI Error Messacress E,-- Command line syntax error Description: The GEM VDI command line includes an illegal character, path, or drive id. Solution: Check for conformance to your operating system's conventions for specifying command lines. Reenter the command line after correcting illegal entries. Unable to find ASSIGN.SYS Description: This message appears when GEM VDI is unable to find the ASSIGN.SYS file in the specified location. Solution: Locate the ASSIGN.SYS file, checking drives and specific directories and subdirectories. Reenter the command with the correct location. Error reading ASSIGN.SYS Description: The format of the ASSIGN.SYS file is incorrect. GEM VDI cannot use the file. Solution: Refer to Appendix B for the correct format for the ASSIGN.SYS file. Memory table corrupted Description: This message appears when memory is corrupted. Solution: Reboot your system. Insufficient memory Description: This message appears when you try to reserve memory and not enough memory exists for allocation. Solution: If your systemhas adequate memory to run GEM VDI, reboot your system. A-1 Invalid memory block address Description: This message occurs when the memory is corrupted. Solution: Reboot the system. Drive specification not allowed in ASSIGN.SYS Description: This error appears when you specify a drive id in the ASSIGN.SYS file, which is illegal. Solution: Remove the drive id from the file with your text editor. Refer to Appendix B for the correct format of an ASSIGN.SYS file. Illegal device id in ASSIGN.SYS Description: This error appears when the device id number is greater than 32767 or an alphanumeric string, for example 12D4. Solution: Refer to Table 1-1 in Section I for the correct numbers to assign to devices, and correct the ASSIGN.SYS file with your text editor. Partial record found in ASSIGN.SYS Description: This error appears when a partial ASSIGN.SYS entry exists. Solution: Check your ASSIGN.SYS file for incomplete device id numbers or filenames. Refer to Appendix B for the correct ASSIGN.SYS file format. Invalid filename encountered in ASSIGN.SYS Description: This error appears when a filename in the ASSIGN.SYS file is too long or contains illegal characters. Solution: Refer to Appendix B for the ASSIGN.SYS file-naming conventions. A-2 UZI-I VL)JL rLOYIdIIIIIIel S k~ulae L-- vui mrror messages Requested path not found Description: This message appears when GEM VDI does not find the requested path specifying the locations of the device drivers. Solution: Respecify the path with the correct path name. ASSIGN.SYS file is empty Description: This message appears when GEM VDI finds an empty ASSIGN.SYS file. Solution: Enter the necessary information with your text editor. Refer to Appendix B for the necessary ASSIGN.SYS file contents. Driver file not found Description: GEM VDI cannot find the first driver specified in the ASSIGN.SYS file. Solution: Make sure that the driver is in the specified drive, in the correct directory, and in the correct subdirectory- Corrupted driver file Description: GEM VDI finds the device driver, but is unable to use it. Solution: Use your distribution disk to make another copy of the device driver. Try to use the new copy. Contact your dealer if the device driver is unusable. End of Appendix A A-3 Appendix B ASSIGNSYS File REQUIRE.MENTS The ASSIGN.SYS file is parsed by the GDOS to create the assignment table. The assignment table resides in memory and is referenced when the application makes an Open Workstation call. The information required by the ASSIGN.SYS includes the device id number and the device driver filename and corresponding faces. Device Id Numbers Table B-1. Device Id Numbers Type -7 Number Monitor 1-10 Plotter 11-20 Printer 21-30 Metafile 31-40 Camera 41-50 Tablet 51-60 Device Driver The device driver filenames follow specific Filename naming conventions: • They must have eight or fewer characters. • The first character must be alphabetic. • The file extension must be SYS. FORMAT Figure B-1 shows the ASSIGN.SYS file format: Figure B-1. ASSIGN.SYS File Format B-1 Device Driver Face Id Filename Name 01 SCREEN.SYS FACE1.FNT SAKPLE ASSIGN.SYS 21 printer. fnt ;comments, if desired facel.fnt ;facel description face2.fnt ;face2 description face3.fnt face3 description 01 screen.fnt ;comments, if desired face4.fnt ;face4 description face5.fnt ;face5 description 11 plotter.fnt ;comments, if desired face6.fnt ;face6 description face7.fnt ;face7 description End of Appendix B B-2 Appendix C GEM VDI Metafile Format INTRODUCTION The metafile driver outputs the information specified below and performs the described operations for the indicated opcodes. STANDARD METAFILE Most function requests passed to the metafile ITHM FORMAT driver result in a standard format metafile item being written to the metafile buffer. In a standard format metafile item, the control, integer, and vertex parameters are written to the metafile in the following format: word value description 0 contrl[01 opcode 1 contrl[l] vertex count 2 contrl[31 integer parameter count 3 contrl[51 sub-opcode (or zero) 4 ptsin[O-nl vertices (if provided) n+4 intin[O-ml integer parameters (if provided) Note that nothing will be output for the ptsin or intin information if the vertex count or the integer parameter count is zero. The following function requests result in the output of a standard metafile item: 3 clear workstation 4 update workstation 5, 2 exit alpha mode escape 5, 3 enter alpha mode escape 5,21 advance form 5,21 output window 5,22 clear display list 5,23 output bit image file 6 polyline 7 polymarker 8 text 9 fill area 11, 1 bar 11, 2 arc 11, 3 pie 11, 4 circle 11, 5 ellipse 11, 6 elliptical arc 11, 7 elliptical pie 11, 8 rounded rectangle 11, 9 filled rounded rectangle 11,10 justified graphics text 12 set character height, absolute mode 13 set character baseline vector 14 set color representation 15 set polyline linetype 16 set polyline line width 17 set polyline color index 18 set polymarker type 19 set polymarker height 20 set polymarker color index 21 set text face 22 set text color index 23 set fill interior style 24 set fill style index 25 set fill color index 32 set writing mode 39 set graphic text alignment 104 set fill perimeter visibility 106 set graphic text special effects 107 set character height, points mode 108 set polyline end styles 112 set user-defined fill pattern 113 set user-defined line style pattern 114 fill rectangle 129 set clipping NONSTANDARD METAFILE ITEMS 1 open The metafile file buffer is initialized and workstation the metafile header is output to it. The workstation description values normally returned by an "open workstation" invocation are returned. C-2 ULJ11 OIJI LIUYLUU11IR-1 U UUIUU UL111 1JJX LIUL!ULIJLUXULHIUL Metafile header format: word description 0 Offffh 1 Length of header in words. 2 100*major version number + minor version number. 3 NDCIRC transformation mode flag 0 = positive y values ascend from origin (origin in lower left corner) 2 = positive y values descend from origin (origin in upper left corner) 4 7 Minimum and maximum x and y extent values for the information contained in the metafile. if ~ndefined by the application (see Escape 98: Update Metafile Extents"), all four values are zero. The values are stored in the following order: minimum x, minimum y, maximum x, maximum y. 8 9 Physical page size: page width in tenths of millimeters, followed by page height in tenths of millimeters. If undefined by the application, both values are zero. (See Appendix H, "Reserved Metafile Sub-opcodes.") 10 13 The coordinate window which defines the coordinate system used in the metafile. If undefined by the application, all four values are zero. The values are stored in the following order: lower left x, lower left y, upper right x, upper right y. (See Appendix H, "Reserved Metafile Sub-opcodes.") C-3 2 close An end-of-metafile opcode is appended to the workstation metafile file buffer. The metafile file buffer is flushed and the metafile is closed. End-of-metafile format: word description Offffh SPECIAL METAFILE ESCAPES 5, 98 update The extents information in the metafile metafile extents header is updated to indicate the extents passed in the ptsin array. 5, 99 write A standard format metafile item is written. metafile item The first word of the intin array should escape contain a sub-opcode that can be used by an application to identify the metafile item when it is read in. 5, 100 change GEM If any information currently exists in the vDi filename metafile or metafile buffer, the buffer is escape flushed and the file is closed. The metafile buffer is reinitialized and rudimentary file name validation is performed. If the drive, path, and filename are valid, they are used to update the file control block (FCB) of the metafile. The metafile will not actually be opened until the first buffer needs to be flushed. C-4 uuvi vLji Progiammet s uuiue uuvi vui meranie, rufmar INQUIRY FUNCTIONS 5, 1 inquire -1 is returned in both INTOUT parameters to addressable indicate that cursor addressing is not alpha character possible. cells escape 26 inquire color -1 is returned for the color index to representation indicate that no value is available. 35 inquire The set values are returned. current polyline attributes 36 inquire current polymarker attributes 37 inquire current fill area attributes 38 inquire current graphic text attributes 102 extended The appropriate inquiry values are returned. inquire function 117 inquire character cell width 131 inquire current face information End of Appendix C -11%. GEM VDI Programmer's Guide GEM VDI Metafile Format Appendix D Standard Keyboard GEM VDI defines a standard keyboard so applications can take advantage of special keys not defined in the standard, 7-bit ASCII character set. A 16-bit value is used to return these characters. The high byte contains a binary value assigned to each key. The low byte contains the 7-bit ASCII value, if such a value is defined, or a zero if the code is an extended code. Table D-1. GEK VDI Standard Keyboard Assignments High Low Byte Byte Character 03 00 CNTL 2 (Nul) 1E 01 CNTL A 30 02 CNTL B 2E 03 CNTL C 20 04 CNTL D 12 05 CNTL E 21 06 CNTL F 22 07 CNTL G 23 08 CNTL H 17 09 CNTL I 24 OA CNTL J 25 OB CNTL K 26 0C CNTL L 32 OD CNTL M 31 OE CNTL N 18 OF CNTL 0 19 10 CNTL P 10 11 CNTL Q 13 12 CNTL R 1F 13 CNTL S 14 14 CNTL T 16 15 CNTL U 2F 16 CNTL V 11 17 CNTL W 2D 18 CNTL X 15 19 CNTL Y 2C 1A CNTL Z 1A 1B CNTL 2B 1C CNTL 1B 1D CNTL 07 1E CNTL 6 OC 1F CNTL - 39 20 Space UIU-1 VLJI PIUYLcimmet 8 UUIUe btAMAM Table D-1. (continued) High Low Byte Byte I Character 02 21 1 28 22 04 23 # 05 24 $ 06 25 % 08 26 & 28 27 OA 28 OB 29 09 2A OD 2B 33 2C 0C 2D 34 2E 35 2F OB 30 0 02 31 1 03 32 2 04 33 3 05 34 4 06 35 5 07 36 6 08 37 7 09 38 8 OA 39 9 27 3A 27 3B 33 3C < OD 3D 34 3E > 35 3F ? 03 40 @ IE 41 A 30 42 B 2E 43 C 20 44 D 12 45 E 21 46 F 22 47 G 23 48 H 17 49 1 24 4A i 25 4B K 26 4C L 32 4D m 31 4E N 18 4F 0 D-2 GEM VDI Programmer's Guide Standard Keyboard Table D-1. (continued) High Low Byte ByteT Character 19 50 P 10 51 Q 13 52 R 1F 53 S 14 54 T 16 55 U 2F 56 v 11 57 w 2D 58 x 15 59 Y 2C 5A z 1A 5B 2B 5C 1B 5D 07 5E 0C 5F Underscore 29 60 1 1E 61 a 30 62 b 2E 63 c 20 64 d 12 65 e 21 66 f 22 67 9 23 68 h 17 69 i 24 6A i 25 6B k 26 6C 1 32 6D m 31 6E n 18 6F 0 19 70 p 10 71 q 13 72 r 1F 73 s 14 74 t 16 75 u 2F 76 v 11 77 w 2D 78 x 15 79 y 2C 7A z 1A 7B 2B 7C 1B 7D 29 7E OE 7F Rubout (DEL) uLm vLji Frogrammer-s uuid6 Standard Keyboard Table D-1. (continued) High Low Byte Byte I Character 81 00 Alt 0 78 00 Alt 1 79 00 Alt 2 7A 00 Alt 3 7B 00 Alt 4 7B 00 Alt 5 7D 00 Alt 6 7E 00 Alt 7 7F 00 Alt 8 80 00 Alt 9 IE 00 Alt A 30 00 Alt B 2E 00 Alt C 20 00 Alt D 12 00 Alt E 21 00 Alt F 22 00 Alt G 23 00 Alt H 17 00 Alt I 24 00 Alt J 25 00 Alt K 26 00 Alt L 32 00 Alt m 31 00 Alt N 18 00 Alt 0 19 00 Alt P 10 00 Alt Q 13 00 Alt R 1F 00 Alt S 14 00 Alt T 16 00 Alt U 2F 00 Alt V 11 00 Alt W 2D 00 Alt X 15 00 Alt Y 2C 00 Alt Z 3B 00 Fl 3C 00 F2 3D 00 F3 3E 00 F4 3F 00 Fs 40 00 F6 41 00 F7 42 00 F8 43 00 F9 44 00 FIO 54 00 Fll D-4 kjWl VL).L rLUYL*LIIIIteI 5 UUIUC --- .,-.z - Table D-1. (continued) High Byte Byt7e Character 55 00 F12 56 00 F13 57 00 F14 58 00 F15 59 00 F16 5A 00 F17 5B 00 Fla 5C 00 F19 5D 00 F20 5E 00 F21 5F 00 F22 60 00 F23 61 00 F24 62 00 F25 63 00 F26 64 00 F27 65 00 F28 66 00 F29 67 00 F30 68 00 F31 69 00 F32 6A 00 F33 6B 00 F34 6C 00 F35 6D 00 F36 6E 00 F37 6F 00 F38 70 00 F39 71 00 F40 73 00 Ctrl left-arrow 4D 00 right-arrow 4D 36 Shift right-arrow 74 00 Ctrl right-arrow 50 00 down-arrow 50 32 Shift down-arrow 48 00 up-arrow 48 38 Shift up-arrow 51 00 Page down 51 33 Shift Page down 76 00 Ctrl Page down 49 00 Page up 49 39 Shift Page up 84 00 Ctrl Page up 77 00 Ctrl Home vu.L rluyLdituttei s tjuiae Standard Keyboard Table D-1. (continued) High Low Byte Byte I Character 47 00 Home 47 37 Shift Home 52 00 Insert 52 30 Shift Insert 53 00 Delete 53 2E Shift Delete 72 00 Ctrl Print Screen 37 2A Print Screen 01 1B Escape OE 08 Backspace 82 00 Alt 83 00 Alt ic OD CR 1C OA Ctrl CR 4C 35 Shift Num Pad 5 4A 2B Num Pad - 4E 2B Num Pad + OF 09 Tab OF 00 Backtab 4B 00 left-arrow 4B 34 Shift left-arrow 4F 00 End 4F 31 Shift End 75 00 Ctrl End End of Appendix D D-6 Appendix E Processor-Specific Data 8086-SPECIFIC DATA Registers and The address of the Parameter Block is passed Interrupts in two 16-bit registers (Ds:Dx for the 8086) from the application program to GEM VDI. Pass 0473h in the Cx register. The interrupt is EF. Note: GEM VDI supports Concurrent'" operating systems that support DOS calls of versions 2.0 and above. Exchange Mouse For 8086-basea microcomputers, the Movement Vector application-dependent code is invoked via a CALL FAR (CALLF) instruction. On entry, the Bx register contains the new x position of the mouse. The Cx register contains the new y position of the mouse. When complete, the application-dependent code should do a RETURN FAR (RETF) instruction with the x,y position of the mouse the driver is to store in Bx, Cx. Exchange Button For 8086-based processors, the application Change Vector code is invoked via a CALL FAR (CALLF) instruction with Ax containing the mouse button keys. Keys are encoded by the same rules that apply to the Sample Mouse Button State function. When complete, the application dependent code should do a RETURN FAR (RETF) instruction with the mouse button state the driver is to store in Ax. E-1 Exchange Cursor For 8086-based machines, the application Change Vector dependent code is invoked with a CALL FAR (CALLF) instruction. Upon entry, the Bx register contains the x position and the Cx register the y position. If the application dependent code does not draw its own cursor, a CALL FAR should be performed to the address returned in contrl(9) and contrl(10) with the x,y position at which to draw the cursor in Bx, Cx. This causes GEM VDI to draw a cursor. When complete, the application should perform a RETURN FAR (RETF) instruction. Exchange Timer For 8086-based processors, the application Interrupt Vector dependent code is invoked with a CALL FAR (CALLF) instruction. When complete, the application should perform a RETURN FAR (RETF) instruction. E-2 -. - -'J~ . - . --, ----- ~r-- -_ 68000-SPECIFIC DATA Registers and The address of the Parameter Block is passed Interrupts in one 32-bit register, DO.1 for 68K from the application program to GEM VDI. Dl.w contains the function code 115. For CP/M-68K, GEM VDI is invoked via TRAP 2. For other 68K operating systems that support GEM VDI , the TRAP is identified in the operating system's manual. Exchange Mouse For 68000-based microcomputers, the Movement Vector application-dependent code is invoked via a JUMP TO SUBROUTINE (JSR) instruction. On entry, the DO.w register contains the new x position of the mouse. The Dl.w register contains the new y position of the mouse. When complete, the application-dependent code should do a RETURN FROM SUBROUTINE (RTS) instruction with the x,y position of the mouse the driver is to store in DO.w, Dl.w. Exchange Button For 68000-based processors, the application Change Vector code is invoked via a JUMP TO SUBROUTINE (JSR) instruction with DO.w containing the mouse button keys. Keys are encoded by the same rules that apply to the Sample Mouse Button State function. When complete, the application-dependent code should do a RETURN FROM SUBROUTINE (RTS) instruction with the mouse button state the driver should store in DO.w. UM1 qu'L LIUYLUmulel 3 k3ulue b8UUU-tpecitic Data Exchange Cursor For 68000-based machines, the application Change Vector dependent code is invoked with a JUMP TO SUBROUTINE (JSR) instruction. Upon entry, the DO.w register contains the x position and the Dl.w register the y position. If the appli cat ion-dependen t code does not draw its own cursor, a JUMP TO SUBROUTINE (JSR) instruction should be performed to the address returned in contrl(9) and contrl(10) with the x,y position at which to draw the cursor in DO.w and Dl.w. This causes GEM VDI to draw a cursor. When complete, the application should perform a RETURN FROM SUBROUTINE (RTS) instruction. Exchange Timer For 68000-based processors, the application Interrupt Vector dependent code is invoked with a JUMP TO SUBROUTINE (JSR) instruction. When complete, the application should perform a RETURN FROM SUBROUTINE (RTS) instruction. End of Appendix E E-4 Appendix F Character Sets The system fonts provided with GEM VDI are illustrated in Figure F-1 and F-2. Figure F-1 shows the USASCII character set. Figure F-2 shows the additional characters included to form the international character set. Note that external fonts (those which are dynamically loaded) do not include characters for decimal equivalents 0 through 31. lffl~, F-I t-IldlaL!Lt!l 3UCH Dk~ tIM M o 16 32 48 64 80 96 112 WXA 0 1 2 3 4 5 6 7 DK INIAI At ki 0 0 BIANK 0 @ p p ,SPA(FI 1 A Q a q 2 2 2 B R b r 3 3 # 3 C S C s 4 4 $ 4 D T d t I s 5 ozo 5 E U e u 6 6 & 6 F V f v 7 7 7 G W g w 8 8 8 H X h x 9 9 9 1 y y 10 A j Z z 11 B + K k 12 C < L I 13 D = m m 14 E > N A n 15 F ? 0 0 Figure F-1. GE24 VDI USASCII Character Set GEM VDI Programmer's Guide Character bets 128 144 1 160 176 192 208 224 40 240 g 9 A B C D F F 0 a, a 0( 0 Ij + 2 2 e /E 0' > 3 3 a 6 U' 7r < 4 4 6,* n- (x f .5 5 a 6 N (Y, 6 6 0 A a 7 7 T 8 8 e y 6 0 9 9 0 F- 10 A e U I I B '/2 12 C 1 'A 13 D 0 14 E P1 15 F 0 TM 7, Al ;A, i Figure F-2. GEM VDI International Character Set Extension F-3 ~ 4-1 - ~ L U9 L C1 XTIM~-- L b %.7 11 10 L- UharacterSets i 2s 144 160 176 192 208 224 24() IONA 9 9 A B C, L.'' wAi %All I T 2 2 e 3 3 4 4 a 6 5 a 6 6 0 a 7 7 8 8 9 9 10 A ci I B 0 12 C 13 D 14 E A 15 F A Figure F-3. GEM VDI International Character Set Extension for FNT Files End of Appendix F F-4 Appendix G Font Format INTRODUCTION The system fonts and external fonts used in GEM VDI are composed of four parts: the font data, a font header, a character offset table, and a horizontal offset table. FONT DATA The font data is organized as a single raster area. The area's height equals the font height and its width equals the sum of the character widths. The top scan line of the first character in the font is aligned to a byte boundary. The top scan line of the second character is abutted to the first character and is not necessarily byte-aligned. That is, the end of any character and the beginning of the following character often occur within the same byte; no byte alignment occurs within the font form. Bit padding occurs only at the end of a scan line. Each scan line in the font form begins on a word boundary. The number of bytes from the beginning of one scan line to the beginning of the next is called the form width. The number of scan lines required to draw any character is called the form height. A flag within the font header indicates the orientation of bytes within a word in the font data. If the flag is cleared, the font data is in a format such that the low byte of a word occurs in memory before the high byte (Inte16 format). If the flag is set, the high byte precedes the low byte in memory. FONT HEADER The font header contains information that describes global aspects of the font. For example, the name of the face, the font size, the minimum and maximum characters in the font, and any other data that applies to every character of the font are global aspects of that font. The format of the font header is shown in Table G-1. G-1 -LLJtJ1UUL1LR~1 J UUIUe FOrit Meader Table G-1. Font Header Format Byte Number Description 0 - 1 face identifier (see the Set Text Face function) 2 - 3 font size in points 4 - 35 face name (see the inquire Face Name and Index function) 36 - 37 lowest ADE value in the face 38 - 39 highest ADE value in the face 40 - 41 *top line distance 42 - 43 *ascent line distance 44 - 45 *half line distance 46 - 47 *descent line distance 48 - 49 *bottom line distance 50 - 51 width of the widest character in the font 52 - 53 width of the widest character cell in the face 54 - 55 left offset (see the Inquire Current Face Information function) 56 - 57 right offset (see the Inquire Current Face Information function) 58 - 59 thickening: the number of pixels by which to widen thickened characters 60 - 61 underline size: the width (in pixels) of the underline G-2 %aWvI VUI r L U9 L CIRIUM! L b "UlUfZ Table G-1. (continued) Byte Number Description 62 - 63 lightening mask: the mask] used to drop pixels out when lightening; usually 5555H 64 - 65 skewing mask: the mask that is rotated to determine when to perform additional rotation on the character to perform skewing; usually 5555H 66 67 flags: bit 0 s e t if d e f a u 1 t system font bit 1 set if horizontal o f f s e t t a b I e s should be used bit 2 byte-swap flag (see "Font Data") bit 3 set if mono-spaced font 68 - 71 pointer to the horizontal offset table 72 - 75 pointer to the character offset table 76 - 79 pointer to the font data 80 - 81 form width (see "Font Data") 82 - 83 form height (see "Font Data") 84 - 87 pointer to the next font (set by the driver) - Distances are measured relative to the character baseline and are always a positive value (magnitude rather than offset). G-3 ur-m viii erogrammer s uuiae Character Uttset Table CHARACTER OFFSET The character offset table is used to index TABLE into the font data and to determine the width of specific characters in the font. It is indexed by relative character value (the ADE value of the desired character, minus the lowest ADE value in the font) and yields the offset from the base of the font data to the beginning of the character definition. The difference between the offset to a character and the offset to the following character gives the width of the character. Note that the character offset table includes one more entry than the number of characters in the font so that a width may be obtained for the final character in the font. Note: The character offset table is required even for mono-spaced fonts. HORIZONTAL OFFSET The horizontal offset table is indexed by TABLE relative character value and yields any additional positive or negative spacing necessary before outputting the character. The horizontal offset table often does not exist. Whether it exists or not is indicated by the horizontal offset table bit in the flags word of the font header. End of Appendix G G-4 Appendix H Reserved Metafile Sub-opcodes HETAFILE SUB- The following sub-opcodes are reserved for OPCODES FOR USE use by the GEM Output application. GEM VDI WITH GEM OUTPUT defines sub-opcodes for the following sub functions: * Physical Page Size e Coordinate Window The opcodes are used by the GEM Output application to define how large a picture is to be rendered on the output page and also to define a transformation which maps from the metafile coordinate system to the output device. The two GEM Output metafile sub-opcodes result in an update of the metafile header. The opcodes are not actually written to the body of the metafile. PHYSICAL PAGE SIZE This sub-function defines the size of the area to be output to. All of the data in the coordinate window is mapped to this area. if no physical page size is defined, the Output application will attempt a best fit on the target device, assuming that "pixels" in the metafile are square. Input contrl(O) Opcode = 5. contrl(l) Number of input vertices = 0. contrl(3) Length of intin array = 3. contrl(5) Function id = 99. contrl(6) Device handle. intin(O) Sub-opcode number = 0. intin(l) Page width in tenths of millimeter. intin(2) Page height in tenths of millimeter. Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 0. H-1 GEM VDI Programmer's Guide Coordinate window COORDINATE WINDOW This sub-function defines the coordinate system used in the metafile. All of the data in the defined coordinate window is mapped to the area defined by the physical page size sub-function. The coordinate window defaults to NDC space (0 to 32K). The location of the origin, (0, 0), depends on the coordinate space set when the metafile was opened (see "Open Workstation"). For example, if the Open Workstation function was invoked specifying raster coordinate space, the origin would be located in the upper left corner of the display surface. Note that the window corner information must be specified as the lower left and upper right corners. Arbitrary opposing corners will not convey enough information. Input contrl(O) Opcode = S. contrl(l) Number of input vertices = 0. contrl(3) Length of intin array = 5. contrl(5) Function id = 99. contrl(6) Device handle. intin(O) Sub-opcode = 1. intin(l) x-coordinate of lower left corner of window. intin(2) y-coordinate of lower left corner of window. intin(3) x-coordinate of upper right corner of window. intin(4) y-coordinate of upper right corner of window. Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 0. H-2 GEM VDI Programmer's Guide Metafile Sub-opcodes with GEM Draw NETAFILE SUB- The following sub-opcodes are reserved for OPCODES FOR USE use by the GEM Draw" application. GEM VDI WITH GEM DRAW defines the sub-opcodes for the following sub functions: • Start Group • End Group • Set Attribute Shadow On * Set Attribute Shadow Off • Start Draw Area Type Primitive • End Draw Area Type Primitive • Set No Line Style START GROUP This sub-function indicated the beginning of a group of primitives for the GEM Draw application. All subsequent primitives which occur before the next End Group sub-opcode will be regarded as a group by the GEM Draw application. Input contrl(O) Opcode = 5. contrl(l) Number of input vertices = 0. contrl(3) Length of intin array = 1. contrl(5) Function id = 99. contrl(6) Device handle. intin(O) Sub-opcode number = 10. Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 0. H-3 GEM VDI Programmer's Guicie -1AA - --V END GROUP This sub-function indicated the end of a group of primitives for the GEM Draw application. Input contrl(O) Opcode = 5. contrl(l) Number of input vertices = 0. contrl(3) Length of intin array = 1. contrl(5) Function id = 99. contrl(6) Device handle. intin(O) Sub-opcode number = 11. Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 0. SET no LIM STYLE This sub-function is used by GEM Draw to indicate that subsequent area type primitives are not to be outlined. The effects of this sub-opcode are cancelled by any subsequent set line style opcode. Input contrl(O) Opcode = 5. contrl(l) Number of input vertices = 0. contrl(3) Length of intin array = 1. contrl(5) Function id = 99. contrl(6) Device handle. intin(O) -- Sub-opcode number = 49. Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 0. H-4 . ~tVL -LLLAUULt: 01MUUW ~11 SET ATTRIBUTE This sub-function is used by GEM Draw to SHADOW ON indicate that all subsequent primitives which occur before the next Set Attribute Shadow Off sub-opcode should be ignored because they are used to draw a drop shadow for the first primitive immediately following the Set Attribute Shadow Off sub-opcode. Internally, GEM Draw assigns a shadowed attribute to the first primitive following the Set Attribute Shadow Off sub-opcode and performs its own shadow drawing. All attribute information which occurs between Set Attribute Shadow On and Set Attribute Shadow Off will continue to be processed. Note that GEM Draw will not drop shadows from text or from polylines consisting of only two vertices. Input contrl(O) Opcode = 5. contrl(l) Number of input vertices = 0. contrl(3) Length of intin array = 1. contrl(5) Function id = 99. contrl(6) Device handle. intin(O) Sub-opcode number = 50. Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 0. I-*-- H-5 kirA'l VLJ.L rLUYLdH11L1fdL b UUIUe allL J%LLL1LJULU 011dUUW ULL SET ATTRIBUTE This sub-function indicates to GEM Draw the SHADOW OFF end of primitives used to draw a drop shadow of the first primitive following this sub-opcode. Input contrl(O) Opcode = 5. contrl(l) Number of input vertices = 0. contrl(3) Length of intin array = 1. contrl(S) Function id = 99. contrl(6) Device handle. intin(O) Sub-opcode number = 51. Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 0. START DRAW AREA This sub-function indicates to GEM Draw that TYPE PRIMITIVE an area type primitive block follows. GEM Draw will use the vertices of the first primitive (anything except text) which follows this sub opcode to define a GEM Draw area type primitive. All other primitives encountered before the next End Draw Area Type Primitive sub-opcode will be ignored. Input contrl(O) Opcode = 5. contrl(l) Number of input vertices = 0. contrl(3) Length of intin array = 1. contrl(S) Function id = 99. contrl(6) Device handle. intin(O) Sub-opcode number = 80. Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 0. H-6 END DRAW AREA This sub-function indicates to GEM Draw the TYPE PRIMITIVE end of an area type primitive block. Input contrl(O) Opcode = 5. contrl(l) Number of input vertices = 0. contrl(3) Length of intin array = 1. contrl(5) Function id = 99. contrl(6) Device handle. intin(O) Sub-opcode number = 81. Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 0. End of Appendix H H-7 Appendix I Bit Inage File Fornat INTRODUCTION A GEM VDI bit image file has the extension IMG and contains information used to recreate a picture from its bit (pixel) image. The file consists of a header and raw pixel information. The pixel information can be encoded in a variety of formats. HEADER FORMAT The bit image file header consists of a variable number of 16-bit words in which the high byte of the word precedes the low byte. Word Contents 0 image file version number 1 length of the header in words 2 source device bits per pixel (i.e., number of planes) 3 pattern definition length (bytes) 4 source device pixel width (microns) 5 source device pixel height (microns) 6 scan line width (pixels) 7 number of scan lines The third word of the header gives the number of bytes the file uses to describe pattern run (see Note 5 below). The value can range from 1 to 8. (For most bit image captures from screen devices, the typical value is 2.) DATA FORMAT The following describes the syntax of the bit image data: file ::= * EOF scan-line E], (see Note 1) vert_rep (see Note 2) planeJ ::= * (see Note 3) encoded-data ::= [ I I ] I-1 solid-run ::= (see Note 4) pattern_run (see Note 5) bit-string (see Note 6) Note 1 Each scan line consists ofan optional vertical replication count followed by encoded data for each bit plane. The bit planes are specified in order. The first plane corresponds to the lowest order bit of a pixel value (see Table 6 1); the last plane corresponds to the highest order bit. For example, in a three-plane system, the red plane is described first, followed by the green plane, then the blue plane. Data is always provided for all defined bit planes. Note 2 A vertical replication item consists of the following: byte contents 0 must be zero I must be zero 2 must be 255 (hex FF) 3 count The count specified in the last byte of the vertical replication item indicates how many identical scan lines are defined by the scan--line item. Note 3 Thenumber of pixels described for each bit plane of a scan line is not necessarily the scan-line width specified in the file header. Because the data is encoded in byte-wide packets (packets of eight pixels), the number of pixels actually described is always a multiple of eight and is never more than seven pixels wider than the scan-line width. 1-2 GULI 1LJ1 LIUYLUIUMLI J UUIUI! BIL 11RAgg P116 25PMAE Note 4 A solid - run item contains a single byte that describes a state (SET or NOT SET) and the number of bytes for which that state is true. The high-order bit defines the state (1 = SET, 0 = NOT SET), and the low-order seven bits define the run length. For example, in a three-plane system, a stream of 24 red pixels can be encoded as a solid run of ls three bytes long in the red plane (hex 83). In the same system, the green and blue planes would each have a solid run of Os three bytes long (hex 03). Note 5 A pattern run item describes a set of pattern bytes and the number of times the pattern bytes should be repeated. The number of bytes in a pattern is defined in the bit image file header; typically, it is two for a screen device image. The pattern-run item is defined as follows: byte contents 0 must be zero 1 run length 2 first byte of pattern n last byte of pattern For example, a three-plane system could have a stream of 48 pixels alternating red and blue. If the pattern width item in the image-file header is set to two, the red and blue bit planes can be encoded in the following manner: e red bit plane: a three-byte pattern run with the pattern bytes set to hex AAAA * blue bit plane: a three-byte pattern run with the pattern bytes set to hex 5555 The green bit plane in this example is a six byte solid run of Os (hex 06). 1-3 GEM VDI Programmer's uuiae Olt- Lmage r.L.Le ruimaL Note 6 If a stream of pixels for a given plane cannot be encoded efficiently as a solid run or pattern run, it must be encoded as a bit string. The bit-string item is defined as follows: byte contents 0 must be hex 80 1 byte count 2 first byte of bit string n last byte of bit string End of Appendix I 1-4 Glossary ASSIGN.SYS Text file created by the driver installation program. Associates device identification ( id) numbers with specific device driver files so that devices can be referred to by type within the application program. The ASSIGN.SYS file can be modified using any text editor. coordinate scaling Converting points from one space or coordinate system to another. In GEM VDI, this term refers to the change between Normalized Device Coordinates (NDC) and Raster Coordinates (RC). coordinate systems Cartesian space in which points are defined. GEM VDI supports two systems: Normalized Device Coordinates (NDC) and Raster Coordinates (RC). default device First driver named in the ASSIGN.SYS driver file. It must be the largest driver that will be loaded during a graphics session. device driver Device-dependent portion of GEM VDI that translates standard device-independent graphics operations to device-specific command sequences for a particular device. device handle Unique value used to identify which workstation the GEM VDI function should use. GEM VDI assigns these numbers at Open Workstation. device Id number assigned to a device in the identification ASSIGN.SYS file. Each device in the number ASSIGN.SYS file has a unique device number assigned to it. Glossary-1 GEM VDI Programmer's Guide Glossary face Letter style, such as Times Roman. GEM VDI stores the definition of each style in a data file. When an application calls for the use of a particular text face, GEM VDI uses the definition to form the text characters on the specified graphics device. font Collection of characters all in one typeface, a subset of face. function code See operation code. graphics command Command that loads the GDOS into memory. graphics device Hardware that accepts graphics input (mouse or keyboard, for example) or displays graphics output (screen, printer, or plotter, for example). Graphics Device Device-independent portion of GEM VDI that Operating System services graphics requests and calls the (GDOS) device driver to send commands to graphics devices. Generalized Display function used to address special Drawing device capabilities such as curve drawing. Primitive (GDP) GEM NIDI supports the following GDPs: bar, arc, pie, circle, ellipse, elliptical arc, elliptical pie, rounded rectangle, filled rounded rectangle, and justified graphics text. Not all devices support all GDPs. Graphics Graphics extension to microcomputer opera- Environment Manager ting systems. The GEM VDI makes it possible Virtual Device to run graphics applications on a micro- Interface (GEM VDI) computer. Graphical Kernel International standard for the programming System (GKS) interface to graphics from an application program. graphics Basic graphics operations performed by GEM primitives VDI, for example, drawing lines, markers, and text strings. Glossary-2 ____ --- - -_1 uiossary hot spot Area of the cursor that covers the pixel whose x,y location is returned during locator input. For example, the hot spot on a cross hair cursor is the intersection point of the two lines making up the cross. metafile Data file containing a picture description. The GEM VDI metafile can be sent to any device or used to exchange a picture between two applications. Memory Form Block of memory that defines a raster area. Definition Block An MFDB includes the following raster area (MFDB) information: pointer to the memory address of the upper left corner of the first plane height and width, in pixels width, in words number of planes flag to indicate if format is standard or device-dependent locations reserved for future use Normalized Device Uniform virtual space by which a graphics Coordinate (NDC) application program can pass graphics space information to a device. The GDOS maps NDCs to RCs. NDC space has its origin in the lower left corner. normalized Any point in NDC space. device coordinates (NDC) operation codes Passed to GDOS as part of a parameter list. (opcodes) The opcode indicates which graphics operation is requested. pixel (pixel Smallest element of a display surface that element) can be independently referenced. Glossary-3 uLm vui erogrammer s uuiue raster area Rectangular blocks of either bits in memory or pixels on a physical device. Rasters are the steps between pixels. Raster Actual device units. Raster coordinate space Coordinate (RC) has its origin in the upper left corner. Its space limits are determined by the resolution of the specific device. Raster Coordinate Point in RC space. (RC) raster functions Functions that -operate on pixels either individually or in groups. transformation Determines which coordinate systemthe mode application is using, NDC or RC. If NDC, the transformation mode determines how the GDOS maps the NDCs to the RCs with two methods: full NDC to RC space or uniform NDC to RC space. Virtual Device Standard interface between device-dependent interface (VDI) and device-independent code in a graphics environment. The GEM VDI makes all device drivers appear identical to the calling program. virtual screen Block of memory that can be addressed as if it were a memory-mapped display. End of Glossary Glossary-4 Index A inquire addressable alpha character cells, 9-1, 9-4 architecture, 1-2 inquire current alpha cursor address, 9-2, 9-18 B inquire palette driver state, 9-2, 9-33 bit image file format, 1-1 inquire palette film BYTE, 2-1 types, 9-2, 9-32 inquire tablet status, C 9-2, 9-19 output bit image file, 9-27 Cell Array function, 4-11 output cursor addressable character offset, G-4 alpha text, 9-1, 9-15 Close Virtual Screen output window, 9-2, 9-24 Workstation function, 3-13 palette error inquire, Close Workstation function, 3-9 9-2, 9-39 control array, 1-5 place graphic cursor at coordinate window, H-1, H-2 location, 9-2, 9-21 Copy Raster remove last graphic opaque function, 6-7 cursor, 9-2, 9-22 Transparent functionr 6-9 reverse video off, 9-2, 9-17 D reverse video on, 9-1, 9-16 data format with bit image save palette driver state, files, 1-1 9-2, 9-37 device drivers, 1-2 select palette, 9-2, device handle, 1-4 9-30 device id number, 1-4 set palette driver state, 9-2, 9-35 E suppress palette messages, 9-2, 9-38 error messages, A-1 update metafile extents, 9-41 escape write metafile item, alpha cursor down, 9-1, 9-8 9-2, 9-43 alpha cursor home, 9-11 Exchange Button Change alpha cursor left, 9-1, 9-10 Vector function, 7-27 alpha cursor right, 9-1, 9-9 Exchange Cursor Change alpha cursor up, 9-1, 9-7 Vector function, 7-31 clear display list, 9-2, 9-26 Exchange Mouse Movement direct alpha cursor address, Vector function, 7-29 9-1, 9-14 extended run-length encoding, enter alpha mode, 9-1, 9-6 1-2 erase to end of alpha screen, external fonts, G-1 9-1, 9-12 erase to end of alpha text F line, 9-1, 9-13 exit alpha mode, 9-1, 9-5 Filled Area function, 4-8 form advance, 9-2, 9-23 Filled Rounded Rectangle change GEM VDI filename, 9-44 function, 4-25 hard copy, 9-2, 9-20 font data, G-1 home alpha cursor, 9-1, 9-11 font form, G-1 Index-1 font format, G-1 Set Polyline End Styles, 5-12 font header, G-1 Set Text Face, 5-24 Form Advance Set User-defined Fill function, 9-23 Pattern, 5-37 function code Text, 4-6 escape, 9-1 Unload Fonts, 3-17 function Update Workstation, 3-15 Bar, 4-8 Cell Array, 4-11 G Circle, 4-28 Close Virtual Screen GDOS, 1-2 Workstation, 3-13 GDP Close Workstation, 3-9 Arc & Pie function, 4-19 Copy Raster, Opaque, 6-7 Bar function, 4-18 Copy Raster, Transparent, 6-9 Circle function, 4-21 Exchange Button Change Ellipse, 4-24 Vector, 7-27 Elliptical Arc and Pie, 4-22 Exchange Cursor Change Vector GEMVDI command, 2-19 function, 7-31 Get Pixel function, 6-13 Exchange Mouse Movement Graphics Device Operating Vector, 7-30 System, See GDOS Filled Area, 4-8 Filled Rounded Rectangle, H 4-25 Get Pixel, 6-13 hard copy escape, 9-20 Input Locator, Request Mode, header format with bit image 7-3 files, 1-1 Input Locator, Sample Mode, hide cursor escape, 7-25 7-6 horizontal offset table, G-4 Input String, Request Mode, 7-15 Input String, Sample Mode, 7-17 Input Locator Input Valuator, 7-9 Request Mode function, 7-3 Inquire Current Face Sample Mode function, 7-6 Information, 8-21 input parameters array, 1-5 Inquire Face Name and Index, input point coordinates, 1-5 8-19 Input String Justified Graphics Text, 4-27 Request Mode function, 7-15 Load Fonts, 3-16 Sample Mode function, 7-17 Open Virtual Screen Input Valuator function, 7-9 Workstation, 3-10 inquire cell array, 8-23 Open Workstation, 3-1 inquire character cell width, Polyline, 4-1 8-17 Polymarker, 4-4 inquire color representation, Rounded Rectangle, 4-25 8-5 Sample Keyboard State Inquire Current Face Information, 7-33 Information function, B-21 Sample Mouse Button State, Inquire Face Name and Index 7-26 function, 8-19 Set Graphic Text Special Inquire Palette Driver State Effects, 5-27 Escape, 9-33 Set Input Mode, 7-1 Inquire Palette Film Types Set Mouse Form, 7-19 Escape, 9-32 Index-2 inquire text extent, 8-15 Rounded Rectangle function, interrupt for 68K, E-3 4-25 interrupt for 8086, E-1 run-length encoding, 1-1, 1-2 J S justified graphics text, 4-27 Sample Keyboard State Information function, 7-33 L Sample Mouse Button State function, 7-26 Load Fonts function, 3-16 Save Palette Driver State Escape, 9-37 scan line, G-1 Select Palette memory requirements, 2-20 Escape, 9-30 metafile sub-opcodes, H-1, H-3 set character baseline vector, multiple workstations, 1-4 5-22 set character cell height N points mode, 5-18, 5-20 set character height NDC, 1-4, 1-6 absolute mode, 5-18 normalized device coordinates, Set Clipping Rectangle 1-4, 1-6 function, 3-19 set color representation, 5-4 0 set fill color index, 5-35 set fill interior style, 5-32 Open Virtual Screen Workstation set fill perimeter visibility, function, 3-10 5-36 Open Workstation function, 3-1 set fill style index, 5-33 output parameters, 1-5 set graphic text alignment, output point parameters, 1-5 5-30 Output Window set graphic text color index, Escape, 9-24 5-26 set graphic text special P effects, 5-27 Set Input Mode function, 7-1 Palette Error Inquire Set Mouse Form function, 7-19 Escape, 9-39 Set Palette Driver State physical page size, H-1 Escape, 9-32 plotter functions, 2-13 set polyline color index, 5-11 Polaroid Palette Escapes, 9-31 Set Polyline End Styles Polyline function, 4-1 function, 5-12 Polymarker function, 4-4 set polyline line type, 5-6 set polyline line width, 5-9 R set polymarker color index, 5-17 registers for 68K, E-3 set polymarker height, 5-16 registers for 8086, E-1 set polymarker type, 5-14 required functions for set text color index, 5-24 printers, 2-11 Set Text Face function, 5-24 required functions for screens, Set User-defined Fill Pattern 2-9 function, 5-33 reserved metafile sub-opcodes, set user-defined line style, H-1 5-8 Index-3 set writing mode, 5-1 show cursor, 7-23 stack requirements, 2-20 sub-opcodes, H-1 Suppress Palette Messages Escape, 9-38 system fonts, G-1 T Text function, 4-6 transforming points, 1-6 U Unload fonts function, 3-17 Update Workstation function, 3-15 V VDI, 1-5 Virtual Device Interface, 1-5 VDI, 1-5 WORD, 2-1 Write Metafile Item Escape,. 9-43 Index-4 GEM VDI Function Reference Card Op Code Function Name-Section Procedure Name 1 Open Workstation- I v - opnwk(work - in, &handle, work-out); 2 Close Workstation-1 v-clswk(handle); 3 Clear Workstation- I v_clrwk(handle); 4 Update Workstation-1 v_updwk(handle); 5 Escapes 5-1 Inquire Addressable Character Cells-9 vq chcells(handle, &rows, &columns); 5-2 Exit Alpha Mode-9 v-exit - cur(handfe); 5-3 Enter Alpha Mode-9 v-enter - cur(handle); 5-4 Cursor Up-9 v_curup(handle); 5-5 Cursor Down-9 v_curdown(handle); 5-6 Cursor Right-9 v-curright(handle); 5-7 Cursor Left-9 v_curleft(handle) ' 5-8 Home Cursor-9 v_curhome(handle); 5-9 Erase to End of Screen-9 v_eeos(handle); 5-10 Erase to End of Line-9 v_eeol(handle); 5-11 Direct Cursor Address-9 vs_curaddress(handle, row, column); 5-12 Output Cursor Addressable Text-9 v curtext(handle, &string), 5-13 Reverse Video On-9 v rvon(handle); 5-14 Reverse Video Off-9 v_rvoff(handle); 5-15 Inquire Current Alpha Cursor Address-9 vq_curaddress(handle, &row, &column); 5-16 Inquire Tablet Status-9 status=vq tabstatus(handle), 5-17 Hard Copy-9 v-hardcopy(handle); 5-18 Place Graphic Cursor at Location-9 v_dspcur(handle, x, y); 5-19 Remove Last Graphic Cursor-9 v_rmcur(handle); 5-20 Form Advance-9 v form_adv(handle); 5-21 Output Window-9 v output window(handle, xvarray); 5-22 Clear Display List-9 v clear disp list(handle); 5-23 Output Bit Image File-9 v-bit-image(handle,filename,aspect, scaling,num pts,xyarray)~ 5-60 Select Palette-9 selected=vs palette(handle, palette); 5-91 Inquire Palette Film Types-9 vqp films(handle, film names); 5-92 Inquire Palette Driver State-9 vqp-state(handle, &port, Wilm-name, Mightness, Mriterlace, &planes, Wndexes), 5-93 Set Palette Driver State-9 vsp_state(handle, port, film - num, lightness, interlace, planes, indexes), 5-94 Save Palette Driver State-9 vsp_save(handle), 5-95 Suppress Palette Messages-9 vsp message(handle); 5-96 Palette Error Inquire-9 status=vqp-error(handle); 5-98 Update Metafile Extents-9 v_meta_extents(handle,min-x,min-y, max-x,max-y); 5-99 Write Metafile Item-9 v-write-meta(handle, num-intin, intin, num_ptsin, ptsin); p Code Function Name-Section Procedure Name 5-100 Change GEM VDI File Name-9 vm filename(handle, filename); 6 Polyline-4 v - pline(handle, count, pxyarray); 7 Polymarker-4 v-pmarker(handle, count, pxyarray); 8 Text-4 v gtext(handle, x, y, string); 9 Filled Area-4 v fillarea(handle, count, pxyarray); 10 Cell Array-4 v-cellarray(handle, pxyarray, row-length, el-used, num_rows, wrt-mode, colarray); 11 GDPs 11-1 Bar-4 v_bar(handle, pxyarray); 11-2 Arc-4 v-arc(handle, x, y, radius, begang, endang): 11-3 Pie-4 v_pieslice(handle, x, y, radius, begang,endang); 11-4 Circle-4 v_circle(handle, x, y, radius); 11-5 Ellipse-4 v_ellipse(handle, x, y, xradius, yradius); 11-6 Elliptical Arc-4 v_ellarc(handle, x, y, xradius, Vradius, begang, endang); 11-7 Elliptical Pie-4 v-ellpie(handle, x, y, xradius, yradius, begang, endang); 11-8 Rounded Rectangle-8 v rbox(handle, xyarray); 11-9 Filled Rounded Rectangle-8 v-rfbox(handle, xyarray); 11-10 Justified Graphics Text-8 vjustified(handle, x, y, string, length, word_space, char-space); 12 Set Character Height, Absolute Mode-5 vst-height(handle, height, &char - width, &char-height, &cell - width, &cell_height); 13 Set Character Baseline Vector-5 set-baseline=vst-rotation(handle, angle); 14 Set Color Representation- 5 vs_color(handle, index, rgb - in); 15 Set Polyline Linetype-5 set-type-vsl-type(handle, style); 16 Set Polyline Line Width-5 s et-width-vs I_width (handle, width); 17 Set Polyline Color Index-5 set-color-vsl_color(ha n die, color index); 18 Set Polymarker Type-5 set-type=vsm - type(handle, symbol); 19 Set Polymarker Height-5 set_height-vsm_height(handle, height); 20 Set Polymarker Color Index-5 set-color-vsm_color(han die, color-index); 21 Set Text Face-5 set - font=vst - font(handle, font), 22 Set Graphic Text Color Index-5 set-color=vst_color(handle, color - index); 23 Set Fill Interior Style-5 set-interior=vsf-interior(handle, style); Op Code Function Name-Section Procedure Name 24 Set Fill Style Index-5 set_style=vsf_style(handle, style - index); 25 Set Fill Color Index-5 set-color=vsf - color(handle, color-index), 26 Inquire Color Representation -8 vq-color(handle, color-index, set - flag, rgb); 27 Inquire Cell Array-8 vq_cellarray(handle, pxyarray, row_length, num_rows, &el - used, &rows - used, &status, colarray); 28 Input Locator, Request Mode-7 vrq-locator(handle, x, y, &xout, &yout, Merm); 28 Input Locator, Sample Mode-7 status=vsm_locator(handle, x, y, Uout, &yout, Merm); 29 Input Valuator, Request Mode-7 vrq-valuator(handle, valuator-in, &valuator-out, Merminator); 29 Input Valuator, Sample Mode-7 vsm-valuator(handle, val-in, &val - out, Merm, &status); 30 Input Choice, Request Mode-7 vrq - choice(handle, ch-in, &ch-out); 30 Input Choice, Sample Mode-7 status=vsm - choice(handle, &choice); 31 Input String, Request Mode-7 vrq-string(handle, max-length, echo-mode, echo-xy, &string); 31 Input String, Sample Mode-7 status=vsm - string(handle, max length, echo - mode, echo-xy, &string); 32 Set Writing Mode-5 set-mode=vswr-mode(handle, mode); 33 Set Input Mode-7 vsin - mode(handle, dev-type, mode); 35 Inquire Current Polyline Attributes-8 vql-attributes(handle, attrib); 36 Inquire Current Polylmarker Attributes-8 vqm-attributes(handle, attrib); 37 Inquire Current Fill Area Attributes-8 vqf-attributes(handle, attrib); 38 Inquire Current Graphic Text Attributes-8 vqt_attributes(handle, attrib); 39 Set Graphic Text Alignment-5 vst-alignment(handle, hor-in, vert - in, &hor - out, &vert out); 100 Open Virtual Screen Workstation-1 v-opnvwk(work-in, Mandle, work-out), 101 Close Virtual Screen Workstation-1 v clsvwk(handle); 102 Extended Inquire-8 vq-extnd(handle, owflag, work-out), 103 Contour Fill-4 v_contourfill(handle, x, y, index); 104 Set Fill Perimeter Visibility-5 set-perimeter-vsf_perimeter(handle, per vis); 105 Get Pixel-6 v_get-pixel(handle, x, V, pel, index); 106 Set Graphic Text Special Effects-5 set effect-vst-effects(handle, effect); Op Code Function Name-Section Procedure Name 107 Set Character Cell Height, Points Mode-5 set point-vst_point(handle, point, &char width, &char height, &cell-Width, &cell-height); 108 Set Polyline End Styles-5 vsl_ends(handle, beg_style, end style); 109 Copy Raster, Opaque-6 vro_cpyfm(handle, wr_mode, pxyarray, srcMFDB, pdesMFDB); 110 Transform Form-6 vr trn fm(handle, psrcMFDB, pdesMFDB); ill Set Mouse Form-6 vsc_form(handle, pcur - form); 112 Set User-defined Fill Pattern-6 vsf-udpat(handle, pfill-pat); 113 Set User-defined Line Style-6 vsl_udsty(handle, pattern); 114 Fill Rectangle-6 vr 7 recfl(handle, pxyarray); 115 Inquire Input Mode-8 vqin_mode(handle, dev type, Wnput mode); 116 Inquire Text Extent-8 vqt - extent(handle, string, extent); 117 Inquire Character Cell Width-8 status-vqt - width(handle, character, &cell-width, &left-delta, &right delta); 118 Exchange Timer Interrupt Vector-7 vex-timv(handle, tim-addr, otim - addr,&tim-conv); 119 Load Fonts-3 additional-vst-load-fonts(handle, select); 120 Unload Fonts-3 vst_unload_fonts(handle, select); 121 Copy Raster, Transparent-6 vrt-cpyfm(handle, wr-mode, pxyarray, psrcMFDB, pdesMFDB, color-index); 122 Show Cursor-6 v_show - c(handle, reset); 123 Hide Cursor-6 v-hide-c(handle); 124 Sample Mouse Button State-7 vq_mouse(handle, &pstatus, &x, &V); 125 Exchange Button Change Vector-7 vex_butv(handle, pusrcode, psavcode); 126 Exchange Mouse Movement Vector-7 vex - motv(handle, pusrcode, psavcode); 127 Exchange Cursor Change Vector-7 vex-curv(handle, pusrcode, psavcode); 128 Sample Keyboard State Information-7 vqkey~_s(handle, &pstatus); 129 Set Clipping Rectangle-3 vs_clip(handle, clip2lag, pxyarrav); 130 Inquire Face Name and Index-8 index-vqt - name(handle, element-num, name); 131 Inquire Current Face Information-8 vqt-font_info(handle, &minADE, &maxADE, distances, maxwidth, effects);