#include <LUA_API_Sound.h>

Public Member Functions
void	setLooped (int enableState)
	Set the looped state of the sound. This Function is used when creating a new sound. You need to set this function before calling createSound() or create3DSound(). More...

void	setVolume (float volume)
	Set the Volume of the new sound to create. This Function is used when creating a new sound. You need to set this function before calling createSound() or create3DSound(). More...

void	setPitch (float pitch)
	Set the Pitch of the new sound to create. This Function is used when creating a new sound. You need to set this function before calling createSound() or create3DSound(). More...

void	setSoundFile (string soundFilename)
	Set the Soundfile to use. This Function is used when creating a new sound. You need to set this function before calling createSound() or create3DSound(). More...

void	setIsStreamed (int enableState)
	Set whether the Soundfile is streamed from the hard drive. This Function is used when creating a new sound. You need to set this function before calling createSound() or create3DSound(). More...

int	createSound ()
	Create a new 2D Sound using the Properties you set by calling the previous functions. This will return a sound ID that you can use to identify the sound. More...

void	play2DSound (int soundID)
	Play the Specified sound by passing this function a Sound ID. More...

void	play3DSound (int soundID, float posX, float posY, float posZ)
	Play the Specified sound in 3D space by passing this function a Sound ID. This will play the sound at a location in world space. When the camera moves closer to the sound, then the volume increases. If the camera moves away from the sound, then the volume decreases. More...

void	stopSound (int soundID)
	Stop a sound that is currently playing. More...

int	isPlaying (int soundID)
	Check whether a sound is being played. Looped sounds are automatically stopped, so their playing flag changes to 0 when the loop stops. More...

void	changePosition (int soundID, float posX, float posY, float posZ)
	Change the location in world space of a 3D sound that is playing. The 3D sound can be accessed by passing the sound ID through the function. More...

void	changeVolume (int soundID, float volume)
	Change the Volume of a sound without stopping and playing the effect. It also works on sounds that loop and can be lengthy. More...

void	changePitch (int soundID, float pitch)
	Change the Pitch of a sound without stopping and restarting the effect. It also works on sounds that loop and sounds that are lengthy. More...

void	setRolloff (int soundID, float rolloff)
	Sets the sounds attenuation fall off amount ie how quicly the sound fades out. More...

void	setMaxDistance (int soundID, float distance)
	Sets the sounds max attenuation distance. At this distance the sound will be at its lowest volume or zero based on an exponential equation. Use the rolloff the change the attenuation curve. More...

void	setMinDistance (int soundID, float distance)
	Sets the sounds min attenuation distance. This is where the sound will be at its loudest before attenuation begins based on an exponential equation. More...

void	freeSound (int soundID)
	Frees the sound for reuse. It also works on sounds that loop and sounds that are lengthy. More...

sound	distanceAttenuation (int soundID, float minDistance, float maxDistance, float minimum, float maximum)
	add to an update() to give an spawned sound distance attenuation. More...

Detailed Description

The following ui functions can be used to display basic game play data, very light weight and handy when prototyping a game idea.
Use as sound.function()
For more information on how these functions can be used please visit the User Manual - https://home.aurasoft-skyline.co.uk

Here is a Global Example of how to create and use a Sound:

function onInit(objID)
    sound.setLooped( 1 );
    sound.setVolume( 1 );
    sound.setSoundFile( "My_Sound.ogg" );
    sound.setIsStreamed( 0 );
    sound_ID = sound.createSound();
    sound.play2DSound( sound_ID );
end

Member Function Documentation

void sound::changePitch	(	int	soundID,
		float	pitch
	)

Change the Pitch of a sound without stopping and restarting the effect. It also works on sounds that loop and sounds that are lengthy.

Parameters

soundID	: The sound the ID represents will be played.
pitch	: How loud the sound is. 0 - low pitch(0 is no sound), 1 - normal pitch. >1 higher pitch.

The following is a Small Example on how to use this function:

function onInit(objID)
    sound.changePitch( sound_ID, 0.5 );
end

void sound::changePosition	(	int	soundID,
		float	posX,
		float	posY,
		float	posZ
	)

Change the location in world space of a 3D sound that is playing. The 3D sound can be accessed by passing the sound ID through the function.

Parameters

soundID	: The sound the ID represents will be played.
posX	: The position on the X axis in world space to play this sound.
posY	: The position on the Y axis in world space to play this sound.
posZ	: The position on the Z axis in world space to play this sound.

The following is a Small Example on how to use this function:

function onInit(objID)
    x,y,z = entity.getPosition(objID);
    sound.changePosition( sound_ID, x, y, z );
end

void sound::changeVolume	(	int	soundID,
		float	volume
	)

Change the Volume of a sound without stopping and playing the effect. It also works on sounds that loop and can be lengthy.

Parameters

soundID	: The sound the ID represents will be played.
volume	: How loud the sound is. 0 - no sound, 1 - normal sound. >1 extra volume.

The following is a Small Example on how to use this function:

function onInit(objID)
    sound.changeVolume( sound_ID, 0.5 );
end

int sound::createSound ( )

Create a new 2D Sound using the Properties you set by calling the previous functions. This will return a sound ID that you can use to identify the sound.

Returns: soundID : The ID of the sound for use later. E.g. when playing the sound you will need the ID to reference the sound.

The following is a Small Example on how to use this function:

function onInit(objID)
    sound_ID = sound.createSound();
end

sound sound::distanceAttenuation	(	int	soundID,
		float	minDistance,
		float	maxDistance,
		float	minimum,
		float	maximum
	)

add to an update() to give an spawned sound distance attenuation.

Parameters

soundID	: The sound the ID represents will be freed.
minDistance	:
maxDistance	:
minimum	:
maximum	:

void sound::freeSound ( int soundID )

Frees the sound for reuse. It also works on sounds that loop and sounds that are lengthy.

Parameters

soundID : The sound the ID represents will be freed.

Frees the sound ID so that the 256 limit is not reached. It is advisable to call this from the lua stop event
to free the sound for reuse next time the game is played from the editor. This will not be an issue in the final game exe
only required for development.

The following is a Small Example on how to use this function:

function onStop(  )
    sound.freeSound(sound_ID);
end

int sound::isPlaying ( int soundID )

Check whether a sound is being played. Looped sounds are automatically stopped, so their playing flag changes to 0 when the loop stops.

Parameters

soundID : The sound ID to check if playing.

The following is a Small Example on how to use this function:

function update(objID)
    soundIsPlaying = sound.isPlaying(sound_ID);
    sky.lprint("soundIsPlaying"..soundIsPlaying);
end

-- should print 1 or 0

void sound::play2DSound ( int soundID )

Play the Specified sound by passing this function a Sound ID.

Parameters

soundID : The sound the ID represents will be played.
Use the Functions setLooped(), setVolume(), setPitch(), setSoundFile() and setIsStreamed() to control the properties of the sound to play.

The following is a Small Example on how to use this function:

function onInit(objID)
    sound.play2DSound( sound_ID );
end

void sound::play3DSound	(	int	soundID,
		float	posX,
		float	posY,
		float	posZ
	)

Play the Specified sound in 3D space by passing this function a Sound ID. This will play the sound at a location in world space. When the camera moves closer to the sound, then the volume increases. If the camera moves away from the sound, then the volume decreases.

Also has built in doppler effect.

Parameters

soundID	: The sound the ID represents will be played.
posX	: The position on the X axis in world space to play this sound.
posY	: The position on the Y axis in world space to play this sound.
posZ	: The position on the Z axis in world space to play this sound.

Use the Functions setLooped(), setVolume(), setPitch(), setSoundFile() and setIsStreamed() to control the properties of the sound to play.

The following is a Small Example on how to use this function:

function onInit(objID)
    sound.play3DSound( sound_ID, 0, 0, 0 );
end

void sound::setIsStreamed ( int enableState )

Set whether the Soundfile is streamed from the hard drive. This Function is used when creating a new sound.
You need to set this function before calling createSound() or create3DSound().

Parameters

enableState : 0 = false; 1 = true. Set whether the sound is streamed.

The following is a Small Example on how to use this function:

function onInit(objID)
    sound.setIsStreamed( 0 );
end

void sound::setLooped ( int enableState )

Set the looped state of the sound. This Function is used when creating a new sound.
You need to set this function before calling createSound() or create3DSound().

Parameters

enableState : 0 = false; 1 = true. Set whether this sound is looped or not

The following is a Small Example on how to use this function:

function onInit(objID)
    sound.setLooped( 1 );
end

void sound::setMaxDistance	(	int	soundID,
		float	distance
	)

Sets the sounds max attenuation distance. At this distance the sound will be at its lowest volume or zero based on an exponential equation. Use the rolloff the change the attenuation curve.

Parameters

soundID	: The sound the ID represents will be played.
distance	: The max attenuation distance.

The following is a Small Example on how to use this function:

function onInit(objID)
    sound.setMaxDistance(soundID,0.9);
end

void sound::setMinDistance	(	int	soundID,
		float	distance
	)

Sets the sounds min attenuation distance. This is where the sound will be at its loudest before attenuation begins based on an exponential equation.

Parameters

soundID	: The sound the ID represents will be played.
distance	: The min attenuation distance.

The following is a Small Example on how to use this function:

function onInit(objID)
    sound.setMinDistance(soundID,0.9);
end

void sound::setPitch ( float pitch )

Set the Pitch of the new sound to create. This Function is used when creating a new sound.
You need to set this function before calling createSound() or create3DSound().

Parameters

volume : Set the Pitch of the sound to create.

The following is a Small Example on how to use this function:

function onInit(objID)
    sound.setPitch( 1 );
end

void sound::setRolloff	(	int	soundID,
		float	rolloff
	)

Sets the sounds attenuation fall off amount ie how quicly the sound fades out.

Parameters

soundID	: The sound the ID represents will be played.
rolloff	: The attenuation falloff.

The following is a Small Example on how to use this function:

function onInit(objID)
    sound.setRolloff(soundID,0.9);
end

void sound::setSoundFile ( string soundFilename )

Set the Soundfile to use. This Function is used when creating a new sound.
You need to set this function before calling createSound() or create3DSound().

Parameters

soundFilename : Set the Soundfile to use. You will need to specify the file format the sound is in.

The following is a Small Example on how to use this function:

function onInit(objID)
    sound.setSoundFile( "My_Sound.ogg" );
end

void sound::setVolume ( float volume )

Set the Volume of the new sound to create. This Function is used when creating a new sound.
You need to set this function before calling createSound() or create3DSound().

Parameters

volume : Set the Volume of the sound to create.

The following is a Small Example on how to use this function:

function onInit(objID)
    sound.setVolume( 1 );
end

void sound::stopSound ( int soundID )

Stop a sound that is currently playing.

Parameters

soundID : The sound ID to stop playing.

The following is a Small Example on how to use this function:

function onInit(objID)
    sound.play3DSound( sound_ID, 0, 0, 0 );
end

function onKeyDown(key)
    if( key == "1" and sound.isPlaying(sound_ID) == 1 )then sound.stopSound(sound_ID); end
end

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

LUA_API_Sound.h

Public Member Functions

Detailed Description

Member Function Documentation