═══ 1. About this Book ═══ The Graphics Adapter Device Driver Reference for OS/2 Warp, Version 3, PowerPC Edition describes the Graphics Adapter Device Driver (GRADD) Model design, how the components work together, and why GRADDs are a valuable addition to OS/2 Warp, PowerPC Edition device-driver support. Note: THE INFORMATION IN THIS DOCUMENT IS A PRELIMINARY VERSION AND IS SUBJECT TO CHANGE. Detailed descriptions of control structures, data structures, and I/O formats have been included to help you understand and use the interfaces. Knowledge of a programming language (such as C or assembler) that is used for writing OS/2 applications is necessary, and you must be familiar with the workings of the OS/2 operating system. This book consists of seven chapters, with supporting appendixes, as follows: Introduction to Graphics Adapter Device Drivers This chapter briefly describes the design philosophy of the Graphics Adapter Device Driver (GRADD) Model. GRADD Model Components This chapter provides details on each of the components and how they work together within the GRADD Model. Video Manager This chapter contains a list of the Video Manager Interface functions, as well as a detailed description of each. Graphics Adapter Device Drivers This chapter describes the device driver interface (DDI) for a GRADD, as well as how and when adding extensions is useful. Also included is a list of the Graphics Hardware Interface functions and a detailed description of each. In addition, this chapter describes the Enhanced Direct Interface Video Extension (EnDIVE) functions. VIDEOPMI DLL Exported Functions This chapter describes the format and syntax of the file used to define the data necessary to set a video mode while in OS/2 Protect Mode. VIDEO Protect-Mode Interface This chapter discusses the purpose of the VIDEO Protect-Mode Interface (PMI) used in OS/2 Warp, PowerPC Edition. It is an extension of the VESA SVPMI standard currently in use by the operating system's base and virtual video subsystems. The PMI provides a means of setting Super VGA video modes while in Protect Mode and of enabling their virtualization in multiple DOS sessions. Video Installation and Configuration This chapter details the Video Configuration Manager (VCMAN), including the functions used to install and configure video adapters and monitors. Appendixes Appendix A. Syntax Conventions This appendix shows the conventions that have been used for the parameter names found in the data types included in Appendix B. Appendix B. Data Types This appendix contains a description of the parameters for all the data types called by the Video Manager Interface, the Graphics Hardware Interface, the Video Configuration Manager, or the Protect-Mode Interface. Appendix C. Notices This appendix contains legal notices. Miscellaneous A glossary and an index are included. ═══ 2. Notices ═══ First Edition (April 1995) The following paragraph does not apply to the United Kingdom or any country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you. This publication could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time. It is possible that this publication may contain reference to, or information about, IBM products (machines and programs), programming, or services that are not announced in your country. Such references or information must not be construed to mean that IBM intends to announce such IBM products, programming, or services in your country. Requests for technical information about IBM products should be made to your IBM authorized reseller or IBM marketing representative. ═══ 2.1. Copyright Notices ═══ COPYRIGHT LICENSE: This publication contains printed sample application programs in source language, which illustrate OS/2 programming techniques. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the OS/2 application programming interface. Each copy of any portion of these sample programs or any derivative work, which is distributed to others, must include a copyright notice as follows: "(C) (your company name) (year). All rights reserved." (C) Copyright International Business Machines Corporation 1995. All rights reserved. Note to U.S. Government Users - Documentation related to restricted rights - Use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp. ═══ 2.2. Disclaimers ═══ References in this publication to IBM products, programs, or services do not imply that IBM intends to make these available in all countries in which IBM operates. Any reference to an IBM product, program or service is not intended to state or imply that only IBM's product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any of IBM's intellectual property rights or other legally protectable rights may be used instead of the IBM product, program, or service. Evaluation and verification of operation in conjunction with other products, programs, or services, except those expressly designated by IBM, are the user's responsibility. IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to the IBM Director of Licensing, IBM Corporation, 500 Columbus Avenue, Thornwood NY 10594, U.S.A. ═══ 2.3. Trademarks ═══ The following terms are trademarks of the IBM Corporation in the United States or other countries: Common User Access CUA IBM Multimedia Presentation Manager/2 OS/2 OS/2 Warp Personal System/2 Presentation Manager SAA Systems Application Architecture WIN-OS/2 Workplace Shell XGA The following terms are trademarks of other companies: Trademark Owner ATI ATI Technologies, Inc. Cirrus Logic Cirrus Logic, Inc. MASM Microsoft Corporation PCMCIA Personal Computer Memory Card International Association S3 S3 Incorporated SVPMI Super VGA Protect Mode Interface VDM Geographics Systems, Ltd. VESA Video Electronics Standards Association Viper VLB Diamond Computer Systems, Inc. Weitek Weitek Corporation Windows is a trademark of Microsoft Corporation Other company, product, and service names, which may be denoted by a double asterisk (**), may be trademarks or service marks of others. ═══ 3. Introduction to Graphics Adapter Device Drivers ═══ This chapter briefly describes the design and intent of the Graphics Adapter Device Driver (GRADD) Model. Details on specific components of the GRADD Model are located in GRADD Model Components. The GRADD Model is divided into several components that work together to support a variety of operating system services for OS/2 Warp, Version 3, PowerPC Edition on the same desktop. (Operating system services are defined as "different operating systems running on top of the IBM Microkernel.") GRADD components include the following: o Video Manager and the Video Manager Interface (VMI) protocol o Translation layers, one for each operating system service in OS/2 Warp, PowerPC Edition o SOFTDRAW for default software simulation of graphics functions o Graphics Adapter Device Drivers (GRADDs) and the Graphics Hardware Interface (GHI) protocol Video display device drivers in OS/2 Warp, PowerPC Edition are referred to as GRADDs (Graphics Adapter Device Drivers). GRADDs provide video support to all the graphics subsystems (operating system services) that can run on OS/2 Warp, PowerPC Edition. A GRADD contains only the hardware-dependent code needed to do graphic functions that are common among the different graphics subsystems. These common functions are designed to act as a small set of building blocks for the larger, more complex operations that are typically required by a graphics engine. Translation layers exist between the graphics subsystems and the components of the GRADD Model, providing access to the GRADD building blocks. Each translation layer converts the more complex function calls given by its graphics subsystem into the protocol required by the GRADD Model. The GRADD Model makes the development of video display drivers much easier and faster than it was for OS/2 Releases 2.0 and earlier. This more efficient development cycle is a result of the reduced set of mandatory functions within a GRADD. Initialization, returning capabilities, returning mode information, setting the mode, and setting the palette (if using 256 colors) are the only mandatory GHI functions required for a GRADD Model device driver. If the graphics adapter supports direct access to video memory, all other GHI functions are not mandatory. The GRADD Model provides a way to simulate the drawing functions using a software library called SOFTDRAW. The simulated functions include drawing bit maps and lines and handling pointer support. Software simulation allows a developer to write a driver, in incremental stages, that takes advantage of hardware acceleration, rather than forcing the developer to write the entire driver at once. After the mandatory functions are completed, a developer can invoke the software simulation for those optional functions that have not yet been written to use the accelerated features of the hardware. When an optional function is handled by a GRADD, the results can be compared with the results of the software simulation. This comparison gives developers a way to ensure that their GRADDs are producing correct output. For most developers, writing code based on the GRADD Model will be confined exclusively to writing a GRADD. The other components handle commonly used functions that do not need direct access to the hardware and, therefore, do not need to be located in the GRADD. This design allows GRADDs to maintain a clean and simple architecture so that developers can write device drivers easily and quickly. ═══ 4. GRADD Model Components ═══ This chapter describes the individual components of the Graphics Adapter Device Driver (GRADD) Model used for developing device drivers. The GRADD Model is made up of several components that coordinate the communication between each of the running operating system services (graphic subsystems) and the available graphics hardware. The components include the following: o Video Manager (VMAN), the main component that ties all the components together in the GRADD model o Translation layers, each representing an OS/2 Warp, Version 3, PowerPC Edition operating system service o SOFTDRAW, which acts as a graphics library for VMAN and the system o One or more GRADDs that, together, represent the available video hardware Video Manager (VMAN): The main job of VMAN is to synchronize the communication between translation layers and a GRADD. VMAN also manages the graphics pointer. When an operating system service requests a graphics operation, the associated translation layer sends one of the defined Video Manager Interface (VMI) commands to VMAN. Upon receiving a VMI command, VMAN will either handle the request or send it down to the appropriate GRADD. Translation Layers: The translation layers convert function calls, made by the graphics engines of the various operating system services, to the VMI protocol required by VMAN. SOFTDRAW: When a GRADD requests that a drawing operation be simulated in software, VMAN can default to SOFTDRAW for the operation. Graphics Adapter Device Driver: Executes the requested operation or returns it for simulation. When a GRADD receives a GHI function call from VMAN that is not mandatory, the GRADD has the option of performing the requested operation or returning the request to VMAN with a return code of RC_SIMULATE. The RC_SIMULATE return code informs VMAN that the operation needs to be simulated in software. The following figure graphically illustrates the components of the GRADD Model. ═══ 4.1. Video Manager (VMAN) ═══ This section describes the Video Manager (VMAN) component and how it fits into the GRADD Model. When VMAN is initialized, a series of components is loaded and initialized. These components include SOFTDRAW and the GRADDs that are needed for the available graphics adapters. Each graphics adapter is not limited to a single GRADD, however. The GRADD Model supports multiple GRADDs. If a developer wishes to extend the GRADD Model or filter out operations, a filter GRADD can be placed between VMAN and the main GRADD running the hardware. This form of linking GRADDs is called chaining and provides a way of modifying a GRADD's behavior without rewriting and recompiling the GRADD. "Adding Extensions" in Graphics Adapter Device Drivers, discusses the specifics involved when extending the GRADD architecture. ═══ 4.1.1. Video Manager Interface (VMI) ═══ The VMAN component relies on a special protocol to receive requests from the translation layers. The VMAN protocol is called the Video Manager Interface (VMI) and consists of a small set of operations, each of which is identified by a unique function number. Separate function numbers are needed for each operation because VMAN exports only one entry point for the translation layers to communicate with VMAN. The exported function is called "VMIEntry." It expects four parameters from each function call it receives from a translation layer, as follows: ULONG VMIENTRY(GID gid, ULONG ulFunction, PVOID pIn, PVOID pOut); Because the VMIEntry function receives many different types of requests from the translation layers, the gid parameter is always the ID number of the GRADD to receive the operation. The ulFunction parameter is the function number that identifies the operation being requested. The last two parameters (pIn, pOut) are pointers to input and output data structures that are unique to each VMI function. Most of the operations VMAN receives from a translation layer are passed directly to the appropriate GRADD. Each GRADD has its own exported function called "HWEntry," which is the same function type as VMIEntry. The differences between the VMAN protocol (VMI) and the protocol for the GRADDs (GHI) include the following: o The VMI is a super set of the GHI. o The ulFunction parameter value changes to the appropriate VMI_CMD_ function name. ═══ 4.1.2. Pointer Management in the Video Manager ═══ VMAN is responsible for pointer management. When a pointer movement occurs, VMAN is notified via the VMI_CMD_MOVEPTR function. VMAN will call down the GRADD chain for the pointer update. The GRADD can either update the pointer or return to VMAN for simulation. If RC_SIMULATE is returned, VMAN will simulate the pointer movement by using the regular bitblit command. VMAN keeps information about the current state of the pointer. When a drawing operation arrives, VMAN will check to see if the pointer needs to be removed around the call. This situation typically arises when a software pointer is in use. All drawing VMI commands that affect the display surface must include the areas of the screen being updated by the primitive. VMAN uses this information to determine if the pointer needs to be hidden before passing the drawing command down the GRADD chain. Upon return from the drawing command, VMAN will restore the pointer if it was previously taken down. ═══ 4.1.3. Video Helper Functions ═══ VMAN exports two helper services for operations that are common across all GRADDs. These helper functions are described below. VHAllocMem: This helper returns a 32-bit pointer to a piece of memory. The caller of this function supplies the byte count required. The function prototype is displayed below: PVOID VHAllocMem( ULONG ); VHFreeMem: This helper frees memory that has been allocated via the VHAllocMem helper. The function prototype is displayed below: ULONG VHFreeMem( PVOID ); By using video helpers, a GRADD can be written without using calls that are operating-system specific. ═══ 4.2. Translation Layers ═══ This section describes the translation layers, which gain access to the hardware capabilities and available modes via the CHAININFO structure. The CHAININFO structure is returned from the VMI_CMD_QUERYCHAININFO function. When the VMIEntry function receives an operation from a translation layer, VMAN checks the function number and either handles the operation or forwards it to the appropriate GRADD. VMAN will handle the operation if the GRADD returns an RC_SIMULATE. The GRADD Model diagram shows how the VMAN component handles communication among the various components and the paths that commands can take during processing. ═══ 4.2.1. Translation Layer between OS/2 Graphics Engine and VMAN ═══ The translation layer for the OS/2 Graphics Engine (GRE) is called GRE2VMAN. For a system that uses OS/2 as the dominant operating system service, GRE2VMAN is the first translation layer and the first component of the GRADD model to be loaded. When GRE2VMAN is loaded, it calls VMAN's VMIEntry function with a VMI_CMD_INIT command. When VMAN receives a VMI_CMD_INIT for the first time, it loads the other GRADD model components. ═══ 4.2.2. Virtual VMI Video Device Driver (VVMI) ═══ The virtual VMI video device driver, referred to as VVMI, provides a mechanism for GDI2VMAN to call the video manager (VMAN). GDI2VMAN calls the VVMI by using the VMI protocol. The VVMI then calls VMAN directly on behalf of GDI2VMAN. VMAN, a shared library, exports a single entry point called VMIEntry. The VVMI imports VMIEntry and calls VMAN directly. ═══ 4.2.3. Future Translation Layers ═══ In the future, other graphics subsystems can be adapted to work in the OS/2 Warp, Version 3, PowerPC Edition operating system. In order to accomplish this, a translation layer must be provided (shown as 'n2VMAN' in the GRADD Model diagram. This translation layer must map the graphics primitives of the graphics subsystem to the appropriate VMI_CMD_ functions. ═══ 4.2.4. Translation Layer for Extensions ═══ The GRADD Model can be extended using the VMI extension protocol. Using this protocol, a translation layer directs extension functions to a GRADD via the VMI_CMD_EXTENSION function. In order to accomplish this, a translation layer must be provided (shown as 'EXT2VMAN' in the GRADD Model diagram. See Adding Extensions for more information. ═══ 4.3. SOFTDRAW ═══ This section describes the SOFTDRAW component. SOFTDRAW is the default for any simulated graphics functions for nonaccelerated graphics operations. SOFTDRAW exports base drawing functions (SDBitBlt and SDLINE) that are used by VMAN to simulate graphics operations. SOFTDRAW provides a generic graphics library. Given a pointer to a linear address (a VRAM bit map or system-memory bit map), SOFTDRAW can draw the bits directly into the bit map. ═══ 4.4. Graphics Adapter Device Driver (GRADD) ═══ This section describes the Graphics Adapter Device Driver component and how GRADDs interface with VMAN. ═══ 4.4.1. Graphics Hardware Interface (GHI) ═══ The entry point and functions supported by a GRADD are referred to as the Graphics Hardware Interface (GHI). The differences between the VMAN protocol (VMI) and the protocol for the GRADDs (GHI) include the following: o The GHI is a subset of the VMI. o The ulFunction parameter value changes to the appropriate GHI_CMD_ function name. Each GRADD has an exported function called "HWEntry," which is the same function type as VMIEntry in VMAN. ULONG HWENTRY(GID gid, ULONG ulFunction, PVOID pIn, PVOID pOut); HWEntry receives all of the operations from VMAN. For most systems, the GRADDs are the only components that access the video hardware. A GRADD contains the code that uses the accelerated features of a graphics adapter. If a GRADD returns RC_SIMULATE for a graphics operation, the GRADD is giving permission for the SOFTDRAW component to draw directly to the video memory of the hardware. The serialization of video memory is handled by the Video Manager via the GHI_CMD_REQUESTHW function. Each GRADD must process the following GHI_CMD_ functions: o GHI_CMD_INIT o GHI_CMD_QUERYCAPS o GHI_CMD_QUERYMODES o GHI_CMD_SETMODE o GHI_CMD_PALETTE * * This function is mandatory only when a 256-color mode has been chosen. The following GHI functions can return RC_SIMULATE and let VMAN handle the operations: o GHI_CMD_BITBLT o GHI_CMD_LINE o GHI_CMD_SETPTR o GHI_CMD_MOVEPTR o GHI_CMD_SHOWPTR The GHI function numbers are assigned in such a way that they can be used as a zero-based index into a function jump table. ═══ 4.4.2. Systems Management (RAS) ═══ Due to the performance-critical nature of the video graphics subsystem, all systems management and RAS hooks should be placed in a filter GRADD. This will ensure that the majority of users, who do not need this support, will not experience the performance degradations caused by the addition of trace points and hooks. ═══ 5. Video Manager ═══ This chapter describes the functions, called by the Video Manager, that are designated by the prefix VMI_CMD_. The following table lists those functions that have corresponding GHI_CMD_ functions in the Graphics Hardware Interface. Next, the Video Helper functions are listed; following that, in alphabetic order, each function is described in detail. ═══ 5.1. VMI_CMD_xx Functions Identical to GHI_CMD_xx Functions ═══ There are only a few differences between the VMAN protocol, Video Manager Interface (VMI), and the GRADD protocol, Graphics Hardware Interface (GHI). In fact, the majority of the functions are identical, with only the prefix (VMI or GHI) indicating to which component the function belongs. The common functions are as follows: ┌──────────────────────────────┬──────────────────────────────┐ │Video Manager Interface (VMI) │Graphics Hardware Interface │ │ │(GHI) │ ├──────────────────────────────┼──────────────────────────────┤ │VMI_CMD_BITBLT │GHI_CMD_BITBLT │ ├──────────────────────────────┼──────────────────────────────┤ │VMI_CMD_EVENT │GHI_CMD_EVENT │ ├──────────────────────────────┼──────────────────────────────┤ │VMI_CMD_EXTENSION │GHI_CMD_EXTENSION │ ├──────────────────────────────┼──────────────────────────────┤ │VMI_CMD_INIT │GHI_CMD_INIT │ ├──────────────────────────────┼──────────────────────────────┤ │VMI_CMD_INITPROC │GHI_CMD_INITPROC │ ├──────────────────────────────┼──────────────────────────────┤ │VMI_CMD_LINE │GHI_CMD_LINE │ ├──────────────────────────────┼──────────────────────────────┤ │VMI_CMD_MOVEPTR │GHI_CMD_MOVEPTR │ ├──────────────────────────────┼──────────────────────────────┤ │VMI_CMD_PALETTE │GHI_CMD_PALETTE │ ├──────────────────────────────┼──────────────────────────────┤ │VMI_CMD_QUERYCAPS │GHI_CMD_QUERYCAPS │ ├──────────────────────────────┼──────────────────────────────┤ │VMI_CMD_QUERYMODES │GHI_CMD_QUERYMODES │ ├──────────────────────────────┼──────────────────────────────┤ │VMI_CMD_REQUESTHW │GHI_CMD_REQUESTHW │ ├──────────────────────────────┼──────────────────────────────┤ │VMI_CMD_SETMODE │GHI_CMD_SETMODE │ ├──────────────────────────────┼──────────────────────────────┤ │VMI_CMD_SETPTR │GHI_CMD_SETPTR │ ├──────────────────────────────┼──────────────────────────────┤ │VMI_CMD_SHOWPTR │GHI_CMD_SHOWPTR │ ├──────────────────────────────┼──────────────────────────────┤ │VMI_CMD_TERM │GHI_CMD_TERM │ ├──────────────────────────────┼──────────────────────────────┤ │VMI_CMD_TERMPROC │GHI_CMD_TERMPROC │ ├──────────────────────────────┼──────────────────────────────┤ │VMI_CMD_VRAM │GHI_CMD_VRAM │ └──────────────────────────────┴──────────────────────────────┘ The only difference between the two types of functions (VMI_ and GHI_) is that the ulFunction parameter in VMIEntry and HWEntry points to the respective VMI_ or GHI_ function name. The Video Manager Interface functions are described in this chapter. Refer to Graphics Adapter Device Drivers for descriptions of the Graphics Hardware Interface functions and the EnDIVE functions. There is one function that is unique to VMAN and has no corresponding GHI function: VMI_CMD_QUERYCHAININFO. ═══ 5.2. Video Helper Functions ═══ The video helper functions are listed below: o VHAllocMem o VHFreeMem The remainder of this chapter contains a detailed description of each of the Video Helper and VMI functions. The functions are in alphabetic order by function name. ═══ 5.3. VHAllocMem ═══ ═══ VHAllocMem - Syntax ═══ /*******************************************/ /* Description: VHAllocMem returns a */ /* 32-bit pointer to a piece of memory. */ /* The caller of this function supplies */ /* the byte count required. This function */ /* is a helper service for operations that */ /* are common across all GRADDs. */ /*******************************************/ #include ULONG cBytes; /* Number of bytes of memory required. */ PVOID rc; /* Return codes. */ rc = VHAllocMem(cBytes); ═══ VHAllocMem Parameter - cBytes ═══ cBytes (ULONG) - input Number of bytes of memory required. Indicates the number of bytes of memory required for this allocation request. ═══ VHAllocMem Return Value - rc ═══ rc (PVOID) - returns Return codes. RC_SUCCESS Returns pointer to allocated memory. RC_ERROR Returns NULL pointer. ═══ VHAllocMem - Parameters ═══ cBytes (ULONG) - input Number of bytes of memory required. Indicates the number of bytes of memory required for this allocation request. rc (PVOID) - returns Return codes. RC_SUCCESS Returns pointer to allocated memory. RC_ERROR Returns NULL pointer. ═══ VHAllocMem - Remarks ═══ Memory is valid across all processes. ═══ VHAllocMem - Topics ═══ Select an item: Syntax Parameters Returns Remarks Glossary ═══ 5.4. VHFreeMem ═══ ═══ VHFreeMem - Syntax ═══ /*******************************************/ /* Description: VHFreeMem frees memory */ /* that has been allocated via the */ /* VHAllocMem helper. This function is a */ /* helper service for operations that are */ /* common across all GRADDs. */ /*******************************************/ #include PVOID cBytes; /* Pointer to previous memory allocation. */ ULONG rc; /* Return codes. */ rc = VHFreeMem(cBytes); ═══ VHFreeMem Parameter - cBytes ═══ cBytes (PVOID) - input Pointer to previous memory allocation. Pointer to memory previously allocated via VHAllocMem. ═══ VHFreeMem Return Value - rc ═══ rc (ULONG) - returns Return codes. RC_SUCCESS RC_ERROR ═══ VHFreeMem - Parameters ═══ cBytes (PVOID) - input Pointer to previous memory allocation. Pointer to memory previously allocated via VHAllocMem. rc (ULONG) - returns Return codes. RC_SUCCESS RC_ERROR ═══ VHFreeMem - Remarks ═══ None. ═══ VHFreeMem - Topics ═══ Select an item: Syntax Parameters Returns Remarks Glossary ═══ 5.5. VMI_CMD_BITBLT ═══ ═══ VMI_CMD_BITBLT - Syntax ═══ /*******************************************/ /* Description: VMI_CMD_BITBLT is called */ /* to blit a rectangle or series of */ /* rectangles to or from the video */ /* display. VMAN passes this command */ /* directly to the GRADD chain identified */ /* by the GRADD ID provided by the caller. */ /*******************************************/ #include GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to VMI_CMD_BITBLT. */ PVOID pIn; /* Pointer to a BITBLTINFO data structure. */ PVOID pOut; /* Null; no output structure needed. */ ULONG rc; /* Return codes. */ rc = VMIENTRY(gid, ulFunction, pIn, pOut); ═══ VMI_CMD_BITBLT Parameter - gid ═══ gid (GID) - input ID of the GRADD. ═══ VMI_CMD_BITBLT Parameter - ulFunction ═══ ulFunction (ULONG) - input Set equal to VMI_CMD_BITBLT. ═══ VMI_CMD_BITBLT Parameter - pIn ═══ pIn (PVOID) - input Pointer to a BITBLTINFO data structure. ═══ VMI_CMD_BITBLT Parameter - pOut ═══ pOut (PVOID) - output Null; no output structure needed. ═══ VMI_CMD_BITBLT Return Value - rc ═══ rc (ULONG) - returns Return codes. RC_SUCCESS RC_ERROR ═══ VMI_CMD_BITBLT - Parameters ═══ gid (GID) - input ID of the GRADD. ulFunction (ULONG) - input Set equal to VMI_CMD_BITBLT. pIn (PVOID) - input Pointer to a BITBLTINFO data structure. pOut (PVOID) - output Null; no output structure needed. rc (ULONG) - returns Return codes. RC_SUCCESS RC_ERROR ═══ VMI_CMD_BITBLT - Remarks ═══ None. ═══ VMI_CMD_BITBLT - Topics ═══ Select an item: Syntax Parameters Returns Remarks Glossary ═══ 5.6. VMI_CMD_EVENT ═══ ═══ VMI_CMD_EVENT - Syntax ═══ /*******************************************/ /* Description: VMI_CMD_EVENT is called */ /* to notify a GRADD of specific events. */ /* VMAN sends this command directly to the */ /* GRADD chain identified by the GRADD ID. */ /*******************************************/ #include GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to VMI_CMD_EVENT. */ PVOID pIn; /* Pointer to an HWEVENTIN data structure. */ PVOID pOut; /* NULL; no output structure needed. */ ULONG rc; /* Return codes. */ rc = VMIENTRY(gid, ulFunction, pIn, pOut); ═══ VMI_CMD_EVENT Parameter - gid ═══ gid (GID) - input ID of the GRADD. ═══ VMI_CMD_EVENT Parameter - ulFunction ═══ ulFunction (ULONG) - input Set equal to VMI_CMD_EVENT. ═══ VMI_CMD_EVENT Parameter - pIn ═══ pIn (PVOID) - input Pointer to an HWEVENTIN data structure. ═══ VMI_CMD_EVENT Parameter - pOut ═══ pOut (PVOID) - output NULL; no output structure needed. ═══ VMI_CMD_EVENT Return Value - rc ═══ rc (ULONG) - returns Return codes. RC_UNSUPPORTED RC_SUCCESS ═══ VMI_CMD_EVENT - Parameters ═══ gid (GID) - input ID of the GRADD. ulFunction (ULONG) - input Set equal to VMI_CMD_EVENT. pIn (PVOID) - input Pointer to an HWEVENTIN data structure. pOut (PVOID) - output NULL; no output structure needed. rc (ULONG) - returns Return codes. RC_UNSUPPORTED RC_SUCCESS ═══ VMI_CMD_EVENT - Remarks ═══ None. ═══ VMI_CMD_EVENT - Topics ═══ Select an item: Syntax Parameters Returns Remarks Glossary ═══ 5.7. VMI_CMD_EXTENSION ═══ ═══ VMI_CMD_EXTENSION - Syntax ═══ /*******************************************/ /* Description: VMI_CMD_EXTENSION is */ /* called to send an extension command to */ /* a GRADD. VMAN sends this command */ /* directly to the GRADD chain identified */ /* by the GRADD ID provided by the caller. */ /*******************************************/ #include GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to VMI_CMD_EXTENSION. */ PVOID pIn; /* Pointer to an HWEXTENSION data structure. */ PVOID pOut; /* Pointer to an extension-specific output structure. */ ULONG rc; /* Return codes. */ rc = VMIENTRY(gid, ulFunction, pIn, pOut); ═══ VMI_CMD_EXTENSION Parameter - gid ═══ gid (GID) - input ID of the GRADD. ═══ VMI_CMD_EXTENSION Parameter - ulFunction ═══ ulFunction (ULONG) - input Set equal to VMI_CMD_EXTENSION. ═══ VMI_CMD_EXTENSION Parameter - pIn ═══ pIn (PVOID) - input Pointer to an HWEXTENSION data structure. ═══ VMI_CMD_EXTENSION Parameter - pOut ═══ pOut (PVOID) - output Pointer to an extension-specific output structure. ═══ VMI_CMD_EXTENSION Return Value - rc ═══ rc (ULONG) - returns Return codes. RC_UNSUPPORTED RC_SUCCESS RC_ERROR ═══ VMI_CMD_EXTENSION - Parameters ═══ gid (GID) - input ID of the GRADD. ulFunction (ULONG) - input Set equal to VMI_CMD_EXTENSION. pIn (PVOID) - input Pointer to an HWEXTENSION data structure. pOut (PVOID) - output Pointer to an extension-specific output structure. rc (ULONG) - returns Return codes. RC_UNSUPPORTED RC_SUCCESS RC_ERROR ═══ VMI_CMD_EXTENSION - Remarks ═══ None. ═══ VMI_CMD_EXTENSION - Topics ═══ Select an item: Syntax Parameters Returns Remarks Glossary ═══ 5.8. VMI_CMD_INIT ═══ ═══ VMI_CMD_INIT - Syntax ═══ /*******************************************/ /* Description: VMI_CMD_INIT informs the */ /* Video Manager (VMAN) that a translation */ /* layer has been loaded and that VMAN may */ /* need to be initialized. VMAN */ /* initializes itself once only; */ /* subsequent VMI_CMD_INIT calls are */ /* ignored. During the first */ /* initialization, VMAN loads SOFTDRAW and */ /* all of the GRADDs specified by the */ /* environment variables. */ /*******************************************/ #include GID gid; /* NULL. */ ULONG ulFunction; /* Set equal to VMI_CMD_INIT. */ PVOID pIn; /* NULL. */ PVOID pOut; /* NULL. */ ULONG rc; /* Return codes. */ rc = VMIEntry(gid, ulFunction, pIn, pOut); ═══ VMI_CMD_INIT Parameter - gid ═══ gid (GID) - input NULL. ═══ VMI_CMD_INIT Parameter - ulFunction ═══ ulFunction (ULONG) - input Set equal to VMI_CMD_INIT. ═══ VMI_CMD_INIT Parameter - pIn ═══ pIn (PVOID) - input NULL. ═══ VMI_CMD_INIT Parameter - pOut ═══ pOut (PVOID) - output NULL. ═══ VMI_CMD_INIT Return Value - rc ═══ rc (ULONG) - returns Return codes. RC_SUCCESS RC_ERROR ═══ VMI_CMD_INIT - Parameters ═══ gid (GID) - input NULL. ulFunction (ULONG) - input Set equal to VMI_CMD_INIT. pIn (PVOID) - input NULL. pOut (PVOID) - output NULL. rc (ULONG) - returns Return codes. RC_SUCCESS RC_ERROR ═══ VMI_CMD_INIT - Remarks ═══ None. ═══ VMI_CMD_INIT - Topics ═══ Select an item: Syntax Parameters Returns Remarks Glossary ═══ 5.9. VMI_CMD_INITPROC ═══ ═══ VMI_CMD_INITPROC - Syntax ═══ /*******************************************/ /* Description: VMI_CMD_INITPROC informs */ /* VMAN that a new process is being */ /* initialized. It indicates that this new */ /* process intends to be a client of the */ /* VMAN component. VMAN ensures that all */ /* data and code is valid under this new */ /* process. */ /*******************************************/ #include GID gid; /* NULL. */ ULONG ulFunction; /* Set equal to VMI_CMD_INITPROC. */ PVOID pIn; /* NULL. */ PVOID pOut; /* Pointer to an INITPROCOUT data structure. */ ULONG rc; /* Return codes. */ rc = VMIEntry(gid, ulFunction, pIn, pOut); ═══ VMI_CMD_INITPROC Parameter - gid ═══ gid (GID) - input NULL. ═══ VMI_CMD_INITPROC Parameter - ulFunction ═══ ulFunction (ULONG) - input Set equal to VMI_CMD_INITPROC. ═══ VMI_CMD_INITPROC Parameter - pIn ═══ pIn (PVOID) - input NULL. ═══ VMI_CMD_INITPROC Parameter - pOut ═══ pOut (PVOID) - output Pointer to an INITPROCOUT data structure. ═══ VMI_CMD_INITPROC Return Value - rc ═══ rc (ULONG) - returns Return codes. RC_SUCCESS RC_ERROR ═══ VMI_CMD_INITPROC - Parameters ═══ gid (GID) - input NULL. ulFunction (ULONG) - input Set equal to VMI_CMD_INITPROC. pIn (PVOID) - input NULL. pOut (PVOID) - output Pointer to an INITPROCOUT data structure. rc (ULONG) - returns Return codes. RC_SUCCESS RC_ERROR ═══ VMI_CMD_INITPROC - Remarks ═══ None. ═══ VMI_CMD_INITPROC - Topics ═══ Select an item: Syntax Parameters Returns Remarks Glossary ═══ 5.10. VMI_CMD_LINE ═══ ═══ VMI_CMD_LINE - Syntax ═══ /*******************************************/ /* Description: VMI_CMD_LINE is called to */ /* draw a line to the video display. VMAN */ /* sends this command directly to the */ /* GRADD chain identified by the GRADD ID */ /* provided by the caller. */ /*******************************************/ #include GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to VMI_CMD_LINE. */ PVOID pIn; /* Pointer to a LINEINFO data structure. */ PVOID pOut; /* NULL; no output structure is needed. */ ULONG rc; /* Return codes. */ rc = VMIENTRY(gid, ulFunction, pIn, pOut); ═══ VMI_CMD_LINE Parameter - gid ═══ gid (GID) - input ID of the GRADD. ═══ VMI_CMD_LINE Parameter - ulFunction ═══ ulFunction (ULONG) - input Set equal to VMI_CMD_LINE. ═══ VMI_CMD_LINE Parameter - pIn ═══ pIn (PVOID) - input Pointer to a LINEINFO data structure. ═══ VMI_CMD_LINE Parameter - pOut ═══ pOut (PVOID) - output NULL; no output structure is needed. ═══ VMI_CMD_LINE Return Value - rc ═══ rc (ULONG) - returns Return codes. RC_SUCCESS RC_ERROR ═══ VMI_CMD_LINE - Parameters ═══ gid (GID) - input ID of the GRADD. ulFunction (ULONG) - input Set equal to VMI_CMD_LINE. pIn (PVOID) - input Pointer to a LINEINFO data structure. pOut (PVOID) - output NULL; no output structure is needed. rc (ULONG) - returns Return codes. RC_SUCCESS RC_ERROR ═══ VMI_CMD_LINE - Remarks ═══ None. ═══ VMI_CMD_LINE - Topics ═══ Select an item: Syntax Parameters Returns Remarks Glossary ═══ 5.11. VMI_CMD_MOVPTR ═══ ═══ VMI_CMD_MOVPTR - Syntax ═══ /*******************************************/ /* Description: VMI_CMD_MOVPTR is called */ /* to change the position of the pointer */ /* hot spot. VMAN sends this command */ /* directly to the GRADD chain identified */ /* by the GRADD ID provided by the caller. */ /*******************************************/ #include GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to VMI_CMD_MOVPTR. */ PVOID pIn; /* Pointer to an HWMOVEPTRIN data structure. */ PVOID pOut; /* NULL; no output structure is needed. */ ULONG rc; /* Return codes. */ rc = VMIENTRY(gid, ulFunction, pIn, pOut); ═══ VMI_CMD_MOVPTR Parameter - gid ═══ gid (GID) - input ID of the GRADD. ═══ VMI_CMD_MOVPTR Parameter - ulFunction ═══ ulFunction (ULONG) - input Set equal to VMI_CMD_MOVPTR. ═══ VMI_CMD_MOVPTR Parameter - pIn ═══ pIn (PVOID) - input Pointer to an HWMOVEPTRIN data structure. ═══ VMI_CMD_MOVPTR Parameter - pOut ═══ pOut (PVOID) - output NULL; no output structure is needed. ═══ VMI_CMD_MOVPTR Return Value - rc ═══ rc (ULONG) - returns Return codes. RC_SUCCESS RC_ERROR ═══ VMI_CMD_MOVPTR - Parameters ═══ gid (GID) - input ID of the GRADD. ulFunction (ULONG) - input Set equal to VMI_CMD_MOVPTR. pIn (PVOID) - input Pointer to an HWMOVEPTRIN data structure. pOut (PVOID) - output NULL; no output structure is needed. rc (ULONG) - returns Return codes. RC_SUCCESS RC_ERROR ═══ VMI_CMD_MOVPTR - Remarks ═══ None. ═══ VMI_CMD_MOVPTR - Topics ═══ Select an item: Syntax Parameters Returns Remarks Glossary ═══ 5.12. VMI_CMD_PALETTE ═══ ═══ VMI_CMD_PALETTE - Syntax ═══ /*******************************************/ /* Description: VMI_CMD_PALETTE is */ /* mandatory if the device supports */ /* 256-color mode. This function is */ /* called to query or set the hardware */ /* color palette. VMAN sends this command */ /* directly to the GRADD chain identified */ /* by the GRADD ID provided by the */ /* caller. The GRADD is expected to */ /* respond by describing the palettte in a */ /* given array or by using the palette */ /* given in the array. The GRADD is always */ /* given an HWPALETTEINFO structure with */ /* either the PALETTE_GET or PALETTE_SET */ /* flag to specifiy the operation to */ /* perform. */ /*******************************************/ #include GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to VMI_CMD_PALETTE. */ PVOID pIn; /* Pointer to an HWPALETTEINFO data structure. */ PVOID pOut; /* Depends on value of pIn. */ ULONG rc; /* Return codes. */ rc = VMIENTRY(gid, ulFunction, pIn, pOut); ═══ VMI_CMD_PALETTE Parameter - gid ═══ gid (GID) - input ID of the GRADD. ═══ VMI_CMD_PALETTE Parameter - ulFunction ═══ ulFunction (ULONG) - input Set equal to VMI_CMD_PALETTE. ═══ VMI_CMD_PALETTE Parameter - pIn ═══ pIn (PVOID) - input Pointer to an HWPALETTEINFO data structure. ═══ VMI_CMD_PALETTE Parameter - pOut ═══ pOut (PVOID) - output Depends on value of pIn. If '_SET' is specified by pIn, pOut If '_GET' is specified by pIn, pOut is a pointer to an HWPALETTEINFO data structure. ═══ VMI_CMD_PALETTE Return Value - rc ═══ rc (ULONG) - returns Return codes. RC_SUCCESS RC_ERROR ═══ VMI_CMD_PALETTE - Parameters ═══ gid (GID) - input ID of the GRADD. ulFunction (ULONG) - input Set equal to VMI_CMD_PALETTE. pIn (PVOID) - input Pointer to an HWPALETTEINFO data structure. pOut (PVOID) - output Depends on value of pIn. If '_SET' is specified by pIn, pOut If '_GET' is specified by pIn, pOut is a pointer to an HWPALETTEINFO data structure. rc (ULONG) - returns Return codes. RC_SUCCESS RC_ERROR ═══ VMI_CMD_PALETTE - Remarks ═══ None. ═══ VMI_CMD_PALETTE - Topics ═══ Select an item: Syntax Parameters Returns Remarks Glossary ═══ 5.13. VMI_CMD_QUERYCAPS ═══ ═══ VMI_CMD_QUERYCAPS - Syntax ═══ /*******************************************/ /* Description: VMI_CMD_QUERYCAPS returns */ /* the capabilities of a particular */ /* GRADD. VMAN sends this command directly */ /* to the GRADD chain identified by the */ /* GRADD ID provided by the caller. */ /* VMI_CMD_QUERYCAPS is not typically used */ /* by translation layers because the */ /* VMI_CMD_QUERYCHAININFO function returns */ /* the capabilities of all GRADDs, as */ /* opposed to just one. */ /* VMI_CMD_QUERYCHAININFO is the */ /* recommended way of querying the */ /* capabilities of all GRADDs in the */ /* system. */ /*******************************************/ #include GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to VMI_CMD_QUERYCAPS. */ PVOID pIn; /* NULL. */ PVOID pOut; /* Pointer to a VMIQCI data structure. */ ULONG rc; /* Return codes. */ rc = VMIENTRY(gid, ulFunction, pIn, pOut); ═══ VMI_CMD_QUERYCAPS Parameter - gid ═══ gid (GID) - input ID of the GRADD. ═══ VMI_CMD_QUERYCAPS Parameter - ulFunction ═══ ulFunction (ULONG) - input Set equal to VMI_CMD_QUERYCAPS. ═══ VMI_CMD_QUERYCAPS Parameter - pIn ═══ pIn (PVOID) - input NULL. ═══ VMI_CMD_QUERYCAPS Parameter - pOut ═══ pOut (PVOID) - output Pointer to a VMIQCI data structure. ═══ VMI_CMD_QUERYCAPS Return Value - rc ═══ rc (ULONG) - returns Return codes. RC_SUCCESS RC_ERROR ═══ VMI_CMD_QUERYCAPS - Parameters ═══ gid (GID) - input ID of the GRADD. ulFunction (ULONG) - input Set equal to VMI_CMD_QUERYCAPS. pIn (PVOID) - input NULL. pOut (PVOID) - output Pointer to a VMIQCI data structure. rc (ULONG) - returns Return codes. RC_SUCCESS RC_ERROR ═══ VMI_CMD_QUERYCAPS - Remarks ═══ None. ═══ VMI_CMD_QUERYCAPS - Topics ═══ Select an item: Syntax Parameters Returns Remarks Glossary ═══ 5.14. VMI_CMD_QUERYCHAININFO ═══ ═══ VMI_CMD_QUERYCHAININFO - Syntax ═══ /*******************************************/ /* Description: VMI_CMD_QUERYCHAININFO is */ /* unique to VMAN (there is no */ /* corresponding function in the Graphics */ /* Hardware Interface). This function is */ /* called to obtain a pointer to the video */ /* chain information, which contains */ /* information about every GRADD currently */ /* loaded. Each GRADDINFO structure */ /* contains information, such as */ /* capabilities and mode information, for */ /* a single GRADD. The CHAININFO structure */ /* contains a pointer to a linked list of */ /* GRADDINFO structures. If multiple GRADD */ /* chains are in use, the head CHAININFO */ /* structure contains a pointer to the */ /* next CHAININFO structure. */ /*******************************************/ #include GID gid; /* NULL. */ ULONG ulFunction; /* Set equal to VMI_CMD_QUERYCHAININFO. */ PVOID pIn; /* NULL. */ PVOID pOut; /* Pointer to a VMIQCI data structure. */ ULONG rc; /* Return codes. */ rc = VMIEntry(gid, ulFunction, pIn, pOut); ═══ VMI_CMD_QUERYCHAININFO Parameter - gid ═══ gid (GID) - input NULL. ═══ VMI_CMD_QUERYCHAININFO Parameter - ulFunction ═══ ulFunction (ULONG) - input Set equal to VMI_CMD_QUERYCHAININFO. ═══ VMI_CMD_QUERYCHAININFO Parameter - pIn ═══ pIn (PVOID) - input NULL. ═══ VMI_CMD_QUERYCHAININFO Parameter - pOut ═══ pOut (PVOID) - output Pointer to a VMIQCI data structure. ═══ VMI_CMD_QUERYCHAININFO Return Value - rc ═══ rc (ULONG) - returns Return codes. RC_SUCCESS RC_ERROR ═══ VMI_CMD_QUERYCHAININFO - Parameters ═══ gid (GID) - input NULL. ulFunction (ULONG) - input Set equal to VMI_CMD_QUERYCHAININFO. pIn (PVOID) - input NULL. pOut (PVOID) - output Pointer to a VMIQCI data structure. rc (ULONG) - returns Return codes. RC_SUCCESS RC_ERROR ═══ VMI_CMD_QUERYCHAININFO - Remarks ═══ None. ═══ VMI_CMD_QUERYCHAININFO - Topics ═══ Select an item: Syntax Parameters Returns Remarks Glossary ═══ 5.15. VMI_CMD_QUERYMODES ═══ ═══ VMI_CMD_QUERYMODES - Syntax ═══ /*******************************************/ /* Description: VMI_CMD_QUERYMODES */ /* returns video mode information for a */ /* particular GRADD. VMAN passes this */ /* command directly to the GRADD chain */ /* identified by the GRADD ID provided by */ /* the caller. VMI_CMD_QUERYMODES is not */ /* typically used by translation layers */ /* because the VMI_CMD_QUERYCHAININFO */ /* function returns the capabilities of */ /* all GRADDs, as opposed to just one. */ /* VMI_CMD_QUERYCHAININFO is the */ /* recommended way of querying the */ /* available modes of all GRADDs in the */ /* system. */ /*******************************************/ #include GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to VMI_CMD_QUERYMODES. */ PVOID pIn; /* Pointer that identifies a QUERYMODE operation. */ PVOID pOut; /* Pointer to the pIn operation. */ ULONG rc; /* Return codes. */ rc = VMIEntry(gid, ulFunction, pIn, pOut); ═══ VMI_CMD_QUERYMODES Parameter - gid ═══ gid (GID) - input ID of the GRADD. ═══ VMI_CMD_QUERYMODES Parameter - ulFunction ═══ ulFunction (ULONG) - input Set equal to VMI_CMD_QUERYMODES. ═══ VMI_CMD_QUERYMODES Parameter - pIn ═══ pIn (PVOID) - input Pointer that identifies a QUERYMODE operation. This pointer identifies one of the following operations: QUERYMODE_NUM_MODES QUERYMODE_MODE_DATA ═══ VMI_CMD_QUERYMODES Parameter - pOut ═══ pOut (PVOID) - output Pointer to the pIn operation. This pointer indicates one of the following, depending on the value of pIn: QUERYMODE_NUM_MODES Indicates a pointer to a ULONG containing the number of supported modes. QUERYMODE_MODE_DATA Indicates a pointer to an array of GDDMODEINFO structures large enough for the number of supported modes. ═══ VMI_CMD_QUERYMODES Return Value - rc ═══ rc (ULONG) - returns Return codes. RC_SUCCESS RC_ERROR ═══ VMI_CMD_QUERYMODES - Parameters ═══ gid (GID) - input ID of the GRADD. ulFunction (ULONG) - input Set equal to VMI_CMD_QUERYMODES. pIn (PVOID) - input Pointer that identifies a QUERYMODE operation. This pointer identifies one of the following operations: QUERYMODE_NUM_MODES QUERYMODE_MODE_DATA pOut (PVOID) - output Pointer to the pIn operation. This pointer indicates one of the following, depending on the value of pIn: QUERYMODE_NUM_MODES Indicates a pointer to a ULONG containing the number of supported modes. QUERYMODE_MODE_DATA Indicates a pointer to an array of GDDMODEINFO structures large enough for the number of supported modes. rc (ULONG) - returns Return codes. RC_SUCCESS RC_ERROR ═══ VMI_CMD_QUERYMODES - Remarks ═══ None. ═══ VMI_CMD_QUERYMODES - Topics ═══ Select an item: Syntax Parameters Returns Remarks Glossary ═══ 5.16. VMI_CMD_REQUESTHW ═══ ═══ VMI_CMD_REQUESTHW - Syntax ═══ /*******************************************/ /* Description: VMI_CMD_REQUESTHW is */ /* called to request access to the video */ /* hardware. VMAN processes this command */ /* and sends a GHI_CMD_REQUESTHW call to */ /* the GRADD chain identified by the GRADD */ /* ID provided by the caller. */ /*******************************************/ #include GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to VMI_CMD_REQUESTHW. */ PVOID pIn; /* Pointer to an HWREQIN data structure. */ PVOID pOut; /* NULL; no output structure is needed. */ ULONG rc; /* Return codes. */ rc = VMIENTRY(gid, ulFunction, pIn, pOut); ═══ VMI_CMD_REQUESTHW Parameter - gid ═══ gid (GID) - input ID of the GRADD. ═══ VMI_CMD_REQUESTHW Parameter - ulFunction ═══ ulFunction (ULONG) - input Set equal to VMI_CMD_REQUESTHW. ═══ VMI_CMD_REQUESTHW Parameter - pIn ═══ pIn (PVOID) - input Pointer to an HWREQIN data structure. ═══ VMI_CMD_REQUESTHW Parameter - pOut ═══ pOut (PVOID) - output NULL; no output structure is needed. ═══ VMI_CMD_REQUESTHW Return Value - rc ═══ rc (ULONG) - returns Return codes. RC_SUCCESS RC_ERROR ═══ VMI_CMD_REQUESTHW - Parameters ═══ gid (GID) - input ID of the GRADD. ulFunction (ULONG) - input Set equal to VMI_CMD_REQUESTHW. pIn (PVOID) - input Pointer to an HWREQIN data structure. pOut (PVOID) - output NULL; no output structure is needed. rc (ULONG) - returns Return codes. RC_SUCCESS RC_ERROR ═══ VMI_CMD_REQUESTHW - Remarks ═══ None. ═══ VMI_CMD_REQUESTHW - Topics ═══ Select an item: Syntax Parameters Returns Remarks Glossary ═══ 5.17. VMI_CMD_SETMODE ═══ ═══ VMI_CMD_SETMODE - Syntax ═══ /*******************************************/ /* Description: VMI_CMD_SETMODE sets the */ /* video display adapter to a given mode. */ /* VMAN passes this command directly to */ /* the GRADD chain identified by the GRADD */ /* ID provided by the caller. The GRADD is */ /* expected to set the video mode, given */ /* an ID of the chosen mode. */ /*******************************************/ #include GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to VMI_CMD_SETMODE. */ PVOID pIn; /* Pointer to PULONG containing the ID of the requested mode. */ PVOID pOut; /* NULL. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunction, pIn, pOut); ═══ VMI_CMD_SETMODE Parameter - gid ═══ gid (GID) - input ID of the GRADD. ═══ VMI_CMD_SETMODE Parameter - ulFunction ═══ ulFunction (ULONG) - input Set equal to VMI_CMD_SETMODE. ═══ VMI_CMD_SETMODE Parameter - pIn ═══ pIn (PVOID) - input Pointer to PULONG containing the ID of the requested mode. ═══ VMI_CMD_SETMODE Parameter - pOut ═══ pOut (PVOID) - output NULL. ═══ VMI_CMD_SETMODE Return Value - rc ═══ rc (ULONG) - returns Return codes. RC_SUCCESS RC_ERROR ═══ VMI_CMD_SETMODE - Parameters ═══ gid (GID) - input ID of the GRADD. ulFunction (ULONG) - input Set equal to VMI_CMD_SETMODE. pIn (PVOID) - input Pointer to PULONG containing the ID of the requested mode. pOut (PVOID) - output NULL. rc (ULONG) - returns Return codes. RC_SUCCESS RC_ERROR ═══ VMI_CMD_SETMODE - Remarks ═══ None. ═══ VMI_CMD_SETMODE - Topics ═══ Select an item: Syntax Parameters Returns Remarks Glossary ═══ 5.18. VMI_CMD_SETPTR ═══ ═══ VMI_CMD_SETPTR - Syntax ═══ /*******************************************/ /* Description: VMI_CMD_SETPTR sets the */ /* pointer AND,XOR masks. VMAN sends this */ /* command to the GRADD chain identified */ /* by the GRADD ID provided by the caller. */ /*******************************************/ #include GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to VMI_CMD_SETPTR. */ PVOID pIn; /* Pointer to an HWSETPTRIN data structure. */ PVOID pOut; /* Pointer to an HWSETPTROUT data structure. */ ULONG rc; /* Return codes. */ rc = VMIENTRY(gid, ulFunction, pIn, pOut); ═══ VMI_CMD_SETPTR Parameter - gid ═══ gid (GID) - input ID of the GRADD. ═══ VMI_CMD_SETPTR Parameter - ulFunction ═══ ulFunction (ULONG) - input Set equal to VMI_CMD_SETPTR. ═══ VMI_CMD_SETPTR Parameter - pIn ═══ pIn (PVOID) - input Pointer to an HWSETPTRIN data structure. ═══ VMI_CMD_SETPTR Parameter - pOut ═══ pOut (PVOID) - output Pointer to an HWSETPTROUT data structure. ═══ VMI_CMD_SETPTR Return Value - rc ═══ rc (ULONG) - returns Return codes. RC_SUCCESS RC_ERROR ═══ VMI_CMD_SETPTR - Parameters ═══ gid (GID) - input ID of the GRADD. ulFunction (ULONG) - input Set equal to VMI_CMD_SETPTR. pIn (PVOID) - input Pointer to an HWSETPTRIN data structure. pOut (PVOID) - output Pointer to an HWSETPTROUT data structure. rc (ULONG) - returns Return codes. RC_SUCCESS RC_ERROR ═══ VMI_CMD_SETPTR - Remarks ═══ None. ═══ VMI_CMD_SETPTR - Topics ═══ Select an item: Syntax Parameters Returns Remarks Glossary ═══ 5.19. VMI_CMD_SHOWPTR ═══ ═══ VMI_CMD_SHOWPTR - Syntax ═══ /*******************************************/ /* Description: VMI_CMD_SHOWPTR sets the */ /* visibility state of the pointer. VMAN */ /* sends this command to the GRADD chain */ /* identified by the GRADD ID provided by */ /* the caller. */ /*******************************************/ #include GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to VMI_CMD_SHOWPTR. */ PVOID pIn; /* Pointer to an HWSHOWPTRIN data structure. */ PVOID pOut; /* NULL; no output structure needed. */ ULONG rc; /* Return codes. */ rc = VMIENTRY(gid, ulFunction, pIn, pOut); ═══ VMI_CMD_SHOWPTR Parameter - gid ═══ gid (GID) - input ID of the GRADD. ═══ VMI_CMD_SHOWPTR Parameter - ulFunction ═══ ulFunction (ULONG) - input Set equal to VMI_CMD_SHOWPTR. ═══ VMI_CMD_SHOWPTR Parameter - pIn ═══ pIn (PVOID) - input Pointer to an HWSHOWPTRIN data structure. ═══ VMI_CMD_SHOWPTR Parameter - pOut ═══ pOut (PVOID) - output NULL; no output structure needed. ═══ VMI_CMD_SHOWPTR Return Value - rc ═══ rc (ULONG) - returns Return codes. RC_SUCCESS RC_ERROR ═══ VMI_CMD_SHOWPTR - Parameters ═══ gid (GID) - input ID of the GRADD. ulFunction (ULONG) - input Set equal to VMI_CMD_SHOWPTR. pIn (PVOID) - input Pointer to an HWSHOWPTRIN data structure. pOut (PVOID) - output NULL; no output structure needed. rc (ULONG) - returns Return codes. RC_SUCCESS RC_ERROR ═══ VMI_CMD_SHOWPTR - Remarks ═══ None. ═══ VMI_CMD_SHOWPTR - Topics ═══ Select an item: Syntax Parameters Returns Remarks Glossary ═══ 5.20. VMI_CMD_TERM ═══ ═══ VMI_CMD_TERM - Syntax ═══ /*******************************************/ /* Description: VMI_CMD_TERM informs VMAN */ /* that an existing client process is */ /* being terminated. */ /*******************************************/ #include GID gid; /* NULL; parameter ignored by VMAN. */ ULONG ulFunction; /* Set equal to VMI_CMD_TERM. */ PVOID pIn; /* NULL. */ PVOID pOut; /* NULL. */ ULONG rc; /* Return codes. */ rc = VMIENTRY(gid, ulFunction, pIn, pOut); ═══ VMI_CMD_TERM Parameter - gid ═══ gid (GID) - input NULL; parameter ignored by VMAN. ═══ VMI_CMD_TERM Parameter - ulFunction ═══ ulFunction (ULONG) - input Set equal to VMI_CMD_TERM. ═══ VMI_CMD_TERM Parameter - pIn ═══ pIn (PVOID) - input NULL. ═══ VMI_CMD_TERM Parameter - pOut ═══ pOut (PVOID) - output NULL. ═══ VMI_CMD_TERM Return Value - rc ═══ rc (ULONG) - returns Return codes. RC_SUCCESS RC_ERROR ═══ VMI_CMD_TERM - Parameters ═══ gid (GID) - input NULL; parameter ignored by VMAN. ulFunction (ULONG) - input Set equal to VMI_CMD_TERM. pIn (PVOID) - input NULL. pOut (PVOID) - output NULL. rc (ULONG) - returns Return codes. RC_SUCCESS RC_ERROR ═══ VMI_CMD_TERM - Remarks ═══ None. ═══ VMI_CMD_TERM - Topics ═══ Select an item: Syntax Parameters Returns Remarks Glossary ═══ 5.21. VMI_CMD_TERMPROC ═══ ═══ VMI_CMD_TERMPROC - Syntax ═══ /*******************************************/ /* Description: VMI_CMD_TERMPROC is */ /* mandatory and informs VMAN that an */ /* existing client process is being */ /* terminated. VMAN cleans up all */ /* resources owned by this process. VMAN */ /* passes this command directly to the */ /* GRADD chain identified by the GRADD ID */ /* provided by the caller. */ /*******************************************/ #include GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to VMI_CMD_TERMPROC. */ PVOID pIn; /* NULL. */ PVOID pOut; /* NULL. */ ULONG rc; /* Return codes. */ rc = VMIENTRY(gid, ulFunction, pIn, pOut); ═══ VMI_CMD_TERMPROC Parameter - gid ═══ gid (GID) - input ID of the GRADD. ═══ VMI_CMD_TERMPROC Parameter - ulFunction ═══ ulFunction (ULONG) - input Set equal to VMI_CMD_TERMPROC. ═══ VMI_CMD_TERMPROC Parameter - pIn ═══ pIn (PVOID) - input NULL. ═══ VMI_CMD_TERMPROC Parameter - pOut ═══ pOut (PVOID) - output NULL. ═══ VMI_CMD_TERMPROC Return Value - rc ═══ rc (ULONG) - returns Return codes. RC_SUCCESS RC_ERROR ═══ VMI_CMD_TERMPROC - Parameters ═══ gid (GID) - input ID of the GRADD. ulFunction (ULONG) - input Set equal to VMI_CMD_TERMPROC. pIn (PVOID) - input NULL. pOut (PVOID) - output NULL. rc (ULONG) - returns Return codes. RC_SUCCESS RC_ERROR ═══ VMI_CMD_TERMPROC - Remarks ═══ None. ═══ VMI_CMD_TERMPROC - Topics ═══ Select an item: Syntax Parameters Returns Remarks Glossary ═══ 5.22. VMI_CMD_VRAM ═══ ═══ VMI_CMD_VRAM - Syntax ═══ /*******************************************/ /* Description: VMI_CMD_VRAM is called to */ /* allocate off-screen video memory. VMAN */ /* sends this command to the GRADD chain */ /* identified by the GRADD ID provided by */ /* the caller. */ /*******************************************/ #include GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to VMI_CMD_VRAM. */ PVOID pIn; /* Pointer to a VRAMALLOCIN data structure. */ PVOID pOut; /* Pointer to a VRAMALLOCOUT data structure. */ ULONG rc; /* Return codes. */ rc = VMIENTRY(gid, ulFunction, pIn, pOut); ═══ VMI_CMD_VRAM Parameter - gid ═══ gid (GID) - input ID of the GRADD. ═══ VMI_CMD_VRAM Parameter - ulFunction ═══ ulFunction (ULONG) - input Set equal to VMI_CMD_VRAM. ═══ VMI_CMD_VRAM Parameter - pIn ═══ pIn (PVOID) - input Pointer to a VRAMALLOCIN data structure. ═══ VMI_CMD_VRAM Parameter - pOut ═══ pOut (PVOID) - output Pointer to a VRAMALLOCOUT data structure. ═══ VMI_CMD_VRAM Return Value - rc ═══ rc (ULONG) - returns Return codes. RC_UNSUPPORTED RC_SUCCESS RC_ERROR ═══ VMI_CMD_VRAM - Parameters ═══ gid (GID) - input ID of the GRADD. ulFunction (ULONG) - input Set equal to VMI_CMD_VRAM. pIn (PVOID) - input Pointer to a VRAMALLOCIN data structure. pOut (PVOID) - output Pointer to a VRAMALLOCOUT data structure. rc (ULONG) - returns Return codes. RC_UNSUPPORTED RC_SUCCESS RC_ERROR ═══ VMI_CMD_VRAM - Remarks ═══ None. ═══ VMI_CMD_VRAM - Topics ═══ Select an item: Syntax Parameters Returns Remarks Glossary ═══ 5.23. VMIEntry ═══ ═══ VMIEntry - Syntax ═══ /*******************************************/ /* Description: VMIEntry is the single */ /* exported function from the Video */ /* Manager component. It is part of the */ /* Video Manager Interface (VMI) protocol */ /* and receives operations from the */ /* translation layer components. */ /*******************************************/ #include GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set to appropriate VMI_CMD_ function. */ PVOID pIn; /* Pointer to applicable data structure. */ PVOID pOut; /* Pointer to applicable data structure. */ ULONG rc; /* Return codes. */ rc = VMIEntry(gid, ulFunction, pIn, pOut); ═══ VMIEntry Parameter - gid ═══ gid (GID) - input ID of the GRADD. ═══ VMIEntry Parameter - ulFunction ═══ ulFunction (ULONG) - input Set to appropriate VMI_CMD_ function. This parameter is set to one of the VMI_CMD_ functions shown in the table of common functions shown at the beginning of this section. ═══ VMIEntry Parameter - pIn ═══ pIn (PVOID) - input Pointer to applicable data structure. ═══ VMIEntry Parameter - pOut ═══ pOut (PVOID) - output Pointer to applicable data structure. ═══ VMIEntry Return Value - rc ═══ rc (ULONG) - returns Return codes. Valid values are dictated by the applicable VMI_CMD_ function. ═══ VMIEntry - Parameters ═══ gid (GID) - input ID of the GRADD. ulFunction (ULONG) - input Set to appropriate VMI_CMD_ function. This parameter is set to one of the VMI_CMD_ functions shown in the table of common functions shown at the beginning of this section. pIn (PVOID) - input Pointer to applicable data structure. pOut (PVOID) - output Pointer to applicable data structure. rc (ULONG) - returns Return codes. Valid values are dictated by the applicable VMI_CMD_ function. ═══ VMIEntry - Remarks ═══ None. ═══ VMIEntry - Topics ═══ Select an item: Syntax Parameters Returns Remarks Glossary ═══ 6. Graphics Adapter Device Drivers ═══ This chapter describes the functions called by individual Graphics Adapter Device Drivers (GRADDs), which are designated by the prefix GHI_CMD_. The chapter also discusses Enhanced Direct Interface Video Extension (EnDIVE) functions, which are designated by the prefix EXT_CMD_. ═══ 6.1. User Interfaces ═══ All GRADDs must export a function of the following typedef: ULONG HWEntry(GID gid, ULONG ulFunction, PVOID pIn, PVOID pOut); ═══ 6.2. Adding Extensions ═══ One of the most important design points of the GRADD Model is the ability to extend or enhance the overall architecture. It is not possible to anticipate the changes in future graphics hardware, so we must provide a mechanism to extend the architecture in a manner that takes fullest advantage of the new hardware. There are many ways to extend the GRADD Model. Using the VMI_CMD_EXTENSION command, an extension can be written that passes its own defined commands to a GRADD. Support for an extension can be added to an existing GRADD, or a new GRADD can be written to handle the additional support for a given extension. ═══ 6.2.1. Adding Extensions to an Existing GRADD ═══ When the Video Manager (VMAN) issues the GHI_CMD_INIT command to a GRADD, it gives the GRADD a unique ID. Upon return from the GHI_CMD_INIT command, the GRADD returns the number of function classes it supports. The GRADD must assign a unique GID to each of its function-class instances. The GID provided to the GRADD by VMAN must be bumped up by one for every function-class instance. Note: For Presentation Manager and Seamless Windows functions, a GRADD must support the Base Function class of services. The GRE2VMAN component looks specifically for a GRADD that supports this class of function. VMAN will allocate one GRADDINFO structure for every class of function that a GRADD supports. VMAN will call GHI_CMD_QUERYCAPS once for every function-class instance. This allows an extension layer to associate a GID with a set of function classes. The extension layer uses the VMI_CMD_EXTENSION function to communicate with a GRADD. It is up to the extension layer to define the unique extension functions. The extensions must use VMAN to communicate with the GRADD. The input packet to the VMI_CMD_EXTENSION function includes information about screen change areas and hardware serialization. This information allows VMAN to maintain hardware pointer support and hardware serialization. ═══ 6.2.2. Creating an Extension GRADD ═══ An extension GRADD can be added to the system without interfering with normal operations. The extension GRADD works in the same manner as a normal GRADD. The extension GRADD identifies itself to the system via the pszFunctionClassID field of the CAPSINFO data structure. This structure is returned to VMAN via GHI_CMD_QUERYCAPS. The extension layer communicates with the extension GRADD in the same manner described in the "Adding Extensions to an Existing GRADD" section earlier. ═══ 6.2.2.1. Creating an EnDIVE Multimedia Extension GRADD ═══ OS/2 Warp supports an enhanced direct interface video extension, referred to as EnDIVE. This extension is designed to support graphics chips that handle video acceleration in hardware. The EnDIVE multimedia extension described here supports the same level of functionality under the GRADD Model. An EnDIVE driver for OS/2 Warp is directly portable to OS/2 Warp, Version 3, PowerPC Edition, because it has been designed as an extension GRADD. The following figure diagrams the DIVE Display Engine. The phrase "video acceleration" recently has taken on a new meaning. In the past, video acceleration was a way of describing hardware assist for bitblts, lines, and so on. Today, video acceleration or video accelerators describe hardware assist for video-acceleration software. The minimum requirement necessary to be considered a video accelerator is the ability to perform a stretch blit in hardware. More powerful video accelerators perform additional functions, such as dynamic color conversion, decompression, and compression. These types of operations are directly applicable to the needs of multimedia video-acceleration software. The EnDIVE multimedia extension GRADD consists of four functions, contained in the ulXSubFunction field of the HWEXTENSION packet. For each extension function, the input packet is pointed to by the pXP1 field of the HWEXTENSION packet. The four EnDIVE functions are listed below: o EXT_CMD_ENDIVE_GET o EXT_CMD_ENDIVE_INIT o EXT_CMD_ENDIVE_PUT o EXT_CMD_ENDIVE_QUERY For details on each of these functions, refer to Enhanced Direct Interface Video Extension (EnDIVE) Functions. ═══ 6.3. NLS Support ═══ The GRADD Model is independent of the language and the operating system service being used. Double-byte character sets and other issues for different language releases are a matter of the translation of the operating system service, not of any code in the GRADD Model. ═══ 6.4. Graphics Hardware Interface Functions ═══ The Graphics Adapter Device Driver Interface (GHI) functions are listed in the following table for easy reference. Each of these functions has an identical corresponding VMAN VMI_CMD_ function. The difference is that the VMI functions use VMIEntry, while the GHI functions use HWEntry. The following table lists the GRADD Graphics Hardware Interface functions and whether they are mandatory or optional. ┌────────────────────────────────────────┬────────────────────┐ │Function │Type │ ├────────────────────────────────────────┼────────────────────┤ │GHI_CMD_BITBLT │Optional │ ├────────────────────────────────────────┼────────────────────┤ │GHI_CMD_EVENT │Optional │ ├────────────────────────────────────────┼────────────────────┤ │GHI_CMD_EXTENSION │Optional │ ├────────────────────────────────────────┼────────────────────┤ │GHI_CMD_INIT │Mandatory │ ├────────────────────────────────────────┼────────────────────┤ │GHI_CMD_INITPROC │Mandatory │ ├────────────────────────────────────────┼────────────────────┤ │GHI_CMD_LINE │Optional │ ├────────────────────────────────────────┼────────────────────┤ │GHI_CMD_MOVEPTR │Optional │ ├────────────────────────────────────────┼────────────────────┤ │GHI_CMD_PALETTE │Mandatory* │ ├────────────────────────────────────────┼────────────────────┤ │GHI_CMD_QUERYCAPS │Mandatory │ ├────────────────────────────────────────┼────────────────────┤ │GHI_CMD_QUERYMODES │Mandatory │ ├────────────────────────────────────────┼────────────────────┤ │GHI_CMD_REQUESTHW │Optional │ ├────────────────────────────────────────┼────────────────────┤ │GHI_CMD_SETMODE │Mandatory │ ├────────────────────────────────────────┼────────────────────┤ │GHI_CMD_SETPTR │Optional │ ├────────────────────────────────────────┼────────────────────┤ │GHI_CMD_SHOWPTR │Optional │ ├────────────────────────────────────────┼────────────────────┤ │GHI_CMD_TERM │Optional │ ├────────────────────────────────────────┼────────────────────┤ │GHI_CMD_TERMPROC │Optional │ ├────────────────────────────────────────┼────────────────────┤ │GHI_CMD_VRAM │Optional │ │ │* At 256 color modes│ │ │only. │ └────────────────────────────────────────┴────────────────────┘ ═══ 6.5. GHI_CMD_BITBLT ═══ ═══ GHI_CMD_BITBLT - Syntax ═══ /*******************************************/ /* Description: GHI_CMD_BITBLT is */ /* optional and is called to draw bit maps */ /* to and from the video display. The */ /* GRADD can return this function call to */ /* VMAN for simulation. */ /*******************************************/ #include GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to GHI_CMD_BITBLT. */ PVOID pIn; /* Pointer to a BITBLTINFO data structure. */ PVOID pOut; /* NULL; no output structure needed. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunction, pIn, pOut); ═══ GHI_CMD_BITBLT Parameter - gid ═══ gid (GID) - input ID of the GRADD. ═══ GHI_CMD_BITBLT Parameter - ulFunction ═══ ulFunction (ULONG) - input Set equal to GHI_CMD_BITBLT. ═══ GHI_CMD_BITBLT Parameter - pIn ═══ pIn (PVOID) - input Pointer to a BITBLTINFO data structure. ═══ GHI_CMD_BITBLT Parameter - pOut ═══ pOut (PVOID) - output NULL; no output structure needed. ═══ GHI_CMD_BITBLT Return Value - rc ═══ rc (ULONG) - returns Return codes. RC_SIMULATE RC_SUCCESS RC_ERROR ═══ GHI_CMD_BITBLT - Parameters ═══ gid (GID) - input ID of the GRADD. ulFunction (ULONG) - input Set equal to GHI_CMD_BITBLT. pIn (PVOID) - input Pointer to a BITBLTINFO data structure. pOut (PVOID) - output NULL; no output structure needed. rc (ULONG) - returns Return codes. RC_SIMULATE RC_SUCCESS RC_ERROR ═══ GHI_CMD_BITBLT - Remarks ═══ None. ═══ GHI_CMD_BITBLT - Topics ═══ Select an item: Syntax Parameters Returns Remarks Glossary ═══ 6.6. GHI_CMD_EVENT ═══ ═══ GHI_CMD_EVENT - Syntax ═══ /*******************************************/ /* Description: GHI_CMD_EVENT is optional */ /* and is called to notify a GRADD of */ /* specific events. */ /*******************************************/ #include GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to GHI_CMD_EVENT. */ PVOID pIn; /* Pointer to an HWEVENTIN data structure. */ PVOID pOut; /* NULL; no output structure needed. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunction, pIn, pOut); ═══ GHI_CMD_EVENT Parameter - gid ═══ gid (GID) - input ID of the GRADD. ═══ GHI_CMD_EVENT Parameter - ulFunction ═══ ulFunction (ULONG) - input Set equal to GHI_CMD_EVENT. ═══ GHI_CMD_EVENT Parameter - pIn ═══ pIn (PVOID) - input Pointer to an HWEVENTIN data structure. ═══ GHI_CMD_EVENT Parameter - pOut ═══ pOut (PVOID) - output NULL; no output structure needed. ═══ GHI_CMD_EVENT Return Value - rc ═══ rc (ULONG) - returns Return codes. RC_UNSUPPORTED RC_SUCCESS RC_ERROR ═══ GHI_CMD_EVENT - Parameters ═══ gid (GID) - input ID of the GRADD. ulFunction (ULONG) - input Set equal to GHI_CMD_EVENT. pIn (PVOID) - input Pointer to an HWEVENTIN data structure. pOut (PVOID) - output NULL; no output structure needed. rc (ULONG) - returns Return codes. RC_UNSUPPORTED RC_SUCCESS RC_ERROR ═══ GHI_CMD_EVENT - Remarks ═══ None. ═══ GHI_CMD_EVENT - Topics ═══ Select an item: Syntax Parameters Returns Remarks Glossary ═══ 6.7. GHI_CMD_EXTENSION ═══ ═══ GHI_CMD_EXTENSION - Syntax ═══ /*******************************************/ /* Description: GHI_CMD_EXTENSION is */ /* optional and is called to send an */ /* extension command to a GRADD. The */ /* extension subfunction is placed in the */ /* ulXSubFunction field of the pIn input */ /* packet. */ /*******************************************/ #include GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to GHI_CMD_EXTENSION. */ PVOID pIn; /* Pointer to an HWEXTENSION structure. */ PVOID pOut; /* Pointer to an extension-specific output structure. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunction, pIn, pOut); ═══ GHI_CMD_EXTENSION Parameter - gid ═══ gid (GID) - input ID of the GRADD. ═══ GHI_CMD_EXTENSION Parameter - ulFunction ═══ ulFunction (ULONG) - input Set equal to GHI_CMD_EXTENSION. ═══ GHI_CMD_EXTENSION Parameter - pIn ═══ pIn (PVOID) - input Pointer to an HWEXTENSION structure. ═══ GHI_CMD_EXTENSION Parameter - pOut ═══ pOut (PVOID) - output Pointer to an extension-specific output structure. ═══ GHI_CMD_EXTENSION Return Value - rc ═══ rc (ULONG) - returns Return codes. RC_UNSUPPORTED RC_SUCCESS RC_ERROR ═══ GHI_CMD_EXTENSION - Parameters ═══ gid (GID) - input ID of the GRADD. ulFunction (ULONG) - input Set equal to GHI_CMD_EXTENSION. pIn (PVOID) - input Pointer to an HWEXTENSION structure. pOut (PVOID) - output Pointer to an extension-specific output structure. rc (ULONG) - returns Return codes. RC_UNSUPPORTED RC_SUCCESS RC_ERROR ═══ GHI_CMD_EXTENSION - Remarks ═══ None. ═══ GHI_CMD_EXTENSION - Topics ═══ Select an item: Syntax Parameters Returns Remarks Glossary ═══ 6.8. GHI_CMD_INIT ═══ ═══ GHI_CMD_INIT - Syntax ═══ /*******************************************/ /* Description: GHI_CMD_INIT is mandatory */ /* and is called to initialize the GRADD. */ /* It is the first command a GRADD */ /* receives from the Video Manager (VMAN). */ /*******************************************/ #include GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to GHI_CMD_INIT. */ PVOID pIn; /* Pointer to a GDDINITIN data structure. */ PVOID pOut; /* Pointer to a GDDINITOUT data structure. */ ULONG rc; /* Return codes. */ rc = HWEntry(gid, ulFunction, pIn, pOut); ═══ GHI_CMD_INIT Parameter - gid ═══ gid (GID) - input ID of the GRADD. ═══ GHI_CMD_INIT Parameter - ulFunction ═══ ulFunction (ULONG) - input Set equal to GHI_CMD_INIT. ═══ GHI_CMD_INIT Parameter - pIn ═══ pIn (PVOID) - input Pointer to a GDDINITIN data structure. ═══ GHI_CMD_INIT Parameter - pOut ═══ pOut (PVOID) - output Pointer to a GDDINITOUT data structure. ═══ GHI_CMD_INIT Return Value - rc ═══ rc (ULONG) - returns Return codes. RC_SUCCESS RC_ERROR ═══ GHI_CMD_INIT - Parameters ═══ gid (GID) - input ID of the GRADD. ulFunction (ULONG) - input Set equal to GHI_CMD_INIT. pIn (PVOID) - input Pointer to a GDDINITIN data structure. pOut (PVOID) - output Pointer to a GDDINITOUT data structure. rc (ULONG) - returns Return codes. RC_SUCCESS RC_ERROR ═══ GHI_CMD_INIT - Remarks ═══ None. ═══ GHI_CMD_INIT - Topics ═══ Select an item: Syntax Parameters Returns Remarks Glossary ═══ 6.9. GHI_CMD_INITPROC ═══ ═══ GHI_CMD_INITPROC - Syntax ═══ /*******************************************/ /* Description: GHI_CMD_INITPROC is */ /* mandatory and informs a GRADD that a */ /* new process is being initialized. It */ /* indicates that this new process intends */ /* to be a client of the GRADD component. */ /* The GRADD ensures that all data and */ /* code is valid under this new process. */ /*******************************************/ #include GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to GHI_CMD_INITPROC. */ PVOID pIn; /* NULL. */ PVOID pOut; /* Pointer to an INITPROCOUT data structure. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunction, pIn, pOut); ═══ GHI_CMD_INITPROC Parameter - gid ═══ gid (GID) - input ID of the GRADD. ═══ GHI_CMD_INITPROC Parameter - ulFunction ═══ ulFunction (ULONG) - input Set equal to GHI_CMD_INITPROC. ═══ GHI_CMD_INITPROC Parameter - pIn ═══ pIn (PVOID) - input NULL. ═══ GHI_CMD_INITPROC Parameter - pOut ═══ pOut (PVOID) - output Pointer to an INITPROCOUT data structure. ═══ GHI_CMD_INITPROC Return Value - rc ═══ rc (ULONG) - returns Return codes. RC_SUCCESS RC_ERROR ═══ GHI_CMD_INITPROC - Parameters ═══ gid (GID) - input ID of the GRADD. ulFunction (ULONG) - input Set equal to GHI_CMD_INITPROC. pIn (PVOID) - input NULL. pOut (PVOID) - output Pointer to an INITPROCOUT data structure. rc (ULONG) - returns Return codes. RC_SUCCESS RC_ERROR ═══ GHI_CMD_INITPROC - Remarks ═══ None. ═══ GHI_CMD_INITPROC - Topics ═══ Select an item: Syntax Parameters Returns Remarks Glossary ═══ 6.10. GHI_CMD_LINE ═══ ═══ GHI_CMD_LINE - Syntax ═══ /*******************************************/ /* Description: GHI_CMD_LINE is optional */ /* and is called to draw lines to the */ /* video display. The GRADD can return */ /* this function call to VMAN for */ /* simulation. */ /*******************************************/ #include GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to GHI_CMD_LINE. */ PVOID pIn; /* Pointer to a LINEINFO data structure. */ PVOID pOut; /* NULL; no output structure needed. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunction, pIn, pOut); ═══ GHI_CMD_LINE Parameter - gid ═══ gid (GID) - input ID of the GRADD. ═══ GHI_CMD_LINE Parameter - ulFunction ═══ ulFunction (ULONG) - input Set equal to GHI_CMD_LINE. ═══ GHI_CMD_LINE Parameter - pIn ═══ pIn (PVOID) - input Pointer to a LINEINFO data structure. ═══ GHI_CMD_LINE Parameter - pOut ═══ pOut (PVOID) - output NULL; no output structure needed. ═══ GHI_CMD_LINE Return Value - rc ═══ rc (ULONG) - returns Return codes. RC_SIMULATE RC_SUCCESS RC_ERROR ═══ GHI_CMD_LINE - Parameters ═══ gid (GID) - input ID of the GRADD. ulFunction (ULONG) - input Set equal to GHI_CMD_LINE. pIn (PVOID) - input Pointer to a LINEINFO data structure. pOut (PVOID) - output NULL; no output structure needed. rc (ULONG) - returns Return codes. RC_SIMULATE RC_SUCCESS RC_ERROR ═══ GHI_CMD_LINE - Remarks ═══ None. ═══ GHI_CMD_LINE - Topics ═══ Select an item: Syntax Parameters Returns Remarks Glossary ═══ 6.11. GHI_CMD_MOVEPTR ═══ ═══ GHI_CMD_MOVEPTR - Syntax ═══ /*******************************************/ /* Description: GHI_CMD_MOVEPTR is */ /* optional and is called to move the */ /* pointer to the new location. The GRADD */ /* can return this function call to VMAN */ /* for simulation. */ /*******************************************/ #include GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to GHI_CMD_MOVEPTR. */ PVOID pIn; /* Pointer to an HWMOVEPTRIN structure. */ PVOID pOut; /* NULL; no output structure needed. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunction, pIn, pOut); ═══ GHI_CMD_MOVEPTR Parameter - gid ═══ gid (GID) - input ID of the GRADD. ═══ GHI_CMD_MOVEPTR Parameter - ulFunction ═══ ulFunction (ULONG) - input Set equal to GHI_CMD_MOVEPTR. ═══ GHI_CMD_MOVEPTR Parameter - pIn ═══ pIn (PVOID) - input Pointer to an HWMOVEPTRIN structure. ═══ GHI_CMD_MOVEPTR Parameter - pOut ═══ pOut (PVOID) - output NULL; no output structure needed. ═══ GHI_CMD_MOVEPTR Return Value - rc ═══ rc (ULONG) - returns Return codes. RC_SIMULATE RC_SUCCESS RC_ERROR ═══ GHI_CMD_MOVEPTR - Parameters ═══ gid (GID) - input ID of the GRADD. ulFunction (ULONG) - input Set equal to GHI_CMD_MOVEPTR. pIn (PVOID) - input Pointer to an HWMOVEPTRIN structure. pOut (PVOID) - output NULL; no output structure needed. rc (ULONG) - returns Return codes. RC_SIMULATE RC_SUCCESS RC_ERROR ═══ GHI_CMD_MOVEPTR - Remarks ═══ None. ═══ GHI_CMD_MOVEPTR - Topics ═══ Select an item: Syntax Parameters Returns Remarks Glossary ═══ 6.12. GHI_CMD_PALETTE ═══ ═══ GHI_CMD_PALETTE - Syntax ═══ /*******************************************/ /* Description: GHI_CMD_PALETTE is */ /* mandatory if the device supports */ /* 256-color mode. This function is */ /* called to set the hardware palette. The */ /* GRADD is expected to respond by */ /* describing the palette in a given array */ /* or by using the palette given in the */ /* array. The GRADD is always given an */ /* HWPALETTEINFO structure with either the */ /* PALETTE_GET or PALETTE_SET flag to */ /* specify the operation to perform. */ /*******************************************/ #include GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to GHI_CMD_PALETTE. */ PVOID pIn; /* Pointer to an HWPALETTEINFO structure. */ PVOID pOut; /* Depends on value of pIn. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunction, pIn, pOut); ═══ GHI_CMD_PALETTE Parameter - gid ═══ gid (GID) - input ID of the GRADD. ═══ GHI_CMD_PALETTE Parameter - ulFunction ═══ ulFunction (ULONG) - input Set equal to GHI_CMD_PALETTE. ═══ GHI_CMD_PALETTE Parameter - pIn ═══ pIn (PVOID) - input Pointer to an HWPALETTEINFO structure. ═══ GHI_CMD_PALETTE Parameter - pOut ═══ pOut (PVOID) - output Depends on value of pIn. If '_SET' is specified by pIn, pOut If '_GET' is specified by pIn, pOut is a pointer to an HWPALETTEINFO data structure. ═══ GHI_CMD_PALETTE Return Value - rc ═══ rc (ULONG) - returns Return codes. RC_SUCCESS RC_ERROR ═══ GHI_CMD_PALETTE - Parameters ═══ gid (GID) - input ID of the GRADD. ulFunction (ULONG) - input Set equal to GHI_CMD_PALETTE. pIn (PVOID) - input Pointer to an HWPALETTEINFO structure. pOut (PVOID) - output Depends on value of pIn. If '_SET' is specified by pIn, pOut If '_GET' is specified by pIn, pOut is a pointer to an HWPALETTEINFO data structure. rc (ULONG) - returns Return codes. RC_SUCCESS RC_ERROR ═══ GHI_CMD_PALETTE - Remarks ═══ None. ═══ GHI_CMD_PALETTE - Topics ═══ Select an item: Syntax Parameters Returns Remarks Glossary ═══ 6.13. GHI_CMD_QUERYCAPS ═══ ═══ GHI_CMD_QUERYCAPS - Syntax ═══ /*******************************************/ /* Description: GHI_CMD_QUERYCAPS is */ /* mandatory. The GRADD is expected to */ /* return its capabilities. The returned */ /* capabilities are packaged by VMAN and */ /* given to a Translation Layer. The */ /* Translation Layer uses these */ /* capabilities to decide which GHI_CMD_ */ /* functions are sent to the GRADD. */ /*******************************************/ #include GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to GHI_CMD_QUERYCAPS. */ PVOID pIn; /* NULL. */ PVOID pOut; /* Pointer to a CAPSINFO data structure. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunction, pIn, pOut); ═══ GHI_CMD_QUERYCAPS Parameter - gid ═══ gid (GID) - input ID of the GRADD. ═══ GHI_CMD_QUERYCAPS Parameter - ulFunction ═══ ulFunction (ULONG) - input Set equal to GHI_CMD_QUERYCAPS. ═══ GHI_CMD_QUERYCAPS Parameter - pIn ═══ pIn (PVOID) - input NULL. ═══ GHI_CMD_QUERYCAPS Parameter - pOut ═══ pOut (PVOID) - output Pointer to a CAPSINFO data structure. ═══ GHI_CMD_QUERYCAPS Return Value - rc ═══ rc (ULONG) - returns Return codes. RC_SUCCESS RC_ERROR ═══ GHI_CMD_QUERYCAPS - Parameters ═══ gid (GID) - input ID of the GRADD. ulFunction (ULONG) - input Set equal to GHI_CMD_QUERYCAPS. pIn (PVOID) - input NULL. pOut (PVOID) - output Pointer to a CAPSINFO data structure. rc (ULONG) - returns Return codes. RC_SUCCESS RC_ERROR ═══ GHI_CMD_QUERYCAPS - Remarks ═══ None. ═══ GHI_CMD_QUERYCAPS - Topics ═══ Select an item: Syntax Parameters Returns Remarks Glossary ═══ 6.14. GHI_CMD_QUERYMODES ═══ ═══ GHI_CMD_QUERYMODES - Syntax ═══ /*******************************************/ /* Description: GHI_CMD_QUERYMODES is */ /* mandatory and is called to query the */ /* available video mode information. The */ /* GRADD is expected to respond with */ /* information regarding the video */ /* graphics modes supported by the GRADD. */ /*******************************************/ #include GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to GHI_CMD_QUERYMODES. */ PVOID pIn; /* Pointer that identifies a QUERYMODE operation. */ PVOID pOut; /* Pointer to the pIn operation. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunction, pIn, pOut); ═══ GHI_CMD_QUERYMODES Parameter - gid ═══ gid (GID) - input ID of the GRADD. ═══ GHI_CMD_QUERYMODES Parameter - ulFunction ═══ ulFunction (ULONG) - input Set equal to GHI_CMD_QUERYMODES. ═══ GHI_CMD_QUERYMODES Parameter - pIn ═══ pIn (PVOID) - input Pointer that identifies a QUERYMODE operation. This pointer identifies one of the following operations: QUERYMODE_NUM_MODES QUERYMODE_MODE_DATA ═══ GHI_CMD_QUERYMODES Parameter - pOut ═══ pOut (PVOID) - output Pointer to the pIn operation. This pointer indicates one of the following, depending on the value of pIn: QUERYMODE_NUM_MODES Indicates a pointer to a ULONG that is to be given the number of supported modes. QUERYMODE_MODE_DATA Indicates a pointer to an array of GDDMODEINFO structures large enough for the number of supported modes. ═══ GHI_CMD_QUERYMODES Return Value - rc ═══ rc (ULONG) - returns Return codes. RC_SUCCESS RC_ERROR ═══ GHI_CMD_QUERYMODES - Parameters ═══ gid (GID) - input ID of the GRADD. ulFunction (ULONG) - input Set equal to GHI_CMD_QUERYMODES. pIn (PVOID) - input Pointer that identifies a QUERYMODE operation. This pointer identifies one of the following operations: QUERYMODE_NUM_MODES QUERYMODE_MODE_DATA pOut (PVOID) - output Pointer to the pIn operation. This pointer indicates one of the following, depending on the value of pIn: QUERYMODE_NUM_MODES Indicates a pointer to a ULONG that is to be given the number of supported modes. QUERYMODE_MODE_DATA Indicates a pointer to an array of GDDMODEINFO structures large enough for the number of supported modes. rc (ULONG) - returns Return codes. RC_SUCCESS RC_ERROR ═══ GHI_CMD_QUERYMODES - Remarks ═══ None. ═══ GHI_CMD_QUERYMODES - Topics ═══ Select an item: Syntax Parameters Returns Remarks Glossary ═══ 6.15. GHI_CMD_REQUESTHW ═══ ═══ GHI_CMD_REQUESTHW - Syntax ═══ /*******************************************/ /* Description: GHI_CMD_REQUESTHW is */ /* optional and allows a translation layer */ /* exclusive access to the video hardware. */ /* It can do such operations as writing */ /* directly to the video buffer. This */ /* function is used to request and release */ /* the video hardware. The fRequest field */ /* of the pIn data packet determines if */ /* this function is a request or a release.*/ /*******************************************/ #include GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to GHI_CMD_REQUESTHW. */ PVOID pIn; /* Pointer to an HWREQIN data structure. */ PVOID pOut; /* NULL; no output structure needed. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunction, pIn, pOut); ═══ GHI_CMD_REQUESTHW Parameter - gid ═══ gid (GID) - input ID of the GRADD. ═══ GHI_CMD_REQUESTHW Parameter - ulFunction ═══ ulFunction (ULONG) - input Set equal to GHI_CMD_REQUESTHW. ═══ GHI_CMD_REQUESTHW Parameter - pIn ═══ pIn (PVOID) - input Pointer to an HWREQIN data structure. ═══ GHI_CMD_REQUESTHW Parameter - pOut ═══ pOut (PVOID) - output NULL; no output structure needed. ═══ GHI_CMD_REQUESTHW Return Value - rc ═══ rc (ULONG) - returns Return codes. RC_UNSUPPORTED RC_SUCCESS RC_ERROR ═══ GHI_CMD_REQUESTHW - Parameters ═══ gid (GID) - input ID of the GRADD. ulFunction (ULONG) - input Set equal to GHI_CMD_REQUESTHW. pIn (PVOID) - input Pointer to an HWREQIN data structure. pOut (PVOID) - output NULL; no output structure needed. rc (ULONG) - returns Return codes. RC_UNSUPPORTED RC_SUCCESS RC_ERROR ═══ GHI_CMD_REQUESTHW - Remarks ═══ None. ═══ GHI_CMD_REQUESTHW - Topics ═══ Select an item: Syntax Parameters Returns Remarks Glossary ═══ 6.16. GHI_CMD_SETMODE ═══ ═══ GHI_CMD_SETMODE - Syntax ═══ /*******************************************/ /* Description: GHI_CMD_SETMODE is */ /* mandatory. The GRADD is expected to set */ /* the video mode, given an ID of the */ /* chosen mode. */ /*******************************************/ #include GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to GHI_CMD_SETMODE. */ PVOID pIn; /* Pointer to PULONG containing the ID of the requested mode. */ PVOID pOut; /* NULL. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunction, pIn, pOut); ═══ GHI_CMD_SETMODE Parameter - gid ═══ gid (GID) - input ID of the GRADD. ═══ GHI_CMD_SETMODE Parameter - ulFunction ═══ ulFunction (ULONG) - input Set equal to GHI_CMD_SETMODE. ═══ GHI_CMD_SETMODE Parameter - pIn ═══ pIn (PVOID) - input Pointer to PULONG containing the ID of the requested mode. ═══ GHI_CMD_SETMODE Parameter - pOut ═══ pOut (PVOID) - output NULL. ═══ GHI_CMD_SETMODE Return Value - rc ═══ rc (ULONG) - returns Return codes. RC_SUCCESS RC_ERROR ═══ GHI_CMD_SETMODE - Parameters ═══ gid (GID) - input ID of the GRADD. ulFunction (ULONG) - input Set equal to GHI_CMD_SETMODE. pIn (PVOID) - input Pointer to PULONG containing the ID of the requested mode. pOut (PVOID) - output NULL. rc (ULONG) - returns Return codes. RC_SUCCESS RC_ERROR ═══ GHI_CMD_SETMODE - Remarks ═══ None. ═══ GHI_CMD_SETMODE - Topics ═══ Select an item: Syntax Parameters Returns Remarks Glossary ═══ 6.17. GHI_CMD_SETPTR ═══ ═══ GHI_CMD_SETPTR - Syntax ═══ /*******************************************/ /* Description: GHI_CMD_SETPTR is */ /* optional and is called to set the */ /* pointer bit masks. Both monochrome and */ /* color pointers can be set. The GRADD */ /* can return this function call to VMAN */ /* for simulation. */ /*******************************************/ #include GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to GHI_CMD_SETPTR. */ PVOID pIn; /* Pointer to an HWSETPTRIN data structure. */ PVOID pOut; /* Pointer to an HWSETPTROUT data structure. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunction, pIn, pOut); ═══ GHI_CMD_SETPTR Parameter - gid ═══ gid (GID) - input ID of the GRADD. ═══ GHI_CMD_SETPTR Parameter - ulFunction ═══ ulFunction (ULONG) - input Set equal to GHI_CMD_SETPTR. ═══ GHI_CMD_SETPTR Parameter - pIn ═══ pIn (PVOID) - input Pointer to an HWSETPTRIN data structure. ═══ GHI_CMD_SETPTR Parameter - pOut ═══ pOut (PVOID) - output Pointer to an HWSETPTROUT data structure. ═══ GHI_CMD_SETPTR Return Value - rc ═══ rc (ULONG) - returns Return codes. RC_SIMULATE RC_SUCCESS RC_ERROR ═══ GHI_CMD_SETPTR - Parameters ═══ gid (GID) - input ID of the GRADD. ulFunction (ULONG) - input Set equal to GHI_CMD_SETPTR. pIn (PVOID) - input Pointer to an HWSETPTRIN data structure. pOut (PVOID) - output Pointer to an HWSETPTROUT data structure. rc (ULONG) - returns Return codes. RC_SIMULATE RC_SUCCESS RC_ERROR ═══ GHI_CMD_SETPTR - Remarks ═══ None. ═══ GHI_CMD_SETPTR - Topics ═══ Select an item: Syntax Parameters Returns Remarks Glossary ═══ 6.18. GHI_CMD_SHOWPTR ═══ ═══ GHI_CMD_SHOWPTR - Syntax ═══ /*******************************************/ /* Description: GHI_CMD_SHOWPTR is */ /* optional and sets the visibility state */ /* of the pointer. The fShow field of the */ /* pIn data packet determines the */ /* visibility state. The GRADD can return */ /* this function call to VMAN for */ /* simulation. */ /*******************************************/ #include GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to GHI_CMD_SHOWPTR. */ PVOID pIn; /* Pointer to an HWSHOWPTRIN data structure. */ PVOID pOut; /* NULL; no output structure needed. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunction, pIn, pOut); ═══ GHI_CMD_SHOWPTR Parameter - gid ═══ gid (GID) - input ID of the GRADD. ═══ GHI_CMD_SHOWPTR Parameter - ulFunction ═══ ulFunction (ULONG) - input Set equal to GHI_CMD_SHOWPTR. ═══ GHI_CMD_SHOWPTR Parameter - pIn ═══ pIn (PVOID) - input Pointer to an HWSHOWPTRIN data structure. ═══ GHI_CMD_SHOWPTR Parameter - pOut ═══ pOut (PVOID) - output NULL; no output structure needed. ═══ GHI_CMD_SHOWPTR Return Value - rc ═══ rc (ULONG) - returns Return codes. RC_SIMULATE RC_SUCCESS RC_ERROR ═══ GHI_CMD_SHOWPTR - Parameters ═══ gid (GID) - input ID of the GRADD. ulFunction (ULONG) - input Set equal to GHI_CMD_SHOWPTR. pIn (PVOID) - input Pointer to an HWSHOWPTRIN data structure. pOut (PVOID) - output NULL; no output structure needed. rc (ULONG) - returns Return codes. RC_SIMULATE RC_SUCCESS RC_ERROR ═══ GHI_CMD_SHOWPTR - Remarks ═══ None. ═══ GHI_CMD_SHOWPTR - Topics ═══ Select an item: Syntax Parameters Returns Remarks Glossary ═══ 6.19. GHI_CMD_TERM ═══ ═══ GHI_CMD_TERM - Syntax ═══ /*******************************************/ /* Description: GHI_CMD_TERM is optonal */ /* and is called by a Translation Layer */ /* when it no longer requires the services */ /* of VMAN. */ /*******************************************/ #include GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to GHI_CMD_TERM. */ PVOID pIn; /* NULL. */ PVOID pOut; /* NULL. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunction, pIn, pOut); ═══ GHI_CMD_TERM Parameter - gid ═══ gid (GID) - input ID of the GRADD. ═══ GHI_CMD_TERM Parameter - ulFunction ═══ ulFunction (ULONG) - input Set equal to GHI_CMD_TERM. ═══ GHI_CMD_TERM Parameter - pIn ═══ pIn (PVOID) - input NULL. ═══ GHI_CMD_TERM Parameter - pOut ═══ pOut (PVOID) - output NULL. ═══ GHI_CMD_TERM Return Value - rc ═══ rc (ULONG) - returns Return codes. RC_UNSUPPORTED RC_SUCCESS RC_ERROR ═══ GHI_CMD_TERM - Parameters ═══ gid (GID) - input ID of the GRADD. ulFunction (ULONG) - input Set equal to GHI_CMD_TERM. pIn (PVOID) - input NULL. pOut (PVOID) - output NULL. rc (ULONG) - returns Return codes. RC_UNSUPPORTED RC_SUCCESS RC_ERROR ═══ GHI_CMD_TERM - Remarks ═══ None. ═══ GHI_CMD_TERM - Topics ═══ Select an item: Syntax Parameters Returns Remarks Glossary ═══ 6.20. GHI_CMD_TERMPROC ═══ ═══ GHI_CMD_TERMPROC - Syntax ═══ /*******************************************/ /* Description: GHI_CMD_TERMPROC is */ /* optional and informs the GRADD that an */ /* existing client process is being */ /* terminated. The GRADD should clean up */ /* all resources owned by this process. */ /*******************************************/ #include GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to GHI_CMD_TERMPROC. */ PVOID pIn; /* NULL. */ PVOID pOut; /* NULL. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunction, pIn, pOut); ═══ GHI_CMD_TERMPROC Parameter - gid ═══ gid (GID) - input ID of the GRADD. ═══ GHI_CMD_TERMPROC Parameter - ulFunction ═══ ulFunction (ULONG) - input Set equal to GHI_CMD_TERMPROC. ═══ GHI_CMD_TERMPROC Parameter - pIn ═══ pIn (PVOID) - input NULL. ═══ GHI_CMD_TERMPROC Parameter - pOut ═══ pOut (PVOID) - output NULL. ═══ GHI_CMD_TERMPROC Return Value - rc ═══ rc (ULONG) - returns Return codes. RC_UNSUPPORTED RC_SUCCESS RC_ERROR ═══ GHI_CMD_TERMPROC - Parameters ═══ gid (GID) - input ID of the GRADD. ulFunction (ULONG) - input Set equal to GHI_CMD_TERMPROC. pIn (PVOID) - input NULL. pOut (PVOID) - output NULL. rc (ULONG) - returns Return codes. RC_UNSUPPORTED RC_SUCCESS RC_ERROR ═══ GHI_CMD_TERMPROC - Remarks ═══ None. ═══ GHI_CMD_TERMPROC - Topics ═══ Select an item: Syntax Parameters Returns Remarks Glossary ═══ 6.21. GHI_CMD_VRAM ═══ ═══ GHI_CMD_VRAM - Syntax ═══ /*******************************************/ /* Description: GHI_CMD_VRAM is optional */ /* and is called to request allocation of */ /* off-screen video memory. */ /*******************************************/ #include GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to GHI_CMD_VRAM. */ PVOID pIn; /* Pointer to a VRAMIN data structure. */ PVOID pOut; /* Pointer to a function-specific output data structure. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunction, pIn, pOut); ═══ GHI_CMD_VRAM Parameter - gid ═══ gid (GID) - input ID of the GRADD. ═══ GHI_CMD_VRAM Parameter - ulFunction ═══ ulFunction (ULONG) - input Set equal to GHI_CMD_VRAM. ═══ GHI_CMD_VRAM Parameter - pIn ═══ pIn (PVOID) - input Pointer to a VRAMIN data structure. ═══ GHI_CMD_VRAM Parameter - pOut ═══ pOut (PVOID) - output Pointer to a function-specific output data structure. ═══ GHI_CMD_VRAM Return Value - rc ═══ rc (ULONG) - returns Return codes. RC_UNSUPPORTED RC_SUCCESS RC_ERROR ═══ GHI_CMD_VRAM - Parameters ═══ gid (GID) - input ID of the GRADD. ulFunction (ULONG) - input Set equal to GHI_CMD_VRAM. pIn (PVOID) - input Pointer to a VRAMIN data structure. pOut (PVOID) - output Pointer to a function-specific output data structure. rc (ULONG) - returns Return codes. RC_UNSUPPORTED RC_SUCCESS RC_ERROR ═══ GHI_CMD_VRAM - Remarks ═══ None. ═══ GHI_CMD_VRAM - Topics ═══ Select an item: Syntax Parameters Returns Remarks Glossary ═══ 6.22. HWEntry ═══ ═══ HWEntry - Syntax ═══ /*******************************************/ /* Description: HWEntry is the single */ /* exported function from a graphics */ /* adapter device driver (GRADD). It is */ /* part of the Graphics Hardware Interface */ /* (GHI) protocol for GRADDs and receives */ /* all of the operations from the Video */ /* Manager (VMAN) component. */ /*******************************************/ #include GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set to appropriate GHI_CMD_ function. */ PVOID pIn; /* Pointer to a GHI_-specific input data structure. */ PVOID pOut; /* Pointer to a GHI_-specific output data structure. */ ULONG rc; /* Return codes. */ rc = HWEntry(gid, ulFunction, pIn, pOut); ═══ HWEntry Parameter - gid ═══ gid (GID) - input ID of the GRADD. ═══ HWEntry Parameter - ulFunction ═══ ulFunction (ULONG) - input Set to appropriate GHI_CMD_ function. This parameter is set to one of the GHI_CMD_ functions shown in the table at the beginning of this section. ═══ HWEntry Parameter - pIn ═══ pIn (PVOID) - input Pointer to a GHI_-specific input data structure. ═══ HWEntry Parameter - pOut ═══ pOut (PVOID) - output Pointer to a GHI_-specific output data structure. ═══ HWEntry Return Value - rc ═══ rc (ULONG) - returns Return codes. Valid values are dictated by the applicable GHI_CMD_ function. ═══ HWEntry - Parameters ═══ gid (GID) - input ID of the GRADD. ulFunction (ULONG) - input Set to appropriate GHI_CMD_ function. This parameter is set to one of the GHI_CMD_ functions shown in the table at the beginning of this section. pIn (PVOID) - input Pointer to a GHI_-specific input data structure. pOut (PVOID) - output Pointer to a GHI_-specific output data structure. rc (ULONG) - returns Return codes. Valid values are dictated by the applicable GHI_CMD_ function. ═══ HWEntry - Remarks ═══ None. ═══ HWEntry - Topics ═══ Select an item: Syntax Parameters Returns Remarks Glossary ═══ 6.23. Enhanced Direct Interface Video Extension (EnDIVE) Functions ═══ The following table lists the EXT_CMD_ functions that are specific to the Enhanced Direct Interface Video Extension (EnDIVE) process. These EnDIVE functions do not have corresponding VMI_CMD_ functions. An EnDIVE driver created for OS/2 Warp can be easily ported to OS/2 Warp, Version 3, PowerPC Edition because it is an extension GRADD. The following table lists the EnDIVE functions and whether they are mandatory or optional. ┌────────────────────────────────────────┬────────────────────┐ │Function │Type │ ├────────────────────────────────────────┼────────────────────┤ │EXT_CMD_ENDIVE_GET │Optional │ ├────────────────────────────────────────┼────────────────────┤ │EXT_CMD_ENDIVE_INIT │Mandatory │ ├────────────────────────────────────────┼────────────────────┤ │EXT_CMD_ENDIVE_PUT │Mandatory │ ├────────────────────────────────────────┼────────────────────┤ │EXT_CMD_ENDIVE_QUERY │Mandatory │ └────────────────────────────────────────┴────────────────────┘ ═══ 6.24. EXT_CMD_ENDIVE_GET ═══ ═══ EXT_CMD_ENDIVE_GET - Syntax ═══ /*******************************************/ /* Description: EXT_CMD_ENDIVE_GET is */ /* optional and is called to blit an image */ /* from the screen. */ /*******************************************/ #include GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to EXT_CMD_ENDIVE_GET. */ PVOID pIn; /* Pointer to an IMAGEPACK data structure. */ PVOID pOut; /* NULL. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunction, pIn, pOut); ═══ EXT_CMD_ENDIVE_GET Parameter - gid ═══ gid (GID) - input ID of the GRADD. ═══ EXT_CMD_ENDIVE_GET Parameter - ulFunction ═══ ulFunction (ULONG) - input Set equal to EXT_CMD_ENDIVE_GET. ═══ EXT_CMD_ENDIVE_GET Parameter - pIn ═══ pIn (PVOID) - input Pointer to an IMAGEPACK data structure. ═══ EXT_CMD_ENDIVE_GET Parameter - pOut ═══ pOut (PVOID) - output NULL. ═══ EXT_CMD_ENDIVE_GET Return Value - rc ═══ rc (ULONG) - returns Return codes. R_SIMULATE RC_SUCCESS RC_ERROR ═══ EXT_CMD_ENDIVE_GET - Parameters ═══ gid (GID) - input ID of the GRADD. ulFunction (ULONG) - input Set equal to EXT_CMD_ENDIVE_GET. pIn (PVOID) - input Pointer to an IMAGEPACK data structure. pOut (PVOID) - output NULL. rc (ULONG) - returns Return codes. R_SIMULATE RC_SUCCESS RC_ERROR ═══ EXT_CMD_ENDIVE_GET - Remarks ═══ None. ═══ EXT_CMD_ENDIVE_GET - Topics ═══ Select an item: Syntax Parameters Returns Remarks Glossary ═══ 6.25. EXT_CMD_ENDIVE_INIT ═══ ═══ EXT_CMD_ENDIVE_INIT - Syntax ═══ /*******************************************/ /* Description: EXT_CMD_ENDIVE_INIT is */ /* mandatory and is called to initialize */ /* the hardware. The GRADD must determine */ /* if the hardware is present. */ /*******************************************/ #include GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to EXT_CMD_ENDIVE_INIT. */ PVOID pIn; /* Pointer to an FBINFO data structure. */ PVOID pOut; /* Pointer to an EXTINITOUT data structure. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunction, pIn, pOut); ═══ EXT_CMD_ENDIVE_INIT Parameter - gid ═══ gid (GID) - input ID of the GRADD. ═══ EXT_CMD_ENDIVE_INIT Parameter - ulFunction ═══ ulFunction (ULONG) - input Set equal to EXT_CMD_ENDIVE_INIT. ═══ EXT_CMD_ENDIVE_INIT Parameter - pIn ═══ pIn (PVOID) - input Pointer to an FBINFO data structure. ═══ EXT_CMD_ENDIVE_INIT Parameter - pOut ═══ pOut (PVOID) - output Pointer to an EXTINITOUT data structure. ═══ EXT_CMD_ENDIVE_INIT Return Value - rc ═══ rc (ULONG) - returns Return codes. RC_SUCCESS RC_ERROR ═══ EXT_CMD_ENDIVE_INIT - Parameters ═══ gid (GID) - input ID of the GRADD. ulFunction (ULONG) - input Set equal to EXT_CMD_ENDIVE_INIT. pIn (PVOID) - input Pointer to an FBINFO data structure. pOut (PVOID) - output Pointer to an EXTINITOUT data structure. rc (ULONG) - returns Return codes. RC_SUCCESS RC_ERROR ═══ EXT_CMD_ENDIVE_INIT - Remarks ═══ None. ═══ EXT_CMD_ENDIVE_INIT - Topics ═══ Select an item: Syntax Parameters Returns Remarks Glossary ═══ 6.26. EXT_CMD_ENDIVE_PUT ═══ ═══ EXT_CMD_ENDIVE_PUT - Syntax ═══ /*******************************************/ /* Description: EXT_CMD_ENDIVE_PUT is */ /* mandatory and is called to blit an */ /* image to the screen. */ /*******************************************/ #include GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to EXT_CMD_ENDIVE_PUT. */ PVOID pIn; /* Pointer to an IMAGEPACK data structure. */ PVOID pOut; /* NULL. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunction, pIn, pOut); ═══ EXT_CMD_ENDIVE_PUT Parameter - gid ═══ gid (GID) - input ID of the GRADD. ═══ EXT_CMD_ENDIVE_PUT Parameter - ulFunction ═══ ulFunction (ULONG) - input Set equal to EXT_CMD_ENDIVE_PUT. ═══ EXT_CMD_ENDIVE_PUT Parameter - pIn ═══ pIn (PVOID) - input Pointer to an IMAGEPACK data structure. ═══ EXT_CMD_ENDIVE_PUT Parameter - pOut ═══ pOut (PVOID) - output NULL. ═══ EXT_CMD_ENDIVE_PUT Return Value - rc ═══ rc (ULONG) - returns Return codes. RC_SUCCESS RC_ERROR ═══ EXT_CMD_ENDIVE_PUT - Parameters ═══ gid (GID) - input ID of the GRADD. ulFunction (ULONG) - input Set equal to EXT_CMD_ENDIVE_PUT. pIn (PVOID) - input Pointer to an IMAGEPACK data structure. pOut (PVOID) - output NULL. rc (ULONG) - returns Return codes. RC_SUCCESS RC_ERROR ═══ EXT_CMD_ENDIVE_PUT - Remarks ═══ None. ═══ EXT_CMD_ENDIVE_PUT - Topics ═══ Select an item: Syntax Parameters Returns Remarks Glossary ═══ 6.27. EXT_CMD_ENDIVE_QUERY ═══ ═══ EXT_CMD_ENDIVE_QUERY - Syntax ═══ /*******************************************/ /* Description: EXT_CMD_ENDIVE_QUERY is */ /* mandatory and queries the capabilities */ /* of the hardware. */ /*******************************************/ #include GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to EXT_CMD_ENDIVE_QUERY. */ PVOID pIn; /* NULL. */ PVOID pOut; /* Pointer to an IMAGECAPS data structure. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunction, pIn, pOut); ═══ EXT_CMD_ENDIVE_QUERY Parameter - gid ═══ gid (GID) - input ID of the GRADD. ═══ EXT_CMD_ENDIVE_QUERY Parameter - ulFunction ═══ ulFunction (ULONG) - input Set equal to EXT_CMD_ENDIVE_QUERY. ═══ EXT_CMD_ENDIVE_QUERY Parameter - pIn ═══ pIn (PVOID) - input NULL. ═══ EXT_CMD_ENDIVE_QUERY Parameter - pOut ═══ pOut (PVOID) - output Pointer to an IMAGECAPS data structure. ═══ EXT_CMD_ENDIVE_QUERY Return Value - rc ═══ rc (ULONG) - returns Return codes. RC_SUCCESS RC_ERROR ═══ EXT_CMD_ENDIVE_QUERY - Parameters ═══ gid (GID) - input ID of the GRADD. ulFunction (ULONG) - input Set equal to EXT_CMD_ENDIVE_QUERY. pIn (PVOID) - input NULL. pOut (PVOID) - output Pointer to an IMAGECAPS data structure. rc (ULONG) - returns Return codes. RC_SUCCESS RC_ERROR ═══ EXT_CMD_ENDIVE_QUERY - Remarks ═══ None. ═══ EXT_CMD_ENDIVE_QUERY - Topics ═══ Select an item: Syntax Parameters Returns Remarks Glossary ═══ 7. VIDEOPMI DLL Exported Functions ═══ There is only one exported entry point for VIDEOPMI. The various PMI services are accessed through different function numbers passed in the parameters. The exported entry point is prototyped, together with the PMI-related structures, in the common header file SVGADEFS.h. ═══ 7.1. Exported Entry Point ═══ Prototype typedef APIRET (EXPENTRY *PFNVIDEOPMIREQUEST)( PVIDEO_ADAPTER pAdapterInstance, ULONG Function, PVOID pInput, PVOID pOutput); Parameters pAdapterInstance: Pointer to the current VIDEO_ADAPTER structure. Function: PMIREQUEST function number. pInput: Pointer to the input parameter, if applicable. pOutput: Pointer to the output parameter, if applicable. Return Value NO_ERROR: Successful completion. DOS error messages, otherwise. Notes EXPENTRY is C calling convention defined in OS/2 header file. See the PMIREQUEST function, PMIREQUEST_LOADPMIFILE, for the definition of VIDEO_ADAPTER. ═══ 7.2. Supported Functions ═══ ┌───────────────────────────────────┬─────────────────────────┐ │Function Name │Purpose │ ├───────────────────────────────────┼─────────────────────────┤ │PMIREQUEST_LOADPMIFILE │Load the specified PMI │ │ │file │ ├───────────────────────────────────┼─────────────────────────┤ │PMIREQUEST_SETMODE │Set the given mode │ ├───────────────────────────────────┼─────────────────────────┤ │PMIREQUEST_LOCKREGISTERS │Lock extended registers │ ├───────────────────────────────────┼─────────────────────────┤ │PMIREQUEST_UNLOCKREGISTERS │Unlock extended registers│ ├───────────────────────────────────┼─────────────────────────┤ │PMIREQUEST_CLEANUP │Clean up extended │ │ │registers │ ├───────────────────────────────────┼─────────────────────────┤ │PMIREQUEST_SAVESTATE │Save video adapter state │ ├───────────────────────────────────┼─────────────────────────┤ │PMIREQUEST_RESTORESTATE │Restore video adapter │ │ │state │ ├───────────────────────────────────┼─────────────────────────┤ │PMIREQUEST_GETBANK │Get currently addressed │ │ │bank │ ├───────────────────────────────────┼─────────────────────────┤ │PMIREQUEST_SETBANK │Set current bank │ ├───────────────────────────────────┼─────────────────────────┤ │PMIREQUEST_GETCLUT │Get copy of Color Lookup │ │ │Table │ ├───────────────────────────────────┼─────────────────────────┤ │PMIREQUEST_SETCLUT │Set Color Lookup Table │ ├───────────────────────────────────┼─────────────────────────┤ │PMIREQUEST_GETPALETTE │Get copy of palette │ │ │registers │ ├───────────────────────────────────┼─────────────────────────┤ │PMIREQUEST_SETPALETTE │Set palette registers │ ├───────────────────────────────────┼─────────────────────────┤ │PMIREQUEST_GETFONT │Get current loaded font │ ├───────────────────────────────────┼─────────────────────────┤ │PMIREQUEST_SETFONT │Load given font │ ├───────────────────────────────────┼─────────────────────────┤ │PMIREQUEST_TUNEDISPLAY │Tune the display │ ├───────────────────────────────────┼─────────────────────────┤ │PMIREQUEST_IDENTIFYADAPTER │Identify the installed │ │ │adapter │ ├───────────────────────────────────┼─────────────────────────┤ │PMIREQUEST_QUERYMAXMODEENTRIES │Return number of │ │ │available modes │ ├───────────────────────────────────┼─────────────────────────┤ │PMIREQUEST_QUERYMAXMODELISTSIZE │Return maximum size │ │ │required to store mode │ │ │data │ ├───────────────────────────────────┼─────────────────────────┤ │PMIREQUEST_QUERYMODEINFODATA │Return table of video │ │ │mode information │ ├───────────────────────────────────┼─────────────────────────┤ │PMIREQUEST_QUERYMAXTRAPENTRIES │Return number of trap │ │ │entries │ ├───────────────────────────────────┼─────────────────────────┤ │PMIREQUEST_QUERYTRAPLISTDATA │Return table of data for │ │ │trapped ports │ ├───────────────────────────────────┼─────────────────────────┤ │PMIREQUEST_QUERYMODEHRDWRLIST │Return the set mode │ │ │command list │ ├───────────────────────────────────┼─────────────────────────┤ │PMIREQUEST_WPOSVIDEOACCESS │Map the video resource to│ │ │the address space of the │ │ │calling process │ ├───────────────────────────────────┼─────────────────────────┤ │PMIREQUEST_WPOSGETPIOINT │Get the virtual address │ │ │of a physical address │ └───────────────────────────────────┴─────────────────────────┘ ═══ 7.2.1. PMIREQUEST_LOADPMIFILE ═══ Description Loads the specified .PMI file. Parameters pAdapterInstance: Adapter instance (VIDEO_ADAPTER) Function: PMIREQUEST_LOADPMIFILE pInput: szFile (PSZ) .PMI file name. pOutput: pStatus (PULONG) If the .PMI file is already loaded, the value to which pStatus points is set to TRUE. Otherwise, it is set to FALSE. Related Structures and Defines #define MAX_OEM_STRING 128 #define MAX_DAC_STRING 128 #define MAX_VERSION 128 /* * definitions of bus type */ #define ISA_BUS 0 #define VLB_BUS 1 #define PCI_BUS 2 #define EISA_BUS 3 #define PCMCIA**_BUS 4 #define MCA_BUS 5 /* * endian type */ #define LITTLE_ENDIAN 0 #define BIG_ENDIAN 1 #define HVIDEO PVOID typedef HVIDEO *PHVIDEO; typedef struct _ADAPTERINFO { ULONG ulAdapterID; CHAR szOEMString[MAX_OEM_STRING]; CHAR szDACString[MAX_DAC_STRING]; CHAR szRevision[MAX_VERSION]; ULONG ulTotalMemory; ULONG ulMMIOBaseAddress; ULONG ulPIOBaseAddress; BYTE bBusType; BYTE bEndian; USHORT usDeviceBusID; USHORT usVendorBusID; USHORT SlotID; } ADAPTERINFO, FAR *PADAPTERINFO; /* * Adapter Instance definition. The structure will be passed in * every PMIREQUEST call. */ typedef struct _VIDEO_ADAPTER { HVIDEO hvideo; ADAPTERINFO Adapter; VIDEOMODEINFO ModeInfo; } VIDEO_ADAPTER, FAR *PVIDEO_ADAPTER; See PMIREQUEST_QUERYMODEINFODATA for the definition of VIDEOMODEINFO. Notes If the .PMI file is successfully loaded, the Adapter field in VIDEO_ADAPTER will be filled with the information from the .PMI file. ═══ 7.2.2. PMIREQUEST_SETMODE ═══ Description Sets requested video mode. Parameters Function: PMIREQUEST_SETMODE pInput: pModeId (PMODEID) Pointer to mode ID, from VIDEOMODEINFO structure. pOutput: pHWSetModeList(PHWCOMMAND) Pointer to the set mode hardware command list. Related Structures and Defines typedef ULONG * PMODEID; Notes If pHWSetModeList is not NULL, the hardware command list of SetMode is copied. It will be used in saving and restoring a session. The size of the memory to which pHWSetModeList points is the maximum size of the hardware command list, which is returned by the PMIREQUEST_QUERYMAXMODELISTSIZE function. The HWCOMMAND structure is used internally in VIDEOPMI. ═══ 7.2.3. PMIREQUEST_SAVESTATE ═══ Description Saves partial or complete state of the hardware. Parameters Function: PMIREQUEST_SAVESTATE pInput: None. pOutput: pStateData (PVIDEOSTATE) Pointer to the video state. Related Structures and Defines /* ** possible values for fStateFlags */ #define STATEFLAG_REGISTERS 0x0001 #define STATEFLAG_CLUT 0x0002 #define STATEFLAG_VRAM 0x0004 #define STATEFLAG_FONT 0x0008 typedef BYTE * PVRAMDATA; typedef struct _VIDEOSTATE { ULONG fStateFlags; MODEID miState; PVOID pModeData; ULONG ulVRAMSaveSize; PVRAMDATA pVRAM; PCLUTDATA pCLUT; PFONTDATA pFont; } VIDEOSTATE; typedef VIDEOSTATE FAR *PVIDEOSTATE; See PMIREQUEST_GETCLUT for the definition of PCLUTDATA and PMIREQUEST_GETFONT for the definition of PFONTDATA. Notes miState is the current mode ID in VIDEOMODEINFO. Four states can be saved and restored by setting fStateFlags accordingly, as follows: o Video mode (STATEFLAG_REGISTERS) The SetMode command list was saved in pModeData when the mode was set. For saving state, the values of registers set by BOUTB are copied back to pModeData. For restoring state, pModeData is executed to set the mode. o Video Memory (STATEFLAG_VRAM) Video memory of size ulVRAMSaveSize is saved to pVRAM in saving state or restored from pVRAM in restoring state. o Color Lookup Table (STATEFLAG_CLUT) Color Lookup Table can be saved to or restored from pCLUT. o Font (STATEFLAG_FONT) Font can be saved to or restored from pFont. ═══ 7.2.4. PMIREQUEST_RESTORESTATE ═══ Description Restores the state of the hardware from supplied data. Parameters Function: PMIREQUEST_RESTORESTATE pInput: pStateData (PVIDEOSTATE) Pointer to the video state. pOutput: None. Related Structures and Defines See PMIREQUEST_SAVESTATE. Notes See PMIREQUEST_SAVESTATE. ═══ 7.2.5. PMIREQUEST_LOCKREGISTERS ═══ Description Locks extended registers. Parameters Function: PMIREQUEST_LOCKREGISTERS pInput: None. pOutput: None. Related Structures and Defines None. Notes The [LOCK] section in the .PMI file will be executed. ═══ 7.2.6. PMIREQUEST_UNLOCKREGISTERS ═══ Description Unlocks extended registers. Parameters Function: PMIREQUEST_UNLOCKREGISTERS pInput: None. pOutput: None. Related Structures and Defines None. Notes The [UNLOCK] section in the .PMI file will be executed. ═══ 7.2.7. PMIREQUEST_CLEANUP ═══ Description Executes the cleanup section. Parameters Function: PMIREQUEST_CLEANUP pInput: None. pOutput: None. Related Structures and Defines None. Notes The [CLEANUP] section in the .PMI file will be executed. ═══ 7.2.8. PMIREQUEST_GETBANK ═══ Description Gets current bank. Parameters Function: PMIREQUEST_GETBANK pInput: None. pOutput: pBankData (PBANKDATA) Related Structures and Defines typedef struct _BANKDATA { MODEID miBank; /* ID of the current mode */ ULONG ulBank; /* Current bank number */ } BANKDATA; typedef BANKDATA FAR *PBANKDATA; Notes The current bank number is saved in pBankData->ulBank. ═══ 7.2.9. PMIREQUEST_SETBANK ═══ Description Sets bank to requested value. Parameters Function: PMIREQUEST_SETBANK pInput: pBankData (PBANKDATA) pOutput: None. Related Structures and Defines See PMIREQUEST_GETBANK. Notes The current bank is set to pBankData->ulBank by executing the [SETBANK] section in the .PMI file. ═══ 7.2.10. PMIREQUEST_GETCLUT ═══ Description Gets a copy of Color Lookup Table from hardware. Parameters Function: PMIREQUEST_GETCLUT pInput: None. pOutput: pCLUTData (PCLUTDATA) Related Structures and Defines typedef struct _SVGARGB { BYTE bR; BYTE bG; BYTE bB; BYTE bUnused; } SVGARGB; typedef SVGARGB FAR *PSVGARGB; typedef struct _CLUTDATA { ULONG ulRGBCount; /* Number of aRGB entries that follow */ ULONG ulRGBStart; /* Start index for RGB triplets */ SVGARGB aRGB[1]; /* One defined, ulRGBCount entries */ } CLUTDATA; typedef CLUTDATA FAR *PCLUTDATA; Notes None. ═══ 7.2.11. PMIREQUEST_SETCLUT ═══ Description Sets Color Lookup Table to supplied values. Parameters Function: PMIREQUEST_SETCLUT pInput: pCLUTData (PCLUTDATA) pOutput: None. Related Structures and Defines See PMIREQUEST_GETCLUT. Notes None. ═══ 7.2.12. PMIREQUEST_GETPALETTE ═══ Description Gets a copy of palette registers from hardware. Parameters Function: PMIREQUEST_GETPALETTE pInput: None. pOutput: pPaletteData (PPALETTEDATA) Related Structures and Defines typedef struct _PALETTEDATA { ULONG ulPalCount; /* No. of entries that follow */ ULONG ulPalStart; /* Start index for data */ BYTE bPaletteData[1]; /* One defined, ulPalCount entries */ } PALETTEDATA; typedef PALETTEDATA FAR *PPALETTEDATA; Notes None. ═══ 7.2.13. PMIREQUEST_SETPALETTE ═══ Description Sets palette registers to supplied values. Parameters Function: PMIREQUEST_SETPALETTE pInput: pPaletteData (PPALETTEDATA) pOutput: None. Related Structures and Defines See PMIREQUEST_GETPALETTE. Notes None. ═══ 7.2.14. PMIREQUEST_GETFONT ═══ Description Reads current font from video memory. Parameters Function: PMIREQUEST_GETFONT pInput: None. pOutput: pfontData (PFONTDATA) Related Structures and Defines typedef struct _FONTDATA { ULONG ulCharCount; /* Number of characters in font */ ULONG ulFontHeight; /* Number of scanlines per character */ BYTE bFontData[1]; /* ulCharCount*ulFontHeight entries */ } FONTDATA; typedef FONTDATA FAR *PFONTDATA; Notes None. ═══ 7.2.15. PMIREQUEST_SETFONT ═══ Description Sets font to that supplied. Parameters Function: PMIREQUEST_SETFONT pInput: pfontData (PFONTDATA) pOutput: None. Related Structures and Defines See PMIREQUEST_GETFONT. Notes None. ═══ 7.2.16. PMIREQUEST_TUNEDISPLAY ═══ Description Executes the [TuneDisplay] section in the .PMI file. Parameters Function: PMIREQUEST_TUNEDISPLAY pInput: None. pOutput: None. Related Structures and Defines None. Notes None. ═══ 7.2.17. PMIREQUEST_IDENTIFYADAPTER ═══ Description Executes the [IdentifyAdapter] section in the specified .PMI file. Parameters Function: PMIREQUEST_IDENTIFYADAPTER pInput: szFileName (PSZ) .PMI file name. pOutput: None. Related Structures and Defines None. Notes If the .PMI file is for the adapter installed, NO_ERROR is returned. Otherwise, ERROR_ADAPTER_NOT_SUPPORTED is returned. ═══ 7.2.18. PMIREQUEST_QUERYMAXMODEENTRIES ═══ Description Returns maximum number of mode entries available. Parameters Function: PMIREQUEST_QUERYMAXMODEENTRIES pInput: None. pOutput: pulModes (PULONG) Pointer to the number of available modes. Related Structures and Defines None. Notes None. ═══ 7.2.19. PMIREQUEST_QUERYMAXMODELISTSIZE ═══ Description Returns maximum size required to save a mode list. Parameters Function: PMIREQUEST_QUERYMAXMODELISTSIZE pInput: None. pOutput: pulMaxListSize (PULONG) Number of bytes required to store largest mode data list. Related Structures and Defines None. Notes None. ═══ 7.2.20. PMIREQUEST_QUERYMODEINFODATA ═══ Description Returns an array of all available video modes. Parameters Function: PMIREQUEST_QUERYMODEINFODATA pInput: None. pOutput: pVideoModeInfo (PVIDEOMODEINFO) Array of available video mode structures. Related Structures and Defines /* ** Mode flag values ** used in VIDEOMODEINFO */ #define MODE_FLAG_NOT_MONO 0x0001 /* Mono-compatible */ #define MODE_FLAG_GRAPHICS 0x0002 /* Text mode, Graphics */ #define MODE_FLAG_NO_CLR_BRST 0x0004 /* Disable Color burst */ #define MODE_FLAG_NATIVE 0x0008 /* Native (advanced function) */ #define IGNORE_CLR_BRST 0x0010 /* Disable color burst */ /* doesn't make sense for this mode */ #define NOT_PLASMA 0x0020 /* won't work on plasma */ /* display */ #define MODE_FLAG_VGA_ENTRY 0x0040 /* VGA mode, need clean up */ typedef struct _VIDEOMODEINFO { MODEID miModeId; /* used to make setmode request */ USHORT usType; /* mode type bits */ USHORT usInt10ModeSet; /* int 10 mode */ USHORT usXResolution; /* horizontal pels */ USHORT usYResolution; /* vertical scan lines */ ULONG ulBufferAddress; /* physical address of VRAM */ ULONG ulApertureSize; /* VRAM aperture */ BYTE bBitsPerPixel; /* number of colors */ BYTE bBitPlanes; /* number of planes */ BYTE bXCharSize; /* font width */ BYTE bYCharSize; /* font height */ USHORT usBytesPerScanLine; /* logical line length in bytes */ USHORT usTextRows; /* text rows */ ULONG ulPageLength; /* number of bytes to save a plane */ ULONG ulSaveSize; /* total bytes of VRAM to save */ /* * Monitor Info */ BYTE bVrtRefresh; BYTE bHrtRefresh; BYTE bVrtPolPos; BYTE bHrtPolPos; USHORT usScrnTop; USHORT usScrnBottom; USHORT usScrnLeft; USHORT usScrnRight; CHAR szColorFormat[8]; /* for true color or hi-color modes */ CHAR szColorWeight[8]; /* for true color or hi-color modes */ } VIDEOMODEINFO; typedef VIDEOMODEINFO FAR *PVIDEOMODEINFO; Notes None. ═══ 7.2.21. PMIREQUEST_QUERYMAXTRAPENTRIES ═══ Description Returns the maximum number of traplist entries. Parameters Function: PMIREQUEST_QUERYMAXTRAPENTRIES pInput: None. pOutput: pulNumTrapRegs (PULONG) Number of traplist entries. Related Structures and Defines None. Notes None. ═══ 7.2.22. PMIREQUEST_QUERYTRAPLISTDATA ═══ Description Returns an array of trap register information structures. Parameters Function: PMIREQUEST_QUERYTRAPLISTDATA pInput: None. pOutput: pTrapRegInfo (PTRAPREGINNFO) Array of trap info structures. Related Structures and Defines /* ** flag values for fPortFlags in TRAPREGINFO @V2.2TSU00 */ #define BYTE_IOPORT 0x001 #define WORD_IOPORT 0x002 #define DWORD_IOPORT 0x004 #define BYTE_MMIOPORT 0x008 #define WORD_MMIOPORT 0x010 #define DWORD_MMIOPORT 0x020 #define INDEXED 0x040 #define ACCEL 0x080 #define RESET_PORT 0x100 #define READ_ONLY 0x200 #define WRITE_ONLY 0x400 #define READ_WRITE 0x800 #define MASK_SIZE 32 typedef struct _TRAPREGINFO { ULONG ulAddressPort; /* Address Port */ ULONG ulDataPort; /* Data Port */ USHORT fPortFlags; /* port type */ USHORT usIndex; /* value in index port */ ULONG ulIndexMask; /* index mask */ ULONG ulDataMask; /* data mask */ ULONG ulResetOneMask; /* */ ULONG ulResetZeroMask; /* */ BYTE abIndexList[MASK_SIZE]; /* bit mask of trapped */ /* indexed ports */ BYTE abUpdateList[MASK_SIZE];/* bit mask of updated */ /* port indices */ PVOID aTrapRegData; /* trap registers data area */ } TRAPREGINFO; typedef TRAPREGINFO FAR *PTRAPREGINFO; Notes None. ═══ 7.2.23. PMIREQUEST_QUERYMODEHRDWRLIST ═══ Description Returns the SetMode hardware command list of the passed mode ID. Parameters Function: PMIREQUEST_QUERYMODEHRDWRLIST pInput: pulModeId (PMODEID) Pointer to the mode ID. pOutput: pSetModeList (PHWCOMMAND) Pointer to the SetMode hardware command list. Related Structures and Defines None. Notes None. ═══ 7.2.24. PMIREQUEST_WPOSVIDEOACCESS ═══ Description Maps the video hardware resources to the address space of the calling process. Parameters Function: PMIREQUEST_WPOSVIDEOACCESS pInput: None. pOutput: pResource (PVIDEORESOURCEPACK) Pointer to resource definition packet. Related Structures and Defines typedef struct { cons_resource_info_t * ConsRes; // array of resource definition ULONG ulNumCons; // number of resources } VIDEORESOURCEPACK, * PVIDEORESOURCEPACK; Notes This call should be made before any other PMI calls. It will map the hardware resource to the calling process's address space. The output parameter is optional. It can be NULL or a pointer to VIDEORESOURCEPACK. If it is not NULL, the number of resources and the array of cons_resource_info_t for the resources will be returned in the output parameter packet. The cons_resource_info_t array is defined in the microkernel header files. If you do not want to handle detailed microkernel I/O functions, this information is not needed. ═══ 7.2.25. PMIREQUEST_GETPIOINFO ═══ Description Gets the virtual address of the passed physical address. Parameters Function: PMIREQUEST_GETPIOINFO pInput: ulPhysAddr (ULONG) Physical address. pOutput: pPioInfoPack (PPIOINFOPACK) Pointer to PIOINFOPACK. Related Structures and Defines typedef struct { ULONG ulVirtAddr; // virtual address after mapping ULONG ulOffset; // offset within the address range // of this video resource pio_info_t * pPioInfo; // pointer to the pio_info_t which this // physical address is in } PIOINFOPACK, * PPIOINFOPACK; Notes Every piece of resource defined in rdf.stz is represented as a pio_info_t structure. Microkernel PIO hardware access functions require the pointer to the pio_info_t structure and the offset within the address range of the resource defined in rdf.stz. If you do not want to call microkernel hardware access functions to access hardware, you do not need this pointer. The pio_info_t in this structure definition can be replaced with ULONG; in this case, microkernel header files need not be included. ═══ 7.2.26. Code Sample ═══ #include #include #define DLLNAME "videopmi" #define REQUEST_ENTRYPOINT "VIDEOPMI32Request" #define FAIL_LENGTH 256 /* * Adapter instance. */ VIDEO_ADAPTER AdapterInstance; /* * Entry point to videopmi */ PFNVIDEOPMIREQUEST pfnPMIRequest; /* * mode table. It is an array of VIDEOMODEINFOs. */ PVIDEOMODEINFO ModeTable; ULONG ulTotalModes; ═══ 7.2.26.1. Load PMI File ═══ /************************************************************ * Load the .PMI file, get the hardware information about the * adapter and the entry point to videopmi. * * Returns 0 if successful; DOS error token, otherwise. ************************************************************/ APIRET LoadPMIService (VOID) { APIRET rc; char sFail[FAIL_LENGTH] = {0}; HMODULE hmodVIDEOPMI; /* * Load videopmi.dll */ if (!(rc = DosLoadModule (sFail, FAIL_LENGTH, DLLNAME, &hmodVIDEOPMI))) { /* * Get PMIREQUEST entry point */ if (!(rc = DosQueryProcAddr (hmodVIDEOPMI, 0, REQUEST_ENTRYPOINT, &pfnPMIRequest))) /* * Map the hardware resource * ADAPTERINFO in AdapterInstance will be filled with the * information in .PMI file, e.g., TotalMemory. * Check svgadefs.h for details. */ rc = pfnPMIRequest (&AdapterInstance, PMIREQUEST_WPOSVIDEOACCESS, NULL, NULL); if (rc) DosFreeModule (hmodVIDEOPMI); } return rc; } ═══ 7.2.26.2. Set Up Mode Table ═══ /************************************************************ * Copy the mode table from videopmi. It is an arrary of modes. * All the information in [ModeInfo] and * [MonitorModeInfo], if any, is included. * * Returns 0 if successful; DOS error token, otherwise. ************************************************************/ APIRET SetUpModeTable (VOID) { APIRET rc; /* * Get the total number of modes */ if (!(rc = pfnPMIRequest (&AdapterInstance, PMIREQUEST_QUERYMAXMODEENTRIES, NULL, &ulTotalModes))) /* * Allocate memory for mode table */ if (!(rc = DosAllocSharedMem ((PPVOID)&ModeTable, NULL, ulTotalModes * sizeof (VIDEOMODEINFO), OBJ_GETTABLE | PAG_COMMIT | PAG_WRITE))) /* * Copy mode table. * Please check svgadefs.h for the fields in VIDEOMODEINFO. */ rc = pfnPMIRequest (&AdapterInstance, PMIREQUEST_QUERYMODEINFODATA, NULL, ModeTable); return rc; } ═══ 7.2.26.3. Set Mode ═══ /************************************************************ * You can select the mode based on any information in the VIDEOMODEINFO * structure. The following is only an example to set the graphics mode * based on resolution and refresh rate. * PM driver should not call videopmi to set the mode directly. * It should call BVH to set the mode as before, such that * the mode can be set based on the current monitor capability * handled by BVH. * * Returns 0 if successful; DOS error token, otherwise. ************************************************************/ APIRET SETSVGAMODE (ULONG ulHorRes, ULONG ulVerRes, ULONG ulColors, ULONG ulVerRefr, PULONG pulModeInd, PCLUTDATA pCLUTData) { APIRET rc=0xFFFF; ULONG i; /* Search mode */ if (ulVerRefr >= 0xFFL) /* pick the first mode of the resolution */ { for(i=0; i < ulTotalModes; i++) if ((ModeTable[i].usXResolution == (USHORT) ulHorRes) && (ModeTable[i].usYResolution == (USHORT) ulVerRes) && (ModeTable[i].bBitsPerPixel == (BYTE) ulColors)) *pulModeInd = i; } else /* verify all including the refresh parameter */ { for(i=0; i < ulTotalModes; i++) if ((ModeTable[i].usXResolution == (USHORT )ulHorRes) && (ModeTable[i].usYResolution == (USHORT) ulVerRes) && (ModeTable[i].bBitsPerPixel == (BYTE) ulColors) && ((ModeTable[i].bVrtRefresh == 0xFF) || (ModeTable[i]bVrtRefresh == (BYTE) ulVerRefr))) *pulModeInd= i; } if (i == ulTotalModes) return rc; /* mode not found */ /* * Copy VIDEOMODEINFO of the selected mode to AdapterInstance. * Depending on the .PMI file, this information may be needed. */ AdapterInstance.ModeInfo = ModeTable[*pulModeInd]; /* * Call videopmi to set the mode. */ rc = pfnPMIRequest (&AdapterInstance, PMIREQUEST_SETMODE, &ModeTable[*pulModeInd].miModeId, NULL); if (rc) return rc; else /* Load Color Lookup Table */ if (ModeTable[*pulModeInd].bBitsPerPixel <= 8) rc = pfnPMIRequest (&AdapterInstance, PMIREQUEST_SETCLUT, pCLUTData, NULL); return rc; } ═══ 7.2.26.4. Write to Video Buffer ═══ APIRET DisplayImageBuffer (ULONG ulModeInd, ULONG ulSize, PBYTE pImageBuffer) { VIDEOSTATE sVideoState = {0}; APIRET rc; sVideoState.miState = ModeTable[ulModeInd].miModeId; sVideoState.fStateFlags |= STATEFLAG_VRAM; sVideoState.ulVRAMSaveSize = ulSize; sVideoState.pVRAM = pImageBuffer; return pfnPMIRequest (&AdapterInstance, PMIREQUEST_RESTORESTATE, &sVideoState, NULL); } ═══ 8. VIDEO Protect-Mode Interface ═══ This chapter describes the syntax of the VIDEO Protect-Mode-Interface (VIDEOPMI) in OS/2 Warp, Version 3, PowerPC Edition, which is an extension of the VESA SVPMI standard currently in use by the operating system's base and virtual video subsystems. The interface describes a graphics adapter in terms of its ports and memory space. The interface also provides a means to query supported modes and set, save, and restore video modes in Protect-Mode. ═══ 8.1. Overview ═══ The VIDEOPMI interface provides parameters for the adapter virtualization in multiple DOS sessions and a number of support functions. The adapter description is provided as a flat file with a .PMI extension. The main goal of the VIDEOPMI interface is to centralize all of the SetMode-related services and provide a consistent interface that is not dependent on availability of BIOS service or OEM utilities. The following list includes the topics covered in this chapter: o .PMI file o PMI Procedural Interface o Supported Modes o Monitor Timings Support o Save and Restore State o Adapter Configuration o Video Configuration and Installation ═══ 8.1.1. .PMI file ═══ The VIDEOPMI interface is driven by the sections of the .PMI file. There are two main types of sections: o Those that describe adapter capabilities o Those that service hardware programming requests Query sections provide information on hardware descriptions; lists of ports; lists of supported modes; and the range or set of supported timing values. The Set sections provide the capability to identify adapters; unlock registers; cleanup, size, and position the active display; set a mode; save and restore a mode, and the VRAM used by the mode. The VIDEOPMI language defines a video adapter as a hardware controller in terms of its I/O and memory addresses that are programmable by the CPU. The video controller can be a dumb frame VGA/SVGA, an accelerator, or a general-purpose coprocessor. The .PMI file must contain all of the informational sections and a minimal set of Set sections (see PMI Sections). An adapter description starts with its Hardware section, followed by IdentifyAdapter, a number of support sections, and a list of all available modes with the corresponding SetMode sections. The PMI facilitates dynamic hardware configuration, which includes port remapping as well as adding or removing an adapter and its PMI definition. It also includes changing the attached display and multiple instances of the same video hardware driven by the same .PMI file. The interface defines monitor timing variables needed to drive a CRT monitor. These variables provide extensive monitor support and a consistent user configuration interface. The PMI language also facilitates programming of the support chips that can be mapped into the I/O and memory space addressable by the CPU, such as external clock-synchronizing chips or smart Digital-to-Analog Converters (DACs). .PMI files are to be provided by the video chip or adapter manufacturers, or by the providers of the display drivers. The file should be part of the video-adapter installation kit, either as a pre-manufactured flat file or one created by the OEM's installation utility. The activation of PMI services for an adapter does not require a reset or power-up. ═══ 8.1.2. PMI Procedural Interface ═══ .PMI file sections are interpreted by the VIDEOPMI interpreter, also called the VIDEOPMI engine, and translated into information blocks or into hardware command lists. In the OS/2 Warp, PowerPC Edition environment, VIDEOPMI callers include the OS/2 full-screen driver (OS2CHAR.DLL), PM driver, and system configuration utilities. The VIDEOPMI Procedural Interface defines a structure that corresponds to the video hardware instance, which contains all of the PMI keyvariables listed in PMI Language Elements. This structure is called the VIDEO_ADAPTER structure. It defines the state of the adapter in terms of its hardware configuration elements, such as I/O and Memory range, and its current mode-state parameters. All of the Set type of procedural calls pass the VIDEO_ADAPTER structure, which then allows each PMI section to take the current state into account in its programming. See Supported Modes, as well as [SetMode] and [ModeInfo] in PMI Sections for more information on the mode elements. The Procedural Interface of the VIDEOPMI Interpreter is covered in VIDEOPMI DLL Exported Functions. ═══ 8.1.2.1. Limitations of the PMI ═══ The following limitations exist in the PMI: o PMI does not provide a graphical interface. o PMI does not provide a means of accessing addresses that are internal to the video controller and are not mappable into the CPU space. o Save and Restore Hardware State Services have certain limitations (see "Save and Restore State" in this chapter). o PMI does not provide the means to manipulate certain video parameters outside the context of the SetMode section. PMI does allow, and it requires, indirect management of all of the parameters within the Mode Set sections. For example, there are no services for the manipulation of the hardware cursor or RAMDAC outside the context of a mode set. These services are an integral part of the SetMode. Programming of the monitor timing is considered a special case. It is an integral part of the SetMode, but it also can be independently invoked, if the .PMI file defines a SetMonitorTimings section. The same is true for manipulation of the active display size. If the .PMI file contains a TuneDisplay section, this manipulation is offered independently. o Port descriptions have some limitations: - Ports that require double or triple indirection cannot be adequately described in the PMI language. - I/O addresses that serve as latches, or flip-flops, cannot be successfully described. - There are no provisions for describing port addresses that define different registers depending on the read or write access. These limitations have an influence on the level and success of the adapter virtualization using the system-provided virtual driver. See [TrapRegs] in PMI Sections. ═══ 8.1.3. Supported Modes ═══ This section lists the OS/2 Warp, PowerPC Edition requirements for the modes included in a .PMI file. Each supported mode is represented by a set of sections, as follows: o Comment (optional) o ModeInfo (required) o MonitorModeInfo (optional) o SetMode (optional) The ModeInfo section is a list of the common mode elements (PMI keyvariables) that define the resolution, window, and size elements of the mode. The mode definition is then complemented by all of the MonitorModeInfo sections following the ModeInfo section. There could be zero or more MonitorModeInfo sections, depending on the capabilities of the hardware to program timings. An adapter may not support a CRT in a particular mode; a single MonitorModeInfo section with zero values is used to indicate such a case. If the adapter can support only a distinct set of values, rather than a range of horizontal and vertical refresh values, multiple MonitorModeInfo sections per horizontal/vertical refresh pair are used to indicate this fact. An adapter with flexibility in programming a range of dotclock (which translates into horizontal and vertical refreshes) should list only one MonitorModeInfo entry with the end of range values for the vertical/horizontal refresh. Suggested modes include the following: o 40 x 25 and 80 x 25 text. o At least one of the 132-column text modes (if applicable). o At best, all of the supported 256-color modes with respective refresh rates (see "Monitor Timings Support" in this chapter). At the minimum, modes that are supported by the respective Presentation Manager display driver. If the adapter in question has both accelerated and non-accelerated modes, only the accelerated modes should be provided. o At best, all of the supported hi-color and true-color modes with respective refresh rates (see "Monitor Timings Support" in this chapter). At the minimum, modes which are supported by the respective Presentation Manager display driver. If the adapter in question has both accelerated and nonaccelerated modes, only the accelerated modes should be provided. ═══ 8.1.4. Monitor Timings Support ═══ The PMI defines eight display-timing-related variables as mode keyvariables. These variables facilitate selection of the mode, depending on the current monitor specification and sizing of the active display for the current mode. The MonitorModeInfo section contains all of the timing-related PMI key variables. The display-timing-related variables are: VerticalRefresh Vertical refresh in Hz (rounded to the nearest integer) HorizontalRefresh Horizontal refresh in KHz (rounded to the nearest integer) HPolarityPositive Contains the Horizontal polarity (0,1) for the current mode selection VPolarityPositive Contains the Vertical polarity (0,1) for the current mode selection ScreenLeftEdge Represents the end of the horizontal blanking (HBP) in pixel count along the horizontal sweep (HSP) ScreenRightEdge Represents the start of the horizontal blanking (HFP) in pixel count along the horizontal sweep (HSP) ScreenTopEdge Represents the end of the vertical blanking (VBP) in line count along the vertical sweep (VSP) ScreenBottomEdge Represents the start of the vertical blanking (VFP) The last four timing elements, defining the start and end of the horizontal active display and start and end of the vertical active display, are suggested as mode elements in order to enhance visual quality. Their values are never directly communicated to the end user configuring the adapter, only the net results. The values are manipulated through a TuneDisplay function as part of the SetMode or upon the end user's configuration request. See [TuneDisplay] in PMI Sections. There is no interface for specification and manipulation of the widths of the Horizontal Sweep (HSP) and Vertical Sweep (VSP) signals. If an adapter is capable of supporting both non-CRT- and CRT-style displays, modes of both types should be listed. Non-CRT Mode sections are those that have 0 for both horizontal and vertical refresh rate. If the adapter has monitor sensing, identification, and auto-adjusting capability built in so that software manipulation of the timing-related registers is not required, none of the timing-related mode elements have to be specified. No MonitorModeInfo sections should be included and monitor sizing parameters and the TuneDisplay function should not be listed. The vendor providing the .PMI file can supply either a single MonitorModeInfo, which denotes the upper limit for horizontal and vertical refresh, or a number of MonitorModeInfo sections with distinct sets of horizontal and vertical refresh values. In the first case, the OS/2 Warp, PowerPC Edition configuration utility offers refresh values that are part of the current monitor definition for the desired resolution, as long as the monitor specification is within the range specified by the adapter. If more than one MonitorModeInfo section exists per mode, an exact match of the vertical refresh values between the adapter and monitor specification is performed by the OS/2 Warp, PowerPC Edition Display Configuration Manager. Polarity PMI keyvariables are not required, unless an exact match with the monitor's capabilities is desired by the adapter vendor. ═══ 8.1.5. Save and Restore State ═══ VIDEOPMI does not have dedicated SaveState or RestoreState sections. The VIDEOPMI engine does offer those services. ═══ 8.1.5.1. SaveRestore VRAM ═══ VIDEOPMI offers saving and restoring of the video buffer of SaveSize for each mode and is internally aware of the type of VRAM access it has to perform. The parameters taken into consideration when addressing the VRAM are BufferAddress, ApertureSize, and SaveSize. See [ModeInfo] in PMI Sections. If ApertureSize is equal to or greater than SaveSize, direct linear access to the BufferAddress is assumed. If this is not the case, the SetBank function is necessary in order to save and restore the entire on-screen VRAM. Granularity of a bank is assumed to be the ApertureSize. SaveSize should be set to reflect the logical line length programmed by the current mode, rather than just horizontal resolution. ═══ 8.1.5.2. SaveRestore Hardware ═══ This service is available for .PMI files that use the PMI language to define SetMode sections. The PM driver performs its own Save and Restore of the state and is not dependent on the service. The OS2CHAR.DLL uses the Save and Restore State service and, in case of a partial restore, reissues the mode set and restores the important video attributes. The SaveRestore Hardware service is based on the PMI sequence for the SetMode; all of the ports that are programmed by the SetMode section for the current mode will be saved and restored. When saving a mode, the VIDEOPMI interpreter parses the command list of the SetMode section. BOUTB commands are converted into BINB commands. The VIDEOPMI executes the newly constructed section in order to capture register values and converts all of the commands back into their original SetMode format. The command list is then ready for a subsequent RestoreState call and is returned to the user. This approach has some limitations, mainly for adapters that employ double and higher indirection levels in register addressing; for example, the WDc24. ═══ 8.1.6. Adapter Configuration ═══ This portion of the chapter specifies the requirements placed on the .PMI file by the video subsystem. It does not address the physical installation steps for an adapter, the bus management, device enumeration, and conflict management employed by the operating system. An adapter is defined by its Hardware section, which lists the type of bus, the default start address of the I/O and memory space, and alternative addresses for the I/O and memory space, as addressable by the CPU. The adapter is uniquely defined by its OEMString and Version strings. On desktop PowerPCs, only PCI adapters are supported. ═══ 8.2. PMI Language Elements ═══ The VIDEOPMI language consists of the following elements: o Sections o User-defined functions o Expressions o PMI commands, identifiers, constants, variables, string-literals, and comments The language is not case-sensitive, so BOUTB and boutb represent the same identifier. Throughout this section, Backus-Naur Form (BNF) grammar is used to describe the syntax. Some examples are given in the text. Where such examples are omitted, sample .PMI files accompanying the document should be used as a reference. ═══ 8.2.1. Comments and Delimiters ═══ Comments can be either in-line comments (//) or ANSI C-style comments (/* */). White space is used as the token delimiter and a semicolon (;) is used as the expression delimiter. The Comment section defines a mode-info related comment that describes the mode to the user. See [Comment] in PMI Sections. ═══ 8.2.2. Include Files ═══ PMI allows for inclusion of other .PMI files, all of which must conform to the PMI language. An Include file facility is provided in order to offer flexibility in supporting multiple adapter configurations with a single .PMI file. PMI sub-files are included via #include directive. The include statement can be found anywhere in the .PMI file as long as it meets the following conditions: o The include statement does not violate the integrity of the section before and the section after. o References to the objects belonging to the include file are made after the inclusion. The included files should be in the same directory as the current .PMI file. #include "filename" //PMI extension assumed ═══ 8.2.3. Constants, String-Literals, Identifiers, and Keywords ═══ PMI constants are 32-bit integer constants, either in decimal or hexadecimal format. ::= '0'..'9' ::= | 'a'..'f' ::= 'a'..'z' | 'A'.. 'Z'| '_' | '.' ::= | ::= '0x' | ::= | String-literals consist of any combination of printable ASCII characters in quotes. String-literals are not parsed in any way; they are stored in their uppercase format and are passed on query-style calls, converting both source and target to uppercase. String-literals are limited to 128 characters in length, including 0 at the end. Binary strings are also limited to 128 bits (4 doublewords). ::= " []" ::= " <'0'|'1'> | <'0'|1'> []" An Identifier, or a name, is a sequence of letters and digits. The first character must be a letter. The underscore (_) and point (.) count as a letter, but point (.) cannot be used in the first position. Maximum length of an identifier is 32 characters. ::= ::= { | [ ]} Keywords are reserved identifiers and are divided into three groups: o PMI keyvariables, which are keywords representing configuration and mode parameters o PMI constants, backed by system-wide definitions o All other reserved identifiers All of the PMI keyvariables are available through the VIDEOPMI programming interface as fields of the video instance structure. They are also available to all of the PMI sections and functions and can be used in conditional statements or expressions. At run time, during a SetMode, some of the ModeInfo PMI keyvariables could differ from the values assigned by the .PMI file. These PMI keyvariables can be modified at the user or system level and are, therefore, regarded as dynamic. Others are called static. At the procedural level, static PMI keyvariables are fixed to the values specified in the .PMI file and cannot be changed for a given mode. Some dynamic variables have a limited set of possible values; others are valid in a range that should be verified by dedicated sections. See [ModeInfo], [Hardware], and [TuneDisplay] in PMI Sections for more information on dynamic vs. static keyvariables. Not all of the PMI keyvariables have to be defined. See [ModeInfo] and [Hardware] in PMI Sections for further explanations. ═══ 8.2.3.1. PMI keyvariables ═══ The following table lists all of the keyvariables for the Protect Mode Interface (PMI): ┌──────────────────────────────┬──────────────────────────────┐ │Name │Section │ ├──────────────────────────────┼──────────────────────────────┤ │ApertureSize │ModeInfo │ ├──────────────────────────────┼──────────────────────────────┤ │BitsPerPixel │ModeInfo │ ├──────────────────────────────┼──────────────────────────────┤ │BufferAddress │ModeInfo │ ├──────────────────────────────┼──────────────────────────────┤ │BusType │Hardware │ ├──────────────────────────────┼──────────────────────────────┤ │BytesPerScanLine │ModeInfo │ ├──────────────────────────────┼──────────────────────────────┤ │ColorFormat │ModeInfo │ ├──────────────────────────────┼──────────────────────────────┤ │ColorWeight │ModeInfo │ ├──────────────────────────────┼──────────────────────────────┤ │DACString │Hardware │ ├──────────────────────────────┼──────────────────────────────┤ │Endian │Hardware │ ├──────────────────────────────┼──────────────────────────────┤ │HorizontalRefresh │MonitorModeInfo │ ├──────────────────────────────┼──────────────────────────────┤ │HPolarityPositive │MonitorModeInfo │ ├──────────────────────────────┼──────────────────────────────┤ │Int10ModeSet │ModeInfo │ ├──────────────────────────────┼──────────────────────────────┤ │MemoryIOAddress │Hardware │ ├──────────────────────────────┼──────────────────────────────┤ │ModeAttributes │ModeInfo │ ├──────────────────────────────┼──────────────────────────────┤ │NumberOfPlanes │ModeInfo │ ├──────────────────────────────┼──────────────────────────────┤ │OEMString │Hardware │ ├──────────────────────────────┼──────────────────────────────┤ │PageLength │ModeInfo │ ├──────────────────────────────┼──────────────────────────────┤ │PortIOAddress │Hardware │ ├──────────────────────────────┼──────────────────────────────┤ │SaveSize │ModeInfo │ ├──────────────────────────────┼──────────────────────────────┤ │ScreenLeftEdge │MonitorModeInfo │ ├──────────────────────────────┼──────────────────────────────┤ │ScreenRightEdge │MonitorModeInfo │ ├──────────────────────────────┼──────────────────────────────┤ │ScreenBottomEdge │MonitorModeInfo │ ├──────────────────────────────┼──────────────────────────────┤ │ScreenTopEdge │MonitorModeInfo │ ├──────────────────────────────┼──────────────────────────────┤ │SlotID │EnableController │ ├──────────────────────────────┼──────────────────────────────┤ │TextRows │ModeInfo │ ├──────────────────────────────┼──────────────────────────────┤ │TotalMemory │Hardware │ ├──────────────────────────────┼──────────────────────────────┤ │VerticalRefresh │MonitorModeInfo │ ├──────────────────────────────┼──────────────────────────────┤ │VPolarityPositive │MonitorModeInfo │ ├──────────────────────────────┼──────────────────────────────┤ │XCharSize │ModeInfo │ ├──────────────────────────────┼──────────────────────────────┤ │XResolution │ModeInfo │ ├──────────────────────────────┼──────────────────────────────┤ │YCharSize │ModeInfo │ ├──────────────────────────────┼──────────────────────────────┤ │YResolution │ModeInfo │ └──────────────────────────────┴──────────────────────────────┘ ═══ 8.2.3.2. PMI Constants ═══ The following table lists the constants used by the Protect Mode Interface (PMI): ┌──────────────────────────────┬──────────────────────────────┐ │Name │Section │ ├──────────────────────────────┼──────────────────────────────┤ │BIG │Hardware │ ├──────────────────────────────┼──────────────────────────────┤ │EISA │Hardware │ ├──────────────────────────────┼──────────────────────────────┤ │ISA │Hardware │ ├──────────────────────────────┼──────────────────────────────┤ │LITTLE │Hardware │ ├──────────────────────────────┼──────────────────────────────┤ │MCA │Hardware │ ├──────────────────────────────┼──────────────────────────────┤ │MMIO │Declarations │ ├──────────────────────────────┼──────────────────────────────┤ │PCI │Hardware │ ├──────────────────────────────┼──────────────────────────────┤ │PCMCIA** │Hardware │ ├──────────────────────────────┼──────────────────────────────┤ │PIO │Declarations │ ├──────────────────────────────┼──────────────────────────────┤ │VLB │Hardware │ └──────────────────────────────┴──────────────────────────────┘ ═══ 8.2.3.3. PMI Keywords ═══ The following table lists the reserved identifiers, called Keywords, used by the Protect Mode Interface (PMI): ┌──────────────────────────────┬──────────────────────────────┐ │Name │Section │ ├──────────────────────────────┼──────────────────────────────┤ │[Cleanup] │PMI sections │ ├──────────────────────────────┼──────────────────────────────┤ │[Comment] │PMI sections │ ├──────────────────────────────┼──────────────────────────────┤ │[Declarations] │PMI sections │ ├──────────────────────────────┼──────────────────────────────┤ │[DisableController] │PMI sections │ ├──────────────────────────────┼──────────────────────────────┤ │[EnableController] │PMI sections │ ├──────────────────────────────┼──────────────────────────────┤ │[GetBank] │PMI sections │ ├──────────────────────────────┼──────────────────────────────┤ │[Hardware] │PMI sections │ ├──────────────────────────────┼──────────────────────────────┤ │[IdentifyAdapter] │PMI sections │ ├──────────────────────────────┼──────────────────────────────┤ │[IsEngineBusy] │PMI sections │ ├──────────────────────────────┼──────────────────────────────┤ │[ModeInfo] │PMI sections │ ├──────────────────────────────┼──────────────────────────────┤ │[MonitorModeInfo] │PMI sections │ ├──────────────────────────────┼──────────────────────────────┤ │[PMIVersion] │PMI sections │ ├──────────────────────────────┼──────────────────────────────┤ │[SetBank] │PMI sections │ ├──────────────────────────────┼──────────────────────────────┤ │[SetMode] │PMI sections │ ├──────────────────────────────┼──────────────────────────────┤ │[SetMonitorTimings] │PMI sections │ ├──────────────────────────────┼──────────────────────────────┤ │[TrapRegs] │PMI sections │ ├──────────────────────────────┼──────────────────────────────┤ │[TuneDisplay] │PMI sections │ ├──────────────────────────────┼──────────────────────────────┤ │[UnLock] │PMI sections │ ├──────────────────────────────┼──────────────────────────────┤ │ABOUTDW │PMI commands │ ├──────────────────────────────┼──────────────────────────────┤ │ABOUTW │PMI commands │ ├──────────────────────────────┼──────────────────────────────┤ │ACCEL │TrapRegs │ ├──────────────────────────────┼──────────────────────────────┤ │BYTE_IOPORT │TrapRegs │ ├──────────────────────────────┼──────────────────────────────┤ │BYTE_MMIOPORT │TrapRegs │ ├──────────────────────────────┼──────────────────────────────┤ │BINB │PMI commands │ ├──────────────────────────────┼──────────────────────────────┤ │BOUTB │PMI commands │ ├──────────────────────────────┼──────────────────────────────┤ │DATAMASK │TrapRegs │ ├──────────────────────────────┼──────────────────────────────┤ │DWORD_IOPORT │TrapRegs │ ├──────────────────────────────┼──────────────────────────────┤ │DWORD_MMIOPORT │TrapRegs │ ├──────────────────────────────┼──────────────────────────────┤ │ENDWHILE │PMI constructs │ ├──────────────────────────────┼──────────────────────────────┤ │GOTO │PMI constructs │ ├──────────────────────────────┼──────────────────────────────┤ │IF │PMI constructs │ ├──────────────────────────────┼──────────────────────────────┤ │INB │PMI commands │ ├──────────────────────────────┼──────────────────────────────┤ │INDEX │TrapRegs │ ├──────────────────────────────┼──────────────────────────────┤ │INDEXMASK │TrapRegs │ ├──────────────────────────────┼──────────────────────────────┤ │INDW │PMI commands │ ├──────────────────────────────┼──────────────────────────────┤ │INW │PMI commands │ ├──────────────────────────────┼──────────────────────────────┤ │MEMCMP │PMI constructs │ ├──────────────────────────────┼──────────────────────────────┤ │OUTB │PMI commands │ ├──────────────────────────────┼──────────────────────────────┤ │OUTDW │PMI commands │ ├──────────────────────────────┼──────────────────────────────┤ │OUTW │PMI commands │ ├──────────────────────────────┼──────────────────────────────┤ │RESET │TrapRegs │ ├──────────────────────────────┼──────────────────────────────┤ │READB │PMI commands │ ├──────────────────────────────┼──────────────────────────────┤ │READDW │PMI commands │ ├──────────────────────────────┼──────────────────────────────┤ │READW │PMI commands │ ├──────────────────────────────┼──────────────────────────────┤ │RMWB │PMI commands │ ├──────────────────────────────┼──────────────────────────────┤ │RMWBI │PMI commands │ ├──────────────────────────────┼──────────────────────────────┤ │RMWW │PMI commands │ ├──────────────────────────────┼──────────────────────────────┤ │RO │TrapRegs │ ├──────────────────────────────┼──────────────────────────────┤ │RW │TrapRegs │ ├──────────────────────────────┼──────────────────────────────┤ │STRCMP │PMI constructs │ ├──────────────────────────────┼──────────────────────────────┤ │WHILE │PMI constructs │ ├──────────────────────────────┼──────────────────────────────┤ │WO │TrapRegs │ ├──────────────────────────────┼──────────────────────────────┤ │WORD_IOPORT │TrapRegs │ ├──────────────────────────────┼──────────────────────────────┤ │WORD_MMIOPORT │TrapRegs │ ├──────────────────────────────┼──────────────────────────────┤ │WRITEB │PMI commands │ ├──────────────────────────────┼──────────────────────────────┤ │WRITEDW │PMI commands │ ├──────────────────────────────┼──────────────────────────────┤ │WRITEW │PMI commands │ └──────────────────────────────┴──────────────────────────────┘ Variables are user-defined identifiers that symbolically represent a hardware register in terms of its offset, in either the CPU's I/O space or memory space. Use of variables is required for system architectures in which dynamic configuration and multiple instances of the same hardware are possible. A variable must be declared prior to being used. See [Declarations] in PMI Sections. ::= = 'MMIO{''}' ::= = 'PIO{''}' ::= ::= For example: seq_address = PIO{0x3c4}; interrupt_en = MMIO{0x00000080} Labels are user-defined identifiers that refer to code locations. The scope of a label is its containing function (or section). A label name within an adapter definition should be unique. The label must be declared prior to its reference.