Added DebugBreak.

[wine] / documentation / status / multimedia

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) lowlevel drivers. The implementation
can be found in the multimedia/ subdirectory.

The multimedia stuff is split into 3 layers. The lowlevel (device drivers),
midlevel (MCI commands) and highlevel abstraction layers.

The lowlevel may depend on current hardware and OS services (like OSS). 
Mid-level and high-level must be written independantly from the hardware and OS
services.

1. Lowlevel layers

   Following lowlevel layers are implemented:

1.1 (Waveform) Audio

   The API consists of the waveIn*/waveOut* functions found in
   multimedia/mmsystem.c. They call the real lowlevel audiodriver using
   the wodMessage/widMessage function in multimedia/audio.c, which handles
   the different requests.

   The lowlevel audio driver is currently only implemented for the
   OpenSoundSystem (OSS) as supplied in the Linux and FreeBSD kernels by
   4Front Technologies (http://www.4front-tech.com/). The presence of this
   driver is checked by configure (depends on the <sys/soundcard.h> file).

   The implementation contains all features commonly used, but has several
   problems. For instance:
      Writes are not done asynchronously as they are supposed to be done.
   This breaks some programs (soundrec.exe from the Windows applets),
   but doesn't worry other programs. 

   TODO:
        - add asynchronous writes (must use threads)
        - verify all functions for correctness
        - add drivers for other soundsystems (Sun Audio, remote audio systems
          (using X extensions, ...), ALSA
        - WaveHdr must be sent though mmsystem.c to get the linear address
          set correctly. An application calling directly (wod|wid)Message
          will fail

1.2 Mixer

   The API consists of the mixer* functions found in multimedia/mmsystem.c.
   They call the lowlevel driver functions in multimedia/mixer.c using the
   mixMessage function.

   The current implementation tries to use the OpenSoundSystem mixer, but is
   missing nearly everything. There is no report of a working application.
   
   TODO:
        - implement mixing functionality for OSS correctly.
        - implement mixing lowlevel drivers for other mixers.

1.3 MIDI
        
   The API consists of the midi* functions found in multimedia/mmsystem.c.
   They call the lowlevel driver functions in multimedia/midi.c using the
   midMessage and the modMessage functions.

   The lowlevel audio driver is currently only implemented for the
   OpenSoundSystem (OSS) as supplied in the Linux and FreeBSD kernels by
   4Front Technologies (http://www.4front-tech.com/). The presence of this
   driver is checked by configure (depends on the <sys/soundcard.h> file).
   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:
        - Do not implement a software synthesizer. This should be done
          using MIDI loopback devices in an external program (like timidity).
          the only trouble is that timidity is GPL'ed...
        - 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 ?
        - MidiHdr must be sent though mmsystem.c to get the linear address
          set correctly. An application calling directly (wod|wid)Message
          will fail
        - implement asynchronous playback of MidiHdr 

1.4 Timers

   The API consists of the timer* functions found in multimedia/timer.c. 
   There is currently only one implementation, which uses normal windows timers.
   The implementation works for most cases found. The only problem is that
   it doesn't support asynchronous timer events (as it is supposed to do).

   There is a workaround for this lack in timeGetTime() to make Diablo work
   and 'Pinball! SpaceCadet' at least start up.

   TODO:
        - Implemented asynchronous timers (using the service thread)

1.5 MMIO
   
   The API consists of the mmio* functions found in multimedia/mmio.c.

   FIXME: I am not sure about the status of this implementation.

   TODO:
        - add win32 support.
        - ...

1.6 AUX
   
   The API consists of the aux* functions found in multimedia/mmsystem.c.
   They call auxMessage in multimedia/mmaux.c.

   The aux* functions are the predecessor of the mixer* functions.

   The implementation uses the OSS mixer API, and is incomplete.

   TODO:
        - verify the implementation

1.7 JOYSTICK
   
   The API consists of the joy* functions found in multimedia/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)

2. Midlevel drivers (MCI)
   
   The midlevel drivers are represented by some common API functions, 
   mostly mciSendCommand and mciSendString. The mciSendString function
   uses commandstrings, which are translated into normal MCI commands as
   used by mciSendCommand. The API can be found in multimedia/mmsystem.c
   and multimedia/mcistring.c.
   The functions there (mciOpen,mciSysInfo) handle midlevel driver
   allocation and calls.

   The implementation is not complete.
 
   MCI drivers are seen as regular WINE modules, and can be loaded 
   (with a correct loadorder between builtin, 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, supercedes the mci
          key in c:\windows\system.ini

   TODO:
        - support windows MCI drivers (should be possible for they usually 
          do not use lowlevel calls)
        - MCI command loading support
        - better implement non waiting command (without the MCI_WAIT flag). 
          First shot is present in midi.c but requires much more work (and
          will impact sndPlaySound() as well which shall be written as
          as set of MCI commands).
        - implement other stuff as yet unknown
        - in mciString(), make use of hiword from mciSendMessage
          return value to convert value into string...
        - move mci drivers as regular DLLs (loading in wine, elfglue...)

   WINE implements several MCI midlevel drivers:

2.1 CDAUDIO
   
   The currently best implementation is the MCI CDAUDIO driver that can
   be found in multimedia/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 similair, but are not implemented.)

   A very small example of a cdplayer consists just of the line
   mciSendString("play cdaudio",NULL,0,0);

   Native MCICDA is starting to output sounds... It uses the mscdex
   traps (on int 2f).

   TODO:
        - add support for other cdaudio drivers

2.2 MCIWAVE
   
   The implementation is rather complete and can be found in 
   multimedia/audio.c.
   It uses the lowlevel 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
   
   Native MCIWAVE has been working but is currently blocked by
   scheduling issues.

2.3 MIDI/SEQUENCER
   
   The implementation can be found in multimedia/midi.c. Except from the
   Record command, should be close to completion (except for non blocking
   commands).

   TODO: 
        - implement it correctly
        - finish asynchronous commands

   Native MCIMIDI has been working but is currently blocked by
   scheduling issues.

2.4 MCIANIM

   The implementation consists of stubs and is in multimedia/mcianim.c.

   TODO: 
        - implement it, probably using xanim or something similair. Could
          also be implemented by using the Windows MCI video drivers.

2.5 MCIAVI

   The implementation consists of stubs and is in multimedia/mciavi.c.

   TODO: 
        - implement it, probably using xanim or something similair. Could
          also be implemented by using the Windows MCI video drivers.

3 High-level layers

   The rest (basically the MMSYSTEM and WINMM DLLs entry points).