DIGITAL RESEARCH* GEM” Programmer’s Guide Volume 1: VDI DIGITAL RESEARCH GEM" Programmer’s Guide Volume 1: VDI COPYRIGHT Copyright © 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 obligation 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 filenames and in the files actually included on the distribution 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 was printed in the United States of America. ******************************** * First Edition: April 1985 * ******************************** GEM™ Programmer's Guide Volume 1: VDI Release Note 01 The first two pages of this release note contain additions and changes that you should make to your copy of the GEM Programmer 1 s Guide, Volume 1: VDI . In addition, please do the following: • Insert the descriptions of the two new escapes, Escape 24 and Escape 25, after page 9-29 in your manual. • Replace Appendix I, "Bit Image File Format," with the new text we provide. Page 2-11 Under "Required Functions for Printers," add the following to the list of Escape values: 24 Inquire printer scan heights 25 Output printer alpha text Pages 2-14 and 2-15 Under "Required Functions for Metafiles," add the following to the list of Escape values: 25 Output printer alpha text Delete the following from the list of opcodes: 117 Inquire character cell width 131 Inquire current face information Page 6-9 Under "Copy Raster, Transparent," change the first sentence to read as follows: This function copies a monochrome rectangular raster area from a source form (which cannot be the screen) to a color area. Page 6-12 Under "Transparent Form," add the following as the third paragraph: 5047-2029-101 GEM Programmer's Guide, Volume Is VDI Release Note 01 The source and destination forms may be completely coincident or completely separate, but they may not partially overlap. Page 8-3 In the section on the Extended Inquire Function, after intout(18) in "Output," add and change as follows: intout(19)— Clipping flag. 0 = Clipping off. 1 = Clipping on. intout(20-44)- Reserved, contains zeros. ptsout(0)— ptsout(l)— ptsout(2)— ptsout(3)— ptsout(4-11)- Upper left x of the clipping window. Upper left y of the clipping window. Lower right x of the clipping window. Lower right y of the clipping window. Reserved, contains zeros. Page 9-2 In Table 9-1, insert the following: 24 INQUIRE PRINTER SCAN HEIGHTS 25 OUTPUT PRINTER ALPHA TEXT Change the number value immediately following from "24-59" to "26- 59." Page C-l Under "Standard Metafile Item Format" in Appendix C, add the following in the list of function requests, immediately after "5,23": 5,25 output printer alpha text Page D-l The page header should read "Standard Keyboard". GEM VDI Function Reference Card (at end of manual) The section reference under Op Code 114 (Fill Rectangle) should be to Section 4 instead of Section 6. 2 GEM VDI Programmer's Guide Release Note 01 Copyright© 1985 Digital Research Inc. All rights reserved. Digital Research and its logo are registered trademarks of Digital Research Inc. GEM is a trademark of Digital Research Inc. We Make Computers Work is a service mark of Digital Research Inc. End of Release Note GEM VDI Programmer 1 s Guide Inquire Printer Scan Heights ESCAPE 24: This escape returns to the calling program INQUIRE PRINTER information that describes the printing SCAN HEIGHTS characteristics of the printer. The information includes the height in pixels of a printer head pass (in both graphics and alpha modes) and the number of head passes in a full page. For devices in which the height of a single head pass is not a discrete number of pixels, this escape returns a division factor that should be factored in. For example, if the device outputs 12.5 pixels in a single alpha pass and 4 pixels in a single graphics pass, this escape returns an alpha scan height of 25, a graphics scan height of 8, and a division factor of 2. Input contrl(O) — Opcode = 5. contrl(l) — Number of input vertices = 0. contrl(3) — Length of intin array = 0. contrl(5) — Function id = 24. contrl(6) — Device handle. Output contrl(2) — Number of output vertices = 0. contrl(4) — Length of intout array = 5. intout(0) — Graphics scan height in scaled pixels. intout(l) — Number of graphics head passes per page. intout(2) — Alpha scan height in scaled pixels. intout(3) — Number of alpha head passes per page. intout(4) — Scan height division factor. C BINDING Procedure name vq_scan( handle, &g_height, &g_slices, &a_height, &a_slices, Sefactor ); 9-29a GEM VDI Programmer's Guide Inquire Printer Scan Heights Data types Input arguments Output arguments WORD vq_scan()? WORD handle; WORD g_height, g_slices, a_height, factor; handle = contrl[6] g_height = intout[0] g_slices = intout[l] a_height = intout[2] a_slices = intout[3] factor = intout[4] a slices. 9-29b GEM VDI Programmer's Guide Output Printer Alpha Text ESCAPE 25: OUTPUT This escape is required only for printers. PRINTER ALPHA TEXT It allows the application to request immediate output of a string of alpha text to the printer. The text is output at the current printer head position. All characters are output exactly as specified, with the following exceptions: • The form-feed character (ADE value 12) has the same effect as execution of the "Form Advance" escape (Escape 20). • The following two-character control sequences invoke the described functions on the printer, if they exist. ["(DC2)" refers to ADE value 18.] (DC2) 0 (DC2) 1 ( DC 2 ) 2 (DC2) 3 ( DC 2 ) 4 (DC2) 5 Begin bolding. End bolding. Begin italicizing. End italicizing. Begin underlining. End underlining. Input contrl(O) Opcode = 5. contrl(l) — Number of input vertices = 0 . contrl(3) contrl(5) contrl(6) — Length of intin array = — Function id = 25. — Device handle. n. intin Character string as codes, as described "Text" in Section 4. ASCII under Output contrl(2) — Number of output vertices = 0. contrl(4) — Length of intout array = 0. C BINDING Procedure name v_alpha_text( handle, string ); 9-29c GEM VDI Programmer's Guide Output Printer Alpha Text Data types Input arguments WORD v_alpha_text(); WORD handle; BYTE stringEn]; handle = contrl[6] string = intin Note: Bytes for the string array are mapped into the eight least significant bits of intin. The string must be null-terminated. 9-29d GEM VDI Programmer's Guide Bit Image File Format Appendix I Bit Image File Format 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 ::= <scan_line>* EOF scan_line :: = [<vert_rep>]<planel>, ... , <planeN> (see Note 1) vert_rep ::= (see Note 2) planeJ ::= <encoded_data>* (see Note 3) encoded_data ::= {<solid_run> I <pattern_run> I <bit_string>} 1-1 GEM VDI Programmer's Guide Bit Image File Format solid_run ::= (see Note 4) pattern_run ::= (see Note 5) bit_string ::= (see Note 6) Note 1 Each scan line consists of an 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 1 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 The number 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 GEM VDI Programmer's Guide Bit Image File Format 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 Is 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: • 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 Guide Bit Image File Format 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 Foreword OBJECTIVE This guide describes the features and operation of the Graphics Environment Manager™ (GEM™ ) Virtual Device Interface (VDI), the successor to the Digital Research® 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). i ii 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. Table of Contents 1 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 . 1-3 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 . 1-6 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 Text. 4-6 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. 5-1 Replace. 5-2 Transparent. 5-2 XOR. 5-2 Reverse Transparent . 5-3 Set Color Representation . 5-4 Set Polyline Line Type. 5-6 Set User-defined Line Style Pattern . 5-8 Set Polyline Line Width. 5-9 Set Polyline Color Index . 5-11 Set Polyline End Styles.5-12 Set Polymarker Type.5-14 vii 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 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.8-19 Inquire Current Face Information . 8-21 Inquire Cell Array.8-23 Inquire Input Mode. 8-25 9 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 GEM VDI Error Messages. A-l B ASSIGN.SYS File Requirements . B-l Device Id Numbers. B-l Device Driver Filename . B-l Format. B-l Sample ASSIGN.SYS . B-2 C GEM VDI Metafile Format Introduction . C-l Standard Metafile Item Format . C-l 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-l E Processor-Specific Data 8086-Specific Data .. E-l 68000-Specific Data. E-3 F Character Sets. F-l xii Table of Contents (continued) G Font Format Introduction . G-l Font Data. G-l Font Header. G-l Character Offset Table ... . G-4 Horizontal Offset Table . G-4 H Reserved Metafile Sub-opcodes Metafile Sub-opcodes for Use with GEM Output. H-l Physical Page Size. H-l 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 . 1-1 Header Format . 1-1 Data Format. 1-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 . 1 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 Mapping for 16-color Screens . 6-4 6- 3. Raster Operation Logic Operations . 6-6 7- 1. Sample Mode Status Returned . 7-7 8- 1. Face Names and Styles.8-19 9- 1. Escape Function Indentifiers . 9-1 B-l. Device id Numbers. B-l D-l. GEM VDI Standard Keyboard Assignments. D-l G-l. Font Header Format. G-2 xiv Table of Contents (continued) Figures 1- 1. Transformation Modes . 1-8 2- 1. Output from the Sample Program. 2-2 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-l F-l. GEM VDI USASCII Character. Set. F-2 F-2. GEM VDI International Character Set Extension .... F-3 Listings 2-1. Sample Program. 2-2 2-2. Sample Assembly Language Application . 2-3 xv Section 1 Overview INTRODUCTION The GEM VDI provides a device-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. • GEM VDI provides a device-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. ENHANCEMENTS 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 Graphics Device Operating System (GDOS) GEM VDI provides graphics primitives for 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. The Graphics Device Operating System (GDOS) contains the basic host and device¬ 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. 1-2 GEM VDI Programmer's Guide Architecture Graphics The graphics device drivers are similar to Device Drivers any I/O 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. Metafiles 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 graphics 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 Workstations The application program specifies the 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 With appropriate calls to the GDOS, you can PROGRAMS write application programs in assembly language or in 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 Appendix E for the main entry into the VDI for your operating system. The main entry point into the VDI is a single subroutine with five arguments, in the form of five arrays: • control array • array of input parameters • array of input point coordinates • array of output parameters • array of output point coordinates 1-5 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, contrl(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 GEM 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 coordinate size. These units are then mapped to Raster Coordinates by the GDOS. The transformation mode set at Open Workstation determines whether the GDOS maps from NDC units to the Raster Coordinates. 1-6 GEM VDI Programmer's Guide Transforming Points 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 corner, 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 Raster Coordinates (RC), the GDOS assumes a raster coordinate 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 programmer 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 (for example, rasters for screens or steps for plotters and printers). Unlike NDCs, RCs have their origin at the upper left corner, and the (xmax,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 effect. 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. 1-7 GEM VDI Programmer's Guide Transforming Points (32767,32767) Mode 0 Full NDC mapped to full RC space Mode 2 Application works in RC space (640,200) 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 disks, first duplicate them and then store FILES them in a safe place. Then, using the duplicate disks, transfer the GEM VDI files to working system disks. Always use the duplicate disks to generate any new copies of GEM VDI. Do not use the distribution disks for routine operations. WRITING THE You can write your graphics application in PROGRAM one of two ways: • using assembly language • using high-level language bindings (C language bindings are provided.) The first method addresses functions by their opcode numbers, the second by procedure name. The C Language bindings provided for each function 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 sample assembly language graphics program. 2-1 GEM Programmer's Guide Writing the Program Figure 2-1. Output from the Sample Program Listing 2-1. Sample Program /* The following globals must be declared to satisfy the */ /* external references from the C binding routine. */ int contrl[12]; int intin[128]; int ptsin[128]; int intout[128]; int ptsout[128]; main ( ) int handle, i, pxyarray[12], work_in[ll], work_out[57]; int x,y, term; /* Open the workstation. */ work_in[0] = 1; for (i = 1; i < 10; i++) work_in[i] = 1; work_in[10] =0; /* use NDC coordinates */ v_opnwk(work_in, Shandle, work_out); /* Output a polyline. */ pxyarray[0] = 12000; /* vertices... */ pxyarray[1] = 12000; pxyarray[2] = 12000; pxyarray[3] = 20000; pxyarray[4] = 14000; pxyarray[5] = 21000; pxyarray[6] = 16000; pxyarray[7] = 20000; pxyarray[8] = 16000; pxyarray [9] = 12000; pxyarray[10] = 12000; pxyarraytll] = 12000; v_pline(handle, 6, pxyarray); /* output polyline */ 2-2 GEM Programmer's Guide Writing the Program Listing 2-1. (continued) /* Pause for viewing. */ vrq_locator(handle, 16000, 16000, &x, &y, sterm)j /* 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 * 7 * .******************************************************************* false equ 0 true equ not false dly equ 05FH ; for delay process, 0FFFF is max delay possible W_0 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 W_15 equ word ptr 30 w_16 equ word ptr 32 W_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 * **************************************************************** CONTRL_SIZE equ 11 INTIN_SIZE equ 128 PTSIN_SIZE equ 256 INT0UTJ3IZE equ 128 PTS0UTJ5IZE equ 12 .***************************************************************** ; start the main body of the code * .***************************************************************** 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 cx,sp mov bx,ss cli mov ax,seg mystack mov ss,ax mov sp, offset mystack_top sti popf ; set up the pointers to the gemvdi arrays (contrl_ptr = offset:segment of CONTRL) ; this example does it when the code is loaded ? opnwk: ; load the CONTRL and INTIN arrays for an openworkstation call mov CONTRL + W_0,1 ; opcode for openworkstation mov CONTRL + W_1,0 ; 0 ptsin values mov CONTRL + W_3,11 j 11 intin values 2-4 GEM Programmer's Guide Writing the Program Listing 2-2. (continued) mov INTIN + W_0,1 mov INTIN + W_l,l mov INTIN + W_2,1 mov INTIN + W_3,l mov INTIN + W_4,1 mov INTIN + W_5,l mov INTIN + W_6,l mov INTIN + W_7,l mov INTIN + W_8,1 mov INTIN + W_9,1 mov INTIN + W_10,2 ; 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 into 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 ; opcode 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 ; nothing for INTIN mov PTSIN + W_0,0 ; point 1 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 ; point 2 is at (xresmx,0) 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 ; point 3 is at (xresmx,yresmx) mov PTSIN + W_5,bx mov PTSIN + W_6,0 ; point 4 is at (0,yresmx) mov PTSIN + W_7,bx device ia = i linetype line color marker type marker color font text color fill interior style fill style index fill color index transformation flag = RC system 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_ll,bx ; call gemvdi call gemvdi announce: ; load CONTRL and INTIN arrays to write "hello world" in the default ; system face and font, with default 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 location vertice mov CONTRL + W_3,length anncmnt ; length of the text string to be sent mov ax,open_device + W_0 ; put the max x resolution in ax shr ax,l ; divide the max x resolution by two mov bx,open_device + W_1 ; put the max y resolution in bx shr bx,l ; divide the max y resolution by two mov PTSIN + w_0,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 internallooplj 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 GEM Programmer’s Guide Writing the Program Listing 2-2. (continued) pop cx loop delayloop2 pop cx loop delayloop3 clswk: ; load CONTRL array to closeworkstation call mov CONTRL + W_0,2 ; opcode for close workstation mov ax,handle ; put the handle into CONTRL mov CONTRL + W_6,ax mov CONTRL + W_1,0 ; no input vertices mov CONTRL + W_3,0 ; no INTIN values ; call gemvdi call gemvdi ; done with the main program, return to the operating system mov ax,4c00h xor cx,cx xor dx,dx int 21h ; this is where control 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 to 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 GDOS ; end of the code segment of the sample program t ; begin the data segment for the sample program DATA dseg PUBLIC word DGROUP GROUP DATA t ; 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 GEM Programmer's Guide Writing the Program Listing 2-2. (continued) public PTSOUT public contrl_ptr public intin_ptr public ptsin_ptr public intout_ptr public ptsout_ptr public handle public open_device CONTRL rw CONTRL_SIZE INTIN rw INTIN_SIZE PTSIN rw PTSIN_SIZE INTOUT rw INTOUT_SIZE PTSOUT rw PTSOUT SIZE contrl_ptr dw offset CONTRL dw seg CONTRL intin_ptr dw offset INTIN dw seg INTIN ptsin_ptr dw offset PTSIN dw seg PTSIN intout_ptr dw offset INTOUT dw seg INTOUT ptsout_ptr dw offset PTSOUT dw seg PTSOUT these are fixed when the program is loaded to be double word pointers to the arrays this is the parameter block to which ds:dx points when GEM VDI is called handle dw 0 open_device rw INTOUT_SIZE + PTSOUTSIZE 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 the stack segment for the sample program 2-8 GEM Programmer's Guide Writing the Program Listing 2-2. (continued) ; end the sample program. Indicate this is main body and code starts at entry end entry GEM 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 GEM 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 100 Open virtual screen workstation 101 Close virtual screen workstation 102 Extended inquire function 2-10 GEM VDI Programmer's Guide Writing the Program 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 111 Set mouse form 112 Set user-defined fill pattern 113 Set user-defined linestyle 114 Fill rectangle 115 Inquire input mode 116 Inquire text extent 117 Inquire character cell width 118 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 subfunctions: 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 GEM VDI Programmer’s Guide Writing the Program 6 7 8 9 11 12 15 17 18 20 21 22 23 24 25 26 32 35 36 37 38 39 102 104 106 107 108 112 116 117 129 130 131 Polyline Polymarker Text Filled area 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 Set character height absolute mode Set polyline linetype Set polyline color index Set polymarker type Set polymarker color index Set text face Set text color index Set fill interior style Set fill style index Set fill color index Inquire color representation Set writing mode Inquire current polyline attributes Inquire current polymarker attributes Inquire current fill area attributes Inquire current graphic text attributes Set graphic text alignment Extended inquire function Set fill perimeter visibility Set graphic text special effects Set character height points mode Set polyline end styles Exchange fill pattern Inquire text extent Inquire character cell width Set clipping Inquire face name and index Inquire current face information 2-12 GEM VDI Programmer's Guide Writing the Program Required Functions Plotters require the following functions and for Plotters subfunctions: Opcode Definition 1 Open workstation 2 Close workstation 3 Clear workstation 4 Update workstation 5 Escape id Definition 1 Inquire addressable character cells 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 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 35 Inquire current polyline attributes 36 Inquire current polymarker attributes 37 Inquire current fill area attributes 38 Inquire current graphic text attributes 2-13 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 Metafiles device, the required functions are all those common 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 Opcodes You can determine if a function is available in a specific driver in one of the following ways: • 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 two values 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 all GEM VDI functions. Input Parameters contrl(O) — Opcode number for the GEM VDI function. contrl(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 contrl(3) — Length of integer array intin. contrl(5) — Subfunction identification number for a Generalized Drawing Primitive (GDP) or Escape. contrl(6) — Device handle. contrl(7-n) — Opcode-dependent information. intin — Array of integer input parameters. 2-16 GEM VDI Programmer's Guide Writing the Program ptsin — Array of input point 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 contrl(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. contrl(7-n) — Opcode-dependent information. intout — Array of integer output point parameters. ptsout — Array 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, contrl(l), is set correctly. Contrl(l) 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 integer count, are always set correctly by GEM VDI. These values contain zeros if no information is being passed back in ptsout and intout, respectively. The double-word addresses of the five parameter arrays are stored in a ten-word data structure referred to as a Parameter Block (PB) . 2-17 GEM VDI Programmer's Guide Calling Conventions Registers and Interrupts RUNNING GRAPHICS APPLICATIONS UNDER GEM VDI Refer to Appendix E for the specific 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) To use the graphics features provided by GEM VDI, you must ensure that the following conditions are met: 1. Your 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 GEM 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 ASSIGN.SYS file. 4. After successfully compiling or assembling and linking your application program, you can 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: GEMVDI /FILENAME To load GEM VDI and start a GEM application, type the following command: GEMVDI FILENAME To load GEM VDI and start the GEM Desktop™ application, type the following command: GEMVDI Each command loads GDOS and any drivers declared resident in the ASSIGN.SYS file. ASSIGN.SYS and the driver files must be located in one of the directories in the current search path. Any application to be invoked by a GEMVDI command must also be located in the search path. 2-19 GEM VDI Programmer's Guide Disabling Graphics 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 2-20 Section 3 Control Functions INTRODUCTION The control functions initialize the graphics workstation and set defaults for use with the application. OPEN WORKSTATION The Open Workstation function loads a graphics device driver for the application program and returns a device handle. The device is initialized with the parameters in the input array. Information about the device is returned; additional dev i ce-specif ic information is returned in the Extended Inquire function. If the device is a screen, it is initialized to graphics mode. GEM VDI clears the display surface. If the device cannot be opened, GEM VDI returns a zero as the device handle in contrl(6). Any nonzero value in contrl(6) indicates a successful operation. Input contrl(O) — contrl(l) — contrl(3) — intin intin(O) — intin(l) intin(2) intin(3) intin(4) — intin(5) — intin(6) intin(7) intin(8) — intin(9) Opcode = 1. Number of input vertices = 0. Length of intin array = 11. Initial defaults (for example, linestyle, color, character size). Device id number. This value determines which device driver to dynamically load in memory. Linetype. Polyline color index. Marker type. Polymarker color index. Text face. Text color index. Fill interior style. Fill style index. Fill color index. 3-1 GEM VDI Programmer's Guide Open 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 contrl(2) contrl(4) contrl(6) intout(0) intout(1) intout (2) Number of output vertices = 6. Length of intout array = 45. Device handle for this device. 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(0)=639). 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(1)=479). Device Coordinate units flag. 0= Device capable 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) intout(4) intout(5) — Width step, screen) — Height step, screen) Number of one pixel (plotter or aspect ratio for in microns. of one pixel (plotter or aspect ratio for in microns, of character heights. 0 = Continuous scaling. intout(6) intout(7) Number Number of linetypes. of line widths. 0 = Continuous scaling. intout(8) Number of marker types. 3-2 GEM VDI Programmer's Guide Open Workstation intout(9) — Number of marker sizes. 0 = Continuous scaling. intout(lO) — Number of faces supported by device (not the highest numbered face index). intout(ll) — Number of patterns. intout(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 arc 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 Guide Open Workstation intout(36) — intout(37) — intout(38) — intout(39) — intout(40) — intout(41) — intout(42) — intout(43) — Text rotation capability flag. 0 — No 1 — Yes Fill area capability flag. 0 — No 1 — Yes Cell array operation capability flag. 0 — No 1 — Yes 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 of colors available Number of locator devices available. 1 — Keyboard only 2 — Devices with keyboard and other input Number of valuator devices available. 1 — Keyboard 2 — If another valuator device is available Number of choice devices available. 1 — Function keys on keyboard 2 — If another button pad is available Number of string devices available. 1 — Keyboard 3-4 GEM VDI Programmer's Guide Open Workstation intout(44) — ptsout(O) ptsout(l) — ptsout(2) ptsout(3) ptsout(4) ptsout(5) — ptsout(6) — ptsout(7) ptsout(8) ptsout(9) ptsout(lO) — ptsout(ll) — Workstation type. 0 — Output only 1 — Input only 2 — Input/output 3 — Reserved 4 — Metafile output Minimum character width. Minimum character height in the y-axis in the 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. Maximum character width. Maximum character height in the y-axis in the current coordinate system. 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. 0 . Maximum line width in the x-axis in the current coordinate system. 0 . Minimum marker width in x-axis in the current coordinate system. Minimum marker height in x-axis in the current coordinate system. Maximum marker width in x-axis in the current coordinate system. 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 Color 0 White 1 Black Table 3-2. Monochrome Printer/Plotters Index Color 0 White 1 Black Table 3-3. Color Screens Index Color 0 White 1 Black 2 Red 3 Green 4 Blue 5 Cyan 6 Yellow 7 Magenta 8 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 Attribute Default Value Character height Nominal character height Character baseline rotation 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 3 -' GEM VDI Programmer's Guide Open Workstation C BINDING Procedure Name v_opnwk( work_in, Schandle, work_out ) Data Types WORD v_opnwk ( ); WORD work_in[ll]; WORD handle; WORD wo rk_ou t[5 7]; Input Arguments work__in[0] = intin[0] work_in[l] = intin[l] work_in[10] = intin[10] Output Arguments handle = contrl[6] work_out[0] = intoutCO] work_out[l] = intout[l] work_out[44] = intout[44] work_out[45] = ptsoutCO] work_out[56] = ptsout[ll] 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 printer, an update occurs if one has not just taken place. For a metafile, GEM VDI flushes the buffer and closes the metafile. Note: Close before closing your open virtual workstations the workstation. Input contrl(O) — contrl(l) — contr1(3) — contrl(6) — Opcode = 2. Number of input vertices = 0. Length of intin array = 0. Device handle. Output contrl(2) — contrl(4) — Length of output vertices = 0. Length of intout array = 0. C BINDING Procedure Name v_clswk( handle ) Data Types WORD v_clswk ( WORD handle; ) 7 Input Arguments handle = contrl[6] 3-9 GEM VDI Programmer's Guide Open Virtual Screen Workstation OPEN VIRTUAL SCREEN WORKSTATION Input This function allows a single physical screen to act 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. contrl(0) contrl(l) contrl(3) contrl(6) Opcode = 100. Number of input vertices = 0. Length of intin = 11. Device handle of a previously opened screen device. intin — For a description of the intin parameters required in the intin array see Open Workstation (Opcode 1). 3-10 GEM VDI Programmer's Guide Open Virtual Screen Workstation Output contr1(2) — contrl(4) — contrl(6) — Warning: Wote: Number of output vertices = 6. Length of intout = 45. The device handle for the Virtual Screen Device just opened. Contrl(6) is an input/output parameter. The value is changed to that of the Virtual Screen Workstation device handle. All output parameters are the same as those of Open Workstation (Opcode 1). 3-11 GEM VDI Programmer's Guide Open Virtual Screen Workstation C BINDING Procedure Name Data Types Input Arguments Output Arguments v_opnvwk{ work_in, &handle, work_out ) WORD v_opnvwk( ); WORD handle? WORD work_in[11]? WORD work out[57]? handle = contrl[6] work_in[0] = intin[0] work__in[10] = intin[10] work_out[0] = intoutCO] work__out[44] = intout[44] work_out[45] = ptsout[0] work_out[563 = ptsout[ll] 3-12 GEM VDI Programmer's Guide Close Virtual Screen Workstation CLOSE VIRTUAL SCREEN WORKSTATION The Close Virtual Screen Workstation function terminates the virtual device and prevents any further output to it. Input contrl(0) contrl(l) contrl(3) contrl(6) — Opcode Number Length Device = 101. of input vertices = 0. of intin = 0. handle. Output contrl(2) contrl(4) — Number Length of output vertices = 0. of intout = 0. C BINDING Procedure Name v_clsvwk( handle ) Data Types WORD v clsvwk( WORD handle; ); Input Arguments handle = contrl[6] 3-13 GEM VDI Programmer's Guide Clear Workstation CLEAR WORKSTATION The Clear Workstation function erases the screen. GEM VDI sets the screen to the currently selected background color, which is defined 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 contrl(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 handle; Input Arguments handle = contrl[6] 3-14 GEM VDI Programmer's Guide 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 must 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 contrl(0) contrl(l) contrl(3) contrl(6) Opcode = 4. Number of input vertices = 0. Length of intin = 0. Device handle. Output contrl(2) — Number in output vertices = 0. contrl(4) — Length of intout = 0. C BINDING Procedure Name v_updwk( handle ) Data Types WORD v_updwk ( ); WORD handle; Input Arguments handle = contrl[6] 3-15 GEM VDI Programmer's Guide Load Fonts LOAD FONTS This function loads the fonts associated with a particular driver in the ASSIGN.SYS file. It then makes them available to the appropriate program. 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 additional font identifiers. Note: You do not need to invoke this function if the default system fonts for a particular driver are sufficient. Input contrl(O) — Opcode = 119. contrl(l) — Number of input vertices = 0. contrl(3) — Length of intin array = 1. contrl(6) — Device handle. intin(O) — Reserved for future use = 0. Output contrl(2) — Number of output vertices = 0. contrl(4) — Length of output array = 1. intout(O) — Number of additional font identifiers. C BINDING Procedure Name Data Types Input Arguments Output Arguments additional = vst_load_fonts( handle, select ) WORD vst_load_fonts( ); WORD additional; WORD handle; WORD select; handle = contrl[6] select = intin[0] additional = intout[0] 3-16 GEM VDI Programmer's Guide 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 fonts request that the external fonts be unloaded The default system fonts for the workstation remain loaded and available. Input contrl(0) contrl(l) contrl(3) contrl(6) Opcode = 120. Number of input vertices = 0. Length of intin array = 1. Device handle. intin(0) Reserved for future use. Output contrl(2) contrl(4) Number of Length of output vertices = intout array = 0. 0 . 3-17 GEM VDI Programmer's Guide Unload Fonts C BINDING Procedure Name Data Types Input Arguments vst_unload fonts( handle. WORD vst_unload_fonts( ); WORD handle; WORD select; handle = contrl[6] select = intin[0] select ) 3-18 GEM VDI Programmer's Guide Set Clipping Rectangle SET CLIPPING RECTANGLE Input This function enables or disables clipping of 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. contrl(0) contrl(1) contrl(3) contrl(6) Opcode = 129. Number of input vertices = 2. Length of intin array = 1. Device handle. intin(0) ptsin(0) ptsin (1) ptsin(2) ptsin(3) Clipping flag. 0 = Turn clipping off. non-zero = Turn clipping on. x-coordinate of corner of the clipping rectangle in NDC/RC units. y-coordinate of corner of the clipping rectangle in NDC/RC units. x-coordinate of corner diagonally across from the corner selected in ptsin(0) of the clipping rectangle in NDC/RC units, y-coordinate of corner diagonally across from the corner selected in ptsin(l) of the clipping rectangle in NDC/RC units. 3-19 GEM VDI Programmer's Guide Set Clipping Rectangle C BINDING Procedure Name Data Types Input Arguments vs_clip( handle, clip_flag, pxyarray ) WORD vs_clip(); WORD handle? WORD clip_flag; WORD pxyarray[4]? handle = contrl[6] clip_flag = intin[0] pxyarray[0] = ptsin[0] pxyarray[l] = ptsin[l] pxyarray[2] = ptsin[2] pxyarray[3] = ptsin[3] End of Section 3 Section 4 Output Functions INTRODUCTION POLYLINE The output functions display graphics primitives (polyline or circle, for example) on devices. 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 • current writing mode For wide lines, the first point (ptsin(O), ptsin(l)) is drawn as shown in Figure 4-1. Figure 4-1. First Point for Wide Lines 4-1 laMa vui t-rogrammer ■ s Guide Polyline Input contrl(O) — contrl(l) — contrl(3) — contrl(6) — ptsin ptsin(O) ptsin(l) ptsin(2) ptsin(3) Opcode = 6. Number of vertices (x,y pairs) in polyline = n. (Maximum number is returned in Extended Inquire.) Length of intin array = 0. Device handle. Array of coordinates of polyline in NDC/RC units. x-coordinate of first point in NDC/RC units. y-coordinate of first point in NDC/RC units. x-coordinate of second point in NDC/RC units. y-coordinate of second point in NDC/RC units. x-coordinate of last point in NDC/RC units. y-coordinate of last point in NDC/RC units. ptsin(2n-2) — ptsin(2n-l) — Output contrl(2) contrl(4) Number of output Length of intout vertices = array = 0. 0 . 4-2 GEM VDI Programmer's Guide Polyline C BINDING Procedure Name Data Types Input Arguments v_pline( handle, count, pxyarray ) WORD v_pline ( ); WORD handle; WORD count; WORD pxyarray[2 * count]; handle = contrl[6] count = contrl[l] pxyarray[0] = ptsin[0] pxyarrayfl] = ptsin[l] pxyarray[2n-2] = ptsin[2n-2] pxyarray[2n-l] = ptsin[2n-l] 4-3 GEM 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) — contrl(l) — Opcode = 7 . Number of markers = n. (Maximum number is returned in Extended Inquire.) contrl(3) — contrl(6) — Length of intin array = 0. Device handle. ptsin Array of coordinates in NDC/RC units. ptsin(O) ptsin(l) ptsin(2) ptsin{3) x-coordinate of first marker in NDC/RC units. y-coordinate of first marker in NDC/RC units. x-coordinate of second marker in NDC/RC units. y-coordinate of second marker in NDC/RC units. ptsin(2n-2) -- ptsin(2n-l) — x-coordinate of last marker in NDC/RC units. y-coordinate of last marker in NDC/RC units. Output contrl{2) — contrl(4) — Number of output vertices = 0. Length of intout array = 0. 4-4 GEM VDI Programmer's Guide Polymarker C BINDING Procedure Name Data Types Input Arguments v_pmarker( handle, count, pxyarray ) WORD v_pmarker ( ); WORD handle; WORD count; WORD pxyarray[2 * count]; handle = contrl[6] count = contrl[l] pxyarray[Oj = ptsin[0] pxyarray[l] = ptsin[lj pxyarray[2n-2] = ptsin[2n-2] pxyarray[2n-l] = ptsin[2n-l] 4-5 GEM VDI Programmer's Guide Text 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) — contrl(l) — contrl(3) — contrl(6) — Opcode = 8. Number of input vertices = 1. Length of intin array = n. Device handle. intin Character string as ASCII codes in 16-bit words. The maximum number of characters equals the size of the intin array. See Extended Inquire. ptsin(O) ptsin(l) x-coordinate of alignment point of text in NDC/RC units, y-coordinate of alignment point of text in NDC/RC units. Output contrl{2) — contrl{4) — Number of output vertices = 0. Length of intout array = 0. GEM VDI Programmer's Guide Text C BINDING Procedure Name Data Types Input Arguments v_gtext( handle, x, y, string ) WORD v_gtext ( ); WORD handle; WORD x; WORD y? BYTE string[n]; handle = contrl[6] x = ptsin[0] y = ptsin[l] string = intin Note: Bytes for the string array are mapped into the eight least significant bits of intin. The string must be null-terminated. 4-7 GEM 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 Guide Filled Area Input contrl(O) — contrl(l) — contrl(3) — contrl(6) — ptsin ptsin(O) — ptsin(l) — ptsin(2) — ptsin(3) — ptsin(2n-2) — ptsin(2n-l) — Opcode = 9. Number of vertices in polygon = n. Maximum number returned in Extended Inquire. Length of intin array = 0. Device handle. Array of coordinates of polygon in NDC/RC units, x-coordinate of first point in NDC/RC units. y-coordinate of first point in NDC/RC units. x-coordinate of second point in NDC/RC units. y-coordinate of second point in NDC/RC units. x-coordinate of last point in NDC/RC units. y-coordinate of last point in NDC/RC units. Output contr1(2) contrl (4) Number of output vertices = 0. Length of intout array = 0. 4-9 GEM VDI Programmer's Guide Filled Area C BINDING Procedure Name Data Types Input Arguments v_fillarea( handle, count, WORD v_fillarea ( ); WORD handle; WORD count; WORD pxyarray[2 * count]; handle = contrl[6] count = contrl[l] pxyarray[0] = ptsin[0] pxyarrayfl] = ptsin[l] pxyarray[2n-2] = ptsin[2n- pxyarray[2n-l] = ptsin[2n- pxyarray ) 2 ] 1 ] 4-10 GEM VDI Programmer's Guide Cell Array CELL ARRAY Input With the Cell Array function, the device draws a rectangular array defined by the input parameter (x,y) coordinates and the color index array. 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. contrl(O) — contrl(l) — contrl(3) — contrl(6) — contrl(7) — contrl{8) — contrl(9) — contrl (10) — Opcode = 10. Number of input vertices = 2. Length of color index array. Device handle. Length of each row in color index array (size as declared in a high-level language). Number of elements used in each row of color index array. Number of rows in color index array. Pixel operation to be performed. (See Set Writing Mode function in Section 5 for description of each mode. the ) intin(O) Color index array, stored by row. ptsin(O) — x-coordinate of lower corner in NDC/RC units. left ptsin(l) y-coordinate of lower corner in NDC/RC units. left ptsin(2) — x-coordinate of upper corner in NDC/RC units. right ptsin(3) y-coordinate of upper corner in NDC/RC units. right 4-11 GEM VDI Programmer's Guide Cell Array Output C BINDING Procedure Name Data Types Input Arguments contrl(2) — Number of output vertices = 0. contrl(4) — Length of intin array = 0. v_cellarray( handle, pxyarray, row_length, el_used, num_rows, wrtjmode, colarray ) 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]; handle = contrl[6] pxyarray[0] = ptsine[0] pxyarraytl] = ptsin[l] pxyarray[2] = ptsin[2] pxyarray[3] = ptsin[3] row_length = contrl[7] el_used = contrl[8] num_rows = contrl[9] wrt_mode = contrl[10] colarray[0] = intin[0] 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 surface or the color index stated in intin(0). This function is sometimes called a seed fill or a flood fill. If intin(0) 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) — contrl(l) — contrl(3) — contrl (6) — Opcode = 103. Number of input vertices = 1. Length of intin array = 1. Device handle. intin(O) Color index that defines the contour. ptsin(O) ptsin(l) — x-coordinate of starting point in NDC/RC units, 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[0] y = ptsinfl] index = intin[0] 4-13 GEM VDI Programmer's Guide Fill 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) — contrl(l) — contrl(3) — contrl(6) — ptsin(O) ptsin(l) ptsin(2) ptsin(3) Opcode = 114. Number of input vertices = 2. Length of intin array = 0. Device handle. x-coordinate of corner of destination r ec tangle in RC/NDC. y-coordinate of corner of destination r ec tangle i n RC/NDC. x-coordinate of corner of destination rectangle in RC/NDC diagonally opposite corner specified in ptsin(O). 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[0] = ptsin[0] pxyarray[3] = ptsin[3] 4-14 GEM VDI Programmer's Guide GDP GENERALIZED DRAWING PRIMITIVE (GDP) 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, with 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 . The Generalized Drawing Primitive (GDP) function allows you to use the predefined primitives. The application can draw special elements, such as arcs, circles, and ellipses using this function. 900 1800 -0 2700 Figure 4-2. Angle Specification Input contrl(0) — contrl(l) — contrl(3) — contrl(5) — 1 — BAR: 4 — CIRCLE: Opcode = 11. Number of vertices in ptsin. Length of input array intin. Primitive id. Uses fill area attributes (fill interior style, style index, writing mode, color and perimeter style). Uses fill area attributes (fill interior style, style index, writing mode, fill color and perimeter style). 4-15 GEM VDI Programmer's Guide GDP 2 — 3 — 5 — 6 — 7 — 8 — 9 __ 10 - Uses line attributes (color, linetype, writing mode, width, and end styles). Uses fill area attributes (interior style, writing mode, fill style, fill color, and perimeter style). Uses fill area attributes (fill interior style, writing mode, style index, color, and perimeter style). ELLIPTICAL ARC: Uses line attributes (color, linetype, writing mode, width, and end styles). ELLIPTICAL PIE: Uses fill area attributes (fill interior style, writing mode, style index, color and perimeter style). ROUNDED RECTANGLE: Uses line attributes (color, linetype, writing mode, and width). FILLED ROUNDED RECTANGLE: Uses fill area attributes (fill interior style, writing mode, style index color, and perimeter style, color, and width). JUSTIFIED GRAPHICS TEXT: Uses text attributes (face, character height, character baseline vector, color index, special effects, and alignment). ARC: PIE: ELLIPSE: contr1(6) Device handle. ptsin Array of coordinates for GDPs in NDC/RC units. ptsin(0) ptsin(1) ptsin(2) x-coordinate of first point in NDC/RC units. y-coordinate of first point in NDC/RC units. x-coordinate of second point in NDC/RC units. 4-16 GEM VDI Programmer's Guide GDP ptsin(3) ptsin(2n-2) ptsin(2n-l) intin y-coordinate of second point in NDC/RC units. — x-coordinate of last point in NDC/RC units. — y-coordinate of last point in NDC/RC units. — Angle for arcs and pies or characters for justified graphics text. 4-17 GEM VDI Programmer's Guide BAR BAR Opcode = 11. Number of input vertices = 2. Length of intin array = 0. Primitive id = 1. Device handle. x-coordinate of corner of bar in NDC/RC units. y-coordinate of corner of bar in NDC/RC units. x-coordinate of corner diagonally opposite the corner selected in ptsin(O) of bar in NDC/RC units. y-coordinate of 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 Procedure Name v_bar( handle, pxyarray ) Data Types WORD v_bar ( ); WORD handle; WORD pxyarray[4]; Input Arguments handle = contrl[6] pxyarray[0] = ptsin[0] pxyarrayfl] = ptsin[l] pxyarray[2] = ptsin[2] pxyarray[3] = ptsin[3] Input contrl(O) — contrl(l) — contrl(3) — contrl(5) — contrl(6) — ptsin{0) ptsin(l) ptsin(2) ptsin(3) 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(1)). Input contrl(0) Opcode = 11. contr1(1) — 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(0) — Start angle (in tenths of degrees 0-3600), counterclockwise. intin(1) " End angle (in tenths of degrees 0-3600) . ptsin(0) — x-coordinate of center point of arc in NDC/RC units. ptsin(1) — 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 vertices = 0 contrl (4) — Length of intout array = 0. 4-19 GEM VDI Programmer's Guide ARC & PIE C BINDING Procedure Name Data Types Input Arguments v_arc( handle, x, y, radius, begang, endang ) v_pieslice( handle, x, y, radius, begang, endang ) WORD v_arc ( ); WORD handle; WORD x, y; WORD radius; handle = contrl[6] x = ptsin[0] y = ptsin[lj radius = ptsin[6] begang = intin[0] endang = intinfl] 4-20 GEM VDI Programmer's Guide CIRCLE CIRCLE This function is not required and may not be supported on all devices. Input contrl (0) — — Opcode = 11. contrl(1) — Number of input vertices = 3. contrl (3) — Length of intin array = 0. contrl(5) — Primitive id = 4. contrl(6) — Device handle. ptsin(0) — x-coordinate of center point of circle in NDC/RC units. ptsin (1) — — 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[0] y = ptsinfl] radius = ptsin[4] GEM VDI Programmer's Guide ELLIPTICAL ARC and PIE ELLIPTICAL ARC AND PIE Input contrl(O) — contrl{l) — contrl(3) — contrl{5) — contrl(6) — intin(O) intin(l) ptsin(O) ptsin(l) ptsin(2) ptsin(3) Opcode = 11. Number of input vertices = 2. Length of intin array = 2. Primitive id. 6 = ELLIPTICAL ARC 7 = ELLIPTICAL PIE SLICE Device handle. Start angle (in tenths of degrees 0-3600) , counterclockwise. End angle (in tenths of degrees 0-3600) . x-coordinate of center point of arc in NDC/RC units. y-coordinate of center point of arc in NDC/RC units. Radius units. of X-axis in NDC/RC Radius units. of Y-axis in NDC/RC Output contrl(2) — Number of output vertices = 0. contrl(4) — Length of intout array = 0. 4-22 GEM VDI Programmer's Guide ELLIPTICAL ARC and PIE C BINDING Procedure Name v_ellarc( handle, x, y, begang, endang ) xradius, yradius v_ellpie( handle, x, y, begang, endang ) xradius, yradius 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[0] y = ptsin[l] xradius = ptsin[2] yradius = ptsin[3] begang = intin[0] endang = intin[l] 4-23 GEM VDI Programmer's Guide ELLIPSE ELLIPSE Input contrl(O) — contrl(I) — contrI(3) — contrl(5) — contrl(6) — ptsin{0) ptsin(l) ptsin(2) ptsin(3) Opcode = 11. Number of input vertices = 2. Length of intin array = 0. Primitive id = 5. Device handle. x-coordinate of center point of ellipse in NDC/RC units, y-coordinate of center point of ellipse in NDC/RC units. Radius of X-axis in NDC/RC units. 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[6] x = ptsin[0] y = ptsinfl] xradius = ptsin[2] yradius = ptsin[3] 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) — contrl(l) — contrl(3) — contrl(5) — contrl(6) — ptsin(O) ptsin(l) ptsin(2) ptsin(3) Opcode = 11. Number of input vertices = 2. Length of intin array = 0. Primitive id. 8 = Rounded Rectangle 9 = Filled Rounded Rectangle Device handle. x-coordinate of corner of rectangle in NDC/RC units, y-coordinate of corner of rectangle in NDC/RC units, x-coordinate of corner diagonally opposite corner selected in ptsin(O) of rectangle in NDC/RC units, y-coordinate of corner diagonally opposite corner selected in ptsin(l) of rectangle in NDC/RC units. Output contr1(2) contr1(4) Number of output vertices = Length of intout array = 0. 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 handle; WORD xyarray[4]; Input Arguments handle = contrl[6]; attributes = intin[0]; xyarray[0] = ptsin[0]; xyarray[l] = ptsin[l]; xyarray[2] = ptsin[2]; xyarray[3] = ptsin[3]; 4-26 GEM VDI Programmer's Guide Justified Graphics Text JUSTIFIED TEXT Input GRAPHICS This function outputs graphics text to the 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. contrl(O) — contrl(l) — contrl(3) — contrl(5) — contrl(6) — Opcode = 11. Number of input vertices = 2. Length of intin array = 2 + n (characters in string). Primitive id = 10. Device handle. intin(0) intin(1) intin(2) Inter-word spacing flag. 0 = Doesn't allow GEM VDI to modify inter-word spacing. nonzero = Allows GEM VDI to modify inter-word spacing. Inter-character spacing flag. 0 = Doesn't allow GEM VDI to modify inter-character spacing. nonzero = Allows GEM VDI to modify inter-character spacing. First character of text string. intin(n+1) — Last character of text string. 4-27 GEM VDI Programmer's Guide Justified Graphics Text ptsin(O) x-coordinate of the text alignment point, units. in NDC/RC ptsin(l) y-coordinate of the text alignment point, units. in NDC/RC 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 Data Types Input Arguments v_justified(handle, x, y, string, length, word_space, char_space); WORD v_justified(); WORD handle; WORD x, y; WORD length; WORD word_space; WORD char_space; BYTE string [ ]; handle = contrl[6]; x = ptsin[0]; y = ptsin[1]; length = ptsin[2]; word_space = intin[0]; char_space = intin[1]; stringtj] = intin[j+2]; 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 4-29 Section 5 Attribute Functions INTRODUCTION SET WRITING MODE Attribute functions determine qualities of all subsequent output primitives such as color, type, style, and height. 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 5-1 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 GEM VDI Programmer's Guide Set Writing Mode Reverse transparent mode only affects the 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) — contrl(l) — contrl(3) — contrl(6) — Opcode = 32. Number of input vertices = 0. Length of intin array = 1. Device handle. intin(O) Writing mode requested. Output contrl(2) — contrl(4) — Number of output vertices = 0. Length of intout array = 1. 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 = contrl[6] mode = intin[0] Output Arguments set_mode = intout[0] Reverse Transparent 5-3 GEM VDI Programmer's Guide Set Color Representation 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(0) contrl(l) contrl(3) contrl(6) intin(0) intin(l) intin(2) intin(3) Opcode = 14. Number of input vertices = 0. Length of intin array = 4. Device handle. Color index. Red color intensity (in tenths of percent, 0-1000). Green color intensity. Blue color intensity. Output contrl(2) contrl(4) Number of Length of output vertices = intout array = 0. 0 . 5-4 GEM VDI Programmer's Guide Set Color Representation C BINDING Procedure Name Data Types Input Arguments vs_color( handle, index, rgb_in ) WORD vs_color ( ); WORD handle; WORD index; WORD rgb_in[3]; handle = contrl[6] index = intinCO] rgb_in[0] = intin[l] rgb__in[l] = intin[2] rgb_in[2] = intin[3] 5-5 GEM VDI Programmer's Guide Set Polyline Line Type SET POLYLINE LINE TYPE This function sets the line type for subsequent polyline operations. The total number of line styles available is device¬ dependent, but all devices support at least six. If the requested line style is out of range, GEM VDI selects solid (1) line style. The pixel value in the pattern word is 1 = pixel on (active); 0 = pixel off. 16 Bits Style MSB LSB 1 solid 2 long dash 3 dot 4 dash,dot 5 dash 6 dash,dot,dot 7 user-defined style 8-n device¬ dependent 1111111111111111 1111111111110000 1110000011100000 1111111000111000 1111111100000000 1111000110011000 16 bits (1 word) Most Significant Bit = first pixel displayed. Line style seven, user-defined style, uses the pattern the Set User-defined Line Style Pattern function defines. This pattern defaults to solid until the user defines it. Notes If a nondefault line width is used, the device may draw the thickened line using a solid line style and may change the writing mode. 5-6 GEM VDI Programmer's Guide Set Polyline Line Type Input contrl(O) — contrl(l) — contrl(3) -- contrl(6) — Opcode = 15. Number of input vertices = 0. Length of intin array = 1. Device handle. intin(O) Requested line style. Output contrl(2) — contrl(4) — Number of output vertices = 0. 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 = contrlC6] style = intin[0] Output Arguments set_type = intout[0] 5-7 GEM VDI Programmer's Guide Set User-defined Line Style Pattern SET USER-DEFINED LINE STYLE PATTERN This function sets the current user-defined 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 contrl(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[6] pattern = intin[0] 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 contrl(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 Guide Set Polyline Line Width C BINDING Procedure Name Data Types Input Arguments set width = vsl_width( handle, width ) WORD set_width; WORD vsl_width? WORD handle; WORD width? handle = contrl[6] width = ptsin[0] set_width = ptsout[0] Output Arguments GEM VDI Programmer's Guide Set Polyline Color Index 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. contrl(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 = 1. 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 handle; WORD color index; Input Arguments handle = contrl[6] color_index = intinCO] Output Arguments set_color = intout[0] 5-11 GEM VDI Programmer's Guide Set Polyline End Styles SET POLYLINE 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) — contrl(l) — contrl(3) — contrl(6) — Opcode = 108. Number of input vertices = 0. Length of intin array = 2. Device handle. intin(0) intin(l) End style for beginning point of polyline. 0 - squared (default) 1 - arrow 2 - rounded End style for ending point of polyline. 0 - squared (default) 1 - arrow 2 - rounded Output contrl(2) — contrl(4) — Number of output vertices = 0. Length of intout array = 0. 5-12 GEM VDI Programmer's Guide Set Polyline End Styles C BINDING Procedure Name vsl_ends( handle, beg_style, end_style ) Data Types WORD vsl_ends(); WORD handle; WORD beg_style; WORD end_style; Input Arguments handle = contrl[6]? beg_style = intin[0]; end_style = intin[l]; 5-13 GEM VDI Programmer's Guide Set Polymarker Type 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: 1 2 3 4 5 6 7 - + _ * - 0 - X - <> Dot Plus Asterisk Square Diagonal Cross Diamond Device-dependent If the requested marker type is out of range, GEM VDI uses an asterisk, type 3. Marker 1 is the smallest dot GEM VDI displays on the device; it cannot be scaled. Input contrl(0) contr1(1) contrl(3) contrl(6) Opcode = 18. Numbers of input vertices = 0. Length of intin array = 1. Device handle. intin(0) Requested polymarker type. Output contrl(2) — Number of output vertices = 0. contrl(4) — Length of intout array = 1. intout(O) — Polymarker type selected. 5-14 GEM VDI Programmer's Guide Set Polymarker Type C BINDING Procedure Name Data Types Input Arguments set_type = vsm_type( handle, symbol ) WORD set_type; WORD vsm_type ( ); WORD handle; WORD symbol; handle = contrl[6] symbol = intin[0] Output Arguments set_type = intout[0] GEM VDI Programmer's Guide Set Polymarker Height SET POLYMARKER This function sets a polymarker height for HEIGHT subsequent polymarker functions. If 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 contrl(O) — Opcode = 19. contrl(l) — Number of input vertices = 1. 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 = 1. 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 handle? WORD height? Input Arguments handle = contrl[6] height = ptsin[l] Output Arguments set_height = ptsout[l] 5-16 GEM VDI Programmer's Guide Set Polymarker Color Index SET POLYMARKER COLOR INDEX This function sets the color index for 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) — contrl(l) — contrl{3) — contrl(6) — Opcode = 20. Number of input vertices = 0. Length of intin array = 1. Device handle. intin(O) Requested polymarker color index. Output contrl(2) — contrl(4) — number of output vertices = 0. 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[6] color index = intin[0] Output Arguments set color = intout[0] 5-17 GEM VDI Programmer's Guide Set Character Height, Absolute Mode This function sets the current graphic text character height in NDC/RC units. The 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. SET CHARACTER HEIGHT, ABSOLUTE MODE Input contrl(O) — contrl(l) — contrl(3) — contrl(6) — Opcode = 12. Number of input vertices = 1. Length of intin array = 0. 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 GEM VDI Programmer's Guide Set Character Height, Absolute Mode C BINDING Procedure Name Data Types Input Arguments Output Arguments vst_height( handle, height, &char_width, &char_height, &cell_width, &cell_height ) WORD vst_height ( ); WORD handle; WORD height; WORD char_width; WORD char_height; WORD cell_width; WORD cell_height; handle = contrl[6] height = ptsin[l] char_width = ptsout[0] char_height = ptsout[l] cell_width = ptsout[2] cell_height = ptsout[3] 5-19 GEM VDI Programmer's Guide Set Character Height, Points Mode SET CHARACTER CELL HEIGHT, POINTS MODE Input This function sets the current graphic text character height in printer points. A point is l/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 w Character Width Cell Width Figure 5-1. Character Cell Definition contrl(0) contrl(l) contrl(3) contrl(6) Opcode = 107. Number of input vertices = 0. Length of intin array = 1. Device handle. intin(0) Cell height in points. 5-20 GEM VDI Programmer's Guide Set Character Height, Points Mode Output C BINDING Procedure Name Data Types Input Arguments Output Arguments contrl(2) — Number of output vertices = 2. contrl(4) — Length of intout array = 1. intout(O) — Selected cell height in points. ptsout(O) — ptsout(l) — ptsout(2) — ptsout(3) — Character width selected in NDC/RC units. Character height selected in NDC/RC units. Character cell width in NDC/RC units. Character cell height in NDC/RC units. set_j?oint = vst_jpoint( handle, point, &char_width, &char__height, &cell_width, &cell_height ) WORD set_point; WORD vst_point( ); WORD handle; WORD point; WORD char_width; WORD char_height; WORD cell_width; WORD cell_height; handle = contrl[6] point = intin[0] set_point( ) = intout[0] char_width = ptsout[0] char_height = ptsoutCl] cell_width = ptsout[2] cell_height = ptsout[3] 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 Notes 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(0) contrl(1) contrl(3) contrl(6) Opcode = 13. Number of input vertices = 0. Length of intin array = 1. Device handle. intin(O) — Requested angle of rotation of character baseline (in tenths of degrees, 0 - 3600). Output contrl(2) contrl(4) intout(0) Number of output vertices = 0. Length of intout array = 1. Angle of rotation of character baseline selected (in tenths of degrees 0-3600). 5-22 GEM VDI Programmer's Guide Set Character Baseline Vector C BINDING Procedure Name set_baseline = vst_rotation( handle, angle ) Data Types WORD set_baseline; WORD vst_rotation ( ) ; WORD handle; WORD angle; Input Arguments handle = contrl[6] angle = intinCO] Output Arguments set_baseline = intout[0] 5-23 GEM VDI Programmer's Guide Set Text Face 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. Opcode = 21. Number of input vertices = 0. Length of intin array = 1. Device handle. Requested software text face number. 1 - 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 = 1. intout(0) — Text face selected. Input contrl(0) contrl(1) contrl(3) contrl(6) intin(0) 5-24 GEM VDI Programmer's Guide Set Text Face C BINDING Procedure Name Data Types Input Arguments Output Arguments set_font = vst_font( handle, font ) WORD set_font; WORD vst_font ( ); WORD handle? WORD font? handle = contrl[6] font = intin[0] set font = intout[0] 5-25 GEM VDI Programmer's Guide Set Graphic Text Color Index 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 device-dependent maximum. If the requested index is out of range, GEM VDI selects color index 1. Input contrl(0) contr1(1) contr1(3) contrl(6) Opcode = 22. Number of input vertices = 0. Length of intin array = 1. Device handle. intin(0) Requested text color index. Output contrl(2) — Number of output vertices = 0. contr1(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[6] color_index = intin[0] Output Arguments set color = intout[0] 5-26 GEM VDI Programmer's Guide Set Graphic Text Special Effects SET GRAPHIC TEXT SPECIAL EFFECTS This function sets text special effects for 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 Bit Value Description 0 Thickened 0 thickened not selected 1 set style to thickened 1 Intensity 0 normal intensity 1 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(0) contrl(l) contrl( 3 ) contrl(6) Opcode = 106. — Number of input vertices = 0. Length of intin array = 1. Device handle. intin(0) Special effect word. Number of output vertices = 0. — Length of intout array = 1. — Styles actually selected (style word with the appropriate bits set). Normal Thickened Light Intensity Skewed Underlined Figure 5-3. Graphic Text Special Effects ABCDE ABODE a o r\ r~ ^ I' I .? f ; I " ® li mmmm ABODE ABCDE Output contrl(2) contrl(4) intout(0) 5-28 GEM VDI Programmer's Guide Set Graphic Text Special Effects C BINDING Procedure Name Data Types Input Arguments Output Arguments set_effect = vst_effects( handle. WORD set_effect; WORD vst_effects( ); WORD handle? WORD effect; handle = contrl[6] effect = intin[0] set_effect = intout[0] effect ) 5-29 GEM VDI Programmer's Guide Set Graphic Text Alignment SET GRAPHIC ALIGNMENT TEXT This function sets horizontal and vertical 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. Leading Tod Line Ascent Line a ~*~r Half Line AlgTL Base Line _^_ Bottom Line Tod Line Ascent Line Half Line This Base Line Descent Line Bottom Line Figure 5-4. Graphic Text Alignment 5-30 GEM VDI Programmer's Guide Set Graphic Text Alignment Input contrl(O) — contrl(l) — contrl(3) — contrl(6) — Opcode = 39. Number of input vertices =0. Length of intin array = 2. Device handle. intin(O) — Horizontal alignment requested. 0 = left justified (default) 1 = 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) — contrl(4) — Number of output vertices = 0. Length of intout array = 2. intout(O) — intout(1) — Horizontal alignment selected. 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 = contrl[6] hor_in = intin[0] vert_in = intin[l] Output Arguments hor_out = intout[0] vert out = intout[l] 5-31 GEM VDI Programmer's Guide Set Fill Interior Style SET FILL INTERIOR STYLE This function sets the fill interior 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 contrl(O) — contrl(l) — contrl(3) — contrl(6) — Opcode = 23. Number of input vertices = 0. Length of intin array = 1. Device handle. intin(O) Requested fill interior style. 0 - hollow 1 - solid 2 - pattern 3 - hatch 4 - user-defined style Output contrl(2) — contrl(4) — Number of output vertices = 0. Length of intout array = 1. intout(O) — Fill interior style selected. C BINDING Procedure Name set_interior = vsf_interior( handle, style ) Data Types WORD set_interior; WORD vsf_interior ( ) WORD handle; WORD style; Input Arguments handle = contrl[6] style = intinCO] Output Arguments set_interior = intout[0] 5-32 GEM VDI Programmer's Guide Set Fill Style Index SET FILL INDEX STYLE This function selects a fill style based on 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. 0,n iYiYiViW 2,1 miiiimnutiii 2,2 t fy'i iSui'yV VVt^Vtx'W 2,3 Bill 2,4 ws. 2,5 2,6 2,7 Bsgf; 2,8 2,9 2,10 A ’’’ ■' 2,11 T7TTTTT7T 2,12 '/ 2,13 i* i'.' 2,14 2,15 2,16 2,17 ’ 2,18 2,19 W': 2,20 A A.~ 2,21 II llllltMlIMHIl 2,22 . 2,23 ■Hi 2,24 '&///. 3,1 7777 / 3,2 TO 3,3 mm 3,4 1 1 3,5 1 t 1 1 3,6 / / 3,7 szn 3,8 3,10 3,11 3,12 Figure 5-5. Fill Styles and Indices 5-33 GEM VDI Programmer’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) — contrl(l) — contrl(3) — contrl(6) — Opcode = 24. Number of input vertices = 0. Length of intin array = 1. Device handle. intin(O) Requested fill style index for pattern or hatch fill. Output contrl(2) — contrl(4) — Number of output vertices = 0. 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[6] style_index = intin[0] Output Arguments set_style = intout[0] 5-34 GEM VDI Programmer's Guide Set Fill Color Index 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 = 1. 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[6] color index = intin[0] Output Arguments set_color = intout[0] 5-35 GEM VDI Programmer's Guide Set Fill Perimeter Visibility SET FILL PERIMETER VISIBILITY This function turns the outline of a fill 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 vis ible. Input contrl(O) — contrl(l) — contrl(3) — contrl(6) — Opcode = 104. Number of input vertices = 0. Length of intin array = 1. Device handle. intin(O) Visibility flag. zero - invisible nonzero - visible Output contrl(2) — contrl(4) — Number of output vertices = 0. 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[6] per_vis = intin[0] Output Arguments set_j?erimeter = intout[0] 5-36 GEM VDI Programmer's Guide Set User-defined Fill Pattern 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 contrl(O) — Opcode = 112. contrl(l) — Number of input vertices = 0. contrl(3) — Length of intin array = 16 to n. contrl(6) — Device handle. 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 GEM VDI Programmer's Guide Set User-defined Fill Pattern C BINDING Procedure Name Data Types Input Arguments vsf_udpat( handle, pfill_pat, planes ) WORD vsf_udpat; WORD handle; WORD pfill_pat[16 x n where n > 0] WORD planes; handle = contrl[6] pfill_ pfill pat planes = contrl[3]/l6 End of Section 5 5-38 Section 6 Raster Operations INTRODUCTION MEMORY FORM DEFINITION BLOCK Raster operations perform logic operations on rectangular blocks of bits in memory and on rectangular blocks of pixels on physical devices. A raster area is defined by a Memory Form Definition Block (MFDB). An MFDB consists of the following components: • A 32-bit pointer to the memory address of the upper left corner of the first plane of the raster area. This pointer corresponds to an offset-segment pointer for 8086-based microcomputers. If all 32 bits of this pointer are 0, the MFDB is for a physical device, and the other parameters are ignored. • The height and width of the raster area in pixels. • The width of the raster area in words. This value is equal to the width of the raster area in pixels, divided by the word size. • The number of planes in the raster area. • A flag indicating whether the format of the raster area is standard or device-dependent. • Some locations reserved for future use. A raster area must start on a word boundary and have a width that is an integral multiple of the word size- 6-1 GEM VDI Programmer's Guide Memory Form Definition Block RASTER AREA FORMATS Word 1 Word 2 Word 3 Word 4 Word 5 Word 6 Word 7 Word 8 Word 9 Word 10 Figure 6-1. Memory Form Definition Block One word (16 bits) Memory pointer word 1 Memory pointer word 2 Form Width in Pixels Form Height in Pixels Form Width in Words Form format flag Number of Memory Planes Reserved for future use Reserved for future use Reserved for future use Two memory formats are associated with raster 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 GEM VDI Programmer's Guide Raster Area Formats • 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 pixel-value-to-color-index mapping for eight-color and sixteen-color screens, respectively. • 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. • 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 Color Index Color 0 white 2 red 010 3 green Oil 6 yellow 4 blue 101 7 magenta 110 5 cyan 111 1 black 6-3 GEM VDI Programmer's Guide Raster Area Formats Table 6-2. Pixel Value to Color Index Mapping for 16-color Screens Pixel Value Color Index Color 0000 0 white 0001 2 red 0010 3 green 0011 6 yellow 0100 4 blue 0101 7 magenta 0110 5 cyan 0111 8 low white 1000 9 grey 1001 10 light red 1010 11 light green 1011 14 light yellow 1100 12 light blue 1101 15 light magenta 1110 13 light cyan 1111 1 black Note: A pixel value of 0 maps to the background color. In addition to the MFDB, Copy Raster also takes a rectangle as an argument. This allows operations on a specified portion of the raster area. A rectangle is specified by the x,y coordinates of its upper left and lower right vertices. COORDINATE SYSTEMS A sample single-plane memory form with a form width of 16 pixels, a form height of 8 pixels, and a highlighted rectangle with corners of (3,1) and (6,5) is shown in Figure 6-3. 6-4 GEM VDI PRogrammer's Guide Coordinate Systems GEM VDI PRogrammer's Guide Logic Operations 1AGIC 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 • D'= destination pixel value after the logical operation Table 6-3. Raster Operation Logic Operations Mode Definition 0 D 1 = 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 D] 10 D'= NOT D 11 D'= S OR [NOT D] 12 D 1 = NOT S 13 D'= [NOT S] OR D 14 D'= NOT [S AND D] 15 D’= 1 6-6 GEM VDI Programmer's Guide Copy Raster, Opaque COPY RASTER, OPAQUE Input This function copies a rectangular raster 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. 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. contr 1( 9-10) - Double-word address of the destination Memory Form Definition Block. intin(O) ptsin(O) ptsin{l) — ptsin{2) — ptsin(3) — Logic operation (refer to "Introduction" in this section). x-coordinate of corner of source rectangle in RC/NDC. y-coordinate of corner of source rectangle in RC/NDC. x-coordinate of corner diagonally opposite corner selected in ptsin(O) of source rectangle in RC/NDC. y-coordinate of corner diagonally opposite corner selected in ptsin(l) of source rectangle in RC/NDC. 6-7 GEM VDI Programmer's Guide ptsin(4) ptsin(5) ptsin(6) ptsin(7) Copy Raster, Opaque x-coordinate of corner of destination rc/ndc. r e c tangle in y-coordinate of corner of destination RC/NDC. r e c tangle i n x-coordina te of corner of de s t ina t ion RC/NDC. r ec tangle i n y-coordinate of corner of destination RC/NDC. r ec tangle i n 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, pdesMFDB ) Data Types WORD vro_cpyfm ( ); WORD handle 7 WORD wr_mode 7 WORD pxyarray[8]7 WORD *psrcMFDB 7 WORD *pdesMFDB 7 Input Arguments handle = contrl[6] wr_mode = intin[0] pxyarrayCO] = ptsin[0] pxyarrayCl] = ptsin[l] pxyarray[7] = ptsin[7] psrcMFDB = contrl[7-8] pdesMFDB = contrl[9-10] 6-8 GEM VDI Programmer's Guide Copy Raster, Transparent COPY RASTER, TRANSPARENT This function copies a monochrome rectangular raster area from source form to a color area. A writing mode and color indices for both 0's and l'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 Transparent Mode Reverse Transparent mode only affects the pixels associated with a source value of 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 Opcode = 121. Number of input vertices = 4. Length of intin array = 3. Device handle. Double-word address of the source Memory Form Definition Block. Double-word address of the destination Memory Form Definition Block. Writing Mode. Color index for Is in data. Color index for Os in data. x-coordinate of corner of source rectangle in RC/NDC. y-coordinate of corner of source rectangle in RC/NDC. x-coordinate of corner diagonally opposite corner selected in ptsin(O) of source rectangle in RC/NDC. y-coordinate of corner diagonally opposite corner selected in ptsin(l) of source rectangle in RC/NDC. contrl(O) — contrl(l) — contrl(3) — contrl{6) — contrl(7-8)— contr1(9-10) - intin(O) intin(l) intin{2) — ptsin(O) ptsin(l) ptsin(2) ptsin{3) ptsin(4) — ptsin(5) ptsin(6) — ptsin(7) x-coordinate destination RC/NDC. y-coordinate de s tination RC/NDC. x-coordinate de s tination RC/NDC. y-coordinate destination RC/NDC. of corner of r e c tangle in of corner of rectangle in of corner of rec tangle i n of corner of rec tangle in 6-10 GEM VDI Programmer's Guide Copy Raster, Transparent Output C BINDING Procedure Name Data Types Input Arguments contrl(2) — Number of output vertices = 0. contrl(4) — Length of intout array = 0. vrt_cpyfm( handle, wr_mode, pxyarray, psrcMFDB, pdesMFDB, color_index ) WORD vrt_cpyfm ( ); WORD handle; WORD wr_mode; WORD pxyarray[8]; WORD *psrcMFDB; WORD *pdesMFDB; WORD color index[2]; handle = contrl[6] wr_mode = intin[0] pxyarrayCO] = ptsin[0] pxyarrayCl] = ptsin[l] pxyarray[7] = ptsin[7] psrcMFDB = contrl[7-8] pdesMFDB = contrl[9-10] color_index[03 = intin[l] color_index[lD = intin[2] 6-11 GEM VDI Programmer's Guide Transform Form 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) — contrl(l) — contrl(3) — contrl(6) — contrl(7-8) — contrl(9-10) - Opcode = 110. Number of input vertices = 0. Length of intin array = 0. Device handle. Double-word address of the source MFDB. Double-word address of the destination MFDB. Output contrl(2) — contrl(4) — Number of output vertices = 0. Length of intout array = 0. C BINDING Procedure Name vr_trnfm( handle, psrcMFDB, pdesMFDB ) Data Types WORD vr_trnfm ( ); WORD handle? WORD *psrcMFDB? WORD *pdesMFDB; Input Arguments handle = contrl[6] psrcMFDB = contrl[7-8] pdesMFDB = contrl[9-10] 6-12 GEM VDI Programmer's Guide Get Pixel GET PIXEL This function returns a pixel value and a color index for the pixel specified by ptsin(O), ptsin(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(1) — Number of input vertices = 1. contrl(3) — Length of intin array = 0. contrl(6) — Device handle. ptsin(0) — x-coordinate of pixel in RC/NDC units. ptsin(1) — y-coordinate of pixel in RC/NDC units. Output contr1(2) contrl (4) Number of output vertices = 0. Length of intout array = 2. intout(0) — Pixel value, intout(1) — Color index. GEM VDI Programmer's Guide Get Pixel C BINDING Procedure Name Data Types Input Arguments Output Arguments v_get_j?ixel( handle, x, y, pel, index ) WORD v get pixel( ); WORD handle; WORD x; WORD y; WORD *pel; WORD *index; handle = contrl[6] x = ptsin[0] y = ptsinCl] pel = intout[0] 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: • locator • valuator • choice • string Select the input mode in intin(l). Input contr1(0) — Opcode = 33. contrl(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. 1 = request 2 = sample 7-1 GEM VDI Programmer's Guide Set Input Mode Output C BINDING Procedure Name Data Types Input Arguments contrl(2) — Number of output vertices = 0. contrl(4) — Length of intout array = 1. intout(O) — Input mode selected. vsin_mode( handle, dev_type, mode ) WORD vsin_mode ( ); WORD handle; WORD dev_type; WORD mode; handle = contrl[6] dev_type = intin[0] mode = intin[l] 7-2 GEM VDI Programmer's Guide Input Locator, Request Mode INPOT LOCATOR, 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. 7-3 GEM VDI Programmer's Guide Input Locator, Request Mode Output contrl(2) — contrl(4) — intout(O) — ptsout(O) — ptsout(l) — Number of output vertices = 1. Length of intout array = 1. 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. Final x-coordinate of locator in NDC/RC units. Final y-coordinate of locator in NDC/RC units. 7-4 GEM VDI Programmer's Guide Input Locator, Request Mode C BINDING Procedure Name Data Types Input Arguments Output Functions vrq_locator( handle, x, y, &xout, &term ) WORD vrq_locator ( ); WORD handle; WORD X, y; WORD xout; WORD yout; WORD term; handle = contrl[6] x = ptsin[0] y = ptsinfl] xout = ptsout[0] yout = ptsoutfl] term = intout[0] &yout, 7-5 GEM VDI Programmer's Guide Input Locator, Sample Mode INPUT LOCATOR, SAMPLE MODE This function returns the position in NDCs 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 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. Output contrl(2) — Number of output vertices. 1 = coordinate changed 0 = no coordinate changed contrl(4) — Length of intout array. 0 = no keypress character 1 = keypress character returned 7-6 GEM VDI Programmer's Guide Input Locator, Sample Mode Table 7-1. Sample Mode Status Returned Event Control (2) Array (4) Coordinates change. 1 0 Key pressed; coordinates not changed from what was pressed. 0 1 No input. 0 0 Key pressed; coordinates changed. 1 1 intout(O) ptsout(O) ptsout(l) Locator keypress if keypress occurs. This information is the same as for Input Locator, Request Mode function. New x-coordinate of locator in NDC/RC units. New y-coordinate of locator in NDC/RC units. 7-7 GEM VDI Programmer's Guide Input Locator, Sample Mode C BINDING Procedure Name Data Types Input Arguments Output Arguments status = vsm_locator( handle, x, y, &xout, &yout, Scterm ) WORD status; WORD vsm_locator ( ); WORD handle; WORD x, y ; WORD xout; WORD yout; WORD term; handle = contrl[6] x = ptsinCO] y = ptsinCl] status = contrl[2] | (contrl[4] << 1) xout = ptsout[0] yout = ptsout[l] term = intout[0] 7-8 GEM VDI Programmer's Guide Input Valuator, Request Mode 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) — contrl(l) — contrl(3) — contrl(6) — Opcode = 29. Number of input Length of intin Device handle. vertices = 0. array = 1. intin(0) Initial value. Output contrl(2) contrl(4) Number of output vertices = 0. Length of intout array = 2. intout(0) — Output value, intout(1) — Terminator. 7-9 GEM VDI Programmer's Guide Input Valuator, Request Mode C BINDING Procedure Name Data Types Input Arguments Output Arguments vrq_valuator( handle, valuator_in, Svaluator out, sterminator ) WORD vrq_valuator ( ); WORD handle; WORD valuator_in; WORD valuator_out; WORD terminator; handle = contrl[6] valuator_in = intin[0] valuator_out = intout[0] terminator = intout[1] 7-10 GEM VDI Programmer's Guide Input Valuator, Sample Mode 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) — contrl(l) — contrl(3) — contrl(6) — Opcode = 29. Number of input vertices = 0. Length of intin array = 1. Device handle. intin(O) Initial value. Output contr1(2) contrl(4) intout(0) intout( 1) Number of output vertices = 0. Length of intout array. 0 = nothing happened 1 = valuator changed 2 = keypress character New valuator value. Keypress, if keypress event occurred. 7-11 GEM VDI Programmer's Guide Input Valuator, Sample Mode C BINDING Procedure Name Data Types Input Arguments Output Arguments vsm_valuator( handle, val_in, &val_out, Scterm, &status ) WORD vsm_valuator ( ); WORD handle; WORD val_in; WORD val_out; WORD term; WORD status; handle = contrl[6] val in = intin[0] val_out = intout[0] term = intout[l] status = contrl[4] 7-12 GEM VDI Programmer's Guide Input Choice, Request Mode 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 is a 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 vr q choice( handle, ch_in, &ch_out ) Data Types WORD vrq_choice ( ); WORD handle? WORD ch_in? WORD *ch out ? Input Arguments handle = contrl[6] ch in = intin[0] Output Arguments *ch_out = intout[0] 7-13 GEM VDI Programmer's Guide Input Choice, Sample Mode INPUT CHOICE, SAMPLE MODE This function returns the choice status of 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 contrl(O) — contrl(l) — contrl(3) — contrl(6) — Opcode = 30. Number of input vertices = 0. Length of intin array = 0. Device handle. Output contrl(2) — contrl(4) — Number of output vertices = 0. Choice status. 0 = nothing happened 1 = sample successful intout(0) — 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 Output Arguments handle = contrl[6] choice = intout[0] status = contrl[4] 7-14 GEM VDI Programmer's Guide Input String, Request Mode This function returns a string from the 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 contrl(O) — contrl(l) — contrl(3) — contrl(6) — Opcode = 31. Number of input vertices = 1. Length of intin array = 2. Device handle. intin(O) intin(l) Maximum string length. Echo mode. 0 = no echo 1 = echo input characters' at position specified ptsin(O) ptsin(l) x-coordinate of echo area in NDC/RC units. 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. INPUT STRING, REQUEST MODE 7-15 GEM VDI Programmer's Guide Input String, Request Mode C BINDING Procedure Name Data Types Input Arguments Output Arguments vrq_string( handle, max_length, echo__mode, echo_xy, &string ) WORD vrq_string ( ); WORD handle; WORD max_length; WORD echo_mode; WORD echo_xy[2]; BYTE string[max_length+l]; handle = contrl[6] max_length = intin[0] echo_mode = intin[l] echo_x,y = ptsin[0-l] 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, SAMPLE MODE This function returns a string from the 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 contrl(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) contrl(4) intout Number of output vertices = 0. Length of output string. 0 = sample unsuccessful (characters not available) >0 = sample successful (characters available) Output string, if sample successful. 7-17 GEM VDI Programmer's Guide Input String, Sample Mode C BINDING Procedure Name Data Types Input Arguments Output Arguments status = vsm_string( handle, max_length, echo_mode, echo_xy, &string ) WORD vsm_string ( ); WORD handle; WORD max_length; WORD echo_mode; WORD echo_xy[2]; BYTE string[max_length+l]; WORD status; handle = device handle max_length = intin[0] echo_mode = intin[l] echo_xy - ptsin[0-l] string = intout status = contrl[4] 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 GEM VDI Programmer's Guide Set Mouse Form 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. Is in the mask cause the corresponding pixel to be set to the color index defined in intin(3). 3. Is in the mouse form data cause the corresponding pixel to be set to the color index defined in intin(4). Input Contrl(O) Contrl(l) Contr1(3) Contr1(6) Opcode = 111. Number of input vertices = 0. Length of intin array = 37. Device Handle. intin(O) intin(l) intin(2) intin(3) intin(4) intin(5-20) - intin(21-36)- x-coordinate of hot spot, y-coordinate of hot spot. Reserved for future use, must be 1 . Mask color index, normally 0. Data color index, normally 1. 16 words of 16-bit cursor mask. 16 words of 16-bit cursor data. Output Contr 1(2) — Number of output vertices = 0. Contr 1(4) — Length of intout array = 0. 7-19 GEM VDI Programmer's Guide Set Mouse Form C BINDING Procedure Name vsc_form( handle, pcur_form ) Data Types WORD vsc_form ( ); WORD handle? WORD pcur_form[37]; Input Arguments handle = contrl[6] pcur_form[0] = intin[0] pcur_form[36] = intin[36] 7-20 GEM VDI Programmer's Guide Exchange Timer Interrupt Vector EXCHANGE TIMER 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(lO). The application-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) — contrl(l) — contrl(3) contrl(6) contrl(7-8) — Opcode = 118. Number of input vertices = 0. Length of intin array = 0. Device handle. Address of application timer routine. Output contrl(2) contrl(4) contrl(9-10 )- Number of output vertices = 0. Length of intout array = 1. Address of the old timer routine. intout(O) — Milliseconds per tick. 7-21 GEM VDI Programmer's Guide Exchange Timer Interrupt Vector C BINDING Procedure Name Data Types Input Arguments Output Arguments vex_timv( handle, &tim conv ) tim addr, ot WORD vex_timv( ); WORD handle; WORD *tim__addr; WORD *otim_addr; WORD tim conv; handle = contrl[6] tim addr = contrl[7-8] otim_addr = contrl[9-10] tim conv = intout[0] im_addr. 7-22 GEM VDI Programmer's Guide Show Cursor 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) — contrl(l) — contrl(3) — contrl(6) — Opcode = 122. Number of input vertices = 0. Length of intin array = 1. Device handle. intin(O) Reset flag. 0 = ignore number of Hide Cursor calls nonzero = normal Show Cursor functionality Output contrl(2) — contrl(4) — Number of output vertices = 0. Length of intout array = 0. 7-23 GEM VDI Programmer's Guide Show Cursor C BINDING Procedure Name Data Types v_show__c( handle, reset ) WORD v_show_c ( ); WORD handle; WORD reset Input Arguments handle = contrl[6] reset = intinCO] 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 contr1(0) contrl(l) contr1(3) contr1(6) Opcode = 123. Number of input vertices = 0. Length of intin array = 0. Device handle. Output contr1(2) — Number of output vertices = 0. contr1(4) — Length of intout array = 0. C BINDING Procedure Name v_hide_c( handle ) Data Types WORD v_hide_c ( )? WORD handle; Input Arguments handle = contr1[6] 7-25 GEM VDI Programmer's Guide Sample Mouse Button State SAMPLE MOUSE BUTTON STATE This function returns the current state of 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) — contrl(l) — contrl(3) — contrl(6) — Opcode = 124. Number of input vertices = 0. Length of intin array = 0. Device handle. Output contrl(2) — contrl(4) — Number of output vertices = 1. Length of intout array = 1. intout(O) — Mouse button state. ptsout(O) — ptsout(l) — x position of cursor in NDC/RC units. y position of cursor in NDC/RC units. C BINDING Procedure Name vq_mouse( handle, &pstatus, &x, &y ) Data Types WORD vq_mouse { ); WORD handle; WORD pstatus; WORD x, y; Input Arguments handle = contrl[6] Output Arguments pstatus = intout[0] x = ptsout[0] y = ptsoutCl] 7-26 GEM VDI Programmer's Guide Exchange Button Change Vector 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(lO) 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. Contr1(7-8) — Address of application mouse button state change routine. 7-27 GEM VDI Programmer's Guide Exchange Button Change Vector Output C BINDING Procedure Name Data Types Input Arguments Output Arguments 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. vex_butv( handle, pusrcode, psavcode ) WORD vex_butv ( ) ; WORD handle; WORD *pusrcode; WORD *psavcode; handle = contrl[6] pusrcode = contrl[7-8] psavcode = contrl[9-10] 7-28 GEM VDI Programmer's Guide Exchange Mouse Movement Vector EXCHANGE MOUSE This function allows the application to MOVEMENT VECTOR perform some action each time the mouse moves to a new location. The application receives 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 contr1(10). When the mouse moves, the application-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. 7-29 GEM VDI Programmer's Guide Exchange Mouse Movement Vector 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 handle; WORD *pusrcode; WORD *psavcode; Input Arguments handle = contrl[6] pusrcode = contrl[7-8] Output Arguments psavcode = contrl[9-10] 7-30 GEM VDI Programmer's Guide Exchange Cursor Change Vector EXCHANGE CURSOR CHANGE VECTOR This function allows the application to 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(lO). 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(lO). 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-specific instructions and register names. 7-31 GEM VDI Programmer's Guide Exchange Cursor Change Vector Input contrl{0) — contrl(l) — contrl(3) — contrl(6) — contrl(7-8) — Opcode = 127. Number of input vertices = 0. Length of intin array = 0. Device handle. Address of application cursor draw routine. Output contrl(2) — contrl(4) — contrl(9-10) - Number of output vertices = 0. Length of intout array = 0. 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[6] pusrcode = contrl[7-8] Output Arguments psavcode = contrl[9-10] 7-32 GEM VDI Programmer's Guide Sample Keyboard State Information SAMPLE KEYBOARD STATE INFORMATION This function returns the current state of 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 contrl(O) — contrl(l) — contrl(3) — contrl(6) — Opcode = 128. Number of input vertices = 0. Length of intin array = 0. Device handle. Output contrl(2) — contrl(4) — Number of output vertices = 0. Length of intout array = 1. intout(O) — Keyboard state. C BINDING Procedure Name Data Types Input Arguments vq_key_s( handle, &pstatus ) WORD vq_key_s ( ); WORD handle; WORD pstatus; handle = contrl[6] Output Arguments pstatus = intout[0] End of Section 7 7-33 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(0) contrl(1) contrl(3) contrl(6) Opcode = 102. Number of input vertices = 0. Length of intin array = 1. 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) — contrl(4) — intout(O) — intout(l) — intout(2) — intout(3) — intout(4) — intout(5) — intout(6) — intout(7) — intout(8) — Number of output vertices = 6. Length of intout array = 45. Type of screen. 0 — not screen 1 — 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 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). Text effects supported. (See "Set Graphic Text Special Effects" in Section 5 for values.) Scale rasters. 0 = scaling not possible 1 = scaling possible Number of planes. Lookup table supported. 0 = table supported 1 = table not supported Performance factor, number of 16 x 16 pixel raster ops per second. Contour fill capability. Character rotation ability. 0 = none 1 = 90-degree increments only 2 = arbitrary angles 8-2 GEM VDI Programmer's Guide Extended Inquire intout(9) — intout(lO)— intout(ll) — intout(12) — intout(13) — intout(14)— intout(l5)— intout(16)— intout(17)— intout(18)— intout(19-44) ptsout(0-11) Number of writing modes available. Highest level of input mode available. 0 = none 1 = request 2 = sample Text alignment capability flag. 0 = no 1 = yes Inking capability flag. 0 = device cannot ink 1 = device can ink Rubberbanding capability flag. 0 = no 1 = capable of rubberband lines 2 = capable of both rubberband lines and rectangles Maximum vertices for Polyline, Polymarker, or Filled Area. -1 = no maximum Maximum intin. -1 = no maximum Number of keys available on the mou se. Styles for wide lines. 0 = no 1 = yes Writing modes for wide lines. Reserved, contains zeros. Reserved, contains zeros. 8-3 GEM VDI Programmer's Guide Extended Inquire C BINDING Procedure Name vq_extnd( handle, owflag, work_out ) Data Types WORD vq_extnd ( ); WORD handle; WORD owflag; WORD work out[57] Input Arguments handle = contrl[6] owflag = intin[0] Output Arguments work_out[0] = intout[0] work_out[44] = intout[44] work_out[45] = ptsoutCO] work_out[56] = ptsout[ll] 8-4 GEM VDI Programmer's Guide Inquire Color Representation INQUIRE COLOR REPRESENTATION This function returns either the requested or 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) — contrl(l) — contrl(3) — contrl(6) — Opcode = 26. Number of input vertices = 0. Length of intin array = 2. Device handle. intin(O) intin(l) Requested color index. Set or realized flag. 0 = set ( return color values requested) 1 = realized (return color values realized on device) Output contrl(2) — contrl(4) — Number of output vertices = 0. Length of intout array = 4. intout(O) — intout(1) — intout(2) — intout(3) — Color index. Red intensity (in tenths of percent 0-1000). Green intensity. Blue intensity. 8-5 GEM VDI Programmer's Guide Inquire Color Representation C BINDING Procedure Name Data Types Input Arguments Output Arguments vq_color( handle, color_index, set_flag, rgb ) WORD vq_color ( ); WORD handle? WORD color_index? WORD set_flag; WORD rgb[3]; handle = contrl[6] color__index = intin[0] set_flag = intin[l] rgb[0] = intout[l] rgb[l] = intout[2] rgb[2] = intout[3] 8-6 GEM VDI Programmer's Guide Inquire Polyline Attributes INQUIRE CURRENT POLYLINE ATTRIBUTES This function reports the current setting of all attributes that affect polylines, such as line type, line color, line width, end styles, and writing mode. Input contrl(O) — contrl(l) — contrl(3) — contrl(6) — Opcode Number Length Device = 35. of input vertices = 0. of intin array = 0. handle. Output contrl(2) — contrl(4) — intout(O) — intout(1) — intout(2) — intout(3) — intout(4) — ptsout(O) — ptsout(l) — Number of output vertices = 1. Length of intout array = 5. Current polyline line type. (Refer to Set Polyline Line Type function.) Current polyline line color index. Current writing mode. (Refer to the Set Writing Mode function. ) End style for beginning point of polyline. End style for ending point of polyline. Current line width, in current coordinate system. 0 . 8-7 GEM VDI Programmer's Guide Inquire Polyline Attributes C BINDING Procedure Name Data Types Input Arguments Output Arguments vql_attributes( handle. WORD vql_attributes ( ) WORD handle? WORD attrib[4]; handle = contrl[6] attribCO] = intoutCO] attrib[l] = intout[l] attrib[2] = intout[2] attrib[3] = ptsout[0] attrib ) 8-8 GEM VDI Programmer's Guide Inquire Polymarker Attributes 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(1) — 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. 8-9 GEM VDI Programmer's Guide Inquire Polymarker Attributes C BINDING Procedure Name Data Types Input Arguments Output Arguments vqm_attributes( handle. WORD vqm_attributes ( ) WORD handle; WORD attrib[4]; handle = contrl[6] attrib[0] = intoutCO] attrib[l] = intoutCl] attrib[2] = intout[2] attrib[3] = ptsoutCl] attrib ) 8-10 GEM VDI Programmer's Guide Inquire Fill Area Attributes INQUIRE CURRENT FILL AREA ATTRIBUTES This function reports the current setting of all attributes that affect fill areas, such 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 contr1(4) contrl(6) intout(0) intout(1) intout(2) intout(3) intout(4) Number of output vertices = 0. Length of intout array = 5. Current fill area interior style. (Refer to Set Fill Interior Style function.) Current fill area color index. Current fill area style index. (Refer to Set Fill Style Index function.) Current writing mode. (Refer to the Set Writing Mode function. ) Current fill perimeter status. 8-11 GEM VDI Programmer's Guide Inquire Fill Area Attributes C BINDING Procedure Name Data Types Input Arguments Output Arguments vqf_attributes( handle, attrib ) WORD vqf_attributes( ); WORD handle? WORD attrib[4]; handle = contrl[6] attribCO] attrib[l] attrib[2] attrib[3] intout[0] intout[1] intout[2] intoutE 3] 8-12 GEM VDI Programmer's Guide Inquire Graphic Text Attributes INQUIRE CURRENT GRAPHIC TEXT ATTRIBUTES This function returns the current setting of all attributes that affect graphic text, such as text size, text color, text face alignment, baseline rotation, and writing mode. Input contrl(0) contrl(l) contrl(3) contrl(6) Opcode = 38. Number of input vertices = 0. Length of intin array = 0. Device handle. Output contr1(2) contrl(4) intout( 0) intout(1) intout(2) intout(3) intout(4) intout(5) ptsout(0) ptsout (1) ptsout(2) ptsout(3) Number of output vertices = 2. Length of intout = 6. Current graphic text face. Current graphic text color index. Current angle of rotation of text baseline ( in tenths of degrees 0-3600). Current horizontal alignment. (Refer to Set Graphic Text Alignment function.) Current vertical alignment. (Refer to Set Graphic Text Alignment function.) Current writing mode. (Refer to the Set Writing Mode function.) Current character width in current coordinate system. Current character height in current coordinate system. Current character cell width in current coordinate system. Current character cell height in current coordinate system. 8-13 GEM VDI Programmer's Guide Inquire Graphic Text Attributes C BINDING Procedure Name Data Types Input Arguments Output Arguments vqt_attributes( handle, attrib ) WORD vqt_attributes ( ); WORD handle; WORD attrib[10]; handle = contrl[6] attrib[0] = intout[0] attrib[l] = intout[l] attrib[5] = intout[5] attrib[6] = ptsout[0] attrib[9] ptsout[3] 8-14 GEM VDI Programmer's Guide Inquire Text Extent INQUIRE EXTENT Input TEXT This function returns a rectangle that encloses the requested string. The coordinates of the vertices are given relative to 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. Figure 8—1. Inquire Text Extent Function contrl(0) contrl(l) contr1(3) contrl(6) Opcode = 116. Number of input vertices = 0. Number of words in text. Device handle. intin Character string in current character set. 8-15 GEM VDI Programmer's Guide Inquire Text Extent Output C BINDING Procedure Name Data Types Input Arguments Output Arguments contrl(2) — Number of output vertices = 4. contrl(4) — Length of intout array = 0. ptsout(O) — ptsout(l) — ptsout(2) — ptsout(3) — ptsout(4) — ptsout(5) — ptsout(6) — ptsout(7) — delta-x for point 1 of the s t r i n g i n the current coordinate system. delta-y for point 1 of the s t r i n g i n the current coordinate system. delta-x for point 2 of the s t r i n g i n the current coordinate system. delta-y for point 2 of the s t r i n g i n the current coordinate system. delta-x for point 3 of the s t r i n g i n the current coordinate system. delta-y for point 3 of the string i n the current coordinate system. delta-x for point 4 of the s t r i n g i n the current coordinate system. delta-y for point 4 of the s t r i n g i n the current coordinate system. vqt_extent( handle, string, extent ) WORD vqt_extent( ); WORD handle; WORD extent[8D; BYTE stringC]; handle = contrl[6] string = intin extent[0] = ptsout[0] extent[7] = ptsout[7] 8-16 GEM VDI Programmer's Guide Inquire Character Cell Width INQUIRE CHARACTER CELL WIDTH Input This function returns the character cell 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. Lett Character Alignment Delta Right Character Alignment Delta ' * ‘ ' * ' _ 1 m 1 1 ■ Character Width Cell Height Cell Width Figure 8-2. Character Cell Definition contrl(0) contr1(1) contr1(3) contr1(6) Opcode = 117. Number of input vertices = 0. Length of intin array = 1. Device handle. intin(0) Character value in current character set in ADE format. 8-17 GEM VDI Programmer's Guide Inquire Character Cell Width Output C BINDING Procedure Name Data Types Input Arguments Output Arguments contrl(2) — Number of output vertices = 3. contrl(4) — Length of intout array = 1. intout(O) — ptsout(O) — ptsout(l) — ptsout(2) — ptsout(3) — ptsout(4) — ptsout(5) — ADE value of the character being inquired on; -1 if an invalid character (status). Cell width of the character in the current coordinate system. 0 . Left character alignment delta. 0 . Right character alignment delta. 0 . status = vqt_width( handle, character, &cell_width, &left_delta, &right_delta ) WORD status; WORD vqt_width( ); WORD handle; BYTE character; WORD cell_width; WORD left_delta; WORD right_delta; handle = contrl[6] character = intin[0] status = intout[0] cell_width = ptsout[0] left_delta = ptsout[2] right_delta = ptsout[4] 8-18 GEM VDI programmer's Guide Inquire Face Name and Index INQUIRE FACE NAME 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( 1. . . 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 Nanes and Styles Face Name Styles Swiss 721 Light Swiss 721 Thin Italic Dutch 801 Roman Du tch 801 Bold Italic Input contrl(0) contrl(l) contrl(3) contrl(6) Opcode = 130. Number of input vertices = 0. Length of intin array = 1. Device handle. intin(0) Element number. Output contrl(2) — Number of output vertices = 0 contrl(4) — Length of intout array = 33. intout(O) — ID number. intout(1) to intout(32) - 32 ADE. 8-19 GEM VDI programmer’s Guide Inquire Face Name and Index C BINDING Procedure Name Data Types Input Arguments Output Arguments index = vqt_name( handle, element_num, name ) WORD index; WORD vqt_name( ); WORD handle; WORD element num, BYTE name[32T; handle = contr[6] element num = intin[0] index = intoutCO] name[0] = intout[l] nameC 31] intout[32] 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 GEM VDI Programmer's Guide Inquire Current Face Information INQUIRE CURRENT This function returns size information for FACE INFORMATION 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 Figure 8-3. Right and Left Offset Input contr1(0) contrl(1) contrl(3) contrl(6) Opcode = 131. Number of input vertices = 0. Length of intin array = 0. Device handle. Output contrl(2) — contrl(4) — intout(O) — intout(l) — ptsout(O) — ptsout(l) — ptsout(2) — Number of output vertices = 5. Length of output array = 2. Minimum ADE (ASCII Decimal Equivalent) the first character in this face. Maximum ADE, the last character in this face. Maximum cell width not including special effects. Bottom line distance relative to baseline. Special effects delta x. The current special effects increase character width by this amount. GEM VDI Programmer's Guide Inquire Current Face Information C BINDING Procedure Name Data Types Input Arguments Output Arguments ptsout(4) — Left offset; (see Figure 8 -2) positive value relative position. to ptsout(5) — Half distance relative baseline. to ptsout(6) — Right offset (see Figure 8- 2). ptsout(7) — Ascent distance relative baseline. to ptsout(8) — 0 . ptsout(9) — Top distance relative baseline. to vqt_fontinfo( distances. handle, &minADE, SmaxADE, &maxwidth, effects ) WORD vqt_fontinfo( ); WORD handle; WORD minADE; WORD maxADE; WORD distances[5] ; WORD maxwidth? WORD effects[3]? handle = contrl[6] minADE = intout[0] maxADE = intout[l] distances[0] = ptsout[l] distances[l] = ptsout[3] distances[2] = ptsout[5] distances[3] = ptsout[7] distances[4] = ptsout[9] maxwidth = ptsout[0] effects[0] = ptsout[2] effects[l] = ptsout[4] effectsC2] = ptsout[6] 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 downwa rd. Note: This function is not required and may not be available on all devices. Input contrl(O) — contrl(l) — contrl(3) — contrl(6) — contrl(7) — contrl(8) — ptsin(O) ptsin(l) — ptsin(2) ptsin(3) Opcode = 27. Number of input vertices = 2. Length of intin array = 0. Device handle. Length of each row in color index array. Number of rows in color index array. x-coordinate of lower left corner in current coordinate system. y-coordinate of lower left corner in current coordinate system. x-coordinate of upper right corner in current coordinate system. y-coordinate of upper right corner in current coordinate system. Output contrl(2) contrl(4) contrl(9) contrl(lO) — contrl(ll) — Number of output vertices = 0. Length of the color index array, same as contrl(3). Number of elements used in each row of color index array. Number of rows used in color index array. Invalid value flag. 0 — if no errors 1 — if a color value could not be determined for some pixel 8-23 GEM VDI Programmer's Guide Inquire Cell Array C BINDING Procedure Name Data Types Input Arguments Output Arguments intout — Color index array, stored one row at time. -1 — indicates that a color index could not be determined for that particular pixel vq__cellarray( handle, pxyarray, row_length, num_rows, &el_used, &rows_used, &status, colarray ) WORD vq_cellarray( ); WORD handle? WORD pxyarray[4]; WORD row_length; WORD num_rows? WORD el_used; WORD rows_used; WORD status; WORD colarrayCn]; handle = contrl[6] pxyarray[0] = ptsin[0] pxyarrayCl] = ptsin[l] pxyarrayC2] = ptsin[2] pxyarray[3] = ptsin[3] row_length = contrl[73 num_rows = contrl[8] el_used = contrl[9] rows_used = contrl[10] status = contrl[ll] colarrayCO] = intout[0] colarrayCn] = intin[n] 8-24 GEM VDI Programmer's Guide Inquire Input Mode INQUIRE INPUT MODE This function returns the current input mode for the specified logical input device: locator, valuator, choice, and string. Input contrl(O) — contrl(l) — contrl(3) — contrl(6) — Opcode = 115. Number of input vertices = 0. Length of intin array = 1. Device handle. intin(O) Logical input device. 1 = locator 2 = valuator 3 = choice 4 = string Output contrl(2) — contrl(4) — Number of output vertices = 0. Length of intout array = 1. intout(0) — Input mode. 1 = 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[0] Output Arguments inputmode = intout[0] End of Section 8 8-25 Section 9 Escapes ESCAPE Input 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. contrl(0) contrl(l) contrl( 3) contrl{5) contr1{6) Opcode = 5. Number of input vertices. Number of input parameters. Function identifier (id). Device 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 ON 9-1 GEM VDI Programmer's Guide Escapes Table 9-1. (continued) Number Description 14 REVERSE VIDEO OFF 15 INQUIRE CURRENT ALPHA CURSOR ADDRESS 16 INQUIRE TABLET STATUS 17 HARD COPY 18 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 GEM VDI Programmer's Guide Escapes 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 GEM VDI Programmer's Guide Inquire Addressable Character Cells ESCAPE Is INQUIRE ADDRESSABLE ALPHA CHARACTER CELLS This escape returns information to the calling program about the number of vertical (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) — contrl(l) — contrl(3) — contrl(5) — contrl(6) — Opcode = 5. Number of input vertices = 0. Length of intin array = 0. Function id = 1. Device handle. Output contrl(2) — contrl(4) — Number of output vertices = 0. Length of intout array = 2. intout(O) — intout(1) — Number of addressable rows on the screen, (-1 indicates cursor addressing not possible). Number of addressable columns on the screen, (-1 indicates cursor addressing not possible). C BINDING Procedure Name Data Types Input Arguments Output Arguments vq_chcells( handle, &rows, Scolumns ) WORD vq_chcells ( ); WORD handle; WORD rows; WORD columns; handle = contrl[6] rows = intout[0] columns = intout[l] 9-4 GEM VDI Programmer’s Guide Exit Alpha Mode ESCAPE 2 s 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(0) contrl(l) contrl(3) contrl(5) contrl(6) Opcode = 5. Number of input vertices = 0. Length of intin array = 0. Function id = 2. 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[6] 9-5 GEM VDI Programmer's Guide Enter Alpha Mode ESCAPE 3: ENTER ALPHA MODE This escape causes the graphics device to 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(0) contrl(1) contrl( 3) contrl(5) contr1( 6) Opcode = 5. Number of input vertices = 0. — Length of intin array = 0. Function id = 3. — Device handle. Output contrl (2) contrl(4) Number of output vertices = 0. Length of intout array = 0. C BINDING Procedure Name v enter cur( handle ) Data Types WORD v_enter_cur ( ) WORD handle; Input Arguments handle = contrl[6] 9-6 GEM VDI Programmer's Guide Alpha Cursor Up ESCAPE 4: ALPHA CURSOR UP This escape moves the alpha cursor up one row without altering its horizontal position. If the cursor is already at the top margin, nothing happens. Input contrl(O) — contrl(l) — contrl(3) — contrl(5) — contrl(6) — Opcode = 5. Number of input vertices = 0. Length of intin array = 0. Function id = 4. Device handle. Output contrl(2) — contrl(4) — Number of output vertices = 0. Length of intout array = 0. C BINDING Procedure Name v_curup( handle ) Data Types WORD v curup WORD handle; ( ); Input Arguments handle = contrl[6] 9-7 GEM VDI Programmer's Guide Alpha Cu r sor Down ESCAPE 5: ALPHA CURSOR DOWN This escape moves the alpha cursor down one row without altering its horizontal position. If the cursor is already at the bottom 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 = 5. contrl(6) — Device handle. Output contrl(2) — Number of output vertices = 0. contrl(4) — Length of intout array = 0. C BINDING Procedure Name v_curdown( handle ) Data Types WORD v curdown ( ); WORD handle; Input Arguments handle = contrl[6] GEM VDI Programmer 1 s Guide Alpha Cursor Right ESCAPE 6: ALPHA CURSOR RIGHT The Alpha Cursor Right escape moves the alpha cursor right one column without altering its vertical position. If the cursor is already at the right margin, nothing happens. Input contrl(0) contrl(l) contrl(3) contrl(5) contrl(6) Opcode = 5. Number of input vertices = 0. Length of intin array = 0. Function id = 6. Device handle. Output contrl( 2) contr1(4) Number of output vertices = 0. Length of intout array = 0. C BINDING Procedure Name v_curright( handle ) Data Types WORD v_curright ( ); WORD handle? Input Arguments handle = contrl[6] GEM VDI Programmer's Guide Alpha Cursor Left ESCAPE 7: ALPHA CURSOR LEFT The Alpha Cursor Left escape moves the alpha cursor left one column without altering its vertical position. If the cursor is already at the left margin, nothing happens. Input contrl( 0) contrl(l) contrl(3) contrl(5) contrl(6) Opcode = 5. Number of input vertices = 0. Length of intin array = 0. Function id = 7. Device handle. Output contr1(2) contr1(4) Number of output vertices = 0. Length of intout array = 0. C BINDING Procedure Name v_curleft( handle ) Data Types WORD v_curleft ( ); WORD handle; Input Arguments handle = contrl[6] 9-10 GEM VDI Programmer's Guide Home Alpha Cursor ESCAPE 8s HOME ALPHA CURSOR This escape moves the alpha cursor to the home position, usually the upper left character cell of the display device. Input contrl(O) — contrl(l) — contrl(3) — contrl(5) — contrl(6) — Opcode = 5. Number of input vertices = 0. Length of intin array = 0. Function id = 8. Device handle. Output contrl(2) — contrl(4) — Number of output vertices = 0. Length of intout array = 0. C BINDING Procedure Name v_curhome( handle ) Data Types WORD v curhome WORD handle; ( ); Input Arguments handle = contrl[6] 9-11 GEM VDI Programmer's Guide Erase to End of Alpha Screen ESCAPE 9 s ERASE TO END OF ALPHA SCREEN This escape erases the display surface from the current alpha cursor position to the end 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 handle; Input Arguments handle = contrl[6] 9-12 GEM VDI Programmer's Guide Erase to End of Alpha Text Line ESCAPE 10: ERASE TO END OF ALPHA TEXT LINE This escape erases the display surface from the current alpha cursor position to the end of the current alpha text line. The current alpha cursor location does not change. Input contrl(O) — contrl(l) — contrl{3) — contrl(5) — contrl(6) — Opcode = 5. Number of input vertices = 0. Length of intin array = 0. Function id = 10. Device handle. Output contrl(2) — contrl(4) — Number of output vertices = 0. Length of intout array = 0. C BINDING Procedure Name Data Types Input Arguments v_eeol( handle ) WORD v_eeol ( ) ; WORD handle; handle = contrlL6] 9-13 GEM VDI Programmer’s Guide Direct Alpha Cursor Address ESCAPE 11s DIRECT ALPHA CURSOR ADDRESS The Direct Alpha Cursor Address escape moves the alpha cursor directly to the specified 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 BINDING Procedure Name vs_curaddress( handle, row, column ) Data Types WORD vs__curaddress ( ) ; WORD handle; WORD row; WORD column; Input Arguments handle = contrl[6] row = intin[0] column = intin[l] 9-14 GEM VDI Programmer's Guide Output Cursor Addressable Alpha Text ESCAPE 12: OUTPUT CURSOR ADDRESSABLE ALPHA TEXT This escape displays a string of alpha text starting at the current cursor position. 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 in 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 stringC]; Input Arguments handle = contrl[6] 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: REVERSE VIDEO ON This escape displays text in reverse video. all subsequent alpha Input contrl(O) — contrl(l) — contrl(3) — contrl(5) — contrl(6) — Opcode = 5. Number of input vertices = 0. Length of intin array = 0. Function id = 13. Device handle. Output contrl(2) — contrl(4) — Number Length of output vertices = 0. of intout array = 0. C BINDING Procedure Name Data Types Input Arguments v_rvon( handle ) WORD r_von ( ); WORD handle; handle = contrl[6] 9-16 GEM VDI Programmer's Guide Reverse Video Off ESCAPE 14: REVERSE VIDEO OFF This escape displays all subsequent alpha text in normal video format. Input contrl(O) — contrl(l) — contr 1(3) — contrl(5) — contrl(6) — Opcode = 5. Number of input vertices = 0. Length of intin array = 0. Function id = 14. Device handle. Output contrl(2) — contrl(4) — Number of output vertices = 0. Length of intout array = 0. C BINDING Procedure Name v_rvoff( handle ) Data Types WORD v_rvoff ( ); WORD handle; Input Arguments handle = contrl[6l 9-17 GEM VDI Programmer's Guide Inquire Current Alpha Cursor Address ESCAPE 15: INQUIRE CURRENT ALPHA CURSOR ADDRESS This escape returns the current position of the alpha cursor in row, column coordinates. Input contrl(0) _ Opcode = 5. contrl(1) — Number of input vertices = 0. contrl( 3) — Length of intin array = 0. contrl(5) — Function id = 15. contr 1{ 6) Device handle. Output contrl(2) _ Number of output vertices = 0. contrl(4) — Length of intout array = 2. intout(0) — Row number (1 to the maximum number of rows). intout (1 ) Column number (1 to the maximum number of columns) . C BINDING Procedure Name Data Types Input Arguments vq_curaddress( handle, &row, &column ) WORD vq curaddress ( ); WORD handle; WORD row; WORD handle; handle = contrl[6] Output Arguments row = intout[0] column = intout[l] 9-18 GEM VDI Programmer's Guide Inquire Tablet Status ESCAPE 16: INQUIRE TABLET STATUS This escape of a graphics other similar returns the availability status tablet, mouse, joystick, or device. Input contrl(O) — contrl(l) — contrl(3) — contrl(5) — contrl(6) — Opcode = 5. Number of input vertices = 0. Length of intin array = 0. Function id = 16. Device handle. Output contrl(2) — contrl(4) — intout(O) — Number of output vertices = 0. Length of intout array = 1. 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[6] Output Arguments status = intoutCO] 9-19 GEM VDI Programmer' 1 s Guide Hard Copy ESCAPE 17s HARD COPY The device generates a hard copy with this escape. The escape is device-specific and copies the physical screen to a printer or other attached hard copy device. Input contrl(O) — contrl(l) — contrl(3) — contrl(5) — contrl(6) — Opcode = 5. Number of input vertices = 0. Length of intin array = 0. Function id = 17. Device handle. Output contrl(2) — contrl(4) — Number of output vertices = 0. Length of intout array = 0. C BINDING Procedure Name v_hardcopy( handle ) Data Types WORD v_hardcopy ( ); WORD handle; Input Arguments handle = contrl[6] 9-20 GEM VDI Programmer's Guide Place Graphic Cursor at Location 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[6] x = ptsin[0] y = ptsin[l] 9-21 GEM VDI Programmer's Guide Remove Last Graphic Cursor ESCAPE 19: REMOVE This escape removes the last graphic cursor LAST GRAPHIC placed on the screen. CURSOR Input contrl(O) contrl(1) contrl(3) contrl(5) contrl(6) Opcode = 5. Number of input vertices = 0. Length of intin array = 0. Function id = 19. Device handle. Output contrl(2) — Number of output vertices = 0. contrl(4) — Length of intout array = 0. C BINDING Procedure Name v rmcur( handle ) Data Types WORD v_rmcur ( ); WORD handle; Input Arguments handle = contrl[6] 9-22 GEM VDI Programmer's Guide Form Advance ESCAPE 20: FORM ADVANCE This escape is required only for printers. 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. Output 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 handle; Input Arguments handle = contrl[6] 9-23 GEM VDI Programmer's Guide Output Window ESCAPE 21: OUTPUT This escape is required only for printers. WINDOW 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) contrl(l) contrl(3) contrl(5) contr1{ 6) ptsin(0) ptsin(l) ptsin(2) ptsin(3) Opcode = 5. Number of input vertices = 2. Length of intin array = 0. Function id = 21. Device handle. x-coordinate of corner of window to be output in NDC/RC. y-coordinate of corner of window to be output in NDC/RC. x-coordinate of corner of window, diagonally opposite corner selected in ptsin(O), in NDC/RC. y-coordinate of corner of window, diagonally opposite corner selected inptsin(l), in NDC/RC. Output contrl(2) contrl(4) Number of output Length of intout vertices = array = 0. 0 . 9-24 GEM VDI Programmer’s Guide Output Window C BINDING Procedure Name v_output_window( handle, xyarray ) Data Types WORD v_output_window( ); WORD handle; WORD xyarray[4]; Input Arguments handle = contrl[6] xyarray[0] = ptsin[0] xyarray[3] = ptsin[3] 9-25 GEM VDI Programmer's Guide Clear Display List ESCAPE 22i CLEAR DISPLAY LIST This escape is required only for printers. 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 BINDING Procedure Name v_clear_disp_list( handle ) Data Types WORD v clear disp list( ); WORD handle; Input Arguments handle = contrl[6] 9-26 GEM VDI Programmer's Guide Output Bit Image File 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 three 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 defined in the bit image file. 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 fit the corresponding 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 GEM VDI Programmer's Guide Output Bit Image File 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 contr 1(0) — contrl(l) — contrl(3) — contrl{5) — contrl(6) — intin(O) intin(l) intin(2) intin(3) intin(4) intin(5) intin (n+4) — Opcode = 5. Number of input vertices = 2. Length of intin array = length of filename + 5. Function id = 23. Device handle. Aspect ratio flag. 0 = ignore aspect ratio 1 = honor pixel aspect ratio Scaling for x-axis. 0 = fractional scaling 1 = integer scaling Scaling for y-axis. 0 = fractional scaling 1 = integer scaling Horizontal alignment. 0 = left 1 = center 2 = right Vertical alignment. 0 = top 1 = middle 2 = bottom First character of filename. Last (nth) character of filename. 9-28 GEM VDI Programmer's Guide Output Bit Image File 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_image(); 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 + 1] aspect = intin[0] x_scale = intin[l] y_scale = intin[2] h_align = intin[3] v_align = intin[4] xyarray[0] = ptsin[0] xyarray[l] = ptsin[l] xyarray[2] = ptsin[2] xyarray[3] = ptsin[3] Note: Bytes for the filename array are mapped into the corresponding eight least significant bits of intin. The string must be null- terminated . 9-29 GEM VDI Programmer's Guide Select Palette ESCAPE 60: PALETTE SELECT This escape palette on screen. allows the selection of the the IBM® medium-resolution color Input contrl(O) — contrl(l) — contrl(3) — contrl(5) — contrl(6) — Opcode = 5. Number of input vertices = 0. Length of input array = 1. Function id = 60. Device handle. intin(O) Color selection. 0 = use red, green, brown palette (default) 1 = use cyan, magenta, white palette Output contrl(2) — contrl(4) — Number of output vertices = 0. Length of intout array = 1. intout(O) — Palette selected. C BINDING Procedure Name Data Types Input Arguments Output Arguments selected = vs__palette( handle, palette ) WORD vs_palette( ); WORD handle; WORD palette; handle = contrl[6] palette = intin[0] selected = intout[0] GEM VDI Programmer's Guide Polaroid Palette POLAROID® 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 (1...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 Film Types ESCAPE 91s INQUIRE PALETTE FILM TYPES This escape returns five strings that describe the films that the driver is 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) — contrl(l) — contrl(3) — contrl(5) — contrl(6) — Opcode = 5. Number of input vertices =0. Length of intin array = 0. Function id = 91. Device handle. Output contrl(2) — contrl(4) — Number of output vertices = 0. Length of intout = 125. intout — 5 sets of 25 ADE character strings. C BINDING Procedure Name Data Types Input Arguments Output Arguments vqp_films( handle, film_names ) WORD vqp_fi1ms( ); WORD handle; WORD film_names[1253; handle = contrl[6] film names = intout Note: Intout words (ADE) are converted to byte string. 9-32 GEM VDI Programmer's Guide Inquire Palette Driver State ESCAPE 92: INQUIRE PALETTE DRIVER STATE This escape returns a block of data that describes the current state of the driver. The state can be updated by changing this block and returning it to the driver with Escape 93. Input contrl(0) contrl(l) contrl(3) contrl(5) contrl(6) Opcode = 5. Number of input vertices = 0. Length of intin = 0. Function id = 92. Device handle. Output contrl(2) — contrl(4) — intout(O) — intout(l) — intout(2) — intout(3) — intout(4) — intout(5 to 20) Number of output vertices = 0. Length of intout array = 20. Port number. 0 = first comm port Film number (0...$). 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. Interlace flag. 0 = noninterlaced 1 = interlaced A noninterlaced picture requires slightly more than half the memory of an interlaced picture. Planes, a number (1...4) corresponding to number of colors (2 ...16 ). Two-character color codes for 8- color indices stored in ADE format. 9-33 GEM VDI Programmer's Guide Inquire Palette Driver State C BINDING Procedure Name Data Types Input Arguments Output Arguments vqp_state( handle, Sport, &film_name, Slightness, sinterlace, Splanes, Sindexes ) WORD vqp_state( ); WORD handle; WORD port; WORD film_name; WORD lightness; WORD interlace; WORD planes; WORD indexes[8][2]; handle = contrl[6] port = intoutCO] film_name = intoutCl] lightness = intout[2] interlace = intout[3] planes = intout[4] indexes = intout[5...20] 9-34 GEM VDI Programmer’s Guide Set Palette Driver State ESCAPE 93: SET PALETTE DRIVER STATE Input This escape moves a block of characteristics into the driver. Use this function after Escape 92. contrl(0) contrl(l) contrl(3) contrl(5) contrl(6) intin(O) i nt i n (1) intin(2) intin(3) intin(4) intin(5 to 20) Opcode = 5. Number of input vertices = 0. Length of intin array = 20. Function id = 93. Device handle. Port number. 0 = first comm port Film number (0...4). 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. Interlace flag. 0 = noninterlaced 1 = interlaced Planes (1 to 4), number corresponds to number of colors (2 to 16). Color codes for up to 16 colors. 9-35 GEM VDI Programmer's Guide Set Palette Driver State C BINDING Procedure Name Data Types Input Arguments vsp_state( handle, port, film_num, interlace, planes, indexes ) WORD vsp_style( ); WORD handle; WORD port; WORD film_num; WORD lightness, WORD interlace; WORD planes; WORD indexes[8][2]; handle = contrl[6] port = intinCO] film_num = intin[l] lightness = intin[2] interlace = intin[3] planes = intin[4] indexes = intin[5-20] lightness. 9-36 GEM VDI Programmer's Guide Save Palette Driver State ESCAPE 94: SAVE PALETTE DRIVER STATE This escape saves the current state of the driver to disk. The application can change the default film and index mapping with this escape. Input contrl(0) contrl(l) contrl(3) contrl(5) contrl(6) Opcode = 5. Number of input vertices = 0. Length of intin array = 0. Function id = 94. Device handle. Output contrl(2) — Number of output vertices = 0. contrl(4) — Length of intout array = 0. C BINDING Procedure Name vsp_save( handle ) Data Types WORD vsp_save( ); WORD handle; Input Arguments handle = contrl[6] GEM VDI Programmer's Guide Suppress Palette Messages ESCAPE 95: SUPPRESS PALETTE MESSAGES This escape allows the application to suppress the messages the palette driver 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(0) contrl(1) contrl(3) contrl(5) contrl(6) Opcode = 5. Number of input vertices = 0. Length of intin array = 0. — Function id = 95. Device handle. Output contrl(2 ) contrl(4) Number of output vertices = 0. — Length of output array = 0. C BINDING Procedure Name vsp_message( handle ) Data Types WORD vsp_message( ); WORD handle; Input Arguments handle = contrl[6] 9-38 GEM VDI Programmer's Guide Palette Error Inquire ESCAPE 96: PALETTE ERROR INQUIRE This escape returns an error code so the application can notify the user of a problem. 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) — contrl(l) — contrl(3) — contrl(5) — contrl(6) — Opcode = 5. Number of input vertices = 0. Length of intin array = 0. Function id = 96. Device handle. Output contrl(2) contrl(4) intout(0) Number of output vertices = 0. Length of intout array = 1. 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 GEM VDI Programmer's Guide Palette Error Inquire C BINDING Procedure Name status = vqp_error( handle ) Data Types WORD vqp_error( ); WORD handle; Output Arguments status = intout[0] Input Arguments handle = contrl[6] 9-40 GEM VDI Programmer's Guide Update Metafile Extents ESCAPE 98: UPDATE The values passed in the ptsin array are METAFILE 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) contrl(1) contr1(3) contrl(5) contrl(6) ptsin(0) ptsin(1) ptsin(2) ptsin(3) Opcode = 5. Number of input vertices = 2. Length of intin array =0. Function id = 98. Device handle. Minimum x value of the minimum bounding rectangle. Minimum y value of the minimum bounding rectangle. Maximum x value of the minimum bounding rectangle. Maximum y value of the minimum bounding rectangle. Output contrl(2) contrl(4) Number of Length of output vertices = intout array = 0. 9-41 GEM VDI Programmer's Guide Update Metafile Extents C BINDING Procedure Name Data Types Input Arguments v_meta_extents(handle, min_x, min_y, max_x, max y ) WORD v_meta_extents(); WORD handle, min_x, min_y, max_x, max y; handle = contrl[6]; min_x = ptsin[0]; min y = ptsinCl]; max_x = ptsin[2]; max_y = ptsin[3]; 9-42 GEM VDI Programmer's Guide Write Metafile Item ESCAPE 99: WRITE The parameters passed in the intin and ptsin METAFILE ITEM arrays are written to the metafile with an opcode defining the item as a user-defined metafile item. Intin (0) 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) — contrl(l) — contrl(3) — contrl(5) — contrl(6) — Opcode = 5. Number of input vertices. Length of intin array. Function id = 99. Device handle. intin intin(O) User-defined information. Sub-opcode. ptsin User-defined information. Output contrl(2) — contrl(4) — Number of output vertices = 0. Length of intout array = 0. C BINDING Procedure Name Data Types Input Arguments v_write_meta (handle, num__intin, intin, num_ptsin, ptsin) WORD v_write_meta(); WORD handle, num_intin, num_ptsin; WORD intin[num_intin], ptsin[num_ptsin]; handle = contrl[6]; num_intin = contrl[3]; num_ptsin = contrl[l]; intin = intin; ptsin = ptsin; 9-43 GEM VDI Programmer's Guide Change GEM VDI Filename This escape renames a metafile from GEMFILE.GEM to the specified name and 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 [1...74]. contrl(5) — Function id = 100. contrl(6) — Device handle. intin(0 to n) Path/filename. Output contrl(2) — Number of output vertices = 0. contrl(4) — Length of intout array = 0. C BINDING Procedure Name vm_filename( handle, filename ) Data Types WORD vm_filename( ); WORD handle; BYTE filename[ 3; Input Arguments handle = contrl[6] filename = intin[0-n] Note: The filename must be null-terminated. End of Section 9 ESCAPE 100: CHANGE GEM VDI FILENAME 9-44 Appendix A GEM VDI Error Messages 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 system has adequate memory to run GEM VDI, reboot your system. A-l GEM VDI Programmer's Guide GEM VDI Error Messages 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 1 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 GEM VDI Programmer's Guide GEM VDI Error 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: Re specify the path with the correct path name. ASSIGN.SYS file is eapty 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 ASSIGN.SYS File REQUIREMENTS 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 Nunbers Table B-l. Device Id Nunbers Type 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-l shows the ASSIGN.SYS file format: Device Id Driver Filename Face Name 01 SCREEN.SYS FACE1.FNT Figure B-l. ASSIGN.SYS File Format B-l GEM VDI Programmer's Guide Sample ASSIGN.SYS SAMPLE ASSIGN.SYS 21 printer, fnt /comments, if desired facel.fnt zfacel description face2.fnt ;face2 description face3.fnt ;face3 description 01 screen.fnt /comments, if desired face4.fnt zface4 description face5.fnt /face5 description 11 plotter.fnt /comments, if desired face6.fnt zface6 description face7.fnt zface7 description End of Appendix B Appendix C GEM VDI Metafile Format INTRODUCTION STANDARD METAFILE ITEM FORMAT The metafile driver outputs the information specified below and performs the described operations for the indicated opcodes. Most function requests passed to the metafile 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 1 2 3 4.. . n+4... contrl[0] contrlCl] contrl[3] contr1[5] ptsin[0-n] intin[0-m] opcode vertex count integer parameter count sub-opcode (or zero) vertices (if provided) 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 C-l GEM VDI Programmer's Guide GEM VDI Metafile Format NONSTANDARD METAFILE ITEMS 1 open workstation 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 The metafile file buffer is initialized and the metafile header is output to it. The workstation description values normally returned by an "open workstation" invocation are returned. C-2 GEM VDI Programmer's Guide GEM VDI Metafile Format Metafile header format: word description 0 Offffh 1 Length of header in words. 2 100*major version number + minor version number. 3 NDC/RC 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 undefined 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 GEM VDI Programmer’s Guide GEM VDI Metafile Format 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 1 Offffh SPECIAL METAFILE ESCAPES 5, 98 update metafile extents The extents information in the metafile header is updated to indicate the extents passed in the ptsin array. 5, 99 write metafile item escape A standard format metafile item is written. The first word of the intin array should 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 GEM VDI Programmer's Guide GEM VDI Metafile Format 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 C-5 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-l. GEM VDI Standard Keyboard Assignments High Byte Low Byte Cha racter 03 00 CNTL 2 (Nul) IE 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 0A CNTL J 25 0B CNTL K 26 OC CNTL L 32 0D CNTL M 31 0E CNTL N 18 OF CNTL O 19 10 CNTL P 10 11 CNTL Q 13 12 CNTL R IF 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 IB CNTL [ 2B 1C CNTL \ IB ID CNTL ] 07 IE CNTL 6 OC IF CNTL - 39 20 Space D-l GEM VDI Programmer's Guide Standard Keyboard Table D-l. (continued) High Byte Low Byte Character 02 21 ! 28 22 It 04 23 # 05 24 $ 06 25 % 08 26 Sc 28 27 ' 0A 28 ( OB 29 ) 09 2A * 0D 2B + 33 2C OC 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 7 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 I 24 4A J 25 4B K 26 4C L 32 4D M 31 4E N 18 4F O D-2 GEM VDI Programmer's Guide Standard Keyboard Table D-l. (continued) High Byte Low Byte Character 19 50 P 10 51 Q 13 52 R IF 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 \ IB 5D ] 07 5E A OC 5F Underscore 29 60 IE 61 a 30 62 b 2E 63 c 20 64 d 12 65 e 21 66 f 22 67 g 23 68 h 17 69 i 24 6A j 25 6B k 26 6C 1 32 6D m 31 6E n 18 6F o 19 70 P 10 71 q 13 72 r IF 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 IB 7D 29 7E 0E 7F Rubout (DEL) D-3 GEM VDI Programmer's Guide Standard Keyboard Table D-l. (continued) High Byte Low Byte 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 IF 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 FI 30 00 F2 3D 00 F3 3E 00 F4 3F 00 F5 40 00 F6 41 00 F7 42 00 F8 43 00 F9 44 00 F10 54 00 Fll D-4 GEM VDI Programmer's Guide Standard Keyboard Table D-l. (continued) High Byte Low Byte Character 55 00 F12 56 00 F13 57 00 F14 58 00 F15 59 00 F16 5A 00 F17 5B 00 F18 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 D-5 GEM VDI Programmer's Guide Standard Keyboard Table D-l. (continued) High Byte Low Byte 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 IB Escape 0E 08 Backspace 82 00 Alt - 83 00 Alt = 1C 0D CR 1C 0A 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 Appendix E Processor-Specific Data 8086-SPECIFIC DATA Registers and Interrupts Note: GEM VDI supports Concurrent™ operating systems that support DOS calls of versions 2.0 and above. The address of the Parameter Block is passed 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. Exchange Mouse For 8086-based 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 Change Vector For 8086-based processors, the application 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 GEM VDI Programmer's Guide 8086-specific Data Exchange Cursor Change Vector For 8086-based machines, the application- 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(lO) 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 Interrupt Vector For 8086-based processors, the application- dependent code is invoked with a CALL FAR (CALLF) instruction. When complete, the application should perform a RETURN FAR (RETF) instruction. E-2 GEM VDI Programmer's Guide 68000-specific Data 68000-SPECIFIC DATA Registers and The address of the Parameter Block is passed Interrupts in one 32-bit register, D0.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. E-3 GEM VDI Programmer's Guide 68000-specific Data Exchange Cursor Change Vector Exchange Timer Interrupt Vector For 68000-based machines, the application- 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 application-dependent 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(lO) 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. For 68000-based processors, the application- 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-l and F-2. Figure F-l 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. F-l GEM VDI Programmer's Guide Character Sets HFXA | DECIMALl Q 0 0 1 1 2 2 3 3 5 5 6 6 7 7 8 8 9 9 10 A 11 B 12 C 13 D 14 E 15 F 32 48 2 3 BLANK (SPACE) 0 ! • 1 2 # 3 $ 4 % 5 & 6 5 7 n 8 B 9 □B + • ? ? < = . > / • 5 6 7 P P A Q a q B R C S c s D T d E U e u F V f v G W g w H X h x I Y i y J Z K L \ M z k { m } n o A F-2 GEM VDI Programmer's Guide Character Sets 0 0 1 1 2 2 3 3 5 5 6 6 7 7 8 8 9 9 10 A 11 B 12 C 13 D 14 E 15 F e IO 160 176 A B f a a / i 6 / o 0 / u 0 n oe N CE a \ A o A • 6 i ■ ~n B y 2 + X A % « » TM a 0 ± > 7r < 0 ° 0 ft 5 § n <t> G F-3 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 (Intel® 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-l. G-l GEM VDI Programmer's Guide Font Header Table G-l. 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 func tion) 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 GEM VDI Programmer's Guide Font Header 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 set if default system font bit 1 set if horizontal offset tables 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 GEM VDI Programmer's Guide Character Offset Table CHARACTER OFFSET TABLE HORIZONTAL OFFSET TABLE The character offset table is used to index 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. The horizontal offset table is indexed by 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 Appendix H Reserved Metafile Sub-opcodes METAFILE SOB- 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 • 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 dev ice. 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) contrl(l) contr1(3) contrl(5) contr1(6) intin(0) intin(1) intin(2) Opcode = 5. Number of input vertices = 0. Length of intin array = 3. Function id = 99. Device handle. Sub-opcode number = 0. Page width in tenths of mi Hi me ter. Page height in tenths of millimeter. Output contr1(2) contr1(4) Number of output vertices = 0. Length of intout array = 0. 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(0) — Opcode = 5. contrl(l) — Number of input vertices = 0. contrl(3) — Length of intin array = 5. contrl(5) — Function id = 99. contrl(6) — Device handle. intin(0) 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) — contrl(4) — Number of output Length of intout vertices = array = 0. 0 . H-2 GEM VDI Programmer 1 s Guide Metafile Sub-opcodes with GEM Draw METAFILE SUB¬ OPCODES FOR USE WITH GEM DRAW The following sub-opcodes are reserved for use by the GEM Draw™ application. GEM VDI 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(0) contrl(l) contr1(3) contrl(5) contrl(6) Opcode = 5. Number of input vertices = 0. Length of intin array = 1. Function id = 99. Device handle. intin(0) Sub-opcode number = 10. Output contrl(2) contrl(4) Number of Length of output vertices = intout array = 0. 0 . H-3 GEM VDI Programmer's Guide End Group END GROUP This sub-function indicated the end of a group of primitives for the GEM Draw application. Input contrl(0 ) contrl(1 ) contrl( 3) contrl(5) contrl( 6) — Opcode = 5. — Number of input vertices = 0. Length of intin array = 1. Function id = 99. Device handle. intin(O) Sub-opcode number = 11. Output contr1( 2 ) contrl(4) Number of output vertices = 0. Length of intout array =0. SET MO LINE 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 contr1(0) contrl(l) contr1( 3 ) contrl(5) contrl{ 6 ) — Opcode = 5. — Number of input vertices =0. — Length of intin array = 1. — Function id = 99. — Device handle. intin(0 ) — Sub-opcode number = 49. Output contr1( 2) contr1( 4) — Number of output vertices = 0. — Length of intout array = 0. H-4 GEM VDI Programmer's Guide Set Attribute Shadow On 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 contr1(0) contrl(l) contrl(3) contrl(5) contrl(6) intin(0) Opcode = 5. Number of input vertices = 0. Length of intin array = 1. Function id = 99. Device handle. Sub-opcode number = 50. Output contr1(2) contrl(4) Number of Length of output vertices = intout array = 0. 0 . H-5 GEM VDI Programmer's Guide Set Attribute Shadow Off SET ATTRIBUTE SHADOW OFF This sub-function indicates to GEM Draw the 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(5) — 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(5) — 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 GEM VDI Programmer's Guide End Draw Area Type Primitive END DRAW AREA TYPE PRIMITIVE This sub-function indicates to GEM Draw the 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 Appendix I Bit Image File Format INTRODUCTION A GEM VDI bit image file is a file with extension .IMG and contains information which may be used to re-create a picture from its bit (pixel) image. The file consists of a header and raw pixel information. The pixel information may be encoded in a variety of formats. HEADER FORMAT The bit image file header consists of sixteen words. Each word is in machine-dependent format (for example, oriented with low byte first for Intel 808x processors or with high byte first for Motorola 68000 processors). Word Contents 0 1 2 3 4 5 6 7 8 9 upper left x of the bit image upper left y of the bit image lower right x of the bit image lower right y of the bit image source device page width source device page height source device pixel width in microns source device pixel height in microns bits per pixel 16 reserved for future use (zero) DATA FORMAT Pixel data may be encoded in any of four formats. All four formats may occur within the same bit image file. The four formats include: • run-length encoding • extended run-length encoding • raster encoding • raster-run encoding The data portion of the bit image file is encoded as bytes of information. 1-1 GEM VDI Programmer's Guide Data Format Each of the four formats except for run-length encoding (the default) consists of a single packet prefaced by an opcode. A run-length encoded packet has no preface opcode. Run-length Encoding This is the default pixel data format and requires no identifying opcode (i.e., when an extended run, a raster stream, or a raster-run stream ends, run-length encoding is in effect). A run-length packet consists of two bytes of information: a run length and a pixel value. The run length must be less than 128 and the pixel value must be less than 256. A run of pixels may wrap across lines. Run-length packet: byte 0 run length byte 1 pixel value Extended Run- length Encoding When a run is longer than 127 pixels, the extended run-length encoding may be used. An extended run includes a count of 128 pixel runs. For example, if a run exists which is 1000 pixels in length, it would be most efficient to encode it as an extended run of length seven (896 pixels) followed by a standard run of length 104. Extended run-length packet: byte 0 opcode = -1 byte 1 extended run length byte 2 pixel value 1-2 GEM VDI Programmer's Guide Extended Run-length Encoding Raster Encoding Data which is not efficiently encoded in any of the other formats may be raster-encoded. A raster stream is built which consists of packed pixel values. Pixel values are packed into bytes such that each pixel value occupies the number of bits indicated in the "bits per pixel" parameter of the file header and such that a pixel value packed into a higher order portion of the byte occurs before the adjacent lower order pixel value. Pixel values should be packed across byte boundaries when necessary. For example, assume that five pixels are to be encoded in raster format and that their pixel values are, respectively, one, two, three, four, and five. Assume that there are three bits per pixel. The resulting raster stream would be as follows: pixels: 12345 bits: 001 010 011 100 101 x byte 0 byte 1 The bit designated "x" may be either 0 or 1. Raster packet: byte 0 opcode = -2 byte 1 number of pixels in the stream byte 2 packed pixel values Raster-run encoding may be used to run- length encode groups of raster streams. For example, if a pattern of pixels repeats a number of times, the pattern may be packed into a raster stream (see "Raster Encoding" above) and a repeat count may be indicated. Raster-run packet: byte 0 opcode = -3 byte 1 pattern repeat count byte 2 number of pixels in the stream byte 3 packed pixel values End of Appendix I Raster-run Encoding 1-3 Glossary ASSIGN.SYS coordinate scaling coordinate systems default device driver device driver device handle device identification number 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. 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). Cartesian space in which points are defined. GEM VDI supports two systems: Normalized Device Coordinates (NDC) and Raster Coordinates (RC). First driver named in the ASSIGN.SYS file. It must be the largest driver that will be loaded during a graphics session. Device-dependent portion of GEM VDI that translates standard device-independent graphics operations to device-specific command sequences for a particular device. Unique value used to identify which workstation the GEM VDI function should use. GEM VDI assigns these numbers at Open Workstation. Id number assigned to a device in the ASSIGN.SYS file. Each device in the ASSIGN.SYS file has a unique device number assigned to it. Glossary-1 GEM VDI Programmer's Guide Glossary face font function code graphics command graphics device Graphics Device Operating System (GDOS) Generalized Drawing Primitive (GDP) Graphics Environment Manager Virtual Device Interface (GEM VDI) Graphical Kernel System (GKS) graphics primitives 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. Collection of characters all in one typeface, a subset of face. See operation code. Command that loads the GDOS into memory. Hardware that accepts graphics input (mouse or keyboard, for example) or displays graphics output (screen, printer, or plotter, for example) . Device-independent portion of GEM VDI that services graphics requests and calls the device driver to send commands to graphics dev ices. Display function used to address special device capabilities such as curve drawing. GEM VDI 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 extension to microcomputer opera¬ ting systems. The GEM VDI makes it possible to run graphics applications on a micro¬ computer. International standard for the programming interface to graphics from an application program. Basic graphics operations performed by GEM VDI, for example, drawing lines, markers, and text strings. Glossary-2 GEM VDI Programmer's Guide Glossary hot spot metafile Memory Form Definition Block (MFDB) Normalized Device Coordinate (NDC) space normalized device coordinates (NDC) operation codes (opcodes) pixel (pixel element) 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. 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. Block of memory that defines a raster area. An MFDB includes the following raster area 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 Uniform virtual space by which a graphics application program can pass graphics information to a device. The GDOS maps NDCs to RCs. NDC space has its origin in the lower left corner. Any point in NDC space. Passed to GDOS as part of a parameter list. The opcode indicates which graphics operation is requested. Smallest element of a display surface that can be independently referenced. Glossary-3 GEM VDI Programmer's Guide Glossary raster area Raster Coordinate (RC) space Raster Coordinate (RC) raster functions transformation node Virtual Device Interface (VDI) virtual screen Rectangular blocks of either bits in memory or pixels on a physical device. Rasters are the steps between pixels. Actual device units. Raster coordinate space has its origin in the upper left corner. Its limits are determined by the resolution of the specific device. Point in RC space. Functions that operate on pixels either individually or in groups. Determines which coordinate system the 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. Standard interface between device-dependent and device-independent code in a graphics environment. The GEM VDI makes all device drivers appear identical to the calling program. Block of memory that can be addressed as if it were a memory-mapped display. End of Glossary Glossary-4 Index A architecture, 1-2 B bit image file format, 1-1 BYTE, 2-1 C Cell Array function, 4-11 character offset, G-4 Close Virtual Screen Workstation function, 3-13 Close Workstation function, 3-9 control array, 1-5 coordinate window, H-l, H-2 Copy Raster Opaque function, 6-7 Transparent function, 6-9 D data format with bit image files, 1-1 device drivers, 1-2 device handle, 1-4 device id number, 1-4 E error messages, A-l escape alpha cursor down, 9-1, 9-8 alpha cursor home, 9-11 alpha cursor left, 9-1, 9-10 alpha cursor right, 9-1, 9-9 alpha cursor up, 9-1, 9-7 clear display list, 9-2, 9-26 direct alpha cursor address, 9-1, 9-14 enter alpha mode, 9-1, 9-6 erase to end of alpha screen, 9-1, 9-12 erase to end of alpha text line, 9-1, 9-13 exit alpha mode, 9-1, 9-5 form advance, 9-2, 9-23 change GEM VDI filename, 9-44 hard copy, 9-2, 9-20 home alpha cursor, 9-1, 9-11 inquire addressable alpha character cells, 9-1, 9-4 inquire current alpha cursor address, 9-2, 9-18 inquire palette driver state, 9-2, 9-33 inquire palette film types, 9-2, 9-32 inquire tablet status, 9-2, 9-19 output bit image file, 9-27 output cursor addressable alpha text, 9-1, 9-15 output window, 9-2, 9-24 palette error inquire, 9-2, 9-39 place graphic cursor at location, 9-2, 9-21 remove last graphic cursor, 9-2, 9-22 reverse video off, 9-2, 9-17 reverse video on, 9-1, 9-16 save palette driver state, 9-2, 9-37 select palette, 9-2, 9-30 set palette driver state, 9-2, 9-35 suppress palette messages, 9-2, 9-38 update metafile extents, 9-41 write metafile item, 9-2, 9-43 Exchange Button Change Vector function, 7-27 Exchange Cursor Change Vector function, 7-31 Exchange Mouse Movement Vector function, 7-29 extended run-length encoding, 1-2 external fonts, G-l F Filled Area function, 4-8 Filled Rounded Rectangle function, 4-25 font data, G-l font form, G-l Index-1 font format, G-l font header, G-l Form Advance function, 9-23 function code escape, 9-1 function Bar, 4-8 Cell Array, 4-11 Circle, 4-28 Close Virtual Screen Workstation, 3-13 Close Workstation, 3-9 Copy Raster, Opaque, 6-7 Copy Raster, Transparent, 6-9 Exchange Button Change Vector, 7-27 Exchange Cursor Change Vector function, 7-31 Exchange Mouse Movement Vector, 7-30 Filled Area, 4-8 Filled Rounded Rectangle, 4-25 Get Pixel, 6-13 Input Locator, Request Mode, 7-3 Input Locator, Sample Mode, 7-6 Input String, Request Mode, 7-15 Input String, Sample Mode, 7- 17 Input Valuator, 7-9 Inquire Current Face Information, 8-21 Inquire Face Name and Index, 8- 19 Justified Graphics Text, 4-27 Load Fonts, 3-16 Open Virtual Screen Workstation, 3-10 Open Workstation, 3-1 Polyline, 4-1 Polymarker, 4-4 Rounded Rectangle, 4-25 Sample Keyboard State Information, 7-33 Sample Mouse Button State, 7-26 Set Graphic Text Special Effects, 5-27 Set Input Mode, 7-1 Set Mouse Form, 7-19 Set Polyline End Styles, 5-12 Set Text Face, 5-24 Set User-defined Fill Pattern, 5-37 Text, 4-6 Unload Fonts, 3-17 Update Workstation, 3-15 G GDOS, 1-2 GDP Arc & Pie function, 4-19 Bar function, 4-18 Circle function, 4-21 Ellipse, 4-24 Elliptical Arc and Pie, 4-22 GEMVDI command, 2-19 Get Pixel function, 6-13 Graphics Device Operating System, See GDOS H hard copy escape, 9-20 header format with bit image files, 1-1 hide cursor escape, 7-25 horizontal offset table, G-4 I Input Locator Request Mode function, 7-3 Sample Mode function, 7-6 input parameters array, 1-5 input point coordinates, 1-5 Input String Request Mode function, 7-15 Sample Mode function, 7-17 Input Valuator function, 7-9 inquire cell array, 8-23 inquire character cell width, 8-17 inquire color representation, 8-5 Inquire Current Face Information function, 8-21 Inquire Face Name and Index function, 8-19 Inquire Palette Driver State Escape, 9-33 Inquire Palette Film Types Escape, 9-32 Index-2 inquire text extent, 8-15 interrupt for 68K, E-3 interrupt for 8086, E-l J justified graphics text, 4-27 L Load Fonts function, 3-16 M memory requirements, 2-20 metafile sub-opcodes, H-l, H-3 multiple workstations, 1-4 N NDC, 1-4, 1-6 normalized device coordinates, 1- 4, 1-6 O Open Virtual Screen Workstation function, 3-10 Open Workstation function, 3-1 output parameters, 1-5 output point parameters, 1-5 Output Window Escape, 9-24 P Palette Error Inquire Escape, 9-39 physical page size, H-l plotter functions, 2-13 Polaroid Palette Escapes, 9-31 Polyline function, 4-1 Polymarker function, 4-4 R registers for 68K, E-3 registers for 8086, E-l required functions for printers, 2-11 required functions for screens, 2- 9 reserved metafile sub-opcodes, H-l Rounded Rectangle function, 4- 25 run-length encoding, 1-1, 1-2 S Sample Keyboard State Information function, 7-33 Sample Mouse Button State function, 7-26 Save Palette Driver State Escape, 9-37 scan line, G-l Select Palette Escape, 9-30 set character baseline vector, 5- 22 set character cell height points mode, 5-18, 5-20 set character height absolute mode, 5-18 Set Clipping Rectangle function, 3-19 set color representation, 5-4 set fill color index, 5-35 set fill interior style, 5-32 set fill perimeter visibility, 5-36 set fill style index, 5-33 set graphic text alignment, 5-30 set graphic text color index, 5-26 set graphic text special effects, 5-27 Set Input Mode function, 7-1 Set Mouse Form function, 7-19 Set Palette Driver State Escape, 9-32 set polyline color index, 5-11 Set Polyline End Styles function, 5-12 set polyline line type, 5-6 set polyline line width, 5-9 set polymarker color index, 5-17 set polymarker height, 5-16 set polymarker type, 5-14 set text color index, 5-24 Set Text Face function, 5-24 Set User-defined Fill Pattern function, 5-33 set user-defined line style, 5-8 Index-3 set writing mode, 5-1 show cursor, 7-23 stack requirements, 2-20 sub-opcodes, H-l Suppress Palette Messages Escape, 9-38 system fonts, G-l T Text function, 4-6 transforming points, 1-6 D Unload fonts function, 3-17 Update Workstation function, 3-15 V VDI, 1-5 Virtual Device Interface, 1-5 VDI, 1-5 W 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-1 v_opnwk(work in, 8(handle, work out); 2 Close Workstation-1 v_clswk(handle); 3 Clear Workstation-1 vclrwk(handle); 4 Update Workstation-1 v updwk(handle); 5 Escapes 5-1 Inquire Addressable Character Cells-9 vq_chcells(handle, 8irows, 8icolumns); 5-2 Exit Alpha Mode-9 v_exit_ c ur(handl e ); 5-3 Enter Alpha Mode-9 ventercur(handle); 5-4 Cursor Up-9 vcurup(handle); 5-5 Cursor Down-9 vcurdown(handle); 5-6 Cursor Right-9 v_curright(handle); 5-7 Cursor Left-9 vcurleft(handle); 5-8 Home Cursor-9 vcurhome(handle); 5-9 Erase to End of Screen-9 v eeos(handle); 5-10 Erase to End of Line-9 veeol(handle); 5-11 Direct Cursor Address-9 vs_curaddress(handle, row, column); 5-12 Output Cursor Addressable Text-9 v_curtext(handle, 8istring); 5-13 Reverse Video On-9 vrvon(handle); 5-14 Reverse Video Off-9 v_rvoff(handle); 5-15 Inquire Current Alpha Cursor Address-9 vq_curaddress(handle, 8trow, &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, xyarray); 5-22 Clear Display List-9 vcleardispjist(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, 8iport, 8ifilm_name, tightness, 8«interlace, 8<planes, 8iindexes); 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 vspmessage(handle); 5-96 Palette Error lnquire-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, numintin, intin, num ptsin, ptsin); Op 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(hand!e, 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, yradius, 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 v_justified(handle, x, y, string, length, word space, char space); 12 Set Character Height, Absolute Mode-5 vst_height(handle, height, 8ichar_width, 8<char_height, 8icell_width, 8icell_height); 13 Set Character Baseline Vector-5 set_baseline=vst_rotation(handle, angle); 14 Set Color Representation-5 vs_color(handle, index, rgbjn); 15 Set Polyline Linetype-5 set type=vsl type(hand!e, style); 16 Set Polyline Line Width-5 set_width=vsl_width(handle, width); 17 Set Polyline Color Index-5 set_color=vsl_color(handle, colorindex); 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(handle, color index); 21 Set Text Face-5 22 Set Graphic Text Color Index-5 23 Set Fill Interior Style-5 Op Code Function Name-Section 24 Set Fill Style Index-5 25 Set Fill Color Index-5 26 Inquire Color Representation-8 27 Inquire Cell Array-8 28 Input Locator, Request Mode-7 28 Input Locator, Sample Mode-7 29 Input Valuator, Request Mode-7 29 Input Valuator, Sample Mode-7 30 Input Choice, Request Mode-7 30 Input Choice, Sample Mode-7 31 Input String, Request Mode-7 31 Input String, Sample Mode-7 32 Set Writing Mode-5 33 Set Input Mode-7 35 Inquire Current Polyline Attributes-8 36 Inquire Current Polylmarker Attributes-8 37 Inquire Current Fill Area Attributes-8 38 Inquire Current Graphic Text Attributes-8 39 Set Graphic Text Alignment-5 100 Open Virtual Screen Workstation-1 101 102 Close Virtual Screen Workstation-1 Extended lnquire-8 set_font=vst_font(handle, font); set_color=vst_color(handle, color index); set_interior=vsf_interior(handle, style); Procedure Name set_style=vsf_style(handle, style index); set_color=vsf_color(handle, color index); vq_color(handle, colorjndex, set_flag, rgb); vq_cellarray(handle, pxyarray, rowjength, num_rows, &el_used, &rows_used, &status, colarray); vrq_locator(handle, x, y, &xout, &yout, &term); status=vsm_locator(handle, x, y, &xout, &yout, &term); vrq_valuator(handle, valuatorJn, &valuator_out, &terminator); vsm_valuator(handle, valjn, &val_out, &term, &status); vrq_choice(handle, chjn, 8(Ch_out); status=vsm_choice(handle, &choice); vrq_string(handle, max iength, echo mode, echo xy, 8<string); status=vsm_string(handle, max iength, echo mode, echo_xy, 8istring); set_mode=vswr_mode(handle, mode); vsin_mode(handle, dev type, mode); vql_attributes(handle, attrib); vqm_attributes(handle, attrib); vqf_attributes(handle, attrib); vqt_attributes(handle, attrib); vst_alignment(handle, hor in, vert in, &hor_out, &vert out); v_opnvwk(work_in, &handle, workout); v_clsvwk(handle); 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 ge^pixeKhandle, x, y, 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, 8tchar height, 8tcell_width, 8«cell_height); 108 Set Polyline End Styles-5 vsl_ends(handle, beg style, endstyle); 109 Copy Raster, Opaque-6 vro cpyfm(handle, wr mode, pxyarray, srcMFDB, pdesMFDB); 110 Transform Form-6 vr_trn_fm(handle, psrcMFDB, pdesMFDB); 111 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 recfl(handle, pxyarray); 115 Inquire Input Mode-8 vqin_mode(handle, dev type, 8tinput_mode); 116 Inquire Text Extent-8 vqt_extent(handle, string, extent); 117 Inquire Character Cell Width-8 status=vqt_width(handle, character, 8tcell_width, 8ileft_delta, 8iright_delta); 118 Exchange Timer Interrupt Vector-7 vex_timv(handle, tim addr, otim_addr,8itim_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, wrmode, pxyarray, psrcMFDB, pdesMFDB, color index); 122 Show Cursor-6 v show c(handle, reset); 123 Hide Cursor-6 vhidecjhandle); 124 Sample Mouse Button State-7 vq_mouse(handle, 8ipstatus, 8ix, &y); 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 vq_key_s(handle, 8ipstatus); 129 Set Clipping Rectangle-3 vs_clip(handle, clip flag, pxyarray); 130 Inquire Face Name and Index-8 index=vqt_name(handle, element num, name); 131 Inquire Current Face Information-8 vqt_font_info(handle, 8iminADE, &maxADE, distances, maxwidth, effects);