From ccc4f49c22d00e10a63ac679030cddc4ac8f8a7e Mon Sep 17 00:00:00 2001 From: Micky Date: Sun, 7 Jan 2024 17:28:48 +0100 Subject: [PATCH] Add missing documentation for AudioStream & AudioStreamPlayback (cherry picked from commit 8f4598bad4d9e87e6647d8c6f4ad529934508a79) --- doc/classes/AudioServer.xml | 2 ++ doc/classes/AudioStream.xml | 12 ++++++++++-- doc/classes/AudioStreamPlayback.xml | 9 +++++++++ 3 files changed, 21 insertions(+), 2 deletions(-) diff --git a/doc/classes/AudioServer.xml b/doc/classes/AudioServer.xml index d13511ee1cf..3a6eb293204 100644 --- a/doc/classes/AudioServer.xml +++ b/doc/classes/AudioServer.xml @@ -280,6 +280,8 @@ + If set to [code]true[/code], all instances of [AudioStreamPlayback] will call [method AudioStreamPlayback._tag_used_streams] every mix step. + [b]Note:[/b] This is enabled by default in the editor, as it is used by editor plugins for the audio stream previews. diff --git a/doc/classes/AudioStream.xml b/doc/classes/AudioStream.xml index b2d60320633..51eed1e8612 100644 --- a/doc/classes/AudioStream.xml +++ b/doc/classes/AudioStream.xml @@ -16,31 +16,39 @@ + Overridable method. Should return the total number of beats of this audio stream. Used by the engine to determine the position of every beat. + Ideally, the returned value should be based off the stream's sample rate ([member AudioStreamWAV.mix_rate], for example). + Overridable method. Should return the tempo of this audio stream, in beats per minute (BPM). Used by the engine to determine the position of every beat. + Ideally, the returned value should be based off the stream's sample rate ([member AudioStreamWAV.mix_rate], for example). + Override this method to customize the returned value of [method get_length]. Should return the length of this audio stream, in seconds. + Override this method to customize the name assigned to this audio stream. Unused by the engine. + Override this method to customize the returned value of [method instantiate_playback]. Should returned a new [AudioStreamPlayback] created when the stream is played (such as by an [AudioStreamPlayer]).. + Override this method to customize the returned value of [method is_monophonic]. Should return [code]true[/code] if this audio stream only supports one channel. @@ -52,13 +60,13 @@ - Returns an AudioStreamPlayback. Useful for when you want to extend [method _instantiate_playback] but call [method instantiate_playback] from an internally held AudioStream subresource. An example of this can be found in the source files for [code]AudioStreamRandomPitch::instantiate_playback[/code]. + Returns a newly created [AudioStreamPlayback] intended to play this audio stream. Useful for when you want to extend [method _instantiate_playback] but call [method instantiate_playback] from an internally held AudioStream subresource. An example of this can be found in the source code for [code]AudioStreamRandomPitch::instantiate_playback[/code]. - Returns true if this audio stream only supports monophonic playback, or false if the audio stream supports polyphony. + Returns [code]true[/code] if this audio stream only supports one channel ([i]monophony[/i]), or [code]false[/code] if the audio stream supports two or more channels ([i]polyphony[/i]). diff --git a/doc/classes/AudioStreamPlayback.xml b/doc/classes/AudioStreamPlayback.xml index fced312c5b6..806ce272d87 100644 --- a/doc/classes/AudioStreamPlayback.xml +++ b/doc/classes/AudioStreamPlayback.xml @@ -13,16 +13,19 @@ + Overridable method. Should return how many times this audio stream has looped. Most built-in playbacks always return [code]0[/code]. + Overridable method. Should return the current progress along the audio stream, in seconds. + Overridable method. Should return [code]true[/code] if this playback is active and playing its audio stream. @@ -31,28 +34,34 @@ + Override this method to customize how the audio stream is mixed. This method is called even if the playback is not active. + [b]Note:[/b] It is not useful to override this method in GDScript or C#. Only GDExtension can take advantage of it. + Override this method to customize what happens when seeking this audio stream at the given [param position], such as by calling [method AudioStreamPlayer.seek]. + Override this method to customize what happens when the playback starts at the given position, such as by calling [method AudioStreamPlayer.play]. + Override this method to customize what happens when the playback is stopped, such as by calling [method AudioStreamPlayer.stop]. + Overridable method. Called whenever the audio stream is mixed if the playback is active and [method AudioServer.set_enable_tagging_used_audio_streams] has been set to [code]true[/code]. Editor plugins may use this method to "tag" the current position along the audio stream and display it in a preview.