home *** CD-ROM | disk | FTP | other *** search
/ Big Green CD 8 / BGCD_8_Dev.iso / NEXTSTEP / Drivers / joystick-0.0-I / JOYDOCS.ZIP / joyprog.doc < prev   
Encoding:
Text File  |  1995-05-06  |  10.9 KB  |  408 lines
  1. Advanced OS/2 Joystick Device Driver API Information 1.0
  2.  
  3. OVERVIEW
  4.   The Advanced OS/2 Joystick Device Driver API allows an OS/2 application
  5.   to access the machine's game port, providing it with reliable joystick
  6.   readings.  We encourage the use of this specification in hopes of providing
  7.   a common interface for game port facilities in all OS/2 games and other
  8.   applications.
  9.  
  10. USAGE SUMMARY
  11.   Interfacing with the driver is accomplished rather straightforwardly through
  12.   IOCTL functions after opening the new GAME$ device.
  13.  
  14. NOTE
  15.   Versions of the joystick device driver prior to 0.2a only have stub
  16.   open, read and close routines enabled.  Please be sure to do any testing
  17.   with version 0.2a or above of the driver.
  18.  
  19. USAGE EXAMPLES
  20.  
  21. /****************************************************************************/
  22. 1. Open the device
  23.  
  24.     HFILE        hGame;
  25.     ULONG        action;
  26.     APIRET        rc;
  27.  
  28.     rc = DosOpen(
  29.         GAMEPDDNAME,                /* "GAME$" */
  30.         &hGame,
  31.         &action,
  32.         0,
  33.         FILE_READONLY,
  34.         FILE_OPEN,
  35.         OPEN_ACCESS_READONLY | OPEN_SHARE_DENYNONE,
  36.         NULL);
  37.     if (rc != 0)
  38.     {
  39.         /* ERROR opening device : result code in rc */
  40.     }
  41. /****************************************************************************/
  42.  
  43. /****************************************************************************/
  44. 2. Get the version number of the driver
  45.  
  46.     HFILE        hGame;
  47.     ULONG        version;
  48.     ULONG        dataLen;
  49.     APIRET        rc;
  50.  
  51.     dataLen = sizeof(version);
  52.     rc = DosDevIOCtl(
  53.         hGame,
  54.         IOCTL_CAT_USER, GAME_GET_VERSION,    /* 0x80, 0x01 */
  55.         NULL, 0, NULL,
  56.         &version, dataLen, &dataLen);
  57.     if (rc != 0)
  58.     {
  59.         /* ERROR in IOCtl : result code in rc */
  60.     }
  61. /****************************************************************************/
  62.  
  63. /****************************************************************************/
  64. 3. Get driver parameters
  65.  
  66.     /*-- below defined in joyos2.h -----------------------------*/
  67.  
  68.     /* in use bitmasks originating in 1.0 */
  69.     #define GAME_USE_BOTH_OLDMASK    0x01    /* for backward compat with bool */
  70.     #define GAME_USE_X_NEWMASK    0x02
  71.     #define GAME_USE_Y_NEWMASK    0x04
  72.     #define GAME_USE_X_EITHERMASK    (GAME_USE_X_NEWMASK|GAME_USE_BOTH_OLDMASK)
  73.     #define GAME_USE_Y_EITHERMASK    (GAME_USE_Y_NEWMASK|GAME_USE_BOTH_OLDMASK)
  74.     #define GAME_USE_BOTH_NEWMASK    (GAME_USE_X_NEWMASK|GAME_USE_Y_NEWMASK)
  75.  
  76.     /* only timed sampling implemented in version 1.0 */
  77.     #define GAME_MODE_TIMED        1    /* timed sampling */
  78.     #define GAME_MODE_REQUEST    2    /* request driven sampling */
  79.  
  80.     /* only raw implemented in version 1.0 */
  81.     #define    GAME_DATA_FORMAT_RAW    1    /* [l,c,r]   */
  82.     #define    GAME_DATA_FORMAT_SIGNED    2    /* [-l,0,+r] */
  83.     #define    GAME_DATA_FORMAT_BINARY    3    /* {-1,0,+1} */
  84.     #define    GAME_DATA_FORMAT_SCALED    4    /* [-10,+10] */
  85.  
  86.     // parameters defining the operation of the driver
  87.     typedef struct
  88.     {
  89.         USHORT            useA;        /* new bitmasks: see above */
  90.         USHORT            useB;
  91.         USHORT            mode;        /* see consts above */
  92.         USHORT            format;        /* see consts above */
  93.         USHORT            sampDiv;    /* samp freq = 32 / n */
  94.         USHORT            scale;        /* scaling factor */
  95.         USHORT            res1;        /* must be 0 */
  96.         USHORT            res2;        /* must be 0 */
  97.     }
  98.     GAME_PARM_STRUCT;
  99.  
  100.     /*----------------------------------------------------------*/
  101.  
  102.     HFILE            hGame;
  103.     GAME_PARM_STRUCT    gameParms;
  104.     ULONG            dataLen;
  105.     APIRET            rc;
  106.  
  107.     dataLen = sizeof(gameParms);
  108.     rc = DosDevIOCtl(
  109.         hGame,
  110.         IOCTL_CAT_USER, GAME_GET_PARMS,        /* 0x80, 0x02 */
  111.         NULL, 0, NULL,
  112.         &gameParms, dataLen, &dataLen);
  113.     if (rc != 0)
  114.     {
  115.         /* ERROR in IOCtl : result code in rc */
  116.     }
  117. /****************************************************************************/
  118.  
  119. /****************************************************************************/
  120. 4. Set driver parameters
  121.  
  122.     /*-- see section above from joyos2.h -----------------------*/
  123.  
  124.     HFILE            hGame;
  125.     GAME_PARM_STRUCT    gameParms;
  126.     ULONG            parmLen;
  127.     APIRET            rc;
  128.  
  129.     parmLen = sizeof(gameParms);
  130.     rc = DosDevIOCtl(
  131.         hGame,
  132.         IOCTL_CAT_USER, GAME_SET_PARMS,        /* 0x80, 0x03 */
  133.         &gameParms, parmLen, &parmLen,
  134.         NULL, 0, NULL);
  135.     if (rc != 0)
  136.     {
  137.         /* ERROR in IOCtl : result code in rc */
  138.     }
  139. /****************************************************************************/
  140.  
  141. /****************************************************************************/
  142. 5. Get calibration values for joystick(s)
  143.  
  144.     /*-- below defined in joyos2.h -----------------------------*/
  145.  
  146.     // 1-D position struct used for each axis
  147.     typedef    SHORT    GAME_POS;    /* some data formats require signed values */
  148.  
  149.     // struct to be used for calibration and digital response on each axis
  150.     typedef struct
  151.     {
  152.         GAME_POS        lower;
  153.         GAME_POS        centre;
  154.         GAME_POS        upper;
  155.     }
  156.     GAME_3POS_STRUCT;
  157.  
  158.     // calibration values for each axis:
  159.     //    - upper limit on value to be considered in lower range
  160.     //    - centre value
  161.     //    - lower limit on value to be considered in upper range
  162.     typedef struct
  163.     {
  164.         GAME_3POS_STRUCT    Ax;
  165.         GAME_3POS_STRUCT    Ay;
  166.         GAME_3POS_STRUCT    Bx;
  167.         GAME_3POS_STRUCT    By;
  168.     }
  169.     GAME_CALIB_STRUCT;
  170.  
  171.     /*----------------------------------------------------------*/
  172.  
  173.     HFILE            hGame;
  174.     GAME_CALIB_STRUCT    gameCalib;
  175.     ULONG            dataLen;
  176.     APIRET            rc;
  177.  
  178.     dataLen = sizeof(gameCalib);
  179.     rc = DosDevIOCtl(
  180.         hGame,
  181.         IOCTL_CAT_USER, GAME_GET_CALIB,        /* 0x80, 0x04 */
  182.         NULL, 0, NULL,
  183.         &gameCalib, dataLen, &dataLen);
  184.     if (rc != 0)
  185.     {
  186.         /* ERROR in IOCtl : result code in rc */
  187.     }
  188. /****************************************************************************/
  189.  
  190. /****************************************************************************/
  191. 6. Calibrate joystick(s) (set calibration values)
  192.  
  193.     /*-- see section above from joyos2.h -----------------------*/
  194.  
  195.     /*
  196.     for each stick
  197.         - tell user to centre joystick and press button
  198.         - call get status with wait
  199.         - tell user to move to upper-left and press button
  200.         - call get status with wait
  201.         - tell user to move to lower-right and press button
  202.         - call get status with wait
  203.  
  204.     then call set calibration IOCTL with these values
  205.     */
  206.  
  207.     HFILE            hGame;
  208.     GAME_CALIB_STRUCT    gameCalib;
  209.     ULONG            parmLen;
  210.     APIRET            rc;
  211.  
  212.     parmLen = sizeof(gameCalib);
  213.     rc = DosDevIOCtl(
  214.         hGame,
  215.         IOCTL_CAT_USER, GAME_SET_CALIB,        /* 0x80, 0x05 */
  216.         &gameCalib, parmLen, &parmLen,
  217.         NULL, 0, NULL);
  218.     if (rc != 0)
  219.     {
  220.         /* ERROR in IOCtl : result code in rc */
  221.     }
  222. /****************************************************************************/
  223.  
  224. /****************************************************************************/
  225. 7. Get VDM digital response values for joystick(s)
  226.  
  227.     /*-- below defined in joyos2.h -----------------------------*/
  228.  
  229.     // 1-D position struct used for each axis
  230.     typedef    SHORT    GAME_POS;    /* some data formats require signed values */
  231.  
  232.     // struct to be used for calibration and digital response on each axis
  233.     typedef struct
  234.     {
  235.         GAME_POS        lower;
  236.         GAME_POS        centre;
  237.         GAME_POS        upper;
  238.     }
  239.     GAME_3POS_STRUCT;
  240.  
  241.     // struct defining the digital response values for all axes
  242.     typedef struct
  243.     {
  244.         GAME_3POS_STRUCT    Ax;
  245.         GAME_3POS_STRUCT    Ay;
  246.         GAME_3POS_STRUCT    Bx;
  247.         GAME_3POS_STRUCT    By;
  248.     }
  249.     GAME_DIGSET_STRUCT;
  250.  
  251.     /*----------------------------------------------------------*/
  252.  
  253.     HFILE            hGame;
  254.     GAME_DIGSET_STRUCT    gameDigset;
  255.     ULONG            dataLen;
  256.     APIRET            rc;
  257.  
  258.     dataLen = sizeof(gameDigset);
  259.     rc = DosDevIOCtl(
  260.         hGame,
  261.         IOCTL_CAT_USER, GAME_GET_DIGSET,    /* 0x80, 0x06 */
  262.         NULL, 0, NULL,
  263.         &gameDigset, dataLen, &dataLen);
  264.     if (rc != 0)
  265.     {
  266.         /* ERROR in IOCtl : result code in rc */
  267.     }
  268. /****************************************************************************/
  269.  
  270. /****************************************************************************/
  271. 8. Set VDM digital response values for joystick(s)
  272.  
  273.     /*-- see section above from joyos2.h -----------------------*/
  274.  
  275.     HFILE            hGame;
  276.     GAME_DIGSET_STRUCT    gameDigset;
  277.     ULONG            parmLen;
  278.     APIRET            rc;
  279.  
  280.     parmLen = sizeof(gameDigset);
  281.     rc = DosDevIOCtl(
  282.         hGame,
  283.         IOCTL_CAT_USER, GAME_SET_DIGSET,    /* 0x80, 0x07 */
  284.         &gameDigset, parmLen, &parmLen,
  285.         NULL, 0, NULL);
  286.     if (rc != 0)
  287.     {
  288.         /* ERROR in IOCtl : result code in rc */
  289.     }
  290. /****************************************************************************/
  291.  
  292. /****************************************************************************/
  293. 9. Get the status of the joystick(s)
  294.  
  295.     /*-- below defined in joyos2.h -----------------------------*/
  296.  
  297.     // 1-D position struct used for each axis
  298.     typedef    SHORT    GAME_POS;    /* some data formats require signed values */
  299.  
  300.     // simple 2-D position for each joystick
  301.     typedef struct
  302.     {
  303.         GAME_POS        x;
  304.         GAME_POS        y;
  305.     }
  306.     GAME_2DPOS_STRUCT;
  307.  
  308.     // struct defining the instantaneous state of both sticks and all buttons
  309.     typedef struct
  310.     {
  311.         GAME_2DPOS_STRUCT    A;
  312.         GAME_2DPOS_STRUCT    B;
  313.         USHORT            butMask;
  314.     }
  315.     GAME_DATA_STRUCT;
  316.  
  317.     // status struct returned to OS/2 applications:
  318.     // current data for all sticks as well as button counts since last read
  319.     typedef struct
  320.     {
  321.         GAME_DATA_STRUCT    curdata;
  322.         USHORT            b1cnt;
  323.         USHORT            b2cnt;
  324.         USHORT            b3cnt;
  325.         USHORT            b4cnt;
  326.     }
  327.     GAME_STATUS_STRUCT;
  328.  
  329.     /*----------------------------------------------------------*/
  330.  
  331.     HFILE            hGame;
  332.     GAME_STATUS_STRUCT    gameStatus;
  333.     ULONG            dataLen;
  334.     APIRET            rc;
  335.  
  336.     dataLen = sizeof(gameStatus);
  337.     rc = DosDevIOCtl(
  338.         hGame,
  339.         IOCTL_CAT_USER, GAME_GET_STATUS,    /* 0x80, 0x10 */
  340.         NULL, 0, NULL,
  341.         &gameStatus, dataLen, &dataLen);
  342.     if (rc != 0)
  343.     {
  344.         /* ERROR in IOCtl : result code in rc */
  345.     }
  346. /****************************************************************************/
  347.  
  348. /****************************************************************************/
  349. 10. Get the status of the joystick(s) at next button press
  350.  
  351.     /*-- see section above from joyos2.h -----------------------*/
  352.  
  353.     /* NOTE: this call will block */
  354.  
  355.     HFILE            hGame;
  356.     GAME_STATUS_STRUCT    gameStatus;
  357.     ULONG            dataLen;
  358.     APIRET            rc;
  359.  
  360.     dataLen = sizeof(gameStatus);
  361.     rc = DosDevIOCtl(
  362.         hGame,
  363.         IOCTL_CAT_USER, GAME_GET_STATUS_BUTWAIT, /* 0x80, 0x11 */
  364.         NULL, 0, NULL,
  365.         &gameStatus, dataLen, &dataLen);
  366.     if (rc != 0)
  367.     {
  368.         /* ERROR in IOCtl : result code in rc */
  369.     }
  370. /****************************************************************************/
  371.  
  372. /****************************************************************************/
  373. 11. Get the status of the joystick(s) at next sample (depends on mode)
  374.  
  375.     /*-- see section above from joyos2.h -----------------------*/
  376.  
  377.     /* NOTE: this call will block */
  378.  
  379.     HFILE            hGame;
  380.     GAME_STATUS_STRUCT    gameStatus;
  381.     ULONG            dataLen;
  382.     APIRET            rc;
  383.  
  384.     dataLen = sizeof(gameStatus);
  385.     rc = DosDevIOCtl(
  386.         hGame,
  387.         IOCTL_CAT_USER, GAME_GET_STATUS_SAMPWAIT, /* 0x80, 0x12 */
  388.         NULL, 0, NULL,
  389.         &gameStatus, dataLen, &dataLen);
  390.     if (rc != 0)
  391.     {
  392.         /* ERROR in IOCtl : result code in rc */
  393.     }
  394. /****************************************************************************/
  395.  
  396. /****************************************************************************/
  397. 12. Close the device
  398.  
  399.     HFILE        hGame;
  400.     APIRET        rc;
  401.  
  402.     rc = DosClose(hGame);
  403.     if (rc != 0)
  404.     {
  405.         /* ERROR closing device : result code in rc */
  406.     }
  407. /****************************************************************************/
  408.