A sound (either memory-resident or streamed). More...

#include <sound.h>

Public Member Functions
void	setMixer (CkMixer *)
	Sets the mixer to which this sound is assigned.

CkMixer *	getMixer ()
	Gets the mixer to which this sound is assigned.

bool	isReady () const
	Returns true if the sound is ready.

bool	isFailed () const
	Returns true if an error occurred while creating the sound.

void	play ()
	Play the sound.

void	stop ()
	Stop the sound.

bool	isPlaying () const
	Gets whether the sound is playing.

void	setPaused (bool)
	Sets whether the sound is paused.

bool	isPaused () const
	Gets whether the sound is paused.

void	setLoop (int startFrame, int endFrame)
	Set the loop start and end.

void	getLoop (int &startFrame, int &endFrame) const
	Get the loop start and end.

void	setLoopCount (int)
	Sets the number of times the sound should loop.

int	getLoopCount () const
	Gets the number of times the sound should loop.

int	getCurrentLoop () const
	Gets the number of the current loop.

void	releaseLoop ()
	Makes the current loop the last.

void	setPlayPosition (int)
	Set the play position in the sound, in sample frames.

void	setPlayPositionMs (float)
	Set the play position in the sound, in milliseconds.

int	getPlayPosition () const
	Get the current play position in the sound, in sample frames.

float	getPlayPositionMs () const
	Get the current play position in the sound, in milliseconds.

void	setVolume (float)
	Sets the volume.

float	getVolume () const
	Gets the volume.

float	getMixedVolume () const
	Gets the volume value used for mixing.

void	setPan (float)
	Sets the pan.

float	getPan () const
	Gets the pan.

void	setPanMatrix (float ll, float lr, float rl, float rr)
	Sets the pan matrix explicitly.

void	getPanMatrix (float &ll, float &lr, float &rl, float &rr) const
	Gets the pan matrix.

void	setPitchShift (float halfSteps)
	Sets the pitch shift value, in half-steps.

float	getPitchShift () const
	Gets the pitch shift value, in half-steps.

void	setSpeed (float)
	Sets the playback speed.

float	getSpeed () const
	Gets the playback speed.

int	getLength () const
	Gets the total duration of the sound, in sample frames.

float	getLengthMs () const
	Gets the total duration of the sound, in milliseconds.

int	getSampleRate () const
	Gets the sample rate of the sound, in Hz.

int	getChannels () const
	Gets the number of channels in the sound (1 for mono, 2 for stereo).

void	setAudioCallback (CkAudioCallback, void *data)
	Sets a callback to be called for each slice of audio coming from this sound.

void	getAudioCallback (CkAudioCallback &, void *&data)
	Gets a callback to be called for each slice of audio coming from this sound.

void	set3dEnabled (bool)
	Sets whether 3D positioning is enabled.

bool	is3dEnabled () const
	Gets whether 3D positioning is enabled.

void	set3dPosition (float x, float y, float z)
	Sets the position of the sound emitter in 3D space.

void	get3dPosition (float &x, float &y, float &z) const
	Gets the position of the sound emitter in 3D space.

void	set3dVelocity (float vx, float vy, float vz)
	Sets the velocity of the sound emitter in 3D space.

void	get3dVelocity (float &vx, float &vy, float &vz) const
	Gets the velocity of the sound emitter in 3D space.

void	destroy ()
	Destroys the sound.

Static Public Member Functions
static void	set3dListenerPosition (float eyeX, float eyeY, float eyeZ, float lookAtX, float lookAtY, float lookAtZ, float upX, float upY, float upZ)
	Sets the listener position and rotation in 3D space.

static void	get3dListenerPosition (float &eyeX, float &eyeY, float &eyeZ, float &lookAtX, float &lookAtY, float &lookAtZ, float &upX, float &upY, float &upZ)
	Gets the listener position and rotation in 3D space.

static void	set3dListenerVelocity (float vx, float vy, float vz)
	Sets the listener velocity in 3D space.

static void	get3dListenerVelocity (float &vx, float &vy, float &vz)
	Gets the listener velocity in 3D space.

static void	set3dAttenuation (CkAttenuationMode mode, float nearDist, float farDist, float farVol)
	Sets parameters used for 3D volume attenuation.

static void	get3dAttenuation (CkAttenuationMode &mode, float &nearDist, float &farDist, float &farVol)
	Gets parameters used for 3D volume attenuation.

static void	set3dSoundSpeed (float)
	Sets the speed of sound.

static float	get3dSoundSpeed ()
	Gets the speed of sound.

static CkSound *	newBankSound (CkBank *, int index)
	Creates a sound from a bank by index.

static CkSound *	newBankSound (CkBank , const char name)
	Creates a sound from a bank by name.

static CkSound *	newStreamSound (const char *path, CkPathType=kCkPathType_Default)
	Creates a stream from a file path.

static CkSound *	newCustomStreamSound (CkCustomStream *)
	Creates a custom stream.

static CkSound *	newAssetStreamSound (const char *url)
	Creates a stream from a URL for an asset in the iTunes library.

static CkSound *	newNetworkStreamSound (const char *url)
	Creates an HTTP network stream.

Static Public Attributes
static const float	k_soundSpeed_CentimetersPerSecond
	The speed of sound in dry air at 20 degrees C, in centimeters per second.

static const float	k_soundSpeed_MetersPerSecond
	The speed of sound in dry air at 20 degrees C, in meters per second.

static const float	k_soundSpeed_InchesPerSecond
	The speed of sound in dry air at 20 degrees C, in inches per second.

static const float	k_soundSpeed_FeetPerSecond
	The speed of sound in dry air at 20 degrees C, in feet per second.

Detailed Description

A sound (either memory-resident or streamed).

Member Function Documentation

void CkSound::destroy ( )

Destroys the sound.

static void CkSound::get3dAttenuation	(	CkAttenuationMode &	mode,
		float &	nearDist,
		float &	farDist,
		float &	farVol
	)

static

Gets parameters used for 3D volume attenuation.

Parameters

mode	The attenuation mode
nearDist	The near distance; sounds closer than this distance will not be attenuated.
farDist	The far distance; sounds further than this will be at the far volume.
farVol	The far volume; sounds further than farDist will be at this volume.

static void CkSound::get3dListenerPosition	(	float &	eyeX,
		float &	eyeY,
		float &	eyeZ,
		float &	lookAtX,
		float &	lookAtY,
		float &	lookAtZ,
		float &	upX,
		float &	upY,
		float &	upZ
	)

static

Gets the listener position and rotation in 3D space.

This is used for pan and volume calculations when 3D positioning is enabled.

Parameters

eyeX,eyeY,eyeZ	The listener's position
lookAtX,lookAtY,lookAtZ	The listener's look-at point
upX,upY,upZ	The listener's up vector

static void CkSound::get3dListenerVelocity	(	float &	vx,
		float &	vy,
		float &	vz
	)

static

Gets the listener velocity in 3D space.

This is used for doppler shift calculations when 3D positioning is enabled. The units should be the same as those used for the set3dSoundSpeed().

void CkSound::get3dPosition	(	float &	x,
		float &	y,
		float &	z
	)		const

Gets the position of the sound emitter in 3D space.

This is used for pan and volume calculations when 3D positioning is enabled.

static float CkSound::get3dSoundSpeed ( )

static

Gets the speed of sound.

This is used for doppler shift calculations when 3D positioning is enabled.

void CkSound::get3dVelocity	(	float &	vx,
		float &	vy,
		float &	vz
	)		const

Gets the velocity of the sound emitter in 3D space.

This is used for doppler shift calculations when 3D positioning is enabled. The units should be the same as those used for the set3dSoundSpeed().

void CkSound::getAudioCallback	(	CkAudioCallback &	,
		void *&	data
	)

Gets a callback to be called for each slice of audio coming from this sound.

int CkSound::getChannels ( ) const

Gets the number of channels in the sound (1 for mono, 2 for stereo).

Stream sounds will return -1 if they are not ready.

int CkSound::getCurrentLoop ( ) const

Gets the number of the current loop.

For example, returns 0 if this is the first time playing through this sample; returns 1 if it is on its second loop through the sample; etc.

int CkSound::getLength ( ) const

Gets the total duration of the sound, in sample frames.

Stream sounds will return -1 if they are not ready or if the length is unknown.

float CkSound::getLengthMs ( ) const

Gets the total duration of the sound, in milliseconds.

Stream sounds will return -1 if they are not ready or if the length is unknown.

void CkSound::getLoop	(	int &	startFrame,
		int &	endFrame
	)		const

Get the loop start and end.

int CkSound::getLoopCount ( ) const

Gets the number of times the sound should loop.

0 means no looping (play once and then stop). 1 means it will play twice; 2 means it will play 3 times; etc. -1 means it will loop indefinitely until the sound is stopped or releaseLoop() is called.

float CkSound::getMixedVolume ( ) const

Gets the volume value used for mixing.

This is the product of the volume set with setVolume() and the mixed volume value of the mixer to which the sound is assigned.

CkMixer* CkSound::getMixer ( )

Gets the mixer to which this sound is assigned.

float CkSound::getPan ( ) const

Gets the pan.

The pan can range from -1 (left) to +1 (right). The default is 0 (center).

void CkSound::getPanMatrix	(	float &	ll,
		float &	lr,
		float &	rl,
		float &	rr
	)		const

Gets the pan matrix.

The pan matrix determines how the left and right channels of an input are weighted during mixing. Usually it is set by setPan(), but you can use setPanMatrix() if you need more control. For a mono input, the left channel of the output is the input scaled by ll, and the right channel of the output is the input scaled by rr. The off-diagonal lr and rl terms are ignored. For a stereo input, the left channel of the output is the left channel of the input scaled by ll plus the right channel of the input scaled by lr. The right channel of the output is the left channel of the input scaled by rl plus the right channel of the input scaled by rr.

float CkSound::getPitchShift ( ) const

Gets the pitch shift value, in half-steps.

Positive values mean higher pitch (and faster playback); lower values mean lower pitch (and slower playback). The default value is 0.

Android note:: This does not work for streams in formats other than .cks.

int CkSound::getPlayPosition ( ) const

Get the current play position in the sound, in sample frames.

float CkSound::getPlayPositionMs ( ) const

Get the current play position in the sound, in milliseconds.

int CkSound::getSampleRate ( ) const

Gets the sample rate of the sound, in Hz.

Stream sounds will return -1 if they are not ready.

float CkSound::getSpeed ( ) const

Gets the playback speed.

Values greater than 1 mean faster playback; values less than 1 mean slower playback. The default value is 1.

Android note:: This does not work for streams in formats other than .cks.

float CkSound::getVolume ( ) const

Gets the volume.

The volume can range from 0 to 1. The default value is 1.

bool CkSound::is3dEnabled ( ) const

Gets whether 3D positioning is enabled.

If enabled, pan will be determined by the sound and listener positions, ignoring the value set by setPan(). Volume will be attenuated based on the sound and listener positions and the attenuation settings.

bool CkSound::isFailed ( ) const

Returns true if an error occurred while creating the sound.

bool CkSound::isPaused ( ) const

Gets whether the sound is paused.

bool CkSound::isPlaying ( ) const

Gets whether the sound is playing.

bool CkSound::isReady ( ) const

Returns true if the sound is ready.

Bank sounds are ready immediately after creation; stream sounds may not be.

static CkSound* CkSound::newAssetStreamSound ( const char * url )

static

Creates a stream from a URL for an asset in the iTunes library.

The URL should be determined using an MPMediaQuery object; see the "iPod Library Access Programming Guide" document in the iOS Developer Library. Note that this will only work for music files without DRM; for such files the URL will be returned as nil.

Only available on iOS version 4.3 or later.

static CkSound* CkSound::newBankSound	(	CkBank *	,
		int	index
	)

static

Creates a sound from a bank by index.

static CkSound* CkSound::newBankSound	(	CkBank *	,
		const char *	name
	)

static

Creates a sound from a bank by name.

If bank is NULL, all loaded banks are searched for the first matching sound.

static CkSound* CkSound::newCustomStreamSound ( CkCustomStream * )

static

Creates a custom stream.

This could be used, for example, for streaming audio from a proprietary file format.

static CkSound* CkSound::newNetworkStreamSound ( const char * url )

static

Creates an HTTP network stream.

Only available on Android, and only for formats other than .cks.

static CkSound* CkSound::newStreamSound	(	const char *	path,
		CkPathType	= `kCkPathType_Default`
	)

static

Creates a stream from a file path.

void CkSound::play ( )

Play the sound.

void CkSound::releaseLoop ( )

Makes the current loop the last.

This is useful when you don't know in advance how many times you will want to loop; set the loop count to -1, and call releaseLoop() when you want it to stop looping and play to the end.

static void CkSound::set3dAttenuation	(	CkAttenuationMode	mode,
		float	nearDist,
		float	farDist,
		float	farVol
	)

static

Sets parameters used for 3D volume attenuation.

Parameters

mode	The attenuation mode (default is kCkAttenuationMode_InvDistanceSquared)
nearDist	The near distance; sounds closer than this distance will not be attenuated (default is 1.0)
farDist	The far distance; sounds further than this will be at the far volume (default is 100.0)
farVol	The far volume; sounds further than farDist will be at this volume (default is 0.0)

void CkSound::set3dEnabled ( bool )

Sets whether 3D positioning is enabled.

If enabled, pan will be determined by the sound and listener positions, ignoring the value set by setPan(). Volume will be attenuated based on the sound and listener positions and the attenuation settings.

static void CkSound::set3dListenerPosition	(	float	eyeX,
		float	eyeY,
		float	eyeZ,
		float	lookAtX,
		float	lookAtY,
		float	lookAtZ,
		float	upX,
		float	upY,
		float	upZ
	)

static

Sets the listener position and rotation in 3D space.

This is used for pan and volume calculations when 3D positioning is enabled.

Parameters

eyeX,eyeY,eyeZ	The listener's position
lookAtX,lookAtY,lookAtZ	The listener's look-at point
upX,upY,upZ	The listener's up vector

static void CkSound::set3dListenerVelocity	(	float	vx,
		float	vy,
		float	vz
	)

static

Sets the listener velocity in 3D space.

This is used for doppler shift calculations when 3D positioning is enabled. The units should be the same as those used for the set3dSoundSpeed().

void CkSound::set3dPosition	(	float	x,
		float	y,
		float	z
	)

Sets the position of the sound emitter in 3D space.

This is used for pan and volume calculations when 3D positioning is enabled.

static void CkSound::set3dSoundSpeed ( float )

static

Sets the speed of sound.

This is used for doppler shift calculations when 3D positioning is enabled. If no doppler shift is desired, this can be set to 0 (which is the default value). You may want to use the predefined constants for the speed of sound (such as k_soundSpeed_MetersPerSecond); use the constant that corresponds to the unit system you are using for your velocity and position values. You can also exaggerate the doppler effect by using a smaller value.

void CkSound::set3dVelocity	(	float	vx,
		float	vy,
		float	vz
	)

Sets the velocity of the sound emitter in 3D space.

This is used for doppler shift calculations when 3D positioning is enabled. The units should be the same as those used for the set3dSoundSpeed().

void CkSound::setAudioCallback	(	CkAudioCallback	,
		void *	data
	)

Sets a callback to be called for each slice of audio coming from this sound.

This will be called on a thread that is not the main thread; be sure not to spend too much time in the callback.

Android note:: This does not work for streams in formats other than .cks.

void CkSound::setLoop	(	int	startFrame,
		int	endFrame
	)

Set the loop start and end.

Default is to loop over all sample frames. EndFrame is defined as one frame after the last frame of the loop. Setting endFrame = -1 is equivalent to setting it to getLength().

Android note:: This has no effect for streams in formats other than .cks.

void CkSound::setLoopCount ( int )

Sets the number of times the sound should loop.

0 means no looping (play once and then stop). 1 means it will play twice; 2 means it will play 3 times; etc. -1 means it will loop indefinitely until the sound is stopped or releaseLoop() is called.

void CkSound::setMixer ( CkMixer * )

Sets the mixer to which this sound is assigned.

Setting NULL will assign it to the master mixer.

void CkSound::setPan ( float )

Sets the pan.

The pan can range from -1 (left) to +1 (right). The default is 0 (center).

void CkSound::setPanMatrix	(	float	ll,
		float	lr,
		float	rl,
		float	rr
	)

Sets the pan matrix explicitly.

The pan matrix determines how the left and right channels of an input are weighted during mixing. Usually it is set by setPan(), but you can use setPanMatrix() if you need more control. For a mono input, the left channel of the output is the input scaled by ll, and the right channel of the output is the input scaled by rr. The off-diagonal lr and rl terms are ignored. For a stereo input, the left channel of the output is the left channel of the input scaled by ll plus the right channel of the input scaled by lr. The right channel of the output is the left channel of the input scaled by rl plus the right channel of the input scaled by rr.

void CkSound::setPaused ( bool )

Sets whether the sound is paused.

void CkSound::setPitchShift ( float halfSteps )

Sets the pitch shift value, in half-steps.

This also changes the playback speed of the sound. Positive values mean higher pitch (and faster playback); lower values mean lower pitch (and slower playback). The default value is 0.

Android note:: This does not work for streams in formats other than .cks.

void CkSound::setPlayPosition ( int )

Set the play position in the sound, in sample frames.

This can be called before playing, to start from an offset into the sound; or during playback, to jump to a new location.

void CkSound::setPlayPositionMs ( float )

Set the play position in the sound, in milliseconds.

This can be called before playing, to start from an offset into the sound; or during playback, to jump to a new location.

void CkSound::setSpeed ( float )

Sets the playback speed.

Values greater than 1 mean faster playback; values less than 1 mean slower playback. The default value is 1.

Android note:: This does not work for streams in formats other than .cks.

void CkSound::setVolume ( float )

Sets the volume.

The volume can range from 0 to 1. The default value is 1.

void CkSound::stop ( )

Stop the sound.

Member Data Documentation

const float CkSound::k_soundSpeed_CentimetersPerSecond

static

The speed of sound in dry air at 20 degrees C, in centimeters per second.

This value is provided as a convenience for CkSound::set3dSoundSpeed().

const float CkSound::k_soundSpeed_FeetPerSecond

static

The speed of sound in dry air at 20 degrees C, in feet per second.

This value is provided as a convenience for CkSound::set3dSoundSpeed().

const float CkSound::k_soundSpeed_InchesPerSecond

static

The speed of sound in dry air at 20 degrees C, in inches per second.

This value is provided as a convenience for CkSound::set3dSoundSpeed().

const float CkSound::k_soundSpeed_MetersPerSecond

static

The speed of sound in dry air at 20 degrees C, in meters per second.

This value is provided as a convenience for CkSound::set3dSoundSpeed().

The documentation for this class was generated from the following file:

sound.h

Public Member Functions

Static Public Member Functions

Static Public Attributes

Detailed Description

Member Function Documentation

Member Data Documentation