git.oblomov.eu Git - wine/blob - documentation/multimedia.sgml

   1   <chapter id="multimedia">
   2     <title>Wine and Multimedia</title>
   3
   4     <para>
   5       This file contains information about the implementation of the
   6       multimedia layer of Wine.
   7     </para>
   8
   9     <para>
  10       The implementation can be found in the dlls/winmm/ directory (and in
  11       many of its subdirectories), but also in dlls/msacm/ (for the
  12       audio compression/decompression manager) and dlls/msvideo/ (for the
  13       video compression/decompression manager).
  14     </para>
  15
  16     <sect1 id="mm-overview">
  17       <title>Overview</title>
  18
  19       <para>
  20         The multimedia stuff is split into 3 layers. The low level (device
  21         drivers), mid level (MCI commands) and high level abstraction layers.
  22         The low level layer has also some helper DLLs (like the MSACM/MSACM32
  23         and MSVIDEO/MSVFW32 pairs).
  24       </para>
  25
  26       <para>
  27         The low level layer may depend on current hardware and OS services
  28         (like OSS on Unix). Mid level (MCI) and high level layers must be
  29          written independently from the hardware and OS services.
  30       </para>
  31
  32       <para>
  33         There are two specific low level drivers (msacm.drv for wave input/output,
  34         midimap.drv for MIDI output only), whose role is:
  35         <itemizedlist>
  36           <listitem>
  37             <para>
  38               help choosing one low level driver between many
  39             </para>
  40           </listitem>
  41           <listitem>
  42             <para>
  43               add the possibility to convert streams (ie ADPCM =&gt;
  44               PCM) (this is useful if the format required by the
  45               application for playback isn't supported by the soundcard).
  46             </para>
  47           </listitem>
  48           <listitem>
  49             <para>
  50               add the possibility to filter a stream (adding echo, equalizer...
  51               to a wave stream), or modify the instruments that have to be
  52               played (MIDI).
  53             </para>
  54           </listitem>
  55         </itemizedlist>
  56       </para>
  57
  58       <para>
  59         All of those components are defined as DLLs (one by one).
  60       </para>
  61
  62     </sect1>
  63
  64     <sect1 id="mm-low">
  65       <title>Low level layers</title>
  66
  67       <para>
  68         Please note that native low level drivers are not currently supported
  69         in Wine, because they either access hardware components or require
  70         VxDs to be loaded; Wine does not correctly supports those two so far.
  71       </para>
  72
  73       <para>
  74         The following low level layers are implemented (as built-in DLLs):
  75       </para>
  76
  77       <sect2>
  78         <title>(Wave form) Audio</title>
  79
  80         <para>
  81           MMSYSTEM and WINMM call the real low level audio driver using the
  82           wodMessage/widMessage which handles the different requests.
  83         </para>
  84
  85         <sect3>
  86           <title>OSS implementation</title>
  87
  88           <para>
  89             The low level audio driver is currently only implemented for the
  90             OpenSoundSystem (OSS) as supplied in the Linux and FreeBSD kernels by
  91             <ulink url="http://www.4front-tech.com/">4Front Technologies</ulink>.
  92             The presence of this driver is checked by configure (depends on the
  93             &lt;sys/soundcard.h&gt; file). Source code resides in
  94             dlls/winmm/wineoss/audio.c.
  95           </para>
  96
  97           <para>
  98             The implementation contains all features commonly used, but has
  99             several problems (see TODO list).
 100           </para>
 101
 102           <para>
 103             Note that some Wine specific flag has been added to the wodOpen function,
 104             so that the dsound DLL can share the /dev/dsp access. Currently, this
 105             only provides mutual exclusion for both DLLs. Future extension could add
 106             a virtual mixer between the two output streams.
 107           </para>
 108
 109           <para>TODO:
 110             <itemizedlist>
 111               <listitem>
 112                 <para>
 113                   verify all functions for correctness
 114                 </para>
 115               </listitem>
 116               <listitem>
 117                 <para>
 118                   Add virtual mixer between wave-out and dsound interfaces.
 119                 </para>
 120               </listitem>
 121             </itemizedlist>
 122           </para>
 123
 124         </sect3>
 125
 126         <sect3>
 127           <title>Other sub systems</title>
 128
 129           <para>
 130             Support is also provided for ALSA, aRts, NAS, Jack,
 131             AudioIO, but with less intensive debugging than the OSS.
 132           </para>
 133
 134           <para>
 135             EsounD isn't supported yet. ALSA support still needs a
 136             couple of refinements.
 137           </para>
 138
 139         </sect3>
 140
 141       </sect2>
 142
 143       <sect2>
 144         <title>MIDI</title>
 145
 146         <para>
 147           MMSYSTEM and WINMM call the low level driver functions using the
 148           midMessage and the modMessage functions.
 149         </para>
 150
 151         <sect3>
 152           <title>OSS driver</title>
 153
 154           <para>
 155             The low level audio driver is currently only implemented for the
 156             OpenSoundSystem (OSS) as supplied in the Linux and FreeBSD kernels by
 157             <ulink url="http://www.4front-tech.com/">4Front Technologies</ulink>.
 158             The presence of this driver is checked by configure (depends on the
 159             &lt;sys/soundcard.h&gt; file, and also some specific defines because
 160             MIDI is not supported on all OSes by OSS). Source code resides in
 161             dlls/winmm/wineoss/midi.c
 162           </para>
 163
 164           <para>
 165             Both Midi in and Midi out are provided. The type of MIDI devices
 166             supported is external MIDI port (requires an MIDI capable device -
 167             keyboard...) and OPL/2 synthesis (the OPL/2 patches for all
 168             instruments are in midiPatch.c).
 169           </para>
 170
 171           <para>TODO:
 172             <itemizedlist>
 173               <listitem>
 174                 <para>
 175                   use better instrument definition for OPL/2 (midiPatch.c) or use
 176                   existing instrument definition (from playmidi or kmid) with a
 177                   .winerc option
 178                 </para>
 179               </listitem>
 180               <listitem>
 181                 <para>
 182                   have a look at OPL/3 ?
 183                 </para>
 184               </listitem>
 185               <listitem>
 186                 <para>
 187                   implement asynchronous playback of MidiHdr
 188                 </para>
 189               </listitem>
 190               <listitem>
 191                 <para>
 192                   implement STREAM'ed MidiHdr (question: how shall we share the code
 193                   between the midiStream functions in MMSYSTEM/WINMM and the code
 194                   for the low level driver)
 195                 </para>
 196               </listitem>
 197               <listitem>
 198                 <para>
 199                   use a more accurate read mechanism than the one of snooping on
 200                   timers (like select on fd)
 201                 </para>
 202               </listitem>
 203             </itemizedlist>
 204           </para>
 205
 206         </sect3>
 207
 208         <sect3>
 209           <title>Other sub systems</title>
 210
 211           <para>
 212             Could support other MIDI implementation for other sub
 213             systems (ALSA, any other idea here ?)
 214           </para>
 215
 216           <para>
 217             Could also implement a software synthesizer, either inside Wine or
 218             using using MIDI loop back devices in an external program (like
 219             timidity). The only trouble is that timidity is GPL'ed...
 220             Note: this could be achieved using the ALSA sequencer and
 221             Timidity being used as a server.
 222           </para>
 223
 224         </sect3>
 225
 226       </sect2>
 227
 228       <sect2>
 229         <title>Mixer</title>
 230
 231         <para>
 232           MMSYSTEM and WINMM call the low level driver functions using the
 233           mxdMessage function.
 234         </para>
 235
 236         <sect3>
 237           <title>OSS implementation</title>
 238
 239           <para>
 240             The current implementation uses the OpenSoundSystem mixer, and resides
 241             in dlls/winmm/wineoss/mixer.c
 242           </para>
 243
 244           <para>TODO:
 245             <itemizedlist>
 246               <listitem>
 247                 <para>
 248                   implement notification mechanism when state of mixer's controls
 249                   change
 250                 </para>
 251               </listitem>
 252             </itemizedlist>
 253           </para>
 254
 255         </sect3>
 256
 257         <sect3>
 258           <title>Other sub systems</title>
 259
 260           <para>TODO:
 261             <itemizedlist>
 262               <listitem>
 263                 <para>
 264                   implement mixing low level drivers for other mixers (ALSA...)
 265                 </para>
 266               </listitem>
 267             </itemizedlist>
 268           </para>
 269
 270         </sect3>
 271
 272       </sect2>
 273
 274       <sect2>
 275         <title>Aux</title>
 276
 277         <para>
 278           The AUX low level driver is the predecessor of the mixer driver
 279           (introduced in Win 95).
 280         </para>
 281
 282         <sect3>
 283           <title>OSS driver</title>
 284
 285           <para>
 286             The implementation uses the OSS mixer API, and is incomplete.
 287           </para>
 288
 289           <para>TODO:
 290             <itemizedlist>
 291               <listitem>
 292                 <para>
 293                   verify the implementation
 294                 </para>
 295               </listitem>
 296               <listitem>
 297                 <para>
 298                   check with what is done in mixer
 299                 </para>
 300               </listitem>
 301               <listitem>
 302                 <para>
 303                   open question: shall we implement it on top of the low level mixer
 304                   functions ?
 305                 </para>
 306               </listitem>
 307             </itemizedlist>
 308
 309           </para>
 310
 311         </sect3>
 312
 313       </sect2>
 314
 315       <sect2>
 316         <title>Wine OSS</title>
 317
 318         <para>
 319            All the OSS dependent functions are stored into the WineOSS DLL. It still
 320            lack a correct installation scheme (as any multimedia device under Windows),
 321            so that all the correct keys are created in the registry. This requires
 322            an advanced model since, for example, the number of wave out devices can
 323            only be known on the destination system (depends on the sound card driven
 324            by the OSS interface). A solution would be to install all the multimedia
 325            drivers through the SETUPX DLL; this is not doable yet (the multimedia
 326            extension to SETUPX isn't written yet).
 327         </para>
 328
 329       </sect2>
 330
 331       <sect2>
 332         <title>Joystick</title>
 333
 334         <para>
 335           The API consists of the joy* functions found in dlls/winmm/joystick/joystick.c.
 336           The implementation currently uses the Linux joystick device driver
 337           API. It is lacking support for enhanced joysticks and has not been
 338           extensively tested.
 339         </para>
 340
 341         <para>TODO:
 342           <itemizedlist>
 343             <listitem>
 344               <para>
 345                 better support of enhanced joysticks (Linux 2.2 interface is available)
 346               </para>
 347             </listitem>
 348             <listitem>
 349               <para>
 350                 support more joystick drivers (like the XInput extension)
 351               </para>
 352             </listitem>
 353             <listitem>
 354               <para>
 355                 should load joystick DLL as any other driver (instead of hardcoding)
 356                 the driver's name, and load it as any low lever driver.
 357               </para>
 358             </listitem>
 359           </itemizedlist>
 360         </para>
 361
 362       </sect2>
 363
 364       <sect2>
 365         <title>Wave mapper (msacm.drv)</title>
 366
 367         <para>
 368           The Wave mapper device allows to load on-demand codecs in order to
 369           perform software conversion for the types the actual low level driver
 370           (hardware). Those codecs are provided through the standard ACM
 371           drivers.
 372         </para>
 373
 374         <sect3>
 375           <title>Built-in</title>
 376
 377           <para>
 378             A first working implementation for wave out as been provided (wave in
 379             exists, but doesn't allow conversion).
 380           </para>
 381
 382           <para>
 383             Wave mapper driver implementation can be found in dlls/winmm/wavemap/
 384             directory. This driver heavily relies on MSACM and MSACM32 DLLs which
 385             can be found in dlls/msacm and dlls/msacm32. Those DLLs load ACM
 386             drivers which provide the conversion to PCM format (which is normally
 387             supported by low level drivers). ADPCM, MP3... fit into the category
 388             of non PCM formats.
 389           </para>
 390
 391           <para>
 392             There is currently no built-in ACM driver in Wine, so you must use
 393             native ones if you're looking for non PCM playback.
 394           </para>
 395
 396           <para>TODO:
 397             <itemizedlist>
 398               <listitem>
 399                 <para>
 400                   check for correctness and robustness
 401                 </para>
 402               </listitem>
 403             </itemizedlist>
 404           </para>
 405         </sect3>
 406
 407         <sect3>
 408           <title>Native</title>
 409
 410           <para>
 411             Seems to work quite ok (using of course native MSACM/MSACM32 DLLs)
 412             Some other testings report some issues while reading back the registry
 413             settings.
 414           </para>
 415
 416         </sect3>
 417
 418       </sect2>
 419
 420       <sect2>
 421         <title>MIDI mapper</title>
 422
 423         <para>
 424           Midi mapper allows to map each one of 16 MIDI channels to a specific
 425           instrument on an installed sound card. This allows for example to
 426           support different MIDI instrument definition (XM, GM...). It also
 427           permits to output on a per channel basis to different MIDI renderers.
 428         </para>
 429
 430         <sect3>
 431           <title>Built-in</title>
 432
 433           <para>
 434             A built-in MIDI mapper can be found in dlls/winmm/midimap/. It partly
 435             provides the same functionality as the Windows' one. It allows to pick up
 436             destination channels (you can map a given channel to a specific playback
 437             device channel (see the configuration bits for more details).
 438           </para>
 439
 440           <para>TODO:
 441             <itemizedlist>
 442               <listitem>
 443                 <para>
 444                   implement the Midi mapper features (instrument on the fly modification)
 445                   if it has to be done as under Windows, it required parsing the midi
 446                   configuration files (didn't find yet the specs)
 447                 </para>
 448               </listitem>
 449             </itemizedlist>
 450           </para>
 451
 452         </sect3>
 453
 454         <sect3>
 455           <title>Native</title>
 456
 457           <para>
 458             The native midimapper from Win 98 works, but it requires a bunch of
 459             keys in the registry which are not part of the Wine source yet.
 460           </para>
 461
 462           <para>TODO:
 463             <itemizedlist>
 464               <listitem>
 465                 <para>
 466                   add native midimapper keys to the registry to let it run. This
 467                   will require proper multimedia driver installation routines.
 468                 </para>
 469               </listitem>
 470             </itemizedlist>
 471           </para>
 472
 473         </sect3>
 474
 475       </sect2>
 476
 477     </sect1>
 478
 479     <sect1 id="mm-mci">
 480       <title>Mid level drivers (MCI)</title>
 481
 482       <para>
 483         The mid level drivers are represented by some common API functions,
 484         mostly mciSendCommand and mciSendString. See status in chapter 3 for
 485         more information. Wine implements several MCI mid level drivers
 486         (status is given for both built-in and native implementation):
 487       </para>
 488
 489       <para>TODO: (apply to all built-in MCI drivers)
 490         <itemizedlist>
 491           <listitem>
 492             <para>
 493               use MMSYSTEM multitasking caps instead of the home grown
 494             </para>
 495           </listitem>
 496         </itemizedlist>
 497       </para>
 498
 499
 500       <sect2>
 501         <title>CDAUDIO</title>
 502
 503         <sect3>
 504           <title>Built-in</title>
 505
 506           <para>
 507             The currently best implementation is the MCI CDAUDIO driver that can
 508             be found in dlls/winmm/mcicda/mcicda.c. The implementation is mostly
 509             complete, there have been no reports of errors. It makes use of
 510             dlls/ntdll/cdrom.c Wine cdrom interface.
 511             This interface has been ported on Linux, FreeBSD and NetBSD. (Sun
 512             should be similar, but are not implemented.)
 513           </para>
 514
 515           <para>
 516             A very small example of a cdplayer consists just of the line
 517             mciSendString("play cdaudio",NULL,0,0);
 518           </para>
 519
 520           <para>TODO:
 521             <itemizedlist>
 522               <listitem>
 523                 <para>
 524                   add support for other cdaudio drivers (Solaris...)
 525                 </para>
 526               </listitem>
 527               <listitem>
 528                 <para>
 529                   add support for multiple cdaudio devices (plus a decent
 530                   configuration scheme)
 531                 </para>
 532               </listitem>
 533             </itemizedlist>
 534           </para>
 535
 536         </sect3>
 537
 538         <sect3>
 539           <title>Native</title>
 540
 541           <para>
 542             Native MCICDA works also correctly... It uses the MSCDEX traps (on int
 543             2f). However, some commands (like seeking) seem to be broken.
 544           </para>
 545
 546         </sect3>
 547
 548       </sect2>
 549
 550       <sect2>
 551         <title>MCIWAVE</title>
 552
 553         <sect3>
 554           <title>Built-in</title>
 555
 556           <para>
 557             The implementation is rather complete and can be found in
 558             dlls/winmm/mciwave/audio.c. It uses the low level audio API (although
 559             not abstracted correctly).
 560           </para>
 561
 562           <para>FIXME:
 563             <itemizedlist>
 564               <listitem>
 565                 <para>
 566                   The MCI_STATUS command is broken.
 567                 </para>
 568               </listitem>
 569             </itemizedlist>
 570           </para>
 571
 572           <para>TODO:
 573             <itemizedlist>
 574               <listitem>
 575                 <para>
 576                   check for correctness
 577                 </para>
 578               </listitem>
 579               <listitem>
 580                 <para>
 581                   better use of asynchronous playback from low level
 582                 </para>
 583               </listitem>
 584               <listitem>
 585                 <para>
 586                   better implement non waiting command (without the MCI_WAIT flag).
 587                 </para>
 588               </listitem>
 589             </itemizedlist>
 590           </para>
 591
 592         </sect3>
 593
 594         <sect3>
 595           <title>Native</title>
 596
 597           <para>
 598             Native MCIWAVE works also correctly.
 599           </para>
 600
 601         </sect3>
 602
 603       </sect2>
 604
 605       <sect2>
 606         <title>MCISEQ (MIDI sequencer)</title>
 607
 608         <sect3>
 609           <title>Built-in</title>
 610
 611           <para>
 612             The implementation can be found in dlls/winmm/mciseq/mcimidi.c. Except
 613             from the Record command, should be close to completion (except for non
 614             blocking commands, as many MCI drivers).
 615           </para>
 616
 617           <para>TODO:
 618             <itemizedlist>
 619               <listitem>
 620                 <para>
 621                   implement it correctly
 622                 </para>
 623               </listitem>
 624               <listitem>
 625                 <para>
 626                   finish asynchronous commands (especially for reading/record)
 627                 </para>
 628               </listitem>
 629               <listitem>
 630                 <para>
 631                   better implement non waiting command (without the MCI_WAIT flag).
 632                 </para>
 633               </listitem>
 634               <listitem>
 635                 <para>
 636                   implement the recording features
 637                 </para>
 638               </listitem>
 639             </itemizedlist>
 640           </para>
 641
 642         </sect3>
 643
 644         <sect3>
 645           <title>Native</title>
 646
 647           <para>
 648             Native MCIMIDI has been working but is currently blocked by scheduling
 649             issues (mmTaskXXX no longer work).
 650           </para>
 651           <para>FIXME:
 652             <itemizedlist>
 653               <listitem>
 654                 <para>
 655                   midiStreamPlay get from time to time an incorrect MidiHdr when
 656                   using the native MCI sequencer
 657                 </para>
 658               </listitem>
 659             </itemizedlist>
 660           </para>
 661
 662         </sect3>
 663
 664       </sect2>
 665
 666       <sect2>
 667         <title>MCIANIM</title>
 668
 669         <sect3>
 670           <title>Built-in</title>
 671
 672           <para>
 673             The implementation is in dlls/winmm/mcianim/.
 674           </para>
 675
 676           <para>TODO:
 677             <itemizedlist>
 678               <listitem>
 679                 <para>
 680                   implement it, probably using xanim or something similar.
 681                 </para>
 682               </listitem>
 683             </itemizedlist>
 684           </para>
 685
 686         </sect3>
 687
 688         <sect3>
 689           <title>Native</title>
 690
 691           <para>
 692             Native MCIANIM is reported to work (but requires native video DLLs
 693             also, even though the built-in video DLLs start to work correctly).
 694           </para>
 695
 696         </sect3>
 697
 698       </sect2>
 699
 700       <sect2>
 701         <title>MCIAVI</title>
 702
 703         <sect3>
 704           <title>Built-in</title>
 705
 706           <para>
 707             The implementation is in dlls/winmm/mcianim/. Basic features are present,
 708             simple playing is available, even if lots remain to be done. It rather
 709             heavily relies on MSVIDEO/MSVFW32 DLLs pair to work.
 710           </para>
 711
 712           <para>TODO:
 713             <itemizedlist>
 714               <listitem>
 715                 <para>
 716                   finish the implementation
 717                 </para>
 718               </listitem>
 719               <listitem>
 720                 <para>
 721                   fix the audio/video synchronization issue
 722                 </para>
 723               </listitem>
 724             </itemizedlist>
 725           </para>
 726
 727         </sect3>
 728
 729         <sect3>
 730           <title>Native</title>
 731
 732           <para>
 733             Native MCIAVI is reported to work (but requires native video DLLs
 734             also). Some files exhibit some deadlock issues anyway.
 735           </para>
 736
 737         </sect3>
 738
 739       </sect2>
 740
 741     </sect1>
 742
 743     <sect1 id="mm-high">
 744       <title>High level layers</title>
 745
 746       <para>
 747         The rest (basically the MMSYSTEM and WINMM DLLs entry points). It also
 748         provides the skeleton for the core functionality for multimedia
 749         rendering. Note that native MMSYSTEM and WINMM do not currently work
 750         under Wine and there is no plan to support them (it would require to
 751         also fully support VxD, which is not done yet).
 752         Moreover, native DLLs require 16 bit MCI and low level drivers. Wine
 753         implements them as 32 bit drivers.
 754         MCI and low level drivers can either be 16 or 32 bit for Wine.
 755       </para>
 756
 757       <para>TODO:
 758         <itemizedlist>
 759           <listitem>
 760             <para>
 761               it seems that some program check what's installed in registry
 762               against value returned by drivers. Wine is currently broken
 763               regarding this point.
 764             </para>
 765           </listitem>
 766           <listitem>
 767             <para>
 768               check thread-safeness for MMSYSTEM and WINMM entry points
 769             </para>
 770           </listitem>
 771           <listitem>
 772             <para>
 773               unicode entry points are badly supported
 774             </para>
 775           </listitem>
 776         </itemizedlist>
 777       </para>
 778
 779       <sect2>
 780         <title>MCI skeleton</title>
 781
 782         <para>
 783           Implementation of what is needed to load/unload MCI drivers, and to
 784           pass correct information to them. This is implemented in
 785           dlls/winmm/mci.c. The mciSendString function uses command strings,
 786           which are translated into normal MCI commands as used by
 787           mciSendCommand with the help of command tables. The API can be found
 788           in dlls/winmm/mmsystem.c and dlls/winmm/mci.c. The functions there
 789           (mciOpen,mciSysInfo) handle mid level driver allocation and calls. The
 790           implementation is not complete.
 791         </para>
 792
 793         <para>
 794           MCI drivers are seen as regular Wine modules, and can be loaded (with
 795           a correct load order between builtin, native), as any other DLL.
 796           Please note, that MCI drivers module names must bear the .drv
 797           extension to be correctly understood.
 798         </para>
 799
 800         <para>
 801           The list of available MCI drivers is obtained as follows:
 802           1. key 'mci' in [option] section from .winerc (or wineconf)
 803           mci=CDAUDIO:SEQUENCER gives the list of MCI drivers (names, in
 804           uppercase only) to be used in Wine.
 805           2. This list, when defined, supersedes the mci key in
 806           c:\windows\system.ini
 807        </para>
 808
 809         <para>
 810           Note that native VIDEODISC crashes when the module is loaded, which
 811           occurs when the MCI procedures are initialized. Make sure that this is
 812           not in the list from above. Try adding:
 813           mci=CDAUDIO:SEQUENCER:WAVEAUDIO:AVIVIDEO:MPEGVIDEO
 814           to the [options] section of the wine config file.
 815         </para>
 816
 817         <para>TODO:
 818           <itemizedlist>
 819             <listitem>
 820               <para>
 821                 correctly handle the MCI_ALL_DEVICE_ID in functions.
 822               </para>
 823             </listitem>
 824             <listitem>
 825               <para>
 826                 finish mapping 16 <=> 32 of MCI structures and commands
 827               </para>
 828             </listitem>
 829             <listitem>
 830               <para>
 831                 MCI_SOUND is not handled correctly (should not be sent to MCI
 832                 driver =&gt; same behavior as MCI_BREAK)
 833               </para>
 834             </listitem>
 835             <listitem>
 836               <para>
 837                 implement auto-open feature (ie, when a string command is issued
 838                 for a not yet opened device, MCI automatically opens it)
 839               </para>
 840             </listitem>
 841           </itemizedlist>
 842         </para>
 843
 844       </sect2>
 845
 846       <sect2>
 847         <title>MCI multi-tasking</title>
 848
 849         <para>
 850           Multi-tasking capabilities used for the MCI drivers are provided in
 851           dlls/winmm/mmsystem.c.
 852         </para>
 853
 854         <para>TODO:
 855           <itemizedlist>
 856             <listitem>
 857               <para>
 858                 mmTaskXXX functions are currently broken because the 16 loader does
 859                 not support binary command lines =&gt; provide Wine's own mmtask.tsk not
 860                 using binary command line.
 861               </para>
 862             </listitem>
 863           </itemizedlist>
 864         </para>
 865
 866       </sect2>
 867
 868       <sect2>
 869         <title>Timers</title>
 870
 871         <para>
 872           It currently uses a service thread, run in the context of the calling
 873           process, which should correctly mimic Windows behavior.
 874         </para>
 875
 876         <para>TODO:
 877           <itemizedlist>
 878             <listitem>
 879               <para>
 880                 Check if minimal time is satisfactory for most programs.
 881               </para>
 882             </listitem>
 883             <listitem>
 884               <para>
 885                 current implementation may let a timer tick (once) after it has
 886                 been destroyed
 887               </para>
 888             </listitem>
 889           </itemizedlist>
 890         </para>
 891
 892       </sect2>
 893
 894       <sect2>
 895         <title>MMIO</title>
 896
 897         <para>
 898           The API consists of the mmio* functions found in dlls/winmm/mmio.c.
 899           Seems to work ok in most of the cases. There's some linear/segmented
 900           issues with 16 bit code. There are also some bugs when writing MMIO
 901           files.
 902         </para>
 903
 904       </sect2>
 905
 906       <sect2>
 907         <title>sndPlayXXX functions</title>
 908
 909         <para>
 910           Seem to work correctly.
 911         </para>
 912
 913       </sect2>
 914
 915     </sect1>
 916
 917     <sect1 id="mm-conf">
 918       <title>Multimedia configuration</title>
 919
 920       <para>
 921         Currently, multimedia configuration heavily relies on Win 3.x
 922         configuration model.
 923       </para>
 924
 925       <sect2>
 926         <title>Drivers</title>
 927
 928         <para>
 929           Since all multimedia drivers (MCI, low level ones, ACM drivers,
 930           mappers) are, at first, drivers they need to appear in the [mci] or
 931           [mci32] section of the system.ini file.
 932           Since all drivers are, at first, DLLs, you can choose to load their
 933           Wine's (built-in) or Windows (native) version.
 934         </para>
 935
 936       </sect2>
 937
 938       <sect2>
 939         <title>MCI</title>
 940
 941         <para>
 942           A default [mci] section (in system.ini) looks like (see the note above
 943           on videodisc):
 944         </para>
 945
 946         <screen>
 947    [mci]
 948    cdaudio=mcicda.drv
 949    sequencer=mciseq.drv
 950    waveaudio=mciwave.drv
 951    avivideo=mciavi.drv
 952    videodisc=mcipionr.drv
 953    vcr=mcivisca.drv
 954    MPEGVideo=mciqtz.drv
 955         </screen>
 956
 957         <para>
 958           By default, the list of loadable MCI drivers will be made of those
 959           drivers (in the [mci] section).
 960         </para>
 961
 962         <para>
 963           The list of loadable (recognized) MCI drivers can be altered in the
 964           [option] section of the wine config file, like:
 965           mci=CDAUDIO:SEQUENCER:WAVEAUDIO:AVIVIDEO:MPEGVIDEO
 966         </para>
 967
 968         <para>TODO:
 969           <itemizedlist>
 970             <listitem>
 971               <para>
 972                 use a default registry setting to bypass this (ugly) configuration
 973                 model
 974               </para>
 975             </listitem>
 976             <listitem>
 977               <para>
 978                 we need also a generic tool to let the end user pick
 979                 up his/her driver depending on the hardware present on the machine.
 980                 model
 981               </para>
 982             </listitem>
 983           </itemizedlist>
 984         </para>
 985
 986       </sect2>
 987
 988       <sect2>
 989         <title>Low level drivers</title>
 990
 991         <para>
 992            Configuration of low level drivers is done with the Wine configuration file.
 993            Default keys are provided in winedefault.reg.
 994         </para>
 995
 996         <para>
 997           The registry keys used here differ from the Windows' one. Using the Windows' one
 998           would require implementing something equivalent to a (real) driver installation.
 999           Even if this would be necessary in a few cases (mainly using MS native multimedia)
1000           modules, there's no real need so far (or it hasn't been run into yet).
1001         </para>
1002
1003         <para>
1004           See the configuration part of the User's Guide for more details.
1005         </para>
1006
1007       </sect2>
1008
1009       <sect2>
1010         <title>Midi mapper</title>
1011
1012         <para>
1013           The Midi mapper configuration is the same as on Windows 9x. Under the key
1014           <screen>
1015 HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Multimedia\MIDIMap
1016           </screen>
1017           if the 'UseScheme' value is not set, or is set to a null value, the midi
1018           mapper will always use the driver identified by the 'CurrentInstrument'
1019           value. Note: Wine (for simplicity while installing) allows to define
1020           'CurrentInstrument' as "#n" (where n is a number), whereas Windows only
1021           allows the real device name here. If UseScheme is set to a non null value,
1022           'CurrentScheme' defines the name of the scheme to map the different channels.
1023           All the schemes are available with keys like
1024           <screen>
1025 HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\MediaProperties\PrivateProperties\Midi\Schemes\%name_of_scheme%
1026           </screen>
1027           For every scheme, under this key, will be a sub-key (which name is usually
1028           a two digit index, starting at 00). Its default value is the name of the
1029           output driver, and the value 'Channels' lists all channels (of the 16
1030           standard MIDI ones) which have to be copied to this driver.
1031         </para>
1032
1033         <para>
1034           To provide enhanced configuration and mapping capabilities, each driver
1035           can define under the key
1036           <screen>
1037 HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\MediaProperties\PrivateProperties\Midi\Ports\%driver_name%
1038           </screen>
1039           a link to and .IDF file which allows to remap channels internally (for
1040           example 9 -&gt; 16), to change instruments identification, event
1041           controllers values. See the source file dlls/winmm/midimap/midimap.c
1042           for the details (this isn't implemented yet).
1043         </para>
1044       </sect2>
1045
1046       <sect2>
1047         <title>ACM</title>
1048
1049         <para>
1050           To be done (use the same mechanism as MCI drivers configuration).
1051         </para>
1052
1053       </sect2>
1054
1055       <sect2>
1056         <title>VIDC</title>
1057
1058         <para>
1059           To be done (use the same mechanism as MCI drivers configuration).
1060         </para>
1061
1062       </sect2>
1063
1064     </sect1>
1065
1066     <sect1 id="mm-arch">
1067       <title>Multimedia architecture</title>
1068
1069       <sect2>
1070         <title>Windows 9x multimedia architecture</title>
1071
1072         <screen>
1073              |
1074 Kernel space |                    Client applications
1075              |
1076              |           | |         ^ ^       | |          | |
1077              |        16>| |<32   16>| |<32 16>| |<32    16>| |<32
1078              |           | v         | |       | v          | v
1079              |      +----|-----------|---------|------------|-------+
1080              |      |    |           |         |            |       |  WinMM.dll
1081              |      |    |           |         |            |       |   32 bit
1082              |      +----|-----------|---------|------------|-------+
1083              |           | |         | ^       | |          |
1084              |  +------+ | |<16      | |       | |<16       |
1085              |  |   16>| | |         | |       | |          |
1086              |  |      v v v         | |       v v          v
1087              |  |   +---------------+---+-------------+-------------+
1088              |  |   | waveInXXX     |   | mciXXX      | *playSound* |
1089              |  |   | waveOutXXX    |   |             | mmioXXX     |
1090              |  |   | midiInXXX     |   |             | timeXXX     |
1091              |  |   | midiOutXXX    |   |             | driverXXX   |
1092              |  |   | midiStreamXXX |   |             |             |  MMSystem.dll
1093              |  |   | mixerXXX      |   |             |             |     16 bit
1094  +--------+  |  |   | auxXXX    +---+   +---+ mmThread|             |
1095  |MMDEVLDR|<------->| joyXXX    | Call back | mmTask  |             |
1096  +--------+  |  |   +-----------+-----------+---------+-------------+
1097      ^       |  |          |       ^    ^     | ^
1098      |       |  |       16>|       |<16>|  16>| |<16
1099      v       |  |          v       |    |     v |
1100  +--------+  |  |   +-------------+    +----------+
1101  |  VxD   |<------->|    *.drv    |    | mci*.drv |
1102  +--------+  |  |   +--------------+   +-----------+
1103              |  |    |  msacm.drv  |    | mciwave  |
1104              |  |    +--------------+   +-----------+
1105              |  |     | midimap.drv |    | mcimidi  |
1106              |  |     +-------------+    +-----------+
1107              |  |    Low-level drivers    |    ...   | MCI drivers
1108              |  |                         +----------+
1109              |  |                               |
1110              |  |                               |<16
1111              |  +-------------------------------+
1112              |
1113         </screen>
1114
1115         <para>
1116           The important points to notice are:
1117           <itemizedlist>
1118             <listitem>
1119               <para>
1120                 all drivers (and most of the core code) is 16 bit
1121               </para>
1122             </listitem>
1123             <listitem>
1124               <para>
1125                 all hardware (or most of it) dependent code reside in the kernel
1126                 space (which is not surprising)
1127               </para>
1128             </listitem>
1129           </itemizedlist>
1130         </para>
1131
1132       </sect2>
1133
1134       <sect2>
1135         <title>Wine multimedia architecture</title>
1136
1137         <screen>
1138              |
1139 Kernel space |                    Client applications
1140              |
1141              |           | |         ^ ^       | |          | |
1142              |        16>| |<32   16>| |<32 16>| |<32    16>| |<32
1143              |           | |         | |       | |          | |
1144              |  +------+ | |         | |       | |          | |
1145              |  |32/16>| | |         | |       | |          | |
1146              |  |      v v v         | |       v v          v v
1147              |  |   +---------------+---+-------------+-------------+
1148              |  |   | waveInXXX     |   | mciXXX      | *playSound* |
1149              |  |   | waveOutXXX    |   |             | mmioXXX     | WinMM.dll
1150              |  |   | midiInXXX     |   |             | timeXXX     |   32 bit
1151              |  |   | midiOutXXX    |   |             | driverXXX   |
1152              |  |   | midiStreamXXX |   |             |             | MMSystem.dll
1153              |  |   | mixerXXX      |   |             |             |   16 bit
1154              |  |   | auxXXX    +---+   +---+ mmThread|             |
1155              |  |   | joyXXX    | Call back | mmTask  |             |
1156              |  |   +-----------+-----------+---------+-------------+
1157              |  |         ||      ^    ^     ||    ^^
1158              |  |      16>||<32   |<16>|  16>||<32>||<16
1159              |  |         vv      |<32>|     vv    ||
1160 +---------+  |  |   +-------------+    +----------+
1161 |HW driver|<------->|    *.drv    |    | mci*.drv |
1162 +---------+  |  |   +--------------+   +-----------+
1163              |  |    |  msacm.drv  |    | mciwave  |
1164              |  |    +--------------+   +-----------+
1165              |  |     | midimap.drv |    | mcimidi  |
1166              |  |     +-------------+    +-----------+
1167              |  |    Low-level drivers    |    ...   | MCI drivers
1168              |  |                         +----------+
1169              |  |                               |
1170              |  |                               |<32/16
1171              |  +-------------------------------+
1172              |
1173         </screen>
1174
1175         <para>
1176           From the previous drawings, the most noticeable differences are:
1177           <itemizedlist>
1178             <listitem>
1179               <para>
1180                 low-level drivers can either be 16 or 32 bit
1181               </para>
1182             </listitem>
1183             <listitem>
1184               <para>
1185                 MCI drivers can either be 16 or 32 bit
1186               </para>
1187             </listitem>
1188             <listitem>
1189               <para>
1190                 MMSystem and WinMM will be hosted in a single elfglue library
1191               </para>
1192             </listitem>
1193             <listitem>
1194               <para>
1195                 no link between the MMSystem/WinMM pair on kernel space shall
1196                 exist. For example, there will be a low level driver to talk to a
1197                 UNIX OSS (Open Sound System) driver
1198               </para>
1199             </listitem>
1200             <listitem>
1201               <para>
1202                 all built-in drivers (low-level and MCI) will be written as 32 bit
1203                 drivers
1204               </para>
1205             </listitem>
1206             <listitem>
1207               <para>
1208                 all native drivers will be 16 bits drivers
1209               </para>
1210             </listitem>
1211           </itemizedlist>
1212         </para>
1213
1214       </sect2>
1215
1216     </sect1>
1217
1218     <sect1 id="msacm">
1219       <title>MS ACM Dlls</title>
1220
1221       <sect2>
1222         <title>Contents</title>
1223
1224         <para>tbd</para>
1225       </sect2>
1226
1227       <sect2>
1228         <title>Status</title>
1229
1230         <para>tbd</para>
1231       </sect2>
1232
1233       <sect2>
1234         <title>Caching</title>
1235
1236         <para>
1237           The MSACM/MSACM32 keeps some data cached for all known ACM
1238           drivers. Under the key
1239           <screen>
1240                   Software\Microsoft\AudioCompressionManager\DriverCache\&lt;driver
1241                   name&gt;
1242           </screen>
1243           , are kept for values:
1244             <itemizedlist>
1245               <listitem>
1246                 <para>
1247                       aFormatTagCache which contains an array of
1248                       DWORD. There are two DWORDs per cFormatTags
1249                       entry. The first DWORD contains a format tag
1250                       value, and the second the associated maximum
1251                       size for a WAVEFORMATEX structure.
1252                       (Fields dwFormatTag and cbFormatSize from
1253                       ACMFORMATDETAILS)
1254                  </para>
1255               </listitem>
1256               <listitem>
1257                 <para>
1258                       cFilterTags contains the number of tags supported by the driver
1259                       for filtering.
1260                 </para>
1261               </listitem>
1262               <listitem>
1263                 <para>
1264                       cFormatTags contains the number of tags support
1265                       by the driver for conversions.
1266                 </para>
1267               </listitem>
1268               <listitem>
1269                 <para>
1270                       fdwSupport (the same as the one returned from
1271                       acmDriverDetails).
1272                 </para>
1273               </listitem>
1274             </itemizedlist>
1275           </para>
1276
1277         <para>
1278                 The cFilterTags, cFormatTags, fdwSupport are the same
1279                 values as the ones returned from acmDriverDetails
1280                 function.
1281         </para>
1282       </sect2>
1283     </sect1>
1284
1285   </chapter>
1286
1287 <!-- Keep this comment at the end of the file
1288 Local variables:
1289 mode: sgml
1290 sgml-parent-document:("wine-devel.sgml" "set" "book" "part" "chapter" "")
1291 End:
1292 -->