Contents
========

1. Overview
2. DirectSound API Changes
3. DirectSound Driver Support
4. What's Left to Do?
5. Known Bugs


1. Overview
===========

The core DirectSound functionality has been enhanced significantly since
beta-1.  What did we do?

- Several modification were made to improve efficiency.  The mixing
code was moved into Ring-3 to improve stability and reduce the overhead
of ring transitions.  Improvements to the driver interface also reduce
the communications between DirectSound and the drivers.

- DirectSound driver support has been extended to Sound Blaster, ESS,
MediaVision, Aztech, and Windows Sound System cards.  If a DirectSound
driver is not available, emulation support allows DirectSound to run
on any Windows sound driver (although latency is higher).

- An input-focus tracking mechanism allows sharing of the sound device
between multiple applications.  Multiple applications can create a
DirectSound object and play sound buffers, but only the application
with the input focus will be audible.

- Improvements to the driver interface allow DirectSound applications
to take advantage of several types of hardware acceleration, including
on-board sound memory and hardware mixing.  Applications can query the
DirectSound for the hardware resources, allowing games to scale their
audio output to the available acceleration.  Check out hardware mixing
on the Sound Blaster AWE32 card by launching the "DirectSound Test"
program (dsshow.exe)!

- Support for 3D positional audio was dropped for the first release,
due to lack of time.  3D audio will be supported in the next release
of DirectSound.  For a preview, check out the Appendix of the
DirectSound API specification (dsound.doc).


2. DirectSound API Changes
==========================

The API specification has been substantially modified for several reasons:
to make it easier to use, to improve functionality, to provide for future
enhancements which are already being developed, and to improve consistency
with the other Direct APIs.  Although most of the changes are cosmetic, it
will probably mean that ISV developers will have to spend some time porting
their application from the beta-1 API to the beta-2 API.  Hopefully this
won't be too painful.  The consolation: we don't believe the API will change
at all between beta-2 and the final release.

A new addition is the IDirectSound::SetCooperativeLevel call.  This should
be called immediately after the DirectSound object is created.  It is used
to determine the multitasking and resource-sharing characteristics for that
application.

Another addition is the DSBCAPS_TYPESTATIC flag which can specified when
creating a sound buffer.  This indicates to DirectSound that the sound
buffer will hold static data, i.e. that the buffer will contain a complete
sound rather than a small segment of a larger sound.  Static sound buffers
are appropriate for downloading to hardware memory such as is found on the
Sound Blaster AWE32.  Specifying this flag wherever appropriate helps
DirectSound to take maximum advantage of hardware mixing.

The API changes are described in detail in the DirectSound Application
Programming Interface (dsound.doc).  This document now includes examples
and basic usage scenarios which explain how to get the best performance
out of DirectSound.


3. DirectSound Driver Support
=============================

This beta release contains DirectSound versions of all sound drivers
included in the Windows 95 product.  This includes the following:

- Sound Blaster:  8-bit cards, 16-bit cards, and the AWE32.
- ESS: 488, 688, 1488, 1688.
- MediaVision: PAS 16, PAS Studio, Pro 3D, and the Blue Lite Special.
- Aztech: Nova 16, Washington 16.
- Microsoft: Windows Sound System.

Note, however, that there is a known bug with the MediaVision PAS Plus
which causes it to fail the creation of DirectSound objects.  This bug
has been fixed internally already, but the fix is not included in the
current beta due to inadequate testing of this fix on the other
MediaVision cards.  This card will be fully supported in the final release.

Any sound cards which do not have DirectSound drivers can still be accessed
through DirectSound.  If no driver is available, DirectSound will use its
emulation layer to communicate with the device through the standard Wave
driver interface.  This provides full DirectSound functionality, but
increases latency significantly and prevents access to hardware
acceleration.


4. What's Left to Do?
=====================

All the main code and APIs are currently working successfully.  We
anticipate few or no changes to the API specification.  There are a number
of known bugs to fix, as listed below.  There are also a couple of
performance enhancements which we are currently investigating.

The following APIs are currently unimplemented (but will be implemented
for the final release):
        IDirectSound::Compact
        IDirectSound::DuplicateSoundBuffer
        IDirectSound::GetLatency
        IDirectSound::SetLatency
        IDirectSoundBuffer::Restore
        IDirectSoundBuffer::WaveBlt

In addition, there are several error checking, parameter validation,
and verification code sections which have not yet been implemented.  This
means that an application can successfully perform a few operations which
the DirectSound specifications states to be illegal.  The final release
of DirectSound will include routines to detect and block such situations.
If you are trying something which contradicts the guidelines in the
specification, do not assume that it will work in the final release just
because it works in beta-2.


5. Known Bugs
=============

All of the following bugs are known and understood.  They will be fixed
for the final release.

- The PAS Plus card will fail to create a DirectSound object, except if
accessed through emulation mode.

- Input focus tracking doesn't work when using emulated drivers; the
audio will continue to be audible even if you switch away from the app.

- On some machine configurations, you may encounter some clicks and pops
in the audio output.  This is due to delays in the mixer thread scheduling.
We are currently evaluating various methods of solving this problem; it will
be fixed for the final release.

- If you are playing a secondary buffer and then obtain DSSCL_WRITEPRIMARY
access, the secondary buffer will keep playing.  In the final build, it
will be automatically stopped.  You should not Play secondary buffer if
you plan to be writing directly to the primary buffer.
