home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: Multimed / Multimed.zip / lbmix04.zip / Source / ioctl90.h < prev    next >
Text File  |  1999-11-18  |  10KB  |  242 lines
  1. //-----------------------------------------------------------------------------
  2. // Freeware.  This file may be used freely to promote the ioctl90 mixer API.
  3. //
  4. //-----------------------------------------------------------------------------
  5. // File: ioctl90.h                                      Date Created: 10/14/98
  6. // Description: prototypes for cat 90 mixer IOCTLs      Last Update : 11/16/99
  7. //-----------------------------------------------------------------------------
  8. //
  9. // Crystal Semiconductor defined category 0x90 OS/2 mixer IOCTLS.
  10. // 
  11. // STATUS: (Drivers known to implement this API)
  12. //    Crystal Semiconductor ISA Mode 3 driver version 2.08.
  13. //    Crystal Semiconductor PCI driver version 3.02.
  14. //
  15. //-----------------------------------------------------------------------------
  16. //
  17. // This header file contains application usable defines for calls to 
  18. // Crystal Semiconductor device driver to manage hardware mixer.
  19. // It is primarily used to adjust the listening level of
  20. // mixer inputs (CD-ROM, Aux, Line, Phone...).  The API also allows
  21. // adjustment to the record gain as an override to MMPM/2 stream 
  22. // specific API.
  23. //
  24. // API is modeled off of AC97 mixer.  This does not mean that the device
  25. // uses an AC97 mixer.  Being a relatively low-function device, the model
  26. // should be usable on most hardware architectures.
  27. //
  28. // For information on AC97 hardware architecuture, consult data book
  29. // for the CS4297 databook:
  30. //    Crystal Clear(tm) SoundFusion(tm) Audio Codec '97 (CS4297)
  31. // Available from http://www.cirrus.com/
  32. //
  33. //
  34. // API DEFINITION
  35. // --------------
  36. //
  37. // Architecture notes:
  38. // - All volumes sent to the device driver are range 0..100.
  39. // - Mute is a boolean stored in a ULONG (range 0..1)
  40. // - All APIs effect the device on GLOBAL basis (not per-stream).
  41. // - API does not control master volume or per-stream volume.
  42. //   These are controlled by MMPM/2 MCI and AUDIODD IOCTLS (category 0x80).
  43. // - API does permit override of MMPM/2 record gain.  The value sent is
  44. //   global and will only be used by the device driver if the master
  45. //   gain is set via this API.  Once set, the global value will be used
  46. //   in preference to the MMPM/2 per-stream setting, until next reboot.
  47. //
  48. // IOCTL Category 0x90, functions:
  49. // 40 - MonoInSet        60 - MonoInQuery
  50. // 41 - PhoneSet         61 - PhoneQuery
  51. // 42 - MicSet           62 - MicQuery
  52. // 43 - LineSet          63 - LineQuery
  53. // 44 - CDSet            64 - CDQuery
  54. // 45 - VideoSet         65 - VideoQuery
  55. // 46 - AuxSet           66 - AuxQuery
  56. // 4C - ThreeDSet        6C - ThreeDQuery
  57. // 4D - StreamVolSet     6D - StreamVolQuery
  58. // 4E - RecordSrcSet     6E - RecordSrcQuery
  59. // 4F - RecordGainSet    6F - RecordGainQuery
  60. // 80 - ApiLevelQuery    
  61. // 81 - GetApiMap
  62. // 82 - CallbackReg
  63. //
  64. // Application passes a structure (ioctl data buffer) 
  65. // which contains:
  66. // ULONG Mute;     // UnMute==0, Mute==1
  67. // ULONG ulVolL;   // Left volume in percent 0..100
  68. // ULONG ulVolR;   // Right volume in percent 0..100
  69. //
  70. // With the exception of the record gain APIs, these APIs effect 
  71. // what you hear (output bus connections).
  72. //
  73. //-----------------------------------------------------------------------------
  74. //
  75. // Calling code should query the device driver name by calling
  76. // MMPM/2 MCI APIs to get the PDD name for the "WaveAudio" MCI device.
  77. // Application should then issue DosOpen on the device followed
  78. // by DosDevIOCTLs to perform operations.
  79. //
  80. // Here is sample code for DosOpen and DosDevIOCTL
  81. //
  82. // Driver name in call to the open function should include "\\DEV\\"
  83. //    Example: hPdd = DevOpen ("\\DEV\\BSAUD1$"); or
  84. //    Example: hPdd = DevOpen ("\\DEV\\CWCAUD1$");
  85. //
  86. // HFILE DevOpen (char *ddName)
  87. // {
  88. //    ULONG ulRC;
  89. //    ULONG OpenFlags;
  90. //    ULONG OpenMode;
  91. //    ULONG ulFileSize      = 0;
  92. //    ULONG ulFileAttribute = 0;
  93. //    ULONG ulActionTaken   = 0;
  94. //    HFILE hPdd            = NULL;
  95. // 
  96. //    OpenFlags = OPEN_ACTION_OPEN_IF_EXISTS;   // Do not create file
  97. // 
  98. //    OpenMode  = OPEN_ACCESS_READWRITE +       // Read/Write file
  99. //                OPEN_SHARE_DENYNONE +         // Non-exclusive access
  100. //                OPEN_FLAGS_FAIL_ON_ERROR;     // No system popups on errors
  101. // 
  102. //    ulRC = DosOpen (ddName,          // in
  103. //                    &hPdd,           //    out (handle)
  104. //                    &ulActionTaken,  //    out
  105. //                    ulFileSize,      // in
  106. //                    ulFileAttribute, // in
  107. //                    OpenFlags,       // in
  108. //                    OpenMode,        // in
  109. //                    NULL);           // in
  110. // 
  111. //    printf ("DosOpen RC = %x\n", ulRC);
  112. // 
  113. //    if (ulRC != 0)
  114. //       hPdd = NULL;
  115. // 
  116. //    return (hPdd);
  117. // }
  118. //
  119. // ULONG SendIOCTL (HFILE hPdd, ULONG ulFunc, PMIXSTRUCT pMix)
  120. // {
  121. //    ULONG     ulRC;
  122. //    ULONG     ulSizeOfStruct =  = sizeof (MixStruct);
  123. // 
  124. //    ulRC = DosDevIOCtl 
  125. //       (hPdd,               // Device Handle
  126. //        0x90,               // Category (user defined >= 0x80)
  127. //        ulFunc,             // Function Use defines in this .H file
  128. //        NULL,               // in      Address of parm data (not used)
  129. //        0,                  // in      Max size of parm data structure
  130. //        NULL,               // in out  Actual size of parm data structure
  131. //        pMix,               // in      Address of command data
  132. //        ulSizeOfStruct,     // in      Maximum size of command data
  133. //        &ulSizeOfStruct);   // in out  Size of command data
  134. // 
  135. //    printf ("DosDevIOCtl ulRC = %d\n", ulRC);
  136. // 
  137. //    return (ulRC);
  138. // }
  139. //
  140. // MODIFICATION HISTORY
  141. // 14-Oct-98 Joe Nord   Create (Crystal Semiconductor, Inc).
  142. // 05-Mar-99 Joe Nord   Added version query and API map query ioctls (80, 81)
  143. //                      First release, Crystal PCI 3.02
  144. // 13-Apr-99 Joe Nord   Added support for global record gain set and query
  145. // 15-Jul-99 Joe Nord   Add callback semaphore support
  146. // 10-Nov-99 Joe Nord   Added support for 3D sound effect set and query
  147. // 15-Nov-99 Joe Nord   Added support for stream volume override
  148. // 16-Nov-99 Joe Nord   Added support for message buffer return
  149. //-----------------------------------------------------------------------------
  150.  
  151. // This prototype is used in the device driver only (common header)
  152. //USHORT ioctlmixMain (USHORT Function, 
  153. //                     USHORT SysFileNum,
  154. //                     ULONG  ulpvData, 
  155. //                     USHORT usDLength);
  156.  
  157. // This structure is passed to the device driver using DosDevIOCTL.
  158. typedef struct
  159. {
  160.    ULONG Mute;                  // UnMute==0, Mute==1
  161.    ULONG VolumeL;               // 0..100 percent
  162.    ULONG VolumeR;               // 0..100 percent
  163. } MIXSTRUCT, *PMIXSTRUCT;
  164.  
  165. typedef struct
  166. {
  167.    ULONG pBuffer;     // Application linear address to message buffer (in)
  168.    ULONG ulSize;      // Size of buffer (in).  Count of chars (out).
  169.    ULONG fClear;      // PDD should clear buffer after copy (in)
  170.    ULONG fError;      // Message buffer includes error message (out)
  171.    ULONG fNewInfo;    // Message buffer has new text since last read (out)
  172.    ULONG ulCharsLost; // Messages lost - circular queue wrap around (out)
  173. } MIXMSGBUF, *PMIXMSGBUF;
  174.  
  175.  
  176. //
  177. // Defines for use by applications
  178. //
  179. #define MONOINSET       0x40    // SET functions in the 0x40 range
  180. #define PHONESET        0x41
  181. #define MICSET          0x42
  182. #define LINESET         0x43
  183. #define CDSET           0x44
  184. #define VIDEOSET        0x45
  185. #define AUXSET          0x46
  186. #define THREEDSET       0x4C
  187. #define STREAMVOLSET    0x4D
  188. #define RECORDSRCSET    0x4E
  189. #define RECORDGAINSET   0x4F
  190.  
  191. #define MONOINQUERY     0x60    // Query functions in the 0x60 range
  192. #define PHONEQUERY      0x61
  193. #define MICQUERY        0x62
  194. #define LINEQUERY       0x63
  195. #define CDQUERY         0x64
  196. #define VIDEOQUERY      0x65
  197. #define AUXQUERY        0x66
  198. #define THREEDQUERY     0x6C
  199. #define STREAMVOLQUERY  0x4D
  200. #define RECORDSRCQUERY  0x6E
  201. #define RECORDGAINQUERY 0x6F
  202.  
  203. #define APILEVELQUERY   0x80
  204. #define GETAPIMAP       0x81    // Get 256 byte BOOL list of supported IOCTLs
  205. #define CALLBACKREG     0x82    // Provide HEV for mixer change callbacks
  206. #define MSGBUF          0x83    // Get PDD error log message buffer
  207.  
  208. // RECORDSRCSET
  209. // Support mixer application override of record gain values.
  210. // Only use the global values when a mixer app has instructed to do so.
  211. // This allows override of settings from MMPM/2 applications.
  212.  
  213. #define I90SRC_BASE     0x00000010      // 0..F are reserved (MMPM/2 space)        
  214. #define I90SRC_MIC      0x00000010
  215. #define I90SRC_CD       0x00000020
  216. #define I90SRC_VIDEO    0x00000040
  217. #define I90SRC_AUX      0x00000080
  218. #define I90SRC_LINE     0x00000100
  219. #define I90SRC_RES5     0x00000200
  220. #define I90SRC_RES6     0x00000400
  221. #define I90SRC_PHONE    0x00000800
  222.  
  223.  
  224. // In first release, the APILEVELQUERY function returns a ULONG, 0x01.  
  225. // As significant changes are made to the ioctlmix API, the return value
  226. // of this function will be incremented.
  227.  
  228. // GETAPIMAP
  229. // To help an application know what APIs are supported by this device driver, 
  230. // return an array of booleans (BYTES).  TRUE => Supported.
  231. // The array must be declared as 256 bytes.  This is larger than necessary as 
  232. // the first 64 entries, range 0x00..0x39, are guaranteed to be zero.
  233. // The extra bytes allows the array to be indexed using the IOCTL function
  234. // defines in this file.
  235. //
  236. // Notice that a FALSE value in an array position (for example "video set") 
  237. // can be used to inform the mixer application that this device driver does
  238. // not support a "video" connection to the audio device.
  239. // Where a device driver is called for an input that it does not support, the
  240. // DosDevIOCTL will fail with return code RPGENFAIL.
  241.  
  242.