## Display Device Driver Reference for OS/2

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

### Virtual Mouse Device Driver Services

For the virtual mouse device driver, the virtual video device driver provides a VDHRequestVDD function, as well as several direct interfaces for pointer drawing operations.

The following VDHRequestVDD service is provided:

         VDHRequestVDD
         (
            HVDD  hvddVideo,
            HVDM  hvdm,
            INT   iFunc,    /* Virtual video device               */
                            /* driverEVREQ_POSTMOUSE (4)          */
            PVOID pReqIn,   /* Undefined.                         */
            PVOID pReqOut   /* Undefined.                         */
         );                 /* Returns TRUE.                      */

The virtual mouse device driver must return the address of a function that permits the virtual video device driver to obtain mouse position and button status during processing of the INT 10h, Query Light Pen function, when light pen emulation is enabled for the active DOS session. Also, whenever the DOS session changes video modes (including the initial mode change that takes place during DOS-session creation), the virtual video device driver notifies the virtual mouse device driver driver of the new mode and screen dimensions.

The POSTMOUSE notification is intended to be called whenever the mouse is about to record a button transition event (that is, button going down or button coming up). Its purpose is to notify the virtual video device driver that a video event is likely to occur.

The direct-call interfaces are exported by way of the following VDHRequestVDD to the virtual mouse device driver during the creation of the first DOS session. (To avoid introducing a loading-order dependency, they are not exported during virtual device driver initialization.)

         VDHRequestVDD
         (
            HVDD  hvddMouse,
            HVDM  hvdm,
            INT   iFunc,    /* iFunc = VMDEVREQ_REGISTER (1)      */
            PVMREG pvmreg,  /* Pointer to VMREG structure         */
            PVMFUNC pvmfunc /* Pointer to VMFUNC structure        */
         );                 /* Returns TRUE                       */

where VMREG is a structure containing all the direct-call addresses:

         typedef struct vmreg_s
         {
            ULONG     nb;              /* Size of structure, in   */
                                       /*  bytes (24)             */
            PFNSHOWPTR  pfnShowPtr;    /* Ptr to show pointer fn. */
            PFNHIDEPTR  pfnHidePtr;    /* Ptr to hide pointer fn. */
            PFNDEFTEXT  pfnDefTextPtr; /* Ptr to define text
                                       /*  pointer fn.            */
            PFNDEFGRAPH pfnDefGraphPtr;/* Ptr to define graphics
                                       /*  pointer fn.            */
            PFNSETPAGE  pfnSetPtrPage; /* Ptr to set pointer      */
                                       /*  page fn.               */
            PFNSETLPEN  pfnSetLPenEm;  /* Ptr to enable/disable   */
                                       /*  lpen fn.               */
         }  VMREG;

and where VMFUNC is a structure in which the virtual mouse device driver must return the address of its own exported function to return mouse position and button status:

         typedef struct vmfunc_s
         {
            ULONG      nb;               /* Size of structure,    */
                                         /* in bytes (8)          */
            PFNQUERYSTAT pfnQueryStatus; /* Ptr to query virtual  */
                                         /* status proc.          */
         }  VMFUNC;

The virtual video device driver also uses VDHRequestVDD to notify the virtual mouse device driver of changes in video mode:

         VDHRequestVDD
         (
            HVDD  hvddMouse,
            HVDM  hvdm,
            INT   iFunc,              /* VMDEVREQ_SETSIZE (2)      */
            PVMSS pvmss,              /* Pointer to VMSS structure */
            PVOID pReqOut             /* Undefined                 */
         );

where VMSS is a structure containing the following information:

         typedef struct vmss_s
         {
            ULONG nb;          /* Size of structure, in bytes (36)*/
            LONG  lMode;       /* Video mode (for example,        */
                               /* 00h-13h, or -1)                 */
            ULONG ulWidth;     /* Width of screen, in pels        */
            ULONG ulHeight;    /* Height of screen, in pels       */
            ULONG ulCellWidth; /* Width of screen cells, in pels  */
            ULONG ulCellHeight;/* Height of screen cells, in pels */
            ULONG ulPtrWidth;  /* Width of pointer drawing size,  */
                               /* in pels                         */
            ULONG ulPtrHeight; /* Height of pointer drawing size, */
                               /* in pels                         */
            ULONG ulUnitWidth; /* Width of pointer drawing unit,  */
                               /* in pels                         */
         }  VMSS;

The direct-call interfaces supplied by virtual video device drivers are defined as follows:

         BOOL FNSHOWPTR VVShowPtr
         (
            HVDM hvdm,           /* DOS session handle,           */
                                 /* or CURRENT_VDM                */
            ULONG xNew,          /* Horizontal pel (NOT cell)     */
                                 /* coordinate                    */
            ULONG yNew           /* Vertical pel (NOT cell)       */
                                 /* coordinate                    */
         );                      /* Returns TRUE unless ptr         * /
                                    / *   drawing   disabled                 * /

          BOOL   FNHIDEPTR   VVHidePtr
          (
             HVDM   hvdm               / *   DOS   session   handle ,   or          * /
                                    / *   CURRENT _ VDM                      * /
          ) ;                          / *   Returns   TRUE   unless   ptr         * /
                                    / *   drawing   disabled * /               * /

          BOOL   FNDEFTEXT   VVDefTextPtr
          (
             HVDM   hvdm ,              / *   DOS   session   handle ,   or          * /
                                    / *   CURRENT _ VDM                      * /
             ULONG   ulANDMask ,       / *   Screen   mask                      * /
             ULONG   ulXORMask ,       / *   Pointer   mask                     * /
             BOOL   fHW                / *   TRUE   to   use   hardware   cursor     * /
          ) ;                          / *   Returns   TRUE                     * /

          BOOL   FNDEFGRAPH   VVDefGraphPtr
          (
             HVDM   hvdm ,              / *   DOS   session   handle ,   or          * /
                                    / *   CURRENT _ VDM                      * /
             USHORT   ausMasks [ ] ,     / *   Screen   mask ,   followed   by        * /
                                    / *   pointer   mask                     * /
             ULONG   xHot ,            / *   Relative   horizontal   hot - spot
                                    / *   coordinate                       * /
             ULONG   yHot              / *   Relative   vertical   hot - spot      * /
                                    / *   coordinate                       * /
          ) ;                          / *   Returns   TRUE                     * /

          BOOL   FNSETPAGE   VVSetPtrPage
          (
             HVDM   hvdm ,              / *   DOS   session   handle ,   or          * /
                                    / *   CURRENT _ VDM                      * /
             ULONG   ulPage           / *   Video   page   number                * /
          ) ;                          / *   Returns   TRUE                     * /

          BOOL   FNSETLPEN   VVSetLPenEm
          (
             HVDM   hvdm ,              / *   DOS   session   handle ,   or          * /
                                    / *   CURRENT _ VDM                      * /
             BOOL   fEnable           / *   TRUE   to   enable   emulation        * /
          ) ;                          / *   Returns   TRUE                     * /

For reference, the function supplied by a virtual mouse device driver to a virtual video device driver is defined as follows:

         BOOL FNQUERYSTAT VMQueryStatus
         (
            HVDM hvdm,       /* DOS session handle, or            */
                             /* CURRENT_VDM                       */
            PVMSTAT pvmstat  /* Pointer to VMSTAT info structure  */
         );                  /* Returns TRUE                      */

where VMSTAT is a structure containing:

         typedef struct vmstat_s
         {
            BOOL  fPtrHidden;    /* Visual pointer status         */
            ULONG x;             /* Current virtual x position    */
            ULONG y;             /* Current virtual y position    */
            ULONG flButtons;     /* Current button status         */
         }  VMSTAT;

         /*
         ** Button status bit definitions
         */

         #define BUTBIT_LEFT     0x0001
         #define BUTBIT_RIGHT    0x0002
         #define BUTBIT_CENTER   0x0004

    /--- DESIGN NOTE ------------------------------------------\

    |                                                          |

    |  The POSTMOUSE notification currently is not supplied by |

    |  the virtual mouse device driver, nor is it currently    |

    |  monitored by the virtual video device driver.           |

    |                                                          |

    \----------------------------------------------------------/