windows-xp/Source/XPSP1/NT/multimedia/media/read.me

Files for \NT\PRIVATE\WINDOWS\MEDIA

(Not all the files for media are here - VIDCAP is also
part of media, but is (currently) a separate project.
Some of the parts have the common Daytona/Chicago master
sources in Redmond - e.g. Soundrec.  Look at ssyncme.bat
and read.me files to spot these).

The "I" in the rest of this is NigelT.  It's not been
kept up to date, but there still seems to be some value in it,
so I (LaurieGr 3/94) have just left it.
---------------------------------------------------------------



                NT / Win32 Multimedia Project
                =============================

This note will tell you about the project tree structure, how to
enlist, what each element is for and what items are complete.

Enlisting
---------

Enlist in the MEDIA project as a subdirectory of the WINDOWS project.

Example:

    [C:\nt\private\windows] md media
    [C:\nt\private\windows] cd media
    [C:\nt\private\windows\media] enlist -s \\rastaman\ntwin -p media

Project tree
------------

The media project consists of a number of DLLs and some test applications.

media
    |
    +- inc              Assorted header files
    +- sounds           Licensed Prosonus sounds for the PDK
    +- winmm            Source for WINMM.DLL
    +- mciwave          Source for MCIWAVE.DLL
    +- mcicda           Source for MCICDA.DLL
    |
    +- test
    |   |
    |   +- playsnd      Source for PLAYSND.EXE
    |   +- mci          Source for MCI.EXE
    |   +- mcitest      Source for MCITEST.EXE
    |   +- mmiotest     Source for MMIOTEST.EXE
    |
    +- tools
        |
        +- extract      Source for EXTRACT.EXE
        +- docfmt       Source for DOCFMT.EXE

A bit more detail on each item follows.  As a general note: when
viewing the sources, remember that much of the code and headers were
taken directly from Win16 sources and consequently have their own
coding style, documentation technique and data types.

Include files
-------------

gmem.h      This header redefines some global memory allocation macros
            used in winmm which avoids rewriting the winmm code.

mcihand.h   This is a partial definition of an interface for MCI handlers
            which could one day be made public.

mmiocf.h    This defines the unpublished (by anyone) compound file
            support for RIFF format files.  It would become public when
            the file definition becomes public.  There is currently
            only stub support for these APIs.

Sound Files
-----------

The sounds directory contains a set of sounds which were licensed
from Prosonus by Microsoft for use in the Multimedia Windows product.
The license allows us to distribute them with any MS product.
One file (bummer.wav) was recorded at MS by me (NigelT). It is the
voice of my old program manager Bob Seidensticker and may also be
distributed freely.


WINMM
-----

This DLL provides the Multimedia api set.  Currently (PDK) this
is only PlaySound, but should include the MCI API set.  Please
refer to the source and the Level I Multimedia documents for more
details on MCI (Media Control Interface).  Support for the MMIO
API set is also included here.  See the Level I docs for details.

I have ported the MCI APIs and most of it works.  The auto open
feature is missing however.  This was achieved in Windows by using
a second task and needs to be implemented here with a thread.  The
code path is a little obscure here but the function which needs
attention is called mciSendSystemString.

The code is almost exactly the Win16 code as written by DavidLe
with minor tweaks to get rid of compile time warnings.

The test apps below exercise this DLL.  See also the notes on
debugging support.

Once MCI works with wave files, the PlaySound API should be reworked
to use MCI.  This will allow PlaySound to play files which don't fit
in the available memory quota (~250k).


MCIWAVE
-------

This DLL provides an MCI handler for wave files.  It is not yet
written.  See the MCICDA handler for a more complete example.
This handler should use a thread to asynchronously supply the
sound driver with data from a file, resource or whatever and respond
to the commands sent to it by the MCI support in WINMM.DLL

MCICDA
------

This DLL provides an MCI handler for playing audio CDs via a CD-ROM
drive on the SCSI bus.  I have been working with Mike Glass on this.
About 20% of it is done.  It can play a CD from and to a specifiec
location on the disk.


PLAYSND
-------

This app will play Multimedia sound files.  It is currently a part
of the daily build and is currently in vogue as a demo and hence
there will be much wailing when it is found to be broken next.
It uses only the PlaySound and MessageBeep APIs to do the business.
This is primarily a test app for PlaySound and not a demo so
whoever is developing should feel free to modify it - I did.


MCI
---

This is a Win32 console app which exercises the MCI string interface
and hence most of MCI and the MCI handlers.  I have been using this
to test the MCICDA handler.  The code is only a few lines long and is
an indication of just how easy it is to add Multimedia support
to an app.


MCITEST
-------

This is an incomplete port of a Win16 test app for MCI.  I gave up
with this because of USER/GDI troubles.  This should be completed
and used instead of MCI since it has a better feature set from a
test perspective and is a GUI app not a boring old char mode app.


MMIOTEST
--------

This is the wierdest port of all.  I couldn't be bothered to port
this Win16 app to Win32 so I simply wrote a 'main' which calls the
test functions inside it.  If you look at it, ignore all the
windowing code - it's never executed.

Run it from a console window to test the MMIO API set and features
in WINMM.DLL.


EXTRACT and DOCFMT
------------------

These are rather rough OS/2 port of tools the Multimedia group
developed for generating documentation from the source code.  This
system is called AUTODOC and can generate WinHelp, WinWord and Ventura
output directly from the source code - usually by invoking a make
option such as "make docs".

Since much of the code I have ported contains this embedded doc
support, I ported the tools to be able to print it out.  The system
is 4,000,000,000 times better than the NT doc system but wasn't
invented here.

Details of how to use AUTODOC for global domination projects can
be obtained from the Multimedia group (t-MarkMc).


Debugging support
-----------------

Most apps and all of the dlls have run-time variable debug level
messages.  Look at the debug.c module in each DLL source for details.
As an example the variable winmmDebugLevel controls the output from
WINMM.

Debug levels are used as follows:

    0   No output (even for errors)
    1   Error reporting
    2   Major function calls
    3   Minor function calls
    4   Mindless detail, data dumps etc.

This isn't always how it's used but that's the idea.
The header files show how the dprintf1,2,3,4 macros work that generate
this output.