Class DirectSound

public class DirectSound implements IDirectSound
{
  // Methods
  public void compact();
  public DirectSoundBuffer createSoundBuffer(
        DSBufferDesc bufferDesc, byte[] format);
  public DirectSoundBuffer createSoundBuffer(
        DSBufferDesc bufferDesc, WaveFormatEx format);
  public DirectSoundBuffer duplicateSoundBuffer(
        DirectSoundBuffer original);
  public void enumSoundDrivers(IEnumSoundDriversCallback callback,
        IUnknown context);
  public void getCaps(DSCaps caps);
  public void getSpeakerConfig(int[] speakerConfig);
  public void initialize(_Guid guid);
  public void setCooperativeLevel(int hwnd, int level);
  public void setSpeakerConfig(int speakerConfig);
}

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

Methods

compact

public void compact();

Moves the unused portions of onboard sound memory, if any, to a contiguous block so that the largest portion of free memory will be available.

Return Value:

No return value.

Remarks:

If the application calls this method, it must have exclusive cooperation with the DirectSound object. (To get exclusive access, specify DSSCL_EXCLUSIVE in a call to the setCooperativeLevel method.) This method will fail if any operations are in progress.

See Also: setCooperativeLevel

createSoundBuffer

public DirectSoundBuffer createSoundBuffer(DSBufferDesc bufferDesc,
        byte[] format);

Creates a DirectSoundBuffer object to hold a sequence of audio samples.

Return Value:

Returns the DirectSoundBuffer object if successful; null otherwise.

Parameter	Description
bufferDesc	A DSBufferDesc object that contains the description of the sound buffer to be created.
format	Array variable that specifies the wave format for the sound buffer.

Remarks:

Before it can play any sound buffers, the application must specify a cooperative level for a DirectSound object by using the setCooperativeLevel method.

The bufferDesc parameter is an object that describes the type of buffer desired, including format, size, and capabilities. The application must specify the needed capabilities, or they will not be available. For example, if the application creates a DirectSoundBuffer object without specifying the DSBCAPS_CTRLFREQUENCY flag, any call to setFrequency will fail.

The DSBCAPS_STATIC flag can also be specified, in which case DirectSound stores the buffer in onboard memory, if available, in order to take advantage of hardware mixing. To force the buffer to use either hardware or software mixing, use the DSBCAPS_LOCHARDWARE or DSBCAPS_LOCSOFTWARE flags.

See Also: com.ms.directX.DSBufferDesc, duplicateSoundBuffer, setCooperativeLevel

createSoundBuffer

public DirectSoundBuffer createSoundBuffer(DSBufferDesc bufferDesc,
        WaveFormatEx format);

Creates a DirectSoundBuffer object to hold a sequence of audio samples.

Return Value:

Returns the DirectSoundBuffer object if successful; null otherwise.

Parameter	Description
bufferDesc	A DSBufferDesc object that contains the description of the sound buffer to be created.
format	A WaveFormatEx object that specifies the wave format for the sound buffer.

Remarks:

Before it can play any sound buffers, the application must specify a cooperative level for a DirectSound object by using the setCooperativeLevel method.

The bufferDesc parameter is an object that describes the type of buffer desired, including format, size, and capabilities. The application must specify the needed capabilities, or they will not be available. For example, if the application creates a DirectSoundBuffer object without specifying the DSBCAPS_CTRLFREQUENCY flag, any call to setFrequency will fail.

The DSBCAPS_STATIC flag can also be specified, in which case DirectSound stores the buffer in onboard memory, if available, in order to take advantage of hardware mixing. To force the buffer to use either hardware or software mixing, use the DSBCAPS_LOCHARDWARE or DSBCAPS_LOCSOFTWARE flags.

See Also: com.ms.directX.DSBufferDesc, duplicateSoundBuffer, setCooperativeLevel

duplicateSoundBuffer

public DirectSoundBuffer duplicateSoundBuffer(DirectSoundBuffer original);

Creates a new DirectSoundBuffer object that uses the same buffer memory as the original object.

Return Value:

Returns the DirectSoundBuffer object if successful; null otherwise.

Parameter	Description
original	The DirectSoundBuffer object to be duplicated.

Remarks:

The new object can be used just like the original.

Initially, the duplicate buffer will have the same parameters as the original buffer. However, the application can change the parameters of each buffer independently, and each can be played or stopped without affecting the other.

If data in the buffer is changed through one object, the change will be reflected in the other object since the buffer memory is shared.

The buffer memory will be released when the last object referencing it is released.

See Also: createSoundBuffer

enumSoundDrivers

public void enumSoundDrivers(IEnumSoundDriversCallback callback,
        IUnknown context);

Enumerates the DirectSound drivers installed in the system.

Return Value:

No return value.

Parameter	Description
callback	The IEnumSoundDriversCallback interface that contains the callback function to be called for each DirectSound object installed in the system.
context	User-defined context passed to the enumeration callback function every time that function is called.

getCaps

public void getCaps(DSCaps caps);

Retrieves the capabilities of the hardware device that is represented by the DirectSound object.

Return Value:

No return value.

Parameter	Description
caps	The DSCaps object that receives the capabilities of this sound device.

Remarks:

Information retrieved in the DSCaps object describes the maximum capabilities of the sound device and those currently available, such as the number of hardware mixing channels and the amount of onboard sound memory. This information can be used to fine-tune performance and optimize resource allocation.

Because of resource sharing requirements, the maximum capabilities in one area might only be available at the cost of another area. For example, the maximum number of hardware-mixed streaming sound buffers may only be available if there are no hardware static sound buffers.

See Also: directSoundCreate, com.ms.directX.DSCaps

getSpeakerConfig

public void getSpeakerConfig(int[] speakerConfig);

Retrieves the speaker configuration specified for this DirectSound object.

Return Value:

No return value.

Parameter	Description
speakerConfig	Array variable that receives the speaker configuration for this DirectSound object. The speaker configuration is specified with one value of DSSPEAKER_ type.

See Also: setSpeakerConfig

initialize

public void initialize(_Guid guid);

Initializes the DirectSound object if it has not yet been initialized.

Return Value:

No return value.

Parameter	Description
guid	The GUID specifying the sound driver for this DirectSound object to bind to, or null to select the primary sound driver.

setCooperativeLevel

public void setCooperativeLevel(int hwnd, int level);

Sets the cooperative level of the application for this sound device.

Return Value:

No return value.

Parameter	Description
hwnd	Window handle for the application.
level	One value of DSSCL_ type, specifying the requested priority level.

Remarks:

The application must set the cooperative level by calling this method before its buffers can be played. The recommended cooperative level is DSSCL_NORMAL; use other priority levels when necessary.

You must call the show() or addNotify() method before calling setCooperativeLevel

class Test implements DirectXConstants{

    void run(){
                  DirectSound ds = new DirectSound();
                  this.show();
                  ds.setCooperativeLevel(this,DSSCL_EXCLUSIVE);
              }
}

See Also: compact

setSpeakerConfig

public void setSpeakerConfig(int speakerConfig);

Specifies the speaker configuration for the DirectSound object.

Return Value:

No return value.

Parameter	Description
speakerConfig	One value of DSSPEAKER_ type, specifying the speaker configuration of the specified DirectSound object.

See Also: getSpeakerConfig