Class DirectSoundBuffer

public class DirectSoundBuffer implements IDirectSoundBuffer
{
  // Methods
  public DirectSound3dBuffer get3dBuffer();
  public DirectSound3dListener get3dListener();
  public void getCaps(DSBCaps caps);
  public void getCurrentPosition(DSCursors cursors);
  public void getFormat(byte[] format, int size);
  public WaveFormatEx getFormat();
  public int getFormatSize();
  public int getFrequency();
  public int getPan();
  public int getStatus();
  public int getVolume();
  public void play(int flags);
  public void restore();
  public void setCurrentPosition(int newPosition);
  public void setFormat(byte[] format);
  public void setFormat(WaveFormatEx format);
  public void setFrequency(int frequency);
  public void setPan(int pan);
  public void setVolume(int volume);
  public void stop();
  public void transferToSoundBuffer(DSResourceDesc resourceDesc,
        int flags);
  public void writeBuffer(int start, int size, byte[] buffer,
        int flags);
}

Applications use the methods of the DirectSoundBuffer class to create DirectSoundBuffer objects and set up the environment.

Note This class does not provide an initialize method. Use the DirectSound.createSoundBuffer method to create and initialize DirectSoundBuffer objects.

Methods

get3dBuffer

public DirectSound3dBuffer get3dBuffer();

Retrieves a DirectSound3dBuffer object for the DirectSound buffer.

get3dListener

public DirectSound3dListener get3dListener();

Retrieves a DirectSound3dListener object for the DirectSound buffer.

getCaps

public void getCaps(DSBCaps caps);

Retrieves the capabilities of the DirectSoundBuffer object.

Return Value:

No return value.

Parameter	Description
caps	A DSBCaps object that receives the capabilities of this sound buffer.

Remarks:

The DSBCaps object contains similar information to the DSBufferDesc object passed to the createSoundBuffer method, with some additional information. This additional information can include the location of the buffer, either in hardware or software, and some cost measures. Examples of cost measures include the time it takes to download to a hardware buffer and the processing overhead required to mix and play the buffer when it is in the system memory.

The flags specified in the flags field of the DSBCaps object are the same flags used by the DSBufferDesc object. The only difference is that in the DSBCaps object, either DSBCAPS_LOCHARDWARE or DSBCAPS_LOCSOFTWARE will be specified according to the location of the buffer memory. In the DSBufferDesc object, these flags are optional and, depending on which flag is specified, force the buffer to be located in either hardware or software.

See Also: com.ms.directX.DirectSound, com.ms.directX.DSBCaps, com.ms.directX.DSBufferDesc

getCurrentPosition

public void getCurrentPosition(DSCursors cursors);

Retrieves the current position of the play and write cursors in the sound buffer.

Return Value:

No return value.

Parameter	Description
cursors	A DSCursors object that receives the current play and write positions in the DirectSoundBuffer object. These positions are offsets within the sound buffer and are specified in bytes.

Remarks:

The write cursor indicates the position at which it is safe to write new data into the buffer. The write cursor always leads the play cursor, typically by about 15 milliseconds worth of audio data.

It is always safe to change data that is behind the play position.

See Also: setCurrentPosition

getFormat

public void getFormat(byte[] format, int size);

Retrieves a description of the format of the sound data in the buffer.

Return Value:

No return value.

Parameter	Description
format	Array variable that receives a description of the sound data in the buffer.
size	Length of the array assigned to v1. DirectSound writes, at most, insz bytes to that array.

Remarks:

Before retrieving the format description, always use the getFormatSize method to query the DirectSoundBuffer object for the size of the format. Use this size to create an array of sufficient length to receive the format description.

See Also: getFormatSize, setFormat

getFormat

public WaveFormatEx getFormat();

Retrieves a description of the format of the sound data in the buffer.

Return Value:

Returns the WaveFormatEx object if successful; null otherwise.

See Also: setFormat

getFormatSize

public int getFormatSize();

Retrieves the size of the format information.

Return Value:

Returns the size.

getFrequency

public int getFrequency();

Retrieves the frequency, in samples per second, at which the buffer is being played. This value will be in the range of 100-100,000.

Return Value:

Returns the frequency at which the audio buffer is being played.

See Also: setFrequency

getPan

public int getPan();

Retrieves a variable that represents the relative volume between the left and right audio channels.

Return Value:

Returns the relative mix between the left and right speakers.

Remarks:

The returned value is measured in hundredths of a decibel (dB), in the range of -10,000 to 10,000. The value -10,000 means the right channel is attenuated by 100 dB. The value 10,000 means the left channel is attenuated by 100 dB. 0 is the neutral value; a return value of 0 means that both channels are at full volume (they are attenuated by 0 decibels). At any setting other than 0, one of the channels is at full volume and the other is attenuated.

A pan of -2173 means that the left channel is at full volume and the right channel is attenuated by 21.73 dB. Similarly, a pan of 870 means that the left channel is attenuated by 8.7 dB and the right channel is at full volume. A pan of -10,000 means that the right channel is silent and the sound is "all the way to the left," while a pan of 10,000 means that the left channel is silent and the sound is "all the way to the right."

The pan control acts cumulatively with the volume control.

See Also: getVolume, setPan, setVolume

getStatus

public int getStatus();

Retrieves the current status of the sound buffer.

Return Value:

Returns one value of DSBSTATUS_ type, specifying the status of the sound buffer.

getVolume

public int getVolume();

Retrieves the current volume for this sound buffer.

Return Value:

Returns the volume associated with the specified DirectSound buffer.

Remarks:

The volume is specified in hundredths of decibels (dB), and ranges from 0 to -10,000. The value 0 represents the original, unadjusted volume of the stream. The value -10,000 indicates an audio volume attenuated by 100 dB, which, for all practical purposes, is silence. Amplification is not currently supported by DirectSound.

The decibel (dB) scale corresponds to the logarithmic hearing characteristics of the ear. For example, an attenuation of 10 dB makes a buffer sound half as loud, and an attenuation of 20 dB makes a buffer sound one quarter as loud.

See Also: setVolume

play

public void play(int flags);

Causes the sound buffer to play from the current position.

Return Value:

No return value.

Parameter	Description
flags	One value of DSBPLAY_ type, specifying how to play the buffer.

Remarks:

For secondary sound buffers, this method will cause the buffer to be mixed into the primary buffer and output to the sound device. If this is the first buffer to play, it will implicitly create a primary buffer and start playing that buffer; the application does not need to explicitly direct the primary buffer to play.

If the buffer specified in the method is already playing, the call to the method will succeed and the buffer will continue to play. However, the flags that define playback characteristics are superseded by the flags defined in the most recent call.

Primary buffers must be played with the DSBPLAY_LOOPING flag set.

For primary sound buffers, this method will cause them to start playing to the sound device. If the application is set to the DSSCL_WRITEPRIMARY cooperative level, this will cause the audio data in the primary buffer to be output to the sound device. However, if the application is set to any other cooperative level, this method will ensure that the primary buffer is playing even when no secondary buffers are playing; in that case, silence will be played. This may reduce processing overhead when sounds are started and stopped in sequence since the primary buffer will be playing continuously rather than stopping and starting between secondary buffers.

Note Before this method can be called on any sound buffer, the application must call the setCooperativeLevel method and specify a cooperative level, typically DSSCL_NORMAL. If setCooperativeLevel has not been called, the play method carries out no action.

See Also: com.ms.directX.DirectSound

restore

public void restore();

Restores the memory allocation for a lost sound buffer for the specified DirectSoundBuffer object.

Return Value:

No return value.

Remarks:

If the application does not have the input focus, restore may not succeed. For example, if the application with the input focus has the DSSCL_WRITEPRIMARY cooperative level, no other application will be able to restore its buffers. Similarly, an application with the DSSCL_WRITEPRIMARY cooperative level must have the input focus to restore its primary sound buffer.

Once DirectSound restores the buffer memory, the application must rewrite the buffer with valid sound data. DirectSound cannot restore the contents of the memory, only the memory itself.

The application can receive notification that a buffer is lost when it specifies that buffer in a call to the play method. The getStatus method can also be used to retrieve the status of the sound buffer and test for the DSBSTATUS_BUFFERLOST flag.

See Also: play, getStatus

setCurrentPosition

public void setCurrentPosition(int newPosition);

Moves the current play cursor for secondary sound buffers.

Return Value:

No return value.

Parameter	Description
newPosition	New position, in bytes, from the beginning of the buffer that will be used when the sound buffer is played.

Remarks:

This method cannot be called on primary sound buffers.

If the buffer is playing, it will immediately move to the new position and continue. If it is not playing, it will begin from the new position the next time the play method is called.

See Also: getCurrentPosition, play

setFormat

public void setFormat(byte[] format);

Sets the format of the primary sound buffer for the application. Whenever this application has the input focus, DirectSound will set the primary buffer to the specified format.

Return Value:

No return value.

Parameter	Description
format	Array variable that specifies the new format for the primary sound buffer.

Remarks:

If this method is called on a primary buffer which is being accessed in write-primary cooperative level, the buffer must be stopped before setFormat is called. If this method is being called on a primary buffer for a non-write-primary level, DirectSound will implicitly stop the primary buffer, change the format, and restart the primary; the application does not need to do this explicitly.

A call to this method fails if the hardware does not directly support the requested pulse coded modulation (PCM) format. It will also fail if the calling application has the DSSCL_NORMAL cooperative level.

If a secondary sound buffer requires a format change, the application should create a new DirectSoundBuffer object using the new format.

DirectSound supports PCM formats; it does not currently support compressed formats.

See Also: getFormat

setFormat

public void setFormat(WaveFormatEx format);

Sets the format of the primary sound buffer for the application. Whenever this application has the input focus, DirectSound will set the primary buffer to the specified format.

Return Value:

No return value.

Parameter	Description
format	A WaveFormatEx object that specifies the wave format to set.

Remarks:

If this method is called on a primary buffer which is being accessed in write-primary cooperative level, the buffer must be stopped before setFormat is called. If this method is being called on a primary buffer for a non-write-primary level, DirectSound will implicitly stop the primary buffer, change the format, and restart the primary; the application does not need to do this explicitly.

A call to this method fails if the hardware does not directly support the requested pulse coded modulation (PCM) format. It will also fail if the calling application has the DSSCL_NORMAL cooperative level.

If a secondary sound buffer requires a format change, the application should create a new DirectSoundBuffer object using the new format.

DirectSound supports PCM formats; it does not currently support compressed formats.

See Also: getFormat

setFrequency

public void setFrequency(int frequency);

Sets the frequency at which the audio samples are played.

Return Value:

No return value.

Parameter	Description
frequency	New frequency, in Hz, at which to play the audio samples. The value must be between 100 and 100,000. If the value is 0, the frequency is reset to the current buffer format. This format is specified in the createSoundBuffer method.

Remarks:

Increasing or decreasing the frequency changes the perceived pitch of the audio data. This method does not affect the format of the buffer.

See Also: getFrequency, play, setFormat, com.ms.directX.DirectSound

setPan

public void setPan(int pan);

Specifies the relative volume between the left and right channels.

Return Value:

No return value.

Parameter	Description
pan	Relative volume between the left and right channels. This value has a range of -10,000 to 10,000 and is measured in hundredths of a decibel.

Remarks:

0 is the neutral value for pan and indicates that both channels are at full volume (attenuated by 0 decibels). At any other setting, one of the channels is at full volume and the other is attenuated. For example, a pan of -2173 means that the left channel is at full volume and the right channel is attenuated by 21.73 dB. Similarly, a pan of 870 means that the left channel is attenuated by 8.7 dB and the right channel is at full volume.

A pan of -10,000 means that the right channel is silent and the sound is "all the way to the left," while a pan of 10,000 means that the left channel is silent and the sound is "all the way to the right."

The pan control is cumulative with the volume control.

See Also: getPan, getVolume, setVolume

setVolume

public void setVolume(int volume);

Changes the volume of a sound buffer.

Return Value:

No return value.

Parameter	Description
volume	New volume requested for this sound buffer. Values range from 0 (0 dB, no volume adjustment) to -10,000 (-100 dB, essentially silent). DirectSound does not currently support amplification.

Remarks:

Volume units of are in hundredths of decibels, where 0 is the original volume of the stream.

Positive decibels correspond to amplification and negative decibels correspond to attenuation. The decibel scale corresponds to the logarithmic hearing characteristics of the ear. An attenuation of 10 dB makes a buffer sound half as loud; an attenuation of 20 dB makes a buffer sound one quarter as loud. DirectSound does not currently support amplification.

The pan control is cumulative with the volume control.

See Also: getPan, getVolume, setPan

stop

public void stop();

Causes the sound buffer to stop playing.

Return Value:

No return value.

Remarks:

For secondary sound buffers, stop will set the current position of the buffer to the sample that follows the last sample played. This means that if the play method is called on the buffer, it will continue playing where it left off.

For primary sound buffers, if an application has the DSSCL_WRITEPRIMARY level, this method will stop the buffer and reset the current position to 0 (the beginning of the buffer). This is necessary because the primary buffers on most sound cards can only play from the beginning of the buffer.

However, if stop is called on a primary buffer and the application has a cooperative level other than DSSCL_WRITEPRIMARY, this method simply reverses the effects of play. It configures the primary buffer to stop if no secondary buffers are playing. If other buffers are playing in this or other applications, the primary buffer will not actually stop until they are stopped. This method is useful because playing the primary buffer consumes processing overhead even if the buffer is playing sound data with the amplitude of 0 dB.

See Also: play

transferToSoundBuffer

public void transferToSoundBuffer(DSResourceDesc resourceDesc, int flags);

Transfers the wave data from the given resource to the start of the sound buffer.

Return Value:

No return value.

Parameter	Description
resourceDesc	A DSResourceDesc object that specifies the wave resource to transfer.
flags	A value of DSBLOCK_ type specifying how the buffer should be locked before it receives the wave data.

Remarks:

This method automatically locks and unlocks the buffer before and after writing the data.

writeBuffer

public void writeBuffer(int start, int size, byte[] buffer, int flags);

Writes the contents of a buffer to the given position in the sound buffer.

Return Value:

No return value.

Parameter	Description
start	Offset, in bytes, from the start of the buffer to the position to begin writing the data. This parameter is ignored if DSBLOCK_FROMWRITECURSOR is specified in the flags parameter.
size	Size, in bytes, of the portion of the buffer to write to.
buffer	Array variable that contain the data to write.
flags	A value of DSBLOCK_ type specifying how the buffer should be locked before it is written to.

Remarks:

This method automatically locks and unlocks the buffer before and after writing the data.