BGameSound Class Reference

BGameSound is the base class used in the other sound classes in the kit. More...

Inherited by BSimpleGameSound, and BStreamingGameSound.

Public Member Functions
	BGameSound (BGameSoundDevice *device=NULL)
	Creates a BGameSound object.
virtual	~BGameSound ()
	Destroys the BGameSound object and frees the memory it uses.
virtual BGameSound *	Clone () const =0
	Pure virtual method to create a copy of the BGameSound object.
BGameSoundDevice *	Device () const
	Returns a pointer to the sound playback device.
const gs_audio_format &	Format () const
	Returns a gs_audio_format struct instance with the format of the sound associated with the BGameSound object.
gs_id	ID () const
	Returns the identifier of the sound associated with the BGameSound object.
status_t	InitCheck () const
	Verifies if the BGameSound object was successfully initialized.
Playback
virtual status_t	StartPlaying ()
	Plays the sound in the playback device.
virtual bool	IsPlaying ()
	Checks whether the sound is being played or not in the playback device.
virtual status_t	StopPlaying ()
	Stops the playback of a sound currently playing.
Sound Attributes
status_t	SetGain (float gain, bigtime_t duration=0)
	Sets the gain of the sound, that is, the amount of amplification of the input signal.
status_t	SetPan (float pan, bigtime_t duration=0)
	Sets the panning of the sound, that is, the distribution of the audio signal anywhere in the stereophonic sound field.
float	Gain ()
	Retrieves the current level of gain of the sound.
float	Pan ()
	Retrieves the current value of panning of the sound.
virtual status_t	SetAttributes (gs_attribute *attributes, size_t attributeCount)
	Sets the attributes for the current sound.
virtual status_t	GetAttributes (gs_attribute *attributes, size_t attributeCount)
	Retrieves the attributes of the current sound.

Detailed Description

BGameSound is the base class used in the other sound classes in the kit.

This class is not meant to be used directly. Any of the derived classes should be used instead.

Since

BeOS R4.5

Constructor & Destructor Documentation

BGameSound()

BGameSound::BGameSound

(

BGameSoundDevice *

device = NULL

)

Creates a BGameSound object.

The device parameter is currently unused and has to be defined as NULL. Currently the class itself will retrieve the default device.

Parameters

[in]

device

The sound device to be used.

Since

BeOS R4.5

~BGameSound()

BGameSound::~BGameSound ( )

virtual

Destroys the BGameSound object and frees the memory it uses.

It releases any buffer connected to the game sound device and then releases the device itself.

Since

BeOS R4.5

Member Function Documentation

Clone()

BGameSound * BGameSound::Clone ( ) const

pure virtual

Pure virtual method to create a copy of the BGameSound object.

Since

BeOS R4.5

Implemented in BFileGameSound.

Device()

BGameSoundDevice * BGameSound::Device

(

)

const

Returns a pointer to the sound playback device.

Since

BeOS R4.5

Format()

const gs_audio_format & BGameSound::Format

(

)

const

Returns a gs_audio_format struct instance with the format of the sound associated with the BGameSound object.

Since

BeOS R4.5

Gain()

float BGameSound::Gain

(

)

Retrieves the current level of gain of the sound.

If there is no sound initialized, by default it returns 0.0.

Since

BeOS R4.5

GetAttributes()

status_t BGameSound::GetAttributes ( gs_attribute *  attributes, size_t  attributeCount  )

virtual

Retrieves the attributes of the current sound.

attributes is a pre-allocated array of gs_attribute structures, with the "attribute" field of each one pre-filled with the desired attribute's identifier, for which the information is going to be retrieved.

Parameters

[out]	attributes	The gs_attribute list where to save the attributes.
[in]	attributeCount	The number of items in the attributes list.

Return values

B_OK	The attributes were retrieved successfully.
B_ERROR	The BGameSound's sound was not initialized.

Since

BeOS R4.5

ID()

gs_id BGameSound::ID

(

)

const

Returns the identifier of the sound associated with the BGameSound object.

Since

BeOS R4.5

InitCheck()

status_t BGameSound::InitCheck

(

)

const

Verifies if the BGameSound object was successfully initialized.

Since

BeOS R4.5

IsPlaying()

bool BGameSound::IsPlaying ( )

virtual

Checks whether the sound is being played or not in the playback device.

Return values

true	The sound is currently being played.
false	The sound is not being played.

Since

BeOS R4.5

Pan()

float BGameSound::Pan

(

)

Retrieves the current value of panning of the sound.

If there is no sound initialized, by default it returns 0.0.

Since

BeOS R4.5

SetAttributes()

status_t BGameSound::SetAttributes ( gs_attribute *  attributes, size_t  attributeCount  )

virtual

Sets the attributes for the current sound.

Parameters

[in]	attributes	An array of the group of attributes to be applied to the sound.
[in]	attributeCount	The number of those attributes.

Return values

B_OK	The attributes were applied successfully, or no error.
B_ERROR	The BGameSound's sound was not initialized.
others	Depending on the type of attribute.

Since

BeOS R4.5

SetGain()

status_t BGameSound::SetGain	(	float	gain,
		bigtime_t	duration = 0
	)

Sets the gain of the sound, that is, the amount of amplification of the input signal.

The gain is represented as a proportion, from 0.0 as the lowest to 1.0 as the highest level of gain.

A non-zero duration makes the transition from the current gain to the new gain take place over time in the amount set (in microseconds). If it is 0, the change occurs immediately instead.

Parameters

[in]	gain	Level of sound gain.
[in]	duration	Duration of transition from the older gain level to the newer level.

Return values

B_OK	The gain was applied successfully.
B_BAD_VALUE	An out-of-bounds value for the gain was provided (not being 0.0 <= gain <= 1.0).

Since

BeOS R4.5

SetPan()

status_t BGameSound::SetPan	(	float	pan,
		bigtime_t	duration = 0
	)

Sets the panning of the sound, that is, the distribution of the audio signal anywhere in the stereophonic sound field.

A value of pan of -1.0 sets the sound at the most left side, 0.0 at the front, and 1.0 at the most right side.

A non-zero duration makes the transition from the current pan to the new pan take place over time in the amount set (in microseconds). If it is 0, the change occurs immediately instead.

Parameters

[in]	pan	Level of panning.
[in]	duration	Duration of transition from the older panning value to the newer value.

Return values

B_OK	The pan was applied successfully.
B_ERROR	The BGameSound's sound was not initialized.
B_BAD_VALUE	An out-of-bounds value for the pan was provided (not being -1.0 <= pan <= 1.0).

Since

BeOS R4.5

StartPlaying()

status_t BGameSound::StartPlaying ( )

virtual

Plays the sound in the playback device.

Return values

B_OK	Playback started successfully.

Since

BeOS R4.5

Reimplemented in BFileGameSound.

StopPlaying()

status_t BGameSound::StopPlaying ( )

virtual

Stops the playback of a sound currently playing.

Return values

B_OK	The sound stopped playing.

Since

BeOS R4.5

Reimplemented in BFileGameSound.