documentation/status/multimedia

   1 This file contains information about the implementation of the multimedia
   2 layer of WINE.
   3
   4 The libraries consist of MMSYSTEM.DLL (win16), WINMM.DLL (win32) and some
   5 (abstracted, not Windows compatible) lowlevel drivers. The implementation
   6 can be found in the multimedia/ subdirectory.
   7
   8 The multimedia stuff is split into 3 layers. The lowlevel (device drivers),
   9 midlevel (MCI commands) and highlevel abstraction layers.
  10
  11 The lowlevel may depend on current hardware and OS services (like OSS).
  12 Mid-level and high-level must be written independantly from the hardware and OS
  13 services.
  14
  15 1. Lowlevel layers
  16
  17    Following lowlevel layers are implemented:
  18 1.1 (Waveform) Audio
  19
  20    The API consists of the waveIn*/waveOut* functions found in
  21    multimedia/mmsystem.c. They call the real lowlevel audiodriver using
  22    the wodMessage/widMessage function in multimedia/audio.c, which handles
  23    the different requests.
  24
  25    The lowlevel audio driver is currently only implemented for the
  26    OpenSoundSystem (OSS) as supplied in the Linux and FreeBSD kernels by
  27    4Front Technologies (http://www.4front-tech.com/). The presence of this
  28    driver is checked by configure (depends on the <sys/soundcard.h> file).
  29
  30    The implementation contains all features commonly used, but has several
  31    problems. For instance:
  32       Writes and reads are not done asynchronously as they are supposed to
  33    be done. This breaks some programs (soundrec.exe from the Windows applets),
  34    but doesn't worry other programs. Some callbacks are probably done
  35    incorrectly (there are reports of some broken multimedia applications,
  36    but I haven't found one yet.)
  37
  38    TODO:
  39         - add asynchronous writes and reads (must use threads)
  40         - check the callback functions
  41         - verify all functions for correctness
  42         - add drivers for other soundsystems (Sun Audio, remote audio systems
  43           (using X extensions, ...)
  44
  45 1.2 Mixer
  46
  47    The API consists of the mixer* functions found in multimedia/mmsystem.c.
  48    They call the lowlevel driver functions in multimedia/mixer.c using the
  49    mixMessage function.
  50
  51    The current implementation tries to use the OpenSoundSystem mixer, but is
  52    missing nearly everything. There is no report of a working application.
  53
  54    TODO:
  55         - implement mixing functionality for OSS correctly.
  56         - implement mixing lowlevel drivers for other mixers.
  57
  58 1.3 MIDI
  59
  60    The API consists of the midi* functions found in multimedia/mmsystem.c.
  61    They call the lowlevel driver functions in multimedia/midi.c using the
  62    midMessage and the modMessage functions.
  63
  64    The lowlevel audio driver is currently only implemented for the
  65    OpenSoundSystem (OSS) as supplied in the Linux and FreeBSD kernels by
  66    4Front Technologies (http://www.4front-tech.com/). The presence of this
  67    driver is checked by configure (depends on the <sys/soundcard.h> file).
  68    Both Midi in and Midi out are provided. The type of MIDI devices supported
  69    is external MIDI port (requires an MIDI capable device - keyboard...) and
  70    OPL/2 synthesis (the OPL/2patches for all instruments are in midiPatch.c).
  71
  72    TODO:
  73         - Do not implement a software synthesizer. This should be done
  74           using MIDI loopback devices in an external program (like timidity).
  75           the only trouble is that timidity is GPL'ed...
  76         - use better instrument definition for OPL/2 (midiPatch.c)
  77         - have a look at OPL/3 ?
  78         - a hack is used in mmsystem.c (setting reserved to the 32 bit linear
  79           address of the block whatever the call is made from 16 or 32 bits
  80           code...). this should be made in midi.c I think
  81
  82 1.4 Timers
  83
  84    The API consists of the timer* functions found in multimedia/timer.c.
  85    There is currently only one implementation, which uses normal windows timers.
  86    The implementation works for most cases found. The only problem is that
  87    it doesn't support asynchronous timer events (as it is supposed to do).
  88
  89    There is a workaround for this lack in timeGetTime() to make Diablo work
  90    and 'Pinball! SpaceCadet' at least start up.
  91
  92    TODO:
  93         - Implemented asynchronous timers (using a thread probably)
  94
  95 1.5 MMIO
  96
  97    The API consists of the mmio* functions found in multimedia/mmio.c.
  98
  99    FIXME: I am not sure about the status of this implementation.
 100
 101    TODO:
 102         - add win32 support.
 103         - ...
 104
 105 1.6 AUX
 106
 107    The API consists of the aux* functions found in multimedia/mmsystem.c.
 108    They call auxMessage in multimedia/mmaux.c.
 109
 110    The aux* functions are the predecessor of the mixer* functions.
 111
 112    The implementation uses the OSS mixer API, and is incomplete.
 113
 114    TODO:
 115         - verify the implementation
 116
 117 1.7 JOYSTICK
 118
 119    The API consists of the joy* functions found in multimedia/joystick.c.
 120    The implementation currently uses the Linux joystick device driver API.
 121    It is lacking support for enhanced joysticks and has not been extensively
 122    tested.
 123
 124    TODO:
 125         - better support of enhanced joysticks
 126         - support more joystick drivers (like the XInput extension)
 127
 128 2. Midlevel drivers (MCI)
 129
 130    The midlevel drivers are represented by some common API functions,
 131    mostly mciSendCommand and mciSendString. The mciSendString function
 132    uses commandstrings, which are translated into normal MCI commands as
 133    used by mciSendCommand. The API can be found in multimedia/mmsystem.c
 134    and multimedia/mcistring.c.
 135    The functions there (mciOpen,mciSysInfo) handle midlevel driver
 136    allocation and calls.
 137
 138    The implementation is not complete.
 139
 140    TODO:
 141         - support windows MCI drivers (should be possible for they usually
 142           do not use lowlevel calls)
 143         - MCI command loading support
 144         - better implement non waiting command (without the MCI_WAIT flag).
 145           First shot is present in midi.c but requires much more work (and
 146           will impact sndPlaySound() as well which shall be written as
 147           as set of MCI commands).
 148         - implement other stuff as yet unknown
 149
 150    WINE implements several MCI midlevel drivers:
 151
 152 2.1 CDAUDIO
 153
 154    The currently best implementation is the MCI CDAUDIO driver that can
 155    be found in multimedia/mcicda.c. The implementation is mostly complete,
 156    there have been no reports of errors.
 157    The implementation currently uses only the Linux /dev/cdrom controlling
 158    functions. (Sun and BSD like should be similair, but are not implemented.)
 159
 160    A very small example of a cdplayer consists just of the line
 161    mciSendString("play cdaudio",NULL,0,0);
 162
 163    TODO:
 164         - add support for other cdaudio drivers
 165
 166 2.2 MCIWAVE
 167
 168    The implementation is rather complete and can be found in
 169    multimedia/audio.c.
 170    It uses the lowlevel audio API (although not abstracted correctly).
 171    FIXME: The MCI_STATUS command is broken.
 172
 173    TODO: - check for correctness
 174
 175 2.3 MIDI/SEQUENCER
 176
 177    The implementation can be found in multimedia/midi.c. Except from the
 178    Record command, should be close to completion (except for non blocking
 179    commands).
 180
 181    TODO:
 182         - implement it correctly
 183         - finish asynchronous commands
 184
 185 2.4 MCIANIM
 186
 187    The implementation consists of stubs and is in multimedia/mcianim.c.
 188
 189    TODO:
 190         - implement it, probably using xanim or something similair. Could
 191           also be implemented by using the Windows MCI video drivers.
 192
 193 3 High-level layers
 194
 195    The rest (basically the MMSYSTEM and WINMM DLLs entry points.