?  search:
summary | log | graphiclog1 | graphiclog2 | commit | commitdiff | tree | refs | edit | fork
blame | history | raw | HEAD
Added an implementation of iphlpapi.dll; most Get* functions
[wine.git] / documentation / multimedia.sgml
blobbf763d56153d9929eca6ee28f280ba2f3dc03650
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 -->
Windows API implementation