Microsoft Programmer's Library 1.3

home *** CD-ROM | disk | FTP | other *** search

/ Microsoft Programmer's Library 1.3 / Microsoft_Programmers_Library.7z / MPL / os2 / os2dev.txt < prev next >

Wrap

Text File | 2013-11-08 | 1.6 MB | 50,465 lines

Text Truncated. Only the first 1MB is shown below. Download the file for the complete contents. Microsoft Operating System/2 - Device Driver Reference ──────────────────────────────────────────────────────────────────────────── Microsoft(R) Operating System/2 - Device Driver Reference Version 1.2 ──────────────────────────────────────────────────────────────────────────── Information in this document is subject to change without notice and does not represent a commitment on the part of Microsoft Corporation. The software and/or databases described in this document are furnished under a license agreement or nondisclosure agreement. The software and/or databases may be used or copied only in accordance with the terms of the agreement. The purchaser may make one copy of the software for backup purposes. No part of this manual and/or database may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying, recording, or information storage and retrieval systems, for any purpose other than the purchaser's personal use, without the written permission of Microsoft Corporation. (C) Copyright Microsoft Corporation, 1990. All rights reserved. Printed in the United States of America. Patent #4,825,358 Patent #4,779,187 Microsoft(R), MS(R), MS-DOS(R), the Microsoft logo, and InPort(R) are registered trademarks, and Windows(tm) is a trademark, of Microsoft Corporation. SideKick(R) is a registered trademark of Borland International, Inc. IBM(R), PC/AT(R), and PS/2(R) are registered trademarks of International Business Machines Corporation. SY10190-1289 OEMO786-1Z Preface Notational Conventions Other References Chapter 1 Overview of Base and Installable Device Drivers 1.1 MS OS/2 Device Drivers 1.2 Device Driver Logical Structure 1.3 Device Driver Segment Structure 1.4 Device Driver Executable File Format 1.5 Device Driver Header Chapter 2 Device Commands 2.1 Introduction 2.2 Request Packets 2.3 MS OS/2 Device Driver Commands Chapter 3 Device Helper Services 3.1 Device Helper Services 3.2 Using DevHlp Routines Chapter 4 Base Video Device Handlers 4.1 Introduction 4.2 BVH Installation and the DevEnable Function 4.3 VDH Function Calls 4.4 LVB Formats 4.5 VDH Function Reference Chapter 5 Mouse Device Drivers 5.1 Introduction 5.2 System-supplied IDC Functions 5.3 Device-dependent Driver Requirements 5.4 Mouse IDC Function Reference Chapter 6 Overview of Presentation Manager Device Drivers 6.1 Introduction 6.2 Overview 6.3 The Graphics Engine 6.4 Presentation Manager Device Drivers 6.5 Installed Simulations 6.6 Device Driver Components Chapter 7 Graphics Functions 7.1 Introduction 7.2 Function Groups 7.3 Function Directory Chapter 8 Spooler Functions 8.1 Introduction Chapter 9 Types, Macros, Structures 9.1 Introduction 9.2 Types 9.3 Macros 9.4 Structures Chapter 10 File Formats 10.1 Introduction 10.2 Font Files 10.3 Keyboard Translation Tables 10.4 Resource-File Formats Chapter 11 MS OS/2 System Debugger 11.1 Introduction 11.2 Debugger Command Reference Chapter 12 Assembly-Language Macros 12.1 Introduction 12.2 Cmacros Reference Appendix A A Device Driver Installation A.1 Introduction A.2 Device Driver Profile Appendix B B Setting Up the System Debugger B.1 Introduction B.2 Symbol Files Appendix C C Dos Functions for Installable Device Drivers C.1 Introduction C.2 Function Reference Appendix D D Presentation Manager Spooler-Queue Processor D.1 Overview D.2 Functions Appendix E E OEMHLP$ EISA Configuration Support E.1 Introduction E.2 Calls from Base Device Drivers E.3 Calls from Installable Drivers E.4 EISA Configuration Buffers Preface ──────────────────────────────────────────────────────────────────────────── This manual describes the Microsoft(R) Operating System/2 (MS(R) OS/2) device driver interfaces, a set of routines that MS OS/2 device drivers use or supply to carry out tasks. MS OS/2 device drivers consist of routines that carry out device-specific actions as requested by the operating system. To carry out a requested action, device drivers may, in turn, call routines in the operating system. For any device driver, the set of routines that the driver must have combined with the set of system routines that the driver may call is the MS OS/2 interface for that particular device. The MS OS/2 interfaces for base and installable device drivers are defined in assembly language or in the C language. Interfaces for Presentation Manager device drivers are defined in the C language. This manual has three parts and five appendixes: Part 1 Chapters 1 through 5 describe the interfaces for base and installable device drivers. Part 2 Chapters 6 through 10 describe the interfaces for Presentation Manager device drivers. Part 3 Chapters 11 and 12 describe the MS OS/2 version 1.2 tools for the development and testing of device drivers. Chapter 1, "Overview of Base and Installable Device Drivers," explains the logical and segment structure, file format, and header for MS OS/2 version 1.2 device drivers. Chapter 2, "Device Commands," defines the device command interface. MS OS/2 uses this interface to send device commands to base and installable device drivers that run at ring-0. Chapter 3, "Device Helper Services," defines the MS OS/2 device helper (DevHlp) interface. MS OS/2 provides the DevHlp routines for base and installable device drivers that need to carry out specific tasks, such as allocating memory. Chapter 4, "Base Video Device Handlers," defines the structure of an MS OS/2 version 1.2 BVH (base video handler) and the functions that it supplies. Chapter 5, "Mouse Device Drivers," defines the IDC (inter-device driver communication) interface between the device-independent mouse driver supplied by MS OS/2 version 1.2 and any device-dependent mouse driver that is added to the system. Chapter 6, "Overview of Presentation Manager Device Drivers," explains the basics of Presentation Manager device drivers, their components, the graphics engine, installed simulations, and the corresponding data structures. Chapter 7, "Graphics Functions," defines each function of the graphics interface. MS OS/2 uses this interface to send graphics commands to a particular display or printer driver. Chapter 8, "Spooler Functions," defines the functions that a device driver uses to access the spooler (the print-queue manager). The spooler is a dynamic-link library containing functions that create and store print jobs. Chapter 9, "Types, Macros, Structures," defines the data types, macros, and structures used with the graphics interface. Chapter 10, "File Formats," defines the files used with Presentation Manager device drivers, such as font files and resource files containing bitmaps, icons, and cursors. Chapter 11, "MS OS/2 System Debugger," defines the system-debugger command keys, parameters, and commands for testing and debugging device driver code. Chapter 12, "Assembly-Language Macros," defines the Cmacros that can be used to simplify the interface between assembly-language device drivers and the function and segment conventions of languages such as C. Appendix A, "Device Driver Installation," describes the ddinstal utility. Appendix B, "Setting Up the System Debugger," describes the equipment needed to use the system debugger, how to set it up, and how to set up the system-debugger software. Appendix C, "Dos Functions for Installable Device Drivers," describes those functions that installable ring-0 drivers may call during initialization. Appendix D, "Presentation Manager Spooler Queue Processor," describes the functions that the spooler calls to access the print-queue processor. This processor is a dynamic-link library containing functions that prepare a print job for printing or plotting on an output device. Appendix E, "OEMHLP$ EISA Configuration Support," describes how a base or installable driver can get configuration information if it is running on an EISA (extended industry standard architecture) machine. This manual is intended to fully describe the MS OS/2 device driver interfaces, together with the structures and file formats used with each routine. However, it does not show how to use these interfaces to carry out specific tasks, nor how to write, compile, and link programs containing the interfaces. For more information about these topics, see the Microsoft Operating System/2 Programmer's Reference. Notational Conventions The following notational conventions are used throughout this manual: Convention Meaning ──────────────────────────────────────────────────────────────────────────── bold Bold is used for keywords, such as function, data-type, structure, and macro names. These names are spelled exactly as they should appear in source programs. italics Italics are used to name a (formal) parameter; the name is a metasymbol, and any required parameter must be replaced by an actual argument. monospace Monospace type is used for example code fragments and for layout diagrams. Other References For information on 80286 or 80386 architecture, please refer to the following books: iAPX 286 Programmer's Reference Manual including the iAPX 286 Numeric Supplement, 1985, Intel Corporation. iAPX 286 Operating Systems Writer's Guide, 1983, Intel Corporation. 80386 Programmer's Reference Manual, 1986, Intel Corporation. 80387 Programmer's Reference Manual, 1987, Intel Corporation. Chapter 1 Overview of Base and Installable Device Drivers ──────────────────────────────────────────────────────────────────────────── 1.1 MS OS/2 Device Drivers A device driver is the intermediary between a peripheral hardware device and MS OS/2. Figure 1.1 illustrates this relationship, using a keyboard as a representative peripheral device. (This figure may be found in the printed book). .AR 210p As the system boots, MS OS/2 must load certain essential device drivers in the following order: ■ Clock driver─clock0x.sys names a replacement clock driver. ■ Display driver─screen0x.sys names a replacement display driver. ■ Keyboard driver─kbd0x.sys names a replacement keyboard driver. ■ Printer driver─print0x.sys names a replacement printer driver. ■ Disk driver─disk0x.sys names a replacement disk driver. These essential drivers are called base drivers. MS OS/2 version 1.2 combines its own base drivers into a single device driver called basedd01.sys for AT-class machines, basedd02.sys for PS/2 machines, or basedd03.sys for Model 30 286 machines, and locates basedd0x.sys in high memory. Early in the boot process, MS OS/2 steps through the base driver table in basedd0x.sys and determines whether there is a replacement file for one (or more) of the base drivers. If a replacement file exists, the system loads and initializes this replacement driver, locates it in low memory, and ignores the corresponding portion of basedd0x.sys after system boot. MS OS/2 inserts three stub base device drivers between the base keyboard and printer drivers of basedd0x.sys. Device driver programmers should not attempt to replace any of these stubs with another base device driver. During the boot process, MS OS/2 can also load additional device drivers, according to the device directives found in the config.sys file. Such drivers are called installable drivers. Both base and installable device drivers have the following common features: ■ Logical structure driver must have a strategy routine to handle incoming device commands and an interrupt routine to handle hardware interrupts. ■ Physical structure driver must have a particular .exe file image. ■ Bimodal operation driver can handle incoming device commands and hardware interrupts under the current CPU execution mode, whether it is protected or real. ■ Reentrancy driver must be reentrant so that it can manage overlapping I/O requests for its device in a multitasking environment. ■ Interfaces with the MS OS/2 kernel kernel sends device-specific commands as request packets to the appropriate driver. The driver, in turn, can call the MS OS/2 DevHlp routines in order to carry out these requests. ■ Classification as a character or a block driver drivers control devices that transfer data one byte at a time. Block drivers control devices that transfer data in blocks, rather than byte-by-byte. ■ Incorporation into the system at boot time drivers load early in the boot process. Installable drivers load slightly later, because they usually support devices that are add-ons to the standard system. However, an installable driver also may replace a system-supplied base driver when MS OS/2 processes the config.sys file during system boot. For more detailed information about the request-packet interface, see Chapter 2, "Device Commands." For more detailed information about the DevHlp routines, see Chapter 3, "Device Helper Services." 1.2 Device Driver Logical Structure MS OS/2 device drivers have the following functional parts: ■ Strategy routine driver's strategy routine handles I/O requests and other device commands via a request-packet interface with the kernel. The strategy routine must be bimodal (able to run both in protected and real modes) and must follow the far call/ret model. The kernel saves and restores registers for the strategy routine. ■ Hardware-interrupt handler driver's interrupt routine, or interrupt handler, is called when a hardware interrupt occurs. It must be bimodal and must follow the far call/ret model. When the interrupt handler has processed an interrupt, it must clear the carry (C) flag just before its far ret. This routine should run as much as possible with interrupts enabled, and it should dismiss the interrupt at the PIC (programmable interrupt controller) as soon as possible with a call to the DevHlp routine EOI. ■ ROM BIOS handler (optional) driver's ROM BIOS software interrupt handler, if any, runs only in real mode. The driver's strategy routine may install such a handler with a call to the DevHlp routine SetROMVector in order to intercept a particular ROM BIOS software interrupt. The handler may call the DevHlp routine ROMCritSection to protect a critical section of ROM BIOS execution. Figure 1.2 shows the functional parts of a device driver and their relationship to the system. (This figure may be found in the printed book). .AR 181p Note that the MS OS/2 kernel routes all I/O requests to the driver's strategy routine, which calls other routines in the driver, usually through a command-dispatch table. The strategy routine must call the driver's other routines that process device commands. 1.3 Device Driver Segment Structure MS OS/2 version 1.2 device drivers may have multiple code and data segments. However, the driver's first-linked segments must be a data segment followed by a code segment. MS OS/2 assumes that these are the driver's primary data and code segments and that they must be permanently fixed in low memory (below 640K) after driver initialization, which has the following effects: ■ Data in the driver's primary data segment is directly accessible, whatever the operating mode. Data used by the driver's interrupt handler should be in this segment. The primary data segment also contains the driver's command-dispatch table, which defines symbolic offsets to the driver's routines that process particular device commands. ■ Code in the driver's primary code segment must be executable in real and protected modes. There must be an entry point for the driver's strategy routine in this segment. The driver's bimodal hardware-interrupt handler and real-mode ROM BIOS handler, if any, must also be in this segment. ■ When it passes control to the device driver, MS OS/2 sets the ds and cs registers to these segments, using a protected-mode selector or a real-mode segment value, depending on the current operating mode. The driver's primary data segment must contain a device driver header as its initial data item. The driver must define a header in this segment for each character device it supports. For more information about device driver headers, see Section 1.5. The driver's primary code segment must contain an entry point for its strategy routine. MS OS/2 calls the strategy routine to handle I/O requests and other device commands, such as driver initialization, via a request-packet interface with the kernel. For more information about the request packet for each device command, see Chapter 2, "Device Commands." The driver's other code and data segments, if any, are loaded into high memory. MS OS/2 assumes that such segments can be discarded after the driver initializes. However, you can mark segments to be kept in high memory with the Microsoft Segmented-Executable Linker (link), version 5.0. Set up permanent segments in your driver's module definition file by using the link SEGMENTS directive and the IOPL option (thereby overloading IOPL since your driver runs at ring-0 after it initializes). Note that MS OS/2 loads and keeps the driver's non-primary but permanent data and code segments (if any) above 640K, which has the following effects: ■ Data in such segments cannot be accessed in real mode. The virtual address of a data item is always a protected-mode selector:offset. ■ Code in such segments is executable only in protected mode. The address of an entry point is a selector:offset. ■ MS OS/2 assumes that such segments can be moved and swapped but not discarded. Your device driver can fix a segment permanently in high memory, however, by calling the DevHlp routine Lock when it initializes. For more information about Lock, see Chapter 3, "Device Helper Services." After the device driver initializes, MS OS/2 discards all extra code or data segments that are not marked as permanent in the link module definition file. Device drivers that must be compatible with MS OS/2 version 1.0 may have only the single data segment and single code segment that are required of MS OS/2 version 1.2 device drivers. 1.4 Device Driver Executable File Format One of the ways a device driver file differs from an ordinary .exe file is that the initial (primary) data segment must contain a device driver header at the top of the segment. The data segment must precede the code segment so that the device driver header follows the .exe file header. Figure 1.3 shows the file image of an MS OS/2 device driver. (This figure may be found in the printed book). .AR 180p A character driver that supports more than one device must define a header in its primary data segment for each character device it supports. 1.5 Device Driver Header The device driver header is a static data structure that defines a device within the system. For example, this header supplies information that the kernel's request router (see Figure 1.2) uses, such as the code segment offset to the driver's strategy routine and whether the driver controls a character or block device. Figure 1.4 shows the layout of the 26-byte device driver header with each field and its size. (This figure may be found in the printed book). +--------------------------------+ | Pointer_To_Next_Header | DWORD +--------------------------------+ | Device_Attribute | WORD +--------------------------------+ | Offset_To_Strategy_Routine | WORD +--------------------------------+ | Offset_To_IDC_Routine* | WORD +--------------------------------+ | Name_Or_Units | 4 WORDS +--------------------------------+ | Reserved | 4 WORDS +--------------------------------+ *Reserved = 0 if the driver does not participate in inter-device driver communication (IDC) The following sections explain each field in the device driver header. 1.5.1 Pointer_to_Next_Header Field Both words of the Pointer_to_Next_Header field should be set to -1 for drivers that support one device. For drivers that support more than one character device, this field should be set to the header for the next character device, as follows: ■ The first word of this dword field is the offset to the next header. ■ The second word is the segment address. ■ Both words of the last header in a chain of linked headers should be set to -1. 1.5.2 Device_Attribute Field The Device_Attribute field of the device driver header defines the characteristics of the device driver. Figure 1.5 shows the format of the Device_Attribute field. (This figure may be found in the printed book). 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ | C | I | I | S | O |///| |///|///|///| C | N | S | K | | H | D | B | H | P |///| Level |///|///|///| L | U | C | B | | R | C | M | R | N |///| |///|///|///| K | L | R | D | +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ The bit fields in the Device_Attribute word indicate the following: Bit field Usage ──────────────────────────────────────────────────────────────────────────── 0 Standard Input─Set this bit if your driver will be the new standard-input character device driver. 1 Standard Output─Set this bit if your driver will be the new standard-output character device driver. 2 Null Attribute─Set this bit if your character driver is a null device. If set, this bit tells MS OS/2 that the system's null device is being used, but you cannot reassign the null device. 3 Clock Device─Set this bit if your character driver is the new standard system clock driver. 4 Reserved = 0 5 Reserved = 0 6 Reserved = 0 7-9 Level─Set this field to 001B (DevLev_1 driver) or to 010B (DevLev_2 driver) for a character driver or for a block driver that supports removable media and the logical partition types 1, 4, and 6. Set this field to 010B (DevLev_2 driver) for a block driver that also supports the logical partition type 7, which is the partition type of HPFS (High Performance File System). MS OS/2 version 1.2 sends all DevLev_2 device drivers an extended GenericIOCtl request packet with more information than it sends to DevLev_1 drivers. MS OS/2 version 1.2 also sends extended Read, Write, and WriteVerify request packets to DevLev_2 block drivers. The system sends request packets that are identical to those of MS OS/2 versions 1.0 and 1.1 to DevLev_1 drivers. For more information about GenericIOCtl, Read, Write, and WriteVerify requests, see Chapter 2, "Device Commands." 10 Reserved = 0 11 Open/Close─For character device drivers, set this bit if your driver must receive OpenDevice and CloseDevice request packets. For more information about OpenDevice and CloseDevice requests, see Chapter 2, "Device Commands." 11 Removable Media─For block device drivers, set this bit if your driver handles removable media. 12 Shared─For character device drivers, set this bit if file-system sharing rules apply to your driver as they apply to any other file-system name. Under these rules, a physical device may have only one logical name (no aliases), and a device name is protected by the sharer. For character device drivers, clear this bit (default) if your driver uses aliases and assumes responsibility for providing contention control. For block device drivers, this bit has no meaning and must be zero. 13 Media Type─For block device drivers, set this bit if your driver uses information in the BPB (BIOS parameter block) to determine the media type or if your driver supports the logical partition type 7 of HPFS. For character device drivers, this bit has no meaning and must be zero. 14 Inter-Device Driver Communication─Set this bit if your driver participates in inter-device driver communication to indicate that the Offset_to_IDC_Routine field has been set up (see Section 1.5.4). Clear this bit if your driver does not communicate with another device driver. 15 Character Driver─Set this bit if your driver is a character device driver. Clear this bit if the driver is a block device driver. 1.5.3 Offset_to_Strategy_Routine Field The Offset_to_Strategy_Routine field of the device driver header contains the offset from the driver's primary code segment to the entry point of its strategy routine. The MS OS/2 request router calls the driver's strategy routine by using the driver's cs selector or segment value and this word field value as a far pointer. 1.5.4 Offset_to_IDC_Routine Field The Offset_to_IDC_Routine field of the device driver header contains the offset from the driver's primary code segment to the entry point that is callable by other device drivers. Note that bit 14 of the Device_Attribute field must be set, indicating that the driver participates in inter-device driver communication, for this field to have meaning. The Offset_to_IDC_Routine field and bit 14 of the Device_Attribute field should be zero if the driver is not an IDC target driver. 1.5.5 Name_or_Units Field The Name_or_Units field of the device driver header contains the name of the device supported by a character device driver, or it contains the number of logical units supported by a block device driver. For a character device driver, the Name_or_Units field must contain uppercase ASCII characters and must be left-justified and blank-filled at the right. Applications identify the device for I/O by this name. To avoid a conflict between identical device and file names, choose a device name with some unusual character such as a dollar sign ($). Otherwise, if there are identical device and file names, an application that calls DosOpen or DosOpen2 for the file will always open the device. For character device drivers that use ABIOS (advanced basic I/O system), the device name represents a single device identified by the logical ID (LID). For a block device driver, the first byte of the Name_or_Units field can contain the number of units supported by the driver. However, this is optional because MS OS/2 fills this field during device driver initialization. For block device drivers that use ABIOS, the number of units represents the number of devices (or units) under the LID. Chapter 2 Device Commands ──────────────────────────────────────────────────────────────────────────── 2.1 Introduction MS OS/2 calls a device driver's strategy routine to handle I/O requests via a request-packet interface with the kernel. For each request packet sent to the driver, MS OS/2 supplies certain input parameters in a static, 13-byte Request Header that has a byte-sized Command_Code field at offset 2. The driver examines the Command_Code value to determine what operation it should carry out. For a subset of requests, MS OS/2 supplies additional information in the non-static, Command-specific_Data area of the request packet and expects the driver to return updated information on a command-specific basis. For certain requests, the Command-specific_Data area includes extra fields for MS OS/2 version 1.2 DevLev_2 drivers. When it has carried out the appropriate operation, the driver must always update the word-sized Status field at offset 3 in the Request Header of the request packet. For more information about request packets in general and the Request Header fields in particular, see Section 2.2. For detailed information about command-specific requests, see Section 2.3. For more information about device driver strategy routines and about MS OS/2 version 1.2 DevLev_1 and DevLev_2 drivers, see Chapter 1, "Overview of Base and Installable Device Drivers." 2.2 Request Packets MS OS/2 calls the device driver's strategy routine with the es:bx register pair pointing to the request packet. The pointer is a virtual address─a selector:offset or a segment:offset─depending on the current operating mode. However, MS OS/2 does not guarantee that the order of API requests issued by multiple threads will be preserved when the corresponding request packets arrive at the device driver. Multiple application threads (and threads created by the DosReadAsync and DosWriteAsync functions) can get blocked in the system, so an API request packet from an unblocked thread can arrive out of order. The device driver must provide a synchronization mechanism between itself and application processes (and threads) if it supports multiple outstanding requests and if request-packet ordering must be preserved. Each request packet has two parts: a 13-byte Request Header and a variable-sized Command-specific_Data area. Figure 2.1 shows the layout of MS OS/2 version 1.2 request packets, including each field in the Request Header with its size and its offset from the virtual pointer in es:bx, and the Command-specific Data area. MS OS/2 calls the device driver's strategy routine for each request and always passes access to the request packet in the es:bx register pair. The strategy routine may store this pointer as a virtual or converted address in its primary data segment as part of its request-queue management scheme. The device driver's interrupt handler accesses the head of the work queue in the driver's primary (low-memory) data segment to get a pointer to the request packet. 2.2.1 Length_of_Request_Packet Field The Length_of_Request_Packet field is set to the number of bytes in the request packet. The length is the sum of the 13-byte Request Header and the number of bytes in the Command-specific_Data area. (This figure may be found in the printed book). +----------------------------+ --| Length_of_Request_Packet | BYTE PTR ReqPak+0 | +----------------------------+ | | Block_Device_Unit_Code | BYTE PTR ReqPak+1 | +----------------------------+ | Static | Command_Code | BYTE PTR ReqPak+2 | Request +----------------------------+ | Header | Status | WORD PTR ReqPak+3 | +----------------------------+ | | Reserved | DWORD PTR ReqPak+5 | +----------------------------+ | | Queue_Linkage | DWORD PTR ReqPak+9 | +----------------------------+ --| Command-specific_Data | BYTE PTR ReqPak+0DH ~ ~ DevLev_1 drivers: 0-13 BYTEs | | DevLev_2 drivers: 0-16 BYTEs +----------------------------+ Note that MS OS/2 version 1.2 request packets for DevLev_1 drivers have a Command-specific_Data area that varies from zero to 13 bytes in size, depending on the command. For DevLev_1 drivers, the size of this area is identical to the request packets for the same commands in MS OS/2 versions 1.0 and 1.1. However, MS OS/2 version 1.2 supplies extra information to DevLev_2 drivers, so the size of the Command-specific_Data area varies from zero to 16 bytes for DevLev_2 drivers. 2.2.2 Block_Device_Unit_Code Field The Block_Device_Unit_Code field of the Request Header identifies the logical unit for which the request is intended. This field has no meaning for character device drivers, so they can ignore it. 2.2.3 Command_Code Field The Command_Code field of the Request Header indicates which operation the driver should carry out. Table 2.1 lists the Command_Code value for every MS OS/2 version 1.2 request, in numeric order, and indicates whether it is sent to block (BLK) or character (CHR) device drivers, or both. <TT>Summary of Commands for Device Drivers"</TT> Code Command Block/Character device drivers ──────────────────────────────────────────────────────────────────────────── 00 Init BLK, CHR 01 MediaCheck BLK 02 BuildBPB BLK 03 Reserved 04 Read BLK, CHR (input) 05 Nondestruc CHR tiveReadNo Wait 06 InputStatu CHR s 07 InputFlush CHR 08 Write BLK, CHR (output) 09 WriteVerif BLK, CHR y 0AH OutputStat CHR us 0BH OutputFlus CHR h 0CH Reserved 0DH OpenDevice BLK, CHR 0EH CloseDevic BLK, CHR e 0FH RemovableM BLK edia 10H GenericIOC BLK, CHR tl 11H ResetMedia BLK 12H GetLogical BLK DriveMappi ng 13H SetLogical BLK DriveMappi ng 14H Deinstall CHR 15H Reserved 16H Partitiona BLK bleFixedDi sks 17H GetFixedDi BLK sk/Logical UnitMap 18H NonCaching BLK Read 19H NonCaching BLK Write 1AH NonCaching BLK WriteVerif y 1BH Reserved 1CH PrepareFor BLK, CHR SysShutdow n For detailed information about each command, see Section 2.3. 2.2.4 Status Field The Status field of the Request Header describes the state of the request. When the kernel calls the driver's strategy routine, it defines Status field values only for OpenDevice (Command_Code value 0DH) and CloseDevice (0EH) request packets: ■ For an OpenDevice request, bit 3 of the Status field is set if the DosMonOpen function caused generation of the request packet. Otherwise, the DosOpen or DosOpen2 function caused generation of the request packet. ■ For a CloseDevice request, bit 3 of the Status field is set if the DosMonClose or DosClose function caused generation of the request packet with a handle that was generated by the DosMonOpen function. Otherwise, the DosClose function caused generation of the request packet with a non-monitor handle. The driver's strategy routine carries out whatever operations it must in order to handle the request, possibly calling a command-specific subroutine or detecting an error condition. Then, it must update the Status field to describe the resulting status of the request before it returns control to the kernel. Figure 2.2 defines the format of the resulting Status field. (This figure may be found in the printed book). 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ | E | D |///|///|///|///| B | D | | | R | E |///|///|///|///| U | O | error code if error | | R | V |///|///|///|///| S | N | | +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ The fields in the Status word indicate the following: Field Usage ──────────────────────────────────────────────────────────────────────────── 0-7 Error code─Set the low-order byte to a code for one of the standard errors (listed in Section 2.2.5) when bit 15 is set to indicate an error but bit 14 is clear. A driver may define a private error code for use when bit 14 is also set. 8 Done─Set this bit when an operation is complete before the driver exits. 9 Busy─Set this bit when the device is busy only for InputStatus (Command_Code value 06), OutputStatus (0AH), or RemovableMedia (0FH) requests. 10-13 Reserved = 0 14 Driver-defined error─Set this bit in conjunction with bit 15 for a driver-defined error. 15 Error─Set this bit for an error and set the appropriate standard error code in bits 0 to 7, provided bit 14 is clear. 2.2.5 Errors When the Status field in the returned request packet indicates an error (bit 15 is set), MS OS/2 processes the error code in one of the following ways and returns the result to the application that made the request: ■ If the IOCtl category code bit is set (user-defined), the byte-sized error code is combined with 0FF00H by the OR operator. ■ If the IOCtl category code bit is clear (system-defined) but bit 14 is set, the driver-defined, byte-wide error code is combined with 0FE00H by the OR operator. ■ Otherwise, the error code is a standard error code that MS OS/2 maps to one of the API return codes. The following lists the standard error codes that the driver may set in bits 0 to 7 of the Status field: Error code Means ──────────────────────────────────────────────────────────────────────────── 00 Write-protect violation 01 Unknown unit 02 Device not ready 03 Unknown command 04 CRC error 05 Bad drive request structure length 06 Seek error 07 Unknown media 08 Sector not found 09 Printer out of paper 0AH Write fault 0BH Read fault 0CH General failure 0DH Change disk (logical switch) 0EH Reserved 0FH Reserved 10H Uncertain media 11H Character I/O call interrupted 12H Monitors not supported 13H Invalid parameter 14H Device already in use The driver determines which standard error code to return in the Status field, according to the nature of the device(s) it supports. The driver should return error code 03 (Unknown command) if it ever gets a request that is inappropriate to the kind of device that it supports and set the error and done bits of the Status field. When the state of the media in the drive is uncertain, a diskette device driver should return error code 10H (Uncertain media), but this response should not be returned for an Init request (Command_Code value 00). For fixed disks, the device driver must begin in an uncertain-media state to have the media correctly labeled. Use the following general guidelines to determine when to respond with error code 10H (Uncertain media): ■ When a drive-not-ready condition is detected, return Uncertain media to all subsequent requests until a ResetMedia (Command_Code value 11H) request is received. ■ When accessing removable media without change-line support and a time delay of two or more seconds has occurred, return Uncertain media. ■ When the state of the change-line indicates that the media might have changed, return Uncertain media. COM drivers should respond with error code 14H (Device already in use) when they cannot open a port in response to an OpenDevice request (Command_Code value 0DH) because another driver has already opened the same port but not yet closed it. COM drivers should return error code 0CH (General failure) when they cannot open a port for any other reason. Character drivers should respond with error code 11H (Character I/O call interrupted) when performing I/O for a blocked thread and the thread terminates before the requested operation was complete. Drivers that do not support monitors should respond with error code 12H (Monitors not supported) for all monitor requests caused by an application call to DosMonOpen, DosMonClose, or the IOCtl function DEV_QUERYMONSUPPORT (category 0BH, function 60h). All drivers should respond with error code 13H (Invalid parameter) when they receive a request packet with one or more fields containing invalid values. 2.2.6 Queue_Linkage Field The Queue_Linkage field in the Request Header may contain a pointer to the next request packet so the driver can maintain a linked list of request packets. The device driver may manage its own queue, or it can use the DevHlp request-packet or character-queue routines described in Chapter 3, "Device Helper Services." Note that the pointer to a request packet is bimodal: valid in both protected and real modes. Such a pointer can be used directly from the Queue_Linkage field, without converting it to a physical address that must be reconverted if a mode switch occurs. 2.2.7 Command-specific_Data Area The Command_Code field in the Request Header tells the driver which function to perform. The Command-specific_Data area in the request packet contains any parameters and additional function or return codes for the command. The size of this area varies from zero to 13 bytes for DevLev_1 drivers, depending on the command. For DevLev_2 drivers, the size of this area varies from zero to 16 bytes. All dword pointer parameters are stored with offset first and selector/segment next in the Command-specific_Data area. For detailed information about the Command-specific_Data area for each MS OS/2 version 1.2 request packet, see Section 2.3, next. 2.3 MS OS/2 Device Driver Commands The following sections explain the device driver commands in numeric order by command code (see Table 2.1 for a list of Command_Code values). The structure of each request packet shows an abbreviated Request Header (see Figure 2.1 for details), followed by the fields, if any, of the Command-specific_Data area. █ Init ──────────────────────────────────────────────────────────────────────────── +--------------------------------------+ | Request Header | 13 BYTEs +--------------------------------------+ | Data_1 | BYTE PTR ReqPak+0DH | (Number_of_Units on exit) | +--------------------------------------+ | Pointer_1 | DWORD PTR ReqPak+0EH | (Pointer_to_Device_Help on entry) | | (Offset_Ending_Code_Address on exit) | | (Offset_Ending_Data_Address on exit) | +--------------------------------------+ | Pointer_2 | DWORD PTR ReqPak+12H | (Pointer_to_Init_Arguments on entry) | | (Pointer_to_BPB_Array on exit) | +--------------------------------------+ | Data_2 | | (Drive_Number on entry) | BYTE PTR ReqPak+14H +--------------------------------------+ The Init request tells the driver to initialize the device. The Command_Code value in the Request Header is 00. Comments On entry, the Command-specific_Data area of the request packet contains the following fields as input to the device driver: ■ Pointer_1 is set to point to the DevHlp strategy routine's entry point. The DevHlp entry point is a bimodal address; the driver may call a DevHlp routine by setting up the appropriate registers and loading the dl register with the DevHlp function code (for more information, see Chapter 3, "Device Helper Services"). ■ Pointer_2 is set to point to device-specific information needed to initialize the device. For every base device driver that is preloaded with the operating system, the device-specific arguments are passed by the system initialization process. For an installable device driver, device-specific initialization arguments are obtained from its device line in the config.sys file, so each driver can use configurable parameters to initialize itself and the device. ■ Data_2 is set to the drive number for the first block device unit. At initialization time, the device driver runs as a thread under a protected-mode process at application level, with I/O privilege. Both base and installable device drivers may call one or more DevHlp routines that are permitted during initialization. Installable device drivers may also call the following MS OS/2 base system functions: Function Description ──────────────────────────────────────────────────────────────────────────── DosBeep Generates sound from the speaker. DosCaseMap Performs case mapping. DosChgFilePtr Changes (moves) a file read/write pointer. DosClose Closes a file handle. DosDelete Deletes a file. DosDevConfig Gets a device's configuration. DosDevIOCtl I/O Control (IOCtl) for devices. DosDevIOCtl2 I/O Control (IOCtl) for devices. DosFindClose Closes a search-directory handle. DosFindFirst Finds the first matching file. DosFindFirst2 Finds the first matching file. DosFindNext Finds the next matching file. DosGetEnv Gets the address of a process environment string. DosGetMessage Gets a system message from a system-message file. DosOpen Opens a file. DosOpen2 Opens a file. DosPutMessage Outputs text to the indicated handle. DosQCurDir Queries the current directory. DosQCurDisk Queries the current disk. DosQFileInfo Queries file information. DosQFileMode Queries the file mode. DosRead Reads from a file. DosSMRegisterDD Registers a driver with Session Manager for event notifications. DosWrite Writes synchronously to a file. For more information about these system functions, see Appendix C, "Dos Functions for Installable Device Drivers." On successful completion of initialization, the device driver must set fields in the request packet as follows: ■ A block driver must set the Data_1 field to the number of logical block devices or units available (Number_of_Units). MS OS/2 will assign sequential drive letters to these units. Character device drivers should set the Data_1 field to zero. ■ The driver must set the first word of the Pointer_1 field to the offset of the last byte in the driver's initial (and current) code segment (Offset_Ending_Code_Address). The driver must set the next word of the Pointer_1 field to the offset of the last byte in the driver's initial data segment (Offset_Ending_Data_Address). Doing this allows a device driver to release code and data that is used only by the driver's initialization routine. First, the initialization-only code and data must be located at the end of the appropriate segments. Then, as the final step in initialization, the device driver sets the offsets for the end of the code segment and the end of the data segment to retain the code and data that it needs after initialization. Doing this also allows every device driver to load with a maximum-sized data segment and then allows the kernel to release memory that each driver does not need from the primary (low-memory) data and code segments. ■ A block device driver must set the Pointer_2 field to the BPB (BIOS parameter block) array for the logical block devices or units that it supports (Pointer_to_BPB_Array). Character device drivers must set the Pointer _2 field to zero. ■ The driver must set the Status field in the Request Header to 0100H indicating no error and done. The driver must return the following values in the following fields of the request packet to indicate an initialization failure: Value Field ──────────────────────────────────────────────────────────────────────────── 810CH Status (General failure error code and done). 00H Data_1 (Number_of_Units for block device drivers only). 0000H Pointer_1 (first word for Offset_Ending_Code_address). 0000H Pointer_1 + 2 (second word for Offset_Ending_Data_Address). A device driver that allocates multiple character device headers can fail initialization of a subset of its header chain. MS OS/2 retains the last nonzero code and data segment offsets returned for a device by a device driver that completes initialization successfully. The system initialization process uses these values to resize the device driver's code and data segments after Init request packets have been sent for each device in the device driver's header chain. When the driver cannot initialize a device in the header chain, it sets the code and data segment offsets in the Pointer_1 field to zero to indicate initialization failure for that device (as shown in the preceding list of fail values). If every device in the device driver's header chain fails initialization, the driver will not remain loaded. The MS OS/2 initialization process maintains the pass/fail return status for each device header in a device driver's header chain. Thus, the device driver should not manipulate the linkages in a chain of device driver headers. See Also Command codes 02 (BuildBPB) and 10H (GenericIOCtl) █ MediaCheck ──────────────────────────────────────────────────────────────────────────── +------------------------------+ | Request Header | 13 BYTEs +------------------------------+ | Media_Descriptor | BYTE PTR ReqPak+0DH +------------------------------+ | Return_Code | BYTE PTR ReqPak+0EH +------------------------------+ | Ret_Ptr_Prev_Vol_ID | DWORD PTR ReqPak+0FH | (if supported) | +------------------------------+ The MediaCheck request tells a block driver to determine the state of the media. The Command_Code value in the Request Header is 01. Comments On entry, the Media_Descriptor field of the request packet contains a code as input to the device driver. The following lists some examples of Media_Descriptor codes: Value Disk type ──────────────────────────────────────────────────────────────────────────── F0H 3.5-inch with 2 sides and 18 sectors per track. F8H Fixed. F9H 3.5-inch with 2 sides and 9 sectors per track. 5.25-inch with 2 sides and 15 sectors per track. FCH 5.25-inch with 1 side and 9 sectors per track. FDH 5.25-inch with 2 sides and 9 sectors per track 8-inch with 2 sides and 26 sectors per track. FEH 5.25-inch with 1 side and 8 sectors per track. 8-inch with 1 side and 26 sectors per track. 8-inch with 2 sides and 8 sectors per track. FFH 5.25-inch with 2 sides and 8 sectors per track. If your driver supports removable media, it must set the Ret_Ptr_Prev_Vol_ID field to the previous volume ID. The device driver must set the Return_Code field to one of the following values: Value Meaning ──────────────────────────────────────────────────────────────────────────── -1 Media has been changed. 0 Unsure whether media has been changed. 1 Media is unchanged. In addition, the driver must do the following: ■ Set the error bit (15) and error code (bits 0 to 7) in the Status field of the Request Header if there is an error. ■ Set the done bit (8) in the Status field. The characteristics of 8-inch diskettes are as follows: ■ Media_Descriptor FDH is a double-sided, single-density diskette that is soft-sectored with 128 bytes per sector, 4 sectors per allocation unit, 4 reserved sectors, 2 FATs (file allocation tables), 68 directory entries and 77*26*2 sectors. ■ Media_Descriptor FEH can be a single-sided, single-density diskette that is soft-sectored with 128 bytes per sector, 4 sectors per allocation unit, 1 reserved sector, 2 FATs, 68 directory entries, and 77*26 sectors. ■ Media_Descriptor FEH can be a double-sided, double-density diskette that is soft-sectored with 1024 bytes per sector, 1 sector per allocation unit, 1 reserved sector, 2 FATs, 192 directory entries, and 77*8*2 sectors. The device driver can support the IOCtl function DSK_GETDEVICEPARAMS (category 8, function 63) if application programmers are expected to determine the type of media by calling this IOCtl function and referencing the BPB (BIOS parameter block). See Also Command codes 02 (BuildBPB) and 10H (GenericIOCtl) █ BuildBPB ──────────────────────────────────────────────────────────────────────────── +-----------------------------+ | Request Header | 13 BYTEs +-----------------------------+ | Media_Descriptor | BYTE PTR ReqPak+0DH +-----------------------------+ | Transfer_Address | DWORD PTR ReqPak+0EH +-----------------------------+ | Ptr_To_BPB_Table | DWORD PTR ReqPak+12H +-----------------------------+ MS OS/2 issues the BuildBPB request in order to build the BPB (BIOS parameter block) when the media has changed or when the state of the media is uncertain. The Command_Code value in the Request Header is 02. Comments On entry, the Command-specific_Data area of the request packet contains the following fields as input to the device driver: ■ Media_Descriptor is set for the drive identified in the Request Header. ■ Transfer_Address is a virtual pointer to a buffer containing the data in sector 0. For DevLev_1 block drivers, this is the boot sector information for removable media or for the logical partition types 1, 4, and 6. For DevLev_2 block drivers, this can be the boot sector information for removable media or for the logical partition types 1, 4, and 6. However, DevLev_2 block drivers also support the logical partition type 7 of HPFS (High Performance File System), and the boot sector for this partition type need not be in sector 0. The device driver must do the following: ■ Determine the media type in the drive in order to set the Ptr_To_BPB_Table field. ■ Update the Media_Descriptor field. ■ Set the error bit (15) and error code (bits 0 to 7) in the Status field of the Request Header if there is an error. ■ Set the done bit (8) in the Status field. The driver determines the return value for Ptr_To_BPB_Table after reading the buffer to be sure that all BPB fields have values that are compatible with MS OS/2 versions 1.0 and 1.1. Otherwise, the driver should return an error. The driver should return error code 07H (Unknown media) if it cannot build the BPB because the buffer does not contain a boot sector with valid BPB field values. The BPB information for removable media and for logical partition types 1, 4, and 6 is kept in the boot sector. The BPB information for logical partition type 7 is not necessarily in sector 0. The MS OS/2 version 1.2 BPB has the following layout: Length Field description ──────────────────────────────────────────────────────────────────────────── word Number of bytes per sector─This field is at offset 0BH of the boot sector for removable media and for logical partition types 1, 4, and 6. byte Sectors per allocation unit─This field is always zero for partition-type 7 media, and it must be a power of 2 for the other media. word Number of reserved sectors (starting at logical sector 0)─This field is always zero for partition-type 7 media and a nonnegative value for the other media. byte Number of FATs (file allocation tables)─This field is always zero for partition-type 7 media and a nonnegative value for other media. word Maximum number of root directory entries allowed─This field is always zero for partition-type 7 media and a nonnegative value for other media. word Total sectors in logical image (all media sectors, including boot sector, directories, etc.)─This field is always zero for partition-type 7 media and a nonnegative value for other media. When this field is zero, the last BPB field contains the total sector value for the logical drive. byte Media descriptor─This field is always zero for partition-type 7 media and a value in the range F0H to FFH for other media. word Number of sectors per FAT─This field is always zero for partition-type 7 media and a nonnegative value for other media. word Sectors per track. word Number of heads. dword Number of hidden sectors. dword Big total sectors─This field is a nonnegative value for partition-type 7 media and zero for other media. 6 bytes Reserved. Drivers that support volume identification and disk change should read a new volume identification off the disk in response to the BuildBPB request. See Also Command codes 01 (MediaCheck), 04 (Read), 08 (Write), 09 (WriteVerify) █ Read ──────────────────────────────────────────────────────────────────────────── +------------------------+ | Request Header | 13 BYTEs +------------------------+ | Media_Descriptor | BYTE PTR ReqPak+0DH +------------------------+ | Transfer_Address | DWORD PTR ReqPak+0EH +------------------------+ | Byte_Or_Sector_Count | WORD PTR ReqPak+12H +------------------------+ | Start_Sector_Num | DWORD PTR ReqPak+14H | (block device) | +------------------------+ | Sys_File_Num | WORD PTR ReqPak+18H +------------------------+ -| Advice_Code | WORD PTR ReqPak+20H | DevLev_2 block +------------------------+ -- drivers only The Read request tells a driver to read from a device. The Command_Code value in the Request Header is 04. Comments On entry, the Command-specific_Data area of the request packet contains the following fields as input to the device driver: ■ Media_Descriptor is set for the drive identified in the Request Header, or it has zero for a character device. ■ Transfer_Address has the 32-bit physical address of the data buffer. ■ Byte_Or_Sector_Count has the number of bytes to transfer for character device drivers or the number of sectors to transfer for block device drivers. ■ Start_Sector_Num is set for where to begin the transfer on the block device. Character device drivers can ignore this field. ■ Sys_File_Num is set to a unique number associated with an OpenDevice request. ■ Advice_Code is set for DevLev_2 block drivers, but drivers that do not cache data can ignore this field. A DevLev_2 block driver that caches data can use the Advice_Code value to improve both its own I/O performance and the throughput of the whole system. Block drivers that cache data may ignore the least significant bit (bit 0) of the Advice_Code. Bit 1 of the Advice_Code is advisory, not mandatory. Bit 1 advises the driver whether to read data into its cache. If bit 1 is set, this data is unlikely to be accessed again by the requesting process, so the driver need not cache this data. Advice_Code may be one of following values: Value Meaning ──────────────────────────────────────────────────────────────────────────── 0000 The driver should read the data into its cache, if possible, because the requesting process might want access to this data again. 0001 The driver should read the data into its cache, if possible, because the requesting process might want access to this data again. 0002 The driver need not read the data into its cache, because the requesting process is unlikely to want access to this data again. 0003 The driver need not read the data into its cache, because the requesting process is unlikely to want access to this data again. Block drivers that support the partition-type 7 media of HPFS (High Performance File System) can improve their own and the system's I/O performance by not caching data. HPFS already caches the data read in by such a DevLev_2 driver if the requesting process is likely to access this data again. The device driver must do the following: ■ Perform the requested function. ■ Set the actual number of bytes (character drivers) or sectors (block drivers) transferred in the Byte_Or_Sector_Count field. ■ Set the error bit (15) and error code (bits 0 to 7) in the Status field of the Request Header if there is an error. ■ Set the done bit (8) in the Status field. Note that the Transfer_Address field on entry contains a locked 32-bit physical address. The device driver can call the PhysToVirt routine to convert this physical address into a selector:offset or segment:offset virtual address, according to the current operating mode. The driver need not unlock the address when it has completed the Read request. For more information about PhysToVirt, see Chapter 3, "Device Helper Services." See Also Command codes 05 (NondestructiveReadNoWait), 08 (Write), 09 (WriteVerify), 0DH (OpenDevice), 18H (NonCachingRead) █ NondestructiveReadNoWait ──────────────────────────────────────────────────────────────────────────── +-----------------------------+ | Request Header | 13 BYTEs +-----------------------------+ | Data_Returned | BYTE PTR ReqPak+0DH +-----------------------------+ The NondestructiveReadNoWait request tells the driver to copy a character from the buffer. If no character is in the buffer, the driver returns the packet without waiting for an input character. The Command_Code value in the Request Header is 05. Comments If one or more characters are in the device driver's input buffer, the driver must do the following: ■ Copy the first character in the buffer and move the copy into the Data_Returned field of the request packet. ■ Clear the busy bit (9) in the Status field of the Request Header. ■ Set the done bit (8) in the Status field. This function allows MS OS/2 to look ahead one input character without blocking in the device driver. If no characters are in the buffer, the driver must do the following: ■ Set the busy bit (9) in the Status field of the Request Header. ■ Set the done bit (8) in the Status field. If the character driver finds an error, it must do the following: ■ Set the error bit (15) and error code (bits 0 to 7) in the Status field. ■ Set the done bit (8) in the Status field. See Also Command code 04 (Read) █ InputStatus ──────────────────────────────────────────────────────────────────────────── +-----------------------------+ | Request Header | 13 BYTEs +-----------------------------+ The InputStatus request tells a character driver to determine the input status on its device. The Command_Code value in the Request Header is 06. Comments The device driver must do the following: ■ Perform the requested function. ■ Set the busy bit (9) in the Status field of the Request Header if there are no characters currently in the driver's input buffer. ■ Clear the busy bit if there is at least one character currently in the driver's input buffer. ■ Set the done bit (8) in the Status field of the Request Header. If the driver returns the busy bit clear, indicating that it has one or more characters in the buffer, a read of one character should not need to block. A character driver that does not have an input buffer must do the following: ■ Clear the busy bit (9) in the Status field of the Request Header. ■ Set the done bit (8) in the Status field. See Also Command codes 05 (NondestructiveReadNoWait), 0AH (OutputStatus) █ InputFlush ──────────────────────────────────────────────────────────────────────────── +-----------------------------+ | Request Header | 13 BYTEs +-----------------------------+ The InputFlush request tells a character driver to terminate all pending input requests. The Command_Code value in the Request Header is 07. Comments The device driver must do the following: ■ Perform the requested function. ■ Set the error bit (15) and error code (bits 0 to 7) in the Status field of the Request Header if there is an error. ■ Set the done bit (8) in the Status field. InputFlush tells the device driver to terminate all known pending requests. Its primary use is to flush the input queue on character devices. See Also Command code 0BH (OutputFlush) █ Write ──────────────────────────────────────────────────────────────────────────── +------------------------+ | Request Header | 13 BYTEs +------------------------+ | Media_Descriptor | BYTE PTR ReqPak+0DH +------------------------+ | Transfer_Address | DWORD PTR ReqPak+0EH +------------------------+ | Byte_Or_Sector_Count | WORD PTR ReqPak+12H +------------------------+ | Start_Sector_Num | DWORD PTR ReqPak+14H | (block device) | +------------------------+ | Sys_File_Num | WORD PTR ReqPak+18H +------------------------+ -| Advice_Code | WORD PTR ReqPak+20H | DevLev_2 block +------------------------+ -- drivers only The Write request tells the driver to write to the device. The Command_Code value in the Request Header is 08. Comments On entry, the Command-specific_Data area of the request packet contains the following fields as input to the device driver: ■ Media_Descriptor is set for the drive identified in the Request Header, or it has zero for a character device. ■ Transfer_Address has the 32-bit physical address of the buffer for the data. ■ Byte_Or_Sector_Count has the number of bytes to transfer for character device drivers or the number of sectors to transfer for block device drivers. ■ Start_Sector_Num is set for where to begin the transfer on the block device. Character device drivers can ignore this field. ■ Sys_File_Num is set to a unique number associated with an OpenDevice request. ■ Advice_Code is set for DevLev_2 block drivers, but drivers that do not cache data can ignore this field. Drivers that do not cache data must write all data to the device before returning the request packet (marked done) to the system. A DevLev_2 block driver that caches data can use the Advice_Code value to improve its own and the system's I/O performance, while maintaining the integrity of files on the device. DevLev_2 block drivers that cache data must obey the least significant bit (bit 0) of the Advice_Code. Bit 0 tells the driver whether to write all data out to the device before returning the request packet to the system. If bit 0 is set, the device driver may not cache data to be written out later. Bit 1 advises the driver whether to cache the data, if possible. Unlike bit 0, bit 1 is not mandatory. If bit 1 is set but bit 0 is clear, the driver may cache data to be written out to the device later. Advice_Code may be one of following values: Value Meaning ──────────────────────────────────────────────────────────────────────────── 0000 The driver should copy the data into its cache, if possible, and write the data from the cache out to its device later. 0001 The driver must write all data to its device before returning the request packet (marked done) to the system, in order to maintain file integrity on the device. The driver should also copy the data into its cache, if possible. 0002 The driver need not copy the data into its cache, but it may do so and write the data from the cache out to its device later. 0003 The driver must write all data out to its device before returning the request packet (marked done) to the system, in order to maintain file integrity on the device. The driver need not copy the data into its cache, but it may do so. Block drivers that support the partition-type 7 media of HPFS (High Performance File System) can improve their own and the system's I/O performance by not caching data. HPFS already caches the data to be written out by such a DevLev_2 driver, so the driver can assume that every Write request has bit 0 of the Advice_Code set. The device driver must do the following: ■ Perform the requested function. ■ Set the actual number of bytes (character drivers) or sectors (block drivers) transferred in the Byte_Or_Sector_Count field. ■ Set the error bit (15) and error code (bits 0 to 7) in the Status field of the Request Header if there is an error. ■ Set the done bit (8) in the Status field. Note that the Transfer_Address field on entry contains a locked 32-bit physical address. The device driver can call the PhysToVirt routine to convert this physical address into a selector:offset or segment:offset virtual address, according to the current operating mode. The driver need not unlock the address when it has completed the Write request. For more information about PhysToVirt, see Chapter 3, "Device Helper Services." See Also Command codes 04 (Read), 09 (WriteVerify), 0DH (OpenDevice), 19H (NonCachingWrite) █ WriteVerify ──────────────────────────────────────────────────────────────────────────── +------------------------+ | Request Header | 13 BYTEs +------------------------+ | Media_Descriptor | BYTE PTR ReqPak+0DH +------------------------+ | Transfer_Address | DWORD PTR ReqPak+0EH +------------------------+ | Byte_Or_Sector_Count | WORD PTR ReqPak+12H +------------------------+ | Start_Sector_Num | DWORD PTR ReqPak+14H | (block device) | +------------------------+ | Sys_File_Num | WORD PTR ReqPak+24H +------------------------+ -| Advice_Code | WORD PTR ReqPak+20H | DevLev_2 block +------------------------+ -- drivers only The WriteVerify request tells the driver to write to the device and to verify the write. The Command_Code value in the Request Header is 09. Comments On entry, the Command-specific_Data area of the request packet contains the following fields as input to the device driver: ■ Media_Descriptor is set for the drive identified in the Request Header, or it has zero for a character device. ■ Transfer_Address has the 32-bit physical address of the data buffer. ■ Byte_Or_Sector_Count has the number of bytes to transfer for character device drivers or the number of sectors to transfer for block device drivers. ■ Start_Sector_Num is set for where to begin the transfer on the block device. Character device drivers can ignore this field. ■ Sys_File_Num is set to a unique number associated with an OpenDevice request. ■ Advice_Code is set for DevLev_2 block drivers, but drivers that do not cache data can ignore this field. Drivers that do not cache data must write all data to the device before returning the request packet (marked done) to the system. A DevLev_2 block driver that caches data can use the Advice_Code value to improve its own and the system's I/O performance, while maintaining the integrity of files on the device. DevLev_2 block drivers that cache data must obey the least significant bit (bit 0) of the Advice_Code. Bit 0 tells the driver whether to write all data out to the device before returning the request packet to the system. If bit 0 is set, the device driver may not cache data to be written out later. Bit 1 advises the driver whether to cache the data, if possible. Unlike bit 0, bit 1 is not mandatory. If bit 1 is set but bit 0 is clear, the driver may cache data to be written out to the device later. Advice_Code may be one of following values: Value Meaning ──────────────────────────────────────────────────────────────────────────── 0000 The driver should copy the data into its cache, if possible, and write the data from the cache out to its device later. 0001 The driver must write all data to its device before returning the request packet (marked done) to the system, in order to maintain file integrity on the device. The driver should also copy the data into its cache, if possible. 0002 The driver need not copy the data into its cache, but it may do so and write the data from the cache out to its device later. 0003 The driver must write all data out to its device before returning the request packet (marked done) to the system, in order to maintain file integrity on the device. The driver need not copy the data into its cache, but it may do so. Block drivers that support the partition-type 7 media of HPFS can improve their own and the system's I/O performance by not caching data. HPFS already caches the data to be written out by such a DevLev_2 driver, so the driver can assume that every Write request has bit 0 of the Advice_Code set. The device driver must do the following: ■ Perform the requested function. ■ Set the actual number of bytes (character drivers) or sectors (block drivers) transferred in the Byte_Or_Sector_Count field. ■ Set the error bit (15) and error code (bits 0 to 7) in the Status field of the Request Header if there is an error. ■ Set the done bit (8) in the Status field. Note that the Transfer_Address field on entry contains a locked 32-bit physical address. The device driver can call the PhysToVirt routine to convert this physical address into a selector:offset or segment:offset virtual address, according to the current operating mode. The driver need not unlock the address when it has completed the WriteVerify request. For more information about PhysToVirt, see Chapter 3, Device Helper Services. See Also Command codes 04 (Read), 08 (Write), 0DH (OpenDevice), 1AH (NonCachingWriteVerify) █ OutputStatus ──────────────────────────────────────────────────────────────────────────── +-----------------------------+ | Request Header | 13 BYTEs +-----------------------------+ The OutputStatus request tells a character driver to determine the output status on its device. The Command_Code value in the Request Header is 0AH. Comments The device driver must do the following: ■ Perform the requested function. ■ Set the busy bit (9) in the Status field of the Request Header if an output request is currently active. ■ Clear the busy bit if no output request is currently active. ■ Set the done bit (8) in the Status field. If the driver returns the busy bit set, a subsequent write request to the device driver must wait for completion of a currently active request. If the driver returns the busy bit clear, a subsequent write request starts immediately. See Also Command code 06 (InputStatus) █ OutputFlush ──────────────────────────────────────────────────────────────────────────── +----------------------------+ | Request Header | 13 BYTEs +----------------------------+ The OutputFlush request tells a character driver to terminate pending output requests. The Command_Code value in the Request Header is 0BH. Comments The device driver must do the following: ■ Perform the requested function. ■ Set the error bit (15) and error code (bits 0 to 7) in the Status field of the Request Header if there is an error. ■ Set the done bit (8) in the Status field. OutputFlush tells the device driver to terminate all known pending requests. Its primary use is to flush the output queue on character devices. See Also Command code 07 (InputFlush) █ OpenDevice ──────────────────────────────────────────────────────────────────────────── +-----------------------------+ | Request Header | 13 BYTEs +-----------------------------+ | Sys_File_Num | WORD PTR ReqPak+0DH +-----------------------------+ The OpenDevice request tells a driver to open its device. The Command_Code value in the Request Header is 0DH. Comments The Sys_File_Num field contains a unique number assigned with this request. The device driver must do the following: ■ Perform the requested function. ■ Set the error bit (15) and error code (bits 0 to 7) in the Status field of the Request Header if there is an error. ■ Set the done bit (8) in the Status field. Character device drivers can use incoming OpenDevice and CloseDevice requests to coordinate use of their device with application I/O activity. For example, a character driver that increments a count at each OpenDevice request and decrements the count at each CloseDevice request might flush its input and output buffers whenever the count is zero. An OpenDevice request when the count is zero tells the driver to send an initialization string to the device; a CloseDevice request when the count is one tells the driver to decrement the count and flush its buffers. A printer driver could reset the font and page size on its device whenever it receives an OpenDevice request and send a form feed on receipt of the corresponding CloseDevice request. It can use the Sys_File_Num value to keep track of files. When an application calls the DosOpen or DosOpen2 function with a character driver's name, the driver gets a GenericIOCtl request packet for the IOCtl function PRT_ACTIVATEFONT (category 05, function 48H) before the driver gets the OpenDevice request packet. A printer driver should process the PRT_ACTIVATEFONT request, but drivers for other devices should dismiss the GenericIOCtl request, as follows: ■ Set the error bit (15) and set the error code to 03 (Unknown command) in the Status field of the Request Header. ■ Set the done bit (8) in the Status field. See Also Command codes 07 (InputFlush), 0BH (OutputFlush), 0EH (CloseDevice), 10H (GenericIOCtl) █ CloseDevice ──────────────────────────────────────────────────────────────────────────── +-----------------------------+ | Request Header | 13 BYTEs +-----------------------------+ | Sys_File_Num | WORD PTR ReqPak+0DH +-----------------------------+ The CloseDevice request tells a driver close its device. The Command_Code value in the Request Header is 0EH. Comments The Sys_File_Num field contains a unique number associated with the corresponding OpenDevice request. The device driver must do the following: ■ Perform the requested function. ■ Set the error bit (15) and error code (bits 0 to 7) in the Status field of the Request Header if there is an error. ■ Set the done bit (8) in the Status field. Note that a printer driver can use the Sys_File_Num value to keep track of corresponding OpenDevice and CloseDevice requests when it has more than one pending OpenDevice request. See Also Command code 0DH (OpenDevice) █ RemovableMedia ──────────────────────────────────────────────────────────────────────────── +-----------------------------+ | Request Header | 13 BYTEs +-----------------------------+ The RemovableMedia tells a block driver to check for removable media. The Command_Code value in the Request Header is 0FH. Comments The device driver must do the following: ■ Set the busy bit (9) in the Status field of the Request Header if the media is nonremovable, or clear the busy bit if the media is removable. ■ Set the error bit (15) and error code (bits 0 to 7) in the Status field if there is an error. ■ Set the done bit (8) in the Status field. Note that the device driver receives this request packet when an application calls the IOCtl function DSK_BLOCKREMOVABLE (category 08, function 20H), rather than receiving a GenericIOCtl request packet (command code 10H). Nonremovable and removable drives may print different versions of certain prompts, so the application might need to know what kind of drive it is dealing with. See Also Command code 10H (GenericIOCtl) █ GenericIOCtl ──────────────────────────────────────────────────────────────────────────── +----------------------------+ | Request Header | 13 BYTEs +----------------------------+ | IOCtl_Category | BYTE PTR ReqPak+0DH +----------------------------+ | IOCtl_Function_Code | BYTE PTR ReqPak+0EH +----------------------------+ | Ptr_To_Param_Buff | DWORD PTR ReqPak+0FH +----------------------------+ | Ptr_To_Data_Buff | DWORD PTR ReqPak+13H +----------------------------+ | Sys_File_Num | WORD PTR ReqPak+17H +----------------------------+ -| Param_Buff_Len | WORD PTR ReqPak+19h | DevLev_2 +----------------------------+ | drivers | Data_Buff_Len | WORD PTR ReqPak+1BH | only +----------------------------+ - The GenericIOCtl request tells the device driver to respond to an IOCtl function call. The Command_Code value in the Request Header is 10H. Comments On entry, the Command-specific_Data area of the request packet contains the following fields as input to the device driver: ■ IOCtl_Category has the category code. ■ IOCtl_Function_Code has the function code. ■ Ptr_To_Param_Buff is set as a protected-mode selector:offset or real-mode segment:offset pointer to the parameter buffer, if any. The virtual address is zero if the IOCtl function does not pass parameters. ■ Ptr_To_Data_Buff is set as a protected-mode selector:offset or real-mode segment:offset pointer to the data buffer, if any. The virtual address is zero if the IOCtl function does not pass access to data. ■ Sys_File_Num is set to a unique number associated with an OpenDevice request. ■ Param_Buff_Len is set to the number of bytes in the parameter buffer, if any. DevLev_2 drivers can use this value to be sure that the buffer contains all necessary parameters. Such a driver should stay within the bounds of the parameter buffer. ■ Data_Buff_Len is set to the number of bytes in the data buffer, if any. DevLev_2 drivers can use this value to be sure that no data was lost from the buffer. Such a driver should stay within the bounds of the data buffer. The device driver must do the following: ■ Check the validity of the Ptr_To_Param_Buff and Ptr_To_Data_Buff addresses, if the request packet contains application-supplied addresses. The system cannot verify the validity of user addresses passed in an IOCtl call, but the device driver can use the VerifyAccess routine to be sure that the application has proper access rights for these addresses. ■ Perform the requested IOCtl function. ■ Set the error bit (15) and error code (bits 0 to 7) in the Status field of the Request Header if there is an error. ■ Set the done bit (8) in the Status field. If the driver cannot perform the requested function immediately, it must do the following: ■ Call the Lock routine for the parameter and/or data pointer segment(s), then VerifyAccess to check the validity of these address(es). ■ Call the VirtToPhys routine with the parameter and/or data pointers to convert each virtual address into a 32-bit physical address if the driver requested a fixed-type lock. ■ Store any converted addresses in the driver's low-memory data segment. ■ Call the PhysToVirt routine to reconvert each stored address that the driver needs to use if the driver requested a fixed-type lock. This reconversion ensures that the correct virtual address is used for the current operating mode. ■ Call the UnLock routine for the parameter and/or data pointer segment(s) when the driver completes the IOCtl function. ■ Set the error bit (15) and error code (bits 0 to 7) in the Status field of the Request Header if there is an error. ■ Set the done bit (8) in the Status field of the Request Header. The driver must call Lock for a fixed-type lock on the parameter and data buffer segment(s) if it is necessary to call VirtToPhys to convert the pointers to physical addresses. Otherwise, it may call Lock for a short-term, verify-type lock on the segment(s). For more information about the Lock, PhysToVirt, Unlock, VerifyAccess, and VirtToPhys routines, see Chapter 3, "Device Helper Services." Note that a device driver may support some IOCtl functions that do not require MS OS/2 to pass parameters, data, or both. For these IOCtls, the incoming request packet will have zeros in the Ptr_To_Param_Buff field and/or the Ptr_To_Data_Buff field. If the driver determines that IOCtl_Function_Code indicates such an IOCtl, it can ignore the pointer fields of the incoming packet. See Also Command codes 0DH (OpenDevice) and 0FH (RemovableMedia) █ ResetMedia ──────────────────────────────────────────────────────────────────────────── +-----------------------------+ | Request Header | 13 BYTEs +-----------------------------+ The ResetMedia request tells a block driver to reset the Uncertain media error condition and allow MS OS/2 to identify the media. The Command_Code value in the Request Header is 11H. Comments On entry, the Block_Device_Unit_Code field in the Request Header identifies the unit number to be reset. This request occurs after the device driver returns an Uncertain media error code (10H) for a MediaCheck request or for some other request. An incoming ResetMedia informs the device driver that it need not return this error any longer. The device driver must do the following: ■ Reset the error condition for the drive. ■ Set the done bit (8) in the Status field of the Request Header. Note that a device driver for a fixed disk must begin in an uncertain-media state to have the media correctly labeled. See Also Command codes 00 (Init), 01 (MediaCheck) █ GetLogicalDriveMapping ──────────────────────────────────────────────────────────────────────────── +-----------------------------+ | Request Header | 13 BYTEs +-----------------------------+ MS OS/2 issues the GetLogicalDriveMapping request to determine which logical drive is currently mapped to a particular physical unit. The Command_Code value in the Request Header is 12H. Comments On entry, the Request Header contains the following field as input to the device driver: ■ Block_Device_Unit_Code identifies the physical drive. The device driver must do the following: ■ Set the Block_Device_Unit_Code field to the logical drive that is mapped onto the physical drive if the driver has more than one logical drive mapped onto the given physical drive. ■ Clear the Block_Device_Unit_Code field if the driver has only one logical drive mapped onto the given physical drive. ■ Set the error bit (15) and error code (bits 0 to 7) in the Status field of the Request Header if there is an error. ■ Set the done bit (8) in the Status field. See Also Command code 13H (SetLogicalDriveMapping) █ SetLogicalDriveMapping ──────────────────────────────────────────────────────────────────────────── +-----------------------------+ | Request Header | 13 BYTEs +-----------------------------+ MS OS/2 issues the SetLogicalDriveMapping request to determine which physical unit is currently mapped to a particular logical drive. The Command_Code value in the Request Header is 13H. Comments On entry, the Request Header contains the following field as input to the device driver: ■ Block_Device_Unit_Code identifies the logical drive. The device driver must do the following: ■ Set the Block_Device_Unit_Code field to the physical drive that has the mapping for the logical drive. ■ Clear the Block_Device_Unit_Code field if there is only one logical drive mapped onto the physical drive. ■ Set the error bit (15) and error code (bits 0 to 7) in the Status field of the Request Header if there is an error. ■ Set the done bit (8) in the Status field. See Also Command code 12H (GetLogicalDriveMapping) █ Deinstall ──────────────────────────────────────────────────────────────────────────── +-----------------------------+ | Request Header | 13 BYTEs +-----------------------------+ The Deinstall request asks a character device driver to deinstall itself. The Command_Code value in the Request Header is 14H. Comments MS OS/2 uses the Device_Attribute and Name fields of the device driver header to determine if a newly loaded device driver is attempting to replace an already installed driver. If it is making such an attempt, the system sends a Deinstall request to the installed driver. The already installed device driver can refuse the request and prevent initialization of the new driver. If the driver will deinstall itself, it must do the following: ■ Release any physical memory that it has allocated. ■ Release any hardware interrupt level that it has claimed by calling the UnSetIRQ routine. ■ Make a jump to the previous ROM BIOS interrupt handler if the driver has a ROM BIOS software-interrupt handler. The driver cannot reset the vector. ■ Release any logical ID (LID) that it has claimed by calling the FreeLIDEntry routine if it is an ABIOS device driver. The driver must discontinue support of all units under the LID. ■ Perform any other cleanup that is necessary. ■ Clear the error bit (15) in the Status field of the Request Header to indicate a successful deinstallation. ■ Set the done bit (8) in the Status field. For more information about the FreeLIDEntry and UnSetIRQ routines, see Chapter 3, "Device Helper Services." If the already installed driver determines that it cannot or will not deinstall itself, it must do the following: ■ Set the error bit (15) and set the error code (bits 0 to 7) to 03 (Unknown command) in the Status field. ■ Set the done bit (8) in the Status field. A driver that is already installed must refuse the Deinstall request if its device cannot be told to stop (or will not stop) generating interrupts. Such a driver must not remove its interrupt handler. See Also Command code 00 (Init) █ PartitionableFixedDisks ──────────────────────────────────────────────────────────────────────────── +-----------------------------+ | Request Header | 13 BYTEs +-----------------------------+ | Count | BYTE PTR ReqPak+0DH +-----------------------------+ | Reserved | DWORD PTR ReqPak+0EH +-----------------------------+ MS OS/2 issues the PartitionableFixedDisks request to get a count of how many partitionable fixed disks the device driver supports. The Command_Code value in the Request Header is 16H. Comments The disk driver must do the following: ■ Set the number of physical partitionable disks it supports in the Count field; the value must be one-based. ■ Set the error bit (15) and error code (bits 0 to 7) in the Status field of the Request Header if there is an error. ■ Set the done bit (8) in the Status field. The reserved dword in the request packet is zero. This value should be preserved. Note that MS OS/2 initiates a PartitionableFixedDisks request as a general query of the driver's device support. The driver returns only a count that is not tied to any particular unit it supports. This allows MS OS/2 to route applications' category 09 IOCtl requests to the correct device driver. See Also Command codes 10H (GenericIOCtl), 17H (GetFixedDisk/LogicalUnitMap) █ GetFixedDisk/LogicalUnitMap ──────────────────────────────────────────────────────────────────────────── +-----------------------------------+ | Request Header | 13 BYTEs +-----------------------------------+ | Units-supported_Bit_Mask | DWORD PTR ReqPak+0DH +-----------------------------------+ | Reserved | DWORD PTR ReqPak+0EH +-----------------------------------+ MS OS/2 issues the GetFixedDisk/LogicalUnitMap request to determine which logical units on a given physical partitionable fixed disk are supported by the device driver. The Command_Code value in the Request Header is 17H. Comments On entry, the Request Header contains the following field as input to the device driver: ■ Block_Device_Unit_Code identifies a physical-disk number, not a logical-unit number. This value is zero-based and relative to the number of physical, partitionable fixed disks returned for a preceding PartitionableFixedDisks request. The reserved dword in the request packet is zero. This value should be preserved. The device driver must do the following: ■ Supply a mask in the Units-supported_Bit_Mask field to indicate which of its logical units (if any) exist on the given physical disk. ■ Set the error bit (15) and error code (bits 0 to 7) in the Status field of the Request Header if there is an error. ■ Set the done bit (8) in the Status field. The 4-byte bit mask has the following layout: ■ The least significant bit (bit 0 of the low-address byte) represents the first logical unit that the device driver supports. Bit 1 of the low-address byte represents the second logical unit that the driver supports, and so forth. ■ A cleared bit means that the logical unit does not exist on the given physical disk; a set bit means that it does. For example, suppose a driver supports five logical units spread over two diskette drives and one partitionable fixed disk. Its unit 0 and unit 1 map to the diskette drives while units 2, 3, and 4 map to the fixed disk. In response to a GetFixedDisk/LogicalUnitMap request, this device driver would set the bit mask to one of the following values: 0000 0000 0000 0000 0000 0000 0001 1100B 00 00 00 1CH All bits in the Units-supported_Bit_Mask field could be zero if the driver has no logical units on a given physical disk because it is not yet initialized. See Also Command code 16H (PartitionableFixedDisks) █ NonCachingRead ──────────────────────────────────────────────────────────────────────────── +------------------------+ | Request Header | 13 BYTEs +------------------------+ | Media_Descriptor | BYTE PTR ReqPak+0DH +------------------------+ | Transfer_Address | DWORD PTR ReqPak+0EH +------------------------+ | Sector_Count | WORD PTR ReqPak+12H +------------------------+ | Start_Sector_Num | DWORD PTR ReqPak+14H +------------------------+ | Sys_File_Num | WORD PTR ReqPak+18H +------------------------+ The NonCachingRead request tells a block driver to read data directly from the device and to bypass the disk cache. The Command_Code value in the Request Header is 18H. Comments On entry, the Command-specific_Data area of the request packet contains the following fields as input to the device driver: ■ Media_Descriptor is set for the drive identified in the Request Header. ■ Transfer_Address has the 32-bit physical address of the data buffer. ■ Sector_Count has the number of sectors to transfer. ■ Start_Sector_Num is set for where to begin the transfer on the device. ■ Sys_File_Num is set to a unique number associated with an OpenDevice request. The device driver must do the following: ■ Perform the requested function. ■ Set the actual number of sectors transferred in the Sector_Count field. ■ Set the error bit (15) and error code (bits 0 to 7) in the Status field of the Request Header if there is an error. ■ Set the done bit (8) in the Status field. Note that the Transfer_Address field on entry contains a locked 32-bit physical address. The device driver can call the PhysToVirt routine to convert this physical address into a selector:offset or segment:offset virtual address, according to the current operating mode. The driver need not unlock the address when it has completed the NonCachingRead request. For more information about PhysToVirt, see Chapter 3, "Device Helper Services." See Also Command codes 04 (Read), 19H (NonCachingWrite), 1AH (NonCachingWriteVerify), 0DH (OpenDevice) █ NonCachingWrite ──────────────────────────────────────────────────────────────────────────── +------------------------+ | Request Header | 13 BYTEs +------------------------+ | Media_Descriptor | BYTE PTR ReqPak+0DH +------------------------+ | Transfer_Address | DWORD PTR ReqPak+0EH +------------------------+ | Sector_Count | WORD PTR ReqPak+12H +------------------------+ | Start_Sector_Num | DWORD PTR ReqPak+14H +------------------------+ | Sys_File_Num | WORD PTR ReqPak+18H +------------------------+ The NonCachingWrite request tells a block driver to to write data directly to the device and to bypass the disk cache. The Command_Code value in the Request Header is 19H. Comments On entry, the Command-specific_Data area of the request packet contains the following fields as input to the device driver: ■ Media_Descriptor is set for the drive identified in the Request Header. ■ Transfer_Address has the 32-bit physical address of the data buffer. ■ Sector_Count has the number of sectors to transfer. ■ Start_Sector_Num is set for where to begin the transfer on the device. ■ Sys_File_Num is set to a unique number associated with an OpenDevice request. The device driver must do the following: ■ Perform the requested function. ■ Set the actual number of sectors transferred in the Sector_Count field. ■ Set the error bit (15) and error code (bits 0 to 7) in the Status field of the Request Header if there is an error. ■ Set the done bit (8) in the Status field. Note that the Transfer_Address field on entry contains a locked 32-bit physical address. The device driver can call the PhysToVirt routine to convert this physical address into a selector:offset or segment:offset virtual address, according to the current operating mode. The driver need not unlock the address when it has completed the NonCachingWrite request. For more information about PhysToVirt, see Chapter 3, "Device Helper Services." See Also Command codes 08 (Write), 18H (NonCachingRead), 1AH (NonCachingWriteVerify), 0DH (OpenDevice) █ NonCachingWriteVerify ──────────────────────────────────────────────────────────────────────────── +------------------------+ | Request Header | 13 BYTEs +------------------------+ | Media_Descriptor | BYTE PTR ReqPak+0DH +------------------------+ | Transfer_Address | DWORD PTR ReqPak+0EH +------------------------+ | Sector_Count | WORD PTR ReqPak+12H +------------------------+ | Start_Sector_Num | DWORD PTR ReqPak+14H +------------------------+ | Sys_File_Num | WORD PTR ReqPak+18H +------------------------+ The NonCachingWriteVerify request tells a block driver to write data directly to the device, to bypass the disk cache, and to verify the write. The Command_Code value in the Request Header is 1AH. Comments On entry, the Command-specific_Data area of the request packet contains the following fields as input to the device driver: ■ Media_Descriptor is set for the drive identified in the Request Header. ■ Transfer_Address has the 32-bit physical address of the data buffer. ■ Sector_Count has the number of sectors to transfer. ■ Start_Sector_Num is set for where to begin the transfer on the device. ■ Sys_File_Num is set to a unique number associated with an OpenDevice request. The device driver must do the following: ■ Perform the requested function. ■ Set the actual number of sectors transferred in the Sector_Count field. ■ Set the error bit (15) and error code (bits 0 to 7) in the Status field of the Request Header if there is an error. ■ Set the done bit (8) in the Status field. Note that the Transfer_Address field on entry contains a locked 32-bit physical address. The device driver can call the PhysToVirt routine to convert this physical address into a selector:offset or segment:offset virtual address, according to the current operating mode. The driver need not unlock the address when it has completed the NonCachingWriteVerify request. For more information about PhysToVirt, see Chapter 3, "Device Helper Services." See Also Command codes 09 (WriteVerify), 18H (NonCachingRead), 19H (NonCachingWrite), 0DH (OpenDevice) █ PrepareForSysShutdown ──────────────────────────────────────────────────────────────────────────── +-----------------------------+ | Request Header | 13 BYTEs +-----------------------------+ | Sub_Req_Code | BYTE PTR ReqPak+0DH +-----------------------------+ | Reserved | DWORD PTR ReqPak+0EH +-----------------------------+ The PrepareForSysShutdown command tells a device driver that it should transfer buffered data to a storage device before the system powers down. The Command_Code value in the Request Header is 1CH. Comments On entry, the Sub_Req_Code of the request packet contains one of the following values as input to any device driver that transfers buffered data to a long-term storage device: Value Means ──────────────────────────────────────────────────────────────────────────── 0 Beginning shutdown. 1 Shutdown completing. The driver should respond to the beginning-shutdown request by getting itself ready to handle the shutdown-completing request and setting the done bit (8) in the Status word of the Request Header when it has. Only drivers that transfer buffered data to long-term storage devices must ready themselves to flush data to the device. Other drivers should do the following: ■ Set the error bit (15) and set the error code (bits 0 to 7) to 03 (Unknown command) in the Status field of the request header. ■ Set the done bit (8) in the Status field. Drivers that transfer buffered data to long-term storage devices should respond to the shutdown-completing request as follows: ■ Flush buffered writes to the storage media. Only data that must be preserved across power downs need be flushed. ■ Set the error bit (15) and error code (bits 0 to 7) in the Status field of the Request Header if there is an error. ■ Set the done bit (8) in the Status field. For all its devices that save data across power downs, the device driver should return from this request with the write buffers flushed. After the driver receives this request, it should also do the following: ■ Process any subsequent write requests synchronously. ■ Do not carry out any operation that could block permanently. ■ Otherwise, continue to perform normally. Drivers that buffer data to non-saving devices should not flush their buffers. In particular, a driver should not carry out any operation that might block permanently, such as flushing to a com port. Drivers that do not buffer data to long-term storage devices should do the following: ■ Set the error bit (15) and set the error code (bits 0 to 7) to 03 (Unknown command) in the Status field of the request header. ■ Set the done bit (8) in the Status field. Chapter 3 Device Helper Services ──────────────────────────────────────────────────────────────────────────── 3.1 Device Helper Services An MS OS/2 device driver needs to do both system-level and hardware-specific operations. Therefore, the DevHlp interface to operating system services is available for device drivers. DevHlp services are available in the following categories: Category Routines ──────────────────────────────────────────────────────────────────────────── System-clock management SchedClockAddr Process management Block, DevDone, Run, TCYield, Yield Semaphore management SemClear, SemHandle, SemRequest Request-queue management AllocReqPacket, FreeReqPacket, PullParticular, PullReqPacket, PushReqPacket, SortReqPacket Character-queue management QueueFlush, QueueInit, QueueRead, QueueWrite Memory management AllocateGDTSelector, AllocPhys, FreePhys, Lock, PhysToGDTSelector, PhysToUVirt, PhysToVirt, Unlock, UnPhysToVirt, VerifyAccess, VirtToPhys Interrupt management EOI, RegisterStackUsage, SetIRQ, SetROMVector, UnSetIRQ Timer services ResetTimer, SetTimer, TickCount Processor-mode services ProtToReal, RealToProt Monitor management DeRegister, MonFlush, MonitorCreate, MonWrite, Register System services ABIOSCall, ABIOSCommonEntry, AttachDD, FreeLIDEntry, GetDosVar, GetLIDEntry, LogEntry, ROMCritSection, SendEvent Access to these system services is obtained at device driver initialization. The request packet for the Init command contains a bimodal pointer to the DevHlp interface. Because the pointer is bimodal, the device driver can request DevHlp services without being sensitive to whether the current operating mode is protected or real. The device driver calls a service by setting up the appropriate registers, loading a function code into the dl register, and making a far call to the DevHlp interface routine, whose address was supplied at device initialization time. Table 3.1 lists in numeric order the DevHlp function codes, the corresponding services, and a short description of each service. <TT>Function Codes for DevHlp Services" ""</TT> Code DevHlp Description service ──────────────────────────────────────────────────────────────────────────── 00 SchedClock Gets address of system's Addr clock-tick handler. 01 DevDone Signals that device I/O is complete. 02 Yield Yields the CPU. 03 TCYield Yields the CPU to a time-critical thread. 04 Block Blocks a thread from running. 05 Run Releases a blocked thread. 06 SemRequest Requests a semaphore. 07 SemClear Releases a semaphore. 08 SemHandle Gets a semaphore handle. 09 PushReqPac Pushes a request packet onto ket a queue. 0AH PullReqPac Pulls a request packet from ket a queue. 0BH PullPartic Pulls a specific request ular packet from a queue. 0CH SortReqPac Inserts a request packet in ket sorted order. 0DH AllocReqPa Allocates a request packet. cket 0EH FreeReqPac Frees an allocated request ket packet. 0FH QueueInit Initializes a character queue. 10H QueueFlush Flushes a character queue. 11H QueueWrite Inserts a character in a queue. 12H QueueRead Reads a character from a queue. 13H Lock Locks a memory segment. 14H Unlock Unlocks a memory segment. 15H PhysToVirt Maps a physical address to a virtual address. 16H VirtToPhys Maps a virtual address to a physical address. 17H PhysToUVir Maps a physical address to a t user virtual address. 18H AllocPhys Allocates a physical memory block. 19H FreePhys Frees a physical memory block. 1AH SetROMVect Sets a ROM BIOS interrupt or handler. 1BH SetIRQ Sets a hardware-interrupt handler. 1CH UnSetIRQ Resets a hardware-interrupt handler. 1DH SetTimer Sets a timer handler. 1EH ResetTimer Resets a timer handler. 1FH MonitorCre Creates a monitor. ate 20H Register Registers a monitor. 21H DeRegister Deregisters a monitor. 22H MonWrite Writes data records to a monitor. 23H MonFlush Flushes data from a monitor stream. , 24H GetDosVar Gets a pointer to a DOS variable. 25H SendEvent Sends an event. 26H ROMCritSec Flags a critical section of tion execution. 27H VerifyAcce Verifies memory access. ss 2AH AttachDD Attaches to another device driver. 2DH AllocGDTSe Allocates a set of GDT lector selectors. 2EH PhysToGDTS Converts a physical address elector to a GDT selector. 2FH RealToProt Changes from real to protected mode. 30H ProtToReal Changes from protected to real mode. 31H EOI Issues an end-of-interrupt. 32H UnPhysToVi Marks completion of virtual rt address use. 33H TickCount Modifies a timer. 34H GetLIDEntr Gets a logical ID. y 35H FreeLIDEnt Releases a logical ID. ry 36H ABIOSCall Calls an ABIOS service. 37H ABIOSCommo Calls an ABIOS common entry nEntry point. 3AH RegisterSt Registers a device driver's ackUsage stack usage. 3BH LogEntry Places data in the system error-log buffer. 3CH VideoPause Suspends or resumes video DMA transfers. 3DH DispMsg Displays a message from a device driver after initialization. At any given moment, device driver code runs in one of four contexts: ■ Kernel mode─the context in which the device driver's strategy routine runs. ■ Interrupt mode─the context in which the device driver's hardware-interrupt handler runs. ■ User mode─the context in which the device driver's handler for a real-mode ROM BIOS interrupt runs. ■ Initialization mode─the context in which the device driver's strategy routine runs when it is called by the Init request packet. Certain restrictions apply to when individual DevHlp services may be used. Table 3.2 summarizes these restrictions for the DevHlp routines, listed in alphabetic order. For each routine, a valid context can be one or more of the following: kernel (KNL), interrupt (ITR), user (USR), or initialization (INI). <TT>DevHlp Services and Corresponding States" ""</TT> DevHlp service Code Valid in context ──────────────────────────────────────────────────────────────────────────── ABIOSCall 36H KNL, ITR, USR, INI ABIOSCommonEntry 37H KNL, ITR, USR, INI AllocGDTSelector 2DH INI AllocPhys 18H KNL, INI AllocReqPacket 0DH KNL AttachDD 2AH KNL, INI Block 04 KNL, USR DeRegister 21H KNL DevDone 01 KNL, ITR DispMsg 3DH INI EOI 31H ITR, INI FreeLIDEntry 35H KNL, INI FreePhys 19H KNL, INI FreeReqPacket 0EH KNL GetDosVar 24H KNL, INI GetLIDEntry 34H KNL, INI Lock 13H KNL, INI LogEntry 39H KNL, ITR, USR MonFlush 23H KNL MonitorCreate 1FH KNL, INI MonWrite 22H KNL, ITR, USR PhysToGDTSelector 2EH KNL, ITR, USR, INI PhysToUVirt 17H KNL, INI PhysToVirt 15H KNL, ITR, INI ProtToReal 30H ITR PullParticular 0BH KNL, ITR PullReqPacket 0AH KNL, ITR PushReqPacket 09 KNL QueueFlush 10H KNL, ITR, USR QueueInit 0FH KNL, ITR, USR, INI QueueRead 12H KNL, ITR, USR QueueWrite 11H KNL, ITR, USR RealToProt 2FH ITR Register 20H KNL RegisterStackUsage 3AH INI ResetTimer 1EH KNL, ITR, INI ROMCritSection 26H USR Run 05 KNL, ITR, USR SchedClockAddr 00 INI SemClear 07 KNL, ITR, USR SemHandle 08 KNL, ITR SemRequest 06 KNL, USR SendEvent 25H KNL, ITR SetIRQ 1BH KNL, INI SetROMVector 1AH KNL, INI SetTimer 1DH KNL, INI SortReqPacket 0CH KNL TCYield 03 KNL TickCount 33H KNL, ITR, USR, INI Unlock 14H KNL, INI UnPhysToVirt 32H KNL, ITR, INI UnSetIRQ 1CH KNL, ITR, INI VerifyAccess 27H KNL VideoPause 3CH KNL, ITR, INI VirtToPhys 16H KNL, INI Yield 02 KNL 3.2 Using DevHlp Routines Your device driver calls a DevHlp routine by setting up the appropriate registers, loading the appropriate function code into the dl register, and making a far call to the DevHlp interface routine. In addition to the return values for each routine, the interrupt and carry flags can be set or cleared by some routines. Other flags can also be affected by the calls. Some routines require that the interrupt flag be clear (interrupts disabled) when they are called. For your device driver, you can assume the following: ■ All registers except flags are preserved across DevHlp calls unless they contain return parameters. ■ A DevHlp routine will preserve the state of the interrupt flag and will not enable interrupts unless explicitly stated otherwise in the functional description of the routine. A functional description follows for each DevHlp routine, in alphabetic order. The assembly code example for each routine loads specific registers with named parameters. However, these names are metasymbols rather than names that you must use for the parameters your driver passes to the DevHlp routines. The Parameters section for each routine defines each parameter that must be passed. You can name a parameter anything you like, as long as you load it into the register shown in the assembly example before calling the DevHlp entry point. █ ABIOSCall ──────────────────────────────────────────────────────────────────────────── MOV AX,LID ; logical ID for device MOV SI,RBOffset ; offset in data segment ; to ABIOS request block MOV DH,EntryPoint ; ABIOS service entry point: ; 0 = start, 1 = interrupt, 2 = timeout MOV DL,DEVHLP_ABIOSCALL ; DEVHLP_ABIOSCALL EQU 36H CALL [Device_Help] The ABIOSCall routine calls an ABIOS service for a device driver that uses the Operating System Transfer Convention. Under this convention, MS OS/2 determines the effective address of the ABIOS-service entry point. This convention is generally used for handling interrupts from character and programmed I/O devices that repeatedly call a single ABIOS subroutine. The ABIOS services are not available for AT-class machines. Parameters LID the logical ID for the device requiring ABIOS service. The LID value is obtained by a call to GetLIDEntry when the driver initializes. RBOffset the offset of the ABIOS request block within the device driver's data segment. EntryPoint the code for the ABIOS-service entry point. It may be one of the following values: Value Meaning ──────────────────────────────────────────────────────────────────────────── 0 Start - make a service request. 1 Interrupt - resume a multi-staged request. 2 Timeout - terminate a request that fails to receive an interrupt in a specified time. DEVHLP_ABIOSCALL the function code; its value is 36H. Return Value The carry (C) flag is cleared if the routine successfully calls the ABIOS service. Otherwise, the C flag is set and the ax register may have one of the following error values: ■ ABIOS not present. ■ Unknown ABIOS command. Comments This routine determines the mode-dependent address of the requested ABIOS service, sets up the stack for the call to ABIOS, and calls the specified ABIOS service for the device driver. The driver must initialize the return-code field of its ABIOS request block to 0FFFFH before issuing ABIOSCall for the Start service. The ds register must point to the device driver's low-memory data segment. If the driver has already called the PhysToVirt routine with ds, this register must be reset to the driver's low-memory data segment. The driver's low-memory data segment is the first-linked segment that contains the device header. This segment contains one or more ABIOS request blocks and usually contains the driver's data transfer buffers as well. When the buffers are in this segment, the driver creates logical addressability to its buffers for ABIOS without having to consider the current operating mode or interrupt disable time. For performance reasons, a device driver should call ABIOS services with processor interrupts enabled. The driver can use an intermediate buffer located in its low-memory data segment for the data transfer performed by ABIOS. The data can be transferred later to a logically addressed buffer (selector:offset or segment:offset according to the current operating mode). In other words, the device driver must double buffer data transferred by ABIOS if the target location could be high memory while running in real mode or if the driver needs to run with interrupts enabled. In a multi-staged data transfer request, the driver might have to change the address of a logically addressed data buffer in the ABIOS request block from stage to stage (at each change in operating mode). However, the driver must call Lock for all stages of a transfer to or from devices that require physical-address data transfers, such as DMA devices. If the driver calls ABIOS services in user mode, it can call ROMCritSection immediately before ABIOSCall to keep the ABIOS service from being suspended in the background. Without the call to ROMCritSection, a foreground real-mode process would be suspended indefinitely if a request for a context switch to a protected-mode application occurs. When the ABIOS service returns, ABIOSCall cleans up the stack before relinquishing control to the device driver. The return code of the ABIOS service will be in the ABIOS request block. However, the driver cannot assume that the return codes for ABIOS requests occur in any given order. Consider the case of a staged-on-interrupt request where the device driver's strategy routine calls the ABIOS Start service. If a device interrupt occurs after ABIOS Start has updated its return code but the device driver's strategy routine has not yet examined it, the interrupt handler would process the ABIOS request block. The interrupt handler should flag whether it has already processed the request to completion when it returns control to the strategy routine. Then, the strategy routine need not examine the ABIOSCall return code because it can check the flag. If the request is complete, the strategy routine can clean up its request-packet queue and pull the next request packet for an ABIOSCall to Start service on another ABIOS request block. For a multi-staged request where the strategy routine is expected to call Block on interrupt, the strategy routine can ignore the ABIOSCall return code by checking the flag, but it may still have to call Block if the interrupt handler returns control without processing the request to completion. The ABIOSCall Start service sets the return code to staged-on-interrupt for a request that must wait for an interrupt associated with a particular device. In fact, several requests for the same LID may be started and waiting for the device interrupt. When this interrupt occurs, the interrupt handler must call the ABIOS Interrupt service for every outstanding staged-on-interrupt request block in order to completely process the LID; this includes any ABIOS request blocks in which the Start service has changed the return code from 0FFFFH but not yet returned control to the caller. The interrupt handler may call EOI only after completely processing the LID associated with the interrupt. To minimize pre-EOI processing time, the interrupt handler may call EOI before it sets the return information in the system request packet or before it begins processing a request packet queued by the device driver's strategy routine. After it issues the EOI, the interrupt handler can be reentered at its entry point. Device drivers can also make multi-staged data transfers with the ABIOSCall Timeout service. The driver can call SetTimer or TickCount to force its timer-tick entry point to receive control as infrequently as possible. The granularity of the ABIOS Timeout service is in one-second increments. MS OS/2 device drivers must support both protected- and real-mode operations. For devices whose state information is kept internally in the ABIOS and BIOS device blocks (such as diskettes and disks), the device driver must reset the device when switching between ABIOS and compatibility BIOS operations. See Also Block, EOI, GetLIDEntry, Lock, ROMCritSection, SetTimer, TickCount █ ABIOSCommonEntry ──────────────────────────────────────────────────────────────────────────── MOV AX,LID ; logical ID for device MOV SI,RBOffset ; offset in data segment ; to ABIOS request block MOV DH,EntryPoint ; ABIOS common entry point: ; 0 = start, 1 = interrupt, 2 = timeout MOV DL,DEVHLP_ABIOSCOMMONENTRY ; DEVHLP_ABIOSCOMMONENTRY EQU 37H CALL [Device_Help] The ABIOSCommonEntry routine calls an ABIOS service for a device driver that uses the Advanced BIOS Transfer Convention. ABIOS services are not available for AT-class machines. Parameters LID the logical ID for the device requiring ABIOS service. The LID value is obtained by a call to GetLIDEntry when the driver initializes. RBOffset the offset of the ABIOS request block within the device driver's data segment. EntryPoint the code for the ABIOS common entry point. It may be one of the following values: Value Meaning ──────────────────────────────────────────────────────────────────────────── 0 Start - make a service request. 1 Interrupt - resume a multi-staged request. 2 Timeout - terminate a request that fails to receive an interrupt in a specified time. DEVHLP_ABIOSCOMMONENTRY the function code; its value is 37H. Return Value The carry (C) flag is cleared if the routine successfully calls the ABIOS service. Otherwise, the C flag is set and the ax register may have one of the following error values: ■ ABIOS not present. ■ Unknown ABIOS command. Comments This routine determines the mode-dependent address of the requested ABIOS common entry point, sets up the stack for the call to ABIOS, and calls the specified ABIOS common entry point for the device driver. The driver must initialize the return-code field of its ABIOS request block to 0FFFFH before issuing ABIOSCommonEntry for the Start service. The ds register must point to the device driver's low-memory data segment. If the driver has already called the PhysToVirt routine with ds, this register must be reset to the driver's low-memory data segment. The driver's low-memory data segment is the first-linked segment that contains the device header. This segment contains one or more ABIOS request blocks and usually contains the driver's data transfer buffers as well. When the buffers are in this segment, the driver creates logical addressability to its buffers for ABIOS without having to consider the current operating mode or the interrupt disable time. For performance reasons, a device driver should call ABIOS services with processor interrupts enabled. The driver can use an intermediate buffer located in its low-memory data segment for the data transfer performed by ABIOS. The data can be transferred later to a logically addressed buffer (selector:offset or segment:offset according to the current operating mode). In other words, the device driver must double buffer data transferred by ABIOS if the target location could be high memory while running in real mode or if the driver needs to run with interrupts enabled. In a multi-staged data transfer request, the driver might have to change the address of a logically addressed data buffer in the ABIOS request block from stage to stage (at each change in operating mode). However, the driver must call Lock for all stages of a transfer to or from devices that require physical-address data transfers, such as DMA devices. If the driver calls ABIOS services in user mode, it can call ROMCritSection immediately before ABIOSCommonEntry to keep the ABIOS routine from being suspended in the background. Without the call to ROMCritSection, a foreground real-mode process would be suspended indefinitely if a request for a context switch to a protected-mode application occurs. When the ABIOS routine returns, ABIOSCommonEntry cleans up the stack before relinquishing control to the device driver. The return code of the ABIOS routine will be in the ABIOS request block. However, the driver cannot assume that the return codes for ABIOS requests occur in any given order. Consider the case of a staged-on-interrupt request where the device driver's strategy routine calls the ABIOS Start service. If a device interrupt occurs after ABIOS Start has updated its return code but the driver's strategy routine has not yet examined it, the interrupt handler would process the ABIOS request block. The interrupt handler should flag whether it has already processed the request to completion when it returns control to the strategy routine. Then, the strategy routine need not examine the return-code field because it can check the flag. If the request is complete, the strategy routine can clean up its request-packet queue and pull the next request packet for an ABIOSCommonEntry call to the Start service on another ABIOS request block. For a multi-staged request where the strategy routine is expected to call Block on interrupt, the strategy routine can ignore the return code by checking the flag, but it may still have to call Block if the interrupt handler returns control without processing the request to completion. The ABIOSCommonEntry Start service sets the return code to staged-on-interrupt for a request that must wait for an interrupt associated with a particular device. In fact, several requests for the same LID may be started and waiting for the device interrupt. When this interrupt occurs, the interrupt handler must call the ABIOS Interrupt service for every outstanding staged-on-interrupt request block in order to completely process the LID; this includes any ABIOS request blocks in which the Start service has changed the return code from 0FFFFH but not yet returned control to the caller. The interrupt handler may call EOI only after completely processing the LID associated with the interrupt. To minimize pre-EOI processing time, the interrupt handler may call EOI before it sets the return information in the system request packet or before it begins processing a request packet queued by the device driver's strategy routine. After it issues EOI, the interrupt handler can be reentered at its entry point. Device drivers can also make multi-staged data transfers with the ABIOSCommonEntry Timeout service. The driver can call SetTimer or TickCount to force its timer-tick entry point to receive control as infrequently as possible. The granularity of the ABIOS Timeout service is in one-second increments. MS OS/2 device drivers must support both protected- and real-mode operations. For devices whose state information is kept internally in the ABIOS and BIOS device blocks (such as diskettes and disks), the device driver must reset the device when switching between ABIOS and compatibility BIOS operations. See Also Block, EOI, GetLIDEntry, Lock, ROMCritSection, SetTimer, TickCount █ AllocGDTSelector ──────────────────────────────────────────────────────────────────────────── MOV ES,AddressHigh ; 32-bit address MOV DI,AddressLow ; of GDT selector array MOV CX,Number ; number of selectors requested MOV DL,DEVHLP_ALLOCGDTSELECTOR ; DEVHLP_ALLOCGDTSELECTOR EQU 2DH CALL [Device_Help] The AllocGDTSelector routine allocates a set of GDT (global descriptor table) selectors for use by a device driver. The allocation occurs when the driver initializes. Parameters AddressHigh the high word (selector or segment) of the memory address where a word array will be filled with allocated GDT selectors. AddressLow the low word (offset) of the memory address where the array will be filled with allocated GDT selectors. Number the number of selectors to allocate. DEVHLP_ALLOCGDTSELECTOR the function code; its value is 2DH. Return Value The carry (C) flag is cleared if the routine is successful. Otherwise, the C flag is set and the ax register may have one of the following error values: ■ Invalid address. ■ Zero selectors requested. ■ Not enough selectors available. Comments This routine allocates a set of GDT selectors that a device driver can use for bimodal task- and interrupt-time operations. The address passed into es:di locates the first word of an array to be filled with GDT selectors by AllocGDTSelector. Note that the returned selectors are not necessarily contiguous. The task handler of a bimodal device driver can transfer data without being dependent on the current operating mode. MS OS/2 device drivers must support both protected- and real-mode I/O. The task handler may use the RealToProt and ProtToReal routines to change the current operating mode. If it calls RealToProt or ProtToReal, the driver must restore the original operating mode before relinquishing control. The interrupt handler of a bimodal device driver can address data buffers through the GDT regardless of the context of the current process. The driver might need to access a buffer that is not within the data space addressed by the current LDT (local descriptor table). The interrupt handler may use the PhysToGDTSelector routine to establish the addressability of a GDT selector. For a fixed memory area, the returned selector remains valid until the handler calls PhysToGDTSelector for the same selector. See Also Lock, PhysToGDTSelector, ProtToReal, RealToProt, Unlock █ AllocReqPacket ──────────────────────────────────────────────────────────────────────────── MOV DH,WaitFlag ; wait for available request packet: ; 0 = wait, 1 = no wait MOV DL,DEVHLP_ALLOCREQPACKET ; DEVHLP_ALLOCREQPACKET EQU 0DH CALL [Device_Help] The AllocReqPacket routine returns a bimodal pointer to a request packet. Parameters WaitFlag whether to wait for an available request packet. It may be one of the following: Value Meaning ──────────────────────────────────────────────────────────────────────────── 0 Wait for request packet. 1 Return immediately if packet not available. DEVHLP_ALLOCREQPACKET the function code; its value is 0DH. Return Value The carry (C) flag is cleared and the es:bx register pair contains the address of the allocated request packet if the routine is successful. Otherwise, the C flag is set. Comments This routine returns a bimodal pointer to a request packet. The bimodal pointer is a virtual address that is valid for both protected and real modes. MS OS/2 device drivers must support both protected- and real-mode operations. A driver cannot use request packets stored in its data segment because the pointers would not be bimodal. Instead, the driver allocates a dword queue header in its (ds) data segment to point to a bimodal request-packet list. It initializes the queue header to zero before its first call to AllocReqPacket. Because the pointer returned by AllocReqPacket is bimodal, the driver can use its own request-queue management to place and maintain the request-packet pointers and linkage fields. The queue header points to the next packet to be serviced by the device; a queue header value of zero indicates an empty request queue. The queue-linkage field of the request packet contains a pointer to the next packet in the queue; a queue-linkage value of zero indicates the end of the queue. For more information about the layout of request packets, see Chapter 2, "Device Commands." The device driver can queue request packets that cannot be serviced immediately whenever the device is busy. For example, a disk device driver that supports more than one device would allocate a queue header and maintain a request-packet list for each device it supports. After a call to AllocReqPacket, the driver can place the allocated packet in the queue with a call to PushReqPacket. Certain device drivers such as disk drivers need additional request packets to service task-time requests. Disk (block) device drivers can use SortReqPacket to place an allocated packet in the request queue. Device drivers remove a request packet from the queue with PullReqPacket or PullParticular. Already serviced (or unused) request packets should be released as soon as possible with a call to FreeReqPacket so that the next call to AllocReqPacket is more likely to find a packet available. The AllocReqPacket routine does not preserve the state of the interrupt flag. See Also FreeReqPacket, PullParticular, PullReqPacket, PushReqPacket, SortReqPacket █ AllocPhys ──────────────────────────────────────────────────────────────────────────── MOV BX,SizeLow ; 32-bit block size in bytes MOV AX,SizeHigh MOV DH,HighOrLow ; position relative to 1 megabyte: ; 0 = above 1 meg, 1 = below 1 meg MOV DL,DEVHLP_ALLOCPHYS ; DEVHLP_ALLOCPHYS EQU 18H CALL [Device_Help] The AllocPhys routine allocates a block of fixed memory. Parameters SizeLow the low word of the 32-bit block size in bytes. SizeHigh the high word of the 32-bit block size in bytes. HighOrLow the position of the allocated memory relative to the one-megabyte memory boundary. This value may be one of the following: Value Meaning ──────────────────────────────────────────────────────────────────────────── 0 Allocated memory is above one megabyte. 1 Allocated memory is below one megabyte. DEVHLP_ALLOCPHYS the function code; its value is 18H. Return Value The carry (C) flag is cleared and the ax:bx register pair contains the 32-bit physical address if the routine is successful. Otherwise, the C flag is set and the ax register may have the following error value: ■ Memory not allocated. Comments This routine allocates fixed memory that cannot be moved by a call to Unlock. Call FreePhys to release memory allocated by AllocPhys. AllocPhys returns an error if the device driver clears HighOrLow and there is no available memory above one megabyte. The driver could then attempt to allocate low memory. The routine also returns an error if the device driver sets HighOrLow and there is no available memory below one megabyte. The driver could then attempt to allocate high memory. See Also FreePhys, Unlock █ AttachDD ──────────────────────────────────────────────────────────────────────────── MOV BX,OFFSET DDName ; name of device driver ; to get IDC from MOV DI,OFFSET DD@ ; data area to hold IDC addresses MOV DL,DEVHLP_ATTACHDD ; DEVHLP_ATTACHDD EQU 2AH CALL [Device_Help] The AttachDD routine gets addressability to the inter-device driver communication (IDC) entry point of a specified device driver for the calling device driver. Parameters DDName Specifies the ASCII name of the target device driver. For a target character device driver, DDName must match the name in the device header. DD@ Specifies a 12-byte field with the following layout: Length Description ──────────────────────────────────────────────────────────────────────────── word Real-mode offset of IDC entry point. word Real-mode cs segment of IDC entry point. word Real-mode ds of target IDC device driver. word Protected-mode offset of IDC entry point. word Protected-mode cs selector of IDC entry point. word Protected-mode ds of IDC device driver. DEVHLP_ATTACHDD the function code; its value is 2AH. Return Value The carry (C) flag is cleared and the data area at DD@ is filled if the routine is successful. Otherwise, the C flag is set and the ax register has one of the following error values: ■ Device driver not found. ■ No IDC entry point. Comments This routine allows device drivers to communicate and to pass data among themselves. However, communicating drivers must set up their device headers as follows: ■ The Attribute field must indicate that the driver can participate in the inter-device driver communication. ■ The offset to a target driver's IDC-entry-point data area must be identified for the device driver that calls it. In addition, the calling driver must initialize storage for the target driver's name (DDName) and must allocate storage for the target's IDC addresses (DD@) in the low-memory data segment. The calling driver's low-memory data segment is its first-linked segment that contains the device header. This segment is accessed by the ds register. For more information about device headers, see Chapter 1, "Overview of Base and Installable Device Drivers." After a successful call to AttachDD, the calling device driver must verify that it obtained a nonzero IDC-entry-point value for the operating mode in which it will make the IDC call. The calling driver must also set the ds register for the target device driver. If the source driver passes parameters to the target driver, the target must define the other registers used in the calling convention. The IDC entry point of the target device driver must follow the far call/ret model. █ Block ──────────────────────────────────────────────────────────────────────────── MOV BX,EventIDLow ; low word of event ID MOV AX,EventIDHigh ; high word of event ID MOV DI,TimeLimitHigh ; time-out interval in milliseconds MOV CX,TimeLimitLow ; with -1 = never time-out MOV DH,InterruptibleFlag ; interruptible sleep: ; 0 = interruptible, 1 = not interruptible MOV DL,DEVHLP_PROCBLOCK ; DEVHLP_PROCBLOCK EQU 04H CALL [Device_Help] The Block routine "sleeps" (suspends) the current device driver thread until the driver calls Run on the event identifier or until a time-out occurs. Parameters EventIDLow the low word of the event identifier. EventIDHigh the high word of the event identifier. By convention, an event identifier is the physical address of some structure or memory location associated with the reason for blocking. TimeLimitHigh the high word of the time-out interval in milliseconds. If the value is -1 for both time-limit parameters, the thread sleeps indefinitely until the device driver calls Run if the block is not interruptible. TimeLimitLow the low word of the time-out interval in milliseconds. If the value is -1, the thread sleeps indefinitely until the device driver calls Run if the block is not interruptible. InterruptibleFlag whether the thread's sleep is interruptible. This parameter may be one of the following values: Value Meaning ──────────────────────────────────────────────────────────────────────────── 0 Interruptible: MS OS/2 can return from the block if some internal event requires the driver's attention. 1 Not interruptible: the thread sleeps until the driver calls Run or the time-out interval expires. DEVHLP_PROCBLOCK the function code; its value is 4. Return Value The carry (C) flag is cleared and the al register contains zero if the driver called Run on an event. Otherwise, the C flag is set, indicating an unusual wake-up and the al register contains a nonzero error code. The zero (Z) flag is cleared if the wake-up was due to a time-out, and the Z flag is set if the wake-up was due to an interrupt. Comments This routine can be called only by the task-time portion of a device driver. The Run routine is its companion routine, usually called by the driver's interrupt handler. Device drivers coordinate Block and Run calls by an EventID value that is, if possible, used only by the driver's blocking and running routines. EventID specifies an arbitrary 32-bit value, so the system cannot guarantee immunity from a spurious wake-up if some unrelated thread happens to run with an EventID value that matches a driver's call to Block. Choose an EventID value for block/run operations that is likely to be unique, such as the 32-bit physical address of some structure or memory location associated with the reason for blocking. For example, a thread blocking until a resource is cleared could use the physical address of the ownership flag for that resource. Note that a device driver could be blocked in protected mode but run in real mode (and vice versa), so you should not use a virtual address for an EventID. The logical address of an item in one mode is not the same as its logical address in the other mode. Before calling Run for a block-on-event, check the reason for the wake-up to be sure that the event occurred. If your EventID value was not unique, the wake-up might have been accidental. MS OS/2 will not immediately return from Block. Instead, it removes the current thread from the run queue and starts executing some other thread. In other words, a call to Block causes a context switch. Depending on the parameter values, the thread is reactivated and Block returns when the driver calls Run, the time-out interval expires, or an interrupt causes a return from Block. Use the following sequence when calling Block: Disable interrupts while (need to wait) Block (value) Disable interrupts First, disable interrupts before checking the wait-condition (such as I/O done, resource freed, or any other), to avoid deadlock if an interrupt-time Run call occurs before the call to Block completes. The Block routine re-enables interrupts. Second, check the wait-condition repeatedly and call block again, if necessary. If the TimeLimit specification is -1, Block waits indefinitely until the driver calls Run or the sleep is interrupted. If the InterruptibleFlag value is zero, MS OS/2 can abort the blocked thread and return from Block to the caller. On return from Block, the C and Z flags indicate what caused the wake-up. If C is set, check the Z flag to determine whether the sleep was interrupted. If it was, an internal event occurred that requires the driver's attention, such as a signal, a process death, or some other forced action. The driver can perform any necessary clean-up, set the error code in the Status field of the request packet, and call DevDone to return the packet to the kernel. Calls to Block should be interruptible unless the blocked thread will sleep for less than one second. See Also DevDone, GetDosVar, Run, TCYield, Yield █ DeRegister ──────────────────────────────────────────────────────────────────────────── MOV BX,MonitorPID ; process ID of monitor task MOV AX,MonHandle ; handle for chain ; returned by MonitorCreate MOV DL,DEVHLP_DEREGISTER ; DEVHLP_DEREGISTER EQU 21H CALL [Device_Help] The DeRegister routine removes the monitors associated with a monitor task from the monitor chain. Parameters MonitorPID the process identifier of the monitor task. The device driver called GetDosVar to get LocINFOSeg access and obtained this value from the current LDT (local descriptor table). MonHandle the monitor chain. DEVHLP_DEREGISTER the function code; its value is 21H. Return Value The carry (C) flag is cleared if the routine is successful, and the ax register contains the number of monitors that are still registered in the monitor chain, if any. Otherwise, the C flag is set and the ax register may have the following error value: ■ Invalid monitor handle. Comments This routine removes one or more monitors from a monitor chain for a given monitor task. The monitor task calls DosMonClose, passing the monitor handle, to request removal of its monitors. The MS OS/2 monitor dispatcher forwards the request to the appropriate driver. The device driver may call DeRegister only at task time in protected mode. The device driver supplies the monitor-chain handle and the process identifier (PID) of the requesting monitor task when it calls DeRegister. The driver determines the PID of the requesting task by calling GetDosVar for access to LocINFOSeg (the current LDT). Note that DeRegister removes all monitors for the specified PID from the specified monitor chain. However, the monitor chain might not be empty when DeRegister returns. If the driver registered monitors for another monitor task (with a different PID) in the same chain, DeRegister returns a count of the remaining monitors in the ax register. The driver must remove all monitors from a chain before calling MonitorCreate to remove the chain itself. See Also GetDosVar, MonitorCreate, Register █ DevDone ──────────────────────────────────────────────────────────────────────────── LES BX,ReqPacket ; pointer to I/O request packet MOV DL,DEVHLP_DEVDONE ; DEVHLP_DEVDONE EQU 01H CALL [Device_Help] The DevDone routine indicates that an I/O request packet has been fully serviced. A device driver calls DevDone for just completed requests that had been returned to the kernel at strategy time because they were incomplete. Parameters ReqPacket to an I/O request packet. DEVHLP_DEVDONE the function code; its value is 1. Return Value DevDone does not return a value. Comments DevDone boosts the priority of all threads that are blocked in the kernel waiting for the driver to service the request packet, as well as setting the Done bit in the Status field of the request-packet header and calling Run for the blocked threads. Unlike DevDone, Run merely releases a blocked thread at its original priority. DevDone is usually called by the driver's interrupt handler, but it can be called in kernel mode. For more information about request packets, see Chapter 2, "Device Commands." The interrupt handler should set appropriate error flags in the Status field of the request-packet header before it calls DevDone. The ReqPacket pointer is bimodal, valid in both protected and real modes. If the device driver's strategy routine completes a request, the driver need not call DevDone for that request. The strategy routine simply sets the done bit (8) in the request packet and returns it to the kernel. Call DevDone only for I/O request packets that were returned incomplete by the strategy routine or for unusual wake-ups of blocked threads. Do not call DevDone for request packets allocated by a call to AllocReqPacket. See Also AllocReqPacket, Block █ EOI ──────────────────────────────────────────────────────────────────────────── MOV AL,IRQNum ; interrupt level number (0-0FH) MOV DL,DEVHLP_EOI ; DEVHLP_EOI EQU 31H CALL [Device_Help] The EOI routine issues an end-of-interrupt (EOI) to the master or slave PIC (programmable interrupt controller) as appropriate to the specified interrupt level. Parameters IRQNum the interrupt-level number, in the range 00 to 0FH. DEVHLP_EOI the function code; its value is 31H. Return Value EOI does not return a value. Comments This routine issues an end-of-interrupt to the PIC(s) when the interrupt handler has processed requests for that interrupt level. If the specified IRQNum is for the slave PIC, EOI issues the end-of-interrupt to both master and slave PICs. EOI preserves the state of the interrupt flag. However, the interrupt handler should disable interrupts with the cli instruction before calling EOI if the handler will return immediately to the operating system from the EOI call. Then, the processing of interrupts completes before the system must service the next interrupt, thus reducing the chance of stack overflow. Device drivers that use this routine to send an end-of-interrupt are upward compatible under MS OS/2. EOI is bimodal and can be called both during device driver initialization and for interrupt processing. See Also RegisterStackUsage, SetIRQ, SetROMVector █ FreeLIDEntry ──────────────────────────────────────────────────────────────────────────── MOV AX,LID ; logical ID from GetLIDEntry MOV DL,DEVHLP_FREELIDENTRY ; DEVHLP_FREELIDENTRY EQU 35H CALL [Device_Help] The FreeLIDEntry routine releases a logical ID when an ABIOS device driver deinstalls. ABIOS services are not available for AT-class machines. Parameters LID the logical ID for a device that was associated with the device driver by a call to GetLIDEntry when the driver initialized. DEVHLP_FREELIDENTRY the function code; its value is 35H. Return Value The carry (C) flag is cleared if the routine is successful. Otherwise, the C flag is set and the ax register may have one of the following error values: ■ Not your LID. ■ LID does not exist. ■ ABIOS not present. Comments The device driver must release its LID(s) when it terminates. The attempt to free a logical ID will fail if the driver is not associated (by GetLIDEntry) with the specified LID value or if the LID does not exist. When FreeLIDEntry is called, the ds register must point to the device driver's low-memory data segment. The driver's low-memory data segment is the first-linked segment that contains the device header. If the driver has called the PhysToVirt routine with ds, this register must be reset to the driver's low-memory data segment. See Also GetLIDEntry, ABIOSCall, ABIOSCommonEntry, PhysToVirt █ FreeReqPacket ──────────────────────────────────────────────────────────────────────────── LES BX,ReqPacket ; pointer to request packet ; provided by AllocReqPacket MOV DL,DEVHLP_FREEREQPACKET ; DEVHLP_FREEREQPACKET EQU 0EH CALL [Device_Help] The FreeReqPacket routine releases a request packet that was allocated by AllocReqPacket. Parameters ReqPacket to the request packet that will be released to the system. DEVHLP_FREEREQPACKET the function code; its value is 0EH. Return Value FreeReqPacket does not return a value. Comments This routine releases a request packet when a device driver no longer needs it. The request packet must have been allocated by the AllocReqPacket routine. Call FreeReqPacket as soon as the packet is not in use, rather than allocating request packets to hold for future use. If you allocate packets as needed and free them promptly, your calls to AllocReqPacket are more likely to find request packets available. FreeReqPacket does not preserve the state of the interrupt flag. Use FreeReqPacket, not the DevDone routine, to return request packets allocated by AllocReqPacket. See Also AllocReqPacket, DevDone █ FreePhys ──────────────────────────────────────────────────────────────────────────── MOV BX,AddressLow ; 32-bit physical address MOV AX,AddressHigh MOV DL,DEVHLP_FREEPHYS ; DEVHLP_FREEPHYS EQU 19H CALL [Device_Help] The FreePhys routine releases memory allocated by a call to AllocPhys. Parameters AddressLow the low word of the 32-bit physical address of a memory block allocated by AllocPhys. AddressHigh the high word of the 32-bit physical address of a memory block allocated by AllocPhys. DEVHLP_FREEPHYS the function code; its value is 19H. Return Value The carry (C) flag is cleared if the routine is successful. Otherwise, the memory is not released and the C flag is set, indicating the following error: ■ Cannot free memory not allocated by AllocPhys. Comments Any memory block allocated by AllocPhys should be released with a call to FreePhys before the device driver terminates. See Also AllocPhys █ GetDosVar ──────────────────────────────────────────────────────────────────────────── MOV AL,VarNumber ; index of variable MOV DL,DEVHLP_GETDOSVAR ; DEVHLP_GETDOSVAR EQU 24H CALL [Device_Help] The GetDosVar routine returns a bimodal pointer to an internal DOS-compatibility variable. Parameters VarNumber the index of the MS OS/2 variable. It can be one of the following values: Index Description ──────────────────────────────────────────────────────────────────────────── 1 Specifies the SysINFOSeg, a word that is the bimodal selector or segment address of the system global descriptor table (GDT) INFO segment. This index specification is valid at task time and interrupt time. 2 Specifies the LocINFOSeg, a dword that is the selector:offset or segment:offset of the local descriptor table (LDT) INFO segment. This index specification is valid only task time. 4 Specifies the VectorSDF, a dword that is the vector to the stand-alone dump facility. This index specification is valid at task time and interrupt time. 5 Specifies the VectorReboot, a dword that is the vector to reboot DOS. This index is valid at task time and interrupt time. 6 Specifies the VectorMSATS, a qword that contains the protected-and real-mode pointers to the MSATS facility. This index specification is valid at task time and interrupt time. 7 Specifies the YieldFlag, a byte that indicates whether to yield the CPU; if this flag is set, a thread of equal or higher priority is waiting to run. This index specification is valid only at task time. 8 Specifies the TCYieldFlag, a byte that indicates whether to yield the CPU; if this flag is set, a time-critical thread of equal or higher priority is waiting to run. This index specification is valid only at task time. 11 Specifies the CodePageTagPtr, a dword that is the segment:offset of the current real-mode code page. This index specification is valid only at task time. 12 Specifies the VectorRIPL, a dword that points to the boot environment descriptor table; if this pointer is nonzero, the boot environment is an RIPL (remote initial program load). This index specification is valid at task time and interrupt time. DEVHLP_GETDOSVAR the function code; its value is 24H. Return Value The carry (C) flag is cleared and the ax:bx register pair points to the specified variable if the routine is successful. Otherwise, the C flag is set. Comments This routine returns a bimodal pointer to an indexed variable. Note that this pointer sometimes accesses a data structure and sometimes is a vector to a facility. All indexed variables are read-only. Index values 3, 9, and 10 are reserved. The list of available variables might change in future versions of MS OS/2. See Also TCYield, Yield █ GetLIDEntry ──────────────────────────────────────────────────────────────────────────── MOV AL,DeviceID ; device type ID MOV BL,RelativeLIDNum ; Nth logical ID of this device ID: ; 0 = first available LID, 1 = first LID, ; 2 = second LID, ..., ; 0FFH = max LID value MOV DH,DeviceState ; requested LID indicator: ; 1 = DMA or POS, 0 = all other device types MOV DL,GETLIDENTRY ; GETLIDENTRY EQU 34H CALL [Device_Help] The GetLIDEntry routine associates the logical ID of an existing device with a device driver when the ABIOS driver initializes. ABIOS services are not available on AT-class machines. Parameters DeviceID the kind of device for which the device driver requests an LID. This parameter may be one of the following values: Value Meaning ──────────────────────────────────────────────────────────────────────────── 01 Diskette 02 Disk 03 Video 04 Keyboard 05 Parallel port 06 Asynchronous communications 07 System timer 08 Real-time clock timer 0AH Nonmaskable interrupt 0BH Pointing device 0EH Nonvolatile Random Access Memory (NVRAM) 0FH Direct Memory Access (DMA) 10H Programmable Option Select (POS) 16H Keyboard security All other DeviceID values are reserved. RelativeLIDNum either the first available LID for the device (value 0) or a particular LID for the device (nonzero values). The range of LID values for each device type depends on how many devices of that type are available in the system. DeviceState whether the device type is shared among drivers (value 1 for DMA and POS device types) or whether each driver is associated with an exclusive LID entry for the device type (value zero for all non-DMA and non-POS device types). DEVHLP_GETLIDENTRY the function code; its value is 34H. Return Value The carry (C) flag is cleared and the ax register contains the LID number associated with the device driver if the routine is successful. Otherwise, the C flag is set and the ax register may have one of the following error values: ■ Not your LID. ■ LID does not exist. ■ ABIOS not present. Comments This routine associates an available LID with a device driver when it initializes at system boot. An available LID is "awake" in the system and not already claimed for the exclusive use of another device driver. The device driver can use this routine in two different ways: ■ One way is for the driver to specify a particular relative logical ID for the device type specified. Because the ordering of LIDs corresponds to the ordering of the physical devices, the device driver can determine if the specified LID entry is available. For example, a character device driver that supports com4 would specify 04 for the parameter RelativeLIDNum in order to get the LID entry for the fourth com port if it is available or to get a message if it isn't. ■ The other way is for the driver to request the first available logical ID for the specified device type. For example, a block device driver for diskettes would specify zero for the parameter Relative LIDNum in order to get the first available LID entry for the DeviceID value 01. In either case, GetLIDEntry will search the Advanced BIOS Common Data Area table for an entry corresponding to the specified RelativeLIDNum value and return the LID if an entry is available. The routine returns an error if no entry is available or if the specified LID is nonsharable and associated with a previously initialized device driver. The DMA and POS device types are shared among device drivers. For these DeviceID values, GetLIDEntry will allow multiple device drivers to access the LID concurrently. It is up to each device driver to determine whether the device is available for use when necessary. GetLIDEntry must be called with DeviceState set to obtain an LID for DMA and POS devices. For all other DeviceID specifications, DeviceState must be zero. When GetLIDEntry is called, the ds register must point to the device driver's low-memory data segment. The low-memory data segment is the first-linked segment that contains the device header. If the driver has already called the PhysToVirt routine with ds, this register must be reset to the driver's low-memory data segment. See Also ABIOSCall, ABIOSCommonEntry, FreeLIDEntry, PhysToVirt █ Lock ──────────────────────────────────────────────────────────────────────────── MOV AX,MemSeg@ ; selector or segment MOV BH,TypeLock ; duration (bit 0) of lock: ; 0 = short-term, 1 = long-term ; memory location (bit 1) of lock: ; 0 = any location, 1 = high memory ; type (bit 2) of lock: ; 0 = fixed, 1 = verify MOV BL,WaitFlag ; wait or return: ; 0 = block until locked, ; 1 = return if MemSeg not available MOV DL,DEVHLP_LOCK ; DEVHLP_LOCK EQU 13H CALL [Device_Help] The Lock routine guarantees that access to a memory segment will not change. Parameters MemSeg@ the selector or segment value for the segment to be locked. TypeLock where (bit 1) the segment should be located and the duration (bit 0) and type (bit 2) of the lock. This parameter may have one of the following values: Value Meaning ──────────────────────────────────────────────────────────────────────────── 00 Any memory location for a short-term, fixed lock: mark the segment as fixed at its current physical address. 01 Any memory location for a long-term, fixed lock: mark the segment as fixed, but it can be moved into the system's fixed-segment region and given a new physical address. 03 High memory location for a long-term, fixed, and irreversible lock: mark the segment as fixed when the device driver initializes, move it into the system's high-memory, fixed-segment region until a reboot occurs, and do not return a lock handle for this segment. This specification is valid only in a device driver's initialization routine and only if the MemSeg@ value is the selector of a segment in the driver's load image. 04 Any memory location for a short-term, verify lock: mark the segment as swappable but neither shrinkable nor freeable until the lock is removed explicitly. Access to the segment remains valid even after the driver blocks. WaitFlag whether to block until the segment has been locked. This parameter may be one of the following values: Value Meaning ──────────────────────────────────────────────────────────────────────────── 0 Wait (block) until memory segment is locked. 1 Return immediately if memory segment is not available. DEVHLP_LOCK the function code; its value is 13H. Return Value The carry (C) flag is cleared if the routine is successful, and the ax:bx register pair contains the lock handle for reversible locks. Otherwise, the C flag is set if the segment is unavailable or the handle is invalid. Comments For TypeLock values 00 and 01, this routine locks a segment in memory at task time so a device driver can use physical addresses to access the segment at interrupt time. A driver must specify whether Lock should return immediately if the segment is not available (there is not enough memory or the segment is swapped out). Lock does not block on a long-term lock request if it cannot lock the segment specified. The routine returns immediately with the C flag set, even if the WaitFlag was clear for a long-term lock request that fails. For the TypeLock value 04, this routine guarantees access to the segment. Calling Lock with TypeLock value 04 does not make the segment present, and it can be swapped out, but it cannot be resized or freed. MS OS/2 guarantees valid access to this segment until the driver calls Unlock to release the verify lock. Use a long-term lock (TypeLock value 01 or 03) in the following circumstances: ■ An operation on a locked segment could last more than two seconds. ■ The routine that calls Lock might not call Unlock before it returns to its caller. Using short-term locks for longer than two seconds might hang the system. For any segment with a short-term lock (TypeLock values 00 and 04), call Unlock before two seconds elapse or before the driver returns control to its caller, whichever comes first. If a fixed-memory operation will take more than two seconds, call Lock with a TypeLock specification of 01. Then, the system can (but might not) move the segment into a region it reserves for fixed, protected-mode segments. If the call is successful, Lock returns a lock handle for the driver to use until it calls Unlock. A driver need not call Lock for segments that the MS OS/2 kernel has already locked. For example, any segment address passed to a device driver in a read/write request gives access to an already locked segment. However, addresses passed to a device driver via an IOCtl call should be verified after a task-time call to Lock. Call VerifyAccess in protected mode to confirm that the user process has correct access rights to the memory segment (call RealToProt before VerifyAccess, if necessary). If the segment must be fixed and present (TypeLock 00 or 01), call Lock and then call VerifyAccess. When the segment is locked and user access is verified, a device driver can call VirtToPhys to access the locked segment by its physical address. Such an access verification remains valid for the duration of the lock. During initialization, a device driver may request a permanent, locked segment in the system's reserved region for fixed, protected-mode segments. The device driver conserves low-memory space for real mode operations by using this type of lock. The Lock routine does not return a handle when the TypeLock value is 03, but the segment is guaranteed to be in high memory if the call succeeds. See Also Block, RealToProt, TCYield, Unlock, VerifyAccess, VirtToPhys, Yield █ LogEntry ──────────────────────────────────────────────────────────────────────────── MOV CX,FCode ; 0 = reserved, 1 = log data to buffer LES BX,DataPtr ; pointer to data MOV DL,DEVHLP_LOGENTRY ; DEVHLP_LOGENTRY EQU 3BH CALL [Device_Help] The LogEntry routine places data in the system's error-log buffer. Parameters FCode be 1, requesting that data be placed in the error-log buffer. DataPtr the virtual address of a buffer in the device driver's primary data segment. This buffer contains data to be placed in the system error-log buffer. DEVHLP_LOGENTRY the function code; its value is 3BH. Return Value LogEntry does not return a value. Comments A device driver may call this routine at interrupt, user, or task time. The es register must be set to the driver's primary data segment. The primary data segment is the driver's first-linked segment that contains the device header. A mode switch occurs when a device driver calls LogEntry in real mode. However, the driver always regains control in its calling mode. █ MonitorCreate ──────────────────────────────────────────────────────────────────────────── LES SI,FinalBuffer ; pointer to final buffer in chain PUSH CS POP DS MOV DI,OFFSET NotifyRtn ; pointer to notification routine MOV AX,MonHandle ; handle for this monitor chain: ; 0 = create chain, nonzero = remove chain MOV DL,DEVHLP_MONITORCREATE ; DEVHLP_MONITORCREATE EQU 1FH CALL ES:[Device_Help] The MonitorCreate routine either creates or destroys a monitor chain. The routine creates an initially empty chain of monitors with the device driver's buffer and notification entry point as the last element in the chain. The routine destroys an existing monitor chain after all monitor tasks registered with this chain have been deregistered. Parameters FinalBuffer the final buffer for the monitor chain. The device driver's data segment contains the final buffer; the buffer's first word contains the length in bytes of the buffer, including its first word. NotifyRtn the entry point of the notification routine. The driver's code segment contains the notification routine. MonHandle the monitor handle. This parameter may be either a zero or nonzero value with the following meanings: Value Meaning ──────────────────────────────────────────────────────────────────────────── 0 Create new monitor chain and return a handle for it. Nonzero Remove the monitor chain for the specified handle. DEVHLP_MONITORCREATE the function code; its value is 1FH. Return Value The carry (C) flag is cleared if the routine is successful, and the ax register contains the new monitor chain handle if MonHandle was zero. Otherwise, the C flag is set and the ax register has one of the following error values: ■ Not enough memory. ■ Monitor chain not empty. ■ Invalid monitor handle. Comments This routine creates or removes a monitor chain for a device that performs synchronous I/O. A monitor chain is a list of monitors, with a device driver's buffer address and code address as the last element in this list. At creation, a monitor chain is empty so that data written into the chain is placed immediately in the output buffer. The device driver may call MonitorCreate only at task time in protected mode, and it must call MonitorCreate before calling Register to add a monitor to the monitor chain. The device driver must call DeRegister for each monitor task associated with the chain before it calls MonitorCreate to remove the monitor chain. The MonWrite routine places data in a monitor chain. The MS OS/2 monitor dispatcher feeds the data through all registered monitors in the chain. It puts the resulting data, if any, into the device driver's monitor buffer and calls the driver's notification routine at task time in protected mode. An interrupt-time notification call occurs only if MonWrite is called at interrupt time and the monitor chain is empty. When the system monitor dispatcher places a data record in the driver's monitor buffer, it also does the following: ■ Fills the first word of the buffer with the length in bytes of the record. ■ Holds the address of the buffer in es:si. ■ Sets the ds register to the driver's data segment. ■ Calls the driver's notification routine in protected mode. The device driver must process the contents of the monitor buffer as quickly as possible and return control to the monitor dispatcher. Note that the driver's notification routine must save and restore es and si if it uses these registers. The driver can call MonitorCreate at initialization or at task time in response to a monitor task's DosMonOpen or DosMonReg request, but the driver must call MonitorCreate once to obtain a chain handle before it can call Register in order to add monitors to the chain. The driver should keep track of the monitors it registers with each monitor chain that it supports for a given process. When a monitor task calls DosMonClose, the driver must call DeRegister to remove every monitor associated with the process from the chain. However, the chain must have no monitors when the driver calls MonitorCreate to remove the chain itself. See Also DeRegister, DosMonClose, DosMonOpen, DosMonReg, MonFlush, MonWrite, Register █ MonFlush ──────────────────────────────────────────────────────────────────────────── MOV AX,MonHandle ; handle for chain ; returned by MonitorCreate MOV DL,DEVHLP_MONFLUSH ; DEVHLP_MONFLUSH EQU 23H CALL [Device_Help] The MonFlush routine removes all data from the specified monitor chain. Parameters MonHandle the monitor chain. DEVHLP_MONFLUSH the function code; its value is 23H. Return Value The carry (C) flag cleared if the routine is successful. Otherwise, the C flag is set and the ax register may have the following error value: ■ Invalid monitor handle. Comments This routine tells the system monitor dispatcher to place a monitor-flush record in the monitor chain. This record passes through every monitor in the chain, and every monitor should discard any current data to pass the monitor-flush record along. The system monitor dispatcher places no new data records into the chain of monitors until the monitor-flush record reaches the device driver's monitor chain buffer. A device driver may call MonFlush only at task time. Subsequent calls to MonWrite will fail (or block) until the flush completes. The MonFlush routine does not preserve the state of the interrupt flag. See Also MonitorCreate, MonWrite █ MonWrite ──────────────────────────────────────────────────────────────────────────── MOV SI,OFFSET DataRecord ; offset to data record ; in driver's DS segment MOV CX,Count ; count of bytes in data record MOV AX,MonHandle ; handle for chain ; returned by MonitorCreate MOV DH,WaitFlag ; for monitor dispatcher synchronization: ; 0 = wait, 1 = no wait required MOV DL,DEVHLP_MONWRITE ; DEVHLP_MONWRITE EQU 22H CALL [Device_Help] The MonWrite routine passes data records from a device driver to the chain of monitors for filtering. Parameters DataRecord the data record to be written into the driver's monitor buffer and passed to the next monitor in the chain. Count the size in bytes of the data record. The maximum size for a valid data record is two bytes less than the size of the device driver's monitor buffer. MonHandle the monitor chain. WaitFlag whether the routine should wait until the system monitor dispatcher performs synchronization. This parameter may be one of the following values: Value Meaning ──────────────────────────────────────────────────────────────────────────── 0 Wait until the monitor dispatcher performs synchronization (at task or user time). 1 No wait required (at task or interrupt time). DEVHLP_MONWRITE the function code; its value is 22H. Return Value The carry (C) flag is cleared if the routine is successful. Otherwise, the C flag is set and the ax register may have one of the following error values: ■ Invalid monitor handle. ■ Not enough memory. ■ Data record too large. Comments This routine transfers a single, complete data record to the monitor chain. The driver may call MonWrite at task time or interrupt time. The ds register must point to the driver's low-memory data segment when the call occurs. This low-memory data segment is the first-linked segment that contains the device header. If the driver has already called PhysToVirt with ds, this register must be reset before the call to MonWrite. The not-enough-memory error condition occurs when the MonWrite call is made and the buffer did not contain sufficient free space to receive the data. If this condition occurs at interrupt time, there is an overrun. If it occurs at task time, the process can block. An in-progress MonFlush call can also cause a not-enough-memory condition. Waiting until the MonFlush call has completed may correct this condition. The MonWrite routine does not preserve the state of the interrupt flag. See Also MonitorCreate, MonFlush, PhysToVirt █ PhysToGDTSelector ──────────────────────────────────────────────────────────────────────────── MOV AX,AddressHigh ; 32-bit physical address MOV BX,AddressLow MOV CX,Length ; length in bytes of segment MOV SI,Selector ; selector to be set up MOV DL,DEVHLP_PHYSTOGDTSELECTOR ; DEVHLP_PHYSTOGDTSELECTOR EQU 2EH CALL [Device_Help] The PhysToGDTSelector routine converts a 32-bit physical address into a GDT (global descriptor table) selector:offset pair. Parameters AddressHigh the high-order word of the 32-bit physical address. AddressLow the low-order word of the 32-bit physical address. Length the length in bytes of the data segment to be accessed. Selector a selector returned by AllocGDTSelector; the selector will index the GDT entry. DEVHLP_PHYSTOGDTSELECTOR the function code; its value is 2EH. Return Value The carry (C) flag is cleared if the routine is successful. Otherwise, the C flag is set and the ax register may have one of the following error values: ■ Invalid address. ■ Invalid selector. Comments This routine maps a physical address to one of the GDT selectors allocated by AllocGDTSelector when the device driver was intitialized. The driver can then fetch data through the returned GDT selector. PhysToGDTSelector creates selector:offset addressability for a 32-bit physical address. However, the returned GDT selector and offset does not represent a normal MS OS/2 memory segment: the selector cannot be passed in system calls. Instead, this selector represents a fabricated segment for private use by the device driver. Only the driver can use it to fetch data. Call the Lock routine before calling PhysToGDTSelector at task time if the memory being addressed is not a fixed memory area, such as ROM or video. The lock may be long-term or short-term. The selector returned by PhysToGDTSelector remains valid until the device driver calls Unlock or calls PhysToGDTSelector again for the same selector. See Also AllocGDTSelector, Lock, Unlock █ PhysToUVirt ──────────────────────────────────────────────────────────────────────────── MOV AX,AddressHigh ; 32-bit physical address MOV BX,AddressLow ; or selector if ReqType = 2 MOV CX,Length ; length of area (max 65535) ; with 0 = 65536 bytes MOV DH,ReqType ; type of request: ; 0 = get virtual & make seg ExecuteRead ; at application privilege level (IOPL=3) ; 1 = get virtual & make seg ReadWrite ; at application privilege level (IOPL=3) ; 2 = free virtual (protected mode only) ; 3 = get virtual & make seg ExecuteRead ; with protected I/O access (IOPL=2) ; 4 = get virtual & make seg ReadWrite ; with protected I/O access (IOPL=2) ; 5 = get virtual & make seg ReadWrite ; at application privilege level (IOPL=3) ; with associated TagType MOV SI,TagType ; if ReqType = 5: ; 0 = foreground-only PVB selector MOV DL,DEVHLP_PHYSTOUVIRT ; DEVHLP_PHYSTOUVIRT EQU 17H CALL [Device_Help] The PhysToUVirt routine converts a 32-bit physical address into a virtual address. It converts the physical address into a valid selector:offset that can be addressed from the current LDT (local descriptor table) in protected mode, or it converts the physical address into a valid segment:offset if the physical address is below one megabyte in real mode. The PhysToUVirt routine can also free a selector that was returned by a preceding call to this routine. Parameters AddressHigh the high word of the 32-bit physical address, or the selector if the ReqType value is 2. AddressLow the low word of the 32-bit physical address. This parameter is ignored if the ReqType value is 2. Length the size in bytes of the segment accessed by the physical address; it may any value in the range 0 to 65,535. If this parameter is 0, the routine uses 65,536 bytes. This parameter is ignored if the ReqType value is 2. ReqType the type of request. It may be one of the following values: Value Meaning ──────────────────────────────────────────────────────────────────────────── 0 Get virtual address, make segment er (executable-readable), and mark LDT selector with I/O privilege level 3 (application program IOPL, least protected, cannot access physical I/O ports directly under MS OS/2). 1 Get virtual address, make segment rw (readable-writable), and mark LDT selector with I/O privilege level 3 (application program IOPL, least protected, cannot access physical I/O ports directly under MS OS/2). 2 Free protected-mode virtual address (selector). 3 Get virtual address, make segment er, and mark LDT selector with I/O privilege level 2 (protected from accidental modification by any program with IOPL equal to 3, may access physical I/O ports directly under MS OS/2). 4 Get virtual address, make segment rw, and mark LDT selector with I/O privilege level 2 (protected from accidental modification by any program with IOPL equal to 3, may access physical I/O ports directly under MS OS/2). 5 Get virtual address, make segment rw, mark LDT selector with I/O privilege level 3 (application program IOPL, least protected) and check the associated TagType for what kind of special processing is required. TagType what kind of special processing the system should supply for a ReqType value 5. Currently, the TagType value must be 0, indicating a foreground-only PVB (physical video buffer) selector. DEVHLP_PHYSTOUVIRT the function code; its value is 17H. Return Value The carry (C) flag is cleared if the routine is successful, and the es:bx register pair contains the selector:offset or segment:offset virtual address for ReqType 0, 1, 3, 4, or 5. Otherwise, the C flag is set for an invalid address specification. Comments This routine is typically used to provide a caller of the device driver with addressability to a fixed memory area, such as ROM code or data. The device driver must know the physical address of the memory area in order to provide addressability to an application or to a dynamic-link-library routine. PhysToUVirt leaves its result in es:bx for every ReqType specification except 2. In protected mode, the routine returns a zero offset to bx and creates selector:offset LDT addressability for the 32-bit physical address. In real mode, the routine creates segment:offset addressability for the 32-bit physical address if it is below one megabyte. It is an error to call PhysToUVirt in real mode for an address above one megabyte. A selector or segment:offset returned by PhysToUVirt represents the virtual address of a fabricated segment for private use between the driver and a client process. The data within such a segment cannot be passed in system calls; it may be used only by the receiving application to retrieve data. With a ReqType value of 0 or 1, the driver can give an application process addressability to a fixed memory area, such as the BIOS-reserved range from 640K bytes to one megabyte or the device driver's primary data segment. With a ReqType value of 3 or 4, the driver can give a dynamic-link-library routine addressability to such a fixed memory area so that the routine can perform I/O. These ReqType specifications keep the area from being accessed by "runaway" applications. With a ReqType value of 5, the driver tags the selector as requiring special handling by the system. You must specify 0 for TagType if you specify 5 for ReqType. For all other values of ReqType, PhysToUVirt preserves the si register. However, subsequent versions of MS OS/2 might define additional values for TagType. PhysToUVirt frees a selector in the ax register for a ReqType value of 2 (protected mode only). It ignores the specifications for AddressLow (assumed to be zero) in bx and for Length in cx. When the ReqType value is 2, this routine releases a virtual address that was returned by a preceding PhysToUVirt call. See Also PhysToVirt, UnPhysToVirt █ PhysToVirt ──────────────────────────────────────────────────────────────────────────── MOV BX,AddressLow ; lower 16 bits of physical address MOV AX,AddressHigh ; upper 16 bits of physical address MOV CX,Length ; length of segment in bytes MOV DH,Result ; leave result: ; 0 = in DS:SI, 1 = in ES:DI MOV DL,DEVHLP_PHYSTOVIRT ; DEVHLP_PHYSTOVIRT EQU 15H CALL [Device_Help] The PhysToVirt routine converts a 32-bit physical address into a virtual address, a selector:offset in protected mode or a segment:offset in real mode. When PhysToVirt is called in real mode and the physical address is above one megabyte, a mode switch occurs. Parameters AddressLow the low word of the 32-bit physical address. AddressHigh the high word of the 32-bit physical address. Length the size in bytes of the memory location (buffer) accessed by the physical address. Result where the converted-to-virtual address should be be returned. This parameter may be one of the following values: Value Meaning ──────────────────────────────────────────────────────────────────────────── 0 Return result in ds:si register pair. 1 Return result in es:di register pair. DEVHLP_PHYSTOVIRT the function code; its value is 15H. Return Value The carry (C) flag is cleared and the ds:si or es:di register pair receives a valid virtual address if the routine is successful. Otherwise, the C flag is set if the address was invalid. For a successful call, the zero (Z) flag is cleared if the operating mode is unchanged. The Z flag is set if a mode switch occurred, and previously stored addresses must be recalculated. Comments This routine provides addressability to data for bimodal operations performed during task time and interrupt time. At task time, the driver calls PhysToVirt to perform mode-dependent addressing, relieving it of the need to recognize the CPU mode and the consequent effects on accessing memory. However, this routine is essential when the device driver must access a memory location at both task and interrupt times. The interrupt handler of a bimodal device driver must be able to address data regardless of the context of the current process. The current LDT (local descriptor table) will not necessarily address the data space that the interrupt handler needs to access. The ds register must point to the segment containing the device driver's header when the driver calls PhysToVirt for the first time and whenever it calls PhysToVirt for the first time after a call to UnPhysToVirt. If a driver routine is in real mode when it calls PhysToVirt, a mode switch occurs if the physical-address parameter is above one megabyte. The routine can make multiple calls to PhysToVirt, but it must call the companion routine UnPhysToVirt once before the routine exits. PhysToVirt preserves the state of the cs, ss, and sp registers and preserves the state of ds when results are in es:di or of es when results are in ds:si, provided that no mode switch occurs. Depending on the value of Result and whether a mode switch occurs, PhysToVirt returns the following: Value PhysToVirt effect on registers: ──────────────────────────────────────────────────────────────────────────── 0 The ds:si register pair contains the valid virtual address. The cs, ss, sp, and es registers are preserved if no mode switch occurred. Otherwise, the cs and ss addresses are converted to protected mode, the sp address is preserved, and the es address is converted only if it accessed the device driver's primary data segment when the driver first calls PhysToVirt. 1 The es:di register pair contains the valid virtual address. The cs, ss, sp, and ds registers are preserved if no mode switch occurred. Otherwise, the cs and ss addresses are converted to protected mode, the sp address is preserved, and the ds address is converted only if it accesses the device driver's primary data segment. Note that all real-mode addresses that PhysToVirt returned are no longer valid if a subsequent call causes a mode switch. Such addresses must be converted to protected mode by calls to PhysToVirt. Note also that previously stored address pointers that contain the real-mode ds value of the driver's data segment must be converted to protected mode before use. Check the Z flag to determine whether PhysToVirt caused a switch to protected mode. Then call PhysToVirt to convert each necessary address into a selector:offset. Converted addresses are valid as long as the device driver retains control of the CPU; calls to Block, TCYield, and Yield, and execution of the ret instruction invalidate the addresses supplied by PhysToVirt. An interrupt handler can use these addresses with interrupts enabled until it calls EOI. If the handler will use PhysToVirt addresses after the EOI, it must disable interrupts before calling EOI to keep these addresses valid. For performance reasons, a device driver routine can optimize its use of PhysToVirt calls as follows: ■ If the ds register does not point to the driver's primary data segment (containing the device header), reset it to this segment. ■ Choose an address that is most likely to cause a mode switch and specify Result as 1 for the first call to PhysToVirt. If the call is successful, results are in es:di. If a mode switch occurred, the Z flag is set and the ds segment value for the driver's primary data segment has been converted to a protected-mode selector. ■ While the pointer returned by PhysToVirt is in use, do not enable interrupts, change the returned es or ds value, save the returned es or ds values on the stack and restore them, or call another DevHlp routine. The returned pointer may be saved in the driver's data segment before another call to PhysToVirt. The driver can make multiple calls to PhysToVirt. ■ Call UnPhysToVirt to release all the addresses returned by calls to PhysToVirt before returning control. Because PhysToVirt leaves its results in es:di or ds:si, the driver can move strings from buffer to buffer in either direction, without having to convert real-mode addresses if the first PhysToVirt call switched modes. See Also Block, EOI, PhysToUVirt, TCYield, UnPhysToVirt, Yield █ ProtToReal ──────────────────────────────────────────────────────────────────────────── MOV DL,DEVHLP_PROTTOREAL ; DEVHLP_PROTTOREAL EQU 30H CALL [Device_Help] The ProtToReal routine changes the operating mode from protected to real for an interrupt handler. Parameters DEVHLP_PROTTOREAL the function code; its value is 30H. Return Value The carry (C) flag is cleared if the routine is successful. Otherwise, the C flag is set and the operating mode has not changed to real mode. Note that the C flag is set for a real mode call of ProtToReal, and the ax register has the following error value: ■ Stack in high memory. Comments This routine changes the operating mode from protected to real at interrupt time so that the device driver can service a device interrupt. On entry, the ds register should be set to the device driver's low-memory data segment. ProtToReal does not preserve the contents of the es register. When it has finished servicing the device, the interrupt handler must restore the original operating mode before relinquishing control. Example The following example shows how to determine whether the processor must be switched from protected mode to real mode and back by checking the machine status word (MSW): SMSW AX ; get current MSW PUSH AX ; save original MSW RCR AX,1 ; shift Protect Enabled bit into Carry Flag JNC RM1 ; jump if already in real mode MOV DL,DEVHLP_PROTTOREAL ; DEVHLP_PROTTOREAL EQU 30H CALL [Device_Help] ; if in protected mode RM1: ; process in real mode . . POP AX ; retrieve original MSW RCR AX,1 ; shift PE bit into CF JNC RM2 ; jump if originally in real mode MOV DL,DEVHLP_REALTOPROT CALL [Device_Help] ; switch back to protected mode RM2: . . See Also RealToProt █ PullParticular ──────────────────────────────────────────────────────────────────────────── MOV SI,OFFSET Queue ; offset to queue header that ; points to next request LES BX,ReqPacket ; pointer to request packet ; to be pulled from queue MOV DL,DEVHLP_PULLPARTICULAR ; DEVHLP_PULLPARTICULAR EQU 0BH CALL [Device_Help] The PullParticular routine pulls the specified request packet from the specified queue. Parameters Queue the queue header in the device driver's data segment (accessed by ds). The queue header points to the next request for the device to service. ReqPacket to the request packet to be removed from the queue. DEVHLP_PULLPARTICULAR the function code; its value is 0BH. Return Value The carry (C) flag is cleared if the routine is successful. Otherwise, the C flag is set if the specified request packet is not found. Comments This routine removes the specified request packet when this packet is not necessarily the first element in the request queue. The first element can be removed by a call to PullReqPacket. See Also AllocReqPacket, PullReqPacket, PushReqPacket █ PullReqPacket ──────────────────────────────────────────────────────────────────────────── MOV SI,OFFSET Queue ; offset to queue header that ; points to next request MOV DL,DEVHLP_PULLREQUEST ; DEVHLP_PULLREQUEST EQU 0AH CALL [Device_Help] The PullReqPacket routine pulls the next request packet waiting for device service in the specified queue. Parameters Queue the queue header in the device driver's data segment (accessed by ds). The queue header points to the next request for the device to service. DEVHLP_PULLREQUEST the function code; its value is 0AH. Return Value The carry (C) flag is cleared and the es:bx register pair contains the address of the first request packet in the queue if the routine is successful. Otherwise, the C flag is set if the queue is empty. Comments This routine removes the next request packet from the request list for device service. The device driver uses the PushReqPacket and PullReqPacket routines to maintain a request queue for each device it supports. See Also AllocReqPacket, FreeReqPacket, PullParticular, PushReqPacket, SortReqPacket █ PushReqPacket ──────────────────────────────────────────────────────────────────────────── MOV SI,OFFSET Queue ; offset to queue header that ; points to next request LES BX,ReqPacket ; pointer to request packet that ; goes into the queue MOV DL,DEVHLP_PUSHREQUEST ; DEVHLP_PUSHREQUEST EQU 09H CALL [Device_Help] The PushReqPacket routine adds the specified device request packet to the list of packets waiting for device service. Parameters Queue the queue header in the device driver's data segment (accessed by ds). The queue header points to the next request for the device to service. ReqPacket to the request packet to be added to the list. DEVHLP_PUSHREQUEST the function code; its value is 09. Return Value PushReqPacket does not return a value. Comments This routine places request packets allocated by AllocReqPacket into the request queue for device service. The device driver task-time thread adds all incoming read/write requests to its request list. This thread then determines whether the interrupt-time thread is active. If not, it sends the request to the device. Since the device may be active at this point, the task-time thread must turn off interrupts before calling the device. Otherwise, a window exists in which the device finishes before the request packet is put on the list. See Also AllocReqPacket, PullParticular, PullReqPacket, SortReqPacket █ QueueFlush ──────────────────────────────────────────────────────────────────────────── MOV BX,OFFSET ChQueue ; offset to character buffer MOV DL,DEVHLP_QUEUEFLUSH ; DEVHLP_QUEUEFLUSH EQU 10H CALL [Device_Help] The QueueFlush routine clears the specified character-queue buffer. Parameters ChQueue the character-queue buffer in the device driver's data segment (accessed by ds). DEVHLP_QUEUEFLUSH the function code; its value is 10H. Return Value QueueFlush does not return a value. Comments This routine empties the character-queue buffer. The buffer must have been initialized by QueueInit before the call to QueueFlush. See Also QueueInit, QueueRead, QueueWrite █ QueueInit ──────────────────────────────────────────────────────────────────────────── MOV BX,OFFSET ChQueue ; offset to character buffer ; to be initialized with ; QSize field already set up MOV DL,DEVHLP_QUEUEINIT ; DEVHLP_QUEUEINIT EQU 0FH CALL [Device_Help] The QueueInit routine initializes the specified character-queue buffer. Parameters ChQueue the character-queue buffer whose structure is defined as follows: CharQueue STRUC QSize DW ? ; size of queue in bytes QChrOut DW ? ; index of next char out QCount DW ? ; count of chars in queue QBase DB ? ; start of queue buffer CharQueue ENDS The buffer resides in the device driver's low-memory data segment (accessed by ds). The QSize field of the character buffer must be initialized before the call to QueueInit. DEVHLP_QUEUEINIT the function code; its value is 0FH. Return Value QueueInit does not return a value. Comments This routine initializes a simple circular buffer of characters for a device driver. The driver does the following: ■ Defines the buffer structure. ■ Allocates one or more character-queue buffers. ■ Initializes the QSize field for each buffer. ■ Calls QueueInit for each buffer before calling other character-queue routines that operate on the buffer. The routines QueueWrite, QueueRead, and QueueFlush operate on the uninitialized fields of the structure. The driver can ignore these fields. Note that the driver always has addressability to its low-memory data segment (accessed by ds), so a character-queue buffer is accessible in both protected and real modes. See Also QueueFlush, QueueRead, QueueWrite █ QueueRead ──────────────────────────────────────────────────────────────────────────── MOV BX,OFFSET ChQueue ; offset to character buffer MOV DL,DEVHLP_QUEUEREAD ; DEVHLP_QUEUEREAD EQU 12H CALL [Device_Help] The QueueRead routine removes a character from the beginning of the specified character-queue buffer. Parameters ChQueue the character-queue buffer in the device driver's data segment (accessed by ds). DEVHLP_QUEUEREAD the function code; its value is 12H. Return Value The carry (C) flag is cleared and the al register contains the character removed from the queue if the routine is successful. Otherwise, the C flag is set if the queue is empty. Comments This routine removes a character from a character device driver's data buffer. The buffer must have been initialized by QueueInit before the call to QueueRead, but the buffer remains empty until a character is inserted by QueueWrite. See Also QueueFlush, QueueInit, QueueWrite █ QueueWrite ──────────────────────────────────────────────────────────────────────────── MOV BX,OFFSET ChQueue ; offset to character buffer MOV AL,Character ; character to insert into queue MOV DL,DEVHLP_QUEUEWRITE ; DEVHLP_QUEUEWRITE EQU 11H CALL [Device_Help] The QueueWrite routine inserts a character at the end of the specified character-queue buffer. Parameters ChQueue the character-queue buffer in the device driver's data segment (accessed by ds). Character the character to be inserted at the end of the queue. DEVHLP_QUEUEWRITE the function code; its value is 11H. Return Value The carry (C) flag is cleared if the routine is successful. Otherwise, the C flag is set if the queue is full. Comments This routine adds a character to the device driver's data buffer. The buffer must have been initialized by QueueInit before the call to QueueWrite. See Also QueueFlush, QueueInit, QueueRead █ RealToProt ──────────────────────────────────────────────────────────────────────────── MOV DL,DEVHLP_REALTOPROT ; DEVHLP_REALTOPROT EQU 2FH CALL [Device_Help] The RealToProt routine changes the operating mode from real to protected for an interrupt handler. Parameters DEVHLP_REALTOPROT the function code; its value is 2FH. Return Value The carry (C) flag is cleared if the routine is successful. Otherwise, the C flag is set and the operating mode has not changed to protected mode. Note that the C flag is set for a protected-mode call of RealToProt. Comments This routine changes the operating mode from real to protected at interrupt time so that the device driver can service a device interrupt. On entry, the ds register should be set to the device driver's data segment. RealToProt does not preserve the contents of the es register. When it has serviced the device, the interrupt handler must restore the original operating mode before relinquishing control. Example The following example shows how to determine whether the processor must be switched from protected mode to real mode and back by checking the machine status word (MSW): SMSW AX ; get current MSW PUSH AX ; save original MSW RCR AX,1 ; shift Protect Enabled bit into Carry Flag JC PM1 ; jump if already in protected mode MOV DL,DEVHLP_REALTOPROT ; DEVHLP_REALTOPROT EQU 2FH CALL [Device_Help] ; if in real mode PM1: ; process in protected mode . . POP AX ; retrieve original MSW RCR AX,1 ; shift PE bit into CF JC PM2 ; jump if originally in protected mode MOV DL,DEVHLP_PROTTOREAL CALL [Device_Help] ; switch back to real mode PM2: . . See Also ProtToReal █ Register ──────────────────────────────────────────────────────────────────────────── LES SI,InBuff ; pointer to input buffer MOV DI,OutBuffOffset ; offset of output buffer MOV CX,MonitorPID ; Process ID of monitor task MOV AX,MonHandle ; handle for chain ; returned by MonitorCreate MOV DH,PlacementFlag ; high or low place in chain MOV DL,DEVHLP_REGISTER ; DEVHLP_REGISTER EQU 20H CALL [Device_Help] The Register routine adds a monitor to a chain of monitors that the device driver supports. Parameters InBuff to the input buffer. The monitor task's DosMonReg request supplied this value in the IOCtl request packet. OutBuffOffset the offset to the output buffer. The monitor task's request also supplied this value. MonitorPID the process identifier of the monitor task. The driver called GetDosVar to get LocINFOSeg access and obtained this value from the current LDT (local descriptor table). MonHandle the monitor chain. The device driver called MonitorCreate to obtain this value. PlacementFlag where to place the monitor in the chain. The monitor task's request also supplied this value. DEVHLP_REGISTER the function code; its value is 20H. Return Value The carry (C) flag is cleared if the routine is successful. Otherwise, the C flag is set and the ax register may have one of the following error values: ■ Invalid monitor handle. ■ Not enough memory. ■ Monitor buffer too small. Comments This routine adds a monitor to a monitor chain whose last element is two addresses: the device driver's monitor buffer and notification routine. The driver may call Register only at task time in protected mode. A monitor task supplies a pointer to its input buffer, its output buffer offset, and a placement flag when it calls DosMonReg to request monitor registration. Each buffer's first word must contain the length in bytes of the supplied buffer. A monitor's input and output buffers must be at least twenty bytes greater than the length of the device driver's monitor buffer. MS OS/2 forwards a monitor task's registration request to the appropriate device driver. The device driver supplies the monitor-chain handle returned by MonitorCreate and the process identifier (PID) of the requesting monitor task when it calls Register. The driver determines the PID of the requesting monitor task by calling GetDosVar for access to the LocINFOSeg (current LDT). Note that a process may make more than one monitor-registration request, supplying different input- and output-buffer parameters in each request forwarded to the driver by the system monitor dispatcher. A process may also register different monitors in different monitor chains. The device driver should keep track of the monitors registered for each monitor chain it supports. When a monitor task calls DosMonClose, the driver must call DeRegister to remove the task's monitors from the chain. A chain must be empty when the device driver calls MonitorCreate to remove the chain itself. See Also DeRegister, GetDosVar, MonCreate, MonFlush, MonWrite █ RegisterStackUsage ──────────────────────────────────────────────────────────────────────────── MOV BX,OFFSET StackUse ; offset in DS data segment MOV DL,DEVHLP_REGISTERSTACKUSAGE ; DEVHLP_REGISTERSTACKUSAGE EQU 3AH CALL [Device_Help] The RegisterStackUsage routine tells the system interrupt manager the device driver's expected stack requirements when it initializes. Parameters StackUse the driver's expected interrupt stack usage as structured data, defined as follows: StackUsage STRUC SU_cbStruc DW 14 SU_Flags DW ? SU_iIRQ DW ? SU_cbStackCLI DW ? SU_cbStackSTI DW ? SU_cbStackEOI DW ? SU_cNest DW ? StackUsage ENDS The StackUse fields specify the following: Field Specifies ──────────────────────────────────────────────────────────────────────────── SU_cbStruc Number of bytes in structure, including this field. SU_Flags Value 0001H if the interrupt handler enables interrupts; otherwise, 0000H (reserved). SU_iIRQ IRQ level (0-0FH) for the interrupt handler described by the next three fields: SU_cbStackCLI Number of stack bytes that the interrupt handler uses when interrupts are disabled. SU_cbStackSTI Number of stack bytes that the interrupt handler uses after it enables interrupts. SU_cbStackEOI Number of stack bytes used after the interrupt handler calls the EOI routine. SU_cNest Maximum number of levels that the driver expects interrupt routines to nest. DEVHLP_REGISTERSTACKUSAGE the function code; its value is 3AH. Return Value The carry (C) flag is cleared if the routine is successful. Otherwise, the C flag is set if the stack usage exceeds the system maximum (8K for the interrupt stack). Comments This routine registers a device driver's interrupt stack requirements with the system interrupt manager when the driver initializes. The maximum interrupt stack is 8K, so the driver must call UnSetIRQ if its stack usage specification exceeds the system maximum. If the device driver services multiple IRQs, it must call RegisterStackUsage for each IRQ it handles. If the driver underestimates the maximum number of levels that its interrupt routines nest, the system interrupt manager disables the IRQ at the PIC (programmable interrupt controller) until a reboot occurs. See Also EOI, SetIRQ, UnSetIRQ █ ResetTimer ──────────────────────────────────────────────────────────────────────────── MOV AX,OFFSET CS:TimerHandler ; offset to driver's timer handler MOV DL,DEVHLP_RESETTIMER ; DEVHLP_RESETTIMER EQU 1EH CALL [Device_Help] The ResetTimer routine releases a device driver's registered timer handler. The routine removes the specified timer handler from the list of timer handlers to be called on a tick count. Parameters TimerHandler the offset in the driver's code segment to the timer handler. DEVHLP_RESETTIMER the function code; its value is 1EH. Return Value The carry (C) flag is cleared if the routine is successful. Otherwise, the C flag is set if the specified TimerHandler address is not found in the list of registered timer handlers. Comments This routine removes a timer handler from the system list of registered timer handlers when a device driver does not need it. The driver may call SetTimer or TickCount to reregister the timer handler when it needs the handler again. MS OS/2 timer handlers are analogous to the user timer interrupt (INT 1CH). The ds register must point to the device driver's low-memory data segment when the driver calls ResetTimer. This low-memory data segment is the first-linked segment that contains the device header. If the driver has already called PhysToVirt with ds, this register must be reset before the call to ResetTimer. See Also PhysToVirt, SetTimer, TickCount █ ROMCritSection ──────────────────────────────────────────────────────────────────────────── MOV AL,EnterOrExit ; critical section flag: ; 0 = exit, nonzero = enter MOV DL,DEVHLP_ROMCRITSECTION ; DEVHLP_ROMCRITSECTION EQU 26H CALL [Device_Help] The ROMCritSection routine flags a critical section of execution in the ROM BIOS to prevent the real-mode session from being suspended in the background. Device drivers' ROM BIOS compatibility handlers call this routine. Parameters EnterOrExit a critical-section flag with one of the following values: Value Meaning ──────────────────────────────────────────────────────────────────────────── 0 Exit critical section. Nonzero Enter critical section. DEVHLP_ROMCRITSECTION the function code; its value is 26H. Return Value ROMCritSection does not return a value. Comments This routine protects a critical section of execution in the ROM BIOS. Certain sections of ROM BIOS code must be protected from the preemption that would occur if a user starts a protected-mode application, causing the real-mode session to be suspended in the background. Some real-mode I/O processing should never be suspended, in particular, the printer (BIOS INT 17H), disk (BIOS INT 13H), and screen (BIOS INT 10H). The device driver must intercept the appropriate ROM BIOS interrupt and call ROMCritSection to protect the ROM BIOS critical section of execution. ──────────────────────────────────────────────────────────────────────────── Warning When the driver's interrupt handler calls ROMCritSection to enter a critical section, the foreground real-mode session will remain in the foreground. This can cause problems for the user. ──────────────────────────────────────────────────────────────────────────── For example, if a real-mode terminate-and-stay-resident (TSR) program takes control while the CPU is executing the ROM BIOS, time spent in the critical section will be longer and the user will be unable to switch screens. The worst case occurs when the TSR program is interactive, thus preventing the interrupt handler from calling ROMCritSection in order to exit. Under these conditions, the user cannot switch screens until the TSR program ends. See Also SetROMVector █ Run ──────────────────────────────────────────────────────────────────────────── MOV BX,EventIDLow ; low word of event ID MOV AX,EventIDHigh ; high word of event ID MOV DL,DEVHLP_PROCRUN ; DEVHLP_PROCRUN EQU 05H CALL [Device_Help] The Run routine releases a thread that was suspended by a call to Block. Parameters EventIDLow the low word of the event identifier. EventIDHigh the high word of the event identifier. DEVHLP_PROCRUN the function code; its value is 05. Return Value The ax register contains a count of the threads released by Run. If none were released, the zero (Z) flag is cleared. Otherwise, the Z flag is set. Comments This routine awakens all threads that were blocked for the specified event identifier and returns immediately to its caller, usually an interrupt handler. Run is the companion routine to Block. MS OS/2 puts the awakened threads into the run queue to be executed at the next available opportunity. See Also Block █ SchedClockAddr ──────────────────────────────────────────────────────────────────────────── MOV AX,OFFSET PtrSave ; offset to DWORD in driver's DS data segment MOV DL,DEVHLP_SCHEDCLOCK ; DEVHLP_SCHEDCLOCK EQU 00H CALL [Device_Help] The SchedClockAddr routine returns an indirect pointer to the address of the MS OS/2 clock-tick handler, SchedClock, for a clock device driver to use. The clock driver must call SchedClock on each occurrence of a periodic clock tick. Parameters PtrSave the offset to a dword allocated in the clock driver's low-memory data segment (accessed by ds). DEVHLP_SCHEDCLOCK the function code; its value is 00. Return Value The PtrSave location contains an indirect bimodal pointer to the system tick handler SchedClock. Comments The SchedClockAddr routine is called during a clock device driver's initialization. The driver must do the following: ■ Before it calls SchedClockAddr, allocate a dword PtrSave area in its first-linked segment that contains the device header. ■ When it calls SchedClockAddr, ensure that the ds register points to this data segment and supply the offset to the PtrSave area. The SchedClockAddr routine then fills the PtrSave area with a bimodal pointer to a dword in system memory that contains the pointer to the SchedClock routine. Because the returned pointer is bimodal, the clock driver need not perform conversions for protected- and real-mode operations with this pointer. The driver uses the PtrSave pointer to call the SchedClock routine. The driver's interrupt handler must call SchedClock for each periodic clock tick in order to indicate the passage of system time. The handler makes the call as follows: MOV AL,Millisecs ; milliseconds since last call MOV DH,EOIFlag ; this tick relative to EOI: ; 0 = before EOI, 1 = after EOI CALL [PtrSaveValue] ; pointer returned by SchedClockAddr ; to system pointer to SchedClock routine Note that the driver's interrupt handler must use the pointer returned by SchedClockAddr to make a far indirect call to the system's SchedClock routine. The clock driver's interrupt handler must run with interrupts enabled before it calls EOI for the timer interrupt. The handler must also do any critical processing, such as updating the fraction-of-seconds count, before it calls the SchedClock routine. SchedClock disperses the tick to appropriate components of the system prior to dismissal of the interrupt. When SchedClock returns, the clock driver must call EOI and then call SchedClock again. Note that the device driver's interrupt handler can be reentered after the EOI call. The system's SchedClock routine is also reentrant. See Also EOI █ SemClear ──────────────────────────────────────────────────────────────────────────── MOV BX,SemHandleLow ; system or RAM semaphore handle MOV AX,SemHandleHigh MOV DL,DEVHLP_SEMCLEAR ; DEVHLP_SEMCLEAR EQU 07H CALL [Device_Help] The SemClear routine releases ownership of a semaphore and restarts any blocked threads waiting on the semaphore. Parameters SemHandleLow the low word of the semaphore handle. SemHandleHigh the high word of the semaphore handle. DEVHLP_SEMCLEAR the function code; its value is 07. Return Value The carry (C) flag is cleared if the routine is successful. Otherwise, the C flag is set and the ax register may have one of the following error values: ■ Invalid handle. ■ Exclusive semaphore already owned. ■ Invalid at interrupt time. ■ Protection violation. Comments This routine releases the ownership of a semaphore that was claimed by a call to SemRequest. A device driver may clear either a RAM semaphore in a user, task, or interrupt routine or a system semaphore in a task or interrupt routine. For a system semaphore, the original handle was passed to the device driver by an application via an IOCtl routine. However, the driver must pass a valid system semaphore handle to SemClear. Before calling SemClear, the driver must have marked the handle as "in use" with a SemHandle call, claimed the semaphore with a SemRequest call, and marked the handle as no longer "in use" with another SemHandle call. For a RAM semaphore, the handle is the virtual address of the dword that the driver allocated for the semaphore, usually in the driver's low-memory data segment (containing the device header). This virtual address is a selector:offset in protected mode or a segment:offset in real mode. If the device driver calls SemClear for the RAM semaphore at interrupt time, the semaphore must be in the device driver's low-memory data segment so that it is directly addressable. See Also SemHandle, SemRequest █ SemHandle ──────────────────────────────────────────────────────────────────────────── MOV BX,SemHandleLow ; application semaphore identifier MOV AX,SemHandleHigh ; passed to device driver MOV DH,UsageFlag ; mark driver's usage: ; 0 = not in use, 1 = in use MOV DL,DEVHLP_SEMHANDLE ; DEVHLP_SEMHANDLE EQU 08H CALL [Device_Help] The SemHandle routine converts an application's task-specific semaphore handle, passed in an IOCtl call to a device driver, into a system semaphore handle for the driver to use; the routine later marks the system semaphore as no longer "in use" by the driver. SemHandle returns a RAM semaphore handle unchanged. Parameters SemHandleLow the low word of the semaphore handle. SemHandleHigh the high word of the semaphore handle. UsageFlag whether to mark the semaphore as "in use" by the driver. This parameter may be one of the following values: Value Meaning ──────────────────────────────────────────────────────────────────────────── 0 Not in use (no longer needed by the driver). 1 In use by the driver. DEVHLP_SEMHANDLE the function code; its value is 08. Return Value The carry (C) flag is cleared and the ax:bx register pair is set to the system handle for the semaphore if the routine is successful and the UsageFlag is equal to 1. Otherwise, the C flag is set if the semaphore handle is invalid. Comments This routine maps an application's task-specific semaphore handle to a system-specific semaphore handle that the device driver can use at interrupt time. At task time, the driver can also use the system handle returned by SemHandle safely. If the driver used the application's task-specific semaphore handle, the application could delete the semaphore while the driver was using it. The device driver calls SemHandle once at task time to mark the system-specific semaphore as "in use" and again at task or interrupt time to mark the semaphore as "not in use." For each in-use call to SemHandle, there must be a corresponding not-in-use call to indicate that the driver has finished with the system semaphore. A driver can call SemHandle for a RAM semaphore, but the routine merely returns the original handle, a virtual address value. If the semaphore handle returned by SemHandle is changed by the routine, it is a system semaphore. However, the device driver should call VerifyAccess with the TypeOfAccess parameter set for read/write before assuming that the returned handle is a RAM semaphore when the C flag is set by a SemHandle call. A RAM semaphore handle must be accessed only at task time unless it is in locked memory. The SemHandle routine does not preserve the state of the interrupt flag. See Also Lock, SemClear, SemRequest, VerifyAccess █ SemRequest ──────────────────────────────────────────────────────────────────────────── MOV BX,SemHandleLow ; system or RAM semaphore handle MOV AX,SemHandleHigh MOV CX,SemTimeoutLow ; time-out value: MOV DI,SemTimeoutHigh ; 0 = no wait if semaphore owned ; -1 = wait forever ; > 0 = time-out in milliseconds MOV DL,DEVHLP_SEMREQUEST ; DEVHLP_SEMREQUEST EQU 06H CALL [Device_Help] The SemRequest routine claims a semaphore. If the semaphore is already owned, the device driver thread can be placed in a wait state until the semaphore is released or until a time-out occurs. Parameters SemHandleLow the low word of the system or RAM semaphore handle. SemHandleHigh the high word of the system or RAM semaphore handle. SemTimeoutLow the low word of the value for the time-out limit. SemTimeoutHigh the high word of the value for the time-out limit. The combined low and high words can be one of the following values: Value Meaning ──────────────────────────────────────────────────────────────────────────── 0 Return immediately if the semaphore is already owned. -1 Wait indefinitely for the semaphore (time-out never occurs). > 0 Time-out limit in milliseconds. DEVHLP_SEMREQUEST the function code; its value is 06. Return Value The carry (C) flag is cleared if the routine is successful. Otherwise, the C flag is set and the ax register may have one of the following error values: ■ Semaphore time-out. ■ Interrupt. ■ Semaphore owner died. ■ Invalid handle. ■ Too many semaphore requests. Comments SemRequest first checks the status of a semaphore. If it is unowned, then SemRequest marks it as owned and returns immediately to the caller. If the semaphore is already owned, SemRequest does one of three things, depending on the value of the time-out parameter: ■ Returns immediately. ■ Blocks the device driver thread until the semaphore is released. ■ Blocks the device driver thread until the semaphore is released or the time-out occurs. The time-out parameter places an upper bound on the amount of time for SemRequest to block before returning to the requesting device driver thread. The device driver releases ownership of a claimed semaphore by calling the SemClear routine either at task time or at interrupt time. For a system semaphore, the device driver's task or interrupt handler must do the following: ■ Call SemHandle to make any semaphore passed to the driver via an IOCtl system-specific (rather than task-specific) and to indicate that this system semaphore is "in use" before the handler calls SemRequest to claim semaphore ownership. ■ Call SemHandle again and clear the usage flag before the handler calls SemClear to release system semaphore ownership. Note that system semaphores are created by an application process through a system call. The driver cannot create a system semaphore. System semaphores are not available to a device driver's user-mode routines. However, a device driver can create RAM semaphores to control user-mode operations within itself. For a RAM semaphore, the device driver must do the following: ■ Allocate a dword of storage, initialize it to zero, and use its virtual address (selector:offset or segment:offset) as the semaphore handle for calls to SemRequest or SemClear. ■ Manage the addressability to the RAM semaphore, allocating it in the device driver's low-memory data segment (containing the device header) if the driver references the semaphore at interrupt time. Note that the driver need not call SemHandle with a RAM semaphore, and that it may make user-mode calls to SemRequest and SemClear only for RAM semaphores. The SemRequest routine does not preserve the state of the interrupt flag. See Also SemClear, SemHandle █ SendEvent ──────────────────────────────────────────────────────────────────────────── MOV AH,Event ; event to signal MOV BX,Argument ; for event being signaled MOV DL,DEVHLP_SENDEVENT ; DEVHLP_SENDEVENT EQU 25H CALL [Device_Help] The SendEvent routine tells the system that an event occurred. Parameters Event the event being signaled. This parameter can be one of the following values: Value Meaning ──────────────────────────────────────────────────────────────────────────── 1 CTRL+BREAK 2 CTRL+C 3 CTRL+NUMLOCK 4 CTRL+PRTSC 5 SHIFT+PRTSC 6 Session Manager keyboard hot key 7 CTRL+ALT+DEL (reboot) Argument a parameter for the event being signaled. Its value and meaning depend on the Event parameter, as follows: Value Meaning ──────────────────────────────────────────────────────────────────────────── 1 Zero (reserved). 2 Zero (reserved). 3 Foreground session number. 4 Zero (reserved). 5 Zero (reserved). 6 HotkeyID set by a call to the IOCtl function, KBD_SETSESMGRHOTKEY (category 4, function 56). 7 Zero (reserved). DEVHLP_SENDEVENT the function code; its value is 25H. Return Value The C flag is cleared if the routine is successful. Otherwise, the C flag is set if the signal is in error. Comments The Event value 0 is reserved. The keyboard driver should dismiss the interrupt after calling SendEvent for a reboot (Event value 7). See Also EOI █ SetIRQ ──────────────────────────────────────────────────────────────────────────── MOV AX,OFFSET CS:Handler ; offset to interrupt handler MOV BX,IRQNum ; interrupt-level number (0-0FH) MOV DH,ShareFlag ; interrupt sharing: ; 0 = not shared, 1 = shared MOV DL,DEVHLP_SETIRQ ; DEVHLP_SETIRQ EQU 1BH CALL [Device_Help] The SetIRQ routine registers a device interrupt handler for a hardware interrupt level. Parameters Handler the offset in the device driver's code segment to the interrupt handler. IRQNum the interrupt-level number, in the range 00 to 0FH. ShareFlag whether interrupt sharing is available. This flag can be one of the following values: Value Meaning ──────────────────────────────────────────────────────────────────────────── 0 Not shared. 1 Shared. DEVHLP_SETIRQ the function code; its value is 1BH. Return Value The C flag is cleared if the routine is successful. Otherwise, the C flag is set if the specified IRQ is not available. Comments This routine enables the interrupt level at the PIC (programmable interrupt controller) on behalf of the device driver's interrupt handler if the IRQ is available. The ds register must point to the device driver's low-memory data segment when the driver calls SetIRQ. This low-memory data segment is the first-linked segment that contains the device header. If the driver has already called PhysToVirt with ds, this register must be reset before the call to SetIRQ. Whatever the value of ShareFlag, a call to SetIRQ will fail if the value specified for the IRQNum parameter is one of the following: ■ An IRQ owned by a real-mode interrupt handler. ■ The IRQ used to cascade the slave PIC. Otherwise, the value of ShareFlag affects the success of a call to SetIRQ as follows: ■ If ShareFlag is set, the call will fail if IRQNum is already owned by another device driver as "not shared." ■ If ShareFlag is clear, the call will fail if IRQNum is already owned by another device driver, whatever its shared status. The device driver's interrupt handler need not save registers on entry nor restore them on exit. The MS OS/2 interrupt manager does this for the driver. See Also PhysToVirt, RegisterStackUsage, UnSetIRQ █ SetROMVector ──────────────────────────────────────────────────────────────────────────── MOV AX,OFFSET CS:Handler ; offset to new interrupt handler MOV BX,IntNum ; interrupt number MOV SI,OFFSET CS:SaveDS ; offset to WORD in code segment ; where real-mode DS saved MOV DL,DEVHLP_SETROMVECTOR ; DEVHLP_SETROMVECTOR EQU 1AH CALL [Device_Help] The SetROMVector routine returns a real-mode pointer to a DOS software interrupt handler for chaining. Use this routine to replace the previous handler with a handler in your device driver. Parameters Handler the offset in the device driver's code segment to the new interrupt handler. IntNum the software-interrupt number. It may be any interrupt vector that is not reserved for hardware interrupts. Do not specify numbers in the following reserved ranges: ■ 08H-0FH. ■ 50H-57H. ■ 70H-77H. SaveDS the offset to a word in the device driver's code segment. SetROMVector saves the real-mode ds segment value of the previous interrupt handler in SaveDS. DEVHLP_SETROMVECTOR the function code; its value is 1AH. Return Value If the routine is successful, the following conditions apply: ■ The carry (C) flag is cleared. ■ The ax:dx register pair contains the real-mode pointer to the previous handler. ■ The cs:si register pair contains the real-mode pointer to the previous handler's data segment. Otherwise, the C flag is set when an invalid interrupt number is specified for the parameter IntNum. Comments SetROMVector allows a bimodal device driver to hook a real-mode ROM BIOS interrupt and to perform any interlocking necessary to coordinate device I/O between the driver and ROM BIOS. The ds register must point to the device driver's low-memory data segment when the driver calls SetROMVector. This low-memory data segment is the first-linked segment that contains the device header. If the driver has already called PhysToVirt with ds, this register must be reset before the call to SetROMVector. The device driver's handler for the specified interrupt gets control directly when this interrupt occurs. Consequently, the ds register is not set up for the handler on entry. Instead, the handler must load the ds register with the data segment value that SetROMVector saved in the handler's code segment. See Also EOI, PhysToVirt, RegisterStackUsage, ROMCritSection █ SetTimer ──────────────────────────────────────────────────────────────────────────── MOV AX,OFFSET CS:TimerHandler ; offset to driver's timer handler MOV DL,DEVHLP_SETTIMER ; DEVHLP_SETTIMER EQU 1DH CALL [Device_Help] The SetTimer routine registers a new timer handler: it adds the specified timer handler to the list of timer handlers to be called on a timer tick. Parameters TimerHandler the offset in the driver's code segment to the timer handler. DEVHLP_SETTIMER the function code; its value is 1DH. Return Value The carry (C) flag is cleared if the routine is successful. Otherwise, the C flag is set if the specified timer handler cannot be registered. If C is set, either the timer handler is already registered or the system has already registered its maximum number of timer handlers, 32. Comments This routine is a subset of the TickCount routine. SetTimer registers a timer handler to be called on every tick count; TickCount registers or changes a registered timer handler to be called on a specified tick count. A device driver may use a timer handler to drive a non-interrupt device rather than calling Block and Run with time-outs. Character device drivers, in particular, can minimize task switches by not calling Block and Run for character-by-character I/O. However, a device driver's timer routine must save any registers it uses and restore them on exit. A timer handler has the form of a call/ret routine, but it operates in interrupt mode. An MS OS/2 timer handler is analogous to an INT 1CH user timer handler. An MS OS/2 device driver should not remain in a timer handler very long, definitely less than the tick resolution of 31.25 milliseconds. The ds register must point to the device driver's low-memory data segment when the driver calls SetTimer. This low-memory data segment is the first-linked segment that contains the device header. If the driver has already called PhysToVirt with ds, this register must be reset before the call to SetTimer. MS OS/2 has a maximum of 32 different timer handlers. See Also Block, PhysToVirt, ResetTimer, Run, TickCount █ SortReqPacket ──────────────────────────────────────────────────────────────────────────── MOV SI,OFFSET Queue ; offset to queue header that ; points to next request LES BX,ReqPacket ; pointer request packet ; that goes into sorted queue MOV DL,DEVHLP_SORTREQUEST ; DEVHLP_SORTREQUEST EQU 0CH CALL [Device_Help] The SortReqPacket routine inserts the specified request packet into a queue that is ordered from high to low by starting sector number. Disk (block) device drivers can use this routine instead of PushReqPacket to add elements to the request list. Parameters Queue the queue header in the device driver's data segment (accessed by ds). The queue header points to the next request for the device to service. ReqPacket to the request packet to be inserted in the list. DEVHLP_SORTREQUEST the function code; its value is 0CH. Return Value SortReqPacket does not return a value. Comments This routine places I/O request packets allocated by AllocReqPacket into the request queue for a disk device. It inserts the request packet into the specified, ordered queue according to the starting sector number of the new packet. A request list sorted by sector number reduces the length and number of head seeks. However, SortReqPacket does not take into account multiple heads on the media or the target drive in the request packet. See Also AllocReqPacket, PushReqPacket, PullParticular, PullReqPacket █ TCYield ──────────────────────────────────────────────────────────────────────────── MOV DL,DEVHLP_TCYIELD ; DEVHLP_TCYIELD EQU 03H CALL [Device_Help] The TCYield routine yields the CPU to a time-critical thread of equal or higher priority if one is scheduled for execution. Parameters DEVHLP_TCYIELD the function code; its value is 03. Return Value TCYield does not return a value. Comments This routine is a subset of the Yield routine: it yields the CPU to a scheduled thread of equal or higher priority only if it is a time-critical thread. If it calls TCYield, a device driver need not call Yield as well. MS OS/2 is designed so that the CPU is never preemptively scheduled while in kernel mode. Most kernel routines perform their job and exit quickly. However, kernel routines usually must block while waiting for I/O to complete and sometimes must block while waiting for a resource. Device drivers that perform I/O on long strings of data or that poll the device in kernel mode can tie up a lot of CPU time. For best performance, such drivers can call GetDosVar to obtain the address of the TCYieldFlag and check the flag value every three milliseconds. If the TCYieldFlag is set, the driver should call TCYield to allow the time-critical thread to execute. This thread can change the state of the interrupt flag, so the driver must check and possibly adjust this flag when it regains the CPU. See Also GetDosVar, Yield █ TickCount ──────────────────────────────────────────────────────────────────────────── MOV AX,OFFSET CS:TimerHandler ; offset to driver's timer handler MOV BX,Count ; N tick counts (0-0FFFFH) ; with 0 = 0FFFFH+1 ticks MOV DL,DEVHLP_TICKCOUNT ; DEVHLP_TICKCOUNT EQU 33H CALL [Device_Help] The TickCount routine either registers a new timer handler or changes the count of ticks until a registered timer handler is called. Parameters TimerHandler the offset in the driver's code segment to the timer handler. Count the number of ticks at which the handler is called. Count is a number in the range 00 to 0FFFFH, where zero means 0FFFFH+1. DEVHLP_TICKCOUNT the function code; its value is 33H. Return Value The carry (C) flag is cleared if the routine is successful. Otherwise, the C flag is set if the timer handler cannot be registered or changed. The specified timer handler cannot be registered if it is already registered or if MS OS/2 has registered 32 timer handlers (system maximum). The specified timer handler cannot be changed if it is not registered by the calling driver. Comments This routine registers a new timer handler or changes the tick-count interval of a registered timer handler. TickCount is a superset of the SetTimer routine. A device driver may use a timer handler to drive a noninterrupt device rather than calling Block and Run with time-outs. Character device drivers, in particular, can minimize task switches by not calling Block and Run for character-by-character I/O. However, a device driver's timer routine must save any registers it uses and restore them on exit. A timer handler has the form of a call/ret routine, but it operates in interrupt mode. An MS OS/2 timer handler is analogous to an INT 1CH user timer handler. An MS OS/2 device driver should not remain in a timer handler very long, definitely less than the tick resolution of 31.25 milliseconds. The ds register must point to the device driver's low-memory data segment when the driver calls TickCount. This low-memory data segment is the first-linked segment that contains the device header. If the driver has already called PhysToVirt with ds, this register must be reset before the call to TickCount. The device driver may call TickCount to register a new timer handler only at task time (not in user or interrupt mode). The driver may modify a handler that was registered by SetTimer at task time also. In user and interrupt modes, the driver can call TickCount only to change the number of ticks that must occur before a registered timer handler gets control. In this way, the driver can support the time-outs without needing to count timer ticks. Note that the SetTimer routine sets a Count of 1 when it registers a timer handler. The driver can call TickCount many times to modify a registered handler, but only the last TickCount setting will be in effect for the handler. A TickCount call for a timer handler has no effect on other timer handlers in the system. MS OS/2 has a maximum of 32 different timer handlers. See Also Block, PhysToVirt, ResetTimer, Run, SetTimer █ Unlock ──────────────────────────────────────────────────────────────────────────── MOV BX,LockHandleLow ; handle returned by Lock MOV AX,LockHandleHigh ; for segment MOV DL,DEVHLP_UNLOCK ; DEVHLP_UNLOCK EQU 14H CALL [Device_Help] The Unlock routine releases a lock on a memory segment. Parameters LockHandleLow the low word of the segment handle returned by Lock. LockHandleHigh the high word of the segment handle returned by Lock. DEVHLP_UNLOCK the function code; its value is 14H. Return Value The carry (C) flag is cleared if the routine is successful. Otherwise, the C flag is set if the segment remains locked. Comments This routine unlocks a memory segment that was locked at task time. Unlock does not return if the lock handle is invalid. An invalid lock handle can hang the system, so take care that the handle passed to Unlock matches the handle obtained from Lock. A driver should call Unlock for each short-term lock (Lock TypeLock values 00 or 04) that it sets, before either of the following occurs: ■ Two seconds elapse. ■ The driver returns control to its caller. A segment that was locked during device driver initialization (Lock TypeLock value 03) is permanently locked until reboot occurs. It cannot be released by a call to Unlock. See Also Lock, VerifyAccess █ UnPhysToVirt ──────────────────────────────────────────────────────────────────────────── MOV DL,DEVHLP_UNPHYSTOVIRT ; DEVHLP_UNPHYSTOVIRT EQU 32H CALL [Device_Help] The UnPhysToVirt routine marks completion of the address conversions done by PhysToVirt calls. Parameters DEVHLP_UNPHYSTOVIRT the function code; its value is 32H. Return Value The zero (Z) flag is cleared if the operating mode is unchanged. The Z flag is set if a mode switch occurred. Comments This routine undoes one or more preceding PhysToVirt calls just before a device driver exits a routine. PhysToVirt and UnPhysToVirt relieve the driver of the need to recognize the CPU mode and the consequent effects on accessing memory. UnPhysToVirt must be called by the same routine that called PhysToVirt when use of converted addresses is completed and before the routine returns to its caller. The driver routine that had called PhysToVirt may call other driver routines before calling UnPhysToVirt, but it should not call other DevHlp routines except PhysToVirt. In fact, multiple PhysToVirt calls may be made prior to the UnPhysToVirt call. Only one UnPhysToVirt call is needed to undo multiple PhysToVirt calls. If a call to PhysToVirt caused a switch to protected mode, UnPhysToVirt will switch back to real mode. The Z flag is set if such a mode switch occurred. When a switch to real mode occurs, UnPhysToVirt converts the cs and ss values to real-mode segment addresses, preserves the sp address, and resets the ds and es registers to the segment address of the device driver's primary data segment, which contains the device header. See Also PhysToUVirt, PhysToVirt █ UnSetIRQ ──────────────────────────────────────────────────────────────────────────── MOV BX,IRQNum ; interrupt level number (0-0FH) MOV DL,DEVHLP_UNSETIRQ ; DEVHLP_UNSETIRQ EQU 1CH CALL [Device_Help] The UnSetIRQ routine removes the specified hardware-interrupt handler. Parameters IRQNum the interrupt level number in the range 00 to 0FH. DEVHLP_UNSETIRQ the function code; its value is 1CH. Return Value UnSetIRQ does not return a value. Comments This routine deinstalls a hardware interrupt handler. The ds register must point to the device driver's low-memory data segment when the driver calls UnSetIRQ. This low-memory data segment is the first-linked segment that contains the device header. If the driver has already called PhysToVirt with ds, this register must be reset before the call to UnSetIRQ. See Also PhysToVirt, SetIRQ █ VerifyAccess ──────────────────────────────────────────────────────────────────────────── MOV AX,MemSeg@ ; selector MOV CX,MemLength ; length of memory area ; with 0 = 64K bytes MOV DI,MemOffset ; offset to memory area MOV DH,TypeOfAccess ; verify access for: ; 0 = read-only, 1 = read/write MOV DL,DEVHLP_VERIFYACCESS ; DEVHLP_VERIFYACCESS EQU 27H CALL [Device_Help] The VerifyAccess routine confirms whether a user process has the correct access rights for a memory area passed to the device driver via an IOCtl call. If the process does not have the correct access rights, it will be terminated when the driver returns. Parameters MemSeg@ the selector of the memory segment passed by the user process. MemLength the length in bytes of the memory area to be verified for access. Zero means 64K bytes. MemOffset the offset in the memory segment passed by the user process. TypeOfAccess access privileges of the memory segment. This parameter has one of the following values: Value Meaning ──────────────────────────────────────────────────────────────────────────── 0 Read only segment. 1 Read/write segment. DEVHLP_VERIFYACCESS the function code; its value is 27H. Return Value The carry (C) flag is cleared if the routine confirms the user process's access rights to the segment. Otherwise, the C flag is set and the user process killed. Comments This routine protects a device driver from attempting to use invalid data that was passed to it by an erroneous or malicious user process. MS OS/2 cannot verify addresses embedded in an application IOCtl call. A device driver may call VerifyAccess to confirm that a user process passed a valid address. When a VerifyAccess call succeeds, it guarantees that the device driver has valid access to the segment until the driver blocks. A device driver can block by touching a not-present segment, by exiting its strategy routine, or by calling another DevHlp routine. If the driver calls Lock for a user-supplied address, it should place the Lock call before the call to VerifyAccess. Otherwise, the segment might be resized or freed if a block occurs during the lock. The device driver should call Unlock for the segment immediately if VerifyAccess fails the user address. For a successful lock and verification, the device driver's access remains valid until it calls Unlock for the segment. Call VerifyAccess only in protected mode. A real-mode call supplies no information because VerifyAccess always returns with the C flag clear from a real-mode call. If necessary, call the RealToProt routine before calling VerifyAccess. See Also Lock, RealToProt, TCYield, Unlock, Yield █ VirtToPhys ──────────────────────────────────────────────────────────────────────────── PUSH DS ; save DS LDS SI,VirtAddr ; virtual address is ; selector:offset or segment:offset MOV DL,DEVHLP_VIRTTOPHYS ; DEVHLP_VIRTTOPHYS EQU 16H POP ES ; ES gets old DS to driver's data segment CALL ES:[Device_Help] The VirtToPhys routine converts a virtual address into a 32-bit physical address. A virtual address is a selector:offset in protected mode or a segment:offset in real mode. Parameters VirtAddr the virtual address as a selector:offset or segment:offset. DEVHLP_VIRTTOPHYS the function code; its value is 16H. Return Value The carry (C) flag is cleared and the ax:bx register pair contains the physical address (32 bits) if the routine is successful. Otherwise, the C flag is set. Comments This routine converts a virtual address, usually passed to a device driver from a user process via an IOCtl call, into a physical address at task time. The driver's interrupt handler can use the converted address to access user memory and service the IOCtl request. Before it calls VirtToPhys, the handler should do the following: ■ Call Lock to keep the segment from being moved or swapped while the handler accesses it if the process-supplied location is not already locked. Note that MS OS/2 locks memory for addresses passed as read/write requests but not for user-process addresses passed via an IOCtl to the handler. ■ Call VerifyAccess in protected mode to confirm the validity and segment access rights of any user address passed via an IOCtl. If it is necessary to change operating modes, call RealToProt before VerifyAccess. To change back to real mode when access is confirmed, call ProtToReal. The physical address returned by VirtToPhys remains valid while the segment is locked. See Also Lock, ProtToReal, RealToProt, Unlock, VerifyAccess █ Yield ──────────────────────────────────────────────────────────────────────────── MOV DL,DEVHLP_YIELD ; DEVHLP_YIELD EQU 02H CALL [Device_Help] The Yield routine yields the CPU to a thread of equal or higher priority if one is scheduled for execution. Parameters DEVHLP_YIELD the function code; its value is 02. Return Value Yield does not return a value. Comments This routine is a superset of the TCYield routine: it yields the CPU to a scheduled thread of equal or higher priority. If it calls Yield, a device driver need not call TCYield as well. MS OS/2 is designed so that the CPU is never preemptively scheduled while in kernel mode. Most kernel routines perform their job and exit quickly. However, kernel routines usually must block while waiting for I/O to complete and sometimes must block while waiting for a resource. Device drivers that perform I/O on long strings of data or that poll the device in kernel mode can tie up a lot of CPU time. For best performance, such drivers can call GetDosVar to obtain the YieldFlag address value and check this flag every three milliseconds. If the YieldFlag is set, the driver should call Yield. When the driver yields, another thread can change the state of the interrupt flag, so the driver must check and possibly adjust the interrupt flag when it regains the CPU. See Also GetDosVar, TCYield Chapter 4 Base Video Device Handlers ──────────────────────────────────────────────────────────────────────────── 4.1 Introduction MS OS/2 version 1.2 base video device handlers manage text-mode displays for their adapters. A BVH (base video handler) consists of one or more dynamic-link libraries coded in C or assembly language, or in both. A BVH can also have one or more ring-0 components that are character device drivers; a BVH must have a ring-0 component for certain kinds of adapters. BVHs execute in protected mode. At system boot, MS OS/2 first loads the base drivers, including the driver named screen$, and then loads the boot-up text-display handler when it processes the config.sys file. The boot-up text-display handler supports screen output for the system during config.sys processing. This BVH (and every other BVH) is an installable device driver, consisting of at least one dynamic-link library component and possibly a ring-0 component. For example, the following lines in config.sys set up the dynamic-link library named BVHMyDll to be the boot-up text-display handler: ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ; following lines set video environment variables for a system ; ; configured with two displays ; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; set video_devices=VIO_MyBVH,VIO_OtherBVH set vio_MyBVH=device(BVHMyDll,MyAdptr) ptrdevp(MyPrtPt) ptrdevr(MyRlPt) set vio_OtherBVH=device(BVHEGA,OtherDll) Because the MyBVH handler defines the first BVH dynamic-link library component in config.sys, it becomes the boot-up text-display handler if it installs successfully. This BVH has two components, bvhmydll.dll and a ring-0 myadptr.sys, defining a single logical BVH. It also specifies custom protected- and real-mode pointer drivers (MyPrtPt and MyRlPt) with the keywords ptrdevp and ptrdevr. A BVH must have a ring-0 component if its adapter's native mode cannot be changed by the real-mode interrupt 10H. Otherwise, a BVH need not have a ring-0 component because its dynamic-link library component(s) may call the screen$ driver to provide ring-0 support. For more information about BVH ring-0 components, see Section 4.2.4. MS OS/2 version 1.2 uses the default system driver named pointer$ if the optional keywords ptrdevr and ptrdevp are not specified with replacement pointer drivers for the BVH in config.sys. The BVH that loads after MyBVH uses the default pointer driver pointer$. If this BVH came before the "set vio_MyBVH..." statement in config.sys and installed successfully, the OtherBVH handler would become the boot-up text-display handler. The OtherBVH has two dynamic-link library components, bvhega.dll and otherdll.dll. The second of these components is "chained to" the existing EGA driver. For more information about chaining base video device handlers, see Section 4.2.3. By convention, base video device handlers name their dynamic-link library components with the prefix BVH in config.sys (and in the Microsoft Segmented-Executable Linker, version 5.0, definition file). They name the C-language modules that make up such a component with the prefix VDH (video device handler). 4.2 BVH Installation and the DevEnable Function During system boot, MS OS/2 reads in config.sys and calls each BVH dynamic-link library component, in turn, through its entry point, the DevEnable function. The first-linked module of each BVH dynamic-link library component must contain its DevEnable function. This function has the following syntax if it is coded in the C language: USHORT EXPENTRY DevEnable(Parm2, Parm1, Subfunction) /* EXPENTRY forces Pascal FAR calling */ /* conventions in C-language modules */ Dev_Parm2 FAR *pParm2; /* Parm2 packet has two FAR pointers, */ /* FAR *pfsFlags and */ /* FAR *paCallVectorTable */ Dev_Parm1 FAR *pParm1; /* Parm1 packet has two ULONGS, */ /* ULONG EngineVersion (PM's Gre) */ /* ULONG cTableEntries */ ULONG ulSubfunction; /* ulSubfunction has two possible values, */ /* 3L=FnFillInitDevBlock or */ /* 1L=FnFillLogicalDevBlock */ The initial call to DevEnable has one purpose: to put symbolic far pointers into the system's video call vector table for those VDH functions that the BVH component supplies. A BVH dynamic-link library component supplies its symbolic pointers to VDH functions only once at system boot. (At subsequent calls to DevEnable, the dynamic-link library component may do per-process initialization, such as getting a handle for the screen$ driver.) If the initial call is successful, DevEnable returns zero (to the ax register for assembly-language modules); otherwise, it returns the value for PMERR_DEV_FUNC_NOT_INSTALLED. The Parm2 packet contains a far pointer to a USHORT Boolean flag, indicating whether this BVH component has initialized already, and another far pointer to the BVS (base video subsystem) dispatch table, itself an array of far pointers that is indexed by VDH function codes. For more information about the VDH functions, see Sections 4.3 and 4.5. The Parm1 packet supplies the version number for the Presentation Manager graphics engine, which the BVH component may ignore, and a count of the number of BVS entries in the system's video call vector table. This value defines the maximum number of pointers that the BVH may put into the BVS range of the system's video call vector table. The ulSubfunction value is either 3L or 1L, depending on whether the BVH is to be the boot-up display handler. MS OS/2 calls each dynamic-link library component of the first BVH in config.sys, using its DevEnable entry point with ulSubfunction 3L, until the BVH's dynamic-link library component(s) initialize successfully. After that, it calls the remaining BVH components, if any, using their DevEnable entry points with ulSubfunction 1L. MS OS/2 loads a default BVH (bvhinit.dll, supplied with the system) if there are no BVHs in config.sys to drive the boot-up display. However, the system crashes if a BVH specified in config.sys fails the call to DevEnable, ulSubfunction 3L. The system does not load a BVH if one of its dynamic-link library components fails the call to DevEnable, ulSubfunction 1L, or if a ring-0 component fails to initialize (for more information about ring-0 components, see Section 4.2.4). 4.2.1 BVS/VDH Functions in the Video Call Vector Table MS OS/2 version 1.2 dedicates the function-code range from 256L to 287L (hexadecimal 100 to 11F) to BVS in the system's video call vector table. (MS OS/2 version 1.2 also reserves the function-code range from 000 to 255 for the Presentation Manager, and the range from 288 to 319 for other purposes.) BVS routes application VIO calls through this call vector table to the appropriate BVH dynamic-link library component that supplies an entry point for the corresponding VDH function. BVS supplies system default routines for 24 VDH functions in the range from 256L to 279L, although most of its default routines merely return an error. This subrange of the system's video call vector table defines the MS OS/2 version 1.2 BVS dispatch table for VDH function calls. All BVHs must supply a subset of these functions, and a BVH may supply all of them. The VDH functions, listed in function-code order, are as follows: Function code Function description ──────────────────────────────────────────────────────────────────────────── 256L TextBufferUpdate Reads from, scrolls, or writes to the display. 257L InitializeEnvironment Sets up the environment buffer for a new session. 258L SaveEnvironment Saves the foreground session's environment when a session switch is about to occur. 259L RestoreEnvironment Restores a background session's environment when a session switch is about to occur. 260L RetConfigInfo Returns information that identifies the current adapter and display. 261L GetDBCSDisplayInfo Returns the range of double-cell DBCS (double-byte character set) characters. 262L GetColorLookup Returns color definitions from the color lookup table for VGA-type adapters. 263L SetColorLookup Sets color definitions from the color lookup table for VGA-type adapters. 264L GetCursorInfo Returns information about the cursor's position, its type, or both. 265L SetCursorInfo Sets the cursor's position, its type, or both. 266L GetFont Returns a user-defined, code-page, or ROM font compatible with the current mode. 267L SetFont Sets up a user-font definition and loads a font compatible with the current mode. 268L GetMode Returns information about the current video mode. 269L SetMode Sets or changes the video mode. 270L GetPaletteRegisters Reads the current palette register settings into the palette buffer. 271L SetPaletteRegisters Loads palette settings from the palette buffer. 272L GetPhysBuf Returns LDT (local descriptor table) access to the PVB (physical video buffer). 273L FreePhysBuf Releases an LDT selector allocated by GetPhysBuf. 274L GetVariableInfo Returns information about selected adapter features, such as blink state, border color (overscan), video enable state, etc. 275L SetVariableInfo Sets selected adapter features, such as blink, border color, video enable, etc. 276L TerminateEnvironment Cleans up the environment before a session terminates. 277L PrintScreen Sends a copy of a text-mode display to a printer. 278L WriteTTY Writes a character string to the display. 279L GetLVBInfo Returns information about an LVB (logical video buffer). The VDH functions TerminateEnvironment, PrintScreen, and WriteTTY are optional, and the functions GetColorLookup and SetColorLookup are required only for BVHs that support VGA-type adapters. Each VDH function must be callable both from ring-2 and from ring-3. For this reason, a BVH dynamic-link library component must place at least the entry points for its VDH functions in a conforming code segment with I/O privilege. For more information about the VDH functions, see Sections 4.3 and 4.5. 4.2.2 BVH Component Installation Each BVH dynamic-link library component overwrites one or more of the VDH function addresses in the BVS dispatch table when its DevEnable function executes at system boot. Each component usually keeps a static copy of the BVS dispatch table in its data segment with the names (symbolic addresses) of the VDH functions it supports and the zero-valued constant UNSUPPORTED_FUNCTION for those VDH functions that it does not support. At the DevEnable call, the component assigns the names of its functions (nonzero values) to the corresponding slots in the BVS dispatch table. When a BVH has more than one dynamic-link library component, each subsequent component also overwrites one or more symbolic addresses in the BVS dispatch table as its DevEnable function executes. Each dynamic-link library component supplies symbolic addresses for the VDH functions that it supports until the BVH, as a whole, has supplied all the required VDH entry points, plus entry points for any optional VDH functions that it cares to supply. For more information about ring-0 component installation, see Section 4.2.4. If a BVH is the boot-up text-display handler, its first-installed dynamic-link library component must supply the following VDH functions: Function Support required ──────────────────────────────────────────────────────────────────────────── TextBufferUpdate Full implementation InitializeEnvironment Full implementation SaveEnvironment Full implementation RestoreEnvironment Full implementation GetDBCSInfo Full implemenatation GetCursorInfo Full implementation SetCursorInfo Full implemenatation GetMode 80 * 25 text or equivalent only SetMode 80 * 25 text or equivalent only GetVariableInfo Code page only SetVariableInfo Code page only GetLVBInfo Full implementation However, a subsequent dynamic-link library component can overwrite any VDH function addresses that were supplied by the first component in the BVS dispatch table. Note that a subsequent component for the boot-up BVH might do this in order to supply more powerful versions of the GetMode, SetMode, GetVariableInfo, and SetVariableInfo VDH functions after the first component installs. 4.2.3 Chained BVHs After the first dynamic-link library component of a logical BVH installs, a subsequent dynamic-link library component need not destroy any of the first component's addresses, even if the subsequent component supplies versions of the same functions. Instead, the subsequent component can do the following: ■ Keep a copy of the prior component's call vector table that is already initialized with pointers to the VDH functions supplied by the prior component. ■ Put its own addresses into the BVS dispatch table, overwriting the prior component's symbolic addresses in the system's call vector table. ■ Pre-process VDH function calls as they come in with its own functions. Then, route calls through the copied dispatch table to the prior component's corresponding function, and let it process the request from BVS. ■ Do any post-processing necessary after the prior component's function returns control. Then, return control to BVS. This technique, called "chaining," allows a BVH to add features to a basic dynamic-link library component (whose VDH functions are merely adequate to handle BVS calls) by adding a subsequent dynamic-link library component. A chained BVH must also allocate an environment buffer that contains the chainee's environment buffer as a proper subset. 4.2.4 Ring-0 Components Most BVHs have only dynamic-link library components. However, a BVH must have a ring-0 component if its adapter does not recognize the real-mode interrupt 10H at system boot. The ring-0 component is a character device driver that can force the adapter out of its native mode and pass control to BVS's real-mode PanicWrite function (INT 10H WriteTTY) in case MS OS/2 must terminate abnormally before it loads the video subsystem. Then, MS OS/2 can send a termination message to the screen. A BVH may have a ring-0 component in order to take advantage of an adapter's special features, such as paged-memory support. A BVH ring-0 component is required to support the Init, OpenDevice, and GenericIOCtl requests. It should return "Unknown command" (standard error code 03) and "done" in the Status word of the request packet for any device commands that it does not support. The ring-0 component must verify that the adapter is present at the Init request, and it must also process the IOCtl category 03, function 73H, GenericIOCtl request (and verify that the adapter is present at this request also). The category 03, function 73H, GenericIOCtl request is a ring-0 version of the DevEnable function for a BVH dynamic-link library component. The Ptr_To_Data_Buff in the GenericIOCtl request packet accesses a data packet with the following layout: +-------------------+ | Subfunction | DWORD +-------------------+ | Parm1 | DWORD PTR Ptr_To_Data_Buff+4 +-------------------+ | Parm2 | DWORD PTR Ptr_To_Data_Buff+8 +-------------------+ | FnReturnCode | WORD PTR Ptr_To_Data_Buff+0CH +-------------------+ The Subfunction, Parm1, and Parm2 parameters are identical to those of the DevEnable function (see Section 4.2). The input Subfunction value is 1H. On exit, the FnReturnCode field should contain a zero for success or the value ERROR_VIO_BAD_ADAPTER. However, the ring-0 component must set up a call gate if it overwrites any VDH function address in the BVS dispatch table, because all VDH functions must be callable from both ring-2 and ring-3. Rather than setting up a call gate, the BVH can use either of the following techniques: ■ Code at least an initial dynamic-link library component that specifies entry points for the VDH functions in a conforming code segment with I/O privilege. If the BVH is the boot-up text-display handler, this component must be the initial dynamic-link library that supplies the required boot-up VDH functions (see Section 4.2.2). Put support routines for the VDH functions into the ring-0 component. Call DosDevIOCtl or DosDevIOCtl2 from a dynamic-link library component when one of your VDH functions needs ring-0 support. ■ If a ring-0 component is optional, install it as a separate screen/adapter device driver with its own device statement in config.sys. Put support routines for the VDH functions into this driver for the VDH functions in your BVH dynamic-link library components. Call DosDevIOCtl or DosDevIOCtl2 when a VDH function needs ring-0 support. Note that dynamic-link library code must call DosOpen or DosOpen2 to obtain a device handle before making an IOCtl call to a ring-0 component or driver. Device handles are system resources, so the BVH code should be designed to release device handles as quickly as possible. A ring-0 replacement screen$ driver must handle the following category 03 IOCtl calls that support BVHs: Function Description ──────────────────────────────────────────────────────────────────────────── 70H Allocates an LDT selector (supports VDH GetPhysBuf). 75H Allocates an LDT selector with offset (supports VDH GetPhysBuf). 71H Deallocates an LDT selector (supports VDH FreePhysBuf). For more information about the Init, OpenDevice, and GenericIOCtl requests, see Chapter 2, "Device Commands." For general information about installable ring-0 drivers, see Chapter 1, "Overview of Base and Installable Device Drivers." For more information about the DosOpen, DosOpen2, DosDevIOCtl, and DosDevIOCtl2 functions, see Appendix C, "Dos Functions for Installable Device Drivers." Note that a BVH dynamic-link library component runs at ring-2, not at ring-0, so it can call these functions after the BVH is installed. 4.3 VDH Function Calls BVS passes three parameters to every VDH function on the application's stack. The following is a C-language template for a BVH's declaration of every VDH function: USHORT Function_Name(pEnvironment, pParmBlock, ulFunction) ENVIRONMENT far *pEnvironment; /* pointer to environment buffer */ /* for this session */ VDH_xxx far *pParmBlock; /* pointer to function-specific */ /* parameter block */ ULONG ulFunction; /* VDH function code (index) */ The pEnvironment pointer is a huge selector that accesses the environment buffer for the calling application's session. The environment buffer has a maximum size of one megabyte, so the pEnvironment selector accesses the first 64K segment of this buffer. The format of the environment buffer is BVH-specific. The BVH developer defines the ENVIRONMENT structure to suit the needs of the adapter and his or her code. However, every BVH ENVIRONMENT structure must contain certain fields, including a copy of the VIOMODEINFO structure. For more information about the format of the environment buffer, see the InitializeEnvironment function in Section 4.5. All pointer parameters to VDH functions are protected-mode virtual addresses. Pointers to the environment or logical video buffers are huge selectors, because MS OS/2 calls DosAllocHuge to set up these buffers for each new session. If the environment buffer or LVB is greater than 64K in length, use the value returned by the DosGetHugeShift function to access the next segment. The format of the parameter block (pointed to by pParmBlock) is function-specific. The general structure of the parameter block is as follows: typedef struct { USHORT usLength; /* bytes in ParmBlock, including usLength*/ USHORT fsFlags; /* bit 0=0--operate on environment */ /* buffer or on LVB only */ /* bit 0=1--operate on adapter and update*/ /* environment buffer and/or */ /* LVB also */ /* bits 1-15 function-specific */ /* additional fields are function-specific */ } VDH_xxx; The parameter block for every VDH function always contains the first two fields. The least significant bit of the fsFlags field tells the BVH whether the calling application is running in the foreground. If bit 0 of fsFlags is set on entry to a VDH function, the BVH must access the adapter to perform the operation and must update the environment buffer with the changes it makes on the adapter. BVHs that handle DBCS (double-byte character set) text display, must update the LVB before the PVB (physical video buffer). The ulFunction value identifies the VDH function by its function code in the BVS dispatch table. For a list of the VDH function codes, see Section 4.2.1. Every VDH function returns a value (to the ax register, if it is coded in assembly language). Each function returns zero if it is successful. For more information about function-specific errors that a BVH should return, see Section 4.5. 4.4 LVB Formats The contents of the LVB are a sequence of character-attribute pairs that map to cells on the display. MS OS/2 version 1.2 defines two basic formats for LVBs, so that a BVH can map an LVB to the PVB and vice versa. BVS passes LVB selectors to the BVH for many VDH functions. The BVH manages its own PVB addresses. 4.4.1 Default LVB Format A BVH that uses the MS OS/2 default LVB format must supply its code values for some VDH functions. The following constants define these values: #define DefaultFormat 0x00 #define DefaultAttrCount 0x01 An LVB in the default format is a stream of two-byte character-attribute pairs. The first byte is a character code point. The second is an attribute byte, specifying the appearance of the character on the display. Each character-attribute pair in the LVB maps to one cell on the display, as is common for US-standard adapters. However, BVHs that handle DBCS (double-byte character set) displays must sometimes handle characters that require two cells to display, as well as those that require one cell. For these BVHs, the default LVB format is inadequate. 4.4.2 World-wide LVB Format A BVH that uses the MS OS/2 world-wide LVB format must also supply its code values for some VDH functions. The following constants define these values: #define WorldFormat 0x70 #define WorldAttrCount 0x03 An LVB in the world-wide format is a stream of four-byte character-attribute pairs. The first byte is a character code point, as for the default format. The next three bytes specify attributes. Each character-attribute pair in the world-wide LVB format is defined as follows: <TT>World-wide LVB Character-attribute Format" ""</TT> Byte Bit Meaning ──────────────────────────────────────────────────────────────────────────── First Character code point (for example, SHIFTJIS if the code page is DBCS 93 Second CGA attributes (background and foreground color) Third 0-1 Reserved (must be zero) 2 Top horizontal grid attribute 3 Left vertical grid attribute 4 Background transparency (set has meaning in AVIO context only) 5 Blinking 6 Reverse video 7 Underscore Fourth 0 DBCS byte (set for DBCS byte) 1-6 Reserved (must be zero) 7 Trailing byte, DBCS double-cell character (set for trailing byte) In this format, a single-cell DBCS character also has three attribute bytes per character code point in the LVB. The attribute bytes for a single-cell DBCS character contain the font-identification code. In MS OS/2 world-wide format, a character code point can represent an SBCS (single-byte character set) character, the leading or trailing byte of a double-cell DBCS character, or a DBCS single-cell character. The fourth attribute byte of a DBCS character is sometimes called the "system byte," because it is read-only at the calling application's level; the BVH has read-write access to the system byte. A BVH that defines an LVB format identical to that of its adapter should use the value 0x80 as the format ID. It should use an attribute-count value identical to the number of attribute bytes per character code point. 4.4.3 Shadow LVBs A BVH that uses only the default LVB format may write character-attribute pairs directly to the display for the current foreground session. It need not maintain an LVB for this session, since the default format maps one-to-one to single cells on the display. When a session switch occurs, the BVH saves the PVB to an LVB for the about-to-go-background session. When BVS calls the BVH to restore an LVB for a background session, BVS supplies the corresponding LVB selector to the BVH. A BVH that uses only the default LVB format need not maintain an LVB, called a "shadow LVB," for the current foreground session, but it may do so. However, a BVH that uses world-wide LVB format must maintain one or more shadow LVBs for the foreground session. Such BVHs sometimes overlay the display with a conversion rectangle. Each conversion rectangle must have its own LVB, so that the calling application's LVB is intact when a conversion rectangle is dismissed, and so the BVH can refresh any conversion rectangle after it scrolls the display or writes to it at an application's VIO call. 4.4.4 DBCS Text Display Updates A BVH that handles DBCS displays must handle double-cell DBCS characters correctly when the following problems occur: ■ A read or write request begins or ends at a position that would bisect a double-cell character. ■ An application's input buffer ends on the leading byte of a double-cell character, or a write operation ends at the last cell of the LVB/PVB and this last cell is the leading byte of a double-cell character. ■ A write operation is about to bisect a double-cell character at the edge of the screen. To handle such problems correctly, the BVH must obey the following general rules: ■ Always update the LVB before updating the PVB. ■ Replace any bisected double-cell character with single-cell space characters in the destination buffer, except at the edge of the screen. At a screen edge, retain the double-cell character in the LVB; the BVH should (but not must) replace the bisected character with a space in the PVB. ■ When a conversion rectangle is dismissed, restore any bisected double-cell characters that were overlaid by a border of the conversion rectangle when refreshing the PVB from the LVB. For function-specific information about DBCS update rules, see the TextBufferUpdate and WriteTTY in Section 4.5, next. MS OS/2 guarantees compatibility across DBCS displays for BVHs that obey these function-specific DBCS update rules. 4.5 VDH Function Reference This section describes the VDH functions in alphabetic order. █ FreePhysBuf ──────────────────────────────────────────────────────────────────────────── USHORT FreePhysBuf (pEnvironment, pParmBlock, ulFunction) ENVIRONMENT far * pEnvironment; /*pointer to environment buffer */ VDH_FREEPVB far * pParmBlock; /*pointer to parameter block */ ULONG ulFunction; /*function index */ The FreePhysBuf function deallocates an LDT (local descriptor table) selector that was allocated by the GetPhysBuf function. Parameters pEnvironment to the environment buffer. pParmBlock to the parameter block for FreePhysBuf, defined by the following structure: typedef struct { USHORT usLength; /* ParmBlock = 6 bytes */ USHORT fsFlags; /* must be zero */ USHORT selLDTSelector; /* allocated by GetPhysBuf */ } VDH_FREEPVB; ulFunction FreePhysBuf in the call vector table; its value is 273L (0x0111). Return Value If it is successful, FreePhysBuff should return zero (to the ax register when coded in assembly language). Otherwise, it should return one of the following errors when it encounters any one of the following conditions: Return Conditions ──────────────────────────────────────────────────────────────────────────── ERROR_VIO_INVALID_PARMS If the ulFunction value is anything except 273L (0x0111); if the ParmBlock fsFlags value is nonzero; or if the pEnvironment value is zero. ERROR_INVALID_LENGTH If the ParmBlock usLength value is not 6. ERROR_VIO_PTR If the ParmBlock selLDTSelector passed to a ring-0 BVH component is not a ring-3 selector. Comments The FreePhysBuf function may use either of the following methods to release the LDT selector: ■ Call the DosFreeSeg function to release the input selector. ■ Call the DosDevIOCtl or DosDevIOCtl2 function with the input physical address, the screen$ driver handle, and the IOCtl code combination category 0x0003 and function 0x0071 to free the selector or selector with offset that was obtained by GetPhysBuf. For more information about DosDevIOCtl and DosDevIOCtl2, see Appendix C, "Dos Functions for Installable Device Drivers." Note that a BVH dynamic-link library component runs at ring-2, not at ring-0, so it can call these functions after the BVH is installed. Otherwise, the FreePhysBuf function must have support from a BVH ring-0 component that calls the DevHlp routine PhysToUVirt to release the LDT selector. In this case, the ring-0 support routine must check the input LDT selector's RPL (requested privilege level) before calling PhysToUVirt; if the RPL value is not 3, FreePhysBuf should not release the input selector. For more information about PhysToUVirt, see Chapter 3, "Device Helper Services." See Also DosFreeSeg, GetPhysBuf █ GetColorLookup ──────────────────────────────────────────────────────────────────────────── USHORT GetColorLookup (pEnvironment, pParmBlock, ulFunction) ENVIRONMENT far * pEnvironment; /*pointer to environment buffer */ VDH_CLUT far * pParmBlock; /*pointer to parameter block */ ULONG ulFunction; /*function index */ The GetColorLookup function reads a specified number of color definitions from the color lookup table for VGA-type or VGA-compatible adapters. Parameters pEnvironment to the environment buffer. pParmBlock to the parameter block for GetColorLookup, defined as the following structure: typedef struct { USHORT usLength; /* ParmBlock = 12 bytes */ USHORT fsFlags; /* 0x0000=read from environment buf */ /* 0x0001=read adapter and update */ /* environment buffer also */ CLUTDATA far *pLookupTable /* pointer to device-dependent CLUT */ USHORT iFirstEntry; /* index to first entry to read */ USHORT usNumEntries; /* how many entries to read */ } VDH_CLUT; ulFunction GetColorLookup in the call vector table; its value is 262L (0x0106). Return Value If it is successful, GetColorLookup should return zero (to the ax register when coded in assembly language). Otherwise, it should return one of the following errors when it encounters any one of the following conditions: Return Conditions ──────────────────────────────────────────────────────────────────────────── ERROR_VIO_INVALID_PARMS If the ulFunction value is anything except 262L (0x0106); if the ParmBlock fsFlags value is greater than 1; if the ParmBlock iFirstEntry value is outside the range of entries in the color lookup table; if the ParmBlock usNumEntries value is less than 1; or if the pEnvironment value is zero. ERROR_INVALID_LENGTH If the ParmBlock usLength value is not 12; or if the ParmBlock usNumEntries value is too large, either greater than the number of entries in the color lookup table or greater than the total entries following iFirstEntry. Comments Only BVHs that support VGA-type adapters need supply a GetColorLookup function. An odd value for the fsFlags field implies that the calling application is running in the foreground. If all ParmBlock fields are valid, GetColorLookup should do the following: ■ Read the adapter's color registers into the specified range of the environment buffer's color lookup table. ■ Update the parameter block's color lookup table with these settings. If the input fsFlags value is zero, GetColorLookup must return values from the environment buffer. The format of the color lookup table is device-dependent. See Also SetColorLookup █ GetCursorInfo ──────────────────────────────────────────────────────────────────────────── USHORT GetCursorInfo (pEnvironment, pParmBlock, ulFunction) ENVIRONMENT far * pEnvironment; /*pointer to environment buffer */ VDH_CURSOR far * pParmBlock; /*pointer to parameter block */ ULONG ulFunction; /*function index */ The GetCursorInfo function returns selected information about the cursor's position, its type, or both. Parameters pEnvironment to the environment buffer. pParmBlock to the parameter block for GetCursorInfo, defined as the following structure: typedef struct { USHORT usLength; /* ParmBlock = 16 bytes */ USHORT fsFlags; /* bit 0=0--get from environ buf */ /* bit 0=1--read from HW state, if */ /* possible */ /* bit 1=1--get cursor position */ /* bit 2=1--get cursor type */ /* bits 3-15 must be zero */ USHORT usRow; /* 0=top row */ USHORT usColumn; /* 0=leftmost column */ USHORT usTopScanLine; /* 0=top scan line of n scan */ USHORT usBottomScanLine; /* lines,(n-1)=bottom scan line */ USHORT usWidth; /* in columns for text mode */ USHORT usAttribute; /* -1=hidden for text mode */ } VDH_CURSOR; ulFunction GetCursorInfo in the call vector table; its value is 264L (0x0108). Return Value If it is successful, GetCursorInfo should return zero (to the ax register when coded in assembly language). Otherwise, it should return one of the following errors when it encounters any one of the following conditions: Return Conditions ──────────────────────────────────────────────────────────────────────────── ERROR_VIO_INVALID_PARMS If the ulFunction value is anything except 264L (0x0108); if the ParmBlock fsFlags value is greater than 7; or if the pEnvironment value is zero. ERROR_INVALID_LENGTH If the ParmBlock usLength value is not 16. ERROR_VIO_MODE If a check of the fbType value in the environment buffer's VDHMODEINFO data indicates graphics mode. Comments The ParmBlock usRow and usColumn fields contain the cursor position information. The fsFlags field may be a combination (OR) of the following values: Value Meaning ──────────────────────────────────────────────────────────────────────────── 0x0001 Read in values from the adapter, if possible. Otherwise, return cursor information from the environment buffer. 0x0002 Get the cursor position values. 0x0004 Get the cursor type values. An odd value for fsFlags implies that the calling application is running in the foreground. In this case, GetCursorInfo should do the following: ■ Read the cursor information from the adapter, if possible. ■ Update the environment buffer with this information. ■ Return the cursor information to the appropriate fields of ParmBlock. If the adapter is write-only or if the fsFlags value is even, GetCursorInfo must return the cursor information from the environment buffer. If the fsFlags value is one or zero, GetCursorInfo may ignore the adapter and environment-buffer settings and return success. See Also GetModeInfo, SetCursorInfo, VioGetCurPos, VioGetCurType █ GetDBCSDisplayInfo ──────────────────────────────────────────────────────────────────────────── USHORT GetDBCSDisplayInfo (pEnvironment, pParmBlock, ulFunction) ENVIRONMENT far * pEnvironment; /*pointer to environment buffer */ VDH_DBCS far * pParmBlock; /*pointer to parameter block */ ULONG ulFunction; /*function index */ The GetDBCSDisplayInfo function returns DBCS (double-byte character set) information about characters that require two cells each to display. Parameters pEnvironment to the environment buffer. pParmBlock to the parameter block for GetDBCSDisplayInfo, defined as the following structure: typedef struct { USHORT usLength; /* minimum, 2 bytes */ USHORT fsFlags; /* must be zero */ USHORT cbCellTableLen; /* number of bytes in double-cell */ /* character table */ USHORT cbCellTableOFF; /* offset to double-cell table */ } VDH_DBCS; ulFunction GetDBCSDisplayInfo in the call vector table; its value is 261L (0x0105). Return Value If it is successful, GETDBCSDisplayInfo should return zero (to the ax register when coded in assembly language). Otherwise, it should return one of the following errors when it encounters any one of the following conditions: Return Conditions ──────────────────────────────────────────────────────────────────────────── ERROR_VIO_INVALID_PARMS If the ulFunction value is anything except 261L (0x0105); if the ParmBlock fsFlags value is not zero; or if the pEnvironment value is zero. ERROR_INVALID_LENGTH If the ParmBlock usLength field is less than 2 or if the value is less than 8 plus the size of the double-cell table in the environment buffer and the BVH supports DBCS code pages. ERROR_VIO_MODE If a check of the fbType value in the environment buffer's VDHMODEINFO data indicates graphics mode. Comments If the ParmBlock usLength value is 2, GetDBCSDisplayInfo should return the number of bytes that it needs to return the double-cell table data. For US-standard adapter types, this value is 6, since GetDBCSDisplayInfo need only return a zero to the cbCellTableLen field of the VDH_DBCS structure. For international adapter types that display double-cell DBCS characters, GetDBCSDisplayInfo should return the sum of the ParmBlock size (8 bytes) and the length of the double-cell table when the input usLength value is 2. When the input usLength value is greater than 2, it defines the maximum amount of data for GetDBCSDisplayInfo to return. If this usLength specification is too short to return the double-cell table, GetDBCSDisplayInfo should return an error. Otherwise, GetDBCSDisplayInfo should return the length and offset of the double-cell character table, which it obtains from the environment buffer. The double-cell character table is an array of paired USHORT values. Each USHORT pair defines the low and high characters of a range of double-cell characters. Each double-cell DBCS character requires two cells on the display. See Also GetLVBInfo █ GetFont ──────────────────────────────────────────────────────────────────────────── USHORT GetFont (pEnvironment, pParmBlock, ulFunction) ENVIRONMENT far * pEnvironment; /*pointer to environment buffer */ VDH_FONT far * pParmBlock; /*pointer to parameter block */ ULONG ulFunction; /*function index */ The GetFont function returns either the currently active font or a selected font that is compatible with the current mode. Parameters pEnvironment to the environment buffer. pParmBlock to the parameter block for GetFont, defined as the following structure: typedef struct { USHORT usLength; /* ParmBlock = 14 bytes */ USHORT fsFlags; /* bit 0=0--read from environment buf*/ /* bit 0=1--read from adapter and */ /* update environ buf also */ /* bit 1=0--return current font */ /* bit 1=1--return selected font for */ /* current mode */ /* bits 2-15 must be zero */ UCHAR far *pFontBuf; /* pointer to font buffer for */ /* returned font definition */ USHORT cbFontLen; /* length of font buffer or zero */ USHORT usPelColumns; /* pels per character cell in width */ /* for selected font */ USHORT usPelRows; /* pels per character cell in height */ /* for selected font */ } VDH_FONT; ulFunction GetFont in the call vector table; its value is 266L (0x010A). Return Value If it is successful, GetFont should return zero (to the ax register when coded in assembly language). Otherwise, it should return one of the following errors when it encounters any one of the following conditions: Return Conditions ──────────────────────────────────────────────────────────────────────────── ERROR_VIO_INVALID_PARMS If the ulFunction value is anything except 266L (0x010A); if the ParmBlock fsFlags value is greater than 3; if the ParmBlock cbFontLen value is zero but pFontBuf is a nonzero value; or if the pEnvironment value is zero. ERROR_INVALID_LENGTH If the ParmBlock usLength value is not 14; or if the ParmBlock cbFontLen value is too small to define a font, given the value of usPelRows. ERROR_VIO_MODE If a check of the fbType value in the environment buffer's VDHMODEINFO data indicates graphics mode. ERROR_VIO_FONT If the ParmBlock usPelColumns and usPelRows values specify a font that does not match any user, code-page, or ROM font supported in the current mode. Comments The type of adapter determines the format of the font definition. The fsFlags field may be a combination (OR) of the following values: Value Meaning ──────────────────────────────────────────────────────────────────────────── 0x0001 Read the adapter state, if possible, and update the environment buffer before returning the data. Otherwise, return data from the environment buffer. 0x0002 Return the font definition selected by the ParmBlock usPelColumns and usPelRows values. Otherwise, return the current font definition. An odd value for the fsFlags field implies that the calling application is running in the foreground. If all other ParmBlock fields are valid, GetFont should do the following: ■ Read the current or selected font from the adapter, if possible, and update the environment buffer. If the adapter is write-only, get the font definition from the environment buffer. ■ If the input cbFontLen and pFontBuf values are zero, return the buffer length needed for a font definition to cbFontLen. Otherwise, return the font definition to the buffer accessed by pFontBuf. See Also InitializeEnvironment, SetFont, SetMode, VioSetFont █ GetLVBInfo ──────────────────────────────────────────────────────────────────────────── USHORT GetLVBInfo (pEnvironment, pParmBlock, ulFunction) ENVIRONMENT far * pEnvironment; /*pointer to environment buffer */ VDH_LVB far * pParmBlock; /*pointer to parameter block */ ULONG ulFunction; /*function index */ The GetLVBInfo function returns selected information associated with an LVB (logical video buffer), such as the allocation size and default character attributes for a specified LVB. Parameters pEnvironment to the environment buffer. pParmBlock to the parameter block for GetLVBInfo, defined by the following structure: typedef struct { USHORT usLength; /* value (min. 14) selects information */ USHORT fsFlags; /* 0x0000=read from environment buf only */ /* 0x0001=read from adapter and update */ /* environment buf also */ UCHAR uchFormatID; /* 0x00=default (US) */ /* 0x70=world (international) */ /* 0x80=identical to adapter's (DBCS) */ UCHAR uchAttrCount; /* 0x01=default,0x03=world; otherwise, */ /* adapter-specific for DBCS */ USHORT usLVBWidth; /* number of cells in current mode */ USHORT usLBVHeight; /* number of cells in current mode */ ULONG ulLVBSize; /* size for current mode (returned) */ USHORT cbAttrBufSize; /* bytes in default attribute return buf */ UCHAR far *pafbAttrBufAddr; /* pointer to default attribute buf */ /* (array of char-attribute bytes) */ } VDH_LVB; ulFunction GetLVBInfo in the call vector table; its value is 279L (0x0117). Return Value If it is successful, GetLVBInfo should return zero (to the ax register when coded in assembly language). Otherwise, it should return one of the following errors when it encounters any one of the following conditions: Return Conditions ──────────────────────────────────────────────────────────────────────────── ERROR_VIO_INVALID_PARMS If the ulFunction value is anything except 279L (0x0117); if the ParmBlock fsFlags field has any of bits 1 to 15 set; if the (input) ParmBlock uchFormatID and uchAttrCount pair are mismatched (not 0x00 and 0x01, or 0x70 and 0x03); if an input, nonzero ParmBlock cbAttrBufSize value is less than the corresponding cbAttrBufSize value in the environment buffer; or if the pEnvironment value is zero. ERROR_INVALID_LENGTH If the ParmBlock usLength value is less than 14, does not fall on a ParmBlock field boundary, or is greater than 20; or if an input, nonzero ParmBlock cbAttrBufSize value is too small to return the data for an input, nonzero pafbAttrBufAddr. ERROR_VIO_MODE If a check of the fbType value in the environment buffer's VDHMODEINFO data indicates graphics mode. Comments The input ParmBlock usLength value determines how much information GetLVBInfo should return. Note that the input usLength value has a minimum of 14 and must fall on a ParmBlock field boundary (14, 16, or 20); GetLVBInfo need not attempt to return partial information in a field. The ParmBlock fsFlags value determines whether GetLVBInfo calculates the LVB information from the adapter and updates the environment buffer before returning values to the ParmBlock fields. If both the ParmBlock uchFormatID and uchAttrCount fields contain input zeros, GetLVBInfo should return the LVB allocation size values for the current mode, including the current mode's values for these two fields. GetLVBInfo should also return the current mode's value when the input ParmBlock chAttrBufSize is zero. However, an input zero for pafbAttrBufAddr indicates that GetLVBInfo need not return character-attribute data. If the input values for cbAttrBufSize and pafbAttrBufAddr are nonzero, GetLVBInfo must check the cbAttrBufSize value and return an error when this value is too small to return all the attribute data. The adapter-specific uchFormatID value 0x80 requires the BVH to set a corresponding value for its default uchAttrCount. By convention, this value represents the number of attribute bytes per character byte for BVHs that support DBCS (double-byte character set) text display. See Also GetMode, InitializeEnvironment █ GetMode ──────────────────────────────────────────────────────────────────────────── USHORT GetMode (pEnvironment, pParmBlock, ulFunction) ENVIRONMENT far * pEnvironment; /*pointer to environment buffer */ VDH_MODE far * pParmBlock; /*pointer to parameter block */ ULONG ulFunction; /*function index */ The GetMode function returns the current video mode information. Parameters pEnvironment to the environment buffer. pParmBlock to the parameter block for GetMode, defined as the following structure: typedef struct { USHORT usLength; /* ParmBlock = 8 bytes */ USHORT fsFlags; /* bit 0=0--get from environment buf */ /* bit 0=1--get from adapter, if */ /* possible, and update */ /* environment buf also */ /* bits 1-15 must be zero (reserved) */ PVIOMODEINFO; /* pointer to VIOMODEINFO data */ } VDH_MODE; ulFunction GetMode in the call vector table; its value is 268L (0x010C). Return Value If it is successful, GetMode should return zero (to the ax register when coded in assembly language). Otherwise, it should return one of the following errors when it encounters any one of the following conditions: Return Conditions ──────────────────────────────────────────────────────────────────────────── ERROR_VIO_INVALID_PARMS If the ulFunction value is anything except 268L (0x010C); if the ParmBlock fsFlags value is greater than 1; or if the pEnvironment value is zero. ERROR_INVALID_LENGTH If the ParmBlock usLength value is not 8; or if the calling application's mode data (pointed to by the ParmBlock PVIOMODEINFO field) has a cb length value that is not 2 or is not at least 34. Comments The GetMode function returns the current mode settings to the buffer accessed by ParmBlock PVIOMODEINFO. This pointer must access a buffer that specifies a cb length value that is either 2 or at least the length of the _VDHMODEINFO structure (34) when GetMode is called. If the cb value is 2 or greater than the largest possible length, GetMode returns the length of the _VDHMODEINFO structure to the cb field. The _VDHMODEINFO structure is equivalent to VIOMODEINFO. An odd value for the fsFlags field implies that the calling application is running in the foreground. In this case, GetMode should do the following: ■ Read in the current mode settings from the adapter, if possible. ■ Update the mode data in the environment buffer with these settings and return the information to the buffer accessed by PVIOMODEINFO. If the adapter is write-only or if the fsFlags field is zero, GetMode must return values from the environment buffer. See Also InitializeEnvironment, SetMode, VioGetMode █ GetPaletteRegisters ──────────────────────────────────────────────────────────────────────────── USHORT GetPaletteRegisters (pEnvironment, pParmBlock, ulFunction) ENVIRONMENT far * pEnvironment; /*pointer to environment buffer */ VDH_PALET far * pParmBlock; /*pointer to parameter block */ ULONG ulFunction; /*function index */ The GetPaletteRegisters function reads a specified number of palette register settings from the adapter or from the environment buffer into the palette buffer. Parameters pEnvironment to the environment buffer. pParmBlock to the parameter block for GetPaletteRegisters, defined as the following structure: typedef struct { USHORT usLength; /* ParmBlock = 12 bytes */ USHORT fsFlags; /* 0x0000=read environment buf only */ /* 0x0001=read adapter's palette regs*/ /* if possible, and update */ /* environment buffer's pointer to */ USHORT far *pPalDataBuf; /* palette buffer (array) */ USHORT iFirstEntry; /* index of first register to read */ USHORT usNumEntries; /* number of entries to read in */ } VDH_PALETTE; ulFunction GetPaletteRegisters in the call vector table; its value is 270L (0x010E). Return Value If it is successful, GetPaletteRegisters should return zero (to the ax register when coded in assembly language). Otherwise, it should return one of the following errors when it encounters any one of the following conditions: Return Conditions ──────────────────────────────────────────────────────────────────────────── ERROR_VIO_INVALID_PARMS If the ulFunction value is anything except 270L (0x010E); if the ParmBlock fsFlags value is greater than 1; if the ParmBlock iFirstEntry value is outside the range of index values for the palette registers; if the ParmBlock usNumEntries is less than 1; or if the pEnvironment value is zero. ERROR_INVALID_LENGTH If the ParmBlock usLength value is not 12; or if the ParmBlock usNumEntries value is too large, either greater than the number of entries in the palette buffer array or greater than the total entries following iFirstEntry. Comments An odd value for the fsFlags field implies that the calling application is running in the foreground. If all ParmBlock fields are valid, GetPaletteRegisters should do the following: ■ Read the specified range of palette-register settings into the corresponding area of the environment buffer, if possible. ■ Update the palette buffer with these settings. If the adapter is write-only or if the input fsFlags field is zero, GetPaletteRegisters must return values from the environment buffer. The ParmBlock pPalDataBuf field points to a buffer that is an array of USHORT values. The GetPaletteRegisters function should not change the video-enable state of the adapter. See Also SetPaletteRegisters, VioSetState █ GetPhysBuf ──────────────────────────────────────────────────────────────────────────── USHORT GetPhysBuf (pEnvironment, pParmBlock, ulFunction) ENVIRONMENT far * pEnvironment; /*pointer to environment buffer */ VDH_GETPVB far * pParmBlock; /*pointer to parameter block */ ULONG ulFunction; /*function index */ The GetPhysBuf function returns one or more LDT (local descriptor table) selectors that access the physical video buffer in 64K-sized blocks. Unless a specific address range is requested, this function returns selectors to the current PVB (physical video buffer). Parameters pEnvironment to the environment buffer. pParmBlock to the parameter block for GetPhysBuf, defined by the following structure: typedef struct { USHORT usLength; /* ParmBlock = 8 bytes */ USHORT fsFlags; /* must be zero */ PVIOPHYSBUF pPVBDataPTR; /* pointer to VDHVIOPHYSBUF */ /* or to ALT_VIOPHYSBUF data */ } VDH_GETPVB; ulFunction GetPhysBuf in the call vector table; its value is 272L (0x0110). Return Value If it is successful, GetPhysBuf should return zero (to the ax register when coded in assembly language). Otherwise, it should return one of the following errors when it encounters any one of the following conditions: Return Conditions ──────────────────────────────────────────────────────────────────────────── ERROR_VIO_INVALID_PARMS If the ulFunction value is anything except 272L (0x0110); if the ParmBlock fsFlags value is nonzero; or if the pEnvironment value is zero. ERROR_INVALID_LENGTH If the ParmBlock usLength value is not 8. ERROR_VIO_PTR If the input physical address is outside the valid range for the device. Comments VDHVIOPHYSBUF and ALT_VIOPHYSBUF contain the MS OS/2 version 1.2 VIOPHYSBUF structure. PVIOPHYSBUF is a far pointer to the VDHVIOPHYSBUF structure, defined as follows: struct _VDHVIOPHYSBUF { PBYTE pBuf; /* 32-bit pointer to PVB */ ULONG cb; /* length in bytes of PVB */ SEL aSel[4]; /* array of max=4 selectors */ }; However, if the application passes a length value of zero for VIOPHYSBUF, PVIOPHYSBUF points to the ALT_VIOPHYSBUF structure, defined as follows: typedef struct { USHORT cb; /* length in bytes of PBV */ SEL aSel[2]; /* array of max=2 selectors */ } ALT_VIOPHYSBUF; If the PVB address and length passed on input are zero, this function should return one or more LDT selectors that correspond to the adapter's current mode, which the BVH can obtain from the environment buffer. If the input PVB address is nonzero, the BVH should do one of the following: ■ Provide read/write access to the physical-address range where the PVB is located (within 0xA0000 to 0xBFFFF). ■ Provide read-only access to the physical-address range where the ROM fonts are located (within 0x00000 to 0xFFFFF). ■ Return an error if the input physical address is not within the PVB or ROM-font ranges. GetPhysBuf may obtain the LDT selector(s) from the base device driver named screen$, as follows: ■ Call the DosOpen or DosOpen2 function to obtain a handle for the base screen device driver. ■ Call the DosDevIOCtl or DosDevIOCtl2 function with the input physical address, the screen-driver handle, and either of the IOCtl code combinations category 0x0003 and function 0x0070, or category 0x0003 and function 0x0075. The category 0x0003 IOCtl function 0x0070 returns a 16-bit selector. Function 0x0075 returns a 16-bit selector with an offset; this function enhances the portability of BVH components that use it. The base screen driver must return a selector with the correct access rights for valid PVB or ROM-font addresses, or it returns an error in the ax register. For more information about the DosOpen, DosOpen2, DosDevIOCtl, and DosDevIOCtl2 functions, see Appendix C, "Dos Functions for Installable Device Drivers." Note that a BVH dynamic-link library component runs at ring-2, not at ring-0, so it can call these functions after the BVH is installed. Otherwise, the GetPhysBuf function must have support from a BVH ring-0 component that calls the DevHlp routine PhysToUVirt to convert the input physical address into an LDT selector with the correct access rights. Note that a ring-0 support routine must check that the input physical address is within the PVB or ROM-font range before it calls PhysToUVirt. For more information about PhysToUVirt, see Chapter 3, "Device Helper Services." See Also FreePhysBuff, VioGetPhysBuf █ GetVariableInfo ──────────────────────────────────────────────────────────────────────────── USHORT GetVariableInfo (pEnvironment, pParmBlock, ulFunction) ENVIRONMENT far * pEnvironment; /*pointer to environment buffer */ VDH_VARIABLE far * pParmBlock; /*pointer to parameter block */ ULONG ulFunction; /*function index */ The GetVariableInfo function returns information about selected features of the video adapter, including the blink state, overscan (border color), underscore line, video enable, plane enable, code page, scrollable rectangle, and the number of text rows and columns of the display. Parameters pEnvironment to the environment buffer. pParmBlock to the parameter block for GetVariableInfo, defined by the following structure: typedef struct { USHORT usLength; /* value (6-30) selects information */ USHORT fsFlags; /* 0x0000=read from environment buf only,*/ /* 0x0001=read from hardware, if possible*/ /* bits 1-15 must be zero */ USHORT fsBlink; /* 0x0000=blink highlights selected cell */ /* 0x0001=background intensity highlights*/ USHORT usOverscan; /* border color */ USHORT usUnderscore; /* n=scan line for underscore (n=0-31), */ /* 32=no underscore */ USHORT fsVideoEnable; /* 0x0000=disabled,0x0001=enabled */ ULONG flDisplayMask; /* bit n=1 implies plane n enabled */ /* (n=0-31); otherwise, plane n disabled */ USHORT usCodePageID; /* current ROM-font or user-font ID */ USHORT usScrlLeft; /* 0=leftmost column of current mode's */ /* scrollable rectangle */ USHORT usSrclTop; /* 0=top row */ USHORT usScrlRight; /* right column */ USHORT usSrclBottom; /* bottom row */ USHORT usScreenRows; /* number of rows in current mode */ USHORT usScreenColumns; /* number of columns in current mode */ } VDH_VARIABLE; ulFunction GetVariableInfo in the call vector table; its value is 274L (0x0112). Return Value If it is successful, GetVariableInfo should return zero (to the ax register when coded in assembly language). Otherwise, it should return one of the following errors when it encounters any one of the following conditions: Return Conditions ──────────────────────────────────────────────────────────────────────────── ERROR_VIO_INVALID_PARMS If the ulFunction value is anything except 274L (0x0112); if the ParmBlock usFlags field has any of bits 1 through 15 set; or if the pEnvironment value is zero. ERROR_INVALID_LENGTH If the ParmBlock usLength value is less than 6, does not fall on a ParmBlock field boundary, or is greater than 30; or if GetVariableInfo reads in a field value that is out of range for the current mode. ERROR_VIO_MODE If a check of the fbType value in the environment buffer's VDHMODEINFO data indicates graphics mode. Comments The input value for the usLength field determines how much information GetVariableInfo should return. Note that the input usLength value must fall on a ParmBlock field boundary (6, 8, 10, 12, 16, 18, ...); GetVariableInfo need not attempt to return partial information in a field. An odd value for the fsFlags field implies that the calling application is running in the foreground. In this case, GetVariableInfo should do the following: ■ Read the information in from the adapter, if possible. A BVH for a write-only adapter must get information from the environment buffer. ■ Update the environment buffer with information that is read from the adapter. ■ Return information to the appropriate fields of ParmBlock. The GetVariableInfo function should return 32 to the usUnderscore field when there is no underscore. If the usLength value is 18 or more, a BVH that does not support an 8514-compatible adapter may ignore the flDisplayMask field. See Also GetMode, SetVariableInfo, TextBufferUpdate (Scrolls) █ InitializeEnvironment ──────────────────────────────────────────────────────────────────────────── USHORT InitializeEnvironment (pEnvironment, pParmBlock, ulFunction) ENVIRONMENT far * pEnvironment; /*pointer to environment buffer */ VDH_ENVRN far * pParmBlock; /*pointer to parameter block */ ULONG ulFunction; /*function index */ The InitializeEnvironment function sets up the environment buffer and optionally the adapter state for a new session. Parameters pEnvironment to the environment buffer. pParmBlock to the parameter block for InitializeEnvironment, defined as the following structure: typedef struct { USHORT usLength; /* ParmBlock = 6 bytes */ USHORT fsFlags; /* bit 0=0--init envirn buf only */ /* bit 0=1--init adapter state also */ /* bit 1=0--3xBox not being */ /* initialized /* bit 1=1--3xBox being initialized */ /* bits 2-15 must be zero (reserved) */ USHORT selLVBSel; /* huge (max 1MB) LVB selector */ } VDH_ENVRN; ulFunction InitializeEnvironment in the call vector table; its value is 257L (0x0101). Return Value If it is successful, InitializeEnvironment should return zero (to the ax register when coded in assembly language). Otherwise, it should return one of the following errors when it encounters any one of the following conditions: Return Conditions ──────────────────────────────────────────────────────────────────────────── ERROR_VIO_INVALID_PARMS If the ulFunction value is anything except 257L (0x0101); if the ParmBlock fsFlags value is greater than 3; or if the pEnvironment value is zero. ERROR_INVALID_LENGTH If the ParmBlock usLength value is not 6. Comments The BVH determines the size of its environment buffer. The maximum size is one megabyte, so the pEnvironment value is a huge selector. The layout of data in the environment buffer is, to a certain extent, adapter-specific. However, all MS OS/2 version 1.2 adapters use an environment buffer that contains the data defined in the following structure: typedef struct { USHORT usModeDataOff; /* offset to _VDHMODEINFO data */ UCHAR iModeIndex; /* indexes current mode */ UCHAR iROMFontIndex /* index in ROM font table */ _VDHMODEINFO ModeData; /* identical to VIOMODEINFO */ SCROLRECT ScrollRect; /* scrollable area of screen, */ /* defined as 0x0000=leftmost */ /* column,0x0000=topmost row, */ /* rightmost col and bottom row*/ /* are adapter-dependent */ /*********************************/ /* ScrollRect MUST follow */ /* ModeData */ /*********************************/ USHORT cbAttrBufSize; /* char-attribute bytes in */ /* current mode */ UCHAR uchAttrBuf[4]; /* default for current mode */ /* (2 or 4 bytes) */ USHORT fsEnvFlags; /* flag for this environment, */ /* 0x0001=3xBox, default zero */ USHORT usCursorAttributes;/* 0xFFFF=hidden, otherwise */ /* value (default) and visible */ HWREGS Hardware; /* adapter's registers */ USHORT fsVideoEnable; /* 0x0001=enabled,0x0000=disabled*/ UCHAR far *pActiveFontPTR; /* to currently active font */ SHORT sCodePageID; /* current code-page number or */ /* 0x0000=not selectable */ SHORT sUserFont; /* -1=selectable,-2=not selectabl*/ /*****************************************************************/ /* The following fields are defined only if the BVH supports */ /* user-defined fonts; these fields MUST be last in environment */ /* buffer, so that the user-font table is expandable */ /*****************************************************************/ USHORT usNumUserFonts; /* number of entries in array */ USHORT UserFonts; /* first entry, user-font */ /* definitions */ } VDH_ENVIRONMENT; Note that this structure contains a copy of the _VDHMODEINFO structure, that the scrollable-text region of the screen must be defined following the mode data, and that user-font definitions, if supported, must be the located at the end of the environment buffer. If a BVH must add adapter-specific data areas in the environment buffer or if it is chained to another BVH, it may modify the VDH_ENVIRONMENT structure in one of the following ways: ■ Define all new fields and append VDH_ENVIRONMENT as the last field of the adapter-specific structure if the BVH supports user-defined fonts. ■ Add new fields at the end of VDH_ENVIRONMENT if the BVH does not support user-defined fonts. ■ Insert new fields into VDH_ENVIRONMENT without separating the mode information from the scrollable-rectangle data and without separating a "length" field from the following field or buffer (for example, uchAttrBufSize belongs with uchAttrBuf[4]). A chained BVH must allocate an environment buffer that contains the chainee's VDH_ENVIRONMENT as a proper subset. For more information about chained BVHs, see Section 4.2.3. InitializeEnviroment sets up the default mode data, active font support (ROM or code page), cursor attributes, video enable, and scrollable rectangle for each session. A BVH need not support any scrollable region other than the entire display area, but it may limit the scrollable area. Bit 1 of the fsFlags field tells the BVH whether a DOS real-mode session (3xBox) is also being initialized for the new session. A BVH saves and restores a DOS session as a part of the physical display, but it provides no other support for DOS applications since BVHs run only in protected mode. An odd value for the fsFlags field implies that the new session will run in the foreground. In this case, InitializeEnvironment also must set up the adapter state, not just the environment buffer, for the new session. A BVH that supports DBCS (double-byte character set) code pages or DBCS user-defined fonts must maintain an LVB (logical video buffer) that maps to (or "shadows") its PVB (physical video buffer) for each active session. The selLVBSel field should access an LVB in the world-wide format, if possible. For more information about world-wide LVB format, see Section 4.4.2. A BVH that supports only SBCS (single-byte character set) fonts may maintain an LVB that shadows its PVB, but it need not do so. MS OS/2 allocates the buffer accessed by selLVBSel by calling the DosAllocHuge function. The BVH must define the number of huge selectors it needs to shadow or to save the display when it initializes at system boot. For the InitializeEnvironment function, the selLVBSel accesses the first segment of the buffer. To calculate the selector value for each segment following selLVBSel, use the value returned by the DosGetHugeShift function. See Also DosAllocHuge, DosGetHugeShift, RestoreEnvironment, SaveEnvironment, SetMode, SetVariableInfo, TerminateEnvironment, VioSetMode █ PrintScreen ──────────────────────────────────────────────────────────────────────────── USHORT PrintScreen (pEnvironment, pParmBlock, ulFunction) ENVIRONMENT far * pEnvironment; /*pointer to environment buffer */ VDH_PRTSCRN far * pParmBlock; /*pointer to parameter block */ ULONG ulFunction; /*function index */ The PrintScreen function writes the contents of the current screen to the specified printer. Parameters pEnvironment to the environment buffer. pParmBlock to the parameter block for PrintScreen, defined as the following structure: typedef struct { USHORT usLength; /* ParmBlock = 8 bytes */ USHORT fsFlags; /* 0x0000=print LVB contents only */ /* 0x0001=print PVB contents */ /* bits 1-15 must be zero */ USHORT selLVBSel; /* huge (max 1MB) LVB selector */ USHORT hfPrinter; /* printer-device handle */ } VDH_PRTSCRN; ulFunction PrintScreen in the call vector table; its value is 277L (0x0115). Return Value If it is successful, PrintScreen should return zero (to the ax register when coded in assembly language). Otherwise, it should return one of the following errors when it encounters any one of the following conditions: Return Conditions ──────────────────────────────────────────────────────────────────────────── ERROR_VIO_INVALID_PARMS If the BVH provides a PrintScreen function and if the ulFunction value is anything except 277L (0x0115); if the ParmBlock fsFlags value is greater than 1; or if the pEnvironment value is zero. ERROR_INVALID_LENGTH If the ParmBlock usLength value is not 8. ERROR_VIO_MODE If a check of the fbType value in the environment buffer's VDHMODEINFO data indicates graphics mode. Comments A PrintScreen function is optional. Most BVHs can use the default print-screen support provided by BVS. BVS supplies a default (text-mode) print-screen routine with the same level of support as MS OS/2 version 1.1. The default BVS routine must be called by the currently active (foreground) session. A BVH may supply a PrintScreen of its own to replace the default BVS routine if its adapter has unique print-screen needs. The PrintScreen function may check the environment buffer to determine whether a DOS real-mode session (3xBox) was initialized for the session it will print. This function may call DosBeep if it cannot open the printer and if it runs at ring-3 (application privilege level). See Also WriteTTY █ RestoreEnvironment ──────────────────────────────────────────────────────────────────────────── USHORT RestoreEnvironment (pEnvironment, pParmBlock, ulFunction) ENVIRONMENT far * pEnvironment; /*pointer to environment buffer */ VDH_ENVRN far * pParmBlock; /*pointer to parameter block */ ULONG ulFunction; /*function index */ The RestoreEnvironment function restores one or more of the adapter state and the full physical display or partial physical display when a session switch is about to occur. Parameters pEnvironment to the environment buffer. pParmBlock to the parameter block for RestoreEnvironment, defined as the following structure: typedef struct { USHORT usLength; /* ParmBlock = 6 bytes */ USHORT fsFlags; /* bit 0 must be zero (reserved) */ /* bit 1=0--do not restore adapter */ /* state */ /* bit 1=1--restore adapter state */ /* bit 2=0--do not restore full */ /* physical display */ /* bit 2=1--restore full physical */ /* display */ /* bit 3=0--do not restore partial */ /* physical display */ /* bit 3=1--restore partial physical */ /* display (popup window) */ /* bits 4-15 must be zero (reserved) */ USHORT selLVBSel; /* huge (max 1MB) LVB selector */ } VDH_ENVRN; ulFunction RestoreEnvironment in the call vector table; its value is 259L (0x0103). Return Value If it is successful, RestoreEnvironment should return zero (to the ax register when coded in assembly language). Otherwise, it should return one of the following errors when it encounters any one of the following conditions: Return Conditions ──────────────────────────────────────────────────────────────────────────── ERROR_VIO_INVALID_PARMS If the ulFunction value is anything except 259L (0x0103); if the ParmBlock fsFlags field has both bits 2 and 3 set, or if it has any of bits 4 to 15 or 0 set; or if the pEnvironment value is zero. ERROR_INVALID_LENGTH If the ParmBlock usLength value is not 6. ERROR_VIO_MODE If RestoreEnvironment fails to restore the adapter state and/or display from the environment buffer. Comments Bits 2 and 3 of the fsFlags field are mutually exclusive. Otherwise, this field may be a combination (OR) of the following values: Value Meaning ──────────────────────────────────────────────────────────────────────────── 0x0002 Restore the adapter state. Otherwise, restore only one of the full or partial physical display. 0x0004 Restore the full physical display for a session switch, provided that bit 3 is clear. 0x0008 Restore the partial physical display for a popup window, provided that bit 2 is clear. In most cases, the input selLVBSel field accesses the first of the segments that map to a full or partial display state. To calculate the selector value for each segment following selLVBSel, use the value returned by the DosGetHugeShift function. However, RestoreEnvironment can be called for an environment that has never been saved. For example, RestoreEnvironment must handle the situation when InitializeEnvironment has set up the environment, but the SaveEnvironment function has never been called for a given session. See Also DosAllocHuge, DosGetHugeShift, InitializeEnvironment, SaveEnvironment █ RetConfigInfo ──────────────────────────────────────────────────────────────────────────── USHORT RetConfigInfo (pEnvironment, pParmBlock, ulFunction) ENVIRONMENT far * pEnvironment; /*pointer to environment buffer */ VDH_CONFIG far * pParmBlock; /*pointer to parameter block */ ULONG ulFunction; /*function index */ The RetConfigInfo function returns all of the information necessary to identify the current video adapter and display. Parameters pEnvironment to the environment buffer. This address should be zero for the RetConfigInfo function. pParmBlock to the parameter block for RetConfigInfo, defined as the following structure: typedef struct { USHORT usLength; /* ParmBlock = 8 bytes */ USHORT fsFlags; /* must be zero */ VDHCONFIGINFO far *pConfigData; /* pointer to config info data */ } VDH_CONFIG; ulFunction RetConfigInfo in the call vector table; its value is 260L (0x0104). Return Value If it is successful, RetConfigInfo should return zero (to the ax register when coded in assembly language). Otherwise, it should return one of the following errors when it encounters any one of the following conditions: Return Conditions ──────────────────────────────────────────────────────────────────────────── ERROR_VIO_INVALID_PARMS If the ulFunction value if not 260L (0x0104); if the ParmBlock fsFlags value is not zero; or if the pEnvironment value is not zero. ERROR_INVALID_LENGTH If the ParmBlock usLength value is not 8; or if the cb length value (in VDHCONFIGINFO) is less than 2. Comments This function does not use the environment buffer, so the pEnvironment address value should be zero. The VDHCONFIGINFO structure contains the MS OS/2 version 1.2 VIOCONFIGINFO structure. Your VDHCONFIGINFO must contain at least the first twelve fields that are defined in the following structure: typedef struct { USHORT cb ; /* length of structure (min = 34, */ /* max = 42 bytes) */ USHORT usAdapter; /* display-adapter type: 0=MPA,1=CGA, */ /* 2=EGA,3=VGA or PS/2,4=IBMJapanG, */ /* 5=IBMJapanH,6=IBMJapanST,7=8514a */ USHORT usDisplay; /* display-monitor type: 0=5051mono, */ /* 1=5153color,2=5154enhanced, */ /* 4=8512/8513color,5=Japan5550mono, */ /* 6=Japan5550color,7=Japan5570color, */ /* 8=Japan5570fullpage,9=8514color */ ULONG cbMemory; /* adapter's memory (in bytes) */ USHORT usConfiguration; /* should be 0=unknown */ USHORT usDeviceDriver; /* DD version number */ USHORT usFlags; /* 1=boot-up display, 0=other */ ULONG ulHWBufferSize; /* sizeof HW state buff in bytes */ ULONG ulFullSaveSize; /* sizeof PVB for current mode */ ULONG ulPartSaveSize; /* sizeof PVB for popup mode */ USHORT usEMAdaptersOFF; /* offset to usLEMulatedAdapterData */ USHORT usEMDisplaysOFF; /* offset to usLEMulatedDisplayData */ /* preceding fields are required, */ /* following fields may follow your */ /* VDHCONFIGINFO in same data segment */ USHORT usLEMAdapterData; /* length of emulated-adapter data */ USHORT usEMAdapters; /* AND mask 0x008F extracts standard */ /* US adapter types emulated */ USHORT usLEMDisplayData; /* length of emulated-display data */ USHORT usEMDisplays; /* AND mask 0x021F extracts standard */ /* US display types emulated */ } VDHCONFIGINFO; You may define the last four fields of VDHCONFIGINFO in one or two separate data structures for emulated adapters and displays. If you do, the following constraints apply for these structures: ■ The emulated-adapter data and emulated-display data structure(s) must be defined in the same data segment following your VDHCONFIGINFO structure. ■ The usEMAdaptersOFF field of your VDHCONFIGINFO must contain the offset, in bytes, to the length field of your emulated-adapter data structure. ■ The usEMDisplaysOFF field of your VDHCONFIGINGO must contain the offset, in bytes, to the length field of your emulated-display data structure. If the length specified for the first field of VDHCONFIGINFO either is 2 or is larger than the maximum possible length (42 bytes), RetConfigInfo should replace this value with the largest valid length. See Also VioGetConfig █ SaveEnvironment ──────────────────────────────────────────────────────────────────────────── USHORT SaveEnvironment (pEnvironment, pParmBlock, ulFunction) ENVIRONMENT far * pEnvironment; /*pointer to environment buffer */ VDH_ENVRN far * pParmBlock; /*pointer to parameter block */ ULONG ulFunction; /*function index */ The SaveEnvironment function saves one or more of the adapter state and the full physical display or the partial physical display when a session switch is about to occur. Parameters pEnvironment to the environment buffer. pParmBlock to the parameter block for SaveEnvironment, defined as the following structure: typedef struct { USHORT usLength; /* ParmBlock = 6 bytes */ USHORT fsFlags; /* bit 0 must be zero (reserved) */ /* bit 1=0--do not save adapter state */ /* bit 1=1--save adapter state */ /* bit 2=0--do not save full physical */ /* display */ /* bit 2=1--save full phys. display */ /* bit 3=0--do not save partial */ /* physical display */ /* bit 3=1--save partial physical */ /* display (popup window) */ /* bits 4-15 must be zero (reserved) */ USHORT selLVBSel; /* huge (max 1MB) LVB selector */ } VDH_ENVRN; ulFunction SaveEnvironment in the call vector table; its value is 258L (0x0102). Return Value If it is successful, SaveEnvironment should return zero (to the ax register when coded in assembly language). Otherwise, it should return one of the following errors when it encounters any one of the following conditions: Return Conditions ──────────────────────────────────────────────────────────────────────────── ERROR_VIO_INVALID_PARMS If the ulFunction value is anything except 258L (0x0102); if the ParmBlock fsFlags field has both bits 2 and 3 set, or if it has any of bits 4 to 15 or 0 set; or if the pEnvironment value is zero. ERROR_INVALID_LENGTH If the ParmBlock usLength value is not 6. ERROR_VIO_MODE If SaveEnvironment fails to save the adapter state and/or display buffer in the environment buffer. Comments Bits 2 and 3 of the fsFlags field are mutually exclusive. Otherwise, this field may be a combination (OR) of the following values: Value Meaning ──────────────────────────────────────────────────────────────────────────── 0x0002 Save the adapter state, including everything except the PVB. Otherwise, save only one of the full or partial display. 0x0004 Save the full display for a session switch, provided that bit 3 is clear. 0x0008 Save the partial display (area overwritten) for a popup window, provided that bit 2 is clear. MS OS/2 allocates the LVB and (environment buffer) by calling the DosAllocHuge function. The BVH must define the number of huge selectors it requires for a full-display save and for a partial-display save when it initializes at system boot. The ParmBlock selLVBSel field accesses the first of the segments in which SaveEnvironment shadows or stores the display. To calculate the selector value for each segment following selLVBSel, use the value returned by the DosGetHugeShift function. A BVH must save whatever portion of the display could be overlaid by a popup window. When a hard-error popup occurs before a VIO popup has been cleared, BVS calls SaveEnvironment twice before calling the RestoreEnvironment function. For this reason, the SaveEnvironment function must be prepared to handle both a partial save of a graphics-mode popup and a full save of a text-mode user popup. A BVH may set its partial-save size to zero only if its display cannot be overlaid by a popup window. If the BVH initialized the environment for a session that has a DOS real-mode session (3xBox) present on the display, SaveEnviroment must also do one of the following when bit 1 of the fsFlags field is set: ■ Read in the adapter's state, update the environment buffer, and update the video BIOS data area (based at 0x0040:0000) for the DOS session. ■ If the adapter is write-only, copy the DOS session's information from the video BIOS data area to the environment buffer. Note that SaveEnvironment must obtain selector:offset access to the video BIOS data area in order to do this. BVHs run only in protected mode. See Also DosAllocHuge, DosGetHugeShift, InitializeEnvironment, RestoreEnvironment █ SetColorLookup ──────────────────────────────────────────────────────────────────────────── USHORT SetColorLookup (pEnvironment, pParmBlock, ulFunction) ENVIRONMENT far * pEnvironment; /*pointer to environment buffer */ VDH_CLUT far * pParmBlock; /*pointer to parameter block */ ULONG ulFunction; /*function index */ The SetColorLookup function sets a specified number of colors from the color lookup table for VGA-type or VGA-compatible adapters. Parameters pEnvironment to the environment buffer. pParmBlock to the parameter block for SetColorLookup, defined as the following structure: typedef struct { USHORT usLength; /* ParmBlock = 12 bytes */ USHORT fsFlags; /* 0x0000=set environment buffer only*/ /* 0x0001=set adapter and environ buf*/ CLUTDATA far *pLookupTable /* pointer to device-dependent CLUT */ USHORT iFirstEntry; /* index to first entry to set */ USHORT usNumEntries; /* how many entries to set */ } VDH_CLUT; ulFunction SetColorLookup in the call vector table; its value is 263L (0x0107). Return Value If it is successful, SetColorLookup should return zero (to the ax register when coded in assembly language). Otherwise, it should return one of the following errors when it encounters any one of the following conditions: Return Conditions ──────────────────────────────────────────────────────────────────────────── ERROR_VIO_INVALID_PARMS If the ulFunction value is anything except 263L (0x0107); if the ParmBlock fsFlags value is greater than 1; if the ParmBlock iFirstEntry value is outside the range of entries in the color lookup table; if the ParmBlock usNumEntries value is less than 1; or if the pEnvironment value is zero. ERROR_INVALID_LENGTH If the ParmBlock usLength value is not 12; or if the ParmBlock usNumEntries value is too large, either greater than the number of entries in the color lookup table or greater than the total entries following iFirstEntry. Comments Only BVHs that support VGA-type adapters need supply a SetColorLookup function. An odd value for the fsFlags field implies that the calling application is running in the foreground. If all ParmBlock fields are valid, SetColorLookup should do the following: ■ Load the specified range of entries from the color lookup table into the adapter's color registers. ■ Update the environment buffer's color lookup table with these settings also. If the fsFlags value is zero, SetColorLookup sets values only in the environment buffer. The format of the color lookup table is device-dependent. For example, the following structure defines the format of each entry in the color lookup table for a VGA adapter: typedef struct { UCHAR uchRed; /* color index */ UCHAR uchGreen; UCHAR uchBlue; } CLUTDATA_VGA; The VGA format has three bytes containing, respectively, the red, green, and blue indices for each color being set. See Also GetColorLookup █ SetCursorInfo ──────────────────────────────────────────────────────────────────────────── USHORT SetCursorInfo (pEnvironment, pParmBlock, ulFunction) ENVIRONMENT far * pEnvironment; /*pointer to environment buffer */ VDH_CURSOR far * pParmBlock; /*pointer to parameter block */ ULONG ulFunction; /*function index */ The SetCursorInfo function sets selected information about the cursor's position, its type, or both. Parameters pEnvironment to the environment buffer. pParmBlock to the parameter block for SetCursorInfo, defined as the following structure: typedef struct { USHORT usLength; /* ParmBlock = 16 bytes */ USHORT fsFlags; /* bit 0=0--set environ buf only */ /* bit 0=1--set HW state also */ /* bit 1=1--set cursor position */ /* bit 2=1--set cursor type */ /* bits 3-15 must be zero */ USHORT usRow; /* 0=top row */ USHORT usColumn; /* 0=leftmost column */ USHORT usTopScanLine; /* 0=top scan line of n scan */ USHORT usBottomScanLine; /* lines,(n-1)=bottom scan line */ USHORT usWidth; /* in columns for text mode */ USHORT usAttribute; /* -1=hidden for text mode */ } VDH_CURSOR; ulFunction SetCursorInfo in the call vector table; its value is 265L (0x0109). Return Value If it is successful, SetCursorInfo should return zero (to the ax register when coded in assembly language). Otherwise, it should return one of the following errors when it encounters any one of the following conditions: Return Conditions ──────────────────────────────────────────────────────────────────────────── ERROR_VIO_INVALID_PARMS If the ulFunction value is anything except 265L (0x0109); if the ParmBlock fsFlags value is greater than 7; if the ParmBlock usTopScanLine or usBottomScanLine values are out of range; or if the pEnvironment value is zero. ERROR_INVALID_LENGTH If the ParmBlock usLength value is not 16. ERROR_VIO_MODE If a check of the fbType value in the environment buffer's VDHMODEINFO data indicates graphics mode. ERROR_VIO_ROW If the value of ParmBlock usRow is out of range for the current mode. ERROR_VIO_COLUMN If the value of ParmBlock usColumn is out of range for the current mode. ERROR_VIO_WIDTH If the value of ParmBlock usWidth is greater than 1. Comments The ParmBlock usRow and usColumn fields contain the cursor-position information. The fsFlags field may be a combination (OR) of the following values: Value Meaning ──────────────────────────────────────────────────────────────────────────── 0x0001 Set values in the adapter and in the enviroment buffer. Otherwise, set values in the environment buffer only. 0x0002 Set the cursor position values. 0x0004 Set the cursor type values. If the value of fsFlags is one or zero, SetCursorInfo should return success without updating the adapter or environment buffer. Note that an odd value for fsFlags implies that the calling application is running in the foreground and that the hardware state and environment buffer should be updated with new cursor settings. Before writing the input usRow and usColumn values, SetCursorInfo should check ranges as follows: ■ If the fsFlags value is odd, use the adapter's settings to determine whether the row and column values are in range. ■ If the fsFlags value is even, use the environment buffer's settings to determine whether the row and column values are in range. The ParmBlock usWidth value must be 1 in text mode. See Also GetCursorInfo, SetModeInfo, VioSetCurPos, VioSetCurType █ SetFont ──────────────────────────────────────────────────────────────────────────── USHORT SetFont (pEnvironment, pParmBlock, ulFunction) ENVIRONMENT far * pEnvironment; /*pointer to environment buffer */ VDH_FONT far * pParmBlock; /*pointer to parameter block */ ULONG ulFunction; /*function index */ The SetFont function sets up a new user-font definition. Then, SetFont either resets the current font in the environment buffer, or it loads a user-defined, code-page, or ROM font that is compatible with the current mode into the adapter and updates the environment buffer. Parameters pEnvironment to the environment buffer. pParmBlock to the parameter block for SetFont, defined as the following structure: typedef struct { USHORT usLength; /* ParmBlock = 14 bytes */ USHORT fsFlags; /* 0x0000=update environment buf only*/ /* 0x0001=update adapter state also */ /* bits 1-15 must be 0 (reserved) */ UCHAR far *pFontBuf; /* pointer to font buffer data */ USHORT cbFontLen; /* length of font buffer */ USHORT usPelColumns; /* pels per character cell in width */ USHORT usPelRows; /* pels per character cell in height */ } VDH_FONT; ulFunction SetFont in the call vector table; its value is 267L (0x010B). Return Value If it is successful, SetFont should return zero (to the ax register when coded in assembly language). Otherwise, it should return one of the following errors when it encounters any one of the following conditions: Return Conditions ──────────────────────────────────────────────────────────────────────────── ERROR_VIO_INVALID_PARMS If the ulFunction value is anything except 267L (0x010B); if the ParmBlock fsFlags value is greater than 1; or if the pEnvironment value is zero. ERROR_INVALID_LENGTH If the ParmBlock usLength value is not 14; or if the ParmBlock cbFontLen value is too small to define a user font, given the value of usPelRows. ERROR_VIO_MODE If a check of the fbType value in the environment buffer's VDHMODEINFO data indicates graphics mode. ERROR_VIO_USER_FONT If the specified user font is not compatible with the current mode. ERROR_NOT_ENOUGH_MEMORY If the environment buffer is too small to contain another new user-font definition. Comments The type of adapter determines the format of the font definition. The BVH determines how many user-defined fonts it supports when it allocates the environment buffer. The SetFont function adds entries to the user-font table, which must be located at the end of the environment buffer. If the user-font table contains a font with the same dimensions as the ParmBlock usPelColumns and usPelRows values, SetFont replaces the existing entry. Otherwise, SetFont adds the new font to the user-font table. When a new font is inappropriate for the current mode, SetFont should save the font definition for possible use when a subsequent SetMode call occurs. However, SetFont should return an error when the font definition is incompatible with the current mode and reset the current font to the nearest match it can find for the specified font. An odd value for the fsFlags field implies that the calling application is running in the foreground. If all other ParmBlock fields are valid, the SetFont function should do the following: ■ Load the new user font into the adapter if it is appropriate for the current mode. ■ Otherwise, search the user-font table for an appropriate font and load it into the adapter if one is found. If not, load an appropriate code-page font if one can be found. If not, load an appropriate ROM font. Whatever the value of the fsFlags field, SetFont must update the environment buffer. See Also GetFont, InitializeEnvironment, SetMode, VioSetFont █ SetMode ──────────────────────────────────────────────────────────────────────────── USHORT SetMode (pEnvironment, pParmBlock, ulFunction) ENVIRONMENT far * pEnvironment; /*pointer to environment buffer */ VDH_MODE far * pParmBlock; /*pointer to parameter block */ ULONG ulFunction; /*function index */ The SetMode function either sets up a video mode in the environment buffer or loads a video mode into the adapter and updates the environment buffer. Parameters pEnvironment to the environment buffer. pParmBlock to the parameter block for SetMode, defined as the following structure: typedef struct { USHORT usLength; /* ParmBlock = 8 bytes */ USHORT fsFlags; /* bit 0=0--update environment buf */ /* bit 0=1--load the adapter also */ /* bits 1-15 must be zero (reserved) */ PVIOMODEINFO; /* pointer to VDHMODEINFO data */ } VDH_MODE; ulFunction SetMode in the call vector table; its value is 269L (0x010D). Return Value If it is successful, SetMode should return zero (to the ax register when coded in assembly language). Otherwise, it should return one of the following errors when it encounters any one of the following conditions: Return Conditions ──────────────────────────────────────────────────────────────────────────── ERROR_VIO_INVALID_PARMS If the ulFunction value is anything except 269L (0x010D); if the ParmBlock fsFlags value is greater than 1; or if the pEnvironment value is zero. ERROR_INVALID_LENGTH If the ParmBlock usLength value is not 8; or if the calling application's mode data (pointed to by ParmBlock PVIOMODEINFO) has a cb length value that is less than 3, does not fall on a field boundary of the VIOMODEINFO structure, or is greater than 34. ERROR_VIO_MODE If SetMode cannot find a match for the requested mode among the modes it supports. Comments For a BVH, the video mode includes not only the text-display characteristics that it can support but also the ROM, code-page, and user-defined fonts that it has available. SetMode must validate the mode data without using the environment buffer, because the buffer might not have been initialized or might not be valid for the adapter. This function implicitly initializes the environment buffer, if it is not already initialized; it initializes the buffer to its default mode if the requested mode is not valid for the adapter. The ParmBlock PVIOMODEINFO field points to the calling application's mode data. The mode data must specify values for at least the first two fields and may specify values for up to the first nine fields of the following structure: struct _VDHMODEINFO { USHORT cb; /* length, in bytes, of mode data */ UCHAR fbType; /* bit 0=0--Mono-compatible */ /* bit 0=1--Other (not mono) */ /* bit 1=0--Text mode */ /* bit 1=1--Graphics mode */ /* bit 2=0--Color burst enabled */ /* bit 2=1--Color burst disabled */ /* bit 3=0--Adapter native mode disabled */ /* or none available */ /* bit 3=1--Adapter native (advanced */ /* function) mode enabled */ /* bits 4-7 must be zero (reserved) */ UCHAR color; /* number of colors (power of 2) */ USHORT usCol; /* number of text columns */ USHORT usRow; /* number of text rows */ USHORT usHRes; /* pel columns (horizontal resolution) */ USHORT usVRes; /* pel rows (vertical resolution) */ UCHAR uchFormatID; /* 0x00=default (US, single-byte chars) */ /* 0x70=world (international, DBCS) */ UCHAR uchAttrCount; /* 0x01=default, 0x03=world */ UCHAR far *pBuffAddr; /* (returned) 32-bit address of PVB */ ULONG ulBufferLen; /* (returned) length, in bytes, of PVB */ ULONG ulFullBufSize; /* (returned) bytes needed for saving */ /* full video display */ ULONG ulPartialBufSize;/* (returned) bytes needed for saving */ /* parital display if popup occurs */ UCHAR far *pExtDataArea;/* pointer to adapter's native mode */ /* data, if any; otherwise, zero */ }; Note that the VDH_ENVIRONMENT structure includes the field ModeData, whose structure (VIOMODEINFO) is equivalent to _VDHMODEINFO. The input ParmBlock PVIOMODEINFO field must access a buffer that contains at least an fbType value, so the input cb length must be at least 3 when SetMode is called. If the cb length value does not fall on a _VDHMODEINFO field boundary, SetMode returns an error. (The function need not attempt to set a mode from incomplete mode information for any field.) SetMode also returns an error if the cb length value is greater than the length of the _VDHMODEINFO structure. The value of the ParmBlock uchAttrCount field must be appropriate to the value of uchFormatID. The uchAttrCount value must be 0x01 when uchFormatID is 0x00 (default); 0x03 when uchFormatID is 0x70 (world-wide); or an appropriate value when uchFormatID is 0x80 (identical to adapter format). Note that the uchFormatID value determines the value of the environment buffer's cbAttrBufSize, with one attribute byte per character byte for the default format and three attribute bytes per character byte for the world format. An odd value for the fsFlags field implies that the calling application is running in the foreground. In this case, SetMode must do the following: ■ Load a matching mode into the adapter if the PVIOMODEINFO field accesses mode data values that are valid and a match can be found among the supported modes. ■ Update the environment buffer with the new mode. See Also GetMode, InitializeEnvironment, SetFont, SetVariableInfo, VioSetMode █ SetPaletteRegisters ──────────────────────────────────────────────────────────────────────────── USHORT SetPaletteRegisters (pEnvironment, pParmBlock, ulFunction) ENVIRONMENT far * pEnvironment; /*pointer to environment buffer */ VDH_PALETTE far * pParmBlock; /*pointer to parameter block */ ULONG ulFunction; /*function index */ The SetPaletteRegisters function sets a specified number of entries from the palette buffer into the environment buffer or into the adapter's palette registers and the environment buffer. Palette buffer entries define the relationship between text attributes and the color registers. Parameters pEnvironment to the environment buffer. pParmBlock to the parameter block for SetPaletteRegisters, defined as the following structure: typedef struct { USHORT usLength; /* ParmBlock = 12 bytes */ USHORT fsFlags; /* 0x0000=set environment buffer only*/ /* 0x0001=set adapter's palette regs */ /* and update enviroment buf */ USHORT far *pPalDataBuf; /* pointer to palette buf (array) */ USHORT iFirstEntry; /* index of first register to set */ USHORT usNumEntries; /* number of entries to set */ } VDH_PALETTE; ulFunction SetPaletteRegisters in the call vector table; its value is 271L (0x010F). Return Value If it is successful, SetPaletteRegisters should return zero (to the ax register when coded in assembly language). Otherwise, it should return one of the following errors when it encounters any one of the following conditions: Return Conditions ──────────────────────────────────────────────────────────────────────────── ERROR_VIO_INVALID_PARMS If the ulFunction value is anything except 271L (0x010F); if the ParmBlock fsFlags value is greater than 1; if the ParmBlock iFirstEntry value is outside the range of index values for the palette registers; if the ParmBlock usNumEntries is less than 1; or if the pEnvironment value is zero. ERROR_INVALID_LENGTH If the ParmBlock usLength value is not 12; or if the ParmBlock usNumEntries value is too large, either greater than the number of entries in the palette buffer array or greater than the total entries following iFirstEntry. Comments An odd value for the fsFlags field implies that the calling application is running in the foreground. If all ParmBlock fields are valid, SetPaletteRegisters should do the following: ■ Load the specified range of entries from the palette buffer into the adapter's palette registers. ■ Update the environment buffer with these settings also. If the fsFlags value is zero, SetPaletteRegisters sets values only in the environment buffer. The ParmBlock pPalDataBuf field points to a buffer containing a USHORT color value for each register being set. The SetPaletteRegisters function should not change the video-enable state of the adapter. See Also GetPaletteRegisters, VioSetState █ SetVariableInfo ──────────────────────────────────────────────────────────────────────────── USHORT SetVariableInfo (pEnvironment, pParmBlock, ulFunction) ENVIRONMENT far * pEnvironment; /*pointer to environment buffer */ VDH_VARIABLE far * pParmBlock; /*pointer to parameter buffer */ ULONG ulFunction; /*function index */ The SetVariableInfo function sets selected features of the video adapter, including one or more of the blink state, border color, underscore line, video enable, plane enable, code page, scrollable rectangle, and the number of text rows and columns of the display. Parameters pEnvironment to the environment buffer. pParmBlock to the parameter block for SetVariableInfo, defined by the following structure: typedef struct { USHORT usLength; /* ParmBlock = 6-30 bytes */ USHORT fsFlags; /* bit 0=0--set environ buf only */ /* bit 0=1--set adapter state also */ /* bit 1=1--set blink or */ /* bit 1=0--set background intensity */ /* bit 2=1--set overscan (border) color */ /* bit 3=1--set underscore scan line */ /* bit 4=1--set video enabled */ /* bit 5=1--set display mask (plane enable) */ /* bit 6=1--set code-pageID without change */ /* from SBCS to DBCS or vice versa */ /* bit 7=1--set code-pageID, change from */ /* SBCS to DBCS or vice versa if bit 6=1 */ /* bit 8=1--set scrollable rectangle */ /* bit 9=1--set screen dimensions */ /* bits 10-15 must be zero (reserved) */ USHORT fsBlink; /* 0x0000=blink highlights selected cell */ /* 0x0001=background intensity highlights */ USHORT usOverscan; /* border color */ USHORT usUnderscore; /* n=scan line for underscore (n=0-31), */ /* 32=no underscore */ USHORT fsVideoEnable; /* 0x0000=disabled,0x0001=enabled */ ULONG flDisplayMask; /* bit n=1 implies plane n to be enabled */ /* (n=0-31); otherwise, plane n disabled */ USHORT usCodePageID; /* valid ROM-font or user-font ID */ USHORT usScrlLeft; /* 0=leftmost column of current mode's */ /* scrollable rectangle */ USHORT usSrclTop; /* 0=top row */ USHORT usScrlRight; /* right column */ USHORT usSrclBottom; /* bottom row */ USHORT usScreenRows; /* number of rows in current mode */ USHORT usScreenColumns; /* number of columns in current mode */ } VDH_VARIABLE; ulFunction SetVariableInfo in the call vector table; its value is 275L (0x0113). Return Value If it is successful, SetVariableInfo should return zero (to the ax register when coded in assembly language). Otherwise, it should return one of the following errors when it encounters any one of the following conditions: Return Conditions ──────────────────────────────────────────────────────────────────────────── ERROR_VIO_INVALID_PARMS If the ulFunction value is anything except 275L (0x0113); if the ParmBlock fsFlags field has any of bits 10 through 15 set; if bit 5 of fsFlags is set and the BVH does not support an 8514-compatible adapter; or if the pEnvironment value is zero. ERROR_INVALID_LENGTH If the ParmBlock usLength value is not at least 6 or is greater than 30; if any valid bit of fsFlags is set and the usLength value is too small to include the corresponding field; or if any valid bit of fsFlags is set and the corresponding field in ParmBlock has a value that out of range. ERROR_VIO_MODE If a check of the fbType value in the environment buffer's VDHMODEINFO data indicates graphics mode. ERROR_VIO_BAD_CP If bit 6 of fsFlags is set, bit 7 is clear, and the BVH must call SetMode to change the code page. Comments The ParmBlock fsFlags value indicates what SetVariableInfo should set. An odd value implies that the calling application is running in the foreground and that SetVariableInfo should update the hardware state, as well as the environment buffer. The fsFlags field may be a combination (OR) of the following values: Value Meaning ──────────────────────────────────────────────────────────────────────────── 0x0001 Set values in the hardware state and in the environment buffer. Otherwise, set values in the environment buffer only. 0x0002 Set blink; otherwise, set background intensity. 0x0004 Set overscan (border) color. 0x0008 Set underscore scan line. 0x0010 Set video enable. 0x0020 Set display mask, where bits 0 to 31, if set, enable the corresponding plane. 0x0040 Set the code page, if possible, without changing the display mode, provided that bit 7 is clear. (Setting a DBCS code page from an SBCS mode forces a mode change, and vice versa.) 0x0080 Set the code page and force a mode change, if necessary, in order to set a DBCS or SBCS code page, provided that bit 6 is set. 0x0100 Set the scrollable rectangle values, where zero represents the leftmost column and top row for the current display mode. 0x0200 Set the usScreenRows and usScreenColumns fields (screen dimensions) to the current mode's values. After SetVariableInfo disables video signals, the signal must remain disabled until SetVariableInfo is called again to enable it. In other words, the SetMode function should not re-enable video signals when SetVariableInfo has disabled them. If bit 5 of fsFlags is set, the SetVariableInfo function should write the flDisplayMask value to an 8514-compatible adapter. Otherwise, it should return an error. A BVH that supports a US-standard type of adapter may ignore bit 7 of the ParmBlock fsFlags field; bit 7 has meaning only if the BVH handles DBCS (double-byte character set) text displays. If bit 6 of fsFlags is set and bit 7 is clear, SetVariableInfo should set the code page only if the international-type adapter can use the new code page without changing from a DBCS to an SBCS (single-byte character set) mode or vice versa. It should return an error if a mode switch would be required to change the code page. If both bits 6 and 7 of fsFlags are set, SetVariableInfo may call the SetMode or InitializeEnvironment function to force a mode switch when setting a DBCS code page from a SBCS mode, or vice versa. It should ignore bit 7 when bit 6 is clear. The scrollable rectangle fields indicate the area of the screen that may scroll during scroll and write TTY operations. A BVH need not support any scrollable region other than the entire display area, but it may constrain the scrolling region by setting the scrollable rectangle fields. All coordinates are in text display cells, where (0,0) represents the leftmost column and top row of the current mode. See Also GetVariableInfo, InitializeEnvironment, SetMode, TextBufferUpdate (Scrolls), WriteTTY █ TerminateEnvironment ──────────────────────────────────────────────────────────────────────────── USHORT TerminateEnvironment (pEnvironment, pParmBlock, ulFunction) ENVIRONMENT far * pEnvironment; /*pointer to environment buffer */ VDH_ENVRN far * pParmBlock; /*pointer to parameter block */ ULONG ulFunction; /*function index */ The TerminateEnvironment function tells a VDH that the environment is about to be freed, allowing the VDH to perform any necessary cleanup. Parameters pEnvironment to the environment buffer. pParmBlock to the parameter block for TerminateEnvironment, defined as the following structure: typedef struct { USHORT usLength; /* ParmBlock = 6 bytes */ USHORT fsFlags; /* must be zero (reserved) */ USHORT selLVBSel; /* huge (max 1MB) LVB selector */ } VDH_ENVRN; ulFunction TerminateEnvironment in the call vector table; its value is 276L (0x0114). Return Value If it is successful, TerminateEnvironment should return zero (to the ax register when coded in assembly language). Otherwise, it should return one of the following errors when it encounters any one of the following conditions: Return Conditions ──────────────────────────────────────────────────────────────────────────── ERROR_VIO_INVALID_PARMS If the VDH provides a TerminateEnvironment function and if the ulFunction value is anything except 276L (0x0114); if the ParmBlock fsFlags value is not zero; or if the pEnvironment value is zero. ERROR_INVALID_LENGTH If the ParmBlock usLength value is not 6. Comments A VDH need not provide a TerminateEnvironment function if it has no cleanup to do when a session ends and before the environment buffer is freed. See Also InitializeEnvironment, RestoreEnvironment, SaveEnvironment █ TextBufferUpdate (Reads) ──────────────────────────────────────────────────────────────────────────── USHORT TextBufferUpdate (pEnvironment, pParmBlock, ulFunction) ENVIRONMENT far * pEnvironment; /*pointer to environment buffer */ VDH_FULLBUFUP far * pParmBlock; /*pointer to parameter block */ ULONG ulFunction; /*function index */ The TextBufferUpdate function performs text updates to the LVB (logical video buffer) or to both the LVB and PVB (physical video buffer). An index value in the parameter block determines whether TextBufferUpdate reads from, writes to, or scrolls and fills the logical or physical display. For MS OS/2 version 1.2, the TextBufferUpdate function handles 13 possible index values. Two kinds of text updates require TextBufferUpdate to read the LVB/PVB information into the application's data buffer. A third requires TextBufferUpdate to read the LVB or PBV and return information about a specified cell to the application data buffer. Parameters pEnvironment to the environment buffer. pParmBlock to the parameter block for TextBufferUpdate, defined by the following structure: typedef struct { USHORT usLength; /* 26-44 bytes USHORT fsFlags; /* bit 0=0--do not update PVB */ /* bit 0=1--must update PVB */ /* bit 1=0--may update LVB also */ /* bit 1=1--must update LVB */ /* bit 2=0--use current attribute format */ /* bit 2=1--translate current attribute */ /* format to CGA, if necessary */ /* bits 3-15 must be zero (reserved) */ UCHAR far *pAppDataAddr; /* return data here for reads */ UCHAR far *pAppCellAddr; /* (not used for reads) */ USHORT iIndex; /* 0x0000--read cell at (usStartRow, */ /* usStartCol) and return USHORT flag */ /* of single/double-cell character info */ /* 0x0001--read characters from */ /* (usStartRow,usStartCol) */ /* 0x0002--read cells from (usStartRow, */ /* usStartCol) */ /* index values 3-13 for scrolls, writes */ USHORT usStartRow; /* starting row for update */ USHORT usStartCol; /* starting column for update */ USHORT usSecondRow; /* (not used for reads) */ USHORT usSecondCol; /* (not used for reads) */ USHORT usRepeatFactor; /* number of chars/cells to read */ /* (not used for iIndex=0x0000) */ USHORT selLogicalBufSel; /* huge LVB selector (min 64K,max 1MB) */ /******************************************/ /* MINIMUM INPUT ParmBlock ENDS HERE */ /******************************************/ SHORT sTouchXLeft; /* return -1 for reads (no cells touched) */ SHORT sTouchYTop; /* return -1 for reads */ SHORT sTouchXRight; /* return -1 for reads */ SHORT sTouchYBottom; /* return -1 for reads */ /*******************************************************************/ /* The following fields specify an LVB that maps to a conversion */ /* rectangle (window) within the full display area for DBCS BVHs. */ /*******************************************************************/ USHORT usLVBRowOff; /* upper-left corner (row offset for LVB) */ /* expressed as a PVB coordinate */ USHORT usLVBColOff; /* upper-left corner (column offset for */ /* LVB) expressed as a PVB coordinate */ USHORT usLVBWidth; /* width in cells of LVB (must be > 0) */ USHORT usLVBHeight; /* height in cells of LVB (must be > 0) */ UCHAR uchLVBFormatID; /* 0x00--use current value, or one of */ /* 0x00=default (US), 0x70=world, or */ /* 0x80=identical to adapter's format */ UCHAR uchAttrCount; /* 0x00--use current value, or must be */ /* 0x01 if default format ID, 0x03 if */ /* if world format ID; otherwise, is */ /* adapter-specific */ } VDH_FULLBUFUP; ulFunction TextBufferUpdate in the call vector table; its value is 256L (0x0100). Return Value If it is successful, TextBufferUpdate should return zero (to the ax register when coded in assembly language). Otherwise, it should return one of the following errors when it encounters any one of the following conditions: Return Conditions ──────────────────────────────────────────────────────────────────────────── ERROR_VIO_INVALID_PARMS If the ulFunction value is anything except 256L (0x0100); if the ParmBlock fsFlags field has bit 1 set but bit 0 clear, or if it has any of bits 3 to 15 set; if the ParmBlock iIndex value is greater than 13; if any of the usLVBRowOff through usLVBHeight values are invalid; if the (input) ParmBlock uchFormatID and uchAttrCount pair are nonzero but mismatched (not 0x00 and 0x01, or 0x70 and 0x03); or if the pEnvironment value is zero. ERROR_INVALID_LENGTH If the ParmBlock usLength value is less than 26, does not fall on a ParmBlock field boundary, does not include sufficient data for optional but logically grouped fields of VDH_FULLBUFUP, or is greater than 44. ERROR_VIO_MODE If a check of the fbType value in the environment buffer's VDHMODEINFO data indicates graphics mode. ERROR_VIO_ROW If the ParmBlock usStartRow value is out of range for the current mode. ERROR_VIO_COLUMN If the ParmBlock usStartColumn value is out of range for the current mode. ERROR_VIO_INTERNAL_RESOURCE If a check of the environment buffer reveals that the calling application either has a null PVB selector or has made a SetMode call (so the PVB selector in the environment buffer is out-of-date), and an attempt to allocate a current PVB selector fails. Comments The usLength value determines whether TextBufferUpdate may assume the default values for this environment. If usLength is greater than 26, TextBufferUpdate must validate input data and return values for additional fields passed in the call. TextBufferUpdate reads should return -1 to the sTouchXLeft through sTouchYBottom fields of ParmBlock. If ParmBlock includes LVB data for a conversion rectangle and uchLVBFormatID is a nonzero value, TextBufferUpdate must validate the input LVB dimensions and either return an error or use the specified LVB to read the data. For TextBufferUpdate reads, bit 1 of the fsFlags field has meaning only if bit 0 is set. Otherwise, this field may be a combination (OR) of the following values: Value Meaning ──────────────────────────────────────────────────────────────────────────── 0x0001 Read the PVB to obtain return information, because the calling application is running in the foreground. Otherwise, get information from the LVB. 0x0002 Update the LVB with the information read from the PVB. Otherwise, an update to the LVB is optional. 0x0004 Translate LVB or PVB information into CGA format (if the LVB/PVB does not use CGA format) before returning the information to the application's data buffer (ANSI is enabled if bit 3 of fsFlags is set). Otherwise, return information in the current format. For TextBufferUpdate reads, the ParmBlock iIndex field is one of three possible values: Value Meaning ──────────────────────────────────────────────────────────────────────────── 0x0000 If the BVH supports only SBCS (single-byte character set) text display, return 0x0000 to the application's data buffer at pAppDataAddr. If the BVH also supports DBCS (double-byte character set) text display, read the cell specified by the ( usStartRow,usStartColumn) values. Return 0x0000 when ParmBlock either does not include the uchLVBFormatID and uchAttrCount fields or their values are zero, and a check of the environment buffer's mode data indicates that the current uchFormatID is 0x00 (default US format). Otherwise, examine the specified cell's character-attribute bytes to determine whether it is an SCBS character or a double-cell or single-cell DBCS character. Return 0x0000 to the application's data buffer if it is an SCBS character; return 0x0001 if it is a single-cell DBCS character. Otherwise, continue examining the specified cell's character-attribute bytes to determine whether it is the leading or trailing cell of the double-cell character. Return 0x0002 if it is the leading cell or 0x0003 if it is the trailing cell of the double-cell character. ] 0x0001 If the BVH supports only SBCS text display or if the current code page is SCBS, read the number of characters specified by usRepeatFactor (or until the end of the PVB/LVB) and start reading at (usStartRow,usStartColumn). Return the characters to the application's data buffer at pAppDataAddr and return the number of characters that were read to usRepeatFactor. If ParmBlock does not include LVB data (last six fields of VDH_FULLBUFUP) or if both the uchLVBFormatID and uchAttrCount fields are zero, use the current uchFormatID value, obtained from the environment buffer's mode data. If the current code page is DBCS, a single character can require two display cells. If the read operation starts on a trailing byte or ends on a leading byte of a double-cell character, replace this character with a blank (single-cell space character) before returning data at pAppDataAddr. 0x0002 If the BVH supports only SBCS text display or if the current code page is SBCS, read the number of cells specified by usRepeatFactor (or until the end of the PVB/LVB) and start reading at ( usStartRow,usStartColumn). Return the cells read to the application's data buffer at pAppDataAddr and return the number of cells that were read to usRepeatFactor. If ParmBlock does not include LVB data (last six fields of VDH_FULLBUFUP) or if both the uchLVBFormatID and uchAttrCount fields are zero, use the current uchFormatID value, obtained from the environment buffer's mode data. If the current code page is DBCS, a single DBCS character can require two display cells. If the read operation starts on a trailing byte or ends on a leading byte of a double-cell character, replace this character with a blank (single-cell space character) before returning data at pAppDataAddr. , Note that the usLVBRowOff through usLVBHeight fields of a conversion rectangle allow an LVB to map to a display area that does not have its upper-left corner at (0,0) on the physical display and that such an LVB might have different row and column dimensions than other LVBs that map to the same display. See Also InitializeEnvironment, SetMode, TextBufferUpdate (Scrolls), TextBufferUpdate (Writes), VioReadCellStr, VioReadCharStr █ TextBufferUpdate (Scrolls) ──────────────────────────────────────────────────────────────────────────── USHORT TextBufferUpdate (pEnvironment, pParmBlock, ulFunction) ENVIRONMENT far * pEnvironment; /*pointer to environment buffer */ VDH_FULLBUFUP far * pParmBlock; /*pointer to parameter block */ ULONG ulFunction; /*function index */ The TextBufferUpdate function performs text updates to the LVB (logical video buffer) or to both the LVB and PVB (physical video buffer). An index value in the parameter block determines whether TextBufferUpdate reads from, writes to, or scrolls and fills the logical or physical display. For MS OS/2 version 1.2, the TextBufferUpdate function handles 13 possible index values. Four kinds of scrolling operations require TextBufferUpdate to update the LVB or the LVB and PVB. Parameters pEnvironment to the environment buffer. pParmBlock to the parameter block for TextBufferUpdate, defined by the following structure: typedef struct { USHORT usLength; /* 26-44 bytes USHORT fsFlags; /* bit 0=0--do not update PVB */ /* bit 0=1--must update PVB */ /* bit 1=0--may update LVB also */ /* bit 1=1--must update LVB */ /* bit 2=0--use current attribute format */ /* bit 2=1--translate from CGA attribute */ /* format, if necessary */ /* bits 3-15 must be zero (reserved) */ UCHAR far *pAppDataAddr; /* (not used for scrolls) */ UCHAR far *pAppCellAddr; /* pointer to cell used to fill void in */ /* scrolled area (rectangle bounded */ /* by (usStartRow,usStartColumn) and */ /* (usSecondRow,usSecondColumn)) */ USHORT iIndex; /* 0x0003--scroll up */ /* 0x0004--scroll down */ /* 0x0005--scroll left */ /* 0x0006--scroll right */ /* iIndex 0-2 for reads,7-13 for writes */ USHORT usStartRow; /* starting row for scroll update */ USHORT usStartCol; /* starting column for scroll */ USHORT usSecondRow; /* ending row for scroll */ USHORT usSecondCol; /* ending column for scroll */ USHORT usRepeatFactor; /* number of rows/columns to scroll */ USHORT selLogicalBufSel; /* huge LVB selector (min 64K,max 1MB) */ .ET /*****************************************/ /* MINIMUM INPUT ParmBlock ENDS HERE */ /*****************************************/ /* return following TouchXXX values for */ /* smallest rectangle enclosing all */ /* cells affected by scroll operations */ SHORT sTouchXLeft; /* x-coordinate, upper leftmost cell */ SHORT sTouchYTop; /* y-coordinate, upper leftmost cell */ SHORT sTouchXRight; /* x-coordinate, lower rightmost cell */ SHORT sTouchYBottom; /* y-coordinate, lower rightmost cell */ /******************************************************************/ /* The following fields specify an LVB that maps to a conversion */ /* rectangle (window) within the full display area for DBCS BVHs. */ /******************************************************************/ USHORT usLVBRowOff; /* (not used for scrolls) */ USHORT usLVBColOff; /* (not used for scrolls) */ USHORT usLVBWidth; /* (not used for scrolls) */ USHORT usLVBHeight; /* (not used for scrolls) */ UCHAR uchLVBFormatID; /* (not used for scrolls) */ UCHAR uchAttrCount; /* (not used for scrolls) */ /* (not used for scrolls) */ } VDH_FULLBUFUP; ulFunction TextBufferUpdate in the call vector table; its value is 256L (0x0100). Return Value If it is successful, TextBufferUpdate should return zero (to the ax register when coded in assembly language). Otherwise, it should return one of the following errors when it encounters any one of the following conditions: Return Conditions ──────────────────────────────────────────────────────────────────────────── ERROR_VIO_INVALID_PARMS If the ulFunction value is anything except 256L (0x0100); if the ParmBlock fsFlags field has both bits 0 and 1 clear or any of bits 3 to 15 set; if the ParmBlock iIndex value is greater than 13; if the ParmBlock usRepeatFactor value is zero; or if the pEnvironment value is zero. ERROR_INVALID_LENGTH If the ParmBlock usLength value is less than 26, does not fall on a ParmBlock field boundary, does not include sufficient data for optional but logically grouped fields of VDH_FULLBUFUP, or is greater than 44. ERROR_VIO_MODE If a check of the fbType value in the environment buffer's VDHMODEINFO data indicates graphics mode. ERROR_VIO_ROW If the ParmBlock usStartRow or usSecondRow value is out of range for the current mode. ERROR_VIO_COLUMN If the ParmBlock usStartColumn or usSecondColumn value is out of range for the current mode. ERROR_VIO_INTERNAL_RESOURCE If a check of the environment buffer reveals that the calling application either has a null PVB selector or has made a SetMode call (so the PVB selector in the environment buffer is out-of-date), and an attempt to allocate a current PVB selector fails. Comments If the usLength value is greater than 26, TextBufferUpdate must calculate and return values for additional fields passed in the call. TextBufferUpdate scrolls must return values to the sTouchXLeft, sTouchYTop, sTouchXRight, and sTouchYBottom fields if ParmBlock includes a touch rectangle (usLength is at least 34). These values should specify the smallest possible rectangle that encloses all cells affected by the scroll operation. BVS uses the touched coordinates if it must call the BVH again to refresh a display area that was overwritten by the scroll. For TextBufferUpdate scrolls, bit 1 of the fsFlags field has meaning only if bit 0 is set. Otherwise, fsFlags may be a combination (OR) of the following values: Value Meaning ──────────────────────────────────────────────────────────────────────────── 0x0001 Update the display (PVB) with the scrolling information, because the calling application is running in the foreground. Otherwise, update the LVB. 0x0002 Update the LVB with the scrolling information. Otherwise, the PVB has been updated and an update to the LVB is optional. 0x0004 Translate the value at pAppCellAddr from CGA attribute format (if the LVB/PVB does not use CGA format) before updating the PVB or the LVB. Otherwise, use this value in its current attribute format. For TextBufferUpdate scrolls, the iIndex field is one of four possible values, each indicating the direction for the scroll: Value Meaning ──────────────────────────────────────────────────────────────────────────── 0x0003 Scroll text up within the specified rectangle for the specified number of rows. The rectangle bounded at the upper-left corner by (usStartRow,usStartColumn) and at the lower-right corner by ( usSecondRow,usSecondColumn) is the area to be scrolled up. The usRepeatFactor value is the number of rows to scroll. The rectangle bounded by ((usSecondRow - usRepeatFactor + 1),usStartColumn) and ( usSecondRow,usSecondColumn) is the area to be filled. If the usRepeatFactor value is greater than or equal to (usSecondRow - usStartRow + 1), TextBufferUpdate may simply fill the specified rectangle with the cell at pAppCellAddr. Otherwise, TextBufferUpdate must move data in the specified rectangle and fill part of the scroll rectangle at the bottom. 0x0004 Scroll text down within the specified rectangle for the specified number of rows. The rectangle bounded at the upper-left corner by (usStartRow,usStartColumn) and at the lower-right corner by ( usSecondRow,usSecondColumn) is the area to be scrolled down. The usRepeatFactor value is the number of rows to scroll. The rectangle bounded by (usStartRow, usStartColumn) and ((usStartRow + usRepeatFactor - 1),usSecondColumn) is the area to be filled. If the usRepeatFactor value is greater than or equal to (usSecondRow - usStartRow + 1), TextBufferUpdate may simply fill the specified rectangle with the cell at pAppCellAddr. Otherwise, TextBufferUpdate must move data in the specified rectangle and fill part of the scroll rectangle at the top. 0x0005 Scroll text left within the specified rectangle for the specified number of columns. The rectangle bounded at the upper-left corner by (usStartRow,usStartColumn) and at the lower-right corner by ( usSecondRow,usSecondColumn) is the area to be scrolled left. The usRepeatFactor value is the number of columns to scroll. The rectangle bounded by (usStartRow, ( usSecondColumnusRepeatFactor + 1)) and ( usSecondRow,usSecondColumn) is the area to be filled. If the usRepeatFactor value is greater than or equal to (usSecondColumn - usStartColumn + 1), TextBufferUpdate may simply fill the specified rectangle with the cell at pAppCellAddr. Otherwise, TextBufferUpdate must move data in the specified rectangle and fill part of the scroll rectangle at the right. 0x0006 Scroll text right within the specified rectangle for the specified number of columns. The rectangle bounded at the upper-left corner by (usStartRow,usStartColumn) and at the lower-right corner by ( usSecondRow,usSecondColumn) is the area to be scrolled right. The usRepeatFactor value is the number of columns to scroll. The rectangle bounded by (usStartRow, usStartColumn) and (usSecondRow,( usStartColumn + usRepeatFactor - 1)) is the area to be filled. If the usRepeatFactor value is greater than or equal to (usSecondColumn - usStartColumn + 1), TextBufferUpdate may simply fill the specified rectangle with the cell at pAppCellAddr. Otherwise, TextBufferUpdate must move data in the specified rectangle and fill part of the scroll rectangle at the right. The BVH must support scrolling operations within the scrollable rectangle for the current mode (see SetVariableInfo). The upper-left cell of the full display has the coordinates (0,0). If the BVH supports DBCS text display, TextBufferUpdate must not bisect a double-cell DBCS character on the display. The scroll operations should substitute a single-cell space character for any double-cell DBCS character that would otherwise be bisected at the edge of the screen or at the border of a conversion rectangle, including the input fill-cell character. If the BVH supports DBCS text display, TextBufferUpdate must sometimes scroll text on a display where one or more conversion rectangles cover all or part of the scroll rectangle. A conversion rectangle uses its own LVB when it overwrites a display area, so the BVH retains the original LVB for the display. When it writes the formerly hidden characters from the LVB to the PVB, TextBufferUpdate restores bisected double-cell DBCS characters that were displayed as single-cell blanks at a border of the conversion rectangle. For scrolls, TextBufferUpdate may ignore the usLVBRowOff through uchAttrCount fields of VDH_FULLBUFUP, since MS OS/2 version 1.2 does not allow scrolling within conversion rectangles. See Also InitializeEnvironment, SetMode, SetVariableInfo, TextBufferUpdate (Reads), TextBufferUpdate (Writes), VioScrollDn, VioScrollLf, VioScrollRt, VioScrollUp █ TextBufferUpdate (Writes) ──────────────────────────────────────────────────────────────────────────── USHORT TextBufferUpdate (pEnvironment, pParmBlock, ulFunction) ENVIRONMENT far * pEnvironment; /*pointer to environment buffer */ VDH_FULLBUFUP far * pParmBlock; /*pointer to parameter block */ ULONG ulFunction; /*function index */ The TextBufferUpdate function performs text updates to the LVB (logical video buffer) or to both the LVB and PVB (physical video buffer). An index value in the parameter block determines whether TextBufferUpdate reads from, writes to, or scrolls and fills the logical or physical display. For MS OS/2 version 1.2, the TextBufferUpdate function handles 13 possible index values. Three kinds of text updates require TextBufferUpdate to write characters or cells from the application's data buffer to the LVB or to the LVB and PVB. Three more require TextBufferUpdate to write a repeated character, attribute, or cell from the application's data buffer to the LVB or to the LVB and PVB. Another requires TextBufferUpdate to copy an LVB rectangle to the PVB. Parameters pEnvironment to the environment buffer. pParmBlock to the parameter block for TextBufferUpdate, defined by the following structure: typedef struct { USHORT usLength; /* 26-44 bytes USHORT fsFlags; /* bit 0=0--do not update PVB */ /* bit 0=1--must update PVB */ /* bit 1=0--may update LVB also */ /* bit 1=1--must update LVB */ /* bit 2=0--use current attribute format */ /* bit 2=1--translate from CGA attribute */ /* format, if necessary */ /* bits 3-15 must be zero (reserved) */ UCHAR far *pAppDataAddr; /* get characters/cells here for */ /* iIndex=7-12 writes */ UCHAR far *pAppCellAddr; /* get attribute here, iIndex=9 writes */ /******************************************************************/ /* Writes either to rectangle bounded by (usStartRow, */ /* usStartColumn) and (usSecondRow,usSecondColumn) or starting */ /* at (usStartRow,usStartColumn) */ /******************************************************************/ USHORT iIndex; /* 0x0007--write cells */ /* 0x0008--write characters */ /* 0x0009--write characters with */ /* constant attribute */ /* 0x0010--write repeated character */ /* 0x0011--write repeated attribute */ /* 0x0012--write repeated cell */ /* 0x0013--copy LVB rectangle to PVB */ /* iIndex values 0-6 for reads,scrolls */ USHORT usStartRow; /* starting row iIndex=7-12, upper-left */ /* row for start-cell iIndex=13 */ USHORT usStartCol; /* starting column iIndex=7-12, upper- */ /* left column for start-cell iIndex=13 */ USHORT usSecondRow; /* ending row iIndex=7-9, (not used */ /* iIndex=10-12), lower-right row for */ /* end-cell iIndex=13 */ USHORT usSecondCol; /* ending column iIndex=7-9, (not used */ /* iIndex=10-12), lower-right column */ /* for end-cell iIndex=13 */ USHORT usRepeatFactor; /* number of chars/cells to write */ /* (zero for iIndex=13) */ USHORT selLogicalBufSel; /* huge LVB selector (min 64K,max 1MB) */ .ET /*****************************************/ /* MINIMUM INPUT ParmBlock ENDS HERE */ /*****************************************/ /* return following TouchXXX values for */ /* smallest rectangle enclosing all */ /* cells affected by write operations */ SHORT sTouchXLeft; /* x-coordinate, upper-leftmost cell */ SHORT sTouchYTop; /* y-coordinate, upper-leftmost cell */ SHORT sTouchXRight; /* x-coordinate, lower-rightmost cell */ SHORT sTouchYBottom; /* y-coordinate, lower-rightmost cell */ /******************************************************************/ /* The following fields specify an LVB that maps to a conversion */ /* rectangle (window) within the full display area for DBCS BVHs. */ /******************************************************************/ USHORT usLVBRowOff; /* upper-left corner (row offset for LVB)*/ /* expressed as a PVB coordinate */ USHORT usLVBColOff; /* upper-left corner (column offset for */ /* LVB) expressed as a PVB coordinate */ USHORT usLVBWidth; /* width in cells of LVB (must be > 0) */ USHORT usLVBHeight; /* height in cells of LVB (must be > 0) */ UCHAR uchLVBFormatID; /* 0x00--use current value, or one of */ /* 0x00=default (US), 0x70=world, or */ /* 0x80=identical to adapter's format */ UCHAR uchAttrCount; /* 0x00--use current value, or must be */ /* 0x01 if default formatID, 0x03 */ /* if world formatID; otherwise, is */ /* adapter-specific */ } VDH_FULLBUFUP; ulFunction TextBufferUpdate in the call vector table; its value is 256L (0x0100). Return Value If it is successful, TextBufferUpdate should return zero (to the ax register when coded in assembly language). Otherwise, it should return one of the following errors when it encounters any one of the following conditions: Return Conditions ──────────────────────────────────────────────────────────────────────────── ERROR_VIO_INVALID_PARMS If the ulFunction value is anything except 256L (0x0100); if the ParmBlock fsFlags field has any of bits 3 to 15 set; if the ParmBlock iIndex value is greater than 13; if any of the usLVBRowOff through usLBVHeight values are invalid; if the (input) ParmBlock uchFormatID and uchAttrCount pair are nonzero but mismatched (not 0x00 and 0x01, or 0x70 and 0x03); or if the pEnvironment value is zero. ERROR_INVALID_LENGTH If the ParmBlock usLength value is less than 26, does not fall on a ParmBlock field boundary, does not include sufficient data for optional but logically grouped fields of VDH_FULLBUFUP, or is greater than 44. ERROR_VIO_MODE If a check of the fbType value in the environment buffer's VDHMODEINFO data indicates graphics mode. ERROR_VIO_ROW If the ParmBlock usStartRow or usSecondRow value is out of range for the current mode. ERROR_VIO_COLUMN If the ParmBlock usStartColumn usSecondColumn value is out of range for the current mode. ERROR_VIO_INTERNAL_RESOURCE If a check of the environment buffer reveals that the calling application either has a null PVB selector or has made a SetMode call (so the PVB selector in the environment buffer is out-of-date), and an attempt to allocate a current PVB selector fails. Comments The usLength value determines whether TextBufferUpdate may assume the default values for this environment. If usLength is greater than 26, TextBufferUpdate must validate input data and calculate return values for additional fields passed in the call. TextBufferUpdate writes must return values to the sTouchXLeft, sTouchYTop, sTouchXRight, and sTouchYBottom fields if ParmBlock includes a touch rectangle (usLength is at least 34). These values should specify the smallest possible rectangle that encloses all cells affected by the write operation. BVS uses the touched coordinates if it must call TextBufferUpdate again (iIndex value of 13) to refresh a display area that was overwritten. If ParmBlock includes LVB data, TextBufferUpdate must validate the input LVB dimensions and return an error if any dimension is invalid. Otherwise, it must use the values of (usLVBRowOff,usLVBColOff), usLVBWidth, and usLVBHeight to determine a rectangle that contains the rectangle to be written (bounded by (usStartRow,usStartColumn) and (usSecondRow, usSecondColumn)). For TextBufferUpdate writes, bit 1 of the fsFlags field has meaning only if bit 0 is set. Otherwise, this field may be a combination (OR) of the following values: Value Meaning ──────────────────────────────────────────────────────────────────────────── 0x0001 Write to the PVB, because the calling application is running in the foreground. Otherwise, write to the LVB. 0x0002 Update the LVB before writing to the PVB. (If the BVH supports DBCS text display, its LVB should retain double-cell characters that it must write to the PVB as blanks, rather than bisecting such characters at a border of the display area.) Otherwise, an update to the LVB is optional. 0x0004 Translate data at ParmBlock pAppDataAddr from CGA format (ANSI is enabled if bit 3 of fsFlags is set), if the LVB/PVB does not use CGA format. Otherwise, use the data in its current format. For TextBufferUpdate writes, the iIndex field is one of seven possible values: Value Meaning ──────────────────────────────────────────────────────────────────────────── 0x0007 If the BVH supports only SBCS text display or if the current code page is SBCS, get the number of cells specified by usRepeatFactor from the buffer at pAppDataAddr or get all cells in the buffer if there are fewer than the value of usRepeatFactor. Write the cells to the rectangle bounded by (usStartRow, usStartColumn) on the upper left and by (usSecondRow,usSecondColumn) on the lower right. Return the number of cells that were written to usRepeatFactor. If ParmBlock does not include LVB data (last six fields of VDH_FULLBUFUP) or if both the uchLVBFormatID and uchAttrCount values are zero, use the current uchFormatID value, obtained from the environment buffer's mode data. If the current code page is DBCS, a single character can require two display cells. If the pAppCellAddr field contains a selector that matches the LVB selector in the environment buffer and the current value of uchFormatID is 0x70, restore each DBCS character's system-attribute byte when updating the LVB; as always, update the LVB before updating the PVB. If a write operation starts on a trailing byte or ends on a leading byte of a double-cell character, replace this character with a blank (single-cell space character). 0x0008 If the BVH supports only SBCS text display or if the current code page is SBCS, get the number of characters specified by usRepeatFactor from the buffer at pAppDataAddr or get all characters in the buffer if there are fewer than the value of usRepeatFactor. Write the characters to the rectangle bounded by (usStartRow,usStartColumn) on the upper left and by (usSecondRow, usSecondColumn) on the lower right. Return the number of characters that were written to usRepeatFactor. If ParmBlock does not include LVB data (last six fields of VDH_FULLBUFUP) or if both the uchLVBFormatID and uchAttrCount values are zero, use the current uchFormatID value, obtained from the environment buffer's mode data. If the current code page is DBCS, a single character can require two display cells. Update the LVB before updating the PVB if bit 0 of usFlags is set. If a write operation starts on a trailing byte or ends on a leading byte of a double-cell character, replace this character with a blank (single-cell space character). 0x0009 If the BVH supports only SBCS text display or if the current code page is SBCS, get the number of characters specified by usRepeatFactor from the buffer at pAppDataAddr or get all characters in the buffer if there are fewer than the value of usRepeatFactor. Get the attribute to be applied to each character from the buffer at pAppCellAddr. Write the characters to the rectangle bounded by (usStartRow, usStartColumn) on the upper left and by (usSecondRow,usSecondColumn) on the lower right. Return the number of characters that were written to usRepeatFactor. If ParmBlock does not include LVB data (last six fields of VDH_FULLBUFUP) or if both the uchLVBFormatID and uchAttrCount values are zero, use the current uchFormatID value, obtained from the environment buffer's mode data. If the current code page is DBCS, a single character can require two display cells. Update the LVB before updating the PVB if bit 0 of usFlags is set. If a write operation starts on a trailing byte or ends on a leading byte of a double-cell character, replace this character with a blank (single-cell space character). 0x0010 If the BVH supports only SBCS text display or if the current code page is SBCS, get the the character to be written from the buffer at pAppDataAddr and the number of times to write it from usRepeatFactor. Write the character repeatedly, starting at (usStartRow, usStartColumn) on the upper left until usRepeatFactor characters are written or until the end of the LVB/PVB. Return the number of characters that were written to usRepeatFactor. If ParmBlock does not include LVB data (last six fields of VDH_FULLBUFUP) or if both the uchLVBFormatID and uchAttrCount values are zero, use the current uchFormatID value, obtained from the environment buffer's mode data. If the current code page is DBCS, a single character can require two display cells. Update the LVB before updating the PVB if bit 0 of usFlags is set. If a write operation starts on a trailing byte or ends on a leading byte of a double-cell character, replace this character with a blank (single-cell space character). 0x0011 If the BVH supports only SBCS text display or if the current code page is SBCS, get the the attribute to be written from the buffer at pAppDataAddr and the number of times to write it from usRepeatFactor. Write the attribute repeatedly, starting at (usStartRow, usStartColumn) on the upper left until usRepeatFactor attributes are written or until the end of the LVB/PVB. Return the number of attributes that were written to usRepeatFactor. If ParmBlock does not include LVB data (last six fields of VDH_FULLBUFUP) or if both the uchLVBFormatID and uchAttrCount values are zero, use the current uchFormatID value, obtained from the environment buffer's mode data. If the current code page is DBCS, update the LVB before updating the PVB if bit 0 of usFlags is set. 0x0012 If the BVH supports only SBCS text display or if the current code page is SBCS, get the the cell to be written from the buffer at pAppDataAddr and the number of times to write it from usRepeatFactor. Write the cell repeatedly, starting at (usStartRow, usStartColumn) on the upper left until usRepeatFactor cells are written or until the end of the LVB/PVB. Return the number of cells that were written to usRepeatFactor. If ParmBlock does not include LVB data (last six fields of VDH_FULLBUFUP) or if both the uchLVBFormatID and uchAttrCount values are zero, use the current uchFormatID value, obtained from the environment buffer's mode data. If the current code page is DBCS, a single character can require two display cells. Update the LVB before updating the PVB if bit 0 of usFlags is set. If a write operation starts on a trailing byte or ends on a leading byte of a double-cell character, replace this character with a blank (single-cell space character). 0x0013 If the BVH supports only SBCS text display, it may or may not implement TextBufferUpdate for iIndex 0x0013, depending on whether the BVH maintains a shadow LVB for sessions running in the foreground and whether it returns touch rectangle values that are less than a full-screen display. If it does, the ( usStartRow, usStartColumn) coordinates determine the upper-left corner, and the (usSecondRow,usSecondColumn) coordinates determine the lower-right corner of the rectangle to be copied from the LVB to the PVB. If ParmBlock does not include LVB data (last six fields of VDH_FULLBUFUP) or if both the uchLVBFormatID and uchAttrCount values are zero, use the current uchFormatID value, obtained from the environment buffer's mode data. If the current code page is SBCS, copy the rectangle bounded by (usStartRow, usStartColumn) and (usSecondRow, usSecondColumn) from the LVB to the PVB. Otherwise, a single DBCS character can require two display cells. If a write operation starts on a trailing byte of a double-cell character at a coordinate that is not the leftmost column of the LVB, write both the leading and trailing cells to the PVB. If a write operation ends on a leading byte of a double-cell character at a coordinate that is not the rightmost column of the LVB, write both the leading and trailing cells to the PVB. A BVH must maintain the integrity of its LVBs. The BVH should refuse to write any application-supplied data that would result in malformed display output. In particular, BVHs that support DBCS text displays must do the following: ■ Update the LVB before writing to the PVB when bit 0 is set in the fsFlags field, in order to retain full double-cell DBCS characters in the LVB. TextBufferUpdate writes must retain a full double-cell DBCS character in the LVB for each such character that should be written as a blank at the edge of the display. ■ Keep either a full single-cell SBCS character or the leading cell of a DBCS double-cell character as the initial character of the LVB. Except for this initial character, DBCS double-cell characters may occur at any location in the LVB. Note that the usLVBRowOff through usLVBHeight fields of a conversion rectangle allow an LVB to map to a display area that does not have its upper-left corner at (0,0) on the physical display and that such an LVB might have different row and column dimensions than other LVBs that map to the same display. When a DBCS conversion rectangle is dismissed, the subsequent write operation (TextBufferUpdate with iIndex value 0x0013) should restore the formerly bisected double-cell DBCS characters that were covered by a border column of the conversion rectangle. For this reason, TextBufferUpdate should return values for the touch rectangle fields sTouchXLeft through sTouchYBottom that allow this restoration when a conversion rectangle is dismissed. See Also InitializeEnvironment, SetMode, TextBufferUpdate (Reads), TextBufferUpdate (Scrolls), VioWrtCellStr, VioWrtCharStr, VioWrtCharStrAtt, VioWrtNAttr, VioWrtNCell, VioWrtNChar, WriteTTY █ WriteTTY ──────────────────────────────────────────────────────────────────────────── USHORT WriteTTY (pEnvironment, pParmBlock, ulFunction) ENVIRONMENT far * pEnvironment; /*pointer to environment buffer */ VDH_WRTTTY far * pParmBlock; /*pointer to parameter block */ ULONG ulFunction; /*function index */ The WriteTTY function writes a character string to the screen, starting at the current cursor position, and optionally does a print screen as well. Parameters pEnvironment to the environment buffer. pParmBlock to the parameter block for WriteTTY, defined as the following structure: typedef struct { USHORT usLength; /* ParmBlock = 14 bytes */ USHORT fsFlags; /* bit 0=0--do not update PVB */ /* bit 0=1--update the PVB also */ /* bit 1=0--may update LVB also */ /* bit 1=1--must update LVB */ /* bit 2=0--ANSI not enabled */ /* bit 2=1--ANSI enabled */ /* bit 3=0--Ctrl+PrtSc not enabled */ /* bit 3=1--Ctrl+PrtSc enabled */ /* bits 4-15 must be 0 (reserved) */ USHORT selLVBSel; /* huge (max 1MB) LVB selector */ ULONG pchString; /* far pointer to character string */ /* to be written */ USHORT cbStrLen; /* length of character string */ USHORT hfPrinter; /* printer device handle if */ /* Ctrl+PrtSc enabled */ } VDH_WRTTTY; ulFunction WriteTTY in the call vector table; its value is 278L (0x0116). Return Value If it is successful, WriteTTY should return zero (to the ax register when coded in assembly language). Otherwise, it should return one of the following errors when it encounters any one of the following conditions: Return Conditions ──────────────────────────────────────────────────────────────────────────── ERROR_VIO_INVALID_PARMS If the BVH provides a WriteTTY function and if the ulFunction value is anything except 278L (0x0116); if the ParmBlock fsFlags field has any of bits 4 to 15 set; or if the pEnvironment value is zero. ERROR_INVALID_LENGTH If the ParmBlock usLength value is not 14; or if the cbStrLen value is zero. ERROR_VIO_MODE If a check of the fbType value in the environment buffer's VDHMODEINFO data indicates graphics mode. Comments A WriteTTY function is optional. Most BVHs can use the default WriteTTY support provided by BVS. BVS supplies a default (text-mode) WriteTTY routine with the same level of support as MS OS/2 version 1.1. However, unique video adapters can have unique needs, so a BVH may supply a WriteTTY of its own to replace the default BVS routine. An odd value for the fsFlags field implies that the calling application is running in the foreground and that WriteTTY must send output to the physical display. This field may be a combination (OR) of the following values: Value Meaning ──────────────────────────────────────────────────────────────────────────── 0x0001 The PVB must be updated. Otherwise, the PVB may not be updated. 0x0002 The LVB must be updated. Otherwise, the LVB may be updated. 0x0004 ANSI is enabled, so the BVH must process any ANSI escape sequences in the string accessed by the ParmBlock pchString value. Otherwise, ANSI is disabled, and the WriteTTY function should handle any ANSI escape sequences as text data. 0x0008 CTRL+PRTSC is active, and WriteTTY must echo its output to the printer specified by the ParmBlock hfPrinter parameter. If CTRL+PRTSC is active but WriteTTY cannot open the device specified in the hfPrinter field, this routine may call DosBeep to indicate an error. For a BVH that supports DBCS (double-byte character set) text display, WriteTTY should do the following: ■ Substitute a blank (single-cell space character) for any double-cell DBCS character that would be bisected at the last column of the display, and write the full double-cell character in the following row. ■ Save any double-cell DBCS leading byte that occurs as the last character in an application-supplied string until it can be written with its corresponding trailing byte when WriteTTY is called again. ■ Ignore control codes (carriage return, linefeed, backspace, tab, or bell characters) that are passed as the trailing byte of a double-cell character. ■ Process every backspace one at a time, even if a backspace positions the cursor at the trailing byte of a double-cell character. It is the application's responsibility to supply backspace control codes that maintain a correct cursor position with respect to double-cell characters. See Also DosBeep, PrintScreen, VioWrtTTY Chapter 5 Mouse Device Drivers ──────────────────────────────────────────────────────────────────────────── 5.1 Introduction MS OS/2 version 1.2 supplies the driver named mouse$ that provides all device-independent support for mouse devices. The mouse$ driver supports all of the following: ■ MS OS/2 standard category 07 IOCtl functions. ■ An IDC (inter-device driver communication) interface to the pointer-draw driver (named pointer$). ■ The standard Int 33H interface to the real-mode mouse. ■ An IDC interface with the system's device-dependent mouse drivers and to any device-dependent drivers that are add-ons. The mouse$ driver must be specified following the device-dependent driver in the config.sys file so that mouse$ can establish IDC to the newly installed device-dependent driver. A device-dependent driver communicates directly only with the kernel, with its device, and with the system's mouse$ driver. 5.2 System-supplied IDC Functions The mouse$ driver's IDC interface to device-dependent drivers includes the following two callable functions: Function code Function ──────────────────────────────────────────────────────────────────────────── 00001H ProcessPacket Processes a packet of data that is gotten from the device when an interrupt occurs, formatted, and written into a shared data buffer by the device-dependent driver. 0002H DisableSupport Stops the mouse$ driver from routing API calls to the device-dependent driver as it processes a Deinstall request from the kernel. For more information about Deinstall, see Section 5.3.2.2. The device-dependent driver must pass required parameters in specific registers when it calls these functions. For detailed information about ProcessPacket and DisableSupport, see Section 5.4. 5.3 Device-dependent Driver Requirements Device-dependent mouse drivers also have an IDC interface to the system's mouse$ driver. Such a driver must set up its header indicating that it participates in inter-device driver communication. Such a driver also must allocate storage in its primary data segment for the mouse$'s IDC addresses, as defined by the following structure: Attach_DD struc RealEntry dd ? ; real-mode entry point RealDS dw ? ; real-mode data segment ProtEntry dd ? ; protected-mode entry point ProtDS dw ? ; protected-mode data selector Attach_DD ends For more information about device driver headers and drivers' primary data segments, see Chapter 1, "Overview of Base and Installable Device Drivers." 5.3.1 Driver-supplied IDC Functions The device-dependent driver must supply the following five IDC functions that the mouse$ driver calls: Function code Function ──────────────────────────────────────────────────────────────────────────── 0001H Query_Config Returns device configuration data for the attached device. 0002H Read_Enable Calls the DevHlp routine AttachDD if the device-dependent driver has not yet established IDC to mouse$; always updates a flag indicating that the device-dependent driver may transfer data from the device into a shared buffer in the mouse$ driver's data segment and may call the ProcessPacket function (see Section 5.2). 0003H Read_Disable Updates a flag indicating that the device-dependent driver must wait for a Read_Enable call before it transfers data from the device into the shared buffer and calls ProcessPacket. 0004H Enable_Device Re-enables or reactivates the device, if necessary; enables interrupts at the port or at the device. 0005H Disable_Device Disables interrupts at the port or the device; makes the device quiescent, if necessary. , The device-dependent driver finds required parameters in specific registers when these functions are called. For detailed information about the Query_Config, Read_Enable, Read_Disable, Enable_Device, and Disable_Device functions, see Section 5.4. For more information about the AttachDD routine, see Chapter 3, "Device Helper Services." 5.3.2 Driver Command Support The device-dependent driver must provide full support for Init and Deinstall requests from the kernel. For all other requests, the driver's strategy routine may return the request packet with the standard error "Unknown command" (error code 03) and the error and done bits set in the Status field of the request packet. For more information about Init, Deinstall, and the request packet's Status field, see Chapter 2, "Device Commands." 5.3.2.1 Driver Initialization When the device-dependent driver installs, it must do the following: ■ Validate the machine it is loading on (IBM PC-AT, PS/2, Model 30-286, etc.). ■ Validate the presence of its device (adapter, ports, etc.). ■ Claim an exclusive or shared IRQ, as appropriate to the machine class. A serial driver is guaranteed exclusive access to the requested I/O port, but it cannot have exclusive access to a device interrupt. Drivers on a PS/2 that use ABIOS (advanced basic I/O system) services must not request a predetermined interrupt level and must share the IRQ level. ■ Disable the device until IDC initialization is complete (when the device-dependent driver's Read_Enable function has established IDC to the mouse$ driver). ■ Process the serial configuration command, if any, in config.sys. The default value for serial is com1; this value may be com1 or com2 on AT-class machines and may be com1 through com8 on PS/2 machines. The model parameter is valid only for the system-supplied drivers msser$ (model=099) and msbus$ (model=199). The mouse$ driver processes the mode, qsize, and type configuration commands in config.sys. The device-dependent driver's file name is the required parameter to the type command. Device-dependent drivers should follow the MS OS/2 standard naming convention for their file names. The format of a driver file name is a six-letter name, followed by a two-digit version number, followed by the extension sys. 5.3.2.2 Driver Deinstallation If the kernel sends a Deinstall request to the device-dependent driver, it must do the following: ■ Call the DisableSupport function through the IDC entry point for the current mode (protected or real). ■ Deinstall itself, releasing its IRQ, allocated memory, LID (logical ID) if the driver uses ABIOS services, etc. For more information about DisableSupport, see Sections 5.2 and 5.4. For more information about IDC entry points, see Section 5.3. 5.3.3 Interrupt Handling The device-dependent driver must supply an interrupt handler to service interrupts from its device. Once it has established IDC with the mouse$ driver, the device-dependent driver's interrupt handler must keep track of two things: ■ Whether the mouse$ driver is ready to process data from the device. ■ Whether the interrupt is enabled for its device. To track these states, the device-dependent driver maintains a DevStatus flag that may be a combination of the following values: Value Meaning ──────────────────────────────────────────────────────────────────────────── 0001H READENABLE─The mouse$ driver is ready to receive data from the device-dependent driver. 0002H ATTACHED─IDC has been established with the mouse$ driver (the device-dependent driver has IDC addresses stored in its primary data segment). 0004H IRQENABLED─The driver has claimed an IRQ for the device. 0008H DEINSTALLED─The device-dependent driver has deinstalled itself (the mouse$ driver must deinstall itself next). 0010H DEVICEENABLED─Interrupts are enabled at the port or the device, and the device itself is enabled. When DEVICEENABLED and IRQENABLED are set, the device-dependent driver may get data from its device and store it in a common format (for details, see the ProcessPacket function in Section 5.4) in the driver's data segment. However, the device-dependent driver may not transfer this data into the shared buffer provided by the mouse$ driver, nor may it call ProcessPacket, unless ATTACHED and READENABLE are also set. When an interrupt occurs, the device-dependent driver's interrupt handler should do the following: ■ Check whether the interrupt belongs to its device. If the interrupt does not belong, set the carry flag and return. Note that this interrupt handler, like every MS OS/2 interrupt handler, must use an inter-segment (far) ret instruction to return control to the system. ■ Otherwise, disable the device and call the DevHlp routine EOI. The interrupt handler should disable its device in the same manner as the driver's Disable_Device function, which must preserve the state of the interrupt flag (see Section 5.4). ■ Transfer formatted data to the shared buffer in the mouse$ driver's data segment, using the mouse$ driver's IDC ds address for the current mode. Call the ProcessPacket function when data transfer is complete. ■ If the device is disabled on return from ProcessPacket, re-enable the device. The interrupt handler should enable its device in the same manner as the driver's Enable_Device function, which must preserve the state of the interrupt flag (see Section 5.4). ■ Disable interrupts and clear the carry flag just before the interrupt handler returns control to the system. The device-dependent driver may call its own Disable_Device and Enable_Device functions, as long as these functions do not call any DevHlp routines that are illegal at interrupt time. For more information about EOI and the other interrupt-time DevHlp routines, see Chapter 3, "Device Helper Services." 5.4 Mouse IDC Function Reference The following sections describe both the system-supplied and driver-required mouse IDC functions, in alphabetic order. For the system-supplied functions ProcessPacket and DisableSupport, this section shows which registers must contain particular parameters when the device-dependent driver makes the call. For the driver-supplied functions Query_Config, Read_Enable, Read_Disable, Enable_Device, and Disable_Device, this section shows the contents of particular registers that each function can use when it is called. █ Disable_Device (0005H) ──────────────────────────────────────────────────────────────────────────── AX = 0005H ; Disable_Device function code DS = DD's DataSeg ; (called) device-dependent driver's DS ES = mouse$'s DataSeg ; (caller) device-independent driver's DS ; BX, CX, DX, DI, and SI undefined The Disable_Device function disables interrupts from the device, either at the port or at the device. If necessary, Disable_Device "sleeps" the device as well. Return Value AX = nonzero (error) if carry flag set, undefined if carry clear ES = mouse$'s DataSeg ; (caller) device-independent driver's DS ; (unchanged or restored to input value) ; BX, CX, DX, SI, DI, and DS undefined Comments The device-dependent driver supplies the Disable_Device function. Disable_Device must preserve the state of the interrupt flag, but it may disable interrupts using the cli instruction while it disables the device. Disable_Device updates the device-dependent driver's DevStatus flag with the following value: Value Meaning ──────────────────────────────────────────────────────────────────────────── NOT DEVICEENABLED Bit 4 clear─The device-dependent driver has disabled interrupts from its device. Disable_Device has also put the device into an inactive state, if disabling its interrupt does not make the device quiescent. The mouse$ driver calls Disable_Device when it must have interrupts from the device disabled at task or interrupt time. See Also Enable_Device █ DisableSupport (0002H) ──────────────────────────────────────────────────────────────────────────── Parameters ax the value 0002H, which is the function code for DisableSupport. es the selector or segment for the device-dependent driver's primary data segment. This value depends on the current operating mode (protected or real). IDC_DataSeg the IDC (inter-device driver communication) selector or segment value for the mouse$ driver's data segment. The device-dependent driver stored the IDC addresses in its own data segment at the initial call to Read_Enable; it must use the appropriate value for the current operating mode. IDC_Entry the selector:offset or segment:offset value for the mouse$ driver's IDC entry point. The device-dependent driver must use the appropriate value for the current operating mode. Return Value AX = nonzero (error) if carry flag set, undefined if carry clear DS = mouse$'s DataSeg ; (called) device-independent driver's DS ES = DD's DataSeg ; (unchanged or restored to input value) ; BX, CX, DX, DI, and SI undefined Comments The mouse$ driver supplies the DisableSupport function. The device-dependent driver calls DisableSupport if it gets a Deinstall request from the kernel. For more information about deinstallation, see Section 5.3.2.2. The device-dependent driver cannot make this call if its DevStatus flag shows the following value: Value Meaning ──────────────────────────────────────────────────────────────────────────── NOT ATTACHED Bit 1 clear─The device-dependent driver has not yet called the DevHlp routine AttachDD, or the call failed, so IDC has not been established with the mouse$ driver. For more information about AttachDD, see Chapter 3, "Device Helper Services." DisableSupport prevents the mouse$ driver from routing API calls to the device-dependent driver while it shuts down its device and releases the IRQ level that it claimed at initialization. █ Enable_Device (0004H) ──────────────────────────────────────────────────────────────────────────── AX = 0004H ; Enable_Device function code DS = DD's DataSeg ; (called) device-dependent driver's DS ES = mouse$'s DataSeg ; (caller) device-independent driver's DS ; BX, CX, DX, DI, and SI undefined The Enable_Device function enables interrupts from the device, either at the port or at the device itself, and, if necessary, reactivates the device as well. Return Value AX = nonzero (error) if carry flag set, undefined if carry clear ES = mouse$'s DataSeg ; (caller) device-independent driver's DS ; (unchanged or restored to input value) ; BX, CX, DX, SI, DI, and DS undefined Comments The device-dependent driver supplies the Enable_Device function. Enable_Device must preserve the state of the interrupt flag, but it may disable interrupts using the cli instruction while it enables the device. Enable_Device updates the device-dependent driver's DevStatus flag with the following value: Value Meaning ──────────────────────────────────────────────────────────────────────────── DEVICEENABLED Bit 4 set─The device-dependent driver has enabled interrupts from the device and restored it to the operational state that existed before the Disable_Device function was called. The mouse$ driver calls Enable_Device when it has completed task-time or interrupt-time operations that required interrupts from the device to be disabled. See Also Disable_Device █ ProcessPacket (0001H) ──────────────────────────────────────────────────────────────────────────── Parameters ax the value 0001H, which is the function code for ProcessPacket. es the selector or segment for the device-dependent driver's primary data segment. This value depends on the current operating mode (protected or real). IDC_DataSeg the IDC (inter-device driver communication) selector or segment value for the mouse$ driver's data segment. The device-dependent driver stored the IDC addresses in its own data segment at the initial call to Read_Enable; it must use the appropriate value for the current operating mode. IDC_Entry the selector:offset or segment:offset value for the mouse$ driver's IDC entry point. The device-dependent driver must use the appropriate value for the current operating mode. Return Value AX = nonzero (error) if carry flag set, undefined if carry clear DS = mouse$'s DataSeg ; (called) device-independent driver's DS ES = DD's DataSeg ; (unchanged or restored to input value) ; BX, CX, DX, DI, and SI undefined Comments The mouse$ driver supplies the ProcessPacket function. When an interrupt occurs, the device-dependent driver puts device data into a shared buffer in the mouse$ driver's data segment. The offset to this buffer was passed in the Read_Enable call. The device-dependent driver's interrupt handler calls ProcessPacket when it has completed getting, formatting, and transferring device data into this buffer. The buffer has the following structure: mouse_data struc butn_stat dw ? ; button-status flags: ; bit 0=1--pure motion (no buttons pressed) ; bit 1=1--button 1 pressed with motion ; bit 2=1--button 1 pressed without motion ; bit 3=1--button 2 pressed with motion ; bit 4=1--button 2 pressed without motion ; bit 5=1--button 3 pressed with motion ; bit 6=1--button 3 pressed without motion col_micks dw ? ; relative column mickey motion: ; +cols/pels = to right, -cols/pels = to left row_micks dw ? ; relative row mickey motion: ; +rows/pels = up, -rows/pels = down mouse_data ends The device-dependent driver reports mickey motion to the right or up as positive. It reports motion down or to the left as negative. The device-dependent driver must have its device disabled when it calls ProcessPacket. For more information about interrupt-handling requirements, see Section 5.3.3. See Also Disable_Device, Read_Enable █ Query_Config (0001H) ──────────────────────────────────────────────────────────────────────────── AX = 0001H ; Query_Config function code DS = DD's DataSeg ; (called) device-dependent driver's DS ES = mouse$'s DataSeg ; (caller) device-independent driver's DS DI = OFFSET Buffer ; in mouse$'s DataSeg (shared) ; BX, CX, DX, and SI undefined The Query_Config function returns configuration data for the attached device after the mouse$ driver has initialized IDC (inter-device driver communication) with the device-dependent driver and vice versa. Parameters es:di a protected-mode selector offset. On entry, this register pair points to a buffer in the mouse$ driver's data segment. The device-dependent driver returns the configuration data to this shared buffer when the call to Query_Config occurs. This buffer has the following structure: config_data struc length dw ? ; max=6 bytes (length of structure) num_micks db ? ; device resolution, mickeys/cm num_butn db ? ; number of device buttons dev_irq db ? ; device IRQ level mousetype db ? ; 0=unknown, 1=bus, 2=serial, 3=inport, ; 4=inboard (5-255 reserved) config_data ends On entry, the length field specifies the number of bytes of data to be returned. Return Value AX = nonzero (error) if carry flag set, undefined if carry clear ES = mouse$'s DataSeg ; (caller) device-independent driver's DS DI = OFFSET Buffer ; in mouse$'s DataSeg (shared) ; (ES:DI unchanged or restored to input values) ; BX, CX, DX, SI, and DS undefined Comments The device-dependent driver supplies the Query_Config function. Query_Config writes the device-dependent driver's configuration data into a buffer in the mouse$ driver's data segment. See Also Read_Enable █ Read_Disable (0003H) ──────────────────────────────────────────────────────────────────────────── AX = 0003H ; Read_Disable function code DS = DD's DataSeg ; (called) device-dependent driver's DS ES = mouse$'s DataSeg ; (caller) device-independent driver's DS ; BX, CX, DX, DI and SI undefined The Read_Disable function updates a software flag to disable data transfers from the device until a subsequent Read_Enable call occurs. Return Value AX = nonzero (error) if carry flag set, undefined if carry clear ES = mouse$'s DataSeg ; (caller) device-independent driver's DS ; (unchanged or restored to input value) ; BX, CX, DX, SI, DI, and DS undefined Comments The device-dependent driver supplies the Read_Disable function. Read_Disable updates the device-dependent driver's DevStatus flag with the following value: Value Meaning ──────────────────────────────────────────────────────────────────────────── NOT READENABLE Bit 0 clear─The device-dependent driver's interrupt handler may get data if an interrupt occurs at the device, but it may not reference the shared buffer in the mouse$ driver's data segment, and it may not call the ProcessPacket function. ' Read_Disable should disable interrupts, reset bit 0 of the DevStatus flag, and enable interrupts again. The interrupt handler must save any data that it gets locally until Read_Enable has been called to set bit 0 of the DevStatus flag. In particular, the device-dependent driver must not reference the shared data buffer in the mouse$ driver's data segment. The MS OS/2 mouse$ driver calls Read_Disable if it suspends data-packet processing and is not ready to receive data transferred from the device. See Also Enable_Device, ProcessPacket, Read_Enable █ Read_Enable (0002H) ──────────────────────────────────────────────────────────────────────────── AX = 0002H ; Read_Enable function code DS = DD's DataSeg ; (called) device-dependent driver's DS ES = mouse$'s DataSeg ; (caller) device-independent driver's DS DI = OFFSET Buffer ; in mouse$'s DataSeg (shared) ; BX, CX, DX, and SI undefined The Read_Enable function updates a software flag that enables the device-dependent driver to transfer data to the mouse$ driver. Read_Enable also attaches the device-dependent driver to mouse$, if it is not already attached, in order to get IDC (inter-device driver communication) entry addresses for the ProcessPacket function and IDC selector and segment values for the mouse$ driver's data segment. Parameters es:di a protected-mode selector:offset, since Read_Enable is called just after the mouse$ driver installs. On entry, this register pair points to a shared buffer in the mouse$ driver's data segment. The device-dependent driver should save the offset value so that its interrupt handler can return data to the buffer, using the mouse$ driver's IDC ds value for the current mode. For more information about the structure of the buffer, see the ProcessPacket function. Return Value AX = nonzero (error) if carry flag set, undefined if carry clear ES = mouse$'s DataSeg ; (caller) device-independent driver's DS ; (unchanged or restored to input value) ; BX, CX, DX, SI, DI, and DS undefined Comments The device-dependent driver supplies the Read_Enable function. Read_Enable updates the device-dependent driver's DevStatus flag with one or both of the following values: Value Meaning ──────────────────────────────────────────────────────────────────────────── READENABLE Bit 0 set─The device-dependent driver's interrupt handler may write device data into the shared buffer and call the ProcessPacket function. ATTACHED Bit 1 set─The device-dependent driver has copies of the mouse$ driver's IDC addresses stored in its primary data segment. If the device-dependent driver does not have copies of the mouse$ driver's IDC addresses already, Read_Enable must call the DevHlp routine AttachDD to get these addresses. Read_Enable sets bit 1 of the DevStatus flag when the AttachDD call succeeds. If the AttachDD call fails, the kernel sends a Deinstall request to the device-dependent driver. For more information about IDC addresses, see Section 5.3. For more information about AttachDD, see Chapter 3, "Device Helper Services." For more information about deinstallation, see Section 5.3.2.2. The driver's interrupt handler must use the mouse$ driver's IDC ds value for the current mode (protected or real) with the offset value passed in the si register to transfer data into the shared buffer. It must also use the IDC entry address for the current mode when it calls the ProcessPacket function. The MS OS/2 mouse$ driver calls Read_Enable when it has set up data-packet processing and is ready to receive data from the device. See Also Enable_Device, ProcessPacket, Read_Disable Chapter 6 Overview of Presentation Manager Device Drivers ──────────────────────────────────────────────────────────────────────────── 6.1 Introduction This chapter describes MS OS/2 Presentation Manager device drivers, the graphics engine, installed simulations, and the components of a Presentation Manager device driver. 6.2 Overview To create output on a device, Presentation Manager applications call down to the graphics engine through the window manager and the graphics programming interface (GPI). The graphics engine is the heart of Presentation Manager graphics. It processes many graphics requests from GPI and the window manager and passes other calls to a device driver. A device driver, in turn, converts the calls to device-specific instructions and passes those instructions to the device, which creates output. The following illustration shows the relationship between a Presentation Manager application, the window manager, the graphics programming interface, the graphics engine, the installed simulations, a device driver, and a device: (This figure may be found in the printed book). .AR 168p 6.3 The Graphics Engine The graphics engine is a dynamic-link library containing functions that do the following tasks: ■ Process graphics requests from GPI and the window manager using the dispatch table. ■ Manage the engine's device context (DC). ■ Manage local identifiers (LCIDs) for fonts and bitmaps. ■ Create, alter, and destroy journal files. 6.3.1 Graphics Engine Functions The graphics engine functions, like most API functions, are device independent. These functions process data for any output device that a Presentation Manager device driver supports. 6.3.2 Graphics Engine Dispatch Table The graphics engine processes some graphics requests from GPI and the window manager and passes other calls to a device driver. The engine keeps track of which calls it should process and which calls it should pass─via a dispatch table─to the driver. A dispatch table is an array of function addresses that resides in the engine's heap. When GPI or the window manager calls the engine, the engine locates the address of the corresponding function in the dispatch table and passes execution to that address. 6.3.2.1 Device Context Management Functions The engine's device context is a data structure that contains attribute bundles, an LCID table, and graphics data structures─for example, arc parameters and transformation matrices. The graphics engine manages its device context by altering its fields when an application changes corresponding fields in its presentation space. For example, when an application changes character colors or line styles, graphics engine functions alter the fields in the corresponding attribute bundles. 6.3.2.2 LCID Management Functions When an application creates a font or a fill pattern (from a bitmap), it identifies that font or fill pattern with a local identifier. However, a device driver identifies bitmaps and fonts with handles, not LCIDs. The graphics engine contains functions that translate a local identifier into a handle that a device driver can use. 6.3.2.3 Journal Functions A journal file is a special file that raster printers use for banding operations. Banding operations make it possible for some raster printers to create complex line output even though they cannot scroll backwards. The graphics engine contains functions that create, alter, and destroy journal files. 6.4 Presentation Manager Device Drivers A Presentation Manager device driver is a dynamic-link library containing functions that do the following tasks: ■ Enable a device driver. ■ Retrieve device capabilities (or modes). ■ Retrieve the names of supported devices. ■ Set pels on a device. ■ Draw lines, bitmaps, and text on a device. ■ Disable a device driver. 6.4.1 Device Driver Functions The device driver functions are device dependent. Unlike the graphic engine functions, which process data for any output device, Presentation Manager device driver functions support only a certain device, or certain type of device. For example, a driver for the HP laser printer may support several printer models. 6.4.1.1 Enable Functions When an application calls the DevOpenDC function, the graphics engine loads a device driver and calls the driver's OS2_PM_DRV_ENABLE function. All Presentation Manager device drivers contain a function with the name OS2_PM_DRV_ENABLE, which calls four subfunctions to enable the driver. This function is not found in the dispatch table. Instead, the device driver exports the function in its module definition file. The following excerpt from a module definition file shows how one device driver exports the enable function and assigns it the optional ordinal value 200: . . . EXPORTS OS2_PM_DRV_ENABLE @200 To enable a device driver, OS2_PM_DRV_ENABLE calls the following four subfunctions: Subfunction name Description ──────────────────────────────────────────────────────────────────────────── FILL_LOGICAL_DEVICE_BLOCK Constructs a dispatch table and initializes the device driver. FILL_PHYS_DEVICE_BLOCK Constructs a data structure for the physical device that describes the current drawing environment. ENABLE_DDC Reserves memory for and initializes a device's instance data. COMPLETE_OPEN_DDC Performs additional driver initialization after a device context is complete. 6.4.1.2 Modes Function When an application calls the DevPostDeviceModes function, the graphics engine calls the driver's OS2_PM_DRV_DEVMODE function, which retrieves device capabilities, or modes. This function, like the enable function, is exported by the device driver (and is not found in the dispatch table); it copies mode data into the abGeneralData field of a DRIVDATA structure. This structure has the following form: typedef struct _DRIVDATA { /* driv */ LONG cb; LONG lVersion; CHAR szDeviceName[32]; CHAR abGeneralData[1]; } DRIVDATA; When an application calls DevPostDeviceModes and sets the pbDriverData parameter to NULL, OS2_PM_DRV_DEVMODE returns the length of the DRIVDATA structure. When the application allocates space for the data and calls DevPostDeviceModes a second time, OS2_PM_DRV_DEVMODE fills abGeneralData, the last field in the structure, with device-specific information. 6.4.1.3 Names Function When an application calls the DevOpenDC function, the graphics engine loads a device driver and calls the driver's OS2_PM_DRV_ENABLE function. When an application calls the DevQueryDeviceNames function, the graphics engine calls the driver's OS2_PM_DRV_DEVICENAMES function, which retrieves a list of names of the devices that a device driver supports. A Presentation Manager device driver must export this function, also, in its module definition file. OS2_PM_DRV_DEVICENAMES corresponds to the DevQueryDeviceNames function. When an application calls DevQueryDeviceNames and sets the pdn and pdt parameters to zero, OS2_PM_DEVICNAMES returns the number of devices supported by the driver. When the application allocates space for these device names and types, OS2_PM_DEVICENAMES returns the name of each device that the driver supports. 6.4.1.4 Output Functions A device driver contains a number of functions that convert graphics requests from the engine into device-specific instructions that set pels and draw lines, bitmaps, and text. The device driver adds the addresses of these functions to the engine's dispatch table when Presentation Manager calls the driver's enable function. 6.4.1.5 Disable Functions To disable a driver, OS2_PM_DRV_ENABLE calls the following three subfunctions: Subfunction name Description ──────────────────────────────────────────────────────────────────────────── DISABLE_PHYS_DEVICE_BLOCK Disables a device and deallocates the memory that the device driver used. DISABLE_DDC Informs a device driver that it should deallocate the memory that it allocated for a device context. BEGIN_CLOSE_DDC Signals a device driver that a device context is about to close. 6.4.2 Presentation Manager Display Drivers Together, a display driver and the graphics engine provide the code and entry points for 212 functions. A Presentation Manager display driver must provide code and entry points for 69 of these functions; the graphics engine provides the code and entry points for the remaining 143. The 69 required functions are in the following categories: Function category Description ──────────────────────────────────────────────────────────────────────────── Drawing The drawing functions set and retrieve the current position, draw lines and arcs, set individual pels, clear the display, and save and restore screens. Bitmap The bitmap functions perform bit block transfers (bitblt operations) and create, delete, and select bitmaps. Text The text functions draw strings of text. Font The font functions retrieve information about available display fonts, set the code page, retrieve the current code-page identifier, and perform other font operations. Attribute The attribute functions set and retrieve line, character, image, marker, and area attributes. Bounds The bounds functions retrieve and set the dimensions of the current boundary rectangle. Correlation The correlation functions retrieve and set the dimensions of the current pick-aperture rectangle. Escape The escape functions create documents, print horizontal "bands" of a bitmap or document, and delete documents. Window management The window-management functions prevent other processes from drawing to the display, set the device-context origin, and invalidate the current visible region. Optimization The optimization functions provide notification of clipping or transformation changes. Color table The color-table functions retrieve and set color information. Query The query functions retrieve bitmap and display information. For a list of function names in each of these categories, see Chapter 7, "Graphics Functions." 6.4.3 Presentation Manager Printer and Plotter Drivers Together, a Presentation Manager printer or plotter driver and the graphics engine must support a total of 199 functions. There are three types of Presentation Manager printer and plotter drivers. Each provides code and entry points for a specific set of functions. The first type of driver is called a minimal driver because it provides code and entry points for the required minimum 56 functions. The graphics engine provides the code and entry points for the remaining 143 functions needed for graphics operations. The second type of driver is called a lazy driver because it relies on a second device driver to provide the code and entry points for most of the 56 required functions. The graphics engine supports the remaining 143 functions that are not supported by the lazy driver or its counterpart. The third type of driver is called a sophisticated driver because it provides code and entry points for the 56 required functions as well as many of the functions that the graphics engine typically supports. The actual number of functions supported by a sophisticated driver varies, depending on the capabilities of the device. (Of the remaining 199 functions, the graphics engine supports any that a sophisticated driver does not support.) The following list describes the categories of functions that a Presentation Manager printer driver and the graphics engine support: Function category Description ──────────────────────────────────────────────────────────────────────────── Arc The arc functions set and retrieve the arc parameters and draw partial arcs and ellipses, fillets and splines, paths, and rectangles (with rounded or square corners). Line The line functions set and retrieve the current position, draw connected line segments, and draw the short line segments that construct an arc. Scan The scan function draws multiple scan-lines. This is the function that fills the interior of areas. Bitmap The bitmap functions create and destroy bitmaps on a device, set single pels, and copy bitmap bits to memory. String The string functions draw character strings and retrieve character-string information. Marker The marker function draws one or more markers. Path The path functions create, modify, draw, and destroy paths and areas. Region The region functions create, fill, and combine regions and compute their dimensions. Clip The clip functions create clipping regions, save and restore regions, and determine whether points lie within a region. Transformation The transformation functions set scaling, rotation, translation, reflection, and shear transformations. Color The color functions create color tables and set and retrieve color information. Device The device functions retrieve device-specific bitmap information, device capabilities (such as aspect ratios, color capabilities, and default page sizes), and perform escape operations such as creating and closing documents and banding (printing horizontal "bands" of a bitmap or document). Miscellaneous The miscellaneous functions set and retrieve device attributes (such as pen color and fill-pattern texture), select a code page, retrieve the current code page identifier, select a font, retrieve information about available fonts, and lock and unlock a device. 6.4.3.1 Minimal Presentation Manager Drivers Minimal printer or plotter drivers must provide the code and entry points for 56 required functions. These 56 functions are in the following categories: ■ Line ■ Scan ■ Bitmap ■ String ■ Marker ■ Color ■ Device ■ Miscellaneous For a list of these required functions, see Chapter 7, "Graphics Functions." A minimal driver relies on the graphics engine to provide the code and entry points for the functions in the following categories: ■ Arc ■ Path ■ Region ■ Clip ■ Transformation 6.4.3.2 Lazy Presentation Manager Drivers Lazy Presentation Manager printer or plotter drivers rely on a second device driver and the graphics engine to provide code and entry points for the most of the dispatch-table functions. The sample Epson printer driver that ships with this package is a lazy driver. The Epson driver provides the code and entry points for 13 of the required functions. The Epson driver relies on a display driver to provide the code and entry points for 43 additional functions. The graphics engine provides the code and entry points for the remaining functions. 6.4.3.3 Sophisticated Presentation Manager Drivers Sophisticated Presentation Manager printer or plotter drivers support devices that use private page-description languages such as PostScript. These drivers provide the code and entry points for many functions that are supported by the graphics engine. For example, minimal and lazy drivers rely on graphics-engine code and entry points for the FullArcBoundary, FullArcInterior, and FullArcBoth functions. Sophisticated drivers, however, often provide code and entry points for these functions. The PostScript driver that ships with this package is a sophisticated driver. 6.5 Installed Simulations The engine's dispatch table may contain addresses of installed simulations that the system loaded at boot time. An installed simulation is a graphics function that replaces a graphics-engine simulation in order to enhance the performance of Presentation Manager applications. For example, the graphics-engine simulations that perform geometric transformations do not use an 80387 math coprocessor for floating-point computations. Instead, they use special 32-bit values called fixed values. However, floating-point computations performed with fixed values are significantly slower than computations performed with an 80387 math coprocessor. Therefore, to take advantage of the speed improvements offered by an 80387 coprocessor, a user would load the dispatch table with the addresses of installed simulations that would replace the graphics engine's transformation simulations. To load these simulations, the user would create appropriate entries in the config.sys file. 6.6 Device Driver Components A module definition file for a Presentation Manager device-driver describes the components that form the driver. These components include code and data segments, a heap, a stack, exported and imported functions, and a stub program. Some of these components are commmon to all types of drivers; others are found only in one type. Some components are optional; some are required. 6.6.1 Components Common to All Drivers There are five components common to all Presentation Manager drivers: ■ At least one ring-3 code segment ■ One or more ring-2 code segments ■ At least one data segment that contains driver instance data ■ An exported call to the OS2_PM_DRV_ENABLE function ■ A stub program that executes from real mode 6.6.1.1 Ring-3 Code Segments Most Presentation Manager drivers declare one ring-3 code segment in the module definition file. This code segment, which executes at ring-3, contains a module entry point that the graphics engine uses to initialize the driver, This initialization code is necessary if the driver will maintain an instance data structure in its heap. An instance data structure contains information about the current drawing environment, including line, arc, and text drawing information, color table information, and so on. The following excerpt from a driver's module definition file shows the declaration of a ring-3 code segment: SEGMENTS . . . _TEXTRING3 CLASS 'CODE' SHARED 6.6.1.2 Ring-2 Code Segments Every Presentation Manager driver declares one or more ring-2 code segments in its module definition file. These code segments, which execute at ring-2, contain the graphics code that accesses the device's I/O ports. (In order to access I/O ports, these functions must execute at ring-2.) The following excerpt from a driver's module definition file shows the declaration of a ring-2 code segment: SEGMENTS . . . _TEXT CLASS 'CODE' SHARED IOPL CONFORMING The IOPL constant specifies that the code segment executes at ring-2. The CONFORMING constant specifies that either ring-2 or ring-3 code segments can call functions in this segment. 6.6.1.3 Instance Data Most Presentation Manager drivers create at least one data segment that contains the driver's instance data. The following excerpt from a driver's module definition file shows the declaration for this data segment: SEGMENTS . . . _DATA CLASS 'DATA' SHARED 6.6.1.4 Enable Function All Presentation Manager drivers (whether they are printer, plotter, or display drivers) must export the enable function OS2_PM_DRV_ENABLE. This is the function that the graphics engine calls after an application issues the DevOpenDC call for a particular device. The following excerpt from a driver's module definition file shows the declaration that exports this call: EXPORTS OS2_PM_DRV_ENABLE 6.6.2 Components Common to Printer or Plotter Drivers There are five components common to printer and plotter drivers but not display drivers: ■ Two exported calls to the OS2_PM_DRV_DEVMODE and OS2_PM_DRV_DEVICENAMES functions ■ At least one exported call to a dialog procedure ■ A resource that defines the printer dialog boxes ■ Two imported calls to the GetDriverInfo and SetDriverInfo functions ■ An imported call to the GreEntry functions 6.6.2.1 Exported Calls Most printer and plotter drivers export two functions: OS2_PM_DRV_DEVMODE and OS2_PM_DRV_DEVICENAMES. An application or the Control Panel calls these functions to display a dialog that identifies job properties or to retrieve the names of devices that a driver supports. The graphics engine calls OS2_PM_DRV_DEVMODE after an application calls DevPostDeviceModes, and calls OS2_PM_DRV_DEVICENAMES after an application calls DevQueryDeviceNames. The following excerpt from a driver's module definition file shows the declaration that exports these two functions: EXPORTS . . . OS2_PM_DRV_DEVMODE OS2_PM_DRV_DEVICENAMES 6.6.2.2 Exported Dialog Procedure If a printer or plotter driver exports OS2_PM_DRV_DEVMODE, it should either export its dialog procedure or define the procedure with the _loadds keyword. This dialog procedure processes messages for the dialog controls. The following excerpt from a driver's module definition file shows the declaration that exports a driver's dialog procedure: EXPORTS . . . DrvDlgProc @32 This declaration uses the optional ordinal value 32. 6.6.2.3 Dialog Resources In addition to exporting a dialog procedure, a printer or plotter driver should also provide a resource that describes the dialog. The resource defines the size and style of the dialog-window frame and specifies each control item. For more information about dialogs and dialog procedures, see the Microsoft Operating System/2 Programmer's Reference, Volume 1. 6.6.2.4 Imported Information Functions A printer or plotter driver should import the engine functions GetDriverInfo and SetDriverInfo. GetDriverInfo validates an engine device context or bitmap handle. SetDriverInfo associates driver instance data with an engine device context or bitmap. The following excerpt from a driver's module definition file shows the declarations that import the GetDriverInfo and SetDriverInfo functions: IMPORTS . . . GetDriverInfo =PMGRE.GETDRIVERINFO SetDriverInfo =PMGRE.SETDRIVERINFO 6.6.2.5 Imported Callback Functions If it calls back to the graphics engine, a printer or plotter driver should import the graphics engine's GreEntry functions. There are nine GreEntry functions, each identified by a number in the function name that specifies the number of arguments that the function handles. The following excerpt from a driver's module definition file shows the declarations that import the GreEntry functions: IMPORTS . . . GreEntry2 =PMGRE.GREENTRY2 GreEntry3 =PMGRE.GREENTRY3 GreEntry4 =PMGRE.GREENTRY4 GreEntry5 =PMGRE.GREENTRY5 GreEntry6 =PMGRE.GREENTRY6 GreEntry7 =PMGRE.GREENTRY7 GreEntry8 =PMGRE.GREENTRY8 GreEntry9 =PMGRE.GREENTRY9 GreEntry10 =PMGRE.GREENTRY0 6.6.3 Components Common to Display Drivers There are three components common to display drivers but not printer and plotter drivers: ■ A resource that defines system pointer shapes, system bitmaps, and system fonts ■ A ring-2 code segment that contains cursor-drawing functions ■ A ring-2 data segment that contains cursor-drawing data 6.6.3.1 Display Resources All display drivers must provide a resource that defines system pointers, system bitmaps, and system fonts. 6.6.3.2 Cursor Code Segment All display drivers must place cursor-drawing functions in code segments that are not movable. The following excerpt from a display-driver's module definition file shows the declaration that exports the code segment containing the cursor code: EXPORTS . . . _POINTER CLASS 'CODE' SHARED PRELOAD IOPL 6.6.3.3 Cursor Data Segment All display drivers must place cursor data structures in a data segment that is not movable. The following excerpt from a display-driver's module definition file shows the declaration that exports the data segment containing the cursor data structures: EXPORTS . . . _POINTERDT CLASS 'DATA' SHARED PRELOAD IOPL Chapter 7 Graphics Functions ──────────────────────────────────────────────────────────────────────────── 7.1 Introduction This chapter describes the functions for graphics device drivers as used by MS OS/2 Presentation Manager. These drivers provide graphics, alphanumerics, and raster operations to output devices (for example, screen windows) and to bitmaps. A graphics device driver is a dynamic-link library, a collection of code and data segments that applications access at run time. The code segments in a device driver's dynamic-link library contain the functions that convert application requests for graphics operations into actual device commands. 7.1.1 Function Definitions The function definitions in this chapter give a function name, function syntax in C format, and function operation. The definition also gives a detailed explanation of the function parameters. All handles and pointers are passed to functions as 32-bit values. Coordinates passed to functions are 28-bit values in world or model space, as defined by the function call. After transformation to device space, coordinate values must be in the range -32,768 to 32,767, inclusive. The error condition PMERR_COORDINATE_OVERFLOW should be raised when the (x,y) coordinate is too large to handle. Parameters are passed using the Pascal calling convention. This means the parameters in the function syntax are pushed in left-to-right order. The function must pop the parameters off the stack before returning. The last parameter passed to most of the functions is the ulFunN parameter. The high word of this parameter contains a mask of the following flags, which may be set by the graphics programming interface (GPI), the engine, or a driver: Flag Description ──────────────────────────────────────────────────────────────────────────── COM_DRAW Indicates that primitives should be drawn on the output device. COM_BOUND Indicates that boundary data should be collected for the application. COM_CORRELATE Indicates that correlation should be performed. COM_ALT_BOUND Indicates that boundary data should be collected for the window manager. COM_AREA Indicates that an area bracket is open. COM_PATH Indicates that a path bracket is open. COM_TRANSFORM Indicates that transformations should be performed. COM_RECORDING Indicates that journaling is in progress. COM_DEVICE Indicates that the driver must handle this call. (The driver cannot pass the call back to the engine if this bit is set.) The functions should also save and restore the si, di, ds, and bp registers. The dx:ax register may need to be used for return values. Registers bx, cx, and es may be destroyed. 7.1.2 Function Categories This chapter contains an alphabetic list of engine, installed-simulation, and device driver functions. These functions are divided into two categories: 1. Functions handled only by the engine or by installed simulations. 2. Functions handled by the engine, by installed simulations, or by the device driver. The functions in the first category either process information that isn't available to a device driver, or they perform device-independent operations. For example, the OpenDC, CloseDC, and ResetDC functions are in the first category because they process device-context information (device drivers cannot access device contexts). In addition to the device-context functions, the first category includes the local identifier (LCID) functions, journaling functions, and all of the device-independent graphics-engine functions. The functions in the second category include the required device driver functions as well as the engine-simulation functions that a device driver or an installed simulation can hook. (A device driver or installed simulation "hooks" a function when it replaces that function in the device driver's dispatch table.) The functions in the second category can be subdivided into subcategories (or groups). For example, the second category contains arc, logical-color-table, transformation, bitmap, region, and other function groups. The following section lists all of the functions by group and specifies whether they belong to the first or the second category. 7.2 Function Groups The graphic functions are grouped as follows: ■ Arc functions ■ Line functions ■ Scanning functions ■ Bitmap functions ■ Window-pointer functions ■ String functions ■ Marker functions ■ Path functions ■ Region functions ■ Clipping functions ■ Transformation functions ■ Miscellaneous functions ■ Pick-window functions ■ Logical-color-table functions ■ Device functions ■ Device-context functions ■ Device-support functions ■ SetId and LCID functions ■ Font functions ■ Journaling functions The following sections list the functions in each group, with a brief description of the group as a whole. Each list specifies whether a function belongs to category one or two and whether the function is display specific or is used in both display and printer drivers. The following designators are used: Designator Meaning ──────────────────────────────────────────────────────────────────────────── [ENGINE] The function belongs to category one and is not hookable. Only the graphics engine or an installed simulation will handle these functions. [REQUIRED] The function belongs to category two and is hookable. Printer, plotter, and display device drivers must handle these functions since there are no corresponding graphics-engine simulations. [REQUIRED/DISPLAY] The function belongs to category two and is hookable. Display device drivers must handle these functions since there are no corresponding graphics-engine simulations. These functions are not required by printer or plotter device drivers. Unless designated as an ENGINE function, every function listed is "hookable." 7.2.1 Arc Functions The arc functions draw arcs, such as circles, ellipses, fillets, splines, and other curved figures. There are the following arc functions: Arc BoxBoth BoxBoundary BoxInterior CookPathCurves CookWholePath DrawConicsInPath FullArcBoth FullArcBoundary FullArcInterior GetArcParameters GetDefaultArcParameters PartialArc PolyFillet PolyFilletSharp PolySpline RenderPath SetArcParameters SetDefaultArcParameters 7.2.2 Line Functions The line functions draw straight lines and set the current position. There are the following line functions: DisjointLines DrawLinesInPath [REQUIRED] GetCurrentPosition [REQUIRED] PolyLine PolyShortLine [REQUIRED] SetCurrentPosition [REQUIRED] 7.2.3 Scanning Functions The scanning function draws rows of bits on a page of printer paper or the video display. There is one scanning function: PolyScanline [REQUIRED] 7.2.4 Bitmap Functions The bitmap functions set bitmap bits, draw bitmapped images, set individual pels on a display, retrieve the state of pels on the display, and perform other related bitmap operations. There are the following bitmap functions: Bitblt [REQUIRED] DeviceCreateBitmap [REQUIRED] DeviceDeleteBitmap [REQUIRED] DeviceSelectBitmap [REQUIRED] DeviceSetCursor [REQUIRED/DISPLAY] DrawBorder [REQUIRED/DISPLAY] GetBitmapBits [REQUIRED] GetPel [REQUIRED] ImageData [REQUIRED] RestoreScreenBits [REQUIRED/DISPLAY] SaveScreenBits [REQUIRED/DISPLAY] SetBitmapBits [REQUIRED] SetPel [REQUIRED] 7.2.5 Window-Pointer Functions The window-pointer function repositions and redraws a color-cursor bitmap. There is one window-pointer function: SetColorCursor 7.2.6 String Functions The display functions draw strings of text output and retrieve text and character information. There are the following string functions: CharRect [REQUIRED/DISPLAY] CharStr [REQUIRED/DISPLAY] CharString [REQUIRED] CharStringPos [REQUIRED] QueryCharPositions QueryTextBox QueryWidthTable ScrollRect [REQUIRED/DISPLAY] UpdateCursor [REQUIRED/DISPLAY] 7.2.7 Marker Functions The marker function draws one or more special characters called a marker. There is one marker function: PolyMarker [REQUIRED] 7.2.8 Path Functions The path functions create, modify, and draw paths and areas. There are the following path functions: AreaSetAttributes BeginArea BeginPath Clip1DPath CloseFigure DrawCookedPath DrawRawPath EndArea EndPath FillPath ModifyPath OutlinePath RestorePath SavePath SelectClipPath StrokePath 7.2.9 Region Functions The region functions create, combine, offset, and draw regions. There are the following region functions: CombineRectRegion CombineRegion CombineShortLineRegion CreateRectRegion DestroyRegion EqualRegion GetRegionBox GetRegionRects OffsetRegion PaintRegion PtInRegion RectInRegion SetRectRegion SetRegionOwner 7.2.10 Clipping Functions The clipping functions create and alter clipping regions and perform related operations. There are the following clipping functions: ClipPathCurves CopyClipRegion ExcludeClipRectangle GetClipBox GetClipRects IntersectClipRectangle OffsetClipRegion PtVisible QueryClipRegion RectVisible RegionSelectBitmap RestoreRegion SaveRegion SelectClipRegion SelectPathRegion SetupDC SetXformRect 7.2.11 Transformation Functions The transformation functions set transformations and retrieve information about current transformation settings. There are the following transformation functions: Convert ConvertPath ConvertWithMatrix GetDefaultViewingLimits GetGlobalViewingXform GetGraphicsField GetModelXform GetPageUnits GetPageViewport GetViewingLimits GetWindowViewportXform MultiplyXforms QueryViewportSize RestoreXform RestoreXformData SaveXform SaveXformData SetDefaultViewingLimits SetGlobalViewingXform SetGraphicsField SetModelXform SetPageUnits SetPageViewport SetViewingLimits SetWindowViewportXform 7.2.12 Miscellaneous Functions This group of functions performs a variety of tasks, such as computing boundary data, retrieving font information, clearing the contents of a display, retrieving device-context information, and so on. These miscellaneous functions are listed as follows: AccumulateBounds [REQUIRED] Death [REQUIRED/DISPLAY] DeviceGetAttributes [REQUIRED] DeviceInvalidateVisRegion [REQUIRED/DISPLAY] DeviceQueryFontAttributes [REQUIRED] DeviceQueryFonts [REQUIRED] DeviceSetAttributes [REQUIRED] DeviceSetAVIOFont [REQUIRED/DISPLAY] DeviceSetDCOrigin [REQUIRED] DeviceSetGlobalAttribute [REQUIRED] ErasePS [REQUIRED] GetBoundsData [REQUIRED] GetCodePage [REQUIRED] GetDCOrigin GetLineOrigin [REQUIRED] GetPairKerningTable [REQUIRED] GetStyleRatio [REQUIRED] LockDevice [REQUIRED] NotifyClipChange [REQUIRED for clipping optimizations] NotifyTransformChange [REQUIRED for transformation optimizations] RealizeFont [REQUIRED] ResetBounds [REQUIRED] Resurrection [REQUIRED/DISPLAY] SetCodePage [REQUIRED] SetLineOrigin [REQUIRED] SetStyleRatio [REQUIRED] UnlockDevice [REQUIRED] 7.2.13 Pick-Window Functions The pick-window functions set the pick window and retrieve its current dimensions. There are the following pick-window functions: GetPickWindow [REQUIRED/DISPLAY] SetPickWindow [REQUIRED/DISPLAY] 7.2.14 Logical-Color-Table Functions The logical-color-table functions create, alter, and retrieve information about logical color tables. There are the following logical-color-table functions: CreateLogColorTable [REQUIRED] QueryColorData [REQUIRED] QueryColorIndex [REQUIRED] QueryLogColorTable [REQUIRED] QueryNearestColor [REQUIRED] QueryRealColors [REQUIRED] QueryRGBColor [REQUIRED] RealizeColorTable [REQUIRED] UnrealizeColorTable [REQUIRED] 7.2.15 Device Functions The device functions set and retrieve device-dependent data. There are the following device functions: Escape [REQUIRED] QueryDeviceBitmaps [REQUIRED] QueryDeviceCaps [REQUIRED] QueryDevResource [REQUIRED] QueryHardcopyCaps [REQUIRED] 7.2.16 Device-Context Functions The device-context functions open, close, and alter an engine device context (DC). There are the following device-context functions: CloseDC [ENGINE] GetHandle [ENGINE] GetProcessControl [ENGINE] OpenDC [ENGINE] QueryDeviceNames [ENGINE] QueryEngineVersion [ENGINE] ResetDC [ENGINE] RestoreDC [ENGINE] SaveDC [ENGINE] SetDCOwner [ENGINE] SetHandle [ENGINE] SetProcessControl [ENGINE] 7.2.17 Device-Support Functions The device-support functions perform operations on a device. There are the following device-support functions: CreateBitmap [ENGINE] DeleteBitmap [ENGINE] GetAttributes [ENGINE] GetBitmapDimension [ENGINE] GetBitmapParameters [ENGINE] GetDefaultAttributes [ENGINE] InvalidateVisRegion [ENGINE] SelectBitmap [ENGINE] SetAttributes [ENGINE] SetBitmapDimension [ENGINE] SetBitmapOwner [ENGINE] SetCursor [ENGINE] SetDefaultAttributes [ENGINE] SetGlobalAttribute [ENGINE] 7.2.18 SetId and LCID Functions The SetId and LCID functions set, delete, and retrieve information about local identifiers (LCIDs). There are the following SetId and LCID functions: CopyDCLoadData [ENGINE] DeleteSetId [ENGINE] QueryBitmapHandle [ENGINE] QueryNumberSetIds [ENGINE] QuerySetIds [ENGINE] SetBitmapID [ENGINE] 7.2.19 Font Functions The font functions create, load, unload, and retrieve information about fonts. There are the following font functions: CreateLogicalFont [ENGINE] LoadFont [ENGINE] LoadPublicFont [ENGINE] QueryCodePageVector [ENGINE] QueryFontAttributes [ENGINE] QueryFontFileDescriptions [ENGINE] QueryFonts [ENGINE] QueryLogicalFont [ENGINE] UnloadFont [ENGINE] UnLoadPublicFont [ENGINE] 7.2.20 Journaling Functions The journaling functions create, delete, alter, and play journal files. There are the following journal functions: AccumulateJournalFile [ENGINE] CreateJournalFile [ENGINE] DeleteJournalFile [ENGINE] OpenJournalFile [ENGINE] PlayJournalFile [ENGINE] StartJournalFile [ENGINE] StopJournalFile [ENGINE] 7.3 Function Directory This section describes the graphics device functions, in alphabetic order. █ AccumulateBounds ──────────────────────────────────────────────────────────────────────────── ULONG AccumulateBounds (hdc, prcl, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ PRECTL prcl; /*pointer to RECTL structure */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The AccumulateBounds function computes the dimensions of the smallest rectangle that will completely surround existing output. The coordinates of the rectangle's lower-left and upper-right corners are stored in a RECTL structure pointed to by the prcl parameter. Parameters hdc the engine's device context. prcl to a RECTL structure that contains the coordinates of the rectangle's lower-left and upper-right corners in device space. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the device driver may record: PMERR_COORDINATE_OVERFLOW PMERR_DEV_FUNC_NOT_INSTALLED PMERR_HDC_BUSY PMERR_INV_COORD_SPACE PMERR_INV_HDC PMERR_INV_LENGTH_OR_COUNT PMERR_INV_RECT Comments This is a required device driver function. Any engine simulations that collect bounds data call this function. The engine, a simulation, or a device driver can accumulate boundary data. █ AccumulateJournalFile ──────────────────────────────────────────────────────────────────────────── ULONG AccumulateJournalFile (ulParam1, ..., ulParamN, hddc, ulFunN) TYPE ulParam1; /*first parameter of journaled function */ TYPE ulParamN; /*last parameter of journaled function */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The AccumulateJournalFile function creates a journal record for the specified function and stores the record on disk in a journal file. Parameters ulParam1 the first parameter of the journaled function. ulParamN the last parameter of the journaled function. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value This function returns the return value of the journaled function. Errors If an error occurs during the execution of this function, the graphics engine calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine may record: PMERR_BASE_ERROR PMERR_BITMAP_IS_SELECTED PMERR_BITMAP_NOT_SELECTED PMERR_COORDINATE_OVERFLOW PMERR_DEV_FUNC_NOT_INSTALLED PMERR_EXCEEDS_MAX_SEG_LENGTH PMERR_HBITMAP_BUSY PMERR_HDC_BUSY PMERR_HRGN_BUSY PMERR_HUGE_FONTS_NOT_SUPPORTED PMERR_INCOMPATIBLE_BITMAP PMERR_INCORRECT_DC_TYPE PMERR_INSUFFICIENT_MEMORY PMERR_INV_BACKGROUND_COL_ATTR PMERR_INV_BACKGROUND_MIX_ATTR PMERR_INV_BITBLT_MIX PMERR_INV_BITBLT_STYLE PMERR_INV_BITMAP_DIMENSION PMERR_INV_CHAR_DIRECTION_ATTR PMERR_INV_CHAR_MODE_ATTR PMERR_INV_CHAR_SET_ATTR PMERR_INV_CHAR_SHEAR_ATTR PMERR_INV_CODEPAGE PMERR_INV_COLOR_ATTR PMERR_INV_COLOR_DATA PMERR_INV_COLOR_FORMAT PMERR_INV_COLOR_INDEX PMERR_INV_COLOR_OPTIONS PMERR_INV_COLOR_START_INDEX PMERR_INV_COORD_SPACE PMERR_INV_COORDINATE PMERR_INV_DC_DATA PMERR_INV_DC_TYPE PMERR_INV_DRIVER_NAME PMERR_INV_GEOM_LINE_WIDTH_ATTR PMERR_INV_HBITMAP PMERR_INV_HDC PMERR_INV_HRGN PMERR_INV_ID PMERR_INV_IN_AREA PMERR_INV_IN_PATH PMERR_INV_INFO_TABLE PMERR_INV_LENGTH_OR_COUNT PMERR_INV_LINE_END_ATTR PMERR_INV_LINE_JOIN_ATTR PMERR_INV_LINE_TYPE_ATTR PMERR_INV_LINE_WIDTH_ATTR PMERR_INV_MARKER_SET_ATTR PMERR_INV_MARKER_SYMBOL_ATTR PMERR_INV_METAFILE PMERR_INV_MIX_ATTR PMERR_INV_PATTERN_REF_PT_ATTR PMERR_INV_PATTERN_SET_ATTR PMERR_INV_PATTERN_SET_FONT PMERR_INV_PICK_APERTURE_POSN PMERR_INV_PRIMITIVE_TYPE PMERR_INV_RECT PMERR_INV_REGION_CONTROL PMERR_INV_REGION_MIX_MODE PMERR_INV_SCAN_START PMERR_INV_SETID PMERR_INV_USAGE_PARM PMERR_JFILE_BUSY PMERR_JNL_FUNCTION_DATA_TOO_LONG PMERR_RAM_JNL_FILE_TOO_SMALL PMERR_REALIZE_NOT_SUPPORTED PMERR_REGION_IS_CLIP_REGION PMERR_UNSUPPORTED_ATTR PMERR_UNSUPPORTED_ATTR_VALUE Comments Only the graphics engine calls AccumulateJournalFile. If you develop an installed simulation that handles journaling, you must provide code for this function, in addition to the other journaling functions. █ Arc ──────────────────────────────────────────────────────────────────────────── LONG Arc (hdc, aptl, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ PPOINTL aptl; /*address of two-element array of POINTL structures */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The Arc function draws an arc using the current arc parameters. It draws the arc through three points: the current position, an intermediate point (which is the first point in the array addressed by the aptl parameter), and an endpoint (which is the last point in the array). Parameters hdc the engine's device context. aptl the address of a two-element array. Each element is a POINTL structure that specifies the arc's intermediate point and its endpoint. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is GPI_OK or GPI_HITS if the function is successful (it is GPI_HITS if the detectable attribute is set for the presentation space and a correlation hit occurs). The return value is GPI_ERROR if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine or the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine or the device driver calls record: PMERR_BASE_ERROR PMERR_BITMAP_NOT_SELECTED PMERR_COORDINATE_OVERFLOW PMERR_DEV_FUNC_NOT_INSTALLED PMERR_HDC_BUSY PMERR_INV_COLOR_DATA PMERR_INV_COLOR_INDEX PMERR_INV_COORD_SPACE PMERR_INV_HDC PMERR_INV_IN_AREA PMERR_INV_IN_PATH PMERR_INV_LENGTH_OR_COUNT PMERR_INV_MATRIX_ELEMENT PMERR_INV_PICK_APERTURE_POSN PMERR_INV_RECT PMERR_PATH_LIMIT_EXCEEDED PMERR_PATH_UNKNOWN Comments If the intermediate point is the same as either the startpoint or the endpoint, a straight line is drawn from the startpoint to the endpoint. The current position is updated to the second point in the array addressed by the aptl parameter. If the determinant of the arc parameters is significantly less than one (|pq - rs| < 1), this function will fail. █ AreaSetAttributes ──────────────────────────────────────────────────────────────────────────── BOOL AreaSetAttributes (hdc, ulType, flDefs, flAttrs, pBundle, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ ULONG ulType; /*attribute-bundle type */ ULONG flDefs; /*default mask */ ULONG flAttrs; /*attribute mask */ PBUNDLE pBundle; /*pointer to attribute bundle */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The AreaSetAttributes function sets the fields in the line-attribute bundle when an area bracket is open. Parameters hdc the engine's device context. ulType the type of attribute bundle. It can be one of the following values: Value Meaning ──────────────────────────────────────────────────────────────────────────── PRIM_LINE Line-attribute bundle PRIM_CHAR Character-attribute bundle PRIM_MARKER Marker-attribute bundle PRIM_AREA Pattern-attribute bundle PRIM_IMAGE Image-attribute bundle flDefs which attributes to set to their default values. flAttrs which attributes should be modified with the values in the bundle pointed to by the pBundle parameter. pBundle to a fixed-format bundle that contains the attribute values to be set, as specified by the flAttrs parameter. In the bundle, only the attribute fields that correspond to the attribute flags set in flAttrs and not set in the flDefs parameter contain valid values. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine or the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine or the device driver calls record: Comments The SetAttributes function calls AreaSetAttributes if an area bracket is open and an application attempts to modify any of the attribute bundles. If the attribute bundle is a line bundle, the function modifies the appropriate fields. If the attribute bundle is a character, marker, image, or pattern bundle, the function does not modify the bundle and leaves the original fields intact. If a device driver replaces the engine's area functions (such as BeginArea and EndArea), it must also replace the engine's version of AreaSetAttributes with its own code. █ BeginArea ──────────────────────────────────────────────────────────────────────────── LONG BeginArea (hdc, flCmd, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ ULONG flCmd; /*command flags */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The BeginArea function defines the beginning of an area bracket. An area bracket is a set of graphic functions that define the shape of an area's borders. Parameters hdc the engine's device context. flCmd whether boundary lines are to be drawn, and specifies whether the area is filled using the winding or the alternate mode. Bit Setting ──────────────────────────────────────────────────────────────────────────── 0 Set to 1 to draw boundary lines (BA_BOUNDARY); set to 0 for no boundary lines (BA_NOBOUNDARY). 1 Set to 1 for winding fill mode (BA_WINDING); set to 0 for alternate fill mode (BA_ALTERNATE). hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is GPI_OK if the function is successful or GPI_ERROR if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine or the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine or the device driver calls record: PMERR_ALREADY_IN_AREA PMERR_BASE_ERROR PMERR_COORDINATE_OVERFLOW PMERR_DEV_FUNC_NOT_INSTALLED PMERR_HDC_BUSY PMERR_INV_AREA_CONTROL PMERR_INV_COORD_SPACE PMERR_INV_HDC PMERR_INV_IN_PATH PMERR_INV_LENGTH_OR_COUNT PMERR_PATH_LIMIT_EXCEEDED Comments An area is one or more closed figures that are filled or filled and outlined. Although the current (x,y) position is not changed by BeginArea, it will be affected by the drawing orders in the boundary definition. Character, marker, image, and bitblt functions are invalid in an area bracket, as are functions that alter the background color or mix mode. Only line and arc functions are valid in an area bracket. Correlation occurs after the area is drawn. (Correlation cannot occur within an open area bracket.) █ BeginPath ──────────────────────────────────────────────────────────────────────────── BOOL BeginPath (hdc, phid, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ PHID phid; /*path identifier (must be 1 for current release of PM)*/ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The BeginPath function defines the beginning of a path bracket. A path bracket is a set of graphic functions that define the shape of a path. Parameters hdc the engine's device context. phid the path. This value must be 1 for the current release of MS OS/2 Presentation Manager. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine or the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine or the device driver calls record: PMERR_ALREADY_IN_PATH PMERR_BASE_ERROR PMERR_COORDINATE_OVERFLOW PMERR_DEV_FUNC_NOT_INSTALLED PMERR_HDC_BUSY PMERR_INV_COORD_SPACE PMERR_INV_HDC PMERR_INV_IN_AREA PMERR_INV_LENGTH_OR_COUNT PMERR_INV_PATH_ID PMERR_PATH_LIMIT_EXCEEDED Comments A path is a figure that is filled or outlined. Applications use paths to draw geometric (wide) lines, create nonrectangular clipping regions, and outline and/or fill irregular shapes and polygons. Paths can be open or closed. An open path is a path that is not terminated by the CloseFigure function. A closed path is one that is terminated by the CloseFigure function. A path bracket typically contains line and arc functions that define the shape of its borders. The EndPath function defines the end of a path bracket. If there are no line or arc functions between a BeginPath and an EndPath function call, a null path is defined. No more than one path bracket can be open at any given time. A path cannot be re-opened after a path bracket is closed (that is, after the EndPath function call.) Note that calling the ResetDC function within the path restores the device context to its original state and deletes all paths, fonts, patterns, etc. The CharString and CharStringPos functions are valid in a path bracket only if the current font is an outline font. Functions that set character attributes are not allowed in a path bracket. A path bracket cannot occur within an area bracket. A single path cannot contain more than 64K of data. █ Bitblt ──────────────────────────────────────────────────────────────────────────── LONG Bitblt (hdc, hdcSrc, cptl, pbbp, lMix, flCmd, pbba, hddc, ulFunN) HDC hdc; /*handle of engine's target device context */ HDC hdcSrc; /*handle of engine's source device context */ LONG cptl; /*number of points in array */ PBITBLTPARAMETERS pbbp; /*pointer to BITBLTPARAMETERS structure */ LONG lMix; /*color mix mode */ ULONG flCmd; /*line and column compression flag */ PBITBLTATTRS pbba; /*pointer to BITBLTATTRS structure */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The Bitblt function copies a bitmap from one device context to another. It can also modify a bitmap within a rectangle in a single device context. If the function modifies a bitmap within a single device context, the target coordinates can be either device or world coordinates. However, if the target coordinates are world coordinates, rotation transformations have no effect on the Bitblt operation. Parameters hdc the engine's target device context. hdcSrc the engine's source device context. cptl the number of points pointed to by the pbbp parameter. It can be one of the following: Value Meaning ──────────────────────────────────────────────────────────────────────────── 2 The points addressed by the pbbp parameter are the lower-left and upper-right corners of the target rectangle. If this value is specified, the mix mode must not use a source color. 3 The points addressed by pbbp are the lower-left and upper-right corners of the target rectangle, and the lower-left corner of the source rectangle. The upper-right corner of the target rectangle is adjusted so that the dimensions of the target rectangle are identical to those of the source rectangle. 4 The points addressed by pbbp are the lower-left and upper-right corners of the target and source rectangles. If the dimensions of the rectangles aren't equal, the source bitmap is stretched or compressed so that it fits the target rectangle. Bitblt uses the flCmd flag to determine how the bitmap should be compressed. If the raster operation does not include the source, the source coordinates are ignored. pbbp to a BITBLTPARAMETERS structure that contains the coordinates of the lower-left and upper-right corners of the target and source rectangles. lMix the raster operation for the function. It can be any value in the range 0 to 255. The raster operation is applied to each color plane in the target rectangle. For any pel in a target plane, three bits together with the raster operation value determine the color of the pel. These three bits specify the pattern color (P), source color (S), and initial value of the target color (T). For any combination of P-S-T values, the final target value is determined by the mix bit, as shown in the following table: (Initial) P-S-T (Final) T ──────────────────────────────────────────────────────────────────────────── 0 0 0 0 (Mix bit) (LS) 0 0 1 1 (Mix bit) 0 1 0 2 (Mix bit) 0 1 1 3 (Mix bit) 1 0 0 4 (Mix bit) 1 0 1 5 (Mix bit) 1 1 0 6 (Mix bit) 1 1 1 7 (Mix bit) (MS) A special gray raster operation is provided: ROP_GRAY 0x000080CA This option causes alternate pattern background pels to be written in the background color. Pattern foreground pels are left unchanged in the target. The source is ignored for this option. This is required for display device drivers but need not be supported for printer or plotter drivers. flCmd stretching and compressing options; specifies whether the target rectangle coordinates are world units; specifies whether the source handle is a bitmap handle or a device-context handle; and specifies whether the pbba argument contains the address of a BITBLTATTRS structure. Bits 0 and 1 of this flag have the following meaning: Value Meaning ──────────────────────────────────────────────────────────────────────────── 0x0000L If compression is necessary, OR the eliminated rows or columns (BBO_OR). 0x0001L If compression is necessary, AND the eliminated rows or columns (BBO_AND). 0x0002L If compression is necessary, ignore the eliminated rows or columns (BBO_IGNORE). 0x0003L The target rectangle's coordinates are world coordinates (BBO_TARGWORLD). Bit 16 of this flag has the following meaning: Value Meaning ──────────────────────────────────────────────────────────────────────────── 0 The source handle is a device context handle into which the bitmap is selected. 1 The source handle is a bitmap handle. (If this bit is set, the bitmap cannot be currently selected into a device context). Bit 17 of this flag has the following meaning: Value Meaning ──────────────────────────────────────────────────────────────────────────── 0 The pbba parameter is ignored. 1 The pbba parameter contains the address of a BITBLTATTRS structure. pbba to a BITBLTATTRS structure that contains information about the source bitmap's background and foreground color: typedef struct _BITBLTATTRS { /* bba */ LONG cSize; LONG lColor; LONG lBackColor; } BITBLTATTRS; You must provide this structure if the source handle identifies a color bitmap. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is GPI_OK or GPI_HITS if the function is successful (it is GPI_HITS if the detectable attribute is set for the presentation space and a correlation hit occurs). The return value is GPI_ERROR if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine may record: PMERR_BASE_ERROR PMERR_BITMAP_IS_SELECTED PMERR_BITMAP_NOT_SELECTED PMERR_COORDINATE_OVERFLOW PMERR_DEV_FUNC_NOT_INSTALLED PMERR_EXCEEDS_MAX_SEG_LENGTH PMERR_HBITMAP_BUSY PMERR_HDC_BUSY PMERR_HUGE_FONTS_NOT_SUPPORTED PMERR_INCOMPATIBLE_BITMAP PMERR_INCORRECT_DC_TYPE PMERR_INSUFFICIENT_MEMORY PMERR_INV_BACKGROUND_COL_ATTR PMERR_INV_BACKGROUND_MIX_ATTR PMERR_INV_BITBLT_MIX PMERR_INV_BITBLT_STYLE PMERR_INV_BITMAP_DIMENSION PMERR_INV_CHAR_DIRECTION_ATTR PMERR_INV_CHAR_MODE_ATTR PMERR_INV_CHAR_SET_ATTR PMERR_INV_CHAR_SHEAR_ATTR PMERR_INV_CODEPAGE PMERR_INV_COLOR_ATTR PMERR_INV_COLOR_DATA PMERR_INV_COLOR_FORMAT PMERR_INV_COLOR_INDEX PMERR_INV_COLOR_OPTIONS PMERR_INV_COLOR_START_INDEX PMERR_INV_COORD_SPACE PMERR_INV_COORDINATE PMERR_INV_DC_DATA PMERR_INV_DC_TYPE PMERR_INV_DRIVER_NAME PMERR_INV_GEOM_LINE_WIDTH_ATTR PMERR_INV_HBITMAP PMERR_INV_HDC PMERR_INV_HRGN PMERR_INV_ID PMERR_INV_IN_AREA PMERR_INV_IN_PATH PMERR_INV_INFO_TABLE PMERR_INV_LENGTH_OR_COUNT PMERR_INV_LINE_END_ATTR PMERR_INV_LINE_JOIN_ATTR PMERR_INV_LINE_TYPE_ATTR PMERR_INV_LINE_WIDTH_ATTR PMERR_INV_MARKER_SET_ATTR PMERR_INV_MARKER_SYMBOL_ATTR PMERR_INV_MIX_ATTR PMERR_INV_PATTERN_REF_PT_ATTR PMERR_INV_PATTERN_SET_ATTR PMERR_INV_PATTERN_SET_FONT PMERR_INV_PICK_APERTURE_POSN PMERR_INV_PRIMITIVE_TYPE PMERR_INV_RECT PMERR_INV_REGION_CONTROL PMERR_INV_SCAN_START PMERR_INV_SETID PMERR_INV_USAGE_PARM PMERR_REALIZE_NOT_SUPPORTED PMERR_UNSUPPORTED_ATTR PMERR_UNSUPPORTED_ATTR_VALUE Comments If the call to Bitblt modifies a bitmap within a single device context and the source and target rectangles overlap, the copy will be nondestructive. The target coordinates may optionally be specified in world coordinates. In this case, the target rectangle's points are transformed into device coordinates, and the Bitblt operation is performed into an upright rectangle in device space, regardless of whether there were any rotational elements in any transformations. All four target points must be present. The device contexts may be either memory device contexts (with a selected bitmap), or device contexts for devices that support raster operations. Foreground and background bitmap colors may be specified by the pbba parameter; otherwise, the current foreground and background bitmap colors of the target device context are used. Also, if the mix requires both source and pattern then a three-way operation is performed (using the pattern defined by the current pattern of the target device context); otherwise, a two-way operation is performed. Note that for a StretchBlt operation, only the source data and not the pattern is stretched. If any of the source data is not available, for example if the source device context is connected to a screen window, and the source rectangle is not currently all visible, no error code is returned and the operation proceeds by reading what is there. Note that rectangles defined by Bitblt are non-inclusive. They include the left and lower boundaries of the rectangles in device units, but not the right and upper boundaries. Thus, if the lower left maps to the same device pixel as the upper right, that rectangle is considered empty. The color attribute values are used in converting between monochrome and color data. This is the only format conversion performed by Bitblt. The three conversions are as follows: Outputting a monochrome pattern to a color device In this case, the pattern is interpreted in two colors, using the current pattern colors: ■ Pattern ones (1) are interpreted as the pattern foreground color. ■ Pattern zeros (0) are interpreted as the pattern background color. The color pattern is then copied to the target without regard to the pattern's original values. Bltblting from a monochrome bitmap to a color bitmap (or device) The source bits are converted as follows: ■ Source ones (1) are converted to the target image's foreground color. ■ Source zeros (0) are converted to the target image's background color. Bltblting from a color bitmap to a monochrome bitmap (or device) ■ Source pels of the image background color are converted to the target image's background color. ■ All other pels are converted to the target image's foreground color. In all of these cases, it is the attributes of the target presentation space that are used. Note that if the options specify BBO_TARGWORLD, then all of the boundaries of the target rectangle are considered part of its interior; otherwise (if BBO_TARGWORLD is not specified), the lower and left boundaries of the target rectangle are considered to be part of its interior but the upper and right boundaries are not. █ BoxBoth ──────────────────────────────────────────────────────────────────────────── LONG BoxBoth (hdc, pboxp, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ PBOXPARAMS pboxp; /*pointer to BOXPARAMS structure */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The BoxBoth function draws the outline of a rectangular box and fills its interior using the current area fill pattern. The current position defines the coordinates of one corner of the box. The first field in the structure pointed to by the pboxp parameter contains the coordinates of the opposite corner. The second field in this structure specifies the major and minor axis of an ellipse that is used to draw the box's corners. Parameters hdc the engine's device context. pboxp to a BOXPARAMS structure. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is GPI_OK or GPI_HITS if the function is successful (it is GPI_HITS if the detectable attribute is set for the presentation space and a correlation hit occurs). The return value is GPI_ERROR if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine or the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine or the device driver calls record: PMERR_ALREADY_IN_AREA PMERR_BASE_ERROR PMERR_BITMAP_NOT_SELECTED PMERR_COORDINATE_OVERFLOW PMERR_DEV_FUNC_NOT_INSTALLED PMERR_EXCEEDS_MAX_SEG_LENGTH PMERR_HDC_BUSY PMERR_HRGN_BUSY PMERR_HUGE_FONTS_NOT_SUPPORTED PMERR_INSUFFICIENT_MEMORY PMERR_INV_AREA_CONTROL PMERR_INV_BACKGROUND_COL_ATTR PMERR_INV_BACKGROUND_MIX_ATTR PMERR_INV_BOX_ROUNDING_PARM PMERR_INV_CHAR_DIRECTION_ATTR PMERR_INV_CHAR_MODE_ATTR PMERR_INV_CODEPAGE PMERR_INV_COLOR_ATTR PMERR_INV_COLOR_DATA PMERR_INV_COLOR_INDEX PMERR_INV_COORD_SPACE PMERR_INV_COORDINATE PMERR_INV_HDC PMERR_INV_HRGN PMERR_INV_IN_AREA PMERR_INV_IN_PATH PMERR_INV_LENGTH_OR_COUNT PMERR_INV_LINE_TYPE_ATTR PMERR_INV_MIX_ATTR PMERR_INV_NESTED_FIGURES PMERR_INV_PATTERN_REF_PT_ATTR PMERR_INV_PATTERN_SET_ATTR PMERR_INV_PATTERN_SET_FONT PMERR_INV_PICK_APERTURE_POSN PMERR_INV_RECT PMERR_INV_REGION_CONTROL PMERR_NOT_IN_AREA PMERR_NOT_IN_PATH PMERR_PATH_LIMIT_EXCEEDED PMERR_PATH_UNKNOWN PMERR_REGION_IS_CLIP_REGION Comments If the current position is (x0,y0) and the point specified by the second argument is (x1,y1), the sides of the box are drawn in the following order: (x0,y0)->(x1,y0)->(x1,y1)->(x0,y1)->(x0,y0) The corners of the box may be rounded by means of quarter ellipses, with major and minor axes specified by the second parameter. If the value of either axis is zero, no rounding occurs. If the value of either axis exceeds the length of the corresponding side, that value is used as the diameter instead. Note that for correlation operations, a correlation hit is recorded under the following circumstances: ■ The boundary is being drawn and the pick aperture intersects it. ■ The interior is being filled and the pick aperture intersects or is completely within the interior (even if the transparent mix mode is used for the fill operation). ■ The boundary is being drawn and the interior is being filled, and the pick aperture intersects or is completely within the interior (even if the transparent mix mode is used for the fill operation). The current position is not altered by the BoxBoth function. █ BoxBoundary ──────────────────────────────────────────────────────────────────────────── LONG BoxBoundary (hdc, pboxp, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ PBOXPARAMS pboxp; /*pointer to BOXPARAMS structure */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The BoxBoundary function draws the outline of a rectangular box. The current position defines the coordinates of one corner of the box. The first field in the structure pointed to by the pboxp parameter contains the coordinates of the opposite corner. The second field in this structure specifies the major and minor axis of an ellipse that is used to draw the box's corners. Parameters hdc the engine's device context. pboxp to a BOXPARAMS structure. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is GPI_OK or GPI_HITS if the function is successful (it is GPI_HITS if the detectable attribute is set for the presentation space and a correlation hit occurs). The return value is GPI_ERROR if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine or the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine or the device driver calls record: PMERR_BASE_ERROR PMERR_BITMAP_NOT_SELECTED PMERR_COORDINATE_OVERFLOW PMERR_DEV_FUNC_NOT_INSTALLED PMERR_HDC_BUSY PMERR_INV_BOX_ROUNDING_PARM PMERR_INV_COLOR_DATA PMERR_INV_COLOR_INDEX PMERR_INV_COORD_SPACE PMERR_INV_HDC PMERR_INV_IN_AREA PMERR_INV_IN_PATH PMERR_INV_LENGTH_OR_COUNT PMERR_INV_NESTED_FIGURES PMERR_INV_PICK_APERTURE_POSN PMERR_INV_RECT PMERR_NOT_IN_PATH PMERR_PATH_LIMIT_EXCEEDED PMERR_PATH_UNKNOWN Comments If the current position is (x0,y0) and the point specified by the second argument is (x1,y1), the sides of the box are drawn in the following order: (x0,y0)->(x1,y0)->(x1,y1)->(x0,y1)->(x0,y0) The corners of the box may be rounded by means of quarter ellipses, with major and minor axes specified by the second parameter. If the value of either axis is zero, no rounding occurs. If the value of either axis exceeds the length of the corresponding side, that value is used as the diameter instead. Note that for correlation operations, a correlation hit is recorded under the following circumstances: ■ The boundary is being drawn and the pick aperture intersects the boundary. ■ The interior is being filled and the pick aperture intersects or is completely within the interior (even if the transparent mix mode is used for the fill operation). ■ The boundary is being drawn and the interior is being filled, and the pick aperture intersects or is completely within the interior (even if the transparent mix mode is used for the fill operation). The current position is not altered by the BoxBoundary function. █ BoxInterior ──────────────────────────────────────────────────────────────────────────── LONG BoxInterior (hdc, pboxp, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ PBOXPARAMS pboxp; /*pointer to BOXPARAMS structure */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The BoxInterior function fills the interior of a box using the current area fill pattern. The current position defines the coordinates of one corner of the box. The first field in the structure pointed to by the pboxp parameter contains the coordinates of the opposite corner. The second field in this structure specifies the major and minor axes of an ellipse that is used to draw the box's corners. Parameters hdc the engine's device context. pboxp to a BOXPARAMS structure. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is GPI_OK or GPI_HITS if the function is successful (it is GPI_HITS if the detectable attribute is set for the presentation space and a correlation hit occurs). The return value is GPI_ERROR if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine or the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine or the device driver calls record: PMERR_ALREADY_IN_AREA PMERR_BASE_ERROR PMERR_BITMAP_NOT_SELECTED PMERR_COORDINATE_OVERFLOW PMERR_DEV_FUNC_NOT_INSTALLED PMERR_EXCEEDS_MAX_SEG_LENGTH PMERR_HDC_BUSY PMERR_HRGN_BUSY PMERR_HUGE_FONTS_NOT_SUPPORTED PMERR_INSUFFICIENT_MEMORY PMERR_INV_AREA_CONTROL PMERR_INV_BACKGROUND_COL_ATTR PMERR_INV_BACKGROUND_MIX_ATTR PMERR_INV_BOX_ROUNDING_PARM PMERR_INV_CHAR_DIRECTION_ATTR PMERR_INV_CHAR_MODE_ATTR PMERR_INV_CODEPAGE PMERR_INV_COLOR_ATTR PMERR_INV_COLOR_DATA PMERR_INV_COLOR_INDEX PMERR_INV_COORD_SPACE PMERR_INV_COORDINATE PMERR_INV_HDC PMERR_INV_HRGN PMERR_INV_IN_AREA PMERR_INV_IN_PATH PMERR_INV_LENGTH_OR_COUNT PMERR_INV_LINE_TYPE_ATTR PMERR_INV_MIX_ATTR PMERR_INV_NESTED_FIGURES PMERR_INV_PATTERN_REF_PT_ATTR PMERR_INV_PATTERN_SET_ATTR PMERR_INV_PATTERN_SET_FONT PMERR_INV_PICK_APERTURE_POSN PMERR_INV_RECT PMERR_INV_REGION_CONTROL PMERR_NOT_IN_AREA PMERR_NOT_IN_PATH PMERR_PATH_LIMIT_EXCEEDED PMERR_PATH_UNKNOWN PMERR_REGION_IS_CLIP_REGION Comments If the current position is (x0,y0) and the point specified by the second argument is (x1,y1), the sides of the box are drawn in the following order: (x0,y0)->(x1,y0)->(x1,y1)->(x0,y1)->(x0,y0) The corners of the box may be rounded by means of quarter ellipses, with major and minor axes specified by the second parameter. If the value of either axis is zero, no rounding occurs. If the value of either axis exceeds the length of the corresponding side, that value is used as the diameter instead. Note that for correlation operations, a correlation hit is recorded under the following circumstances: ■ The boundary is being drawn and the pick aperture intersects the boundary. ■ The interior is being filled and the pick aperture intersects or is completely within the interior (even if the transparent mix mode is used for the fill operation). ■ The boundary is being drawn and the interior is being filled, and the pick aperture intersects or is completely within the interior (even if the transparent mix mode is used for the fill operation). The current position is not altered by the BoxInterior function. █ CharRect ──────────────────────────────────────────────────────────────────────────── ULONG CharRect (hdc, phvps, pGridRectRef, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ ULONG FAR * phvps; /*address of AVIO presentation space */ ULONG FAR * pGridRectRef; /*address of GridRectRef structure */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The CharRect function writes a rectangle of alphanumeric characters to the specified device context. Parameters hdc the engine's device context. phvps to an AVIO presentation-space handle. pGridRectRef to a GridRectRef structure that contains information about the character rectangle. The structure has the following form: typedef struct _GridRectRef { /* cellrect */ ULONG StartRow; ULONG StartColumn; ULONG RectWidth; ULONG RectDepth; } GridRectRef; The following list describes the fields in this structure: Field Description ──────────────────────────────────────────────────────────────────────────── StartRow Specifies the starting row. StartCol Specifies the starting column in the presentation space of the character rectangle to be output. RectWidth Specifies the width of the rectangle to be updated. RectHeight Specifies the height of the rectangle to be updated. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is zero if the function is successful or nonzero if an error occurs. Errors If an error occurs during the execution of this function, the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the device driver may record: PMERR_COORDINATE_OVERFLOW PMERR_DEV_FUNC_NOT_INSTALLED PMERR_HDC_BUSY PMERR_INV_COORD_SPACE PMERR_INV_COORDINATE PMERR_INV_HDC PMERR_INV_LENGTH_OR_COUNT PMERR_INV_RECT PMERR_INV_REGION_CONTROL Comments The set of characters and attributes for the rectangle is taken from the presentation-space cell buffer. The characters are drawn and clipped according to the window's cell-buffer origin, the location of the rectangle relative to that origin, and the size of the window. Note that this call will be used to implement the advanced video-input-and-output (AVIO) function VioSetOrg. █ CharStr ──────────────────────────────────────────────────────────────────────────── ULONG CharStr (hdc, phvps, pch, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ ULONG FAR * phvps; /*pointer to AVIO presentation space */ PCH pch; /*address of character string */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The CharStr function draws a character string, positioning the first character in the string at the current row and column position in the advanced video input-and-output (AVIO) presentation space. Parameters hdc the engine's device context. phvps to an AVIO presentation-space handle. pch to a string of characters. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the device driver may record: PMERR_COORDINATE_OVERFLOW PMERR_DEV_FUNC_NOT_INSTALLED PMERR_HDC_BUSY PMERR_INV_COORD_SPACE PMERR_INV_COORDINATE PMERR_INV_HDC PMERR_INV_LENGTH_OR_COUNT PMERR_INV_RECT PMERR_INV_REGION_CONTROL █ CharString ──────────────────────────────────────────────────────────────────────────── LONG CharString (hdc, cch, pch, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ LONG cch; /*character count */ PCH pch; /*address of character string */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The CharString function draws a character string, positioning the first character in the string at the current position. The current position is updated each time a character is drawn. Parameters hdc the engine's device context. cch the number of characters in the string. pch to a string of characters which the function will draw. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is GPI_OK or GPI_HITS if the function is successful (it is GPI_HITS if the detectable attribute is set for the presentation space and a correlation hit occurs). The return value is GPI_ERROR if an error occurs. Errors If an error occurs during the execution of this function, the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the device driver may record: PMERR_ALREADY_IN_PATH PMERR_BASE_ERROR PMERR_BITMAP_NOT_SELECTED .ET PMERR_COORDINATE_OVERFLOW PMERR_DEV_FUNC_NOT_INSTALLED PMERR_EXCEEDS_MAX_SEG_LENGTH PMERR_FONT_AND_MODE_MISMATCH PMERR_HDC_BUSY PMERR_HRGN_BUSY PMERR_HUGE_FONTS_NOT_SUPPORTED PMERR_INSUFFICIENT_MEMORY PMERR_INV_BACKGROUND_COL_ATTR PMERR_INV_BACKGROUND_MIX_ATTR PMERR_INV_CHAR_ANGLE_ATTR PMERR_INV_CHAR_DIRECTION_ATTR PMERR_INV_CHAR_MODE_ATTR PMERR_INV_CHAR_POS_OPTIONS PMERR_INV_CHAR_SET_ATTR PMERR_INV_CHAR_SHEAR_ATTR PMERR_INV_CLIP_PATH_OPTIONS PMERR_INV_CODEPAGE PMERR_INV_COLOR_ATTR PMERR_INV_COLOR_DATA PMERR_INV_COLOR_INDEX PMERR_INV_COORD_SPACE PMERR_INV_COORDINATE PMERR_INV_DC_TYPE PMERR_INV_END_PATH_OPTIONS PMERR_INV_FILL_PATH_OPTIONS PMERR_INV_GEOM_LINE_WIDTH_ATTR PMERR_INV_HDC PMERR_INV_HRGN PMERR_INV_ID PMERR_INV_IN_AREA PMERR_INV_IN_PATH PMERR_INV_LENGTH_OR_COUNT PMERR_INV_LINE_END_ATTR PMERR_INV_LINE_JOIN_ATTR PMERR_INV_LINE_TYPE_ATTR PMERR_INV_LINE_WIDTH_ATTR PMERR_INV_MARKER_SET_ATTR PMERR_INV_MARKER_SYMBOL_ATTR PMERR_INV_MATRIX_ELEMENT PMERR_INV_MIX_ATTR PMERR_INV_PATH_ID PMERR_INV_PATTERN_REF_PT_ATTR PMERR_INV_PATTERN_SET_ATTR PMERR_INV_PATTERN_SET_FONT PMERR_INV_PICK_APERTURE_POSN PMERR_INV_PRIMITIVE_TYPE PMERR_INV_RECT PMERR_INV_REGION_CONTROL PMERR_INV_SETID PMERR_INV_TRANSFORM_TYPE PMERR_NOT_IN_PATH PMERR_PATH_LIMIT_EXCEEDED PMERR_PATH_UNKNOWN PMERR_REGION_IS_CLIP_REGION PMERR_UNSUPPORTED_ATTR PMERR_UNSUPPORTED_ATTR_VALUE █ CharStringPos ──────────────────────────────────────────────────────────────────────────── LONG CharStringPos (hdc, pptlStart, prclOpaque, flCmd, cch, pch, pdx, pcsp, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ PPOINTL pptlStart; /*address of POINTL structure */ PRECTL prclOpaque; /*address of RECTL structure */ ULONG flCmd; /*option flags */ LONG cch; /*character count */ PCH pch; /*address of characters to be drawn */ PLONG pdx; /*pointer to array of increment values */ PCSP_INFO pcsp; /*pointer to CSP_INFO structure */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The CharStringPos function draws a character string starting at the current position and using one or more formatting options. The options direct the function to draw a background for the string, clip the string to the given rectangle, or position the characters in the string using distances given in an array. After drawing the string, the function either leaves the current position at the end of the string or resets it to the beginning of the string. Parameters hdc the engine's device context. pptlStart to a POINTL structure that contains the coordinates of the optional starting position. prclOpaque to a RECTL structure that contains the coordinates of the optional background rectangle. Depending on the options specified, this rectangle can be drawn opaque, used to clip characters, or both. flCmd the control flags. This parameter can be one of the following: Value Meaning ──────────────────────────────────────────────────────────────────────────── CHS_OPAQUE Draw an opaque rectangle. If not given, do not draw opaque. CHS_VECTOR Use the increment vector. If this value is not given, do not use the vector. CHS_LEAVEPOS Leave the current position at the start of character string. If this value is not given, move the current position to end of the character string. CHS_CLIP Clip the string to a rectangle. If this value is not given, do not clip. CHS_START_XY Use the start position. If this value is not given, do not use the start position. CHS_ATTR_INFO Use the attributes structure. If this value is not given, do not use the attributes structure. If a rectangle is not present, CHS_OPAQUE and CHS_CLIP must not be used. cch the number of characters (bytes) in the character string. pch to the string of character code points. pdx to an array of character increments. Each character increment is given in world coordinates. The current position may optionally be moved to the end of the character string, according to the flCmd parameter. pcsp to a CSP_INFO structure that contains attributes to be used in the operation. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is GPI_OK or GPI_HITS if the function is successful (it is GPI_HITS if the detectable attribute is set for the presentation space and a correlation hit occurs). The return value is GPI_ERROR if an error occurs. Errors If an error occurs during the execution of this function, the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the device driver may record: PMERR_ALREADY_IN_PATH PMERR_BASE_ERROR PMERR_BITMAP_NOT_SELECTED PMERR_COORDINATE_OVERFLOW PMERR_DEV_FUNC_NOT_INSTALLED PMERR_EXCEEDS_MAX_SEG_LENGTH PMERR_FONT_AND_MODE_MISMATCH PMERR_HDC_BUSY PMERR_HRGN_BUSY PMERR_HUGE_FONTS_NOT_SUPPORTED PMERR_INSUFFICIENT_MEMORY PMERR_INV_BACKGROUND_COL_ATTR PMERR_INV_BACKGROUND_MIX_ATTR PMERR_INV_CHAR_ANGLE_ATTR PMERR_INV_CHAR_DIRECTION_ATTR PMERR_INV_CHAR_MODE_ATTR PMERR_INV_CHAR_POS_OPTIONS PMERR_INV_CHAR_SET_ATTR PMERR_INV_CHAR_SHEAR_ATTR PMERR_INV_CLIP_PATH_OPTIONS PMERR_INV_CODEPAGE PMERR_INV_COLOR_ATTR PMERR_INV_COLOR_DATA PMERR_INV_COLOR_INDEX PMERR_INV_COORD_SPACE PMERR_INV_COORDINATE PMERR_INV_DC_TYPE PMERR_INV_END_PATH_OPTIONS PMERR_INV_FILL_PATH_OPTIONS PMERR_INV_GEOM_LINE_WIDTH_ATTR PMERR_INV_HDC PMERR_INV_HRGN PMERR_INV_ID PMERR_INV_IN_AREA PMERR_INV_IN_PATH PMERR_INV_LENGTH_OR_COUNT PMERR_INV_LINE_END_ATTR PMERR_INV_LINE_JOIN_ATTR PMERR_INV_LINE_TYPE_ATTR PMERR_INV_LINE_WIDTH_ATTR PMERR_INV_MARKER_SET_ATTR PMERR_INV_MARKER_SYMBOL_ATTR PMERR_INV_MATRIX_ELEMENT PMERR_INV_MIX_ATTR PMERR_INV_PATH_ID PMERR_INV_PATTERN_REF_PT_ATTR PMERR_INV_PATTERN_SET_ATTR PMERR_INV_PATTERN_SET_FONT PMERR_INV_PICK_APERTURE_POSN PMERR_INV_PRIMITIVE_TYPE PMERR_INV_RECT PMERR_INV_REGION_CONTROL PMERR_INV_SETID PMERR_INV_TRANSFORM_TYPE PMERR_NOT_IN_PATH PMERR_PATH_LIMIT_EXCEEDED PMERR_PATH_UNKNOWN PMERR_REGION_IS_CLIP_REGION PMERR_UNSUPPORTED_ATTR PMERR_UNSUPPORTED_ATTR_VALUE Comments To control the positioning of characters after the first, you can specify (optionally) a vector of increments. These increments are measured in world coordinates (along the baseline for left-to-right and right-to-left character directions, and along the shearline for top-to-bottom and bottom-to-top). The ith increment is the distance of the reference point (for example, the lower-left corner) of the (i+1)th character from the reference point of the ith. The last increment may be needed to update the current position. These increments, if specified, set the widths of each character. A further option allows you to specify a rectangle, which you may use as a clip rectangle─and as the background of the string, rather than using the normal method of defining the background. The points on the borders of the rectangle are included within the rectangle. You may use the optional CSP_INFO structure to specify the foreground and background colors for the operation. Otherwise, the characters are drawn using the current character-attribute values, and the background is drawn using the current character background color and an overpaint mix mode. Both corners of the rectangle are specified, so that the rectangle is positioned independently of the current position. A further option allows you to clip the string to the rectangle. This clipping is independent of whether the rectangle is actually drawn. You may (optionally) update the current position to the point at which the next character would have been drawn, had there been one; or you can leave the current position at the start of the string. The opaque rectangle (which is drawn if bit 0 is equal to 1) will ignore any background mix attributes, and be drawn using overpaint and the character's background color attribute. The current character mode affects how the function applies the character increment when it draws each character. For a complete description of the character modes and their affect on text output, see the Microsoft Operating System/2 Programmer's Reference, Volume 1. █ Clip1DPath ──────────────────────────────────────────────────────────────────────────── BOOL Clip1DPath (hdc, pph, api, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ PPATH pph; /*pointer to PATH structure */ PPIPELINEINFO api; /*pointer to array of PIPELINEINFO structs */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The Clip1DPath function clips a path against the current clip path, producing new records of clipped curves in the PATH structure. Parameters hdc the engine's device context. pph to a PATH structure. api to an array of two PIPELINEINFO structures. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine or the device driver calls the WinSetErrorInfo function and records the associated error code. The following is a possible error code that the engine or the device driver calls record: PMERR_DEV_FUNC_NOT_INSTALLED Comments The Clip1DPath function never uses more than half of the available records in the path segment. █ ClipPathCurves ──────────────────────────────────────────────────────────────────────────── BOOL ClipPathCurves (hdc, pph, api, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ PPATH pph; /*pointer to PATH structure */ PIPELINEINFO api; /*pointer to array of PIPELINEINFO structs */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The ClipPathCurves function clips a path against the current region, producing new records of clipped curves in the PATH structure. Parameters hdc the engine's device context. pph to a PATH structure. This structure contains pointers to one or more SUBPATH structures, which in turn point to one or more LINE and/or CURVE structures that define the shape of the path. api to an array of two PIPELINEINFO structures. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine or the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine or the device driver calls record: PMERR_BASE_ERROR PMERR_COORDINATE_OVERFLOW PMERR_HDC_BUSY PMERR_INV_HDC Comments The function performs bounds and correlation (if required). █ CloseDC ──────────────────────────────────────────────────────────────────────────── BOOL CloseDC (hdc, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The CloseDC function closes a device context. If the device context is a memory device context with a selected bitmap, then this function automatically deselects the bitmap before destroying the device context. Parameters hdc the engine's device context. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine may record: PMERR_BASE_ERROR PMERR_BITMAP_IS_SELECTED PMERR_DEV_FUNC_NOT_INSTALLED PMERR_EXCEEDS_MAX_SEG_LENGTH PMERR_HBITMAP_BUSY PMERR_HDC_BUSY PMERR_INSUFFICIENT_MEMORY PMERR_INV_BITMAP_DIMENSION PMERR_INV_CODEPAGE PMERR_INV_COORDINATE PMERR_INV_DC_TYPE PMERR_INV_HBITMAP PMERR_INV_HDC PMERR_INV_HRGN PMERR_INV_ID PMERR_INV_IN_AREA PMERR_INV_IN_PATH PMERR_INV_INFO_TABLE PMERR_INV_LENGTH_OR_COUNT PMERR_INV_RECT PMERR_INV_REGION_CONTROL PMERR_INV_SCAN_START Comments This function will delete regions (clip regions and visible regions) selected into the device context. █ CloseFigure ──────────────────────────────────────────────────────────────────────────── BOOL CloseFigure (hdc, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The CloseFigure function closes a figure within a path bracket. Parameters hdc the engine's device context. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine or the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine or the device driver calls record: PMERR_BASE_ERROR PMERR_COORDINATE_OVERFLOW PMERR_DEV_FUNC_NOT_INSTALLED PMERR_HDC_BUSY PMERR_INV_COORD_SPACE PMERR_INV_HDC PMERR_INV_LENGTH_OR_COUNT PMERR_NOT_IN_PATH PMERR_PATH_LIMIT_EXCEEDED Comments The current figure is closed by means of appending a straight line from the current position to the starting point of the figure. An "open" figure may be generated by starting a new figure (with a "move" function), or by ending the path, without first issuing the CloseFigure function. If this function occurs outside a path bracket, it has no effect. █ CombineRectRegion ──────────────────────────────────────────────────────────────────────────── LONG CombineRectRegion (hdc, hrgnDst, prcl, hrgnSrc, ulMode, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ HRGN hrgnDst; /*handle of destination region */ PRECTL prcl; /*pointer to RECTL structure */ HRGN hrgnSrc; /*handle of source region */ ULONG ulMode; /*combining flag */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The CombineRectRegion function combines a source region with a rectangle to form a final destination region. Parameters hdc the engine's device context. hrgnDst the final destination region. prcl to a RECTL structure that contains the coordinates of the rectangle that the function combines with the source region in order to create the destination region. hrgnSrc the second source region that the function combines with the first source region in order to create the destination region. ulMode the region combining method. It can be one of the following: Value Meaning ──────────────────────────────────────────────────────────────────────────── CRGN_OR (1) Specifies the union of Src1 and Src2. CRGN_COPY (2) Specifies Src1 only (Src2 is ignored). CRGN_XOR (4) Specifies the symmetric difference of Src1 and Src2. CRGN_AND (6) Specifies the intersection of Src1 and Src2. CRGN_DIFF (7) Specifies Src1 and not(Src2). hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is RGN_NULL, RGN_RECT, or RGN_COMPLEX if the function is successful. The return value is RGN_ERROR if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine or the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine or the device driver calls record: PMERR_HRGN_BUSY PMERR_INSUFFICIENT_MEMORY PMERR_INV_COORDINATE PMERR_INV_HRGN PMERR_INV_RECT PMERR_INV_REGION_MIX_MODE PMERR_REGION_IS_CLIP_REGION █ CombineRegion ──────────────────────────────────────────────────────────────────────────── LONG CombineRegion (hdc, hrgnDst, hrgnSrc1, hrgnSrc2, ulMode, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ HRGN hrgnDst; /*handle of destination region */ HRGN hrgnSrc1; /*handle of source region 1 */ HRGN hrgnSrc2; /*handle of source region 2 */ ULONG ulMode; /*region combining flag */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The CombineRegion function combines two regions to form a third, final region. Parameters hdc the engine's device context. hrgnDst the final destination region. hrgnSrc1 the first source region that the function combines with the second source region in order to create the destination region. hrgnSrc2 the second source region that the function combines with the first source region in order to create the destination region. ulMode the region combining method. It can be one of the following: Value Meaning ──────────────────────────────────────────────────────────────────────────── CRGN_OR (1) Specifies the union of Src1 and Src2. CRGN_COPY (2) Specifies Src1 only (Src2 is ignored). CRGN_XOR (4) Specifies the symmetric difference of Src1 and Src2. CRGN_AND (6) Specifies the intersection of Src1 and Src2. CRGN_DIFF (7) Specifies Src1 and not(Src2). hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is RGN_NULL, RGN_RECT, or RGN_COMPLEX if the function is successful. The return value is RGN_ERROR if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine or the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine or the device driver calls record: PMERR_HRGN_BUSY PMERR_INSUFFICIENT_MEMORY PMERR_INV_COORDINATE PMERR_INV_HRGN PMERR_INV_RECT PMERR_INV_REGION_MIX_MODE PMERR_REGION_IS_CLIP_REGION █ CombineShortLineRegion ──────────────────────────────────────────────────────────────────────────── LONG CombineShortLineRegion (hdc, hrgn, psl, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ HRGN hrgn; /*handle of region */ PSHORTLINE psl; /*pointer to SHORTLINE structure */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The CombineShortLineRegion function combines the region identified by the hrgn parameter with the polygon specified by the ppsl parameter into a single final region. It combines the region and the polygon using the OR operation, forming the union of the two objects. Parameters hdc the engine's device context. hrgn the original region. psl to a SHORTLINE structure. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine or the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine or the device driver calls record: PMERR_HRGN_BUSY PMERR_INSUFFICIENT_MEMORY PMERR_INV_HRGN PMERR_REGION_IS_CLIP_REGION █ Convert ──────────────────────────────────────────────────────────────────────────── BOOL Convert (hdc, lSrc, lTarg, pptl, cptl, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ LONG lSrc; /*source coordinate space identifier */ LONG lTarg; /*target coordinate space identifier */ PPOINTL pptl; /*pointer to POINTL structure */ LONG cptl; /*count of points */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The Convert function converts the specified coordinates from one coordinate space to another, using the current values of the transformations. Parameters hdc the engine's device context. lSrc one of the following source coordinate spaces: Value Meaning ──────────────────────────────────────────────────────────────────────────── 1 World space (CVTC_WORLD) 2 Model space (CVTC_MODEL) 3 Default page space (CVTC_DEFAULTPAGE) 4 Page space (CVTC_PAGE) 5 Device space (CVTC_DEVICE) lTarg one of the following target coordinate spaces: Value Meaning ──────────────────────────────────────────────────────────────────────────── 1 World space 2 Model space 3 Default page space 4 Page space 5 Device space pptl to the POINTL structure that contains the coordinates to be converted. The converted coordinates replace the original coordinates. cptl the number of points. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine or the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine or the device driver calls record: PMERR_COORDINATE_OVERFLOW PMERR_HDC_BUSY PMERR_INV_COORD_SPACE PMERR_INV_HDC PMERR_INV_LENGTH_OR_COUNT Comments Screen coordinates have the format of 32-bit signed integers and are used by the device driver as screen pixel addresses. █ ConvertPath ──────────────────────────────────────────────────────────────────────────── BOOL ConvertPath (hdc, pph, lSrc, lTarg, pcvFirst, ccv, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ PPATH pph; /*pointer to PATH structure */ LONG lSrc; /*source coordinate space */ LONG lTarg; /*target coordinate space */ PCURVE pcvFirst; /*pointer to first curve */ LONG ccv; /*count of curves */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The ConvertPath function transforms coordinates in a specified number of curves of the specified path, starting at the first curve (specified in the pcvFirst parameter). If pcvFirst is zero, all the curves in the path are transformed. Parameters hdc the engine's device context. pph to a PATH structure, which defines the path to be transformed. The PATH structure contains pointers to one or more SUBPATH structures, which in turn point to one or more LINE and/or CURVE structures that define the shape of the path. lSrc one of the following source coordinate spaces: Value Meaning ──────────────────────────────────────────────────────────────────────────── 1 World space (CVTC_WORLD) 2 Model space (CVTC_MODEL) 3 Default page space (CVTC_DEFAULTPAGE) 4 Page space (CVTC_PAGE) 5 Device space (CVTC_DEVICE) lTarg one of the following target coordinate spaces: Value Meaning ──────────────────────────────────────────────────────────────────────────── 1 World space 2 Model space 3 Default page space 4 Page space 5 Device space pcvFirst to the first curve in the path. ccv a count of the number of curves to convert. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine or the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine or the device driver calls record: PMERR_COORDINATE_OVERFLOW PMERR_HDC_BUSY PMERR_INV_COORD_SPACE PMERR_INV_HDC PMERR_INV_LENGTH_OR_COUNT PMERR_PATH_UNKNOWN Comments The ConvertPath function "walks" along the given path and converts the coordinates from one space to another, using the current transformation values. All points in the path are LONG values (they may become FIXED values after the CookPathCurves function is called). This is necessary since there is no way to store points in world coordinates into 16-bit values. █ ConvertWithMatrix ──────────────────────────────────────────────────────────────────────────── BOOL ConvertWithMatrix (hdc, aptl, cptl, pxform, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ PPOINTL aptl; /*address of array of POINTL structures */ LONG cptl; /*count of points */ PXFORM pxform; /*pointer to XFORM structure */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The ConvertWithMatrix function uses the supplied matrix to transform points. Parameters hdc the engine's device context. aptl to an array of POINTL structures containing the coordinates to be transformed. On completion, the array contains the new coordinates. cptl the number of points addressed by the aptl parameter. pxform to an XFORM structure. The structure has the following form: typedef struct _XFORM { /* xform */ FIXED fxM11; FIXED fxM12; FIXED fxM21; FIXED fxM22; LONG lM41; LONG lM42; } XFORM; hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine or the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine or the device driver calls record: PMERR_COORDINATE_OVERFLOW PMERR_INV_LENGTH_OR_COUNT Comments This function does not take into account any other transformation matrices. █ CookPathCurves ──────────────────────────────────────────────────────────────────────────── BOOL CookPathCurves (hdc, pph, api, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ PPATH pph; /*pointer to PATH structure */ PPIPELINEINFO api; /*pointer to array of PIPELINEINFO structures */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The CookPathCurves function starts at the first curve in the array of PIPELINEINFO structures and turns raw conics and lines into cooked conics and lines by filling in equation blocks and style information. (In this context, a curve is either a line or a fillet with a sharpness value.) Parameters hdc the engine's device context. pph to a PATH structure. The PATH structure contains pointers to one or more SUBPATH structures, which in turn point to one or more LINE and/or CURVE structures that define the shape of the path. api the address of an array of PIPELINEINFO structures. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine or the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine or the device driver calls record: PMERR_BASE_ERROR PMERR_COORDINATE_OVERFLOW PMERR_DEV_FUNC_NOT_INSTALLED PMERR_HDC_BUSY PMERR_INV_COORD_SPACE PMERR_INV_HDC PMERR_INV_LENGTH_OR_COUNT PMERR_PATH_LIMIT_EXCEEDED Comments The graphics engine creates a raw path when it transforms the curves in that path from world space to device space by calling ConvertPath. The graphics engine creates a cooked path by examining each curve in a raw path. If the curve is a line, it passes the coordinates of that line to the device driver and the driver draws the line. If the curve is a sharp fillet, the engine subdivides the curve into extremely short lines that the driver can draw and passes the coordinates of the short lines to the device driver. The CookPathCurves function never uses more than half of the free blocks in the segments. The "cooking" process includes the following: ■ Making the equation blocks for either lines or conics. ■ Carving the conics up if in order to make them octant monotonic. ■ Computing the style─each CURVE structure has the style state─which is basically the length of the curve up to that point calculated with whatever style metric is used. █ CookWholePath ──────────────────────────────────────────────────────────────────────────── BOOL CookWholePath (hdc, pph, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ PPATH pph; /*pointer to PATH structure */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The CookWholePath function fills the empty fields in each of the structures associated with a path. Parameters hdc the engine's device context. pph to a PATH structure. This structure contains pointers to one or more SUBPATH structures, which in turn point to one or more LINE and/or CURVE structures that define the shape of a path. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine or the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine or the device driver calls record: PMERR_BASE_ERROR PMERR_COORDINATE_OVERFLOW PMERR_DEV_FUNC_NOT_INSTALLED PMERR_HDC_BUSY PMERR_INV_HDC PMERR_PATH_LIMIT_EXCEEDED Comments On a display or printer, a path is a collection of curves and lines that form a figure. At the device driver level, a path is a collection of structures that describe these curves and lines. Upon creation, a path exists in its raw form. This means that only certain fields in the path's CURVE and LINE structures are initialized. When the engine or a device driver "cooks" a path, it fills in the remaining fields in the CURVE and LINE structures. If the cooking process exhausts memory, this function returns the error PMERR_PATH_LIMIT_EXCEEDED. █ CopyClipRegion ──────────────────────────────────────────────────────────────────────────── LONG CopyClipRegion (hdc, hrgn, prclBounds, flOptions, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ HRGN hrgn; /*handle of copied region */ PRECTL prclBounds; /*address of RECTL structure */ ULONG flOptions; /*option flags */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The CopyClipRegion function creates a copy of a device context's visible region and returns a handle identifying the new copy as well as a complexity code describing the new region. Parameters hdc the engine's device context. hrgn the new copy of the visible region. prclBounds to a RECTL structure that contains the lower-left and upper-right coordinates of the region's bounding rectangle. flOptions the options. This flag can be one of the following: Option Meaning ──────────────────────────────────────────────────────────────────────────── COPYCRGN_ALLINTERSECT Returns copy of the "Rao" region: the intersection of the million or so regions that describe the true clip region. The region is returned in screen coordinates (0,0 = lower-left corner of the screen). COPYCRGN_VISRGN Returns copy of the visible region only. The region is returned in screen coordinates (0,0 = lower-left corner of the screen). COPYCRGN_CLIPRGN Returns a copy of the clip region only. The region is returned in device coordinates (0,0 = lower-left corner of the device context). hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is RGN_NULL, RGN_RECT, or RGN_COMPLEX if the function is successful. The return value is RGN_ERROR if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine or the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine or the device driver calls record: PMERR_DEV_FUNC_NOT_INSTALLED PMERR_HDC_BUSY PMERR_HRGN_BUSY PMERR_INSUFFICIENT_MEMORY PMERR_INV_COORDINATE PMERR_INV_HDC PMERR_INV_HRGN PMERR_INV_RECT PMERR_REGION_IS_CLIP_REGION If the return value is zero, the region doesn't exist. Comments If the prclBounds parameter points to a RECTL structure, CopyClipRegion copies the coordinates of the region's bounding rectangle into the structure. If prclBounds is NULL, CopyClipRegion does not return the coordinates of the bounding rectangle. The bounding-rectangle coordinates are defined in the same coordinate space in which the region was defined. █ CopyDCLoadData ──────────────────────────────────────────────────────────────────────────── BOOL CopyDCLoadData (hdc, flCmd, hdcSrc, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ LONG flCmd; /*option flag for copying fonts */ HDC hdcSrc; /*handle of source device context */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The CopyDCLoadData function copies local identifiers, bitmaps, fonts, and the color table from a source device context into a target device context. Parameters hdc the target device context. flCmd whether the function should copy AVIO logical fonts, GPI logical fonts, or both types of fonts from the source device context. The following list describes the three possible options: Option Meaning ──────────────────────────────────────────────────────────────────────────── 1 Copy only Gpi logical fonts. 2 Copy only AVIO logical fonts. 3 Copy both Gpi and AVIO logical fonts. hdcSrc the source device context. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine may record: PMERR_BASE_ERROR PMERR_BITMAP_IS_SELECTED PMERR_COORDINATE_OVERFLOW PMERR_DEV_FUNC_NOT_INSTALLED PMERR_EXCEEDS_MAX_SEG_LENGTH PMERR_HBITMAP_BUSY PMERR_HDC_BUSY PMERR_INSUFFICIENT_MEMORY PMERR_INV_BITMAP_DIMENSION PMERR_INV_CODEPAGE PMERR_INV_COLOR_DATA PMERR_INV_COLOR_FORMAT PMERR_INV_COLOR_INDEX PMERR_INV_COLOR_OPTIONS PMERR_INV_COLOR_START_INDEX PMERR_INV_COORD_SPACE PMERR_INV_COORDINATE PMERR_INV_DC_TYPE PMERR_INV_EXTENDED_LCID PMERR_INV_FONT_ATTRS PMERR_INV_FONTDEF PMERR_INV_HBITMAP PMERR_INV_HDC PMERR_INV_HRGN PMERR_INV_ID PMERR_INV_IN_AREA PMERR_INV_IN_PATH PMERR_INV_INFO_TABLE PMERR_INV_LENGTH_OR_COUNT PMERR_INV_RECT PMERR_INV_REGION_CONTROL PMERR_INV_SCAN_START PMERR_INV_SETID PMERR_REALIZE_NOT_SUPPORTED PMERR_SETID_IN_USE Comments This function copies the source device context's local identifier (lcid) table into the target device context. CopyDCLoadData will call the CreateLogicalFont function if it is necessary to create matching fonts for the target device context. If bitmaps in the source device context are different than those in the target device context, CreateLogicalFont performs the necessary translations. Upon completion, this function sets the source device context's color table and attribute bundle to their default values. The function fails if the target device context's local identifier table contains values used in the source device context's local identifier table. If the color table was originally created with the LCOL_REALIZABLE option and the device driver of the target device context does not support this option, a warning (PMERR_REALIZE_NOT_SUPPORTED) is logged and the color table is treated as non-realizable. If the device driver does support this option, it treats the color table as realizable. The effect of CopyDCLoadData on fonts is as follows: ■ Any logical fonts that are still in effect for the old device context are effectively reloaded into the new device context, using the same parameters as were used originally by the application. ■ Any generic fonts that were selected by match identification can still be selected that way, unless this font is unsuitable for the new device─for example, it is a raster font and the new device is a plotter. ■ Any device fonts that were selected by match identification may select a device font if the new device happens to have a font with the same match identifier. However, the characteristics of this font may differ from the original font. If the new device does not have a font with this match identifier, the default action is taken. The application must manage this process. If the application must use the font on the new device, then it should reload it, after determining from the QueryFonts function the characteristics and match identifiers of the fonts on the new device. However, if the application does not have to use the font on the new device, but may later to re-associate to the original device, then it need take no action. A warning will be raised if any font could not be reloaded on association (not on disassociation). █ CreateBitmap ──────────────────────────────────────────────────────────────────────────── HBITMAP CreateBitmap (hdc, pbmp, flCmd, pbBits, pbmi, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ PBITMAPINFOHEADER pbmp; /*pointer to BITMAPINFOHEADER structure */ ULONG flCmd; /*initialization options */ PBYTE pbBits; /*pointer to bitmap bits */ PBITMAPINFO pbmi; /*pointer to BITMAPINFO structure */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The CreateBitmap function creates a bitmap. If the function is successful, it returns a handle that identifies the new bitmap. Parameters hdc the engine's device context. pbmp to a BITMAPINFOHEADER structure that specifies the width and height of the bitmap in pels, the number of color planes in the bitmap, and the number of adjacent color bits per pel. Each bitmap plane has ((cx * cBitCount + 31)/32 * 4 * cy) bytes. flCmd initialization information. This parameter can be one of the following values: Bit Meaning ──────────────────────────────────────────────────────────────────────────── 0 Reserved 1 Reserved 2 CBM_INIT If bit 2 is set, the function uses the values in the pbBits and pbmi parameters. pbBits to the bitmap data to be copied. It is assumed that enough data is supplied to initialize the entire bitmap. pbmi to a BITMAPINFO structure that contains bitmap format and color information. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is the handle of the created bitmap if the function is successful. Otherwise, it is zero. Errors If an error occurs during the execution of this function, the graphics engine calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine may record: PMERR_DEV_FUNC_NOT_INSTALLED PMERR_HDC_BUSY PMERR_INSUFFICIENT_MEMORY PMERR_INV_BITMAP_DIMENSION PMERR_INV_HDC PMERR_INV_INFO_TABLE PMERR_INV_LENGTH_OR_COUNT PMERR_INV_SCAN_START PMERR_INV_USAGE_PARM Comments Bitmap size is limited by available memory; the maximum width and height are 64K. There are several standard bitmap formats that should normally be adhered to. These formats are listed as follows: Bitcount Planes ──────────────────────────────────────────────────────────────────────────── 1 1 4 1 8 1 24 1 The only bitmap formats supported are the standard formats (above) plus any that the device supports. The device-context handle supplied to this function must never be NULL. The bitmap will be created on the device specified. The bitmap can be selected to a different device later and the engine will handle transfer of bits from one device to the other but bitmaps always belong to some device. Note that a bitmap information header and a bitmap information table have the following structures, respectively: /* bitmap parameterization used by CreateBitmap and others */ typedef struct _BITMAPINFOHEADER { /* bmp */ ULONG cbFix; USHORT cx; USHORT cy; USHORT cPlanes; USHORT cBitCount; } BITMAPINFOHEADER; typedef BITMAPINFOHEADER FAR *PBITMAPINFOHEADER; /* RGB data for _BITMAPINFO struct */ typedef struct _RGB { /* rgb */ BYTE bBlue; BYTE bGreen; BYTE bRed; } RGB; /* bitmap data used by SetBitmapBits and others */ typedef struct _BITMAPINFO { /* bmi */ ULONG cbFix; USHORT cx; USHORT cy; USHORT cPlanes; USHORT cBitCount; RGB argbColor[1]; } BITMAPINFO; typedef BITMAPINFO FAR *PBITMAPINFO; If the value specified for cPlanes or cBitCount is incompatible with the physical device specified by the hdc parameter, the engine returns an error. █ CreateJournalFile ──────────────────────────────────────────────────────────────────────────── HJOURNAL CreateJournalFile (pszFileName, flCmd, cbBufSize, hddc, ulFunN) PSZ pszFileName; /*pointer to journal filename */ ULONG flCmd; /*type of journal file */ LONG cbBufSize; /*size of journal file (max. of 64K) */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The CreateJournalFile function creates a journal file on a disk. Parameters pszFileName to a null-terminated string that specifies the name of the journal file. flCmd the type of journal file. This name can be one of the following: Constant/Value Meaning ──────────────────────────────────────────────────────────────────────────── JNL_TEMP_FILE An temporary journal file will be created; the pszFileName parameter is ignored. The length of a temporary journal file can exceed 64K bytes. JNL_PERM_FILE A permanent journal file will be created; pszFileName points to a fully qualified path/file name. The length of permanent journal files can exceed 64K bytes. JNL_ENGINERAM_FILE A memory journal file will be created in shared memory allocated by the engine; pszFileName is ignored. The length of memory journal files cannot exceed 64K bytes. JNL_USERRAM_FILE A memory journal file will be created in memory supplied by the application; pszFileName is the pointer to the memory. The length of memory journal files cannot exceed 64K bytes. JNL_DRAW_OPTIMIZATION The draw bit will not be modified on accumulation or playback (otherwise, the draw bit is forced off on accumulation and is not modified on playback). JNL_BOUNDS_OPTIMIZATION The bounds bit will be forced off on playback and not modified on accumulation (otherwise, the bounds bit is not modified on accumulation or playback). cbBufSize the size (in bytes) of the journal file. If the size is greater than zero, it suggests how large the file must be (in the case of the constant JNL_USERRAM_FILE, cbBufSize must be greater than zero and is the size of the buffer, which cannot be extended). hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is a handle that identifies the new journal file if the function is successful. Otherwise, it is zero. Errors If an error occurs during the execution of this function, the graphics engine calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine may record: PMERR_BASE_ERROR PMERR_INSUFFICIENT_MEMORY PMERR_INV_IN_AREA PMERR_INV_IN_PATH PMERR_INV_JOURNAL_OPTION PMERR_RAM_JNL_FILE_TOO_SMALL █ CreateLogColorTable ──────────────────────────────────────────────────────────────────────────── BOOL CreateLogColorTable (hdc, flCmd, ulFormat, lStart, clColorData, plColorData, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ ULONG flCmd; /*options */ ULONG ulFormat; /*color-table format */ LONG lStart; /*starting index value */ LONG clColorData; /*number of color-data entries */ PLONG plColorData; /*pointer to color data */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The CreateLogColorTable function creates a logical color table in the device context that hdc identifies, or it sets the RGB mode in that device context. A color table is an array of RGB values or an array of (index, RGB) values. Parameters hdc the engine's device context. flCmd various options. It can be one of the following: Value Meaning ──────────────────────────────────────────────────────────────────────────── LCOL_RESET Resets the color table to its default settings before processing the remainder of the data in this function. If this option is set, the entry format must be LCOLF_INDRGB or LCOLF_CONSECRGB. This option is forced if the color table is currently in RGB mode and is being changed to index mode (that is, if either LCOLF_INDRGB or LCOLF_CONSECRGB is specified). LCOL_REALIZABLE Creates a realizable color table for the application. This may affect the way the system maps the indices when the logical color table is not realized. If this option is not set, RealizeColorTable may have no effect. LCOL_PURECOLOR Does not use color dithering for colors not available in the physical palette. If this option is set, only pure colors are used and no dithering is done. The default is color dithering. Other flags are reserved and must be zero. ulFormat the format of entries in the color table. This parameter can be one of the following: Value Meaning ──────────────────────────────────────────────────────────────────────────── LCOLF_INDRGB Specifies an array of (index,RGB) values. Each pair of entries is 8 bytes long: 4 bytes (local format) index, and 4 bytes color value. This option sets the color table into index mode (and forces the LCOL_RESET option) if it is currently in RGB mode. , LCOLF_CONSECRGB Specifies an array of (RGB) values, corresponding to color indices lStart upwards. Each entry is 4 bytes long. This option sets the color table into index mode (and forces the LCOL_RESET option) if it is currently in RGB mode. , LCOLF_RGB This option sets the RGB mode in a device context. lStart the starting color index (relevant only for the option LCOLF_CONSECRGB). clColorData the number of elements supplied in the plColorData parameter. This parameter must contain a value that is greater than or equal to zero; if this value is zero, LCOLF_INDRGB and LCOLF_CONSECRGB have the same effect. If the format is LCOLF_INDRGB, the parameter must specify an even number. plColorData to the application data area that contains the color-table definition data. The format depends on the value of ulFormat. Each RGB value is a 4-byte integer, whose value is determined as follows: (R * 65536) + (G * 256) + B where R is the red intensity value, G is the green intensity value, and B is the blue intensity value (since there are 8 bits for each primary color). The maximum intensity for each primary color is 255. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the device driver may record: PMERR_DEV_FUNC_NOT_INSTALLED PMERR_INSUFFICIENT_MEMORY PMERR_INV_COLOR_DATA PMERR_INV_COLOR_FORMAT PMERR_INV_COLOR_INDEX PMERR_INV_COLOR_START_INDEX PMERR_INV_HDC PMERR_INV_IN_AREA PMERR_INV_IN_PATH PMERR_INV_LENGTH_OR_COUNT PMERR_REALIZE_NOT_SUPPORTED Comments When the ulFormat argument is set to LCOLF_RGB, a device driver should ignore the flCmd, lStart, clColorData, and plColorData arguments. When the RGB mode is set in a device context, no color table is associated with that device context and applications select colors using RGB values instead of color table indices. The CreateLogColorTable function may cause the color table to be preset to the default values, listed as follows: Color Value ──────────────────────────────────────────────────────────────────────────── CLR_BACKGROUND 0L CLR_BLUE 1L CLR_RED 2L CLR_PINK 3L CLR_GREEN 4L CLR_CYAN 5L CLR_YELLOW 6L CLR_NEUTRAL 7L CLR_DARKGRAY 8L CLR_PALEBLUE 9L CLR_PALERED 10L CLR_PALEPINK 11L CLR_DARKGREEN 12L CLR_DARKCYAN 13L CLR_BROWN 14L CLR_PALEGRAY 15L Valid color table indices (including the default color table) are in the range 0 through 15. If LCOL_REALIZABLE is set, this (flag) is stored by the engine and used whenever the color table is copied to a device context (using the CopyDCLoadData function) owned by a device driver that supports this option. If LCOL_REALIZABLE is set and is not supported by the device driver, a warning (PMERR_REALIZE_NOT_SUPPORTED) is logged and the color table is treated as non-realizable. If LCOL_REALIZABLE is set and is supported by the device driver, this option is honored. All drawing takes place using the index mapping appropriate to the realized table, even when the table is not realized. This includes line drawing, character drawing, and any bitmaps set by the SetBitmapBits function. The colors in a non-realized picture may therefore differ markedly from what is required or expected. When the table is subsequently realized, however, the colors will appear as correctly as is possible on the device. If the logical color table can be completely loaded to the device, the physical color indices used will be such that color mixing will be predictable (that is, a pixel with a logical color index of 2 when mixed [using OR] with one of logical color index 1 produces a pixel of logical color index 3), providing the device technology allows this─this would not, for example, be true on a plotter. But if the logical color table is too big to be loaded to the device, the system will perform a mapping, and mixing will be unpredictable. The maximum size which may be loaded to the device can be found by calling the QueryCaps function, with the CAPS_COLOR option set; the option CAPS_COLOR_TABLE_SUPPORT (also returned by QueryCaps) indicates whether color mixing will be predictable. When an application creates a logical color table without specifying the LCOL_REALIZABLE option, the system maps the requested RGB values to those values available in the default palette for the device. The first 16 colors are always available, where physically possible, on the device. On devices that support more than 16 colors, there may be additional colors available to which the requested colors may be mapped. However, there is no guarantee that these additional colors will be the same on different devices; they may also vary from release to release. Applications that depend upon precise colors beyond the first 16 should realize their color tables, unless they can tell from the color queries that the color they require are indeed available without realizing. By default, device contexts are in index mode and have a logical color table consisting of the 16 default values above. In index mode, these entries will always be considered part of the color table, unless they are explicitly overwritten. Color indices outside this range, which have not been loaded, are not considered to be part of the color table. Applications should not use color indices beyond the highest in their color table or the colors will not be guaranteed. █ CreateLogicalFont ──────────────────────────────────────────────────────────────────────────── BOOL CreateLogicalFont (hdc, lcid, pName, pfat, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ LCID lcid; /*local identifier of font */ PSTR8 pName; /*pointer to font's name */ PFATTRS pfat; /*pointer to FATTRS structure */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The CreateLogicalFont function selects one font from all of the fonts currently loaded in the system. It makes this selection by comparing requested font attributes to the font attributes of each loaded font. The requested attributes are stored in the FATTRS structure pointed to by the pfat parameter. Parameters hdc the engine's device context. lcid the logical font by number. The system assigns this number to the font if the function is successful. Values of -2, -3, and -4 correspond to AVIO local-identifier values of 1, 2, and 3. pName to a null-terminated string that identifies the logical font by name. The maximum length of this string is eight characters. pfat to a FATTRS structure that defines the characteristics of the requested font. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is 2 if the function successfully matched the font or 1 if the matching failed─in which case, the default font is used. The return value is zero if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine may record: PMERR_BASE_ERROR PMERR_COORDINATE_OVERFLOW PMERR_DEV_FUNC_NOT_INSTALLED PMERR_EXCEEDS_MAX_SEG_LENGTH PMERR_HDC_BUSY PMERR_INSUFFICIENT_MEMORY PMERR_INV_CODEPAGE PMERR_INV_COORD_SPACE PMERR_INV_EXTENDED_LCID PMERR_INV_FONT_ATTRS PMERR_INV_FONTDEF PMERR_INV_HDC PMERR_INV_IN_AREA PMERR_INV_LENGTH_OR_COUNT PMERR_INV_SETID PMERR_SETID_IN_USE Comments Font Selection When CreateLogicalFont is issued, a physical font is selected which will be used for this logical font. The choice is made in one of two ways: ■ The system examines the specified logical-font attributes and selects, from the available physical fonts, the one that best matches these attributes. ■ The application, having determined (by using the QueryFonts function) which font it requires, specifies the same lMatch value in the logical-font attributes as was retrieved for that font by QueryFonts. Once the choice has been made, it is not changed for a particular logical font. Fonts and Character Attributes The interaction between fonts and character attributes depends upon whether the transformable flag (FATTR_FONTUSE_TRANSFORMABLE) is set in the logical font attributes is set. If FATTR_FONTUSE_TRANSFORMABLE is set, the lAveCharWidth and lMaxBaselineExtent fields in the FATTRS structure are not currently used and should be zero. When character strings are drawn with this logical font, the sizes of the characters are determined by the current values of the character attributes. The characters are positioned, rotated, sheared, etc., precisely as required; no check is made. The transformation is calculated by mapping, with respect to character angle and shear, the box defined by the lEmInc and lEmHeight fields in the FONTMETRICS structure to the character box. The character mode (precision) must be 3 when character strings are being drawn. The engine verifies this. If FATTR_FONTUSE_TRANSFORMABLE is not set, the lAveCharWidth and lMaxBaselineExtent fields define the size of the font to be used. This size is not affected by the character-box attribute. Either character mode 1 or 2 may be used with such a font. In mode 1, the start of the string is positioned precisely (with respect to text alignment), and subsequent characters are positioned according to the characteristics of the font. Character box, angle, shear, extra, break extra, and spacing are all ignored. In mode 2, each character is positioned with respect to all of the character attributes, but the characters themselves are not scaled, rotated, or sheared. Note that an attempt to draw a character string in either of the following cases results in an error: ■ Mode equal to 3 and FATTR_FONTUSE_TRANSFORMABLE not set. ■ Mode not equal to 3 and FATTR_FONTUSE_TRANSFORMABLE set. Also, if CreateLogicalFont uses the default font when FATTRS_TRANSFORMABLE is specified, then mode 3 should be used only if the default font is a vector font or outline font. If the default font is a raster font, mode 3 should not be used. Positioning is by the character reference point, which is defined within the font. When non-hollow characters are drawn using outline fonts, they are drawn solid, using the character color and mix mode. If characters with some other fill are required, they can be included within a path bracket using the FillPath function, which uses the pattern attributes. █ CreateRectRegion ──────────────────────────────────────────────────────────────────────────── HRGN CreateRectRegion (hdc, arcl, crcl, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ PRECTL arcl; /*pointer to array of RECTL structures */ LONG crcl; /*count of structures in array */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The CreateRectRegion function creates a region by combining the rectangles in the array pointed to by the arcl parameter. The function creates the region using the OR operator, forming the union of the rectangles. Parameters hdc the engine's device context. arcl to an array of RECTL structures. crcl the number of structures in the array. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is the region handle if the function is successful. Otherwise, it is zero. Errors If an error occurs during the execution of this function, the graphics engine or the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine or the device driver calls record: PMERR_INSUFFICIENT_MEMORY PMERR_INV_COORDINATE PMERR_INV_HRGN PMERR_INV_LENGTH_OR_COUNT PMERR_INV_RECT Comments Points on the right and upper boundaries of a rectangle are not included in the region. Points on the left and lower boundaries (which are not also on the right and upper boundaries) of a rectangle are included in the region. For each RECTL structure in the array, the xRight field must specify a value greater than or equal to the value of the xLeft field, and the yTop field must specify a value greater than or equal to the value of the yBottom field. If the crcl parameter is zero, an empty region is created. The lower and left boundaries of each rectangle are considered part of the interior of the region, but the upper and right boundaries are not. █ Death ──────────────────────────────────────────────────────────────────────────── BOOL Death (hdc, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The Death function provides notification of a screen group switch to another screen group. The device driver must track Death and Resurrection calls and must not update the display while "dead." This function, when issued, goes directly to the device driver interface. Parameters hdc Identifies the engine's device context. hddc Identifies the device driver's device context. ulFunN Specifies the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the device driver may record: PMERR_DEV_FUNC_NOT_INSTALLED █ DeleteBitmap ──────────────────────────────────────────────────────────────────────────── BOOL DeleteBitmap (hbm, hddc, ulFunN) HBITMAP hbm; /*handle of bitmap */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The DeleteBitmap function deletes the bitmap identified by the hbm parameter. Parameters hbm Identifies the bitmap to be deleted. hddc Identifies the device driver's device context. ulFunN Specifies the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine may record: PMERR_BITMAP_IS_SELECTED PMERR_DEV_FUNC_NOT_INSTALLED PMERR_HBITMAP_BUSY PMERR_INSUFFICIENT_MEMORY PMERR_INV_HBITMAP PMERR_INV_HDC PMERR_INV_INFO_TABLE PMERR_INV_LENGTH_OR_COUNT PMERR_INV_SCAN_START Comments If the bitmap is currently selected into a device context, this function issues an error. █ DeleteJournalFile ──────────────────────────────────────────────────────────────────────────── ULONG DeleteJournalFile (hfile, hddc, ulFunN) LHANDLE hfile; /*handle of journal file */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The DeleteJournalFile function frees any objects associated with the journal file identified by the hfile parameter. If hfile identifies a file created with the JNL_TEMP_FILE or JNL_ENGINERAM_FILE options, the file is deleted. Finally, the file handle itself is freed. Parameters hfile the journal file. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is GPI_OK if the function is successful or GPI_ERROR if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine may record: PMERR_BASE_ERROR PMERR_BITMAP_IS_SELECTED PMERR_COORDINATE_OVERFLOW PMERR_DEV_FUNC_NOT_INSTALLED PMERR_EXCEEDS_MAX_SEG_LENGTH PMERR_HBITMAP_BUSY PMERR_HDC_BUSY PMERR_HRGN_BUSY PMERR_HUGE_FONTS_NOT_SUPPORTED PMERR_INSUFFICIENT_MEMORY PMERR_INV_BACKGROUND_COL_ATTR PMERR_INV_BACKGROUND_MIX_ATTR PMERR_INV_BITMAP_DIMENSION PMERR_INV_CHAR_DIRECTION_ATTR PMERR_INV_CHAR_MODE_ATTR PMERR_INV_CHAR_SET_ATTR PMERR_INV_CHAR_SHEAR_ATTR PMERR_INV_CODEPAGE PMERR_INV_COLOR_ATTR PMERR_INV_COORD_SPACE PMERR_INV_COORDINATE PMERR_INV_DC_TYPE PMERR_INV_GEOM_LINE_WIDTH_ATTR PMERR_INV_HBITMAP PMERR_INV_HDC PMERR_INV_HJOURNAL PMERR_INV_HRGN PMERR_INV_ID PMERR_INV_IN_AREA PMERR_INV_IN_PATH PMERR_INV_INFO_TABLE PMERR_INV_LENGTH_OR_COUNT PMERR_INV_LINE_END_ATTR PMERR_INV_LINE_JOIN_ATTR PMERR_INV_LINE_TYPE_ATTR PMERR_INV_LINE_WIDTH_ATTR PMERR_INV_MARKER_SET_ATTR PMERR_INV_MARKER_SYMBOL_ATTR PMERR_INV_METAFILE PMERR_INV_MIX_ATTR PMERR_INV_PATTERN_REF_PT_ATTR PMERR_INV_PATTERN_SET_ATTR PMERR_INV_PATTERN_SET_FONT PMERR_INV_PRIMITIVE_TYPE PMERR_INV_RECT PMERR_INV_REGION_CONTROL PMERR_INV_SCAN_START PMERR_INV_SETID PMERR_JFILE_BUSY PMERR_REGION_IS_CLIP_REGION PMERR_UNSUPPORTED_ATTR PMERR_UNSUPPORTED_ATTR_VALUE █ DeleteSetId ──────────────────────────────────────────────────────────────────────────── BOOL DeleteSetId (hdc, lcid, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ LCID lcid; /*local identifier */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The DeleteSetId function deletes the font or bitmap identified by the lcid parameter. Parameters hdc the engine's device context. lcid the lcid (local identifier) value for a font or bitmap. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine may record: PMERR_COORDINATE_OVERFLOW PMERR_DEV_FUNC_NOT_INSTALLED PMERR_HDC_BUSY PMERR_INSUFFICIENT_MEMORY PMERR_INV_CODEPAGE PMERR_INV_COORD_SPACE PMERR_INV_EXTENDED_LCID PMERR_INV_FONTDEF PMERR_INV_HDC PMERR_INV_IN_AREA PMERR_INV_LENGTH_OR_COUNT PMERR_INV_SETID PMERR_SETID_IN_USE PMERR_SETID_NOT_FOUND Comments An lcid value of 0xFFFFFFFF (-1 if this were a signed number) causes all loaded graphics lcids (logical fonts and bitmap ids) to be destroyed. AVIO lcids (-2, -3, and -4) are unaffected and can only be deleted explicitly, one at a time. If the lcid to be deleted is selected as the current character, pattern or marker set, an error is logged. The lcids -2, -3, and -4, represent AVIO lcids 1, 2, and 3, respectively (the engine must perform the remapping between these values and 1, 2, and 3 for the device driver). █ DestroyRegion ──────────────────────────────────────────────────────────────────────────── BOOL DestroyRegion (hdc, hrgn, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ HRGN hrgn; /*handle of region to be destroyed */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The DestroyRegion function destroys the region identified by the hrgn parameter. Parameters hdc the engine's device context. hrgn the region that the function will destroy. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine or the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine or the device driver calls record: PMERR_HRGN_BUSY PMERR_INV_HRGN PMERR_REGION_IS_CLIP_REGION Comments If the region identified by hrgn is a clipping region or a visible region, DestroyRegion fails and issues an error. █ DeviceCreateBitmap ──────────────────────────────────────────────────────────────────────────── HBITMAP DeviceCreateBitmap (hdc, pbmp, flCmd, pbBits, pbmi, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ PBITMAPINFOHEADER pbmp; /*pointer to BITMAPINFOHEADER structure */ ULONG flCmd; /*options */ PBYTE pbBits; /*pointer to bitmap bits */ PBITMAPINFO pbmi; /*pointer to BITMAPINFO structure */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The DeviceCreateBitmap function creates a bitmap with the specified format and returns a handle that identifies it. Parameters hdc Identifies the engine's device context. pbmp Points to a BITMAPINFOHEADER structure that specifies the width and height of the bitmap in pels, the number of color planes in the bitmap, and the number of adjacent color bits per pel. Each plane has (((cx * cBitCount + 31)/32) * 4 * cy) bytes. flCmd Specifies additional information to help the device when a new bitmap is being created. This information is interpreted as follows: Bit Meaning ──────────────────────────────────────────────────────────────────────────── 0 Reserved. 1 Reserved. 2 CBM_INIT. Specifies whether to use pbBits and pbmi to initialize the newly created bitmap. Value Meaning ──────────────────────────────────────────────────────────────────────────── 0x0 Do not use pbBits and pbmi to initialize the bitmap. 0x1 Use pbBits and pbmi to initialize the bitmap. Bits 16-31 may be used for operations specifically supported by the device driver. pbBits Points to the bitmap data to be copied. It is assumed that enough data is supplied to initialize the whole bitmap. pbmi Points to a BITMAPINFO structure that describes the format and colors of the data bits. hddc Identifies the device driver's device context. ulFunN Specifies the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is the handle of the created bitmap if the function is successful. Otherwise, it is zero. Errors If an error occurs during the execution of this function, the graphics engine calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine may record: PMERR_DEV_FUNC_NOT_INSTALLED PMERR_INSUFFICIENT_MEMORY PMERR_INV_BITMAP_DIMENSION PMERR_INV_HDC PMERR_INV_INFO_TABLE PMERR_INV_LENGTH_OR_COUNT PMERR_INV_SCAN_START Comments Bitmap size is limited by available memory; the maximum width and height are 64K. There are several standard bitmap formats, which are listed as follows: Bitcount Planes ──────────────────────────────────────────────────────────────────────────── 1 1 4 1 8 1 24 1 The only bitmap formats supported are these standard formats plus any that the device supports. The device-context handle supplied to this function must never be NULL. The bitmap will be created on the device specified. The bitmap can be selected to a different device later, and the engine will handle the transfer of bits from one device to the other, but bitmaps always belong to some device. If the BITMAPINFO value specified for the cPlanes or cBitCount field is incompatible with the physical device specified by hdc, an error occurs. █ DeviceDeleteBitmap ──────────────────────────────────────────────────────────────────────────── BOOL DeviceDeleteBitmap (hdc, hbm, pdr, flCmd, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ HBITMAP hbm; /*handle of bitmap to delete */ PDELETERETURN pdr; /*pointer to DELETERETURN structure */ ULONG flCmd; /*options */ ULONG hddc; /*device driver's device context */ ULONG ulFunN; /*flags and function number */ The DeviceDeleteBitmap function deletes the bitmap identified by the hbm parameter. Parameters hdc the engine's device context. hbm the bitmap to delete. pdr to a DELETERETURN structure that contains pointers to the BITMAPINFO structure and the bitmap bits. flCmd whether the bitmap requires translation. Bits 0 and 1 are reserved. If bit 2 is set, the engine or driver must translate the bitmap into one of the standard formats. Two blocks of memory must be allocated to return the data: one for the bitmap data, and the other for the bitmap parameters and color-translation table. The device driver is free to choose which standard format to translate into, but must take into account the parameters the application originally requested in the DeviceCreateBitmap call. In general, the device should try to use the format that requires the smallest space to store and does not lose any information presently in the bitmap. If this bit is not set, bitmap initialization is device dependent. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the device driver may record: PMERR_DEV_FUNC_NOT_INSTALLED PMERR_INSUFFICIENT_MEMORY PMERR_INV_HDC PMERR_INV_INFO_TABLE PMERR_INV_LENGTH_OR_COUNT PMERR_INV_SCAN_START █ DeviceGetAttributes ──────────────────────────────────────────────────────────────────────────── BOOL DeviceGetAttributes (hdc, ulType, flAttrs, pAttrs, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ ULONG ulType; /*primitive-type identifier */ ULONG flAttrs; /*attributes mask */ PBUNDLE pBundle; /*pointer to attribute bundle */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The DeviceGetAttributes function retrieves the current line, character, marker, area, or image attributes. The function stores the attributes in the bundle structure pointed to by the pBundle parameter. Parameters hdc the engine's device context. ulType the type of bundle. This parameter can be one of the following values: Value Meaning ──────────────────────────────────────────────────────────────────────────── PRIM_LINE Line-attribute bundle. PRIM_CHAR Character-attribute bundle PRIM_MARKER Marker-attribute bundle PRIM_AREA Pattern-attribute bundle PRIM_IMAGE Image-attribute bundle flAttrs the attributes to be returned. The mask contains a bit corresponding to each attribute in the bundle record. For all the valid bits set to 1 in the mask, the corresponding attribute values and default mask bits are returned. Only the xBB_COLOR and xBB_BACK_COLOR attributes may be requested (where x = L, A, C, I, or M). pBundle to a buffer in which the current attribute settings are returned. The only fields updated are those corresponding to the attributes to be returned, as specified by the flAttrs parameter. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the device driver may record: PMERR_DEV_FUNC_NOT_INSTALLED PMERR_INV_HDC █ DeviceInvalidateVisRegion ──────────────────────────────────────────────────────────────────────────── BOOL DeviceInvalidateVisRegion (hdc, civr, pivr, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ ULONG civr; /*count of structures */ PDC_BLOCK pivr; /*pointer to array of DC_BLOCK structures */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The DeviceInvalidateVisRegion function invalidates visible regions. These regions are in the device contexts identified in the array pointed to by the pivr parameter. Display drivers must support this function. Parameters hdc the engine's device context. civr the number of structures in the array pointed to by pivr. pivr to an array of DC_BLOCK structures. These structures define the device contexts for the visible regions. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if this function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the device driver may record: PMERR_DEV_FUNC_NOT_INSTALLED █ DeviceQueryFontAttributes ──────────────────────────────────────────────────────────────────────────── BOOL DeviceQueryFontAttributes (hdc, cbfm, pfm, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ LONG cbfm; /*count of font metrics */ PFONTMETRICS pfm; /*pointer to FONTMETRICS structure */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The DeviceQueryFontAttributes function retrieves the metrics of the currently selected font. Parameters hdc the engine's device context. cbfm the size of the structure pointed to by the pfm parameter. pfm to a FONTMETRICS structure where the information is to be returned. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the device driver may record: PMERR_DEV_FUNC_NOT_INSTALLED PMERR_INV_HDC █ DeviceQueryFonts ──────────────────────────────────────────────────────────────────────────── LONG DeviceQueryFonts (hdc, flCmd, pszFaceName, afm, cbfm, pcFonts, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ ULONG flCmd; /*font options */ PSZ pszFaceName; /*pointer to facename string */ PFONTMETRICS afm; /*pointer to array of FONTMETRICS structures */ LONG cbfm; /*count of bytes in each structure */ PLONG pcFonts; /*number of metrics requested */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The DeviceQueryFonts function retrieves information about fonts on a device. The function fills the array of FONTMETRICS structures (pointed to by the afm parameter) with this font information. All measurements and dimensions are specified in world coordinates. Parameters hdc Identifies the engine's device context. flCmd Specifies whether the function should retrieve information about public fonts or private fonts. Public fonts are available to any application running under MS OS/2 Presentation Manager. Private fonts are available only to the application that loads them. The following list describes the two constants associated with this option: Value Meaning ──────────────────────────────────────────────────────────────────────────── QF_PUBLIC Retrieves public fonts. Public fonts were loaded by the system and are available to all applications. QF_PRIVATE Retrieves private fonts. Private fonts were loaded by the application and are available only to it. . pszFaceName to a null-terminated string that specifies the font's facename. If a NULL pointer is specified, all available fonts are queried. afm to an array of FONTMETRICS structures. cbfm the number of bytes in each FONTMETRICS structure in the array. pcFonts to a variable that specifies the number of structures the function should fill. Upon completion, the function fills this parameter with the actual number of metrics retrieved. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is the number of fonts not retrieved (this allows the application to determine the number of fonts by specifying a count equal to 0 in the pcFonts parameter). The return value is GPI_ALTERROR if an error occurs. Errors If an error occurs during the execution of this function, the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the device driver may record: PMERR_DEV_FUNC_NOT_INSTALLED PMERR_INV_HDC █ DeviceSelectBitmap ──────────────────────────────────────────────────────────────────────────── ULONG DeviceSelectBitmap (hdc, hbm, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ HBITMAP hbm; /*handle of bitmap */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The DeviceSelectBitmap function selects a bitmap into a device context. Parameters hdc the engine's device context. hbm the bitmap to select. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is GPI_OK if the function is successful or GPI_ERROR if an error occurs. Errors If an error occurs during the execution of this function, the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the device driver may record: PMERR_DEV_FUNC_NOT_INSTALLED PMERR_INV_HDC Comments It is not necessary for this function to return a handle that identifies the previously selected bitmap. █ DeviceSetAttributes ──────────────────────────────────────────────────────────────────────────── ULONG DeviceSetAttributes (hdc, ulType, flDefs, flAttrs, pBundle, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ ULONG ulType; /*type of bundle */ ULONG flDefs; /*attributes to default */ ULONG flAttrs; /*attributes to modify */ PBUNDLE pBundle; /*pointer to bundle structure */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The DeviceSetAttributes function sets the line, character, image, marker, or area attributes in a device context. These attributes are stored in special structures called bundles. Parameters hdc the engine's device context. ulType the type of bundle. This parameter can be one of the following values: Value Meaning ──────────────────────────────────────────────────────────────────────────── PRIM_LINE Line-attribute bundle PRIM_CHAR Character-attribute bundle PRIM_MARKER Marker-attribute bundle PRIM_AREA Pattern-attribute bundle PRIM_IMAGE Image-attribute bundle flDefs which attributes to set to their default values. flAttrs which attributes to modify. pBundle to the bundle structure that contains the default and modified attributes. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is GPI_OK if the function is successful or GPI_ERROR if an error occurs. Errors If an error occurs during the execution of this function, the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the device driver may record: PMERR_COORDINATE_OVERFLOW PMERR_DEV_FUNC_NOT_INSTALLED PMERR_EXCEEDS_MAX_SEG_LENGTH PMERR_HDC_BUSY PMERR_HUGE_FONTS_NOT_SUPPORTED PMERR_INSUFFICIENT_MEMORY PMERR_INV_BACKGROUND_COL_ATTR PMERR_INV_BACKGROUND_MIX_ATTR PMERR_INV_CHAR_DIRECTION_ATTR PMERR_INV_CHAR_MODE_ATTR PMERR_INV_CODEPAGE PMERR_INV_COLOR_ATTR PMERR_INV_COORD_SPACE PMERR_INV_HDC PMERR_INV_LENGTH_OR_COUNT PMERR_INV_LINE_TYPE_ATTR PMERR_INV_MIX_ATTR PMERR_INV_PATTERN_REF_PT_ATTR PMERR_INV_PATTERN_SET_ATTR PMERR_INV_PATTERN_SET_FONT Comments There are the following device bundle structures: DLINEBUNDLE LINEDEFS AREADEFS DAREABUNDLE DCHARBUNDLE CHARDEFS IMAGEDEFS DIMAGEBUNDLE MARKERDEFS DMARKERBUNDLE For more information, see Chapter 9, "Types, Macros, Structures." These structures consist of two bundles: a bundle of logical attributes and a bundle of device information. The logical bundle is the same as that used by the application. For characters, if CBB_SET is specified and the lcid is zero, the global code page should be used; otherwise, the CHARBUNDLE code page should be used. █ DeviceSetAVIOFont ──────────────────────────────────────────────────────────────────────────── ULONG DeviceSetAVIOFont (hdc, pff, lcid, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ PFOCAFONT pff; /*pointer to FOCAFONT structure */ LCID lcid; /*local identifier */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The DeviceSetAVIOFont function supports loadable cell-image sets for advanced video input-and-output (AVIO) presentation spaces. The function's result is true if the given font can be used with an AVIO presentation space; otherwise, the result is false. The device driver derives a far pointer to the bit array that constitutes the image data for the given font and caches that address within the device context corresponding to the one identified by the hdc parameter. Subsequent CharRect, CharStr, and ScrollRect calls will use those cached addresses in the device context to create character images for local identifiers 1, 2, and 3. Parameters hdc the engine's device context. pfoca to a FOCAFONT structure. The structure has the following form: typedef struct _FOCAFONT { /* ff */ FONTSIGNATURE fsSignature; FOCAMETRICS fmMetrics; FONTDEFINITIONHEADER fdDefinitions; } FOCAFONT; For more information, see Chapter 10, "File Formats." lcid the font by number. This value can be 1, 2, or 3. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the device driver may record: PMERR_DEV_FUNC_NOT_INSTALLED PMERR_HDC_BUSY PMERR_INV_CODEPAGE PMERR_INV_EXTENDED_LCID PMERR_INV_FONTDEF PMERR_INV_HDC █ DeviceSetCursor ──────────────────────────────────────────────────────────────────────────── BOOL DeviceSetCursor (hdc, pptlHotSpot, hbm, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ PPOINTL pptlHotSpot; /*pointer to POINTL structure */ HBITMAP hbm; /*handle of cursor's bitmap */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The DeviceSetCursor function draws the cursor bitmap, positioning its hot spot over the coordinates pointed to by pptlHotSpot. If hbm is NULL, the function removes the cursor from the display. Parameters hdc the engine's device context. pptlHotSpot to a POINTL structure that contains the cursor's hot-spot location. hbm the cursor's bitmap. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the device driver may record: PMERR_DEV_FUNC_NOT_INSTALLED PMERR_INV_COORDINATE PMERR_INV_CURSOR_BITMAP PMERR_INV_HDC █ DeviceSetDCOrigin ──────────────────────────────────────────────────────────────────────────── BOOL DeviceSetDCOrigin (hdc, pptl, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ PPOINTL pptl; /*pointer to POINTL structure */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The DeviceSetDCOrigin function sets the device-context origin to a specified point, in screen coordinates. Parameters hdc the engine's device context. pptl to a POINTL structure that contains the screen coordinates of the device-context origin. The maximum value for these coordinates is 0x7FFE. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the device driver may record: Comments The default device-context origin is (0,0). When an application creates a device context, the origin is set to this default value. When the device-context origin is set, the engine will align the clip regions at all saved levels of the device context (if one is set). The Rao region (the region reflecting the visible area on the screen) will not be recomputed until the engine receives an explicit call to do so. █ DeviceSetGlobalAttribute ──────────────────────────────────────────────────────────────────────────── BOOL DeviceSetGlobalAttribute (hdc, ulType, ulAttr, flCmd, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ ULONG ulType; /*attribute type */ ULONG ulAttr; /*new attribute value */ LONG flCmd; /*action to take */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The DeviceSetGlobalAttribute function sets the five individual primitive attributes to the specified value, in the pen, pattern, character, image, and marker bundles. Parameters hdc the engine's device context. ulType the attribute. This parameter can be one of the following: Value Meaning ──────────────────────────────────────────────────────────────────────────── 1 Foreground color 2 Background color 3 Foreground mix mode 4 Background mix mode ulAttr the new value of the (RBG color or mix mode) attribute. flCmd the action to take. If this parameter is GATTR_DEFAULT, the action is to use the default value for the attribute. All other bits are reserved and must be zero. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the device driver may record: PMERR_DEV_FUNC_NOT_INSTALLED PMERR_INV_BACKGROUND_COL_ATTR PMERR_INV_BACKGROUND_MIX_ATTR PMERR_INV_COLOR_ATTR PMERR_INV_HDC PMERR_INV_MIX_ATTR █ DisjointLines ──────────────────────────────────────────────────────────────────────────── int DisjointLines (hdc, aptl, cptl, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ PPOINTL aptl; /*pointer to array of POINTL structures */ LONG cptl; /*count of points */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The DisjointLines function draws a series of disjoint line segments, starting at the position specified by the first point in the array pointed to by the aptl parameter. The lines are drawn using the current line attributes. Upon completion, the function sets the current position to the last point in the series. Parameters hdc the engine's device context. aptl to an array of POINTL structures. Each structure contains the coordinates of a point. This array must fit within a 64K segment. cptl the number of points. For DisjointLines, the count must be a positive integer divisible by two. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is GPI_OK or GPI_HITS if the function is successful (it is GPI_HITS if the detectable attribute is set for the presentation space and a correlation hit occurs). The return value is GPI_ERROR if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine may record: PMERR_BASE_ERROR PMERR_BITMAP_NOT_SELECTED PMERR_COORDINATE_OVERFLOW PMERR_DEV_FUNC_NOT_INSTALLED PMERR_HDC_BUSY PMERR_INV_COLOR_DATA PMERR_INV_COLOR_INDEX PMERR_INV_COORD_SPACE PMERR_INV_HDC PMERR_INV_IN_AREA PMERR_INV_IN_PATH PMERR_INV_LENGTH_OR_COUNT PMERR_INV_PICK_APERTURE_POSN PMERR_INV_RECT PMERR_PATH_LIMIT_EXCEEDED PMERR_PATH_UNKNOWN Comments For any array aptl of length n, the starting points for the line segments are defined by aptl[0], aptl[2], aptl[4], ..., aptl[n-1]. The endpoints for the line segments are defined by aptl[1], aptl[3], aptl[5], ..., aptl[n]. █ DrawBorder ──────────────────────────────────────────────────────────────────────────── BOOL DrawBorder (hdc, prcl, cx, cy, clrFore, clrBack, flCmd, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ PRECTL prcl; /*pointer to RECTL structure */ LONG cx; /*width of border */ LONG cy; /*height of border */ COLOR clrFore; /*border color */ COLOR clrBack; /*interior color */ ULONG flCmd; /*options */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ This function draws a border inside a rectangle and optionally fills the interior. This is a bitblt accelerator function. If DB_INTERIOR is specified, the area contained within the given rectangle and not included within the borders (as given by the cx and cy parameters) will be drawn using the given mix mode. Degenerate cases which must be allowed: Either or both cx or cy may be given as zero. If both are given as zero, the interior must still be drawn. If either the x borders overlap or the y borders overlap, the border is drawn as a single rectangle with no interior. Parameters prcl to a RECTL structure that contains the (device) coordinates of the rectangle to frame. cx the thickness (in device coordinates) of the horizontal border segments. cy the thickness (in device coordinates) of the vertical border segments. clrFore the color of the border (any valid format). clrBack the color of the interior (any valid format). This parameter is ignored if DB_AREAATTRS is specified. flCmd the options. See "Comments" for more information. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the device driver may record: PMERR_BASE_ERROR PMERR_BITMAP_IS_SELECTED PMERR_BITMAP_NOT_SELECTED PMERR_COORDINATE_OVERFLOW PMERR_DEV_FUNC_NOT_INSTALLED PMERR_EXCEEDS_MAX_SEG_LENGTH PMERR_HBITMAP_BUSY PMERR_HDC_BUSY PMERR_HUGE_FONTS_NOT_SUPPORTED PMERR_INCOMPATIBLE_BITMAP PMERR_INCORRECT_DC_TYPE PMERR_INSUFFICIENT_MEMORY .ET PMERR_INV_BACKGROUND_COL_ATTR PMERR_INV_BACKGROUND_MIX_ATTR PMERR_INV_BITBLT_MIX PMERR_INV_BITBLT_STYLE PMERR_INV_BITMAP_DIMENSION PMERR_INV_CHAR_DIRECTION_ATTR PMERR_INV_CHAR_MODE_ATTR PMERR_INV_CHAR_SET_ATTR PMERR_INV_CHAR_SHEAR_ATTR PMERR_INV_CODEPAGE PMERR_INV_COLOR_ATTR PMERR_INV_COLOR_DATA PMERR_INV_COLOR_FORMAT PMERR_INV_COLOR_INDEX PMERR_INV_COLOR_OPTIONS PMERR_INV_COLOR_START_INDEX PMERR_INV_COORD_SPACE PMERR_INV_COORDINATE PMERR_INV_DC_DATA PMERR_INV_DC_TYPE PMERR_INV_DRAW_BORDER_OPTION PMERR_INV_DRIVER_NAME PMERR_INV_GEOM_LINE_WIDTH_ATTR PMERR_INV_HBITMAP PMERR_INV_HDC PMERR_INV_HRGN PMERR_INV_ID PMERR_INV_IN_AREA PMERR_INV_IN_PATH PMERR_INV_INFO_TABLE PMERR_INV_LENGTH_OR_COUNT PMERR_INV_LINE_END_ATTR PMERR_INV_LINE_JOIN_ATTR PMERR_INV_LINE_TYPE_ATTR PMERR_INV_LINE_WIDTH_ATTR PMERR_INV_MARKER_SET_ATTR PMERR_INV_MARKER_SYMBOL_ATTR PMERR_INV_MIX_ATTR PMERR_INV_PATTERN_REF_PT_ATTR PMERR_INV_PATTERN_SET_ATTR PMERR_INV_PATTERN_SET_FONT PMERR_INV_PICK_APERTURE_POSN PMERR_INV_PRIMITIVE_TYPE PMERR_INV_RECT PMERR_INV_REGION_CONTROL PMERR_INV_SCAN_START PMERR_INV_SETID PMERR_INV_USAGE_PARM PMERR_REALIZE_NOT_SUPPORTED PMERR_UNSUPPORTED_ATTR PMERR_UNSUPPORTED_ATTR_VALUE Comments If the flCmd parameter is DB_ROP, it specifies the mix for the interior and the border and can be one of the following values: Value Meaning ──────────────────────────────────────────────────────────────────────────── DB_PATCOPY Copies the pattern to the destination using the raster operation ROP_PATCOPY (performs the operation D = P). DB_PATINVERT Performs an exclusive-OR (XOR) operation of the pattern with the destination using the raster operation ROP_PATINVERT (performs the operation D = DPx). DB_DESTINVERT Inverts the destination using the raster operation ROP_DESTINVERT (performs the operation D = Dn). DB_AREAMIXMODE Maps the current area foreground mix mode into a Bitblt raster operation (the area background mix mode is ignored). If the flCmd parameter is DB_AREAATTRS, it specifies that for any border, the pattern used will be the pattern as currently defined in the area attribute. For any interior, the pattern used will be the same as if a SetAttributes call for the area attributes was made with the area attribute's background color being passed for the foreground color, and the area attribute's foreground color being passed as its background color. If flCmd is not DB_AREAATTRS, then for any border or interior, the pattern used will be the same as if a SetAttributes call for the area attributes was made with a foreground color of clrFore and a background color of clrBack. If flCmd is DB_STANDARD or DB_DLGBORDER, the engine and device driver ignore the value. The DB_PATCOPY and DB_PATINVERT mix modes are mutually exclusive. DB_PATINVERT may not be used with either DB_INTERIOR or DB_AREAATTRS. Unless DB_PATCOPY or DB_PATINVERT is specified, the current mix mode is used. █ DrawConicsInPath ──────────────────────────────────────────────────────────────────────────── BOOL DrawConicsInPath (hdc, pph, pcvFirst, ccv, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ PPATH pph; /*pointer to PATH structure */ PCURVE pcvFirst; /*pointer to first CURVE structure in path */ LONG ccv; /*count of structures in path */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The DrawConicsInPath function draws the curves in a path. Parameters hdc the engine's device context. pph to a PATH structure. This structure is the second in a linked list of structures that form a path. (The first structure is a PATHSEGMENT structure, and the third through last structures are SUBPATH, LINE, and CURVE.) pcvFirst to the first CURVE structure in a path. ccv the count of CURVE structures in the path. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine or the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine or the device driver calls record: PMERR_BITMAP_NOT_SELECTED PMERR_COORDINATE_OVERFLOW PMERR_DEV_FUNC_NOT_INSTALLED PMERR_HDC_BUSY PMERR_INV_COLOR_DATA PMERR_INV_COLOR_INDEX PMERR_INV_COORD_SPACE PMERR_INV_HDC PMERR_INV_IN_AREA PMERR_INV_IN_PATH PMERR_INV_LENGTH_OR_COUNT PMERR_INV_PICK_APERTURE_POSN Comments DrawConicsInPath draws the fillets and lines in a path. (This function passes the endpoints of all lines to the driver, which then draws the lines.) This function processes all coordinates as device coordinates. █ DrawCookedPath ──────────────────────────────────────────────────────────────────────────── BOOL DrawCookedPath (hdc, pph, pcvFirst, ccv, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ PPATH pph; /*pointer to PATH structure */ PCURVE pcvFirst; /*pointer to first CURVE structure */ LONG ccv; /*count of curves */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The DrawCookedPath function draws from the number of curves specified by the ccv parameter. The function calls the Clip1DPath and ClipPathCurves functions to clip batches of curves, uses the DrawLinesInPath and DrawConicsInPath functions to draw the resulting curve, and draws all curves it is given before returning. Parameters hdc the engine's device context. pph to a PATH structure that defines the path. pcvFirst to the first CURVE structure in the path. ccv a count of the number of curves. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine or the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine or the device driver calls record: PMERR_BASE_ERROR PMERR_BITMAP_NOT_SELECTED PMERR_COORDINATE_OVERFLOW PMERR_DEV_FUNC_NOT_INSTALLED PMERR_HDC_BUSY PMERR_INV_COLOR_DATA PMERR_INV_COLOR_INDEX PMERR_INV_COORD_SPACE PMERR_INV_HDC PMERR_INV_IN_AREA PMERR_INV_IN_PATH PMERR_INV_LENGTH_OR_COUNT PMERR_INV_PICK_APERTURE_POSN PMERR_INV_RECT █ DrawLinesInPath ──────────────────────────────────────────────────────────────────────────── BOOL DrawLinesInPath (hdc, pph, pcvFirst, ccv, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ PPATH pph; /*pointer to PATH structure */ PCURVE pcvFirst; /*pointer to first CURVE structure */ LONG ccv; /*count of curves */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The DrawLinesInPath function draws lines that it finds in the path specified by the pph parameter. The number of lines drawn is specified in the ccv parameter. This function is on the bottom of the pipeline and the lines have all been clipped to both the region and the clip path. The coordinates for DrawLinesInPath are screen coordinates. Note that this is a required function but that PolyLine is not. This function will be called only if all the curves in a path are lines. Parameters hdc the engine's device context. pph to a PATH structure that defines the path. pcvFirst to the first CURVE structure in the path. ccv a count of the number of curves. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the device driver may record: PMERR_BITMAP_NOT_SELECTED PMERR_COORDINATE_OVERFLOW PMERR_DEV_FUNC_NOT_INSTALLED PMERR_HDC_BUSY PMERR_INV_COLOR_DATA PMERR_INV_COLOR_INDEX PMERR_INV_COORD_SPACE PMERR_INV_HDC PMERR_INV_IN_AREA PMERR_INV_IN_PATH PMERR_INV_LENGTH_OR_COUNT PMERR_INV_PICK_APERTURE_POSN █ DrawRawPath ──────────────────────────────────────────────────────────────────────────── BOOL DrawRawPath (hdc, pph, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ PPATH pph; /*pointer to PATH structure */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The DrawRawPath function processes raw paths by calling the CookPathCurves and DrawCookedPath functions. It returns after processing the entire path. Parameters hdc the engine's device context. pph to the PATH structure that defines the path. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine or the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine or the device driver calls record: PMERR_BASE_ERROR PMERR_BITMAP_NOT_SELECTED PMERR_COORDINATE_OVERFLOW PMERR_DEV_FUNC_NOT_INSTALLED PMERR_HDC_BUSY PMERR_INV_COLOR_DATA PMERR_INV_COLOR_INDEX PMERR_INV_COORD_SPACE PMERR_INV_HDC PMERR_INV_IN_AREA PMERR_INV_IN_PATH PMERR_INV_LENGTH_OR_COUNT PMERR_INV_PICK_APERTURE_POSN PMERR_INV_RECT PMERR_PATH_LIMIT_EXCEEDED Comments DrawRawPath processes only paths that have a single subpath. The Arc, PolyFilletSharp, and other curve-drawing functions call the DrawRawPath function. █ EndArea ──────────────────────────────────────────────────────────────────────────── int EndArea (hdc, fCancel, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ ULONG fCancel; /*options flag */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The EndArea function defines the end of an area bracket. An area bracket is a set of line and/or arc functions that define the shape of an area's borders. Parameters hdc the engine's device context. fCancel whether the function should draw the area. If this parameter is EA_DRAW, the area is to be drawn. If this parameter is EA_CANCEL, the area is to be canceled (terminated without being drawn). hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is GPI_OK or GPI_HITS if the function is successful (it is GPI_HITS if the detectable attribute is set for the presentation space and a correlation hit occurs). The return value is GPI_ERROR if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine or the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine or the device driver calls record: PMERR_BASE_ERROR PMERR_BITMAP_NOT_SELECTED PMERR_COORDINATE_OVERFLOW PMERR_DEV_FUNC_NOT_INSTALLED PMERR_EXCEEDS_MAX_SEG_LENGTH PMERR_HDC_BUSY PMERR_HRGN_BUSY PMERR_HUGE_FONTS_NOT_SUPPORTED PMERR_INSUFFICIENT_MEMORY PMERR_INV_AREA_CONTROL PMERR_INV_BACKGROUND_COL_ATTR PMERR_INV_BACKGROUND_MIX_ATTR PMERR_INV_CHAR_DIRECTION_ATTR PMERR_INV_CHAR_MODE_ATTR PMERR_INV_CODEPAGE PMERR_INV_COLOR_ATTR PMERR_INV_COLOR_DATA PMERR_INV_COLOR_INDEX PMERR_INV_COORD_SPACE PMERR_INV_COORDINATE PMERR_INV_HDC PMERR_INV_HRGN PMERR_INV_IN_AREA PMERR_INV_IN_PATH PMERR_INV_LENGTH_OR_COUNT PMERR_INV_LINE_TYPE_ATTR PMERR_INV_MIX_ATTR PMERR_INV_PATTERN_REF_PT_ATTR PMERR_INV_PATTERN_SET_ATTR PMERR_INV_PATTERN_SET_FONT PMERR_INV_PICK_APERTURE_POSN PMERR_INV_RECT PMERR_INV_REGION_CONTROL PMERR_NOT_IN_AREA PMERR_PATH_LIMIT_EXCEEDED PMERR_REGION_IS_CLIP_REGION Comments By calling EndArea with fCancel set to 1, the area bracket is reset to a known state. (When fCancel is 1, an EndArea call is valid, even when it isn't preceded by a BeginArea call.) If there is a correlation hit on any part of the area interior, it is indicated by a return code. (Correlation hits on the boundary are indicated by a return code of the primitive causing the hit.) If the current figure is not closed, this function generates a closure line from the current position to the start of the current figure. If a correlation hit falls on this line as well as on the area interior, a special return code indicates this double hit. On devices in which the hardware assists in filling areas (such as by using an area fill plane), this assistance may be used, or the area definition may be built up in an area fill plane in ordinary memory. For convex figures, it may be faster to record the starting and ending pel positions across each scan line. Whatever algorithms are used, the area interiors must be filled identically in each case; otherwise, bitmap operations may fail to join correctly when copied to the screen, etc. This identical filling is especially important when the area is being moved around the screen using a mix mode of XOR in order to remove it. Upon completion, the current (x,y) position is the last position specified in the boundary definition, unless the figure was closed, in which case it is the start of the last figure in the area definition. █ EndPath ──────────────────────────────────────────────────────────────────────────── BOOL EndPath (hdc, fCancel, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ ULONG fCancel; /*options flag */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The EndPath function defines the end of a path bracket. A path bracket is a set of graphics functions that define the shape of a path. Parameters hdc the engine's device context. fCancel whether the function should create the path. If this parameter is zero, the path is created. If the parameter is 1, the path is canceled (terminated without being created). hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine or the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine or the device driver calls record: PMERR_BASE_ERROR PMERR_COORDINATE_OVERFLOW PMERR_DEV_FUNC_NOT_INSTALLED PMERR_HDC_BUSY PMERR_INV_END_PATH_OPTIONS PMERR_INV_HDC PMERR_NOT_IN_PATH PMERR_PATH_LIMIT_EXCEEDED Comments An EndPath call (when fCancel equals 1) without a previous call to the BeginPath function is valid but has no effect. So it is possible to reset the path bracket to a known state without any knowledge of its current state. █ EqualRegion ──────────────────────────────────────────────────────────────────────────── int EqualRegion (hdc, hrgnSrc1, hrgnSrc2, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ HRGN hrgnSrc1; /*handle of source region 1 */ HRGN hrgnSrc2; /*handle of source region 2 */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function numbers */ The EqualRegion function determines whether the same set of points defines two separate regions. Parameters hdc the engine's device context. hrgnSrc1 the first of two regions. hrgnSrc2 the second of two regions. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is EQRGN_EQUAL if the regions are equal, EQRGN_NOTEQUAL if they are not, and EQRGN_ERROR if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine or the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine or the device driver calls record: PMERR_HRGN_BUSY PMERR_INV_HRGN PMERR_REGION_IS_CLIP_REGION Comments If the hrgnSrc1 or hrgnSrc2 parameter identifies a clip region, the function fails and returns an error. █ ErasePS ──────────────────────────────────────────────────────────────────────────── BOOL ErasePS (hdc, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The ErasePS function erases the display associated with the device context identified by the hdc parameter. Parameters hdc the engine's device context. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the device driver may record: PMERR_BASE_ERROR PMERR_BITMAP_IS_SELECTED PMERR_BITMAP_NOT_SELECTED PMERR_COORDINATE_OVERFLOW PMERR_DEV_FUNC_NOT_INSTALLED .ET PMERR_EXCEEDS_MAX_SEG_LENGTH PMERR_HBITMAP_BUSY PMERR_HDC_BUSY PMERR_HUGE_FONTS_NOT_SUPPORTED PMERR_INCOMPATIBLE_BITMAP PMERR_INCORRECT_DC_TYPE PMERR_INSUFFICIENT_MEMORY PMERR_INV_BACKGROUND_COL_ATTR PMERR_INV_BACKGROUND_MIX_ATTR PMERR_INV_BITBLT_MIX PMERR_INV_BITBLT_STYLE PMERR_INV_BITMAP_DIMENSION PMERR_INV_CHAR_DIRECTION_ATTR PMERR_INV_CHAR_MODE_ATTR PMERR_INV_CHAR_SET_ATTR PMERR_INV_CHAR_SHEAR_ATTR PMERR_INV_CODEPAGE PMERR_INV_COLOR_ATTR PMERR_INV_COLOR_DATA PMERR_INV_COLOR_FORMAT PMERR_INV_COLOR_INDEX PMERR_INV_COLOR_OPTIONS PMERR_INV_COLOR_START_INDEX PMERR_INV_COORD_SPACE PMERR_INV_COORDINATE PMERR_INV_DC_DATA PMERR_INV_DC_TYPE PMERR_INV_DRIVER_NAME PMERR_INV_GEOM_LINE_WIDTH_ATTR PMERR_INV_HBITMAP PMERR_INV_HDC PMERR_INV_HRGN PMERR_INV_ID PMERR_INV_IN_AREA PMERR_INV_IN_PATH PMERR_INV_INFO_TABLE PMERR_INV_LENGTH_OR_COUNT PMERR_INV_LINE_END_ATTR PMERR_INV_LINE_JOIN_ATTR PMERR_INV_LINE_TYPE_ATTR PMERR_INV_LINE_WIDTH_ATTR PMERR_INV_MARKER_SET_ATTR PMERR_INV_MARKER_SYMBOL_ATTR PMERR_INV_MIX_ATTR PMERR_INV_PATTERN_REF_PT_ATTR PMERR_INV_PATTERN_SET_ATTR PMERR_INV_PATTERN_SET_FONT PMERR_INV_PICK_APERTURE_POSN PMERR_INV_PRIMITIVE_TYPE PMERR_INV_RECT PMERR_INV_REGION_CONTROL PMERR_INV_SCAN_START PMERR_INV_SETID PMERR_INV_USAGE_PARM PMERR_REALIZE_NOT_SUPPORTED PMERR_UNSUPPORTED_ATTR PMERR_UNSUPPORTED_ATTR_VALUE Comments The ErasePS function erases the display by using the color identified by color index 0. This operation is unaffected by the draw-process control bit and is subject to all clipping (to clip paths, viewing limits, graphics fields, clip regions, and visible regions). This function does not perform any bounds collection or correlation. █ Escape ──────────────────────────────────────────────────────────────────────────── LONG Escape (hdc, lCmd, cbIn, pbIn, pcbOut, pbOut, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ ULONG lCmd; /*escape-function identifier */ LONG cbIn; /*length of input data */ PBYTE pbIn; /*pointer to input data */ PLONG pcbOut; /*pointer to length of output data */ PBYTE pbOut; /*pointer to output data */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The Escape function accesses special device capabilities that can't be accessed through Gpi functions. These capabilities include banding, sending raw data to the device, and spooling print jobs. Parameters hdc the engine's device context. lCmd the escape function to perform. The following predefined functions are available: Function Code ──────────────────────────────────────────────────────────────────────────── DEVESC_QUERYESCSUPPORT 0L DEVESC_GETSCALINGFACTOR 1L DEVESC_STARTDOC 8150L DEVESC_ENDDOC 8151L DEVESC_NEXTBAND 8152L DEVESC_ABORTDOC 8153L DEVESC_NEWFRAME 16300L DEVESC_DRAFTMODE 16301L DEVESC_FLUSHOUTPUT 16302L DEVESC_RAWDATA 16303L DEVESC_STD_JOURNAL 32600L Values in the range 0 through 32,767 are reserved for these predefined functions. Devices can define additional escape functions by using lCmd values in the range 32,768 through 65,535. Note that at the applications programming interface (API), for a device-context type of OD_QUEUED with a data type of Q_STD or for a device-context type of OD_METAFILE, not all DevEscape calls are passed to the engine/device driver. Depending on the value of lCmd, they may be metafiled or recorded as follows: Value Meaning ──────────────────────────────────────────────────────────────────────────── 0-8149 Not metafiled, not recorded (passed to the device context in both cases). 8150-16299 Metafiled but not recorded (passed to the device context for Q_STD). 16300-24449 Metafiled and recorded (Not passed to the information/device context in either case). 24450-32599 Not metafiled but recorded (passed to the information/device context for OD_METAFILE). 32600-32767 Reserved (for use with Q_ESC spool file). 32768-40959 Not metafiled, not recorded (passed to the information/device context in both cases). 40960-49151 Metafiled but not recorded (passed to the device context for Q_STD). 49152-57343 Metafiled and recorded (Not passed to the information/device context in either case) 57344-65535 Not metafiled but recorded (passed to the information/device context for OD_METAFILE). cbIn the number of bytes of data pointed to by the pbIn parameter. pbIn to the escape function's input data. pcbOut to a value that specifies the number of bytes of output data. pbOut to the escape function's output data. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is DEV_OK if the function is successful, DEVESC_NOTIMPLEMENTED if the escape function does not apply or is not implemented, or DEVESC_ERROR if an error occurs. Errors If an error occurs during the execution of this function, the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the device driver may record: PMERR_DEV_FUNC_NOT_INSTALLED PMERR_INV_LENGTH_OR_COUNT Comments The escape functions are described as follows: The DEVESC_ABORTDOC function aborts the current job, erasing everything the application has written to the device since the last DEVESC_STARTDOC escape, including the DEVESC_STARTDOC. The parameters are set as follows: Parameter Description ──────────────────────────────────────────────────────────────────────────── cbIn Not used, and can be zero. pbIn Not used, and can be set to NULL. pcbOut Not used, and can be zero. pbOut Not used, and can be set to NULL. The DEVESC_ENDDOC function ends a print job started by DEVESC_STARTDOC and returns the job identifier for the spooled print job. The parameters are set as follows: Parameter Description ──────────────────────────────────────────────────────────────────────────── cbIn Not used, and can be zero. pbIn Not used, and can be set to NULL. pcbOut Points to cbOut, which on input is set to the size of the buffer pointed to by pbOut (in this case, 2 bytes) and on output is set to the number of data bytes returned in this buffer (that is, zero if there is no job identifier). pbOut Points to a data area in which the job identifier of the spooled print job is returned. This parameter is set to NULL if there is no job identifier (for example, for a direct printer). The DEVESC_DRAFTMODE function turns draft mode on or off. Turning draft mode on instructs the device driver to print faster and with lower quality, if necessary. The draft mode can be changed only at page boundaries (for example, after a call to DEVESC_NEWFRAME). The parameters are set as follows: Parameter Description ──────────────────────────────────────────────────────────────────────────── cbIn Specifies the number of bytes pointed to by pbIn. pbIn Points to a SHORT value specifying the mode: 1 for draft mode on, 0 for off. pcbOut Not used, and can be zero. pbOut Not used, and can be set to NULL. The DEVESC_FLUSHOUTPUT function flushes any output in the device's buffer. The parameters are set as follows: Parameter Description ──────────────────────────────────────────────────────────────────────────── cbIn Not used, and can be zero. pbIn Not used, and can be set to NULL. pcbOut Not used, and can be zero. pbOut Not used, and can be set to NULL. The DEVESC_GETSCALINGFACTOR function retrieves the scaling factors for the x and y axes of a printing device. For each scaling factor, an exponent of two is put in pcbOut. Thus, the value 3 is used if the scaling factor is 8. Scaling factors are used by devices that cannot support graphics at the same resolution as the device resolution. The parameters are set as follows: Parameter Description ──────────────────────────────────────────────────────────────────────────── cbIn Not used, and can be zero. pbIn Not used, and can be set to NULL. pcbOut Specifies the number of bytes of data pointed to by pbOut. On return, this parameter is updated to the number of bytes returned. pbOut Points to a POINTL structure that receives the output from this escape function: the scaling factors for the x and y axes. This structure has the following form: typedef struct _POINTL { /* ptl */ LONG x; LONG y; } POINTL; The scaling factors are given as exponents of two. </C></ROW> The DEVESC_NEWFRAME function allows the application to specify that it has finished writing to a page. This function, which is similar to the ErasePS function's processing for a screen device context, resets the attributes (for example, color, mix). DEVESC_NEWFRAME is usually used with a printer device to advance to a new page. The parameters are set as follows: Parameter Description ──────────────────────────────────────────────────────────────────────────── cbIn Not used, and can be zero. pbIn Not used, and can be set to NULL. pcbOut Not used, and can be zero. pbOut Not used, and can be set to NULL. The DEVESC_NEXTBAND function allows the application to specify that it has finished writing to a band. The coordinates of the next band are returned. This function is used by applications that handle banding themselves. The parameters are set as follows: Parameter Description ──────────────────────────────────────────────────────────────────────────── cbIn Not used, and can be zero. pbIn Not used, and can be set to NULL. pcbOut Specifies the number of bytes of data pointed to by pbOut. On return, this parameter is updated to the number of bytes returned. pbOut Points to a RECTL structure that receives the device coordinates of the next band, which is a rectangle. The structure has the following form: typedef struct _RECTL { /* rcl */ LONG xLeft; LONG yBottom; LONG xRight; LONG yTop; } RECTL; An empty rectangle (that is, xLeft greater than xRight, and yTop less than yBottom) marks the end of the banding operation. </C></ROW> The DEVESC_QUERYESCSUPPORT function determines whether a particular escape function is implemented by the device driver. The return value gives the result. The parameters are set as follows: Parameter Description ──────────────────────────────────────────────────────────────────────────── cbIn Specifies the number of bytes pointed to by cbIn. pbIn Points to an escape-code value that specifies the escape function to check. pcbOut Not used, and can be zero. pbOut Not used, and can be set to NULL. The DEVESC_RAWDATA function allows an application to send data directly to a device driver. For example, in the case of a printer device driver, the data could be a printer data stream. If application data is mixed with other data (for example, from GPI) being sent to the same page of a device context, the results are unpredictable and depend upon the action taken by the device driver. For example, a device driver might ignore GPI data if raw (binary) data is mixed with it on the same page. In general, DEVESC_RAWDATA should be sent either to a separate page, using the DEVESC_NEWFRAME escape to obtain a new page, or to a separate document, using the DEVESC_STARTDOC and DEVESC_ENDDOC escapes to create a new document. The parameters are set as follows: Parameter Description ──────────────────────────────────────────────────────────────────────────── cbIn Specifies the number of bytes pointed to by pbIn. pbIn Points to the raw data. pcbOut Not used, and can be zero. pbOut Not used, and can be set to NULL. The DEVESC_STARTDOC function allows an application to specify that a new print job is starting and that all subsequent DEVESC_NEWFRAME calls should be spooled under the same job, until a DEVESC_ENDDOC call occurs. This ensures that documents longer than one page are not interspersed with other jobs. The parameters are set as follows: Parameter Description ──────────────────────────────────────────────────────────────────────────── cbIn Specifies the number of characters in the string pointed to by pbIn. pbIn Points to a null-terminated string that specifies the name of the document. pcbOut Not used, and can be zero. pbOut Not used, and can be set to NULL. The DEVESC_STD_JOURNAL function allows a print file in Q_ESC/Journal format to be passed to a device driver. The parameters are set as follows: Parameter Description ──────────────────────────────────────────────────────────────────────────── cbIn Specifies the number of bytes pointed to by pbIn. pbIn Points to the data. pcbOut Not used, and can be zero. pbOut Not used, and can be set to NULL. █ ExcludeClipRectangle ──────────────────────────────────────────────────────────────────────────── int ExcludeClipRectangle (hdc, prcl, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ PRECTL prcl; /*pointer to rectangle structure */ ULONG hddc; /*device driver's device context */ ULONG ulFunN; /*flags and function number */ The ExcludeClipRectangle function excludes the specified rectangle from the clipping region. The bottom and left boundaries of the rectangle are included in the boundary which is to disappear. Note that the rectangle boundaries are considered part of the interior and are clipped. Parameters hdc the engine's device context. prcl to a RECTL structure that specifies the coordinates of the rectangle in world coordinates. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is RGN_NULL, RGN_RECT, or RGN_COMPLEX if the function is successful. The return value is RGN_ERROR if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine or the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine or the device driver calls record: PMERR_COORDINATE_OVERFLOW PMERR_DEV_FUNC_NOT_INSTALLED PMERR_HDC_BUSY PMERR_INSUFFICIENT_MEMORY PMERR_INV_COORD_SPACE PMERR_INV_COORDINATE PMERR_INV_HDC PMERR_INV_HRGN PMERR_INV_IN_AREA PMERR_INV_IN_PATH PMERR_INV_LENGTH_OR_COUNT PMERR_INV_RECT PMERR_INV_REGION_CONTROL █ FillPath ──────────────────────────────────────────────────────────────────────────── BOOL FillPath (hdc, phid, flCmd, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ PHID phid; /*path identifier */ ULONG flCmd; /*options */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function numbers */ The FillPath function fills the interior of closed figures defined within a path bracket. Before filling occurs, this function closes any open figures within the path bracket. After filling the path, the function deletes it. Parameters hdc the engine's device context. phid to the path identifier. This value must be 1 for the current release of MS OS/2 Presentation Manager. flCmd whether the function should fill the path by using the alternate or the winding fill method. This parameter can be one of the following values: Constant Meaning ──────────────────────────────────────────────────────────────────────────── FPATH_ALTERNATE Specifies that the function should fill the path by using the alternate fill method. FPATH_WINDING Specifies that the function should fill the path by using the winding fill method. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is GPI_OK or GPI_HITS if the function is successful (it is GPI_HITS if the detectable attribute is set for the presentation space and a correlation hit occurs). The return value is GPI_ERROR if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine or the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine or the device driver calls record: PMERR_BASE_ERROR PMERR_BITMAP_NOT_SELECTED PMERR_COORDINATE_OVERFLOW PMERR_DEV_FUNC_NOT_INSTALLED PMERR_HDC_BUSY PMERR_HRGN_BUSY PMERR_INSUFFICIENT_MEMORY PMERR_INV_COLOR_DATA PMERR_INV_COLOR_INDEX PMERR_INV_COORD_SPACE PMERR_INV_COORDINATE PMERR_INV_FILL_PATH_OPTIONS PMERR_INV_HDC PMERR_INV_HRGN PMERR_INV_IN_AREA PMERR_INV_IN_PATH PMERR_INV_LENGTH_OR_COUNT PMERR_INV_PATH_ID PMERR_INV_PICK_APERTURE_POSN PMERR_INV_RECT PMERR_INV_REGION_CONTROL PMERR_PATH_LIMIT_EXCEEDED PMERR_PATH_UNKNOWN PMERR_REGION_IS_CLIP_REGION █ FullArcBoth ──────────────────────────────────────────────────────────────────────────── LONG FullArcBoth (hdc, fxMult, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ FIXED fxMult; /*radius multiplier value */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The FullArcBoth function draws the outline of an ellipse and fills its interior with the current fill pattern. The ellipse is centered at the current position. The fxMult parameter specifies the length of the ellipse's radius. Parameters hdc the engine's device context. fxMult the multiplier that determines the size of the arc in relation to an arc with the current arc parameters. The value passed is treated as a 4-byte fixed-point (FIXED) number with the high word as the integer portion, and the low word as the fractional portion. Thus, a value of 65,536 specifies a multiplier of 1. This parameter must be greater than or equal to zero. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is GPI_OK or GPI_HITS if the function is successful (it is GPI_HITS if the detectable attribute is set for the presentation space and a correlation hit occurs). The return value is GPI_ERROR if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine or the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine or the device driver calls record: PMERR_ALREADY_IN_AREA PMERR_BASE_ERROR PMERR_BITMAP_NOT_SELECTED PMERR_COORDINATE_OVERFLOW PMERR_DEV_FUNC_NOT_INSTALLED PMERR_EXCEEDS_MAX_SEG_LENGTH PMERR_HDC_BUSY PMERR_HRGN_BUSY PMERR_HUGE_FONTS_NOT_SUPPORTED PMERR_INSUFFICIENT_MEMORY PMERR_INV_AREA_CONTROL PMERR_INV_BACKGROUND_COL_ATTR PMERR_INV_BACKGROUND_MIX_ATTR PMERR_INV_CHAR_DIRECTION_ATTR PMERR_INV_CHAR_MODE_ATTR PMERR_INV_CODEPAGE PMERR_INV_COLOR_ATTR PMERR_INV_COLOR_DATA PMERR_INV_COLOR_INDEX PMERR_INV_COORD_SPACE PMERR_INV_COORDINATE PMERR_INV_HDC PMERR_INV_HRGN PMERR_INV_IN_AREA PMERR_INV_IN_PATH PMERR_INV_LENGTH_OR_COUNT PMERR_INV_LINE_TYPE_ATTR PMERR_INV_MIX_ATTR PMERR_INV_MULTIPLIER PMERR_INV_NESTED_FIGURES PMERR_INV_PATTERN_REF_PT_ATTR PMERR_INV_PATTERN_SET_ATTR PMERR_INV_PATTERN_SET_FONT PMERR_INV_PICK_APERTURE_POSN PMERR_INV_RECT PMERR_INV_REGION_CONTROL PMERR_NOT_IN_AREA PMERR_NOT_IN_PATH PMERR_PATH_LIMIT_EXCEEDED PMERR_PATH_UNKNOWN PMERR_REGION_IS_CLIP_REGION Comments The current (x,y) position is not changed by FullArcBoth. The arc parameters determine whether the full arc is drawn clockwise or counterclockwise. Note that for correlation operations, a correlation hit is recorded under the following circumstances: ■ The boundary is being drawn and the pick aperture intersects it. ■ The interior is being filled and the pick aperture intersects or is completely in the interior (even if the transparent mix mode is used for the fill operation). ■ The boundary is being drawn and the interior is being filled and the pick aperture intersects or is completely within the interior (even if the transparent mix mode is used for the fill operation). It is the values of the arc parameters p, q, r, and s that determine the direction in which the arc is drawn (clockwise or counterclockwise), not the value of the arc multiplier. █ FullArcBoundary ──────────────────────────────────────────────────────────────────────────── int FullArcBoundary (hdc, fxMult, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ FIXED fxMult; /*radius multiplier value */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The FullArcBoundary function draws the outline of an ellipse. The ellipse is centered at the current position. The fxMult parameter specifies the length of the ellipse's radius. Parameters hdc the engine's device context. fxMult the multiplier that determines the size of the arc in relation to an arc with the current arc parameters. The value passed is treated as a 4-byte fixed-point (FIXED) number with the high word as the integer portion, and the low word as the fractional portion. Thus, a value of 65,536 specifies a multiplier of 1. This parameter must be greater than or equal to zero. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is GPI_OK or GPI_HITS if the function is successful (it is GPI_HITS if the detectable attribute is set for the presentation space and a correlation hit occurs). The return value is GPI_ERROR if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine or the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine or the device driver calls record: PMERR_BASE_ERROR PMERR_BITMAP_NOT_SELECTED PMERR_COORDINATE_OVERFLOW PMERR_DEV_FUNC_NOT_INSTALLED PMERR_HDC_BUSY PMERR_INV_COLOR_DATA PMERR_INV_COLOR_INDEX PMERR_INV_COORD_SPACE PMERR_INV_HDC PMERR_INV_IN_AREA PMERR_INV_IN_PATH PMERR_INV_LENGTH_OR_COUNT PMERR_INV_MULTIPLIER PMERR_INV_NESTED_FIGURES PMERR_INV_PICK_APERTURE_POSN PMERR_INV_RECT PMERR_NOT_IN_PATH PMERR_PATH_LIMIT_EXCEEDED PMERR_PATH_UNKNOWN Comments The current (x,y) position is not changed by FullArcBoundary. The arc parameters determine whether the full arc is drawn clockwise or counterclockwise. Note that for correlation operations, a correlation hit is recorded under the following circumstances: ■ The boundary is being drawn and the pick aperture intersects it. ■ The interior is being filled and the pick aperture intersects or is completely within the interior (even if the transparent mix mode is used for the fill operation). ■ The boundary is being drawn and the interior is being filled and the pick aperture intersects or is completely within the interior (even if the transparent mix mode is used for the fill operation). It is the values of the arc parameters p, q, r, and s that determine the direction in which the arc is drawn (clockwise or counterclockwise), not the value of the arc multiplier. █ FullArcInterior ──────────────────────────────────────────────────────────────────────────── LONG FullArcInterior (hdc, fxMult, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ FIXED fxMult; /*radius multiplier value */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The FullArcInterior function fills the interior of an ellipse with the current fill pattern. The ellipse is centered at the current position. The fxMult parameter specifies the length of the ellipse's radius. Parameters hdc the engine's device context. fxMult the multiplier that determines the size of the arc in relation to an arc with the current arc parameters. The value passed is treated as a 4-byte fixed-point (FIXED) number with the high word as the integer portion, and the low word as the fractional portion. Thus, a value of 65,536 specifies a multiplier of 1. This parameter must be greater than or equal to zero. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is GPI_OK or GPI_HITS if the function is successful (it is GPI_HITS if the detectable attribute is set for the presentation space and a correlation hit occurs). The return value is GPI_ERROR if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine or the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine or the device driver calls record: PMERR_ALREADY_IN_AREA PMERR_BASE_ERROR PMERR_BITMAP_NOT_SELECTED PMERR_COORDINATE_OVERFLOW PMERR_DEV_FUNC_NOT_INSTALLED PMERR_EXCEEDS_MAX_SEG_LENGTH PMERR_HDC_BUSY PMERR_HRGN_BUSY PMERR_HUGE_FONTS_NOT_SUPPORTED PMERR_INSUFFICIENT_MEMORY PMERR_INV_AREA_CONTROL PMERR_INV_BACKGROUND_COL_ATTR PMERR_INV_BACKGROUND_MIX_ATTR PMERR_INV_CHAR_DIRECTION_ATTR PMERR_INV_CHAR_MODE_ATTR PMERR_INV_CODEPAGE PMERR_INV_COLOR_ATTR PMERR_INV_COLOR_DATA PMERR_INV_COLOR_INDEX PMERR_INV_COORD_SPACE PMERR_INV_COORDINATE PMERR_INV_HDC PMERR_INV_HRGN PMERR_INV_IN_AREA PMERR_INV_IN_PATH PMERR_INV_LENGTH_OR_COUNT PMERR_INV_LINE_TYPE_ATTR PMERR_INV_MIX_ATTR PMERR_INV_MULTIPLIER PMERR_INV_NESTED_FIGURES PMERR_INV_PATTERN_REF_PT_ATTR PMERR_INV_PATTERN_SET_ATTR PMERR_INV_PATTERN_SET_FONT PMERR_INV_PICK_APERTURE_POSN PMERR_INV_RECT PMERR_INV_REGION_CONTROL PMERR_NOT_IN_AREA PMERR_NOT_IN_PATH PMERR_PATH_LIMIT_EXCEEDED PMERR_PATH_UNKNOWN PMERR_REGION_IS_CLIP_REGION Comments The current (x,y) position is not changed by FullArcInterior. The arc parameters determine whether the full arc is drawn clockwise or counterclockwise. Note that for correlation operations, a correlation hit is recorded under the following circumstances: ■ The boundary is being drawn and the pick aperture intersects it. ■ The interior is being filled and the pick aperture intersects or is completely within the interior (even if the transparent mix mode is used for the fill operation). ■ The boundary is being drawn and the interior is being filled and the pick aperture intersects or is completely within the interior (even if the transparent mix mode is used for the fill operation). It is the values of the arc parameters p, q, r, and s that determine the direction in which the arc is drawn (clockwise or counterclockwise), not the value of the arc multiplier. █ GetArcParameters ──────────────────────────────────────────────────────────────────────────── BOOL GetArcParameters (hdc, parcp, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ PARCPARAMS parcp; /*pointer to ARCPARAMS structure */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The GetArcParameters function retrieves the current values of the arc parameters: p, q, r, and s. Parameters hdc the engine's device context. parcp to an ARCPARAMS structure that contains the arc parameters. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine or the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine or the driver may record: PMERR_HDC_BUSY PMERR_INV_HDC █ GetAttributes ──────────────────────────────────────────────────────────────────────────── LONG GetAttributes (hdc, ulType, flAttrs, pBundle, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ ULONG ulType; /*primitive type identifier */ ULONG flAttrs; /*attributes mask */ PBUNDLE pBundle; /*pointer to attribute bundle */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The GetAttributes function retrieves the current values for attributes specified by the flAttrs parameter. Parameters hdc the engine's device context. ulType the type of attributes that the function should retrieve. The function places the attributes in a special attribute bundle. This parameter can be one of the following values: Value Meaning ──────────────────────────────────────────────────────────────────────────── PRIM_LINE Line-attribute bundle PRIM_CHAR Character-attribute bundle PRIM_MARKER Marker-attribute bundle PRIM_AREA Area-attribute bundle PRIM_IMAGE Image-attribute bundle flAttrs which fields (in the attribute bundle) that the function should fill. The fields in each bundle are represented by specific bits. The function will retrieve information for each bit that is set. pBundle to a copy of an attribute bundle. Valid information only appears in fields that have a corresponding bit set in the flAttrs parameter. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is the default mask if the function is successful. Otherwise, it is GPI_ALTERROR. Errors If an error occurs during the execution of this function, the graphics engine calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine may record: PMERR_HDC_BUSY PMERR_INV_HDC Comments Only those flags with the corresponding bit set in flAttrs will be updated; other returned flags are undefined. This function retrieves the current value of the attributes specified in flAttrs. If a specified attribute is currently set to its standard default value, the corresponding flag is set in the returned defaults mask and the returned value for this attribute is undefined. For each attribute specified, the engine either returns the value of the attribute─in which case, the corresponding bit in the return value will not be set─or sets the bit in the return value indicating that the attribute specified is set to the default. The corresponding value in the buffer is not valid and may even have been overwritten by the engine. █ GetBitmapBits ──────────────────────────────────────────────────────────────────────────── LONG GetBitmapBits (hdc, hbm, iScanStart, cScanCount, pbBits, pbmi, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ HBITMAP hbm; /*handle of bitmap */ LONG iScanStart; /*starting scan-line number */ LONG cScanCount; /*scan-line count */ PBYTE pbBits; /*pointer to bitmap bits */ PBITMAPINFO pbmi; /*pointer to BITMAPINFO structure */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The GetBitmapBits function copies color information from an image on a display into a bitmap. Parameters hdc the engine's device context. hbm the bitmap. If this parameter is NULL, the hdc parameter must identify a memory device context that will receive the bitmap information. iScanStart the number of the scan line where the function will begin collecting color information. If this value is 0, the function begins with the first scan line. cScanCount the total number of scan lines. pbBits to the bitmap. pbmi to a BITMAPINFO structure that defines the format of the bitmap. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is the number of scan lines returned if the function is successful; otherwise, it is GPI_ALTERROR. Errors If an error occurs during the execution of this function, the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the device driver may record: PMERR_BITMAP_NOT_SELECTED PMERR_DEV_FUNC_NOT_INSTALLED PMERR_INCORRECT_DC_TYPE PMERR_INV_HBITMAP PMERR_INV_IN_AREA PMERR_INV_IN_PATH PMERR_INV_INFO_TABLE PMERR_INV_LENGTH_OR_COUNT PMERR_INV_SCAN_START Comments This function transfers bitmap data from the specified bitmap to application storage. The bitmap may be specified by a bitmap handle or, if the handle is NULL, by a device-context handle. The device context must be a memory device context, with a bitmap currently selected. The BITMAPINFO structure must be initialized with the values of the cPlanes and cBitCount fields set to the applicable bitmap format, which must be a standard format. On return, the cx, cy, and argbColor fields will have been filled by the system. Also, the system will convert the bitmap data, if necessary. The bitmap address specified by pbBits must point to a storage area large enough to contain data for the requested number of scan lines. The amount of storage required for one scan line can be determined by calling the GetBitmapParameters function. This amount is given by the following formula: ((cBitCount * cx + 31)/32) * cPlanes * 4 (bytes) The total amount of storage required for the complete bitmap can be determined by multiplying this by the height of the bitmap (cy). There are four standard bitmap formats. All device drivers are required to be able to translate between any of these formats and their own internal formats. The standard formats are as follows: Format Description ──────────────────────────────────────────────────────────────────────────── Monochrome 1 bit per pel and 1 color plane 16-color 4 bits per pel and 1 color plane 256-color 8 bits per pel and 1 color plane Full-color 24 bits per pel and 1 color plane These formats are chosen because they are identical or similar to all formats commonly used by raster devices. Only single-plane formats are standard, but it is very easy to convert these to any multiple-plane format used internally by a device. The pixel data is stored in the bitmap in the order of the coordinates as they would appear on a display screen. That is, the pixel in the lower-left corner is the first in the bitmap. Pixels are scanned from left to right and up. The first pixel's bits are stored beginning in the most significant bits of the first byte. The data for pixels in each scan line is packed tightly. Each scan line, however, is padded at the end so that each scan line begins on a DWORD boundary. Bitmap Color Tables Each standard-format bitmap must be accompanied by a BITMAPINFO structure. Because these bitmaps are intended to be traded between devices, the color indices in the bitmap are meaningless without more information. For a description of the BITMAPINFOHEADER and BITMAPINFO structures, see Chapter 9, "Types, Macros, Structures." The argbColor field is a packed array of 24-bit RGB values. If there are n bits per pixel, argbColor would contain %2 sup n% RGB values, unless n = 24. The standard-format bitmap with 24 bits per pixel is assumed to contain RGB values and does not require the argbColor array. Example To make the ordering of all the bytes clear, consider the following simple example of a 5 * 3 array of colored pixels that uses the format of 4 bits per pixel: Red Green Blue Red Green Blue Red Green Blue Red Green Blue Red Green Blue ExampleBitmap = 0x23, 0x12, 0x30, 0x00 /* bottom line */ 0x31, 0x23, 0x10, 0x00 /* middle line */ 0x12, 0x31, 0x20, 0x00 /* top line */ #define BLACK 0x000000L #define RED 0xFF0000L #define GREEN 0x00FF00L #define BLUE 0x0000FFL struct _BITMAPINFO { 12, /* length of structure, fixed portion */ 5, /* width */ 3, /* height */ 1, /* planes */ 4, /* bit count */ BLACK, RED, GREEN, BLUE, /* color-table array */ BLACK, BLACK, BLACK, BLACK, BLACK, BLACK, BLACK, BLACK, BLACK, BLACK, BLACK, BLACK }; █ GetBitmapDimension ──────────────────────────────────────────────────────────────────────────── BOOL GetBitmapDimension (hbm, psizl, hddc, ulFunN) HBITMAP hbm; /*handle of bitmap */ PSIZEL psizl; /*pointer to PSIZEL structure for dimensions */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The GetBitmapDimension function retrieves a previously associated width and height from the specified bitmap, in 0.1 mm units. These dimensions can be associated by the SetBitmapDimension function and is not used by the engine. Parameters hbm the bitmap whose width and height are retrieved. psizl to a PSIZEL structure that contains the width and height (in 0.1 mm units) of the bitmap. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine may record: PMERR_BITMAP_IS_SELECTED PMERR_HBITMAP_BUSY PMERR_INV_HBITMAP █ GetBitmapParameters ──────────────────────────────────────────────────────────────────────────── BOOL GetBitmapParameters (hbm, pbmih, hddc, ulFunN) HBM hbm; /*handle of bitmap */ PBITMAPINFOHEADER pbmih; /*pointer to BITMAPINFOHEADER structure */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The GetBitmapParameters function retrieves information about a bitmap's width, height, number of color planes, and number of bits per pel. Parameters hbm the bitmap. pbmih to a BITMAPINFOHEADER structure that receives the bitmap information. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine may record: PMERR_BITMAP_IS_SELECTED PMERR_HBITMAP_BUSY PMERR_INV_HBITMAP █ GetBoundsData ──────────────────────────────────────────────────────────────────────────── BOOL GetBoundsData (hdc, ulType, prcl, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ ULONG ulType; /*boundary-type identifier */ PRECTL prcl; /*pointer to RECTL structure */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The GetBoundsData function retrieves the coordinates of two opposite corners for a bounding rectangle. A bounding rectangle is the smallest rectangle that completely encloses graphics output in either page or device space. Parameters hdc the engine's device context. ulType whether the rectangle coordinates are in page space or device space. Value Meaning ──────────────────────────────────────────────────────────────────────────── GBD_GPI Specifies page coordinates, indicating that the bounding rectangle applies to Gpi functions. GBD_USER Specifies device coordinates, indicating that the bounding rectangle applies to user functions. prcl to a RECTL structure that receives the coordinates of two opposite corners for the bounding rectangle. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the device driver may record: PMERR_COORDINATE_OVERFLOW PMERR_DEV_FUNC_NOT_INSTALLED PMERR_INV_HDC Comments Note that the bounds are inclusive. A NULL boundary is represented by the minimum boundary greater than the maximum boundary. After a call to the ResetBounds function, minimum values will be 0x7FFFFFFF, and the maximum values will be 0x80000000. █ GetClipBox ──────────────────────────────────────────────────────────────────────────── int GetClipBox (hdc, prcl, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ PRECTL prcl; /*pointer to RECTL structure */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The GetClipBox function returns the coordinates for two opposite corners of a special rectangle. This rectangle is the smallest rectangle that completely surrounds the intersection of the visible region, the clip region, the viewing limits, the graphics field, and the clip area. Parameters hdc the engine's device context. prcl to a RECTL structure that receives the coordinates of a special rectangle. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is RGN_NULL, RGN_RECT, or RGN_COMPLEX if the function is successful. The return value is RGN_ERROR if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine or the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine or the device driver calls record: PMERR_COORDINATE_OVERFLOW PMERR_DEV_FUNC_NOT_INSTALLED PMERR_HDC_BUSY PMERR_INV_COORD_SPACE PMERR_INV_HDC PMERR_INV_LENGTH_OR_COUNT PMERR_INV_RECT Comments The return value is the complexity of the Rao region (that is, the intersection of all clipping operations: clip path, viewing limits, graphics field, clip region and visible region). The bounding rectangle is inclusive─that is, points on the boundary of the rectangle are considered inside the rectangle. If the intersection is null, the rectangle returned has the right boundary less than the left, and the top boundary less than the bottom. █ GetClipRects ──────────────────────────────────────────────────────────────────────────── int GetClipRects (hdc, prcl, prgnrect, arcl, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ PRECTL prcl; /*pointer to RECTL structure */ PRGNRECT prgnrect; /*pointer to REGIONRECT structure */ PRECTL arcl; /*pointer to array of RECTL structures */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The GetClipRects function retrieves the coordinates of the rectangle or rectangles that compose the current clipping region and intersect the rectangle specified by the prcl parameter. The current clipping region is the intersection of the visible region, the clip region, the viewing limit, the graphics field, and the clip path. Parameters hdc the engine's device context. prcl to a RECTL structure that defines the area of interest. prgnrect to a REGIONRECT structure that contains fields specifying how this function should enumerate multiple clipping rectangles. arcl to an array of RECTL structures that define the clipping region. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is RGN_NULL, RGN_RECT, or RGN_COMPLEX if the function is successful or RGN_ERROR if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine or the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine or the device driver calls record: PMERR_DEV_FUNC_NOT_INSTALLED PMERR_HDC_BUSY PMERR_INV_COORDINATE PMERR_INV_HDC PMERR_INV_RECT PMERR_INV_REGION_CONTROL █ GetCodePage ──────────────────────────────────────────────────────────────────────────── LONG GetCodePage (hdc, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The GetCodePage function retrieves a value that identifies the current code page. Parameters hdc the engine's device context. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value identifies the code page if the function is successful; otherwise, it is zero. Errors If an error occurs during the execution of this function, the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the device driver may record: PMERR_DEV_FUNC_NOT_INSTALLED Comments The code page returned by this function applies only to the default font. █ GetCurrentPosition ──────────────────────────────────────────────────────────────────────────── BOOL GetCurrentPosition (hdc, pptl, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ PPOINTL pptl; /*pointer to POINTL structure */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The GetCurrentPosition function retrieves the coordinates of the current position. Parameters hdc the engine's device context. pptl to a POINTL structure that receives the coordinates of the current position. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the device driver may record: PMERR_DEV_FUNC_NOT_INSTALLED PMERR_INV_HDC █ GetDCOrigin ──────────────────────────────────────────────────────────────────────────── BOOL GetDCOrigin (hdc, pptl, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ PPOINTL pptl; /*pointer to POINTL structure */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The GetDCOrigin function retrieves the coordinates of the device context origin. (These coordinates are specified in device units.) Parameters hdc the engine's device context. pptl to a POINTL structure that receives the coordinates of the device context origin in device units. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the device driver may record: PMERR_DEV_FUNC_NOT_INSTALLED PMERR_INV_HDC █ GetDefaultArcParameters ──────────────────────────────────────────────────────────────────────────── BOOL GetDefaultArcParameters (hdc, parcp, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ PARCPARAMS parcp; /*pointer to ARCPARAMS structure */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The GetDefaultArcParameters function retrieves the current values of the default arc parameters: p, q, r, and s. Parameters hdc the engine's device context. parcp to an ARCPARAMS structure that contains the arc parameters. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Comments The engine assigns the default arc parameters to a device context when GPI calls the InitializeAttributes function and sets the INAT_CURRENTATTRIBUTES option. The arc parameters define the shape and orientation of an ellipse that the engine uses when it receives subsequent Arc, FullArc, and PartialArc calls. For all of these functions except Arc, the parameters also determine the direction in which the device draws the arc: Parameters Direction ──────────────────────────────────────────────────────────────────────────── p * q > r * s Counterclockwise p * q < r * s Clockwise p * q = r * s Straight line Also, except in the case of Arc, these parameters define the nominal size of the ellipse, although this may be changed by using the multiplier. For the Arc function, the size of the ellipse is determined by the three points specified in the Arc parameters. The arc parameters define a transformation that maps the unit circle to the required ellipse, placed at the origin (0,0): x' = p * x + r * y y' = s * x + q * y If p * r plus q * s is equal to zero, the transformation is termed orthogonal and the line from the origin (0,0) to the point (p,s) is either the radius of the circle or half the major or minor axis of the ellipse. The line from the origin to the point (r,q) is either the radius of the circle or half the other axis of the ellipse. To ensure maximum accuracy, use orthogonal transformations. The standard default values of arc parameters (that define a unit circle) are as follows: p = 1 r = 0 s = 0 q = 1 Arc parameters are transformed in world coordinates. Any other non-square transformations in effect will change the shape of the figure accordingly. █ GetDefaultAttributes ──────────────────────────────────────────────────────────────────────────── BOOL GetDefaultAttributes (hdc, ulType, flAttrs, pBundle, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ ULONG ulType; /*attribute-bundle type */ ULONG flAttrs; /*attribute mask */ PBUNDLE pBundle; /*pointer to attribute bundle */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The GetDefaultAttributes function retrieves the current values for the default attributes identified by the flAttrs parameter. Parameters hdc the engine's device context. ulType the type of attributes to retrieve. This parameter can be one of the following values: Value Meaning ──────────────────────────────────────────────────────────────────────────── PRIM_LINE Line-attribute bundle PRIM_CHAR Character-attribute bundle PRIM_MARKER Marker-attribute bundle PRIM_AREA Area-attribute bundle PRIM_IMAGE Image-attribute bundle flAttrs which attribute values to fill in the bundle. The fields in each bundle are represented by specific bits. The function retrieves information for each bit that is set. pBundle to a copy of an attribute bundle. Only the attribute values that correspond to the flAttrs attribute flags will contain valid information. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Comments The default attributes are those that the graphics engine assigns to the attribute bundles in a device context when GPI calls the InitializeAttributes or SetAttributes function. If GPI calls InitializeAttributes, it must set the option INAT_CURRENTATTRIBUTES. If GPI calls SetAttributes, only those attributes identified by the flDefs flag are set to their default values. █ GetDefaultViewingLimits ──────────────────────────────────────────────────────────────────────────── BOOL GetDefaultViewingLimits (hdc, prcl, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ PRECTL prcl; /*pointer to RECTL structure */ ULONG hddc; /*handle of application's device context */ ULONG ulFunN; /*flags and function number */ The GetDefaultViewingLimits function retrieves the rectangle that specifies the default viewing limits in model-space coordinates. Parameters hdc the engine's device context. prcl to the RECTL structure that receives the viewing limits. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Comments The default viewing limits are those that the graphics engine assigns to a device context when GPI calls the InitializeAttributes function and sets the INAT_CURRENTATTRIBUTES option. █ GetDriverInfo ──────────────────────────────────────────────────────────────────────────── ULONG PASCAL FAR GetDriverInfo (handle, index, hdc) LHANDLE handle; /*handle of device context or bitmap */ ULONG ulIndex; /*index of device context or bitmap */ HDC hdc; /*handle of engine's device context */ The GetDriverInfo function retrieves the handle of a driver's device context that contains the instance data that the engine associated with a device context or a bitmap. The graphics engine validates the handle parameter to ensure that it belongs to the same device driver as the one identified by the hdc parameter and returns an error if not. This provides a mechanism for devices to validate the ownership of a device context or a bitmap. This function is available as a callback function from device drivers to the graphics engine and can be directly dynamically linked to. Parameters handle a device context or a bitmap. ulIndex whether the handle parameter identifies a device context or a bitmap. If this parameter is DI_HDC, handle identifies a device context. If the parameter is DI_HBITMAP, handle identifies a bitmap. hdc the engine's device context. Return Value The return value is the handle to a driver's device context if the function is successful; otherwise, it is -1. Comments The graphics engine exports this function, making it available to Presentation Manager device drivers. However, a device driver must import GetDriverInfo in its module definition file in order to link to the library that contains the call. █ GetGlobalViewingXform ──────────────────────────────────────────────────────────────────────────── BOOL GetGlobalViewingXform (hdc, pxform, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ PXFORM pxform; /*pointer to XFORM structure */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The GetGlobalViewingXform function retrieves values from the current global viewing transformation matrix. Parameters hdc the engine's device context. pxform to an XFORM structure that receives the first two elements from the three rows of a transformation matrix. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine or the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine or the device driver calls record: PMERR_HDC_BUSY PMERR_INV_HDC █ GetGraphicsField ──────────────────────────────────────────────────────────────────────────── BOOL GetGraphicsField (hdc, prcl, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ PRECTL prcl; /*pointer to RECTL structure */ UNSIGNED hddc; /*handle of device driver's device context */ UNSIGNED ulFunN; /*flags and function number */ The GetGraphicsField function retrieves the coordinates of the lower-left and upper-right corners of the graphics field. The graphics field is a clipping area in page space. Parameters hdc the engine's device context. prcl to a RECTL structure that receives the page-space coordinates of the lower-left and upper-right corners of the graphics field. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine or the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine or the device driver calls record: PMERR_HDC_BUSY PMERR_INV_HDC █ GetHandle ──────────────────────────────────────────────────────────────────────────── LONG GetHandle (hdc, ulIndex, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ ULONG ulIndex; /*index for handle */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The GetHandle function retrieves a handle for the specified index. Parameters hdc the engine's device context. ulIndex the index value of the handle in the range 0 to 3. This parameter may specify a handle for a GPI presentation space, an AVIO presentation space, or a metafile. The fourth index value is reserved for future use. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is the specified handle if the function is successful; otherwise, it is GPI_ALTERROR. Errors If an error occurs during the execution of this function, the graphics engine calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine may record: PMERR_HDC_BUSY PMERR_INV_HDC █ GetLineOrigin ──────────────────────────────────────────────────────────────────────────── LONG GetLineOrigin (hdc, pptl, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ PPOINTL pptl; /*pointer to POINTL structure */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The GetLineOrigin function returns the current style state and current position to the device driver. The style state is kept by the device driver. Simulations must be able to query and set the style since some lines/curves are drawn by the driver and some by simulations. The style number is a USHORT value with two parts. The low byte is the position in the style mask, in the range 0 through 255. The high byte is the state of the style error value. Parameters pptl to a POINTL structure that receives the coordinate pair in which the current position is returned. Return Value The return value is GPI_OK if the function is successful or GPI_ERROR if an error occurs. Errors If an error occurs during the execution of this function, the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the device driver may record: PMERR_DEV_FUNC_NOT_INSTALLED PMERR_INV_HDC █ GetModelXform ──────────────────────────────────────────────────────────────────────────── BOOL GetModelXform (hdc, pxform, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ PXFORM pxform; /*pointer to XFORM structure */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The GetModelXform function retrieves values from the current model-transformation matrix. Parameters hdc the engine's device context. pxform to an XFORM structure that contains the first two values from the three rows in a two-dimensional transformation matrix. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine or the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine or the device driver calls record: PMERR_HDC_BUSY PMERR_INV_HDC █ GetPageUnits ──────────────────────────────────────────────────────────────────────────── LONG GetPageUnits (hdc, pulUnits, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ PULONG pulUnits; /*pointer to page dimensions */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The GetPageUnits function retrieves the current page units as well as the presentation-page dimensions. Parameters hdc the engine's device context. pulUnits to a ULONG value that contains the current presentation-page dimensions. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value specifies the page units if the function is successful; otherwise, it is zero. Errors If an error occurs during the execution of this function, the graphics engine or the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine or the device driver calls record: PMERR_HDC_BUSY PMERR_INV_HDC █ GetPageViewport ──────────────────────────────────────────────────────────────────────────── BOOL GetPageViewport (hdc, prcl, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ PRECTL prcl; /*pointer to RECTL structure */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The GetPageViewport function retrieves the coordinates of the lower-left and upper-right corners of the page viewport. Parameters hdc the engine's device context. prcl to a RECTL structure that contains the coordinates of the lower-left and upper-right corners of the page viewport. uhddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine or the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine or the device driver calls record: PMERR_HDC_BUSY PMERR_INV_HDC █ GetPairKerningTable ──────────────────────────────────────────────────────────────────────────── ULONG GetPairKerningTable (hdc, ckp, pkp, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ LONG ckp; /*count of kerning pairs */ PKERNINGPAIRS pkp; /*pointer to KERNINGPAIRS structures */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The GetPairKerningTable function retrieves kerning information for kerning pairs in the current font. Kerning is a process of adding or subtracting space between specific characters in a font. The kerning information identifies each character in the pair and specifies a kerning amount for that pair. The second parameter, ckp, specifies the number of kerning pairs for which the function should retrieve information. Parameters hdc the engine's device context. ckp the number of kerning pairs requested. pkp to KERNINGPAIRS structures which contain information for each kerning pair. Each structure contains a field that specifies the kerning amount as well as two fields that identify the kerned characters. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is the number of kern pairs if the function is successful. Otherwise, it is GPI_ALTERROR. Errors If an error occurs during the execution of this function, the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the device driver may record: PMERR_COORDINATE_OVERFLOW PMERR_DEV_FUNC_NOT_INSTALLED PMERR_EXCEEDS_MAX_SEG_LENGTH PMERR_HDC_BUSY PMERR_INSUFFICIENT_MEMORY PMERR_INV_CODEPAGE PMERR_INV_COORD_SPACE PMERR_INV_HDC PMERR_INV_LENGTH_OR_COUNT PMERR_INV_SETID █ GetPel ──────────────────────────────────────────────────────────────────────────── LONG GetPel (hdc, pptl, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ PPOINTL pptl; /*pointer to POINTL structure */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The GetPel function retrieves the color for a specified pel. (This color may be an RGB value or a color-table index and is dependent on the current color-table mode.) Parameters hdc the engine's device context. pptl to a POINTL structure that contains the current pel coordinates. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is an RGB or color-index value for the pel if the function is successful; otherwise, it is GPI_ALTERROR. Errors If an error occurs during the execution of this function, the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the device driver may record: PMERR_BITMAP_NOT_SELECTED PMERR_COORDINATE_OVERFLOW PMERR_DEV_FUNC_NOT_INSTALLED PMERR_HDC_BUSY PMERR_INV_COORD_SPACE PMERR_INV_COORDINATE PMERR_INV_HDC PMERR_INV_LENGTH_OR_COUNT PMERR_INV_RECT PMERR_PEL_IS_CLIPPED PMERR_PEL_NOT_AVAILABLE Comments If the color table contains indices rather than RGB values and the function fails to find a matching color, it returns the constant CLR_NOINDEX (-254). If the location of the pel is outside of the current clipping areas, the function returns an error. █ GetPickWindow ──────────────────────────────────────────────────────────────────────────── BOOL GetPickWindow (hdc, prcl, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ PRECTL prcl; /*pointer to RECTL structure */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The GetPickWindow function retrieves the coordinates of the pick aperture's lower-left and upper-right corners. Parameters hdc the engine's device context. prcl to a RECTL structure that receives the coordinates (in page units) of the pick aperture's lower-left and upper-right corners. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the device driver may record: PMERR_DEV_FUNC_NOT_INSTALLED PMERR_INV_HDC █ GetProcessControl ──────────────────────────────────────────────────────────────────────────── LONG GetProcessControl (hdc, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The GetProcessControl function retrieves the process-control flags. These flags have the following values: Value Meaning ──────────────────────────────────────────────────────────────────────────── 0x0001 Draw process flag (PCTL_DRAW). 0x0002 Bounds process flag (PCTL_BOUND). 0x0004 Correlate process flag (PCTL_CORRELATE). 0x0008 User bounds process flag (PCTL_USERBOUNDS). 0x0010 Area definition is in progress (PCTL_AREA). 0x0020 Path definition is in progress (PCTL_PATH). All other values are reserved. Parameters hdc the engine's device context. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value specifies the process-control flags if the function is successful; otherwise, it is GPI_ALTERROR. Errors If an error occurs during the execution of this function, the graphics engine calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine may record: PMERR_HDC_BUSY PMERR_INV_HDC █ GetRegionBox ──────────────────────────────────────────────────────────────────────────── int GetRegionBox (hdc, hrgn, prcl, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ HRGN hrgn; /*handle of region */ PRECTL prcl; /*pointer to RECTL structure */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The GetRegionBox function returns the dimensions of the smallest possible rectangle that will fit around a region. If the region is empty, the returned rectangle's right boundary is less than its left, and its top boundary less than its top. Parameters hrgn the region. prcl to a RECTL structure that receives the dimensions of the rectangle in device coordinates. Return Value The return value, if the function is successful, is RGN_NULL if the region is empty, RGN_RECT if the region is a single rectangle, or RGN_COMPLEX if the region consists of multiple rectangles. The return value is RGN_ERROR if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine or the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine or the device driver calls record: PMERR_HRGN_BUSY PMERR_INV_HRGN PMERR_REGION_IS_CLIP_REGION █ GetRegionRects ──────────────────────────────────────────────────────────────────────────── BOOL GetRegionRects (hdc, hrgn, prclBounds, prgnrc, prcl, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ HRGN hrgn; /*handle of region */ PRECTL prclBounds; /*pointer to RECTL structure */ PRGNRECT prgnrc; /*pointer to RGNRECT structure */ PRECTL prcl; /*pointer to RECTL structure */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The GetRegionRects function returns a list of (x,y) coordinates that specify the region associated with the given region handle. A region selected as a clipping region can also be specified. Parameters hdc the engine's device context. hrgn the region for which region data is returned. prclBounds to a RECTL structure that contains a bounding rectangle. The first (x,y) pair defines the minimum coordinates of the rectangle, and the second (x,y) pair defines the maximum coordinates of the rectangle in device coordinates. Only rectangles intersecting this bounding rectangle are retrieved. If this pointer is NULL, all rectangles in the region are enumerated. If prclBounds is not NULL, each of the rectangles returned in the structure pointed to by prcl will be the intersection of the bounding rectangle with a rectangle in the region. prgnrc to a RGNRECT structure. The structure has the following form: typedef struct _RGNRECT { /* rgnrc */ USHORT ircStart; USHORT crc; USHORT crcReturned; USHORT usDirection; } RGNRECT; prcl to a RECTL structure that defines a rectangular region, which is an array of (x,y) pairs in device coordinates. Odd (x,y) pairs specify the minimum coordinates of a rectangle, and even (x,y) pairs specify the maximum coordinates. The format is identical to that for the CreateRectRegion function. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine or the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine or the device driver calls record: PMERR_HRGN_BUSY PMERR_INV_COORDINATE PMERR_INV_HRGN PMERR_INV_RECT PMERR_INV_REGION_CONTROL PMERR_REGION_IS_CLIP_REGION █ GetStyleRatio ──────────────────────────────────────────────────────────────────────────── BOOL GetStyleRatio (hdc, psr, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ PBYTE psr; /*pointer to buffer for style ratio */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The GetStyleRatio function retrieves the style ratio for the device driver. This is a required device driver function. Parameters hdc the engine's device context. psr to the two-byte buffer that receives the style ratio. The low byte specifies the x-component; the high byte specifies the y-component. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the device driver may record: PMERR_DEV_FUNC_NOT_INSTALLED PMERR_INV_HDC █ GetViewingLimits ──────────────────────────────────────────────────────────────────────────── BOOL GetViewingLimits (hdc, prcl, hddc, ulFunN) HDC hdc; /*handle of application's device context */ PRECTL prcl; /*pointer to RECTL structure */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The GetViewingLimits function retrieves the rectangle that specifies the boundaries of the viewing window in model space coordinates. Parameters hdc the engine's device context. prcl to the RECTL structure that receives the viewing limits. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine or the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine or the device driver calls record: PMERR_HDC_BUSY PMERR_INV_HDC █ GetWindowViewportXform ──────────────────────────────────────────────────────────────────────────── BOOL GetWindowViewportXform (hdc, pxform, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ PXFORM pxform; /*pointer to XFORM structure */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The GetWindowViewportXform function retrieves an array of values that define the current window-to-viewport transformation matrix. Parameters hdc the engine's device context. pxform to an XFORM structure that contains the first two rows from the three rows of a transformation matrix. The structure has the following form: typedef struct _XFORM { /* xform */ FIXED fxM11; FIXED fxM12; FIXED fxM21; FIXED fxM22; LONG lM41; LONG lM42; } XFORM; hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine or the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine or the device driver calls record: PMERR_HDC_BUSY PMERR_INV_HDC █ GreEntry ──────────────────────────────────────────────────────────────────────────── GreEntry (param1, ..., paramN, hddc, ulFunN) TYPE1 param1; /*type and name depend on function */ TYPEN paramN; /*type and name depend on function */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The GreEntry function provides Presentation Manager device drivers with access to the graphics engine. Parameters param1...paramN parameters correspond to the parameters of the graphics-engine function that the device driver is calling. The types (TYPE) correspond as well. hddc a device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value depends on the graphics-engine function that the device driver is calling. Comments The GreEntry function validates the device context identified by the hddc parameter before passing a call to the graphics engine. This validation includes verifying that hddc is a valid device context handle and clearing any bits in the handle that GPI may have set. █ ImageData ──────────────────────────────────────────────────────────────────────────── int ImageData (hdc, pbImage, cBits, lRow, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ PBYTE pbImage; /*pointer to buffer for image data */ LONG cBits; /*count of bits in image data */ LONG lRow; /*row for image data */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The ImageData function draws a row of image data. The function uses each bit in the image data pointed to pbImage to determine whether to set a corresponding pel. The first pel in the image is specified by the first bit in the first byte of data. The lRow parameter specifies the vertical offset in pels from the current position to start the image. The function is typically called for each row of the image, with the first call specifying top row in the image and subsequent calls specifying adjacent rows. The function does not change the current position. Parameters hdc the engine's device context. pbImage to a buffer that contains the image data. Each bit represents one pel. The maximum image width is 2040 pels. cBits the number of pels to draw─that is, the number of bits in the image data to use. If the count is not a multiple of 8, any remaining bits in the image data are not used. The function cannot "assume" that unused bits are zero. lRow the row number of the image data. Row 0 is the same row as the current position, row 1 is the next one down the screen, and so on. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is GPI_OK or GPI_HITS if the function is successful (it is GPI_HITS if the detectable attribute is set for the presentation space and a correlation hit occurs). The return value is GPI_ERROR if an error occurs. Errors If an error occurs during the execution of this function, the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the device driver may record: PMERR_BITMAP_NOT_SELECTED PMERR_COORDINATE_OVERFLOW PMERR_DEV_FUNC_NOT_INSTALLED PMERR_HDC_BUSY PMERR_INV_COLOR_DATA PMERR_INV_COLOR_INDEX PMERR_INV_COORD_SPACE PMERR_INV_COORDINATE PMERR_INV_HDC PMERR_INV_IMAGE_DATA_LENGTH PMERR_INV_IN_AREA PMERR_INV_IN_PATH PMERR_INV_LENGTH_OR_COUNT PMERR_INV_PICK_APERTURE_POSN PMERR_INV_RECT PMERR_INV_REGION_CONTROL PMERR_INV_SCAN_START █ Initialize ──────────────────────────────────────────────────────────────────────────── void Initialize () The Initialize function initializes the engine for a given device driver process. A process must call Initialize before making any other engine call. This function has no parameters and returns no value. Comments For all other engine calls, the device driver process calls a single entry point to the graphics engine. The last parameter to this entry point indicates the required function to carry out. █ InitializeAttributes ──────────────────────────────────────────────────────────────────────────── BOOL InitializeAttributes (hdc, flCmd, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ ULONG flCmd; /*command flags */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The InitializeAttributes function either initializes the default attributes to their original values or resets the current attributes to their default values. Parameters hdc Identifies the engine's device context. flCmd Specifies whether the default attributes should be set to their original values, or whether the current attributes should be set to their default values. This field can be set to one or both of the following values: Flag Meaning ──────────────────────────────────────────────────────────────────────────── INAT_DEFAULTATTRIBUTES Set all default attributes to their original values. INAT_CURRENTATTRIBUTES Set all current attributes to their default values. hddc Identifies the device driver's device context. ulFunN Specifies the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Comments If both of the flCmd options are set, the graphics engine resets the default attributes before resetting the current attributes. The default and current attributes include the primitive bundles, the arc parameters, and the viewing limits. █ IntersectClipRectangle ──────────────────────────────────────────────────────────────────────────── int IntersectClipRectangle (hdc, prcl, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ PRECTL prcl; /*pointer to RECTL structure */ ULONG hddc; /*device driver's device context */ ULONG ulFunN; /*flags and function number */ The IntersectClipRectangle function sets the new clip region to the intersection of the current clip region and the specified rectangle. The function creates a clip region if none existed before. All of the boundaries of the rectangle are considered to be part of the interior and are not clipped. Parameters hdc Identifies the engine's device context. prcl Points to the RECTL structure that receives the viewing limits. The structure has the following form: typedef struct _RECTL { /* rcl */ LONG xLeft; LONG yBottom; LONG xRight; LONG yTop; } RECTL; hddc Identifies the device driver's device context. ulFunN Specifies the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is RGN_NULL, RGN_RECT, or RGN_COMPLEX if the function is successful. The return value is RGN_ERROR if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine or the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine or the device driver calls record: PMERR_COORDINATE_OVERFLOW PMERR_DEV_FUNC_NOT_INSTALLED PMERR_HDC_BUSY PMERR_INSUFFICIENT_MEMORY PMERR_INV_COORD_SPACE PMERR_INV_COORDINATE PMERR_INV_HDC PMERR_INV_HRGN PMERR_INV_IN_AREA PMERR_INV_IN_PATH PMERR_INV_LENGTH_OR_COUNT PMERR_INV_RECT PMERR_INV_REGION_CONTROL █ InvalidateVisRegion ──────────────────────────────────────────────────────────────────────────── BOOL InvalidateVisRegion (hdc, civr, pivr, hddc, ulFunN) HDC hdc; /*handle of application's device context */ LONG civr; /*count of DC_BLOCK structures */ PDC_BLOCK pivr; /*pointer to array of DC_BLOCK structures */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The InvalidateVisRegion function invalidates the visible regions in the device contexts identified by the DC_BLOCK structures in the specified array. Parameters hdc Identifies the engine's device context. civr Specifies the number of DC_BLOCK structures that appear in the array pointed to by the pivr parameter. pivr Points to an array of DC_BLOCK structures. hddc Identifies the device driver's device context. ulFunN Specifies the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if this function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine may record: PMERR_DEV_FUNC_NOT_INSTALLED █ LoadFont ──────────────────────────────────────────────────────────────────────────── BOOL LoadFont (pszFilename, hddc, ulFunN) PSZ pszFilename; /*pointer to name of font file */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The LoadFont function loads fonts from the specified resource file. All fonts in the file are "private" and available only to the process that issued this function. Parameters pszFilename Points to a null-terminated string. This string must specify a complete MS OS/2 path and font filename. All MS OS/2 font filenames use the .fon extension. hddc Identifies the device driver's device context. ulFunN Specifies the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is GPI_OK if the function is successful or GPI_ERROR if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine may record: PMERR_BASE_ERROR PMERR_INSUFFICIENT_MEMORY PMERR_INV_FONT_FILE_DATA █ LoadPublicFont ──────────────────────────────────────────────────────────────────────────── BOOL LoadPublicFont (pszFilename, hddc, ulFunN) PSZ pszFilename; /*pointer to name of font file */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The LoadPublicFont function loads fonts from the specified resource file. All fonts in the file are "public"─that is, available to all applications. If LoadPublicFont is called for a font file that has already been loaded by another process, the function should be successful. Parameters pszFilename Points to a null-terminated string. This string must contain a complete path and font filename. (Font filenames should use the .fon extension.) hddc Identifies the device driver's device context. ulFunN Specifies the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is GPI_OK if the function is successful or GPI_ERROR if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine may record: PMERR_BASE_ERROR PMERR_INSUFFICIENT_MEMORY PMERR_INV_FONT_FILE_DATA Comments The UnLoadPublicFont function does not remove a font if another process has local identifiers linked to it. The font is removed when the last process releases it, but before the font can be removed, it is necessary to set the character set to one that does not reference the font and to then delete any local identifiers that reference the font. █ LockDevice ──────────────────────────────────────────────────────────────────────────── BOOL LockDevice (hdc, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The LockDevice function locks the visible region for the device. It allows all current and pending drawing to complete and blocks any further draw requests by other threads. The function permits only the thread that acquired the lock to continue screen I/O. All screen I/O operations by other threads will be blocked until the UnlockDevice function is called. Parameters hdc Identifies the engine's device context. hddc Identifies the device driver's device context. ulFunN Specifies the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the device driver may record: PMERR_DEV_FUNC_NOT_INSTALLED PMERR_INV_HDC Comments The LockDevice and UnlockDevice functions are used mainly in the critical sections of visible-region calculations. To prevent deadlock, it is guaranteed that no Death or Resurrection function will be called by the window manager while the visible region is locked. █ ModifyPath ──────────────────────────────────────────────────────────────────────────── BOOL ModifyPath (hdc, phid, ulMode, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ PHID phid; /*path identifier */ ULONG ulMode; /*modification options */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The ModifyPath function modifies the specified path. After modifying a path, the path can be used only with the FillPath and SelectClipPath functions and then only if the FPATH_WINDING mode is specified. Parameters hdc Identifies the engine's device context. phid Specifies the identifier of the path to modify. This parameter must be greater than zero. For this release of Presentation Manager, it must be set to 1. ulMode Specifies how to modify the path. This parameter can be the following value─the only mode supported by this release of Presentation Manager: Value Meaning ──────────────────────────────────────────────────────────────────────────── MPATH_STROKE Replaces the path with a path enclosing the shape produced by stroking the path using the current geometric wide-line attribute. Any open figures within the path are not closed. The bracket will include the effects of line joins and line ends, according to the current values of these attributes. hddc Identifies the device driver's device context. ulFunN Specifies the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine or the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine or the device driver calls record: PMERR_BASE_ERROR PMERR_BITMAP_NOT_SELECTED PMERR_COORDINATE_OVERFLOW PMERR_DEV_FUNC_NOT_INSTALLED PMERR_HDC_BUSY PMERR_HRGN_BUSY PMERR_INSUFFICIENT_MEMORY PMERR_INV_COLOR_DATA PMERR_INV_COLOR_INDEX PMERR_INV_COORD_SPACE PMERR_INV_COORDINATE PMERR_INV_FILL_PATH_OPTIONS PMERR_INV_HDC PMERR_INV_HRGN PMERR_INV_IN_AREA PMERR_INV_IN_PATH PMERR_INV_LENGTH_OR_COUNT PMERR_INV_MATRIX_ELEMENT PMERR_INV_MODIFY_PATH_MODE PMERR_INV_PATH_ID PMERR_INV_PATTERN_REF_PT_ATTR PMERR_INV_PICK_APERTURE_POSN PMERR_INV_RECT PMERR_INV_REGION_CONTROL PMERR_INV_TRANSFORM_TYPE PMERR_PATH_LIMIT_EXCEEDED PMERR_PATH_UNKNOWN PMERR_REGION_IS_CLIP_REGION Comments A line may be joined to, for example, an arc. The common point is handled according to the line-join parameter, rather than applying a line end at each end. If a figure has been closed by using the GpiCloseFigure function, the joining rules are followed rather than the ending rules, at the starting/ending points. The path bracket keeps track of "crossings," so that a stroked figure─for example, the letter X─does not have a hole in its middle if drawn in XOR mode. A single path cannot contain more than 64K of data. █ MultiplyXforms ──────────────────────────────────────────────────────────────────────────── BOOL MultiplyXforms (hdc, pxform1, pxform2, ulMode, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ PXFORM pxform1; /*pointer to first XFORM structure */ PXFORM pxform2; /*pointer to second XFORM structure */ ULONG ulMode; /*multiplication options */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The MultiplyXforms function multiplies the transformation matrix pointed to by the pxform1 parameter with the matrix made specified by the ulMode parameter and stores the result in pxform2. Parameters hdc Identifies the engine's device context. pxform1 Points to the XFORM structure that contains the transformation to multiply. The structure has the following form: typedef struct _XFORM { /* xform */ FIXED fxM11; FIXED fxM12; FIXED fxM21; FIXED fxM22; LONG lM41; LONG lM42; } XFORM; pxform2 Points to the XFORM structure that contains a transformation to multiply and that receives the result of the multiplication. The structure has the same form as the structure pointed to by pxform1. ulMode Specifies how the supplied array should be used to set the matrix. It can be one of the following values: Value Meaning ──────────────────────────────────────────────────────────────────────────── 0 Set pxform2 to the identity matrix (SX_UNITY). 1 Multiply pxform1 by pxform2 (SX_CAT_AFTER). 2 Multiply pxform2 by pxform1 (SX_CAT_BEFORE). 3 Replace pxform2 with pxform1 (SX_OVERWRITE). hddc Identifies the device driver's device context. ulFunN Specifies the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine or the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine or the device driver calls record: PMERR_INV_MATRIX_ELEMENT PMERR_INV_TRANSFORM_TYPE Comments If the function is used to perform a series of matrix multiplications on the same matrix, there will be a loss of accuracy, since higher extra precision is not retained across calls. █ NotifyClipChange ──────────────────────────────────────────────────────────────────────────── ULONG NotifyClipChange (hdc, pRect, Complexity, ClipPathId, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ PRECTL prcl; /*pointer to RECTL structure */ LONG Complexity; /*clip area complexity */ ULONG ClipPathId; /*clip path identifier */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The NotifyClipChange function is called whenever the clip region that intersects with the visible region is changed. This function is not required and can be handled completely with a far return (retf) call if the device driver is not interested in each clip-region change. The coordinates of the rectangle are screen coordinates. The device driver must redispatch the NotifyClipChange call back to the engine after processing it. This enables the engine to make certain optimizations relating to clipping. Parameters hdc Identifies the engine's device context. prcl Points to a RECTL structure that specifies the rectangle that bounds the new region. If the region is a single rectangle, this will be the same rectangle. The structure has the following form: typedef struct _RECTL { /* rcl */ LONG xLeft; LONG yBottom; LONG xRight; LONG yTop; } RECTL; Complexity Specifies the number of rectangles in the new clip region (that is, the number of rectangles returned by the GetClipRects function). ClipPathId Specifies the current clip path identifier. If this parameter is zero, no clip path is defined. hddc Identifies the device driver's device context. ulFunN Specifies the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the device driver may record: PMERR_DEV_FUNC_NOT_INSTALLED PMERR_HDC_BUSY PMERR_INV_COORDINATE PMERR_INV_HDC PMERR_INV_RECT PMERR_INV_REGION_CONTROL █ NotifyTransformChange ──────────────────────────────────────────────────────────────────────────── BOOL NotifyTransformChange (hdc, flCmd, pntd, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ ULONG flCmd; /*options */ PNOTIFYTRANSFORMDATA pntd; /*pointer to NOTIFYTRANSFORMDATA structure */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The NotifyTransformChange function is called whenever the transformation from world to device coordinates changes. This call provides enough information to the device so that the device can optimize the transformation operation, or possibly even do all point transformations itself. The driver must redispatch the NotifyTransformChange call back to the engine after processing it. This enables the engine to make certain optimizations relating to transforms. Parameters hdc Identifies the engine's device context. flCmd Specifies information about the complexity of the matrix made of the components of the composite transformation from world to device coordinates. This parameter also specifies if there is a translation. The parameter can be a combination the following values: Value Meaning ──────────────────────────────────────────────────────────────────────────── MATRIX_SIMPLE Two entries are zero (0x00000001). MATRIX_UNITS All entries are +1 or -1 (0x00000002). MATRIX_XY_EXCHANGE Zeros are on the diagonal (0x00000004). MATRIX_X_NEGATE X is hit by negative (0x00000008). MATRIX_Y_NEGATE Y is hit by negative (0x00000010). MATRIX_TRANSLATION Nonzero translation (0x00000020). pntd Points to the NOTIFYTRANSFORMDATA structure. The structure has the following form: typedef struct _NOTIFYTRANSFORMDATA { /* ntd */ USHORT usType; XFORM xform; } NOTIFYTRANSFORMDATA; Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the device driver may record: PMERR_BASE_ERROR PMERR_COORDINATE_OVERFLOW PMERR_DEV_FUNC_NOT_INSTALLED PMERR_HDC_BUSY PMERR_INV_COORD_SPACE PMERR_INV_HDC PMERR_INV_IN_AREA PMERR_INV_IN_PATH PMERR_INV_LENGTH_OR_COUNT PMERR_INV_PATTERN_REF_PT_ATTR PMERR_INV_PICK_APERTURE_POSN PMERR_PATH_LIMIT_EXCEEDED Example If the NOTIFYTRANSFORMDATA structure contains {1.0,0.0,0.0,1.0,0,0}, the flCmd parameter is 0x00000003. If the NOTIFYTRANSFORMDATA structure contains {1.0,0.0,0.0,1.0,5,10}, the flCmd parameter is 0x00000023. If the NOTIFYTRANSFORMDATA structure contains {0.0,-1.0,1.0,0.0,17,-5}, the flCmd parameter is 0x00000037. █ OffsetClipRegion ──────────────────────────────────────────────────────────────────────────── int OffsetClipRegion (hdc, pptl, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ PPOINTL pptl; /*pointer to POINTL structure */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The OffsetClipRegion function moves the clipping region by the specified offsets. Parameters hdc Identifies the engine's device context. pptl Points to a POINTL structure that contains the x- and y-offset the region is to be moved in world coordinates. hddc Identifies the device driver's device context. ulFunN Specifies the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is RGN_NULL, RGN_RECT, or RGN_COMPLEX if the function is successful. The return value is RGN_ERROR if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine or the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine or the device driver calls record: PMERR_COORDINATE_OVERFLOW PMERR_DEV_FUNC_NOT_INSTALLED PMERR_HDC_BUSY PMERR_INSUFFICIENT_MEMORY PMERR_INV_COORD_OFFSET PMERR_INV_COORD_SPACE PMERR_INV_COORDINATE PMERR_INV_HDC PMERR_INV_HRGN PMERR_INV_IN_AREA PMERR_INV_IN_PATH PMERR_INV_LENGTH_OR_COUNT PMERR_INV_RECT PMERR_INV_REGION_CONTROL █ OffsetRegion ──────────────────────────────────────────────────────────────────────────── BOOL OffsetRegion (hdc, hrgn, pptl, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ HRGN hrgn; /*handle of region to offset */ PPOINTL pptl; /*pointer to POINTL structure */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The OffsetRegion function moves the given region by the specified offsets unless the region is being used as a clipping region. Parameters hdc Identifies the engine's device context. hrgn Identifies the region to move. pptl Points to the POINTL structure that contains the x- and y-offset the region is to be moved in device coordinates. hddc Identifies the device driver's device context. ulFunN Specifies the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine or the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine or the device driver calls record: PMERR_COORDINATE_OVERFLOW PMERR_HRGN_BUSY PMERR_INV_COORDINATE PMERR_INV_HRGN PMERR_REGION_IS_CLIP_REGION █ OpenDC ──────────────────────────────────────────────────────────────────────────── HDC OpenDC (hdc, ulType, pszToken, lCount, pdop, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ ULONG ulType; /*type of device context */ PSZ pszToken; /*pointer to string for token */ LONG ulCount; /*count of fields in structure */ PDEVOPENDATA pdop; /*pointer to DEVOPENSTRUC structure */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The OpenDC function creates an output device context of a specified type. The data passed depends upon the type of device context being created. It provides information such as the driver name and may also provide data with which the device context is to be initialized. The device context inherits the process code pages of the process that created them at the time they were created. Subsequent calls to the DosSetCp function will not change the code page of a previously created device context. Default (shield layer) Vio and Kbd code pages will always be the last code pages set by any process of the application. Calls to DosSetCp by any application process will change the default Vio and Kbd code pages. Parameters hdc Identifies the engine's device context. ulType Specifies the type of device context to create. This parameter can be one of the following: Value Meaning ──────────────────────────────────────────────────────────────────────────── OD_QUEUED Specifies a device, such as a printer or plotter, for which output is queued by the spooler. OD_DIRECT Specifies a device, such as a printer or plotter. Output is not queued by the spooler. OD_INFO Specifies a device, like OD_DIRECT, but one that is used to retrieve information (for example, font metrics). Drawing can be performed to a presentation space associated with such a device context, but no output medium is updated. OD_MEMORY Specifies a device context that is used to contain a bitmap. pszToken Points to a string that identifies device information, held in the os2.ini file. This information is the same as that which may be pointed to by pdop; any information obtained in this way overrides whatever is obtained by using pszToken. If the token is specified as "*", no device information is taken from os2.ini. lCount Specifies the number of fields supplied in the DEVOPENSTRUC structure. This number may be shorter than the full list if omitted items are irrelevant or supplied from pszToken. pdop Points to a data area that describes the output device. This area can be either an array of pointers or a DEVOPENSTRUC structure. The DEVOPENSTRUC structure has the following form: typedef struct _DEVOPENSTRUC { PSZ pszLogAddress; PSZ pszDriverName; PDRIVDATA pdriv; PSZ pszDataType; PSZ pszComment; PSZ pszQueueProcName; PSZ pszQueueProcParams; PSZ pszSpoolerParams; PSZ pszNetworkParams; } DEVOPENSTRUC; hddc Identifies the device driver's device context. ulFunN Specifies the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is a device-context handle if the function is successful; otherwise, it is zero. Errors If an error occurs during the execution of this function, the graphics engine calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine may record: PMERR_BASE_ERROR PMERR_BITMAP_IS_SELECTED PMERR_COORDINATE_OVERFLOW PMERR_DEV_FUNC_NOT_INSTALLED PMERR_EXCEEDS_MAX_SEG_LENGTH PMERR_HBITMAP_BUSY PMERR_HDC_BUSY PMERR_HUGE_FONTS_NOT_SUPPORTED PMERR_INSUFFICIENT_MEMORY PMERR_INV_BACKGROUND_COL_ATTR PMERR_INV_BACKGROUND_MIX_ATTR PMERR_INV_BITMAP_DIMENSION PMERR_INV_CHAR_DIRECTION_ATTR PMERR_INV_CHAR_MODE_ATTR PMERR_INV_CODEPAGE PMERR_INV_COLOR_ATTR PMERR_INV_COORD_SPACE PMERR_INV_COORDINATE PMERR_INV_DC_DATA PMERR_INV_DC_TYPE PMERR_INV_DRIVER_NAME PMERR_INV_HBITMAP PMERR_INV_HDC PMERR_INV_HRGN PMERR_INV_ID PMERR_INV_IN_AREA PMERR_INV_IN_PATH PMERR_INV_INFO_TABLE PMERR_INV_LENGTH_OR_COUNT PMERR_INV_LINE_TYPE_ATTR PMERR_INV_MIX_ATTR PMERR_INV_PATTERN_REF_PT_ATTR PMERR_INV_PATTERN_SET_ATTR PMERR_INV_PATTERN_SET_FONT PMERR_INV_RECT PMERR_INV_REGION_CONTROL PMERR_INV_SCAN_START █ OpenJournalFile ──────────────────────────────────────────────────────────────────────────── ULONG OpenJournalFile (hdc, pszFileName, lOption, cbBufSize, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ PSZ pszFileName; /*pointer to journal file name */ ULONG lOption; /*options */ LONG cbBufSize; /*size of buffer */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The OpenJournalFile function opens for play a journal file that has been created by the CreateJournalFile function and written to by the AccumulateJournalFile function. Parameters hdc Identifies the engine's device context. pszFileName Points to a null-terminated string that specifies the name of the journal file to open, or, it points to a buffer in memory. lOption Specifies the options for opening the file. This parameter can be one of the following constants: Value Meaning ──────────────────────────────────────────────────────────────────────────── JNL_PERM_FILE Open a disk file with the given name. The file must have been created using the JNL_PERM_FILE option of the CreateJournalFile function. JNL_USERRAM_FILE Open a shared memory file at which pszFileName points. This file must be filled with complete journal records. cbBufSize Specifies the size in bytes of the buffer. hddc Identifies the device driver's device context. ulFunN Specifies the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is the journal-file handle if it is successful; otherwise, it is zero. Errors If an error occurs during the execution of this function, the graphics engine calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine may record: PMERR_BASE_ERROR PMERR_INSUFFICIENT_MEMORY PMERR_INV_IN_AREA PMERR_INV_IN_PATH PMERR_INV_JOURNAL_OPTION PMERR_RAM_JNL_FILE_TOO_SMALL █ OS2_PM_DRV_DEVICENAMES ──────────────────────────────────────────────────────────────────────────── LONG OS2_PM_DRV_DEVICENAMES (pszDriverName, pcMaxNames, achDevName, achDevDescriptions, pcMaxDataType, achDataType, hddc, ulFunN) .V "PSZ " "pszDriverName;" "pointer to string for device name PLONG pcMaxNames; /*maximum number of device drivers */ PSTR32 achDevName; /*pointer to array of device names */ PSTR64 achDevDescriptions; /*pointer to array of device descriptions */ PLONG pcMaxDataType; /*pointer to maximum number of data types */ PSTR16 achDataType; /*pointer to array of data types */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The OS2_PM_DRV_DEVICENAMES function retrieves the names and descriptions of devices and data types that the specified device driver supports. Parameters pszDriverName Points to the null-terminated string that contains the full pathname for the device driver. pcMaxNames Points to a variable containing the maximum number of device names and descriptions that this function should retrieve. If this parameter is zero, the function should retrieve the number of device names that this driver supports. (This means that the function will not update the achDevName and achDevDescriptions parameters.) If this parameter is nonzero, the function should update achDevName and achDevDescriptions with the appropriate names and descriptions of supported devices. achDevName Points to an array of null-terminated strings, each element of which identifies a particular device (for example, model number). Valid names are defined by device drivers. "IBM4201" is an example of a device name. achDevDescriptions Points to an array of null-terminated strings, each element of which is a description of a particular device (for example, model name). Valid names are defined by device drivers. "IBM 4201 Proprinter" is an example of a device description. pcMaxDataType Points to a variable containing the maximum number of data types that can be retrieved. If this parameter is zero, the function should retrieve the number of data types that this driver supports. (This means that the function will not update the achDataType parameter.) If this parameter is nonzero, the function should update achDataType with valid data types for this driver. achDataType Points to an array of null-terminated strings, each element of which identifies a data type. Valid data types are defined by device drivers. "PM_Q_STD" is an example of a data type. hddc Identifies the device driver's device context. This argument is ignored by this function. ulFunN Specifies the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is 1 if the function is successful or zero if an error occurs. Comments A device driver must export this function in its module definition file. This function corresponds to the API function DevQueryDeviceNames. █ OS2_PM_DRV_DEVMODE ──────────────────────────────────────────────────────────────────────────── LONG OS2_PM_DRV_DEVMODE (pbDriverData, pszDriverName, achDeviceName, pszLogAddr, ulOptions) PDRIVDATA pbDriverData; /*pointer to buffer for data */ PSZ pszDriverName; /*pointer to string for driver name */ PSZ achDeviceName; /*pointer to device name */ PSZ pszPrinterName; /*pointer to string for name of output device */ ULONG ulOptions; /*options flag */ The OS2_PM_DRV_DEVMODE function serves four purposes, depending on the value specified by pbDriverData and ulOptions. The function will do one of the following: retrieve the size of the driver data buffer, display a dialog box that allows a user to change job properties, display two dialog boxes (one of which allows the user to change job properties and the other of which allows the user to change printer properties), or return the current job properties. Parameters pbDriverData Points to a buffer that receives data defined by the driver. If this parameter is NULL, the function should return the required size of the buffer in bytes. pszDriverName Points to the null-terminated string that contains the name of the device driver. achDeviceName Points to the null-terminated string that identifies the particular device (for example, its model number). This string must not exceed 32 bytes. Valid names are defined by device drivers. pszPrinterName Points to the null-terminated string that contains the device name. ulOptions Specifies whether the function should display a dialog box that allows the user to change job properties, display two dialog boxes that allow the user to change job and printer properties, or simply return the current job properties. This parameter can be one of the following values: Value Meaning ──────────────────────────────────────────────────────────────────────────── DPDMF_POSTJOBPROP Display a dialog box that allows the user to change job properties. The default values for this dialog box are taken from the PM_SPOOLER_DD section of the os2.ini file if the pszLogAddr parameter specifies a logical address. If pszLogAddr is NULL, the default values are taken from the pbDriverData parameter. DPDMF_CHANGEPROP Display two dialog boxes. The first will allow the user to change job properties; the second will allow the user to change printer properties. The default values for this dialog box are taken from the PM_SPOOLER_DD section of the os2.ini file. The function returns the new values in the pbDriverData parameter. The pszLogAddr parameter cannot be NULL when this option is selected. DPDMF_QUERYJOBPROP Return the current job properties. Return Value If pbDriverData is NULL and the function is successful, it returns the number bytes required by the buffer at which pbDriverData points. If pbDriverData points to a buffer and the function is successful, it returns DEV_OK. If the function fails, the return value is DEV_ERROR. Comments A device driver must export this function in its module definition file. Job properties are characteristics of a print job such as the text quality (draft, near letter, etc.), paper size, and font typeface. Printer properties are settings on a printer, such as the paper-bin number, printer-memory size, and font-cartridge type. █ OS2_PM_DRV_ENABLE ──────────────────────────────────────────────────────────────────────────── LONG OS2_PM_DRV_ENABLE (ulSubfunction, param1, param2) ULONG ulSubfunction; /*subfunction name */ ULONG param1; /*parameter 1 */ ULONG param2; /*parameter 2 */ The OS2_PM_DRV_ENABLE function is called to carry out specific tasks related to the device driver, such as filling logical and physical device blocks, enabling device contexts, and installing simulations. Parameters ulSubfunction Specifies the subfunction to carry out. It can be one of the following: Subfunction Code ──────────────────────────────────────────────────────────────────────────── FILL_LOGICAL_DEVICE_BLOCK 1 FILL_PHYS_DEVICE_BLOCK 2 DISABLE_PHYS_DEVICE_BLOCK 4 ENABLE_DDC 5 DISABLE_DDC 6 SAVE_DDC_STATE 7 RESTORE_DDC_STATE 8 RESET_DDC_STATE 9 COMPLETE_OPEN_DDC 10 BEGIN_CLOSE_DDC 11 INSTALL_SIMULATION 12 Subfunction number 3 is reserved. param1 32 bits of information to be used for the requested subfunction. param2 32 bits of information to be used for the requested subfunction. Return Value The return value depends on the subfunction. Comments A device driver must export this function in its module definition file. The following list describes each subfunction: Function name Description ──────────────────────────────────────────────────────────────────────────── FILL_LOGICAL_DEVICE_BLOCK Fills a special array called a driver dispatch table with addresses of the device driver's graphic functions. FILL_PHYS_DEVICE_BLOCK Fills a data structure with device information, such as the driver name, output type, horizontal and vertical resolution, color planes, foreground and background mix modes, default raster font, and the default vector font. DISABLE_PHYS_DEVICE_BLOCK Disables a device and deallocates the memory that the device driver used. ENABLE_DDC Reserves memory for, initializes, and associates a device's instance data with an engine device context. DISABLE_DDC Removes the device's instance data that was associated with an engine device context at the time of the call to the ENABLE_DDC subfunction. SAVE_DDC_STATE Informs the device driver that it should save its device-context information on a special stack. RESTORE_DDC_STATE Informs the device driver that it should restore a device context by using information on the special stack. RESET_DDC_STATE Informs the device driver that it should reset the device context to its initial state. COMPLETE_OPEN_DDC Informs the device driver that the creation of a device context is complete. Upon receiving this call, the driver can perform operations that require a complete driver device context (such as creating a journal file). BEGIN_CLOSE_DDC Informs the device driver that a device context is about to close. Upon receiving this call, the driver should perform any operations that require a complete device context. INSTALL_SIMULATION Informs an installable simulation that it should load the device driver's dispatch table with pointers to its functions and perform any additional necessary initialization. The OS2_PM_DRV_ENABLE function corresponds to the API function DevOpenDC or DevCloseDC. This means that the system calls OS2_PM_DRV_ENABLE each time a Presentation Manager application calls one of these two API functions. █ OS2_PM_DRV_ENABLE (1) ──────────────────────────────────────────────────────────────────────────── ULONG OS2_PM_DRV_ENABLE (FILL_LOGICAL_DEVICE_BLOCK, pKling1, pKling2) PKLING1 pKling1; /*pointer to structure */ PKLING2 pKling2; /*pointer to structure */ FILL_LOGICAL_DEVICE_BLOCK is a subfunction of OS2_PM_DRV_ENABLE. This subfunction initializes a device driver's logical device block, which is a data structure that contains device and device driver information. FILL_LOGICAL_DEVICE_BLOCK is the first subfunction that the graphics engine calls when it loads a device driver's module. Parameters pKling1 to a structure that contains the following fields: Field Description ──────────────────────────────────────────────────────────────────────────── ulVersion Specifies the version number of the graphics engine. This is a binary-coded decimal number. ulTableSize Specifies the number of entries in the dispatch table. The device driver should not replace pointers past the end of the table as indicated by this number. pKling2 to a structure that contains the following fields: Field Description ──────────────────────────────────────────────────────────────────────────── pFlags Points to a word of logical device flags. The device driver should set bits 0, 1, and 2 of these flags. All other flags are reserved for system use and must not be modified. The bits are defined as follows: Value Meaning ──────────────────────────────────────────────────────────────────────────── 0x0001 Set if each device context for this device will require its own physical device block. Clear if only one physical device block is needed for each physical device. It is expected that printer and plotter drivers would set this bit, and most others would clear it. 0x0002 Set if this device can have only one device context open at any time; this is a serially reusable device. Clear if an arbitrary number of device contexts may coexist. 0x0004 Set if the pdriv and pszDriverName fields in DEVOPENSTRUC (which was passed in a call to the OpenDC function) should be ignored. This would be the case if the device driver supported only one physical device in one configuration─for example, the display driver. .LI "pDispatchTable" Points to the dispatch table. Each entry in the table is a 32-bit pointer to a graphics function. This table is already filled with the addresses of the system-default functions when this call is made. The device driver must replace the table entries that correspond to required major functions. For a complete list of these functions, see Section 7.2. The device driver may replace more entries, at its option. This table will then be used to address functions for all physical devices belonging to this logical device. Return Value The return value is TRUE if the subfunction is successful or FALSE if an error occurs. █ OS2_PM_DRV_ENABLE (2) ──────────────────────────────────────────────────────────────────────────── ULONG OS2_PM_DRV_ENABLE (FILL_PHYS_DEVICE_BLOCK, pdop, ulType) PDEVOPENSTRUC pdop; /*pointer to DEVOPENSTRUC structure */ ULONG ulType; /*type of device context */ FILL_PHYS_DEVICE_BLOCK is a subfunction of OS2_PM_DRV_ENABLE. This subfunction initializes a device driver's physical device block. A physical device block is a data structure that contains information such as the device's name, output type, horizontal and vertical resolutions, color planes, foreground and background mix modes, default fonts, and so on. Parameters pdop to a DEVOPENSTRUC structure. The structure has the following form: typedef struct _DEVOPENSTRUC { PSZ pszLogAddress; PSZ pszDriverName; PDRIVDATA pdriv; PSZ pszDataType; PSZ pszComment; PSZ pszQueueProcName; PSZ pszQueueProcParams; PSZ pszSpoolerParams; PSZ pszNetworkParams; } DEVOPENSTRUC; ulType bit 0 of the pFlags field was set, this argument specifies the type of device context. Otherwise, this argument is zero. Return Value The return value is a handle or a pointer to a physical device block if the subfunction is successful; otherwise, it is -1. Comments The graphics engine may call FILL_PHYS_DEVICE_BLOCK once per physical device or once per device-context allocation, depending on how bit 0 of the pFlags field was set by the FILL_LOGICAL_DEVICE_BLOCK subfunction. The DISABLE_PHYS_DEVICE_BLOCK and ENABLE_DDC subfunctions use the handle or pointer that this subfunction returns. █ OS2_PM_DRV_ENABLE (4) ──────────────────────────────────────────────────────────────────────────── ULONG OS2_PM_DRV_ENABLE (DISABLE_PHYS_DEVICE_BLOCK, hdc, Reserved) HDC hdc; /*handle of engine's device context */ TYPE Reserved; /*Reserved */ DISABLE_PHYS_DEVICE_BLOCK is a subfunction of OS2_PM_DRV_ENABLE. This subfunction deallocates the memory that a device driver occupied. Parameters hdc the physical device block handle returned by the FILL_PHYS_DEVICE_BLOCK subfunction. Reserved Return Value The return value is zero if the subfunction is successful; otherwise, it is 1. Comments If the device driver is a display driver, DISABLE_PHYS_DEVICE_BLOCK should not deallocate the device driver's memory; instead, it should return zero. █ OS2_PM_DRV_ENABLE (5) ──────────────────────────────────────────────────────────────────────────── ULONG OS2_PM_DRV_ENABLE (ENABLE_DDC, pKling, Reserved) PKLING pKling; /*pointer to structure */ TYPE Reserved; /*must be zero */ ENABLE_DDC is a subfunction of OS2_PM_DRV_ENABLE. This subfunction reserves memory for, and initializes, a device's instance data. Parameters pKling to a structure that has the following fields: Field Description ──────────────────────────────────────────────────────────────────────────── ulStateInfo Specifies the handle or pointer returned by the FILL_PHYS_DEVICE_BLOCK subfunction. ulType Specifies the type of device context. hdc Identifies the device context. Reserved a reserved value; must be zero. Return Value The return value is a handle or pointer to the device's instance data if the subfunction is successful; otherwise, it is -1. Comments A device's instance data is device driver data such as the current transform matrix, the current attribute bundles, the current color table, and the current arc parameters. The handle or pointer that this subfunction returns is sometimes called the device's "magic number." █ OS2_PM_DRV_ENABLE (6) ──────────────────────────────────────────────────────────────────────────── ULONG OS2_PM_DRV_ENABLE (DISABLE_DDC, hdc, Reserved) HDC hdc; /*handle of engine's device context */ TYPE Reserved; /*must be zero */ DISABLE_DDC is a subfunction of OS2_PM_DRV_ENABLE. This subfunction informs a device driver that it should release the memory occupied by its device context. Parameters hdc the handle returned by the ENABLE_DDC subfunction. Reserved a reserved value; must be zero. Return Value The return value is zero if the subfunction is successful; otherwise, it is -1. █ OS2_PM_DRV_ENABLE (7) ──────────────────────────────────────────────────────────────────────────── ULONG OS2_PM_DRV_ENABLE (SAVE_DDC_STATE, hdc, Reserved) HDC hdc; /*handle of engine's device context */ TYPE Reserved; /*must be zero */ SAVE_DDC_STATE is a subfunction of OS2_PM_DRV_ENABLE. This subfunction indicates to the device driver that it should save a copy of its device context's instance data on a special stack. Parameters hdc the handle returned by the ENABLE_DDC subfunction. Reserved a reserved value; must be zero. Return Value The return value is zero if the function is successful; otherwise, it is -1. Comments SAVE_DDC_STATE should save the instance data using a LIFO (last-in, first-out) format. If memory is not available for saving a device context's instance data, this subfunction should return -1. █ OS2_PM_DRV_ENABLE (8) ──────────────────────────────────────────────────────────────────────────── ULONG OS2_PM_DRV_ENABLE (RESTORE_DDC_STATE, hdc, hddc) HDC hdc; /*handle of engine's device context */ ULONG hddc; /*handle of device driver's device context */ RESTORE_DDC_STATE is a subfunction of OS2_PM_DRV_ENABLE. This subfunction replaces the current device context's instance data with instance data stored on a special stack. Parameters hdc the handle returned by the ENABLE_DDC subfunction. hddc which instance data (from the stack) the driver should use to replace the current device context's instance data. If the number is positive, it identifies the data according to the order it was pushed onto the stack; that is, if the number is 1, the first pushed state is restored and all others are lost. If the number is 2, the second pushed state is restored and one remains saved. If the number is negative, it indicates how many states will be popped; that is, if the number is -1, pop back one state. If the number is zero, an error is returned. Return Value The return value is zero if the function is successful; otherwise, it is -1. Comments RESTORE_DDC_STATE returns an error if the hddc parameter specifies a negative value greater than the number of states pushed onto the stack. █ OS2_PM_DRV_ENABLE (9) ──────────────────────────────────────────────────────────────────────────── ULONG OS2_PM_DRV_ENABLE (RESET_DDC_STATE, hddc, Reserved) ULONG hddc; /*handle of device driver's device context */ TYPE Reserved; /*must be zero */ RESET_DDC_STATE is a subfunction of OS2_PM_DRV_ENABLE. This subfunction replaces the current device driver's instance data with the original instance data. The original data is the instance data that the device driver created at the time of the ENABLE_DDC subfunction call. Parameters hddc the device driver's device context. Reserved a reserved value; must be zero. Return Value The return value is zero if the function is successful; otherwise, it is -1. Comments The device context pointed to by the hddc parameter is the device context returned by the ENABLE_DDC subfunction or the SetDriverInfo function. RESET_DDC_STATE does not alter the device context's visible region or device-context origin. █ OS2_PM_DRV_ENABLE (10) ──────────────────────────────────────────────────────────────────────────── ULONG OS2_PM_DRV_ENABLE (COMPLETE_OPEN_DDC, hdc, hddc) HDC hdc; /*handle of engine's device context */ ULONG hddc; /*handle of device driver's device context */ COMPLETE_OPEN_DDC is a subfunction of OS2_PM_DRV_ENABLE. It is the last subfunction that the graphics engine calls when it opens a device context. When a device driver receives this call, it can perform final initialization operations such as creating a journal file. Parameters hdc the engine's device context. hddc the device driver's device context. Return Value The return value is zero if the subfunction is successful; otherwise, it is -1. Comments COMPLETE_OPEN_DDC is also sent to any installed simulations. (These simulations should ignore the hddc parameter.) █ OS2_PM_DRV_ENABLE (11) ──────────────────────────────────────────────────────────────────────────── ULONG OS2_PM_DRV_ENABLE (BEGIN_CLOSE_DDC, hdc, hddc) HDC hdc; /*handle of engine's device context */ ULONG hddc; /*handle of device driver's device context */ BEGIN_CLOSE_DDC is a subfunction of OS2_PM_DRV_ENABLE. It is the first subfunction that the graphics engine calls during the process of closing a device context. When a device driver receives this call, it should perform necessary operations such as dumping any graphics into a spool file. Parameters hdc the engine's device context. hddc the device driver's device context. Return Value The return value is zero if the subfunction is successful; otherwise, it is -1. Comments BEGIN_CLOSE_DDC is also sent to any installed simulations (which should ignore the hddc parameter). █ OS2_PM_DRV_ENABLE (12) ──────────────────────────────────────────────────────────────────────────── ULONG OS2_PM_DRV_ENABLE (INSTALL_SIMULATION, pKling, pTable) PKLING pKling; /*pointer to structure */ TYPE pTable; /*pointer to dispatch table */ INSTALL_SIMULATION is a subfunction of OS2_PM_DRV_ENABLE. This subfunction informs an installable simulation that it should load the device driver's dispatch table with pointers to its functions and perform any additional necessary initialization. Parameters pKling to a structure with the following fields: Field Description ──────────────────────────────────────────────────────────────────────────── ulVersion Specifies the version number of the graphics engine. This is a binary-coded decimal number. pComponent Points to the null-terminated string that specifies which component to install. By using these component names, a single file on the disk can contain the code for several simulations, such as: "REGIONS," "TRANSFORMATIONS," or "ARCS." Even if a file contains only one simulation component, it should check the name for consistency. ulTableSize Specifies the number of entries in the dispatch table. The simulation should not replace pointers past the end of the table as indicated by this number. pTable to the device driver's dispatch table. Return Value The return value is zero if the function is successful; otherwise, it is an error value. Comments If an installed simulation doesn't completely handle a particular function, it should save the pointer corresponding to that function before installing a pointer to its own function. █ OutlinePath ──────────────────────────────────────────────────────────────────────────── LONG OutlinePath (hdc, phid, flCmd, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ PHID phid; /*path identifier */ ULONG flCmd; /*options */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The OutlinePath function draws the boundary of the specified path. Parameters hdc Identifies the engine's device context. phid Specifies the identifier of the path to be stroked. This value must be 1 for the current release of MS OS/2. flCmd Specifies the options to use while stroking the path. This argument must be zero for the current release of MS OS/2. hddc Identifies the device driver's device context. ulFunN Specifies the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is GPI_OK or GPI_HITS if the function is successful (it is GPI_HITS if the detectable attribute is set for the presentation space and a correlation hit occurs). The return value is GPI_ERROR if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine or the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine or the device driver calls record: PMERR_BASE_ERROR PMERR_BITMAP_NOT_SELECTED PMERR_COORDINATE_OVERFLOW PMERR_DEV_FUNC_NOT_INSTALLED PMERR_HDC_BUSY PMERR_INV_COLOR_DATA PMERR_INV_COLOR_INDEX PMERR_INV_COORD_SPACE PMERR_INV_FILL_PATH_OPTIONS PMERR_INV_HDC PMERR_INV_IN_AREA PMERR_INV_IN_PATH PMERR_INV_LENGTH_OR_COUNT PMERR_INV_PATH_ID PMERR_INV_PICK_APERTURE_POSN PMERR_INV_RECT PMERR_PATH_UNKNOWN Comments The path is drawn using the current cosmetic (narrow) line attributes, which are defined in the LINEBUNDLE structure. The path is destroyed after it is drawn. █ PaintRegion ──────────────────────────────────────────────────────────────────────────── int PaintRegion (hdc, hrgn, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ HRGN hrgn; /*handle of region */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The PaintRegion function paints the specified region using the current area foreground and background colors. Mixing is controlled by the area foreground mix mode only. Parameters hdc Identifies the engine's device context. hrgn Identifies the region. hddc Identifies the device driver's device context. ulFunN Specifies the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is GPI_OK or GPI_HITS if the function is successful (it is GPI_HITS if the detectable attribute is set for the presentation space and a correlation hit occurs). The return value is GPI_ERROR if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine or the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine or the device driver calls record: PMERR_HDC_BUSY PMERR_HRGN_BUSY PMERR_INV_HDC PMERR_INV_HRGN PMERR_INV_IN_AREA PMERR_INV_IN_PATH PMERR_REGION_IS_CLIP_REGION █ PartialArc ──────────────────────────────────────────────────────────────────────────── int PartialArc (hdc, pptl, fxMult, fxStart, fxSweep, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ PPOINTL pptl; /*pointer to POINTL structure */ FIXED fxMult; /*multiplier */ FIXED fxStart; /*start angle */ FIXED fxSweep; /*sweep angle */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The PartialArc function draws two figures: a straight line, from the current position to the starting point of a partial arc; and the arc itself, with its center at the specified point. The full arc, of which the arc is a part, is identical to that defined by the FullArc function. The part of the arc drawn by this primitive function is defined by the parameters fxStart and fxSweep, which are the start and sweep angles, respectively, subtended from the center─if the current arc parameters specify a circular form. If they do not, these angles are skewed to the same degree that the ellipse is a skewed circle. The fxStart angle is measured counterclockwise from the x-axis of the circle prior to the application of the arc parameters. Both fxStart and fxSweep may be negative. If fxStart is negative, it is measured clockwise from the x-axis. If fxSweep is negative, the arc is drawn in the direction opposite to that indicated by the arc parameters. The arc parameters determine whether the arc is drawn clockwise or counterclockwise. The current position is updated to the final point on the arc. Note this difference from FullArc, in which the current position remains at the center of the figure. A primitive function (for example, PolyLine) following PartialArc will draw from the end point of the arc. Parameters hdc Identifies the engine's device context. pptl Points to a POINTL structure that contains the center point of the arc. fxMult Specifies a multiplier that determines the size of the arc in relation to an arc with the current arc parameters. The value passed is treated as a 4-byte fixed-point (FIXED) number with the high word as the integer portion and the low word as the fractional portion. Thus, a value of 65,536 specifies a multiplier of 1. There is a current implementation limit of 255 for the multiplier (that is, a value passed of 255 * 65,536 = 16,711,680). fxStart Specifies the start angle in degrees. The value passed is a fixed-point number. Thus 180 degrees is represented as 180 * 65,536 = 11,796,480. The value must be greater than or equal to zero. fxSweep Specifies the sweep angle in degrees. The value passed is a fixed-point number. The value must be positive. hddc Identifies the device driver's device context. ulFunN Specifies the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is GPI_OK or GPI_HITS if the function is successful (it is GPI_HITS if the detectable attribute is set for the presentation space and a correlation hit occurs). The return value is GPI_ERROR if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine or the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine or the device driver calls record: PMERR_BASE_ERROR PMERR_BITMAP_NOT_SELECTED PMERR_COORDINATE_OVERFLOW PMERR_DEV_FUNC_NOT_INSTALLED PMERR_HDC_BUSY PMERR_INV_ANGLE_PARM PMERR_INV_COLOR_DATA PMERR_INV_COLOR_INDEX PMERR_INV_COORD_SPACE PMERR_INV_HDC PMERR_INV_IN_AREA PMERR_INV_IN_PATH PMERR_INV_LENGTH_OR_COUNT PMERR_INV_MULTIPLIER PMERR_INV_PICK_APERTURE_POSN PMERR_INV_RECT PMERR_PATH_LIMIT_EXCEEDED PMERR_PATH_UNKNOWN █ PlayJournalFile ──────────────────────────────────────────────────────────────────────────── ULONG PlayJournalFile (hdc, hfile, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ LHANDLE hfile; /*handle of journal file */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The PlayJournalFile function plays the specified journal file to the specified device context. The journal file is read into memory and each journaled GreEntry call is played. Each journaled record is processed before playing to the extent that long pointers to data are fixed up and clone objects (regions or bitmaps) are created, if necessary, from the journaled data. It is assumed that any single journaled function and its associated data fit in a 32K buffer. If the journaled record contains region rectangles or bitmap bits, these do not count in this 32K restriction. Parameters hdc Identifies the engine's device context. hfile Identifies the journal file to play. hddc Identifies the device driver's device context. ulFunN Specifies the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is GPI_OK if the function is successful or GPI_ERROR if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine may record: PMERR_BASE_ERROR PMERR_BITMAP_IS_SELECTED PMERR_BITMAP_NOT_SELECTED PMERR_COORDINATE_OVERFLOW PMERR_DEV_FUNC_NOT_INSTALLED PMERR_EXCEEDS_MAX_SEG_LENGTH PMERR_HBITMAP_BUSY PMERR_HDC_BUSY PMERR_HRGN_BUSY PMERR_HUGE_FONTS_NOT_SUPPORTED PMERR_INCORRECT_DC_TYPE PMERR_INSUFFICIENT_MEMORY PMERR_INV_BACKGROUND_COL_ATTR PMERR_INV_BACKGROUND_MIX_ATTR PMERR_INV_BITMAP_DIMENSION PMERR_INV_CHAR_DIRECTION_ATTR PMERR_INV_CHAR_MODE_ATTR PMERR_INV_CODEPAGE PMERR_INV_COLOR_ATTR PMERR_INV_COORD_SPACE PMERR_INV_COORDINATE PMERR_INV_DC_DATA PMERR_INV_DC_TYPE PMERR_INV_DRIVER_NAME PMERR_INV_HBITMAP PMERR_INV_HDC PMERR_INV_HJOURNAL PMERR_INV_HRGN PMERR_INV_ID PMERR_INV_IN_AREA PMERR_INV_IN_PATH PMERR_INV_INFO_TABLE PMERR_INV_LENGTH_OR_COUNT PMERR_INV_LINE_TYPE_ATTR PMERR_INV_METAFILE PMERR_INV_MIX_ATTR PMERR_INV_PATTERN_REF_PT_ATTR PMERR_INV_PATTERN_SET_ATTR PMERR_INV_PATTERN_SET_FONT PMERR_INV_RECT PMERR_INV_REGION_CONTROL PMERR_INV_REGION_MIX_MODE PMERR_INV_SCAN_START PMERR_INV_USAGE_PARM PMERR_JFILE_BUSY PMERR_RAM_JNL_FILE_TOO_SMALL PMERR_REGION_IS_CLIP_REGION █ PolyFillet ──────────────────────────────────────────────────────────────────────────── int PolyFillet (hdc, aptl, cptl, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ PPOINTL aptl; /*pointer to array of POINTL structures */ LONG cptl; /*count of points */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The PolyFillet function creates a fillet on a series of connected lines, with the first line starting at the current position. Parameters aptl to an array of POINTL structures. Each structure contains the coordinates of a point. cptl the number of points. This must be at least 2. For PolyFillet, a count of 0 is also valid. Return Value The return value is GPI_OK or GPI_HITS if the function is successful (it is GPI_HITS if the detectable attribute is set for the presentation space and a correlation hit occurs). The return value is GPI_ERROR if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine or the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine or the device driver calls record: PMERR_BASE_ERROR PMERR_BITMAP_NOT_SELECTED PMERR_COORDINATE_OVERFLOW PMERR_DEV_FUNC_NOT_INSTALLED PMERR_HDC_BUSY PMERR_INV_COLOR_DATA PMERR_INV_COLOR_INDEX PMERR_INV_COORD_SPACE PMERR_INV_HDC PMERR_INV_IN_AREA PMERR_INV_IN_PATH PMERR_INV_LENGTH_OR_COUNT PMERR_INV_PICK_APERTURE_POSN PMERR_INV_RECT PMERR_PATH_LIMIT_EXCEEDED PMERR_PATH_UNKNOWN Comments If only two points are supplied, an imaginary line is drawn from the current position to the first point, and a second line from the first point to the second. A curve is then constructed, starting at the current position and tangential to the first line at that point. The curve, which has the appearance of a fillet, is drawn such that it reaches the last point at a tangent to the second line. The straight lines are imaginary and are not drawn. If more than two points are supplied, an imaginary series of lines is constructed through them (as with the PolyLine function). All the lines except the first and last are then divided in two at their midpoints. A series of curved fillets are then drawn, with the first drawn starting at the current position to the midpoint of the second imaginary line. The second and subsequent lines are drawn starting at the end point of the previous line. The curves are drawn using the current line attributes. Upon completion, the current (x,y) position is set to the last point in the series. An individual fillet always lies within the area bounded by the starting, ending and control points. It is not an error for more than one of the points to have the same coordinates. The maximum number of fillets allowed in PolyFillet is not less than 4000. █ PolyFilletSharp ──────────────────────────────────────────────────────────────────────────── int PolyFilletSharp (hdc, aptl, cptl, pfxSharpness, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ PPOINTL aptl; /*pointer to array of POINTL structures */ LONG cptl; /*count of points */ PFIXED pfxSharpness; /*pointer to array of fixed-point values */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The PolyFilletSharp function creates a fillet on a series of connected lines, with the first line starting at the current position. Subsequent points identify the end points of the lines. Parameters hdc Identifies the engine's device context. aptl Points to an array of POINTL structures. Each structure contains the coordinates of a point. cptl Specifies the number of points. This number must be at least 2 and divisible by 2 (or 2f, where f is the number of fillets). For PolyFilletSharp, a count of 0 is also valid. pfxSharpness Points to an array of sharpness values for the fillets. The array has n/2 elements, each array element being a fixed-point (FIXED) value. hddc Identifies the device driver's device context. ulFunN Specifies the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is GPI_OK or GPI_HITS if the function is successful (it is GPI_HITS if the detectable attribute is set for the presentation space and a correlation hit occurs). The return value is GPI_ERROR if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine or the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine or the device driver calls record: PMERR_BASE_ERROR PMERR_BITMAP_NOT_SELECTED PMERR_COORDINATE_OVERFLOW PMERR_DEV_FUNC_NOT_INSTALLED PMERR_HDC_BUSY PMERR_INV_COLOR_DATA PMERR_INV_COLOR_INDEX PMERR_INV_COORD_SPACE PMERR_INV_HDC PMERR_INV_IN_AREA PMERR_INV_IN_PATH PMERR_INV_LENGTH_OR_COUNT PMERR_INV_PICK_APERTURE_POSN PMERR_INV_RECT PMERR_PATH_LIMIT_EXCEEDED PMERR_PATH_UNKNOWN Comments This function differs from PolyFillet in the following ways: ■ The sharpness of each fillet is explicitly specified. ■ Both the control and the ending point of each fillet are explicitly specified. ■ Adjacent fillets will in general have a discontinuity in gradient, unless the points are chosen so that this is not the case. The sharpness of each fillet is defined as follows. Let A and C be the starting and ending points, respectively, of the fillet, and let B be the control point. Let W be the midpoint of AC. Let D be the point where the fillet intersects WB. Then the sharpness is given by the following: sharpness (S) = WD/DB If Then ──────────────────────────────────────────────────────────────────────────── S > 1.0 Hyperbola is drawn S = 1.0 Parabola is drawn S < 1.0 Ellipse is drawn The first fillet is drawn using the two lines, one from the current position to the first (x,y) point specified (its control point), and one from there to the second point specified. The fillet starts from the current position and ends at the second point specified. It is tangential to the first line at the current position, and to the second line at the second specified point. The sharpness of this fillet is given by the first sharpness value. Each subsequent fillet is drawn starting from the ending point of the previous fillet, and uses the next two lines in the sequence. Thus, two points and one sharpness value are specified for each fillet. The curves are drawn using the current line attributes. Upon completion, the current (x,y) position is set to the last point in the series. An individual fillet always lies within the area bounded by the starting, ending and control points. It is not an error for any of the points to have the same coordinates. The maximum number of fillets allowed in PolyFilletSharp is not less than 2000. █ PolyLine ──────────────────────────────────────────────────────────────────────────── int PolyLine (hdc, aptl, cptl, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ PPOINTL aptl; /*pointer to array of POINTL structures */ LONG cptl; /*count of points */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The PolyLine function draws a series of straight lines starting at the current position and connecting the specified points. The lines are drawn using the current line attributes. Upon completion, the current position is set to the last point in the series. The maximum number of lines allowed in PolyLine is not less than 8000. Parameters hdc Identifies the engine's device context. aptl Points to an array of POINTL structures. Each structure contains the coordinates of a point. cptl Specifies the number of points. For PolyLine, a count of 0 is also valid. hddc Identifies the device driver's device context. ulFunN Specifies the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is GPI_OK or GPI_HITS if the function is successful (it is GPI_HITS if the detectable attribute is set for the presentation space and a correlation hit occurs). The return value is GPI_ERROR if an error occurs. Errors If an error occurs during the execution of this function, the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the device driver may record: PMERR_BASE_ERROR PMERR_BITMAP_NOT_SELECTED PMERR_COORDINATE_OVERFLOW PMERR_DEV_FUNC_NOT_INSTALLED PMERR_HDC_BUSY PMERR_INV_COLOR_DATA PMERR_INV_COLOR_INDEX PMERR_INV_COORD_SPACE PMERR_INV_HDC PMERR_INV_IN_AREA PMERR_INV_IN_PATH PMERR_INV_LENGTH_OR_COUNT PMERR_INV_PICK_APERTURE_POSN PMERR_INV_RECT PMERR_PATH_LIMIT_EXCEEDED PMERR_PATH_UNKNOWN █ PolyMarker ──────────────────────────────────────────────────────────────────────────── int PolyMarker (hdc, aptl, cptl, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ PPOINTL aptl; /*pointer to array of POINTL structures */ LONG cptl; /*count of points */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The PolyMarker function draws a marker, selected by the current values of the marker set and marker symbol attributes centered over a point. This function draws the first marker at the current position and draws the remaining markers at the points in the array aptl. Upon completion, the current position is set to the last point in the series. Parameters hdc the engine's device context. aptl to an array of POINTL structures. Each structure contains the coordinates of a point. cptl the number of points. For PolyMarker, a count of 0 is also valid. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is GPI_OK or GPI_HITS if the function is successful (it is GPI_HITS if the detectable attribute is set for the presentation space and a correlation hit occurs). The return value is GPI_ERROR if an error occurs. Errors If an error occurs during the execution of this function, the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the device driver may record: PMERR_ALREADY_IN_PATH PMERR_BASE_ERROR PMERR_BITMAP_NOT_SELECTED PMERR_COORDINATE_OVERFLOW PMERR_DEV_FUNC_NOT_INSTALLED PMERR_EXCEEDS_MAX_SEG_LENGTH PMERR_FONT_AND_MODE_MISMATCH PMERR_HDC_BUSY PMERR_HRGN_BUSY PMERR_HUGE_FONTS_NOT_SUPPORTED PMERR_INSUFFICIENT_MEMORY PMERR_INV_BACKGROUND_COL_ATTR PMERR_INV_BACKGROUND_MIX_ATTR PMERR_INV_CHAR_ANGLE_ATTR PMERR_INV_CHAR_DIRECTION_ATTR PMERR_INV_CHAR_MODE_ATTR PMERR_INV_CHAR_POS_OPTIONS PMERR_INV_CHAR_SET_ATTR PMERR_INV_CHAR_SHEAR_ATTR PMERR_INV_CLIP_PATH_OPTIONS PMERR_INV_CODEPAGE PMERR_INV_COLOR_ATTR PMERR_INV_COLOR_DATA PMERR_INV_COLOR_INDEX PMERR_INV_COORD_SPACE PMERR_INV_COORDINATE PMERR_INV_DC_TYPE PMERR_INV_END_PATH_OPTIONS PMERR_INV_FILL_PATH_OPTIONS PMERR_INV_GEOM_LINE_WIDTH_ATTR PMERR_INV_HDC PMERR_INV_HRGN PMERR_INV_ID PMERR_INV_IN_AREA PMERR_INV_IN_PATH PMERR_INV_LENGTH_OR_COUNT PMERR_INV_LINE_END_ATTR PMERR_INV_LINE_JOIN_ATTR PMERR_INV_LINE_TYPE_ATTR PMERR_INV_LINE_WIDTH_ATTR PMERR_INV_MARKER_SET_ATTR PMERR_INV_MARKER_SYMBOL_ATTR PMERR_INV_MATRIX_ELEMENT PMERR_INV_MIX_ATTR PMERR_INV_PATH_ID PMERR_INV_PATTERN_REF_PT_ATTR PMERR_INV_PATTERN_SET_ATTR PMERR_INV_PATTERN_SET_FONT PMERR_INV_PICK_APERTURE_POSN PMERR_INV_PRIMITIVE_TYPE PMERR_INV_RECT PMERR_INV_REGION_CONTROL PMERR_INV_SETID PMERR_INV_TRANSFORM_TYPE PMERR_MATRIX_OVERFLOW PMERR_NOT_IN_PATH PMERR_PATH_LIMIT_EXCEEDED PMERR_PATH_UNKNOWN PMERR_REGION_IS_CLIP_REGION PMERR_UNSUPPORTED_ATTR PMERR_UNSUPPORTED_ATTR_VALUE █ PolyScanline ──────────────────────────────────────────────────────────────────────────── ULONG PolyScanline (hdc, psd, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ PSCANDATA psd; /*pointer to SCANDATA structure */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The PolyScanline function fills the areas between the specified short-line pairs using the current pattern attributes. This function must be supported by all device drivers. The device driver can make the following assumptions: ■ The count of the number of polyscans (short-line pairs) in the buffer is never odd. ■ The two short-lines in a polyscan pair will both have the same height and will never intersect. ■ The ordering of the edges is from bottom to top and from left to right. The device driver must perform region clipping for PolyScanline. For non-display device drivers this can be accomplished by a call to the display device driver. The coordinates for this function are screen coordinates. Parameters hdc the engine's device context. psd to a SCANDATA structure. The structure has the following form: typedef struct _SCANDATA { /* sd */ PSHORTLINE pslFirstLeft; PSHORTLINE pslLastLeft; PSHORTLINE pslFirstRight; PSHORTLINE pslLastRight; ULONG c; RECTL rclBound; } SCANDATA; hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is GPI_OK if the function is successful or GPI_ERROR if an error occurs. Errors If an error occurs during the execution of this function, the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the device driver may record: PMERR_BITMAP_NOT_SELECTED PMERR_COORDINATE_OVERFLOW PMERR_DEV_FUNC_NOT_INSTALLED PMERR_HDC_BUSY PMERR_INV_COLOR_DATA PMERR_INV_COLOR_INDEX PMERR_INV_COORD_SPACE PMERR_INV_COORDINATE PMERR_INV_HDC PMERR_INV_IN_AREA PMERR_INV_IN_PATH PMERR_INV_LENGTH_OR_COUNT PMERR_INV_PICK_APERTURE_POSN PMERR_INV_RECT PMERR_INV_REGION_CONTROL Comments The first SCANDATA structure is a header. It points to the first and last short-line pair. This is because the Bitblt function may have to process the scan lines forward or backward depending on the transfer. The right and left short lines are doubly-linked in two separate short-line lists. Each list is found by using the header. █ PolyShortLine ──────────────────────────────────────────────────────────────────────────── int PolyShortLine (hdc, psl, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ PSHORTLINE psl; /*pointer to SHORTLINE structure */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The PolyShortLine function draws a series of short lines. The function is not available at the API level. The parameters include a pointer to the SHORTLINE structure, which is a linked list of short lines. The function should render each short line in the list until it finds a null short line. The current position is not affected by this call. The lines are assumed already clipped. The coordinates for this function are screen coordinates. Parameters hdc Identifies the engine's device context. psl Points to a SHORTLINE structure. The structure has the following form: typedef struct _SHORTLINE { /* sl */ SHORTLINEHEADER slh; SHORT ax[1]; } SHORTLINE; hddc Identifies the device driver's device context. ulFunN Specifies the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is GPI_OK if the function is successful or GPI_ERROR if an error occurs. Errors If an error occurs during the execution of this function, the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the device driver may record: PMERR_BITMAP_NOT_SELECTED PMERR_COORDINATE_OVERFLOW PMERR_DEV_FUNC_NOT_INSTALLED PMERR_HDC_BUSY PMERR_INV_COLOR_DATA PMERR_INV_COLOR_INDEX PMERR_INV_COORD_SPACE PMERR_INV_HDC PMERR_INV_IN_AREA PMERR_INV_IN_PATH PMERR_INV_LENGTH_OR_COUNT PMERR_INV_PICK_APERTURE_POSN Comments The SHORTLINE structure is a discrete representation of a curve. A curve starts at point %x sub 0 , y sub 0% and ends at point %x sub 1 , y sub 1%. For each of the %y sub 1~-~y sub 0~+~1% rows, there is exactly one x value, contained in the x array. The steps are stored in absolute coordinates; for example: 0 | XXX XXXX XXXXX X The short line is defined as follows: xstart = 0, ystart = 0, xstop = 13, ystop = 4, and the array is {3,7,12,13}. Note there are %y sub 1~-~y sub 0~+~1% numbers in the array. The last point, (13,4), is not drawn. █ PolySpline ──────────────────────────────────────────────────────────────────────────── int PolySpline (hdc, aptl, cptl, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ PPOINTL aptl; /*pointer to array of POINTL structures */ LONG cptl; /*count of points */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The PolySpline function creates a succession of cubic Bezier splines. The first spline is drawn from the current position to the third specified point, with the first and second points used as control points. Subsequent splines start from the ending point of the previous spline, and end at the next specified point but two, with the intervening points their first and second control points. The application must ensure that the gradient is continuous at each end/start point, if this is required. The number of points in the array must be 3s, where s is the number of splines. The points are given in the following order: first control point, second control point, and ending point. The splines are drawn using the current line attributes. Upon completion, the current position is set to the last point in the series. An individual spline always lies within the area bounded by the starting, ending and control points. It is not an error for any of the points have the same coordinates. The maximum number of splines allowed in PolySpline is not less than 2500. Parameters hdc Identifies the engine's device context. aptl Points to an array of POINTL structures. Each structure contains the coordinates of a point. cptl Specifies the number of points in the array of structures. This number must be at least 3 and divisible by 3 (or 3s, where s is the number of splines). For PolySpline, a count of 0 is also valid. hddc Identifies the device driver's device context. ulFunN Specifies the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is GPI_OK or GPI_HITS if the function is successful (it is GPI_HITS if the detectable attribute is set for the presentation space and a correlation hit occurs). The return value is GPI_ERROR if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine or the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine or the device driver calls record: PMERR_BASE_ERROR PMERR_BITMAP_NOT_SELECTED PMERR_COORDINATE_OVERFLOW PMERR_DEV_FUNC_NOT_INSTALLED PMERR_HDC_BUSY PMERR_INV_COLOR_DATA PMERR_INV_COLOR_INDEX PMERR_INV_COORD_SPACE PMERR_INV_HDC PMERR_INV_IN_AREA PMERR_INV_IN_PATH PMERR_INV_LENGTH_OR_COUNT PMERR_INV_PICK_APERTURE_POSN PMERR_INV_RECT PMERR_PATH_LIMIT_EXCEEDED PMERR_PATH_UNKNOWN █ PtInRegion ──────────────────────────────────────────────────────────────────────────── int PtInRegion (hdc, hrgn, pptl, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ HRGN hrgn; /*handle of region */ PPOINTL pptl; /*pointer to POINTL structure */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The PtInRegion function checks whether a point lies within a region. Parameters hdc Identifies the engine's device context. hrgn Identifies the region. pptl Points to a POINTL structure that contains the coordinates of the point to check. hddc Identifies the device driver's device context. ulFunN Specifies the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is PRGN_OUTSIDE or PRGN_INSIDE if the function is successful or PRGN_ERROR if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine or the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine or the device driver calls record: PMERR_HRGN_BUSY PMERR_INV_COORDINATE PMERR_INV_HRGN PMERR_INV_RECT PMERR_REGION_IS_CLIP_REGION █ PtVisible ──────────────────────────────────────────────────────────────────────────── int PtVisible (hdc, pptl, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ PPOINTL pptl; /*pointer to POINTL structure */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The PtVisible function checks whether a point is visible within the clipping region of the specified device context (where clipping region is defined to be the intersection of application clipping and clipping resulting from windowing). Parameters hdc Identifies the engine's device context. pptl Points to a POINTL structure that contains the coordinates of the point in world coordinates. hddc Identifies the device driver's device context. ulFunN Specifies the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is PVIS_VISIBLE or PVIS_INVISIBLE if the function is successful or PVIS_ERROR if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine or the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine or the device driver calls record: PMERR_COORDINATE_OVERFLOW PMERR_DEV_FUNC_NOT_INSTALLED PMERR_HDC_BUSY PMERR_INV_COORD_SPACE PMERR_INV_COORDINATE PMERR_INV_HDC PMERR_INV_LENGTH_OR_COUNT PMERR_INV_RECT █ QueryBitmapHandle ──────────────────────────────────────────────────────────────────────────── HBITMAP QueryBitmapHandle (hdc, lcid, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ LCID lcid; /*local identifier */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The QueryBitmapHandle function retrieves the bitmap handle for the specified local identifier or raises an error if the identifier does not reference a bitmap. Parameters hdc Identifies the engine's device context. lcid Specifies the local identifier for the bitmap. hddc Identifies the device driver's device context. ulFunN Specifies the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is the bitmap handle if the function is successful; otherwise, it is zero. Errors If an error occurs during the execution of this function, the graphics engine calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine may record: PMERR_BITMAP_NOT_SELECTED PMERR_HDC_BUSY PMERR_INV_HDC PMERR_INV_SETID █ QueryCharPositions ──────────────────────────────────────────────────────────────────────────── ULONG QueryCharPositions (hdc, pptlStart, flCmd, cch, pch, pdx, aptlCharPos, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ PPOINTL pptlStart; /*pointer to POINTL structure */ ULONG flCmd; /*options */ LONG cch; /*count of characters */ PCH pch; /*pointer to character string */ PLONG pdx; /*pointer to array of vectors */ PPOINTL aptlCharPos; /*pointer to array of POINTL structures */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The QueryCharPositions function retrieves the positions in world coordinates at which the currently associated device will place each given character, taking into account kerning, extra space, etc. A starting position may optionally be specified. A vector of increments may optionally be specified, which allows control over the positioning of each character after the first. These distances are measured in world coordinates (along the baseline for left-to-right and right-to-left character directions, and along the shearline for top-to-bottom and bottom-to-top) and if specified, set the widths of each character. Any spacing called for by character spacing, character extra, or character-break extra is applied in addition to the widths specified by the vector. Parameters hdc Identifies the engine's device context. pptlStart Points to a POINTL structure that contains the starting position. flCmd Specifies control flags. This parameter can be one of the following: Value Meaning ──────────────────────────────────────────────────────────────────────────── CHS_VECTOR Use increment vectors. If this value is not given, do not use the increment vectors. CHS_START_XY Use the starting position. If this value is not given, use the current position. All other values are reserved. cch Specifies the number of bytes in the character string. pch Points to the string of character code points. pdx Points to an array of vector increments. These are 4-byte signed integers in world coordinates. aptlCharPos Points to an array of POINTL structures. The first element of the array contains the current position and the last contains the new current position. hddc Identifies the device driver's device context. ulFunN Specifies the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is GPI_OK if the function is successful or GPI_ERROR if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine or the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine or the device driver calls record: PMERR_COORDINATE_OVERFLOW PMERR_DEV_FUNC_NOT_INSTALLED PMERR_EXCEEDS_MAX_SEG_LENGTH PMERR_HDC_BUSY PMERR_INSUFFICIENT_MEMORY PMERR_INV_CHAR_ANGLE_ATTR PMERR_INV_CHAR_MODE_ATTR PMERR_INV_CHAR_POS_OPTIONS PMERR_INV_CODEPAGE PMERR_INV_COORD_SPACE PMERR_INV_HDC PMERR_INV_LENGTH_OR_COUNT PMERR_INV_MATRIX_ELEMENT PMERR_INV_SETID PMERR_INV_TRANSFORM_TYPE █ QueryClipRegion ──────────────────────────────────────────────────────────────────────────── HRGN QueryClipRegion (hdc, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The QueryClipRegion function retrieves the handle of the currently selected clip region. Parameters hdc Identifies the engine's device context. hddc Identifies the device driver's device context. ulFunN Specifies the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is the region handle if the function is successful, NULL if no region is selected, or HRGN_ERROR if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine or the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine or the device driver calls record: PMERR_HDC_BUSY PMERR_INV_HDC █ QueryCodePageVector ──────────────────────────────────────────────────────────────────────────── ULONG QueryCodePageVector (ulCodePage, hddc, ulFunN) ULONG ulCodePage; /*code page */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The QueryCodePageVector function retrieves a pointer to a vector of 256 words, which are the code-point-to-glyph mapping numbers. Parameters ulCodePage the code page number. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is a pointer to code-page vector if the function is successful. Otherwise, it is zero. Errors If an error occurs during the execution of this function, the graphics engine calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine may record: PMERR_EXCEEDS_MAX_SEG_LENGTH PMERR_INSUFFICIENT_MEMORY PMERR_INV_CODEPAGE █ QueryColorData ──────────────────────────────────────────────────────────────────────────── BOOL QueryColorData (hdc, clColorData, alColorData, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ LONG clColorData; /*count of color-data elements */ PLONG alColorData; /*pointer to array of color data */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The QueryColorData function retrieves information about the currently available color table and device colors. Default colors are not included in the loaded color index returned in the first and second elements of the color data array. Parameters hdc the engine's device context. clColorData the number of elements to copy to the color data array. alColorData to the color data array. For more information, see "Comments." Information is returned only for the number of elements supplied. Any extra elements supplied are set to zero by the system. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine may record: PMERR_DEV_FUNC_NOT_INSTALLED PMERR_INV_HDC PMERR_INV_LENGTH_OR_COUNT Comments The color data array pointed to by alColorData has the following elements: Index Description ──────────────────────────────────────────────────────────────────────────── QCD_LCT_FORMAT Specifies the format of the loaded color table. This format can be one of the following: Value Meaning ──────────────────────────────────────────────────────────────────────────── LCOLF_DEFAULT Default color table is in effect. (0) LCOLF_INDRGB Color table loaded that translates from index to RGB. (1) LCOLF_RGB Color index = RGB. (3) .LI "QCD_LCT_LOINDEX" Specifies the smallest color index loaded in the color table. This value will always be 0. .LI "QCD_LCT_HIINDEX" Specifies the largest color index in the color table. This value will never be less than 15. █ QueryColorIndex ──────────────────────────────────────────────────────────────────────────── LONG QueryColorIndex (hdc, flCmd, clr, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ ULONG flCmd; /*options */ COLOR clr; /*RGB color value */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The QueryColorIndex function retrieves a color table index or an RGB value. If a device context contains a color table, the function returns the color table index for a device color that is closest to the color specified by the clr parameter. If a device context does not contain a color table─that is, if the RGB mode is set─the function returns clr. Parameters hdc the engine's device context. flCmd various options. If this value is LCOLOPT_REALIZED, the function returns the color index for a color in a realized color table. If this value is zero, the function returns the color index for a color in the current logical color table. All other values are reserved. clr an RGB color value. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is the color index providing the closest match to the specified color if the function is successful. Otherwise, it is GPI_ALTERROR. Errors If an error occurs during the execution of this function, the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the device driver may record: PMERR_DEV_FUNC_NOT_INSTALLED PMERR_INV_COLOR_OPTIONS PMERR_INV_HDC PMERR_INV_RGBCOLOR █ QueryDeviceBitmaps ──────────────────────────────────────────────────────────────────────────── BOOL QueryDeviceBitmaps (hdc, abmf, clBitmapFormats, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ PBITMAPFORMAT abmf; /*pointer to array of BITMAPFORMAT structures */ LONG clBitmapFormats; /*count of bitmap formats */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The QueryDeviceBitmaps function retrieves a list of device bitmap formats supported by the CreateBitmap function. The number of formats supported can be found by calling the QueryDeviceCaps function. The format at the start of the returned list is that which most closely matches the device's bitmap format. The data is returned in the array pointed to by the abmf parameter. Unused array elements are cleared to zero. Parameters hdc Identifies the engine's device context. abmf Points to an array of BITMAPFORMAT structures. Each structure receives the data for one bitmap format. The structure has the following form: typedef struct _BITMAPFORMAT { /* bmf */ ULONG cPlanes; ULONG cBitCount; } BITMAPFORMAT; clBitmapFormats Specifies the number of elements in the array pointed to by abmf. hddc Identifies the device driver's device context. ulFunN Specifies the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the device driver may record: PMERR_DEV_FUNC_NOT_INSTALLED PMERR_INV_LENGTH_OR_COUNT █ QueryDeviceCaps ──────────────────────────────────────────────────────────────────────────── BOOL QueryDeviceCaps (hdc, lIndex, alData, clData, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ LONG lIndex; /*starting index */ PLONG alData; /*pointer to buffer for capabilities */ LONG clData; /*number of bytes in buffer */ ULONG hddc; /*device driver's device context */ ULONG ulFunN; /*flags and function number */ The QueryDeviceCaps function returns information about the capabilities of a specified device. If the lIndex and clData parameters reference an undefined capability, the function returns zero for that element. This is not an error. Parameters hdc the engine's device context. lIndex the index number of the first item of information to be returned in alData. The first element is number 1. alData to an array of 32-bit integers. It must have at least clData elements. Each element receives a capability. For more information about capabilities, see "Comments." clData the number of items of information to be returned in the array specified by alData. This must be greater than zero; otherwise, an error will be logged. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the device driver calls the WinSetErrorInfo function and records the associated error code. The following is a possible error code that the device driver may record: PMERR_DEV_FUNC_NOT_INSTALLED Comments There are the following device capabilities: CAPS_FAMILY the device family (the values are the same as for the type parameter in DevOpenDC/OpenDC). CAPS_IO_CAPS device input/output capability. This value can be one of the following: Value Meaning ──────────────────────────────────────────────────────────────────────────── CAPS_IO_DUMMY Dummy device (1) CAPS_IO_SUPPORTS_OP Device supports output (2) CAPS_IO_SUPPORTS_IP Device supports input (3) CAPS_IO_SUPPORTS_IO Device supports output and input (4) CAPS_TECHNOLOGY the display technology. This value can be one of the following: Value Meaning. ──────────────────────────────────────────────────────────────────────────── CAPS_TECH_UNKNOWN Unknown (for example, metafile) (0) CAPS_TECH_VECTOR_PLOTTER Vector plotter (1) CAPS_TECH_RASTER_DISPLAY Raster display (2) CAPS_TECH_RASTER_PRINTER Raster printer (3) CAPS_TECH_RASTER_CAMERA Raster camera (4) CAPS_DRIVER_VERSION the device driver version number. CAPS_HEIGHT the default page depth (for a full-screen maximized window for displays) in display points (pels). (For a plotter, a display point or pel is defined as the smallest possible displacement of the pen and can be smaller than a pen width.) CAPS_WIDTH the default page width (for a full-screen maximized window for displays) in display points. CAPS_HEIGHT_IN_CHARS the default page depth (for a full-screen maximized window for displays) in character rows. CAPS_WIDTH_IN_CHARS the default page width (for a full-screen maximized window for displays) in character columns. CAPS_VERTICAL_RESOLUTION the vertical resolution of the device in display points (pels) per meter for displays, and plotter units per meter for plotters. CAPS_HORIZONTAL_RESOLUTION the horizontal resolution of the device in display points (pels) per meter for displays, and plotter units per meter for plotters. CAPS_CHAR_HEIGHT the default character-box height in display points (pels). CAPS_CHAR_WIDTH the default character-box width in display points (pels). CAPS_SMALL_CHAR_HEIGHT the default small character-box height in display points (pels). This number is zero if there is only one character-box size). CAPS_SMALL_CHAR_WIDTH the default small character-box width in display points (pels). This number is zero if there is only one character-box size). CAPS_COLORS the number of distinct colors supported at the same time, including background colors (gray scales count as distinct colors). If loadable color tables are supported, this value is the number of entries in the device color table. For plotters, the returned value is the number of pens plus 1 (for the background color). CAPS_COLOR_PLANES the number of color planes. CAPS_COLOR_BITCOUNT the number of adjacent color bits for each pel (within one plane). CAPS_COLOR_TABLE_SUPPORT loadable color-table support. This value can be one of the following: Value Meaning ──────────────────────────────────────────────────────────────────────────── CAPS_COLTABL_RGB_8 RGB color table can be loaded, with a minimum support of 8 bits each for red green and blue. (1) CAPS_COLTABL_RGB_8_PLUS Color table with other than 8 bits for each primary can be loaded. (2) CAPS_COLTABL_TRUE_MIX Mixing will occur when the logical color table has been realized, if the size of the logical color table is not greater than the number of distinct colors supported (see CAPS_COLORS). (4) CAPS_COLTABL_REALIZE Loaded color table can be realized. (8) CAPS_MOUSE_BUTTONS the number of mouse or tablet buttons that are available to the application. A returned value of zero indicates that there are no mouse or tablet buttons available. CAPS_FOREGROUND_MIX_SUPPORT foreground mix-mode support. This value can be a combination of the following: Value Meaning ──────────────────────────────────────────────────────────────────────────── CAPS_FM_OR OR (1) CAPS_FM_OVERPAINT Overpaint (2) CAPS_FM_XOR Exclusive-OR (8) CAPS_FM_LEAVEALONE Leave-alone (16) CAPS_FM_AND AND (32) CAPS_FM_GENERAL_BOOLEAN Mixes 7 through 17 (64) The value returned is the sum of the values appropriate to the mix modes supported. A device capable of supporting OR must, as a minimum, return 1 + 2 + 16 = 19, signifying support for the mandatory mix modes OR, overpaint and leave-alone. Note that these numbers correspond to the decimal representation of a bit string that is seven bits long, with each bit set to 1 if the appropriate mode is supported. Those mix modes returned as supported are guaranteed for all primitive types. CAPS_BACKGROUND_MIX_SUPPORT background mix-mode support. This value can be a combination of the following: Value Meaning ──────────────────────────────────────────────────────────────────────────── CAPS_BM_OR OR (1) CAPS_BM_OVERPAINT Overpaint (2) CAPS_BM_XOR Exclusive-OR (8) CAPS_BM_LEAVEALONE Leave-alone (16) The value returned is the sum of the values appropriate to the mix modes supported. A device must, as a minimum, return 2 + 16 = 18, signifying support for the mandatory background mix modes overpaint, and leave-alone. Note that these numbers correspond to the decimal representation of a bit string that is five bits long, with each bit set to 1 if the appropriate mode is supported. Those mix modes returned as supported are guaranteed for all primitive types. CAPS_VIO_LOADABLE_FONTS the number of logical fonts that may be created for alphanumerics. CAPS_WINDOW_BYTE_ALIGNMENT whether the client area of Vio windows should be byte-aligned. This value can be the following: Value Meaning ──────────────────────────────────────────────────────────────────────────── CAPS_BYTE_ALIGN_REQUIRED Must be byte-aligned. (0) CAPS_BYTE_ALIGN_RECOMMENDED More efficient if byte-aligned, but not required. (1) CAPS_BYTE_ALIGN_NOT_REQUIRED Does not matter whether byte-aligned. (2) CAPS_BITMAP_FORMATS the number of bitmap formats supported by the device. CAPS_RASTER_CAPS the device's raster-operations capability. This value can be one of the following: Value Meaning ──────────────────────────────────────────────────────────────────────────── CAPS_RASTER_BITBLT Bitblt is supported. (1) CAPS_RASTER_BANDING The device supports banding. (2) CAPS_RASTER_BITBLT_SCALING Bitblt with scaling is supported. (4) CAPS_RASTER_SET_PEL SetPel is supported. (16) CAPS_MARKER_HEIGHT the default marker-box width in pels. CAPS_MARKER_WIDTH the default marker-box depth in pels. CAPS_DEVICE_FONTS the number of device specific fonts. CAPS_GRAPHICS_SUBSET the graphics drawing subset that is supported. CAPS_GRAPHICS_VERSION the graphics architecture version number that is supported (1 indicates version 1). CAPS_GRAPHICS_VECTOR_SUBSET the graphics vector drawing subset that is supported. CAPS_DEVICE_WINDOWING device windowing support. If this value is 1, the device supports windowing. Other bits are reserved and must be zero. CAPS_ADDITIONAL_GRAPHICS additional graphics support. This value can be the following: Value Meaning ──────────────────────────────────────────────────────────────────────────── CAPS_GRAPHICS_KERNING_SUPPORT Device supports kerning. (2) CAPS_FONT_OUTLINE_DEFAULT Driver can supply default outline font. (4) . CAPS_FONT_IMAGE_DEFAULT Driver can supply default image font. (8) CAPS_FONT_OUTLINE_MANAGE Driver will manage default outline font. (16) CAPS_FONT_IMAGE_MANAGE Driver will manage default image font. (32) Two fonts will be bound to the engine: an image font and an outline font. These will be used if the driver does not want to supply one or both of these. In addition, if the driver wants to supply default fonts but not manage them, the engine will do so (the driver gives the engine the font selector, and the engine does all the necessary mapping, transforming, etc.). Other bits are reserved and must be zero. CAPS_PHYS_COLORS the maximum number of distinct colors that can be specified on the device. CAPS_COLOR_INDEX the maximum logical color table index supported for this device. This value must be at lease 7. For EGA and VGA adapters, the value is 63. █ QueryDeviceNames ──────────────────────────────────────────────────────────────────────────── BOOL QueryDeviceNames (pszDriverName, pcDevices, pszDeviceNames, pszDeviceDescs, pcDataTypes, pszDataTypes, hddc, ulFunN) .V "PSZ " "pszDriverName;" "pointer to driver name PLONG pcDevices; /*pointer to count of device names */ PSTR32 pszDeviceNames; /*pointer to device names */ PSTR64 pszDeviceDescs; /*pointer to device descriptions */ PLONG pcDataTypes; /*pointer to count of data types */ PSTR16 pszDataTypes; /*pointer to data-type names */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The QueryDeviceNames function retrieves the names of the devices supported by the specified driver, their corresponding descriptions, and the data types the driver supports. ("IBM4201" is an example of a device name, "IBM 4201 Proprinter" is an example of a device description, and "PM_Q_STD" is an example of a data type.) Parameters pszDriverName to a null-terminated string containing the name of the device driver. pcDevices to a count specifying the maximum number of device names and descriptions that can be retrieved. There must be the same number of descriptions as names. If pcDevices is zero, the count is updated to the actual number of devices supported and pszDeviceNames and pszDeviceDescs are not updated. If pcDevices is nonzero, the count is updated to the actual number of device names retrieved and pszDeviceNames and pszDeviceDescs are updated. pszDeviceNames to an array of null-terminated strings identifying the particular devices (model numbers, etc). Valid names are defined by device drivers. pszDeviceDescs to an array of null-terminated strings describing the particular devices. pcDataTypes to a count specifying the maximum number of data types that can be retrieved. If pcDataTypes is zero, the count is updated to the number of data types supported and pszDataTypes is not updated. If pcDataTypes is nonzero, the count is updated to the number of data types actually retrieved and pszDataTypes is updated. pszDataTypes to an array of null-terminated strings identifying the data types. Valid data types are defined by device drivers. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine may record: PMERR_BASE_ERROR PMERR_INV_LENGTH_OR_COUNT Comment The application can call the QueryDeviceNames function with pcDataTypes and pszDataTypes set to zero to determine how much storage is needed for the data areas. After allocating the storage, the application again calls the function to retrieve the data. █ QueryDevResource ──────────────────────────────────────────────────────────────────────────── short QueryDevResource (hdc, ulType, idRes, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ ULONG ulType; /*resource type */ ULONG idRes; /*resource identifier */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The QueryDevResource function is called by a user at setup time to load all pointers and bitmaps and by the engine to load the default fonts, if any. Parameters hdc Identifies the engine's device context. ulType Specifies the resource type. idRes Specifies the resource identifier. hddc Identifies the device driver's device context. ulFunN Specifies the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is a resource selector if the function is successful, zero if the resource is not available, or GPI_ALTERROR if an error occurs. Errors If an error occurs during the execution of this function, the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the device driver may record: PMERR_BASE_ERROR PMERR_DEV_FUNC_NOT_INSTALLED Comments The following resources are accessed through this function: RT_POINTER 1 SPTR_ARROW 1 RT_POINTER 1 SPTR_TEXT 2 RT_POINTER 1 SPTR_WAIT 3 RT_POINTER 1 SPTR_SIZE 4 RT_POINTER 1 SPTR_MOVE 5 RT_POINTER 1 SPTR_SIZENWSE 6 RT_POINTER 1 SPTR_SIZENESW 7 RT_POINTER 1 SPTR_SIZEWE 8 RT_POINTER 1 SPTR_SIZENS 9 RT_POINTER 1 SPTR_APPICON 10 RT_POINTER 1 SPTR_HANDICON 11 RT_POINTER 1 SPTR_QUESICON 12 RT_POINTER 1 SPTR_BANGICON 13 RT_POINTER 1 SPTR_NOTEICON 14 RT_POINTER 1 SPTR_ILLEGAL 18 RT_POINTER 1 SPTR_FILE 19 RT_POINTER 1 SPTR_FOLDER 20 RT_POINTER 1 SPTR_MULTFILE 21 RT_POINTER 1 SPTR_PROGRAM 22 RT_BITMAP 2 SBMP_SYSMENU 1 RT_BITMAP 2 SBMP_SBUPARROW 2 RT_BITMAP 2 SBMP_SBDNARROW 3 RT_BITMAP 2 SBMP_SBRGARROW 4 RT_BITMAP 2 SBMP_SBLFARROW 5 RT_BITMAP 2 SBMP_MENUCHECK 6 RT_BITMAP 2 SBMP_CHECKBOXES 7 RT_BITMAP 2 SBMP_BTNCORNERS 8 RT_BITMAP 2 SBMP_MINBUTTON 9 RT_BITMAP 2 SBMP_MAXBUTTON 10 RT_BITMAP 2 SBMP_RESTOREBUTTON 11 RT_BITMAP 2 SBMP_CHILDSYSMENU 12 RT_BITMAP 2 SBMP_DRIVE 15 RT_BITMAP 2 SBMP_FILE 16 RT_BITMAP 2 SBMP_FOLDER 17 RT_BITMAP 2 SBMP_TREEPLUS 18 RT_BITMAP 2 SBMP_TREEMINUS 19 RT_BITMAP 2 SBMP_PROGRAM 22 FONT 1000 SFONT_RASTER 100 FONT 1000 SFONT_OUTLINE 101 █ QueryEngineVersion ──────────────────────────────────────────────────────────────────────────── LONG QueryEngineVersion (hddc, ulFunN) ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The QueryEngineVersion function returns the version number for the engine. Parameters hddc Identifies the device driver's device context. ulFunN Specifies the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value if the function is successful is a pointer to the version number of the engine, or zero for the initial version of the engine. Otherwise, the return value is GPI_ALTERROR. Errors If an error occurs during the execution of this function, the graphics engine calls the WinSetErrorInfo function and records the associated error code. █ QueryFontAttributes ──────────────────────────────────────────────────────────────────────────── BOOL QueryFontAttributes (hdc, cbfm, pfm, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ LONG cbfm; /*count of font metrics */ PFONTMETRICS pfm; /*pointer to FONTMETRICS structure */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The QueryFontAttributes function obtains the metrics of the font currently selected by the SetCharSet function. Parameters hdc Identifies the engine's device context. cbfm Specifies the length of the font-metrics buffer pointed to by the pfm parameter. pfm Points to a FONTMETRICS structure to contain the information retrieved. hddc Identifies the device driver's device context. ulFunN Specifies the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine may record: PMERR_COORDINATE_OVERFLOW PMERR_DEV_FUNC_NOT_INSTALLED PMERR_HDC_BUSY PMERR_INV_COORD_SPACE PMERR_INV_HDC PMERR_INV_LENGTH_OR_COUNT PMERR_INV_SETID Comment This function will log an error (PMERR_COORDINATE_OVERFLOW) if the operation cannot be performed because the matrix is singular. █ QueryFontFileDescriptions ──────────────────────────────────────────────────────────────────────────── ULONG QueryFontFileDescriptions (pszFilename, pcFonts, pffdescs, hddc, ulFunN) PSZ pszFilename; /*pointer to filename */ PLONG pcFonts; /*pointer to count of fonts */ PFFDESCS pffdescs; /*pointer to font descriptions */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The QueryFontFileDescriptions function retrieves the family and face names for the fonts contained in the specified file if it is a font-resource file. Parameters pszFilename Points to a null-terminated string containing the name of the font-resource file. pcFonts Points to a count of the maximum number of family-name and face-name pairs to be retrieved in the array pointed to by pffdescs. On return, this count is updated to the actual number of name pairs retrieved. pffdescs Points to an array of (2*pcFonts) 32-bit fields in which the family-name and face-name pairs for each font are returned, with the family name first in each pair. hddc Identifies the device driver's device context. ulFunN Specifies the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is a count of the number of fonts for which details were not retrieved (maximum specified minus actual) if the function is successful. Otherwise, it is GPI_ALTERROR. Errors If an error occurs during the execution of this function, the graphics engine calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine may record: PMERR_BASE_ERROR PMERR_INV_FONT_FILE_DATA Comment The application can call the QueryFontFileDescriptions function with pcFonts set to zero to determine how much storage is needed for the font descriptions. After allocating the storage, the application calls the function again to retrieve the data. █ QueryFonts ──────────────────────────────────────────────────────────────────────────── LONG QueryFonts (hdc, flCmd, pszFaceName, afm, cbfm, pcFonts, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ ULONG flCmd; /*options */ PSZ pszFaceName; /*pointer to face name */ PFONTMETRICS afm; /*pointer to array of FONTMETRICS structures */ LONG cbfm; /*count of font metrics */ PLONG pcFonts; /*pointer to count of fonts */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The QueryFonts function retrieves details about the fonts that match the specified face name. Public, private, or both public and private fonts can be specified. Parameters hdc the engine's device context. flCmd whether information about public, private, or both public and private fonts should be retrieved. The following values are valid: Value Meaning ──────────────────────────────────────────────────────────────────────────── QFF_PUBLIC Enumerate public fonts. QFF_PRIVATE Enumerate private fonts. pszFaceName to a null-terminated string containing a valid (non-NULL) face name. (If this is a NULL pointer, all faces are matched.) afm to an array of FONTMETRICS structures in which the metrics of matching fonts are returned. The format of each element is as described for the QueryFontAttributes function, except that the usCodePage field, which has no meaning in this context, is set to zero. No more than cbfm bytes are retrieved for any one font, and the number of fonts retrieved is limited to the value specified by pcFonts. cbfm the length of each FONTMETRICS structure in the afm array. pcFonts to a count specifying the number of fonts for which the application wants metrics. On return, this count is updated to the actual number of fonts for which metrics are retrieved. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is the number of fonts not retrieved (maximum specified minus actual) if the function is successful. Otherwise, the return value is GPI_ALTERROR. Errors If an error occurs during the execution of this function, the graphics engine calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine may record: PMERR_COORDINATE_OVERFLOW PMERR_DEV_FUNC_NOT_INSTALLED PMERR_HDC_BUSY PMERR_INV_COORD_SPACE PMERR_INV_HDC PMERR_INV_LENGTH_OR_COUNT PMERR_INV_OR_INCOMPAT_OPTIONS Comments By inspecting the retrieved data, the application can choose which of the available fonts is most appropriate for its requirements. If necessary, it can force selection of a particular font. The application can call the QueryFonts function with pcFonts set to zero to determine how many fonts match the face name. All sizes are returned in world coordinates. This function will log an error (PMERR_COORDINATE_OVERFLOW) if the operation cannot be performed because the matrix is singular. █ QueryHardcopyCaps ──────────────────────────────────────────────────────────────────────────── LONG QueryHardcopyCaps (hdc, lStart, chci, phci, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ LONG lStart; /*first forms-code number */ LONG chci; /*count of form codes */ PHCINFO phci; /*pointer to HCINFO structure */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The QueryHardcopyCaps function retrieves information about the hard-copy capabilities of the specified device. Parameters hdc the engine's device context. lStart the form-code number the query is to start from, where the first available form code is designated as 0. chci the number of forms the query is to cover. Thus, if there are five form codes defined, lStart is 2, and chci is 3, the query covers form codes 2, 3, and 4. If chci is zero, the count is updated to the number of form codes defined and phci is not updated. If chci is nonzero, the count is updated to the number of form codes for which information was retrieved and phci is updated. phci to a buffer containing the results of the query in chci copies of the following structure: typedef struct _HCINFO { CHAR szformname[32]; LONG cx; LONG cy; LONG xLeftClip; LONG yBottomClip; LONG xRightClip; LONG yTopClip; LONG xPels; LONG yPels; LONG flAttributes; } HCINFO ; hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value if the function is successful is the number of forms for which information was retrieved, or if chci is zero, the number of forms available. Otherwise, the return value is GPI_ALTERROR. Errors If an error occurs during the execution of this function, the device driver calls the WinSetErrorInfo function and records the associated error code. The following is a possible error code that the device driver may record: PMERR_DEV_FUNC_NOT_INSTALLED Comment The lStart and chci parameters can be used together to determine the number of forms available without having to allocate a buffer large enough to hold information on them all. █ QueryLogColorTable ──────────────────────────────────────────────────────────────────────────── LONG QueryLogColorTable (hdc, flCmd, lStart, clColorData, alColorData, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ ULONG flCmd; /*options */ LONG lStart; /*first color index */ LONG clColorData; /*count of color data */ PLONG alColorData; /*pointer to buffer for color data */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The QueryLogColorTable function retrieves the logical colors of the currently associated device, one at a time. Parameters hdc the engine's device context. flCmd the options. If flCmd is LCOLOPT_INDEX, the index is also retrieved for each RGB value. Other values are reserved. lStart the starting index for which data is to be retrieved. clColorData the number of elements available in the array pointed to by alColorData. If flCmd is LCOLOPT_INDEX, this number is the total number of index values plus the total number of RGB values. (The number of index values is always equivalent to the total number of RGB values.) alColorData to an array in which the information is returned. If flCmd is LCOLOPT_INDEX, the array consists of alternating color indices and RGB values, in the order index1, RGB1, index2, RGB2, and so on. If flCmd is LCOLOPT_INDEX and the logical color table is not loaded with a contiguous set of indices, any index values not loaded are simply skipped. If flCmd is not LCOLOPT_INDEX, the array consists of color values only (each value is as defined for the CreateLogColorTable function), starting from the specified index and ending either when there are no further loaded entries in the table or when the number of entries specified by clColorData have been retrieved. If flCmd is not LCOLOPT_INDEX and the logical color table is not loaded with a contiguous set of indices, QLCT_NOTLOADED(-1) is returned as the color value for any index value not loaded. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value if the function is successful is the number of elements retrieved, or QLCT_RGB if the color table is in RGB mode and no elements are retrieved. Otherwise, the return value is QLCT_ERROR. Errors If an error occurs during the execution of this function, the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the device driver may record: PMERR_DEV_FUNC_NOT_INSTALLED PMERR_INV_COLOR_OPTIONS PMERR_INV_COLOR_START_INDEX PMERR_INV_HDC PMERR_INV_LENGTH_OR_COUNT █ QueryLogicalFont ──────────────────────────────────────────────────────────────────────────── BOOL QueryLogicalFont (hdc, lcid, pchName, pfat, cbFontAttrs, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ LCID lcid; /*local identifier */ PSTR8 pchName; /*pointer to logical name */ PFATTRS pfat; /*pointer to FATTRS structure */ LONG cbFontAttrs; /*count of font attributes */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The QueryLogicalFont function retrieves the font attributes for the specified logical font. Parameters hdc the engine's device context. lcid the local identifier of the required logical font. pchName to an 8-character name used to describe the logical font. pfat to a FATTRS structure specified in the CreateLogicalFont function. cbFontAttrs the number of bytes of font-attribute information to be retrieved (the font may become larger in the future). hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the device driver may record: PMERR_HDC_BUSY PMERR_INV_HDC PMERR_INV_LENGTH_OR_COUNT PMERR_INV_SETID Comments Local identifiers -2, -3, and -4 represent advanced video input-and-output (AVIO) lcids 1, 2, and 3, respectively. It is the function of the engine to perform the remapping between these values and 1, 2, and 3 for the device driver. If the specified lcid is in use for a bitmap, QueryLogicalFont returns an error. █ QueryNearestColor ──────────────────────────────────────────────────────────────────────────── LONG QueryNearestColor (hdc, flCmd, clr, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ ULONG flCmd; /*options */ COLOR clr; /*RGB color value */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The QueryNearestColor function returns the RGB color in the physical palette that most closely matches the specified RGB color, even if the returned color is not available in the logical color table. Parameters hdc Identifies the engine's device context. flCmd Specifies the options. If flCmd is LCOLOPT_REALIZED, the nearest color is determined as if the logical color table were realized. Other values are reserved. clr Specifies the required color. hddc Identifies the device driver's device context. ulFunN Specifies the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value If the function is successful, the return value is the nearest RGB value to that specified by clr. Otherwise, it is GPI_ALTERROR. Errors If an error occurs during the execution of this function, the graphics engine calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine may record: PMERR_DEV_FUNC_NOT_INSTALLED PMERR_INV_COLOR_OPTIONS PMERR_INV_HDC PMERR_INV_RGBCOLOR Comments The color returned is that value that would be used for the drawing of lines, text, and so on, and does not take account of the possibility of dithered colors being used for filled areas. With dithering, it is likely that the color used for the filling of areas will be different from that used for lines, text, and so on, when the same color is specified. The algorithm for determining the "nearest" color is as follows: Imagine a cube, treating one corner as the origin and the three edges leaving it as the R, G, and B axes. Call this "RGB space." Any color is simply a point in RGB space. For example, moving up the R axis means increasing RED intensity; the different intensities of CYAN run along the line B = G. █ QueryNumberSetIds ──────────────────────────────────────────────────────────────────────────── LONG QueryNumberSetIds (hdc, ulLcidRange, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ ULONG ulLcidRange; /*range of local identifiers */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The QueryNumberSetIds function returns the total number of logical-font and bitmap identifiers (local identifiers, or lcids) that have been loaded. Parameters hdc Identifies the engine's device context. ulLcidRange Specifies whether to query graphics-programming-interface (GPI) lcids, advanced video input-and-output (AVIO) lcids, or both. This value can be one of the following: Value Meaning ──────────────────────────────────────────────────────────────────────────── LCID_RANGE_GPI Query GPI lcids. LCID_RANGE_AVIO Query AVIO lcids. LCID_RANGE_BOTH Query both GPI and AVIO lcids. hddc Identifies the device driver's device context. ulFunN Specifies the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by GPI, the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is the number of lcids if the function is successful. Otherwise, it is LCID_ERROR. Errors If an error occurs during the execution of this function, the graphics engine calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine may record: PMERR_HDC_BUSY PMERR_INV_HDC PMERR_INV_SETID PMERR_INV_SETID_TYPE Comment The local identifiers -2, -3, and -4 represent AVIO lcids 1, 2, and 3, respectively. It is the function of the engine to perform the remapping between these values and 1, 2, and 3 for the device driver. █ QueryRealColors ──────────────────────────────────────────────────────────────────────────── LONG QueryRealColors (hdc, flCmd, lStart, clColorData, alColorData, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ ULONG flCmd; /*options */ LONG lStart; /*first color index */ LONG clColorData; /*count of color data */ PLONG alColorData; /*pointer to buffer for color data */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The QueryRealColors function retrieves RGB values associated with the colors in a physical palette. Parameters hdc the engine's device context. flCmd the options. If the LCOLOPT_REALIZED option is specified, the color information is determined as if the logical color table were realized. If the LCOLOPT_INDEX option is specified, a color index is returned for each RGB value. Other values are reserved. lStart the ordinal number of the first color required. To start the sequence, this would be 0. Note that this number does not necessarily bear any relationship to the color index; the order in which the colors are returned is not defined. clColorData the number of elements available in the array pointed to by alColorData. alColorData to an array in which the information is returned. If LCOLOPT_INDEX is specified, this is an array of alternating color indices and RGB values in the order index1, RGB1, index2, RGB2, and so on. If there is a color table, colors not in the table but available on the device have a special index of CLR_NOINDEX (-254) when LCOLOPT_INDEX is specified. In RGB mode when LCOLOPT_INDEX is specified, the RGB value appears in the index field. If LCOLOPT_INDEX is not specified, this is an array of color values (each value is as defined for the CreateLogColorTable function). hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value If the function is successful, the return value is the number of elements retrieved. Otherwise, it is GPI_ALTERROR. Errors If an error occurs during the execution of this function, the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the device driver may record: PMERR_DEV_FUNC_NOT_INSTALLED PMERR_INV_COLOR_OPTIONS PMERR_INV_COLOR_START_INDEX PMERR_INV_HDC PMERR_INV_LENGTH_OR_COUNT █ QueryRGBColor ──────────────────────────────────────────────────────────────────────────── LONG QueryRGBColor (hdc, flCmd, clr, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ ULONG flCmd; /*options */ COLOR clr; /*color index */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The QueryRGBColor function returns the RGB color in the physical palette that corresponds to the specified color index. If the logical color table was created using the LCOLF_RGB option, the QueryRGBColor function is identical to the QueryNearestColor function. Parameters hdc Identifies the engine's device context. flCmd Specifies the options. If LCOLOPT_REALIZED is specified, the color information is determined as if the logical color table were realized. Since realizing a logical color table affects the contents of the physical palette, the RGB color value returned with this option may be different from the value returned without it. If LCOLOPT_INDEX is specified, the actual RGB color originally specified for this index is returned. Other values are reserved. clr Specifies the index of the required color. hddc Identifies the device driver's device context. ulFunN Specifies the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is the nearest available RGB color to that specified if the function is successful. Otherwise, it is GPI_ALTERROR. Errors If an error occurs during the execution of this function, the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the device driver may record: PMERR_DEV_FUNC_NOT_INSTALLED PMERR_INV_COLOR_DATA PMERR_INV_COLOR_INDEX PMERR_INV_COLOR_OPTIONS PMERR_INV_HDC Comment The special negative color indices -1, -2, -4, and -5 are valid inputs to this query and correspond, respectively, to CLR_BLACK, CLR_WHITE, CLR_TRUE, and CLR_FALSE; -3 (CLR_DEFAULT) is invalid and returns an error. █ QuerySetIds ──────────────────────────────────────────────────────────────────────────── BOOL QuerySetIds (hdc, clcid, alTypes, pchNames, alcid, ulLcidRange, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ LONG clcid; /*count of local identifiers */ PLONG alTypes; /*pointer to buffer for types */ PSTR8 pchNames; /*pointer to array of names */ PLCID alcid; /*pointer to array of local identifiers */ ULONG ulLcidRange; /*range of local identifiers */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The QuerySetIds function retrieves a list of types, names, and local identifiers (lcids) for all current logical fonts and tagged bitmaps. Parameters hdc the engine's device context. clcid the number of objects to retrieve. If there are fewer than clcid loaded lcids, the remaining types and lcids are set to zero. alTypes to an array of clcid elements in which to retrieve the lcid types. Each element can be one of the following values: Value Meaning ──────────────────────────────────────────────────────────────────────────── LCIDT_FONT Logical font LCIDT_BITMAP Bitmap pchNames to an array in which to retrieve the 8-character names associated with the corresponding lcids. For a bitmap, the name field is filled with zeros. alcid to an array of clcid elements in which to retrieve the lcids. ulLcidRange whether to retrieve graphics-programming-interface (GPI) lcids, advanced video input-and-output (AVIO) lcids, or both. This value can be one of the following: Value Meaning ──────────────────────────────────────────────────────────────────────────── LCID_RANGE_GPI Query GPI lcids. LCID_RANGE_AVIO Query AVIO lcids. LCID_RANGE_BOTH Query both GPI and AVIO lcids. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by GPI, the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine may record: PMERR_HDC_BUSY PMERR_INV_HDC PMERR_INV_LENGTH_OR_COUNT PMERR_INV_SETID PMERR_INV_SETID_TYPE Comment Local identifiers -2, -3, and -4 represent AVIO lcids 1, 2, and 3, respectively. It is the function of the engine to perform the remapping between these values and 1, 2, and 3 for the device driver. █ QueryTextBox ──────────────────────────────────────────────────────────────────────────── BOOL QueryTextBox (hdc, cch, pch, cptlTextBox, aptlTextBox, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ LONG cch; /*count of characters */ PCH pch; /*pointer to character string */ LONG cptlTextBox; /*count of points */ PPOINTL aptlTextBox; /*pointer to array of POINTL structures */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The QueryTextBox function retrieves the text-box and concatenation points for the specified string, using the current character attributes, in an array of up to five points. The first four points are the coordinates of the top-left, bottom-left, top-right, and bottom-right corners of the parallelogram that encompasses the string when it is drawn on the associated device. The fifth point is the concatenation point─that is, the position at which a subsequent string must be drawn if it is to follow smoothly. The points on the borders of the parallelogram are considered to be within the parallelogram. Parameters hdc the engine's device context. cch the number of bytes in the character string. pch to the string of character code points. cptlTextBox the number of points to be retrieved in the array pointed to by aptlTextBox. If this value is TXT_COUNT, the function retrieves the maximum number of points for the text box. aptlTextBox to an array of POINTL structures to contain the points. The elements in this array are defined as follows: Value Meaning ──────────────────────────────────────────────────────────────────────────── TXTBOX_TOPLEFT Upper-left corner TXTBOX_BOTTOMLEFT Lower-left corner TXTBOX_TOPRIGHT Upper-left corner TXTBOX_BOTTOMRIGHT Lower-right corner TXTBOX_CONCAT Concatenation point hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine or the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine or the device driver calls record: PMERR_COORDINATE_OVERFLOW PMERR_DEV_FUNC_NOT_INSTALLED PMERR_EXCEEDS_MAX_SEG_LENGTH PMERR_HDC_BUSY PMERR_INSUFFICIENT_MEMORY PMERR_INV_CHAR_ANGLE_ATTR PMERR_INV_CHAR_MODE_ATTR PMERR_INV_CODEPAGE PMERR_INV_COORD_SPACE PMERR_INV_HDC PMERR_INV_LENGTH_OR_COUNT PMERR_INV_MATRIX_ELEMENT PMERR_INV_SETID PMERR_INV_TRANSFORM_TYPE Comments All coordinates are in world coordinates and are relative to the starting point of the string, as defined by the character direction. This function logs an error (PMERR_COORDINATE_OVERFLOW) if the operation cannot be performed because the matrix is singular. █ QueryViewportSize ──────────────────────────────────────────────────────────────────────────── BOOL QueryViewportSize (hdc, ulUnits, cvs, pvs, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ ULONG ulUnits; /*page units to be emulated */ LONG cvs; /*count of viewport sizes */ PVIEWPORTSIZE pvs; /*pointer to VIEWPORTSIZE structures */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The QueryViewportSize function calculates the viewport sizes (in page coordinates) that, for the specified window sizes, produce a window/viewport transformation that emulates the specified page units using the current page units. Parameters hdc Identifies the engine's device context. ulUnits Specifies the page units to be emulated. cvs Specifies the number of dimension pairs in the array pointed to by pvs. pvs Points to an array of VIEWPORTSIZE structures to contain the viewport dimensions. hddc Identifies the device driver's device context. ulFunN Specifies the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine or the device driver calls the WinSetErrorInfo function and records the associated error code. The following is a possible error code that the engine or the device driver calls record: PMERR_DEV_FUNC_NOT_INSTALLED Comment The QueryViewportSize function is not required for the first release of Presentation Manager. █ QueryWidthTable ──────────────────────────────────────────────────────────────────────────── BOOL QueryWidthTable (hdc, chFirst, cbWidthTable, alWidthTable, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ LONG chFirst; /*first character to be queried */ LONG cbWidthTable; /*count of widths */ PLONG alWidthTable; /*pointer to buffer for widths */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The QueryWidthTable function retrieves the character widths for the currently selected logical fonts, in world coordinates. Parameters hdc the engine's device context. chFirst the code point of the initial character for which width information is required. cbWidthTable the size, in bytes, of the buffer pointed to by the alWidthTable parameter. alWidthTable to a buffer in which the width data is retrieved. hddc the device driver's device context. ulFunN the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the graphics engine or the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the engine or the device driver calls record: PMERR_COORDINATE_OVERFLOW PMERR_DEV_FUNC_NOT_INSTALLED PMERR_EXCEEDS_MAX_SEG_LENGTH PMERR_HDC_BUSY PMERR_INSUFFICIENT_MEMORY PMERR_INV_CHAR_MODE_ATTR PMERR_INV_CODEPAGE PMERR_INV_COORD_SPACE PMERR_INV_FIRST_CHAR PMERR_INV_HDC PMERR_INV_LENGTH_OR_COUNT PMERR_INV_MATRIX_ELEMENT PMERR_INV_SETID PMERR_INV_TRANSFORM_TYPE Comment This function logs an error (PMERR_COORDINATE_OVERFLOW) if the operation cannot be performed because the matrix is singular. This function returns widths of zero for undefined code points. █ RealizeColorTable ──────────────────────────────────────────────────────────────────────────── BOOL RealizeColorTable (hdc, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The RealizeColorTable function sets the device's physical color table to the closest possible match to the logical color table. Parameters hdc Identifies the engine's device context. hddc Identifies the device driver's device context. ulFunN Specifies the function number and a mask of various flags. The low word contains the function number; the high word contains a mask of flags, which may be set by the graphics programming interface (GPI), the engine, or a driver. For a description of these flags, see Section 7.1.1. Return Value The return value is TRUE if the function is successful or FALSE if an error occurs. Errors If an error occurs during the execution of this function, the device driver calls the WinSetErrorInfo function and records the associated error code. The following list contains possible error codes that the device driver may record: PMERR_COL_TABLE_NOT_REALIZABLE PMERR_DEV_FUNC_NOT_INSTALLED PMERR_INV_HDC PMERR_INV_IN_AREA PMERR_INV_IN_PATH PMERR_REALIZE_NOT_SUPPORTED Comments If an attempt is made to realize a color table on a device that does not support the RealizeColorTable function, the function returns an error. A device such as a printer may implicitly realize the color table when the table is created. In this case, the RealizeColorTable function completes without error. █ RealizeFont ──────────────────────────────────────────────────────────────────────────── ULONG RealizeFont (hdc, flCmd, pfatLogFont, pfocaEngFont, hddc, ulFunN) HDC hdc; /*handle of engine's device context */ ULONG flCmd; /*options */ PFATTRS pfatLogFont; /*pointer to logical-font attributes */ PFOCAFONT pfocaEngFont; /*pointer to engine font */ ULONG hddc; /*handle of device driver's device context */ ULONG ulFunN; /*flags and function number */ The RealizeFont function realizes or deletes the specified font. Parameters hdc Identifies the engine's device context. flCmd Specifies the option. This value can be one of the following: Value Meaning ──────────────────────────────────────────────────────────────────────────── REALIZE_FONT Realize a matching device font. REALIZE_ENGINE_FONT Realize a device font using an engine