DIGITAL RESEARCH GEM (TM) Programmer's Guide Volume 1: VDI ***************************************************************************** COPYRIGHT Copyright (9) 1985 Digital. Research Inc. All rights reserved. No part of this publication may be reproduced, transmitted, transcribed, stored in a retrieval system, or translated into any language or computer Language, in any form or by any means, electronic, mechanical, magnetic, optical, chemical, manual or otherwise, without the prior written permission of Digital Research Inc., 60 Garden Court, P.O. Box DRI, Monterey, California 93942. DISCLAIMER DIGITAL RESEARCH INC. MAKES NO REPRESENTATIONS OR WARRANTIES WITH RESPECT TO THE CONTENTS HEREOF AND SPECIFICALLY DISCLAIMS ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE. Further, Digital Research Inc. reserves the right to revise this publication and to make changes, from time to time, in the content hereof without 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 (Tm) Programmer's Guide, Volume 1: VDI was printed in the United States of America. ******************************** * First. Edition: April 1985 * ******************************** ***************************************************************************** Foreword _____________________________________________________________________________ OBJECTIVE This guide describes the features and operation of the Graphics Environment Manager (Tm) (GEM" ) Virtual Device Interface (VDI), the successor to the Digital Research Graphics System Extension (GSX Tm ). 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). iii **************************************************************************** _____________________________________________________________________________ Section 7 describes the input functions, which allow the user to interact with the application program. Section 8 describes the inquire functions, which return the current settings for device specific attributes, such as the number of text styles supported. Section 9 describes the escape functions, which allow the application program to access special device capabilities. Appendix A lists and describes the GEM VDI error messages. Appendix B explains the ASSIGN.SYS file contents, which include information the GDOS uses to identify the output device. Appendix C lists and describes the GEM VDI metafile format. Appendix D defines the GEM VDI standard keyboard. Appendix E describes the mapping of GEM VDI to specific microprocessors and the calling procedures needed to perform that mapping. Appendix F includes the system fonts. Appendix G describes the font file format. Appendix H describes the reserved metafile sub opcodes. Appendix I describes the bit image file format. iv ***************************************************************************** Table of Contents _____________________________________________________________________________ 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 . 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 vi ***************************************************************************** Table of Contents (continued) _____________________________________________________________________________ Filled Area . . . . . . . . . . . . . . . . . . . . . . .4-8 Cell Array . . . . . . . . . . . . . . . . . . . . . . . 4-11 Contour Fill . . . . . . . . . . . . . . . . . . . . . . 4-13 Fill Rectangle . . . . . . . . . . . . . . . . . . . . . 4-14 Generalized Drawing Primitive (GDP) . . . . . . . . . . .4-15 Bar . . . . . . . . . . . . . . . . . . . . . . . . . . .4-18 Arc & Pie . . . . . . . . . . . . . . . . . . . . . . . .4-19 Circle . . . . . . . . . . . . . . . . . . . . . . . . . 4-21 Elliptical Arc and Pie . . . . . . . . . . . . . . . . . 4-22 Ellipse . . . . . . . . . . . . . . . . . . . . . . . . .4-24 Rounded and Filled Rounded Rectangle . . . . . . . . . . 4-25 Justified Graphics Text . . . . . . . . . . . . . . . . .4-27 5 Attribute Functions Introduction . . . . . . . . . . . . . . . . . . . . . . 5-1 Set Writing Mode . . . . . . . . . . . . . . . . . . . .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 viii ***************************************************************************** Table of Contents (continued) _____________________________________________________________________________ Transform Form . . . . . . . . . . . . . . . . . . . . . 6-12 Get Pixel. . . . . . . . . . . . . . . . . . . . . . . . 6-13 7 Input Functions Introduction . . . . . . . . . . . . . . . . . . . . . . 7-1 Set Input Mode . . . . . . . . . . . . . . . . . . . . . 7-1 Input Locator, Request Mode . . . . . . . . . . . . . . .7-3 Input Locator, Sample Mode . . .. . . . . . . . . . . . .7-6 Input Valuator, Request Mode . .. . . . . . . . . . . . .7-9 Input Valuator, Sample Mode . . . . . . . . . . . . . . .7-11 Input Choice, Request Mode . . .. . . . . . . . . . . . .7-13 Input Choice, Sample Mode . . .. . . . . . . . . . . . . 7-14 Input String, Request Mode . . .. . . . . . . . . . . . .7-15 Input String, Sample Mode . . .. . . . . . . . . . . . . 7-17 Set Mouse Form . . . . . . . . .. . . . . . . . . . . . .7-19 Exchange Timer Interrupt Vector. . . . . . . . . . . . . 7-21 Show Cursor. . . . . . . . . .. . . . . . . . . . . . . .7-23 Hide Cursor. . . . . . . . . .. . . . . . . . . . . . . .7-25 Sample Mouse Button State . . .. . . . . . . . . . . . . 7-26 Exchange Button Change Vector .. . . . . . . . . . . . . 7-27 Exchange Mouse Movement Vector .. . . . . . . . . . . . .7-29 Exchange Cursor Change Vector .. . . . . . . . . . . . . 7-31 Sample Keyboard State Information . . . . . . . . . . . .7-33 8 Inquire Functions Introduction . . . . . . . . . . . . . . . . . . . . . . 8-1 Extended Inquire . . . . . . . . . . . . . . . . . . . . 8-1 ix ***************************************************************************** Table of Contents (continued) Inquire Color Representation . . . . . . . . . . . . . . 8-5 Inquire Current Polyline Attributes . . . . . . . . . . .8-7 Inquire Current Polymarker Attributes . . . . . . . . . .8-9 Inquire Current Fill Area Attributes . . . . . . . . . . 8-11 Inquire Current Graphic Text Attributes . . . . . . . . .8-13 Inquire Text Extent . . . . . . . . . . . . . . . . . . .8-15 Inquire Character Cell Width . . . . . . . . . . . . . . 8-17 Inquire Face Name and Index . . . . . . . . . . . . . . .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-1 B ASSIGN.SYS File Requirements . . . . . . . . . . . . . . . . . . . . . . B-1 Device Id Numbers . . . . . . . . . . . . . . . . .B-1 Device Driver Filename . . . . . . . . . . . . . . B-1 Format . . . . . . . . . . . . . . . . . . . . . . . . . B-1 Sample ASSIGN.SYS . . . . . . . . . . . . . . . . . . . .B-2 C GEN VDI Metafile Format Introduction . . . . . . . . . . . . . . . . . . . . . . C-1 Standard Metafile Item Format . . . . . . . . . . . . . .C-1 Nonstandard Metafile Items . . . . . . . . . . . . . . . C-2 1 open workstation . . . . . . . . . . . . . . . . C-2 2 close workstation . . . . . . . . . . . . . . . .C-4 Special Metafile Escapes . . . . . . . . . . . . . . . . C-4 5, 98 update metafile extents . . . . . . . . . . .C-4 5, 99 write metafile item escape . . . . . . . . . C-4 5, 100 change GEM VDI filename escape . . . . . . .C-4 Inquiry Functions . . . . . . . . . . . . . . . . . . . .C-5 D Standard Keyboard . . . . . . . . . . . . . . . . . . . .D-1 E Processor-Specific Data . . . . . . . . . . . . . . . . .E-1 8086-Specific Data . . . . . . . . . . . . . . . . . . . E-1 68000-Specific Data . . . . . . . . . . . . . . . . . . .E-3 F Character Sets . . . . . . . . . . . . . . . . . . . . . F-1 xii ***************************************************************************** Table of Contents (continued) _____________________________________________________________________________ G Font Format Introduction . . . . . . . . . . . . . . . . . . . . . . G-1 Font Data . . . . . . . . . . . . . . . . . . . . . . . .G-1 Font Header . . . . . . . . . . . . . . . . . . . . . . .G-1 Character Offset Table . . . . . . . . . . . . . . . . . G-4 Horizontal Offset Table . . . . . . . . . . . . . . . . .G-4 H Reserved Metafile Sub-opcodes Metafile Sub-opcodes for Use with GEM Output . . . . . . H-1 Physical Page Size . . . . . . . . . . . . . . . . . . . H-1 Coordinate Window . . . . . . . . . . . . . . . . . . . .H-2 Metafile Sub-opcodes for Use with GEM Draw . . . . . . . H-3 Start Group . . . . . . . . . . . . . . . . . . . . . . .H-3 End Group . . . . . . . . . . . . . . . . . . . . . . . .H-4 Set No Line Style . . . . . . . . . . . . . . . . . . . .H-4 Set Attribute Shadow On . . . . . . . . . . . . . . . . .H-5 Set Attribute Shadow Off . . . . . . . . . . . . . . . . H-6 Start Draw Area Type Primitive . . . . . . . . . . . . . H-6 End Draw Area Type Primitive . . . . . . . . . . . . . . H-7 I Bit Image File Format Introduction . . . . . . . . . . . . . . . . . . . . . . I-1 Header Format . . . . . . . . . . . . . . . . . . . . . .I-1 Data Format . . . . . . . . . . . . . . . . . . . . . . .I-1 Run-length Encoding . . . . . . . . . . . . . . . .I-2 Extended Run-length Encoding . . . . . . . . . . . I-2 Raster Encoding . . . . . . . . . . . . . . . . . .I-3 Raster-run Encoding . . . . . . . . . . . . . . . .I-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 M;pping 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-1. Device id Numbers . . . . . . . . . . . . . . . . . . . .B-1 D-1. GEM VDI Standard Keyboard Assignments . . . . . . . . . .D-1 G-1. Font Header Format . . . . . . . . . . . . . . . . . . . G-2 xiv ***************************************************************************** Table of Contents (continued) _____________________________________________________________________________ Figures 1-1. Transformation Modes . . . . . . . . . . . . . . . . . . 1-8 2-1. Output from the Sample Program 4-1. First Point for wide Lines . . . . . . . . . . . . . . . 4-1 4-2. Angle Specification . . . . . . . . . . . . . . . . . . .4-15 5-1. Character Cell Definition . . . . . . . . . . . . . . . .5-20 5-2. Angle Specification . . . . . . . . . . . . . . . . . . .5-22 5-3. Graphic Text Special Effects . . . . . . . . . . . . . . 5-28 5-4. Graphic Text Alignment . . . . . . . . . . . . . . . . . 5-30 5-5. Fill Styles and Indices . . . . . . . . . . . . . . . . .5-33 6-1. Memory Form Definition Block . . . . . . . . . . . . . . 6-2 6-2. Standard Forms . . . . . . . . . . . . . . . . . . . . . 6-5 6-3. Sample Single Plane Memory Form . . . . . . . . . . . . .6-5 8-1. Inquire Text Extent Function . . . . . . . . . . . . . . 8-15 8-2. Character Cell Definition . . . . . . . . . . . . . . . .8-17 8-3. Right and Left Offset . . . . . . . . . . . . . . . . . .8-21 B-1. ASSIGN.SYS File Format . . . . . . . . . . . . . . . . . B-1 F-1. GEM VDI USASCII Character Set . . . . . . . . . . . . . .F-2 F-2. GEM VDI International Character Set E X tension . . . . .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 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. _____________________________________________________________________________ Graphics The Graphics Device Operating System (GDOS) Device Operating contains the basic host and device- System (GDOS) independent graphics functions that can be called by your application program. GDOS provides a standard graphics interface that is constant regardless of specific devices or host hardware, just as the disk operating system standardizes disk interfaces. Your application program accesses the GDOS in much the same way that it accesses the operating system. The GDOS performs coordinate scaling so that your application can specify points in a normalized space. It uses device-specific information to transform (map) the coordinates into the corresponding values for a particular graphics device. An application can also specify points in raster coordinate space, in which case no transformation occurs. 1-2 ***************************************************************************** GEM VDI Programmer's Guide Architecture Graphics The graphics device drivers are similar to Device Drivers any 1/0 system. They contain the device specific code required to interface your particular graphics devices to the GDOS.The device drivers communicate directly with the graphics devices.GEM VDI requires a unique device driver for each graphics device in a system. A single program can use several graphics devices; the GDOS loads only the appropriate device driver file into memory. By referring to devices with a device identification number, an application program can send graphics information to any one of several memory resident device drivers. The device driver outputs the GEM VDI graphics primitives according to the inherent capabilities of a particular graphics device. In some cases, a device driver emulates standard capabilities not provided by the graphics device hardware. For example, some devices require that dashed lines be simulated by a series of short vectors generated in the device driver. The GEM VDI package contains drivers for many of the most popular microcomputer-related graphics devices. _____________________________________________________________________________ DEVICE TYPES You can write a GEM VDI-based graphics application for a variety of devices including screens, plotters, printers, and special cameras. _____________________________________________________________________________ Meta-files A metafile is the stored generic form of a picture file. Any application can create a GEM VDI metafile that can later be called into another qraphics application. The metafile driver stores a description of a picture in a data file. These files can later be sent to any device or used to exchange a picture between two applications. 1-3 ***************************************************************************** GEM VDI Programmer's Guide Device Types _____________________________________________________________________________ When GEM VDI creates a metafile, it provides the ideal device. Raster Coordinate (RC) and Normalized Device Coordinate (NDC) space are the same (0 to 32767). No transform is applied. Refer to "Transforming Points" later in this section for more information on the coordinate spaces. Refer to Appendix C for information about the file format for metafiles. _____________________________________________________________________________ Multiple The application program specifies the Workstations graphics function to be performed by a device driver with an operation code (opcode) in the control array. "Opcodes" in Section 2 describes the opcodes. Because multiple workstations can be open at the same time, each GEM VDI function must be provided with a unique reference to the desired device. This identification is referred to as the device handle. _____________________________________________________________________________ Device Handles The GDOS assigns the device handle when the Open Workstation function is called by the application program. The Open Workstation call returns the device handle in the array element contrl(6). All subsequent GEM VDI calls need to supply the device handle as an input in element contrl(6). _____________________________________________________________________________ ASSIGN.SYS The ASSIGN.SYS file is a text file, and can be created or edited using any text editor. The file lists the device driver filenames and face filenames, their device numbers, and device specific information. The device numbers are assigned according to their type- Refer to Table 1-1 for device numbers. 1-4 ***************************************************************************** GEM VDI Programmer's Guide Device Types _____________________________________________________________________________ Table 1-1. Device Identification Numbers Device Type Device Number Screen 1-10 Plotter 11-20 Printer 21-30 Metafile 31-40 Camera 41-50 Tablet 51-60 _____________________________________________________________________________ APPLICATION 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(0). The content of the input and output parameter arrays depends on the opcode. Refer to Section 2 for more information about writing graphics applications. _____________________________________________________________________________ TRANSFORMING All computer graphics are displayed using a POINTS coordinate system. GEM VDI makes sure the coordinate system of one device matches the coordinate system of another. For example, with 3EM VDI, the application program produces the same graphics image on a printer as on a screen. The linetypes and fill styles are the same in Normalized Device Coordinates (NDC), which are described below. Character sizes are different. The same number of characters are displayed per line, but a printer's line length is generally greater than a screen's. _____________________________________________________________________________ Transformation The application program can address the Mode display surface using one of two coordinate systems: * Normalized Device Coordinates (NDC) * Raster Coordinates (RC) The transformation mode, specified at Open Workstation, determines which coordinate system is used. _____________________________________________________________________________ Normalized Device Normalized Device Coordinates (NDC) address Coordinates the graphics display independent of the device 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 non square 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 affect. The application needs to adjust its transform based on the aspect ratio of pixels on the screen. The raster coordinate system saves the overhead of the GDOS having to perform a transformation on every point. 1-7 ***************************************************************************** GEM VDI Programmer's Guide Transforming Points (32767,32767) (0,0) (640,200) (0,0) Mode 0 Full NDC mapped to full RC space (0,0) (0,0) (640,200) (640,200) Mode 2 Application works in RC space Figure 1-1. Transformation Modes End of Section 1 1-8 ***************************************************************************** Section 2 Writing a Graphics Application _____________________________________________________________________________ INTRODUCTION This section explains how to use GEM VDI in your graphics applications. _____________________________________________________________________________ GEM VDI When you receive your GEM VDI distribution DISTRIBUTION 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[11], 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, &handle, work_out); /* Output a polyline. */ pxyarray[0] = 12000; /* vertices... */ pxyarray[1] = 12000; pxyarray[2] = 12000; pxyarray[3] = 20000; pxyarray[4] = 14000; pxyarray[51 = 21000; pxyarray[6] = 16000; pxyarray[71 = 20000; pxyarray[8] = 16000; pxyarray[91 = 12000; p.yarray[10] = 12000; pxyarray[11] = 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, &term); /* Close the workstation. */ v-clswk(handle); } /* End "main". */ Listing 2-2. Sample Assembly Language Application ;********************************************************************* ; * ; Sample Assembly language program to interface with GEM VDI * ; * ; To open the workstation, draw a border, and say hello world * ; * ;********************************************************************* ; false equ 0 true equ not false dly equ 05FH ; for delay process, OFFFF is max delay possible ; W_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 INTOUT_SIZE equ 128 PTSOUT_SIZE 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 CONTRI, and INTIN arrays ;for an openworkstation call mov CONTRL + W_0,1 ;opcode 1 for openworkstation mov CONTRL + W_1,0 ; 0 ptsin values mov CONTRL + W_3,11 ; 11 intin values 2-4 ***************************************************************************** Gem Programmers Guide Writing the program _____________________________________________________________________________ Listing 2-2. (continued) mov INTIN + W_0,1 ;device id = 1 mov INTIN + W_1,1 ;linetype mov INTIN + W_2,1 ;line color mov INTIN + W_3,1 ;marker type mov INTIN + W_4,1 ;marker color mov INTIN + W_5,1 ;font mov INTIN + W_6,1 ;text color mov INTIN + W_7,1 ;fill interior style mov INTIN + W_8,1 ;fill style index mov INTIN + W_9,1 ;fill color index mov INTIN + W_10,2 ;transformation flag = RC system ; call gemvdi call gemvdi ; save the handle returned by ;openworkstation mov, ax,CONTRL + W_6 ;this is the handle returned by open ;and needed mov handle,ax ;by all other calls to the open workstation ; copy INTOUT and PTSOUT intc open_device, ;my local copy of the Device Table cld ;autoincrement the si and di registers push ds ;prepare es:di to move words to open_device pop es lea di,open_device mov, cx,45 ;prepare to load 45 words from INTOUT lea si,INTOUT rep movsw mov cx,12 ;prepare to load 12 words from PTSOUT lea si,PTSOUT rep movsw border: ; load CONTRL and INTIN arrays ;to draw a border and a diagonal mov CONTRL + W_0,6 ;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 2-5 ***************************************************************************** GEM Programmer's Guide Writing the Program _____________________________________________________________________________ Listing 2-2. (continued) mov PTSIN + W_8,0 ;point 5 is at (0,0) mov PTSIN + W_9,0 mov PTSIN + W_10,ax ;point 6 is at (xresmx,yresmx) mov PTSIN + W_11,bx ;call gemvdi call gemvdi announce: ;load CONTRI, and INTIN arrays ;to write "hello world" in the ;default system face and font, ;with deftult alignment, at the ;center of the device mov CONTRL + W_0,8 ;opcode for text mov ax,handle ;put the handle into CONTRL mov CONTRL + W_6,ax mov CONTRL + W_1,1 ;text location vertice mov CONTRL + W_3,length_anncmnt ; length of the text string to be sent mov ax,open_device + W_0 ; put tle max x resolution in ax shr ax,l ; divide the max x resolution by two mov bx,open_device + W_1 ;put tte max y resolution in bx shr bx,l ;divide the max y resolution by two mov PTSIN + W_0,ax ;put the center point coordinate in PTSIN mov PTSIN + W_1,bx cld ;autoincrement the si and di registers mov cx,length_anncmnt ;prepare to move the announcment ;string into INTIN lea si,anncmnt push ds pop es lea di,INTIN xor ah,ah ;make sure the high byte is clear internalloopl: lodsb ;transfer a byte from the source, ;to the accumulator stosw ;store the accumulator in ;the destination loop internalloopl ;do this operation for each byte ;in the source ;call gemvdi call gemvdi delay: ; delay for viewing mov cx,dly delayloop3: push cx mov cx,dly delayloop2: push cx mov cx,dly delayloopl: xchg ax,bx loop delayloopl 2-6 ***************************************************************************** GEM Programmer's Guide Writing the Program _____________________________________________________________________________ Listing 2-2. (continued) pop cx loop delayloop2 pop cx loop delayloop3 clswk: ; load CONTRL array to ;close workstation 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 o.s. 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 GODS ret ;end of the code segment of the ;sample program ;begin the data segment for the ;sample program DATA dseg PUBLIC word DGROUP GROUP DATA ;declare these publics so that ;the labels appear in the symbol file ;useful for debugging purposes public CONTRL public INTIN public PTSIN public INTOUT 2-7 ***************************************************************************** GEM Programmer's Guide Writing the Program _____________________________________________________________________________ Listing 2-2. (continued) public PTSOUT public contrl_ptr public intin_ptr public ptsin_ptr public intou_ptr public ptsout_ptr public handle public open_device 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, ;these are fixed when the program is loaded dw seg CONTRL, ;to be double word pointers to the arrays intin_ptr dw offset INTIN ;this is the parameter block to which ds:dx dw seg INTIN ;points when GEM VDI is called ptsin_ptr dw offset PTSIN dw seg PTSIN intout_ptr dw offset INTOUT dw seg INTOUT ptsout_ptr dw offset PTSOUT dw seg PTSOUT handle dw 0 open_device rw INTOUT_SIZE + PTSOUT_SIZE anncmnt db 'Sample Assembly Language Program' ;end the data segment for the sample program ;begin the stack segment for the sample program STACK sseg PUBLIC word SGROUP GROUP STACK ;as stated in the VDI programmers guide, the caller must supply at ;least 128 words of stack for the GEM VDI openworkstation call. ;the calls to the gemvdi subroutine in the code above require at most ;6 points, or 12 words words of stack. ;assume an o.s overhead of128 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 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 26 Inquire color representation 32 Set writing mode 35 Inquire current polyline attributes 36 Inquire current polymarker attributes 37 Inquire current fill area attributes 38 Inquire current graphic text attributes 39 Set graphic text alignment 102 Extended inquire function 104 Set fill perimeter visibility 106 Set graphic text special effects 107 Set character height points mode 108 Set polyline end styles 112 Exchange fill pattern 116 Inquire text extent 117 Inquire character cell width 129 Set clipping 130 Inquire face name and index 131 Inquire current face information 2-12 ***************************************************************************** GEM VDI Programmer's Guide Writing the Program _____________________________________________________________________________ Required Functions Plotters require the following functions and for Plotters sub functions: 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 You can determine if a function is available Opcodes 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(0) -- Opcodenumber for the GEM VDI function. contrl(1) -- 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(1), is set correctly. Contrl(1) must be set to 0 if no x,y coordinates are being passed to GEM VDI by the application program. In addition, the input integer count, contrl(3), must always be set. The calling routine must set contrl(3) to 0 if no integers are being passed to GEM VDI. Similarly, contrl(2), the output vertex count, and contrl(4), the output 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 Refer to Appendix E for the specific Interrupts registers and interrupts for various operating systems. Table 2-1. Parameter Block Contents Address Contents PB control array (contrl) PB + 4 input parameter array (intin) PB + 8 input point coordinate array (ptsin) PB + 12 output parameter array (intout) PB + 16 output point coordinate array (ptsout) _____________________________________________________________________________ RUNNING GRAPHICS To use the graphics features provided by APPLICATIONS GEM VDI, you must ensure that the following UNDER GEM VDI conditions are met: 1. 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 non graphics 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 work station 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 device-specific 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 non zero value in contrl(6) indicates a successful operation. _____________________________________________________________________________ Input contrl(0) -- Opcode = 1. contrl(1) -- Number of input vertices = 0. contrl(3) -- Length of intin array = 11. intin -- Initial defaults (for example, linestyle, color, character size). intin(0) -- Device id number. This value determines which device driver to dynamically load in memory. intin(l) -- Linetype. int.in(2) -- Polyline color index. int.in(3) -- Marker type. int.in(4) -- Polymarker color index. intin(5) -- Text face. intin(6) -- Text color index. intin (7) -- Fill interior style. int.in(8) -- Fill style index. int.in(9) -- Fill color index. 3-1 ***************************************************************************** GEM VDI Programmer's Guide 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) -- Number of output vertices = 6. contrl(4) -- Length of intout array = 45. contrl(6) -- Device handle for this device. intout(0) -- 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). intout(l) -- Maximum addressable height of screen or plotter in rasters or steps, assuming a 0 start point (for example, a resolution of 480 implies an addressable area of 0-479, so intout(1)=479). intout(2) -- Device Coordinate units flag. 0 = Device capab1e of producing precisely scaled image (typically a plotter or a printer). 1 = Device not capable of producing precisely scaled image (typically a film recorder). intout(3) -- Width of one pixel (plotter step, or aspect ratio for screen) in microns. intout(4) -- Height of one pixel (plotter step, or aspect ratio for screen) in microns. intout(5) -- Number of character heights. 0 = Continuous scaling. intout(6) -- Number of linetypes. intout(7) -- Number of line widths. 0 = Continuous scaling. intout(8) -- Number of marker types. 3-2 ***************************************************************************** GEM VDI Programmer's Guide Open Workstation _____________________________________________________________________________ intout(9) -- Number of marker sizes. 0 = Continuous scaling. intout(10) -- Number of faces supported by device (not the highest numbered face index). intout(11) -- 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 are 7 Elliptical pie 8 Rounded rectangle 9 Filled rounded rectangle 10 Justified graphics text intout(25) to intout(34) -- Linear list of attribute set associated with each GDP. 0 Polyline 1 Polymarker 2 Text 3 Fill area 4 None intout(35) -- Color capability flag. 0 No 1 Yes 3-3 ***************************************************************************** GEM VDI Programmer's Guide Open Workstation _____________________________________________________________________________ intout(36) -- Text rotation capability flag. 0 No 1 Yes intout(37) -- Fill area capability flag. 0 No 1 Yes intout(38) -- Cell array operation capability flag. 0 No 1 Yes intout(39) -- Number of available colors ( total number of colors in color palette). 0 Continuous device (more than 32767 colors) 2 Monochrome (black and white) >2 Number of co1ors available intout(40) -- Number of locator devices available. 1 Keyboard only 2 Devices with keyboard and other input intout(41) -- Number of valuator devices available. 1 Keyboard 2 If another valuator device is available intout(42) -- Number of choice devices available. 1 Function keys on keyboard 2 If another button pad is available intout(43) -- Number of string devices available. 1 Keyboard 3-4 ***************************************************************************** GEM VDI Programmer's Guide Open Workstation _____________________________________________________________________________ intout(44) -- Workstation type. 0 Output only 1 Input only 2 Input/output 3 Reserved 4 Metafile output ptsout(0) -- Minimum character width. ptsout(1) -- 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. ptsout(2) -- Maximum character width. ptsout(3) -- Maximum character height in the y-axis in the current coordinate system. ptsout(4) -- Minimum line width in the x-axis in current coordinate system. The minimum line width is a nominal device-dependent size. If the minimum line width used is 1 device unit, the line may not be visible on some high resolution devices. ptsout(5) -- 0. ptsout(6) -- Maximum line width in the x-axis in the current coordinate system. ptsout(7) -- 0. ptsout(8) -- Minimum marker width in x-axis in the current coordinate system. ptsout(9) -- Minimum marker height in x-axis in the current coordinate system. ptsout(10) -- Maximum marker width in x-axis in the current coordinate system. ptsout(ll) -- Maximum marker height in x-axis in the current coordinate system. 3-5 ***************************************************************************** GEM VDI Programmer's Guide Open Workstation _____________________________________________________________________________ Default Color The default color table is set up differently Tables for monochrome and color devices. Table 3-1. Monochrome Screens Index 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-7 ***************************************************************************** GEM VDI Programmer's Guide Open Workstation _____________________________________________________________________________ C BINDING Procedure Name v_opnwk( work_in, &handle, work_out ) Data Types WORD v_opnwk ( ); WORD work_in[11]; WORD handle; WORD work_out[57]; Input Arguments work-in[0] = intin[0] work-in[1] = intin[1] . . work-in[10] = intin[10] Output Arguments handle = contrl[6] work_out[0] = intout[0] work_out[1] = intout[1] . . . work_out[44] = intout[44] work_out[45] = ptsout[0] . . . work_out[56] = ptsout[11] 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 your open virtual workstations before closing the workstation. _____________________________________________________________________________ Input contrl(0) -- Opcode = 2. contrl(1) -- Number of input vertices = 0. contrl(3) -- Length of intin array = 0. contrl(6) -- Device handle. _____________________________________________________________________________ Output contrl(2) -- Length of output vertices = 0. cortrl(4) -- Length of intout array = 0. _____________________________________________________________________________ C BINDING Procedure Name v_clswk( handle ) Data Types WORD v_clswk ( ); WORD handle; Input Arguments handle = contrl[6] 3-9 ***************************************************************************** GEM VDI Programmer's Guide Open Virtual Screen Workstation OPEN VIRTUAL This Function allows a single physical screen SCREEN WORKSTATION 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. _____________________________________________________________________________ Input contrl(0) -- Opcode = 100. contrl(l) -- Number of input vertices = 0. contrl(3) -- Length of intin = 11. contrl(6) -- Device handle of a previously opened screen device. intin -- For a description of the intin parameters required in the intin array see Open Workstation (Opcode 1). 3-10 ***************************************************************************** GEM VDI Programmer's Guide Open Virtual Screen Workstation Output contrl(2) -- Number of output vertices = 6. contrl(4) -- Length of intout = 45. contrl(6) -- The device handle for the Virtual Screen Device just opened. warning: Contrl(6) is an input/output parameter. The value is changed to that of the Virtual Screen Workstation device handle. Note: All output parameters are the same as those of Open Workstation (Opcode 1). 3-11 ***************************************************************************** GEM VDI Programmer's Guide Open Virtual Screen Workstation C BINDING Procedure Name v_opnrwk( work_in, &handle, work_out ) Data Types WORD v_opnvwk( ); WORD handle; WORD work_in[11]; WORD work_out[57]; Input Arguments handle = contrl[6] work-in[0] = intin[0] . . work-in[10] = intin[10] Output Arguments work-out[0] = intout[0] . . work-out[44] = intout[44] work-out[45] = ptsout[0] . . work-out[56] = ptsout[11] 3-12 ***************************************************************************** GEM VDI Programmer's Guide Close Virtual Screen Workstation _____________________________________________________________________________ CLOSE VIRTUAL The Close Virtual Screen Workstation function SCREEN WORKSTATION terminates the virtual device and prevents any further output to it. _____________________________________________________________________________ Input contrl(0) -- Opcode = 101. contrl(l) -- Number of input vertices = 0. contrl(3) -- Length of intin = 0. contrl(6) -- Device handle. _____________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout = 0. _____________________________________________________________________________ C BINDING Procedure Name v_clsvwk( handle ) Data Types WORD v_clsvwk( ); WORD handle; Input Arguments handle = contrl[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(0) -- Opcode = 3. contrl(1) -- 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 contri(0) -- Opcode = 4. contrl(l) -- Number of input vertices = 0. contrl(3) -- Length of intin = 0. contrl(6) -- Device handle. _____________________________________________________________________________ Output contrl(2) -- Number in output vertices = 0. contrl(4) -- Length of intout = 0. _____________________________________________________________________________ C BINDING Procedure Name v_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 nakes 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(0) -- Opcode = 119. contrl(1) -- Number of input vertices = 0. contrl(3) -- Length of intin array = 1. contrl(6) -- Device handle. intin(0) -- Reserved for future use = 0. _____________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of output array = 1. intout(0) -- Number of additional font identifiers. _____________________________________________________________________________ C BINDING Procedure Name vst_load_fonts( handle, select, additional ) Data Types WORD vst_load_fonts( ); WORD additional; WORD handle; WORD select; Input Arguments handle = contrl[6] select = intin[0] Output Arguments 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) -- Opcode = 120. contrl(1) -- Number of input vertices = 0. contrl(3) -- Length of intin array = 1. contrl(6) -- Device handle. intin(0) -- Reserved for future use. Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout array = 0. 3-17 ***************************************************************************** GEM VDI Programmer's Guide Unload Fonts _____________________________________________________________________________ C BINDING Procedure Name vst_unload_fonts( handle, select ) Data Types WORD vst_unload_fonts( ); WORD handle; WORD select; Input Arguments handle = contrl[6] select = intin[0] 3-18 ***************************************************************************** GEM VDI Programmer's Guide Set Clipping Rectangle _____________________________________________________________________________ SET CLIPPING This function enables or disables clipping of RECTANGLE all output primitives by GEM VDI. Intin (0) is a flag, which if nonzero, enables clipping. The ptsin array contains the rectangle, specified in the current coordinate system, to clip to. If intin(0) is zero, clipping is turned off. The default at Open Workstation is for clipping to be disabled. _____________________________________________________________________________ Input contrl(0) -- opcode = 129. contrl(l) -- Number of input vertices = 2. contrl(3) -- Length of intin array = 1. contrl(6) -- Device handle. intin(0) -- Clipping flag. 0 = Turn clipping off. non-zero = Turn clipping on. ptsin(0) -- x-coordinate of corner of the clipping rectangle in NDC/RC units. ptsin(l) -- y-coordinate of corner of the clipping rectangle in NDC/RC units. ptsin(2) -- x-coordinate of corner diagonally across from the corner selected in ptsin(0) of the clipping rectangle in NDC/RC units. ptsin(3) -- y-coordinate of corner diagonally across from the corner selected in ptsin(l) of the clipping rectangle in NDC/RC units. 3-19 ***************************************************************************** GEM VDI Programmer's Guide Set Clipping Rectangle _____________________________________________________________________________ C BINDING Procedure Name vs_clip( handle, clip_flag, pxyarray ) Data Types WORD vs_clip(); WORD handle; WORD clip_flag; WORD pxyarray[4]; Input Arguments handle = contrl[6] clip_flag = intin[0] pxyarray[0] = ptsin[0] pxyarray[1] = ptsin[1] pxyarray[2] = ptsin[2] pxyarray[3] = ptsin[3] End of Section 3 3-20 ***************************************************************************** Section 4 Output Functions _________________________________________________________________________ INTRODUCTION The output functions display graphics primitives (polyline or circle, for example) on devices. __________________________________________________________________________ POLYLINE This function displays a polyline on the graphics device. The starting point for the polyline is the first point in the input array. Lines are drawn between subsequent points in the array. GEM VDI displays a zero length line (degenerate case) as a point. GEM VDI will not display a single coordinate pair. Lines are drawn using the following current line attributes: * color * linetype * line width * end style * current writing mode For wide lines, the first point (ptsin (0) ptsin(l)) is drawn as shown in Figure 4-1. .[--- .<--- .(--- Figure 4-1. First Point for Wide Lines note fig 4 shows that fat lines can be terminated square ended, arrowhead ended or round ended 4-1 **************************************************************************** GEM VDI Programmer's Guide Polyline _________________________________________________________________________ Input contrl(0) -- Opcode = 6. contrl(1) -- Number of vertices (x,y pairs) in polyline = n. (Maximum number is returned in Extended inquire.) contrl(3) -- Length of intin array = 0. contrl(6) -- Device handle. ptsin -- Array of coordinates of polyline in NDC/RC units. ptsin(0) -- x-coordinate of first point in NDC/RC units. ptsin(l) -- y-coordinate of first point in NDC/RC units. ptsin(2) -- x-coordinate of second point in NDC/RC units. ptsin(3) -- y-coordinate of second point in NDC/RC units. ptsin(2n-2) -- x-coordinate of last point in NDC/RC units. ptsin(2n-1) -- y-coordinate of last point in NDC/RC units. ________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout array = 0. 4-2 ************************************************************************** GEM VDI Programmer's Guide Polyline ________________________________________________________________________ C BINDING Procedure Name v_pline( handle, count, pxyarray ) Data Types WORD v_pline(); WORD handle; WORD count; WORD pxyarray[2 * count]; Input Arguments handle = contrl[6] count = contrl[l] pxyarray[0] = ptsin[0] pxyarray[l] = ptsin[l] . . . pxyarray[2n-2] = ptsin[2n-2] pxyarray[2n-1] = ptsin[2n-1] 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(0) -- Opcode = 7. contrl(l) -- Number of markers = n. -- (Maximum number is returned in -- Extended Inquire.) contrl(3) -- Length of intin array = 0. contrl(6) -- Device handle. ptsin -- Array of coordinates in NDC/RC -- units. ptsin(0) -- x-coordinate of first marker in -- NDC/RC units. ptsin(l) -- y-coordinate of first marker in -- NDC/RC units. ptsin(2) -- x-coordinate of second marker in -- NDC/RC units. ptsin(3) -- y-coordinate of second marker in -- NDC/RC units. . . ptsin(2n-2) -- x-coordinate of last marker in NDC/RC units. ptsin(2n-1) -- y-coordinate of last marker in NDC/RC units. ________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout array = 0. 4-4 ************************************************************************** GEM VDI Programmer's Guide Polymarker _________________________________________________________________________ C BINDING Procedure Name v_pinarker( handle, count, PxYarray ) Data Types WOPD v_pmarker ( ); WORD handle; WORD count; WORD pxyarray[2 * count); Input Arguments handle = contrl[6] count = contr[l] pxyarray[0] = ptsin[0] pxyarray[l] = ptsin[l] . . pxyarray[2n-2] = ptsin[2n-2] pxyarray[2n-l] = ptsin[2n-1] 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(0) -- Opcode = 8. contrl(l) -- Number of input vertices = 1. contrl(3) -- Length of intin array = n. contrl(6) -- Device handle. intin -- Character string as ASCII codes in 16-bit words. The maximum number of characters equals the size of the intin array. See Extended Inquire. ptsin(0) -- x-coordinate of alignment point of text in NDC/RC units. ptsin(l) -- y-coordinate of alignment point of text in NDC/RC units. ________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout array = 0. 4-6 **************************************************************************** GEM VDI Programmer's Guide Text __________________________________________________________________________ C BINDING Procedure Name v_gtext( handle, x, y, string ) Data Types WORD v_gtext ( ); WORD handle; WORD x; WORD y; BYTE string[n]; Input Arguments handle = contrl[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(0) -- Opcode = 9. contrl(l) -- Number of vertices in polygon = n. Maximum number returned in Extended Inquire. contrl(3) -- Length of intin array = 0. contrl(6) -- Device handle. ptsin -- Array of coordinates of polygon in NDC/RC units. ptsin(0) -- x-coordinate of first point in NDC/RC units. ptsin(l) -- y-coordinate of first point in NDC/RC units. ptsin(2) -- x-coordinate of second point in NDC/RC units. ptsin(3) -- y-coordinate of second point in NDC/RC units. . . ptsin(2n-2) -- x-coordinate of last point in NDC/RC units. ptsin(2n-1) -- y-coordinate of last point in NDC/RC units. Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout array = 0. 4-9 ************************************************************************** GEM VDI Programmer's Guide Filled Area _______________________________________________________________________________ C BINDING Procedure Name v_fillarea( handle, count, pxyarray ) Data Types WORD v fillarea ( ); WORD handle; WORD count; WORD pxyarray[2 * count]; Input Arguments handle = contrl[6] count = contrl[lj pxyarray[0] = ptsin[0] pxyarray[l] = ptsin[l] . . p;yarray[2n-2] = ptsin[2n-2] pxyarray[2n-11 = ptsin[2n-1] 4-10 ***************************************************************************** GEM VDI Programmer's Guide CLell Array _____________________________________________________________________________ CELL ARRAY With the Cell Array function, the device draws a rectangular array defined by the input parameter (x,y) coordinates and the color index 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. ___________________________________________________________________________ Input contrl(0) -- Opcode = 10. contrl(l) -- Number of input vertices = 2. contrl(3) -- Length of color index array. contrl(6) -- Device handle. contrl(7) -- Length of each row in color index array(size as declared in a high-level language). contrl(8) -- Number of elements used in each row of color index array. contrl(9) -- Number of rows in color index array. contrl(10)-- Pixel operation to be performed. (See Set Writing Mode function in Section 5 for the description of each mode.) intin(0) -- Color index array, stored by row. ptsin(0) -- x-coordinate of lower left corner in NDC/RC units. ptsin(l) -- y-coordinate of lower left corner in NDC/RC units. ptsin(2) -- x-coordinate of upper right corner in NDC/RC units. ptsin(3) -- y-coordinate of upper right corner in NDC/RC units. 4-11 ************************************************************************** GEM VDI Programmer's Guide cell Array ______________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intin array = 0. ______________________________________________________________________________ .C BINDING Procedure Name v_cellarray( handle, pxyarray, row_length, el_used, num_rows, wrt_mode, colarray Data Types WORD v_cellarray( ); WORD handle; WORD pxyarray[4]; WORD row_length; WORD el_used; WORD num_rows; WORD wrt_mode; WORD colarray[num_rows*el_used]; Input Arguments handle = contrl[6] pxyarray[0] = ptsine[0] pxyarray[l] = ptsin[l] pxyarray[21 = ptsin[2] pxyarray[31 = ptsin[3] row_length = contrl[7] el_used = contrl[8] num_rows = contrl[91 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(0) -- Opcode = 103. contrl(l) -- Number of input vertices = 1. contrl(3) -- Length of intin array = 1. contrl(6) -- Device handle. intin(0) -- Color index that defines the contour. ptsin(0) -- x-coordinate of starting point in NDC/RC units. ptsin(l) -- y-coordinate of starting point in NDC/RC units. ___________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout array 0. ____________________________________________________________________________ C BINDING Procedure Name v_contourfill( handle, x, y, index ) Data Types WORD v contourfill( ); WORD handle; WORD x; WORD y; WORD index; Input Arguments handle = contrl[6] x = ptsin[0] y = ptsin[l] 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(0) -- Opcode = 114. contrl(l) -- Number of input vertices = 2. contrl(3) -- Length of intin array = 0. contrl(6) -- Device handle. ptsin(0) -- x-coordinate of corner of destination rectangle in RC/NDC. ptsin(l) -- y-coordinate of corner of destination rectangle in RC/NDC. ptsin(2) -- x-coordinate of corner of destination rectangle in RC/NDC diagonally opposite corner specified in ptsin(O). ptsin(3) -- y-coordinate of corner of destination rectangle in RC/NDC diagonally opposite corner specified in ptsin(l). __________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout array = 0. _____________________________________________________________________________ C BINDING Procedure Name vr_-recfl( handle, pxyarray ) Data Types WORD vr_recfl ( ); WORD handle; WORD pxyarray[4]; Input Arguments handle = contrl[6] pxyarray[0] = ptsin[0] . . . pxyarray[3] = ptsin[3] 4-14 ********************************************************************************* GEM VDI Programmer's Guide GDP _________________________________________________________________________________ GENERALIZED The Generalized Drawing Primitive (GDP) DRAWING PRIMITIVE function allows you to use the predefined (GDP) primitives. The application can draw special elements, such as arcs, circles, and ellipses using this function. The contents of the control and data arrays are different for each GDP. For the arc, pie, elliptical arc, and elliptical pie, the information in the radius, start, and end angle variables defines the GDP. All angle specifications are in tenths of degrees and assume that 0 degrees is 90 degrees to the right of vertical, 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. 900 | | 1800-----|-----0 | | 2700 Figure 4-2. Angle Specification _____________________________________________________________________________ Input contrl(0) Opcode = 11. contrl(l) Number of vertices in ptsin. contrl(3) Length of input array intin. contrl(5) Primitive id. 1 BAR: Uses fill area attributes (fill interior style, style index, wr iting mode, color and perimeter style). 4 CIRCLE: Uses fill area attributes (fill interior style, style index, writing mode, fill color and perimeter style). 4-15 ******************************************************************************** GEM VDI Programmer's Guide GDP _______________________________________________________________________________ 2 ARC: Uses line attributes (color, linetype, writing mode, width, and end styles). 3 PIE: Uses fill area attributes (interior style, writing mode, fill style, fill color, and perimeter style). 5 ELLIPSE: Uses fill area attributes (fill interior style, writing mode, sty1e index, co1or , and perimeter style). 6 ELLIPTICAL ARC: Uses line attributes (color, linetype, writing mode, width, and end styles). 7 ELLIPTICAL PIE: Uses fill area attributes (fill interior style, writing mode, sty1e index, color and perimeter style). 8 ROUNDED RECTANGLE: Uses line attributes (color, linetype, writing mode, and width). 9 FILLED ROUNDED RECTANGLE: Uses fill area attributes (fill interior style, writing mode, sty1e index color, and perimeter style, color, and width). 10 JUSTIFIED GRAPHICS TEXT: Uses text attributes (face, character height, character baseline vector, color index, specia1 effects , and alignment). contrl(6) -- Device handle. ptsin -- Array of coordinates for GDPs in NDC/RC units. ptsin(0) -- x-coordinate of first point in NDC/RC units. ptsin(l) -- y-coordinate of first point in NDC/RC units. ptsin(2) -- x-coordinate of second point in NDC/RC units. 4-16 ******************************************************************************* GEM VDI Programmer's Guide GDP _______________________________________________________________________________ ptsin(3) -- y-coordinate of second point in NDC/RC units. . . . ptsin(2n-2) -- x-coordinate of last point in NDC/RC units. ptsin(2n-1) -- y-coordinate of last point in NDC/RC units. intin -- Angle for arcs and pies or characters for justified graphics text. 4-17 ****************************************************************************** GEM VDI Programmer's Guide BAR ______________________________________________________________________________ BAR Input contrl(0) -- Opcode = 11. contrl(l) -- Number of input vertices = 2. contrl(3) -- Length of intin array = 0. contrl(5) -- Primitive id = 1. contrl(6) -- Device handle. ptsin(0) -- x-coordinate of corner of bar in NDC/RC units. ptsin(l) -- y-coordinate of corner of bar in NDC/RC units. ptsin(2) -- x-coordinate o f corner diagonally opposite the corner selected in ptsin(O) of bar in NDC/RC units. ptsin(3) -- y-coordinate o f corner diagonally opposite the corner selected in ptsin(l) of bar in NDC/RC units. ________________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout array 0. ___________________________________________________________________________________ C BINDING Procedure Name v_bar( handle, pxyarray ) Data Types WORD v_bar ( ); WORD h-andle; WORD pxyarray[4]; Input Arguments handle = contrl[6] pxyarray[0] = ptsin[0] pxyarray[l] = ptsin[l] pxyarray[2] = ptsin[2] pxyarray[3] = 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(0),intin(l)). _________________________________________________________________________________ Input contrl(O) -- Opcode = 11. contrl(l) -- Number of input vertices = 4. contrl(3) -- Length of intin array = 2. contrl(5) -- Primitive id. 2 = ARC 3 = PIE contrl(6) -- Device handle. intin(0) -- Start angle (in tenths of degrees 0-3600), counterclockwise. intin(l) -- End angle (in tenths of degrees 0-3600) . ptsin(0) -- x-coordinate of center point of arc in NDC/RC units. ptsin(l) -- y-coordinate of center point of arc in NDC/RC units. ptsin(2) -- 0. ptsin(3) -- 0. ptsin(4) -- 0. ptsin(5) -- 0. ptsin(6) -- Radius in x-coordinate NDC/RC units. ptsin(7) -- 0. ______________________________________________________________________________ Output contrl(2) -- Number of output veitices = 0. contrl(4) -- Length of intout array = 0. 4-19 ********************************************************************************* GEM VDI Programmer's Guide ARC & PIE C BINDING Procedure Name v_arc( handle, x, y, radius, begang, endang ) v_pieslice( handle, x, y, radius, begang, endang ) Data Types WORD v_arc ( ); WORD handle; WORD x, y; WORD radius; Input Arguments handle = contrl[6] x = ptsin[0] y = ptsin[1] 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(l) -- 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(l) -- y-coordinate of center point of circle in NDC/RC units. ptsin(2) -- 0. ptsin(3) -- 0. ptsin(4) -- Radius in x-coordinate NDC/RC units. ptsin(5) -- 0. __________________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout array = 0. __________________________________________________________________________________ C BINDING Procedure Name v_circle( handle, x, y, radius ) Data Types WORD v_circle ( ); WORD handle; WORD x, y; WORD radius; Input Arguments handle = contrl[6] x = ptsin[0] y = ptsin[l) radius = ptsin[4] 4-21 ********************************************************************************** GEM VDI Programmer's Guide ELLIPTICAL ARC and PIE ____________________________________________________________________________________ ELLIPTICAL ARC AND PIE Input contrl(0) -- Opcode = 11. contrl(l) -- Number of input vertices = 2. contrl(3) -- Length of intin array = 2. contrl(5) -- Primitive id. 6 = ELLIPTICAL ARC 7 = ELLIPTICAL PIE SLICE contrl(6) -- Device handle. intin(0) -- Start angle (in tenths of degrees 0-3600), counterclockwise. intin(l) -- 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) -- Radius of X-axis in NDC/RC units. ptsin(3) -- Radius of Y-axis in NDC/RC units. ____________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout array = 0. 4-22 **************************************************************************** GEM VDI Programmer's Guide ELLIPTICAL ARC and PIE _______________________________________________________________________________ C BINDING Procedure Name v_ellarc( handle, x, y, xradius, yradius, begang, endang ) v_ellpie( handle, x, y, xradius, yradius, begang, endang Data Types WORD v_ellarc ( ); WORD v_ellpie ( ); WORD handle; WORD x, y; WORD xradius; WORD yradius; WORD begang; WORD endang; Input Arguments handle = contrl[6] x = ptsin[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(0) -- Opcode = 11. contrl(l) -- Number of input vertices = 2. contrl(3) -- Length of intin array = 0. contrl(5) -- Primitive id = 5. contrl(6) -- Device handle. ptsin(0) -- x-coordinate of center point of ellipse in NDC/RC units. ptsin(l) -- y-coordinate of center point of ellipse in NDC/RC units. ptsin(2) -- Radius of X-axis in NDC/RC units. ptsin(3) -- Radius of Y-axis in NDC/RC units. ___________________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout array = 0. ___________________________________________________________________________________ C BINDING Procedure Name v_ellipse( handle, x, y, xradius, yradius ) Data Types WORD v ellipse ( ); WORD handle; WORD x, y; WORD xradius; WORD yradius; Input Arguments handle = contrl[6] x = ptsin[0] y = ptsin[l] 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(0) -- Opcode = 11. contrl(l) -- Number of input vertices = 2. contrl(3) -- Length of intin array = 0. contrl(5) -- Primitive id. 8 = Rounded Rectangle 9 = Filled Rounded Rectangle contrl(6) -- Device handle. ptsin(0) -- x-coordinate of corner of rectangle in NDC/RC units. ptsin(1) -- y-coordinate of corner of rectangle in NDC/RC units. ptsin(2) -- x-coordinate of corner diagonally opposite corner selected in ptsin(0) of rectangle in NDC/RC units. ptsin(3) -- y-coordinate of corner diagonally opposite corner selected in ptsin (1) of rectangle in NDC/RC units. __________________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout array = 0. 4-25 *********************************************************************************** GEM VDI Programmer's Guide Rounded and Filled Rounded Rectangle ___________________________________________________________________________________ C BINDING Procedure Name v_rbox( handle, xyarray ) v_rfbox( handle, xyarray) Data Types WORD ( v rbox ); WORD ( v rfbox ); WORD 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 GRAPHICS This function outputs graphics text to the TEXT workstation display surface and attempts to perform both left and right justification. The text string is aligned at the requested string alignment points passed in, using the current text alignment attributes. Extra spacing may be inserted or deleted by the driver between words or characters (or both) so that the string will have the requested length. Either form of spacing modification (inter character or inter-word) can be suppressed by so specifying in the provided parameter. __________________________________________________________________________________ Input contrl(0) -- Opcode = 11. contrl(l) -- Number of input vertices = 2. contrl(3) -- Length of intin array = 2 + n (characters in string). contrl(5) -- Primitive id = 10. contrl(6) -- Device handle. intin(0) -- Inter-word spacing flag. 0 = Doesn't allow GEM VDI to modify inter-word spacing. nonzero = Allows GEM VDI to modify inter-word spacing. intin(l) -- Inter-character spacing flag. 0 = Doesn't allow GEM VDI to modify inter-character spacing. nonzero = Allows GEM VDI to modify inter-character spacing. intin(2) -- First character of text string. . . . intin(n+l) -- Last char;cter of text string. 4-27 ********************************************************************************* GEM VDI Programmer's Guide Justified Graphics Text _________________________________________________________________________________ ptsin(0) -- x-coordinate of the text alignment point, in NDC/RC units. ptsin(l) -- y-coordinate of the text alignment point, in NDC/RC units. ptsin(2) -- Requested length of the string, in x-axis NDC/RC units. ptsin(3) -- 0. _________________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout array = 0. 4-28 *********************************************************************************** GEM VDI Programmer's Guide Justified Graphics Text C BINDING Procedure Name v_justified(handle, x, y, string, length, word_space, char-space); Data Types WORD v_justified ( ); WORD handle; WORD x, y; WORD length; WORD word space; WORD char space; BYTE string[); Input Arguments handle = contrl[6]; x = ptsin[0]; y = ptsin[l]; length = ptsin[2); word_space = intin[0]; char_space = intin[l]; string[j] = intin[j+21; Note: Bytes for the string array are mapped into the eight least significant bits of intin words. Note: The string array must be null terminated. End of Section 4 4-29 ************************************************************************************ Section 5 Attribute Functions _____________________________________________________________________________ INTRODUCTION Attribute functions determine qualities of all subsequent output primitives such as color, type, style, and height. ______________________________________________________________________________ SET WRITING MODE This function selects the writing mode used for subsequent drawing operations. The writing mode specifies the operation performed between the color indices of the current pixel (source) and the existing pixel (destination), thus affecting the way new pixels from lines, markers, filled areas, and text are placed on the display. Four modes exist: replace, transparent, XOR, and reverse transparent. If the requested writing mode is out of range, GEM VDI selects replace mode, 1. Table 5-1 lists the writing modes and their numerical assignments. Table 5-1. Writing Modes Number Mode 1 Replace 2 Transparent 3 XOR 4 Reverse Transparent 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 Reverse transparent mode only affects the Transparent pixels where the mask is 0. These are changed to the fore value. The following is the Boolean expression for reverse transparent mode: new = (old AND mask) OR (fore AND NOT mask) _____________________________________________________________________________ Input contrl(0) -- Opcode = 32. contrl(l) -- Number of input vertices = 0. contrl(3) -- Length of intin array = 1. contrl(6) -- Device handle. intin(0) -- Writing mode requested. _____________________________________________________________________________ Output contrl(2) Number of output vertices 0. contrl(4) Length of intout array intout(0) 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] 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) Opcode = 14. contrl(l) Number of input vertices = 0. contrl(3) Length of intin array = 4. contrl(6) Device handle. intin(0) Color index. intin(l) Red color intensity (in tenths of percent, 0-1000). intin(2) Green color intensity. intin(3) Blue color intensity. _____________________________________________________________________________ Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 0. 5-4 ***************************************************************************** GEM VDI Programmer's Guide Set Color Representation _____________________________________________________________________________ C BINDING Procedure Name vs_color( handle, index, rgb_in ) Data Types WORD vs_color ( ); WORD handle; WORD index; WORD rgb_in[3]; Input Arguments handle = contrl[6] index = intin[0] rgb_in[0] = intin[l] rgb_in[l] = intin[2] rgb_in[21 = intin[3] 5-5 ***************************************************************************** GEM VDI Programmers Guide Set Polyline Line Type SET POLYLINE This Function sets the line type for LINE TYPE 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 1111111111111111 2 long dash 1111111111110000 3 dot 1110000011100000 4 dash,dot 1111111000111000 5 dash 1111111100000000 6 dash,dot,dot 1111000110011000 7 user-defined 16 bits (1 word) style Most Significant Bit = first pixel displayed. 8-n device- dependent Line style seven, user-defined style, uses the pattern the Set User Line Style Pattern function defines. This pattern defaults to solid until the user defines it. Note: 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(0) -- Opcode = 15. contrl(l) -- Number of input vertices = 0. contrl(3) -- Length of intin array = 1. contrl(6) -- Device handle. intin(0) -- Requested line style. _____________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout array = 1. intout(0) -- Line style selected. _____________________________________________________________________________ C BINDING Procedure Name set_type = vsl_type( handle, style ) Data Types WORD set_type WORD vsl_type ( ); WORD handle; WORD style; Input Arguments handle = contrl[6] style = intin[01 Output Arguments set_type = intout[0] 5-7 ***************************************************************************** GEM VDI Programmer's Guide Set User-defined Line Style Pattern _____________________________________________________________________________ SET USER-DEFINED This function sets the current user-defined LIKE STYLE PATTERN line style pattern word in the device driver to the value in the specified 16-bit pattern word. The Most Significant Bit (MSB) of the pattern word is the first pixel in the line. This line style is used for subsequent polyline operations when the application selects user defined line style, index 7. _____________________________________________________________________________ Input contri(0) Opcode = 113. contrl(l) Number of input vertices = 0. contrl(3) Length of intin array = 1. contrl(6) Device handle. intin(0) 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 contrI(0) -- Opcode = 16. contrl(l) -- Number of input vertices = 1. contrl(3) -- Length of intin array = 0. contrl(6) -- Device handle. ptsin(0) -- 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(0) -- 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 set_width = vsl_width( handle, width ) Data Types WORD set_width; WORD vsl_width ( ); WORD handle; WORD width; Input Arguments handle = contrl[6] width = ptsin[0] Output Arguments set-width = ptsout[0] 5-10 ***************************************************************************** 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(0) -- Opcode = 17. contri(l) -- Number of input vertices = 0. contrl(3) -- Length of intin array = 1. contrl(6) -- Device handle. intin(0) -- Requested color index. _____________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout array = 1. intout(0) -- 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 = intin[0] 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(0) -- Opcode = 108. contrl(l) -- Number of input vertices = 0. contrl(3) -- Length of intin array = 2. contrl(6) -- Device handle. intin(0) -- End style for beginning point of polyline. 0 - squared (default) 1 - arrow 2 - rounded intin(l) -- End style for ending point of polyline. 0 - squared (default) 1 - arrow 2 - rounded _____________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout array = 0. 5-12 ***************************************************************************** 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 - . Dot 2 - + Plus 3 - * Asterisk 4 - o Square 5 - X Diagonal Cross 6 - <> Diamond 7 ... n Device-dependent If the requested marker type is out of range, GEM VDI uses an asterisk, type 3. Marker 1 is the smallest dot GEM VDI displays on the device; it cannot be scaled. _____________________________________________________________________________ Input contrl(0) -- Opcode = 18. contrl(l) -- Numbers of input vertices = 0. contrl(3) -- Length of intin array = 1. contrl(6) -- Device handle. intin(0) -- Requested polymarker type. _____________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout array = 1. intout(0) -- Polymarker type selected. 5-14 ***************************************************************************** GEM VDI Programmer's Guide Set Polymarker Type _____________________________________________________________________________ C BINDING Procedure Name set_type = vsm_type( handle, symbol ) Data Types WORD set_type; WORD vsm_type ( ); WORD handle; WORD symbol; Input Arguments handle = contrl[6] symbol = intin[0] Output Arguments set_type = intout[0] 5-15 ***************************************************************************** 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 contri(0) -- Opcode = 19. contrl(l) -- Number of input vertices = 1 contrl(3) -- Length of intin array = 0. contrl(6) -- Device handle. ptsin(0) -- 0. ptsin(l) -- Requested polymarker height in y-axis in NDC/RC units. _____________________________________________________________________________ Output contrl(2) -- Number of output vertices contrl(4) -- Length of intout array = 0. ptsout(O) -- Polymarker width selected in x- axis in NDC/RC units. ptsout(l) -- Polymarker height selected in y- axis in NDC/RC units. _____________________________________________________________________________ C BINDING Procedure Name set_height = vsm_height( handle, height ) Data Types WORD set_height; WORD vsm_height ( ); WORD 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 This function sets the color index for COLOR INDEX subsequent polymarker functions. The Set Color Representation function specifies the value of the index. At least two color indices are always supported (monochrome). If the index is out of range, GEM VDI selects color index 1. _____________________________________________________________________________ Input contrl(0) -- Opcode = 20. contri(l) -- Number of input vertices = 0. contrl(3) -- Length of intin array = 1. contrl(6) -- Device handle. intin(0) -- Requested polymarker color index. _____________________________________________________________________________ Output contrl(2) -- number of output vertices = 0. contrl(4) -- length of intout array = 1. intout(0) -- 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 ***************************************************************************** UrAn VLJ.L rLL)qLat~t=& SET CHARACTER This function sets the current graphic text HEIGHT, character height in NDC/RC units, The ABSOLUTE 140DE specified height is the distance from the character baseline to the top of the character cell, rather than the character cell height. GEM VDI returns the selected height and width information to the application. GEM VDI returns both the distance from the baseline to top line selected and the size of a character cell. (See Figure 5-1 under "Set Character Height, Points Mode.") For fixed (monospaced) faces GEM VDI returns the width of a character and the width of a character cell. For proportional faces, GEM VDI returns the width of the widest character and the width of the widest character cell in the face. If the desired character height does not map exactly to a device size, GEM VDI selects the closest character size that does not exceed the requested size. _____________________________________________________________________________ Input contrl(0) -- Opcode = 12. contrl(l) -- Number of input vertices = 1 contrl(3) -- Length of intin array = 0. contrl(6) -- Device handle. ptsin(0) -- 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 vst_height( handle, height, &char_width, &char_height, &cell_width, &cell_height ) Data Types WORD vst_height ( ); WORD handle; WORD height; WORD char_width; WORD char_height; WORD cell_width; WORD cell_height; Input Arguments handle = contrl[6] height = ptsin[l] Output Arguments 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 This function sets the current graphic text HEIGHT, POINTS character height in printer points. A point MODE is 1/72 of an inch. The specified height is the distance between the baseline of one line of text and the baseline of the next line of text, which is the character cell height. The driver returns the selected point size of the character. Height and width information is returned in NDC/RC units. GEM VDI returns the character height, character width, cell height, and the cell width, as shown in Figure 5-1. For proportional faces, GEM VDI returns the width of the widest character and the widest character cell in the face. If the desired character height does not map exactly to a device size, GEM VDI selects the closest character size not exceeding the requested size. Left Character Right Character Alignment Alignment Delta Delta ____ ____ | | | | ---------------------------|-----------| | | | | | | -------------------- | Character | | | | | | Height | -------------------- | | | |\ /\ /| | | | | | \ / \ / | | | | Cell | | \/ \/ | | | | Height ---------------------------| | | | | | | -------------------- | ---------------------------------------| ______________ Character Width _____________________ Cell Width Figure 5-1. Character Cell Definition _____________________________________________________________________________ Input contrl(0) -- Opcode = 107. contrl(l) -- Number of input vertices = 0. contrl(3) -- Length of intin array = 1. contrl(6) -- Device handle. intin(0) -- Cell height in points. 5-20 ***************************************************************************** GEM VDI Programmer's Guide Set Character Height, Points Mode Output contrl(2) -- Number of output vertices = 2. contrl(4) -- Length of intout array = 1. intout(0) -- Selected cell height in points. ptsout(0) -- 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. _____________________________________________________________________________ C BINDING Procedure Name set_point = vst_point( handle, point, &char_width, &char_height, &cell_width, &cell_height Data Types WORD set_point; WORD vst_point ( ); WORD handle; WORD point; WORD char_width; WORD char_height; WORD cell_width; WORD cell_height; Input Arguments handle = contrl[6] point = intin[0] Output Arguments set-point ( ) = intout[0] char_width = ptsout[0] char_height = ptsout[l] 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 Note: This function is not required and may not be supported on all devices. The Extended Inquire function returns the availability of this function. _____________________________________________________________________________ Input contrl(0) -- Opcode = 13. contrl(l) -- Number of input vertices = 0. contrl(3) -- Length of intin array = 1. contrl(6) -- Device handle. intin(0) -- Requested angle of rotation of character baseline (in tenths of degrees, 0 - 3600). _____________________________________________________________________________ Output contrl(2) -- Number of output vertices 0. contrl(4) -- Length of intout array = intout(0) -- 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 = intin[0] 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. _____________________________________________________________________________ Input contrl(0) -- Opcode = 21. contrl(l) -- Number of input vertices = 0. contrl(3) -- Length of intin array = 1. contrl(6) -- Device handle. intin(0) -- 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. 5-24 ***************************************************************************** GEM VDI Programmer's Guide get Text Face _____________________________________________________________________________ C BINDING Procedure Name set_font = vst_font( handle, font ) Data Types WORD set_font; WORD vst_font ( ); WORD handle; WORD font; Input Arguments handle = contrl[6] font = intin[0] Output Arguments 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) -- Opcode = 22. contrl(l) -- Number of input vertices = 0. contrl(3) -- Length of intin array = 1. contrl(6) -- Device handle. intin(0) -- Requested text color index. _____________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout array = 1. intout(0) -- 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 This function sets text special effects for SPECIAL EFFECTS subsequently displayed graphic text. The following effects are available: * thickened * light intensity * skewed * underlined * outlined * shadowed * any combination of the above GEM VDI treats the integer in intin (0) as a bit pattern. The attributes set correspond to the setting in the six least significant bits. Table 5-3. Attribute Bit Mapping 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) -- Opcode = 106. contrl(l) -- Number of input vertices = 0. contrl(3) -- Length of intin array = 1. contrl(6) -- Device handle. intin(0) -- Special effect word. _____________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout array = 1. intout(0) -- Styles actually selected (style word with the appropriate bits set). Normal (sample ABCDE) Thickened (sample ABCDE) Light Intensity (sample ABCDE) Skewed (sample ABCDE) Underlined (sample ABCDE) Figure 5-3. Graphic Text Special Effects 5-28 ***************************************************************************** GEM VDI Programmer's Guide Set Graphic Text Special Effects _____________________________________________________________________________ C BINDING Procedure Name set_effect = vst_effects( handle, effect ) Data Types WORD set_effect; WORD vst_effects( ); WORD handle; WORD effect; Input Arguments handle = contrl[6] effect = intin[0] Output Arguments set_effect = intout[0] 5-29 ***************************************************************************** GEM VDI Programmer's Guide Set Graphic Text Alignment _____________________________________________________________________________ SET GRAPHIC TEXT This function sets horizontal and vertical ALIGNMENT 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. ______________________________Top Line ______________________________Ascent Line _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ Half Line ______________________________Base Line ______________________________Descent Line Leading|______________________________Bottom Line Top Line |______________________________Ascent Line _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ Half Line ______________________________Base Line ______________________________Descent Line ______________________________Bottom Line Figure 5-4. Graphic Text Alignment 5-30 ***************************************************************************** GEM VDI Programmer's Guide Set Graphics Text Alignment _____________________________________________________________________________ Input contrl(0) -- Opcode = 39. contrl(l) -- Number of input vertices = 0. contrl(3) -- Length of intin array = 2. contrl(6) -- Device handle. intin(0) -- 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) -- Number of output vertices = 0. contrl(4) -- Length of intout array = 2. intout(0) -- Horizontal alignment selected. intout(l) -- Vertical alignment selected. _____________________________________________________________________________ C BINDING Procedure Name vst_alignment( handle, hor_in, vert_in, &hor_out, &vert_out ) Data Types WORD vst_alignment( ); WORD handle; WORD hor_in; WORD vert_in; WORD hor_out; WORD vert_out; Input Arguments handle = 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 IMTERIOR This function sets the fill interior style STYLE used in subsequent polygon fill operations. If the application requests an unavailable style, the area is hollow filled. GEM VDI returns the selected style to the application. Hollow style fills the interior with the current background color(index 0). Solid style fills the area with the currently selected fill color. _____________________________________________________________________________ Input contrl(0) -- Opcode = 23. contrl(l) -- Number of input vertices = 0. contrl(3) -- Length of intin array = 1. contrl(6) -- Device handle. intin(0) -- Requested fill interior style. 0 - hollow 1 - solid 2 - pattern 3 - hatch 4 - user-defined style _____________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout array = 1 intout(0) -- 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 = intin[0] Output Arguments set_interior = intout[0] 5-32 ***************************************************************************** GEM VDI Programmer's Guide Set Fill Style Index SET FILL STYLE This function selects a fill style based on INDEX the fill interior style. This index has no effect if the interior style is hollow, solid, or user-defined. Indices range from 1 to a device-dependent maximum. If the requested index is not available, GEM VDI uses index style 1. The index references a hatch style if the selected fill interior style is hatch, or a pattern if the selected interior fill style is pattern. Figure 5-5 shows the available fill styles. Under each rectangle in Figure 5-5 are two numbers, separated by a comma. The number to the left of the comma corresponds to the style: Hollow, Pattern, or Hatch. The number to the right of the comma corresponds to the index for the particular pattern or hatch. 0,n 2,8 2,16 2,24 3,8 2,1 2,9 2,17 3,1 3,9 2,2 2,10 2,18 3.2 3,10 2,3 2,11 2,19 3,3 3,11 2,4 2,12 2,20 3,4 3,12 2,5 2,13 2,21 3,5 2,6 2,14 2,22 3,6 2,7 2,15 2,23 3,7 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(0) -- Opcode = 24. contrl(l) -- Number of input vertices = 0. contrl(3) -- Length of intin array = 1. contrl(6) -- Device handle. intin(0) -- Requested fill style index for pattern or hatch fill. _____________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout array = 1. intout(0) -- 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 device-dependent maximum. If the requested index is out of range, GEM VDI selects color index 1. _____________________________________________________________________________ Input contrl(0) -- Opcode = 25. contrl(l) -- Number of input vertices = 0. contrl(3) -- Length of intin array = 1 contrl(6) -- Device handle. intin(0) -- Requested fill color index. _____________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout array = 1. intout(0) -- 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 This function turns the outline of a fill VISIBILITY area on or off. When visibility is on (the default at Open Workstation) the border of a fill area is drawn in the current fill area color with a solid line. When visibility is off, no outline is drawn. Any nonzero value of the visibility flag causes the perimeter to be visible. _____________________________________________________________________________ Input contrl(0) -- Opcode = 104. contri(l) -- Number of input vertices = 0. contrl(3) -- Length of intin array = 1. contrl(6) -- Device handle. intin(0) -- Visibility flag. zero - invisible nonzero- visible _____________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout array 1. intout(0) -- 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_perimeter = 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 contri(0) -- Opcode = 112. contri(l) -- Number of input vertices = 0. contrl(3) -- Length of intin array = 16 to n. contrl(6) -- Device handl@. intin(0) 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 vsf_udpat( handle, pfill_pat, planes ) Data Types WORD vsf_udpat ( ); WORD handle; WORD pfill_pat[16 x n where n > 0] WORD planes; Input Arguments handle = contrl[6] pfill_ . . . pfill_pat planes = contrl[3]/16 End of Section 5 5-38 ***************************************************************************** Section 6 Raster Operations _____________________________________________________________________________ INTRODUCTION Raster operations perform logic operations on rectangular blocks of bits in memory and on rectangular blocks of pixels on physical devices. _____________________________________________________________________________ MEMORY FORM A raster area is definedby a Memory Form DEFINATION BLOCK 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 the 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, diided 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 boundry and have a width that is an integral multiple of the word size. 6-1 ***************************************************************************** GEM VDI Programmers Guide Memory Form Definition Block _____________________________________________________________________________ One word (16 bits) Word 1 Memory pointer word 1 Word 2 Memory pointer word 2 Word 3 Form Width in Pixels Word 4 Form Height in Pixels Word 5 Form Width in Words Word 6 Form format flag Word 7 Number of Memory Planes Word 8 Reserved for future use Word 9 Reserved for future use Word 10 Reserved for future use Figure 6-1. Memory Form Definition Block _____________________________________________________________________________ RASTER AREA Two memory formats are associated with raster FORMATS areas: * device-specific format * well-defined standard format GEM VDI provides a function to transform a raster area from one format to another. You must transform a form before using Copy Raster. The form format flag can have two values: 0 - The form is in device-specific format. 1 - The form is in standard format. The layout of a standard form format is as follows (see also Figure 6-2): 6-2 ***************************************************************************** GEM VDI Programmers 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 000 0 white 001 2 red 010 3 green 011 6 yellow 100 4 blue 101 7 magenta 110 5 cyan 111 1 black 6-3 ***************************************************************************** GEM VDI Programmers Guide Raster Area Formats Table 6-1. Pixel Value to Color Index Mapping for 8-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 colour. 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 Stems _____________________________________________________________________________ Msb Word 1 Plane 1 Word 1 Msb Lsb Msb Word 1 Plane 2 Msb Word 1 Plane 3 Pixel value of Word 2 Pixel at (0,0) 0,0 Raster Coord Raster Space Coordinates Space Standard Standard Monochrome Form Color Form (3 Planes) Figure 6-2. Standard Forms (0,0) (15,0) (0,7) (15,7) (3,1) (6,5) Figure 6-3. Sample Single Plane Memory Form 6-5 ***************************************************************************** GEM VDI Programmer's Guide Logic Operations _____________________________________________________________________________ LOGIC OPERATIONS To provide greatest flexibility, raster operations subject to a logic operation take the operation as an argument rather than using the logic operation associated with vector primitives. In addition, the operations available are greatly expanded to allow more flexibility. Table 6-3 lists the available operations with the following conventions: * S = pixel value (0 or 1) of source pixel * D = pixel value (0 or 1) of destination pixel * D'= destination pixel value after the logical operation Table 6-3. Raster Operation Logic Operations Mode Definition 0 D'= 0 1 D'= S AND D 2 D'= S AND [NOT D] 3 D'= S ( Replace mode ) 4 D'= [NOT S] AND D ( Erase mode ) 5 D'= D 6 D'= S XOR D ( XOR mode ) 7 D'= S OR D 8 D'= NOT [S OR D] 9 D'= NOT [S XOR D] 10 D'= NOT D 11 D'= S OR [NOT D] 12 D'= 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, This function copies a rectangular raster OPAQUE area from source form to destination form using the logic operation the application specifies. If the source and destination forms are the same, and the rectangles overlap, GEM VDI copies so that the source rectangle is not changed until GEM VDI processes the corresponding area in the destination. No rotation or transformation occurs as a result of this function; the copy is pixel for pixel. If the source and destination rectangles are not the same size, GEM VDI uses the destination as a pointer and uses the source for the size. The Extended Inquire function returns scaling ability. The source and destination forms must be in device-specific form; see "Transform Form" later in this section. _____________________________________________________________________________ Input contrl(0) -- Opcode = 109. contrl(l) -- Number of input vertices = 4. contrl(3) -- Length of intin array = 1. contrl(6) -- Device handle. contrl(7-8) -- Double-word address of the source Memory Form Definition Block. contrl(9-10)-- Double-word address of the destination Memory Form Definition Block. intin(0) -- Logic operation ( refer to "Introduction" in this section) - ptsin(0) -- x-coordinate of corner of source rectangle in RC/NDC. ptsin(l) -- y-coordinate of corner of source rectangle in RC/NDC. ptsin(2) -- x-coordinate of corner diagonally opposite corner selected in ptsin(0) of source rectangle in RC/NDC. ptsin(3) y-coordinate of corner diagonally opposite corner selected in ptsin(l) of source rectangle in RC/NDC. 6-7 ***************************************************************************** GEM VDI Programmer's Guide Copy Raster, Opaque _____________________________________________________________________________ ptsin(4) -- x-coordinate of corner of destination rectangle in RC/NDC. ptsin(5) -- y-coordinate of corner of destination rectangle in RC/NDC. ptsin(6) -- x-coordinate of corner of destination rectangle in RC/NDC. ptsin(7) y-coordinate of corner of destination rectangle in RC/NDC. _____________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout array = 0. _____________________________________________________________________________ C BINDING Procedure Name vro_cpyfm( handle, wr_mode, pxyarray, psrcMFDB, pdesMFDB ) Data Types WORD vro_cpyfm ( ); WORD handle; WORD wr mode; WORD pxyarray[8]; WORD *PsrcMFDB; WORD *pdesMFDB; Input Arguments handle = contrl[6] wr mode = intin[0] pxyarray[0] = ptsin[0] pxyarray[l] = ptsin[l] . . . p;yarray[7] = ptsin[7] psrcMFDB = contrl[7-8] pdesMFDB = contrl[9-10] 6-8 ***************************************************************************** GEM VDI Programmer's Guide Copy Raster, Transparent _____________________________________________________________________________ COPY RASTER, This function copies a monochrome rectangular TRANSPARENT raster area from source form to a color area. A writing mode and color indices for both 0's and 1's are specified in the intin array. If the source and destination rectangles are not the same size, GEM VDI uses the source rectangle for the size and the upper left corner of the destination rectangle for the initial destination location. Transfer of information from the source to the destination is controlled by the specified writing mode as described below. See Table 5-1 for a binding of the available writing modes. _____________________________________________________________________________ Replace Mode Replace mode will result in a replacement of all pixels in the destination rectangle. The foreground color index specified in intin(l) will be output to all pixels associated with source locations which are set to a one. The background color index specified in intin(2) will be output to all pixels associated with source locations which are set to a zero. _____________________________________________________________________________ Transparent Mode Transparent mode only affects the pixels associated with a source value of one. Those pixels are set to the foreground color whose index is specified in intin(l). The color index specified in intin(2) is not used. _____________________________________________________________________________ XOR Mode In XOR mode, the monochrome raster source area is logically XORed with each plane of the destination. The color indices specified in intin(l) and intin(2) are not used. 6-9 ***************************************************************************** GEM VDI Programmer's Guide Copy Raster, Transparent Reverse Reverse Transparent mode only affects the Transparent pixels associated with a source value of Mode zero. Those pixels are set to the background color whose index is specified in intin(2). The color index specified in intin(l) is not used. _____________________________________________________________________________ Input contri(0) -- Opcode = 121. contrl(l) -- Number of input vertices = 4. contrl(3) -- Length of intin array = 3. contrl(6) -- Device handle. ' contrl(7-8) -- Double-word address of the source Memory Form Definition Block. contrl(9-10)-- Double-word address of the destination Memory Form Definition Block. intin(0) -- Writing Mode. intin(l) -- Color index for ls in data. intin(2) -- Color index for Os in data. ptsin(0) -- x-coordinate of corner of source rectangle in RC/NDC. ptsin(l) -- y-coordinate of corner of source rectangle in RC/NDC. ptsin(2) -- x-coordinate of corner diagonally opposite corner selected in ptsin(0) of source rectangle in RC/NDC. ptsin(3) -- y-coordinate of corner diagonally opposite corner selected in ptsin(l) of source rectangle in RC/NDC. ptsin(4) -- x-coordinate of corner of destination rectangle in RC/NDC. ptsin(5) -- y-coordinate of corner of destination rectangle in RC/NDC. ptsin(6) -- x-coordinate of corner of destination rectangle in RC/NDC. ptsin(7) -- y-coordinate of corner of destination rectangle in RC/NDC. 6-10 ***************************************************************************** GEM VDI Programmer's Guide Copy Raster, Transparent _____________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout array = 0. _____________________________________________________________________________ C BINDING Procedure Name vrt_cpyfm( handle, wr_mode, pxyarray, psrcMFDB, pdesMFDB, color_index ) Data Types WORD vrt_cpyfm ( ); WORD handle; WORD wr_mode; WORD pxyarray[8]; WORD *psrcMFDB; WORD *PdesMFDB; WORD color-index[2]; Input Arguments handle = contrl[6] wr_mode = intin[0] pxyarray[0] = ptsin[0] pxyarray[1] = ptsin[1] . . . P;Yarray[7] = ptsin[7] psrcMFDB = contrl[7-8] pdesMFDB = contrl[9-10] color index[0] = intin[1] color_index[1] = 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(0) -- Opcode = 110. contrl(1) -- Number of input vertices = 0. contrl(3) -- Length of intin array = 0. contrl(6) -- Device handle. contrl(7-8) -- Double-word address of the source MFDB. contrl(9-10)-- Double-word address of the destination MFDB. _____________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout array = 0. _____________________________________________________________________________ C 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(0) 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(0) -- 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 contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout array = 2. intout(0) -- Pixel value. intout(1) -- Color index. 6-13 ***************************************************************************** GEM VDI Programmer's Guide Get Pixel _____________________________________________________________________________ C BINDING Procedure Name v_get_pixel( handle, x, y, pel, index ) Data Types WORD v_get_pixel( ); WORD handle; WORD x; WORD y; WORD *pel; WORD *index; Input Arguments handle = contrl[6] x = ptsin[0] y = ptsin[l] Output Arguments 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 contrl(0) -- Opcode = 33. contrl(l) -- Number of input vertices = 0. contrl(3) -- Length of intin array = 2. contrl(6) -- Device handle. intin(0) -- 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 contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout array = 1 intout(0) -- Input mode selected. _____________________________________________________________________________ C BINDING Procedure Name vsin_mode( handle, dev_type, mode ) Data Types WORD vsin_mode ( ); WORD handle; WORD dev_type; WORD mode; Input Arguments handle = contrl[6] dev_type = intin[0] mode = intin[l] 7-2 ***************************************************************************** GEM VDI Programmer's Guide Input Locator, Request Mode INPUT 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(0) Opcode = 28. contrl(l) Number of input vertices = 1. contrl(3) Length of intin array = 0. contrl(6) Device handle. ptsin(0) 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) -- Number of output vertices = 1. contrl(4) -- Length of intout array = 1. intout(0) -- Locator terminator. The low byte contains a character terminator. For keyboard-terminated locator input, this is the ASCII character code of the key struck to terminate input. For nonkeyboard-terminated input (tablet, mouse, and so on), valid locator terminators begin with 20 Hex (space) and increase from there. For instance, if the puck on a tablet has 4 buttons, the first button must generate a 20 Hex as a terminator, the second a 21 Hex, the third a 22 Hex, and the fourth a 23 Hex. ptsout(0) -- Final x-coordinate of locator in NDC/RC units. ptsout(l) -- Final y-coordinate of locator in NDC/RC units. 7-4 ***************************************************************************** GEM VDI Programmer's Guide Input Locator, Request Mode _____________________________________________________________________________ C BINDING Procedure Name vrq_locator( handle, x, y, &xout, &Yout, &term ) Data Types WORD vrq_locator ( ); WORD handle; WORD x, y; WORD xout; WORD yout; WORD term; Input Arguments handle = contrl[6] x = ptsin[0] y = ptsin[l] Output Functions xout = ptsout[0] yout = ptsout[l] term = intout[0] 7-5 ***************************************************************************** GEM VDI Programmer's Guide Input Locator, Sample Mode INPUT LOCATOR, This function returns the position in NDCs SAMPLE MODE of the specified locator device. Upon entry to the locator routine, no cursor is displayed. (Use Show Cursor to display the cursor. ) Input is sampled. If the cursor position has changed, GEM VDI returns the cursor position and contrl(2) is set to 1. Contrl(4) is set to 0 . If a terminating event occurred, GEM VDI returns a character and contrl(4) is set to 1. Contrl(2) is set to 0. Note: If both a keyboard and another locator device are available, the input comes from either, giving the user maximum flexibility. _____________________________________________________________________________ Input contri(0) Opcode = 28. contrl(l) Number of input vertices = 1. contrl(3) Length of intin array = 0. contrl(6) Device handle. ptsin(0) 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 Array (2) (4) Coordinates change. 1 0 Key pressed; coordinates 0 1 not changed from what was pressed. No input. 0 0 Key pressed; coordinates 1 1 changed. intout(0) -- Locator keypress if keypress occurs. This information is the same as for Input Locator, Request Mode function. ptsout(0) -- New x-coordinate of locator in NDC/RC units. ptsout(l) -- New y-coordinate of locator in NDC/RC units. 7-7 ***************************************************************************** GEM VDI Programmer's Guide Input Valuator, Sample Mode _____________________________________________________________________________ C BINDING Procedure Name status = vsm_ locator( handle, x, y, &xout, &yout, &term ) Data Types WORD status; WORD vsm_locator ( ); WORD handle; WORD x, y; WORD xout; WORD yout; WORD term; Input Arguments handle = contrl[6] x = ptsin[0] y = ptsin[l] Output Arguments 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(0) -- Opcode = 29. contrl(l) -- Number of input vertices = 0. contrl(3) -- Length of intin array = 1 contrl(6) -- Device handle. intin(0) -- Initial value. _____________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout array = 2. intout(0) -- Output value. intout(l) -- Terminator. 7-9 ***************************************************************************** GEM VDI Programmer's Guide Input Valuator, Request Mode C BINDING Procedure Name vrq_valuator( handle, valuator_in, &valuator_out, &terminator ) Data Types WORD vrq_valuator ( ); WORD handle; WORD valuator_in; WORD valuator_out; WORD terminator; Input Arguments handle = contrl[6] valuator_in = intin[0] Output Arguments valuator_out = intout[0] terminator = intout[l] 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(0) -- Opcode = 29. contrl(l) -- Number of input vertices = 0. contrl(3) -- Length of intin array = 1. contrl(6) -- Device handle. intin(0) -- Initial value. _____________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout array. 0 = nothing happened 1 = valuator changed 2 = keypress character intout(0) -- New valuator value. intout(l) -- Keypress, if keypress event occurred. 7-11 ***************************************************************************** GEM VDI Programmer's Guide Input Valuator, Sample Mode _____________________________________________________________________________ C BINDING Procedure Name vsm_valuator( handle, val_in, &val_out, &term, &status ) Data Types WORD vsm_valuator ( ); WORD handle; WORD val_in; WORD val_out; WORD term, WORD status; Input Arguments handle = contrl[6] val_in = intin[0] Output Arguments 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(0) -- Opcode = 30. contrl(l) -- Number of input vertices = 0. contrl(3) -- Length of intin array = 1. contrl(6) -- Device handle. intin(0) -- Initial choice number. _____________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout array 1. intout(0) -- Choice number. _____________________________________________________________________________ C BINDING Procedure Name vrq_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, This function returns the choice status of SAMPLE MODE the selected choice device. Upon entry to the routine, GEM VDI samples input. If input is available and is a valid choice key, GEM VDI returns it. Choice numbers range from 1 to a device-dependent maximum value. Note: This function is not required and may not be available on all devices. _____________________________________________________________________________ Input contri(0) -- Opcode = 30. contrl(l) -- Number of input vertices = 0. contrl(3) -- Length of intin array = 0. contrl(6) -- Device handle. _____________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- 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 handle = contrl[6] Output Arguments choice = intout[0] status = contrl[4] 7-14 ***************************************************************************** GEM VDI Programmer's Guide Input String, Request Mode _____________________________________________________________________________ INPUT STRING, This function returns a string from the REQUEST MODE specified device. Input is accumulated until GEM VDI encounters a carriage return or the intout array is full. If the application enables echo mode, text will be echoed to the screen with the current text attributes using the vertex passed in the ptsin array as the justification point. If the number in intin(0) is negative, the values in intout will conform to the standard keyboard defined in Appendix D. In this case, the absolute value of intin(0) is used as the maximum intout size. Note. Echoing of input is not required and may not be available on all devices. _____________________________________________________________________________ Input contrI(0) -- Opcode = 31. contri(l) -- Number of input vertices = 1. contrl(3) -- Length of intin array = 2. contrl(6) -- Device handle. intin(O) -- Maximum string length. intin(l) -- Echo mode. 0 = no echo 1 = echo input characters at position specified ptsin(0) -- x-coordinate of echo area in NDC/RC units. ptsin(l) -- y-coordinate of echo area in NDC/RC units. _____________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout array. intout -- Output string returned in ADE. 7-15 ***************************************************************************** GEM VDI Programmer's Guide Input String, Request Mode _____________________________________________________________________________ C BINDING Procedure Name vrq_string( handle, max_length, echo_mode, echo_xy, &string ) Data Types WORD vrq_string ( ); WORD handle; WORD max_length; WORD echo_mode; WORD echo_xy[2]; BYTE string[max_length+l]; Input Arguments handle = contrl[6] max_length = intin[0] echo_mode = intin[l] echo_x,y = ptsin[0-1] Output Arguments string = intout Note: The BYTE array elements contain the eight least significant bits of the intout array elements. The array is terminated with a null byte. The length of the output variable string includes an additional byte for the terminating null. 7-16 ***************************************************************************** GEM VDI Programmer's Guide Input String, Sample Mode INPUT STRING, This function returns a string from the SAMPLE MODE specified device. Upon entry to the routine, GEM VDI samples input. If data is available, it is accumulated, and GEM VDI samples the input again. Input is accumulated until one of the following events occurs: * Data is no longer available. * A carriage return is encountered. * The intout buffer is full. Note: If the string will always be terminated with RETURN, use Input String, Request Mode. If the number in intin(0) is negative, the values in intout will conform to the standard keyboard defined in Appendix D. In this case, the absolute value of intin(0) is used as the maximum intout size. _____________________________________________________________________________ Input contrl(0) -- Opcode = 31. contrl(l) -- Number of input vertices = 1. contrl(3) -- Length of intin array = 2. contrl(6) -- Device handle. intin(0) -- Maximum string length. intin(l) -- Echo mode. 0 = no echo 1 = echo input characters ptsin(0) -- x-coordinate of echo area in NDC/RC units. ptsin(l) -- y-coordinate of echo area in NDC/RC units. _____________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of output string. 0 = sample unsuccessful (characters not available) >0 = sample successful (characters available) intout -- Output string, if sample successful. 7-17 ***************************************************************************** GEM VDI Programmer's Guide Input String, Sample Mode _____________________________________________________________________________ C BINDING Procedure Name status = vsm_string( handle, max_length, echo_-mode, echo_xy, &string ) Data Types WORD vsm_string ( ); WORD handle; WORD max_length; WORD echo_mode; WORD echo_xy[21; BYTE string[max_length+l]; WORD status; Input Arguments handle = contrl[6] max_length = intin[0] echo_mode = intin[l] echo_xy = ptsin[0-1] Output Arguments 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. ls in the mask cause the corresponding pixel to be set to the color index defined in intin(3). 3. ls in the mouse form data cause the corresponding pixel to be set to the color index defined in intin(4). _____________________________________________________________________________ Input Contrl(0) -- Opcode = 111. Contrl(l) -- Number of input vertices = 0. Contrl(3) -- Length of intin array = 37. Contrl(6) -- Device Handle. intin(0) -- x-coordinate of hot spot. intin(l) -- y-coordinate of hot spot. intin(2) -- Reserved for future use, must be 1. intin(3) -- Mask color index, normally 0. intin(4) -- Data color index, normally 1. intin(5-20) -- 16 words of 16-bit cursor mask. intin(21-36)-- 16 words of 16-bit cursor data. _____________________________________________________________________________ Output Contrl(2) -- Number of output vertices = 0. Contrl(4) -- Length of intout array = 0. 7-19 ***************************************************************************** GEM VDI Programmer's Guide Set Mouse Form _____________________________________________________________________________ C BINDIING 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 _____________________________________________________________________________ EXCRANGE TIKER With this function, the application can INTERRUPT VECTOR perform some action each time a timer tick occurs. The input to this function is a two-word pointer in contrl(7) and contrl(8). The pointer indicates the starting address of the code to receive control when a timer tick occurs. The address of the old timer routine is returned in contrl(9) and contrl(10). The app1ication-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(0). _____________________________________________________________________________ Input contrl(0) -- Opcode = 118. contrl(l) -- Number of input vertices = 0. contrl(3) -- Length of intin array = 0. contrl(6) -- Device handle. contrl(7-8) -- Address of application timer -- routine. Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout array = 1. contrl(9-10)-- Address of the old timer routine. intout(0) -- Milliseconds per tick. 7-21 ***************************************************************************** GEM VDI Programmer's Guide Exchange Timer Interrupt Vector _____________________________________________________________________________ C BINDING Procedure Name vex_timv( handle, tim_addr, otim_addr, &tim_conv ) Data Types WORD vex_ timv ( ); WORD handle; WORD *tim_addr; WORD *otim_addr; WORD tim_conv; Input Arguments handle = contrl[6] tim_addr = contrl[7-8] Output Arguments otim_addr = contrl[9-10] tim_conv - intout[0] 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(0). If intin(0) is zero, the cursor appears on the screen, regardless of the number of Hide Cursor calls. A nonzero value for intin(0) affects the Show Cursor function as described in the preceding paragraph. _____________________________________________________________________________ Input contrl(0) -- Opcode = 122. contrl(l) -- Number of input vertices = 0. contrl(3) -- Length of intin array = 1. contrl(6) -- Device handle. intin(0) -- Reset flag. 0 = ignore number of Hide Cursor calls nonzero = normal Show Cursor functionality _____________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout array = 0. 7-23 ***************************************************************************** GEM VDI Programmer's Guide Show Cursor _____________________________________________________________________________ C BINDING Procedure Name v_show_c( handle, reset ) Data Types WORD v_show_c ( ); WORD handle; WORD reset Input Arguments handle = contrl[6] reset = intin[0] 7-24 ***************************************************************************** GEM VDI Programmer's Guide Hide Cursor _____________________________________________________________________________ HIDE CURSOR This function removes the cursor from the display surface. This state is the default condition set at Open Workstation. The cursor can appear in a new position when the application calls the Show Cursor function because GEM VDI updates the position based on information input from a mouse. Refer to the Show Cursor function for a description of how the number of Hide Cursor calls affects the Show Cursor function. _____________________________________________________________________________ Input contrl(0) -- Opcode = 123. contrl(l) -- Number of input vertices = 0. contrl(3) -- Length of intin array = 0. contrl(6) -- Device handle. _____________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout array = 0. _____________________________________________________________________________ C BINDING Procedure Name v_hide_c( handle ) Data Types WORD v_hide_c ( ); WORD handle; Input Arguments handle = contrl[6] 7-25 ***************************************************************************** GEM VDI Programmer's Guide Sample Mouse Button State _____________________________________________________________________________ SAMPLE MOUSE This function returns the current state of HUTTON STATE the mouse buttons. The leftmost mouse button is returned in the Least Significant Bit of the word. A bit value of 1 indicates the key is currently depressed; a bit value of 0 indicates the key is up. This function also returns the current (x,y) position of the cursor. _____________________________________________________________________________ Input contrl(0) -- Opcode = 124. contrl(l) -- Number of input vertices = 0. contrl(3) -- Length of intin array = 0. contrl(6) -- Device handle. _____________________________________________________________________________ Output contrl(2) -- Number of output vertices = 1. contrl(4) -- Length of intout array = 1. intout(0) -- Mouse button state. ptsout(0) -- x position of cursor in NDC/RC units. ptsout(l) -- 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 = ptsout[l] 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(10) return a two-word pointer to the old mouse routine. Control is passed to the specified address whenever the mouse button state changes. The application code is invoked via a processor dependent call instruction with a processor dependent register containing the mouse button keys. Keys are encoded by the same rules that apply to the Sample Mouse Button State function. When complete, the application dependent code should do a processor -dependent return instruction with the mouse button state the driver is to store in the same register. This gives the application the opportunity to alter the buttons before they are used by the driver. It is the responsibility of the application dependent code to save and restore any registers used. When the application code is invoked, interrupts are disabled. The application should not enable interrupts. See Appendix E for processor-specific instructions and register names. _____________________________________________________________________________ Input Contrl(0) -- Opcode = 125. Contrl(l) -- Number of input vertices = 0. Contrl(3) -- Length of intin array = 0. Contrl(6) -- Device handle. Contrl(7-8) -- Address of application mouse button state change routine. 7-27 ***************************************************************************** GEM VDI Programmer's Guide Exchange Button Change Vector _____________________________________________________________________________ Output Contrl(2) -- Number of output vertices = 0. Contrl(4) -- Length of intout array =0. Contrl(9-10)-- Address of old mouse button state change routine. _____________________________________________________________________________ C BINDING Procedure Name vex_butv( handle, pusrcode, psavcode ) Data Types WORD vex_butv ( ); WORD handle; WORD *pusrcode; WORD *psavcode; Input Arguments handle = contrl[6] pusrcode = contrl[7-8] Output Arguments 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 contrl(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(0) -- 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 This function allows the application to CHANGE VECTOR perform some action each time the cursor is drawn. The application can completely take over drawing the cursor or can perform some action and have GEM VDI draw the cursor. Control is passed to the application whenever the cursor position should be updated. The input to this function is a two-word pointer in contrl(7) and contrl(8), which indicates the starting address of the code to receive control when a cursor is drawn. The address of the old cursor draw routine is returned in contrl(9) and contrl(10). The application-dependent code is invoked with a processor-dependent call instruction. The x,y position at which the cursor should be drawn is contained in a pair of processor dependent registers. If the application dependent code does not draw its own cursor, a processor-dependent call should be performed to the address returned in contrl(9) and contrl(10). This will cause GEM VDI to draw a cursor. When it is done, the application should perform a processor-dependent return instruction. It is the responsibility of the application dependent code to save and restore any registers used. The GEM VDI cursor draw routine preserves the contents of all registers. When the application code is invoked, interrupts are disabled. The application should not enable interrupts. See Appendix E for processor-specific instructions and register names. 7-31 ***************************************************************************** GEM VDI Programmer's Guide Exchange Cursor Change Vector _____________________________________________________________________________ Input contrl(0) -- Opcode = 127. contrl(l) -- Number of input vertices = 0. contrl(3) -- Length of intin array = 0. contrl(6) -- Device handle. contrl(7-8) -- Address of application cursor draw routine. _____________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout array = 0. contrl(9-10)-- Address of the old cursor draw -- routine. _____________________________________________________________________________ C BINDING Procedure Name vex_curv( handle, pusrcode, psavcode ) Data Types WORD vex_curv ( ); WORD handle; WORD *pusrcode; WORD *psavcode; Input Arguments handle = contrl[6] pusrcode = contrl[7-8] Output Arguments psavcode = contrl[9-10] 7-32 ***************************************************************************** GEM VDI Programmer's Guide Sample Keyboard State Information _____________________________________________________________________________ SAMPLE KEYBOARD This function returns the current state of STATE INFORMATION the keyboard's Control, Shift, and Alt keys. These values are returned as a bit-encoded value in intout(0). The keys are assigned to bits as follows: Bit 0 - right Shift Key Bit 1 - left Shift Key Bit 2 - Control Key Bit 3 - Alt Key Bit 0 is the Least Significant Bit of the word. A bit value of zero indicates the key is up, a bit value of 1 indicates the key is depressed. _____________________________________________________________________________ Input contri(0) -- Opcode = 128. contrl(1) -- Number of input vertices = 0. contrl(3) -- Length of intin array = 0. contrl(6) -- Device handle. _____________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout array = 1 intout(0) -- Keyboard state. _____________________________________________________________________________ C BINDING Procedure Name vq_key_s( handle, &pstatus ) Data Types WORD vq_key_s ( ); WORD handle; WORD pstatus; Input Arguments 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(0) 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) -- Opcode = 102. contrl(l) -- Number of input vertices = 0. contrl(3) -- Length of intin array = 1. contrl(6) -- Device handle. intin(0) -- Information type. 0 = Open Workstation values 1 = Extended Inquire values 8-1 ***************************************************************************** GEM VDI Programmer's Guide Extended Inquire _____________________________________________________________________________ Output contrl(2) -- Number of output vertices = 6. contrl(4) -- Length of intout array = 45. intout(0) -- Type of screen. 0 -- not screen I -- separate alpha and graphic controllers and separate video screens 2 -- separate alpha and graphic controllers with a common video screen 3 -- common alpha and graphic controller with separate image memory 4 -- common alpha and graphic controller with common image memory intout(l) -- Number of background colors available in color palette. On some devices this may be different from the number of colors returned from Open Workstation, intout(39). intout(2) -- Text effects supported. (See "Set Graphic Text Special Effects" in Section 5 for values.) intout(3) -- Scale rasters. 0 = scaling not possible 1 = scaling possible intout(4) -- Number of planes. intout(5) -- Lookup table supported. 0 = table supported 1 = table not supported intout(6) -- Performance factor, number of 16 x 16 pixel raster ops per second. intout(7) -- Contour fill capability. intout(8) -- Character rotation ability. 0 = none 1 = 90-degree increments only 2 = arbitrary angles 8-2 ***************************************************************************** GEM VDI Programmer's Guide Extended Inquire intout(9) -- Number of writing modes available. intout(10) -- Highest level of input mode available. 0 = none 1 = request 2 = sample intout(ll) -- Text alignment capability flag. 0 = no 1 = yes intout(12) -- Inking capability flag. 0 = device cannot ink 1 = device can ink intout(13) -- Rubberbanding capability flag. 0 = no 1 = capable of rubberband lines 2 = capable of both rubberband lines and rectangles intout(14) -- Maximum vertices for Polyline, Polymarker, or Filled Area. -1 = no maximum intout(15) -- Maximum intin. -1 = no maximum intout(16) -- Number of keys available on the mouse. intout(17) -- styles for wide lines. 0 = no 1 = yes intout(18) -- Writing modes for wide lines. intout(19-44)- Reserved, contains zeros. ptsout(0-11) - 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] = ptsout[0] . . work_out[56] = ptsout[ll] 8-4 ***************************************************************************** GEM VDI Programmer's Guide Inquire Colour Representation _____________________________________________________________________________ INQUIRE COLOR This function returns either the requested or REPRESENTATION the actual value of the specified color index in RGB units. Both the set and realized values are available. If the selected index is out of range, GEM VDI returns -1 in intout(0). _____________________________________________________________________________ Input contrl(0) -- Opcode = 26. contri(1) -- Number of input vertices = 0. contrl(3) -- Length of intin array = 2. contrl(6) -- Device handle. intin(0) -- Requested color index. intin(l) -- Set or realized flag. 0 = set (return color values requested) 1 = realized ( return color values realized on device) _____________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout array = 4. intout(0) -- Color index. intout(l) -- Red intensity (in tenths of percent 0-1000). intout(2) -- Green intensity. intout(3) -- Blue intensity. 8-5 ***************************************************************************** GEM VDI Programmer's Guide Inquire Colour Representation _____________________________________________________________________________ C BINDING Procedure Name vq_color( handle, color_index, set_flag, rgb ) Data Types WORD vq_color ( ); WORD handle; WORD color_index; WORD set_ffag; WORD rgb[3]; Input Arguments handle = contrl[6] color_index = intin[0] set_flag = intin[1] Output Arguments rgb[0] = intout[1] rgb[1] = intout[21 rgb[2] = intout[3] 8-6 ***************************************************************************** GEM VDI Programmer's Guide Inquire Polyline Attributes _____________________________________________________________________________ INQUIRE CURRENT This function reports the current setting of POLYLINE all attributes that affect polylines, such as ATTRIBUTES line type, line color, line width, end styles, and writing mode. _____________________________________________________________________________ Input contrl(0) -- Opcode = 35. contrl(l) -- Number of input vertices = 0. contrl(3) -- Length of intin array = 0. contrl(6) -- Device handle. _____________________________________________________________________________ Output contrl(2) -- Number of output vertices = 1. contrl(4) Length of intout array = 5. intout(0) Current polyline line type. (Refer to Set Polyline Line Type function. ) intout(l) Current polyline line color index. intout(2) Current writing mode. (Refer to the Set Writing Mode function.) intout(3) End style for beginning point of polyline. intout(4) End style for ending point of polyline. ptsout(0) Current line width, in current coordinate system. ptsout(l) 0. 8-7 ***************************************************************************** GEM VDI Programmer's Guide Inquire Polyline Attributes _____________________________________________________________________________ C BINDING Procedure Name vql_attributes( handle, attrib ) Data Types WORD vql_attributes ( ); WORD handle; WORD attrib[4]; Input Arguments handle = contrl[6] Output Arguments attrib[0] = intout[0] attrib[ll = intout[l] attrib[21 = intout[2] attrib[31 = ptsout[0] 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(0) -- 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(0) -- Current polymarker marker type. (Refer to Set Polymarker Type function.) intout(l) -- Current polymarker marker color index. intout(2) -- Current writing mode. (Refer to the Set Writing Mode function for description. ) ptsout(0) -- 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 vqm_attributes( handle, attrib ) Data Types WORD vqm_attributes ( ); WORD handle; WORD attrib[4]; Input Arguments handle = contrl[6] Output Arguments attrib[0] = intout[0] attrib[l] = intout(l] attrib[2] = intout[21 attrib[31 = ptsout[l] 8-10 ***************************************************************************** GEM VDI Programmer's Guide Inquire Fill Area Attributes _____________________________________________________________________________ INQUIRE CURRENT This function reports the current setting of FILL AREA all attributes that affect fill areas, such ATTRIBUTES as interior style, fill color, fill style index, and writing mode. _____________________________________________________________________________ Input contrl(0) -- Opcode = 37. contrl(l) -- Number of input vertices = 0. contrl(3) -- Length of intin array = 0. contrl(6) -- Device handle. _____________________________________________________________________________ Output contrl(4) -- Number of output vertices = 0. contrl(6) -- Length of intout array = 5. intout(0) -- Current fill area interior style. (Refer to Set Fill Interior Style function.) intout(l) -- Current fill area color index. intout(2) -- Current fill area style index. (Refer to Set Fill Style Index function.) intout(3) -- Current writing mode. (Refer to the Set Writing Mode function.) intout(4) -- Current fill perimeter status. 8-11 ***************************************************************************** GEM VDI Programmer's Guide Inquire Fill Area Attributes _____________________________________________________________________________ C BINDING Procedure Name vqf_attributes( handle, attrib ) Data Types WORD vqf_attributes( WORD handle; WORD attrib[4]; Input Arguments handle = contrl[6] Output Arguments attrib[0] = intout[0] attrib[l] = intout[l] attrib[2] = intout[21 attrib[31 = intout[31 B-12 _____________________________________________________________________________ INQUIRE CURRENT This function returns the current setting of GRAPHIC TEXT all attributes that affect graphic text, such ATTRIBUTES as text size, text color, text face alignment, baseline rotation, and writing mode. _____________________________________________________________________________ Input contrl(0) -- Opcode = 38. contrl(l) -- Number of input vertices = 0. contrl(3) -- Length of intin array = 0. contrl(6) -- Device handle. _____________________________________________________________________________ Output contrl(2) -- Number of output vertices = 2. contrl(4) -- Length of intout = 6. intout(0) -- Current graphic text face. intout(l) -- Current graphic text color index. intout(2) -- Current angle of rotation of text baseline ( in tenths of degrees 0-3600). intout(3) -- Current horizontal alignment. ( Refer to Set Graphic Text Alignment function.) intout(4) -- Current vertical alignment. (Refer to Set Graphic Text Alignment function.) intout(5) -- Current writing mode. (Refer to the Set Writing Mode function.) ptsout(0) -- Current character width in current coordinate system. ptsout(l) -- Current character height in current coordinate system. ptsout(2) -- Current character cell width in current coordinate system. ptsout(3) -- Current character cell height in current coordinate system. B-13 GEM VDI Programmer's Guide Inquire Graphics Text Attributes _____________________________________________________________________________ C BINDING Procedure Name vqt_attributes( handle, attrib ) Data Types WORD vqt_attributes ( ); WORD handle; WORD attrib[10]; Input Arguments handle = contrl[6] Output Arguments 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 TEXT This function returns a rectangle that EXTENT encloses the requested string. The coordinates of the vertices are given relativeto a coordinate system defined such that the extent rectangle touches both the x and y axes, and the string is in the first quadrant. All text attributes, including style and baseline rotation, affect the calculation. | | \<-3 | \ | \ | \ | \ | \<-2 4->|\ | \ | \ | \ | \ | \ X-axis------------------------------------------ | ^ | | | 1 | Y-axis Figure B-1. Inquire Text Extent Function _____________________________________________________________________________ Input contrl(0) -- Opcode = 116. contri(l) -- Number of input vertices = 0. contrl(3) -- Number of words in text. contrl(6) -- Device handle. intin -- Character string in current character set. 8-15 ***************************************************************************** GEM VDI Programmer's Guide Inquire Text Extent _____________________________________________________________________________ Output contrl(2) -- Number of output vertices = 4. contrl(4) -- Length of intout array = 0. ptsout(0) -- delta-x for point 1 of the string in the current coordinate system. ptsout(l) -- delta-y for point 1 of the string in the current coordinate system. ptsout(2) -- delta-x for point 2 of the string in the current coordinate system. ptsout(3) -- delta-y for point 2 of the string in the current coordinate system. ptsout(4) -- delta-x for point 3 of the string in the current coordinate system. ptsout(5) -- delta-y for point 3 of the string in the current coordinate system. ptsout(6) -- delta-x for point 4 of the string in the current coordinate system. ptsout(7) -- delta-y for point 4 of the string in the current coordinate system. _____________________________________________________________________________ C BINDING Procedure Name vqt_extent( handle, string, extent ) Data Types WORD vqt_extent( ); WORD handle; WORD extent[8]; BYTE string[]; Input Arguments handle = contrl[6] string = intin Output Arguments extent[0] = ptsout[0] . . . extent[7] = ptsout[7] B-16 ***************************************************************************** GEM VDI Programmer's Guide Inquire Character Cell Width INQUIRE CHARACTER This function returns the character cell CELL WIDTH width for a specified character in the current text face. The character cell width is the distance from the left edge of the character to the left edge of the character that follows it in a text string. Special effects and rotation do not apply. GEM VDI returns all values in the current coordinate system. Left Character Right Character Alignment Alignment Delta Delta ____ ____ | | | | ---------------------------|-----------| | | | | | | -------------------- | Character | | | | | | Height | -------------------- | | | |\ /\ /| | | | | | \ / \ / | | | | Cell | | \/ \/ | | | | Height ---------------------------| | | | | | | -------------------- | ---------------------------------------| | | | | | ______________ | | Character | | Width | ____________________ Cell Width Figure 8-2. Character Cell Definition _____________________________________________________________________________ Input contrl(0) -- Opcode = 117. contrl(l) -- Number of input vertices = 0. contrl(3) -- Length of intin array = 1. contrl(6) -- 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 contrl(2) -- Number of output vertices = 3. contrl(4) -- Length of intout array = 1. intout(0) -- ADE value of the character being inquired on; -1 if an invalid character (status). ptsout(0) -- Cell width of the character in the current coordinate system. ptsout(l) -- 0. ptsout(2) -- Left character alignment delta. ptsout(3) -- 0. ptsout(4) -- Right character alignment delta. ptsout(5) -- 0. _____________________________________________________________________________ C BINDING Procedure Name status = vqt_width( handle, character, &cell_width, &left_delta, &right_delta ) Data Types WORD status; WORD vqt_width( ); WORD handle; BYTE character; WORD cell_width, WORD left_delta; WORD right_delta; Input Arguments handle = contrl[6] character = intin[0] Output Arguments 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(l ... 32). The face ID to access this face with Set Text Face is returned in intout(l). The first 16 characters name the face. The next 16 characters describe the style and weight. See Table 8-1 for a sample of the possible configurations. Table 8-1. Face Names and Styles Face Name Styles Swiss 721 Light Swiss 721 Thin Italic Dutch 801 Roman Dutch 801 Bold Italic _____________________________________________________________________________ Input contrl(0) -- Opcode = 130. contrl(l) -- Number of input vertices = 0. contrl(3) -- Length of intin array = 1. contrl(6) -- Device handle. intin(0) -- Element number. _____________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout array = 33. intout(0) -- ID number. intout(l) to intout(32) -- 32 ADE. 8-19 ***************************************************************************** GEM VDI Programmer's Guide Inquire Face Name and Index _____________________________________________________________________________ C BINDING Procedure Name index = vqt_name( handle, element_num, name ) Data Types WORD index; WORD vqt name( ); WORD handle; WORD element_num; BYTE name[32]; Input Arguments handle = contr[6] element_num = intin[0] Output Arguments index = intout[0] name[0] intout[l] . . . n;me[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 / /-----/ / | | / / / / | | Left Offset-> / / / / | | |-/-----------------/-----| | |/ ^ / ^ | /___________|_____/ |________| | Character Baseline Figure 8-3. Right and Left offset _____________________________________________________________________________ Input contrl(0) -- Opcode = 131. contrl(l) -- Number of input vertices = 0. contrl(3) -- Length of intin array = 0. contrl(6) -- Device handle. _____________________________________________________________________________ Output contrl(2) -- Number of output vertices = 5. contrl(4) -- Length of output array = 2. intout(0) -- Minimum ADE (ASCII Decimal Equivalent) the first character in this face. intout(l) -- Maximum ADE, the last character in this face. ptsout(0) -- Maximum cell width not including special effects. ptsout(l) -- Bottom line distance relative to baseline. ptsout(2) -- Special effects delta x. The current speclal effects increase character width by this amount. 8-21 ***************************************************************************** GEM VDI Programmer's Guide Inquire Current Face Information _____________________________________________________________________________ ptsout(4) -- Left offset; (see Figure 8-2) positive value relative to position. ptsout(5) -- Half distance relative to baseline. ptsout(6) -- Right offset (see Figure 8-2). ptsout(7) -- Ascent distance relative to baseline. ptsout(8) -- 0. ptsout(9) -- Top distance relative to baseline. _____________________________________________________________________________ C BINDING Procedure Name vqt_fontinfo( handle, &minADE, &maxADE, distances, &maxwidth, effects ) Data Types WORD vqt_fontinfo( ); WORD handle; WORD minADE; WORD maxADE; WORD distances[5]; WORD maxwidth; WORD effects[3], Input Arguments handle = contrl[6] Output Arguments minADE = intout[0] maxADE = intout[l] distances[0] = ptsout[1] distances[l] = ptsout[31 distances[21 = ptsout[5] distances[31 = ptsout[71 distances[41 = ptsout[91 maxwidth = ptsout[0] effects[0] = ptsout[2] effects[l] = ptsout[4] effects[21 = 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 downward. Note: This function is not required and may not be available on all devices. _____________________________________________________________________________ Input contrl(0) -- Opcode = 27. contrl(l) -- Number of input vertices = 2. contrl(3) -- Length of intin array = 0. contrl(6) -- Device handle. contrl(7) -- Length of each row in color index array. contrl(8) -- Number of rows in color index array. ptsin(0) -- x-coordinate of lower left corner in current coordinate system. ptsin(l) -- y-coordinate of lower left corner in current coordinate system. ptsin(2) -- x-coordinate of upper right corner in current coordinate system. ptsin(3) -- y-coordinate of upper right corner in current coordinate system. _____________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of the color index array, same as contrl(3). contrl(9) -- Number of elements used in each row of color index array. contrl(10) -- Number of rows used in color index array. contrl(11) -- 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 _____________________________________________________________________________ intout Color index array, stored one row at time. -1 -- indicates that a color index could not be determined for that particular pixel _____________________________________________________________________________ C BINDING Procedure Name vq_cellarray( handle, pxyarray, row_length, num-rows, &el_used, &rows_used, &status, colarray ) Data Types WORD vq_cellarray( ); WORD handle; WORD pxyarray[4]; WORD row_length; WORD num_rows; WORD el_used; WORD rows_used; WORD status; WORD colarray[n]; Input Arguments handle = contrl[6] pxyarray[0] = ptsin[0] pxyarray[l] = ptsin[1] pxyarray[21 = ptsin[2] pxyarray[31 = ptsin[3] row_length = contrl[7] num_rows = contrl[8] Output Arguments el_used = contrl[9] rows_used = contrl[10] stat_us = contrl[11] colarray[03 = intout[0] . . colarray[n] = 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(0) -- Opcode = 115. contrl(l) -- Number of input vertices = 0. contrl(3) -- Length of intin array = 1. contrl(6) -- Device handle. intin(0) -- Logical input device. 1 = locator 2 = valuator 3 = choice 4 = string _____________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout array = 1. intout(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 input_mode = intout[0] End of Section 8 8-25 ***************************************************************************** Section 9 Escapes _____________________________________________________________________________ ESCAPE The Escape function allows the application program to access the special capabilities of a graphics device. GEM VDI predefines some escape functions; others can be defined for specific devices. The parameters passed depend on the escape function the application requests. _____________________________________________________________________________ Input contrl(0) -- Opcode = 5. contrl(1) -- Number of input vertices. contfl(3) -- Number of input parameters. contrl(5) -- Function identifier (id). contrl(6) -- 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 6N 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 Adressable Character Cells _____________________________________________________________________________ ESCAPE 1: INQUIRE This escape returns information to the ADDRESSABLE ALPHA calling program about the number of vertical CHARACTER CELLS (row) and horizontal (column) positions at which the alpha cursor can be positioned on the screen. Typically, only screens support alpha text. _____________________________________________________________________________ Input contrl(0) -- Opcode = 5. contrl(l) -- Number of input vertices = 0. contrl(3) -- Length of intin array = 0. contri(5) -- Function id = 1. contrl(6) -- Device handle. _____________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout array = 2. intout(0) -- Number of addressable rows on the screen, (-l indicates cursor addressing not possible). intout(1) -- Number of addressable columns on the screen, (-l indicates cursor addressing not possible). _____________________________________________________________________________ C BINDING Procedure Name vq_chcells( handle, &rows, &columns ) Data Types WORD vq_chcells ( ); WORD handle; WORD rows; WORD columns; Input Arguments handle = contrl[6] Output Arguments rows = intout[0] columns = intout[1] 9-4 ***************************************************************************** GEM VDI Programmer's Guide Exit Alpha Mode _____________________________________________________________________________ ESCAPE 2: EXIT This escape causes the graphics device to ALPHA MODE enter graphics mode if graphics mode is different from alpha mode. It is used to exit alpha cursor addressing mode explicitly and to make the transition from alpha to graphics mode properly. _____________________________________________________________________________ Input contrl(0) -- Opcode = 5. contrl(1) -- Number of input vertices = 0. contrl(3) -- Length of intin array = 0. contrl(5) -- Function id = 2. contrl(6) -- Device handle. _____________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout array = 0. _____________________________________________________________________________ C BINDING Procedure Name v_exit_cur( handle ) Data Types WORD v_exit_cur ( ); WORD handle; Input Arguments handle = contrl[6] 9-5 ***************************************************************************** GEM VDI Programmer's Guide Enter Alpha Mode _____________________________________________________________________________ ESCAPE 3: ENTER This escape causes the graphics device to ALPHA MODE exit graphics mode if graphics mode is different from alpha mode. It is used to enter the alpha cursor addressing mode explicitly and to make the transition from graphics to alpha mode properly. This opcode also returns the cursor to the upper left character cell of the display device. _____________________________________________________________________________ Input contrl(0) Opcode = 5. contrl(l) Number of input vertices = 0. contrl(3) Length of intin array = 0. contrl(5) Function id = 3. contrl(6) Device handle. _____________________________________________________________________________ Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 0. _____________________________________________________________________________ C 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 This escape moves the alpha cursor up one row CURSOR UP without altering its horizontal position. if the cursor is already at the top margin, nothing happens. _____________________________________________________________________________ Input contrl(0) -- Opcode = 5. contrl(1) -- Number of input vertices = 0. contrl(3) -- Length of intin array = 0. contrl(5) -- Function id = 4. contrl(6) -- Device handle. _____________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout array = 0. _____________________________________________________________________________ C 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 Cursor Down _____________________________________________________________________________ ESCAPE 5: ALPHA This escape moves the alpha cursor down one CURSOR DOWN row without altering its horizontal position. If the cursor is already at the bottom margin, nothing happens. _____________________________________________________________________________ Input contrl(0) -- Opcode = 5. contrl(1) -- 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] 9-8 ***************************************************************************** GEM VDI Programmer's Guide Alpha Cursor Right _____________________________________________________________________________ ESCAPE 6: ALPHA The Alpha Cursor Right escape moves the alpha CURSOR RIGHT cursor right one column without altering its vertical position. If the cursor is already at the right margin, nothing happens. _____________________________________________________________________________ Input contrl(0) -- Opcode = 5. contrl(1) -- Number of input vertices = 0. contrl(3) -- Length of intin array = 0. contrl(5) -- Function id = 6. contrl(6) -- Device handle. _____________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout array = 0. _____________________________________________________________________________ C BINDING Procedure Name v_curright( handle ) Data Types WORD v_curright ( ); WORD haandle; Input Arguments handle = contrl[6] 9-9 ***************************************************************************** GEM VDI Programmer's Guide Alpha Cursor Left _____________________________________________________________________________ ESCAPE 7: ALPHA The Alpha Cursor Left escape moves the alpha CURSOR LEFT cursor left one column without altering its vertical position. If the'cursor is already at the left margin, nothing happens. _____________________________________________________________________________ Input contrl(0) -- Opcode = 5. contrl(1) -- Number of input vertices = 0. contrl(3) -- Length of intin array = 0. contrl(5) -- Function id = 7. contrl(6) -- Device handle. _____________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout array = 0. _____________________________________________________________________________ C 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 8: HOME This escape moves the alpha cursor to the ALPHA CURSOR home position, usually the upper left character cell of the display device. _____________________________________________________________________________ Input contrl(0) -- Opcode = 5. contrl(1) -- Number of input vertices = 0. contrl(3) -- Length of intin array = 0. contrl(5) -- Function id = 8. contrl(6) -- Device handle. _____________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout array = 0. _____________________________________________________________________________ C BINDING Procedure Name v_curhome( handle ) Data Types WORD v_curhome ( ); WORD handle; Input Arguments handle = contrl[6] 9-11 ***************************************************************************** GEM VDI Programmer's Guide Erase to End of Alpha Screen _____________________________________________________________________________ ESCAPE 9: ERASE This escape erases the display surface from TO END OF ALPHA the current alpha cursor position to the end SCREEN of the alpha screen. The current alpha cursor location does not change. _____________________________________________________________________________ Input contrl(0) -- Opcode = 5. contrl(1) -- 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 This escape erases the display surface from TO END OF ALPHA the current alpha cursor position to the end TEXT LINE of the current alpha text line. The current alpha cursor location does not change. _____________________________________________________________________________ Input contrl(0) -- Opcode = 5. contrl(1) -- Number of input vertices = 0. contrl(3) -- Length of intin array = 0. contrl(5) -- Function id = 10. contrl(6) -- Device handle. _____________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout array = 0. _____________________________________________________________________________ C BINDING Procedure Name v_eeol( handle ) Data Types WORD v_eeol ( ); WORD handle; Input Arguments handle = contrl[6] 9-13 ***************************************************************************** GEM VDI Programmer's Guide Direct Alpha Cursor Address _____________________________________________________________________________ ESCAPE 11: DIRECT The Direct Alpha Cursor Address escape moves ALPHA CURSOR the alpha cursor directly to the specified ADDRESS row and column address anywhere on the display surface. Addresses beyond the displayable range of the screen are set to the nearest value that is within the displayable range of the screen. _____________________________________________________________________________ Input contrl(0) -- Opcode = 5. contrl(1) -- Number of input vertices = 0. contrl(3) -- Length of intin array = 2. contrl(5) -- Function id = 11. contrl(6) -- Device handle. intin(0) -- 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[1] 9-14 ***************************************************************************** GEM VDI Programmer's Guide Output Cursor Addressabie Alpha Text _____________________________________________________________________________ ESCAPE 12: OUTPUT This escape displays a string of alpha text CURSOR ADDRESSABLE starting at the current cursor position. ALPHA TEXT The alpha text attributes currently in effect determine alpha text attributes. _____________________________________________________________________________ Input contrl(0) Opcode = 5. contrl(1) Number of input vertices = 0. contrl(3) Number of characters i n character string. contrl(5) Function id = 12. contrl(6) Device handle. intin Text string in ADE. _____________________________________________________________________________ Output contrl(2) Number of output vertices = 0. contrl(4) Length of intout array = 0. _____________________________________________________________________________ C BINDING Procedure Name v_curtext( handle, &string ) Data Types WORD v_curtext ( ); WORD handle; BYTE string[]; Input Arguments handle = 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: This escape displays all subsequent alpha REVERSE text in reverse video. VIDEO ON _____________________________________________________________________________ Input contrl(0) -- Opcode = 5. contrl(1) -- Number of input vertices = 0. contrl(3) -- Length of intin array = 0. contrl(5) -- Function id = 13. contrl(6) -- Device handle. _____________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout array = 0. _____________________________________________________________________________ C BINDING Procedure Name v_rvon( handle ) Data Types WORD r_von ( ); WORD handle; Input Arguments handle = contrl[6] 9-16 ***************************************************************************** GEM VDI Programmer's Guide Reverse Video Off _____________________________________________________________________________ ESCAPE 14: This escape displays all subsequent alpha REVERSE text in normal video format. VIDEO OFF _____________________________________________________________________________ Input contrl(0) -- Opcode = 5. contrl(1) -- Number of input vertices = 0. contrl(3) -- Length of intin array = 0. contrl(5) -- Function id = 14. contrl(6) -- Device handle. _____________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout array = 0. _____________________________________________________________________________ C BINDING Procedure Name v_rvoff( handle ) Data Types WORD v-rvoff ( ); WORD handle; Input Arguments handle = contrl[6] 9-17 ***************************************************************************** GEM VDI Programmer's Guide Inquire Current Alpha Cursor Address _____________________________________________________________________________ ESCAPE 15: This escape returns the current position of INQUIRE CURRENT the alpha cursor in row, column coordinates. ALPHA CURSOR ADDRESS _____________________________________________________________________________ Input contrl(0) -- Opcode = 5. contri(1) -- Number of input vertices = 0. contrl(3) -- Length of intin array = 0. contrl(5) -- Function id = 15. contrl(6) -- Device handle. _____________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout array = 2. intout(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 vq_curaddress( handle, &row, &column ) Data Types WORD vq_curaddress ( ); WORD handle; WORD row; WORD column; Input Arguments handle = contrl[6] Output Arguments row = intout[0] column = intout[1] 9-18 ***************************************************************************** GEM VDI Programmer's Guide Inquire Tablet Status _____________________________________________________________________________ ESCAPE 16: This escape returns the availability status INQUIRE TABLET of a graphics tablet, mouse, joystick, or STATUS other similar device. _____________________________________________________________________________ Input contrl(0) -- Opcode = 5. contrl(1) -- Number of input vertices = 0. contrl(3) -- Length of intin array = 0. contrl(5) -- Function id = 16. contrl(6) -- Device handle. _____________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout array = 1. intout(0) -- 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 = intout[0] 9-19 ***************************************************************************** GEM VDI Programmer's Guide Hard Copy _____________________________________________________________________________ ESCAPE 17: HARD The device generates a hard copy with this COPY escape. The escape is device-specific and copies the physical screen to a printer or other attached hard copy device. _____________________________________________________________________________ Input contrl(0) -- Opcode - 5. contrl(1) -- Number of input vertices = 0. contrl(3) -- Length of intin array = 0. contrl(5) -- Function id = 17. contrl(6) -- Device handle. _____________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- 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 Graphics 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(0) -- Opcode = 5. contrl(1) -- Number of input vertices = 1. contrl(3) -- Length of intin array = 0. contrl(5) -- Function id = 18. contrl(6) -- Device handle. ptsin(0) -- x-coordinate of location to place cursor in current coordinate system. ptsin(1) -- 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[1] 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(0) -- Opcode = 5. contrl(1) -- Number of input vertices = 0. contrl(3) -- Length of intin array = 0. contrl(5) -- Function id = 19. contrl(6) -- Device handle. _____________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout array = 0. _____________________________________________________________________________ C 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 This escape is required only for printers. ADVANCE It advances the printer page. This escape can be used instead of invoking a Clear Workstation function if it is desirable to retain the current printer display list while advancing to the next page. _____________________________________________________________________________ Input contrl(0) -- Opcode = 5. contrl(1) -- Number of input vertices = 0. contrl(3) -- Length of intin array = 0. contrl(5) -- Function id = 20. contrl(6) -- Device handle. _____________________________________________________________________________ 0utput contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout array = 0. _____________________________________________________________________________ C BINDING Procedure Name v_form_adv( handle ) Data Types WORD v_form_adv( ); WORD 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(0) -- Opcode = 5. contrl(1) -- Number of input vertices = 2. contrl(3) -- Length of intin array = 0. contrl(5) -- Function id = 21. contrl(6) -- Device handle. ptsin(0) -- x-coordinate of corner of window to be output in NDC/RC. ptsin(1) -- y-coordinate of corner of window to be output in NDC/RC. ptsin(2) -- x-coordinate of corner of window, diagonally opposite corner selected in ptsin(0), in NDC/RC. ptsin(3) -- y-coordinate of corner of window, diagonally opposite corner selected in ptsin(l), in NDC/RC. _____________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout array = 0. 9-24 ***************************************************************************** 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 22: CLEAR This escape is required only for printers. DISPLAY LIST It allows the application to request that the printer display list be cleared. It is similar to the Clear Workstation function, but does not cause a form advance on the printer. _____________________________________________________________________________ Input contrl(0) -- Opcode = 5. contrl(1) -- 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 def ined in the bit image f ile. Preserving pixel aspect ratio means the printed object will have the same aspect ratio it had on the device on which it was originally drawn. For example, squares remain squares, and circles remain circles. Ignoring pixel aspect ratio means the printed object will not necessarily have the same aspect ratio it had on the original device. The application can set the two axis scaling flags independently of each other. The flags determine if the bit image's x or y axis 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 contrl(0) -- Opcode = 5. contrl(1) -- Number of input vertices = 2. contrl(3) -- Length of intin array = length of filename + 5. contrl(5) -- Function id = 23. contrl(6) -- Device handle. intin(0) -- Aspect ratio flag. 0 = ignore aspect ratio 1 = honor pixel aspect ratio intin(1) -- Scaling for x-axis. 0 = fractional scaling 1 = integer scaling intin(2) -- Scaling for y-axis. 0 = fractional scaling 1 = integer scaling intin(3) -- Horizontal alignment. 0 = left 1 = center 2 = right intin(4) -- Vertical alignment. 0 = top 1 = middle 2 = bottom intin(5) -- First character of filename. . . . intin(n+4) -- Last (nth) character of filename. 9-28 ***************************************************************************** GEM VDI Programmer's Guide Output Bit Image File _____________________________________________________________________________ ptsin(0) -- Upper left x (if specified). ptsin(1) -- 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[1] y_scale = intin[21 h_align = intin[3] v_align = intin[41 xyarray[0] = ptsin[0] xyarray[l] = ptsin[1] xyarray[2] = ptsin[21 xyarray[3] = ptsin[31 Note: Bytes for the filename array are mapped into the corresponding eight least significant bits of intin. The string must be null terminated. 9-29 ***************************************************************************** GEM VDI Programmer's Guide Select Palette _____________________________________________________________________________ ESCAPE 60: SELECT This escape allows the selection of the PALETTE palette on the IBM (Tm) medium-resolution color screen. _____________________________________________________________________________ Input contrl(0) -- Opcode = 5. contrl(1) -- Number of input vertices = 0. contrl(3) -- Length of input array = 1. contrl(5) -- Function id = 60. contrl(6) -- Device handle. intin(0) -- Color selection. 0 = use red, green, brown palette (default) 1 = use cyan, magenta, white palette _____________________________________________________________________________ Output contrl(2) -- Number of output vertices 0. contrl(4) -- Length of intout array intout(0) -- Palette selected. C BINDING Procedure Name selected vs_palette( handle, palette ) Data Types WORD vs_palette( ); WORD handle; WORD palette; Input Arguments handle = contrl[6] palette = intin[0] Output Arguments selected = intout[0] 9-30 ***************************************************************************** GEM VDI Programmer's Guide Polaroid Palette POLAROID(Tm) Use these escapes to modify the operation of the PALETTE 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 F1IM Types _____________________________________________________________________________ ESCAPE 91: This escape returns five strings that INQUIRE PALETTE describe the films that the driver is FILM TYPES currently capable of exposing. The strings are padded with spaces if they have fewer than 25 characters. The strings are returned as ADE integers in intout. _____________________________________________________________________________ Input contrl(0) -- Opcode = 5. contrl(1) -- Number of input vertices = 0. contrl(3) -- Length of intin array = 0. contrl(5) -- Function id = 91. contrl(6) -- Device handle. _____________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout = 125. intout -- 5 sets of 25 ADE character strings. _____________________________________________________________________________ C BINDING Procedure Name vqp_films( handle, film-names ) Data Types WORD vqp_films( ); WORD handle; WORD film-names[125]; Input Arguments handle = contrl[6] Output Arguments 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: This escape returns a block of data that INQUIRE PALETTE describes the current state of the driver. DRIVER STATE The state can be updated by changing this block and returning it to the driver with Escape 93. _____________________________________________________________________________ Input contrl(0) -- Opcode = 5. contrl(1) -- Number of input vertices = 0. contrl(3) -- Length of intin = 0. contrl(5) -- Function id = 92. contrl(6) -- Device handle. _____________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout array = 20. intout(0) -- Port number. 0 = first comm port intout(1) -- Film number (0...$). intout(2) -- Lightness control (-3...3). Each integer increase represents opening the aperture 1/3 of an f-stop. A -3 results in an exposure half as long as normal, while a 3 doubles the exposure time. intout(3) -- Interlace flag. 0 = noninterlaced 1 = interlaced A noninterlaced picture requires slightly more than half the memory of an interlaced picture. intout(4) -- Planes, a number (1...4) corresponding to number of colors (2...16). intout(5 to 20) -- Two-character color codes for 8- color indices stored in ADE format. 9-33 ***************************************************************************** GEM VDI Programmer's Guide Inquire Palette Driver State _____________________________________________________________________________ C BINDING Procedure Name vqp_state( handle, &port, &film_name, &lightness, &interlace, &planes, &indexes ) Data Types WORD vqp_state( ); WORD handle; WORD port; WORD film_name; WORD lightness; WORD interlace; WORD planes; WORD indexes[8][2]; Input Arguments handle = contrl[6] Output Arguments port = intout[0] film name = intout[1] 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 This escape moves a block of characteristics PALETTE DRIVER into the driver. Use this function after STATE Escape 92. Input contrl(0) -- Opcode = 5. contrl(1) -- Number of input vertices = 0. contrl(3) -- Length of intin array = 20. contrl(5) -- Function id = 93. contrl(6) -- Device handle. intin(0) -- Port number. 0 = first comm port intin(l) -- Film number (0...4). intin(2) -- Lightness control (-3...3). Each integer indicates opening the aperture 1/3 an f-stop. A -3 results in an exposure half as long as normal, while a 3 doubles the exposure time. intin(3) -- Interlace flag. 0 = noninterlaced 1 = interlaced intin(4) -- Planes (1 to 4 ), number corresponds to number of colors (2 to 16). intin(5 to 20) -- Color codes for up to 16 colors. 9-35 ***************************************************************************** GEM VDI Programmer's Guide Set Palette Driver State _____________________________________________________________________________ C BINDING Procedure Name vsp_state( handle, port, film_num, lightness, interlace, planes, indexes Data Types WORD vsp_style( ); WORD handle; WORD port; WORD film_num; WORD lightness, WORD interlace; WORD planes; WORD indexes[8][2]; Input Arguments handle = contrl[6] port = intin[0] film num = intin[l] lighiness = intin[2] interlace = intin[3] planes = intin[4] indexes = intin[5-20] 9-36 ***************************************************************************** GEM VDI Programmer's Guide Save Palette Driver State ESCAPE 94: SAVE This escape saves the current state of the PALETTE DRIVER driver to disk. The application can change STATE the default film and index mapping with this escape. Input contrl(0) -- Opcode = 5. contrl(1) -- Number of input vertices = 0. contrl(3) -- Length of intin array = 0. contrl(5) -- Function id = 94. contrl(6) -- Device handle. Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout array = 0. _____________________________________________________________________________ C BINDING Procedure Name vsp_save( handle ) Data Types WORD vsp_save( ); WORD handle; Input Arguments handle = contrl[6] 9-37 ***************************************************************************** GEM VDI Programmer's Guide Suppress Palette Messages _____________________________________________________________________________ ESCAPE 95: This escape allows the application to SUPPRESS PALETTE suppress the messages the palette driver MESSAGES normally outputs to the screen. These messages are either error messages or user prompts. Refer to Escape 96 for the messages and their codes. _____________________________________________________________________________ Input contrl(0) -- Opcode = 5. contrl(1) -- Number of input vertices = 0. contrl(3) -- Length of intin array = 0. contrl(5) -- Function id = 95. contrl(6) -- Device handle. _____________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of output array = 0. _____________________________________________________________________________ C 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: This escape returns an error code so the PALETTE ERROR application can notify the user of a problem. INQUIRE This escape also returns codes for pending user prompts. The error is not cleared, so a message can be displayed if such messages are not suppressed. _____________________________________________________________________________ Input contrl(0) -- Opcode = 5. contrl(1) -- Number of input vertices = 0. contrl(3) -- Length of intin array = 0. contrl(5) -- Function id = 96. contrl(6) -- Device handle. _____________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout array = 1. intout(0) -- 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 METAILE 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(0) -- Opcode = 5. contrl(1) -- Number of input vertices = 2. contrl(3) -- Length of intin array = 0. contrl(5) -- Function id = 98. contrl(6) -- Device handle. ptsin(0) -- Minimum x value of the minimum bounding rectangle. ptsin(1) -- Minimum y value of the minimum bounding rectangle. ptsin(2) -- Maximum x value of the minimum bounding rectangle. ptsin(3) -- Maximum y value of the minimum bounding rectangle. _____________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout array = 0. 9-41 ***************************************************************************** GEM VDI Programmer's Guide Update Metatile Extents _____________________________________________________________________________ C BINDING Procedure Name v_meta_extents(handle, min_x, min_y, max_x, max_y) Data Types WORD v_meta_extents ( ); WORD handle, min_x, min_y, max_x, max_y; Input Arguments handle = contrl[6]; min_x = ptsin[0]; min_Y = ptsin[l]; 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(0) -- Opcode = 5. contrl(1) -- Number of input vertices. contrl(3) -- Length of intin array. contrl(5) -- Function id = 99. contrl(6) -- Device handle. intin -- User-defined information. intin(0) -- Sub-opcode. ptsin -- User-defined information. _____________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout array = 0. _____________________________________________________________________________ C BINDING Procedure Name v_write_meta(handle, num_intin, intin, num_ptsin, ptsin) Data Types WORD v_write_meta ( ); WORD handle, num_intin, num_ptsin; WORD intin[num_intin], ptsin[num_ptsin]; Input Arguments handle = contrl[6]; num_intin = contrl[3]; num_ptsin = contrl[1]; intin = intin; ptsin = ptsin; 9-43 ***************************************************************************** GEM VDI Programmer's Guide Change GEM VDI Filename ESCAPE 100: This escape renames a metafile from CHANGE GEM VDI GEMFILE.GEM to the specified name and FILENAME 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(0) -- Opcode = 5. contrl(1) -- Number of input vertices = 0. contrl(3) -- Length of intin array = number of significant characters [l...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[ ]; Input Arguments handle = contrl[6] filename = intin[0-n] Note: The filename must be null-terminated. End of Section 9 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-1 ***************************************************************************** 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: Respecify the path with the correct path name. ASSIGN.SYS file is empty Description: This message appears when GEM VDI finds an empty ASSIGN.SYS file. Solution: Enter the necessary information with your text editor. Refer to Appendix B for the necessary ASSIGN.SYS file contents. Driver file not found Description: GEM VDI cannot find the first driver specified in the ASSIGN.SYS file. Solution: Make sure that the driver is in the specified drive, in the correct directory, and in the correct subdirectory- Corrupted driver file Description: GEM VDI finds the device driver, but is unable to use it. Solution: Use your distribution disk to make another copy of the device driver. Try to use the new copy. Contact your dealer if the device driver is unusable. End of Appendix A A-3 ***************************************************************************** Appendix B 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 Numbers Table B-1. Device Id Numbers 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-1 shows the ASSIGN.SYS file format: Device Driver Face Id Filename Name 01 SCREEN.SYS FACE1.FNT Figure B-1. ASSIGN.SYS File Format B1 ***************************************************************************** GEM VDI Programmer's Guide Sample ASSIGN.SYS _____________________________________________________________________________ SAMPLE ASSIGN.SYS 21 printer.fnt ;comments, if desired face1.fnt ;face1 description face2.fnt ;face2 description face3.fnt ;face3 description 01 screen.fnt ;comments, if desired face4.fnt ;face4 description face5.fnt ;face5 description 11 plotter.fnt ;comments, if desired face6.fnt ;face6 description face7.fnt ;face7 description End of Appendix B B-2 ***************************************************************************** Appendix C GEM VDI Metafile Format _____________________________________________________________________________ INTRODUCTION The metafile driver outputs the information specified below and performs the described operations for the indicated opcodes. _____________________________________________________________________________ STANDARD METAFILE Most function requests passed to the metafile ITEM FORMAT driver result in a standard format metafile item being written to the metafile buffer. In a standard format metafile item, the control, integer, and vertex parameters are written to the metafile in the following format: word value description 0 contrl[0] opcode 1 contrl[l] vertex count 2 contrl[3] integer parameter count 3 contrl[5] sub-opcode (or zero) 4... ptsin[0-n] vertices (if provided) n+4... intin[0-m] 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 C-1 ***************************************************************************** GEM VDI Programmer's Guide GEM VDI Metafile Format _____________________________________________________________________________ 11, 4 circle 11, 5 ellipse 11, 6 elliptical arc 11, 7 elliptical pie 11, 8 rounded rectangle 11, 9 filled rounded rectangle 11,10 justified graphics text 12 set character height, absolute mode 13 set character baseline vector 14 set color representation 15 set polyline linetype 16 set polyline line width 17 set polyline color index 18 set polymarker type 19 set polymarker height 20 set polymarker color index 21 set text face 22 set text color index 23 set fill interior style 24 set fill style index 25 set fill color index 32 set writing mode 39 set graphic text alignment 104 set fill perimeter visibility 106 set graphic text special effects 107 set character height, points mode 108 set polyline end styles 112 set user-defined fill pattern 113 set user-defined line style pattern 114 fill rectangle 129 set clipping _____________________________________________________________________________ NONSTANDARD METAFILE ITEMS 1 open The metafile file buffer is initialized and workstation the metafile header is output to it. The workstation description values normally returned by an "open workstation" invocation are returned. C-2 ***************************************************************************** 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 0ffffh _____________________________________________________________________________ SPECIAL METAFILE ESCAPES 5, 98 update The extents information in the metafile metafile extents header is updated to indicate the extents passed in the ptsin array. 5, 99 write A standard format metafile item is written. metafile item The first word of the intin array should escape contain a sub-opcode that can be used by an application to identify the metafile item when it is read in. _____________________________________________________________________________ 5, 100 change GEM If any information currently exists in the vDi filename metafile or metafile buffer, the buffer is escape flushed and the file is closed. The metafile buffer is reinitialized and rudimentary file name validation is performed. If the drive, path, and filename are valid, they are used to update the file control block (FCB) of the metafile. The metafile will not actually be opened until the first buffer needs to be flushed. C-4 ***************************************************************************** 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 ***************************************************************************** Appendix D Standard Keyboard _____________________________________________________________________________ GEM VDI defines a standard keyboard so applications can take advantage of special keys not defined in the standard, 7-bit ASCII character set. A 16-bit value is used to return these characters. The high byte contains a binary value assigned to each key. The low byte contains the 7-bit ASCII value, if such a value is defined, or a zero if the code is an extended code. Table D-1. GEM VDI Standard Keyboard Assignments High Low Byte Byte Character 03 00 CNTL 2 (Nul) 1E 01 CNTL A 30 02 CNTL B 2E 03 CNTL C 20 04 CNTL D 12 05 CNTL E 21 06 CNTL F 22 07 CNTL G 23 08 CNTL H 17 09 CNTL I 24 0A CNTL J 25 0B CNTL K 26 0C CNTL L 32 0D CNTL M 31 0E CNTL N 18 0F CNTL O 19 10 CNTL P 10 11 CNTL Q 13 12 CNTL R 1F 13 CNTL S 14 14 CNTL T 16 15 CNTL U 2F 16 CNTL V 11 17 CNTL W 2D 18 CNTL X 15 19 CNTL Y 2C 1A CNTL Z 1A 1B CNTL [ 2B 1C CNTL \ 1B 1D CNTL ] 07 1E CNTL 6 0C 1F CNTL - 39 20 Space D-1 ***************************************************************************** GEM VDI Programmer's Guide Standard Keyboard _____________________________________________________________________________ Table D-1. (continued) High Low Byte Byte Character 02 21 ! 28 22 " 04 23 # 05 24 $ 06 25 % 08 26 & 28 27 ' 0A 28 ( 0B 29 ) 09 2A * 0D 2B + 33 2C , 0C 2D - 34 2E . 35 2F / 0B 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 0A 39 9 27 3A : 27 3B ; 33 3C < 0D 3D = 34 3E > 35 3F ? 03 40 @ IE 41 A 30 42 B 2E 43 C 20 44 D 12 45 E 21 46 F 22 47 G 23 48 H 17 49 1 24 4A i 25 4B K 26 4C L 32 4D m 31 4E N 18 4F O D-2 ***************************************************************************** GEM VDI Programmer's Guide Standard Keyboard _____________________________________________________________________________ Table D-1. (continued) High Low Byte Byte Character 19 50 P 10 51 Q 13 52 R 1F 53 S 14 54 T 16 55 U 2F 56 V 11 57 W 2D 58 X 15 59 Y 2C 5A Z 1A 5B [ 2B 5C \ 1B 5D ] 07 5E ^ 0C 5F Underscore 29 60 ' 1E 61 a 30 62 b 2E 63 c 20 64 d 12 65 e 21 66 f 22 67 9 23 68 h 17 69 i 24 6A 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 1F 73 s 14 74 t 16 75 u 2F 76 v 11 77 w 2D 78 x 15 79 y 2C 7A z 1A 7B { 2B 7C | 1B 7D } 29 7E ~ 0E 7F Rubout (DEL) D-3 ***************************************************************************** GEM VDI Programmer's Guide Standard Keyboard _____________________________________________________________________________ Table D-1. (continued) High Low Byte Byte Character 81 00 Alt 0 78 00 Alt 1 79 00 Alt 2 7A 00 Alt 3 7B 00 Alt 4 7C 00 Alt 5 7D 00 Alt 6 7E 00 Alt 7 7F 00 Alt 8 80 00 Alt 9 1E 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 O 19 00 Alt P 10 00 Alt Q 13 00 Alt R 1F 00 Alt S 14 00 Alt T 16 00 Alt U 2F 00 Alt V 11 00 Alt W 2D 00 Alt X 15 00 Alt Y 2C 00 Alt Z 3B 00 F1 3C 00 F2 3D 00 F3 3E 00 F4 3F 00 Fs 40 00 F6 41 00 F7 42 00 F8 43 00 F9 44 00 F10 54 00 F11 D-4 ***************************************************************************** GEM VDI Programmer's Guide Standard Keyboard _____________________________________________________________________________ Table D-1. (continued) High Low Byte 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-1. (continued) High Low Byte 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 1B Escape 0E 08 Backspace 82 00 Alt - 83 00 Alt = 1C OD CR 1C OA Ctrl CR 4C 35 Shift Num Pad 5 4A 2B Num Pad - 4E 2B Num Pad + 0F 09 Tab 0F 00 Backtab 4B 00 left-arrow 4B 34 Shift left-arrow 4F 00 End 4F 31 Shift End 75 00 Ctrl End End of Appendix D D-6 ***************************************************************************** Appendix E Processor-Specific Data _____________________________________________________________________________ 8086-SPECIFIC DATA Registers and The address of the Parameter Block is passed Interrupts in two 16-bit registers (Ds:Dx for the 8086) from the application program to GEM VDI. Pass 0473h in the Cx register. The interrupt is EF. Note: GEM VDI supports Concurrent'" operating systems that support DOS calls of versions 2.0 and above. _____________________________________________________________________________ Exchange Mouse For 8086-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 For 8086-based processors, the application Change Vector code is invoked via a CALL FAR (CALLF) instruction with Ax containing the mouse button keys. Keys are encoded by the same rules that apply to the Sample Mouse Button State function. When complete, the application dependent code should do a RETURN FAR (RETF) instruction with the mouse button state the driver is to store in Ax. E-1 ***************************************************************************** GEM VDI Programmer's Guide 8068-specific Data Exchange Cursor For 8086-based machines, the application Change Vector dependent code is invoked with a CALL FAR (CALLF) instruction. Upon entry, the Bx register contains the x position and the Cx register the y position. If the application dependent code does not draw its own cursor, a CALL FAR should be performed to the address returned in contrl(9) and contrl(10) with the x,y position at which to draw the cursor in Bx, Cx. This causes GEM VDI to draw a cursor. When complete, the application should perform a RETURN FAR (RETF) instruction. _____________________________________________________________________________ Exchange Timer For 8086-based processors, the application Interrupt Vector dependent code is invoked with a CALL FAR (CALLF) instruction. When complete, the application should perform a RETURN FAR (RETF) instruction. E-2 ***************************************************************************** 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 For 68000-based machines, the application Change Vector dependent code is invoked with a JUMP TO SUBROUTINE (JSR) instruction. Upon entry, the D0.w register contains the x position and the D1.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(10) with the x,y position at which to draw the cursor in D0.w and D1.w. This causes GEM VDI to draw a cursor. When complete, the application should perform a RETURN FROM SUBROUTINE (RTS) instruction. _____________________________________________________________________________ Exchange Timer For 68000-based processors, the application Interrupt Vector dependent code is invoked with a JUMP TO SUBROUTINE (JSR) instruction. When complete, the application should perform a RETURN FROM SUBROUTINE (RTS) instruction. End of Appendix E E-4 Appendix F Character Sets _____________________________________________________________________________ The system fonts provided with GEM VDI are illustrated in Figure F-1 and F-2. Figure F-1 shows the USASCII character set. Figure F-2 shows the additional characters included to form the international character set. Note that external fonts (those which are dynamically loaded) do not include characters for decimal equivalents 0 through 31. F-1 ***************************************************************************** GEM VDI Programmer's Guide Character Sets t-IldlaL!Lt!l 3UCH DECIMAL VALUE 0 16 32 48 64 80 96 112 HEX DECIMAL 0 1 2 3 4 5 6 7 VALUE 0 0 BLANK 0 @ P ' p (SPACE) 1 1 ! 1 A Q a q 2 2 " 2 B R b r 3 3 # 3 C S c s 4 4 $ 4 D T d t 5 5 % 5 E U e u 6 6 & 6 F V f v 7 7 ' 7 G W g w 8 8 ( 8 H X h x 9 9 ) 9 I Y i y 10 A * : J Z j z 11 B + ; K [ k { 12 C , < L \ 1 | 13 D - = M ] m } 14 E . > N ^ n ~ 15 F / ? O _ o Tri ang Figure F-1. GEM VDI USASCII Character Set F-2 ***************************************************************************** GEM VDI Programmer's Guide Character Sets _____________________________________________________________________________ 128 144 160 176 192 208 224 240 8 9 A B C D E F 0 a, a 0( 1 0 Ij + 2 2 e /E 0' > 3 3 a 6 U' 7r < 4 4 6,* n- (x f 5 5 a 6 N (Y, 6 6 0 A 7 7 T 8 8 e y 6 0 9 9 0 F- 10 A e U 11 B '/2 12 C 1 'A 13 D 0 14 E P1 15 F 0 TM 7, Figure F-2. GEM VDI International Character Set Extension F-3 ***************************************************************************** GEM VDI Programmer's Guide Character Sets _____________________________________________________________________________ 128 144 160 176 192 208 224 240 8 9 A B C D E F 0 1 T 2 2 e 3 3 4 4 a 6 5 a 6 6 a 7 7 8 8 9 9 10 A ci 11 B 0 12 C 13 D 14 E A 15 F A Figure F-3. GEM VDI International Character Set Extension for FNT Files End of Appendix F F-4 ***************************************************************************** Appendix G Font Format _____________________________________________________________________________ INTRODUCTION The system fonts and external fonts used in GEM VDI are composed of four parts: the font data, a font header, a character offset table, and a horizontal offset table. _____________________________________________________________________________ FONT DATA The font data is organized as a single raster area. The area's height equals the font height and its width equals the sum of the character widths. The top scan line of the first character in the font is aligned to a byte boundary. The top scan line of the second character is abutted to the first character and is not necessarily byte-aligned. That is, the end of any character and the beginning of the following character often occur within the same byte; no byte alignment occurs within the font form. Bit padding occurs only at the end of a scan line. Each scan line in the font form begins on a word boundary. The number of bytes from the beginning of one scan line to the beginning of the next is called the form width. The number of scan lines required to draw any character is called the form height. A flag within the font header indicates the orientation of bytes within a word in the font data. If the flag is cleared, the font data is in a format such that the low byte of a word occurs in memory before the high byte (Inte16 format). If the flag is set, the high byte precedes the low byte in memory. _____________________________________________________________________________ FONT HEADER The font header contains information that describes global aspects of the font. For example, the name of the face, the font size, the minimum and maximum characters in the font, and any other data that applies to every character of the font are global aspects of that font. The format of the font header is shown in Table G-1. G-1 ***************************************************************************** GEM VDI Programmer's Guide Font Header Table G-1. Font Header Format Byte Number Description 0 - 1 face identifier (see the Set Text Face function) 2 - 3 font size in points 4 - 35 face name (see the inquire Face Name and Index function) 36 - 37 lowest ADE value in the face 38 - 39 highest ADE value in the face 40 - 41 *top line distance 42 - 43 *ascent line distance 44 - 45 *half line distance 46 - 47 *descent line distance 48 - 49 *bottom line distance 50 - 51 width of the widest character in the font 52 - 53 width of the widest character cell in the face 54 - 55 left offset (see the Inquire Current Face Information function) 56 - 57 right offset (see the Inquire Current Face Information function) 58 - 59 thickening: the number of pixels by which to widen thickened characters 60 - 61 underline size: the width (in pixels) of the underline G-2 ***************************************************************************** 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 The character offset table is used to index TABLE into the font data and to determine the width of specific characters in the font. It is indexed by relative character value (the ADE value of the desired character, minus the lowest ADE value in the font) and yields the offset from the base of the font data to the beginning of the character definition. The difference between the offset to a character and the offset to the following character gives the width of the character. Note that the character offset table includes one more entry than the number of characters in the font so that a width may be obtained for the final character in the font. Note: The character offset table is required even for mono-spaced fonts. HORIZONTAL OFFSET The horizontal offset table is indexed by TABLE relative character value and yields any additional positive or negative spacing necessary before outputting the character. The horizontal offset table often does not exist. Whether it exists or not is indicated by the horizontal offset table bit in the flags word of the font header. End of Appendix G G-4 ***************************************************************************** Appendix H Reserved Metafile Sub-opcodes _____________________________________________________________________________ HETAFILE SUB- Thee 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 device. The two GEM Output metafile sub-opcodes result in an update of the metafile header. The opcodes are not actually written to the body of the metafile. _____________________________________________________________________________ PHYSICAL PAGE SIZE This sub-function defines the size of the area to be output to. All of the data in the coordinate window is mapped to this area. if no physical page size is defined, the Output application will attempt a best fit on the target device, assuming that "pixels" in the metafile are square. _____________________________________________________________________________ Input contrl(0) -- Opcode = 5. contrl(l) -- Number of input vertices = 0. contrl(3) -- Length of intin array = 3. contrl(5) -- Function id = 99. contrl(6) -- Device handle. intin(0) -- Sub-opcode number = 0. intin(1) -- Page width in tenths of millimeter. intin(2) -- Page height in tenths of millimeter. _____________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout array = 0. H-1 ***************************************************************************** GEM VDI Programmer's Guide Coordinate window _____________________________________________________________________________ COORDINATE WINDOW This sub-function defines the coordinate system used in the metafile. All of the data in the defined coordinate window is mapped to the area defined by the physical page size sub-function. The coordinate window defaults to NDC space (0 to 32K). The location of the origin, (0, 0), depends on the coordinate space set when the metafile was opened (see "Open Workstation"). For example, if the Open Workstation function was invoked specifying raster coordinate space, the origin would be located in the upper left corner of the display surface. Note that the window corner information must be specified as the lower left and upper right corners. Arbitrary opposing corners will not convey enough information. _____________________________________________________________________________ Input contrl(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(O) -- Sub-opcode = 1. intin(l) -- x-coordinate of lower left corner of window. intin(2) -- y-coordinate of lower left corner of window. intin(3) -- x-coordinate of upper right corner of window. intin(4) -- y-coordinate of upper right corner of window. _____________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout array = 0. H-2 ***************************************************************************** GEM VDI Programmer's Guide Metafile Sub-opcodes with GEM Draw _____________________________________________________________________________ NETAFILE SUB- The following sub-opcodes are reserved for OPCODES FOR USE use by the GEM Draw" application. GEM VDI WITH GEM DRAW defines the sub-opcodes for the following sub functions: * Start Group * End Group * Set Attribute Shadow On * Set Attribute Shadow Off * Start Draw Area Type Primitive * End Draw Area Type Primitive * Set No Line Style _____________________________________________________________________________ START GROUP This sub-function indicated the beginning of a group of primitives for the GEM Draw application. All subsequent primitives which occur before the next End Group sub-opcode will be regarded as a group by the GEM Draw application. _____________________________________________________________________________ Input contrl(0) -- Opcode = 5. contrl(1) -- Number of input vertices = 0. contrl(3) -- Length of intin array = 1. contrl(5) -- Function id = 99. contrl(6) -- Device handle. intin(0) -- Sub-opcode number = 10. _____________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout array = 0. H-3 ***************************************************************************** GEM VDI Programmer's Guide End Group _____________________________________________________________________________ END GROUP This sub-function indicated the end of a group of primitives for the GEM Draw application. _____________________________________________________________________________ Input contrl(0) -- Opcode = 5. contrl(1) -- Number of input vertices = 0. contrl(3) -- Length of intin array = 1. contrl(5) -- Function id = 99. contrl(6) -- Device handle. intin(0) -- Sub-opcode number = 11. _____________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout array = 0. _____________________________________________________________________________ SET NO 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 contrl(0) Opcode = 5. contrl(1) Number of input vertices = 0. contrl(3) Length of intin array = 1. contrl(5) Function id = 99. contrl(6) Device handle. intin(0) Sub-opcode number = 49. _____________________________________________________________________________ Output contrl(2) Number of output vertices = 0. contrl(4) 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 contrl(0) -- Opcode = 5. contrl(1) -- Number of input vertices = 0. contrl(3) -- Length of intin array = 1. contrl(5) -- Function id = 99. contrl(6) -- Device handle. intin(0) -- Sub-opcode number = 50. _____________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout array = 0. H-5 ***************************************************************************** GEM VDI Programmer's Guide Set Attribute Shadow Off _____________________________________________________________________________ SET ATTRIBUTE This sub-function indicates to GEM Draw the SHADOW OFF end of primitives used to draw a drop shadow of the first primitive following this sub-opcode. _____________________________________________________________________________ Input contrl(0) -- Opcode = 5. contrl(1) -- Number of input vertices = 0. contrl(3) -- Length of intin array = 1. contrl(S) -- Function id = 99. contrl(6) -- Device handle. intin(0) -- 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(0) -- 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(0) -- Sub-opcode number = 80. _____________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout array = 0. H-6 ***************************************************************************** END DRAW AREA This sub-function indicates to GEM Draw the TYPE PRIMITIVE end of an area type primitive block. _____________________________________________________________________________ Input contrl(0) -- Opcode = 5. contrl(1) -- Number of input vertices = 0. contrl(3) -- Length of intin array = 1. contrl(5) -- Function id = 99. contrl(6) -- Device handle. intin(0) -- Sub-opcode number = 81. _____________________________________________________________________________ Output contrl(2) -- Number of output vertices = 0. contrl(4) -- Length of intout array = 0. End of Appendix H H-7 ***************************************************************************** Appendix I Bit 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 ::= * EOF scan-line ::= [], ... , (see Note 1) vert_rep :: (see Note 2) planeJ ::= * (see Note 3) encoded-data ::= { | | } I-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 Thenumber of pixels described for each bit plane of a scan line is not necessarily the scan-line width specified in the file header. Because the data is encoded in byte-wide packets (packets of eight pixels), the number of pixels actually described is always a multiple of eight and is never more than seven pixels wider than the scan-line width. I-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 1s 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 0s 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 0s (hex 06). I-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 I-4 ***************************************************************************** Glossary _____________________________________________________________________________ ASSIGN.SYS Text file created by the driver installation program. Associates device identification ( id) numbers with specific device driver files so that devices can be referred to by type within the application program. The ASSIGN.SYS file can be modified using any text editor. coordinate scaling Converting points from one space or coordinate system to another. In GEM VDI, this term refers to the change between Normalized Device Coordinates (NDC) and Raster Coordinates (RC). coordinate systems Cartesian space in which points are defined. GEM VDI supports two systems: Normalized Device Coordinates (NDC) and Raster Coordinates (RC). default device First driver named in the ASSIGN.SYS driver file.It must be the largest driver that will be loaded during a graphics session. device driver Device-dependent portion of GEM VDI that translates standard device-independent graphics operations to device-specific command sequences for a particular device. device handle Unique value used to identify which workstation the GEM VDI function should use. GEM VDI assigns these numbers at Open Workstation. device Id number assigned to a device in the identification ASSIGN.SYS file. Each device in the number ASSIGN.SYS file has a unique device number assigned to it. Glossary-1 GEM VDI Programmer's Guide Glossary _____________________________________________________________________________ face Letter style, such as Times Roman. GEM VDI stores the definition of each style in a data file. When an application calls for the use of a particular text face, GEM VDI uses the definition to form the text characters on the specified graphics device. font Collection of characters all in one typeface, a subset of face. function code See operation code. graphics command Command that loads the GDOS into memory. graphics Hardware that accepts graphics input (mouse or device keyboard, for example) or displays graphics output (screen, printer, or plotter, for example). Graphics Device-independent portion of GEM VDI that Device services graphics requests and calls the Operating (GDOS) device driver to send commands to graphics System devices. Generalized Display function used to address special Drawing device capabilities such as curve drawing. Primitive (GDP) GEM VIDI supports the following GDPs: bar, arc, pie, circle, ellipse, elliptical arc, elliptical pie, rounded rectangle, filled rounded rectangle, and justified graphics text. Not all devices support all GDPs. Graphics Graphics extension to microcomputer opera- Environment Manager ting systems. The GEM VDI makes it possible Virtual Device to run graphics applications on a micro- Interface (GEM VDI) computer. Graphical International standard for the programming Kernel interface to graphics from an application System (GKS) program. graphics Basic graphics operations performed by GEM primitives VDI, for example, drawing lines, markers, and text strings. Glossary-2 ***************************************************************************** GEM VDI Programmer's Guide Glossary _____________________________________________________________________________ hot spot Area of the cursor that covers the pixel whose x,y location is returned during locator input. For example, the hot spot on a cross hair cursor is the intersection point of the two lines making up the cross. metafile Data file containing a picture description. The GEM VDI metafile can be sent to any device or used to exchange a picture between two applications. Memory Form Block of memory that defines a raster area. Definition An MFDB includes the following raster area Block information: (MFDB) * pointer to the memory address of the upper left corner of the first plane * height and width, in pixels * width, in words * number of planes * flag to indicate if format is standard or device-dependent * locations reserved for future use Normalized Uniform virtual space by which a graphics Device application program can pass graphics Coordinate information to a device. The GDOS maps NDCs to (NDC) RCs. NDC space has its origin in the lower space left corner. normalized Any point in NDC space. device coordinates (NDC) operation codes Passed to GDOS as part of a parameter list. (opcodes) The opcode indicates which graphics operation is requested. pixel (pixel Smallest element of a display surface that element) can be independently referenced. Glossary-3 ***************************************************************************** GEM VDI Programmer's Guide Glossary raster area Rectangular blocks of either bits in memory or pixels on a physical device. Rasters are the steps between pixels. Raster Actual device units. Raster coordinate space Coordinate has its origin in the upper left corner. Its (RC) Space limits are determined by the resolution of the specific device. Raster (RC) Point in RC space. Coordinate raster Functions that operate on pixels either functions individually or in groups. transformation Determines which coordinate system the mode application is using, NDC or RC. If NDC, the transformation mode determines how the GDOS maps the NDCs to the RCs with two methods: full NDC to RC space or uniform NDC to RC space. Virtual Device Standard interface between device-dependent interface (VDI) and device-independent code in a graphics environment. The GEM VDI makes all device drivers appear identical to the calling program. virtual screen Block of memory that can be addressed as if it were a memory-mapped display. End of Glossary Glossary-4 ***************************************************************************** >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> Index _____________________________________________________________________________ A inquire addressable alpha character cells, 9-1, 9-4 architecture, 1-2 inquire current alpha cursor address, 9-2, 9-18 B inquire palette driver state, 9-2, 9-33 bit image file format, 1-1 inquire palette film BYTE, 2-1 types, 9-2, 9-32 inquire tablet status, C 9-2, 9-19 output bit image file, 9-27 Cell Array function, 4-11 output cursor addressable character offset, G-4 alpha text, 9-1, 9-15 Close Virtual Screen output window, 9-2, 9-24 Workstation function, 3-13 palette error inquire, Close Workstation function, 3-9 9-2, 9-39 control array, 1-5 place graphic cursor at coordinate window, H-1, H-2 location, 9-2, 9-21 Copy Raster remove last graphic opaque function, 6-7 cursor, 9-2, 9-22 Transparent function, 6-9 reverse video off, 9-2, 9-17 D reverse video on, 9-1, 9-16 data format with bit image save palette driver state, files, 1-1 9-2, 9-37 device drivers, 1-2 select palette, 9-2, device handle, 1-4 9-30 device id number, 1-4 set palette driver state, 9-2, 9-35 E suppress palette messages, 9-2, 9-38 error messages, A-1 update metafile extents, 9-41 escape write metafile item, alpha cursor down, 9-1, 9-8 9-2, 9-43 alpha cursor home, 9-11 Exchange Button Change alpha cursor left, 9-1, 9-10 Vector function, 7-27 alpha cursor right, 9-1, 9-9 Exchange Cursor Change alpha cursor up, 9-1, 9-7 Vector function, 7-31 clear display list, 9-2, 9-26 Exchange Mouse Movement direct alpha cursor address, Vector function, 7-29 9-1, 9-14 extended run-length encoding, enter alpha mode, 9-1, 9-6 1-2 erase to end of alpha screen, external fonts, G-1 9-1, 9-12 erase to end of alpha text F line, 9-1, 9-13 exit alpha mode, 9-1, 9-5 Filled Area function, 4-8 form advance, 9-2, 9-23 Filled Rounded Rectangle change GEM VDI filename, 9-44 function, 4-25 hard copy, 9-2, 9-20 font data, G-1 home alpha cursor, 9-1, 9-11 font form, G-1 Index-1 ***************************************************************************** font format, G-1 Set Polyline End Styles, 5-12 font header, G-1 Set Text Face, 5-24 Form Advance Set User-defined Fill function, 9-23 Pattern, 5-37 function code Text, 4-6 escape, 9-1 Unload Fonts, 3-17 function Update Workstation, 3-15 Bar, 4-8 Cell Array, 4-11 G Circle, 4-28 Close Virtual Screen GDOS, 1-2 Workstation, 3-13 GDP Close Workstation, 3-9 Arc & Pie function, 4-19 Copy Raster, Opaque, 6-7 Bar function, 4-18 Copy Raster, Transparent, 6-9 Circle function, 4-21 Exchange Button Change Ellipse, 4-24 Vector, 7-27 Elliptical Arc and Pie, 4-22 Exchange Cursor Change Vector GEMVDI command, 2-19 function, 7-31 Get Pixel function, 6-13 Exchange Mouse Movement Graphics Device Operating Vector, 7-30 System, See GDOS Filled Area, 4-8 Filled Rounded Rectangle, H 4-25 Get Pixel, 6-13 hard copy escape, 9-20 Input Locator, Request Mode, header format with bit image 7-3 files, I-1 Input Locator, Sample Mode, hide cursor escape, 7-25 7-6 horizontal offset table, G-4 Input String, Request Mode, 7-15 I Input String, Sample Mode, 7-17 Input Locator Input Valuator, 7-9 Request Mode function, 7-3 Inquire Current Face Sample Mode function, 7-6 Information, 8-21 input parameters array, 1-5 Inquire Face Name and Index, input point coordinates, 1-5 8-19 Input String Justified Graphics Text, 4-27 Request Mode function, 7-15 Load Fonts, 3-16 Sample Mode function, 7-17 Open Virtual Screen Input Valuator function, 7-9 Workstation, 3-10 inquire cell array, 8-23 Open Workstation, 3-1 inquire character cell width, Polyline, 4-1 8-17 Polymarker, 4-4 inquire color representation, Rounded Rectangle, 4-25 8-5 Sample Keyboard State Inquire Current Face Information, 7-33 Information function, B-21 Sample Mouse Button State, Inquire Face Name and Index 7-26 function, 8-19 Set Graphic Text Special Inquire Palette Driver State Effects, 5-27 Escape, 9-33 Set Input Mode, 7-1 Inquire Palette Film Types Set Mouse Form, 7-19 Escape, 9-32 Index-2 ***************************************************************************** inquire text extent, 8-15 Rounded Rectangle function, interrupt for 68K, E-3 4-25 interrupt for 8086, E-1 run-length encoding, 1-1, 1-2 J S justified graphics text, 4-27 Sample Keyboard State Information function, 7-33 L Sample Mouse Button State function, 7-26 Load Fonts function, 3-16 Save Palette Driver State Escape, 9-37 M scan line, G-1 Select Palette memory requirements, 2-20 Escape, 9-30 metafile sub-opcodes, H-1, H-3 set character baseline vector, multiple workstations, 1-4 5-22 set character cell height N points mode, 5-18, 5-20 set character height NDC, 1-4, 1-6 absolute mode, 5-18 normalized device coordinates, Set Clipping Rectangle 1-4, 1-6 function, 3-19 set color representation, 5-4 0 set fill color index, 5-35 set fill interior style, 5-32 Open Virtual Screen Workstation set fill perimeter visibility, function, 3-10 5-36 Open Workstation function, 3-1 set fill style index, 5-33 output parameters, 1-5 set graphic text alignment, output point parameters, 1-5 5-30 Output Window set graphic text color index, Escape, 9-24 5-26 set graphic text special P effects, 5-27 Set Input Mode function, 7-1 Palette Error Inquire Set Mouse Form function, 7-19 Escape, 9-39 Set Palette Driver State physical page size, H-1 Escape, 9-32 plotter functions, 2-13 set polyline color index, 5-11 Polaroid Palette Escapes, 9-31 Set Polyline End Styles Polyline function, 4-1 function, 5-12 Polymarker function, 4-4 set polyline line type, 5-6 set polyline line width, 5-9 R set polymarker color index, 5-17 registers for 68K, E-3 set polymarker height, 5-16 registers for 8086, E-1 set polymarker type, 5-14 required functions for set text color index, 5-24 printers, 2-11 Set Text Face function, 5-24 required functions for screens, Set User-defined Fill Pattern 2-9 function, 5-33 reserved metafile sub-opcodes, set user-defined line style, H-1 5-8 Index-3 ***************************************************************************** set writing mode, 5-1 show cursor, 7-23 stack requirements, 2-20 sub-opcodes, H-1 Suppress Palette Messages Escape, 9-38 system fonts, G-1 T Text function, 4-6 transforming points, 1-6 U Unload fonts function, 3-17 Update Workstation function, 3-15 V VDI, 1-5 Virtual Device Interface, 1-5 VDI, 1-5 WORD, 2-1 Write Metafile Item Escape,. 9-43 Index-4 ***************************************************************************** .