Added rdoc comments to all audio classes.

git-svn-id: https://sfml.svn.sourceforge.net/svnroot/sfml/branches/sfml2@1714 4e206d99-4929-0410-ac5d-dfc041789085
This commit is contained in:
groogy 2010-11-25 19:30:10 +00:00
parent 191776fbec
commit 50a5ecd79f
7 changed files with 336 additions and 2 deletions

View File

@ -34,11 +34,25 @@ static VALUE Music_Free( sf::Music *anObject )
delete anObject;
}
/* call-seq:
* Music.new() -> music
*
* Creates a new music instance.
*/
static VALUE Music_Initialize( int argc, VALUE *args, VALUE self )
{
return self;
}
/* call-seq:
* music.openFromFile() -> true or false
*
* Open a music from an audio file.
*
* This function doesn't start playing the music (call Play() to do so). Here is a complete list of all the supported
* audio formats: ogg, wav, flac, aiff, au, raw, paf, svx, nist, voc, ircam, w64, mat4, mat5 pvf, htk, sds, avr, sd2,
* caf, wve, mpc2k, rf64.
*/
static VALUE Music_OpenFromFile( VALUE self, VALUE aFilename )
{
sf::Music *object = NULL;
@ -53,6 +67,11 @@ static VALUE Music_OpenFromFile( VALUE self, VALUE aFilename )
}
}
/* call-seq:
* music.getDuration() -> float
*
* Get the total duration of the music.
*/
static VALUE Music_GetDuration( VALUE self )
{
sf::Music *object = NULL;
@ -111,7 +130,7 @@ void Init_Music( void )
rb_define_singleton_method( globalMusicClass, "new", Music_New, -1 );
// Instance methods
rb_define_method( globalMusicClass, "initialize", Music_Initialize, -1 );
rb_define_method( globalMusicClass, "initialize", Music_Initialize, 0 );
rb_define_method( globalMusicClass, "openFromFile", Music_OpenFromFile, 1 );
rb_define_method( globalMusicClass, "getDuration", Music_GetDuration, 0 );

View File

@ -37,6 +37,11 @@ static void Sound_Free( sf::Sound *anObject )
delete anObject;
}
/* call-seq:
* Sound.new() -> sound
*
* Creates a new sound instance.
*/
static VALUE Sound_Initialize( int argc, VALUE *args, VALUE self )
{
sf::Sound *object = NULL;
@ -86,6 +91,14 @@ static VALUE Sound_Initialize( int argc, VALUE *args, VALUE self )
return self;
}
/* call-seq:
* sound.play()
*
* Start or resume playing the sound.
*
* This function starts the sound if it was stopped, resumes it if it was paused, and does nothing it is it already
* playing. This function uses its own thread so that it doesn't block the rest of the program while the sound is played.
*/
static VALUE Sound_Play( VALUE self )
{
sf::Sound *object = NULL;
@ -94,6 +107,13 @@ static VALUE Sound_Play( VALUE self )
return Qnil;
}
/* call-seq:
* sound.pause()
*
* Pause the sound.
*
* This function pauses the sound if it was playing, otherwise (sound already paused or stopped) it has no effect.
*/
static VALUE Sound_Pause( VALUE self )
{
sf::Sound *object = NULL;
@ -102,6 +122,14 @@ static VALUE Sound_Pause( VALUE self )
return Qnil;
}
/* call-seq:
* sound.stop()
*
* Stop playing the sound.
*
* This function stops the sound if it was playing or paused, and does nothing if it was already stopped. It also
* resets the playing position (unlike pause()).
*/
static VALUE Sound_Stop( VALUE self )
{
sf::Sound *object = NULL;
@ -110,6 +138,14 @@ static VALUE Sound_Stop( VALUE self )
return Qnil;
}
/* call-seq:
* sound.setBuffer( buffer )
*
* Set the source buffer containing the audio data to play.
*
* It is important to note that the sound buffer is not copied, thus the sf::SoundBuffer instance must remain alive as
* long as it is attached to the sound.
*/
static VALUE Sound_SetBuffer( VALUE self, VALUE aBuffer )
{
VALIDATE_CLASS( aBuffer, globalSoundBufferClass, "buffer" );
@ -122,6 +158,14 @@ static VALUE Sound_SetBuffer( VALUE self, VALUE aBuffer )
return Qnil;
}
/* call-seq:
* sound.setLoop( loop )
*
* Set whether or not the sound should loop after reaching the end.
*
* If set, the sound will restart from beginning after reaching the end and so on, until it is stopped or
* setLoop(false) is called. The default looping state for sound is false.
*/
static VALUE Sound_SetLoop( VALUE self, VALUE aLoop )
{
sf::Sound *object = NULL;
@ -141,6 +185,13 @@ static VALUE Sound_SetLoop( VALUE self, VALUE aLoop )
return Qnil;
}
/* call-seq:
* sound.setPlayingOffset( offset )
*
* Change the current playing position of the sound.
*
* The playing position can be changed when the sound is either paused or playing.
*/
static VALUE Sound_SetPlayingOffset( VALUE self, VALUE aOffset )
{
sf::Sound *object = NULL;
@ -149,11 +200,21 @@ static VALUE Sound_SetPlayingOffset( VALUE self, VALUE aOffset )
return Qnil;
}
/* call-seq:
* sound.getBuffer() -> buffer
*
* Get the audio buffer attached to the sound.
*/
static VALUE Sound_GetBuffer( VALUE self )
{
return rb_iv_get( self, "@__buffer_ref" );
}
/* call-seq:
* sound.getLoop() -> true or false
*
* Tell whether or not the sound is in loop mode.
*/
static VALUE Sound_GetLoop( VALUE self )
{
sf::Sound *object = NULL;
@ -168,6 +229,11 @@ static VALUE Sound_GetLoop( VALUE self )
}
}
/* call-seq:
* sound.getPlayingOffset() -> float
*
* Get the current playing position of the sound.
*/
static VALUE Sound_GetPlayingOffset( VALUE self )
{
sf::Sound *object = NULL;
@ -175,6 +241,11 @@ static VALUE Sound_GetPlayingOffset( VALUE self )
return rb_float_new( object->GetPlayingOffset() );
}
/* call-seq:
* sound.getStatus() -> fixnum
*
* Get the current status of the sound (stopped, paused, playing).
*/
static VALUE Sound_GetStatus( VALUE self )
{
sf::Sound *object = NULL;
@ -182,6 +253,14 @@ static VALUE Sound_GetStatus( VALUE self )
return INT2FIX( static_cast< int >( object->GetStatus() ) );
}
/* call-seq:
* sound.resetBuffer()
*
* Reset the internal buffer of the sound.
*
* This function is for internal use only, you don't have to use it. It is called by the SFML::SoundBuffer that this
* sound uses, when it is destroyed in order to prevent the sound from using a dead buffer.
*/
static VALUE Sound_ResetBuffer( VALUE self )
{
sf::Sound *object = NULL;

View File

@ -115,7 +115,7 @@ static VALUE SoundBuffer_SaveToFile( VALUE self, VALUE aFileName )
}
/* call-seq:
* image.getSamples() -> array of samples
* sound_buffer.getSamples() -> array of samples
*
* Get the array of audio samples stored in the buffer.
*
@ -138,6 +138,13 @@ static VALUE SoundBuffer_GetSamples( VALUE self )
return samples;
}
/* call-seq:
* sound_buffer.getSamplesCount() -> fixnum
*
* Get the number of samples stored in the buffer.
*
* The array of samples can be accessed with the getSamples() function.
*/
static VALUE SoundBuffer_GetSamplesCount( VALUE self )
{
sf::SoundBuffer *object = NULL;
@ -145,6 +152,14 @@ static VALUE SoundBuffer_GetSamplesCount( VALUE self )
return INT2FIX( object->GetSamplesCount() );
}
/* call-seq:
* sound_buffer.getSampleRate() -> fixnum
*
* Get the sample rate of the sound.
*
* The sample rate is the number of samples played per second. The higher, the better the quality (for example,
* 44100 samples/s is CD quality).
*/
static VALUE SoundBuffer_GetSampleRate( VALUE self )
{
sf::SoundBuffer *object = NULL;
@ -152,6 +167,11 @@ static VALUE SoundBuffer_GetSampleRate( VALUE self )
return INT2FIX( object->GetSampleRate() );
}
/* call-seq:
* sound_buffer.getChannelsCount() -> float
*
* Get the total duration of the sound.
*/
static VALUE SoundBuffer_GetChannelsCount( VALUE self )
{
sf::SoundBuffer *object = NULL;
@ -159,6 +179,13 @@ static VALUE SoundBuffer_GetChannelsCount( VALUE self )
return INT2FIX( object->GetChannelsCount() );
}
/* call-seq:
* sound_buffer.getDuration() -> fixnum
*
* Get the number of channels used by the sound.
*
* If the sound is mono then the number of channels will be 1, 2 for stereo, etc.
*/
static VALUE SoundBuffer_GetDuration( VALUE self )
{
sf::SoundBuffer *object = NULL;

View File

@ -103,6 +103,14 @@ static void SoundBufferRecorder_Free( rbSoundBufferRecorder * anObject )
delete anObject;
}
/* call-seq:
* sound_buffer_recorder.getBuffer() -> sound_buffer
*
* Get the sound buffer containing the captured audio data.
*
* The sound buffer is valid only after the capture has ended. This function provides a read-only access to the internal
* sound buffer, but it can be copied if you need to make any modification to it.
*/
static VALUE SoundBufferRecorder_GetBuffer( VALUE self )
{
sf::SoundBufferRecorder *object = NULL;
@ -113,6 +121,11 @@ static VALUE SoundBufferRecorder_GetBuffer( VALUE self )
return rbData;
}
/* call-seq:
* SoundBufferRecorder.new() -> sound_buffer_recorder
*
* Creates a sound buffer recorder instance for us.
*/
static VALUE SoundBufferRecorder_New( int argc, VALUE *args, VALUE aKlass )
{
rbSoundBufferRecorder *object = new rbSoundBufferRecorder();

View File

@ -98,6 +98,15 @@ static void SoundRecorder_Free( rbSoundRecorder * anObject )
delete anObject;
}
/* call-seq:
* sound_recorder.start()
*
* Start the capture.
*
* The sampleRate parameter defines the number of audio samples captured per second. The higher, the better the
* quality (for example, 44100 samples/sec is CD quality). This function uses its own thread so that it doesn't block
* the rest of the program while the capture runs. Please note that only one capture can happen at the same time.
*/
static VALUE SoundRecorder_Start( int argc, VALUE *args, VALUE self )
{
sf::SoundRecorder *object = NULL;
@ -116,6 +125,11 @@ static VALUE SoundRecorder_Start( int argc, VALUE *args, VALUE self )
return Qnil;
}
/* call-seq:
* sound_recorder.stop()
*
* Stop the capture.
*/
static VALUE SoundRecorder_Stop( VALUE self )
{
sf::SoundRecorder *object = NULL;
@ -124,6 +138,14 @@ static VALUE SoundRecorder_Stop( VALUE self )
return Qnil;
}
/* call-seq:
* sound_recorder.getSampleRate() -> fixnum
*
* Get the sample rate.
*
* The sample rate defines the number of audio samples captured per second. The higher, the better the quality
*(for example, 44100 samples/sec is CD quality).
*/
static VALUE SoundRecorder_GetSampleRate( VALUE self )
{
sf::SoundRecorder *object = NULL;
@ -131,6 +153,11 @@ static VALUE SoundRecorder_GetSampleRate( VALUE self )
return INT2FIX( object->GetSampleRate() );
}
/* call-seq:
* SoundRecorder.new() -> sound_recorder
*
* Creates a sound recorder instance for us.
*/
static VALUE SoundRecorder_New( int argc, VALUE *args, VALUE aKlass )
{
rbSoundRecorder *object = new rbSoundRecorder();
@ -139,6 +166,14 @@ static VALUE SoundRecorder_New( int argc, VALUE *args, VALUE aKlass )
return rbData;
}
/* call-seq:
* SoundRecorder.isAvailable() -> true or false
*
* Check if the system supports audio capture.
*
* This function should always be called before using the audio capture features. If it returns false, then any attempt
* to use sf::SoundRecorder or one of its derived classes will fail.
*/
static VALUE SoundRecorder_IsAvailable( VALUE aKlass )
{
return ( sf::SoundRecorder::IsAvailable() == true ? Qtrue : Qfalse );

View File

@ -30,6 +30,11 @@ VALUE globalSoundSourceClass;
/* External classes */
extern VALUE globalVector3Class;
/* call-seq:
* sound_source.getAttenuation() -> float
*
* Get the attenuation factor of the sound.
*/
static VALUE SoundSource_GetAttenuation( VALUE self )
{
sf::SoundSource *object = NULL;
@ -37,6 +42,11 @@ static VALUE SoundSource_GetAttenuation( VALUE self )
return rb_float_new( object->GetAttenuation() );
}
/* call-seq:
* sound_source.getMinDistance() -> float
*
* Get the minimum distance of the sound.
*/
static VALUE SoundSource_GetMinDistance( VALUE self )
{
sf::SoundSource *object = NULL;
@ -44,6 +54,11 @@ static VALUE SoundSource_GetMinDistance( VALUE self )
return rb_float_new( object->GetMinDistance() );
}
/* call-seq:
* sound_source.getPitch() -> float
*
* Get the pitch of the sound.
*/
static VALUE SoundSource_GetPitch( VALUE self )
{
sf::SoundSource *object = NULL;
@ -51,6 +66,11 @@ static VALUE SoundSource_GetPitch( VALUE self )
return rb_float_new( object->GetPitch() );
}
/* call-seq:
* sound_source.getPosition() -> vector3
*
* Get the 3D position of the sound in the audio scene.
*/
static VALUE SoundSource_GetPosition( VALUE self )
{
sf::SoundSource *object = NULL;
@ -59,6 +79,11 @@ static VALUE SoundSource_GetPosition( VALUE self )
return rb_funcall( globalVector3Class, rb_intern( "new" ), 3, rb_float_new( pos.x ), rb_float_new( pos.y ), rb_float_new( pos.z ) );
}
/* call-seq:
* sound_source.getVolume() -> float
*
* Get the volume of the sound.
*/
static VALUE SoundSource_GetVolume( VALUE self )
{
sf::SoundSource *object = NULL;
@ -66,6 +91,11 @@ static VALUE SoundSource_GetVolume( VALUE self )
return rb_float_new( object->GetVolume() );
}
/* call-seq:
* sound_source.isRelativeToListener() -> true or false
*
* Tell whether the sound's position is relative to the listener or is absolute.
*/
static VALUE SoundSource_IsRelativeToListener( VALUE self )
{
sf::SoundSource *object = NULL;
@ -73,6 +103,16 @@ static VALUE SoundSource_IsRelativeToListener( VALUE self )
return ( object->IsRelativeToListener() == true ? Qtrue : Qfalse );
}
/* call-seq:
* sound_source.setAttenuation( value )
*
* Set the attenuation factor of the sound.
*
* The attenuation is a multiplicative factor which makes the sound more or less loud according to its distance from
* the listener. An attenuation of 0 will produce a non-attenuated sound, i.e. its volume will always be the same
* whether it is heard from near or from far. On the other hand, an attenuation value such as 100 will make the sound
* fade out very quickly as it gets further from the listener. The default value of the attenuation is 1.
*/
static VALUE SoundSource_SetAttenuation( VALUE self, VALUE aValue )
{
sf::SoundSource *object = NULL;
@ -81,6 +121,15 @@ static VALUE SoundSource_SetAttenuation( VALUE self, VALUE aValue )
return Qnil;
}
/* call-seq:
* sound_source.setMinDistance( value )
*
* Set the minimum distance of the sound.
*
* The "minimum distance" of a sound is the maximum distance at which it is heard at its maximum volume. Further than
* the minimum distance, it will start to fade out according to its attenuation factor. A value of 0 ("inside the head
* of the listener") is an invalid value and is forbidden. The default value of the minimum distance is 1.
*/
static VALUE SoundSource_SetMinDistance( VALUE self, VALUE aValue )
{
sf::SoundSource *object = NULL;
@ -89,6 +138,15 @@ static VALUE SoundSource_SetMinDistance( VALUE self, VALUE aValue )
return Qnil;
}
/* call-seq:
* sound_source.setPitch( value )
*
* Set the pitch of the sound.
*
* The pitch represents the perceived fundamental frequency of a sound; thus you can make a sound more acute or grave
* by changing its pitch. A side effect of changing the pitch is to modify the playing speed of the sound as well. The
* default value for the pitch is 1.
*/
static VALUE SoundSource_SetPitch( VALUE self, VALUE aValue )
{
sf::SoundSource *object = NULL;
@ -97,6 +155,14 @@ static VALUE SoundSource_SetPitch( VALUE self, VALUE aValue )
return Qnil;
}
/* call-seq:
* sound_source.setPosition( x, y, z )
* sound_source.setPosition( vector3 )
*
* Set the 3D position of the sound in the audio scene.
*
* Only sounds with one channel (mono sounds) can be spatialized. The default position of a sound is (0, 0, 0).
*/
static VALUE SoundSource_SetPosition( int argc, VALUE *args, VALUE self )
{
float x, y, z;
@ -128,6 +194,15 @@ static VALUE SoundSource_SetPosition( int argc, VALUE *args, VALUE self )
return Qnil;
}
/* call-seq:
* sound_source.setRelativeToListener( value )
*
* Make the sound's position relative to the listener or absolute.
*
* Making a sound relative to the listener will ensure that it will always be played the same way regardless the
* position of the listener. This can be useful for non-spatialized sounds, sounds that are produced by the listener,
* or sounds attached to it. The default value is false (position is absolute).
*/
static VALUE SoundSource_SetRelativeToListener( VALUE self, VALUE aValue )
{
sf::SoundSource *object = NULL;
@ -147,6 +222,13 @@ static VALUE SoundSource_SetRelativeToListener( VALUE self, VALUE aValue )
return Qnil;
}
/* call-seq:
* sound_source.setVolume( value )
*
* Set the volume of the sound.
*
* The volume is a value between 0 (mute) and 100 (full volume). The default value for the volume is 100.
*/
static VALUE SoundSource_SetVolume( VALUE self, VALUE aValue )
{
sf::SoundSource *object = NULL;

View File

@ -106,6 +106,14 @@ static VALUE SoundStream_Free( rbSoundStream *anObject )
delete anObject;
}
/* call-seq:
* sound_stream.play()
*
* Start or resume playing the audio stream.
*
* This function starts the stream if it was stopped, resumes it if it was paused, and does nothing it is it already
* playing. This function uses its own thread so that it doesn't block the rest of the program while the stream is played.
*/
static VALUE SoundStream_Play( VALUE self )
{
sf::SoundStream *object = NULL;
@ -114,6 +122,14 @@ static VALUE SoundStream_Play( VALUE self )
return Qnil;
}
/* call-seq:
* sound_stream.pause()
*
* Start or resume playing the audio stream.
*
* This function starts the stream if it was stopped, resumes it if it was paused, and does nothing it is it already
* playing. This function uses its own thread so that it doesn't block the rest of the program while the stream is played.
*/
static VALUE SoundStream_Pause( VALUE self )
{
sf::SoundStream *object = NULL;
@ -122,6 +138,14 @@ static VALUE SoundStream_Pause( VALUE self )
return Qnil;
}
/* call-seq:
* sound_stream.stop()
*
* Stop playing the audio stream.
*
* This function stops the stream if it was playing or paused, and does nothing if it was already stopped. It also
* resets the playing position (unlike pause()).
*/
static VALUE SoundStream_Stop( VALUE self )
{
sf::SoundStream *object = NULL;
@ -130,6 +154,13 @@ static VALUE SoundStream_Stop( VALUE self )
return Qnil;
}
/* call-seq:
* sound_stream.getChannelsCount() -> fixnum
*
* Return the number of channels of the stream.
*
* 1 channel means a mono sound, 2 means stereo, etc.
*/
static VALUE SoundStream_GetChannelsCount( VALUE self )
{
sf::SoundStream *object = NULL;
@ -137,6 +168,13 @@ static VALUE SoundStream_GetChannelsCount( VALUE self )
return INT2FIX( object->GetChannelsCount() );
}
/* call-seq:
* sound_stream.getSampleRate() -> fixnum
*
* Get the stream sample rate of the stream.
*
* The sample rate is the number of audio samples played per second. The higher, the better the quality.
*/
static VALUE SoundStream_GetSampleRate( VALUE self )
{
sf::SoundStream *object = NULL;
@ -144,6 +182,11 @@ static VALUE SoundStream_GetSampleRate( VALUE self )
return INT2FIX( object->GetSampleRate() );
}
/* call-seq:
* sound_stream.getStatus() -> fixnum
*
* Get the current status of the stream (stopped, paused, playing).
*/
static VALUE SoundStream_GetStatus( VALUE self )
{
sf::SoundStream *object = NULL;
@ -151,6 +194,13 @@ static VALUE SoundStream_GetStatus( VALUE self )
return INT2FIX( static_cast< int >( object->GetStatus() ) );
}
/* call-seq:
* sound_stream.setPlayingOffset( offset )
*
* Change the current playing position of the stream.
*
* The playing position can be changed when the stream is either paused or playing.
*/
static VALUE SoundStream_SetPlayingOffset( VALUE self, VALUE anOffset )
{
sf::SoundStream *object = NULL;
@ -159,6 +209,11 @@ static VALUE SoundStream_SetPlayingOffset( VALUE self, VALUE anOffset )
return Qnil;
}
/* call-seq:
* sound_stream.getPlayingOffset() -> float
*
* Get the current playing position of the stream.
*/
static VALUE SoundStream_GetPlayingOffset( VALUE self, VALUE anOffset )
{
sf::SoundStream *object = NULL;
@ -166,6 +221,14 @@ static VALUE SoundStream_GetPlayingOffset( VALUE self, VALUE anOffset )
return rb_float_new( object->GetPlayingOffset() );
}
/* call-seq:
* sound_stream.setLoop( loop )
*
* Set whether or not the stream should loop after reaching the end.
*
* If set, the stream will restart from beginning after reaching the end and so on, until it is stopped or
* SetLoop(false) is called. The default looping state for streams is false.
*/
static VALUE SoundStream_SetLoop( VALUE self, VALUE aLoop )
{
sf::SoundStream *object = NULL;
@ -185,6 +248,11 @@ static VALUE SoundStream_SetLoop( VALUE self, VALUE aLoop )
return Qnil;
}
/* call-seq:
* sound_stream.getLoop() -> true or false
*
* Tell whether or not the stream is in loop mode.
*/
static VALUE SoundStream_GetLoop( VALUE self )
{
sf::SoundStream *object = NULL;
@ -199,6 +267,17 @@ static VALUE SoundStream_GetLoop( VALUE self )
}
}
/* call-seq:
* sound_stream.initialize()
*
* This is a direct binding to the sf::SoundStream::Initialize function.
*
* Define the audio stream parameters.
*
* This function must be called by derived classes as soon as they know the audio settings of the stream to play. Any
* attempt to manipulate the stream (play(), ...) before calling this function will fail. It can be called multiple
* times if the settings of the audio stream change, but only when the stream is stopped.
*/
static VALUE SoundStream_Initialize( VALUE self, VALUE channelsCount, VALUE sampleRate )
{
rbSoundStream *object = NULL;