Skip to content

Commit

Permalink
Merge pull request #80214 from BastiaanOlij/rendering_effect
Browse files Browse the repository at this point in the history 
Implement hooks into renderer
  • Loading branch information
@akien-mga
akien-mga committed Feb 20, 2024
2 parents dc2d1e3 + 5a98845 commit 292f4c7
Show file tree
Hide file tree
Showing 64 changed files with 2,432 additions and 132 deletions.
3 changes: 3 additions & 0 deletions doc/classes/Camera3D.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -159,6 +159,9 @@
<member name="attributes" type="CameraAttributes" setter="set_attributes" getter="get_attributes">
The [CameraAttributes] to use for this camera.
</member>
<member name="compositor" type="Compositor" setter="set_compositor" getter="get_compositor">
The [Compositor] to use for this camera.
</member>
<member name="cull_mask" type="int" setter="set_cull_mask" getter="get_cull_mask" default="1048575">
The culling mask that describes which [member VisualInstance3D.layers] are rendered by this camera. By default, all 20 user-visible layers are rendered.
[b]Note:[/b] Since the [member cull_mask] allows for 32 layers to be stored in total, there are an additional 12 layers that are only used internally by the engine and aren't exposed in the editor. Setting [member cull_mask] using a script allows you to toggle those reserved layers, which can be useful for editor plugins.
Expand Down
17 changes: 17 additions & 0 deletions doc/classes/Compositor.xml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="Compositor" inherits="Resource" experimental="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
The compositor resource holds the configuration with which rendering of a viewport can be customised.
</brief_description>
<description>
The compositor resource holds the configuration with which rendering of a viewport can be customised.
[b]Note:[/b] This functionality is still experimental as more customisation of the rendering pipeline will be added in the near future.
</description>
<tutorials>
</tutorials>
<members>
<member name="compositor_effects" type="CompositorEffect[]" setter="set_compositor_effects" getter="get_compositor_effects" default="[]">
The custom [CompositorEffect]s that are applied during rendering of viewports using this compositor.
</member>
</members>
</class>
85 changes: 85 additions & 0 deletions doc/classes/CompositorEffect.xml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,85 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="CompositorEffect" inherits="Resource" experimental="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
This resource allows for creating a custom rendering effect.
</brief_description>
<description>
This resource defines a custom rendering effect that can be applied to [Viewport]s through the viewports' [Environment]. You can implement a callback that is called during rendering at a given stage of the rendering pipeline and allows you to insert additional passes. Note that this callback happens on the rendering thread.
[b]Note:[/b] This functionality is still experimental, there will be changes to the implementation as we expose more of the rendering internals.
</description>
<tutorials>
</tutorials>
<methods>
<method name="_render_callback" qualifiers="virtual">
<return type="void" />
<param index="0" name="effect_callback_type" type="int" />
<param index="1" name="render_data" type="RenderData" />
<description>
Implement this function with your custom rendering code. [param effect_callback_type] should always match the effect callback type you've specified in [member effect_callback_type]. [param render_data] provides access to the rendering state, it is only valid during rendering and should not be stored.
</description>
</method>
</methods>
<members>
<member name="access_resolved_color" type="bool" setter="set_access_resolved_color" getter="get_access_resolved_color">
If [code]true[/code] and MSAA is enabled, this will trigger a color buffer resolve before the effect is run.
[b]Note:[/b] In [method _render_callback], to access the resolved buffer use:
[codeblock]
var render_scene_buffers : RenderSceneBuffersRD = render_data.get_render_scene_buffers()
var color_buffer = render_scene_buffers.get_texture("render_buffers", "color")
[/codeblock]
</member>
<member name="access_resolved_depth" type="bool" setter="set_access_resolved_depth" getter="get_access_resolved_depth">
If [code]true[/code] and MSAA is enabled, this will trigger a depth buffer resolve before the effect is run.
[b]Note:[/b] In [method _render_callback], to access the resolved buffer use:
[codeblock]
var render_scene_buffers : RenderSceneBuffersRD = render_data.get_render_scene_buffers()
var depth_buffer = render_scene_buffers.get_texture("render_buffers", "depth")
[/codeblock]
</member>
<member name="effect_callback_type" type="int" setter="set_effect_callback_type" getter="get_effect_callback_type" enum="CompositorEffect.EffectCallbackType">
The type of effect that is implemented, determines at what stage of rendering the callback is called.
</member>
<member name="enabled" type="bool" setter="set_enabled" getter="get_enabled">
If [code]true[/code] this rendering effect is applied to any viewport it is added to.
</member>
<member name="needs_motion_vectors" type="bool" setter="set_needs_motion_vectors" getter="get_needs_motion_vectors">
If [code]true[/code] this triggers motion vectors being calculated during the opaque render state.
[b]Note:[/b] In [method _render_callback], to access the motion vector buffer use:
[codeblock]
var render_scene_buffers : RenderSceneBuffersRD = render_data.get_render_scene_buffers()
var motion_buffer = render_scene_buffers.get_velocity_texture()
[/codeblock]
</member>
<member name="needs_normal_roughness" type="bool" setter="set_needs_normal_roughness" getter="get_needs_normal_roughness">
If [code]true[/code] this triggers normal and roughness data to be output during our depth pre-pass, only applicable for the Forward+ renderer.
[b]Note:[/b] In [method _render_callback], to access the roughness buffer use:
[codeblock]
var render_scene_buffers : RenderSceneBuffersRD = render_data.get_render_scene_buffers()
var roughness_buffer = render_scene_buffers.get_texture("forward_clustered", "normal_roughness")
[/codeblock]
</member>
<member name="needs_separate_specular" type="bool" setter="set_needs_separate_specular" getter="get_needs_separate_specular">
If [code]true[/code] this triggers specular data being rendered to a separate buffer and combined after effects have been applied, only applicable for the Forward+ renderer.
</member>
</members>
<constants>
<constant name="EFFECT_CALLBACK_TYPE_PRE_OPAQUE" value="0" enum="EffectCallbackType">
The callback is called before our opaque rendering pass, but after depth prepass (if applicable).
</constant>
<constant name="EFFECT_CALLBACK_TYPE_POST_OPAQUE" value="1" enum="EffectCallbackType">
The callback is called after our opaque rendering pass, but before our sky is rendered.
</constant>
<constant name="EFFECT_CALLBACK_TYPE_POST_SKY" value="2" enum="EffectCallbackType">
The callback is called after our sky is rendered, but before our back buffers are created (and if enabled, before subsurface scattering and/or screen space reflections).
</constant>
<constant name="EFFECT_CALLBACK_TYPE_PRE_TRANSPARENT" value="3" enum="EffectCallbackType">
The callback is called before our transparent rendering pass, but after our sky is rendered and we've created our back buffers.
</constant>
<constant name="EFFECT_CALLBACK_TYPE_POST_TRANSPARENT" value="4" enum="EffectCallbackType">
The callback is called after our transparent rendering pass, but before any build in post effects and output to our render target.
</constant>
<constant name="EFFECT_CALLBACK_TYPE_MAX" value="5" enum="EffectCallbackType">
Represents the size of the [enum EffectCallbackType] enum.
</constant>
</constants>
</class>
22 changes: 22 additions & 0 deletions doc/classes/FramebufferCacheRD.xml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="FramebufferCacheRD" inherits="Object" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Framebuffer cache manager for Rendering Device based renderers.
</brief_description>
<description>
Framebuffer cache manager for Rendering Device based renderers. Provides a way to create a framebuffer and reuse it in subsequent calls for as long as the used textures exists. Framebuffers will automatically be cleaned up when dependent objects are freed.
</description>
<tutorials>
</tutorials>
<methods>
<method name="get_cache_multipass" qualifiers="static">
<return type="RID" />
<param index="0" name="textures" type="RID[]" />
<param index="1" name="passes" type="RDFramebufferPass[]" />
<param index="2" name="views" type="int" />
<description>
Creates, or obtains a cached, framebuffer. [param textures] lists textures accessed. [param passes] defines the subpasses and texture allocation, if left empty a single pass is created and textures are allocated depending on their usage flags. [param views] defines the number of views used when rendering.
</description>
</method>
</methods>
</class>
38 changes: 38 additions & 0 deletions doc/classes/RenderData.xml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="RenderData" inherits="Object" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Abstract render data object, holds frame data related to rendering a single frame of a viewport.
</brief_description>
<description>
Abstract render data object, exists for the duration of rendering a single viewport.
[b]Note:[/b] This is an internal rendering server object, do not instantiate this from script.
</description>
<tutorials>
</tutorials>
<methods>
<method name="get_camera_attributes" qualifiers="const">
<return type="RID" />
<description>
Returns the [RID] of the camera attributes object in the [RenderingServer] being used to render this viewport.
</description>
</method>
<method name="get_environment" qualifiers="const">
<return type="RID" />
<description>
Returns the [RID] of the environments object in the [RenderingServer] being used to render this viewport.
</description>
</method>
<method name="get_render_scene_buffers" qualifiers="const">
<return type="RenderSceneBuffers" />
<description>
Returns the [RenderSceneBuffers] object managing the scene buffers for rendering this viewport.
</description>
</method>
<method name="get_render_scene_data" qualifiers="const">
<return type="RenderSceneData" />
<description>
Returns the [RenderSceneData] object managing this frames scene data.
</description>
</method>
</methods>
</class>
36 changes: 36 additions & 0 deletions doc/classes/RenderDataExtension.xml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="RenderDataExtension" inherits="RenderData" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
This class allows for a RenderData implementation to be made in GDExtension.
</brief_description>
<description>
This class allows for a RenderData implementation to be made in GDExtension.
</description>
<tutorials>
</tutorials>
<methods>
<method name="_get_camera_attributes" qualifiers="virtual const">
<return type="RID" />
<description>
Implement this in GDExtension to return the [RID] for the implementations camera attributes object.
</description>
</method>
<method name="_get_environment" qualifiers="virtual const">
<return type="RID" />
<description>
</description>
</method>
<method name="_get_render_scene_buffers" qualifiers="virtual const">
<return type="RenderSceneBuffers" />
<description>
Implement this in GDExtension to return the [RID] of the implementations environment object.
</description>
</method>
<method name="_get_render_scene_data" qualifiers="virtual const">
<return type="RenderSceneData" />
<description>
Implement this in GDExtension to return the implementations [RenderSceneDataExtension] object.
</description>
</method>
</methods>
</class>
13 changes: 13 additions & 0 deletions doc/classes/RenderDataRD.xml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="RenderDataRD" inherits="RenderData" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Render data implementation for the RenderingDevice based renderers.
[b]Note:[/b] This is an internal rendering server object, do not instantiate this from script.
</brief_description>
<description>
This object manages all render data for the rendering device based renderers.
[b]Note:[/b] This is an internal rendering server object only exposed for GDExtension plugins.
</description>
<tutorials>
</tutorials>
</class>
2 changes: 1 addition & 1 deletion doc/classes/RenderSceneBuffers.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
</brief_description>
<description>
Abstract scene buffers object, created for each viewport for which 3D rendering is done. It manages any additional buffers used during rendering and will discard buffers when the viewport is resized.
[b]Note:[/b] this is an internal rendering server object only exposed for GDExtension plugins.
[b]Note:[/b] This is an internal rendering server object, do not instantiate this from script.
</description>
<tutorials>
</tutorials>
Expand Down
21 changes: 19 additions & 2 deletions doc/classes/RenderSceneBuffersRD.xml
View file
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="RenderSceneBuffersRD" inherits="RenderSceneBuffers" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Abstract render scene buffer implementation for the RenderingDevice based renderers.
Render scene buffer implementation for the RenderingDevice based renderers.
</brief_description>
<description>
This object manages all 3D rendering buffers for the rendering device based renderers. An instance of this object is created for every viewport that has 3D rendering enabled.
All buffers are organized in [b]contexts[/b]. The default context is called [b]render_buffers[/b] and can contain amongst others the color buffer, depth buffer, velocity buffers, VRS density map and MSAA variants of these buffers.
Buffers are only guaranteed to exist during rendering of the viewport.
[b]Note:[/b] this is an internal rendering server object only exposed for GDExtension plugins.
[b]Note:[/b] This is an internal rendering server object, do not instantiate this from script.
</description>
<tutorials>
</tutorials>
Expand Down Expand Up @@ -58,27 +58,35 @@
<method name="get_color_layer">
<return type="RID" />
<param index="0" name="layer" type="int" />
<param index="1" name="msaa" type="bool" default="false" />
<description>
Returns the specified layer from the color texture we are rendering 3D content to.
If [param msaa] is [b]true[/b] and MSAA is enabled, this returns the MSAA variant of the buffer.
</description>
</method>
<method name="get_color_texture">
<return type="RID" />
<param index="0" name="msaa" type="bool" default="false" />
<description>
Returns the color texture we are rendering 3D content to. If multiview is used this will be a texture array with all views.
If [param msaa] is [b]true[/b] and MSAA is enabled, this returns the MSAA variant of the buffer.
</description>
</method>
<method name="get_depth_layer">
<return type="RID" />
<param index="0" name="layer" type="int" />
<param index="1" name="msaa" type="bool" default="false" />
<description>
Returns the specified layer from the depth texture we are rendering 3D content to.
If [param msaa] is [b]true[/b] and MSAA is enabled, this returns the MSAA variant of the buffer.
</description>
</method>
<method name="get_depth_texture">
<return type="RID" />
<param index="0" name="msaa" type="bool" default="false" />
<description>
Returns the depth texture we are rendering 3D content to. If multiview is used this will be a texture array with all views.
If [param msaa] is [b]true[/b] and MSAA is enabled, this returns the MSAA variant of the buffer.
</description>
</method>
<method name="get_internal_size" qualifiers="const">
Expand All @@ -87,6 +95,12 @@
Returns the internal size of the render buffer (size before upscaling) with which textures are created by default.
</description>
</method>
<method name="get_msaa_3d" qualifiers="const">
<return type="int" enum="RenderingServer.ViewportMSAA" />
<description>
Returns the applied 3D MSAA mode for this viewport.
</description>
</method>
<method name="get_render_target" qualifiers="const">
<return type="RID" />
<description>
Expand Down Expand Up @@ -152,14 +166,17 @@
<method name="get_velocity_layer">
<return type="RID" />
<param index="0" name="layer" type="int" />
<param index="1" name="msaa" type="bool" default="false" />
<description>
Returns the specified layer from the velocity texture we are rendering 3D content to.
</description>
</method>
<method name="get_velocity_texture">
<return type="RID" />
<param index="0" name="msaa" type="bool" default="false" />
<description>
Returns the velocity texture we are rendering 3D content to. If multiview is used this will be a texture array with all views.
If [param msaa] is [b]true[/b] and MSAA is enabled, this returns the MSAA variant of the buffer.
</description>
</method>
<method name="get_view_count" qualifiers="const">
Expand Down
55 changes: 55 additions & 0 deletions doc/classes/RenderSceneData.xml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="RenderSceneData" inherits="Object" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Abstract render data object, holds scene data related to rendering a single frame of a viewport.
</brief_description>
<description>
Abstract scene data object, exists for the duration of rendering a single viewport.
[b]Note:[/b] This is an internal rendering server object, do not instantiate this from script.
</description>
<tutorials>
</tutorials>
<methods>
<method name="get_cam_projection" qualifiers="const">
<return type="Projection" />
<description>
Returns the camera projection used to render this frame.
[b]Note:[/b] If more than one view is rendered, this will return a combined projection.
</description>
</method>
<method name="get_cam_transform" qualifiers="const">
<return type="Transform3D" />
<description>
Returns the camera transform used to render this frame.
[b]Note:[/b] If more than one view is rendered, this will return a centered transform.
</description>
</method>
<method name="get_uniform_buffer" qualifiers="const">
<return type="RID" />
<description>
Return the [RID] of the uniform buffer containing the scene data as a UBO.
</description>
</method>
<method name="get_view_count" qualifiers="const">
<return type="int" />
<description>
Returns the number of views being rendered.
</description>
</method>
<method name="get_view_eye_offset" qualifiers="const">
<return type="Vector3" />
<param index="0" name="view" type="int" />
<description>
Returns the eye offset per view used to render this frame. This is the offset between our camera transform and the eye transform.
</description>
</method>
<method name="get_view_projection" qualifiers="const">
<return type="Projection" />
<param index="0" name="view" type="int" />
<description>
Returns the view projection per view used to render this frame.
[b]Note:[/b] If a single view is rendered, this returns the camera projection. If more than one view is rendered, this will return a projection for the given view including the eye offset.
</description>
</method>
</methods>
</class>
Loading

0 comments on commit 292f4c7

Please sign in to comment.