documentation/multimedia.sgml

   1   <chapter id="multimedia">
   2     <title>Wine and Multimedia</title>
   3
   4     <para>
   5       This file contains information about the implementation of the
   6       multimedia layer of Wine.
   7     </para>
   8
   9     <para>
  10       The implementation can be found in the
  11       <filename>dlls/winmm/</filename> directory (and in many of its
  12       subdirectories), but also in <filename>dlls/msacm/</filename>
  13       (for the audio compression/decompression manager) and
  14       <filename>dlls/msvideo/</filename> (for the video
  15       compression/decompression manager).
  16     </para>
  17
  18     <sect1 id="mm-overview">
  19       <title>Overview</title>
  20
  21       <para>
  22         The multimedia stuff is split into 3 layers. The low level (device
  23         drivers), mid level (MCI commands) and high level abstraction layers.
  24         The low level layer has also some helper DLLs (like the MSACM/MSACM32
  25         and MSVIDEO/MSVFW32 pairs).
  26       </para>
  27
  28       <para>
  29         All of those components are defined as DLLs (one by one).
  30       </para>
  31
  32       <para>
  33         The low level layer may depend on current hardware and OS services
  34         (like OSS on Unix). It provides the core of playback/record
  35         using fine grain objects (audio/midi streams...).
  36       </para>
  37       <para>
  38         Mid level (MCI) and high level layers must be written independently from
  39         the hardware and OS services.
  40       </para>
  41
  42       <para>
  43         MCI level provides some coarser grain operations (like playing
  44         a Midi file, or playing a video stream).
  45       </para>
  46
  47     </sect1>
  48
  49     <sect1 id="mm-arch">
  50       <title>Multimedia architecture</title>
  51
  52       <sect2>
  53         <title>Windows 95 multimedia architecture</title>
  54
  55         <screen>
  56              |
  57 Kernel space |                    Client applications
  58              |
  59              |           | |         ^ ^       | |          | |
  60              |        16>| |<32   16>| |<32 16>| |<32    16>| |<32
  61              |           | v         | |       | v          | v
  62              |      +----|-----------|---------|------------|-------+
  63              |      |    |           |         |            |       |  WinMM.dll
  64              |      |    |           |         |            |       |   32 bit
  65              |      +----|-----------|---------|------------|-------+
  66              |           | |         | ^       | |          |
  67              |  +------+ | |<16      | |       | |<16       |
  68              |  |   16>| | |         | |       | |          |
  69              |  |      v v v         | |       v v          v
  70              |  |   +---------------+---+-------------+-------------+
  71              |  |   | waveInXXX     |   | mciXXX      | *playSound* |
  72              |  |   | waveOutXXX    |   |             | mmioXXX     |
  73              |  |   | midiInXXX     |   |             | timeXXX     |
  74              |  |   | midiOutXXX    |   |             | driverXXX   |
  75              |  |   | midiStreamXXX |   |             |             |  MMSystem.dll
  76              |  |   | mixerXXX      |   |             |             |     16 bit
  77  +--------+  |  |   | auxXXX    +---+   +---+ mmThread|             |
  78  |MMDEVLDR|<------->| joyXXX    | Call back | mmTask  |             |
  79  +--------+  |  |   +-----------+-----------+---------+-------------+
  80      ^       |  |          |      ^    ^       | ^
  81      |       |  |       16>|      |<16>|    16>| |<16
  82      v       |  |          v      |    |       v |
  83  +--------+  |  |   +-------------+    +----------+
  84  |  VxD   |<------->|    *.drv    |    | mci*.drv |
  85  +--------+  |  |   +--------------+   +-----------+
  86              |  |    |  msacm.drv  |    | mciwave  |
  87              |  |    +--------------+   +-----------+
  88              |  |     | midimap.drv |    | mcimidi  |
  89              |  |     +-------------+    +-----------+
  90              |  |    Low-level drivers    |    ...   | MCI drivers
  91              |  |                         +----------+
  92              |  |                               |
  93              |  |                               |<16
  94              |  +-------------------------------+
  95              |
  96         </screen>
  97
  98         <para>
  99           The important points to notice are:
 100           <itemizedlist>
 101             <listitem>
 102               <para>
 103                 all drivers (and most of the core code) is 16 bit
 104               </para>
 105             </listitem>
 106             <listitem>
 107               <para>
 108                 all hardware (or most of it) dependent code reside in the kernel
 109                 space (which is not surprising)
 110               </para>
 111             </listitem>
 112           </itemizedlist>
 113         </para>
 114
 115       </sect2>
 116
 117       <sect2>
 118         <title>Windows NT multimedia architecture</title>
 119
 120         <para>
 121           Note that Win 98 has mixed 95/NT architecture, so when
 122           speaking about Windows 95 (resp. NT) architecture, it refers
 123           to the type of architecture, not what's actually
 124           implemented. For example, Windows 98 implements both types
 125           of architectures.
 126         </para>
 127
 128         <para>
 129           The important points to notice (compared to the Windows 95
 130           architecture) are:
 131           <itemizedlist>
 132             <listitem>
 133               <para>
 134                 drivers (low level, MCIs...) are 32 bit and Unicode
 135               </para>
 136             </listitem>
 137             <listitem>
 138               <para>
 139                 the interfaces between kernel and user drivers has
 140                 changed, but it doesn't impact much Wine. Those
 141                 changes allow some good things (like kernel mixing,
 142                 where different apps share the audio hardware) and of
 143                 course bad things (like kernel mixing, which adds
 144                 latency).
 145               </para>
 146             </listitem>
 147           </itemizedlist>
 148         </para>
 149       </sect2>
 150
 151       <sect2>
 152         <title>Wine multimedia architecture</title>
 153
 154         <screen>
 155              |
 156 Kernel space |                    Client applications
 157              |
 158              |           | |         ^ ^       | |          | |
 159              |        16>| |<32   16>| |<32 16>| |<32    16>| |<32
 160              |           | |         | |       | |          | |
 161              |  +------+ | |         | |       | |          | |
 162              |  |32/16>| | |         | |       | |          | |
 163              |  |      v v v         | |       v v          v v
 164              |  |   +---------------+---+-------------+-------------+
 165              |  |   | waveInXXX     |   | mciXXX      | *playSound* |
 166              |  |   | waveOutXXX    |   |             | mmioXXX     | WinMM.dll
 167              |  |   | midiInXXX     |   |             | timeXXX     |   32 bit
 168              |  |   | midiOutXXX    |   |             | driverXXX   |
 169              |  |   | midiStreamXXX |   |             |             | MMSystem.dll
 170              |  |   | mixerXXX      |   |             |             |   16 bit
 171              |  |   | auxXXX    +---+   +---+ mmThread|             |
 172              |  |   | joyXXX    | Call back | mmTask  |             |
 173              |  |   +-----------+-----------+---------+-------------+
 174              |  |         ||      ^    ^       | ^
 175              |  |      16>||<32   |<16>|    16>| |<16
 176              |  |         vv      |<32>|    32>v |<32
 177 +---------+  |  |   +-------------+    +----------+
 178 |HW driver|<------->|    *.drv    |    | mci*.drv |
 179 +---------+  |  |   +--------------+   +-----------+
 180              |  |    |  msacm.drv  |    | mciwave  |
 181              |  |    +--------------+   +-----------+
 182              |  |     | midimap.drv |    | mcimidi  |
 183              |  |     +-------------+    +-----------+
 184              |  |    Low-level drivers    |    ...   | MCI drivers
 185              |  |                         +----------+
 186              |  |                               |
 187              |  |                               |<32/16
 188              |  +-------------------------------+
 189              |
 190         </screen>
 191
 192         <para>
 193           From the previous drawings, the most noticeable differences are:
 194           <itemizedlist>
 195             <listitem>
 196               <para>
 197                 low-level drivers can either be 16 or 32 bit (in fact,
 198                 Wine supports only native wave and audio mappers).
 199               </para>
 200             </listitem>
 201             <listitem>
 202               <para>
 203                 MCI drivers can either be 16 or 32 bit
 204               </para>
 205             </listitem>
 206             <listitem>
 207               <para>
 208                 all built-in drivers (low-level and MCI) will be written as 32 bit
 209                 drivers
 210               </para>
 211             </listitem>
 212           </itemizedlist>
 213         </para>
 214
 215         <para>
 216           Wine's WinMM automatically adapts the messages to be sent to
 217           a driver so that it can convert it to 16 or 32 bit
 218           interfaces.
 219         </para>
 220
 221       </sect2>
 222
 223     </sect1>
 224
 225     <sect1 id="mm-low">
 226       <title>Low level layers</title>
 227
 228       <para>
 229         The low level drivers abstract the hardware specific features
 230         from the rest of the multimedia code. Those are implemented with a
 231         well defined set of APIs, as windows do.
 232       </para>
 233
 234       <para>
 235         Please note that native low level drivers are not currently supported
 236         in Wine, because they either access hardware components or require
 237         VxDs to be loaded; Wine does not correctly supports those two so far.
 238       </para>
 239
 240       <para>
 241         There are two specific low level drivers (msacm.drv for wave input/output,
 242         midimap.drv for MIDI output only). These drivers (also present
 243         in Windows) allow:
 244         <itemizedlist>
 245           <listitem>
 246             <para>
 247               choosing one low level driver between many (we'll
 248               discuss how the choice is made later on)
 249             </para>
 250           </listitem>
 251           <listitem>
 252             <para>
 253               add the possibility to convert stream's format (ie ADPCM =&gt;
 254               PCM) (this is useful if the format required by the
 255               application for playback isn't supported by the soundcard).
 256             </para>
 257           </listitem>
 258           <listitem>
 259             <para>
 260               add the possibility to filter a stream (adding echo, equalizer...
 261               to a wave stream, or modify the instruments that have to be
 262               played for a MIDI stream).
 263             </para>
 264           </listitem>
 265         </itemizedlist>
 266       </para>
 267
 268       <sect2>
 269         <title>Hardware-bound low level drivers</title>
 270
 271         <para>
 272           Each low lever driver has to implement at least one of the
 273           following functionality, through the named function:
 274           <itemizedlist>
 275             <listitem>
 276               <para>
 277                 Waveform audio: out for playback, and in for
 278                 recording. MMSYSTEM and WINMM call the real low level
 279                 audio driver using the driver's
 280                 <function>wodMessage</function> and
 281                 <function>widMessage</function> functions which handle
 282                 the different requests.
 283               </para>
 284             </listitem>
 285             <listitem>
 286               <para>
 287                 MIDI (Musical Instrument Digital Interface): out for
 288                 playback, and in for recording. MMSYSTEM and WINMM
 289                 call the low level driver functions using the driver's
 290                 <function>midMessage</function> and the
 291                 <function>modMessage</function> functions.
 292               </para>
 293             </listitem>
 294             <listitem>
 295               <para>
 296                 Mixer: this allows setting the volume for each one of
 297                 the other functionnality (and also some specific
 298                 attributes, like left/right balance for stereo
 299                 streams...). MMSYSTEM and WINMM call the low level
 300                 driver functions using the
 301                 <function>mxdMessage</function> function.
 302               </para>
 303             </listitem>
 304             <listitem>
 305               <para>
 306                 Aux: this is the predecessor of the mixer
 307                 functionnality (introduced in Win 95). Its usage has
 308                 been deprecated in favor of mixer interfaces.
 309               </para>
 310             </listitem>
 311           </itemizedlist>
 312         </para>
 313
 314         <para>
 315           Wine currently supports the following (kernel) multimedia
 316           interfaces.
 317           <itemizedlist>
 318             <listitem>
 319               <para>
 320                 Open Sound System (OSS) as supplied in the Linux and
 321                 FreeBSD kernels by <ulink
 322                   url="http://www.4front-tech.com/">4Front
 323                   Technologies</ulink>. The presence of this driver is
 324                 checked by configure (depends on the
 325                 &lt;sys/soundcard.h&gt; file). Source code resides in
 326                 <filename>dlls/winmm/wineoss</filename>.
 327               </para>
 328             </listitem>
 329             <listitem>
 330               <para>
 331                 Advanced Linux Sound Architecture (<ulink
 332                   url="http://www.alsa-project.org/">ALSA</ulink>) as
 333                 supplied in the Linux kernel. Source code resides in
 334                 <filename>dlls/winmm/winealsa</filename>.
 335               </para>
 336             </listitem>
 337             <listitem>
 338               <para>
 339                 Analog RealTime Synthetizer (<ulink
 340                   url="http://www.arts-project.org/">aRts</ulink>): a
 341                 network server (and virtual mixer) used in the KDE project.
 342               </para>
 343             </listitem>
 344             <listitem>
 345               <para>
 346                 Network Audio Server (<ulink
 347                   url="http://radscan.com/nas.html">NAS</ulink>): an
 348                 audio server.
 349               </para>
 350             </listitem>
 351             <listitem>
 352               <para>
 353                 <ulink
 354                   url="http://jackit.sourceforge.net/">Jack</ulink>: a
 355                 low latency audio server.
 356               </para>
 357             </listitem>
 358             <listitem>
 359               <para>
 360                 AudioIO: the native Solaris audio interface.
 361               </para>
 362             </listitem>
 363           </itemizedlist>
 364         </para>
 365
 366         <para>
 367           The supported functionnalities per driver is as follows
 368           (this table lists the available features of the products,
 369           not exactly what's actually implemented on Wine):
 370           <table frame="all">
 371             <title>Wine multimedia drivers' functionalities</title>
 372             <tgroup cols="6" align="left" colsep="1" rowsep="1">
 373               <thead>
 374                 <row>
 375                   <entry>Driver</entry>
 376                   <entry>Wave Out</entry>
 377                   <entry>Wave In</entry>
 378                   <entry>Midi Out</entry>
 379                   <entry>Midi In</entry>
 380                   <entry>Mixer (and Aux)</entry>
 381                 </row>
 382               </thead>
 383               <tbody>
 384                 <row>
 385                   <entry>OSS</entry>
 386                   <entry>Yes</entry>
 387                   <entry>Yes</entry>
 388                   <entry>Yes</entry>
 389                   <entry>Yes</entry>
 390                   <entry>Yes</entry>
 391                 </row>
 392                 <row>
 393                   <entry>ALSA</entry>
 394                   <entry>Yes</entry>
 395                   <entry>Yes</entry>
 396                   <entry>Yes</entry>
 397                   <entry>Yes</entry>
 398                   <entry>Yes</entry>
 399                 </row>
 400                 <row>
 401                   <entry>aRts</entry>
 402                   <entry>Yes</entry>
 403                   <entry>Yes</entry>
 404                   <entry>No</entry>
 405                   <entry>No</entry>
 406                   <entry>Yes</entry>
 407                 </row>
 408                 <row>
 409                   <entry>NAS</entry>
 410                   <entry>Yes</entry>
 411                   <entry>Yes</entry>
 412                   <entry>No</entry>
 413                   <entry>No</entry>
 414                   <entry>Yes</entry>
 415                 </row>
 416                 <row>
 417                   <entry>AudioIO</entry>
 418                   <entry>Yes</entry>
 419                   <entry>Yes</entry>
 420                   <entry>No</entry>
 421                   <entry>No</entry>
 422                   <entry>Yes</entry>
 423                 </row>
 424                 <row>
 425                   <entry>Jack</entry>
 426                   <entry>Yes</entry>
 427                   <entry>Yes</entry>
 428                   <entry>No</entry>
 429                   <entry>No</entry>
 430                   <entry>Yes</entry>
 431                 </row>
 432               </tbody>
 433             </tgroup>
 434           </table>
 435         </para>
 436
 437         <para>
 438           Lots of listed drivers won't support Midi (in a short time)
 439           because the exposed "Un*x" native interfaces don't. This
 440           would require using some kind as software synthesis (as
 441           Timidity), but we cannot incorporate as it's GPL'ed.
 442         </para>
 443
 444       </sect2>
 445
 446       <sect2>
 447         <title>Wave mapper (msacm.drv)</title>
 448
 449         <para>
 450           The Wave mapper device allows to load on-demand audio codecs
 451           in order to perform software conversion for the types the
 452           actual low level driver (hardware). Those codecs are
 453           provided through the standard ACM drivers in MSACM32.DLL.
 454         </para>
 455
 456         <para>
 457           Wave mapper driver implementation can be found in
 458           <filename>dlls/winmm/wavemap/</filename> directory. This
 459           driver heavily relies on MSACM and MSACM32 DLLs which can be
 460           found in <filename>dlls/msacm</filename> and
 461           <filename>dlls/msacm32</filename>. Those DLLs load ACM
 462           drivers which provide the conversion to PCM format (which is
 463           normally supported by low level drivers). A Law, uLaw,
 464           ADPCM, MP3... fit into the category of non PCM formats.
 465         </para>
 466
 467       </sect2>
 468
 469       <sect2>
 470         <title>MIDI mapper (midimap.drv)</title>
 471
 472         <para>
 473           Midi mapper allows to map each one of 16 MIDI channels to a
 474           specific instrument on an installed sound card. This allows
 475           for example to support different MIDI instrument definitions
 476           (XM, GM...). It also permits to output on a per channel
 477           basis to different MIDI renderers.
 478         </para>
 479
 480         <para>
 481           A built-in MIDI mapper can be found in
 482           <filename>dlls/winmm/midimap/</filename>. It partly provides
 483           the same functionality as the Windows' one. It allows to
 484           pick up destination channels: you can map a given channel to
 485           a specific playback device channel (see the configuration
 486           bits for more details).
 487         </para>
 488
 489       </sect2>
 490
 491     </sect1>
 492
 493     <sect1 id="mm-mci">
 494       <title>Mid level drivers (MCI)</title>
 495
 496       <para>
 497         The mid level drivers are represented by some common API
 498         functions, mostly <function>mciSendCommand</function> and
 499         <function>mciSendString</function>. Wine implements several
 500         MCI mid level drivers.
 501       </para>
 502
 503       <para>
 504         <table frame="all">
 505           <title>Wine MCI drivers</title>
 506           <tgroup cols="4" align="left" colsep="1" rowsep="1">
 507             <thead>
 508               <row>
 509                 <entry>MCI Name</entry>
 510                 <entry>DLL Name</entry>
 511                 <entry>Role</entry>
 512                 <entry>Location</entry>
 513                 <entry>Comments</entry>
 514               </row>
 515             </thead>
 516             <tbody>
 517               <row>
 518                 <entry>CdAudio</entry>
 519                 <entry>MciCDA.drv</entry>
 520                 <entry>MCI interface to a CD audio player</entry>
 521                 <entry><filename>dlls/winmm/mcicda/</filename></entry>
 522                 <entry>
 523                   Relies on NTDLL CdRom raw interface (through
 524                   <function>DeviceIoControl</function>).
 525                 </entry>
 526               </row>
 527               <row>
 528                 <entry>WaveAudio</entry>
 529                 <entry>MciWave.drv</entry>
 530                 <entry>
 531                   MCI interface for wave playback and record
 532                 </entry>
 533                 <entry><filename>dlls/winmm/mciwave/</filename></entry>
 534                 <entry>It uses the low level audio API.</entry>
 535               </row>
 536               <row>
 537                 <entry>Sequencer</entry>
 538                 <entry>MciSeq.drv</entry>
 539                 <entry>Midi Sequencer (playback)</entry>
 540                 <entry><filename>dlls/winmm/mciseq/</filename></entry>
 541                 <entry>It uses the low level midi APIs</entry>
 542               </row>
 543               <row>
 544                 <entry>AviVideo</entry>
 545                 <entry>MciAvi.drv</entry>
 546                 <entry>AVI playback and record</entry>
 547                 <entry><filename>dlls/winmm/mciavi/</filename></entry>
 548                 <entry>
 549                   It rather heavily relies on MSVIDEO/MSVFW32 DLLs
 550                   pair to work.
 551                 </entry>
 552               </row>
 553             </tbody>
 554           </tgroup>
 555         </table>
 556         The MCI Name column is the name of the MCI driver, as it is
 557         searched in configuration. The DLL Name column is the name of
 558         the DLL the configuration provides as a value. The name listed
 559         here is the default one (see the configuration section for the
 560         details).
 561       </para>
 562
 563       <para>
 564         Adding a new MCI driver is just a matter of writing the
 565         corresponding DLL with the correct interface (see existing MCI
 566         drivers for the details), and to provide the relevant setup
 567         information for <filename>wine.inf</filename>
 568       </para>
 569
 570     </sect1>
 571
 572     <sect1 id="mm-high">
 573       <title>High level layers</title>
 574
 575       <sect2>
 576         <title>WINMM (and MMSYSTEM)</title>
 577
 578         <para>
 579           The high level layers encompass basically the MMSYSTEM and
 580           WINMM DLLs exported APIs. It also provides the skeleton for
 581           the core functionality for multimedia playback and
 582           recording. Note that native MMSYSTEM and WINMM do not
 583           currently work under Wine and there is no plan to support
 584           them (it would require to also fully support VxD, which is
 585           not done yet).
 586         </para>
 587
 588         <para>
 589           WINMM and MMSYSTEM in Wine can handle both 16 bit and 32 bit
 590           drivers (for low level and MCI drivers). It will handle all
 591           the conversions transparently for the all the calls to WINMM
 592           and MMSYSTEM, as it knows what the driver interface is (16
 593           bit or 32 bit) and it manages the information sent
 594           accordingly.
 595         </para>
 596
 597         <para>
 598           MCI drivers are seen as regular Wine modules, and can be
 599           loaded (with a correct load order between builtin, native),
 600           as any other DLL. Please note, that MCI drivers module names
 601           must bear the <filename>.drv</filename> extension to be
 602           correctly understood.
 603         </para>
 604
 605         <para>
 606           Multimedia timers are implemented with a dedicated thread,
 607           run in the context of the calling process, which should
 608           correctly mimic Windows behavior. The only drawback is that
 609           the thread will appear the calling process if it enumerates
 610           the running processes.
 611         </para>
 612
 613       </sect2>
 614
 615       <sect2>
 616         <title>DSOUND</title>
 617
 618         <para>
 619           Wine also provide a DSound (DirectX) DLL with the proper
 620           COM implementation.
 621         </para>
 622
 623         <para>
 624           Note that a Wine specific flag has been added to the
 625           <function>wodOpen</function> function, so that the DSound
 626           DLL can get a reference to a COM sound object from a given
 627           WINMM wave output device. This should be changed in the
 628           future.
 629         </para>
 630
 631       </sect2>
 632
 633     </sect1>
 634
 635     <sect1 id="msacm">
 636       <title>MS ACM Dlls</title>
 637
 638       <sect2>
 639         <title>Contents</title>
 640
 641         <para>
 642           The MSACM32 (and its 16 bit sibbling MSACM) provide a way to
 643           map a given wave format to another format. It also provides
 644           filtering capabilities. Those DLLs only implement the proper
 645           switch between a caller and a driver providing the
 646           implementation of the requested format change or filter
 647           operation.
 648         </para>
 649
 650         <para>
 651           There's nothing specific in Wine's implementation compared
 652           to Windows' one. Here's however a list of the builtin format
 653           change drivers (there's no filter driver yet):
 654           <table frame="all">
 655             <title>Wine ACM drivers</title>
 656             <tgroup cols="2" align="left" colsep="1" rowsep="1">
 657               <thead>
 658                 <row>
 659                   <entry>Name</entry>
 660                   <entry>Provides</entry>
 661                 </row>
 662               </thead>
 663               <tbody>
 664                 <row>
 665                   <entry>imaadp32</entry>
 666                   <entry>IMA ADPCM (adaptative PCM)</entry>
 667                 </row>
 668                 <row>
 669                   <entry>msadp32</entry>
 670                   <entry>Microsoft's ADPCM (adaptative PCM)</entry>
 671                 </row>
 672                 <row>
 673                   <entry>msg711</entry>
 674                   <entry>Microsoft's G.711 (A-Law and µ-Law)</entry>
 675                 </row>
 676                 <row>
 677                   <entry>winemp3</entry>
 678                   <entry>
 679                     Wine's MP3 (MPEG Layer 3), based on mpglib library
 680                   </entry>
 681                 </row>
 682               </tbody>
 683             </tgroup>
 684           </table>
 685         </para>
 686
 687         <para>
 688           Note that Wine also supports native audio codecs as
 689           well.
 690         </para>
 691
 692         <para>
 693           All builtin ACM drivers are 32 bit Unicode DLLs
 694         </para>
 695
 696       </sect2>
 697
 698       <sect2>
 699         <title>Caching</title>
 700
 701         <para>
 702           The MSACM/MSACM32 keeps some data cached for all known ACM
 703           drivers. Under the key
 704           <screen>
 705           Software\Microsoft\AudioCompressionManager\DriverCache\&lt;driver name&gt;
 706           </screen>
 707           , are kept for values:
 708           <itemizedlist>
 709             <listitem>
 710               <para>
 711                 <literal>aFormatTagCache</literal> which
 712                 contains an array of <literal>DWORD</literal>. There
 713                 are two <literal>DWORD</literal>s per <literal>cFormatTags</literal>
 714                 entry. The first <literal>DWORD</literal> contains a
 715                 format tag value, and the second the associated
 716                 maximum size for a <literal>WAVEFORMATEX</literal> structure.
 717                 (Fields <literal>dwFormatTag</literal> and <literal>cbFormatSize</literal> from
 718                 ACMFORMATDETAILS)
 719               </para>
 720             </listitem>
 721             <listitem>
 722               <para>
 723                 <literal>cFilterTags</literal> contains the number of tags supported by the driver
 724                 for filtering.
 725               </para>
 726             </listitem>
 727             <listitem>
 728               <para>
 729                 <literal>cFormatTags</literal> contains the number of tags support
 730                 by the driver for conversions.
 731               </para>
 732             </listitem>
 733             <listitem>
 734               <para>
 735                 <literal>fdwSupport</literal> (the same as the one returned from
 736                 <function>acmDriverDetails</function>).
 737               </para>
 738             </listitem>
 739           </itemizedlist>
 740         </para>
 741
 742         <para>
 743           The <literal>cFilterTags</literal>,
 744           <literal>cFormatTags</literal>,
 745           <literal>fdwSupport</literal> are the same values as the
 746           ones returned from <function>acmDriverDetails</function>
 747           function.
 748         </para>
 749       </sect2>
 750     </sect1>
 751
 752     <sect1 id="msvfw32">
 753       <title>MS Video Dlls</title>
 754
 755       <sect2>
 756         <title>Contents</title>
 757
 758         <para>
 759           The MSVFW32 (and its 16 bit sibbling MSVIDEO) provide
 760           encode/decode video streams. Those DLLs only implement the
 761           proper switch between a caller and a driver providing the
 762           implementation of the requested format coding/decoding
 763           operation.
 764         </para>
 765
 766         <para>
 767           There's nothing specific in Wine's implementation compared
 768           to Windows' one. Here's however a list of the builtin
 769           decoding drivers:
 770           <table frame="all">
 771             <title>Wine VIDC drivers</title>
 772             <tgroup cols="2" align="left" colsep="1" rowsep="1">
 773               <thead>
 774                 <row>
 775                   <entry>Name</entry>
 776                   <entry>Provides</entry>
 777                 </row>
 778               </thead>
 779               <tbody>
 780                 <row>
 781                   <entry>msrle32</entry>
 782                   <entry>Microsoft's RLE (Run-Length encoded)</entry>
 783                 </row>
 784                 <row>
 785                   <entry>msvidc32</entry>
 786                   <entry>Microsoft's Video-1</entry>
 787                 </row>
 788                 <row>
 789                   <entry>iccvid</entry>
 790                   <entry>Radius Cinepak Video Decoder</entry>
 791                 </row>
 792               </tbody>
 793             </tgroup>
 794           </table>
 795         </para>
 796
 797         <para>
 798           Note that Wine also supports native video codecs as well.
 799         </para>
 800
 801         <para>
 802           All builtin VIDC drivers are 32 bit Unicode DLLs
 803         </para>
 804
 805       </sect2>
 806
 807     </sect1>
 808
 809     <sect1 id="mm-conf">
 810       <title>Multimedia configuration</title>
 811
 812       <para>
 813         Unfortunately, multimedia configuration evolved over time:
 814         <itemizedlist>
 815           <listitem>
 816             <para>
 817               In the early days on Windows 3.x, configuration was
 818               stored in <filename>system.in</filename> file, under
 819               various sections (<literal>[drivers]</literal> for low
 820               level drivers, <literal>[mci]</literal>
 821               (resp. <literal>[mci32]</literal>) for 16 bit (resp. 32
 822               bit) MCI drivers...).
 823             </para>
 824           </listitem>
 825           <listitem>
 826             <para>
 827               With the apparition of the registry, in Windows 95,
 828               configuration as been duplicated there, under the key
 829 <screen>
 830 HKLM\System\CurrentControlSet\Control\MediaResources
 831 </screen>
 832             </para>
 833           </listitem>
 834           <listitem>
 835             <para>
 836               Windows NT also adopted the registry, but decided to
 837               store the configuration information under another key
 838               than Windows 9x did.
 839 <screen>
 840 HKLM\Software\Microsoft\Windows NT\CurrentVersion
 841 </screen>
 842               And with a different layout of keys and values beneath
 843               this key.
 844             </para>
 845           </listitem>
 846         </itemizedlist>
 847       </para>
 848
 849       <para>
 850         Currently, Wine tries to load first a driver (low-level or
 851         MCI) from the NT registry settings. If it fails, it will try
 852         the <filename>system.ini</filename> configuration.
 853       </para>
 854
 855       <para>
 856         An out-of-the-box configuration is provided in
 857         <filename>wine.inf</filename>, and shall be stored in registry
 858         and <filename>system.ini</filename> at Wine installation
 859         time. It will setup correctly the MCI drivers' configuration
 860         (as well as the wave and MIDI mappers). As the low-level
 861         drivers depend on hardware, their setup will be handled by
 862         <filename>winecfg</filename>.
 863       </para>
 864
 865       <table frame="all">
 866         <title>Wine multimedia configuration scheme</title>
 867         <tgroup cols="5" align="left" colsep="1" rowsep="1">
 868           <thead>
 869             <row>
 870               <entry>Driver</entry>
 871               <entry>Read from NT registry</entry>
 872               <entry>Read from <filename>system.ini</filename></entry>
 873               <entry>Setup by <filename>wine.inf</filename></entry>
 874               <entry>Setup by <filename>winecfg</filename></entry>
 875             </row>
 876           </thead>
 877           <tbody>
 878             <row>
 879               <entry>MCI drivers</entry>
 880               <entry>Yes (1)</entry>
 881               <entry>Yes (2)</entry>
 882               <entry>Yes</entry>
 883               <entry>No</entry>
 884             </row>
 885             <row>
 886               <entry>Wave and MIDI mappers</entry>
 887               <entry>Yes</entry>
 888               <entry>No</entry>
 889               <entry>Yes</entry>
 890               <entry>No</entry>
 891             </row>
 892             <row>
 893               <entry>Hardware-bound low level drivers</entry>
 894               <entry>Yes</entry>
 895               <entry>No</entry>
 896               <entry>No</entry>
 897               <entry>Yes</entry>
 898             </row>
 899             <row>
 900               <entry>ACM and VIDC drivers (audio & video codecs)</entry>
 901               <entry>No</entry>
 902               <entry>Yes</entry>
 903               <entry>Yes</entry>
 904               <entry>No</entry>
 905             </row>
 906           </tbody>
 907         </tgroup>
 908       </table>
 909
 910       <para>
 911         This will allow most settings to be correctly loaded and
 912         handled. However, it won't if an app tries to search directly
 913         the registry for the actual configuration, as the three
 914         potential configuration places may not be in sync.
 915       </para>
 916
 917       <para>
 918         It still lacks a correct installation scheme (as any
 919         multimedia device under Windows), so that all the correct
 920         keys are created in the registry. This requires an advanced
 921         model since, for example, the number of wave out devices can
 922         only be known on the destination system (depends on the
 923         sound card driven by the OSS interface).
 924       </para>
 925
 926       <para>
 927         The following sections describe which type of information
 928         (depending on the location) Wine's multimedia DLLs understand.
 929       </para>
 930
 931       <sect2>
 932         <title>NT configuration</title>
 933
 934         <para>
 935           Under the
 936           <screen>
 937 HKLM\Software\Microsoft\Windows NT\CurrentVersion
 938           </screen>
 939           key, are stored the names of the DLLs to be loaded for each
 940           MCI driver name:
 941           <screen>
 942             "cdaudio"="mcicda.drv"
 943             "sequencer"="mciseq.drv"
 944             "waveaudio"="mciwave.drv"
 945             "avivideo"="mciavi.drv"
 946             "videodisc"="mcipionr.drv"
 947             "vcr"="mcivisca.drv"
 948             "MPEGVideo"="mciqtz.drv"
 949           </screen>
 950         </para>
 951       </sect2>
 952
 953       <sect2>
 954         <title><filename>system.ini</filename></title>
 955
 956         <para>
 957           Wine will read the MCI drivers from the
 958           <literal>[mci]</literal> or <literal>[mci32]</literal>
 959           section. Wine won't make any difference between the two.
 960         </para>
 961
 962         <para>
 963           Here's a sample configuration:
 964           <screen>
 965    [mci]
 966    cdaudio=mcicda.drv
 967    sequencer=mciseq.drv
 968    waveaudio=mciwave.drv
 969    avivideo=mciavi.drv
 970    videodisc=mcipionr.drv
 971    vcr=mcivisca.drv
 972    MPEGVideo=mciqtz.drv
 973           </screen>
 974         </para>
 975
 976         <para>
 977           ACM drivers' configuration is read (only so far) from the
 978           <filename>system.ini</filename> (and setup at Wine
 979           installation from the <filename>wine.inf</filename> file).
 980           <screen>
 981     [drivers32]
 982     MSACM.imaadpcm=imaadp32.acm
 983     MSACM.msadpcm=msadp32.acm
 984     MSACM.msg711=msg711.acm
 985     MSACM.winemp3=winemp3.acm
 986           </screen>
 987         </para>
 988
 989         <para>
 990           Video (aka vidc) drivers' configuration is read (only so
 991           far) from the <filename>system.ini</filename> (and setup at
 992           Wine installation from the <filename>wine.inf</filename>
 993           file).
 994           <screen>
 995     [drivers32]
 996     VIDC.MRLE=msrle32.dll
 997     VIDC.MSVC=msvidc32.dll
 998     VIDC.CVID=iccvid.dll
 999           </screen>
1000         </para>
1001
1002         <para>
1003           See also the configuration part of the User's Guide for
1004           other information on low level drivers.
1005         </para>
1006
1007       </sect2>
1008
1009       <sect2>
1010         <title>Per driver/DLL configuration</title>
1011
1012         <sect3>
1013           <title>Midi mapper</title>
1014
1015           <para>
1016             The Midi mapper configuration is the same as on Windows
1017             9x. Under the key:
1018           <screen>
1019 HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Multimedia\MIDIMap
1020           </screen>
1021             if the <literal>UseScheme</literal> value is not set, or
1022             is set to a null value, the MIDI mapper will always use
1023             the driver identified by the
1024             <literal>CurrentInstrument</literal> value. Note: Wine
1025             (for simplicity while installing) allows to define
1026             <literal>CurrentInstrument</literal> as
1027             <literal>#n</literal> (where n is a number), whereas
1028             Windows only allows the real device name here. If
1029             <literal>UseScheme</literal> is set to a non null value,
1030             <literal>CurrentScheme</literal> defines the name of the
1031             scheme to map the different channels.  All the schemes are
1032             available with keys like
1033             <screen>
1034 HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\MediaProperties\PrivateProperties\Midi\Schemes\%name_of_scheme%
1035             </screen>
1036             For every scheme, under this key, will be a sub-key (which
1037             name is usually a two digit index, starting at 00). Its
1038             default value is the name of the output driver, and the
1039             value <literal>Channels</literal> lists all channels (of
1040             the 16 standard MIDI ones) which have to be copied to this
1041             driver.
1042           </para>
1043
1044           <para>
1045             To provide enhanced configuration and mapping
1046             capabilities, each driver can define under the key
1047             <screen>
1048 HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\MediaProperties\PrivateProperties\Midi\Ports\%driver_name%
1049             </screen>
1050             a link to and <filename>.IDF</filename> file which allows
1051             to remap channels internally (for  example 9 -&gt; 16), to
1052             change instruments identification, event controllers
1053             values. See the source file
1054             <filename>dlls/winmm/midimap/midimap.c</filename> for the
1055             details (this isn't implemented yet).
1056           </para>
1057
1058         </sect3>
1059
1060       </sect2>
1061
1062     </sect1>
1063
1064   </chapter>
1065
1066 <!-- Keep this comment at the end of the file
1067 Local variables:
1068 mode: sgml
1069 sgml-parent-document:("wine-devel.sgml" "set" "book" "part" "chapter" "")
1070 End:
1071 -->