Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fill the documentation of a few overlooked classes #86927

Merged
merged 1 commit into from
Jan 29, 2024
Merged

Fill the documentation of a few overlooked classes #86927

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 17 additions & 2 deletions doc/classes/AudioEffect.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,18 +1,33 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AudioEffect" inherits="Resource" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Audio effect for audio.
Base class for audio effect resources.
</brief_description>
<description>
Base resource for audio bus. Applies an audio effect on the bus that the resource is applied on.
The base [Resource] for every audio effect. In the editor, an audio effect can be added to the current bus layout through the Audio panel. At run-time, it is also possible to manipulate audio effects through [method AudioServer.add_bus_effect], [method AudioServer.remove_bus_effect], and [method AudioServer.get_bus_effect].
When applied on a bus, an audio effect creates a corresponding [AudioEffectInstance]. The instance is directly responsible for manipulating the sound, based on the original audio effect's properties.
</description>
<tutorials>
<link title="Audio buses">$DOCS_URL/tutorials/audio/audio_buses.html</link>
<link title="Audio Mic Record Demo">https://godotengine.org/asset-library/asset/527</link>
</tutorials>
<methods>
<method name="_instantiate" qualifiers="virtual">
<return type="AudioEffectInstance" />
<description>
Override this method to customize the [AudioEffectInstance] created when this effect is applied on a bus in the editor's Audio panel, or through [method AudioServer.add_bus_effect].
[codeblock]
extends AudioEffect

@export var strength = 4.0

func _instantiate():
var effect = CustomAudioEffectInstance.new()
effect.base = self

return effect
[/codeblock]
[b]Note:[/b] It is recommended to keep a reference to the original [AudioEffect] in the new instance. Depending on the implementation this allows the effect instance to listen for changes at run-time and be modified accordingly.
</description>
</method>
</methods>
Expand Down
7 changes: 7 additions & 0 deletions doc/classes/AudioEffectInstance.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,13 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AudioEffectInstance" inherits="RefCounted" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Manipulates the audio it receives for a given effect.
</brief_description>
<description>
An audio effect instance manipulates the audio it receives for a given effect. This instance is automatically created by an [AudioEffect] when it is added to a bus, and should usually not be created directly. If necessary, it can be fetched at run-time with [method AudioServer.get_bus_effect_instance].
</description>
<tutorials>
<link title="Audio buses">$DOCS_URL/tutorials/audio/audio_buses.html</link>
</tutorials>
<methods>
<method name="_process" qualifiers="virtual">
Expand All @@ -13,11 +16,15 @@
<param index="1" name="dst_buffer" type="AudioFrame*" />
<param index="2" name="frame_count" type="int" />
<description>
Called by the [AudioServer] to process this effect. When [method _process_silence] is not overridden or it returns [code]false[/code], this method is called only when the bus is active.
[b]Note:[/b] It is not useful to override this method in GDScript or C#. Only GDExtension can take advantage of it.
Comment on lines 18 to +20
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Now, the one thing that could be verified is this about GDExtension. I've already asked on RocketChat but I've been left hanging so far. And it better be true, otherwise this method is actually pointless and not working as intended.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

https://chat.godotengine.org/channel/audio?msg=KAsTbQsmDTyoGrh8n

All right, looked it up, extensions can use this. There are GDVIRTUAL calls in there, and arguments come up as pointers in GodotCpp. The fact it appears also in the script API is an odd byproduct of that tho

</description>
</method>
<method name="_process_silence" qualifiers="virtual const">
<return type="bool" />
<description>
Override this method to customize the processing behavior of this effect instance.
Should return [code]true[/code] to force the [AudioServer] to always call [method _process], even if the bus has been muted or cannot otherwise be heard.
</description>
</method>
</methods>
Expand Down
6 changes: 4 additions & 2 deletions doc/classes/MissingNode.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,15 +4,17 @@
An internal editor class intended for keeping the data of unrecognized nodes.
</brief_description>
<description>
This is an internal editor class intended for keeping data of nodes of unknown type (most likely this type was supplied by an extension that is no longer loaded). It can't be manually instantiated or placed in the scene. Ignore it if you don't know what it is.
This is an internal editor class intended for keeping data of nodes of unknown type (most likely this type was supplied by an extension that is no longer loaded). It can't be manually instantiated or placed in a scene.
[b]Warning:[/b] Ignore missing nodes unless you know what you are doing. Existing properties on a missing node can be freely modified in code, regardless of the type they are intended to be.
</description>
<tutorials>
</tutorials>
<members>
<member name="original_class" type="String" setter="set_original_class" getter="get_original_class">
Returns the name of the type this node was originally.
The name of the class this node was supposed to be (see [method Object.get_class]).
</member>
<member name="recording_properties" type="bool" setter="set_recording_properties" getter="is_recording_properties">
If set to [code]true[/code], allows new properties to be added on top of the existing ones with [method Object.set].
</member>
</members>
</class>
6 changes: 4 additions & 2 deletions doc/classes/MissingResource.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,15 +4,17 @@
An internal editor class intended for keeping the data of unrecognized resources.
</brief_description>
<description>
This is an internal editor class intended for keeping data of resources of unknown type (most likely this type was supplied by an extension that is no longer loaded). It can't be manually instantiated or placed in the scene. Ignore it if you don't know what it is.
This is an internal editor class intended for keeping data of resources of unknown type (most likely this type was supplied by an extension that is no longer loaded). It can't be manually instantiated or placed in a scene.
[b]Warning:[/b] Ignore missing resources unless you know what you are doing. Existing properties on a missing resource can be freely modified in code, regardless of the type they are intended to be.
</description>
<tutorials>
</tutorials>
<members>
<member name="original_class" type="String" setter="set_original_class" getter="get_original_class">
Returns the name of the class this resource was originally.
The name of the class this resource was supposed to be (see [method Object.get_class]).
</member>
<member name="recording_properties" type="bool" setter="set_recording_properties" getter="is_recording_properties">
If set to [code]true[/code], allows new properties to be added on top of the existing ones with [method Object.set].
</member>
</members>
</class>
Loading