diff options
Diffstat (limited to 'doc/classes/RenderingDevice.xml')
| -rw-r--r-- | doc/classes/RenderingDevice.xml | 146 |
1 files changed, 121 insertions, 25 deletions
diff --git a/doc/classes/RenderingDevice.xml b/doc/classes/RenderingDevice.xml index fe23f79119..59ca06085f 100644 --- a/doc/classes/RenderingDevice.xml +++ b/doc/classes/RenderingDevice.xml @@ -210,15 +210,12 @@ <method name="draw_list_begin"> <return type="int" /> <param index="0" name="framebuffer" type="RID" /> - <param index="1" name="initial_color_action" type="int" enum="RenderingDevice.InitialAction" /> - <param index="2" name="final_color_action" type="int" enum="RenderingDevice.FinalAction" /> - <param index="3" name="initial_depth_action" type="int" enum="RenderingDevice.InitialAction" /> - <param index="4" name="final_depth_action" type="int" enum="RenderingDevice.FinalAction" /> - <param index="5" name="clear_color_values" type="PackedColorArray" default="PackedColorArray()" /> - <param index="6" name="clear_depth" type="float" default="1.0" /> - <param index="7" name="clear_stencil" type="int" default="0" /> - <param index="8" name="region" type="Rect2" default="Rect2(0, 0, 0, 0)" /> - <param index="9" name="breadcrumb" type="int" default="0" /> + <param index="1" name="draw_flags" type="int" enum="RenderingDevice.DrawFlags" is_bitfield="true" default="0" /> + <param index="2" name="clear_color_values" type="PackedColorArray" default="PackedColorArray()" /> + <param index="3" name="clear_depth_value" type="float" default="1.0" /> + <param index="4" name="clear_stencil_value" type="int" default="0" /> + <param index="5" name="region" type="Rect2" default="Rect2(0, 0, 0, 0)" /> + <param index="6" name="breadcrumb" type="int" default="0" /> <description> Starts a list of raster drawing commands created with the [code]draw_*[/code] methods. The returned value should be passed to other [code]draw_list_*[/code] functions. Multiple draw lists cannot be created at the same time; you must finish the previous draw list first using [method draw_list_end]. @@ -226,7 +223,7 @@ [codeblock] var rd = RenderingDevice.new() var clear_colors = PackedColorArray([Color(0, 0, 0, 0), Color(0, 0, 0, 0), Color(0, 0, 0, 0)]) - var draw_list = rd.draw_list_begin(framebuffers[i], RenderingDevice.INITIAL_ACTION_CLEAR, RenderingDevice.FINAL_ACTION_READ, RenderingDevice.INITIAL_ACTION_CLEAR, RenderingDevice.FINAL_ACTION_DISCARD, clear_colors, RenderingDevice.OPAQUE_PASS) + var draw_list = rd.draw_list_begin(framebuffers[i], RenderingDevice.CLEAR_COLOR_ALL, clear_colors, true, 1.0f, true, 0, Rect2(), RenderingDevice.OPAQUE_PASS) # Draw opaque. rd.draw_list_bind_render_pipeline(draw_list, raster_pipeline) @@ -241,10 +238,11 @@ rd.draw_list_end() [/codeblock] + The [param draw_flags] indicates if the texture attachments of the framebuffer should be cleared or ignored. Only one of the two flags can be used for each individual attachment. Ignoring an attachment means that any contents that existed before the draw list will be completely discarded, reducing the memory bandwidth used by the render pass but producing garbage results if the pixels aren't replaced. The default behavior allows the engine to figure out the right operation to use if the texture is discardable, which can result in increased performance. See [RDTextureFormat] or [method texture_set_discardable]. The [param breadcrumb] parameter can be an arbitrary 32-bit integer that is useful to diagnose GPU crashes. If Godot is built in dev or debug mode; when the GPU crashes Godot will dump all shaders that were being executed at the time of the crash and the breadcrumb is useful to diagnose what passes did those shaders belong to. It does not affect rendering behavior and can be set to 0. It is recommended to use [enum BreadcrumbMarker] enumerations for consistency but it's not required. It is also possible to use bitwise operations to add extra data. e.g. [codeblock] - rd.draw_list_begin(fb[i], RenderingDevice.INITIAL_ACTION_CLEAR, RenderingDevice.FINAL_ACTION_READ, RenderingDevice.INITIAL_ACTION_CLEAR, RenderingDevice.FINAL_ACTION_DISCARD, clear_colors, RenderingDevice.OPAQUE_PASS | 5) + rd.draw_list_begin(fb[i], RenderingDevice.CLEAR_COLOR_ALL, clear_colors, true, 1.0f, true, 0, Rect2(), RenderingDevice.OPAQUE_PASS | 5) [/codeblock] </description> </method> @@ -947,6 +945,13 @@ [b]Note:[/b] This function returns a [code]uint64_t[/code] which internally maps to a [code]GLuint[/code] (OpenGL) or [code]VkImage[/code] (Vulkan). </description> </method> + <method name="texture_is_discardable"> + <return type="bool" /> + <param index="0" name="texture" type="RID" /> + <description> + Returns [code]true[/code] if the [param texture] is discardable, [code]false[/code] otherwise. See [RDTextureFormat] or [method texture_set_discardable]. + </description> + </method> <method name="texture_is_format_supported_for_usage" qualifiers="const"> <return type="bool" /> <param index="0" name="format" type="int" enum="RenderingDevice.DataFormat" /> @@ -984,6 +989,16 @@ [b]Note:[/b] [param to_texture] texture must [b]not[/b] be multisampled and must also be 2D (or a slice of a 3D/cubemap texture). </description> </method> + <method name="texture_set_discardable"> + <return type="void" /> + <param index="0" name="texture" type="RID" /> + <param index="1" name="discardable" type="bool" /> + <description> + Updates the discardable property of [param texture]. + If a texture is discardable, its contents do not need to be preserved between frames. This flag is only relevant when the texture is used as target in a draw list. + This information is used by [RenderingDevice] to figure out if a texture's contents can be discarded, eliminating unnecessary writes to memory and boosting performance. + </description> + </method> <method name="texture_update"> <return type="int" enum="Error" /> <param index="0" name="texture" type="RID" /> @@ -2279,40 +2294,40 @@ </constant> <constant name="DYNAMIC_STATE_STENCIL_REFERENCE" value="64" enum="PipelineDynamicStateFlags" is_bitfield="true"> </constant> - <constant name="INITIAL_ACTION_LOAD" value="0" enum="InitialAction"> + <constant name="INITIAL_ACTION_LOAD" value="0" enum="InitialAction" deprecated="Initial actions are solved automatically by RenderingDevice."> Load the previous contents of the framebuffer. </constant> - <constant name="INITIAL_ACTION_CLEAR" value="1" enum="InitialAction"> + <constant name="INITIAL_ACTION_CLEAR" value="1" enum="InitialAction" deprecated="Initial actions are solved automatically by RenderingDevice."> Clear the whole framebuffer or its specified region. </constant> - <constant name="INITIAL_ACTION_DISCARD" value="2" enum="InitialAction"> + <constant name="INITIAL_ACTION_DISCARD" value="2" enum="InitialAction" deprecated="Initial actions are solved automatically by RenderingDevice."> Ignore the previous contents of the framebuffer. This is the fastest option if you'll overwrite all of the pixels and don't need to read any of them. </constant> - <constant name="INITIAL_ACTION_MAX" value="3" enum="InitialAction"> + <constant name="INITIAL_ACTION_MAX" value="3" enum="InitialAction" deprecated="Initial actions are solved automatically by RenderingDevice."> Represents the size of the [enum InitialAction] enum. </constant> - <constant name="INITIAL_ACTION_CLEAR_REGION" value="1" enum="InitialAction" deprecated="Use [constant INITIAL_ACTION_CLEAR] instead."> + <constant name="INITIAL_ACTION_CLEAR_REGION" value="1" enum="InitialAction" deprecated="Initial actions are solved automatically by RenderingDevice."> </constant> - <constant name="INITIAL_ACTION_CLEAR_REGION_CONTINUE" value="1" enum="InitialAction" deprecated="Use [constant INITIAL_ACTION_LOAD] instead."> + <constant name="INITIAL_ACTION_CLEAR_REGION_CONTINUE" value="1" enum="InitialAction" deprecated="Initial actions are solved automatically by RenderingDevice."> </constant> - <constant name="INITIAL_ACTION_KEEP" value="0" enum="InitialAction" deprecated="Use [constant INITIAL_ACTION_LOAD] instead."> + <constant name="INITIAL_ACTION_KEEP" value="0" enum="InitialAction" deprecated="Initial actions are solved automatically by RenderingDevice."> </constant> - <constant name="INITIAL_ACTION_DROP" value="2" enum="InitialAction" deprecated="Use [constant INITIAL_ACTION_DISCARD] instead."> + <constant name="INITIAL_ACTION_DROP" value="2" enum="InitialAction" deprecated="Initial actions are solved automatically by RenderingDevice."> </constant> - <constant name="INITIAL_ACTION_CONTINUE" value="0" enum="InitialAction" deprecated="Use [constant INITIAL_ACTION_LOAD] instead."> + <constant name="INITIAL_ACTION_CONTINUE" value="0" enum="InitialAction" deprecated="Initial actions are solved automatically by RenderingDevice."> </constant> - <constant name="FINAL_ACTION_STORE" value="0" enum="FinalAction"> + <constant name="FINAL_ACTION_STORE" value="0" enum="FinalAction" deprecated="Final actions are solved automatically by RenderingDevice."> Store the result of the draw list in the framebuffer. This is generally what you want to do. </constant> - <constant name="FINAL_ACTION_DISCARD" value="1" enum="FinalAction"> + <constant name="FINAL_ACTION_DISCARD" value="1" enum="FinalAction" deprecated="Final actions are solved automatically by RenderingDevice."> Discard the contents of the framebuffer. This is the fastest option if you don't need to use the results of the draw list. </constant> - <constant name="FINAL_ACTION_MAX" value="2" enum="FinalAction"> + <constant name="FINAL_ACTION_MAX" value="2" enum="FinalAction" deprecated="Final actions are solved automatically by RenderingDevice."> Represents the size of the [enum FinalAction] enum. </constant> - <constant name="FINAL_ACTION_READ" value="0" enum="FinalAction" deprecated="Use [constant FINAL_ACTION_STORE] instead."> + <constant name="FINAL_ACTION_READ" value="0" enum="FinalAction" deprecated="Final actions are solved automatically by RenderingDevice."> </constant> - <constant name="FINAL_ACTION_CONTINUE" value="0" enum="FinalAction" deprecated="Use [constant FINAL_ACTION_STORE] instead."> + <constant name="FINAL_ACTION_CONTINUE" value="0" enum="FinalAction" deprecated="Final actions are solved automatically by RenderingDevice."> </constant> <constant name="SHADER_STAGE_VERTEX" value="0" enum="ShaderStage"> Vertex shader stage. This can be used to manipulate vertices from a shader (but not create new vertices). @@ -2514,5 +2529,86 @@ </constant> <constant name="DEBUG_PASS" value="786432" enum="BreadcrumbMarker"> </constant> + <constant name="DRAW_DEFAULT_ALL" value="0" enum="DrawFlags" is_bitfield="true"> + Do not clear or ignore any attachments. + </constant> + <constant name="DRAW_CLEAR_COLOR_0" value="1" enum="DrawFlags" is_bitfield="true"> + Clear the first color attachment. + </constant> + <constant name="DRAW_CLEAR_COLOR_1" value="2" enum="DrawFlags" is_bitfield="true"> + Clear the second color attachment. + </constant> + <constant name="DRAW_CLEAR_COLOR_2" value="4" enum="DrawFlags" is_bitfield="true"> + Clear the third color attachment. + </constant> + <constant name="DRAW_CLEAR_COLOR_3" value="8" enum="DrawFlags" is_bitfield="true"> + Clear the fourth color attachment. + </constant> + <constant name="DRAW_CLEAR_COLOR_4" value="16" enum="DrawFlags" is_bitfield="true"> + Clear the fifth color attachment. + </constant> + <constant name="DRAW_CLEAR_COLOR_5" value="32" enum="DrawFlags" is_bitfield="true"> + Clear the sixth color attachment. + </constant> + <constant name="DRAW_CLEAR_COLOR_6" value="64" enum="DrawFlags" is_bitfield="true"> + Clear the seventh color attachment. + </constant> + <constant name="DRAW_CLEAR_COLOR_7" value="128" enum="DrawFlags" is_bitfield="true"> + Clear the eighth color attachment. + </constant> + <constant name="DRAW_CLEAR_COLOR_MASK" value="255" enum="DrawFlags" is_bitfield="true"> + Mask for clearing all color attachments. + </constant> + <constant name="DRAW_CLEAR_COLOR_ALL" value="255" enum="DrawFlags" is_bitfield="true"> + Clear all color attachments. + </constant> + <constant name="DRAW_IGNORE_COLOR_0" value="256" enum="DrawFlags" is_bitfield="true"> + Ignore the previous contents of the first color attachment. + </constant> + <constant name="DRAW_IGNORE_COLOR_1" value="512" enum="DrawFlags" is_bitfield="true"> + Ignore the previous contents of the second color attachment. + </constant> + <constant name="DRAW_IGNORE_COLOR_2" value="1024" enum="DrawFlags" is_bitfield="true"> + Ignore the previous contents of the third color attachment. + </constant> + <constant name="DRAW_IGNORE_COLOR_3" value="2048" enum="DrawFlags" is_bitfield="true"> + Ignore the previous contents of the fourth color attachment. + </constant> + <constant name="DRAW_IGNORE_COLOR_4" value="4096" enum="DrawFlags" is_bitfield="true"> + Ignore the previous contents of the fifth color attachment. + </constant> + <constant name="DRAW_IGNORE_COLOR_5" value="8192" enum="DrawFlags" is_bitfield="true"> + Ignore the previous contents of the sixth color attachment. + </constant> + <constant name="DRAW_IGNORE_COLOR_6" value="16384" enum="DrawFlags" is_bitfield="true"> + Ignore the previous contents of the seventh color attachment. + </constant> + <constant name="DRAW_IGNORE_COLOR_7" value="32768" enum="DrawFlags" is_bitfield="true"> + Ignore the previous contents of the eighth color attachment. + </constant> + <constant name="DRAW_IGNORE_COLOR_MASK" value="65280" enum="DrawFlags" is_bitfield="true"> + Mask for ignoring all the previous contents of the color attachments. + </constant> + <constant name="DRAW_IGNORE_COLOR_ALL" value="65280" enum="DrawFlags" is_bitfield="true"> + Ignore the previous contents of all color attachments. + </constant> + <constant name="DRAW_CLEAR_DEPTH" value="65536" enum="DrawFlags" is_bitfield="true"> + Clear the depth attachment. + </constant> + <constant name="DRAW_IGNORE_DEPTH" value="131072" enum="DrawFlags" is_bitfield="true"> + Ignore the previous contents of the depth attachment. + </constant> + <constant name="DRAW_CLEAR_STENCIL" value="262144" enum="DrawFlags" is_bitfield="true"> + Clear the stencil attachment. + </constant> + <constant name="DRAW_IGNORE_STENCIL" value="524288" enum="DrawFlags" is_bitfield="true"> + Ignore the previous contents of the stencil attachment. + </constant> + <constant name="DRAW_CLEAR_ALL" value="327935" enum="DrawFlags" is_bitfield="true"> + Clear all attachments. + </constant> + <constant name="DRAW_IGNORE_ALL" value="720640" enum="DrawFlags" is_bitfield="true"> + Ignore the previous contents of all attachments. + </constant> </constants> </class> |