diff --git a/documentation/configuring.sgml b/documentation/configuring.sgml
index 7f49ef0c6b5..923b995b80d 100644
--- a/documentation/configuring.sgml
+++ b/documentation/configuring.sgml
@@ -41,6 +41,11 @@
Wine's DLL Usage
+
+
+ Wine's Multimedia drivers and DLL configuration
+
+
@@ -143,6 +148,11 @@
no
Console settings
+
+ [WinMM]
+ yes
+ Multimedia settings
+
@@ -167,7 +177,7 @@
-"Type" = "floppy|hd|cdrom|network" <--- the |'s mean "Type = "<one of the options>"
+"Type" = "floppy|hd|cdrom|network" <--- the |'s mean "Type = '<one of the options>'"
@@ -777,6 +787,48 @@ OPTIONAL:
Sets the program to automatically be run at startup every time.
+
+
+ The [WinMM] Section
+
+ [WinMM] is used to define which multimedia drivers have to be loaded. Since
+ those drivers may depend on the multimedia interfaces available on your sustem
+ (OSS, Alsa... to name a few), it's needed to be able to configure which driver
+ has to be loaded.
+
+
+
+ The content of the section looks like:
+
+[WinMM]
+"Drivers" = "wineoss.drv"
+"WaveMapper" = "msacm.drv"
+"MidiMapper" = "midimap.drv"
+
+ All the keys must be defined:
+
+
+
+ The "Drivers" key is a ';' separated list of modules name, each of
+ them containing a low level driver. All those drivers will be loaded
+ when MMSYSTEM/WINMM is started and will provide their inner features.
+
+
+
+
+ The "WaveMapper" represents the name of the module containing the Wave
+ Mapper driver. Only one wave mapper can be defined in the system.
+
+
+
+
+ The "MidiMapper" represents the name of the module containing the Midi
+ Mapper driver. Only one Midi mapper can be defined in the system.
+
+
+
+
+
diff --git a/documentation/multimedia.sgml b/documentation/multimedia.sgml
new file mode 100644
index 00000000000..304b56d12e0
--- /dev/null
+++ b/documentation/multimedia.sgml
@@ -0,0 +1,1302 @@
+
+ Wine and Multimedia
+
+
+ This file contains information about the implementation of the
+ multimedia layer of WINE.
+
+
+
+ The implementation can be found in the dlls/winmm/ directory (and in
+ many of its subdirectories), but also in dlls/msacm/ (for the
+ audio compression/decompression manager) and dlls/msvideo/ (for the
+ video compression/decompression manager).
+
+
+
+ Written by &name-eric-pouech; &email-eric-pouech;
+ (Last updated: 02/16/2001)
+
+
+
+ Overview
+
+
+ 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).
+
+
+
+ The low level layer may depend on current hardware and OS services
+ (like OSS on Unix). Mid level (MCI) and high level layers must be
+ written independently from the hardware and OS services.
+
+
+
+ There are two specific low level drivers (one for wave input/output,
+ another one for MIDI output only), whose role is:
+
+
+ help choosing one low level driver between many
+
+
+
+ add the possibility to convert streams (ie ADPCM => PCM)
+
+
+
+
+ add the possibility to filter a stream (adding echo, equalizer...
+ to a wave stream), or modify the instruments that have to be
+ played (MIDI).
+
+
+
+
+
+
+ All of those components are defined as DLLs (one by one).
+
+
+
+
+
+ Low level layers
+
+
+ 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.
+
+
+
+ The following low level layers are implemented (as built-in DLLs):
+
+
+
+ (Wave form) Audio
+
+
+ MMSYSTEM and WINMM call the real low level audio driver using the
+ wodMessage/widMessage which handles the different requests.
+
+
+
+ OSS implementation
+
+
+ The low level audio driver is currently only implemented for the
+ OpenSoundSystem (OSS) as supplied in the Linux and FreeBSD kernels by
+ 4Front Technologies.
+ The presence of this driver is checked by configure (depends on the
+ <sys/soundcard.h> file). Source code resides in
+ dlls/winmm/wineoss/audio.c.
+
+
+
+ The implementation contains all features commonly used, but has
+ several problems (see TODO list).
+
+
+
+ Note that some Wine specific flag has been added to the wodOpen function,
+ so that the dsound DLL can share the /dev/dsp access. Currently, this
+ only provides mutual exclusion for both DLLs. Future extension could add
+ a virtual mixer between the two output streams.
+
+
+ TODO:
+
+
+
+ verify all functions for correctness
+
+
+
+
+ Add virtual mixer between wave-out and dsound interfaces.
+
+
+
+
+
+
+
+
+ Other sub systems
+
+
+ No other is available. Could think of Sun Audio, remote audio systems
+ (using X extensions, ...), ALSA, EsounD, ArTs...
+
+
+
+
+
+
+
+ MIDI
+
+
+ MMSYSTEM and WINMM call the low level driver functions using the
+ midMessage and the modMessage functions.
+
+
+
+ OSS driver
+
+
+ The low level audio driver is currently only implemented for the
+ OpenSoundSystem (OSS) as supplied in the Linux and FreeBSD kernels by
+ 4Front Technologies.
+ The presence of this driver is checked by configure (depends on the
+ <sys/soundcard.h> file, and also some specific defines because
+ MIDI is not supported on all OSes by OSS). Source code resides in
+ dlls/winmm/wineoss/midi.c
+
+
+
+ Both Midi in and Midi out are provided. The type of MIDI devices
+ supported is external MIDI port (requires an MIDI capable device -
+ keyboard...) and OPL/2 synthesis (the OPL/2 patches for all
+ instruments are in midiPatch.c).
+
+
+ TODO:
+
+
+
+ use better instrument definition for OPL/2 (midiPatch.c) or use
+ existing instrument definition (from playmidi or kmid) with a
+ .winerc option
+
+
+
+
+ have a look at OPL/3 ?
+
+
+
+
+ implement asynchronous playback of MidiHdr
+
+
+
+
+ implement STREAM'ed MidiHdr (question: how shall we share the code
+ between the midiStream functions in MMSYSTEM/WINMM and the code
+ for the low level driver)
+
+
+
+
+ use a more accurate read mechanism than the one of snooping on
+ timers (like select on fd)
+
+
+
+
+
+
+
+
+ Other sub systems
+
+
+ Could support other MIDI implementation for other sub systems (any
+ idea here ?)
+
+
+
+ Could also implement a software synthesizer, either inside Wine or
+ using using MIDI loop back devices in an external program (like
+ timidity). The only trouble is that timidity is GPL'ed...
+
+
+
+
+
+
+
+ Mixer
+
+
+ MMSYSTEM and WINMM call the low level driver functions using the
+ mixMessage function.
+
+
+
+ OSS implementation
+
+
+ The current implementation uses the OpenSoundSystem mixer, and resides
+ in dlls/winmm/wineoss/mixer.c
+
+
+ TODO:
+
+
+
+ implement notification mechanism when state of mixer's controls
+ change
+
+
+
+
+
+
+
+
+ Other sub systems
+
+ TODO:
+
+
+
+ implement mixing low level drivers for other mixers (ALSA...)
+
+
+
+
+
+
+
+
+
+
+ Aux
+
+
+ The AUX low level driver is the predecessor of the mixer driver
+ (introduced in Win 95).
+
+
+
+ OSS driver
+
+
+ The implementation uses the OSS mixer API, and is incomplete.
+
+
+ TODO:
+
+
+
+ verify the implementation
+
+
+
+
+ check with what is done in mixer
+
+
+
+
+ open question: shall we implement it on top of the low level mixer
+ functions ?
+
+
+
+
+
+
+
+
+
+
+
+ Wine OSS
+
+
+ All the OSS dependent functions are stored into the WineOSS DLL. It still
+ lack 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). A solution would be to install all the multimedia
+ drivers through the SETUPX DLL; this is not doable yet (the multimedia
+ extension to SETUPX isn't written yet).
+
+
+
+
+
+ Joystick
+
+
+ The API consists of the joy* functions found in dlls/winmm/joystick/joystick.c.
+ The implementation currently uses the Linux joystick device driver
+ API. It is lacking support for enhanced joysticks and has not been
+ extensively tested.
+
+
+ TODO:
+
+
+
+ better support of enhanced joysticks (Linux 2.2 interface is available)
+
+
+
+
+ support more joystick drivers (like the XInput extension)
+
+
+
+
+ should load joystick DLL as any other driver (instead of hardcoding)
+ the driver's name, and load it as any low lever driver.
+
+
+
+
+
+
+
+
+ Wave mapper (msacm.drv)
+
+
+ The Wave mapper device allows to load on-demand 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.
+
+
+
+ Built-in
+
+
+ A first working implementation for wave out as been provided (wave in
+ exists, but doesn't allow conversion).
+
+
+
+ Wave mapper driver implementation can be found in dlls/winmm/wavemap/
+ directory. This driver heavily relies on MSACM and MSACM32 DLLs which
+ can be found in dlls/msacm and dlls/msacm32. Those DLLs load ACM
+ drivers which provide the conversion to PCM format (which is normally
+ supported by low level drivers). ADPCM, MP3... fit into the category
+ of non PCM formats.
+
+
+
+ There is currently no built-in ACM driver in Wine, so you must use
+ native ones if you're looking for non PCM playback.
+
+
+ TODO:
+
+
+
+ check for correctness and robustness
+
+
+
+
+
+
+
+ Native
+
+
+ Seems to work quite ok (using of course native MSACM/MSACM32 DLLs)
+ Some other testings report some issues while reading back the registry
+ settings.
+
+
+
+
+
+
+
+ MIDI mapper
+
+
+ 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 definition (XM, GM...). It also
+ permits to output on a per channel basis to different MIDI renderers.
+
+
+
+ Built-in
+
+
+ A built-in MIDI mapper can be found in dlls/winmm/midimap/. It partly
+ provides the same functionnality 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).
+
+
+ TODO:
+
+
+
+ implement the Midi mapper features (instrument on the fly modification)
+ if it has to be done as under Windows, it required parsing the midi
+ configuration files (didn't find yet the specs)
+
+
+
+
+
+
+
+
+ Native
+
+
+ The native midimapper from Win 98 works, but it requires a bunch of
+ keys in the registry which are not part of the Wine source yet.
+
+
+ TODO:
+
+
+
+ add native midimapper keys to the registry to let it run. This
+ will require proper multimedia driver installation routines.
+
+
+
+
+
+
+
+
+
+
+
+
+ Mid level drivers (MCI)
+
+
+ The mid level drivers are represented by some common API functions,
+ mostly mciSendCommand and mciSendString. See status in chapter 3 for
+ more information. WINE implements several MCI mid level drivers
+ (status is given for both built-in and native implementation):
+
+
+ TODO: (apply to all built-in MCI drivers)
+
+
+
+ use MMSYSTEM multitasking caps instead of the home grown
+
+
+
+
+
+
+
+ CDAUDIO
+
+
+ Built-in
+
+
+ The currently best implementation is the MCI CDAUDIO driver that can
+ be found in dlls/winmm/mcicda/mcicda.c. The implementation is mostly
+ complete, there have been no reports of errors. It makes use of
+ misc/cdrom.c Wine internal cdrom interface.
+ This interface has been ported on Linux, FreeBSD and NetBSD. (Sun
+ should be similar, but are not implemented.)
+
+
+
+ A very small example of a cdplayer consists just of the line
+ mciSendString("play cdaudio",NULL,0,0);
+
+
+ TODO:
+
+
+
+ add support for other cdaudio drivers (Solaris...)
+
+
+
+
+ add support for multiple cdaudio devices (plus a decent
+ configuration scheme)
+
+
+
+
+ The DLL is not cleanly separated from the NTDLL DLL. The CDROM
+ interface should be exported someway (or stored in a Wine only DLL)
+
+
+
+
+
+
+
+
+ Native
+
+
+ Native MCICDA works also correctly... It uses the MSCDEX traps (on int
+ 2f). However, some commands (like seeking) seem to be broken.
+
+
+
+
+
+
+
+ MCIWAVE
+
+
+ Built-in
+
+
+ The implementation is rather complete and can be found in
+ dlls/winmm/mciwave/audio.c. It uses the low level audio API (although
+ not abstracted correctly).
+
+
+ FIXME:
+
+
+
+ The MCI_STATUS command is broken.
+
+
+
+
+
+ TODO:
+
+
+
+ check for correctness
+
+
+
+
+ better use of asynchronous playback from low level
+
+
+
+
+ better implement non waiting command (without the MCI_WAIT flag).
+
+
+
+
+
+
+
+
+ Native
+
+
+ Native MCIWAVE works also correctly.
+
+
+
+
+
+
+
+ MCISEQ (MIDI sequencer)
+
+
+ Built-in
+
+
+ The implementation can be found in dlls/winmm/mciseq/mcimidi.c. Except
+ from the Record command, should be close to completion (except for non
+ blocking commands, as many MCI drivers).
+
+
+ TODO:
+
+
+
+ implement it correctly
+
+
+
+
+ finish asynchronous commands (especially for reading/record)
+
+
+
+
+ better implement non waiting command (without the MCI_WAIT flag).
+
+
+
+
+ implement the recording features
+
+
+
+
+
+
+
+
+ Native
+
+
+ Native MCIMIDI has been working but is currently blocked by scheduling
+ issues (mmTaskXXX no longer work).
+ FIXME:
+
+
+
+ midiStreamPlay get from time to time an incorrect MidiHdr when
+ using the native MCI sequencer
+
+
+
+
+
+
+
+
+
+
+ MCIANIM
+
+
+ Built-in
+
+
+ The implementation is in dlls/winmm/mcianim/.
+
+
+ TODO:
+
+
+
+ implement it, probably using xanim or something similar.
+
+
+
+
+
+
+
+
+ Native
+
+
+ Native MCIANIM is reported to work (but requires native video DLLs
+ also, even though the built-in video DLLs start to work correctly).
+
+
+
+
+
+
+
+ MCIAVI
+
+
+ Built-in
+
+
+ The implementation is in dlls/winmm/mcianim/. Basic features are present,
+ simple playing is available, even if lots remain to be done. It rather
+ heavily relies on MSVIDEO/MSVFW32 DLLs pair to work.
+
+
+ TODO:
+
+
+
+ finish the implementation
+
+
+
+
+ fix the audio/video synchronisation issue
+
+
+
+
+
+
+
+
+ Native
+
+
+ Native MCIAVI is reported to work (but requires native video DLLs
+ also). Some files exhibit some deadlock issues anyway.
+
+
+
+
+
+
+
+
+
+ High level layers
+
+
+ The rest (basically the MMSYSTEM and WINMM DLLs entry points). It also
+ provides the skeleton for the core functionality for multimedia
+ rendering. 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).
+ Moreover, native DLLs require 16 bit MCI and low level drivers. Wine
+ implements them as 32 bit drivers.
+ MCI and low level drivers can either be 16 or 32 bit for Wine.
+
+
+ TODO:
+
+
+
+ it seems that some program check what's installed in registry
+ against value returned by drivers. Wine is currently broken
+ regarding this point.
+
+
+
+
+ add clean-up mechanisms when process detaches from MM DLLs
+
+
+
+
+ prepare for the 16/32 big split
+
+
+
+
+ check thread-safeness for MMSYSTEM and WINMM entry points
+
+
+
+
+ unicode entry points are badly supported
+
+
+
+
+
+
+ MCI skeleton
+
+
+ Implementation of what is needed to load/unload MCI drivers, and to
+ pass correct information to them. This is implemented in
+ dlls/winmm/mci.c. The mciSendString function uses command strings,
+ which are translated into normal MCI commands as used by
+ mciSendCommand with the help of command tables. The API can be found
+ in dlls/winmm/mmsystem.c and dlls/winmm/mci.c. The functions there
+ (mciOpen,mciSysInfo) handle mid level driver allocation and calls. The
+ implementation is not complete.
+
+
+
+ MCI drivers are seen as regular WINE modules, and can be loaded (with
+ a correct load order between built-in, native, elfdll, so), as any
+ other DLL. Please note, that MCI drivers module names must bear the
+ .drv extension to be correctly understood.
+
+
+
+ The list of available MCI drivers is obtained as follows:
+ 1. key 'mci' in [option] section from .winerc (or wineconf)
+ mci=CDAUDIO:SEQUENCER gives the list of MCI drivers (names, in
+ uppercase only) to be used in WINE.
+ 2. This list, when defined, supersedes the mci key in
+ c:\windows\system.ini
+
+
+
+ Note that native VIDEODISC crashes when the module is loaded, which
+ occurs when the MCI procedures are initialised. Make sure that this is
+ not in the list from above. Try adding:
+ mci=CDAUDIO:SEQUENCER:WAVEAUDIO:AVIVIDEO:MPEGVIDEO
+ to the [options] section of wine.conf.
+
+
+ TODO:
+
+
+
+ correctly handle the MCI_ALL_DEVICE_ID in functions.
+
+
+
+
+ finish mapping 16 <=> 32 of MCI structures and commands
+
+
+
+
+ MCI_SOUND is not handled correctly (should not be sent to MCI
+ driver => same behavior as MCI_BREAK)
+
+
+
+
+ implement auto-open feature (ie, when a string command is issued
+ for a not yet opened device, MCI automatically opens it)
+
+
+
+
+
+
+
+
+ MCI multi-tasking
+
+
+ Multi-tasking capabilities used for the MCI drivers are provided in
+ dlls/winmm/mmsystem.c.
+
+
+ TODO:
+
+
+
+ mmTaskXXX functions are currently broken because the 16 loader does
+ not support binary command lines => provide Wine's own mmtask.tsk not
+ using binary command line.
+
+
+
+
+ the Wine native MCI drivers should use the mmThreadXXX API (but since
+ all built-in MCI drivers are 32 bit, this would require a special
+ flag to mark 32 bit entry points)
+
+
+
+
+
+
+
+
+ Timers
+
+
+ It currently uses a service thread, run in the context of the calling
+ process, which should correctly mimic Windows behavior.
+
+
+ TODO:
+
+
+
+ Check if minimal time is satisfactory for most programs.
+
+
+
+
+ current implementation may let a timer tick (once) after it has
+ been destroyed
+
+
+
+
+
+
+
+
+ MMIO
+
+
+ The API consists of the mmio* functions found in mdlls/winmm/mmio.c.
+ Seems to work ok in most of the cases. There's some linear/segmented
+ issues with 16 bit code. There are also some bugs when writting MMIO
+ files.
+
+
+
+
+
+ sndPlayXXX functions
+
+
+ Seem to work correctly.
+
+
+
+
+
+
+
+ Multimedia configuration
+
+
+ Currently, multimedia configuration heavily relies on Win 3.x
+ configuration model.
+
+
+
+ Drivers
+
+
+ Since all multimedia drivers (MCI, low level ones, ACM drivers,
+ mappers) are, at first, drivers they need to appear in the [mci] or
+ [mci32] section of the system.ini file.
+ Since all drivers are, at first, DLLs, you can choose to load their
+ Wine's (built-in) or Windows (native) version.
+
+
+
+
+
+ MCI
+
+
+ A default [mci] section (in system.ini) looks like (see the note above
+ on videodisc):
+
+
+
+ [mci]
+ cdaudio=mcicda.drv
+ sequencer=mciseq.drv
+ waveaudio=mciwave.drv
+ avivideo=mciavi.drv
+ videodisc=mcipionr.drv
+ vcr=mcivisca.drv
+ MPEGVideo=mciqtz.drv
+
+
+
+ By default, the list of loadable MCI drivers will be made of those
+ drivers (in the [mci] section).
+
+
+
+ The list of loadable (recognized) MCI drivers can be altered in the
+ [option] section of wine.conf, like:
+ mci=CDAUDIO:SEQUENCER:WAVEAUDIO:AVIVIDEO:MPEGVIDEO
+
+
+ TODO:
+
+
+
+ use a default registry setting to bypass this (ugly) configuration
+ model
+
+
+
+
+
+
+
+
+ Low level drivers
+
+
+ Configuration of low level drivers is done with the Wine configuration file.
+ Default keys are provided in winedefault.reg.
+
+
+
+ The registry keys used here differ from the Windows' one. Using the Windows' one
+ would require implementing something equivalent to a (real) driver installation.
+ Even if this would be necessary in a few cases (mainly using MS native multimedia)
+ modules, there's no real need so far (or it hasn't been run into yet).
+
+
+
+ See the configuration part of the User's Guide for more details.
+
+
+
+
+
+ Midi mapper
+
+
+ The Midi mapper configuration is the same as on Windows 9x. Under the key
+
+HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Multimedia\MIDIMap
+
+ if the 'UseScheme' value is not set, or is set to a null value, the midi
+ mapper will always use the driver identified by the 'CurrentInstrument'
+ value. Note: Wine (for simplicity while installing) allows to define
+ 'CurrentInstrument' as "#n" (where n is a number), whereas Windows only
+ allows the real device name here. If UseScheme is set to a non null value,
+ 'CurrentScheme' defines the name of the scheme to map the different channels.
+ All the schemes are available with keys like
+
+HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\MediaProperties\PrivateProperties\Midi\Schemes\%name_of_scheme%
+
+ 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 'Channels' lists all channels (of the 16
+ standard MIDI ones) which have to be copied to this driver.
+
+
+
+ To provide enhanced configuration and mapping capabilities, each driver
+ can define under the key
+
+HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\MediaProperties\PrivateProperties\Midi\Ports\%driver_name%
+
+ a link to and .IDF file which allows to remap channels internally (for
+ example 9 -> 16), to change instruments identification, event
+ controlers values. See the source file dlls/winmm/midimap/midimap.c
+ for the details (this isn't implemented yet).
+
+
+
+
+ ACM
+
+
+ To be done (use the same mechanism as MCI drivers configuration).
+
+
+
+
+
+ VIDC
+
+
+ To be done (use the same mechanism as MCI drivers configuration).
+
+
+
+
+
+
+
+ Multimedia architecture
+
+
+ Windows 9x multimedia architecture
+
+
+ |
+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
+ | +-------------------------------+
+ |
+
+
+
+ The important points to notice are:
+
+
+
+ all drivers (and most of the core code) is 16 bit
+
+
+
+
+ all hardware (or most of it) dependant code reside in the kernel
+ space (which is not surprising)
+
+
+
+
+
+
+
+
+ Wine multimedia architecture
+
+
+ |
+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>||<32>||<16
+ | | vv |<32>| vv ||
++---------+ | | +-------------+ +----------+
+|HW driver|<------->| *.drv | | mci*.drv |
++---------+ | | +--------------+ +-----------+
+ | | | msacm.drv | | mciwave |
+ | | +--------------+ +-----------+
+ | | | midimap.drv | | mcimidi |
+ | | +-------------+ +-----------+
+ | | Low-level drivers | ... | MCI drivers
+ | | +----------+
+ | | |
+ | | |<32/16
+ | +-------------------------------+
+ |
+
+
+
+ From the previous drawings, the most noticeable differences are:
+
+
+
+ low-level drivers can either be 16 or 32 bit
+
+
+
+
+ MCI drivers can either be 16 or 32 bit
+
+
+
+
+ MMSystem and WinMM will be hosted in a single elfglue library
+
+
+
+
+ no link between the MMSystem/WinMM pair on kernel space shall
+ exist. For example, there will be a low level driver to talk to a
+ UNIX OSS (Open Sound System) driver
+
+
+
+
+ all built-in drivers (low-level and MCI) will be written as 32 bit
+ drivers
+
+
+
+
+ all native drivers will be 16 bits drivers
+
+
+
+
+
+
+
+
+
+
+ MS ACM Dlls
+
+
+ Contents
+
+ tbd
+
+
+
+ Status
+
+ tbd
+
+
+
+ Caching
+
+
+ The MSACM/MSACM32 keeps some data cached for all known ACM
+ drivers. Under the key
+
+ Software\Microsoft\AudioCompressionManager\DriverCache\<driver
+ name>
+
+ are kept for values:
+
+
+
+ aFormatTagCache which contains an array of
+ DWORD. There are two DWORDs per cFormatTags
+ entry. The first DWORD contains a format tag
+ value, and the second the associated maximum
+ size for a WAVEFORMATEX structure.
+ (Fields dwFormatTag and cbFormatSize from
+ ACMFORMATDETAILS)
+
+
+
+
+ cFilterTags contains the number of tags supported by the driver
+ for filtering.
+
+
+
+
+ cFormatTags contains the number of tags support
+ by the driver for conversions.
+
+
+
+
+ fdwSupport (the same as the one returned from
+ acmDriverDetails).
+
+
+
+
+
+
+ The cFilterTags, cFormatTags, fdwSupport are the same
+ values as the ones returned from acmDriverDetails
+ function.
+
+
+
+
+
+
+
+
diff --git a/documentation/status/multimedia b/documentation/status/multimedia
deleted file mode 100644
index 36fd01d11a9..00000000000
--- a/documentation/status/multimedia
+++ /dev/null
@@ -1,598 +0,0 @@
-
- This file contains information about the implementation of the
- multimedia layer of WINE. The libraries consist of MMSYSTEM.DLL
- (win16), WINMM.DLL (win32) and some (abstracted, not Windows
- compatible) low level drivers.
-
- The implementation can be found in the dlls/winmm/ sub directory.
-
-0. Overview
-===========
-
- 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 may depend on current hardware and OS services (like
- OSS). Mid level (MCI) and high level must be written independently
- from the hardware and OS services.
- There are two specific low level drivers call mappers (for wave and
- +midi) whose role is to :
- * help choosing one low level driver between many
- * add the possibility to convert stream (ie ADPCM => PCM)
- * add the possibility to filter a stream (adding echo, equalizer...)
-
- All of those components are defined as DLLs (one by one) and are
- candidate for dllglue migration.
-
-1. Low level layers
-===================
-
- 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.
-
- The following low level layers are implemented:
-
-1.1 (Wave form) Audio
----------------------
-
- MMSYSTEM and WINMM call the real low level audio driver using the
- wodMessage/widMessage which handles the different requests.
-
- 1.1.1 OSS implementation
-
- The low level audio driver is currently only implemented for the
- OpenSoundSystem (OSS) as supplied in the Linux and FreeBSD kernels by
- [1]4Front Technologies. The presence of this driver is checked by
- configure (depends on the file). Source code resides
- in dlls/winmm/wineoss/audio.c,
-
- The implementation contains all features commonly used, but has
- several problems (see TODO list).
-
- TODO:
- * add asynchronous reads [recording] (must use threads) as done for
- writes [playing]
- * verify all functions for correctness
- * looping of WaveHdr will fail
- * share access to /dev/dsp with dsound interface (either on a
- descriptor basis, or using a virtual mixer between different wave
- inputs. EsounD provides this type of capability).
-
- 1.1.2 Other sub systems
-
- None are available. Could think of Sun Audio, remote audio systems
- (using X extensions, ...), ALSA, EsounD
-
-1.2 MIDI
---------
-
- MMSYSTEM and WINMM call the low level driver functions using the
- midMessage and the modMessage functions.
-
- 1.2.1 OSS driver
-
- The low level audio driver is currently only implemented for the
- OpenSoundSystem (OSS) as supplied in the Linux and FreeBSD kernels by
- [1]4Front Technologies . The presence of this driver is checked by
- configure (depends on the file, and also some
- specific defines because MIDI is not supported on all OSes by OSS).
- Source code resides in dlls/winmm/wineoss/midi.c
-
- Both Midi in and Midi out are provided. The type of MIDI devices
- supported is external MIDI port (requires an MIDI capable device -
- keyboard...) and OPL/2 synthesis (the OPL/2 patches for all
- instruments are in midiPatch.c).
-
- TODO:
- * use better instrument definition for OPL/2 (midiPatch.c) or use
- existing instrument definition (from playmidi or kmid) with a
- .winerc option
- * have a look at OPL/3 ?
- * implement asynchronous playback of MidiHdr
- * implement STREAM'ed MidiHdr (question: how shall we share the code
- between the midiStream functions in MMSYSTEM/WINMM and the code
- for the low level driver)
- * use a more accurate read mechanism than the one of snooping on
- timers (like select on fd)
-
- 1.2.2 Other sub systems
-
- Could support other midi implementation for other sub systems (any
- idea here ?)
-
- Could also implement a software synthesizer, either inside Wine or
- using using MIDI loop back devices in an external program (like
- timidity). The only trouble is that timidity is GPL'ed...
-
-1.3 Mixer
----------
-
- MMSYSTEM and WINMM call the low level driver functions using the
- mixMessage function.
-
- 1.3.1 OSS implementation
-
- The current implementation uses the OpenSoundSystem mixer, and resides
- in dlls/winmm/wineoss/mixer.c
-
- TODO:
- * implement notification mechanism when state of mixer's controls
- change
-
-1.3.2 Other sub systems
-
- TODO:
- * implement mixing low level drivers for other mixers (ALSA...)
-
-1.4 AUX
--------
-
- The AUX low level driver is the predecessor of the mixer driver
- (introduced in Win 95).
-
- 1.4.1 OSS driver
-
- The implementation uses the OSS mixer API, and is incomplete.
-
- TODO:
- * verify the implementation
- * check with what is done in mixer
- * open question: shall we implement it on top of the low level mixer
- functions ?
-
-1.5 Joystick
-------------
-
- The API consists of the joy* functions found in dlls/winmm/joystick.c.
- The implementation currently uses the Linux joystick device driver
- API. It is lacking support for enhanced joysticks and has not been
- extensively tested.
-
- TODO:
- * better support of enhanced joysticks
- * support more joystick drivers (like the XInput extension)
- * should make joystick a separate DLL (impact also on
- WINMM/MMSYSTEM), or a real low level driver, as it is on Windows
-
-
-1.6 Wave mapper (msacm.drv)
----------------------------
-
- The Wave mapper device allows to load on-demand 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.
-
-
- 1.6.1 Build-in
-
- A first working implementation for wave out as been provided (wave in
- exists, but doesn't allow conversion).
- Wave mapper driver implementation can be found in dlls/winmm/wavemap/
- directory. This driver heavily relies on MSACM and MSACM32 DLLs which
- can be found in dlls/msacm and dlls/msacm32. Those DLLs load ACM
- drivers which provide the conversion to PCM format (which is normally
- supported by low level drivers). ADPCM, MP3... fit into the category
- of non PCM formats.
-
- There is currently no builtin ACM driver in Wine, so you must use
- native ones if you're looking for non PCM playback.
-
- In order to use native ACM drivers to play non PCM files, you must use
- -dll msacm,msacm32,msacm.drv=b. Note that this code is not complete
- yet, and may cause problems. sndrec32 and mplayer from Win95 appear to
- work reasonably well though.
-
- TODO:
- * do wave in
- * check for correctness and robustness
-
- 1.6.2 Native
-
- Seems to work quite ok (using of course native MSACM/MSACM32 DLLs)
- Some other testings report some issues while reading back the registry
- settings.
-
-1.7 MIDI mapper
----------------
-
- 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 definition (XM, GM...). It also
- permits to output on a per channel basis to different MIDI renderers.
-
-
- 1.7.1 Built-in
-
- A builtin MIDI mapper can be found in dlls/winmm/midimap. It only
- provides the pickup of an existing MIDI low level driver for playback.
-
- TODO:
- * implement the Midi mapper features (channel / instrument on the
- fly modification)
-
- 1.7.2 Native
-
- Currently, the native midimapper i'm using is not working (mainly
- because it reads low level drivers configuration from registry).
-
- TODO:
- * let native midimapper driver load
-
-2. Mid level drivers (MCI)
-==========================
-
- The mid level drivers are represented by some common API functions,
- mostly mciSendCommand and mciSendString. See status in chapter 3 for
- more information. WINE implements several MCI mid level drivers
- (status is given for both built-in and native implementation):
-
- TODO: (apply to all built-in MCI drivers)
- * use mmsystem multitasking caps instead of the home grown
-
-2.1 CDAUDIO
------------
-
- 2.1.1 Built-in
-
- The currently best implementation is the MCI CDAUDIO driver that can
- be found in dlls/winmm/mcicda/mcicda.c. The implementation is mostly
- complete, there have been no reports of errors. It makes use of
- misc/cdrom.c Wine internal cdrom interface.
- This interface has been ported on Linux, FreeBSD and NetBSD. (Sun
- should be similar, but are not implemented.)
-
- A very small example of a cdplayer consists just of the line
- mciSendString("play cdaudio",NULL,0,0);
-
- TODO:
- * add support for other cdaudio drivers (Solaris...)
- * add support for multiple cdaudio devices
-
- 2.1.2 Native
-
- Native MCICDA works also correctly... It uses the mscdex traps (on int
- 2f).
-
-2.2 MCIWAVE
------------
-
- 2.2.1 Built-in
-
- The implementation is rather complete and can be found in
- dlls/winmm/mciwave/audio.c. It uses the low level audio API (although
- not abstracted correctly).
-
- FIXME:
- * The MCI_STATUS command is broken.
-
- TODO:
- * check for correctness
- * better use of asynchronous playback from low level
- * record has to be checked
- * MCI_CUE command is broken
- * better implement non waiting command (without the MCI_WAIT flag).
-
- 2.2.2 Native
-
- Native MCIWAVE works also correctly.
-
-2.3 MCISEQ (MIDI sequencer)
----------------------------
-
- 2.3.1 Built-in
-
- The implementation can be found in dlls/winmm/mciseq/mcimidi.c. Except
- from the Record command, should be close to completion (except for non
- blocking commands).
-
- TODO:
- * implement it correctly
- * finish asynchronous commands (especially for reading/record)
- * better implement non waiting command (without the MCI_WAIT flag).
-
- 2.3.2 Native
-
- Native MCIMIDI has been working but is currently blocked by scheduling
- issues (mmTaskXXX no longer work).
-
- FIXME:
- * midiStreamPlay get from time to time an incorrect MidiHdr when
- using the native MCI sequencer
-
-2.4 MCIANIM
------------
-
- 2.4.1 Built-in
-
- The implementation consists of stubs and is in dlls/winmm/mcianim.c.
-
- TODO:
- * implement it, probably using xanim or something similar.
-
- 2.4.2 Native
-
- Native MCIANIM is reported to work (but requires native video DLLs
- also).
-
-2.5 MCIAVI
-----------
-
- 2.5.1 Built-in
-
- The implementation consists of stubs and is in
- dlls/winmm/mciavi/mciavi.c.
-
- TODO:
- * implement it, probably using xanim or something similar.
-
-2.5.2 Native
-
- Native MCIAVI is reported to work (but requires native video DLLs
- also). Some files exhibit some deadlock issues anyway.
-
-3 High level layers
-===================
-
- The rest (basically the MMSYSTEM and WINMM DLLs entry points). It also
- provides the skeleton for the core functionality for multimedia
- rendering. 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).
- MCI and low level drivers can either be 16 or 32 bit.
-
- TODO:
- * it seems that some program check what's installed in registry
- against value returned by drivers. Wine is currently broken
- regarding this point.
- * add clean-up mechanisms when process detaches from MM DLLs
- * prepare for the 16/32 big split
- * check thread-safeness for MMSYSTEM and WINMM entry points
- * unicode entry points are badly supported
-
-3.1 MCI skeleton
-----------------
-
- Implementation of what is needed to load/unload MCI drivers, and to
- pass correct information to them. This is implemented in
- dlls/winmm/mci.c. The mciSendString function uses command strings,
- which are translated into normal MCI commands as used by
- mciSendCommand with the help of command tables. The API can be found
- in dlls/winmm/mmsystem.c and dlls/winmm/mci.c. The functions there
- (mciOpen,mciSysInfo) handle mid level driver allocation and calls. The
- implementation is not complete.
- MCI drivers are seen as regular WINE modules, and can be loaded (with
- a correct load order between built-in, native, elfdll, so), as any
- other DLL. Please note, that MCI drivers module names must bear the
- .drv extension to be correctly understood.
- The list of available MCI drivers is obtained as follows:
- 1. key 'mci' in [option] section from .winerc (or wineconf)
- mci=CDAUDIO:SEQUENCER gives the list of MCI drivers (names, in
- uppercase only) to be used in WINE.
- 2. This list, when defined, supersedes the mci key in
- c:\windows\system.ini
-
- Note that native VIDEODISC crashes when the module is loaded, which
- occurs when the MCI procedures are initialised. Make sure that this is
- not in the list from above. Try adding:
- mci=CDAUDIO:SEQUENCER:WAVEAUDIO:AVIVIDEO:MPEGVIDEO
- to the [options] section of wine.conf.
-
- TODO:
- * correctly handle the MCI_ALL_DEVICE_ID in functions.
- * finish mapping 16 <=> 32 of MCI structures and commands
- * MCI_SOUND is not handled correctly (should not be sent to MCI
- driver => same behavior as MCI_BREAK)
- * do not display module warning when failed to 32-bit load a 16 bit
- module when 16 bit load can succeed (and the other way around)
- * implement auto-open feature (ie, when a string command is issued
- for a not yet opened device, MCI automatically opens it)
-
-3.2 MCI multi-tasking
----------------------
-
- Multi-tasking capabilities used for the MCI drivers are provided in
- dlls/winmm/mmsystem.c.
-
- TODO:
-
- mmTaskXXX functions are currently broken because the 16 loader does
- not support binary command lines => provide Wine's own mmtask.tsk not
- using binary command line.
-
- the Wine native MCI drivers should use the mmThreadXXX API and no
- longer use the MCI_AsyncCommand hack.
-
-3.3 Timers
-----------
-
- It currently uses a service thread, run in the context of the calling
- process, which should correctly mimic Windows behavior.
-
- TODO:
- * Check if minimal time is satisfactory for most programs.
- * current implementation may let a timer tick (once) after it has
- been destroyed
-
-3.4 MMIO
---------
-
- The API consists of the mmio* functions found in mdlls/winmm/mmio.c.
- Seems to work ok in most of the cases. There's some linear/segmented
- issues with 16 bit code.
-
-3.5 sndPlayXXX functions
-------------------------
-
- Seem to work correctly.
-
-4 Multimedia configuration
-==========================
-
- Currently, multimedia configuration heavily relies on Win 3.x
- configuration model.
-
-4.1 Drivers
------------
-
- Since all multimedia drivers (MCI, low level ones, ACM drivers,
- mappers) are, at first, drivers they need to appear in the [mci] or
- [mci32] section of the system.ini file.
- Since all drivers are, at first, DLLs, you can choose to load their
- Wine's (builtin) or Windows (native) version.
-
-4.2 MCI
--------
-
- A default [mci] section (in system.ini) looks like (see the note above
- on videodisc):
-
- [mci]
- cdaudio=mcicda.drv
- sequencer=mciseq.drv
- waveaudio=mciwave.drv
- avivideo=mciavi.drv
- videodisc=mcipionr.drv
- vcr=mcivisca.drv
- MPEGVideo=mciqtz.drv
-
- By default, the list of loadable MCI drivers will be made of those
- drivers (in the [mci] section).
-
- The list of loadable (recognized) MCI drivers can be altered in the
- [option] section of wine.conf, like:
- mci=CDAUDIO:SEQUENCER:WAVEAUDIO:AVIVIDEO:MPEGVIDEO
-
- TODO:
-
- use a default registry setting to bypass this (ugly) configuration
- model
-
-4.3 Low level drivers
----------------------
-
- They are currently hardcoded in dlls/winmm/lolvldrv.c.
-
- TODO:
-
- use a default registry setting to provide a decent configuration
- model. this shall also help some programs to work (some of them test
- the names returned by low level drivers with the ones defined and
- installed in the registry)
-
-4.4 ACM
--------
-
- To be done (use the same mechanism as MCI drivers configuration).
-
-5 Multimedia architecture
-=========================
-
-5.1 Windows 9x multimedia architecture
---------------------------------------
-
- |
-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 |
- +--------+ | | +--------------+ +-----------+
- | | | msacmm.drv | | mciwave |
- | | +--------------+ +-----------+
- | | | midimap.drv | | mcimidi |
- | | +-------------+ +-----------+
- | | Low-level drivers | ... | MCI drivers
- | | +----------+
- | | |
- | | |<16
- | +-------------------------------+
- |
-
- The important points to notice are:
- * all drivers (and most of the core code) is 16 bit
- * all hardware (or most of it) dependant code reside in the kernel
- space (which is not surprising)
-
-5.2 Wine multimedia architecture
---------------------------------
-
- |
-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 | | | | MSystem.dll
- | | | mixerXXX | | | | 16 bit
- | | | auxXXX +---+ +---+ mmThread| |
- | | | joyXXX | Call back | mmTask | |
- | | +-----------+-----------+---------+-------------+
- | | | | ^ ^ || ^^
- | | 16>| |<32 |<16>| 16>||<32>||<16
- | | v v |<32>| vv ||
-+---------+ | | +-------------+ +----------+
-|HW driver|<------->| .drv | | mci*.drv |
-+---------+ | | +--------------+ +-----------+
- | | | msacmm.drv | | mciwave |
- | | +--------------+ +-----------+
- | | | midimap.drv | | mcimidi |
- | | +-------------+ +-----------+
- | | Low-level drivers | ... | MCI drivers
- | | +----------+
- | | |
- | | |<32/16
- | +-------------------------------+
- |
-
- From the previous drawings, the most noticeable difference are:
- * low-level drivers can either be 16 or 32 bit
- * MCI drivers can either be 16 or 32 bit
- * MMSystem and WinMM will be hosted in a single elfglue library
- * no link between the MMSystem/WinMM pair on kernel space shall
- exist. For example, there will be a low level driver to talk to a
- UNIX OSS (Open Sound System) driver
- * all built-in drivers (low-level and MCI) will be written as 32 bit
- drivers
- all native drivers will be 16 bits drivers
-
- ______________________________________________________
-
- Last updated: 6, December 1999
- By: Eric Pouech (eric.pouech@wanadoo.fr)
-
-References
-
- 1. http://www.4front-tech.com/
diff --git a/documentation/wine-doc.sgml b/documentation/wine-doc.sgml
index f840ba46e8f..87ae33221c9 100644
--- a/documentation/wine-doc.sgml
+++ b/documentation/wine-doc.sgml
@@ -32,6 +32,7 @@
+
@@ -103,6 +104,7 @@
&opengl;
&build;
&dlls;
+ &multimedia;