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