| 1 | <!doctype html public "-//w3c//dtd html 4.0 transitional//en">
|
|---|
| 2 | <html>
|
|---|
| 3 | <head>
|
|---|
| 4 | <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|---|
| 5 | <meta name="Author" content="Joe Nord">
|
|---|
| 6 | <meta name="GENERATOR" content="Mozilla/4.7 [en] (WinNT; U) [Netscape]">
|
|---|
| 7 | <title>Crystal Semiconductor Category 0x90 mixer IOCTLS</title>
|
|---|
| 8 | </head>
|
|---|
| 9 | <body>
|
|---|
| 10 |
|
|---|
| 11 | <center><b><u><font color="#3333FF"><font size=+2>Crystal Semiconductor</font></font></u></b>
|
|---|
| 12 | <br><b><u><font color="#3333FF"><font size=+2>OS/2 Category 0x90 mixer
|
|---|
| 13 | IOCTLs</font></font></u></b></center>
|
|---|
| 14 |
|
|---|
| 15 | <p>This information is for programmers only.
|
|---|
| 16 | <blockquote><b>For feedback, contact <a href="mailto: nord@crystal.cirrus.com">Joe
|
|---|
| 17 | Nord</a></b> at Crystal Semiconductor
|
|---|
| 18 | <br>Last document update 16-Dec-1999.</blockquote>
|
|---|
| 19 | <font color="#3333FF"><font size=+1>Purpose of Category 90 IOCTLs</font></font>
|
|---|
| 20 | <p>The category 90 mixer IOCTLs fill in gaps in the MMPM/2 mixer API.
|
|---|
| 21 | <p>In particular, these IOCTLs are defined to allow a user to control the
|
|---|
| 22 | listening level
|
|---|
| 23 | <br>of a CD-ROM or other source which is not controllable via the standard
|
|---|
| 24 | MMPM/2 API.
|
|---|
| 25 | <p>Users will note that the OS/2 shipped CD-Player application includes
|
|---|
| 26 | a volume slider.
|
|---|
| 27 | <br>This slider adjust the CD-ROM playback volume at the CD-ROM unit.
|
|---|
| 28 | <br>The analog signal from the CD-ROM player is provided to the system
|
|---|
| 29 | audio device via an analog cable.
|
|---|
| 30 | <br>Under MMPM/2, there is no means to adjust the volume of this signal
|
|---|
| 31 | at the audio device.
|
|---|
| 32 | <br>Master volume can be adjusted, but the relative volume of the CD input
|
|---|
| 33 | cannot be adjusted
|
|---|
| 34 | <br>with just the MMPM/2 API.
|
|---|
| 35 | <p>The category 90 mixer IOCTLs fill this gap.
|
|---|
| 36 | <p>The IOCTLs also support volume control for various other inputs to the
|
|---|
| 37 | audio device mixer and the
|
|---|
| 38 | <br>ability to override record gain and stream volume for execution of
|
|---|
| 39 | WinOS2 and other applications
|
|---|
| 40 | <br>that do not implement their own sliders for these controls.
|
|---|
| 41 | <p><font color="#3333FF"><font size=+1>STATUS (Drivers known to implement
|
|---|
| 42 | this API)</font></font>
|
|---|
| 43 | <ul>
|
|---|
| 44 | <li>
|
|---|
| 45 | Crystal Semiconductor ISA Mode 3 device driver, version 2.08</li>
|
|---|
| 46 |
|
|---|
| 47 | <ul>
|
|---|
| 48 | <li>
|
|---|
| 49 | CS4236B, CS4237B, CS4238B, CS4235, CS4239</li>
|
|---|
| 50 | </ul>
|
|---|
| 51 |
|
|---|
| 52 | <li>
|
|---|
| 53 | Crystal Semiconductor PCI device driver set, version 3.02</li>
|
|---|
| 54 |
|
|---|
| 55 | <ul>
|
|---|
| 56 | <li>
|
|---|
| 57 | CS4614, CS4624, CS4280</li>
|
|---|
| 58 | </ul>
|
|---|
| 59 | </ul>
|
|---|
| 60 | <font color="#3333FF"><font size=+1>Limitations and differences from Windows
|
|---|
| 61 | mixer definitions</font></font>
|
|---|
| 62 | <br>A programmer will note that this API does not address some of the common
|
|---|
| 63 | features of a mixer application.
|
|---|
| 64 | <br>Most notable missing function: Master Volume.
|
|---|
| 65 | <p>The IOCTL90 definition attempts to not redefine things that are already
|
|---|
| 66 | defined in MMPM/2 API.
|
|---|
| 67 | <br>Exceptions are made for record gain, record source and stream volume,
|
|---|
| 68 | but these exceptions are
|
|---|
| 69 | <br>kept to a minimum to avoid complicating the progamming of an audio
|
|---|
| 70 | device driver.
|
|---|
| 71 | <p>A developed mixer application is expected to use a combination of the
|
|---|
| 72 | standard MMPM/2 APIs
|
|---|
| 73 | <br>(via MCI commands) along with the the Category 0x90 IOCTLs defined
|
|---|
| 74 | in this file.
|
|---|
| 75 | <p><font color="#3333FF"><font size=+1>Master Volume</font></font>
|
|---|
| 76 | <br>MMPM/2 defines master volume and the operating system ships a master
|
|---|
| 77 | volume application.
|
|---|
| 78 | <br>The standard application works.
|
|---|
| 79 | <p>Since master volume is already handled by the MMPM/2 API, it is not
|
|---|
| 80 | re-invented in the category 90 IOCTLs.
|
|---|
| 81 | <br>Mixer application developers COULD issue appropriate MCI commands to
|
|---|
| 82 | adjust master volume
|
|---|
| 83 | <br>outside IOCTL90. They are encouraged to not implement
|
|---|
| 84 | master volume in the mixer application.
|
|---|
| 85 | <p>The OS/2 shipped "Volume Control" application is not very robust.
|
|---|
| 86 | <br>It provides no means for message callbacks. That is, there can
|
|---|
| 87 | be at-most ONE controller of
|
|---|
| 88 | <br>master volume in the system as any change of master volume by a secondary
|
|---|
| 89 | application cannot be reflected
|
|---|
| 90 | <br>on the GUI of the OS/2 standard volume control application.
|
|---|
| 91 | <p><font color="#3333FF"><font size=+1>Per-Stream Volume and Per-Stream
|
|---|
| 92 | Gain</font></font>
|
|---|
| 93 | <br>On OS/2, wave audio volume, record gain and record source are defined
|
|---|
| 94 | as per-stream concepts.
|
|---|
| 95 | <br>This is very different than Windows where application volume and gain
|
|---|
| 96 | are defined as system global.
|
|---|
| 97 | <p>Any set of these parameters outside the environment of the owning stream
|
|---|
| 98 | is defined to be un-done
|
|---|
| 99 | <br>when a stream is started.
|
|---|
| 100 | <p>Volume and gain are supposed to be different for each application under
|
|---|
| 101 | OS/2 and each application
|
|---|
| 102 | <br>is expected to implement sliders to support adjustment of its stream
|
|---|
| 103 | volume and gain (and most do).
|
|---|
| 104 | <p>Unfortunately, a sufficiently large number of applications do not.
|
|---|
| 105 | Usually, this is due to the application
|
|---|
| 106 | <br>being ported from Windows environment where the support of a global
|
|---|
| 107 | external mixer was assumed.
|
|---|
| 108 | <p>IOCTL90 allows the mixer application to override MMPM/2 per-stream volume
|
|---|
| 109 | and record gain.
|
|---|
| 110 | <p>This action is most useful for execution of Windows multimedia applications
|
|---|
| 111 | inside WinOS2.
|
|---|
| 112 | <br>By allowing the OS/2 native mixer to control these settings globally,
|
|---|
| 113 | the OS/2 mixer can effect record
|
|---|
| 114 | <br>gain, record source and playback volumes for WinOS2 applications.
|
|---|
| 115 | <p>This eliminates the need for a WinOS2 mixer application.
|
|---|
| 116 | <p>
|
|---|
| 117 | <hr WIDTH="100%"><font color="#3333FF"><font size=+1>Hardware mixer model</font></font>
|
|---|
| 118 | <br>The Category 0x90 mixer IOCTLs are modeled on the Intel AC97 Audio
|
|---|
| 119 | CODEC definition.
|
|---|
| 120 | <br>The AC97 audio CODEC is the mixer architecture which is normally used
|
|---|
| 121 | with PCI bus audio devices.
|
|---|
| 122 | <p>The same hardware architecture is used by numerous audio system venders,
|
|---|
| 123 | thus promoting the portability of the IOCTL90 mixer API. The AC97
|
|---|
| 124 | is also a "fairly simple" mixer device and can therefore be emulated on
|
|---|
| 125 | many other more full-function devices, again promoting portability of the
|
|---|
| 126 | API.
|
|---|
| 127 | <p>For details on the AC97 mixer architecture, consult this databook, <a href="ftp://ftp.cirrus.com/pub/pubs/4297.pdf">Crystal
|
|---|
| 128 | Clear(tm) SoundFusion(tm) Audio Codec '97 (CS4297)</a>
|
|---|
| 129 | <p>All Set/Get functions accept a single parameter (data block pointer)
|
|---|
| 130 | which has this definition:
|
|---|
| 131 | <blockquote><tt><font color="#3333FF">typedef struct</font></tt>
|
|---|
| 132 | <br><tt><font color="#3333FF">{</font></tt>
|
|---|
| 133 | <br><tt><font color="#3333FF"> ULONG Mute;
|
|---|
| 134 | // UnMute==0, Mute==1</font></tt>
|
|---|
| 135 | <br><tt><font color="#3333FF"> ULONG VolumeL;
|
|---|
| 136 | // 0..100 percent</font></tt>
|
|---|
| 137 | <br><tt><font color="#3333FF"> ULONG VolumeR;
|
|---|
| 138 | // 0..100 percent</font></tt>
|
|---|
| 139 | <br><tt><font color="#3333FF">} MIXSTRUCT, *PMIXSTRUCT;</font></tt></blockquote>
|
|---|
| 140 | The IOCTLs in the 0x40 and 0x60 range are nearly self explanatory.
|
|---|
| 141 | (Get/Set volume).
|
|---|
| 142 | <br>The 0x80 and 0x81 APIs were added after external review to improve
|
|---|
| 143 | evolution of the API.
|
|---|
| 144 | <p>The query APIs return the value most recently written, not a calculated
|
|---|
| 145 | value based on
|
|---|
| 146 | <br>the setting read from the hardware. This avoids granularity issues
|
|---|
| 147 | of the physical device
|
|---|
| 148 | <br>hardware (often only 32 possible settings) versus 101 possible volume
|
|---|
| 149 | settings in the API (0..100 percent).
|
|---|
| 150 | <p>
|
|---|
| 151 | <hr WIDTH="100%">
|
|---|
| 152 | <br><u><font size=+1>40 - MonoInSet</font></u>
|
|---|
| 153 | <br>Set volume of system Mono input.
|
|---|
| 154 | <p><font color="#009900">Introduced:</font> API Level 1
|
|---|
| 155 | <p>Parameters (PMIXSTRUCT).
|
|---|
| 156 | <br>
|
|---|
| 157 | <table BORDER COLS=2 WIDTH="52%" >
|
|---|
| 158 | <tr>
|
|---|
| 159 | <td>Mute</td>
|
|---|
| 160 |
|
|---|
| 161 | <td>0=>Audible, 1=>Mute</td>
|
|---|
| 162 | </tr>
|
|---|
| 163 |
|
|---|
| 164 | <tr>
|
|---|
| 165 | <td>Left</td>
|
|---|
| 166 |
|
|---|
| 167 | <td>Volume range 0..100</td>
|
|---|
| 168 | </tr>
|
|---|
| 169 |
|
|---|
| 170 | <tr>
|
|---|
| 171 | <td>Right</td>
|
|---|
| 172 |
|
|---|
| 173 | <td>Not used. Set = Left.</td>
|
|---|
| 174 | </tr>
|
|---|
| 175 | </table>
|
|---|
| 176 |
|
|---|
| 177 | <p><font color="#3333FF">Connection</font>:
|
|---|
| 178 | <br>In most add-in card systems, this input is not used.
|
|---|
| 179 | <br>In many motherboard installations, this input is used for PC Speaker
|
|---|
| 180 | (beeps and clicks).
|
|---|
| 181 | <br>It is also used on motherboard systems for the audible signal from
|
|---|
| 182 | internal modems.
|
|---|
| 183 | <p>The device driver takes the MONO volume from the "left" field of the
|
|---|
| 184 | passed structure.
|
|---|
| 185 | <br>Application should fill in "right" field of structure with same value
|
|---|
| 186 | set for left.
|
|---|
| 187 | <br>
|
|---|
| 188 | <p><u><font size=+1>41 - PhoneSet</font></u>
|
|---|
| 189 | <br>Set volume of system Phone input.
|
|---|
| 190 | <p><font color="#009900">Introduced:</font> API Level 1
|
|---|
| 191 | <p>Parameters (PMIXSTRUCT).
|
|---|
| 192 | <br>
|
|---|
| 193 | <table BORDER COLS=2 WIDTH="52%" >
|
|---|
| 194 | <tr>
|
|---|
| 195 | <td>Mute</td>
|
|---|
| 196 |
|
|---|
| 197 | <td>0=>Audible, 1=>Mute</td>
|
|---|
| 198 | </tr>
|
|---|
| 199 |
|
|---|
| 200 | <tr>
|
|---|
| 201 | <td>Left</td>
|
|---|
| 202 |
|
|---|
| 203 | <td>Left volume range 0..100</td>
|
|---|
| 204 | </tr>
|
|---|
| 205 |
|
|---|
| 206 | <tr>
|
|---|
| 207 | <td>Right</td>
|
|---|
| 208 |
|
|---|
| 209 | <td>Right volume range 0..100</td>
|
|---|
| 210 | </tr>
|
|---|
| 211 | </table>
|
|---|
| 212 |
|
|---|
| 213 | <p><font color="#3333FF">Connection</font>:
|
|---|
| 214 | <br>In most add-in card systems, this input is not used.
|
|---|
| 215 | <br>In many PCI audio motherboard installations, this input is used connection
|
|---|
| 216 | from internal modem.
|
|---|
| 217 | <br>
|
|---|
| 218 | <p><u><font size=+1>42 - MicSet</font></u>
|
|---|
| 219 | <br>Set volume of system microphone.
|
|---|
| 220 | <p><font color="#009900">Introduced:</font> API Level 1
|
|---|
| 221 | <p>Parameters (PMIXSTRUCT).
|
|---|
| 222 | <br>
|
|---|
| 223 | <table BORDER COLS=2 WIDTH="52%" >
|
|---|
| 224 | <tr>
|
|---|
| 225 | <td>Mute</td>
|
|---|
| 226 |
|
|---|
| 227 | <td>0=>Audible, 1=>Mute</td>
|
|---|
| 228 | </tr>
|
|---|
| 229 |
|
|---|
| 230 | <tr>
|
|---|
| 231 | <td>Left</td>
|
|---|
| 232 |
|
|---|
| 233 | <td>Left volume range 0..100</td>
|
|---|
| 234 | </tr>
|
|---|
| 235 |
|
|---|
| 236 | <tr>
|
|---|
| 237 | <td>Right</td>
|
|---|
| 238 |
|
|---|
| 239 | <td>Right volume range 0..100</td>
|
|---|
| 240 | </tr>
|
|---|
| 241 | </table>
|
|---|
| 242 |
|
|---|
| 243 | <p><font color="#3333FF">Connection</font>:
|
|---|
| 244 | <br>This IOCTL sets the listening level of the system microphone.
|
|---|
| 245 | System microphone is normally muted.
|
|---|
| 246 | <br>It can be un-muted to enable karoke mode.
|
|---|
| 247 | <p>Note: This IOCTL does not effect the record level for microphone.
|
|---|
| 248 | <br>
|
|---|
| 249 | <p><u><font size=+1>43 - LineSet</font></u>
|
|---|
| 250 | <br>Set volume of system Line-In connection
|
|---|
| 251 | <p><font color="#009900">Introduced:</font> API Level 1
|
|---|
| 252 | <p>Parameters (PMIXSTRUCT).
|
|---|
| 253 | <br>
|
|---|
| 254 | <table BORDER COLS=2 WIDTH="52%" >
|
|---|
| 255 | <tr>
|
|---|
| 256 | <td>Mute</td>
|
|---|
| 257 |
|
|---|
| 258 | <td>0=>Audible, 1=>Mute</td>
|
|---|
| 259 | </tr>
|
|---|
| 260 |
|
|---|
| 261 | <tr>
|
|---|
| 262 | <td>Left</td>
|
|---|
| 263 |
|
|---|
| 264 | <td>Left volume range 0..100</td>
|
|---|
| 265 | </tr>
|
|---|
| 266 |
|
|---|
| 267 | <tr>
|
|---|
| 268 | <td>Right</td>
|
|---|
| 269 |
|
|---|
| 270 | <td>Right volume range 0..100</td>
|
|---|
| 271 | </tr>
|
|---|
| 272 | </table>
|
|---|
| 273 |
|
|---|
| 274 | <p><font color="#3333FF">Connection</font>:
|
|---|
| 275 | <br>Line-In is normally an input on the system sound card - accessible
|
|---|
| 276 | on the back of the computer system.
|
|---|
| 277 | <br>
|
|---|
| 278 | <p><u><font size=+1>44 - CDSet</font></u>
|
|---|
| 279 | <br>Sets the listening level of the CD-ROM analog signal input to the audio
|
|---|
| 280 | device.
|
|---|
| 281 | <p><font color="#009900">Introduced:</font> API Level 1
|
|---|
| 282 | <p>Parameters (PMIXSTRUCT).
|
|---|
| 283 | <br>
|
|---|
| 284 | <table BORDER COLS=2 WIDTH="53%" >
|
|---|
| 285 | <tr>
|
|---|
| 286 | <td>Mute</td>
|
|---|
| 287 |
|
|---|
| 288 | <td>0=>Audible, 1=>Mute</td>
|
|---|
| 289 | </tr>
|
|---|
| 290 |
|
|---|
| 291 | <tr>
|
|---|
| 292 | <td>Left</td>
|
|---|
| 293 |
|
|---|
| 294 | <td>Left volume range 0..100</td>
|
|---|
| 295 | </tr>
|
|---|
| 296 |
|
|---|
| 297 | <tr>
|
|---|
| 298 | <td>Right</td>
|
|---|
| 299 |
|
|---|
| 300 | <td>Right volume range 0..100</td>
|
|---|
| 301 | </tr>
|
|---|
| 302 | </table>
|
|---|
| 303 |
|
|---|
| 304 | <p><font color="#3333FF">Connection</font>:
|
|---|
| 305 | <br>CD-ROM input to sound card volume is controlled with this API.
|
|---|
| 306 | <p>This input is normally connected to the sound card via connector inside
|
|---|
| 307 | the PC system unit. The signal controlled with this API is that which
|
|---|
| 308 | arrives on the analog cable from the CD-ROM drive.
|
|---|
| 309 | <p><i>Note:</i>
|
|---|
| 310 | <br>If CD-DA digital streaming is being used, the sound card views the
|
|---|
| 311 | CD data as normal wave-audio. That is, this API will not effect
|
|---|
| 312 | CD-ROM lisenting level if CD-DA digital streaming is being used (CD player
|
|---|
| 313 | application choice).
|
|---|
| 314 | <br>
|
|---|
| 315 | <p><u><font size=+1>45 - VideoSet</font></u>
|
|---|
| 316 | <br>Sets the listening level of the sound card "video" input.
|
|---|
| 317 | <p><font color="#009900">Introduced:</font> API Level 1
|
|---|
| 318 | <p>Parameters (PMIXSTRUCT).
|
|---|
| 319 | <br>
|
|---|
| 320 | <table BORDER COLS=2 WIDTH="52%" >
|
|---|
| 321 | <tr>
|
|---|
| 322 | <td>Mute</td>
|
|---|
| 323 |
|
|---|
| 324 | <td>0=>Audible, 1=>Mute</td>
|
|---|
| 325 | </tr>
|
|---|
| 326 |
|
|---|
| 327 | <tr>
|
|---|
| 328 | <td>Left</td>
|
|---|
| 329 |
|
|---|
| 330 | <td>Left volume range 0..100</td>
|
|---|
| 331 | </tr>
|
|---|
| 332 |
|
|---|
| 333 | <tr>
|
|---|
| 334 | <td>Right</td>
|
|---|
| 335 |
|
|---|
| 336 | <td>Right volume range 0..100</td>
|
|---|
| 337 | </tr>
|
|---|
| 338 | </table>
|
|---|
| 339 |
|
|---|
| 340 | <p><font color="#3333FF">Connection</font>:
|
|---|
| 341 | <br>On equiped systems, effects the lisenting level of movie playback.
|
|---|
| 342 | <br>Most systems do not used this mixer input.
|
|---|
| 343 | <br>
|
|---|
| 344 | <p><u><font size=+1>46 - AuxSet</font></u>
|
|---|
| 345 | <br>Sets the listening level of the sound card "aux" input.
|
|---|
| 346 | <p><font color="#009900">Introduced:</font> API Level 1
|
|---|
| 347 | <p>Parameters (PMIXSTRUCT).
|
|---|
| 348 | <br>
|
|---|
| 349 | <table BORDER COLS=2 WIDTH="52%" >
|
|---|
| 350 | <tr>
|
|---|
| 351 | <td>Mute</td>
|
|---|
| 352 |
|
|---|
| 353 | <td>0=>Audible, 1=>Mute</td>
|
|---|
| 354 | </tr>
|
|---|
| 355 |
|
|---|
| 356 | <tr>
|
|---|
| 357 | <td>Left</td>
|
|---|
| 358 |
|
|---|
| 359 | <td>Left volume range 0..100</td>
|
|---|
| 360 | </tr>
|
|---|
| 361 |
|
|---|
| 362 | <tr>
|
|---|
| 363 | <td>Right</td>
|
|---|
| 364 |
|
|---|
| 365 | <td>Right volume range 0..100</td>
|
|---|
| 366 | </tr>
|
|---|
| 367 | </table>
|
|---|
| 368 |
|
|---|
| 369 | <p><font color="#3333FF">Connection</font>:
|
|---|
| 370 | <br>On equiped systems, effects the lisenting level of aux input.
|
|---|
| 371 | <br>AC97 systems include an Aux connection that may or may not actually
|
|---|
| 372 | be populated on system.
|
|---|
| 373 | <br>Most ISA devices do not include an Aux connector.
|
|---|
| 374 | <br>
|
|---|
| 375 | <p><u><font size=+1>4B - BassTrebleSet</font></u>
|
|---|
| 376 | <br>Change Bass and Treble settings
|
|---|
| 377 | <p><font color="#009900">Introduced:</font> API Level 1
|
|---|
| 378 | <p>Parameters (PMIXSTRUCT).
|
|---|
| 379 | <br>
|
|---|
| 380 | <table BORDER COLS=2 WIDTH="52%" >
|
|---|
| 381 | <tr>
|
|---|
| 382 | <td>Mute (flags)</td>
|
|---|
| 383 |
|
|---|
| 384 | <td>not used, set to 0</td>
|
|---|
| 385 | </tr>
|
|---|
| 386 |
|
|---|
| 387 | <tr>
|
|---|
| 388 | <td>Left (Bass)</td>
|
|---|
| 389 |
|
|---|
| 390 | <td>0..100</td>
|
|---|
| 391 | </tr>
|
|---|
| 392 |
|
|---|
| 393 | <tr>
|
|---|
| 394 | <td>Right (Treble)</td>
|
|---|
| 395 |
|
|---|
| 396 | <td>0..100</td>
|
|---|
| 397 | </tr>
|
|---|
| 398 | </table>
|
|---|
| 399 |
|
|---|
| 400 | <p><font color="#3333FF">Connection</font>:
|
|---|
| 401 | <br>Bass and Treble are not part of the AC97 mixer definition.
|
|---|
| 402 | <p>They are implemented on some audio devices as a post processing algorithm
|
|---|
| 403 | <br>applied to the output of audio device. Bass and Treble effect
|
|---|
| 404 | the sound level
|
|---|
| 405 | <br>of low frequency and high frequency sounds independent of volume.
|
|---|
| 406 | <p>A device driver can indicate support for Bass only, Treble only or both
|
|---|
| 407 | via
|
|---|
| 408 | <br>the BassTrebleQuery API.
|
|---|
| 409 | <p>Device drivers default both bass and treble to 50%.
|
|---|
| 410 | <br>A setting of 50% means no effect to the audio signal.
|
|---|
| 411 | <br>
|
|---|
| 412 | <p><u><font size=+1>4C - ThreeDSet</font></u>
|
|---|
| 413 | <br>Enables or disables 3D sound effect. Popular algorithms include
|
|---|
| 414 | SRS and QSOUND.
|
|---|
| 415 | <p><font color="#009900">Introduced:</font> API Level 1
|
|---|
| 416 | <p>Parameters (PMIXSTRUCT).
|
|---|
| 417 | <br>
|
|---|
| 418 | <table BORDER COLS=2 WIDTH="52%" >
|
|---|
| 419 | <tr>
|
|---|
| 420 | <td>Mute (enable)</td>
|
|---|
| 421 |
|
|---|
| 422 | <td>0x01=No 3D (Muted)
|
|---|
| 423 | <br>0x00=Enabled </td>
|
|---|
| 424 | </tr>
|
|---|
| 425 |
|
|---|
| 426 | <tr>
|
|---|
| 427 | <td>Left (Space)</td>
|
|---|
| 428 |
|
|---|
| 429 | <td>0..100</td>
|
|---|
| 430 | </tr>
|
|---|
| 431 |
|
|---|
| 432 | <tr>
|
|---|
| 433 | <td>Right (Center)</td>
|
|---|
| 434 |
|
|---|
| 435 | <td>0..100</td>
|
|---|
| 436 | </tr>
|
|---|
| 437 | </table>
|
|---|
| 438 |
|
|---|
| 439 | <p><font color="#3333FF">Connection</font>:
|
|---|
| 440 | <br>3D is a post processing algorithm applied to the output of audio device
|
|---|
| 441 | to
|
|---|
| 442 | <br>artificially make the speakers sound like they are further apart.
|
|---|
| 443 | <p>A device driver can indicate support for Space and Center via the ThreeDQuery
|
|---|
| 444 | API.
|
|---|
| 445 | <p>Enable flags:
|
|---|
| 446 | <br>Application should set only bit D0. Other bits should be zero.
|
|---|
| 447 | <br>Device driver should reference only bit D0. Other bits are don't
|
|---|
| 448 | care.
|
|---|
| 449 | <br>
|
|---|
| 450 | <p><u><font size=+1>4D - StreamVolSet</font></u>
|
|---|
| 451 | <br>Sets the stream playback volume globally - disabling MMPM/2 per-stream
|
|---|
| 452 | volume.
|
|---|
| 453 | <br>Notice that this API is redundent to and overrides the MMPM/2 defined
|
|---|
| 454 | concept of per-stream volume.
|
|---|
| 455 | <p>This API is implemented as counterpart to function 4F RecordGainSet.
|
|---|
| 456 | <p><font color="#009900">Introduced:</font> API Level 2
|
|---|
| 457 | <p>All device drivers implementing this IOCTL are expected to return API
|
|---|
| 458 | level 2 or
|
|---|
| 459 | <br>beyond on API level query IOCTL.
|
|---|
| 460 | <p>Parameters (PMIXSTRUCT).
|
|---|
| 461 | <br>
|
|---|
| 462 | <table BORDER COLS=2 WIDTH="52%" >
|
|---|
| 463 | <tr>
|
|---|
| 464 | <td>Mute (Flags)</td>
|
|---|
| 465 |
|
|---|
| 466 | <td>0x0001=>Mute 0x0002=>Release</td>
|
|---|
| 467 | </tr>
|
|---|
| 468 |
|
|---|
| 469 | <tr>
|
|---|
| 470 | <td>Left</td>
|
|---|
| 471 |
|
|---|
| 472 | <td>Left volume range 0..100</td>
|
|---|
| 473 | </tr>
|
|---|
| 474 |
|
|---|
| 475 | <tr>
|
|---|
| 476 | <td>Right</td>
|
|---|
| 477 |
|
|---|
| 478 | <td>Right volume range 0..100</td>
|
|---|
| 479 | </tr>
|
|---|
| 480 | </table>
|
|---|
| 481 |
|
|---|
| 482 | <p><font color="#3333FF">Connection</font>:
|
|---|
| 483 | <br>Overrides MMPM/2 per-stream volume.
|
|---|
| 484 | <br>Note, this API does not effect system master volume.
|
|---|
| 485 | <br>
|
|---|
| 486 | <p><u><font size=+1>4E - RecordSrcSet</font></u>
|
|---|
| 487 | <br>Overrides MMPM/2 defined per-stream record source.
|
|---|
| 488 | <p>Provided record source will be used as global record source.
|
|---|
| 489 | <br>Call with "release" bit set in flags to return control to MMPM/2.
|
|---|
| 490 | <p><font color="#009900">Introduced:</font> API Level 2
|
|---|
| 491 | <p>Parameters (PMIXSTRUCT).
|
|---|
| 492 | <br>
|
|---|
| 493 | <table BORDER COLS=2 WIDTH="52%" >
|
|---|
| 494 | <tr>
|
|---|
| 495 | <td>Mute (Flags)</td>
|
|---|
| 496 |
|
|---|
| 497 | <td>0x0002=>Release</td>
|
|---|
| 498 | </tr>
|
|---|
| 499 |
|
|---|
| 500 | <tr>
|
|---|
| 501 | <td>Left</td>
|
|---|
| 502 |
|
|---|
| 503 | <td>Record Source</td>
|
|---|
| 504 | </tr>
|
|---|
| 505 |
|
|---|
| 506 | <tr>
|
|---|
| 507 | <td>Right</td>
|
|---|
| 508 |
|
|---|
| 509 | <td>Not used, set to 0</td>
|
|---|
| 510 | </tr>
|
|---|
| 511 | </table>
|
|---|
| 512 |
|
|---|
| 513 | <p><font color="#3333FF">Record Source Definition</font>
|
|---|
| 514 | <table BORDER COLS=2 WIDTH="75%" >
|
|---|
| 515 | <tr>
|
|---|
| 516 | <td>0x00000000..0x0000000F</td>
|
|---|
| 517 |
|
|---|
| 518 | <td>Reserved</td>
|
|---|
| 519 | </tr>
|
|---|
| 520 |
|
|---|
| 521 | <tr>
|
|---|
| 522 | <td>0x00000010</td>
|
|---|
| 523 |
|
|---|
| 524 | <td>Mic</td>
|
|---|
| 525 | </tr>
|
|---|
| 526 |
|
|---|
| 527 | <tr>
|
|---|
| 528 | <td>0x00000020</td>
|
|---|
| 529 |
|
|---|
| 530 | <td>CD-ROM</td>
|
|---|
| 531 | </tr>
|
|---|
| 532 |
|
|---|
| 533 | <tr>
|
|---|
| 534 | <td>0x00000040</td>
|
|---|
| 535 |
|
|---|
| 536 | <td>Video</td>
|
|---|
| 537 | </tr>
|
|---|
| 538 |
|
|---|
| 539 | <tr>
|
|---|
| 540 | <td>0x00000080</td>
|
|---|
| 541 |
|
|---|
| 542 | <td>Aux</td>
|
|---|
| 543 | </tr>
|
|---|
| 544 |
|
|---|
| 545 | <tr>
|
|---|
| 546 | <td>0x00000100</td>
|
|---|
| 547 |
|
|---|
| 548 | <td>Line</td>
|
|---|
| 549 | </tr>
|
|---|
| 550 |
|
|---|
| 551 | <tr>
|
|---|
| 552 | <td>0x00000200</td>
|
|---|
| 553 |
|
|---|
| 554 | <td>Reserved</td>
|
|---|
| 555 | </tr>
|
|---|
| 556 |
|
|---|
| 557 | <tr>
|
|---|
| 558 | <td>0x00000400</td>
|
|---|
| 559 |
|
|---|
| 560 | <td>Reserved</td>
|
|---|
| 561 | </tr>
|
|---|
| 562 |
|
|---|
| 563 | <tr>
|
|---|
| 564 | <td>0x00000800</td>
|
|---|
| 565 |
|
|---|
| 566 | <td>Phone</td>
|
|---|
| 567 | </tr>
|
|---|
| 568 | </table>
|
|---|
| 569 |
|
|---|
| 570 | <p>On query, device driver indicates whether or not it supports input mixer.
|
|---|
| 571 | <p>If input mux, mixer application can set only one source as input.
|
|---|
| 572 | <br>If input mixer, mixer application can OR on appropriate bits.
|
|---|
| 573 | <p>Application should use results of function 81 (function support map)
|
|---|
| 574 | to know
|
|---|
| 575 | <br>which inputs the device supports.
|
|---|
| 576 | <p><font color="#3333FF">Device Specific Notes</font>:
|
|---|
| 577 | <br>On the Crystal Semiconductor ISA Mode 3 device driver, (CS4236B/7B/8B,
|
|---|
| 578 | CS4235, CS4239):
|
|---|
| 579 | <br>MONO-IN is a playback source and its volume can be adjusted via function
|
|---|
| 580 | 0x40.
|
|---|
| 581 | <br>MONO-IN however is not a possible record source.
|
|---|
| 582 | The device driver treats a request to
|
|---|
| 583 | <br>record from MONO-IN as a request to record from NULL device (no sound).
|
|---|
| 584 | <p><u><font size=+1>4F - RecordGainSet</font></u>
|
|---|
| 585 | <br>Sets the record gain globally - disabling MMPM/2 per-stream record
|
|---|
| 586 | gain.
|
|---|
| 587 | <br>Notice that this API is redundent to and overrides the MMPM/2 defined
|
|---|
| 588 | concept of per-stream record gain.
|
|---|
| 589 | <p>It can be argued that this API should only effect record gain for WinOS2.
|
|---|
| 590 | <br>MMPM/2 already defines record gain as a concept for OS/2 applications.
|
|---|
| 591 | <p>The API exists for two primary reasons
|
|---|
| 592 | <ul>
|
|---|
| 593 | <li>
|
|---|
| 594 | Help poorly written OS/2 native applications perform record function -
|
|---|
| 595 | adjust their record gain.</li>
|
|---|
| 596 |
|
|---|
| 597 | <li>
|
|---|
| 598 | WinOS2 support - mixer control for record gain as a global concept as defined
|
|---|
| 599 | in Windows.</li>
|
|---|
| 600 | </ul>
|
|---|
| 601 | This API changes definition of record gain from a MMPM/2 per-stream concept
|
|---|
| 602 | to a
|
|---|
| 603 | <br>mixer application global concept. Once this IOCTL is sent, record
|
|---|
| 604 | gain is global.
|
|---|
| 605 | <br>The gain sent from the mixer application overrules the per-stream gain
|
|---|
| 606 | sent from MMPM/2.
|
|---|
| 607 | <p>API Level 2 includes the ability for the mixer application to return
|
|---|
| 608 | control of
|
|---|
| 609 | <br>gain to traditional MMPM/2 per-stream definition.
|
|---|
| 610 | <p><font color="#009900">Introduced:</font> API Level 1, Current implementation
|
|---|
| 611 | requires API level 2 (for release)
|
|---|
| 612 | <p>Parameters (PMIXSTRUCT).
|
|---|
| 613 | <br>
|
|---|
| 614 | <table BORDER COLS=2 WIDTH="52%" >
|
|---|
| 615 | <tr>
|
|---|
| 616 | <td>Mute (Flags)</td>
|
|---|
| 617 |
|
|---|
| 618 | <td>0x0001=>Mute 0x0002=>Release</td>
|
|---|
| 619 | </tr>
|
|---|
| 620 |
|
|---|
| 621 | <tr>
|
|---|
| 622 | <td>Left</td>
|
|---|
| 623 |
|
|---|
| 624 | <td>Left volume range 0..100</td>
|
|---|
| 625 | </tr>
|
|---|
| 626 |
|
|---|
| 627 | <tr>
|
|---|
| 628 | <td>Right</td>
|
|---|
| 629 |
|
|---|
| 630 | <td>Not used, set to 0</td>
|
|---|
| 631 | </tr>
|
|---|
| 632 | </table>
|
|---|
| 633 |
|
|---|
| 634 | <p><font color="#3333FF">Connection</font>:
|
|---|
| 635 | <br>Sets the record gain setting just before the Analog/Digital converter
|
|---|
| 636 | inside the AC97 mixer.
|
|---|
| 637 | <br>This API effects what you "record", not what you "hear".
|
|---|
| 638 | <p><font color="#3333FF">Notes</font>:
|
|---|
| 639 | <br>Crystal Semiconductor drivers 2.08 (ISA) and 3.03 (PCI) implement this
|
|---|
| 640 | API, but implement
|
|---|
| 641 | <br>it only with global effect (API level 1).
|
|---|
| 642 | <p>Crystal Semiconductor driver 2.09 (ISA) implements this API at API level
|
|---|
| 643 | 2.
|
|---|
| 644 | <br>That is, the "release" bit is defined and recognized by the device
|
|---|
| 645 | driver.
|
|---|
| 646 | <p>In API level 2, the mixer definition was enhanced to allow the mixer
|
|---|
| 647 | to return record gain to be a per-stream concept.
|
|---|
| 648 | <br>That is, to cancel the override and again place record gain into the
|
|---|
| 649 | control of MMPM/2.
|
|---|
| 650 | <p>
|
|---|
| 651 | <hr WIDTH="100%">
|
|---|
| 652 | <br><u><font size=+1>60 - MonoInQuery</font></u>
|
|---|
| 653 | <br>Query volume of system Mono input.
|
|---|
| 654 | <p><font color="#009900">Introduced:</font> API Level 1
|
|---|
| 655 | <p>Parameters (PMIXSTRUCT).
|
|---|
| 656 | <br>
|
|---|
| 657 | <table BORDER COLS=2 WIDTH="50%" >
|
|---|
| 658 | <tr>
|
|---|
| 659 | <td>Mute</td>
|
|---|
| 660 |
|
|---|
| 661 | <td>0=>Audible, 1=>Mute</td>
|
|---|
| 662 | </tr>
|
|---|
| 663 |
|
|---|
| 664 | <tr>
|
|---|
| 665 | <td>Left</td>
|
|---|
| 666 |
|
|---|
| 667 | <td>Volume range 0..100</td>
|
|---|
| 668 | </tr>
|
|---|
| 669 |
|
|---|
| 670 | <tr>
|
|---|
| 671 | <td>Right</td>
|
|---|
| 672 |
|
|---|
| 673 | <td>Not used, PDD will set to 0 </td>
|
|---|
| 674 | </tr>
|
|---|
| 675 | </table>
|
|---|
| 676 |
|
|---|
| 677 | <p><font color="#3333FF">Connection</font>:
|
|---|
| 678 | <br>In most add-in card systems, this input is not used.
|
|---|
| 679 | <br>In many motherboard installations, this input is used for PC Speaker
|
|---|
| 680 | (beeps and clicks).
|
|---|
| 681 | <br>It is also used on motherboard systems for the audible signal from
|
|---|
| 682 | internal modems.
|
|---|
| 683 | <p>The device driver sets the left field to value for mono volume.
|
|---|
| 684 | <br>
|
|---|
| 685 | <p><u><font size=+1>61 - PhoneQuery</font></u>
|
|---|
| 686 | <br>Query volume of system Phone input.
|
|---|
| 687 | <p><font color="#009900">Introduced:</font> API Level 1
|
|---|
| 688 | <p>Parameters (PMIXSTRUCT).
|
|---|
| 689 | <br>
|
|---|
| 690 | <table BORDER COLS=2 WIDTH="52%" >
|
|---|
| 691 | <tr>
|
|---|
| 692 | <td>Mute</td>
|
|---|
| 693 |
|
|---|
| 694 | <td>0=>Audible, 1=>Mute</td>
|
|---|
| 695 | </tr>
|
|---|
| 696 |
|
|---|
| 697 | <tr>
|
|---|
| 698 | <td>Left</td>
|
|---|
| 699 |
|
|---|
| 700 | <td>Left volume range 0..100</td>
|
|---|
| 701 | </tr>
|
|---|
| 702 |
|
|---|
| 703 | <tr>
|
|---|
| 704 | <td>Right</td>
|
|---|
| 705 |
|
|---|
| 706 | <td>Right volume range 0..100</td>
|
|---|
| 707 | </tr>
|
|---|
| 708 | </table>
|
|---|
| 709 |
|
|---|
| 710 | <p><font color="#3333FF">Connection</font>:
|
|---|
| 711 | <br>In most add-in card systems, this input is not used.
|
|---|
| 712 | <br>In many motherboard installations, this input is used connection from
|
|---|
| 713 | internal modem.
|
|---|
| 714 | <br>
|
|---|
| 715 | <p><u><font size=+1>62 - MicQuery</font></u>
|
|---|
| 716 | <br>Query volume of system microphone.
|
|---|
| 717 | <p><font color="#009900">Introduced:</font> API Level 1
|
|---|
| 718 | <p>Parameters (PMIXSTRUCT).
|
|---|
| 719 | <br>
|
|---|
| 720 | <table BORDER COLS=2 WIDTH="53%" >
|
|---|
| 721 | <tr>
|
|---|
| 722 | <td>Mute</td>
|
|---|
| 723 |
|
|---|
| 724 | <td>0=>Audible, 1=>Mute</td>
|
|---|
| 725 | </tr>
|
|---|
| 726 |
|
|---|
| 727 | <tr>
|
|---|
| 728 | <td>Left</td>
|
|---|
| 729 |
|
|---|
| 730 | <td>Left volume range 0..100</td>
|
|---|
| 731 | </tr>
|
|---|
| 732 |
|
|---|
| 733 | <tr>
|
|---|
| 734 | <td>Right</td>
|
|---|
| 735 |
|
|---|
| 736 | <td>Right volume range 0..100</td>
|
|---|
| 737 | </tr>
|
|---|
| 738 | </table>
|
|---|
| 739 |
|
|---|
| 740 | <p><font color="#3333FF">Connection</font>:
|
|---|
| 741 | <br>This IOCTL sets the listening level of the system microphone.
|
|---|
| 742 | System microphone is normally muted.
|
|---|
| 743 | <br>It can be un-muted to enable karoke mode.
|
|---|
| 744 | <p>Note: This IOCTL does not effect the record level for microphone.
|
|---|
| 745 | <br>
|
|---|
| 746 | <p><u><font size=+1>63 - LineQuery</font></u>
|
|---|
| 747 | <br>Query volume of system Line-In connection
|
|---|
| 748 | <p><font color="#009900">Introduced:</font> API Level 1
|
|---|
| 749 | <p>Parameters (PMIXSTRUCT).
|
|---|
| 750 | <br>
|
|---|
| 751 | <table BORDER COLS=2 WIDTH="52%" >
|
|---|
| 752 | <tr>
|
|---|
| 753 | <td>Mute</td>
|
|---|
| 754 |
|
|---|
| 755 | <td>0=>Audible, 1=>Mute</td>
|
|---|
| 756 | </tr>
|
|---|
| 757 |
|
|---|
| 758 | <tr>
|
|---|
| 759 | <td>Left</td>
|
|---|
| 760 |
|
|---|
| 761 | <td>Left volume range 0..100</td>
|
|---|
| 762 | </tr>
|
|---|
| 763 |
|
|---|
| 764 | <tr>
|
|---|
| 765 | <td>Right</td>
|
|---|
| 766 |
|
|---|
| 767 | <td>Right volume range 0..100</td>
|
|---|
| 768 | </tr>
|
|---|
| 769 | </table>
|
|---|
| 770 |
|
|---|
| 771 | <p><font color="#3333FF">Connection</font>:
|
|---|
| 772 | <br>Line-In is normally an input on the system sound card - on the back
|
|---|
| 773 | of the PC system unit.
|
|---|
| 774 | <br>
|
|---|
| 775 | <p><u><font size=+1>64 - CDQuery</font></u>
|
|---|
| 776 | <br>Query the listening level of the CD-ROM analog signal input to the
|
|---|
| 777 | audio device.
|
|---|
| 778 | <p><font color="#009900">Introduced:</font> API Level 1
|
|---|
| 779 | <p>Parameters (PMIXSTRUCT).
|
|---|
| 780 | <br>
|
|---|
| 781 | <table BORDER COLS=2 WIDTH="53%" >
|
|---|
| 782 | <tr>
|
|---|
| 783 | <td>Mute</td>
|
|---|
| 784 |
|
|---|
| 785 | <td>0=>Audible, 1=>Mute</td>
|
|---|
| 786 | </tr>
|
|---|
| 787 |
|
|---|
| 788 | <tr>
|
|---|
| 789 | <td>Left</td>
|
|---|
| 790 |
|
|---|
| 791 | <td>Left volume range 0..100</td>
|
|---|
| 792 | </tr>
|
|---|
| 793 |
|
|---|
| 794 | <tr>
|
|---|
| 795 | <td>Right</td>
|
|---|
| 796 |
|
|---|
| 797 | <td>Right volume range 0..100</td>
|
|---|
| 798 | </tr>
|
|---|
| 799 | </table>
|
|---|
| 800 |
|
|---|
| 801 | <p><font color="#3333FF">Connection</font>:
|
|---|
| 802 | <br>CD-ROM input to sound card volume is controlled with this API.
|
|---|
| 803 | <p>If CD-DA digital streaming is being used, the sound card views the CD
|
|---|
| 804 | data as wave-out. That is, this API will not effect CD-ROM
|
|---|
| 805 | lisenting level if CD-DA digital streaming is being used (CD player application
|
|---|
| 806 | choice).
|
|---|
| 807 | <br>
|
|---|
| 808 | <p><u><font size=+1>65 - VideoQuery</font></u>
|
|---|
| 809 | <br>Query the listening level of the sound card "video" input.
|
|---|
| 810 | <p><font color="#009900">Introduced:</font> API Level 1
|
|---|
| 811 | <p>Parameters (PMIXSTRUCT).
|
|---|
| 812 | <br>
|
|---|
| 813 | <table BORDER COLS=2 WIDTH="53%" >
|
|---|
| 814 | <tr>
|
|---|
| 815 | <td>Mute</td>
|
|---|
| 816 |
|
|---|
| 817 | <td>0=>Audible, 1=>Mute</td>
|
|---|
| 818 | </tr>
|
|---|
| 819 |
|
|---|
| 820 | <tr>
|
|---|
| 821 | <td>Left</td>
|
|---|
| 822 |
|
|---|
| 823 | <td>Left volume range 0..100</td>
|
|---|
| 824 | </tr>
|
|---|
| 825 |
|
|---|
| 826 | <tr>
|
|---|
| 827 | <td>Right</td>
|
|---|
| 828 |
|
|---|
| 829 | <td>Right volume range 0..100</td>
|
|---|
| 830 | </tr>
|
|---|
| 831 | </table>
|
|---|
| 832 |
|
|---|
| 833 | <p><font color="#3333FF">Connection</font>:
|
|---|
| 834 | <br>On equiped systems, effects the lisenting level of movie playback.
|
|---|
| 835 | <br>Most systems do not used this mixer input.
|
|---|
| 836 | <br>
|
|---|
| 837 | <p><u><font size=+1>66 - AuxQuery</font></u>
|
|---|
| 838 | <br>Queries the listening level of the sound card "aux" input.
|
|---|
| 839 | <p><font color="#009900">Introduced:</font> API Level 1
|
|---|
| 840 | <p>Parameters (PMIXSTRUCT).
|
|---|
| 841 | <br>
|
|---|
| 842 | <table BORDER COLS=2 WIDTH="52%" >
|
|---|
| 843 | <tr>
|
|---|
| 844 | <td>Mute</td>
|
|---|
| 845 |
|
|---|
| 846 | <td>0=>Audible, 1=>Mute</td>
|
|---|
| 847 | </tr>
|
|---|
| 848 |
|
|---|
| 849 | <tr>
|
|---|
| 850 | <td>Left</td>
|
|---|
| 851 |
|
|---|
| 852 | <td>Left volume range 0..100</td>
|
|---|
| 853 | </tr>
|
|---|
| 854 |
|
|---|
| 855 | <tr>
|
|---|
| 856 | <td>Right</td>
|
|---|
| 857 |
|
|---|
| 858 | <td>Right volume range 0..100</td>
|
|---|
| 859 | </tr>
|
|---|
| 860 | </table>
|
|---|
| 861 |
|
|---|
| 862 | <p><font color="#3333FF">Connection</font>:
|
|---|
| 863 | <br>On equiped systems, effects the lisenting level of aux input.
|
|---|
| 864 | <br>AC97 systems include an Aux connection that may or may not actually
|
|---|
| 865 | be populated on system.
|
|---|
| 866 | <br>Most ISA devices do not include an Aux connector.
|
|---|
| 867 | <p><u><font size=+1>6C - ThreeDQuery</font></u>
|
|---|
| 868 | <br>Queries 3D sound effect. Popular algorithms include SRS and QSOUND.
|
|---|
| 869 | <p><font color="#009900">Introduced:</font> API Level 1
|
|---|
| 870 | <p>Parameters (PMIXSTRUCT).
|
|---|
| 871 | <br>
|
|---|
| 872 | <table BORDER COLS=2 WIDTH="67%" >
|
|---|
| 873 | <tr>
|
|---|
| 874 | <td>Mute (flags)</td>
|
|---|
| 875 |
|
|---|
| 876 | <td>D0 = 1 3D Is off (muted)
|
|---|
| 877 | <br>D0 = 0 3D Enabled
|
|---|
| 878 | <br>D1 = Space is supported
|
|---|
| 879 | <br>D2 = Center is supported</td>
|
|---|
| 880 | </tr>
|
|---|
| 881 |
|
|---|
| 882 | <tr>
|
|---|
| 883 | <td>Left (Space)</td>
|
|---|
| 884 |
|
|---|
| 885 | <td>0..100</td>
|
|---|
| 886 | </tr>
|
|---|
| 887 |
|
|---|
| 888 | <tr>
|
|---|
| 889 | <td>Right (Center)</td>
|
|---|
| 890 |
|
|---|
| 891 | <td>0..100</td>
|
|---|
| 892 | </tr>
|
|---|
| 893 | </table>
|
|---|
| 894 |
|
|---|
| 895 | <p>A device driver implementing support for 3D sound effect may or may
|
|---|
| 896 | not
|
|---|
| 897 | <br>support Space and Center. Both are independently programmable
|
|---|
| 898 | items.
|
|---|
| 899 | <br>The device driver will turn on the 0x02 and 0x04 bits to indicate which
|
|---|
| 900 | <br>of the slider options can be implemented in mixer application.
|
|---|
| 901 | <p>The 0x01 bit indicates the current state of 3D effect. If bit
|
|---|
| 902 | is on, 3D is enabled.
|
|---|
| 903 | <p><u><font size=+1>6B - BassTrebleQuery</font></u>
|
|---|
| 904 | <br>Query Bass and Treble settings
|
|---|
| 905 | <p><font color="#009900">Introduced:</font> API Level 1
|
|---|
| 906 | <p>Parameters (PMIXSTRUCT).
|
|---|
| 907 | <br>
|
|---|
| 908 | <table BORDER COLS=2 WIDTH="52%" >
|
|---|
| 909 | <tr>
|
|---|
| 910 | <td>Mute (flags)</td>
|
|---|
| 911 |
|
|---|
| 912 | <td>0x0001 - Bass is supported
|
|---|
| 913 | <br>0x0002 - Treble supported</td>
|
|---|
| 914 | </tr>
|
|---|
| 915 |
|
|---|
| 916 | <tr>
|
|---|
| 917 | <td>Left (Bass)</td>
|
|---|
| 918 |
|
|---|
| 919 | <td>0..100</td>
|
|---|
| 920 | </tr>
|
|---|
| 921 |
|
|---|
| 922 | <tr>
|
|---|
| 923 | <td>Right (Treble)</td>
|
|---|
| 924 |
|
|---|
| 925 | <td>0..100</td>
|
|---|
| 926 | </tr>
|
|---|
| 927 | </table>
|
|---|
| 928 |
|
|---|
| 929 | <p><font color="#3333FF">Connection</font>:
|
|---|
| 930 | <br>See the BassTrebleSet API for description for details on Bass and Treble.
|
|---|
| 931 | <p>Device driver returns current setting for Bass and Treble and bit flags
|
|---|
| 932 | <br>indicating which Bass/Treble adjustements are supported by the device.
|
|---|
| 933 | <p>If either Bass or Treble is not supported, the matching bit in the flags
|
|---|
| 934 | <br>will be off and the Left/Right field of the returned parm will be 0.
|
|---|
| 935 | <p>A device driver implementing this Ioctl must support at least
|
|---|
| 936 | <br>one of the adjustable settings (Bass/Treble).
|
|---|
| 937 | <p><u><font size=+1>6D - StreamVolQuery</font></u>
|
|---|
| 938 | <br>Query the global stream volume.
|
|---|
| 939 | <p>See function 4D (StreamVolSet) for a detailed description of this APIs
|
|---|
| 940 | behavior.
|
|---|
| 941 | <p><font color="#009900">Introduced:</font> API Level 2
|
|---|
| 942 | <p>Parameters (PMIXSTRUCT).
|
|---|
| 943 | <br>
|
|---|
| 944 | <table BORDER COLS=2 WIDTH="52%" >
|
|---|
| 945 | <tr>
|
|---|
| 946 | <td>Mute (flags)</td>
|
|---|
| 947 |
|
|---|
| 948 | <td>0x0001=>Mute 0x0002=>Release</td>
|
|---|
| 949 | </tr>
|
|---|
| 950 |
|
|---|
| 951 | <tr>
|
|---|
| 952 | <td>Left</td>
|
|---|
| 953 |
|
|---|
| 954 | <td>Left volume range 0..100</td>
|
|---|
| 955 | </tr>
|
|---|
| 956 |
|
|---|
| 957 | <tr>
|
|---|
| 958 | <td>Right</td>
|
|---|
| 959 |
|
|---|
| 960 | <td>Right volume range 0..100</td>
|
|---|
| 961 | </tr>
|
|---|
| 962 | </table>
|
|---|
| 963 |
|
|---|
| 964 | <p><u>API Level 2:</u>
|
|---|
| 965 | <br>The Mute field is a bit mask (flags).
|
|---|
| 966 | <br>Bit 0x00000001 - If true, then stream volume is muted.
|
|---|
| 967 | <br>Bit 0x00000002 - If true, then stream volume is "released" to
|
|---|
| 968 | MMPM/2 control.
|
|---|
| 969 | <p><font color="#3333FF">Notes</font>:
|
|---|
| 970 | <br>The values returned are dependent on who controls the record gain.
|
|---|
| 971 | <br>If under MMPM/2 control (mixer has released), then the mute and volume
|
|---|
| 972 | <br>levels returned reflect the most recent value programmed from MMPM/2.
|
|---|
| 973 | <p>If mixer application is controlling the setting, then the values returned
|
|---|
| 974 | <br>for mute and volume are the most recent values sent via function 4F.
|
|---|
| 975 | <br>Note, the values returned may reflect the values sent from a different
|
|---|
| 976 | <br>mixer application (multiple mixer clients).
|
|---|
| 977 | <p><u><font size=+1>6E - RecordSrcQuery</font></u>
|
|---|
| 978 | <br>Query global record source.
|
|---|
| 979 | <p><font color="#009900">Introduced:</font> API Level 2
|
|---|
| 980 | <p>Parameters (PMIXSTRUCT).
|
|---|
| 981 | <br>
|
|---|
| 982 | <table BORDER COLS=2 WIDTH="52%" >
|
|---|
| 983 | <tr>
|
|---|
| 984 | <td>Mute (Flags)</td>
|
|---|
| 985 |
|
|---|
| 986 | <td>0x0001=>Reserved
|
|---|
| 987 | <br>0x0002=>Release
|
|---|
| 988 | <br>0x0004=>Input mixer</td>
|
|---|
| 989 | </tr>
|
|---|
| 990 |
|
|---|
| 991 | <tr>
|
|---|
| 992 | <td>Left</td>
|
|---|
| 993 |
|
|---|
| 994 | <td>Record Source</td>
|
|---|
| 995 | </tr>
|
|---|
| 996 |
|
|---|
| 997 | <tr>
|
|---|
| 998 | <td>Right</td>
|
|---|
| 999 |
|
|---|
| 1000 | <td>Not used, set to 0</td>
|
|---|
| 1001 | </tr>
|
|---|
| 1002 | </table>
|
|---|
| 1003 |
|
|---|
| 1004 | <p><font color="#3333FF">See function 4E for definition of record sources.</font>
|
|---|
| 1005 | <p>The record source value returned is dependent on who controls the record
|
|---|
| 1006 | source.
|
|---|
| 1007 | <p>Bit D1 will be set in the flags field to let the mixer application know
|
|---|
| 1008 | <br>if record source definition is global (0) or MMPM/2 per-stream (1).
|
|---|
| 1009 | <p>Bit D2 will be set in the flags field to indicate that the device supports
|
|---|
| 1010 | an
|
|---|
| 1011 | <br>input mixer rather than the AC97 standard input mux.
|
|---|
| 1012 | <p>If under MMPM/2 control (mixer has released), then
|
|---|
| 1013 | <br>1) The record source is a per-stream concept.
|
|---|
| 1014 | <br>2) The record source returned represents the record source most recently
|
|---|
| 1015 | <br> set by MMPM/2. This allows the mixer application
|
|---|
| 1016 | to initialize its record
|
|---|
| 1017 | <br> source to the record source most recently programmed
|
|---|
| 1018 | by MMPM/2.
|
|---|
| 1019 | <p>If mixer application controls record source, then
|
|---|
| 1020 | <br>1) Record source is a global concept
|
|---|
| 1021 | <br>2) Record source may actually be multiple sources (if input mixer)
|
|---|
| 1022 | <br>3) Record source returned represents the record source most recently
|
|---|
| 1023 | <br> sent via function 4F.
|
|---|
| 1024 | <p>Note, the value returned may reflect the value sent from a different
|
|---|
| 1025 | <br>mixer application (multiple mixer clients).
|
|---|
| 1026 | <br>
|
|---|
| 1027 | <p><u><font size=+1>6F - RecordGainQuery</font></u>
|
|---|
| 1028 | <br>Query the global record gain level.
|
|---|
| 1029 | <p>See function 4F (RecordGainSet) for a detailed description of this APIs
|
|---|
| 1030 | behavior.
|
|---|
| 1031 | <p><font color="#009900">Introduced:</font> API Level 1. Enhanced
|
|---|
| 1032 | in API Level 2.
|
|---|
| 1033 | <p><u>In API Level 1</u>
|
|---|
| 1034 | <br>If the device driver has never received API call 4F, this IOCTL will
|
|---|
| 1035 | return
|
|---|
| 1036 | <br>the gain level most recently sent by MMPM/2 for per-stream volume.
|
|---|
| 1037 | <br>This technique can be useful to initialize the value of the record
|
|---|
| 1038 | gain slider to
|
|---|
| 1039 | <br>the volume that is presently in effect per definition from MMPM/2.
|
|---|
| 1040 | <p>Once function 4F has been sent, this API returns the record gain level
|
|---|
| 1041 | most recently set via function 4F.
|
|---|
| 1042 | <p><u>In API Level 2</u>
|
|---|
| 1043 | <br>The values returned are dependent on who controls the record gain.
|
|---|
| 1044 | <br>If under MMPM/2 control (mixer has released), then the mute and volume
|
|---|
| 1045 | <br>levels returned reflect the most recent value programmed from MMPM/2.
|
|---|
| 1046 | <p>If mixer application is controlling the setting, then the values returned
|
|---|
| 1047 | <br>for mute and volume are the most recent values sent via function 4F.
|
|---|
| 1048 | <br>Note, the values returned may reflect the values sent from a different
|
|---|
| 1049 | <br>mixer application (multiple mixer clients).
|
|---|
| 1050 | <p>Parameters (PMIXSTRUCT).
|
|---|
| 1051 | <br>
|
|---|
| 1052 | <table BORDER COLS=2 WIDTH="52%" >
|
|---|
| 1053 | <tr>
|
|---|
| 1054 | <td>Mute (flags)</td>
|
|---|
| 1055 |
|
|---|
| 1056 | <td>0x0001=>Mute 0x0002=>Release</td>
|
|---|
| 1057 | </tr>
|
|---|
| 1058 |
|
|---|
| 1059 | <tr>
|
|---|
| 1060 | <td>Left</td>
|
|---|
| 1061 |
|
|---|
| 1062 | <td>Left volume range 0..100</td>
|
|---|
| 1063 | </tr>
|
|---|
| 1064 |
|
|---|
| 1065 | <tr>
|
|---|
| 1066 | <td>Right</td>
|
|---|
| 1067 |
|
|---|
| 1068 | <td>Not used, PDD will set to 0</td>
|
|---|
| 1069 | </tr>
|
|---|
| 1070 | </table>
|
|---|
| 1071 |
|
|---|
| 1072 | <p><font color="#3333FF">Connection</font>:
|
|---|
| 1073 | <br>Reads the record gain setting just before the Analog/Digital converter
|
|---|
| 1074 | inside the AC97 mixer.
|
|---|
| 1075 | <br>This API effects what you "record", not what you "hear".
|
|---|
| 1076 | <p><u>In API Level 1:</u>
|
|---|
| 1077 | <br>The Mute field is a boolean. If true, then record gain is muted.
|
|---|
| 1078 | <p><u>In API Level 2:</u>
|
|---|
| 1079 | <br>The Mute field is a bit mask (flags).
|
|---|
| 1080 | <br>Bit 0x00000001 - If true, then record gain is muted.
|
|---|
| 1081 | <br>Bit 0x00000002 - If true, then record gain is "released" to MMPM/2
|
|---|
| 1082 | control.
|
|---|
| 1083 | <p><u><font size=+1>80 - ApiLevelQuery</font></u>
|
|---|
| 1084 | <br>In first release, this function returns a ULONG, 0x00000001.
|
|---|
| 1085 | <br>As significant changes are made to the Category 90 mixer API, the return
|
|---|
| 1086 | value
|
|---|
| 1087 | <br>of this function will be incremented.
|
|---|
| 1088 | <p>In current specification, audio device drivers should return 2.
|
|---|
| 1089 | <p><font color="#009900">Introduced:</font> API Level 1
|
|---|
| 1090 | <p>Parameters (PULONG).
|
|---|
| 1091 | <br>
|
|---|
| 1092 | <table BORDER COLS=2 WIDTH="52%" >
|
|---|
| 1093 | <tr>
|
|---|
| 1094 | <td>ulAPILevel</td>
|
|---|
| 1095 |
|
|---|
| 1096 | <td>Driver returns level supported</td>
|
|---|
| 1097 | </tr>
|
|---|
| 1098 | </table>
|
|---|
| 1099 |
|
|---|
| 1100 | <p>API Level Functions Map - Where label omitted, API level is 1
|
|---|
| 1101 | <table BORDER COLS=2 WIDTH="69%" >
|
|---|
| 1102 | <tr>
|
|---|
| 1103 | <td>40 - MonoInSet</td>
|
|---|
| 1104 |
|
|---|
| 1105 | <td>60 - MonoInQuery</td>
|
|---|
| 1106 | </tr>
|
|---|
| 1107 |
|
|---|
| 1108 | <tr>
|
|---|
| 1109 | <td>41 - PhoneSet</td>
|
|---|
| 1110 |
|
|---|
| 1111 | <td>61 - PhoneQuery</td>
|
|---|
| 1112 | </tr>
|
|---|
| 1113 |
|
|---|
| 1114 | <tr>
|
|---|
| 1115 | <td>42 - MicSet</td>
|
|---|
| 1116 |
|
|---|
| 1117 | <td>62 - MicQuery</td>
|
|---|
| 1118 | </tr>
|
|---|
| 1119 |
|
|---|
| 1120 | <tr>
|
|---|
| 1121 | <td>43 - LineSet</td>
|
|---|
| 1122 |
|
|---|
| 1123 | <td>63 - LineQuery</td>
|
|---|
| 1124 | </tr>
|
|---|
| 1125 |
|
|---|
| 1126 | <tr>
|
|---|
| 1127 | <td>44 - CDSet</td>
|
|---|
| 1128 |
|
|---|
| 1129 | <td>64 - CDQuery</td>
|
|---|
| 1130 | </tr>
|
|---|
| 1131 |
|
|---|
| 1132 | <tr>
|
|---|
| 1133 | <td>45 - VideoSet</td>
|
|---|
| 1134 |
|
|---|
| 1135 | <td>65 - VideoQuery</td>
|
|---|
| 1136 | </tr>
|
|---|
| 1137 |
|
|---|
| 1138 | <tr>
|
|---|
| 1139 | <td>46 - AuxSet</td>
|
|---|
| 1140 |
|
|---|
| 1141 | <td>66 - AuxQuery</td>
|
|---|
| 1142 | </tr>
|
|---|
| 1143 |
|
|---|
| 1144 | <tr>
|
|---|
| 1145 | <td>4B - BassTrebleSet</td>
|
|---|
| 1146 |
|
|---|
| 1147 | <td>6B - BassTrebleQuery</td>
|
|---|
| 1148 | </tr>
|
|---|
| 1149 |
|
|---|
| 1150 | <tr>
|
|---|
| 1151 | <td>4C - ThreeDSet</td>
|
|---|
| 1152 |
|
|---|
| 1153 | <td>6C - ThreeDQuery</td>
|
|---|
| 1154 | </tr>
|
|---|
| 1155 |
|
|---|
| 1156 | <tr>
|
|---|
| 1157 | <td>4D - StreamVolSet (2)</td>
|
|---|
| 1158 |
|
|---|
| 1159 | <td>6D - StreamVolQuery (2)</td>
|
|---|
| 1160 | </tr>
|
|---|
| 1161 |
|
|---|
| 1162 | <tr>
|
|---|
| 1163 | <td>4E - RecordSrcSet (2)</td>
|
|---|
| 1164 |
|
|---|
| 1165 | <td>6E - RecordSrcQuery (2)</td>
|
|---|
| 1166 | </tr>
|
|---|
| 1167 |
|
|---|
| 1168 | <tr>
|
|---|
| 1169 | <td>4F - RecordGainSet (1,2)</td>
|
|---|
| 1170 |
|
|---|
| 1171 | <td>4F - RecordGainQuery (1,2)</td>
|
|---|
| 1172 | </tr>
|
|---|
| 1173 |
|
|---|
| 1174 | <tr>
|
|---|
| 1175 | <td>80 - ApiLevelQuery</td>
|
|---|
| 1176 |
|
|---|
| 1177 | <td></td>
|
|---|
| 1178 | </tr>
|
|---|
| 1179 |
|
|---|
| 1180 | <tr>
|
|---|
| 1181 | <td>81 - GetApiMap</td>
|
|---|
| 1182 |
|
|---|
| 1183 | <td></td>
|
|---|
| 1184 | </tr>
|
|---|
| 1185 |
|
|---|
| 1186 | <tr>
|
|---|
| 1187 | <td>82 - CallbackReg</td>
|
|---|
| 1188 |
|
|---|
| 1189 | <td></td>
|
|---|
| 1190 | </tr>
|
|---|
| 1191 |
|
|---|
| 1192 | <tr>
|
|---|
| 1193 | <td>83 - MsgBuf</td>
|
|---|
| 1194 |
|
|---|
| 1195 | <td></td>
|
|---|
| 1196 | </tr>
|
|---|
| 1197 | </table>
|
|---|
| 1198 |
|
|---|
| 1199 | <p>Differences from original API definition result in increment of the
|
|---|
| 1200 | API level.
|
|---|
| 1201 | <p>The table above uses this convention.
|
|---|
| 1202 | <br>With no notation, API level 1 is assumed. API level 1 means that
|
|---|
| 1203 | if the API is
|
|---|
| 1204 | <br>listed in the API support map, it is implemented by the device driver.
|
|---|
| 1205 | <p>New API level 1 IOCTLs can be added even after later API levels are
|
|---|
| 1206 | defined.
|
|---|
| 1207 | <p>The API level is used to describe differences in definition of an IOCTL.
|
|---|
| 1208 | <br>These differences are noted in the table and are documented below and
|
|---|
| 1209 | <br>in the documentation for each IOCTL.
|
|---|
| 1210 | <p><b>(1,2)</b>
|
|---|
| 1211 | <br>The RecordGainSet API differs in behavior on API levels 1 and 2.
|
|---|
| 1212 | <br>In API level 1, once the mixer application forces an override of record
|
|---|
| 1213 | <br>gain, control of record gain is forever in the domain of the mixer
|
|---|
| 1214 | application.
|
|---|
| 1215 | <br>This is enhanced in API level 2 where the mixer application can return
|
|---|
| 1216 | <br>record gain to be a per-stream concept as defined by MMPM/2.
|
|---|
| 1217 | <p><b>(2)</b>
|
|---|
| 1218 | <br>A device driver implementing StreamVolSet API is expected to return
|
|---|
| 1219 | <br>API level 2 or greater. This API follows programming convention
|
|---|
| 1220 | of
|
|---|
| 1221 | <br>the level 2 implementation of RecordGainSet.
|
|---|
| 1222 | <p><u><font size=+1>81 - GetApiMap</font></u>
|
|---|
| 1223 | <br>Device driver fills in an application memory buffer (256 bytes) with
|
|---|
| 1224 | BYTE size booleans representing which of the possible 256 IOCTL functions
|
|---|
| 1225 | that the device driver implements.
|
|---|
| 1226 | <p><font color="#009900">Introduced:</font> API Level 1
|
|---|
| 1227 | <p>This API can be used to identify mixer components that do not apply
|
|---|
| 1228 | for the particular hardware.
|
|---|
| 1229 | <p>For example, the Crystal Semiconductor PCI driver set implements the
|
|---|
| 1230 | full AC97 defined mixer interface.
|
|---|
| 1231 | <br>The Crystal Semiconductor ISA driver however does not implement "Video"
|
|---|
| 1232 | or "Phone" volume as
|
|---|
| 1233 | <br>these are concepts which are alien to the ISA hardware.
|
|---|
| 1234 | <p>Notice that the buffer returned is 256 bytes while it is only possible
|
|---|
| 1235 | for an application to send 192 IOCTL functions (IOCTL API requires that
|
|---|
| 1236 | function be >= 0x40). Wasting these 64 bytes of memory
|
|---|
| 1237 | allows the application to index the array using the IOCTL number rather
|
|---|
| 1238 | than IOCTO function number less 0x40.
|
|---|
| 1239 | <p><u><font size=+1>82 - CallbackReg</font></u>
|
|---|
| 1240 | <br>Application provides handle to shared event semaphore.
|
|---|
| 1241 | <p><font color="#009900">Introduced:</font> API Level 1
|
|---|
| 1242 | <p>Parameters (HEV).
|
|---|
| 1243 | <p>Application provides event semaphore handle to audio device driver.
|
|---|
| 1244 | <p>This API is designed to let multiple mixer applications execute concurrently
|
|---|
| 1245 | with sliders that "track".
|
|---|
| 1246 | <br>Application is responsible for creating the event semahore.
|
|---|
| 1247 | <p>When a mixer component state changes, the device driver posts the event
|
|---|
| 1248 | semaphore which
|
|---|
| 1249 | <br>wakes up an application thread that is blocked on the semaphore.
|
|---|
| 1250 | The application should
|
|---|
| 1251 | <br>then issue query APIs to read the current state of the mixer.
|
|---|
| 1252 | <p>This API is implemented in Crystal Semiconductor PCI driver set 3.04
|
|---|
| 1253 | and ISA 2.09.
|
|---|
| 1254 | <p>Example code
|
|---|
| 1255 | <br><tt><font color="#009900"> HEV hevCallback;</font></tt>
|
|---|
| 1256 | <br><tt><font color="#009900"> ulRC = DosCreateEventSem (NULL, &hevCallback,
|
|---|
| 1257 | DC_SEM_SHARED, FALSE);</font></tt>
|
|---|
| 1258 | <br><tt><font color="#009900"> if (ulRC != 0)</font></tt>
|
|---|
| 1259 | <br><tt><font color="#009900"> {</font></tt>
|
|---|
| 1260 | <br><tt><font color="#009900"> printf ("mixerapiInit
|
|---|
| 1261 | - CreateSem failed\n");</font></tt>
|
|---|
| 1262 | <br><tt><font color="#009900"> hevCallback = NULL;</font></tt>
|
|---|
| 1263 | <br><tt><font color="#009900"> }</font></tt>
|
|---|
| 1264 | <br><tt><font color="#009900"> else</font></tt>
|
|---|
| 1265 | <br><tt><font color="#009900"> {</font></tt>
|
|---|
| 1266 | <br><tt><font color="#009900"> fCallbackThreadAlive
|
|---|
| 1267 | = TRUE;</font></tt>
|
|---|
| 1268 | <br><tt><font color="#009900"> if (_beginthread
|
|---|
| 1269 | (CallbackThreadFunc, NULL, 32*1024, NULL) == -1)</font></tt>
|
|---|
| 1270 | <br><tt><font color="#009900"> {</font></tt>
|
|---|
| 1271 | <br><tt><font color="#009900">
|
|---|
| 1272 | printf ("mixerapiInit - callback thread create failed\n");</font></tt>
|
|---|
| 1273 | <br><tt><font color="#009900">
|
|---|
| 1274 | CallbackFunc = NULL;</font></tt>
|
|---|
| 1275 | <br><tt><font color="#009900">
|
|---|
| 1276 | fCallbackThreadAlive = FALSE;</font></tt>
|
|---|
| 1277 | <br><tt><font color="#009900">
|
|---|
| 1278 | ulRC = 1;</font></tt>
|
|---|
| 1279 | <br><tt><font color="#009900"> }</font></tt>
|
|---|
| 1280 | <br><tt><font color="#009900"> }</font></tt>
|
|---|
| 1281 | <br><tt><font color="#009900"> ulRC = mixerapiIOCTL90 (CALLBACKREG,
|
|---|
| 1282 | &hevCallback, sizeof(hevCallback));</font></tt>
|
|---|
| 1283 | <p>When the mixer application terminates or otherwise closes the semaphore,
|
|---|
| 1284 | it should
|
|---|
| 1285 | <br>contact the audio PDD to de-register. De-register is done by
|
|---|
| 1286 | registering a NULL semaphore.
|
|---|
| 1287 | <p>Example code
|
|---|
| 1288 | <br><tt><font color="#009900"> ulZero = 0;</font></tt>
|
|---|
| 1289 | <br><tt><font color="#009900"> ulRC = mixerapiIOCTL90 (CALLBACKREG,
|
|---|
| 1290 | &ulZero, sizeof(ulZero));</font></tt>
|
|---|
| 1291 | <br><tt><font color="#009900"> ulRC = DosCloseEventSem (hsemCallback);</font></tt>
|
|---|
| 1292 | <br><tt><font color="#009900"> hsemCallback = NULL;</font></tt>
|
|---|
| 1293 | <p><u><font size=+1>83 - MsgBuf</font></u>
|
|---|
| 1294 | <br>Device driver fills in an application memory buffer with characters
|
|---|
| 1295 | displayed during boot
|
|---|
| 1296 | <br>and any strings displayed by device driver for debug or problem diagnosis
|
|---|
| 1297 | in the field.
|
|---|
| 1298 | <p><font color="#009900">Introduced:</font> API Level 1
|
|---|
| 1299 | <p>Parameters (PMSGBUF).
|
|---|
| 1300 | <p><tt>typedef struct</tt>
|
|---|
| 1301 | <br><tt>{</tt>
|
|---|
| 1302 | <br><tt> ULONG pBuffer; // Application
|
|---|
| 1303 | linear address to message buffer (in)</tt>
|
|---|
| 1304 | <br><tt> ULONG ulSize; // Size
|
|---|
| 1305 | of buffer (in). Count of chars (out).</tt>
|
|---|
| 1306 | <br><tt> ULONG fClear; // PDD
|
|---|
| 1307 | should clear buffer after copy (in)</tt>
|
|---|
| 1308 | <br><tt> ULONG fError; // Message
|
|---|
| 1309 | buffer includes error message (out)</tt>
|
|---|
| 1310 | <br><tt> ULONG fNewInfo; // Message buffer
|
|---|
| 1311 | has new text since last read (out)</tt>
|
|---|
| 1312 | <br><tt> ULONG ulCharsLost; // Messages lost - circular queue
|
|---|
| 1313 | wrap around (out)</tt>
|
|---|
| 1314 | <br><tt>} MIXMSGBUF, *PMIXMSGBUF;</tt>
|
|---|
| 1315 | <p>Application should pass NULL buffer on first call.
|
|---|
| 1316 | <br>Device driver will set ulSize field to the maximum possible size of
|
|---|
| 1317 | returned buffer
|
|---|
| 1318 | <br>and will set the boolean return values to indicate what information
|
|---|
| 1319 | is in the buffer.
|
|---|
| 1320 | <p>Application should then malloc that much memory and call device driver
|
|---|
| 1321 | to retrieve
|
|---|
| 1322 | <br>message text.
|
|---|
| 1323 | <p>If pBuffer points to invalid memory, the application will fail with
|
|---|
| 1324 | access violation.
|
|---|
| 1325 | <p>fError and ulCharsLost are clearned when buffer is cleared.
|
|---|
| 1326 | <br>fNewInfo is cleared on each buffer read where pBuffer is not NULL.
|
|---|
| 1327 | <p>When new message text is added to the buffer, the device driver posts
|
|---|
| 1328 | <br>the callback semaphore.
|
|---|
| 1329 | <p>
|
|---|
| 1330 | <hr WIDTH="100%">
|
|---|
| 1331 | <br>Useful prototypes (header file)
|
|---|
| 1332 | <p>// This structure is passed to the device driver using DosDevIOCTL.
|
|---|
| 1333 | <br><tt>typedef struct</tt>
|
|---|
| 1334 | <br><tt>{</tt>
|
|---|
| 1335 | <br><tt> ULONG Mute;
|
|---|
| 1336 | // UnMute==0, Mute==1</tt>
|
|---|
| 1337 | <br><tt> ULONG VolumeL;
|
|---|
| 1338 | // 0..100 percent</tt>
|
|---|
| 1339 | <br><tt> ULONG VolumeR;
|
|---|
| 1340 | // 0..100 percent</tt>
|
|---|
| 1341 | <br><tt>} MIXSTRUCT, *PMIXSTRUCT;</tt>
|
|---|
| 1342 | <p><tt>#define MONOINSET 0x40
|
|---|
| 1343 | // SET functions in the 0x40 range</tt>
|
|---|
| 1344 | <br><tt>#define PHONESET 0x41</tt>
|
|---|
| 1345 | <br><tt>#define MICSET
|
|---|
| 1346 | 0x42</tt>
|
|---|
| 1347 | <br><tt>#define LINESET
|
|---|
| 1348 | 0x43</tt>
|
|---|
| 1349 | <br><tt>#define CDSET
|
|---|
| 1350 | 0x44</tt>
|
|---|
| 1351 | <br><tt>#define VIDEOSET 0x45</tt>
|
|---|
| 1352 | <br><tt>#define AUXSET
|
|---|
| 1353 | 0x46</tt>
|
|---|
| 1354 | <br><tt>#define BASSTREBLESET 0x4B</tt>
|
|---|
| 1355 | <br><tt>#define THREEDSET 0x4C</tt>
|
|---|
| 1356 | <br><tt>#define STREAMVOLSET 0x4D</tt>
|
|---|
| 1357 | <br><tt>#define RECORDSRCSET 0x4E</tt>
|
|---|
| 1358 | <br><tt>#define RECORDGAINSET 0x4F</tt>
|
|---|
| 1359 | <p><tt>#define MONOINQUERY 0x60
|
|---|
| 1360 | // QUERY functions in the 0x60 range</tt>
|
|---|
| 1361 | <br><tt>#define PHONEQUERY 0x61</tt>
|
|---|
| 1362 | <br><tt>#define MICQUERY 0x62</tt>
|
|---|
| 1363 | <br><tt>#define LINEQUERY 0x63</tt>
|
|---|
| 1364 | <br><tt>#define CDQUERY
|
|---|
| 1365 | 0x64</tt>
|
|---|
| 1366 | <br><tt>#define VIDEOQUERY 0x65</tt>
|
|---|
| 1367 | <br><tt>#define AUXQUERY 0x66</tt>
|
|---|
| 1368 | <br><tt>#define BASSTREBLEQUERY 0x6B</tt>
|
|---|
| 1369 | <br><tt>#define THREEDQUERY 0x6C</tt>
|
|---|
| 1370 | <br><tt>#define STREAMVOLQUERY 0x4D</tt>
|
|---|
| 1371 | <br><tt>#define RECORDSRCQUERY 0x4E</tt>
|
|---|
| 1372 | <br><tt>#define RECORDGAINQUERY 0x4F</tt>
|
|---|
| 1373 | <br><tt>#define APILEVELQUERY 0x80</tt>
|
|---|
| 1374 | <br><tt>#define GETAPIMAP 0x81
|
|---|
| 1375 | // Get 256 byte BOOL list of supported IOCTLs</tt>
|
|---|
| 1376 | <br><tt>#define CALLBACKREG 0x82
|
|---|
| 1377 | // Provide HSEM for mixer change callbacks</tt>
|
|---|
| 1378 | <br><tt>#define MSGBUF
|
|---|
| 1379 | 0x83 // Get PDD error log message buffer</tt>
|
|---|
| 1380 | <p>
|
|---|
| 1381 | <hr WIDTH="100%">
|
|---|
| 1382 | <br><font color="#3333FF"><font size=+1>Example Query PDD Name:</font></font>
|
|---|
| 1383 | <p>The application will query the 8 character device driver name by calling
|
|---|
| 1384 | MMPM/2 MCI APIs to get the PDD name for the "WaveAudio" MCI device.
|
|---|
| 1385 | Application should then issue DosOpen on the device name and finally DosDevIOCTL
|
|---|
| 1386 | to perform mixer operations.
|
|---|
| 1387 | <p>NOTE: The device driver names used by Crystal Semiconductor device drivers
|
|---|
| 1388 | DO change and are not guaranteed to remain the same for any given release.
|
|---|
| 1389 | USE the availalbe MMPM/2 APIs!
|
|---|
| 1390 | <p><tt>//</tt>
|
|---|
| 1391 | <br><tt>// OS/2 32-bit program to query the Physical Device Driver name</tt>
|
|---|
| 1392 | <br><tt>// for the default MMPM/2 WaveAudio device. Joe Nord 10-Mar-1999</tt>
|
|---|
| 1393 | <br><tt>//</tt>
|
|---|
| 1394 | <p><tt>#include <stdlib.h></tt>
|
|---|
| 1395 | <br><tt>#include <stdio.h></tt>
|
|---|
| 1396 | <br><tt>#include <string.h></tt>
|
|---|
| 1397 | <p><tt>#include <os2.h></tt>
|
|---|
| 1398 | <p><tt>#define INCL_OS2MM</tt>
|
|---|
| 1399 | <br><tt>#include <os2me.h></tt>
|
|---|
| 1400 | <p><tt>ULONG GetAudioPDDName (char *pszPDDName)</tt>
|
|---|
| 1401 | <br><tt>{</tt>
|
|---|
| 1402 | <br><tt> ULONG
|
|---|
| 1403 | ulRC;</tt>
|
|---|
| 1404 | <br><tt> char
|
|---|
| 1405 | szAmpMix[9] = "AMPMIX01";</tt>
|
|---|
| 1406 | <p><tt> MCI_SYSINFO_PARMS
|
|---|
| 1407 | SysInfo;</tt>
|
|---|
| 1408 | <br><tt> MCI_SYSINFO_LOGDEVICE SysInfoParm;</tt>
|
|---|
| 1409 | <br><tt> MCI_SYSINFO_QUERY_NAME QueryNameParm;</tt>
|
|---|
| 1410 | <p><tt> memset (&SysInfo, '\0', sizeof(SysInfo));</tt>
|
|---|
| 1411 | <br><tt> memset (&SysInfoParm, '\0', sizeof(SysInfoParm));</tt>
|
|---|
| 1412 | <br><tt> memset (&QueryNameParm, '\0', sizeof(QueryNameParm));</tt>
|
|---|
| 1413 | <p><tt> SysInfo.ulItem
|
|---|
| 1414 | = MCI_SYSINFO_QUERY_NAMES;</tt>
|
|---|
| 1415 | <br><tt> SysInfo.usDeviceType = MCI_DEVTYPE_WAVEFORM_AUDIO;</tt>
|
|---|
| 1416 | <br><tt> SysInfo.pSysInfoParm = &QueryNameParm;</tt>
|
|---|
| 1417 | <p><tt> strcpy (QueryNameParm.szLogicalName, szAmpMix);</tt>
|
|---|
| 1418 | <p><tt> ulRC = mciSendCommand (0,</tt>
|
|---|
| 1419 | <br><tt>
|
|---|
| 1420 | MCI_SYSINFO,</tt>
|
|---|
| 1421 | <br><tt>
|
|---|
| 1422 | MCI_SYSINFO_ITEM | MCI_WAIT,</tt>
|
|---|
| 1423 | <br><tt>
|
|---|
| 1424 | (PVOID) &SysInfo,</tt>
|
|---|
| 1425 | <br><tt>
|
|---|
| 1426 | 0);</tt>
|
|---|
| 1427 | <br><tt> if (ulRC != 0)</tt>
|
|---|
| 1428 | <br><tt> {</tt>
|
|---|
| 1429 | <br><tt> printf ("mciSendCommand ulRC=%u\n",
|
|---|
| 1430 | ulRC);</tt>
|
|---|
| 1431 | <br><tt> return (ulRC);</tt>
|
|---|
| 1432 | <br><tt> }</tt>
|
|---|
| 1433 | <p><tt> // Get PDD associated with our AmpMixer</tt>
|
|---|
| 1434 | <br><tt> // Device name is in pSysInfoParm->szPDDName</tt>
|
|---|
| 1435 | <p><tt> SysInfo.ulItem
|
|---|
| 1436 | = MCI_SYSINFO_QUERY_DRIVER;</tt>
|
|---|
| 1437 | <br><tt> SysInfo.usDeviceType = MCI_DEVTYPE_WAVEFORM_AUDIO;</tt>
|
|---|
| 1438 | <br><tt> SysInfo.pSysInfoParm = &SysInfoParm;</tt>
|
|---|
| 1439 | <p><tt> strcpy (SysInfoParm.szInstallName, QueryNameParm.szInstallName);</tt>
|
|---|
| 1440 | <p><tt> ulRC = mciSendCommand (0,</tt>
|
|---|
| 1441 | <br><tt>
|
|---|
| 1442 | MCI_SYSINFO,</tt>
|
|---|
| 1443 | <br><tt>
|
|---|
| 1444 | MCI_SYSINFO_ITEM | MCI_WAIT,</tt>
|
|---|
| 1445 | <br><tt>
|
|---|
| 1446 | (PVOID) &SysInfo,</tt>
|
|---|
| 1447 | <br><tt>
|
|---|
| 1448 | 0);</tt>
|
|---|
| 1449 | <br><tt> if (ulRC != 0)</tt>
|
|---|
| 1450 | <br><tt> {</tt>
|
|---|
| 1451 | <br><tt> printf ("mciSendCommand ulRC=%u\n",
|
|---|
| 1452 | ulRC);</tt>
|
|---|
| 1453 | <br><tt> return (ulRC);</tt>
|
|---|
| 1454 | <br><tt> }</tt>
|
|---|
| 1455 | <p><tt> strcpy (pszPDDName, SysInfoParm.szPDDName);</tt>
|
|---|
| 1456 | <p><tt> return (ulRC);</tt>
|
|---|
| 1457 | <br><tt>}</tt>
|
|---|
| 1458 | <br>
|
|---|
| 1459 | <p><tt>int main (void)</tt>
|
|---|
| 1460 | <br><tt>{</tt>
|
|---|
| 1461 | <br><tt> ULONG ulRC;</tt>
|
|---|
| 1462 | <br><tt> char szPddName [256];</tt>
|
|---|
| 1463 | <p><tt> ulRC = GetAudioPDDName (&szPddName);</tt>
|
|---|
| 1464 | <br><tt> printf ("GetAudioPDDName ulRC=%u\n", ulRC);</tt>
|
|---|
| 1465 | <br><tt> printf (" PddName=%s\n", szPddName);</tt>
|
|---|
| 1466 | <p><tt> return (0);</tt>
|
|---|
| 1467 | <br><tt>}</tt>
|
|---|
| 1468 | <br>
|
|---|
| 1469 | <p>
|
|---|
| 1470 | <hr WIDTH="100%">
|
|---|
| 1471 | <br><font color="#3333FF"><font size=+1>Example DosOpen:</font></font>
|
|---|
| 1472 | <p>Driver name in call to the open function should include "<b>\\DEV\\</b>"
|
|---|
| 1473 | <br> Example: hPdd = DevOpen ("\\DEV\\BSAUD1$");
|
|---|
| 1474 | or
|
|---|
| 1475 | <br> Example: hPdd = DevOpen ("\\DEV\\CWCAUD1$");
|
|---|
| 1476 | <p><tt>HFILE DevOpen (char *ddName)</tt>
|
|---|
| 1477 | <br><tt>{</tt>
|
|---|
| 1478 | <br><tt> ULONG ulRC;</tt>
|
|---|
| 1479 | <br><tt> ULONG OpenFlags;</tt>
|
|---|
| 1480 | <br><tt> ULONG OpenMode;</tt>
|
|---|
| 1481 | <br><tt> ULONG ulFileSize = 0;</tt>
|
|---|
| 1482 | <br><tt> ULONG ulFileAttribute = 0;</tt>
|
|---|
| 1483 | <br><tt> ULONG ulActionTaken = 0;</tt>
|
|---|
| 1484 | <br><tt> HFILE hPdd
|
|---|
| 1485 | = NULL;</tt>
|
|---|
| 1486 | <p><tt> OpenFlags = OPEN_ACTION_OPEN_IF_EXISTS;
|
|---|
| 1487 | // Do not create file</tt>
|
|---|
| 1488 | <p><tt> OpenMode = OPEN_ACCESS_READWRITE +
|
|---|
| 1489 | // Read/Write file</tt>
|
|---|
| 1490 | <br><tt>
|
|---|
| 1491 | OPEN_SHARE_DENYNONE + //
|
|---|
| 1492 | Non-exclusive access</tt>
|
|---|
| 1493 | <br><tt>
|
|---|
| 1494 | OPEN_FLAGS_FAIL_ON_ERROR; // No system popups on
|
|---|
| 1495 | errors</tt>
|
|---|
| 1496 | <p><tt> ulRC = DosOpen (ddName,
|
|---|
| 1497 | // in</tt>
|
|---|
| 1498 | <br><tt>
|
|---|
| 1499 | &hPdd,
|
|---|
| 1500 | // out (handle)</tt>
|
|---|
| 1501 | <br><tt>
|
|---|
| 1502 | &ulActionTaken, // out</tt>
|
|---|
| 1503 | <br><tt>
|
|---|
| 1504 | ulFileSize, // in</tt>
|
|---|
| 1505 | <br><tt>
|
|---|
| 1506 | ulFileAttribute, // in</tt>
|
|---|
| 1507 | <br><tt>
|
|---|
| 1508 | OpenFlags, // in</tt>
|
|---|
| 1509 | <br><tt>
|
|---|
| 1510 | OpenMode, // in</tt>
|
|---|
| 1511 | <br><tt>
|
|---|
| 1512 | NULL); // in</tt>
|
|---|
| 1513 | <p><tt> printf ("DosOpen RC = %x\n", ulRC);</tt>
|
|---|
| 1514 | <p><tt> if (ulRC != 0)</tt>
|
|---|
| 1515 | <br><tt> hPdd = NULL;</tt>
|
|---|
| 1516 | <p><tt> return (hPdd);</tt>
|
|---|
| 1517 | <br><tt>}</tt>
|
|---|
| 1518 | <p>
|
|---|
| 1519 | <hr WIDTH="100%">
|
|---|
| 1520 | <br><font color="#3333FF"><font size=+1>Example DosDevIOCTL:</font></font>
|
|---|
| 1521 | <p><tt>ULONG SendIOCTL (HFILE hPdd, ULONG ulFunc, PMIXSTRUCT pMix)</tt>
|
|---|
| 1522 | <br><tt>{</tt>
|
|---|
| 1523 | <br><tt> ULONG ulRC;</tt>
|
|---|
| 1524 | <br><tt> ULONG ulSizeOfStruct =
|
|---|
| 1525 | = sizeof (MixStruct);</tt>
|
|---|
| 1526 | <p><tt> ulRC = DosDevIOCtl</tt>
|
|---|
| 1527 | <br><tt> (hPdd,
|
|---|
| 1528 | // Device Handle</tt>
|
|---|
| 1529 | <br><tt> 0x90,
|
|---|
| 1530 | // Category (user defined >= 0x80)</tt>
|
|---|
| 1531 | <br><tt> ulFunc,
|
|---|
| 1532 | // Function Use defines in .H file</tt>
|
|---|
| 1533 | <br><tt> NULL,
|
|---|
| 1534 | // in Address of parm data (not used)</tt>
|
|---|
| 1535 | <br><tt> 0,
|
|---|
| 1536 | // in Max size of parm data structure</tt>
|
|---|
| 1537 | <br><tt> NULL,
|
|---|
| 1538 | // in out Actual size of parm data structure</tt>
|
|---|
| 1539 | <br><tt> pMix,
|
|---|
| 1540 | // in Address of command data</tt>
|
|---|
| 1541 | <br><tt> ulSizeOfStruct,
|
|---|
| 1542 | // in Maximum size of command data</tt>
|
|---|
| 1543 | <br><tt> &ulSizeOfStruct);
|
|---|
| 1544 | // in out Size of command data</tt>
|
|---|
| 1545 | <p><tt> printf ("DosDevIOCtl ulRC = %d\n", ulRC);</tt>
|
|---|
| 1546 | <p><tt> return (ulRC);</tt>
|
|---|
| 1547 | <br><tt>}</tt>
|
|---|
| 1548 | <p>
|
|---|
| 1549 | <hr WIDTH="100%">
|
|---|
| 1550 | <br><font color="#3333FF"><font size=+1>Device Specific Information:</font></font>
|
|---|
| 1551 | <p><font color="#000000">The Ioctl90 API is based on AC97 mixer architecture
|
|---|
| 1552 | (common hardware for PCI bus audio). It does not necessarily exactly
|
|---|
| 1553 | map to other mixer architectures. Where known, differences are documented
|
|---|
| 1554 | below.</font>
|
|---|
| 1555 | <p><tt><font color="#000000">AC97 Definition CS4236B/7B/8B
|
|---|
| 1556 | CS4235/9</font></tt>
|
|---|
| 1557 | <br><tt><font color="#000000">PCI Bus designs ISA Mode 3
|
|---|
| 1558 | ISA Mode 3</font></tt>
|
|---|
| 1559 | <br><tt><font color="#000000">--------------- -------------
|
|---|
| 1560 | --------</font></tt>
|
|---|
| 1561 | <br><tt><font color="#000000">MonoIn
|
|---|
| 1562 | MonoIn MonoIn</font></tt>
|
|---|
| 1563 | <br><tt><font color="#000000">Phone
|
|---|
| 1564 | none
|
|---|
| 1565 | none</font></tt>
|
|---|
| 1566 | <br><tt><font color="#000000">Microphone
|
|---|
| 1567 | Mic
|
|---|
| 1568 | Mic</font></tt>
|
|---|
| 1569 | <br><tt><font color="#000000">Line-In
|
|---|
| 1570 | Aux1
|
|---|
| 1571 | Aux1 Aux1 = Line-In connector on card</font></tt>
|
|---|
| 1572 | <br><tt><font color="#000000">CD-ROM
|
|---|
| 1573 | Aux2
|
|---|
| 1574 | Aux2 Aux2 = CD-ROM Analog cable</font></tt>
|
|---|
| 1575 | <br><tt><font color="#000000">Video
|
|---|
| 1576 | none
|
|---|
| 1577 | none</font></tt>
|
|---|
| 1578 | <br><tt><font color="#000000">Aux
|
|---|
| 1579 | Line
|
|---|
| 1580 | DAC2 CS4236B=FM Volume, CS4235=Digital vol</font></tt>
|
|---|
| 1581 | <p>Record sources:
|
|---|
| 1582 | <br>On the Crystal Semiconductor ISA Mode 3 device driver, (CS4236B/7B/8B,
|
|---|
| 1583 | CS4235, CS4239):
|
|---|
| 1584 | <br>MONO-IN is not a possible record source.
|
|---|
| 1585 | <br>
|
|---|
| 1586 | </body>
|
|---|
| 1587 | </html>
|
|---|
