Entire Class Index | Main Class Index | Cross Index | Global Index

# Class CL_SoundBuffer_Session

CL_SoundBuffer_Session provides control over a playing soundeffect.
Contained in: global
Derived from: none
Derived by: none
Group: Sound (Audio Mixing)

#include <ClanLib/sound.h>

### public function member index:

### Construction:

`` | `CL_SoundBuffer_Session` | `()`;
`` | `CL_SoundBuffer_Session` | `(`void`* `handle`, `CL_SoundCard`* `_card`)`;
`` | `CL_SoundBuffer_Session` | `(`const` `CL_SoundBuffer_Session`& `copy`)`;
`` | `~CL_SoundBuffer_Session` | `()`;

### Operators:

``CL_SoundBuffer_Session`&` | `operator``=` | `(`const` `CL_SoundBuffer_Session`& `session`)`;

### Attributes:

``void`*` | `get_handle` | `() `const``;
``CL_SoundCard`*` | `get_card` | `() `const``;
``int`` | `get_position` | `() `const``;
``float`` | `get_position_relative` | `() `const``;
``bool`` | `set_position` | `(`int` `new_pos`)`;
``bool`` | `set_position_relative` | `(`float` `new_pos`)`;
``int`` | `get_length` | `() `const``;
``int`` | `get_frequency` | `() `const``;
``bool`` | `set_frequency` | `(`int` `new_freq`)`;
``float`` | `get_volume` | `() `const``;
``float`` | `get_pan` | `() `const``;

### Operations:

``bool`` | `set_volume` | `(`float` `new_volume`)`;
``bool`` | `set_pan` | `(`float` `new_pan`)`;
``void`` | `play` | `()`;
``void`` | `stop` | `()`;
``bool`` | `is_playing` | `()`;
``void`` | `set_looping` | `(`bool` `loop`)`;
``void`` | `add_filter` | `(`class` `CL_SoundFilter`* `filter`, `bool` `delete_filter` = false)`;
``void`` | `remove_filter` | `(`class` `CL_SoundFilter`* `filter`)`;

## Description:

Whenever a soundbuffer is played, it returns a CL_SoundBuffer_Session class, which can be used to control the sound (its volume, pitch, pan, position). It can of course also be used to retrigger the sound or to stop it. The soundeffect is stored in the layer1 soundmanager until all references to the sound played are removed, meaning that the soundeffect (session) will be ready to play and remember its state and settings (volume, frequency...) until no CL_SoundBuffer_Session refers to it, via a soundbuffer session reference system.

## Function Member Descriptions:

CL_SoundBuffer_Session::CL_SoundBuffer_Session - Creates a soundbuffer session not attached to any object.
`` `CL_SoundBuffer_Session` `()`;

CL_SoundBuffer_Session::CL_SoundBuffer_Session - Sound Buffer Session Constructor
`` `CL_SoundBuffer_Session` `(`void`* `handle`, `CL_SoundCard`* `_card`)`;

CL_SoundBuffer_Session::CL_SoundBuffer_Session - Copy constructor.
`` `CL_SoundBuffer_Session` `(`const` `CL_SoundBuffer_Session`& `copy`)`;

CL_SoundBuffer_Session::add_filter - Adds the sound filter to the session. See CL_SoundFilter for details.
``void`` `add_filter` `(`class` `CL_SoundFilter`* `filter`, `bool` `delete_filter` = false)`;

> filter - Sound filter to pass sound through.
> delete_filter - If true, the filter will be deleted when the session is destroyed.

CL_SoundBuffer_Session::get_card - Returns a pointer to the card on which the soundbuffer controlled
is played/playing.
``CL_SoundCard`*` `get_card` `() `const``;

> Returns - Pointer to soundcard

CL_SoundBuffer_Session::get_frequency - Returns the frequency of the soundeffect played.
``int`` `get_frequency` `() `const``;

> Returns - Frequency of soundeffect played.

CL_SoundBuffer_Session::get_handle - Get Handle
``void`*` `get_handle` `() `const``;

CL_SoundBuffer_Session::get_length - Returns the total length of the soundeffect played.
Value returned will be -1 if the length is unknown (in case of non-static soundeffects like streamed sound)
``int`` `get_length` `() `const``;

> Returns - Length of the soundeffect.

CL_SoundBuffer_Session::get_pan - Returns the current pan (in a measure from -1 -> 1), where -1 means the soundeffect is only playing in the left speaker, and 1 means the soundeffect is only playing in the right speaker.
``float`` `get_pan` `() `const``;

> Returns - Current pan of the soundeffect played.

CL_SoundBuffer_Session::get_position - Returns the current position of the soundeffect
``int`` `get_position` `() `const``;

> Returns - Current position of soundeffect.

CL_SoundBuffer_Session::get_position_relative - Returns the soundeffects relative position, compared to the total length of the soundeffect.
The value returned will be between 0->1, where 0 means the soundeffect is at the beginning, and 1 means that the soundeffect has reached the end.
``float`` `get_position_relative` `() `const``;

> Returns - Relative position of the soundeffect.

CL_SoundBuffer_Session::get_volume - Returns the linear relative volume of the soundeffect.
0 means the soundeffect is muted, 1 means the soundeffect is playing at "max" volume.
``float`` `get_volume` `() `const``;

> Returns - Volume of soundeffect played.

CL_SoundBuffer_Session::is_playing - Returns true if the session is playing
``bool`` `is_playing` `()`;

CL_SoundBuffer_Session::operator = - Copy operator
``CL_SoundBuffer_Session`&` `operator``=` `(`const` `CL_SoundBuffer_Session`& `session`)`;

CL_SoundBuffer_Session::play - Starts playback of the session.
``void`` `play` `()`;

CL_SoundBuffer_Session::remove_filter - Remove the sound filter from the session. See CL_SoundFilter for details.
``void`` `remove_filter` `(`class` `CL_SoundFilter`* `filter`)`;

CL_SoundBuffer_Session::set_frequency - Sets the frequency of the soundeffect played.
``bool`` `set_frequency` `(`int` `new_freq`)`;

> New frequency of soundeffect.
> Returns - Returns true, if the operation completed succesfully.

CL_SoundBuffer_Session::set_looping - Determines whether this session should loop
``void`` `set_looping` `(`bool` `loop`)`;

> loop - true if session should loop, false otherwise

CL_SoundBuffer_Session::set_pan - Sets the panning of the soundeffect played in measures from -1 -> 1
Setting the pan with a value of -1 will pan the soundeffect to the extreme left (left speaker only), 1 will pan the soundeffect to the extreme right (right speaker only).
``bool`` `set_pan` `(`float` `new_pan`)`;

> new_pan - New pan of the soundeffect played.
> Returns - Returns true if the operation completed sucecsfully.

CL_SoundBuffer_Session::set_position - Sets the soundeffects position to 'new_pos'.
``bool`` `set_position` `(`int` `new_pos`)`;

> The new position of the soundeffect.
> Returns - Returns true if operation completed succesfully.

CL_SoundBuffer_Session::set_position_relative - Sets the relative position of the soundeffect.
Value must be between 0->1, where 0 sets the soundeffect to the beginning, and 1 sets it to the end of the soundbuffer.
``bool`` `set_position_relative` `(`float` `new_pos`)`;

> New relative position
> Returns - Returns true if operation completed succesfully.

CL_SoundBuffer_Session::set_volume - Sets the volume of the soundeffect in a relative measure (0->1)
A value of 0 will effectively mute the sound (although it will still be sampled), and a value of 1 will set the volume to "max".
``bool`` `set_volume` `(`float` `new_volume`)`;

> new_volume - New volume of soundeffect
> Returns - Returns true if the operation completed succesfully.

CL_SoundBuffer_Session::stop - Stops playback of the session.
``void`` `stop` `()`;

CL_SoundBuffer_Session::~CL_SoundBuffer_Session - Sound Buffer Session Destructor
`` `~CL_SoundBuffer_Session` `()`;

## Variable Member Descriptions: