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