documentation/multimedia.sgml

  <chapter id="multimedia">
    <title>Wine and Multimedia</title>

    <para>
      This file contains information about the implementation of the
      multimedia layer of Wine.
    </para>

    <para>
      The implementation can be found in the
      <filename>dlls/winmm/</filename> directory (and in many of its
      subdirectories), but also in <filename>dlls/msacm/</filename>
      (for the audio compression/decompression manager) and
      <filename>dlls/msvideo/</filename> (for the video
      compression/decompression manager).
    </para>

    <sect1 id="mm-overview">
      <title>Overview</title>

      <para>
	The multimedia stuff is split into 3 layers. The low level (device
	drivers), mid level (MCI commands) and high level abstraction layers.
        The low level layer has also some helper DLLs (like the MSACM/MSACM32
        and MSVIDEO/MSVFW32 pairs).
      </para>

      <para>
	All of those components are defined as DLLs (one by one).
      </para>

      <para>
	The low level layer may depend on current hardware and OS services
        (like OSS on Unix). It provides the core of playback/record
	using fine grain objects (audio/midi streams...).
      </para>
      <para>
	Mid level (MCI) and high level layers must be written independently from
	the hardware and OS services.
      </para>

      <para>
	MCI level provides some coarser grain operations (like playing
	a Midi file, or playing a video stream).
      </para>

    </sect1>

    <sect1 id="mm-arch">
      <title>Multimedia architecture</title>

      <sect2>
	<title>Windows 95 multimedia architecture</title>

	<screen>
             |
Kernel space |                    Client applications
             |
             |           | |         ^ ^       | |          | |
             |        16>| |<32   16>| |<32 16>| |<32    16>| |<32
             |           | v         | |       | v          | v
             |      +----|-----------|---------|------------|-------+
             |      |    |           |         |            |       |  WinMM.dll
             |      |    |           |         |            |       |   32 bit
             |      +----|-----------|---------|------------|-------+
             |           | |         | ^       | |          |
             |  +------+ | |<16      | |       | |<16       |
             |  |   16>| | |         | |       | |          |
             |  |      v v v         | |       v v          v
             |  |   +---------------+---+-------------+-------------+
             |  |   | waveInXXX     |   | mciXXX      | *playSound* |
             |  |   | waveOutXXX    |   |             | mmioXXX     |
             |  |   | midiInXXX     |   |             | timeXXX     |
             |  |   | midiOutXXX    |   |             | driverXXX   |
             |  |   | midiStreamXXX |   |             |             |  MMSystem.dll
             |  |   | mixerXXX      |   |             |             |     16 bit
 +--------+  |  |   | auxXXX    +---+   +---+ mmThread|             |
 |MMDEVLDR|<------->| joyXXX    | Call back | mmTask  |             |
 +--------+  |  |   +-----------+-----------+---------+-------------+
     ^       |  |          |      ^    ^       | ^
     |       |  |       16>|      |<16>|    16>| |<16
     v       |  |          v      |    |       v |
 +--------+  |  |   +-------------+    +----------+
 |  VxD   |<------->|    *.drv    |    | mci*.drv |
 +--------+  |  |   +--------------+   +-----------+
             |  |    |  msacm.drv  |    | mciwave  |
             |  |    +--------------+   +-----------+
             |  |     | midimap.drv |    | mcimidi  |
             |  |     +-------------+    +-----------+
             |  |    Low-level drivers    |    ...   | MCI drivers
             |  |                         +----------+
             |  |                               |
             |  |                               |<16
             |  +-------------------------------+
             |
	</screen>

	<para>
	  The important points to notice are:
	  <itemizedlist>
	    <listitem>
	      <para>
		all drivers (and most of the core code) is 16 bit
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		all hardware (or most of it) dependent code reside in the kernel
		space (which is not surprising)
	      </para>
	    </listitem>
	  </itemizedlist>
	</para>

      </sect2>

      <sect2>
	<title>Windows NT multimedia architecture</title>

	<para>
	  Note that Win 98 has mixed 95/NT architecture, so when
	  speaking about Windows 95 (resp. NT) architecture, it refers
	  to the type of architecture, not what's actually
	  implemented. For example, Windows 98 implements both types
	  of architectures.
	</para>

	<para>
	  The important points to notice (compared to the Windows 95
	  architecture) are:
	  <itemizedlist>
	    <listitem>
	      <para>
		drivers (low level, MCIs...) are 32 bit and Unicode
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		the interfaces between kernel and user drivers has
		changed, but it doesn't impact much Wine. Those
		changes allow some good things (like kernel mixing,
		where different apps share the audio hardware) and of
		course bad things (like kernel mixing, which adds
		latency).
	      </para>
	    </listitem>
	  </itemizedlist>
	</para>
      </sect2>

      <sect2>
	<title>Wine multimedia architecture</title>

	<screen>
             |
Kernel space |                    Client applications
             |
             |           | |         ^ ^       | |          | |
             |        16>| |<32   16>| |<32 16>| |<32    16>| |<32
             |           | |         | |       | |          | |
             |  +------+ | |         | |       | |          | |
             |  |32/16>| | |         | |       | |          | |
             |  |      v v v         | |       v v          v v
             |  |   +---------------+---+-------------+-------------+
             |  |   | waveInXXX     |   | mciXXX      | *playSound* |
             |  |   | waveOutXXX    |   |             | mmioXXX     | WinMM.dll
             |  |   | midiInXXX     |   |             | timeXXX     |   32 bit
             |  |   | midiOutXXX    |   |             | driverXXX   |
             |  |   | midiStreamXXX |   |             |             | MMSystem.dll
             |  |   | mixerXXX      |   |             |             |   16 bit
             |  |   | auxXXX    +---+   +---+ mmThread|             |
             |  |   | joyXXX    | Call back | mmTask  |             |
             |  |   +-----------+-----------+---------+-------------+
             |  |         ||      ^    ^       | ^
             |  |      16>||<32   |<16>|    16>| |<16
             |  |         vv      |<32>|    32>v |<32
+---------+  |  |   +-------------+    +----------+
|HW driver|<------->|    *.drv    |    | mci*.drv |
+---------+  |  |   +--------------+   +-----------+
             |  |    |  msacm.drv  |    | mciwave  |
             |  |    +--------------+   +-----------+
             |  |     | midimap.drv |    | mcimidi  |
             |  |     +-------------+    +-----------+
             |  |    Low-level drivers    |    ...   | MCI drivers
             |  |                         +----------+
             |  |                               |
             |  |                               |<32/16
             |  +-------------------------------+
             |
	</screen>

	<para>
	  From the previous drawings, the most noticeable differences are:
	  <itemizedlist>
	    <listitem>
	      <para>
		low-level drivers can either be 16 or 32 bit (in fact,
		Wine supports only native wave and audio mappers).
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		MCI drivers can either be 16 or 32 bit
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		all built-in drivers (low-level and MCI) will be written as 32 bit
		drivers
	      </para>
	    </listitem>
	  </itemizedlist>
	</para>

	<para>
	  Wine's WinMM automatically adapts the messages to be sent to
	  a driver so that it can convert it to 16 or 32 bit
	  interfaces.
	</para>

      </sect2>

    </sect1>

    <sect1 id="mm-low">
      <title>Low level layers</title>

      <para>
	The low level drivers abstract the hardware specific features
	from the rest of the multimedia code. Those are implemented with a
	well defined set of APIs, as windows do.
      </para>

      <para>
	Please note that native low level drivers are not currently supported
	in Wine, because they either access hardware components or require
	VxDs to be loaded; Wine does not correctly supports those two so far.
      </para>

      <para>
	There are two specific low level drivers (msacm.drv for wave input/output,
        midimap.drv for MIDI output only). These drivers (also present
        in Windows) allow:
	<itemizedlist>
	  <listitem>
	    <para>
	      choosing one low level driver between many (we'll
              discuss how the choice is made later on)
	    </para>
	  </listitem>
	  <listitem>
	    <para>
              add the possibility to convert stream's format (ie ADPCM =&gt;
              PCM) (this is useful if the format required by the
              application for playback isn't supported by the soundcard). 
            </para>
	  </listitem>
	  <listitem>
	    <para>
	      add the possibility to filter a stream (adding echo, equalizer...
              to a wave stream, or modify the instruments that have to be
              played for a MIDI stream).
	    </para>
	  </listitem>
	</itemizedlist>
      </para>

      <sect2>
	<title>Hardware-bound low level drivers</title>
      
	<para>
	  Each low lever driver has to implement at least one of the
	  following functionality, through the named function: 
	  <itemizedlist>
	    <listitem>
	      <para>
		Waveform audio: out for playback, and in for
		recording. MMSYSTEM and WINMM call the real low level
		audio driver using the driver's
		<function>wodMessage</function> and
		<function>widMessage</function> functions which handle
		the different requests.
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		MIDI (Musical Instrument Digital Interface): out for
		playback, and in for recording. MMSYSTEM and WINMM
		call the low level driver functions using the driver's
		<function>midMessage</function> and the
		<function>modMessage</function> functions.
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		Mixer: this allows setting the volume for each one of
		the other functionnality (and also some specific
		attributes, like left/right balance for stereo
		streams...). MMSYSTEM and WINMM call the low level
		driver functions using the
		<function>mxdMessage</function> function. 
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		Aux: this is the predecessor of the mixer
		functionnality (introduced in Win 95). Its usage has
		been deprecated in favor of mixer interfaces.
	      </para>
	    </listitem>
	  </itemizedlist>
	</para>

	<para>
	  Wine currently supports the following (kernel) multimedia
	  interfaces. 
	  <itemizedlist>
	    <listitem>
	      <para>
		Open Sound System (OSS) as supplied in the Linux and
		FreeBSD kernels by <ulink
		  url="http://www.4front-tech.com/">4Front
		  Technologies</ulink>. The presence of this driver is
		checked by configure (depends on the
		&lt;sys/soundcard.h&gt; file). Source code resides in
		<filename>dlls/winmm/wineoss</filename>.
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		Advanced Linux Sound Architecture (<ulink
		  url="http://www.alsa-project.org/">ALSA</ulink>) as
		supplied in the Linux kernel. Source code resides in
		<filename>dlls/winmm/winealsa</filename>.
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		Analog RealTime Synthetizer (<ulink
		  url="http://www.arts-project.org/">aRts</ulink>): a
		network server (and virtual mixer) used in the KDE project.
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		Network Audio Server (<ulink
		  url="http://radscan.com/nas.html">NAS</ulink>): an
		audio server.
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		<ulink
		  url="http://jackit.sourceforge.net/">Jack</ulink>: a
		low latency audio server.
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		AudioIO: the native Solaris audio interface.
	      </para>
	    </listitem>
	  </itemizedlist>
	</para>

	<para>
	  The supported functionnalities per driver is as follows
	  (this table lists the available features of the products,
	  not exactly what's actually implemented on Wine):
	  <table frame="all">
	    <title>Wine multimedia drivers' functionalities</title>
	    <tgroup cols="6" align="left" colsep="1" rowsep="1">
	      <thead>
		<row>
		  <entry>Driver</entry>
		  <entry>Wave Out</entry>
		  <entry>Wave In</entry>
		  <entry>Midi Out</entry>
		  <entry>Midi In</entry>
		  <entry>Mixer (and Aux)</entry>
		</row>
	      </thead>
	      <tbody>
		<row>
		  <entry>OSS</entry>
		  <entry>Yes</entry>
		  <entry>Yes</entry>
		  <entry>Yes</entry>
		  <entry>Yes</entry>
		  <entry>Yes</entry>
		</row>
		<row>
		  <entry>ALSA</entry>
		  <entry>Yes</entry>
		  <entry>Yes</entry>
		  <entry>Yes</entry>
		  <entry>Yes</entry>
		  <entry>Yes</entry>
		</row>
		<row>
		  <entry>aRts</entry>
		  <entry>Yes</entry>
		  <entry>Yes</entry>
		  <entry>No</entry>
		  <entry>No</entry>
		  <entry>Yes</entry>
		</row>
		<row>
		  <entry>NAS</entry>
		  <entry>Yes</entry>
		  <entry>Yes</entry>
		  <entry>No</entry>
		  <entry>No</entry>
		  <entry>Yes</entry>
		</row>
		<row>
		  <entry>AudioIO</entry>
		  <entry>Yes</entry>
		  <entry>Yes</entry>
		  <entry>No</entry>
		  <entry>No</entry>
		  <entry>Yes</entry>
		</row>
		<row>
		  <entry>Jack</entry>
		  <entry>Yes</entry>
		  <entry>Yes</entry>
		  <entry>No</entry>
		  <entry>No</entry>
		  <entry>Yes</entry>
		</row>
	      </tbody>
	    </tgroup>
	  </table>
	</para>

	<para>
	  Lots of listed drivers won't support Midi (in a short time)
	  because the exposed "Un*x" native interfaces don't. This
	  would require using some kind as software synthesis (as
	  Timidity), but we cannot incorporate as it's GPL'ed.
	</para>

      </sect2>

      <sect2>
	<title>Wave mapper (msacm.drv)</title>

	<para>
	  The Wave mapper device allows to load on-demand audio codecs
	  in order to perform software conversion for the types the
	  actual low level driver (hardware). Those codecs are
	  provided through the standard ACM drivers in MSACM32.DLL.
	</para>

	<para>
	  Wave mapper driver implementation can be found in
	  <filename>dlls/winmm/wavemap/</filename> directory. This
	  driver heavily relies on MSACM and MSACM32 DLLs which can be
	  found in <filename>dlls/msacm</filename> and
          <filename>dlls/msacm32</filename>. Those DLLs load ACM
          drivers which provide the conversion to PCM format (which is
          normally supported by low level drivers). A Law, uLaw,
          ADPCM, MP3... fit into the category of non PCM formats. 
	</para>

      </sect2>

      <sect2>
	<title>MIDI mapper (midimap.drv)</title>

	<para>
	  Midi mapper allows to map each one of 16 MIDI channels to a
	  specific instrument on an installed sound card. This allows
	  for example to support different MIDI instrument definitions
	  (XM, GM...). It also permits to output on a per channel
	  basis to different MIDI renderers.
	</para>

	<para>
	  A built-in MIDI mapper can be found in
	  <filename>dlls/winmm/midimap/</filename>. It partly provides
	  the same functionality as the Windows' one. It allows to
	  pick up destination channels: you can map a given channel to
	  a specific playback device channel (see the configuration
	  bits for more details).
	</para>

      </sect2>

    </sect1>

    <sect1 id="mm-mci">
      <title>Mid level drivers (MCI)</title>

      <para>
	The mid level drivers are represented by some common API
	functions, mostly <function>mciSendCommand</function> and
	<function>mciSendString</function>. Wine implements several
	MCI mid level drivers.
      </para>

      <para>
	<table frame="all">
	  <title>Wine MCI drivers</title>
	  <tgroup cols="4" align="left" colsep="1" rowsep="1">
	    <thead>
	      <row>
		<entry>MCI Name</entry>
		<entry>DLL Name</entry>
		<entry>Role</entry>
		<entry>Location</entry>
		<entry>Comments</entry>
	      </row>
	    </thead>
	    <tbody>
	      <row>
		<entry>CdAudio</entry>
		<entry>MciCDA.drv</entry>
		<entry>MCI interface to a CD audio player</entry>
		<entry><filename>dlls/winmm/mcicda/</filename></entry>
		<entry>
		  Relies on NTDLL CdRom raw interface (through
		  <function>DeviceIoControl</function>). 
		</entry>
	      </row>
	      <row>
		<entry>WaveAudio</entry>
		<entry>MciWave.drv</entry>
		<entry>
		  MCI interface for wave playback and record
		</entry>
		<entry><filename>dlls/winmm/mciwave/</filename></entry> 
		<entry>It uses the low level audio API.</entry>
	      </row>
	      <row>
		<entry>Sequencer</entry>
		<entry>MciSeq.drv</entry>
		<entry>Midi Sequencer (playback)</entry>
		<entry><filename>dlls/winmm/mciseq/</filename></entry>
		<entry>It uses the low level midi APIs</entry>
	      </row>
	      <row>
		<entry>AviVideo</entry>
		<entry>MciAvi.drv</entry>
		<entry>AVI playback and record</entry>
		<entry><filename>dlls/winmm/mciavi/</filename></entry>
		<entry>
		  It rather heavily relies on MSVIDEO/MSVFW32 DLLs
		  pair to work.
		</entry>
	      </row>
	    </tbody>
	  </tgroup>
	</table>
	The MCI Name column is the name of the MCI driver, as it is
	searched in configuration. The DLL Name column is the name of
	the DLL the configuration provides as a value. The name listed
	here is the default one (see the configuration section for the
	details).
      </para>

      <para>
	Adding a new MCI driver is just a matter of writing the
	corresponding DLL with the correct interface (see existing MCI
	drivers for the details), and to provide the relevant setup
	information for <filename>wine.inf</filename>
      </para>

    </sect1>

    <sect1 id="mm-high">
      <title>High level layers</title>

      <sect2>
	<title>WINMM (and MMSYSTEM)</title>
	
	<para>
	  The high level layers encompass basically the MMSYSTEM and
	  WINMM DLLs exported APIs. It also provides the skeleton for
	  the core functionality for multimedia playback and
	  recording. Note that native MMSYSTEM and WINMM do not
	  currently work under Wine and there is no plan to support
	  them (it would require to also fully support VxD, which is
	  not done yet).
	</para>
      
	<para>
	  WINMM and MMSYSTEM in Wine can handle both 16 bit and 32 bit
	  drivers (for low level and MCI drivers). It will handle all
	  the conversions transparently for the all the calls to WINMM
	  and MMSYSTEM, as it knows what the driver interface is (16
	  bit or 32 bit) and it manages the information sent
	  accordingly.
	</para>

	<para>
	  MCI drivers are seen as regular Wine modules, and can be
	  loaded (with a correct load order between builtin, native),
	  as any other DLL. Please note, that MCI drivers module names
	  must bear the <filename>.drv</filename> extension to be
	  correctly understood.
	</para>

	<para>
	  Multimedia timers are implemented with a dedicated thread,
	  run in the context of the calling process, which should
	  correctly mimic Windows behavior. The only drawback is that
	  the thread will appear the calling process if it enumerates
	  the running processes.
	</para>

      </sect2>

      <sect2>
	<title>DSOUND</title>

	<para>
	  Wine also provide a DSound (DirectX) DLL with the proper
	  COM implementation.
	</para>

	<para>
	  Note that a Wine specific flag has been added to the
	  <function>wodOpen</function> function, so that the DSound
	  DLL can get a reference to a COM sound object from a given
	  WINMM wave output device. This should be changed in the
	  future.
	</para>

      </sect2>

    </sect1>

    <sect1 id="msacm">
      <title>MS ACM Dlls</title>

      <sect2>
	<title>Contents</title>

	<para>
	  The MSACM32 (and its 16 bit sibbling MSACM) provide a way to
	  map a given wave format to another format. It also provides
	  filtering capabilities. Those DLLs only implement the proper
	  switch between a caller and a driver providing the
	  implementation of the requested format change or filter
	  operation.
	</para>
	
	<para>
	  There's nothing specific in Wine's implementation compared
	  to Windows' one. Here's however a list of the builtin format
	  change drivers (there's no filter driver yet):
	  <table frame="all">
	    <title>Wine ACM drivers</title>
	    <tgroup cols="2" align="left" colsep="1" rowsep="1">
	      <thead>
		<row>
		  <entry>Name</entry>
		  <entry>Provides</entry>
		</row>
	      </thead>
	      <tbody>
		<row>
		  <entry>imaadp32</entry>
		  <entry>IMA ADPCM (adaptative PCM)</entry>
		</row>
		<row>
		  <entry>msadp32</entry>
		  <entry>Microsoft's ADPCM (adaptative PCM)</entry>
		</row>
		<row>
		  <entry>msg711</entry>
		  <entry>Microsoft's G.711 (A-Law and µ-Law)</entry>
		</row>
		<row>
		  <entry>winemp3</entry>
		  <entry>
		    Wine's MP3 (MPEG Layer 3), based on mpglib library
		  </entry>
		</row>
	      </tbody>
	    </tgroup>
	  </table>
	</para>

	<para>
	  Note that Wine also supports native audio codecs as
	  well.
	</para>
  
	<para>
	  All builtin ACM drivers are 32 bit Unicode DLLs
	</para>

      </sect2>

      <sect2>
	<title>Caching</title>

	<para>
	  The MSACM/MSACM32 keeps some data cached for all known ACM
	  drivers. Under the key
          <screen>
	  Software\Microsoft\AudioCompressionManager\DriverCache\&lt;driver name&gt;
	  </screen>
	  , are kept for values:
	  <itemizedlist>
	    <listitem>
	      <para>
		<literal>aFormatTagCache</literal> which
		contains an array of <literal>DWORD</literal>. There
		are two <literal>DWORD</literal>s per <literal>cFormatTags</literal> 
		entry. The first <literal>DWORD</literal> contains a
		format tag value, and the second the associated
		maximum size for a <literal>WAVEFORMATEX</literal> structure.
		(Fields <literal>dwFormatTag</literal> and <literal>cbFormatSize</literal> from
		ACMFORMATDETAILS)
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		<literal>cFilterTags</literal> contains the number of tags supported by the driver
		for filtering.
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		<literal>cFormatTags</literal> contains the number of tags support
		by the driver for conversions.
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		<literal>fdwSupport</literal> (the same as the one returned from
		<function>acmDriverDetails</function>).
	      </para>
	    </listitem>
	  </itemizedlist>
	</para>

	<para>
	  The <literal>cFilterTags</literal>,
	  <literal>cFormatTags</literal>,
	  <literal>fdwSupport</literal> are the same values as the
	  ones returned from <function>acmDriverDetails</function> 
	  function.
	</para>
      </sect2>
    </sect1>

    <sect1 id="msvfw32">
      <title>MS Video Dlls</title>

      <sect2>
	<title>Contents</title>

	<para>
	  The MSVFW32 (and its 16 bit sibbling MSVIDEO) provide
	  encode/decode video streams. Those DLLs only implement the
	  proper switch between a caller and a driver providing the
	  implementation of the requested format coding/decoding
	  operation.
	</para>
	
	<para>
	  There's nothing specific in Wine's implementation compared
	  to Windows' one. Here's however a list of the builtin
	  decoding drivers:
	  <table frame="all">
	    <title>Wine VIDC drivers</title>
	    <tgroup cols="2" align="left" colsep="1" rowsep="1">
	      <thead>
		<row>
		  <entry>Name</entry>
		  <entry>Provides</entry>
		</row>
	      </thead>
	      <tbody>
		<row>
		  <entry>msrle32</entry>
		  <entry>Microsoft's RLE (Run-Length encoded)</entry>
		</row>
		<row>
		  <entry>msvidc32</entry>
		  <entry>Microsoft's Video-1</entry>
		</row>
		<row>
		  <entry>iccvid</entry>
		  <entry>Radius Cinepak Video Decoder</entry>
		</row>
	      </tbody>
	    </tgroup>
	  </table>
	</para>

	<para>
	  Note that Wine also supports native video codecs as well.
	</para>

	<para>
	  All builtin VIDC drivers are 32 bit Unicode DLLs
	</para>

      </sect2>

    </sect1>

    <sect1 id="mm-conf">
      <title>Multimedia configuration</title>

      <para>
	Unfortunately, multimedia configuration evolved over time:
	<itemizedlist>
	  <listitem>
	    <para>
	      In the early days on Windows 3.x, configuration was
	      stored in <filename>system.in</filename> file, under
	      various sections (<literal>[drivers]</literal> for low
	      level drivers, <literal>[mci]</literal>
	      (resp. <literal>[mci32]</literal>) for 16 bit (resp. 32
	      bit) MCI drivers...).
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      With the apparition of the registry, in Windows 95,
	      configuration as been duplicated there, under the key
<screen>
HKLM\System\CurrentControlSet\Control\MediaResources
</screen>
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      Windows NT also adopted the registry, but decided to
	      store the configuration information under another key
	      than Windows 9x did.
<screen>
HKLM\Software\Microsoft\Windows NT\CurrentVersion
</screen>
	      And with a different layout of keys and values beneath
	      this key.
	    </para>
	  </listitem>
	</itemizedlist>
      </para>

      <para>
	Currently, Wine tries to load first a driver (low-level or
	MCI) from the NT registry settings. If it fails, it will try
	the <filename>system.ini</filename> configuration.
      </para>
      
      <para>
	An out-of-the-box configuration is provided in
	<filename>wine.inf</filename>, and shall be stored in registry
	and <filename>system.ini</filename> at Wine installation
        time. It will setup correctly the MCI drivers' configuration
	(as well as the wave and MIDI mappers). As the low-level
	drivers depend on hardware, their setup will be handled by
	<filename>winecfg</filename>.
      </para>

      <table frame="all">
	<title>Wine multimedia configuration scheme</title>
	<tgroup cols="5" align="left" colsep="1" rowsep="1">
	  <thead>
	    <row>
	      <entry>Driver</entry>
	      <entry>Read from NT registry</entry>
	      <entry>Read from <filename>system.ini</filename></entry>
	      <entry>Setup by <filename>wine.inf</filename></entry>
	      <entry>Setup by <filename>winecfg</filename></entry>
	    </row>
	  </thead>
	  <tbody>
	    <row>
	      <entry>MCI drivers</entry>
	      <entry>Yes (1)</entry>
	      <entry>Yes (2)</entry>
	      <entry>Yes</entry>
	      <entry>No</entry>
	    </row>
	    <row>
	      <entry>Wave and MIDI mappers</entry>
	      <entry>Yes</entry>
	      <entry>No</entry>
	      <entry>Yes</entry>
	      <entry>No</entry>
	    </row>
	    <row>
	      <entry>Hardware-bound low level drivers</entry>
	      <entry>Yes</entry>
	      <entry>No</entry>
	      <entry>No</entry>
	      <entry>Yes</entry>
	    </row>
	    <row>
	      <entry>ACM and VIDC drivers (audio & video codecs)</entry>
	      <entry>No</entry>
	      <entry>Yes</entry>
	      <entry>Yes</entry>
	      <entry>No</entry>
	    </row>
	  </tbody>
	</tgroup>
      </table>

      <para>
	This will allow most settings to be correctly loaded and
	handled. However, it won't if an app tries to search directly
	the registry for the actual configuration, as the three
	potential configuration places may not be in sync.
      </para>

      <para>
	It still lacks a correct installation scheme (as any
	multimedia device under Windows), so that all the correct
	keys are created in the registry. This requires an advanced
	model since, for example, the number of wave out devices can
	only be known on the destination system (depends on the
	sound card driven by the OSS interface).
      </para>

      <para>
	The following sections describe which type of information
	(depending on the location) Wine's multimedia DLLs understand.
      </para>

      <sect2>
	<title>NT configuration</title>

	<para>
	  Under the 
	  <screen>
HKLM\Software\Microsoft\Windows NT\CurrentVersion
	  </screen>
	  key, are stored the names of the DLLs to be loaded for each
	  MCI driver name:
	  <screen>
	    "cdaudio"="mcicda.drv"
	    "sequencer"="mciseq.drv"
	    "waveaudio"="mciwave.drv"
	    "avivideo"="mciavi.drv"
	    "videodisc"="mcipionr.drv"
	    "vcr"="mcivisca.drv"
	    "MPEGVideo"="mciqtz.drv"
	  </screen>
	</para>
      </sect2>

      <sect2>
	<title><filename>system.ini</filename></title>

	<para>
	  Wine will read the MCI drivers from the
	  <literal>[mci]</literal> or <literal>[mci32]</literal>
	  section. Wine won't make any difference between the two.
	</para>

	<para>
	  Here's a sample configuration:
	  <screen>
   [mci]
   cdaudio=mcicda.drv
   sequencer=mciseq.drv
   waveaudio=mciwave.drv
   avivideo=mciavi.drv
   videodisc=mcipionr.drv
   vcr=mcivisca.drv
   MPEGVideo=mciqtz.drv
	  </screen>
	</para>

	<para>
	  ACM drivers' configuration is read (only so far) from the
	  <filename>system.ini</filename> (and setup at Wine
	  installation from the <filename>wine.inf</filename> file).
	  <screen>
    [drivers32]
    MSACM.imaadpcm=imaadp32.acm
    MSACM.msadpcm=msadp32.acm
    MSACM.msg711=msg711.acm
    MSACM.winemp3=winemp3.acm
	  </screen>
	</para>

	<para>
	  Video (aka vidc) drivers' configuration is read (only so
	  far) from the <filename>system.ini</filename> (and setup at
	  Wine installation from the <filename>wine.inf</filename>
	  file).
	  <screen>
    [drivers32]
    VIDC.MRLE=msrle32.dll
    VIDC.MSVC=msvidc32.dll
    VIDC.CVID=iccvid.dll
	  </screen>
	</para>

	<para>
	  See also the configuration part of the User's Guide for
	  other information on low level drivers.
	</para>

      </sect2>

      <sect2>
	<title>Per driver/DLL configuration</title>
	
	<sect3>
	  <title>Midi mapper</title>

	  <para>
	    The Midi mapper configuration is the same as on Windows
	    9x. Under the key:
	  <screen>
HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Multimedia\MIDIMap
	  </screen>
	    if the <literal>UseScheme</literal> value is not set, or
	    is set to a null value, the MIDI mapper will always use
	    the driver identified by the
	    <literal>CurrentInstrument</literal> value. Note: Wine
	    (for simplicity while installing) allows to define
	    <literal>CurrentInstrument</literal> as
	    <literal>#n</literal> (where n is a number), whereas
	    Windows only allows the real device name here. If
	    <literal>UseScheme</literal> is set to a non null value,
	    <literal>CurrentScheme</literal> defines the name of the
	    scheme to map the different channels.  All the schemes are
	    available with keys like 
	    <screen>
HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\MediaProperties\PrivateProperties\Midi\Schemes\%name_of_scheme%
	    </screen>
	    For every scheme, under this key, will be a sub-key (which
	    name is usually a two digit index, starting at 00). Its
	    default value is the name of the output driver, and the
	    value <literal>Channels</literal> lists all channels (of
	    the 16 standard MIDI ones) which have to be copied to this
	    driver.
	  </para>

	  <para>
	    To provide enhanced configuration and mapping
	    capabilities, each driver can define under the key
	    <screen>
HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\MediaProperties\PrivateProperties\Midi\Ports\%driver_name%
	    </screen>
	    a link to and <filename>.IDF</filename> file which allows
	    to remap channels internally (for  example 9 -&gt; 16), to
	    change instruments identification, event controllers
	    values. See the source file
	    <filename>dlls/winmm/midimap/midimap.c</filename> for the
	    details (this isn't implemented yet).
	  </para>

	</sect3>

      </sect2>

    </sect1>

  </chapter>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-parent-document:("wine-devel.sgml" "set" "book" "part" "chapter" "")
End:
-->