From 37ee43fd5ad538caee1517c873c596b1bfd8d94f Mon Sep 17 00:00:00 2001 From: Ovnuniarchos Date: Thu, 21 Jan 2016 01:16:48 +0100 Subject: Documented AudioServserSW, EventPlayer and EventStream*. Corrections on AudioServer and Sample. --- doc/base/classes.xml | 112 +++++++++++++++++++++++++++++++++++++------ scene/audio/event_player.cpp | 6 +-- 2 files changed, 101 insertions(+), 17 deletions(-) diff --git a/doc/base/classes.xml b/doc/base/classes.xml index 4c8e57eca7..d6808f0f34 100644 --- a/doc/base/classes.xml +++ b/doc/base/classes.xml @@ -4120,7 +4120,8 @@ - Create an audio sample, return a [RID] referencing it. The sample will be created with a given format (from the SAMPLE_FORMAT_* enum), a total length (in frames, not samples or bytes), in either stereo or mono. + Create an audio sample, return a [RID] referencing it. The sample will be created with a given format (from the SAMPLE_FORMAT_* enum), a total length (in samples, not bytes), in either stereo or mono. + Even if a stereo sample consists of a left sample and a right sample, it still counts as one sample for length purposes. @@ -4156,7 +4157,7 @@ - Return wether the sample is stereo (2 channels) + Return whether the sample is stereo (2 channels). @@ -4165,7 +4166,7 @@ - Return the length in frames of the audio sample (not samples or bytes). + Return the length in samples (not bytes) of the audio sample. Even if a stereo sample consists of a left sample and a right sample, it still counts as one sample for length purposes. @@ -4175,6 +4176,7 @@ Set the sample data for a given sample as an array of floats. The length must be equal to the sample lenght or an error will be produced. + For this method, a stereo sample is made from two samples. Thus, in case of a stereo sample, the array length must be twice the length returned by [method sample_get_length]. @@ -4183,7 +4185,11 @@ - Set the sample data for a given sample as an array of bytes. The length must be equal to the sample lenght expected in bytes or an error will be produced. + Set the sample data for a given sample as an array of bytes. The length must be equal to the sample lenght expected in bytes or an error will be produced. The byte length can be calculated as follows: + Get the sample length ([method get_sample_length]). + If the sample format is SAMPLE_FORMAT_PCM16, multiply it by 2. + If the sample format is SAMPLE_FORMAT_IMA_ADPCM, divide it by 2 (rounding any fraction up), then add 4. + If the sample is stereo ([method sample_is_stereo]), multiply it by 2. @@ -4498,24 +4504,28 @@ + Set global scale for all voices (not including streams). Default is 1.0. + Return the global scale for all voices. + Set global scale for event-based stream ([EventStream]) playback. Default is 1.0. + Return the global scale for event-based stream playback. @@ -4524,7 +4534,7 @@ Sample format is 8 bits, signed. - Sample format is 16 bits, signed. + Sample format is 16 bits, little-endian, signed. Sample format is IMA-ADPCM compressed. @@ -4572,8 +4582,11 @@ + Software implementation of [AudioServer]. + This is a software audio server. It does not use any kind of hardware acceleration. + This class does not expose any new method. @@ -10230,172 +10243,204 @@ This approximation makes straight segments between each point, then subdivides t + Class for event stream playback. + Class for event stream playback. Event streams are music expressed as a series of events (note on, note off, instrument change...), as opposed to audio streams, which are just audio data. Examples of event-based streams are MIDI files, or MOD music. + Currently, only MOD, S3M, IT, and XM music is supported. + Set the [EventStream] this player will play. + Return the currently assigned stream. + Play the currently assigned stream. + Stop playing. + Return whether this player is playing. + Pause stream playback. + Return whether the playback is currently paused. + Set whether the stream will be restarted at the end. + Return whether this player will be restart the playback at the end. + Set the playback volume for this player. This is a float between 0.0 (silent) and 1.0 (full volume). Values over 1.0 may amplify sound even more, but may introduce distortion. Negative values may just invert the output waveform, which produces no audible difference. + The effect of these special values uiltimately depends on the low-level implementation of the file format being played. + Return the playback volume for this player. + Set the pitch multiplier for all sounds coming from this stream. A value of 2.0 shifts all pitches one octave up, and a value of 0.5 shifts pitches one octave down. + Return the pitch scale factor for this player. + Set the tempo multiplier. This allows to slow down or speed up the music, without affecting its pitch. + Return the tempo multiplier. + Set the playback volume for this player, in decibels. This is a float between -80.0 (silent) and 0.0 (full volume). Values under -79.0 get truncated to -80, but values over 0.0 do not, so the warnings for overamplifying (see [set_volume]) still apply. + Return the playback volume for this player, in decibels. + Return the name of the currently assigned stream. This is not the file name, but a field inside the file. If no stream is assigned, if returns "<No Stream>". + Return the number of times the playback has looped. + Return the playback position. May be in seconds, but depends on the stream type. + Set the playback position. May be in seconds, but depends on the stream type. + Return the song length. May be in seconds, but depends on the stream type. + Set whether this player will start playing as soon as it enters the scene tree. + Return whether this player will start playing as soon as it enters the scene tree. - + + Set the volume scale for an individual channel of the stream, with the same value range as [methid set_volume]. The channel number depends on the stream format. For example, MIDIs range from 0 to 15, and MODs from 0 to 63. + Many stream formats are multichannel, so this allows to affect only a part of the music. - + + Return the volume scale for an individual channel of the stream. - + + Return the time at which the last note of a given channel in the stream plays. @@ -10404,8 +10449,11 @@ This approximation makes straight segments between each point, then subdivides t + Base class for all event-based stream drivers. + Base class for all event-based stream drivers. Event streams are music expressed as a series of events (note on, note off, instrument change...), as opposed to audio streams, which are just audio data. Examples of event-based streams are MIDI files, of MOD music. + This class exposes no methods. @@ -10414,8 +10462,15 @@ This approximation makes straight segments between each point, then subdivides t + Driver for MOD playback. + This driver plays MOD music. MOD music, as all event-based streams, is a music format defined by note events ocurring at defined moments, instead of a stream of audio samples. + Currently, this driver supports the MOD, S3M, IT, and XM formats. + This class exposes no methods. + This class can return its playback positon in seconds, but does not allow to set it, failing with only a console warning. + This class can not return its song length, returning 1.0 when queried. + This class does not limit its volume settings, allowing for overflow/distortion and wave inversion. @@ -28888,8 +28943,8 @@ This method controls whether the position between two cached points is interpola - Create new data for the sample, with format (see FORMAT_* constants), stereo hint, and length in frames (not samples or bytes!). - Calling this method overrides previously existing data. Stereo samples are interleaved pairs of left and right points (in that order). + Create new data for the sample, with format (see FORMAT_* constants), stereo hint, and length in samples (not bytes). + Calling this method overrides previously existing data. Stereo samples are interleaved pairs of left and right points (in that order), but count as one sample for length purposes. @@ -28910,15 +28965,18 @@ This method controls whether the position between two cached points is interpola - Return the sample length in frames. + Return the sample length in samples. Stereo samples count as one, even if they are made of a left and a right sample. - Set sample data. Data must be little endian, no matter the host platform, and exactly as long as to fit all frames. - For example, if data is stereo, 16 bits, 256 frames, it will be 1024 bytes long. + Set sample data. Data must be little endian, no matter the host platform, and exactly as long as to fit all samples. The length of this array can be calculated as follows: + Get the sample length ([method get_length]). + If the sample format is FORMAT_PCM16, multiply it by 2. + If the sample format is FORMAT_IMA_ADPCM, divide it by 2 (rounding any fraction up), then add 4. + If the sample is stereo ([method is_stereo]), multiply it by 2. @@ -28987,7 +29045,7 @@ This method controls whether the position between two cached points is interpola - 8-bits signed little endian PCM audio. + 8-bits signed PCM audio. 16-bits signed little endian PCM audio. @@ -33311,148 +33369,174 @@ This method controls whether the position between two cached points is interpola + Set the [EventStream] this player will play. + Return the currently assigned stream. + Play the currently assigned stream, starting from a given position (in seconds). + Stop the playback. + Return whether this player is playing. + Pause stream playback. + Return whether the playback is currently paused. + Set whether the stream will be restarted at the end. + Return whether the stream will be restarted at the end. + Set the playback volume for this player. This is a float between 0.0 (silent) and 1.0 (full volume). Values over 1.0 will amplify sound even more, but may introduce distortion. Negative values will just invert the output waveform, which produces no audible difference. + Return the playback volume for this player. + Set the playback volume for this player, in decibels. This is a float between -80.0 (silent) and 0.0 (full volume). Values under -79.0 get truncated to -80, but values over 0.0 do not, so the warnings for overamplifying (see [set_volume]) still apply. + Return the playback volume for this player, in decibels. + Set the size (in milliseconds) of the audio buffer. A long audio buffer protects better against slowdowns, but responds worse to changes (in volume, stream played...). A shorter buffer takes less time to respond to changes, but may stutter if the application suffers some slowdown. + Default is 500 milliseconds. + Return the size of the audio buffer. + Set the point in time the stream will rewind to, when looping. + Return the point in time the stream will rewind to, when looping. + Return the name of the currently assigned stream. This is not the file name, but a field inside the file. If no stream is assigned, if returns "<No Stream>". + Return the number of times the playback has looped. + Return the playback position, in seconds. + Set the playback position, in seconds. + Set whether this player will start playing as soon as it enters the scene tree. + Return whether this player will start playing as soon as it enters the scene tree. + Return the length of the stream, in seconds. + This signal triggers when the player stops playing. It will not trigger on each loop. diff --git a/scene/audio/event_player.cpp b/scene/audio/event_player.cpp index b49b285f76..eabe84a8ee 100644 --- a/scene/audio/event_player.cpp +++ b/scene/audio/event_player.cpp @@ -317,9 +317,9 @@ void EventPlayer::_bind_methods() { ObjectTypeDB::bind_method(_MD("set_autoplay","enabled"),&EventPlayer::set_autoplay); ObjectTypeDB::bind_method(_MD("has_autoplay"),&EventPlayer::has_autoplay); - ObjectTypeDB::bind_method(_MD("set_channel_volume","idx","channel_volume"),&EventPlayer::set_channel_volume); - ObjectTypeDB::bind_method(_MD("get_channel_volume","idx"),&EventPlayer::get_channel_volume); - ObjectTypeDB::bind_method(_MD("get_channel_last_note_time","idx"),&EventPlayer::get_channel_last_note_time); + ObjectTypeDB::bind_method(_MD("set_channel_volume","channel","channel_volume"),&EventPlayer::set_channel_volume); + ObjectTypeDB::bind_method(_MD("get_channel_volume","channel"),&EventPlayer::get_channel_volume); + ObjectTypeDB::bind_method(_MD("get_channel_last_note_time","channel"),&EventPlayer::get_channel_last_note_time); ObjectTypeDB::bind_method(_MD("_set_play","play"),&EventPlayer::_set_play); ObjectTypeDB::bind_method(_MD("_get_play"),&EventPlayer::_get_play); -- cgit v1.2.3