PopDirectSound Documentation

==============What is PopDirectSound? ==============
	PopDirectSound is the integration of DirectSound and 
DirectMusic into the Pop Framework, introduced in Pop version 
36.1.  It comprises of both new source files and new project 
files.  In particular, it has added the following files: 
DxSound.cpp/h, dsutil.cpp/h, dxutil.cpp/h, PopDirectSound.sln, 
PopDirectSound.vcproj, PopDirectSound.dsw, and 
PopDirectSound.dsp.
	It has also made small modifications to a few other files 
such as Pop.cpp/h, game.cpp/h, and critter.cpp/h.  Most of these 
modifications were simply a few addition methods.  Note that 
dsutil.cpp/h and dxutil.cpp/h were written by Microsoft and 
distributed as part of the DirectX9 SDK.

==============Why Should I Use DirectSound? ==============
	There are three main advantages of using DirectSound over 
regular windows sound.
	1) Performance - The use of DirectSound has significantly 
better performance over the use of the regular windows API.  
Tests have shown, that in sound intensive situations, regular 
windows sound calls can cause the frame-rate to drop 10 to 30 
fps.  Under the same conditions, but using DirectSound, there is 
no noticeable decrease in frame-rate.

	2) Sound Overlap - In regular windows sound, there is only 
one channel.  That is, only one sound can be played at any 
particular time.  DirectSound enables multiple sounds to be 
playing at the same time, providing smoother sounds.  At present, 
each particular sound can have 5 instances of itself be played at 
one time. 

	3) DirectMusic - PopDirectSound also incorporates 
DirectMusic into the framework.  DirectMusic is used to play 
longer sound files.  Instead of making a copy of the sound data, 
DirectMusic streams the data straight off of the file.

==============How Do I Use PopDirectSound? ==============
	There are currently two versions of the Pop Framework: Pop 
and PopDirectSound.  In order to use DirectSound you must use 
PopDirectSound.  There are basically three functions you should 
be aware of: playSound, playMusic and stopMusic.  They can all be 
accessed by either a cCritter or a cGame (or if you want even a 
cPopApp).  
* To play a sound, simply pass it the resource id or 
filename of the sound e.g. playSound("EXPLOSION") or 
playSound("res/mysoundeffect.wav"). 
* To play music, do the same thing, but with playMusic e.g.
 playMusic("res/mysong.wav") or playMusic("res/mysong.mid").
 Note that the playMusic method can open MIDI *.mid files as
 well as Windows *.wav files.
* To stop the currently playing music, simply call stopMusic().  Note 
that the currently playing music will automatically be stopped if 
you try to play another song over it.

==============What's the Difference Between===========
==============playSound and playMusic? ==============
	Use playSound for short sounds and playMusic for long 
sounds.  A sound effect (explosion, gunshot, yell, etc.) should 
go to playSound.  A song (background music, theme song, etc.) 
should go to playMusic.  Note that you can play many sounds at 
once, but you can play at most 1 music at any one time.

===============How Do I Tell============================
==============If DirectSound Is Working? =============
	Basically you can tell if you're using DirectSound by 
creating a situation that is sound intensive. 
1) Go to the Defender3D game.
2) Make sure the mute button is OFF (by default it's ON).
3) Set the player's shield to true.
4) Select Huge Critter Count.
5) Wait for the enemies to hit the player.
What should happen is a bunch of enemies will hit the 
player, when they do, each one will play a sound.  If DirectSound 
is NOT working, you will hear choppy sounds (because only one can 
play at a time) and your frame-rate will probably drop 
significantly.  Whereas, if you ARE using DirectSound, your 
frame-rate will most likely remain constant, and the sounds will 
sound smoother.

==============Troubleshooting==============
(A) In order to make DirectSound builds, you need to get 
the DirectX download with SDK from www.microsoft.com.
(B) Even after you install DirectX SDK you may have a problem
building the PopDirectSound project.  If you are the adminstrator
of your machine, the default directories for DirectX SDK were
probably added to your machine's environment paths, so this
problem isn't likely to arise. As a fallback, our project files suggest
finding the DirectX SDK include files in the directory
C:\Program Files\DXSDK\Include
If you installed your DirectX SDK to a different location, and you get
a compile error like "dxerr9.h not found," you will need to add some
directory information to your project settings for
Visual Studio.  You can either make this change globally by
customizing your Visual Studio installation using Tools|Options|Projects|
VC++ Directories|Include Files, or you can make the
change to the DirectSoundPop project file by editing Project|Properties|
C++|General|Additional Include Directories.
You may also encounter a similar linking problem.  As a fallback,
our project files suggest finding the DirectX SDK include files
in the directory
C:\Program Files\DXSDK\Lib
If you installed your DirectX SDK to a different location, and you get
a compile error like "dxerr9.lib not found," you will need to add some
directory information to your project settings for
Visual Studio.  You can either make this change by
customizing your Visual Studio installation using Tools|Options|Projects|
VC++ Directories|Library Files, you can make the
change to the DirectSoundPop project file by editing Project|Properties|
Linker|Additional Library Directories.
(C) Note that by default the Mute is ON in the Pop framework,
so you will not hear sound till you turn it on.  You can
change the initial mute status in the pop.cpp file.
(D) With older versions of Visual Studio you'll get a 
compile time error involving the occurances of "DWORD_PTR" in the 
DirectX dsound.h file.  Simply edit your dsound.h file to replace 
these occurances with to "DWORD*".
(E) You may run into a problem with either DirectSound NOT 
working even though you're running the PopDirectSound project, or 
DirectSound WORKING even though you're running the regular Pop 
project.  The reason for this is probably because you've been 
switching between the two i.e. you ran one, and then ran the 
other.  The reason for this is because Visual Studios generates 
some intermediate files, and uses the same files for both builds.  
Thus, whatever the first project compiled was, that is the 
setting that will be used.  The way to prevent this is to delete 
the intermediate files.  You can either do this manually by 
running "clean.bat" or you can click on 'rebuild' (not build) 
under the 'build' menu.

Leo Lee, April 27, 2004
