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