DSOUND.DLL reads certain defualts from the WIN.INI file when the library is initialized (that is, when LibInit/LibEntry are called). These are stored in the section tagged [DSOUND]. Values are read from WIN.INI only when the library is initialized, so later changes made to WIN.INI will not effect DSOUND.DLL. It is possible to update most of the current internal values through function calls described later. There is no API support for changing the WIN.INI settings; use the Windows WriteProfileString function for this.
The DSound Control Panel (SNDCNTRL.EXE) can be used to change the WIN.INI values and the run-time internal values, and for most purposes this will be how the values are changed. The only internal value I can see changing is the global volume, to change the playback volume temporarily for an application. See Get/SetVolume below.
In the Aristosoft version of DSOUND.DLL 3.0, no WIN.INI settings are required for proper operation since this version of the .DLL has autoconfigure code. In the shareware version, there must be an EDelayValue for proper operation in 386 Enhanced mode. The default value for this parameter is hard-wired into the shareware version and will work only on machines that operate exactly as fast as mine!
These are the delay parameters in the [DSOUND] section of WIN.INI:
RDelayValue=nn
SDelayValue=nn
EDelayValue=nn
(nn is a positive integer).
These three entries set the delay value for sound playback in Real, Standard, and Enhanced modes, respectively. The delay value is mainly used in Enhanced mode to pace the playback of sound samples. A delay value of 0 (DS_TIMER in DSOUND.H) instructs DSOUND.DLL to use the built-in timer to pace playback; this is the default behavior for Real and Standard mode. The built-in timer cannot be used in Enhanced mode, though, so a delay value is needed. If the value of EDelayValue is 65535 (DS_AUTO in DSOUND.H) or the WIN.INI entry is missing, the .DLL will choose an appropriate delay value when the library is initialized. In the Aristosoft version, this is quite accurate (and takes a few seconds); in the shareware version, an "average" value is used. The DSound Control panel can be used to find a more suitable value. Any other value will be used as an explicit delay value. Note that changing the delay to 0 with SetDelayValue while in Enhanced mode is bad. Don't do it. The DSOUND Control Panel will not allow a zero value for EDelayValue to be written.
Under some circumstances, it may be necessary to use a non-zero delay value for Standard or Real mode. Similarly, it may be necessary to bypass the auto-delay calculation if it sets the delay to the wrong thing. Both these can be done with the DSOUND Control Panel, or by writing the appropriate values to WIN.INI.
Other WIN.INI parameters:
Volume=nn
Shift=nn
These store the global volume and shift values, described below. The default is 10 for volume and 0 for shift. Both can be changed from the DSound Control Panel.
Port=nn
Device=nn
These allow for determining what hardware to use for playing the sound. Currently, the only supported hardware is the internal speaker (0). The Sound Source will be device 1 when its drivers are completed. The Port entry will allow choosing the base LPT port for the SoundSource or other sound boards. Valid settings will vary acording to hardware.
The DSOUND.DLL API
The DSound API allows C, Turbo Pascal/Windows, Visual Basic, Actor, and most macro languages to include sound support with minimal effort. In many cases, as little as 1 or 2 lines of code are needed. All functions are exported from DSOUND.DLL with the Pascal calling convention. All functions are prototyped in DSOUND.H (for C) and DSOUND.TXT (for Visual Basic and Basic-like macro languages). All references to DSOUND.H below are probably just as valid for DSOUND.TXT. Headers for other languages can be created from these two files in a straightforward manner.
What follows is the documentation for all public functions in DSOUND.DLL. The version of the earliest version of DSOUND.DLL that supported the function is also given.
PlaySound [1.0]
The central function in DSOUND.DLL is PlaySound. It is mainly of use to C users, as the data structures it requires are not easily used in Visual Basic. However, for playing "computed" sound sampled, such as waveforms, it may be useful.
void FAR PASCAL PlaySound(char huge *lpSound, long dSize,
lpSound is a long pointer to a chunk of memory with the samples in it, one byte each. This should be locked but need NOT be in real address space. GlobalAlloc/GlobalLock works fine. Page-locking in Enhanced mode, though not needed, will prevent the sound from stuttering as the sample bytes are paged into memory. lpSound is strictly speaking a char huge *; samples can be much longer than 64K, up to the maximum size GlobalAlloc'able under the current mode (1 Mb in Standard mode, 64 Mb in Enhanced mode). You can play sounds that are larger than available memory by allocating a block of memory and reading in the sound piece by piece, though there will be slight pauses between the pieces. PlaySoundFile does exactly this.
dSize is an unsigned long that tells how many samples there are in lpSound. Currently, this should be the size of the sound data in bytes, but in the future this may not be so. Be accurate; Windows complains if DSOUND.DLL accesses memory you don't own.
uFrequency is the desired playback frequency. Currently 22 KHz, 11KHz, 7.33 KHz, and 5.5 KHz are supported. However, to be open-ended about this all, all frequencies are "valid," and the nearest one is used. That is, 9 KHz will play at 11 KHz, and 44 KHz will play at 22 KHz. Most sounds are recorded at 11 KHz. Note that the actual playback frequency may not be what is specified; samples may be skipped or double-played to compensate. This parameter tells the driver what rate the sample should be played back at.
uSampleType is a code for the sample size. Currently only 8-bit linear is supported, which has the code 0. This parameter is currently ignored, but future versions may support 16-bit sample sizes, log scales, compression, and such. In other words, for future compatibility, pass 0.
uVolume adjusts the dynamics of the sound before playing. Basically, the amplitude of the sound centered around a middlepoint is expanded/compressed by the factor (uVolume/10). Thus, a volume of 5 is about half as loud, and 20 is twice as loud. In theory, that is--the PC speaker is not all that dynamic. Note that this value will be adjusted according to the global volume (Get/SetVolume) similarly. If the global volume is 5, and you pass 20 into PlaySound, the actual playback volume will be 10. Basically, the uVolume parameter should be used to make different sounds have the same apparent volume when played at the same global volume, while the global volume should be used to adjust the user playback level.
uShift is an amount added to each sample before being processed (but after the volume has been accounted for). This wouldn't be useful on a real sound chip, but it allows for compensating for different speaker hardware in this hack. 3-5 seem to work best; 4 is the default SOUNDER.EXE uses. Note that there is a global shift value as well (Get/SetShift). As with volume, the uShift should be used to make a specific sound sound right, while the global shift should be used to compensate for weird hardware. Almost all sounds require a shift value of 4, but those that are not well centered (the waveform isn't centered around 128) will need to be shifted. This parameter may not be used for all hardware output devices. Also, in hindsight, it should probably default to 0 for all files, with the driver compensating for its ideosyncracies, but c'est la vie!
GetDSoundVersion [1.0]
int FAR PASCAL GetDSoundVersion()
This function returns the version of DSOUND.DLL as an integer whose upper byte is the major revision and whose lower byte is the minor revision. The version should be checked before further calls to DSOUND.DLL are made to make sure that all functionality is supported.
Note: Because of a bug in Winword, it returns an error if you call a function with no parameters, even though there should be no error. Because of this, GetDSoundVersionD is also exported; it takes a dummy integer parameters that is ignored.
AboutDSound [3.0]
void FAR PASCAL AboutDSound()
This function displays a MessageBox that tells about DSOUND.DLL and its configuration information. As above, AboutDSoundD should be used from within Winword macros; the dummy integer parameter is ignored.
SetDelayValue / GetDelayValue [2.0]
void FAR PASCAL SetDelayValue(int d)
int FAR PASCAL GetDelayValue()
These set the current delay value used internally. The WIN.INI setting is not affected. In Enhanced mode, setting the delay to 0 will most likely cause a crash.
SetVolume / GetVolume [2.0]
void FAR PASCAL SetVolume(int v)
int FAR PASCAL GetVolume()
These change the current global volume for all sounds being played. The WIN.INI setting is not affected. If you plan on changing the volume, you should get it first and save it, returning it to its former state as soon as possible.
SetShiftValue / GetShiftValue [2.50]
void FAR PASCAL SetShiftValue(int s)
int FAR PASCAL GetShiftValue()
Some hardware may need a shift value other than the 4 that most sounds assume.
SetSoundPort / GetSoundPort [3.0]
void FAR PASCAL SetSoundPort(int p)
int FAR PASCAL GetSoundPort()
Allows setting the I/O port used by the sound driver, if multiple ports are supported. This is generally of use only to the control panel. Currently, this has meaning only with the Sound Source driver.
SetSoundDevice / GetSoundDevice [3.0]
void FAR PASCAL SetSoundDevice(int d)
int FAR PASCAL GetSoundDevice()
Allows for setting the driver to play sounds on. Currently only the PC speaker and Disney Sound Source are supported. DSOUND.H defines constants for these drivers. These calls are probably most useful to the control panel, but an application may decide to alter playback behavior based on the selected driver.
UpdateClock [3.0]
BOOL FAR PASCAL UpdateClock(BOOL f)
Since many drivers run without interrupts, the PC speaker can fall behind. To compensate, with such drivers DSOUND.DLL will adjust the internal time based on the sample size and frequency. This involves calling DOS, which under some circumstances may cause problems. Calling the function with FALSE will disable such updating. TRUE turns it back on. The return value is the previous setting. The time is updated in PlaySound and all functions that call PlaySound internally (PlaySoundxxx). Don't worry about accumulating error; when the flag is FALSE, the lost time is accumulated and reflected in the next updating of the clock.
FindBestDelay [2.50]
int FAR PASCAL FindBestDelay()
This function is currently only useful in the version of DSOUND.DLL which ships with Aristosoft's Wired for Sound, as it was developed under an exclusive agreement with Aristosoft. In fact, it's pretty much useless to any program other than a control panel replacement. It calculates the best delay value for Enhanced mode. The delay value is returned, but the current delay value is not changed; use SetDelayValue() to change it. This call is really useful only in Enhanced mode, as the timer is more accurate and can be used in Real and Standard mode. Again, this call is mostly important to SNDCNTRL.EXE, as auto-delay sensing is implemented within DSOUND.DLL. In the shareware version of DSOUND.DLL 3.0, the function returns a canned, default value which is most likely not the "best" delay value.
Note: As there should be no reason to call this from a Winword macro, there is no "dummy" equivalent. Thus, Winword will return a bogus error if this function is called from a macro.
PlaySoundFile [2.80]
int FAR PASCAL PlaySoundFile(LPSTR filename, int type,
unsigned uFrequency, unsigned uSampleSize,
unsigned uVolume, unsigned uShift)
This call will load and play the sound file specified by filename, if possible. Three file types are supported: .SOU, Sounder 1.0 .SND, and SoundTool .SND. The file type can be specified in the type parameter; if it is DS_GUESS, the file's type will be auto-detected as per below. The remaining four parameters are useful only if the sound file is of type .SOU; they are ignored for the other types since the parameters are in the file. The sound file need not be able to fit in memory; it will be read and played in chunks if necessary. Values for type and return values are defined in DSOUND.H.
SoundFileType [2.80]
int FAR PASCAL SoundFileType(LPSTR filename)
Returns the type of sound file the specified file is (as defined in DSOUND.H). DS_CANTDETECT is returned if the file's type cannot be determined. SoundTool .SND files (DS_MHSND) are determined by looking for "SOUND" at the beginning of the file. If the file's extension is .SND but it isn't a SoundTool .SND file, it's assumed to be a Sounder 1.0 .SND file. If the extension is .SOU, it's assumed to be a .SOU file.
LoadSoundImage [2.80]
GLOBALHANDLE FAR PASCAL LoadSoundImage(LPSTR filename, int type,
unsigned uFrequency, unsigned uSampleSize,
unsigned uVolume, unsigned uShift)
This function loads a sound file into memory but does not play it. The memory sound image is in the Clipboard format as defined in SoundTool and by the SNDHeader structure in DSOUND.H and DSOUND.TXT. What is returned is an unlocked global handle. The parameters are as in PlaySoundFile. Unlike PlaySoundFile, though, the sound must fit entirely within memory. For Visual Basic and macro languages, the return value is simply an integer. Note that the sound should be freed as soon as possible to reclaim its memory. To do so, call the GlobalFree function (exported by the Kernel) with the value returned from LoadSoundImage.
PlaySoundImage [2.80]
int FAR PASCAL PlaySoundImage(GLOBALHANDLE hSound)
This call plays the sound memory image hSound. hSound need not be locked when this is called. This handle will usually be returned from LoadSoundImage. The memory image is assumed to be in the structure defined by SNDHeader. See DSOUND.H for possible error values.
PlaySoundResource [3.0]
int FAR PASCAL PlaySoundResource(HANDLE hSound)
This function operates exactly like PlaySoundImage, except that it uses a handle to a resource in the SND format obtained with calls to FindResource and LoadResource. The resource should be freed with FreeResource when it's not needed. Since few macro languages allow using resources, this is of little use to non-C and Pascal users.
_llread / _llwrite [2.8]
long FAR PASCAL _llread(int file, char huge *buf,
long length)
long FAR PASCAL _llwrite(int file, char huge *buf,
long length)
These have nothing to do with sound, except that they'll make reading in large sound files (> 64K) much easier. They're identical to _lread and _lwrite, except that a long is used for the length and return value, the buffer can be greater than 64K in size, and the read can cross segment boundaries.
Linking to DSOUND.DLL
To use DSOUND.DLL in a C program by linking implicitly, DSOUND.H should be included in your source files that access it and either DSOUND.LIB should be linked with your files or you should put:
IMPORTS
PlaySound=dsound.1
GetDSoundVersion=dsound.2
SetDelayValue=dsound.3
GetDelayValue=dsound.4
SetVolume=dsound.5
GetVolume=dsound.6
FindBestDelay=dsound.7
SetShiftValue=dsound.10
GetShiftValue=dsound.11
PlaySoundFile=dsound.12
_llread=dsound.13
_llwrite=dsound.14
SoundFileType=dsound.15
LoadSoundImage=dsound.16
PlaySoundImage=dsound.17
AboutDSound=dsound.18
PlaySoundResource=dsound.19
GetDSoundVersionD=dsound.20
AboutDSoundD=dsound.21
in you .DEF file. As I eventually learned from Martin Hepperle, author of SoundTool, using import libraries and IMPORTed functions at the same time is bad!
For Visual Basic and Basic-like macro languages, the Declares in DSOUND.TXT perform the necessary linking. They can be used as models for other programming languages.
File and Clipboard Formats
The format of the Sounder 1.0 .SND file is quite simple; the file has the following words, followed by the sample bytes:
word 0 Sample size code (see uSampleSize above)
word 1 Frequency to play back at (see uFrequency above)
word 2 Volume to play at (see uVolume above)
word 3 Shift (see uShift above)
word 4..n Actual sample bytes to be played
The SoundTool .SND format is better, and should be used if possible, It closely matches the memory-image formats and resource format. Only files have the 6-byte SOUND^Z header.
char szMagic[6] = { ┤S┤,┤O┤,┤U┤,┤N┤,┤D┤, 0x1a }
GLOBALHANDLE hGSound; /* not used */
DWORD dwBytes; /* length of complete sample */
DWORD dwStart; /* first byte to play from sample */
DWORD dwStop; /* first byte NOT to play from sample */
WORD wFreq; /* frequency */
WORD wSampleSize;
WORD wVolume;
WORD wShift;
char szName[96]; /* name of sound */
Sound sample follows this header.
This format can also be used for clipboard transfers under the CF_SOUND type.
A third "format" is the .SOU format, which is just a stream of bytes. Since it is necessary to specify the playback parameters manually, this is impractical for most uses. It's included since it's the format other software uses (i.e. reMac), and was supported in Sounder 1.0.
