## Display Device Driver Reference for OS/2

[prev][next][parent][TOC]

### Virtual Video Device Driver Services

Multiple virtual device drivers can be installed for the same adapter. Usually, the second virtual device driver detects that the adapter's address space is already reserved, and so, fails to install. However, virtual video device drivers can be written to take control of a device from an owning virtual device driver when a certain event occurs and then to relinquish control later. This is accomplished by supporting the Release Device and Accept Device inter-virtual device driver requests in both virtual video device drivers. An owning virtual video device driver must unmap all video pages and uninstall all page-fault and I/O hooks upon receipt of a Release request, and later must reinstall all hooks upon receipt of an Accept request.

         VDHRequestVDD(
           HVDD hvddVideo,  /* Virtual video device driver handle */
           HVDM hvdm,       /* Screen group ID of the DOS session */
           INT  iFunc,      /* VVDDEVREQ_DEVACCEPT (5)            */
           PVOID pReqIn,    /* Undefined.                         */
           PVOID pReqOut    /* Undefined.                         */
         );

         VDHRequestVDD(
           HVDD hvddVideo,  /* Virtual video device driver handle */
           HVDM hvdm,       /* Screen group ID of the DOS session */
           INT  iFunc,      /* VVDDEVREQ_DEVRELEASE (6)           */
           PVOID pReqIn,    /* Undefined.                         */
           PVOID pReqOut    /* Undefined.                         */
         );

This support is provided for multiple virtual video device drivers installed for the same device but virtualizing different aspects of the hardware (for example, VGA and Super VGA virtual video device drivers for a single Super VGA adapter). A virtual video device driver that is not currently the owner must silently pass on any DosRequestVDD and VDHRequestVDD requests that it receives to the next virtual video device driver in the chain, using the VDDREQ_PASS return code.

In cases where multiple video adapters use the same physical monitor (such as VGA with 8514/A), there is no need to issue the device requests described previously because the devices are separate. Coordination of which virtual video device driver is currently the display owner must be accomplished by way of a similar pair of inter-virtual device driver requests: Release Display and Accept Display. Virtual video device drivers generally need not act except to update their own display ownership settings. Only the virtual video device driver that is currently the display owner for a given DOS session should respond to requests from the DOS Session Window Manager for that DOS session. The same is true of virtual mouse device driver pointer requests. For example, on a VGA and 8514/A single display system, only the virtual video device driver with display ownership should respond to certain system requests (that is, QUERYMODE, QUERYCURSOR, QUERYPALETTE, COPYLVB, and COPYBITMAP).

         VDHRequestVDD(
           HVDD hvddVideo,  /* Virtual video device driver handle */
           HVDM hvdm,       /* Screen group ID of the DOS session */
           INT  iFunc,      /* VVDDEVREQ_DSPACCEPT (7)            */
           PVOID pReqIn,    /* Undefined.                         */
           PVOID pReqOut    /* Undefined.                         */
         );

         VDHRequestVDD(
           HVDD hvddVideo,  /* Virtual video device driver handle */
           HVDM hvdm,       /* Screen group ID of the DOS session */
           INT  iFunc,      /* VVDDEVREQ_RELEASE (8)              */
           PVOID pReqIn,    /* Undefined.                         */
           PVOID pReqOut    /* Undefined.                         */
         );

For the VGA and 8514/A combination, the VGA virtual video device driver still manages all video event communication with the DOS Session Window Manager. This eliminates major duplicate functionality with the 8514/A. However, because the 8514/A virtual video device driver still must be able to post its own video events, a post event inter-virtual device driver request is supported by the VGA virtual video device driver.

         VDHRequestVDD(
           HVDM hvddVideo,  /* Virtual video device driver handle */
           HVDM hvdm,       /* Screen group ID of the DOS session */
           INT  iFunc,      /* VVDDEVREQ_POSTEVENT (9)            */
           PVVPOST pvvp,    /* Pointer to a VVPOST structure      */
           PVOID pReqOut    /* Undefined.                         */
         );

where VVPOST is a structure containing:

         typedef struct vvp_ { /* vvp (input for POSTEVENT request*/
           LONG  iEvent;    /* See the VVDEVENT_* constants below */
           PVOID pEvent;    /* Event data (varies by event type   */
           ULONG  flEvent;  /* See POSTEVENT_* constants below    */
         }VVPOST;

         #define VVDEVENT_NONE         0   / *   No   change                * /
          # define   VVDEVENT _ MODE           1   / *   Change   in   DOS           * /
                                             / *   session ' s   mode          * /
          # define   VVDEVENT _ PALETTE        2   / *   Change   in   DOS           * /
                                             / *   session ' s   palette       * /
          # define   VVDEVENT _ LVB            3   / *   Change   in   DOS           * /
                                             / *   session ' s   LVB           * /
          # define   VVDEVENT _ SCROLL         4   / *   Scroll   of   DOS           * /
                                             / *   session ' s   LVB           * /
          # define   VVDEVENT _ STRING         5   / *   String   output           * /
          # define   VVDEVENT _ CURSOR         6   / *   Cursor   position / type    * /
                                             / *   change                   * /
          # define   VVDEVENT _ INPUT          7   / *   DOS   session   is   check -   * /
                                             / *   ing   for   input   data      * /
          # define   VVDEVENT _ ENDPASTE       8   / *   DOS   session   has         * /
                                             / *    cancelled   pasting      * /
          # define   VVDEVENT _ PASTE          9   / *   DOS   session   is   ready    * /
                                             / *   for   additional   pasting * /
          # define   VVDEVENT _ SWITCHERROR   10   / *   DOS   session   cannot   be   * /
                                             / *    switched   foreground    * /
          # define   VVDEVENT _ TITLECHANGE   11   / *   DOS   session   title   has   * /
                                                changed                  * /
          # define   VVDEVENT _ DDE           12   / *   Set / Clear   DDE   flag      * /
          # define   POSTEVENT _ ADD      0x0001   / *   Add   given   event .        * /
          # define   POSTEVENT _ FLUSH    0x0002   / *   Flush   given   or          * /
                                                existing   event .         * /
          # define   POSTEVENT _ DELETE   0x0004   / *   Delete   existing   event . * /

The XGA device has VGA device capability built into the hardware, but it is physically impossible to activate the functionality of both devices at the same time without another VGA-capable device installed. The extra VGA device can come in a form of a planar VGA with a display monitor attached, a VGA adapter, or another XGA device. In the event that the XGA device being targeted for save/restore by the XGA virtual device driver is also the startup device (that is, it comes up in VGA mode on system startup), a fast path can be used to temporarily stop the VGA virtual device driver from doing the save/restore of the same device without going through the preferred way of Release and Accept device. In this case, the Save Restore request is supported by the VGA virtual video device driver.

         VDHRequestVDD(
           HVDD hvddVideo,  /* Virtual video device driver handle */
           HVDM hvdm,       /* Screen group ID of the DOS session */
           INT  iFunc,      /* VVDDEVREQ_SAVERESTORE (10)         */
           PVOID (0 or 1),  /* 1=yes, 0=no                        */
           PVOID pReqOut    /* Undefined.                         */
         );

The Repaint request is used by other virtual video device drivers (8514/A and XGA) to indicate whether the PM Desktop's screen image has been damaged by the full-screen DOS session. The virtual video device driver accepting this request must notify the PM display device driver, using QUERYVRAMSTATUS, that repaint of the Desktop is required when the PM becomes foreground.

         VDHRequestVDD(
           HVDD hvddVideo,  /* Virtual video device driver handle */
           HVDM hvdm,       /* Screen group ID of the DOS session */
           INT  iFunc,      /* VVDDEVREQ_REPAINT (11)             */
           PVOID(TRUE),     /* 1 = REPAINT required               */
           PVOID pReqOut    /* Undefined.                         */
         );

The Request Controller request is issued by the virtual Window device driver (VWIN.SYS) on behalf of the WIN-OS/2 display device driver to force the virtual video device driver to immediately release the VGA controller currently owned by a background or windowed DOS session.

         VDHRequestVDD(
           HVDD hvddVideo   /* Virtual video device driver handle */
           HVDM hvdm,       /* Screen group ID of the DOS session */
           INT  iFunc,      /* VVDDEVREQ_REQCTRL (12)             */
           PVOID PReqIn,    /* Undefined.                         */
           PVOID PReqOut    /* Undefined.                         */
         );

The Free Controller request is issued by the virtual Window device driver ( VWIN.SYS) on behalf of the WIN-OS/2 display device driver to notify the virtual video device driver that the VGA controller is now available. This request is issued only when the virtual video device driver requests notification on completion of the current PM operation.

         VDHRequestVDD(
           HVDD hvddVideo,  /* Virtual video device driver handle */
           HVDM hvdm,       /* Screen group ID of the DOS session */
           INT  iFunc,      /* VVDDEVREQ_FREECTRL   ( 13 )               * /
            PVOID   PReqIn ,      / *   Undefined .                             * /
            PVOID   pReqOut      / *   Undefined .                             * /
          ) ;

The Set PM Window request is issued by the virtual Window device driver ( VWIN.SYS) to permit the specified windowed DOS session access to the video device. It is up to the virtual video device driver servicing this request to remove all I/O hooks, map VRAM to physical A0000H as needed, and remove all pending window events for the target DOS session.

         VDHRequestVDD(
           HVDD hvddVideo,  /* Virtual video device driver handle */
           HVDM hvdm,       /* Screen group ID of the DOS session */
           INT  iFunc,      /* VVDDEVREQ_PM_WINDOW (14)           */
           PVOID(TRUE),     /* 1 = Enable WIN-OS/2                */
           PVOID pReqOut    /* Undefined.                         */
         );