SecondaryBuffer.SetEffects Method

Language:

How Do I...?

Add Effects to a SecondaryBuffer Object

Enables effects on a SecondaryBuffer object.

Definition

Visual Basic Public Function SetEffects( _
    ByVal dsEff() As EffectDescription _
) As EffectsReturnValue()

C# public EffectsReturnValue[] SetEffects(
    EffectDescription[] dsEff
);

C++ public:
array<EffectsReturnValue>^ SetEffects(
    array<EffectDescription>^ dsEff
);

JScript public function SetEffects(
    dsEff : EffectDescription[]
) : EffectsReturnValue[];

Visual Basic	Public Function SetEffects( _ ByVal dsEff() As EffectDescription _ ) As EffectsReturnValue()
C#	public EffectsReturnValue[] SetEffects( EffectDescription[] dsEff );
C++	public: array<EffectsReturnValue>^ SetEffects( array<EffectDescription>^ dsEff );
JScript	public function SetEffects( dsEff : EffectDescription[] ) : EffectsReturnValue[];

Parameters

dsEff Microsoft.DirectX.DirectSound.EffectDescription[]
An Array of EffectDescription structures that contains descriptions of the effects to set in the SecondaryBuffer object.

Return Value

Microsoft.DirectX.DirectSound.EffectsReturnValue[]
An array that contains one element for each of the Microsoft DirectSound effect objects that was assigned to the SecondaryBuffer object. One of the following values is returned for each DirectSound effect object.

Remarks

If the method fails, the return value for each effect in EffectsReturnValue is either Present or Unknown. Check these values to determine which effects caused the failure.

For the method to succeed, the buffer must have been created with the BufferDescription.ControlEffects set to true and must not be playing or locked.

If the method throws a SoundException, check the result code array for Present or Unknown to ascertain which effect caused the error. If the method throws an ArgumentException , check the result codes for Failed to see which effects failed to acquire resources.

An effect must be set on a buffer before the effect interface can be obtained. To obtain the effect interface, use SecondaryBuffer.GetEffects or SecondaryBuffer.GetObjectInPath.

Exceptions

ArgumentException An invalid parameter was passed to the called method.

ControlUnavailableException The buffer control (volume, pan, and so on) requested by the caller is not available. Controls must be specified when the buffer is created.

InvalidCallException The method call is invalid for the current state of this object.

PriorityLevelNeededException A cooperative level of Priority or higher is required.

SoundException Root exception type for all DirectSound Exceptions. Derives from DirectXException.

How Do I...?

Add Effects to a SecondaryBuffer Object

This C# example demonstrates how to add effect objects to a SecondaryBuffer object.

              [C#]
              

//Create and setup the sound device.
Device dev = new Device();
dev.SetCooperativeLevel(this,CooperativeLevel.Normal);

//Create and setup the buffer description.
BufferDescription buffer_desc = new BufferDescription();
buffer_desc.ControlEffects = true; //this has to be true to use effects.
buffer_desc.GlobalFocus = true; //play sound even if application loses focus.

//Create and setup the buffer for playing the sound.
SecondaryBuffer buffer = new SecondaryBuffer(
	@"C:\WINDOWS\Media\ding.wav", 
	buffer_desc, 
	dev);

//Create an array of effects descriptions, 
//set the effect objects to echo and chorus and 
//set it in the buffer.
EffectDescription[] effects = new EffectDescription[2];
effects[0].GuidEffectClass = DSoundHelper.StandardEchoGuid;
effects[1].GuidEffectClass = DSoundHelper.StandardChorusGuid;
buffer.SetEffects(effects);

//Play Buffer.
buffer.Play(0,BufferPlayFlags.Default);

ArgumentException	An invalid parameter was passed to the called method.
ControlUnavailableException	The buffer control (volume, pan, and so on) requested by the caller is not available. Controls must be specified when the buffer is created.
InvalidCallException	The method call is invalid for the current state of this object.
PriorityLevelNeededException	A cooperative level of Priority or higher is required.
SoundException	Root exception type for all DirectSound Exceptions. Derives from DirectXException.