From 2d7228251d59c67c40843b34250ee6392eb10faa Mon Sep 17 00:00:00 2001 From: Hugo Locurcio Date: Tue, 28 Mar 2023 17:32:29 +0200 Subject: Improve RenderingServer, RenderingDevice, ShaderGlobalsOverride documentation This brings the overall class reference completion percentage from 87% to 92%. (cherry picked from commit 5056c427d32218e85ad79d51788fa7583d48e293) --- doc/classes/BaseMaterial3D.xml | 4 +- doc/classes/CanvasItem.xml | 8 +- doc/classes/GPUParticlesCollisionHeightField3D.xml | 2 +- doc/classes/GeometryInstance3D.xml | 3 +- doc/classes/Light3D.xml | 2 +- doc/classes/OS.xml | 2 +- doc/classes/ProjectSettings.xml | 55 +- doc/classes/RDAttachmentFormat.xml | 5 + doc/classes/RDFramebufferPass.xml | 6 +- doc/classes/RDPipelineColorBlendState.xml | 6 + .../RDPipelineColorBlendStateAttachment.xml | 70 +++ doc/classes/RDPipelineDepthStencilState.xml | 3 + doc/classes/RDPipelineMultisampleState.xml | 8 + doc/classes/RDPipelineRasterizationState.xml | 8 + doc/classes/RDPipelineSpecializationConstant.xml | 5 + doc/classes/RDSamplerState.xml | 16 + doc/classes/RDShaderFile.xml | 7 + doc/classes/RDShaderSPIRV.xml | 17 + doc/classes/RDShaderSource.xml | 11 + doc/classes/RDTextureFormat.xml | 11 + doc/classes/RDTextureView.xml | 7 + doc/classes/RDUniform.xml | 4 + doc/classes/RDVertexAttribute.xml | 2 + doc/classes/ReflectionProbe.xml | 14 +- doc/classes/RenderingDevice.xml | 604 ++++++++++++++++++- doc/classes/RenderingServer.xml | 648 ++++++++++++++++----- doc/classes/ShaderGlobalsOverride.xml | 4 + doc/classes/Sky.xml | 2 +- doc/classes/Viewport.xml | 5 +- 29 files changed, 1366 insertions(+), 173 deletions(-) (limited to 'doc') diff --git a/doc/classes/BaseMaterial3D.xml b/doc/classes/BaseMaterial3D.xml index 1d95152103..c42b796fc3 100644 --- a/doc/classes/BaseMaterial3D.xml +++ b/doc/classes/BaseMaterial3D.xml @@ -356,13 +356,13 @@ [b]Note:[/b] [member specular_mode] only applies to the specular blob. It does not affect specular reflections from the sky, screen-space reflections, [VoxelGI], SDFGI or [ReflectionProbe]s. To disable reflections from these sources as well, set [member metallic_specular] to [code]0.0[/code] instead. - If [code]true[/code], subsurface scattering is enabled. Emulates light that penetrates an object's surface, is scattered, and then emerges. + If [code]true[/code], subsurface scattering is enabled. Emulates light that penetrates an object's surface, is scattered, and then emerges. Subsurface scattering quality is controlled by [member ProjectSettings.rendering/environment/subsurface_scattering/subsurface_scattering_quality]. If [code]true[/code], subsurface scattering will use a special mode optimized for the color and density of human skin, such as boosting the intensity of the red channel in subsurface scattering. - The strength of the subsurface scattering effect. + The strength of the subsurface scattering effect. The depth of the effect is also controlled by [member ProjectSettings.rendering/environment/subsurface_scattering/subsurface_scattering_scale], which is set globally. Texture used to control the subsurface scattering strength. Stored in the red texture channel. Multiplied by [member subsurf_scatter_strength]. diff --git a/doc/classes/CanvasItem.xml b/doc/classes/CanvasItem.xml index 17114e823a..e2a43093ee 100644 --- a/doc/classes/CanvasItem.xml +++ b/doc/classes/CanvasItem.xml @@ -237,7 +237,7 @@ - Draws a solid polygon of any number of points, convex or concave. Unlike [method draw_colored_polygon], each point's color can be changed individually. See also [method draw_polyline] and [method draw_polyline_colors]. + Draws a solid polygon of any number of points, convex or concave. Unlike [method draw_colored_polygon], each point's color can be changed individually. See also [method draw_polyline] and [method draw_polyline_colors]. If you need more flexibility (such as being able to use bones), use [method RenderingServer.canvas_item_add_triangle_array] instead. @@ -279,7 +279,7 @@ - Draws a rectangle. If [param filled] is [code]true[/code], the rectangle will be filled with the [param color] specified. If [param filled] is [code]false[/code], the rectangle will be drawn as a stroke with the [param color] and [param width] specified. + Draws a rectangle. If [param filled] is [code]true[/code], the rectangle will be filled with the [param color] specified. If [param filled] is [code]false[/code], the rectangle will be drawn as a stroke with the [param color] and [param width] specified. See also [method draw_texture_rect]. If [param width] is negative, then two-point primitives will be drawn instead of a four-point ones. This means that when the CanvasItem is scaled, the lines will remain thin. If this behavior is not desired, then pass a positive [param width] like [code]1.0[/code]. [b]Note:[/b] [param width] is only effective if [param filled] is [code]false[/code]. [b]Note:[/b] Unfilled rectangles drawn with a negative [param width] may not display perfectly. For example, corners may be missing or brighter due to overlapping lines (for a translucent [param color]). @@ -380,7 +380,7 @@ - Draws a textured rectangle at a given position, optionally modulated by a color. If [param transpose] is [code]true[/code], the texture will have its X and Y coordinates swapped. + Draws a textured rectangle at a given position, optionally modulated by a color. If [param transpose] is [code]true[/code], the texture will have its X and Y coordinates swapped. See also [method draw_rect] and [method draw_texture_rect_region]. @@ -392,7 +392,7 @@ - Draws a textured rectangle region at a given position, optionally modulated by a color. If [param transpose] is [code]true[/code], the texture will have its X and Y coordinates swapped. + Draws a textured rectangle from a texture's region (specified by [param src_rect]) at a given position, optionally modulated by a color. If [param transpose] is [code]true[/code], the texture will have its X and Y coordinates swapped. See also [method draw_texture_rect]. diff --git a/doc/classes/GPUParticlesCollisionHeightField3D.xml b/doc/classes/GPUParticlesCollisionHeightField3D.xml index c8ed78b85e..006759bad0 100644 --- a/doc/classes/GPUParticlesCollisionHeightField3D.xml +++ b/doc/classes/GPUParticlesCollisionHeightField3D.xml @@ -50,7 +50,7 @@ Represents the size of the [enum Resolution] enum. - Only update the heightmap when the [GPUParticlesCollisionHeightField3D] node is moved, or when the camera moves if [member follow_camera_enabled] is [code]true[/code]. An update can be forced by slightly moving the [GPUParticlesCollisionHeightField3D] in any direction. + Only update the heightmap when the [GPUParticlesCollisionHeightField3D] node is moved, or when the camera moves if [member follow_camera_enabled] is [code]true[/code]. An update can be forced by slightly moving the [GPUParticlesCollisionHeightField3D] in any direction, or by calling [method RenderingServer.particles_collision_height_field_update]. Update the heightmap every frame. This has a significant performance cost. This update should only be used when geometry that particles can collide with changes significantly during gameplay. diff --git a/doc/classes/GeometryInstance3D.xml b/doc/classes/GeometryInstance3D.xml index c260b3a82f..9e939280c8 100644 --- a/doc/classes/GeometryInstance3D.xml +++ b/doc/classes/GeometryInstance3D.xml @@ -33,7 +33,7 @@ The selected shadow casting flag. See [enum ShadowCastingSetting] for possible values. - Overrides the bounding box of this node with a custom one. This can be used to avoid the expensive [AABB] recalculation that happens when a skeleton is used with a [MeshInstance3D] or to have fine control over the [MeshInstance3D]'s bounding box. To remove this, set value to an [AABB] with all fields set to zero. + Overrides the bounding box of this node with a custom one. This can be used to avoid the expensive [AABB] recalculation that happens when a skeleton is used with a [MeshInstance3D] or to have fine control over the [MeshInstance3D]'s bounding box. To use the default AABB, set value to an [AABB] with all fields set to [code]0.0[/code]. To avoid frustum culling, set [member custom_aabb] to a very large AABB that covers your entire game world such as [code]AABB(-10000, -10000, -10000, 20000, 20000, 20000)[/code]. To disable all forms of culling (including occlusion culling), call [method RenderingServer.instance_set_ignore_culling] on the [GeometryInstance3D]'s [RID]. The extra distance added to the GeometryInstance3D's bounding box ([AABB]) to increase its cull box. @@ -47,6 +47,7 @@ If [code]true[/code], disables occlusion culling for this instance. Useful for gizmos that must be rendered even when occlusion culling is in use. + [b]Note:[/b] [member ignore_occlusion_culling] does not affect frustum culling (which is what happens when an object is not visible given the camera's angle). To avoid frustum culling, set [member custom_aabb] to a very large AABB that covers your entire game world such as [code]AABB(-10000, -10000, -10000, 20000, 20000, 20000)[/code]. Changes how quickly the mesh transitions to a lower level of detail. A value of 0 will force the mesh to its lowest level of detail, a value of 1 will use the default settings, and larger values will keep the mesh in a higher level of detail at farther distances. diff --git a/doc/classes/Light3D.xml b/doc/classes/Light3D.xml index 2a0b2da46c..4502c74dd4 100644 --- a/doc/classes/Light3D.xml +++ b/doc/classes/Light3D.xml @@ -204,7 +204,7 @@ Light is taken into account in static baking ([VoxelGI], [LightmapGI], SDFGI ([member Environment.sdfgi_enabled])). The light can be moved around or modified, but its global illumination will not update in real-time. This is suitable for subtle changes (such as flickering torches), but generally not large changes such as toggling a light on and off. - Light is taken into account in dynamic baking ([VoxelGI] and SDFGI ([member Environment.sdfgi_enabled]) only). The light can be moved around or modified with global illumination updating in real-time. The light's global illumination appearance will be slightly different compared to [constant BAKE_STATIC]. This has a greater performance cost compared to [constant BAKE_STATIC]. + Light is taken into account in dynamic baking ([VoxelGI] and SDFGI ([member Environment.sdfgi_enabled]) only). The light can be moved around or modified with global illumination updating in real-time. The light's global illumination appearance will be slightly different compared to [constant BAKE_STATIC]. This has a greater performance cost compared to [constant BAKE_STATIC]. When using SDFGI, the update speed of dynamic lights is affected by [member ProjectSettings.rendering/global_illumination/sdfgi/frames_to_update_lights]. diff --git a/doc/classes/OS.xml b/doc/classes/OS.xml index ce4f1fbcd4..86b9c582b9 100644 --- a/doc/classes/OS.xml +++ b/doc/classes/OS.xml @@ -471,7 +471,7 @@ - Returns the video adapter driver name and version for the user's currently active graphics card. + Returns the video adapter driver name and version for the user's currently active graphics card. See also [method RenderingServer.get_video_adapter_api_version]. The first element holds the driver name, such as [code]nvidia[/code], [code]amdgpu[/code], etc. The second element holds the driver version. For e.g. the [code]nvidia[/code] driver on a Linux/BSD platform, the version is in the format [code]510.85.02[/code]. For Windows, the driver's format is [code]31.0.15.1659[/code]. [b]Note:[/b] This method is only supported on the platforms Linux/BSD and Windows when not running in headless mode. It returns an empty array on other platforms. diff --git a/doc/classes/ProjectSettings.xml b/doc/classes/ProjectSettings.xml index 16c485c0bc..445aadec31 100644 --- a/doc/classes/ProjectSettings.xml +++ b/doc/classes/ProjectSettings.xml @@ -821,6 +821,7 @@ Default value for [member ScrollContainer.scroll_deadzone], which will be used for all [ScrollContainer]s unless overridden. + If [code]true[/code], snaps [Control] node vertices to the nearest pixel to ensure they remain crisp even when the camera moves or zooms. If [code]true[/code], swaps [b]Cancel[/b] and [b]OK[/b] buttons in dialogs on Windows and UWP to follow interface conventions. [method DisplayServer.get_swap_cancel_ok] can be used to query whether buttons are swapped at run-time. @@ -1952,23 +1953,34 @@ [b]Note:[/b] Only [member physics/common/max_physics_steps_per_frame] physics ticks may be simulated per rendered frame at most. If more physics ticks have to be simulated per rendered frame to keep up with rendering, the project will appear to slow down (even if [code]delta[/code] is used consistently in physics calculations). Therefore, it is recommended to also increase [member physics/common/max_physics_steps_per_frame] if increasing [member physics/common/physics_ticks_per_second] significantly above its default value. + Controls how much of the original viewport size should be covered by the 2D signed distance field. This SDF can be sampled in [CanvasItem] shaders and is used for [GPUParticles2D] collision. Higher values allow portions of occluders located outside the viewport to still be taken into account in the generated signed distance field, at the cost of performance. If you notice particles falling through [LightOccluder2D]s as the occluders leave the viewport, increase this setting. + The percentage specified is added on each axis and on both sides. For example, with the default setting of 120%, the signed distance field will cover 20% of the viewport's size outside the viewport on each side (top, right, bottom, left). + [b]Note:[/b] This property is only read when the project starts. To change the 2D SDF oversizing percentage at runtime, use [method RenderingServer.viewport_set_sdf_oversize_and_scale] instead. + The resolution scale to use for the 2D signed distance field. Higher values lead to a more precise and more stable signed distance field as the camera moves, at the cost of performance. The default value (50%) renders at half the resolution of the viewport size on each axis, which means the SDF is generated with 25% of the viewport's pixel count. + [b]Note:[/b] This property is only read when the project starts. To change the 2D SDF resolution scale at runtime, use [method RenderingServer.viewport_set_sdf_oversize_and_scale] instead. + The size of the 2D shadow atlas in pixels. Higher values result in more precise [Light2D] shadows, at the cost of performance and video memory usage. The specified value is rounded up to the nearest power of 2. + [b]Note:[/b] This property is only read when the project starts. To change the 2D shadow atlas size at runtime, use [method RenderingServer.canvas_set_shadow_texture_size] instead. - If [code]true[/code], [CanvasItem] nodes will internally snap to full pixels. Their position can still be sub-pixel, but the decimals will not have effect. + If [code]true[/code], [CanvasItem] nodes will internally snap to full pixels. Their position can still be sub-pixel, but the decimals will not have effect. This can lead to a crisper appearance at the cost of less smooth movement, especially when [Camera2D] smoothing is enabled. + [b]Note:[/b] This property is only read when the project starts. To toggle 2D transform snapping at runtime, use [method RenderingServer.viewport_set_snap_2d_transforms_to_pixel] on the root [Viewport] instead. + [b]Note:[/b] [Control] nodes are snapped to the nearest pixel by default. This is controlled by [member gui/common/snap_controls_to_pixels]. - If [code]true[/code], vertices of [CanvasItem] nodes will snap to full pixels. Only affects the final vertex positions, not the transforms. + If [code]true[/code], vertices of [CanvasItem] nodes will snap to full pixels. Only affects the final vertex positions, not the transforms. This can lead to a crisper appearance at the cost of less smooth movement, especially when [Camera2D] smoothing is enabled. + [b]Note:[/b] This property is only read when the project starts. To toggle 2D vertex snapping at runtime, use [method RenderingServer.viewport_set_snap_2d_vertices_to_pixel] on the root [Viewport] instead. + [b]Note:[/b] [Control] nodes are snapped to the nearest pixel by default. This is controlled by [member gui/common/snap_controls_to_pixels]. - Sets the number of MSAA samples to use for 2D/Canvas rendering (as a power of two). MSAA is used to reduce aliasing around the edges of polygons. A higher MSAA value results in smoother edges but can be significantly slower on some hardware. This has no effect on shader-induced aliasing or texture aliasing. + Sets the number of MSAA samples to use for 2D/Canvas rendering (as a power of two). MSAA is used to reduce aliasing around the edges of polygons. A higher MSAA value results in smoother edges but can be significantly slower on some hardware, especially integrated graphics due to their limited memory bandwidth. This has no effect on shader-induced aliasing or texture aliasing. [b]Note:[/b] MSAA is only supported in the Forward+ and Mobile rendering methods, not Compatibility. - Sets the number of MSAA samples to use for 3D rendering (as a power of two). MSAA is used to reduce aliasing around the edges of polygons. A higher MSAA value results in smoother edges but can be significantly slower on some hardware. See also bilinear scaling 3d [member rendering/scaling_3d/mode] for supersampling, which provides higher quality but is much more expensive. This has no effect on shader-induced aliasing or texture aliasing. + Sets the number of MSAA samples to use for 3D rendering (as a power of two). MSAA is used to reduce aliasing around the edges of polygons. A higher MSAA value results in smoother edges but can be significantly slower on some hardware, especially integrated graphics due to their limited memory bandwidth. See also [member rendering/scaling_3d/mode] for supersampling, which provides higher quality but is much more expensive. This has no effect on shader-induced aliasing or texture aliasing. [b]Note:[/b] MSAA is only supported in the Forward+ and Mobile rendering methods, not Compatibility. @@ -1987,12 +1999,15 @@ [b]Note:[/b] TAA is only supported in the Forward+ rendering method, not Mobile or Compatibility. + [b]Note:[/b] This property is only read when the project starts. To control the screen-space roughness limiter at runtime, call [method RenderingServer.screen_space_roughness_limiter_set_active] instead. If [code]true[/code], enables a spatial filter to limit roughness in areas with high-frequency detail. This can help reduce specular aliasing to an extent, though not as much as enabling [member rendering/anti_aliasing/quality/use_taa]. This filter has a small performance cost, so consider disabling it if it doesn't benefit your scene noticeably. - [b]Note:[/b] TAA is only supported in the Forward+ and Mobile rendering methods, not Compatibility. + [b]Note:[/b] The screen-space roughness limiter is only supported in the Forward+ and Mobile rendering methods, not Compatibility. + [b]Note:[/b] This property is only read when the project starts. To control the screen-space roughness limiter at runtime, call [method RenderingServer.screen_space_roughness_limiter_set_active] instead. + [b]Note:[/b] This property is only read when the project starts. To control the screen-space roughness limiter at runtime, call [method RenderingServer.screen_space_roughness_limiter_set_active] instead. Sets the quality of the depth of field effect. Higher quality takes more samples, which is slower but looks smoother. @@ -2065,13 +2080,16 @@ Sets the quality of the screen-space indirect lighting effect. Higher values take more samples and so will result in better quality, at the cost of performance. Setting to [code]Ultra[/code] will use the [member rendering/environment/ssil/adaptive_target] setting. - Scales the depth over which the subsurface scattering effect is applied. A high value may allow light to scatter into a part of the mesh or another mesh that is close in screen space but far in depth. + Scales the depth over which the subsurface scattering effect is applied. A high value may allow light to scatter into a part of the mesh or another mesh that is close in screen space but far in depth. See also [member rendering/environment/subsurface_scattering/subsurface_scattering_scale]. + [b]Note:[/b] This property is only read when the project starts. To set the subsurface scattering depth scale at runtime, call [method RenderingServer.sub_surface_scattering_set_scale] instead. - Sets the quality of the subsurface scattering effect. Higher values are slower but look nicer. + Sets the quality of the subsurface scattering effect. Higher values are slower but look nicer. This affects the rendering of materials that have [member BaseMaterial3D.subsurf_scatter_enabled] set to [code]true[/code], along with [ShaderMaterial]s that set [code]SSS_STRENGTH[/code]. + [b]Note:[/b] This property is only read when the project starts. To set the subsurface scattering quality at runtime, call [method RenderingServer.sub_surface_scattering_set_quality] instead. - Scales the distance over which samples are taken for subsurface scattering effect. Changing this does not impact performance, but higher values will result in significant artifacts as the samples will become obviously spread out. A lower value results in a smaller spread of scattered light. + Scales the distance over which samples are taken for subsurface scattering effect. Changing this does not impact performance, but higher values will result in significant artifacts as the samples will become obviously spread out. A lower value results in a smaller spread of scattered light. See also [member rendering/environment/subsurface_scattering/subsurface_scattering_depth_scale]. + [b]Note:[/b] This property is only read when the project starts. To set the subsurface scattering scale at runtime, call [method RenderingServer.sub_surface_scattering_set_scale] instead. Enables filtering of the volumetric fog effect prior to integration. This substantially blurs the fog which reduces fine details but also smooths out harsh edges and aliasing artifacts. Disable when more detail is required. @@ -2111,12 +2129,21 @@ [b]Note:[/b] This property is only read when the project starts. To set half-resolution GI at run-time, call [method RenderingServer.gi_set_use_half_resolution] instead. + The number of frames to use for converging signed distance field global illumination. Higher values lead to a less noisy result, at the cost of taking a longer time to fully converge. This means the scene's global illumination will be too dark for a longer period of time, especially when the camera moves fast. The actual convergence speed depends on rendered framerate. For example, with the default setting of 30 frames, rendering at 60 FPS will make SDFGI fully converge after 0.5 seconds. See also [member rendering/global_illumination/sdfgi/frames_to_update_lights] and [member rendering/global_illumination/sdfgi/probe_ray_count]. + [b]Note:[/b] This property is only read when the project starts. To control SDFGI convergence speed at runtime, call [method RenderingServer.environment_set_sdfgi_frames_to_converge] instead. + The number of frames over which dynamic lights should be updated in signed distance field global illumination. Higher values take more time to update indirect lighting coming from dynamic lights, but result in better performance when many dynamic lights are present. See also [member rendering/global_illumination/sdfgi/frames_to_converge] and [member rendering/global_illumination/sdfgi/probe_ray_count]. + [b]Note:[/b] This only affects [Light3D] nodes whose [member Light3D.light_bake_mode] is [constant Light3D.BAKE_DYNAMIC] (which is the default). Consider making non-moving lights use the [constant Light3D.BAKE_STATIC] bake mode to improve performance. + [b]Note:[/b] This property is only read when the project starts. To control SDFGI light update speed at runtime, call [method RenderingServer.environment_set_sdfgi_frames_to_update_light] instead. + The number of rays to throw per frame when computing signed distance field global illumination. Higher values lead to a less noisy result, at the cost of performance. See also [member rendering/global_illumination/sdfgi/frames_to_converge] and [member rendering/global_illumination/sdfgi/frames_to_update_lights]. + [b]Note:[/b] This property is only read when the project starts. To control SDFGI quality at runtime, call [method RenderingServer.environment_set_sdfgi_ray_count] instead. + The VoxelGI quality to use. High quality leads to more precise lighting and better reflections, but is slower to render. This setting does not affect the baked data and doesn't require baking the [VoxelGI] again to apply. + [b]Note:[/b] This property is only read when the project starts. To control VoxelGI quality at runtime, call [method RenderingServer.voxel_gi_set_quality] instead. The maximum number of rays that can be thrown per pass when baking lightmaps with [LightmapGI]. Depending on the scene, adjusting this value may result in higher GPU utilization when baking lightmaps, leading to faster bake times. @@ -2158,10 +2185,10 @@ The framerate-independent update speed when representing dynamic object lighting from [LightmapProbe]s. Higher values make dynamic object lighting update faster. Higher values can prevent fast-moving objects from having "outdated" indirect lighting displayed on them, at the cost of possible flickering when an object moves from a bright area to a shaded area. - Use 16 bits for shadow depth map. Enabling this results in shadows having less precision and may result in shadow acne, but can lead to performance improvements on some devices. + Use 16 bits for the directional shadow depth map. Enabling this results in shadows having less precision and may result in shadow acne, but can lead to performance improvements on some devices. - The directional shadow's size in pixels. Higher values will result in sharper shadows, at the cost of performance. The value will be rounded up to the nearest power of 2. + The directional shadow's size in pixels. Higher values will result in sharper shadows, at the cost of performance. The value is rounded up to the nearest power of 2. Lower-end override for [member rendering/lights_and_shadows/directional_shadow/size] on mobile devices, due to performance concerns or driver support. @@ -2175,7 +2202,7 @@ Lower-end override for [member rendering/lights_and_shadows/directional_shadow/soft_shadow_filter_quality] on mobile devices, due to performance concerns or driver support. - Use 16 bits for shadow depth map. Enabling this results in shadows having less precision and may result in shadow acne, but can lead to performance improvements on some devices. + Use 16 bits for the omni/spot shadow depth map. Enabling this results in shadows having less precision and may result in shadow acne, but can lead to performance improvements on some devices. Subdivision quadrant size for shadow mapping. See shadow mapping documentation. @@ -2239,10 +2266,12 @@ [b]Note:[/b] This property is only read when the project starts. To adjust the automatic LOD threshold at runtime, set [member Viewport.mesh_lod_threshold] on the root [Viewport]. - The [url=https://en.wikipedia.org/wiki/Bounding_volume_hierarchy]BVH[/url] quality to use when rendering the occlusion culling buffer. Higher values will result in more accurate occlusion culling, at the cost of higher CPU usage. + The [url=https://en.wikipedia.org/wiki/Bounding_volume_hierarchy]Bounding Volume Hierarchy[/url] quality to use when rendering the occlusion culling buffer. Higher values will result in more accurate occlusion culling, at the cost of higher CPU usage. See also [member rendering/occlusion_culling/occlusion_rays_per_thread]. + [b]Note:[/b] This property is only read when the project starts. To adjust the BVH build quality at runtime, use [method RenderingServer.viewport_set_occlusion_culling_build_quality]. - Higher values will result in more accurate occlusion culling, at the cost of higher CPU usage. The occlusion culling buffer's pixel count is roughly equal to [code]occlusion_rays_per_thread * number_of_logical_cpu_cores[/code], so it will depend on the system's CPU. Therefore, CPUs with fewer cores will use a lower resolution to attempt keeping performance costs even across devices. + The number of occlusion rays traced per CPU thread. Higher values will result in more accurate occlusion culling, at the cost of higher CPU usage. The occlusion culling buffer's pixel count is roughly equal to [code]occlusion_rays_per_thread * number_of_logical_cpu_cores[/code], so it will depend on the system's CPU. Therefore, CPUs with fewer cores will use a lower resolution to attempt keeping performance costs even across devices. See also [member rendering/occlusion_culling/bvh_build_quality]. + [b]Note:[/b] This property is only read when the project starts. To adjust the number of occlusion rays traced per thread at runtime, use [method RenderingServer.viewport_set_occlusion_rays_per_thread]. If [code]true[/code], [OccluderInstance3D] nodes will be usable for occlusion culling in 3D in the root viewport. In custom viewports, [member Viewport.use_occlusion_culling] must be set to [code]true[/code] instead. diff --git a/doc/classes/RDAttachmentFormat.xml b/doc/classes/RDAttachmentFormat.xml index 0d5316f29f..1e7377a10b 100644 --- a/doc/classes/RDAttachmentFormat.xml +++ b/doc/classes/RDAttachmentFormat.xml @@ -1,17 +1,22 @@ + Attachment format (used by [RenderingDevice]). + This object is used by [RenderingDevice]. + The attachment's data format. + The number of samples used when sampling the attachment. + The attachment's usage flags, which determine what can be done with it. diff --git a/doc/classes/RDFramebufferPass.xml b/doc/classes/RDFramebufferPass.xml index bf39afd3aa..b7ef3830ca 100644 --- a/doc/classes/RDFramebufferPass.xml +++ b/doc/classes/RDFramebufferPass.xml @@ -1,11 +1,12 @@ - Framebuffer pass attachment description. + Framebuffer pass attachment description (used by [RenderingDevice]). This class contains the list of attachment descriptions for a framebuffer pass. Each points with an index to a previously supplied list of texture attachments. - Multipass framebuffers can optimize some configurations in mobile, on desktop they provide little to no advantage. + Multipass framebuffers can optimize some configurations in mobile. On desktop, they provide little to no advantage. + This object is used by [RenderingDevice]. @@ -28,6 +29,7 @@ + Attachment is unused. diff --git a/doc/classes/RDPipelineColorBlendState.xml b/doc/classes/RDPipelineColorBlendState.xml index 70f03fb1f3..0f0e3ec75c 100644 --- a/doc/classes/RDPipelineColorBlendState.xml +++ b/doc/classes/RDPipelineColorBlendState.xml @@ -1,19 +1,25 @@ + Pipeline color blend state (used by [RenderingDevice]). + This object is used by [RenderingDevice]. + The attachments that are blended together. + The constant color to blend with. See also [method RenderingDevice.draw_list_set_blend_constants]. + If [code]true[/code], performs the logic operation defined in [member logic_op]. + The logic operation to perform for blending. Only effective if [member enable_logic_op] is [code]true[/code]. diff --git a/doc/classes/RDPipelineColorBlendStateAttachment.xml b/doc/classes/RDPipelineColorBlendStateAttachment.xml index b0caca64ee..6490c3afa7 100644 --- a/doc/classes/RDPipelineColorBlendStateAttachment.xml +++ b/doc/classes/RDPipelineColorBlendStateAttachment.xml @@ -1,8 +1,66 @@ + Pipeline color blend state attachment (used by [RenderingDevice]). + Controls how blending between source and destination fragments is performed when using [RenderingDevice]. + For reference, this is how common user-facing blend modes are implemented in Godot's 2D renderer: + [b]Mix:[/b] + [codeblock] + var attachment = RDPipelineColorBlendStateAttachment.new() + attachment.enable_blend = true + attachment.color_blend_op = RenderingDevice.BLEND_OP_ADD + attachment.src_color_blend_factor = RenderingDevice.BLEND_FACTOR_SRC_ALPHA + attachment.dst_color_blend_factor = RenderingDevice.BLEND_FACTOR_ONE_MINUS_SRC_ALPHA + attachment.alpha_blend_op = RenderingDevice.BLEND_OP_ADD + attachment.src_alpha_blend_factor = RenderingDevice.BLEND_FACTOR_ONE + attachment.dst_alpha_blend_factor = RenderingDevice.BLEND_FACTOR_ONE_MINUS_SRC_ALPHA + [/codeblock] + [b]Add:[/b] + [codeblock] + var attachment = RDPipelineColorBlendStateAttachment.new() + attachment.enable_blend = true + attachment.alpha_blend_op = RenderingDevice.BLEND_OP_ADD + attachment.color_blend_op = RenderingDevice.BLEND_OP_ADD + attachment.src_color_blend_factor = RenderingDevice.BLEND_FACTOR_SRC_ALPHA + attachment.dst_color_blend_factor = RenderingDevice.BLEND_FACTOR_ONE + attachment.src_alpha_blend_factor = RenderingDevice.BLEND_FACTOR_SRC_ALPHA + attachment.dst_alpha_blend_factor = RenderingDevice.BLEND_FACTOR_ONE + [/codeblock] + [b]Subtract:[/b] + [codeblock] + var attachment = RDPipelineColorBlendStateAttachment.new() + attachment.enable_blend = true + attachment.alpha_blend_op = RenderingDevice.BLEND_OP_SUBTRACT + attachment.color_blend_op = RenderingDevice.BLEND_OP_SUBTRACT + attachment.src_color_blend_factor = RenderingDevice.BLEND_FACTOR_SRC_ALPHA + attachment.dst_color_blend_factor = RenderingDevice.BLEND_FACTOR_ONE + attachment.src_alpha_blend_factor = RenderingDevice.BLEND_FACTOR_SRC_ALPHA + attachment.dst_alpha_blend_factor = RenderingDevice.BLEND_FACTOR_ONE + [/codeblock] + [b]Multiply:[/b] + [codeblock] + var attachment = RDPipelineColorBlendStateAttachment.new() + attachment.enable_blend = true + attachment.alpha_blend_op = RenderingDevice.BLEND_OP_ADD + attachment.color_blend_op = RenderingDevice.BLEND_OP_ADD + attachment.src_color_blend_factor = RenderingDevice.BLEND_FACTOR_DST_COLOR + attachment.dst_color_blend_factor = RenderingDevice.BLEND_FACTOR_ZERO + attachment.src_alpha_blend_factor = RenderingDevice.BLEND_FACTOR_DST_ALPHA + attachment.dst_alpha_blend_factor = RenderingDevice.BLEND_FACTOR_ZERO + [/codeblock] + [b]Pre-multiplied alpha:[/b] + [codeblock] + var attachment = RDPipelineColorBlendStateAttachment.new() + attachment.enable_blend = true + attachment.alpha_blend_op = RenderingDevice.BLEND_OP_ADD + attachment.color_blend_op = RenderingDevice.BLEND_OP_ADD + attachment.src_color_blend_factor = RenderingDevice.BLEND_FACTOR_ONE + attachment.dst_color_blend_factor = RenderingDevice.BLEND_FACTOR_ONE_MINUS_SRC_ALPHA + attachment.src_alpha_blend_factor = RenderingDevice.BLEND_FACTOR_ONE + attachment.dst_alpha_blend_factor = RenderingDevice.BLEND_FACTOR_ONE_MINUS_SRC_ALPHA + [/codeblock] @@ -10,31 +68,43 @@ + Convenience method to perform standard mix blending with straight (non-premultiplied) alpha. This sets [member enable_blend] to [code]true[/code], [member src_color_blend_factor] to [constant RenderingDevice.BLEND_FACTOR_SRC_ALPHA], [member dst_color_blend_factor] to [constant RenderingDevice.BLEND_FACTOR_ONE_MINUS_SRC_ALPHA], [member src_alpha_blend_factor] to [constant RenderingDevice.BLEND_FACTOR_SRC_ALPHA] and [member dst_alpha_blend_factor] to [constant RenderingDevice.BLEND_FACTOR_ONE_MINUS_SRC_ALPHA]. + The blend mode to use for the alpha channel. + The blend mode to use for the red/green/blue color channels. + Controls how the blend factor for the alpha channel is determined based on the destination's fragments. + Controls how the blend factor for the color channels is determined based on the destination's fragments. + If [code]true[/code], performs blending between the source and destination according to the factors defined in [member src_color_blend_factor], [member dst_color_blend_factor], [member src_alpha_blend_factor] and [member dst_alpha_blend_factor]. The blend modes [member color_blend_op] and [member alpha_blend_op] are also taken into account, with [member write_r], [member write_g], [member write_b] and [member write_a] controlling the output. + Controls how the blend factor for the alpha channel is determined based on the source's fragments. + Controls how the blend factor for the color channels is determined based on the source's fragments. + If [code]true[/code], writes the new alpha channel to the final result. + If [code]true[/code], writes the new blue color channel to the final result. + If [code]true[/code], writes the new green color channel to the final result. + If [code]true[/code], writes the new red color channel to the final result. diff --git a/doc/classes/RDPipelineDepthStencilState.xml b/doc/classes/RDPipelineDepthStencilState.xml index 1f2a40b83c..ce6d9af221 100644 --- a/doc/classes/RDPipelineDepthStencilState.xml +++ b/doc/classes/RDPipelineDepthStencilState.xml @@ -1,8 +1,10 @@ + Pipeline depth/stencil state (used by [RenderingDevice]). + [RDPipelineDepthStencilState] controls the way depth and stencil comparisons are performed when sampling those values using [RenderingDevice]. @@ -30,6 +32,7 @@ + If [code]true[/code], enables depth testing which allows objects to be automatically occluded by other objects based on their depth. This also allows objects to be partially occluded by other objects. If [code]false[/code], objects will appear in the order they were drawn (like in Godot's 2D renderer). diff --git a/doc/classes/RDPipelineMultisampleState.xml b/doc/classes/RDPipelineMultisampleState.xml index 62725137f8..5fde612da3 100644 --- a/doc/classes/RDPipelineMultisampleState.xml +++ b/doc/classes/RDPipelineMultisampleState.xml @@ -1,23 +1,31 @@ + Pipeline multisample state (used by [RenderingDevice]). + [RDPipelineMultisampleState] is used to control how multisample or supersample antialiasing is being performed when rendering using [RenderingDevice]. + If [code]true[/code], alpha to coverage is enabled. This generates a temporary coverage value based on the alpha component of the fragment's first color output. This allows alpha transparency to make use of multisample antialiasing. + If [code]true[/code], alpha is forced to either [code]0.0[/code] or [code]1.0[/code]. This allows hardening the edges of antialiased alpha transparencies. Only relevant if [member enable_alpha_to_coverage] is [code]true[/code]. + If [code]true[/code], enables per-sample shading which replaces MSAA by SSAA. This provides higher quality antialiasing that works with transparent (alpha scissor) edges. This has a very high performance cost. See also [member min_sample_shading]. See the [url=https://registry.khronos.org/vulkan/specs/1.3-extensions/html/vkspec.html#primsrast-sampleshading]per-sample shading Vulkan documentation[/url] for more details. + The multiplier of [member sample_count] that determines how many samples are performed for each fragment. Must be between [code]0.0[/code] and [code]1.0[/code] (inclusive). Only effective if [member enable_sample_shading] is [code]true[/code]. If [member min_sample_shading] is [code]1.0[/code], fragment invocation must only read from the coverage index sample. Tile image access must not be used if [member enable_sample_shading] is [i]not[/i] [code]1.0[/code]. + The number of MSAA samples (or SSAA samples if [member enable_sample_shading] is [code]true[/code]) to perform. Higher values result in better antialiasing, at the cost of performance. + The sampleSee the [url=https://registry.khronos.org/vulkan/specs/1.3-extensions/html/vkspec.html#fragops-samplemask]sample mask Vulkan documentation[/url] for more details. diff --git a/doc/classes/RDPipelineRasterizationState.xml b/doc/classes/RDPipelineRasterizationState.xml index 48599b6262..9940b90e71 100644 --- a/doc/classes/RDPipelineRasterizationState.xml +++ b/doc/classes/RDPipelineRasterizationState.xml @@ -1,13 +1,16 @@ + Pipeline rasterization state (used by [RenderingDevice]). + This object is used by [RenderingDevice]. + The cull mode to use when drawing polygons, which determines whether front faces or backfaces are hidden. @@ -18,16 +21,21 @@ + If [code]true[/code], primitives are discarded immediately before the rasterization stage. + The winding order to use to determine which face of a triangle is considered its front face. + THe line width to use when drawing lines (in pixels). Thick lines may not be supported on all hardware. + The number of control points to use when drawing a patch with tessellation enabled. Higher values result in higher quality at the cost of performance. + If [code]true[/code], performs wireframe rendering for triangles instead of flat or textured rendering. diff --git a/doc/classes/RDPipelineSpecializationConstant.xml b/doc/classes/RDPipelineSpecializationConstant.xml index 1528b9fcc1..d0bfa8130d 100644 --- a/doc/classes/RDPipelineSpecializationConstant.xml +++ b/doc/classes/RDPipelineSpecializationConstant.xml @@ -1,15 +1,20 @@ + Pipeline specialization constant (used by [RenderingDevice]). + A [i]specialization constant[/i] is a way to create additional variants of shaders without actually increasing the number of shader versions that are compiled. This allows improving performance by reducing the number of shader versions and reducing [code]if[/code] branching, while still allowing shaders to be flexible for different use cases. + This object is used by [RenderingDevice]. + The identifier of the specialization constant. This is a value starting from [code]0[/code] and that increments for every different specialization constant for a given shader. + The specialization constant's value. Only [bool], [int] and [float] types are valid for specialization constants. diff --git a/doc/classes/RDSamplerState.xml b/doc/classes/RDSamplerState.xml index a5cfc227d1..c4991bff97 100644 --- a/doc/classes/RDSamplerState.xml +++ b/doc/classes/RDSamplerState.xml @@ -1,41 +1,57 @@ + Sampler state (used by [RenderingDevice]). + This object is used by [RenderingDevice]. + Maximum anisotropy that can be used when sampling. Only effective if [member use_anisotropy] is [code]true[/code]. Higher values result in a sharper sampler at oblique angles, at the cost of performance (due to memory bandwidth). This value may be limited by the graphics hardware in use. Most graphics hardware only supports values up to [code]16.0[/code]. + If [member anisotropy_max] is [code]1.0[/code], forcibly disables anisotropy even if [member use_anisotropy] is [code]true[/code]. + The border color that will be returned when sampling outside the sampler's bounds and the [member repeat_u], [member repeat_v] or [member repeat_w] modes have repeating disabled. + The compare operation to use. Only effective if [member enable_compare] is [code]true[/code]. + If [code]true[/code], returned values will be based on the comparison operation defined in [member compare_op]. This is a hardware-based approach and is therefore faster than performing this manually in a shader. For example, compare operations are used for shadow map rendering by comparing depth values from a shadow sampler. + The mipmap LOD bias to use. Positive values will make the sampler blurrier at a given distance, while negative values will make the sampler sharper at a given distance (at the risk of looking grainy). Recommended values are between [code]-0.5[/code] and [code]0.0[/code]. Only effective if the sampler has mipmaps available. + The sampler's magnification filter. + The maximum mipmap LOD bias to display (lowest resolution). Only effective if the sampler has mipmaps available. + The minimum mipmap LOD bias to display (highest resolution). Only effective if the sampler has mipmaps available. + The filtering method to use for mipmaps. + The repeat mode to use along the U axis of UV coordinates. This affects the returned values if sampling outside the UV bounds. + The repeat mode to use along the V axis of UV coordinates. This affects the returned values if sampling outside the UV bounds. + The repeat mode to use along the W axis of UV coordinates. This affects the returned values if sampling outside the UV bounds. Only effective for 3D samplers. + If [code]true[/code], perform anisotropic sampling. See [member anisotropy_max]. diff --git a/doc/classes/RDShaderFile.xml b/doc/classes/RDShaderFile.xml index 72bf6faaec..b5872c210e 100644 --- a/doc/classes/RDShaderFile.xml +++ b/doc/classes/RDShaderFile.xml @@ -1,8 +1,11 @@ + Compiled shader file in SPIR-V form (used by [RenderingDevice]). Not to be confused with Godot's own [Shader]. + Compiled shader file in SPIR-V form. + See also [RDShaderSource]. [RDShaderFile] is only meant to be used with the [RenderingDevice] API. It should not be confused with Godot's own [Shader] resource, which is what Godot's various nodes use for high-level shader programming. @@ -11,11 +14,13 @@ + Returns the SPIR-V intermediate representation for the specified shader [param version]. + Returns the list of compiled versions for this shader. @@ -23,11 +28,13 @@ + Sets the SPIR-V [param bytecode] that will be compiled for the specified [param version]. + The base compilation error message, which indicates errors not related to a specific shader stage if non-empty. If empty, shader compilation is not necessarily successful (check [RDShaderSPIRV]'s error message members). diff --git a/doc/classes/RDShaderSPIRV.xml b/doc/classes/RDShaderSPIRV.xml index 13dc2c6519..f9bb4c4879 100644 --- a/doc/classes/RDShaderSPIRV.xml +++ b/doc/classes/RDShaderSPIRV.xml @@ -1,8 +1,11 @@ + SPIR-V intermediate representation as part of a [RDShaderFile] (used by [RenderingDevice]). + [RDShaderSPIRV] represents a [RDShaderFile]'s [url=https://www.khronos.org/spir/]SPIR-V[/url] code for various shader stages, as well as possible compilation error messages. SPIR-V a low-level intermediate shader representation. This intermediate representation is not used directly by GPUs for rendering, but it can be compiled into binary shaders that GPUs can understand. Unlike compiled shaders, SPIR-V is portable across GPU models and driver versions. + This object is used by [RenderingDevice]. @@ -11,12 +14,14 @@ + Equivalent to getting one of [member bytecode_compute], [member bytecode_fragment], [member bytecode_tesselation_control], [member bytecode_tesselation_evaluation], [member bytecode_vertex]. + Returns the compilation error message for the given shader [param stage]. Equivalent to getting one of [member compile_error_compute], [member compile_error_fragment], [member compile_error_tesselation_control], [member compile_error_tesselation_evaluation], [member compile_error_vertex]. @@ -24,6 +29,7 @@ + Sets the SPIR-V [param bytecode] for the given shader [param stage]. Equivalent to setting one of [member bytecode_compute], [member bytecode_fragment], [member bytecode_tesselation_control], [member bytecode_tesselation_evaluation], [member bytecode_vertex]. @@ -31,29 +37,40 @@ + Sets the compilation error message for the given shader [param stage] to [param compile_error]. Equivalent to setting one of [member compile_error_compute], [member compile_error_fragment], [member compile_error_tesselation_control], [member compile_error_tesselation_evaluation], [member compile_error_vertex]. + The SPIR-V bytecode for the compute shader stage. + The SPIR-V bytecode for the fragment shader stage. + The SPIR-V bytecode for the tessellation control shader stage. + The SPIR-V bytecode for the tessellation evaluation shader stage. + The SPIR-V bytecode for the vertex shader stage. + The compilation error message for the compute shader stage (set by the SPIR-V compiler and Godot). If empty, shader compilation was successful. + The compilation error message for the fragment shader stage (set by the SPIR-V compiler and Godot). If empty, shader compilation was successful. + The compilation error message for the tessellation control shader stage (set by the SPIR-V compiler and Godot). If empty, shader compilation was successful. + The compilation error message for the tessellation evaluation shader stage (set by the SPIR-V compiler and Godot). If empty, shader compilation was successful. + The compilation error message for the vertex shader stage (set by the SPIR-V compiler and Godot). If empty, shader compilation was successful. diff --git a/doc/classes/RDShaderSource.xml b/doc/classes/RDShaderSource.xml index ddeae95e39..129567c9c0 100644 --- a/doc/classes/RDShaderSource.xml +++ b/doc/classes/RDShaderSource.xml @@ -1,8 +1,11 @@ + Shader source code (used by [RenderingDevice]). + Shader source code in text form. + See also [RDShaderFile]. [RDShaderSource] is only meant to be used with the [RenderingDevice] API. It should not be confused with Godot's own [Shader] resource, which is what Godot's various nodes use for high-level shader programming. @@ -11,6 +14,7 @@ + Returns source code for the specified shader [param stage]. Equivalent to getting one of [member source_compute], [member source_fragment], [member source_tesselation_control], [member source_tesselation_evaluation] or [member source_vertex]. @@ -18,21 +22,28 @@ + Sets [param source] code for the specified shader [param stage]. Equivalent to setting one of [member source_compute], [member source_fragment], [member source_tesselation_control], [member source_tesselation_evaluation] or [member source_vertex]. + The language the shader is written in. + Source code for the shader's compute stage. + Source code for the shader's fragment stage. + Source code for the shader's tessellation control stage. + Source code for the shader's tessellation evaluation stage. + Source code for the shader's vertex stage. diff --git a/doc/classes/RDTextureFormat.xml b/doc/classes/RDTextureFormat.xml index 3bfcd610a4..9005610a1c 100644 --- a/doc/classes/RDTextureFormat.xml +++ b/doc/classes/RDTextureFormat.xml @@ -1,8 +1,10 @@ + Texture format (used by [RenderingDevice]). + This object is used by [RenderingDevice]. @@ -22,22 +24,31 @@ + The number of layers in the texture. Only relevant for 2D texture arrays. + The texture's depth (in pixels). This is always [code]1[/code] for 2D textures. + The texture's pixel data format. + The texture's height (in pixels). + The number of mipmaps available in the texture. + The number of samples used when sampling the texture. + The texture type. + The texture's usage bits, which determine what can be done using the texture. + The texture's width (in pixels). diff --git a/doc/classes/RDTextureView.xml b/doc/classes/RDTextureView.xml index 6f7406d2aa..c9378a3019 100644 --- a/doc/classes/RDTextureView.xml +++ b/doc/classes/RDTextureView.xml @@ -1,21 +1,28 @@ + Texture view (used by [RenderingDevice]). + This object is used by [RenderingDevice]. + Optional override for the data format to return sampled values in. The default value of [constant RenderingDevice.DATA_FORMAT_MAX] does not override the format. + The channel to sample when sampling the alpha channel. + The channel to sample when sampling the blue color channel. + The channel to sample when sampling the green color channel. + The channel to sample when sampling the red color channel. diff --git a/doc/classes/RDUniform.xml b/doc/classes/RDUniform.xml index e4b7883f02..24701b48a1 100644 --- a/doc/classes/RDUniform.xml +++ b/doc/classes/RDUniform.xml @@ -1,8 +1,10 @@ + Shader uniform (used by [RenderingDevice]). + This object is used by [RenderingDevice]. @@ -26,8 +28,10 @@ + The uniform's binding. + The uniform's data type. diff --git a/doc/classes/RDVertexAttribute.xml b/doc/classes/RDVertexAttribute.xml index 747f1f93ba..f60063314f 100644 --- a/doc/classes/RDVertexAttribute.xml +++ b/doc/classes/RDVertexAttribute.xml @@ -1,8 +1,10 @@ + Vertex attribute (used by [RenderingDevice]). + This object is used by [RenderingDevice]. diff --git a/doc/classes/ReflectionProbe.xml b/doc/classes/ReflectionProbe.xml index 8532bbf491..67c5f0458d 100644 --- a/doc/classes/ReflectionProbe.xml +++ b/doc/classes/ReflectionProbe.xml @@ -15,13 +15,13 @@ - The custom ambient color to use within the [ReflectionProbe]'s [member size]. Only effective if [member ambient_mode] is [constant AMBIENT_COLOR]. + The custom ambient color to use within the [ReflectionProbe]'s box defined by its [member size]. Only effective if [member ambient_mode] is [constant AMBIENT_COLOR]. - The custom ambient color energy to use within the [ReflectionProbe]'s [member size]. Only effective if [member ambient_mode] is [constant AMBIENT_COLOR]. + The custom ambient color energy to use within the [ReflectionProbe]'s box defined by its [member size]. Only effective if [member ambient_mode] is [constant AMBIENT_COLOR]. - The ambient color to use within the [ReflectionProbe]'s [member size]. The ambient color will smoothly blend with other [ReflectionProbe]s and the rest of the scene (outside the [ReflectionProbe]'s [member size]). + The ambient color to use within the [ReflectionProbe]'s box defined by its [member size]. The ambient color will smoothly blend with other [ReflectionProbe]s and the rest of the scene (outside the [ReflectionProbe]'s box defined by its [member size]). If [code]true[/code], enables box projection. This makes reflections look more correct in rectangle-shaped rooms by offsetting the reflection center depending on the camera's location. @@ -41,7 +41,7 @@ The maximum distance away from the [ReflectionProbe] an object can be before it is culled. Decrease this to improve performance, especially when using the [constant UPDATE_ALWAYS] [member update_mode]. - [b]Note:[/b] The maximum reflection distance is always at least equal to the probe's extents. This means that decreasing [member max_distance] will not always cull objects from reflections, especially if the reflection probe's [member size] is already large. + [b]Note:[/b] The maximum reflection distance is always at least equal to the probe's extents. This means that decreasing [member max_distance] will not always cull objects from reflections, especially if the reflection probe's box defined by its [member size] is already large. The automatic LOD bias to use for meshes rendered within the [ReflectionProbe] (this is analog to [member Viewport.mesh_lod_threshold]). Higher values will use less detailed versions of meshes that have LOD variations generated. If set to [code]0.0[/code], automatic LOD is disabled. Increase [member mesh_lod_threshold] to improve performance at the cost of geometry detail, especially when using the [constant UPDATE_ALWAYS] [member update_mode]. @@ -66,13 +66,13 @@ Update the probe every frame. This provides better results for fast-moving dynamic objects (such as cars). However, it has a significant performance cost. Due to the cost, it's recommended to only use one ReflectionProbe with [constant UPDATE_ALWAYS] at most per scene. For all other use cases, use [constant UPDATE_ONCE]. - Do not apply any ambient lighting inside the [ReflectionProbe]'s [member size]. + Do not apply any ambient lighting inside the [ReflectionProbe]'s box defined by its [member size]. - Apply automatically-sourced environment lighting inside the [ReflectionProbe]'s [member size]. + Apply automatically-sourced environment lighting inside the [ReflectionProbe]'s box defined by its [member size]. - Apply custom ambient lighting inside the [ReflectionProbe]'s [member size]. See [member ambient_color] and [member ambient_color_energy]. + Apply custom ambient lighting inside the [ReflectionProbe]'s box defined by its [member size]. See [member ambient_color] and [member ambient_color_energy]. diff --git a/doc/classes/RenderingDevice.xml b/doc/classes/RenderingDevice.xml index ef53b6edd7..7b6ad6619c 100644 --- a/doc/classes/RenderingDevice.xml +++ b/doc/classes/RenderingDevice.xml @@ -4,13 +4,14 @@ Abstraction for working with modern low-level graphics APIs. - [RenderingDevice] is an abstraction for working with modern low-level graphics APIs such as Vulkan. - On startup, Godot creates a global [RenderingDevice] which can be retrieved using [method RenderingServer.get_rendering_device]. This global RenderingDevice performs drawing to the screen. - Internally, [RenderingDevice] is used in Godot to provide support for several modern low-level graphics APIs while reducing the amount of code duplication required. + [RenderingDevice] is an abstraction for working with modern low-level graphics APIs such as Vulkan. Compared to [RenderingServer] (which works with Godot's own rendering subsystems), [RenderingDevice] is much lower-level and allows working more directly with the underlying graphics APIs. [RenderingDevice] is used in Godot to provide support for several modern low-level graphics APIs while reducing the amount of code duplication required. [RenderingDevice] can also be used in your own projects to perform things that are not exposed by [RenderingServer] or high-level nodes, such as using compute shaders. + On startup, Godot creates a global [RenderingDevice] which can be retrieved using [method RenderingServer.get_rendering_device]. This global [RenderingDevice] performs drawing to the screen. [b]Local RenderingDevices:[/b] Using [method RenderingServer.create_local_rendering_device], you can create "secondary" rendering devices to perform drawing and GPU compute operations on separate threads. + [b]Note:[/b] [RenderingDevice] assumes intermediate knowledge of modern graphics APIs such as Vulkan, Direct3D 12, Metal or WebGPU. These graphics APIs are lower-level than OpenGL or Direct3D 11, requiring you to perform what was previously done by the graphics driver itself. If you have difficulty understanding the concepts used in this class, follow the [url=https://vulkan-tutorial.com/]Vulkan Tutorial[/url] or [url=https://vkguide.dev/]Vulkan Guide[/url]. It's recommended to have existing modern OpenGL or Direct3D 11 knowledge before attempting to learn a low-level graphics API. [b]Note:[/b] [RenderingDevice] is not available when running in headless mode or when using the Compatibility rendering method. + https://docs.godotengine.org/en/latest/tutorials/shaders/compute_shaders.html @@ -18,6 +19,7 @@ + Puts a memory barrier in place. This is used for synchronization to avoid data races. See also [method full_barrier], which may be useful for debugging. @@ -52,6 +54,7 @@ + Creates a timestamp marker with the specified [param name]. This is used for performance reporting with the [method get_captured_timestamp_cpu_time], [method get_captured_timestamp_gpu_time] and [method get_captured_timestamp_name] methods. @@ -64,6 +67,24 @@ + Starts a list of compute commands created with the [code]compute_*[/code] methods. The returned value should be passed to other [code]compute_list_*[/code] functions. + If [code]allow_draw_overlap[/code] is true, you may have one draw list running at the same time as one compute list. Multiple compute lists cannot be created at the same time; you must finish the previous compute list first using [method compute_list_end]. + A simple compute operation might look like this (code is not a complete example): + [codeblock] + var rd = RenderingDevice.new() + var compute_list = rd.compute_list_begin() + + rd.compute_list_bind_compute_pipeline(compute_list, compute_shader_dilate_pipeline) + rd.compute_list_bind_uniform_set(compute_list, compute_base_uniform_set, 0) + rd.compute_list_bind_uniform_set(compute_list, dilate_uniform_set, 1) + + for i in atlas_slices: + rd.compute_list_set_push_constant(compute_list, push_constant, push_constant.size()) + rd.compute_list_dispatch(compute_list, group_size.x, group_size.y, group_size.z) + # No barrier, let them run all together. + + rd.compute_list_end() + [/codeblock] @@ -88,12 +109,14 @@ + Submits the compute list for processing on the GPU. This is the compute equivalent to [method draw_list_draw]. + Finishes a list of compute commands created with the [code]compute_*[/code] methods. @@ -102,6 +125,7 @@ + Sets the push constant data to [param buffer] for the specified [param compute_list]. The shader determines how this binary data is used. The buffer's size in bytes must also be specified in [param size_bytes] (this can be obtained by calling the [method PackedByteArray.size] method on the passed [param buffer]). @@ -109,17 +133,22 @@ + Creates a new compute pipeline. It can be accessed with the RID that is returned. + Once finished with your RID, you will want to free the RID using the RenderingDevice's [method free_rid] method. + Returns [code]true[/code] if the compute pipeline specified by the [param compute_pieline] RID is valid, [code]false[/code] otherwise. + [b]Note:[/b] The [param compute_pieline] parameter should be named "compute_pipeline", but this typo was kept in the 4.0.x branch to preserve compatibility for C# and GDExtension. + Create a new local [RenderingDevice]. This is most useful for performing compute operations on the GPU independently from the rest of the engine. @@ -127,11 +156,14 @@ + Create a command buffer debug label region that can be displayed in third-party tools such as [url=https://renderdoc.org/]RenderDoc[/url]. All regions must be ended with a [method draw_command_end_label] call. When viewed from the linear series of submissions to a single queue, calls to [method draw_command_begin_label] and [method draw_command_end_label] must be matched and balanced. + The [code]VK_EXT_DEBUG_UTILS_EXTENSION_NAME[/code] Vulkan extension must be available and enabled for command buffer debug label region to work. See also [method draw_command_insert_label] and [method draw_command_end_label]. + Ends the command buffer debug label region started by a [method draw_command_begin_label] call. @@ -139,6 +171,7 @@ + Inserts a command buffer debug label region in the current command buffer. Unlike [method draw_command_begin_label], this region should not be ended with a [method draw_command_end_label] call. @@ -154,6 +187,27 @@ + 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]. + A simple drawing operation might look like this (code is not a complete example): + [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) + + # Draw opaque. + rd.draw_list_bind_render_pipeline(draw_list, raster_pipeline) + rd.draw_list_bind_uniform_set(draw_list, raster_base_uniform, 0) + rd.draw_list_set_push_constant(draw_list, raster_push_constant, raster_push_constant.size()) + rd.draw_list_draw(draw_list, false, 1, slice_triangle_count[i] * 3) + # Draw wire. + rd.draw_list_bind_render_pipeline(draw_list, raster_pipeline_wire) + rd.draw_list_bind_uniform_set(draw_list, raster_base_uniform, 0) + rd.draw_list_set_push_constant(draw_list, raster_push_constant, raster_push_constant.size()) + rd.draw_list_draw(draw_list, false, 1, slice_triangle_count[i] * 3) + + rd.draw_list_end() + [/codeblock] @@ -161,6 +215,8 @@ + High-level variant of [method draw_list_begin], with the parameters automtaically being adjusted for drawing onto the window specified by the [param screen] ID. + [b]Note:[/b] Cannot be used with local RenderingDevices, as these don't have a screen. If called on a local RenderingDevice, [method draw_list_begin_for_screen] returns [constant INVALID_ID]. @@ -177,6 +233,7 @@ + Variant of [method draw_list_begin] with support for multiple splits. The [param splits] parameter determines how many splits are created. @@ -184,6 +241,7 @@ + Binds [param index_array] to the specified [param draw_list]. @@ -191,6 +249,7 @@ + Binds [param render_pipeline] to the specified [param draw_list]. @@ -199,6 +258,7 @@ + Binds [param uniform_set] to the specified [param draw_list]. A [param set_index] must also be specified, which is an identifier starting from [code]0[/code] that must match the one expected by the draw list. @@ -206,12 +266,14 @@ + Binds [param vertex_array] to the specified [param draw_list]. + Removes and disables the scissor rectangle for the specified [param draw_list]. See also [method draw_list_enable_scissor]. @@ -221,6 +283,7 @@ + Submits [param draw_list] for rendering on the GPU. This is the raster equivalent to [method compute_list_dispatch]. @@ -228,12 +291,15 @@ + Creates a scissor rectangle and enables it for the specified [param draw_list]. Scissor rectangles are used for clipping by discarding fragments that fall outside a specified rectangular portion of the screen. See also [method draw_list_disable_scissor]. + [b]Note:[/b] The specified [param rect] is automatically intersected with the screen's dimensions, which means it cannot exceed the screen's dimensions. + Finishes a list of raster drawing commands created with the [code]draw_*[/code] methods. @@ -241,7 +307,7 @@ - Sets blend constants for draw list, blend constants are used only if the graphics pipeline is created with [constant DYNAMIC_STATE_BLEND_CONSTANTS] flag set. + Sets blend constants for the specified [param draw_list] to [param color]. Blend constants are used only if the graphics pipeline is created with [constant DYNAMIC_STATE_BLEND_CONSTANTS] flag set. @@ -250,17 +316,20 @@ + Sets the push constant data to [param buffer] for the specified [param draw_list]. The shader determines how this binary data is used. The buffer's size in bytes must also be specified in [param size_bytes] (this can be obtained by calling the [method PackedByteArray.size] method on the passed [param buffer]). + Switches to the next draw pass and returns the split's ID. Equivalent to [method draw_list_switch_to_next_pass_split] with [code]splits[/code] set to [code]1[/code]. + Switches to the next draw pass, with the number of splits allocated specified in [param splits]. The return value is an array containing the ID of each split. For single-split usage, see [method draw_list_switch_to_next_pass]. @@ -269,6 +338,8 @@ + Creates a new framebuffer. It can be accessed with the RID that is returned. + Once finished with your RID, you will want to free the RID using the RenderingDevice's [method free_rid] method. @@ -277,6 +348,8 @@ + Creates a new empty framebuffer. It can be accessed with the RID that is returned. + Once finished with your RID, you will want to free the RID using the RenderingDevice's [method free_rid] method. @@ -286,6 +359,8 @@ + Creates a new multipass framebuffer. It can be accessed with the RID that is returned. + Once finished with your RID, you will want to free the RID using the RenderingDevice's [method free_rid] method. @@ -293,12 +368,15 @@ + Creates a new framebuffer format with the specified [param attachments] and [param view_count]. Returns the new framebuffer's unique framebuffer format ID. + If [code]view_count[/code] is greater than or equal to [code]2[/code], enables multiview which is used for VR rendering. This requires support for the Vulkan multiview extension. + Creates a new empty framebuffer format with the specified number of [param samples] and returns its ID. @@ -307,6 +385,7 @@ + Creates a multipass framebuffer format with the specified [param attachments], [param passes] and [param view_count] and returns its ID. If [code]view_count[/code] is greater than or equal to [code]2[/code], enables multiview which is used for VR rendering. This requires support for the Vulkan multiview extension. @@ -314,72 +393,85 @@ + Returns the number of texture samples used for the given framebuffer [param format] ID (returned by [method framebuffer_get_format]). + Returns the format ID of the framebuffer specified by the [param framebuffer] RID. This ID is guaranteed to be unique for the same formats and does not need to be freed. + Returns [code]true[/code] if the framebuffer specified by the [param framebuffer] RID is valid, [code]false[/code] otherwise. + Tries to free an object in the RenderingDevice. To avoid memory leaks, this should be called after using an object as memory management does not occur automatically when using RenderingDevice directly. + Puts a [i]full[/i] memory barrier in place. This is a memory [method barrier] with all flags enabled. [method full_barrier] it should only be used for debugging as it can severely impact performance. + Returns the timestamp in CPU time for the rendering step specified by [param index] (in microseconds since the engine started). See also [method get_captured_timestamp_gpu_time] and [method capture_timestamp]. + Returns the timestamp in GPU time for the rendering step specified by [param index] (in microseconds since the engine started). See also [method get_captured_timestamp_cpu_time] and [method capture_timestamp]. + Returns the timestamp's name for the rendering step specified by [param index]. See also [method capture_timestamp]. + Returns the total number of timestamps (rendering steps) available for profiling. + Returns the index of the last frame rendered that has rendering timestamps available for querying. + Returns the name of the video adapter (e.g. "GeForce GTX 1080/PCIe/SSE2"). Equivalent to [method RenderingServer.get_video_adapter_name]. See also [method get_device_vendor_name]. + Returns the universally unique identifier for the pipeline cache. This is used to cache shader files on disk, which avoids shader recompilations on subsequent engine runs. This UUID varies depending on the graphics card model, but also the driver version. Therefore, updating graphics drivers will invalidate the shader cache. + Returns the vendor of the video adapter (e.g. "NVIDIA Corporation"). Equivalent to [method RenderingServer.get_video_adapter_vendor]. See also [method get_device_name]. @@ -388,17 +480,20 @@ + Returns the unique identifier of the driver [param resource] for the specified [param rid]. Some driver resource types ignore the specified [param rid] (see [enum DriverResource] descriptions). [param index] is always ignored but must be specified anyway. + Returns the frame count kept by the graphics API. Higher values result in higher input lag, but with more consistent throughput. For the main [RenderingDevice], frames are cycled (usually 3 with triple-buffered V-Sync enabled). However, local [RenderingDevice]s only have 1 frame. + Returns the memory usage in bytes corresponding to the given [param type]. When using Vulkan, these statistics are calculated by [url=https://github.com/GPUOpen-LibrariesAndSDKs/VulkanMemoryAllocator]Vulkan Memory Allocator[/url]. @@ -407,6 +502,8 @@ + Creates a new index array. It can be accessed with the RID that is returned. + Once finished with your RID, you will want to free the RID using the RenderingDevice's [method free_rid] method. @@ -416,12 +513,16 @@ + Creates a new index buffer. It can be accessed with the RID that is returned. + Once finished with your RID, you will want to free the RID using the RenderingDevice's [method free_rid] method. + Returns the value of the specified [param limit]. This limit varies depending on the current graphics hardware (and sometimes the driver version). If the given limit is exceeded, rendering errors will occur. + Limits for various graphics hardware can be found in the [url=https://vulkan.gpuinfo.org/]Vulkan Hardware Database[/url]. @@ -438,18 +539,23 @@ + Creates a new render pipeline. It can be accessed with the RID that is returned. + Once finished with your RID, you will want to free the RID using the RenderingDevice's [method free_rid] method. + Returns [code]true[/code] if the render pipeline specified by the [param render_pipeline] RID is valid, [code]false[/code] otherwise. + Creates a new sampler. It can be accessed with the RID that is returned. + Once finished with your RID, you will want to free the RID using the RenderingDevice's [method free_rid] method. @@ -463,18 +569,24 @@ + Returns the screen's framebuffer format. + [b]Note:[/b] Only the main [RenderingDevice] returned by [method RenderingServer.get_rendering_device] has a format. If called on a local [RenderingDevice], this method prints an error and returns [constant INVALID_ID]. + Returns the window height matching the graphics API context for the given window ID (in pixels). Despite the parameter being named [param screen], this returns the [i]window[/i] size. See also [method screen_get_width]. + [b]Note:[/b] Only the main [RenderingDevice] returned by [method RenderingServer.get_rendering_device] has a height. If called on a local [RenderingDevice], this method prints an error and returns [constant INVALID_ID]. + Returns the window width matching the graphics API context for the given window ID (in pixels). Despite the parameter being named [param screen], this returns the [i]window[/i] size. See also [method screen_get_height]. + [b]Note:[/b] Only the main [RenderingDevice] returned by [method RenderingServer.get_rendering_device] has a width. If called on a local [RenderingDevice], this method prints an error and returns [constant INVALID_ID]. @@ -482,6 +594,9 @@ + Sets the resource name for [param id] to [param name]. This is used for debugging with third-party tools such as [url=https://renderdoc.org/]RenderDoc[/url]. + The following types of resources can be named: texture, sampler, vertex buffer, index buffer, uniform buffer, texture buffer, storage buffer, uniform set buffer, shader, render pipeline and compute pipeline. Framebuffers cannot be named. Attempting to name an incompatible resource type will print an error. + [b]Note:[/b] Resource names are only set when the engine runs in verbose mode ([method OS.is_stdout_verbose] = [code]true[/code]), or when using an engine build compiled with the [code]dev_mode=yes[/code] SCons option. The graphics driver must also support the [code]VK_EXT_DEBUG_UTILS_EXTENSION_NAME[/code] Vulkan extension for named resources to work. @@ -489,6 +604,8 @@ + Compiles a binary shader from [param spirv_data] and returns the compiled binary data as a [PackedByteArray]. This compiled shader is specific to the GPU model and driver version used; it will not work on different GPU models or even different driver versions. See also [method shader_compile_spirv_from_source]. + [param name] is an optional human-readable name that can be given to the compiled shader for organizational purposes. @@ -496,12 +613,16 @@ + Compiles a SPIR-V from the shader source code in [param shader_source] and returns the SPIR-V as a [RDShaderSPIRV]. This intermediate language shader is portable across different GPU models and driver versions, but cannot be run directly by GPUs until compiled into a binary shader using [method shader_compile_binary_from_spirv]. + If [param allow_cache] is [code]true[/code], make use of the shader cache generated by Godot. This avoids a potentially lengthy shader compilation step if the shader is already in cache. If [param allow_cache] is [code]false[/code], Godot's shader cache is ignored and the shader will always be recompiled. + Creates a new shader instance from a binary compiled shader. It can be accessed with the RID that is returned. + Once finished with your RID, you will want to free the RID using the RenderingDevice's [method free_rid] method. See also [method shader_compile_binary_from_spirv] and [method shader_create_from_spirv]. @@ -509,6 +630,8 @@ + Creates a new shader instance from SPIR-V intermediate code. It can be accessed with the RID that is returned. + Once finished with your RID, you will want to free the RID using the RenderingDevice's [method free_rid] method. See also [method shader_compile_spirv_from_source] and [method shader_create_from_bytecode]. @@ -523,16 +646,23 @@ + Creates a [url=https://vkguide.dev/docs/chapter-4/storage_buffers/]storage buffer[/url] with the specified [param data] and [param usage]. It can be accessed with the RID that is returned. + Once finished with your RID, you will want to free the RID using the RenderingDevice's [method free_rid] method. + Pushes the frame setup and draw command buffers then marks the local device as currently processing (which allows calling [method sync]). + [b]Note:[/b] Only available in local RenderingDevices. + Forces a synchronization between the CPU and GPU, which may be required in certain cases. Only call this when needed, as CPU-GPU synchronization has a performance cost. + [b]Note:[/b] Only available in local RenderingDevices. + [b]Note:[/b] [method sync] can only be called after a [method submit]. @@ -541,6 +671,8 @@ + Creates a new texture buffer. It can be accessed with the RID that is returned. + Once finished with your RID, you will want to free the RID using the RenderingDevice's [method free_rid] method. @@ -553,6 +685,8 @@ + Clears the specified [param texture] by replacing all of its pixels with the specified [param color]. [param base_mipmap] and [param mipmap_count] determine which mipmaps of the texture are affected by this clear operation, while [param base_layer] and [param layer_count] determine which layers of a 3D texture (or texture array) are affected by this clear operation. For 2D textures (which only have one layer by design), [param base_layer] and [param layer_count] must both be [code]0[/code]. + [b]Note:[/b] [param texture] can't be cleared while a draw list that uses it as part of a framebuffer is being created. Ensure the draw list is finalized (and that the color/depth texture using it is not set to [constant FINAL_ACTION_CONTINUE]) to clear this texture. @@ -568,6 +702,12 @@ + Copies the [param from_texture] to [param to_texture] with the specified [param from_pos], [param to_pos] and [param size] coordinates. The Z axis of the [param from_pos], [param to_pos] and [param size] must be [code]0[/code] for 2-dimensional textures. Source and destination mipmaps/layers must also be specified, with these parameters being [code]0[/code] for textures without mipmaps or single-layer textures. Returns [constant @GlobalScope.OK] if the texture copy was successful or [constant @GlobalScope.ERR_INVALID_PARAMETER] otherwise. + [b]Note:[/b] [param from_texture] texture can't be copied while a draw list that uses it as part of a framebuffer is being created. Ensure the draw list is finalized (and that the color/depth texture using it is not set to [constant FINAL_ACTION_CONTINUE]) to copy this texture. + [b]Note:[/b] [param from_texture] texture requires the [constant TEXTURE_USAGE_CAN_COPY_FROM_BIT] to be retrieved. + [b]Note:[/b] [param to_texture] can't be copied while a draw list that uses it as part of a framebuffer is being created. Ensure the draw list is finalized (and that the color/depth texture using it is not set to [constant FINAL_ACTION_CONTINUE]) to copy this texture. + [b]Note:[/b] [param to_texture] requires the [constant TEXTURE_USAGE_CAN_COPY_TO_BIT] to be retrieved. + [b]Note:[/b] [param from_texture] and [param to_texture] must be of the same type (color or depth). @@ -576,6 +716,9 @@ + Creates a new texture. It can be accessed with the RID that is returned. + Once finished with your RID, you will want to free the RID using the RenderingDevice's [method free_rid] method. + [b]Note:[/b] Not to be confused with [method RenderingServer.texture_2d_create], which creates the Godot-specific [Texture2D] resource as opposed to the graphics API's own texture type. @@ -583,6 +726,7 @@ + Creates a shared texture using the specified [param view] and the texture information from [param with_texture]. @@ -594,6 +738,9 @@ + Creates a shared texture using the specified [param view] and the texture information from [param with_texture]'s [param layer] and [param mipmap]. The number of included mipmaps from the original texture can be controlled using the [param mipmaps] parameter. Only relevant for textures with multiple layers, such as 3D textures, texture arrays and cubemaps. For single-layer textures, use [method texture_create_shared] + For 2D textures (which only have one layer), [param layer] must be [code]0[/code]. + [b]Note:[/b] Layer slicing is only supported for 2D texture arrays, not 3D textures or cubemaps. @@ -601,6 +748,9 @@ + Retruns the [param texture] data for the specified [param layer] as raw binary data. For 2D textures (which only have one layer), [param layer] must be [code]0[/code]. + [b]Note:[/b] [param texture] can't be retrieved while a draw list that uses it as part of a framebuffer is being created. Ensure the draw list is finalized (and that the color/depth texture using it is not set to [constant FINAL_ACTION_CONTINUE]) to retrieve this texture. Otherwise, an error is printed and a empty [PackedByteArray] is returned. + [b]Note:[/b] [param texture] requires the [constant TEXTURE_USAGE_CAN_COPY_FROM_BIT] to be retrieved. Otherwise, an error is printed and a empty [PackedByteArray] is returned. @@ -608,18 +758,21 @@ + Returns [code]true[/code] if the specified [param format] is supported for the given [param usage_flags], [code]false[/code] otherwise. + Returns [code]true[/code] if the [param texture] is shared, [code]false[/code] otherwise. See [RDTextureView]. + Returns [code]true[/code] if the [param texture] is valid, [code]false[/code] otherwise. @@ -628,6 +781,14 @@ + Resolves the [param from_texture] texture onto [param to_texture] with multisample antialiasing enabled. This must be used when rendering a framebuffer for MSAA to work. Returns [constant @GlobalScope.OK] if successful, [constant @GlobalScope.ERR_INVALID_PARAMETER] otherwise. + [b]Note:[/b] [param from_texture] and [param to_texture] textures must have the same dimension, format and type (color or depth). + [b]Note:[/b] [param from_texture] can't be copied while a draw list that uses it as part of a framebuffer is being created. Ensure the draw list is finalized (and that the color/depth texture using it is not set to [constant FINAL_ACTION_CONTINUE]) to resolve this texture. + [b]Note:[/b] [param from_texture] requires the [constant TEXTURE_USAGE_CAN_COPY_FROM_BIT] to be retrieved. + [b]Note:[/b] [param from_texture] must be multisampled and must also be 2D (or a slice of a 3D/cubemap texture). + [b]Note:[/b] [param to_texture] can't be copied while a draw list that uses it as part of a framebuffer is being created. Ensure the draw list is finalized (and that the color/depth texture using it is not set to [constant FINAL_ACTION_CONTINUE]) to resolve this texture. + [b]Note:[/b] [param to_texture] texture requires the [constant TEXTURE_USAGE_CAN_COPY_TO_BIT] to be retrieved. + [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). @@ -637,6 +798,10 @@ + Updates texture data with new data, replacing the previous data in place. The updated texture data must have the same dimensions and format. For 2D textures (which only have one layer), [param layer] must be [code]0[/code]. Returns [constant @GlobalScope.OK] if the update was successful, [constant @GlobalScope.ERR_INVALID_PARAMETER] otherwise. + [b]Note:[/b] Updating textures is forbidden during creation of a draw or compute list. + [b]Note:[/b] The existing [param texture] can't be updated while a draw list that uses it as part of a framebuffer is being created. Ensure the draw list is finalized (and that the color/depth texture using it is not set to [constant FINAL_ACTION_CONTINUE]) to update this texture. + [b]Note:[/b] The existing [param texture] requires the [constant TEXTURE_USAGE_CAN_UPDATE_BIT] to be updatable. @@ -644,6 +809,8 @@ + It can be accessed with the RID that is returned. + Once finished with your RID, you will want to free the RID using the RenderingDevice's [method free_rid] method. @@ -652,6 +819,8 @@ + It can be accessed with the RID that is returned. + Once finished with your RID, you will want to free the RID using the RenderingDevice's [method free_rid] method. @@ -676,12 +845,15 @@ + It can be accessed with the RID that is returned. + Once finished with your RID, you will want to free the RID using the RenderingDevice's [method free_rid] method. + Creates a new vertex format with the specified [param vertex_descriptions]. Returns a unique vertex format ID corresponding to the newly created vertex format. @@ -705,478 +877,716 @@ Represents the size of the [enum DeviceType] enum. + Vulkan device driver resource. This is a "global" resource and ignores the RID passed in + Physical device (graphics card) driver resource. + Vulkan instance driver resource. + Vulkan queue driver resource. + Vulkan queue family index driver resource. + Vulkan image driver resource. + Vulkan image view driver resource. + Vulkan image native texture format driver resource. + Vulkan sampler driver resource. + Vulkan [url=https://vkguide.dev/docs/chapter-4/descriptors/]descriptor set[/url] driver resource. + Vulkan buffer driver resource. + Vulkan compute pipeline driver resource. + Vulkan render pipeline driver resource. + 4-bit-per-channel red/green channel data format, packed into 8 bits. Values are in the [code][0.0, 1.0][/code] range. + [b]Note:[/b] More information on all data formats can be found on the [url=https://registry.khronos.org/vulkan/specs/1.1/html/vkspec.html#_identification_of_formats]Identification of formats[/url] section of the Vulkan specification, as well as the [url=https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VkFormat.html]VkFormat[/url] enum. + 4-bit-per-channel red/green/blue/alpha channel data format, packed into 16 bits. Values are in the [code][0.0, 1.0][/code] range. + 4-bit-per-channel blue/green/red/alpha channel data format, packed into 16 bits. Values are in the [code][0.0, 1.0][/code] range. + Red/green/blue channel data format with 5 bits of red, 6 bits of green and 5 bits of blue, packed into 16 bits. Values are in the [code][0.0, 1.0][/code] range. + Blue/green/red channel data format with 5 bits of blue, 6 bits of green and 5 bits of red, packed into 16 bits. Values are in the [code][0.0, 1.0][/code] range. + Red/green/blue/alpha channel data format with 5 bits of red, 6 bits of green, 5 bits of blue and 1 bit of alpha, packed into 16 bits. Values are in the [code][0.0, 1.0][/code] range. + Blue/green/red/alpha channel data format with 5 bits of blue, 6 bits of green, 5 bits of red and 1 bit of alpha, packed into 16 bits. Values are in the [code][0.0, 1.0][/code] range. + Alpha/red/green/blue channel data format with 1 bit of alpha, 5 bits of red, 6 bits of green and 5 bits of blue, packed into 16 bits. Values are in the [code][0.0, 1.0][/code] range. + 8-bit-per-channel unsigned floating-point red channel data format with normalized value. Values are in the [code][0.0, 1.0][/code] range. + 8-bit-per-channel signed floating-point red channel data format with normalized value. Values are in the [code][-1.0, 1.0][/code] range. + 8-bit-per-channel unsigned floating-point red channel data format with scaled value (value is converted from integer to float). Values are in the [code][0.0, 255.0][/code] range. + 8-bit-per-channel signed floating-point red channel data format with scaled value (value is converted from integer to float). Values are in the [code][-127.0, 127.0][/code] range. + 8-bit-per-channel unsigned integer red channel data format. Values are in the [code][0, 255][/code] range. + 8-bit-per-channel signed integer red channel data format. Values are in the [code][-127, 127][/code] range. + 8-bit-per-channel unsigned floating-point red channel data format with normalized value and non-linear sRGB encoding. Values are in the [code][0.0, 1.0][/code] range. + 8-bit-per-channel unsigned floating-point red/green channel data format with normalized value. Values are in the [code][0.0, 1.0][/code] range. + 8-bit-per-channel signed floating-point red/green channel data format with normalized value. Values are in the [code][-1.0, 1.0][/code] range. + 8-bit-per-channel unsigned floating-point red/green channel data format with scaled value (value is converted from integer to float). Values are in the [code][0.0, 255.0][/code] range. + 8-bit-per-channel signed floating-point red/green channel data format with scaled value (value is converted from integer to float). Values are in the [code][-127.0, 127.0][/code] range. + 8-bit-per-channel unsigned integer red/green channel data format. Values are in the [code][0, 255][/code] range. + 8-bit-per-channel signed integer red/green channel data format. Values are in the [code][-127, 127][/code] range. + 8-bit-per-channel unsigned floating-point red/green channel data format with normalized value and non-linear sRGB encoding. Values are in the [code][0.0, 1.0][/code] range. + 8-bit-per-channel unsigned floating-point red/green/blue channel data format with normalized value. Values are in the [code][0.0, 1.0][/code] range. + 8-bit-per-channel signed floating-point red/green/blue channel data format with normalized value. Values are in the [code][-1.0, 1.0][/code] range. + 8-bit-per-channel unsigned floating-point red/green/blue channel data format with scaled value (value is converted from integer to float). Values are in the [code][0.0, 255.0][/code] range. + 8-bit-per-channel signed floating-point red/green/blue channel data format with scaled value (value is converted from integer to float). Values are in the [code][-127.0, 127.0][/code] range. + 8-bit-per-channel unsigned integer red/green/blue channel data format. Values are in the [code][0, 255][/code] range. + 8-bit-per-channel signed integer red/green/blue channel data format. Values are in the [code][-127, 127][/code] range. + 8-bit-per-channel unsigned floating-point red/green/blue/blue channel data format with normalized value and non-linear sRGB encoding. Values are in the [code][0.0, 1.0][/code] range. + 8-bit-per-channel unsigned floating-point blue/green/red channel data format with normalized value. Values are in the [code][0.0, 1.0][/code] range. + 8-bit-per-channel signed floating-point blue/green/red channel data format with normalized value. Values are in the [code][-1.0, 1.0][/code] range. + 8-bit-per-channel unsigned floating-point blue/green/red channel data format with scaled value (value is converted from integer to float). Values are in the [code][0.0, 255.0][/code] range. + 8-bit-per-channel signed floating-point blue/green/red channel data format with scaled value (value is converted from integer to float). Values are in the [code][-127.0, 127.0][/code] range. + 8-bit-per-channel unsigned integer blue/green/red channel data format. Values are in the [code][0, 255][/code] range. + 8-bit-per-channel signed integer blue/green/red channel data format. Values are in the [code][-127, 127][/code] range. + 8-bit-per-channel unsigned floating-point blue/green/red data format with normalized value and non-linear sRGB encoding. Values are in the [code][0.0, 1.0][/code] range. + 8-bit-per-channel unsigned floating-point red/green/blue/alpha channel data format with normalized value. Values are in the [code][0.0, 1.0][/code] range. + 8-bit-per-channel signed floating-point red/green/blue/alpha channel data format with normalized value. Values are in the [code][-1.0, 1.0][/code] range. + 8-bit-per-channel unsigned floating-point red/green/blue/alpha channel data format with scaled value (value is converted from integer to float). Values are in the [code][0.0, 255.0][/code] range. + 8-bit-per-channel signed floating-point red/green/blue/alpha channel data format with scaled value (value is converted from integer to float). Values are in the [code][-127.0, 127.0][/code] range. + 8-bit-per-channel unsigned integer red/green/blue/alpha channel data format. Values are in the [code][0, 255][/code] range. + 8-bit-per-channel signed integer red/green/blue/alpha channel data format. Values are in the [code][-127, 127][/code] range. + 8-bit-per-channel unsigned floating-point red/green/blue/alpha channel data format with normalized value and non-linear sRGB encoding. Values are in the [code][0.0, 1.0][/code] range. + 8-bit-per-channel unsigned floating-point blue/green/red/alpha channel data format with normalized value. Values are in the [code][0.0, 1.0][/code] range. + 8-bit-per-channel signed floating-point blue/green/red/alpha channel data format with normalized value. Values are in the [code][-1.0, 1.0][/code] range. + 8-bit-per-channel unsigned floating-point blue/green/red/alpha channel data format with scaled value (value is converted from integer to float). Values are in the [code][0.0, 255.0][/code] range. + 8-bit-per-channel signed floating-point blue/green/red/alpha channel data format with scaled value (value is converted from integer to float). Values are in the [code][-127.0, 127.0][/code] range. + 8-bit-per-channel unsigned integer blue/green/red/alpha channel data format. Values are in the [code][0, 255][/code] range. + 8-bit-per-channel signed integer blue/green/red/alpha channel data format. Values are in the [code][-127, 127][/code] range. + 8-bit-per-channel unsigned floating-point blue/green/red/alpha channel data format with normalized value and non-linear sRGB encoding. Values are in the [code][0.0, 1.0][/code] range. + 8-bit-per-channel unsigned floating-point alpha/red/green/blue channel data format with normalized value, packed in 32 bits. Values are in the [code][0.0, 1.0][/code] range. + 8-bit-per-channel signed floating-point alpha/red/green/blue channel data format with normalized value, packed in 32 bits. Values are in the [code][-1.0, 1.0][/code] range. + 8-bit-per-channel unsigned floating-point alpha/red/green/blue channel data format with scaled value (value is converted from integer to float), packed in 32 bits. Values are in the [code][0.0, 255.0][/code] range. + 8-bit-per-channel signed floating-point alpha/red/green/blue channel data format with scaled value (value is converted from integer to float), packed in 32 bits. Values are in the [code][-127.0, 127.0][/code] range. + 8-bit-per-channel unsigned integer alpha/red/green/blue channel data format, packed in 32 bits. Values are in the [code][0, 255][/code] range. + 8-bit-per-channel signed integer alpha/red/green/blue channel data format, packed in 32 bits. Values are in the [code][-127, 127][/code] range. + 8-bit-per-channel unsigned floating-point alpha/red/green/blue channel data format with normalized value and non-linear sRGB encoding, packed in 32 bits. Values are in the [code][0.0, 1.0][/code] range. + Unsigned floating-point alpha/red/green/blue channel data format with normalized value, packed in 32 bits. Format contains 2 bits of alpha, 10 bits of red, 10 bits of green and 10 bits of blue. Values are in the [code][0.0, 1.0][/code] range. + Signed floating-point alpha/red/green/blue channel data format with normalized value, packed in 32 bits. Format contains 2 bits of alpha, 10 bits of red, 10 bits of green and 10 bits of blue. Values are in the [code][-1.0, 1.0][/code] range. + Unsigned floating-point alpha/red/green/blue channel data format with normalized value, packed in 32 bits. Format contains 2 bits of alpha, 10 bits of red, 10 bits of green and 10 bits of blue. Values are in the [code][0.0, 1023.0][/code] range for red/green/blue and [code][0.0, 3.0][/code] for alpha. + Signed floating-point alpha/red/green/blue channel data format with normalized value, packed in 32 bits. Format contains 2 bits of alpha, 10 bits of red, 10 bits of green and 10 bits of blue. Values are in the [code][-511.0, 511.0][/code] range for red/green/blue and [code][-1.0, 1.0][/code] for alpha. + Unsigned integer alpha/red/green/blue channel data format with normalized value, packed in 32 bits. Format contains 2 bits of alpha, 10 bits of red, 10 bits of green and 10 bits of blue. Values are in the [code][0, 1023][/code] range for red/green/blue and [code][0, 3][/code] for alpha. + Signed integer alpha/red/green/blue channel data format with normalized value, packed in 32 bits. Format contains 2 bits of alpha, 10 bits of red, 10 bits of green and 10 bits of blue. Values are in the [code][-511, 511][/code] range for red/green/blue and [code][-1, 1][/code] for alpha. + Unsigned floating-point alpha/blue/green/red channel data format with normalized value, packed in 32 bits. Format contains 2 bits of alpha, 10 bits of blue, 10 bits of green and 10 bits of red. Values are in the [code][0.0, 1.0][/code] range. + Signed floating-point alpha/blue/green/red channel data format with normalized value, packed in 32 bits. Format contains 2 bits of alpha, 10 bits of blue, 10 bits of green and 10 bits of red. Values are in the [code][-1.0, 1.0][/code] range. + Unsigned floating-point alpha/blue/green/red channel data format with normalized value, packed in 32 bits. Format contains 2 bits of alpha, 10 bits of blue, 10 bits of green and 10 bits of red. Values are in the [code][0.0, 1023.0][/code] range for blue/green/red and [code][0.0, 3.0][/code] for alpha. + Signed floating-point alpha/blue/green/red channel data format with normalized value, packed in 32 bits. Format contains 2 bits of alpha, 10 bits of blue, 10 bits of green and 10 bits of red. Values are in the [code][-511.0, 511.0][/code] range for blue/green/red and [code][-1.0, 1.0][/code] for alpha. + Unsigned integer alpha/blue/green/red channel data format with normalized value, packed in 32 bits. Format contains 2 bits of alpha, 10 bits of blue, 10 bits of green and 10 bits of red. Values are in the [code][0, 1023][/code] range for blue/green/red and [code][0, 3][/code] for alpha. + Signed integer alpha/blue/green/red channel data format with normalized value, packed in 32 bits. Format contains 2 bits of alpha, 10 bits of blue, 10 bits of green and 10 bits of red. Values are in the [code][-511, 511][/code] range for blue/green/red and [code][-1, 1][/code] for alpha. + 16-bit-per-channel unsigned floating-point red channel data format with normalized value. Values are in the [code][0.0, 1.0][/code] range. + 16-bit-per-channel signed floating-point red channel data format with normalized value. Values are in the [code][-1.0, 1.0][/code] range. + 16-bit-per-channel unsigned floating-point red channel data format with scaled value (value is converted from integer to float). Values are in the [code][0.0, 65535.0][/code] range. + 16-bit-per-channel signed floating-point red channel data format with scaled value (value is converted from integer to float). Values are in the [code][-32767.0, 32767.0][/code] range. + 16-bit-per-channel unsigned integer red channel data format. Values are in the [code][0.0, 65535][/code] range. + 16-bit-per-channel signed integer red channel data format. Values are in the [code][-32767, 32767][/code] range. + 16-bit-per-channel signed floating-point red channel data format with the value stored as-is. + 16-bit-per-channel unsigned floating-point red/green channel data format with normalized value. Values are in the [code][0.0, 1.0][/code] range. + 16-bit-per-channel signed floating-point red/green channel data format with normalized value. Values are in the [code][-1.0, 1.0][/code] range. + 16-bit-per-channel unsigned floating-point red/green channel data format with scaled value (value is converted from integer to float). Values are in the [code][0.0, 65535.0][/code] range. + 16-bit-per-channel signed floating-point red/green channel data format with scaled value (value is converted from integer to float). Values are in the [code][-32767.0, 32767.0][/code] range. + 16-bit-per-channel unsigned integer red/green channel data format. Values are in the [code][0.0, 65535][/code] range. + 16-bit-per-channel signed integer red/green channel data format. Values are in the [code][-32767, 32767][/code] range. + 16-bit-per-channel signed floating-point red/green channel data format with the value stored as-is. + 16-bit-per-channel unsigned floating-point red/green/blue channel data format with normalized value. Values are in the [code][0.0, 1.0][/code] range. + 16-bit-per-channel signed floating-point red/green/blue channel data format with normalized value. Values are in the [code][-1.0, 1.0][/code] range. + 16-bit-per-channel unsigned floating-point red/green/blue channel data format with scaled value (value is converted from integer to float). Values are in the [code][0.0, 65535.0][/code] range. + 16-bit-per-channel signed floating-point red/green/blue channel data format with scaled value (value is converted from integer to float). Values are in the [code][-32767.0, 32767.0][/code] range. + 16-bit-per-channel unsigned integer red/green/blue channel data format. Values are in the [code][0.0, 65535][/code] range. + 16-bit-per-channel signed integer red/green/blue channel data format. Values are in the [code][-32767, 32767][/code] range. + 16-bit-per-channel signed floating-point red/green/blue channel data format with the value stored as-is. + 16-bit-per-channel unsigned floating-point red/green/blue/alpha channel data format with normalized value. Values are in the [code][0.0, 1.0][/code] range. + 16-bit-per-channel signed floating-point red/green/blue/alpha channel data format with normalized value. Values are in the [code][-1.0, 1.0][/code] range. + 16-bit-per-channel unsigned floating-point red/green/blue/alpha channel data format with scaled value (value is converted from integer to float). Values are in the [code][0.0, 65535.0][/code] range. + 16-bit-per-channel signed floating-point red/green/blue/alpha channel data format with scaled value (value is converted from integer to float). Values are in the [code][-32767.0, 32767.0][/code] range. + 16-bit-per-channel unsigned integer red/green/blue/alpha channel data format. Values are in the [code][0.0, 65535][/code] range. + 16-bit-per-channel signed integer red/green/blue/alpha channel data format. Values are in the [code][-32767, 32767][/code] range. + 16-bit-per-channel signed floating-point red/green/blue/alpha channel data format with the value stored as-is. + 32-bit-per-channel unsigned integer red channel data format. Values are in the [code][0, 2^32 - 1][/code] range. + 32-bit-per-channel signed integer red channel data format. Values are in the [code][2^31 + 1, 2^31 - 1][/code] range. + 32-bit-per-channel signed floating-point red channel data format with the value stored as-is. + 32-bit-per-channel unsigned integer red/green channel data format. Values are in the [code][0, 2^32 - 1][/code] range. + 32-bit-per-channel signed integer red/green channel data format. Values are in the [code][2^31 + 1, 2^31 - 1][/code] range. + 32-bit-per-channel signed floating-point red/green channel data format with the value stored as-is. + 32-bit-per-channel unsigned integer red/green/blue channel data format. Values are in the [code][0, 2^32 - 1][/code] range. + 32-bit-per-channel signed integer red/green/blue channel data format. Values are in the [code][2^31 + 1, 2^31 - 1][/code] range. + 32-bit-per-channel signed floating-point red/green/blue channel data format with the value stored as-is. + 32-bit-per-channel unsigned integer red/green/blue/alpha channel data format. Values are in the [code][0, 2^32 - 1][/code] range. + 32-bit-per-channel signed integer red/green/blue/alpha channel data format. Values are in the [code][2^31 + 1, 2^31 - 1][/code] range. + 32-bit-per-channel signed floating-point red/green/blue/alpha channel data format with the value stored as-is. + 64-bit-per-channel unsigned integer red channel data format. Values are in the [code][0, 2^64 - 1][/code] range. + 64-bit-per-channel signed integer red channel data format. Values are in the [code][2^63 + 1, 2^63 - 1][/code] range. + 64-bit-per-channel signed floating-point red channel data format with the value stored as-is. + 64-bit-per-channel unsigned integer red/green channel data format. Values are in the [code][0, 2^64 - 1][/code] range. + 64-bit-per-channel signed integer red/green channel data format. Values are in the [code][2^63 + 1, 2^63 - 1][/code] range. + 64-bit-per-channel signed floating-point red/green channel data format with the value stored as-is. + 64-bit-per-channel unsigned integer red/green/blue channel data format. Values are in the [code][0, 2^64 - 1][/code] range. + 64-bit-per-channel signed integer red/green/blue channel data format. Values are in the [code][2^63 + 1, 2^63 - 1][/code] range. + 64-bit-per-channel signed floating-point red/green/blue channel data format with the value stored as-is. + 64-bit-per-channel unsigned integer red/green/blue/alpha channel data format. Values are in the [code][0, 2^64 - 1][/code] range. + 64-bit-per-channel signed integer red/green/blue/alpha channel data format. Values are in the [code][2^63 + 1, 2^63 - 1][/code] range. + 64-bit-per-channel signed floating-point red/green/blue/alpha channel data format with the value stored as-is. + Unsigned floating-point blue/green/red data format with the value stored as-is, packed in 32 bits. The format's precision is 10 bits of blue channel, 11 bits of green channel and 11 bits of red channel. + Unsigned floating-point exposure/blue/green/red data format with the value stored as-is, packed in 32 bits. The format's precision is 5 bits of exposure, 9 bits of blue channel, 9 bits of green channel and 9 bits of red channel. + 16-bit unsigned floating-point depth data format with normalized value. Values are in the [code][0.0, 1.0][/code] range. + 24-bit unsigned floating-point depth data format with normalized value, plus 8 unused bits, packed in 32 bits. Values for depth are in the [code][0.0, 1.0][/code] range. + 32-bit signed floating-point depth data format with the value stored as-is. + 8-bit unsigned integer stencil data format. + 16-bit unsigned floating-point depth data format with normalized value, plus 8 bits of stencil in unsigned integer format. Values for depth are in the [code][0.0, 1.0][/code] range. Values for stencil are in the [code][0, 255][/code] range. + 24-bit unsigned floating-point depth data format with normalized value, plus 8 bits of stencil in unsigned integer format. Values for depth are in the [code][0.0, 1.0][/code] range. Values for stencil are in the [code][0, 255][/code] range. + 32-bit signed floating-point depth data format with the value stored as-is, plus 8 bits of stencil in unsigned integer format. Values for stencil are in the [code][0, 255][/code] range. + VRAM-compressed unsigned red/green/blue channel data format with normalized value. Values are in the [code][0.0, 1.0][/code] range. The format's precision is 5 bits of red channel, 6 bits of green channel and 5 bits of blue channel. Using BC1 texture compression (also known as S3TC DXT1). + VRAM-compressed unsigned red/green/blue channel data format with normalized value and non-linear sRGB encoding. Values are in the [code][0.0, 1.0][/code] range. The format's precision is 5 bits of red channel, 6 bits of green channel and 5 bits of blue channel. Using BC1 texture compression (also known as S3TC DXT1). + VRAM-compressed unsigned red/green/blue/alpha channel data format with normalized value. Values are in the [code][0.0, 1.0][/code] range. The format's precision is 5 bits of red channel, 6 bits of green channel, 5 bits of blue channel and 1 bit of alpha channel. Using BC1 texture compression (also known as S3TC DXT1). + VRAM-compressed unsigned red/green/blue/alpha channel data format with normalized value and non-linear sRGB encoding. Values are in the [code][0.0, 1.0][/code] range. The format's precision is 5 bits of red channel, 6 bits of green channel, 5 bits of blue channel and 1 bit of alpha channel. Using BC1 texture compression (also known as S3TC DXT1). + VRAM-compressed unsigned red/green/blue/alpha channel data format with normalized value. Values are in the [code][0.0, 1.0][/code] range. The format's precision is 5 bits of red channel, 6 bits of green channel, 5 bits of blue channel and 4 bits of alpha channel. Using BC2 texture compression (also known as S3TC DXT3). + VRAM-compressed unsigned red/green/blue/alpha channel data format with normalized value and non-linear sRGB encoding. Values are in the [code][0.0, 1.0][/code] range. The format's precision is 5 bits of red channel, 6 bits of green channel, 5 bits of blue channel and 4 bits of alpha channel. Using BC2 texture compression (also known as S3TC DXT3). + VRAM-compressed unsigned red/green/blue/alpha channel data format with normalized value. Values are in the [code][0.0, 1.0][/code] range. The format's precision is 5 bits of red channel, 6 bits of green channel, 5 bits of blue channel and 8 bits of alpha channel. Using BC3 texture compression (also known as S3TC DXT5). + VRAM-compressed unsigned red/green/blue/alpha channel data format with normalized value and non-linear sRGB encoding. Values are in the [code][0.0, 1.0][/code] range. The format's precision is 5 bits of red channel, 6 bits of green channel, 5 bits of blue channel and 8 bits of alpha channel. Using BC3 texture compression (also known as S3TC DXT5). + VRAM-compressed unsigned red channel data format with normalized value. Values are in the [code][0.0, 1.0][/code] range. The format's precision is 8 bits of red channel. Using BC4 texture compression. + VRAM-compressed signed red channel data format with normalized value. Values are in the [code][-1.0, 1.0][/code] range. The format's precision is 8 bits of red channel. Using BC4 texture compression. + VRAM-compressed unsigned red/green channel data format with normalized value. Values are in the [code][0.0, 1.0][/code] range. The format's precision is 8 bits of red channel and 8 bits of green channel. Using BC5 texture compression (also known as S3TC RGTC). + VRAM-compressed signed red/green channel data format with normalized value. Values are in the [code][-1.0, 1.0][/code] range. The format's precision is 8 bits of red channel and 8 bits of green channel. Using BC5 texture compression (also known as S3TC RGTC). + VRAM-compressed unsigned red/green/blue channel data format with the floating-point value stored as-is. The format's precision is 8 bits of red channel and 8 bits of green channel. Using BC6H texture compression (also known as BPTC HDR). + VRAM-compressed signed red/green/blue channel data format with the floating-point value stored as-is. The format's precision is between 4 and 7 bits for the red/green/blue channels and between 0 and 8 bits for the alpha channel. Using BC7 texture compression (also known as BPTC HDR). + VRAM-compressed unsigned red/green/blue/alpha channel data format with normalized value. Values are in the [code][0.0, 1.0][/code] range. The format's precision is between 4 and 7 bits for the red/green/blue channels and between 0 and 8 bits for the alpha channel. Also known as BPTC LDR. + VRAM-compressed unsigned red/green/blue/alpha channel data format with normalized value and non-linear sRGB encoding. Values are in the [code][0.0, 1.0][/code] range. The format's precision is between 4 and 7 bits for the red/green/blue channels and between 0 and 8 bits for the alpha channel. Also known as BPTC LDR. + VRAM-compressed unsigned red/green/blue channel data format with normalized value. Values are in the [code][0.0, 1.0][/code] range. Using ETC2 texture compression. + VRAM-compressed unsigned red/green/blue channel data format with normalized value and non-linear sRGB encoding. Values are in the [code][0.0, 1.0][/code] range. Using ETC2 texture compression. + VRAM-compressed unsigned red/green/blue/alpha channel data format with normalized value. Values are in the [code][0.0, 1.0][/code] range. Red/green/blue use 8 bit of precision each, with alpha using 1 bit of precision. Using ETC2 texture compression. + VRAM-compressed unsigned red/green/blue/alpha channel data format with normalized value and non-linear sRGB encoding. Values are in the [code][0.0, 1.0][/code] range. Red/green/blue use 8 bit of precision each, with alpha using 1 bit of precision. Using ETC2 texture compression. + VRAM-compressed unsigned red/green/blue/alpha channel data format with normalized value. Values are in the [code][0.0, 1.0][/code] range. Red/green/blue use 8 bits of precision each, with alpha using 8 bits of precision. Using ETC2 texture compression. + VRAM-compressed unsigned red/green/blue/alpha channel data format with normalized value and non-linear sRGB encoding. Values are in the [code][0.0, 1.0][/code] range. Red/green/blue use 8 bits of precision each, with alpha using 8 bits of precision. Using ETC2 texture compression. + 11-bit VRAM-compressed unsigned red channel data format with normalized value. Values are in the [code][0.0, 1.0][/code] range. Using ETC2 texture compression. + 11-bit VRAM-compressed signed red channel data format with normalized value. Values are in the [code][0.0, 1.0][/code] range. Using ETC2 texture compression. + 11-bit VRAM-compressed unsigned red/green channel data format with normalized value. Values are in the [code][0.0, 1.0][/code] range. Using ETC2 texture compression. + 11-bit VRAM-compressed signed red/green channel data format with normalized value. Values are in the [code][0.0, 1.0][/code] range. Using ETC2 texture compression. + VRAM-compressed unsigned floating-point data format with normalized value, packed in 4×4 blocks (highest quality). Values are in the [code][0.0, 1.0][/code] range. Using ASTC compression. + VRAM-compressed unsigned floating-point data format with normalized value and non-linear sRGB encoding, packed in 4×4 blocks (highest quality). Values are in the [code][0.0, 1.0][/code] range. Using ASTC compression. + VRAM-compressed unsigned floating-point data format with normalized value, packed in 5×4 blocks. Values are in the [code][0.0, 1.0][/code] range. Using ASTC compression. + VRAM-compressed unsigned floating-point data format with normalized value and non-linear sRGB encoding, packed in 5×4 blocks. Values are in the [code][0.0, 1.0][/code] range. Using ASTC compression. + VRAM-compressed unsigned floating-point data format with normalized value, packed in 5×5 blocks. Values are in the [code][0.0, 1.0][/code] range. Using ASTC compression. + VRAM-compressed unsigned floating-point data format with normalized value and non-linear sRGB encoding, packed in 5×5 blocks. Values are in the [code][0.0, 1.0][/code] range. Using ASTC compression. + VRAM-compressed unsigned floating-point data format with normalized value, packed in 6×5 blocks. Values are in the [code][0.0, 1.0][/code] range. Using ASTC compression. + VRAM-compressed unsigned floating-point data format with normalized value and non-linear sRGB encoding, packed in 6×5 blocks. Values are in the [code][0.0, 1.0][/code] range. Using ASTC compression. + VRAM-compressed unsigned floating-point data format with normalized value, packed in 6×6 blocks. Values are in the [code][0.0, 1.0][/code] range. Using ASTC compression. + VRAM-compressed unsigned floating-point data format with normalized value and non-linear sRGB encoding, packed in 6×6 blocks. Values are in the [code][0.0, 1.0][/code] range. Using ASTC compression. + VRAM-compressed unsigned floating-point data format with normalized value, packed in 8×5 blocks. Values are in the [code][0.0, 1.0][/code] range. Using ASTC compression. + VRAM-compressed unsigned floating-point data format with normalized value and non-linear sRGB encoding, packed in 8×5 blocks. Values are in the [code][0.0, 1.0][/code] range. Using ASTC compression. + VRAM-compressed unsigned floating-point data format with normalized value, packed in 8×6 blocks. Values are in the [code][0.0, 1.0][/code] range. Using ASTC compression. + VRAM-compressed unsigned floating-point data format with normalized value and non-linear sRGB encoding, packed in 8×6 blocks. Values are in the [code][0.0, 1.0][/code] range. Using ASTC compression. + VRAM-compressed unsigned floating-point data format with normalized value, packed in 8×8 blocks. Values are in the [code][0.0, 1.0][/code] range. Using ASTC compression. + VRAM-compressed unsigned floating-point data format with normalized value and non-linear sRGB encoding, packed in 8×8 blocks. Values are in the [code][0.0, 1.0][/code] range. Using ASTC compression. + VRAM-compressed unsigned floating-point data format with normalized value, packed in 10×5 blocks. Values are in the [code][0.0, 1.0][/code] range. Using ASTC compression. + VRAM-compressed unsigned floating-point data format with normalized value and non-linear sRGB encoding, packed in 10×5 blocks. Values are in the [code][0.0, 1.0][/code] range. Using ASTC compression. + VRAM-compressed unsigned floating-point data format with normalized value, packed in 10×6 blocks. Values are in the [code][0.0, 1.0][/code] range. Using ASTC compression. + VRAM-compressed unsigned floating-point data format with normalized value and non-linear sRGB encoding, packed in 10×6 blocks. Values are in the [code][0.0, 1.0][/code] range. Using ASTC compression. + VRAM-compressed unsigned floating-point data format with normalized value, packed in 10×8 blocks. Values are in the [code][0.0, 1.0][/code] range. Using ASTC compression. + VRAM-compressed unsigned floating-point data format with normalized value and non-linear sRGB encoding, packed in 10×8 blocks. Values are in the [code][0.0, 1.0][/code] range. Using ASTC compression. + VRAM-compressed unsigned floating-point data format with normalized value, packed in 10×10 blocks. Values are in the [code][0.0, 1.0][/code] range. Using ASTC compression. + VRAM-compressed unsigned floating-point data format with normalized value and non-linear sRGB encoding, packed in 10×10 blocks. Values are in the [code][0.0, 1.0][/code] range. Using ASTC compression. + VRAM-compressed unsigned floating-point data format with normalized value, packed in 12×10 blocks. Values are in the [code][0.0, 1.0][/code] range. Using ASTC compression. + VRAM-compressed unsigned floating-point data format with normalized value and non-linear sRGB encoding, packed in 12×10 blocks. Values are in the [code][0.0, 1.0][/code] range. Using ASTC compression. + VRAM-compressed unsigned floating-point data format with normalized value, packed in 12 blocks (lowest quality). Values are in the [code][0.0, 1.0][/code] range. Using ASTC compression. + VRAM-compressed unsigned floating-point data format with normalized value and non-linear sRGB encoding, packed in 12 blocks (lowest quality). Values are in the [code][0.0, 1.0][/code] range. Using ASTC compression. + 8-bit-per-channel unsigned floating-point green/blue/red channel data format with normalized value. Values are in the [code][0.0, 1.0][/code] range. Blue and red channel data is stored at halved horizontal resolution (i.e. 2 horizontally adjacent pixels will share the same value for the blue/red channel). + 8-bit-per-channel unsigned floating-point blue/green/red channel data format with normalized value. Values are in the [code][0.0, 1.0][/code] range. Blue and red channel data is stored at halved horizontal resolution (i.e. 2 horizontally adjacent pixels will share the same value for the blue/red channel). + 8-bit-per-channel unsigned floating-point green/blue/red channel data with normalized value, stored across 3 separate planes (green + blue + red). Values are in the [code][0.0, 1.0][/code] range. Blue and red channel data is stored at halved horizontal and vertical resolution (i.e. 2×2 adjacent pixels will share the same value for the blue/red channel). + 8-bit-per-channel unsigned floating-point green/blue/red channel data with normalized value, stored across 2 separate planes (green + blue/red). Values are in the [code][0.0, 1.0][/code] range. Blue and red channel data is stored at halved horizontal and vertical resolution (i.e. 2×2 adjacent pixels will share the same value for the blue/red channel). + 8-bit-per-channel unsigned floating-point green/blue/red channel data with normalized value, stored across 2 separate planes (green + blue + red). Values are in the [code][0.0, 1.0][/code] range. Blue and red channel data is stored at halved horizontal resolution (i.e. 2 horizontally adjacent pixels will share the same value for the blue/red channel). + 8-bit-per-channel unsigned floating-point green/blue/red channel data with normalized value, stored across 2 separate planes (green + blue/red). Values are in the [code][0.0, 1.0][/code] range. Blue and red channel data is stored at halved horizontal resolution (i.e. 2 horizontally adjacent pixels will share the same value for the blue/red channel). + 8-bit-per-channel unsigned floating-point green/blue/red channel data with normalized value, stored across 3 separate planes. Values are in the [code][0.0, 1.0][/code] range. + 10-bit-per-channel unsigned floating-point red channel data with normalized value, plus 6 unused bits, packed in 16 bits. Values are in the [code][0.0, 1.0][/code] range. + 10-bit-per-channel unsigned floating-point red/green channel data with normalized value, plus 6 unused bits after each channel, packed in 2×16 bits. Values are in the [code][0.0, 1.0][/code] range. + 10-bit-per-channel unsigned floating-point red/green/blue/alpha channel data with normalized value, plus 6 unused bits after each channel, packed in 4×16 bits. Values are in the [code][0.0, 1.0][/code] range. + 10-bit-per-channel unsigned floating-point green/blue/green/red channel data with normalized value, plus 6 unused bits after each channel, packed in 4×16 bits. Values are in the [code][0.0, 1.0][/code] range. Blue and red channel data is stored at halved horizontal resolution (i.e. 2 horizontally adjacent pixels will share the same value for the blue/red channel). The green channel is listed twice, but contains different values to allow it to be represented at full resolution. + 10-bit-per-channel unsigned floating-point blue/green/red/green channel data with normalized value, plus 6 unused bits after each channel, packed in 4×16 bits. Values are in the [code][0.0, 1.0][/code] range. Blue and red channel data is stored at halved horizontal resolution (i.e. 2 horizontally adjacent pixels will share the same value for the blue/red channel). The green channel is listed twice, but contains different values to allow it to be represented at full resolution. + 10-bit-per-channel unsigned floating-point green/blue/red channel data with normalized value, plus 6 unused bits after each channel. Packed in 3×16 bits and stored across 2 separate planes (green + blue + red). Values are in the [code][0.0, 1.0][/code] range. Blue and red channel data is stored at halved horizontal and vertical resolution (i.e. 2×2 adjacent pixels will share the same value for the blue/red channel). + 10-bit-per-channel unsigned floating-point green/blue/red channel data with normalized value, plus 6 unused bits after each channel. Packed in 3×16 bits and stored across 2 separate planes (green + blue/red). Values are in the [code][0.0, 1.0][/code] range. Blue and red channel data is stored at halved horizontal and vertical resolution (i.e. 2×2 adjacent pixels will share the same value for the blue/red channel). + 10-bit-per-channel unsigned floating-point green/blue/red channel data with normalized value, plus 6 unused bits after each channel. Packed in 3×16 bits and stored across 3 separate planes (green + blue + red). Values are in the [code][0.0, 1.0][/code] range. Blue and red channel data is stored at halved horizontal resolution (i.e. 2 horizontally adjacent pixels will share the same value for the blue/red channel). + 10-bit-per-channel unsigned floating-point green/blue/red channel data with normalized value, plus 6 unused bits after each channel. Packed in 3×16 bits and stored across 3 separate planes (green + blue/red). Values are in the [code][0.0, 1.0][/code] range. Blue and red channel data is stored at halved horizontal resolution (i.e. 2 horizontally adjacent pixels will share the same value for the blue/red channel). + 10-bit-per-channel unsigned floating-point green/blue/red channel data with normalized value, plus 6 unused bits after each channel. Packed in 3×16 bits and stored across 3 separate planes (green + blue + red). Values are in the [code][0.0, 1.0][/code] range. + 12-bit-per-channel unsigned floating-point red channel data with normalized value, plus 6 unused bits, packed in 16 bits. Values are in the [code][0.0, 1.0][/code] range. + 12-bit-per-channel unsigned floating-point red/green channel data with normalized value, plus 6 unused bits after each channel, packed in 2×16 bits. Values are in the [code][0.0, 1.0][/code] range. + 12-bit-per-channel unsigned floating-point red/green/blue/alpha channel data with normalized value, plus 6 unused bits after each channel, packed in 4×16 bits. Values are in the [code][0.0, 1.0][/code] range. + 12-bit-per-channel unsigned floating-point green/blue/green/red channel data with normalized value, plus 6 unused bits after each channel, packed in 4×16 bits. Values are in the [code][0.0, 1.0][/code] range. Blue and red channel data is stored at halved horizontal resolution (i.e. 2 horizontally adjacent pixels will share the same value for the blue/red channel). The green channel is listed twice, but contains different values to allow it to be represented at full resolution. + 12-bit-per-channel unsigned floating-point blue/green/red/green channel data with normalized value, plus 6 unused bits after each channel, packed in 4×16 bits. Values are in the [code][0.0, 1.0][/code] range. Blue and red channel data is stored at halved horizontal resolution (i.e. 2 horizontally adjacent pixels will share the same value for the blue/red channel). The green channel is listed twice, but contains different values to allow it to be represented at full resolution. + 12-bit-per-channel unsigned floating-point green/blue/red channel data with normalized value, plus 6 unused bits after each channel. Packed in 3×16 bits and stored across 2 separate planes (green + blue + red). Values are in the [code][0.0, 1.0][/code] range. Blue and red channel data is stored at halved horizontal and vertical resolution (i.e. 2×2 adjacent pixels will share the same value for the blue/red channel). + 12-bit-per-channel unsigned floating-point green/blue/red channel data with normalized value, plus 6 unused bits after each channel. Packed in 3×16 bits and stored across 2 separate planes (green + blue/red). Values are in the [code][0.0, 1.0][/code] range. Blue and red channel data is stored at halved horizontal and vertical resolution (i.e. 2×2 adjacent pixels will share the same value for the blue/red channel). + 12-bit-per-channel unsigned floating-point green/blue/red channel data with normalized value, plus 6 unused bits after each channel. Packed in 3×16 bits and stored across 3 separate planes (green + blue + red). Values are in the [code][0.0, 1.0][/code] range. Blue and red channel data is stored at halved horizontal resolution (i.e. 2 horizontally adjacent pixels will share the same value for the blue/red channel). + 12-bit-per-channel unsigned floating-point green/blue/red channel data with normalized value, plus 6 unused bits after each channel. Packed in 3×16 bits and stored across 3 separate planes (green + blue/red). Values are in the [code][0.0, 1.0][/code] range. Blue and red channel data is stored at halved horizontal resolution (i.e. 2 horizontally adjacent pixels will share the same value for the blue/red channel). + 12-bit-per-channel unsigned floating-point green/blue/red channel data with normalized value, plus 6 unused bits after each channel. Packed in 3×16 bits and stored across 3 separate planes (green + blue + red). Values are in the [code][0.0, 1.0][/code] range. + 16-bit-per-channel unsigned floating-point green/blue/red channel data format with normalized value. Values are in the [code][0.0, 1.0][/code] range. Blue and red channel data is stored at halved horizontal resolution (i.e. 2 horizontally adjacent pixels will share the same value for the blue/red channel). + 16-bit-per-channel unsigned floating-point blue/green/red channel data format with normalized value. Values are in the [code][0.0, 1.0][/code] range. Blue and red channel data is stored at halved horizontal resolution (i.e. 2 horizontally adjacent pixels will share the same value for the blue/red channel). + 16-bit-per-channel unsigned floating-point green/blue/red channel data with normalized value, plus 6 unused bits after each channel. Stored across 2 separate planes (green + blue + red). Values are in the [code][0.0, 1.0][/code] range. Blue and red channel data is stored at halved horizontal and vertical resolution (i.e. 2×2 adjacent pixels will share the same value for the blue/red channel). + 16-bit-per-channel unsigned floating-point green/blue/red channel data with normalized value, plus 6 unused bits after each channel. Stored across 2 separate planes (green + blue/red). Values are in the [code][0.0, 1.0][/code] range. Blue and red channel data is stored at halved horizontal and vertical resolution (i.e. 2×2 adjacent pixels will share the same value for the blue/red channel). + 16-bit-per-channel unsigned floating-point green/blue/red channel data with normalized value, plus 6 unused bits after each channel. Stored across 3 separate planes (green + blue + red). Values are in the [code][0.0, 1.0][/code] range. Blue and red channel data is stored at halved horizontal resolution (i.e. 2 horizontally adjacent pixels will share the same value for the blue/red channel). + 16-bit-per-channel unsigned floating-point green/blue/red channel data with normalized value, plus 6 unused bits after each channel. Stored across 3 separate planes (green + blue/red). Values are in the [code][0.0, 1.0][/code] range. Blue and red channel data is stored at halved horizontal resolution (i.e. 2 horizontally adjacent pixels will share the same value for the blue/red channel). + 16-bit-per-channel unsigned floating-point green/blue/red channel data with normalized value, plus 6 unused bits after each channel. Stored across 3 separate planes (green + blue + red). Values are in the [code][0.0, 1.0][/code] range. + Represents the size of the [enum DataFormat] enum. + Raster barrier mask. + Compute barrier mask. + Transfer barrier mask. + Barrier mask for all types (raster, compute, transfer). Equivalent to [code]BARRIER_MASK_RASTER | BARRIER_MASK_COMPUTE | BARRIER_MASK_TRANSFER[/code]. + No barrier for any type. 1-dimensional texture. @@ -1203,63 +1613,91 @@ Represents the size of the [enum TextureType] enum. + Perform 1 texture sample (this is the fastest but lowest-quality for antialiasing). + Perform 2 texture samples. + Perform 4 texture samples. + Perform 8 texture samples. Not supported on mobile GPUs (including Apple Silicon). + Perform 16 texture samples. Not supported on mobile GPUs and many desktop GPUs. + Perform 32 texture samples. Not supported on most GPUs. + Perform 64 texture samples (this is the slowest but highest-quality for antialiasing). Not supported on most GPUs. Represents the size of the [enum TextureSamples] enum. + Texture can be sampled. + Texture can be used as a color attachment in a framebuffer. + Texture can be used as a depth/stencil attachment in a framebuffer. + Texture can be used as a [url=https://registry.khronos.org/vulkan/specs/1.3-extensions/html/vkspec.html#descriptorsets-storageimage]storage image[/url]. + Texture can be used as a [url=https://registry.khronos.org/vulkan/specs/1.3-extensions/html/vkspec.html#descriptorsets-storageimage]storage image[/url] with support for atomic operations. + Texture can be read back on the CPU using [method texture_get_data] faster than without this bit, since it is always kept in the system memory. + Texture can be updated using [method texture_update]. + Texture can be a source for [method texture_copy]. + Texture can be a destination for [method texture_copy]. + Texture can be used as a [url=https://registry.khronos.org/vulkan/specs/1.3-extensions/html/vkspec.html#descriptorsets-inputattachment]input attachment[/url] in a framebuffer. + Return the sampled value as-is. + Always return [code]0.0[/code] when sampling. + Always return [code]1.0[/code] when sampling. + Sample the red color channel. + Sample the green color channel. + Sample the blue color channel. + Sample the alpha channel. + Represents the size of the [enum TextureSwizzle] enum. + 2-dimensional texture slice. + Cubemap texture slice. + 3-dimensional texture slice. Nearest-neighbor sampler filtering. Sampling at higher resolutions than the source will result in a pixelated look. @@ -1268,209 +1706,311 @@ Bilinear sampler filtering. Sampling at higher resolutions than the source will result in a blurry look. + Sample with repeating enabled. + Sample with mirrored repeating enabled. When sampling outside the [code][0.0, 1.0][/code] range, return a mirrorred version of the sampler. This mirrored version is mirrored again if sampling further away, with the pattern repeating indefinitely. + Sample with repeating disabled. When sampling outside the [code][0.0, 1.0][/code] range, return the color of the last pixel on the edge. + Sample with repeating disabled. When sampling outside the [code][0.0, 1.0][/code] range, return the specified [member RDSamplerState.border_color]. + Sample with mirorred repeating enabled, but only once. When sampling in the [code][-1.0, 0.0][/code] range, return a mirrored version of the sampler. When sampling outside the [code][-1.0, 1.0][/code] range, return the color of the last pixel on the edge. + Represents the size of the [enum SamplerRepeatMode] enum. + Return a floating-point transparent black color when sampling outside the [code][0.0, 1.0][/code] range. Only effective if the sampler repeat mode is [constant SAMPLER_REPEAT_MODE_CLAMP_TO_BORDER]. + Return a integer transparent black color when sampling outside the [code][0.0, 1.0][/code] range. Only effective if the sampler repeat mode is [constant SAMPLER_REPEAT_MODE_CLAMP_TO_BORDER]. + Return a floating-point opaque black color when sampling outside the [code][0.0, 1.0][/code] range. Only effective if the sampler repeat mode is [constant SAMPLER_REPEAT_MODE_CLAMP_TO_BORDER]. + Return a integer opaque black color when sampling outside the [code][0.0, 1.0][/code] range. Only effective if the sampler repeat mode is [constant SAMPLER_REPEAT_MODE_CLAMP_TO_BORDER]. + Return a floating-point opaque white color when sampling outside the [code][0.0, 1.0][/code] range. Only effective if the sampler repeat mode is [constant SAMPLER_REPEAT_MODE_CLAMP_TO_BORDER]. + Return a integer opaque white color when sampling outside the [code][0.0, 1.0][/code] range. Only effective if the sampler repeat mode is [constant SAMPLER_REPEAT_MODE_CLAMP_TO_BORDER]. + Represents the size of the [enum SamplerBorderColor] enum. + Vertex attribute addressing is a function of the vertex. This is used to specify the rate at which vertex attributes are pulled from buffers. + Vertex attribute addressing is a function of the instance index. This is used to specify the rate at which vertex attributes are pulled from buffers. + Index buffer in 16-bit unsigned integer format. This limits the maximum index that can be specified to [code]65535[/code]. + Index buffer in 32-bit unsigned integer format. This limits the maximum index that can be specified to [code]4294967295[/code]. + Sampler uniform. TODO: Difference between sampler and texture uniform + Sampler uniform with a texture. + Texture uniform. + Image uniform. TODO: Difference between texture and image uniform + Texture buffer uniform. TODO: Difference between texture and texture buffe uniformr + Sampler uniform with a texture buffer. TODO: Difference between texture and texture buffer uniform + Image buffer uniform. TODO: Difference between texture and image uniforms + Uniform buffer uniform. + [url=https://vkguide.dev/docs/chapter-4/storage_buffers/]Storage buffer[/url] uniform. + Input attachment uniform. + Represents the size of the [enum UniformType] enum. Point rendering primitive (with constant size, regardless of distance from camera). - Line rendering primitive. + Line list rendering primitive. Lines are drawn separated from each other. + [url=https://registry.khronos.org/vulkan/specs/1.3-extensions/html/vkspec.html#drawing-line-lists-with-adjacency]Line list rendering primitive with adjacency.[/url] + [b]Note:[/b] Adjacency is only useful with geometry shaders, which Godot does not expose. + Line strip rendering primitive. Lines drawn are connected to the previous vertex. + [url=https://registry.khronos.org/vulkan/specs/1.3-extensions/html/vkspec.html#drawing-line-strips-with-adjacency]Line strip rendering primitive with adjacency.[/url] + [b]Note:[/b] Adjacency is only useful with geometry shaders, which Godot does not expose. + Triangle list rendering primitive. Triangles are drawn separated from each other. + [url=https://registry.khronos.org/vulkan/specs/1.3-extensions/html/vkspec.html#drawing-triangle-lists-with-adjacency]Triangle list rendering primitive with adjacency.[/url] + [b]Note:[/b] Adjacency is only useful with geometry shaders, which Godot does not expose. + Triangle strip rendering primitive. Triangles drawn are connected to the previous triangle. + [url=https://registry.khronos.org/vulkan/specs/1.3-extensions/html/vkspec.html#drawing-triangle-strips-with-adjacency]Triangle strip rendering primitive with adjacency.[/url] + [b]Note:[/b] Adjacency is only useful with geometry shaders, which Godot does not expose. + Triangle strip rendering primitive with [i]primitive restart[/i] enabled. Triangles drawn are connected to the previous triangle, but a primitive restart index can be specified before drawing to create a second triangle strip after the specified index. + [b]Note:[/b] Only compatible with indexed draws. + Tessellation patch rendering primitive. Only useful with tessellation shaders, which can be used to deform these patches. + Represents the size of the [enum RenderPrimitive] enum. + Do not use polygon front face or backface culling. + Use polygon frontface culling (faces pointing towards the camera are hidden). + Use polygon backface culling (faces pointing away from the camera are hidden). + Clockwise winding order to determine which face of a polygon is its front face. + Counter-clockwise winding order to determine which face of a polygon is its front face. + Keep the current stencil value. + Set the stencil value to [code]0[/code]. + Replace the existing stencil value with the new one. + Increment the existing stencil value and clamp to the maximum representable unsigned value if reached. Stencil bits are considered as an unsigned integer. + Decrement the existing stencil value and clamp to the minimum value if reached. Stencil bits are considered as an unsigned integer. + Bitwise-invert the existing stencil value. + Increment the stencil value and wrap around to [code]0[/code] if reaching the maximum representable unsigned. Stencil bits are considered as an unsigned integer. + Decrement the stencil value and wrap around to the maximum representable unsigned if reaching the minimum. Stencil bits are considered as an unsigned integer. + Represents the size of the [enum StencilOperation] enum. + "Never" comparison (opposite of [constant COMPARE_OP_ALWAYS]). + "Less than" comparison. + "Equal" comparison. + "Less than or equal" comparison. + "Greater than" comparison. + "Not equal" comparison. + "Greater than or equal" comparison. + "Always" comparison (opposite of [constant COMPARE_OP_NEVER]). + Represents the size of the [enum CompareOperator] enum. + Clear logic operation (result is always [code]0[/code]). See also [constant LOGIC_OP_SET]. + AND logic operation. + AND logic operation with the [i]destination[/i] operand being inverted. See also [constant LOGIC_OP_AND_INVERTED]. + Copy logic operation (keeps the [i]source[/i] value as-is). See also [constant LOGIC_OP_COPY_INVERTED] and [constant LOGIC_OP_NO_OP]. + AND logic operation with the [i]source[/i] operand being inverted. See also [constant LOGIC_OP_AND_REVERSE]. + No-op logic operation (keeps the [i]destination[/i] value as-is). See also [constant LOGIC_OP_COPY]. Exclusive or (XOR) logic operation. + OR logic operation. + Not-OR (NOR) logic operation. + Not-XOR (XNOR) logic operation. + Invert logic operation. + OR logic operation with the [i]destination[/i] operand being inverted. See also [constant LOGIC_OP_OR_REVERSE]. + NOT logic operation (inverts the value). See also [constant LOGIC_OP_COPY]. + OR logic operation with the [i]source[/i] operand being inverted. See also [constant LOGIC_OP_OR_REVERSE]. + Not-AND (NAND) logic operation. + SET logic operation (result is always [code]1[/code]). See also [constant LOGIC_OP_CLEAR]. + Represents the size of the [enum LogicOperation] enum. + Constant [code]0.0[/code] blend factor. + Constant [code]1.0[/code] blend factor. + Color blend factor is [code]source color[/code]. Alpha blend factor is [code]source alpha[/code]. + Color blend factor is [code]1.0 - source color[/code]. Alpha blend factor is [code]1.0 - source alpha[/code]. + Color blend factor is [code]destination color[/code]. Alpha blend factor is [code]destination alpha[/code]. + Color blend factor is [code]1.0 - destination color[/code]. Alpha blend factor is [code]1.0 - destination alpha[/code]. + Color and alpha blend factor is [code]source alpha[/code]. + Color and alpha blend factor is [code]1.0 - source alpha[/code]. + Color and alpha blend factor is [code]destination alpha[/code]. + Color and alpha blend factor is [code]1.0 - destination alpha[/code]. + Color blend factor is [code]blend constant color[/code]. Alpha blend factor is [code]blend constant alpha[/code] (see [method draw_list_set_blend_constants]). + Color blend factor is [code]1.0 - blend constant color[/code]. Alpha blend factor is [code]1.0 - blend constant alpha[/code] (see [method draw_list_set_blend_constants]). + Color and alpha blend factor is [code]blend constant alpha[/code] (see [method draw_list_set_blend_constants]). + Color and alpha blend factor is [code]1.0 - blend constant alpha[/code] (see [method draw_list_set_blend_constants]). + Color blend factor is [code]min(source alpha, 1.0 - destination alpha)[/code]. Alpha blend factor is [code]1.0[/code]. + Color blend factor is [code]second source color[/code]. Alpha blend factor is [code]second source alpha[/code]. Only relevant for dual-source blending. + Color blend factor is [code]1.0 - second source color[/code]. Alpha blend factor is [code]1.0 - second source alpha[/code]. Only relevant for dual-source blending. + Color and alpha blend factor is [code]second source alpha[/code]. Only relevant for dual-source blending. + Color and alpha blend factor is [code]1.0 - second source alpha[/code]. Only relevant for dual-source blending. + Represents the size of the [enum BlendFactor] enum. Additive blending operation ([code]source + destination[/code]). @@ -1517,68 +2057,100 @@ + Represents the size of the [enum InitialAction] enum. + Store the texture for reading and make it read-only if it has the [constant TEXTURE_USAGE_SAMPLING_BIT] bit (only applies to color, depth and stencil attachments). + Discard the texture data and make it read-only if it has the [constant TEXTURE_USAGE_SAMPLING_BIT] bit (only applies to color, depth and stencil attachments). + Store the texture and continue for further processing. Similar to [constant FINAL_ACTION_READ], but does not make the texture read-only if it has the [constant TEXTURE_USAGE_SAMPLING_BIT] bit. + Represents the size of the [enum FinalAction] enum. + Vertex shader stage. This can be used to manipulate vertices from a shader (but not create new vertices). + Fragment shader stage (called "pixel shader" in Direct3D). This can be used to manipulate pixels from a shader. + Tessellation control shader stage. This can be used to create additional geometry from a shader. + Tessellation evaluation shader stage. This can be used to create additional geometry from a shader. + Compute shader stage. This can be used to run arbitrary computing tasks in a shader, performing them on the GPU instead of the CPU. + Represents the size of the [enum ShaderStage] enum. + Vertex shader stage bit (see also [constant SHADER_STAGE_VERTEX]). + Fragment shader stage bit (see also [constant SHADER_STAGE_FRAGMENT]). + Tessellation control shader stage bit (see also [constant SHADER_STAGE_TESSELATION_CONTROL]). + Tessellation evaluation shader stage bit (see also [constant SHADER_STAGE_TESSELATION_EVALUATION]). + Compute shader stage bit (see also [constant SHADER_STAGE_COMPUTE]). + Khronos' GLSL shading language (used natively by OpenGL and Vulkan). This is the language used for core Godot shaders. + Microsoft's High-Level Shading Language (used natively by Direct3D, but can also be used in Vulkan). + Boolean specialization constant. + Integer specialization constant. + Floating-point specialization constant. + Maximum number of uniform sets that can be bound at a given time. + Maximum number of color framebuffer attachments that can be used at a given time. + Maximum number of textures that can be used per uniform set. + Maximum number of samplers that can be used per uniform set. + Maximum number of [url=https://vkguide.dev/docs/chapter-4/storage_buffers/]storage buffers[/url] per uniform set. + Maximum number of storage images per uniform set. + Maximum number of uniform buffers per uniform set. + Maximum index for an indexed draw command. + Maximum height of a framebuffer (in pixels). + Maximum width of a framebuffer (in pixels). + Maximum number of texture array layers. Maximum supported 1-dimensional texture size (in pixels on a single axis). @@ -1593,48 +2165,70 @@ Maximum supported cubemap texture size (in pixels on a single axis of a single face). + Maximum number of textures per shader stage. + Maximum number of samplers per shader stage. + Maximum number of [url=https://vkguide.dev/docs/chapter-4/storage_buffers/]storage buffers[/url] per shader stage. + Maximum number of storage images per shader stage. + Maximum number of uniform buffers per uniform set. + Maximum size of a push constant. A lot of devices are limited to 128 bytes, so try to avoid exceeding 128 bytes in push constants to ensure compatibility even if your GPU is reporting a higher value. + Maximum size of a uniform buffer. + Maximum vertex input attribute offset. + Maximum number of vertex input attributes. + Maximum number of vertex input bindings. + Maximum vertex input binding stride. + Minimum uniform buffer offset alignment. + Maximum shared memory size for compute shaders. + Maximum number of workgroups for compute shaders on the X axis. + Maximum number of workgroups for compute shaders on the Y axis. + Maximum number of workgroups for compute shaders on the Z axis. + Maximum number of workgroup invocations for compute shaders. + Maximum workgroup size for compute shaders on the X axis. + Maximum workgroup size for compute shaders on the Y axis. + Maximum workgroup size for compute shaders on the Z axis. + Maximum viewport width (in pixels). + Maximum viewport height (in pixels). Memory taken by textures. diff --git a/doc/classes/RenderingServer.xml b/doc/classes/RenderingServer.xml index 05ac18c7fe..261d45cdf9 100644 --- a/doc/classes/RenderingServer.xml +++ b/doc/classes/RenderingServer.xml @@ -4,15 +4,14 @@ Server for anything visible. - The rendering server is the API backend for everything visible. The whole scene system mounts on it to display. - The rendering server is completely opaque, the internals are entirely implementation specific and cannot be accessed. - The rendering server can be used to bypass the scene/[Node] system entirely. + The rendering server is the API backend for everything visible. The whole scene system mounts on it to display. The rendering server is completely opaque: the internals are entirely implementation-specific and cannot be accessed. + The rendering server can be used to bypass the scene/[Node] system entirely. This can improve performance in cases where the scene system is the bottleneck, but won't improve performance otherwise (for instance, if the GPU is already fully utilized). Resources are created using the [code]*_create[/code] functions. These functions return [RID]s which are not references to the objects themselves, but opaque [i]pointers[/i] towards these objects. All objects are drawn to a viewport. You can use the [Viewport] attached to the [SceneTree] or you can create one yourself with [method viewport_create]. When using a custom scenario or canvas, the scenario or canvas needs to be attached to the viewport using [method viewport_set_scenario] or [method viewport_attach_canvas]. - In 3D, all visual objects must be associated with a scenario. The scenario is a visual representation of the world. If accessing the rendering server from a running game, the scenario can be accessed from the scene tree from any [Node3D] node with [method Node3D.get_world_3d]. Otherwise, a scenario can be created with [method scenario_create]. + [b]Scenarios:[/b] In 3D, all visual objects must be associated with a scenario. The scenario is a visual representation of the world. If accessing the rendering server from a running game, the scenario can be accessed from the scene tree from any [Node3D] node with [method Node3D.get_world_3d]. Otherwise, a scenario can be created with [method scenario_create]. Similarly, in 2D, a canvas is needed to draw all canvas items. - In 3D, all visible objects are comprised of a resource and an instance. A resource can be a mesh, a particle system, a light, or any other 3D object. In order to be visible resources must be attached to an instance using [method instance_set_base]. The instance must also be attached to the scenario using [method instance_set_scenario] in order to be visible. - In 2D, all visible objects are some form of canvas item. In order to be visible, a canvas item needs to be the child of a canvas attached to a viewport, or it needs to be the child of another canvas item that is eventually attached to the canvas. + [b]3D:[/b] In 3D, all visible objects are comprised of a resource and an instance. A resource can be a mesh, a particle system, a light, or any other 3D object. In order to be visible resources must be attached to an instance using [method instance_set_base]. The instance must also be attached to the scenario using [method instance_set_scenario] in order to be visible. RenderingServer methods that don't have a prefix are usually 3D-specific (but not always). + [b]2D:[/b] In 2D, all visible objects are some form of canvas item. In order to be visible, a canvas item needs to be the child of a canvas attached to a viewport, or it needs to be the child of another canvas item that is eventually attached to the canvas. 2D-specific RenderingServer methods generally start with [code]canvas_*[/code]. [b]Headless mode:[/b] Starting the engine with the [code]--headless[/code] [url=$DOCS_URL/tutorials/editor/command_line_tutorial.html]command line argument[/url] disables all rendering and window management functions. Most functions from [RenderingServer] will return dummy values in this case. @@ -32,8 +31,8 @@ Creates a camera attributes object and adds it to the RenderingServer. It can be accessed with the RID that is returned. This RID will be used in all [code]camera_attributes_[/code] RenderingServer functions. - Once finished with your RID, you will want to free the RID using the RenderingServer's [method free_rid] static method. - This is the internal equivalent of the [CameraAttributes] resource. + Once finished with your RID, you will want to free the RID using the RenderingServer's [method free_rid] method. + [b]Note:[/b] The equivalent resource is [CameraAttributes]. @@ -99,9 +98,9 @@ - Creates a camera and adds it to the RenderingServer. It can be accessed with the RID that is returned. This RID will be used in all [code]camera_*[/code] RenderingServer functions. - Once finished with your RID, you will want to free the RID using the RenderingServer's [method free_rid] static method. - This is the internal equivalent of the [Camera3D] node. + Creates a 3D camera and adds it to the RenderingServer. It can be accessed with the RID that is returned. This RID will be used in all [code]camera_*[/code] RenderingServer functions. + Once finished with your RID, you will want to free the RID using the RenderingServer's [method free_rid] method. + [b]Note:[/b] The equivalent node is [Camera3D]. @@ -179,7 +178,7 @@ Creates a canvas and returns the assigned [RID]. It can be accessed with the RID that is returned. This RID will be used in all [code]canvas_*[/code] RenderingServer functions. - Once finished with your RID, you will want to free the RID using the RenderingServer's [method free_rid] static method. + Once finished with your RID, you will want to free the RID using the RenderingServer's [method free_rid] method. Canvas has no [Resource] or [Node] equivalent. @@ -302,7 +301,7 @@ - Draws a 2D polygon on the [CanvasItem] pointed to by the [param item] [RID]. See also [method CanvasItem.draw_polygon]. + Draws a 2D polygon on the [CanvasItem] pointed to by the [param item] [RID]. If you need more flexibility (such as being able to use bones), use [method canvas_item_add_triangle_array] instead. See also [method CanvasItem.draw_polygon]. @@ -381,6 +380,8 @@ + Draws a triangle array on the [CanvasItem] pointed to by the [param item] [RID]. This is internally used by [Line2D] and [StyleBoxFlat] for rendering. [method canvas_item_add_triangle_array] is highly flexible, but more complex to use than [method canvas_item_add_polygon]. + [b]Note:[/b] [param count] is unused and can be left unspecified. @@ -393,9 +394,9 @@ - Creates a canvas item and returns the assigned [RID]. It can be accessed with the RID that is returned. This RID will be used in all [code]canvas_item_*[/code] RenderingServer functions. - Once finished with your RID, you will want to free the RID using the RenderingServer's [method free_rid] static method. - This is the internal equivalent of the [CanvasItem] node. + Creates a new CanvasItem instance and returns its [RID]. It can be accessed with the RID that is returned. This RID will be used in all [code]canvas_item_*[/code] RenderingServer functions. + Once finished with your RID, you will want to free the RID using the RenderingServer's [method free_rid] method. + [b]Note:[/b] The equivalent node is [CanvasItem]. @@ -407,6 +408,8 @@ + Sets the canvas group mode used during 2D rendering for the canvas item specified by the [param item] RID. For faster but more limited clipping, use [method canvas_item_set_clip] instead. + [b]Note:[/b] The equivalent node functionality is found in [CanvasGroup] and [member CanvasItem.clip_children]. @@ -414,6 +417,8 @@ + If [param clip] is [code]true[/code], makes the canvas item specified by the [param item] RID not draw anything outside of its rect's coordinates. This clipping is fast, but works only with axis-aligned rectangles. This means that rotation is ignored by the clipping rectangle. For more advanced clipping shapes, use [method canvas_item_set_canvas_group_mode] instead. + [b]Note:[/b] The equivalent node functionality is found in [member Label.clip_text], [RichTextLabel] (always enabled) and more. @@ -431,6 +436,7 @@ + If [param use_custom_rect] is [code]true[/code], sets the custom visibility rectangle (used for culling) to [param rect] for the canvas item specified by [param item]. Setting a custom visibility rect can reduce CPU load when drawing lots of 2D instances. If [param use_custom_rect] is [code]false[/code], automatically computes a visibility rectangle based on the canvas item's draw commands. @@ -438,6 +444,7 @@ + Sets the default texture filter mode for the canvas item specified by the [param item] RID. Equivalent to [member CanvasItem.texture_filter]. @@ -445,6 +452,7 @@ + Sets the default texture repeat mode for the canvas item specified by the [param item] RID. Equivalent to [member CanvasItem.texture_repeat]. @@ -452,6 +460,7 @@ + If [param enabled] is [code]true[/code], enables multichannel signed distance field rendering mode for the canvas item specified by the [param item] RID. This is meant to be used for font rendering, or with specially generated images using [url=https://github.com/Chlumsky/msdfgen]msdfgen[/url]. @@ -459,6 +468,7 @@ + If [param enabled] is [code]true[/code], draws the canvas item specified by the [param item] RID behind its parent. Equivalent to [member CanvasItem.show_behind_parent]. @@ -474,6 +484,7 @@ + Sets the light [param mask] for the canvas item specified by the [param item] RID. Equivalent to [member CanvasItem.light_mask]. @@ -481,7 +492,7 @@ - Sets a new material to the [CanvasItem]. + Sets a new [param material] to the canvas item specified by the [param item] RID. Equivalent to [member CanvasItem.material]. @@ -489,7 +500,7 @@ - Sets a color modulation to the [CanvasItem]. This also affects child canvas items. + Multiplies the color of the canvas item specified by the [param item] RID, while affecting its children. See also [method canvas_item_set_self_modulate]. Equivalent to [member CanvasItem.modulate]. @@ -505,7 +516,7 @@ - Sets a color self-modulation to the [CanvasItem]. It does not affect the child canvas items. + Multiplies the color of the canvas item specified by the [param item] RID, without affecting its children. See also [method canvas_item_set_modulate]. Equivalent to [member CanvasItem.self_modulate]. @@ -513,7 +524,7 @@ - Enables or disables Y-sorting of a [CanvasItem]. + If [param enabled] is [code]true[/code], child nodes with the lowest Y position are drawn before those with a higher Y position. Y-sorting only affects children that inherit from the canvas item specified by the [param item] RID, not the canvas item itself. Equivalent to [member CanvasItem.y_sort_enabled]. @@ -521,7 +532,7 @@ - Sets the transform of the [CanvasItem]. It affects where and how the item will be drawn. Child canvas items' transforms are multiplied by their parent's transform. + Sets the [param transform] of the canvas item specified by the [param item] RID. This affects where and how the item will be drawn. Child canvas items' transforms are multiplied by their parent's transform. Equivalent to [member Node2D.transform]. @@ -588,7 +599,8 @@ Creates a canvas light and adds it to the RenderingServer. It can be accessed with the RID that is returned. This RID will be used in all [code]canvas_light_*[/code] RenderingServer functions. - Once finished with your RID, you will want to free the RID using the RenderingServer's [method free_rid] static method. + Once finished with your RID, you will want to free the RID using the RenderingServer's [method free_rid] method. + [b]Note:[/b] The equivalent node is [Light2D]. @@ -603,7 +615,8 @@ Creates a light occluder and adds it to the RenderingServer. It can be accessed with the RID that is returned. This RID will be used in all [code]canvas_light_occluder_*[/code] RenderingServer functions. - Once finished with your RID, you will want to free the RID using the RenderingServer's [method free_rid] static method. + Once finished with your RID, you will want to free the RID using the RenderingServer's [method free_rid] method. + [b]Note:[/b] The equivalent node is [LightOccluder2D]. @@ -795,7 +808,8 @@ Creates a new light occluder polygon and adds it to the RenderingServer. It can be accessed with the RID that is returned. This RID will be used in all [code]canvas_occluder_polygon_*[/code] RenderingServer functions. - Once finished with your RID, you will want to free the RID using the RenderingServer's [method free_rid] static method. + Once finished with your RID, you will want to free the RID using the RenderingServer's [method free_rid] method. + [b]Note:[/b] The equivalent resource is [OccluderPolygon2D]. @@ -842,14 +856,15 @@ + Sets the [member ProjectSettings.rendering/2d/shadow_atlas/size] to use for [Light2D] shadow rendering (in pixels). The value is rounded up to the nearest power of 2. Creates a canvas texture and adds it to the RenderingServer. It can be accessed with the RID that is returned. This RID will be used in all [code]canvas_texture_*[/code] RenderingServer functions. - Once finished with your RID, you will want to free the RID using the RenderingServer's [method free_rid] static method. - This is the internal equivalent of the [CanvasTexture] resource. + Once finished with your RID, you will want to free the RID using the RenderingServer's [method free_rid] method. See also [method texture_2d_create]. + [b]Note:[/b] The equivalent resource is [CanvasTexture] and is only meant to be used in 2D rendering, not 3D. @@ -858,6 +873,7 @@ + Sets the [param channel]'s [param texture] for the canvas texture specified by the [param canvas_texture] RID. Equivalent to [member CanvasTexture.diffuse_texture], [member CanvasTexture.normal_texture] and [member CanvasTexture.specular_texture]. @@ -866,6 +882,7 @@ + Sets the [param base_color] and [param shininess] to use for the canvas texture specified by the [param canvas_texture] RID. Equivalent to [member CanvasTexture.specular_color] and [member CanvasTexture.specular_shininess]. @@ -873,7 +890,7 @@ - Sets the texture filter used by the [CanvasTexture]. + Sets the texture [param filter] mode to use for the canvas texture specified by the [param canvas_texture] RID. @@ -881,7 +898,7 @@ - Sets the texture repeat used by the [CanvasTexture]. + Sets the texture [param repeat] mode to use for the canvas texture specified by the [param canvas_texture] RID. @@ -895,8 +912,9 @@ Creates a decal and adds it to the RenderingServer. It can be accessed with the RID that is returned. This RID will be used in all [code]decal_*[/code] RenderingServer functions. - Once finished with your RID, you will want to free the RID using the RenderingServer's [method free_rid] static method. - This is the internal equivalent of the [Decal] node. + Once finished with your RID, you will want to free the RID using the RenderingServer's [method free_rid] method. + To place in a scene, attach this decal to an instance using [method instance_set_base] using the returned RID. + [b]Note:[/b] The equivalent node is [Decal]. @@ -904,6 +922,7 @@ + Sets the [param albedo_mix] in the decal specified by the [param decal] RID. Equivalent to [member Decal.albedo_mix]. @@ -911,6 +930,7 @@ + Sets the cull [param mask] in the decal specified by the [param decal] RID. Equivalent to [member Decal.cull_mask]. @@ -920,6 +940,7 @@ + Sets the distance fade parameters in the decal specified by the [param decal] RID. Equivalent to [member Decal.distance_fade_enabled], [member Decal.distance_fade_begin] and [member Decal.distance_fade_length]. @@ -927,6 +948,7 @@ + Sets the emission [param energy] in the decal specified by the [param decal] RID. Equivalent to [member Decal.emission_energy]. @@ -935,6 +957,7 @@ + Sets the upper fade ([param above]) and lower fade ([param below]) in the decal specified by the [param decal] RID. Equivalent to [member Decal.upper_fade] and [member Decal.lower_fade]. @@ -942,7 +965,7 @@ - Sets the color modulation of the [Decal]. + Sets the color multiplier in the decal specified by the [param decal] RID to [param color]. Equivalent to [member Decal.modulate]. @@ -950,6 +973,7 @@ + Sets the normal [param fade] in the decal specified by the [param decal] RID. Equivalent to [member Decal.normal_fade]. @@ -957,7 +981,7 @@ - Sets the size of the [Decal]. + Sets the [param size] of the decal specified by the [param decal] RID. Equivalent to [member Decal.size]. @@ -966,22 +990,23 @@ - Sets the texture of the [Decal]. + Sets the [param texture] in the given texture [param type] slot for the specified decal. Equivalent to [method Decal.set_texture]. + Sets the texture [param filter] mode to use when rendering decals. This parameter is global and cannot be set on a per-decal basis. Creates a directional light and adds it to the RenderingServer. It can be accessed with the RID that is returned. This RID can be used in most [code]light_*[/code] RenderingServer functions. - Once finished with your RID, you will want to free the RID using the RenderingServer's [method free_rid] static method. + Once finished with your RID, you will want to free the RID using the RenderingServer's [method free_rid] method. To place in a scene, attach this directional light to an instance using [method instance_set_base] using the returned RID. - This is the internal equivalent of the [DirectionalLight3D] node. + [b]Note:[/b] The equivalent node is [DirectionalLight3D]. @@ -989,12 +1014,14 @@ + Sets the [param size] of the directional light shadows in 3D. See also [member ProjectSettings.rendering/lights_and_shadows/directional_shadow/size]. This parameter is global and cannot be set on a per-viewport basis. + Sets the filter [param quality] for directional light shadows in 3D. See also [member ProjectSettings.rendering/lights_and_shadows/directional_shadow/soft_shadow_filter_quality]. This parameter is global and cannot be set on a per-viewport basis. @@ -1003,20 +1030,24 @@ + Generates and returns an [Image] containing the radiance map for the specified [param environment] RID's sky. This supports built-in sky material and custom sky shaders. If [param bake_irradiance] is [code]true[/code], the irradiance map is saved instead of the radiance map. The radiance map is used to render reflected light, while the irradiance map is used to render ambient light. See also [method sky_bake_panorama]. + [b]Note:[/b] The image is saved in linear color space without any tonemapping performed, which means it will look too dark if viewed directly in an image editor. + [b]Note:[/b] [param size] should be a 2:1 aspect ratio for the generated panorama to have square pixels. For radiance maps, there is no point in using a height greater than [member Sky.radiance_size], as it won't increase detail. Irradiance maps only contain low-frequency data, so there is usually no point in going past a size of 128×64 pixels when saving an irradiance map. Creates an environment and adds it to the RenderingServer. It can be accessed with the RID that is returned. This RID will be used in all [code]environment_*[/code] RenderingServer functions. - Once finished with your RID, you will want to free the RID using the RenderingServer's [method free_rid] static method. - This is the internal equivalent of the [Environment] resource. + Once finished with your RID, you will want to free the RID using the RenderingServer's [method free_rid] method. + [b]Note:[/b] The equivalent resource is [Environment]. + If [param enable] is [code]true[/code], enables bicubic upscaling for glow which improves quality at the cost of performance. Equivalent to [member ProjectSettings.rendering/environment/glow/upscale_mode]. @@ -1029,7 +1060,7 @@ - Sets the values to be used with the "Adjustment" post-process effect. See [Environment] for more details. + Sets the values to be used with the "adjustments" post-process effect. See [Environment] for more details. @@ -1041,6 +1072,7 @@ + Sets the values to be used for ambient light rendering. See [Environment] for more details. @@ -1048,7 +1080,7 @@ - Sets the [i]BGMode[/i] of the environment. Equivalent to [member Environment.background_mode]. + Sets the environment's background mode. Equivalent to [member Environment.background_mode]. @@ -1056,7 +1088,7 @@ - Color displayed for clear areas of the scene (if using Custom color or Color+Sky background modes). + Color displayed for clear areas of the scene. Only effective if using the [constant ENV_BG_COLOR] background mode. @@ -1089,6 +1121,7 @@ + Configures fog for the specified environment RID. See [code]fog_*[/code] properties in [Environment] for more information. @@ -1107,6 +1140,7 @@ + Configures glow for the specified environment RID. See [code]glow_*[/code] properties in [Environment] for more information. @@ -1123,24 +1157,28 @@ + Configures signed distance field global illumination for the specified environment RID. See [code]sdfgi_*[/code] properties in [Environment] for more information. + Sets the number of frames to use for converging signed distance field global illumination. Equivalent to [member ProjectSettings.rendering/global_illumination/sdfgi/frames_to_converge]. + Sets the update speed for dynamic lights' indirect lighting when computing signed distance field global illumination. Equivalent to [member ProjectSettings.rendering/global_illumination/sdfgi/frames_to_update_lights]. + Sets the number of rays to throw per frame when computing signed distance field global illumination. Equivalent to [member ProjectSettings.rendering/global_illumination/sdfgi/probe_ray_count]. @@ -1216,7 +1254,7 @@ - Sets the variables to be used with the "screen space reflections" post-process effect. See [Environment] for more details. + Sets the variables to be used with the screen-space reflections (SSR) post-process effect. See [Environment] for more details. @@ -1252,6 +1290,7 @@ + Sets the variables to be used with the volumetric fog post-process effect. See [Environment] for more details. @@ -1272,9 +1311,9 @@ - Creates a fog volume and adds it to the RenderingServer. It can be accessed with the RID that is returned. This RID will be used in all [code]fog_volume_*[/code] RenderingServer functions. - Once finished with your RID, you will want to free the RID using the RenderingServer's [method free_rid] static method. - This is the internal equivalent of the [FogVolume] node. + Creates a new fog volume and adds it to the RenderingServer. It can be accessed with the RID that is returned. This RID will be used in all [code]fog_volume_*[/code] RenderingServer functions. + Once finished with your RID, you will want to free the RID using the RenderingServer's [method free_rid] method. + [b]Note:[/b] The equivalent node is [FogVolume]. @@ -1306,29 +1345,32 @@ + Forces redrawing of all viewports at once. + Forces a synchronization between the CPU and GPU, which may be required in certain cases. Only call this when needed, as CPU-GPU synchronization has a performance cost. - Tries to free an object in the RenderingServer. + Tries to free an object in the RenderingServer. To avoid memory leaks, this should be called after using an object as memory management does not occur automatically when using RendeeringServer directly. - Returns the default clear color which is used when a specific clear color has not been selected. + Returns the default clear color which is used when a specific clear color has not been selected. See also [method set_default_clear_color]. + Returns the time taken to setup rendering on the CPU in milliseconds. This value is shared across all viewports and does [i]not[/i] require [method viewport_set_measure_render_time] to be enabled on a viewport to be queried. See also [method viewport_get_measured_render_time_cpu]. @@ -1342,6 +1384,16 @@ + Returns a statistic about the rendering engine which can be used for performance profiling. See [enum RenderingServer.RenderingInfo] for a list of values that can be queried. See also [method viewport_get_render_info], which retruns information specific to a viewport. + [b]Note:[/b] Only 3D rendering is currently taken into account by some of these values, such as the number of draw calls. + [b]Note:[/b] Rendering information is not available until at least 2 frames have been rendered by the engine. If rendering information is not available, [method get_rendering_info] returns [code]0[/code]. To print rendering information in [code]_ready()[/code] successfully, use the following: + [codeblock] + func _ready(): + for _i in 2: + await get_tree().process_frame + + print(RenderingServer.get_rendering_info(RENDERING_INFO_TOTAL_DRAW_CALLS_IN_FRAME)) + [/codeblock] @@ -1354,19 +1406,25 @@ - Returns the ID of the test cube. Creates one if none exists. + Returns the RID of the test cube. This mesh will be created and returned on the first call to [method get_test_cube], then it will be cached for subsequent calls. See also [method make_sphere_mesh]. - Returns the ID of the test texture. Creates one if none exists. + Returns the RID of a 256×256 texture with a testing pattern on it (in [constant Image.FORMAT_RGB8] format). This texture will be created and returned on the first call to [method get_test_texture], then it will be cached for subsequent calls. See also [method get_white_texture]. + Example of getting the test texture and applying it to a [Sprite2D] node: + [codeblock] + var texture_rid = RenderingServer.get_test_texture() + var texture = ImageTexture.create_from_image(RenderingServer.texture_2d_get(texture_rid)) + $Sprite2D.texture = texture + [/codeblock] - Returns the version of the graphics video adapter [i]currently in use[/i] (e.g. "1.2.189" for Vulkan, "3.3.0 NVIDIA 510.60.02" for OpenGL). This version may be different from the actual latest version supported by the hardware, as Godot may not always request the latest version. + Returns the version of the graphics video adapter [i]currently in use[/i] (e.g. "1.2.189" for Vulkan, "3.3.0 NVIDIA 510.60.02" for OpenGL). This version may be different from the actual latest version supported by the hardware, as Godot may not always request the latest version. See also [method OS.get_video_adapter_driver_info]. [b]Note:[/b] When running a headless or server binary, this function returns an empty string. @@ -1394,14 +1452,20 @@ - Returns the ID of a white texture. Creates one if none exists. + Returns the ID of a 4×4 white texture (in [constant Image.FORMAT_RGB8] format). This texture will be created and returned on the first call to [method get_white_texture], then it will be cached for subsequent calls. See also [method get_test_texture]. + Example of getting the white texture and applying it to a [Sprite2D] node: + [codeblock] + var texture_rid = RenderingServer.get_white_texture() + var texture = ImageTexture.create_from_image(RenderingServer.texture_2d_get(texture_rid)) + $Sprite2D.texture = texture + [/codeblock] - If [param half_resolution] is [code]true[/code], renders [VoxelGI] and SDFGI ([member Environment.sdfgi_enabled]) buffers at halved resolution (e.g. 960×540 when the viewport size is 1920×1080). This improves performance significantly when VoxelGI or SDFGI is enabled, at the cost of artifacts that may be visible on polygon edges. The loss in quality becomes less noticeable as the viewport resolution increases. [LightmapGI] rendering is not affected by this setting. See also [member ProjectSettings.rendering/global_illumination/gi/use_half_resolution]. + If [param half_resolution] is [code]true[/code], renders [VoxelGI] and SDFGI ([member Environment.sdfgi_enabled]) buffers at halved resolution on each axis (e.g. 960×540 when the viewport size is 1920×1080). This improves performance significantly when VoxelGI or SDFGI is enabled, at the cost of artifacts that may be visible on polygon edges. The loss in quality becomes less noticeable as the viewport resolution increases. [LightmapGI] rendering is not affected by this setting. Equivalent to [member ProjectSettings.rendering/global_illumination/gi/use_half_resolution]. @@ -1410,29 +1474,38 @@ + Creates a new global shader uniform. + [b]Note:[/b] Global shader parameter names are case-sensitive. + Returns the value of the global shader uniform specified by [param name]. + [b]Note:[/b] [method global_shader_parameter_get] has a large performance penalty as the rendering thread needs to synchronize with the calling thread, which is slow. Do not use this method during gameplay to avoid stuttering. If you need to read values in a script after setting them, consider creating an autoload where you store the values you need to query at the same time you're setting them as global parameters. + Returns the list of global shader uniform names. + [b]Note:[/b] [method global_shader_parameter_get] has a large performance penalty as the rendering thread needs to synchronize with the calling thread, which is slow. Do not use this method during gameplay to avoid stuttering. If you need to read values in a script after setting them, consider creating an autoload where you store the values you need to query at the same time you're setting them as global parameters. + Returns the type associated to the global shader uniform specified by [param name]. + [b]Note:[/b] [method global_shader_parameter_get] has a large performance penalty as the rendering thread needs to synchronize with the calling thread, which is slow. Do not use this method during gameplay to avoid stuttering. If you need to read values in a script after setting them, consider creating an autoload where you store the values you need to query at the same time you're setting them as global parameters. + Removes the global shader uniform specified by [param name]. @@ -1440,6 +1513,7 @@ + Sets the global shader uniform [param name] to [param value]. @@ -1447,6 +1521,7 @@ + Overrides the global shader uniform [param name] with [param value]. Equivalent to the [ShaderGlobalsOverride] node. @@ -1489,9 +1564,9 @@ Creates a visual instance and adds it to the RenderingServer. It can be accessed with the RID that is returned. This RID will be used in all [code]instance_*[/code] RenderingServer functions. - Once finished with your RID, you will want to free the RID using the RenderingServer's [method free_rid] static method. - An instance is a way of placing a 3D object in the scenario. Objects like particles, meshes, and reflection probes need to be associated with an instance to be visible in the scenario using [method instance_set_base]. - This is the internal equivalent of the [VisualInstance3D] node. + Once finished with your RID, you will want to free the RID using the RenderingServer's [method free_rid] method. + An instance is a way of placing a 3D object in the scenario. Objects like particles, meshes, reflection probes and decals need to be associated with an instance to be visible in the scenario using [method instance_set_base]. + [b]Note:[/b] The equivalent node is [VisualInstance3D]. @@ -1500,7 +1575,7 @@ Creates a visual instance, adds it to the RenderingServer, and sets both base and scenario. It can be accessed with the RID that is returned. This RID will be used in all [code]instance_*[/code] RenderingServer functions. - Once finished with your RID, you will want to free the RID using the RenderingServer's [method free_rid] static method. + Once finished with your RID, you will want to free the RID using the RenderingServer's [method free_rid] method. This is a shorthand for using [method instance_create] and setting the base and scenario manually. @@ -1508,6 +1583,8 @@ + Returns the value of the per-instance shader uniform from the specified 3D geometry instance. Equivalent to [method GeometryInstance3D.get_instance_shader_parameter]. + [b]Note:[/b] Per-instance shader parameter names are case-sensitive. @@ -1515,12 +1592,14 @@ + Returns the default value of the per-instance shader uniform from the specified 3D geometry instance. Equivalent to [method GeometryInstance3D.get_instance_shader_parameter]. + Returns a dictionary of per-instance shader uniform names of the per-instance shader uniform from the specified 3D geometry instance. The returned dictionary is in PropertyInfo format, with the keys [code]name[/code], [code]class_name[/code], [code]type[/code], [code]hint[/code], [code]hint_string[/code] and [code]usage[/code]. Equivalent to [method GeometryInstance3D.get_instance_shader_parameter]. @@ -1547,6 +1626,7 @@ + Sets the lightmap GI instance to use for the specified 3D geometry instance. The lightmap UV scale for the specified instance (equivalent to [member GeometryInstance3D.gi_lightmap_scale]) and lightmap atlas slice must also be specified. @@ -1554,6 +1634,7 @@ + Sets the level of detail bias to use when rendering the specified 3D geometry instance. Higher values result in higher detail from further away. Equivalent to [member GeometryInstance3D.lod_bias]. @@ -1578,6 +1659,7 @@ + Sets the per-instance shader uniform on the specified 3D geometry instance. Equivalent to [method GeometryInstance3D.set_instance_shader_parameter]. @@ -1608,7 +1690,7 @@ - Sets the base of the instance. A base can be any of the 3D objects that are created in the RenderingServer that can be displayed. For example, any of the light types, mesh, multimesh, immediate geometry, particle system, reflection probe, lightmap, and the GI probe are all types that can be set as the base of an instance in order to be displayed in the scenario. + Sets the base of the instance. A base can be any of the 3D objects that are created in the RenderingServer that can be displayed. For example, any of the light types, mesh, multimesh, particle system, reflection probe, decal, lightmap, voxel GI and visibility notifiers are all types that can be set as the base of an instance in order to be displayed in the scenario. @@ -1641,6 +1723,7 @@ + If [code]true[/code], ignores both frustum and occlusion culling on the specified 3D geometry instance. This is not the same as [member GeometryInstance3D.ignore_occlusion_culling], which only ignores occlusion culling and leaves frustum culling intact. @@ -1706,7 +1789,7 @@ - Returns an array of object IDs intersecting with the provided AABB. Only visual 3D nodes are considered, such as [MeshInstance3D] or [DirectionalLight3D]. Use [method @GlobalScope.instance_from_id] to obtain the actual nodes. A scenario RID must be provided, which is available in the [World3D] you want to query. This forces an update for all resources queued to update. + Returns an array of object IDs intersecting with the provided AABB. Only 3D nodes that inherit from [VisualInstance3D] are considered, such as [MeshInstance3D] or [DirectionalLight3D]. Use [method @GlobalScope.instance_from_id] to obtain the actual nodes. A scenario RID must be provided, which is available in the [World3D] you want to query. This forces an update for all resources queued to update. [b]Warning:[/b] This function is primarily intended for editor usage. For in-game use cases, prefer physics collision. @@ -1715,7 +1798,7 @@ - Returns an array of object IDs intersecting with the provided convex shape. Only visual 3D nodes are considered, such as [MeshInstance3D] or [DirectionalLight3D]. Use [method @GlobalScope.instance_from_id] to obtain the actual nodes. A scenario RID must be provided, which is available in the [World3D] you want to query. This forces an update for all resources queued to update. + Returns an array of object IDs intersecting with the provided convex shape. Only 3D nodes that inherit from [VisualInstance3D] are considered, such as [MeshInstance3D] or [DirectionalLight3D]. Use [method @GlobalScope.instance_from_id] to obtain the actual nodes. A scenario RID must be provided, which is available in the [World3D] you want to query. This forces an update for all resources queued to update. [b]Warning:[/b] This function is primarily intended for editor usage. For in-game use cases, prefer physics collision. @@ -1725,7 +1808,7 @@ - Returns an array of object IDs intersecting with the provided 3D ray. Only visual 3D nodes are considered, such as [MeshInstance3D] or [DirectionalLight3D]. Use [method @GlobalScope.instance_from_id] to obtain the actual nodes. A scenario RID must be provided, which is available in the [World3D] you want to query. This forces an update for all resources queued to update. + Returns an array of object IDs intersecting with the provided 3D ray. Only 3D nodes that inherit from [VisualInstance3D] are considered, such as [MeshInstance3D] or [DirectionalLight3D]. Use [method @GlobalScope.instance_from_id] to obtain the actual nodes. A scenario RID must be provided, which is available in the [World3D] you want to query. This forces an update for all resources queued to update. [b]Warning:[/b] This function is primarily intended for editor usage. For in-game use cases, prefer physics collision. @@ -1765,6 +1848,7 @@ + Sets the texture filter mode to use when rendering light projectors. This parameter is global and cannot be set on a per-light basis. @@ -1772,6 +1856,7 @@ + Sets the bake mode to use for the specified 3D light. Equivalent to [member Light3D.light_bake_mode]. @@ -1787,7 +1872,7 @@ - Sets the cull mask for this Light3D. Lights only affect objects in the selected layers. Equivalent to [member Light3D.light_cull_mask]. + Sets the cull mask for this 3D light. Lights only affect objects in the selected layers. Equivalent to [member Light3D.light_cull_mask]. @@ -1798,7 +1883,7 @@ - Sets the distance fade for this Light3D. This acts as a form of level of detail (LOD) and can be used to improve performance. Equivalent to [member Light3D.distance_fade_enabled], [member Light3D.distance_fade_begin], [member Light3D.distance_fade_shadow], and [member Light3D.distance_fade_length]. + Sets the distance fade for this 3D light. This acts as a form of level of detail (LOD) and can be used to improve performance. Equivalent to [member Light3D.distance_fade_enabled], [member Light3D.distance_fade_begin], [member Light3D.distance_fade_shadow], and [member Light3D.distance_fade_length]. @@ -1806,6 +1891,7 @@ + Sets the maximum SDFGI cascade in which the 3D light's indirect lighting is rendered. Higher values allow the light to be rendered in SDFGI further away from the camera. @@ -1813,7 +1899,7 @@ - If [code]true[/code], light will subtract light instead of adding light. Equivalent to [member Light3D.light_negative]. + If [code]true[/code], the 3D light will subtract light instead of adding light. Equivalent to [member Light3D.light_negative]. @@ -1822,7 +1908,7 @@ - Sets the specified light parameter. See [enum LightParam] for options. Equivalent to [method Light3D.set_param]. + Sets the specified 3D light parameter. See [enum LightParam] for options. Equivalent to [method Light3D.set_param]. @@ -1830,7 +1916,7 @@ - Not implemented in Godot 3.x. + Sets the projector texture to use for the specified 3D light. Equivalent to [member Light3D.light_projector]. @@ -1852,9 +1938,9 @@ - Creates a lightmap GI and adds it to the RenderingServer. It can be accessed with the RID that is returned. This RID will be used in all [code]lightmap_*[/code] RenderingServer functions. - Once finished with your RID, you will want to free the RID using the RenderingServer's [method free_rid] static method. - This is the internal equivalent of the [LightmapGI] node. + Creates a new lightmap global illumination instance and adds it to the RenderingServer. It can be accessed with the RID that is returned. This RID will be used in all [code]lightmap_*[/code] RenderingServer functions. + Once finished with your RID, you will want to free the RID using the RenderingServer's [method free_rid] method. + [b]Note:[/b] The equivalent node is [LightmapGI]. @@ -1925,6 +2011,7 @@ + Set the textures on the given [param lightmap] GI instance to the texture array pointed to by the [param light] RID. If the lightmap texture was baked with [member LightmapGI.directional] set to [code]true[/code], then [param uses_sh] must also be [code]true[/code]. @@ -1933,15 +2020,15 @@ - Returns a mesh of a sphere with the given number of horizontal and vertical subdivisions. + Returns a mesh of a sphere with the given number of horizontal subdivisions, vertical subdivisions and radius. See also [method get_test_cube]. Creates an empty material and adds it to the RenderingServer. It can be accessed with the RID that is returned. This RID will be used in all [code]material_*[/code] RenderingServer functions. - Once finished with your RID, you will want to free the RID using the RenderingServer's [method free_rid] static method. - This is the internal equivalent of the [Material] resource. + Once finished with your RID, you will want to free the RID using the RenderingServer's [method free_rid] method. + [b]Note:[/b] The equivalent resource is [Material]. @@ -2014,9 +2101,9 @@ Creates a new mesh and adds it to the RenderingServer. It can be accessed with the RID that is returned. This RID will be used in all [code]mesh_*[/code] RenderingServer functions. - Once finished with your RID, you will want to free the RID using the RenderingServer's [method free_rid] static method. + Once finished with your RID, you will want to free the RID using the RenderingServer's [method free_rid] method. To place in a scene, attach this mesh to an instance using [method instance_set_base] using the returned RID. - This is the internal equivalent of the [Mesh] resource. + [b]Note:[/b] The equivalent resource is [Mesh]. @@ -2187,9 +2274,9 @@ Creates a new multimesh on the RenderingServer and returns an [RID] handle. This RID will be used in all [code]multimesh_*[/code] RenderingServer functions. - Once finished with your RID, you will want to free the RID using the RenderingServer's [method free_rid] static method. + Once finished with your RID, you will want to free the RID using the RenderingServer's [method free_rid] method. To place in a scene, attach this multimesh to an instance using [method instance_set_base] using the returned RID. - This is the internal equivalent of the [MultiMesh] resource. + [b]Note:[/b] The equivalent resource is [MultiMesh]. @@ -2203,6 +2290,8 @@ + Returns the MultiMesh data (such as instance transforms, colors, etc). See [method multimesh_set_buffer] for a description of the returned data. + [b]Note:[/b] If the buffer is in the engine's internal cache, it will have to be fetched from GPU memory and possibly decompressed. This means [method multimesh_get_buffer] is potentially a slow operation and should be avoided whenever possible. @@ -2299,6 +2388,20 @@ + Set the entire data to use for drawing the [param multimesh] at once to [param buffer] (such as instance transforms and colors). [param buffer]'s size must match the number of instances multiplied by the per-instance data size (which depends on the enabled MultiMesh fields). Otherwise, an error message is printed and nothing is rendered. See also [method multimesh_get_buffer]. + The per-instance data size and expected data order is: + [codeblock] + 2D: + - Position: 8 floats (8 floats for Transform2D) + - Position + Vertex color: 12 floats (8 floats for Transform2D, 4 floats for Color) + - Position + Custom data: 12 floats (8 floats for Transform2D, 4 floats of custom data) + - Position + Vertex color + Custom data: 16 floats (8 floats for Transform2D, 4 floats for Color, 4 floats of custom data) + 3D: + - Position: 12 floats (12 floats for Transform3D) + - Position + Vertex color: 16 floats (12 floats for Transform3D, 4 floats for Color) + - Position + Custom data: 16 floats (12 floats for Transform3D, 4 floats of custom data) + - Position + Vertex color + Custom data: 20 floats (12 floats for Transform3D, 4 floats for Color, 4 floats of custom data) + [/codeblock] @@ -2320,6 +2423,9 @@ + Creates an occluder instance and adds it to the RenderingServer. It can be accessed with the RID that is returned. This RID will be used in all [code]occluder_*[/code] RenderingServer functions. + Once finished with your RID, you will want to free the RID using the RenderingServer's [method free_rid] method. + [b]Note:[/b] The equivalent resource is [Occluder3D] (not to be confused with the [OccluderInstance3D] node). @@ -2328,25 +2434,30 @@ + Sets the mesh data for the given occluder RID, which controls the shape of the occlusion culling that will be performed. Creates a new omni light and adds it to the RenderingServer. It can be accessed with the RID that is returned. This RID can be used in most [code]light_*[/code] RenderingServer functions. - Once finished with your RID, you will want to free the RID using the RenderingServer's [method free_rid] static method. + Once finished with your RID, you will want to free the RID using the RenderingServer's [method free_rid] method. To place in a scene, attach this omni light to an instance using [method instance_set_base] using the returned RID. + [b]Note:[/b] The equivalent node is [OmniLight3D]. + Creates a new 3D GPU particle collision or attractor and adds it to the RenderingServer. It can be accessed with the RID that is returned. This RID can be used in most [code]particles_collision_*[/code] RenderingServer functions. + [b]Note:[/b] The equivalent nodes are [GPUParticlesCollision3D] and [GPUParticlesAttractor3D]. + Requests an update for the 3D GPU particle collision heightfield. This may be automatically called by the 3D GPU particle collision heightfield depending on its [member GPUParticlesCollisionHeightField3D.update_mode]. @@ -2354,6 +2465,7 @@ + Sets the attenuation [param curve] for the 3D GPU particles attractor specified by the [param particles_collision] RID. Only used for attractors, not colliders. Equivalent to [member GPUParticlesAttractor3D.attenuation]. @@ -2361,6 +2473,7 @@ + Sets the directionality [param amount] for the 3D GPU particles attractor specified by the [param particles_collision] RID. Only used for attractors, not colliders. Equivalent to [member GPUParticlesAttractor3D.directionality]. @@ -2368,6 +2481,8 @@ + Sets the [param setrngth] for the 3D GPU particles attractor specified by the [param particles_collision] RID. Only used for attractors, not colliders. Equivalent to [member GPUParticlesAttractor3D.strength]. + [b]Note:[/b] The [param setrngth] parameter should be named "strength", but this typo was kept in the 4.0.x branch to preserve compatibility for C# and GDExtension. @@ -2375,6 +2490,7 @@ + Sets the [param extents] for the 3D GPU particles collision by the [param particles_collision] RID. Equivalent to [member GPUParticlesCollisionBox3D.size], [member GPUParticlesCollisionSDF3D.size], [member GPUParticlesCollisionHeightField3D.size], [member GPUParticlesAttractorBox3D.size] or [member GPUParticlesAttractorVectorField3D.size] depending on the [param particles_collision] type. @@ -2382,6 +2498,7 @@ + Sets the collision or attractor shape [param type] for the 3D GPU particles collision or attractor specified by the [param particles_collision] RID. @@ -2389,6 +2506,7 @@ + Sets the cull [param mask] for the 3D GPU particles collision or attractor specified by the [param particles_collision] RID. Equivalent to [member GPUParticlesCollision3D.cull_mask] or [member GPUParticlesAttractor3D.cull_mask] depending on the [param particles_collision] type. @@ -2396,6 +2514,7 @@ + Sets the signed distance field [param texture] for the 3D GPU particles collision specified by the [param particles_collision] RID. Equivalent to [member GPUParticlesCollisionSDF3D.texture] or [member GPUParticlesAttractorVectorField3D.texture] depending on the [param particles_collision] type. @@ -2403,6 +2522,7 @@ + Sets the heightmap [param resolution] for the 3D GPU particles heightfield collision specified by the [param particles_collision] RID. Equivalent to [member GPUParticlesCollisionHeightField3D.resolution]. @@ -2410,14 +2530,17 @@ + Sets the [param radius] for the 3D GPU particles sphere collision or attractor specified by the [param particles_collision] RID. Equivalent to [member GPUParticlesCollisionSphere3D.radius] or [member GPUParticlesAttractorSphere3D.radius] depending on the [param particles_collision] type. - Creates a particle system and adds it to the RenderingServer. It can be accessed with the RID that is returned. This RID will be used in all [code]particles_*[/code] RenderingServer functions. - Once finished with your RID, you will want to free the RID using the RenderingServer's [method free_rid] static method. + Creates a GPU-based particle system and adds it to the RenderingServer. It can be accessed with the RID that is returned. This RID will be used in all [code]particles_*[/code] RenderingServer functions. + Once finished with your RID, you will want to free the RID using the RenderingServer's [method free_rid] method. To place in a scene, attach these particles to an instance using [method instance_set_base] using the returned RID. + [b]Note:[/b] The equivalent nodes are [GPUParticles2D] and [GPUParticles3D]. + [b]Note:[/b] All [code]particles_*[/code] methods only apply to GPU-based particles, not CPU-based particles. [CPUParticles2D] and [CPUParticles3D] do not have equivalent RenderingServer functions available, as these use [MultiMeshInstance2D] and [MultiMeshInstance3D] under the hood (see [code]multimesh_*[/code] methods). @@ -2429,6 +2552,7 @@ + Manually emits particles from the [param particles] instance. @@ -2574,6 +2698,7 @@ + Sets whether the GPU particles specified by the [param particles] RID should be rendered in 2D or 3D according to [param mode]. @@ -2637,6 +2762,7 @@ + If [param enable] is [code]true[/code], enables trails for the [param particles] with the specified [param length_sec] in seconds. Equivalent to [member GPUParticles3D.trail_enabled] and [member GPUParticles3D.trail_lifetime]. @@ -2658,14 +2784,16 @@ + Sets the filter quality for omni and spot light shadows in 3D. See also [member ProjectSettings.rendering/lights_and_shadows/positional_shadow/soft_shadow_filter_quality]. This parameter is global and cannot be set on a per-viewport basis. Creates a reflection probe and adds it to the RenderingServer. It can be accessed with the RID that is returned. This RID will be used in all [code]reflection_probe_*[/code] RenderingServer functions. - Once finished with your RID, you will want to free the RID using the RenderingServer's [method free_rid] static method. + Once finished with your RID, you will want to free the RID using the RenderingServer's [method free_rid] method. To place in a scene, attach this reflection probe to an instance using [method instance_set_base] using the returned RID. + [b]Note:[/b] The equivalent node is [ReflectionProbe]. @@ -2673,6 +2801,7 @@ + Sets the reflection probe's custom ambient light color. Equivalent to [member ReflectionProbe.ambient_color]. @@ -2680,6 +2809,7 @@ + Sets the reflection probe's custom ambient light energy. Equivalent to [member ReflectionProbe.ambient_color_energy]. @@ -2687,6 +2817,7 @@ + Sets the reflection probe's ambient light mode. Equivalent to [member ReflectionProbe.ambient_mode]. @@ -2742,6 +2873,7 @@ + Sets the mesh level of detail to use in the reflection probe rendering. Higher values will use less detailed versions of meshes that have LOD variations generated, which can improve performance. Equivalent to [member ReflectionProbe.mesh_lod_threshold]. @@ -2757,6 +2889,7 @@ + Sets the resolution to use when rendering the specified reflection probe. The [param resolution] is specified for each cubemap face: for instance, specifying [code]512[/code] will allocate 6 faces of 512×512 each (plus mipmaps for roughness levels). @@ -2786,7 +2919,7 @@ Creates a scenario and adds it to the RenderingServer. It can be accessed with the RID that is returned. This RID will be used in all [code]scenario_*[/code] RenderingServer functions. - Once finished with your RID, you will want to free the RID using the RenderingServer's [method free_rid] static method. + Once finished with your RID, you will want to free the RID using the RenderingServer's [method free_rid] method. The scenario is the 3D world that all the visual instances exist in. @@ -2795,6 +2928,7 @@ + Sets the camera attributes ([param effects]) that will be used with this scenario. See also [CameraAttributes]. @@ -2802,7 +2936,7 @@ - Sets the environment that will be used with this scenario. + Sets the environment that will be used with this scenario. See also [Environment]. @@ -2819,6 +2953,7 @@ + Sets the screen-space roughness limiter parameters, such as whether it should be enabled and its thresholds. Equivalent to [member ProjectSettings.rendering/anti_aliasing/screen_space_roughness_limiter/enabled], [member ProjectSettings.rendering/anti_aliasing/screen_space_roughness_limiter/amount] and [member ProjectSettings.rendering/anti_aliasing/screen_space_roughness_limiter/limit]. @@ -2835,28 +2970,29 @@ - If [code]true[/code], the engine will generate wireframes for use with the wireframe debug mode. + This method is currently unimplemented and does nothing if called with [param generate] set to [code]true[/code]. - Sets the default clear color which is used when a specific clear color has not been selected. + Sets the default clear color which is used when a specific clear color has not been selected. See also [method get_default_clear_color]. Creates an empty shader and adds it to the RenderingServer. It can be accessed with the RID that is returned. This RID will be used in all [code]shader_*[/code] RenderingServer functions. - Once finished with your RID, you will want to free the RID using the RenderingServer's [method free_rid] static method. + Once finished with your RID, you will want to free the RID using the RenderingServer's [method free_rid] method. + [b]Note:[/b] The equivalent resource is [Shader]. - Returns a shader's code. + Returns a shader's source code as a string. @@ -2874,6 +3010,7 @@ + Returns the default value for the specified shader uniform. This is usually the value written in the shader source code. @@ -2881,6 +3018,7 @@ + Sets the shader's source code (which triggers recompilation after being changed). @@ -2899,6 +3037,7 @@ + Sets the path hint for the specified shader. This should generally match the [Shader] resource's [member Resource.resource_path]. @@ -2947,7 +3086,7 @@ Creates a skeleton and adds it to the RenderingServer. It can be accessed with the RID that is returned. This RID will be used in all [code]skeleton_*[/code] RenderingServer functions. - Once finished with your RID, you will want to free the RID using the RenderingServer's [method free_rid] static method. + Once finished with your RID, you will want to free the RID using the RenderingServer's [method free_rid] method. @@ -2971,13 +3110,16 @@ + Generates and returns an [Image] containing the radiance map for the specified [param sky] RID. This supports built-in sky material and custom sky shaders. If [param bake_irradiance] is [code]true[/code], the irradiance map is saved instead of the radiance map. The radiance map is used to render reflected light, while the irradiance map is used to render ambient light. See also [method environment_bake_panorama]. + [b]Note:[/b] The image is saved in linear color space without any tonemapping performed, which means it will look too dark if viewed directly in an image editor. [param energy] values above [code]1.0[/code] can be used to brighten the resulting image. + [b]Note:[/b] [param size] should be a 2:1 aspect ratio for the generated panorama to have square pixels. For radiance maps, there is no point in using a height greater than [member Sky.radiance_size], as it won't increase detail. Irradiance maps only contain low-frequency data, so there is usually no point in going past a size of 128×64 pixels when saving an irradiance map. Creates an empty sky and adds it to the RenderingServer. It can be accessed with the RID that is returned. This RID will be used in all [code]sky_*[/code] RenderingServer functions. - Once finished with your RID, you will want to free the RID using the RenderingServer's [method free_rid] static method. + Once finished with your RID, you will want to free the RID using the RenderingServer's [method free_rid] method. @@ -2985,7 +3127,7 @@ - Sets the material that the sky uses to render the background and reflection maps. + Sets the material that the sky uses to render the background, ambient and reflection maps. @@ -2993,6 +3135,7 @@ + Sets the process [param mode] of the sky specified by the [param sky] RID. Equivalent to [member Sky.process_mode]. @@ -3000,13 +3143,14 @@ + Sets the [param radiance_size] of the sky specified by the [param sky] RID (in pixels). Equivalent to [member Sky.radiance_size]. Creates a spot light and adds it to the RenderingServer. It can be accessed with the RID that is returned. This RID can be used in most [code]light_*[/code] RenderingServer functions. - Once finished with your RID, you will want to free the RID using the RenderingServer's [method free_rid] static method. + Once finished with your RID, you will want to free the RID using the RenderingServer's [method free_rid] method. To place in a scene, attach this spot light to an instance using [method instance_set_base] using the returned RID. @@ -3014,6 +3158,7 @@ + Sets [member ProjectSettings.rendering/environment/subsurface_scattering/subsurface_scattering_quality] to use when rendering materials that have subsurface scattering enabled. @@ -3021,18 +3166,30 @@ + Sets the [member ProjectSettings.rendering/environment/subsurface_scattering/subsurface_scattering_scale] and [member ProjectSettings.rendering/environment/subsurface_scattering/subsurface_scattering_depth_scale] to use when rendering materials that have subsurface scattering enabled. + Creates a 2-dimensional texture and adds it to the RenderingServer. It can be accessed with the RID that is returned. This RID will be used in all [code]texture_2d_*[/code] RenderingServer functions. + Once finished with your RID, you will want to free the RID using the RenderingServer's [method free_rid] method. + [b]Note:[/b] The equivalent resource is [Texture2D]. + [b]Note:[/b] Not to be confused with [method RenderingDevice.texture_create], which creates the graphics API's own texture type as opposed to the Godot-specific [Texture2D] resource. + Returns an [Image] instance from the given [param texture] [RID]. + Example of getting the test texture from [method get_test_texture] and applying it to a [Sprite2D] node: + [codeblock] + var texture_rid = RenderingServer.get_test_texture() + var texture = ImageTexture.create_from_image(RenderingServer.texture_2d_get(texture_rid)) + $Sprite2D.texture = texture + [/codeblock] @@ -3040,6 +3197,7 @@ + Returns an [Image] instance from the given [param texture] [RID] and [param layer]. @@ -3047,17 +3205,25 @@ + Creates a 2-dimensional layered texture and adds it to the RenderingServer. It can be accessed with the RID that is returned. This RID will be used in all [code]texture_2d_layered_*[/code] RenderingServer functions. + Once finished with your RID, you will want to free the RID using the RenderingServer's [method free_rid] method. + [b]Note:[/b] The equivalent resource is [TextureLayered]. + Creates a placeholder for a 2-dimensional layered texture and adds it to the RenderingServer. It can be accessed with the RID that is returned. This RID will be used in all [code]texture_2d_layered_*[/code] RenderingServer functions, although it does nothing when used. See also [method texture_2d_placeholder_create]. + [b]Note:[/b] The equivalent resource is [PlaceholderTextureLayered]. + Creates a placeholder for a 2-dimensional layered texture and adds it to the RenderingServer. It can be accessed with the RID that is returned. This RID will be used in all [code]texture_2d_layered_*[/code] RenderingServer functions, although it does nothing when used. See also [method texture_2d_layered_placeholder_create] + Once finished with your RID, you will want to free the RID using the RenderingServer's [method free_rid] method. + [b]Note:[/b] The equivalent resource is [PlaceholderTexture2D]. @@ -3066,6 +3232,8 @@ + Updates the texture specified by the [param texture] [RID] with the data in [param image]. A [param layer] must also be specified, which should be [code]0[/code] when updating a single-layer texture ([Texture2D]). + [b]Note:[/b] The [param image] must have the same width, height and format as the current [param texture] data. Otherwise, an error will be printed and the original texture won't be modified. If you need to use different width, height or format, use [method texture_replace] instead. @@ -3077,17 +3245,22 @@ + [b]Note:[/b] The equivalent resource is [Texture3D]. + Returns 3D texture data as an array of [Image]s for the specified texture [RID]. + Creates a placeholder for a 3-dimensional texture and adds it to the RenderingServer. It can be accessed with the RID that is returned. This RID will be used in all [code]texture_3d_*[/code] RenderingServer functions, although it does nothing when used. + Once finished with your RID, you will want to free the RID using the RenderingServer's [method free_rid] method. + [b]Note:[/b] The equivalent resource is [PlaceholderTexture3D]. @@ -3095,6 +3268,8 @@ + Updates the texture specified by the [param texture] [RID]'s data with the data in [param data]. All the texture's layers must be replaced at once. + [b]Note:[/b] The [param texture] must have the same width, height, depth and format as the current texture data. Otherwise, an error will be printed and the original texture won't be modified. If you need to use different width, height, depth or format, use [method texture_replace] instead. @@ -3115,6 +3290,7 @@ + [i]Deprecated.[/i] As ProxyTexture was removed in Godot 4, this method does nothing when called and always returns a null [RID]. @@ -3122,6 +3298,7 @@ + [i]Deprecated.[/i] ProxyTexture was removed in Godot 4, so this method cannot be used anymore. @@ -3129,6 +3306,7 @@ + Replaces [param texture]'s texture data by the texture specified by the [param by_texture] RID, without changing [param texture]'s RID. @@ -3192,19 +3370,25 @@ Creates an empty viewport and adds it to the RenderingServer. It can be accessed with the RID that is returned. This RID will be used in all [code]viewport_*[/code] RenderingServer functions. - Once finished with your RID, you will want to free the RID using the RenderingServer's [method free_rid] static method. + Once finished with your RID, you will want to free the RID using the RenderingServer's [method free_rid] method. + [b]Note:[/b] The equivalent node is [Viewport]. + Returns the CPU time taken to render the last frame in milliseconds. This [i]only[/i] includes time spent in rendering-related operations; scripts' [code]_process[/code] functions and other engine subsystems are not included in this readout. To get a complete readout of CPU time spent to render the scene, sum the render times of all viewports that are drawn every frame plus [method get_frame_setup_time_cpu]. Unlike [method Engine.get_frames_per_second], this method will accurately reflect CPU utilization even if framerate is capped via V-Sync or [member Engine.max_fps]. See also [method viewport_get_measured_render_time_gpu]. + [b]Note:[/b] Requires measurements to be enabled on the specified [param viewport] using [method viewport_set_measure_render_time]. Otherwise, this method returns [code]0.0[/code]. + Returns the GPU time taken to render the last frame in milliseconds. To get a complete readout of GPU time spent to render the scene, sum the render times of all viewports that are drawn every frame. Unlike [method Engine.get_frames_per_second], this method accurately reflects GPU utilization even if framerate is capped via V-Sync or [member Engine.max_fps]. See also [method viewport_get_measured_render_time_gpu]. + [b]Note:[/b] Requires measurements to be enabled on the specified [param viewport] using [method viewport_set_measure_render_time]. Otherwise, this method returns [code]0.0[/code]. + [b]Note:[/b] When GPU utilization is low enough during a certain period of time, GPUs will decrease their power state (which in turn decreases core and memory clock speeds). This can cause the reported GPU time to increase if GPU utilization is kept low enough by a framerate cap (compared to what it would be at the GPU's highest power state). Keep this in mind when benchmarking using [method viewport_get_measured_render_time_gpu]. This behavior can be overridden in the graphics driver settings at the cost of higher power usage. @@ -3213,6 +3397,20 @@ + Returns a statistic about the rendering engine which can be used for performance profiling. This is separated into render pass [param type]s, each of them having the same [param info]s you can query (different passes will return different values). See [enum RenderingServer.ViewportRenderInfoType] for a list of render pass types and [enum RenderingServer.ViewportRenderInfo] for a list of informations that can be queried. + See also [method get_rendering_info], which returns global information across all viewports. + [b]Note:[/b] Viewport rendering information is not available until at least 2 frames have been rendered by the engine. If rendering information is not available, [method viewport_get_render_info] returns [code]0[/code]. To print rendering information in [code]_ready()[/code] successfully, use the following: + [codeblock] + func _ready(): + for _i in 2: + await get_tree().process_frame + + print( + RenderingServer.viewport_get_render_info(get_viewport().get_viewport_rid(), + RenderingServer.VIEWPORT_RENDER_INFO_TYPE_VISIBLE, + RenderingServer.VIEWPORT_RENDER_INFO_DRAW_CALLS_IN_FRAME) + ) + [/codeblock] @@ -3294,6 +3492,7 @@ + Sets the default texture filtering mode for the specified [param viewport] RID. See [enum CanvasItemTextureFilter] for options. @@ -3301,6 +3500,7 @@ + Sets the default texture repeat mode for the specified [param viewport] RID. See [enum CanvasItemTextureRepeat] for options. @@ -3308,7 +3508,7 @@ - If [code]true[/code], the viewport's canvas is not rendered. + If [code]true[/code], the viewport's canvas (i.e. 2D and GUI elements) is not rendered. @@ -3316,6 +3516,7 @@ + If [code]true[/code], the viewport's 3D elements are not rendered. @@ -3347,6 +3548,7 @@ + Sets the measurement for the given [param viewport] RID (obtained using [method Viewport.get_viewport_rid]). Once enabled, [method viewport_get_measured_render_time_cpu] and [method viewport_get_measured_render_time_gpu] will return values greater than [code]0.0[/code] when queried with the given [param viewport]. @@ -3354,7 +3556,7 @@ - Sets the multisample anti-aliasing mode for 2D/Canvas. See [enum ViewportMSAA] for options. + Sets the multisample anti-aliasing mode for 2D/Canvas on the specified [param viewport] RID. See [enum ViewportMSAA] for options. @@ -3362,19 +3564,21 @@ - Sets the multisample anti-aliasing mode for 3D. See [enum ViewportMSAA] for options. + Sets the multisample anti-aliasing mode for 3D on the specified [param viewport] RID. See [enum ViewportMSAA] for options. + Sets the [member ProjectSettings.rendering/occlusion_culling/bvh_build_quality] to use for occlusion culling. This parameter is global and cannot be set on a per-viewport basis. + Sets the [member ProjectSettings.rendering/occlusion_culling/occlusion_rays_per_thread] to use for occlusion culling. This parameter is global and cannot be set on a per-viewport basis. @@ -3382,7 +3586,7 @@ - Sets the viewport's parent to another viewport. + Sets the viewport's parent to the viewport specified by the [param parent_viewport] RID. @@ -3391,7 +3595,7 @@ - Sets the shadow atlas quadrant's subdivision. + Sets the number of subdivisions to use in the specified shadow atlas [param quadrant] for omni and spot shadows. See also [method Viewport.set_positional_shadow_atlas_quadrant_subdiv]. @@ -3400,8 +3604,8 @@ - Sets the size of the shadow atlas's images (used for omni and spot lights). The value will be rounded up to the nearest power of 2. - [b]Note:[/b] If this is set to [code]0[/code], no shadows will be visible at all (including directional shadows). + Sets the [param size] of the shadow atlas's images (used for omni and spot lights) on the viewport specified by the [param viewport] RID. The value is rounded up to the nearest power of 2. If [code]use_16_bits[/code] is [code]true[/code], use 16 bits for the omni/spot shadow depth map. Enabling this results in shadows having less precision and may result in shadow acne, but can lead to performance improvements on some devices. + [b]Note:[/b] If this is set to [code]0[/code], no positional shadows will be visible at all. This can improve performance significantly on low-end systems by reducing both the CPU and GPU load (as fewer draw calls are needed to draw the scene without shadows). @@ -3417,7 +3621,7 @@ - Sets scaling 3d mode. Bilinear scaling renders at different resolution to either undersample or supersample the viewport. FidelityFX Super Resolution 1.0, abbreviated to FSR, is an upscaling technology that produces high quality images at fast framerates by using a spatially aware upscaling algorithm. FSR is slightly more expensive than bilinear, but it produces significantly higher image quality. FSR should be used where possible. + Sets the 3D resolution scaling mode. Bilinear scaling renders at different resolution to either undersample or supersample the viewport. FidelityFX Super Resolution 1.0, abbreviated to FSR, is an upscaling technology that produces high quality images at fast framerates by using a spatially aware upscaling algorithm. FSR is slightly more expensive than bilinear, but it produces significantly higher image quality. FSR should be used where possible. @@ -3434,8 +3638,7 @@ - Sets a viewport's scenario. - The scenario contains information about environment information, reflection atlas etc. + Sets a viewport's scenario. The scenario contains information about environment information, reflection atlas, etc. @@ -3443,6 +3646,7 @@ + Sets the viewport's screen-space antialiasing mode. @@ -3451,6 +3655,7 @@ + Sets the viewport's 2D signed distance field [member ProjectSettings.rendering/2d/sdf/oversize] and [member ProjectSettings.rendering/2d/sdf/scale]. This is used when sampling the signed distance field in [CanvasItem] shaders as well as [GPUParticles2D] collision. This is [i]not[/i] used by SDFGI in 3D rendering. @@ -3459,7 +3664,7 @@ - Sets the viewport's width and height. + Sets the viewport's width and height in pixels. @@ -3467,6 +3672,7 @@ + If [code]true[/code], canvas item transforms (i.e. origin position) are snapped to the nearest pixel when rendering. This can lead to a crisper appearance at the cost of less smooth movement, especially when [Camera2D] smoothing is enabled. Equivalent to [member ProjectSettings.rendering/2d/snap/snap_2d_transforms_to_pixel]. @@ -3474,6 +3680,7 @@ + If [code]true[/code], canvas item vertices (i.e. polygon points) are snapped to the nearest pixel when rendering. This can lead to a crisper appearance at the cost of less smooth movement, especially when [Camera2D] smoothing is enabled. Equivalent to [member ProjectSettings.rendering/2d/snap/snap_2d_vertices_to_pixel]. @@ -3506,6 +3713,7 @@ + If [code]true[/code], enables debanding on the specified viewport. Equivalent to [member ProjectSettings.rendering/anti_aliasing/quality/use_debanding]. @@ -3513,6 +3721,7 @@ + If [code]true[/code], enables occlusion culling on the specified viewport. Equivalent to [member ProjectSettings.rendering/occlusion_culling/use_occlusion_culling]. @@ -3520,7 +3729,7 @@ - If [code]true[/code], use Temporal Anti-Aliasing. + If [code]true[/code], use Temporal Anti-Aliasing. Equivalent to [member ProjectSettings.rendering/anti_aliasing/quality/use_taa]. @@ -3536,7 +3745,7 @@ - Sets the Variable Rate Shading (VRS) mode for the viewport. Note, if hardware does not support VRS this property is ignored. + Sets the Variable Rate Shading (VRS) mode for the viewport. If the GPU does not support VRS, this property is ignored. Equivalent to [member ProjectSettings.rendering/vrs/mode]. @@ -3544,12 +3753,16 @@ - Texture to use when the VRS mode is set to [constant RenderingServer.VIEWPORT_VRS_TEXTURE]. + The texture to use when the VRS mode is set to [constant RenderingServer.VIEWPORT_VRS_TEXTURE]. Equivalent to [member ProjectSettings.rendering/vrs/texture]. + Creates a new 3D visibility notifier object and adds it to the RenderingServer. It can be accessed with the RID that is returned. This RID will be used in all [code]visibility_notifier_*[/code] RenderingServer functions. + Once finished with your RID, you will want to free the RID using the RenderingServer's [method free_rid] method. + To place in a scene, attach this mesh to an instance using [method instance_set_base] using the returned RID. + [b]Note:[/b] The equivalent node is [VisibleOnScreenNotifier3D]. @@ -3583,6 +3796,9 @@ + Creates a new voxel-based global illumination object and adds it to the RenderingServer. It can be accessed with the RID that is returned. This RID will be used in all [code]voxel_gi_*[/code] RenderingServer functions. + Once finished with your RID, you will want to free the RID using the RenderingServer's [method free_rid] method. + [b]Note:[/b] The equivalent node is [VoxelGI]. @@ -3634,6 +3850,7 @@ + Sets the [member VoxelGIData.bias] value to use on the specified [param voxel_gi]'s [RID]. @@ -3641,6 +3858,7 @@ + Sets the [member VoxelGIData.dynamic_range] value to use on the specified [param voxel_gi]'s [RID]. @@ -3648,6 +3866,7 @@ + Sets the [member VoxelGIData.energy] value to use on the specified [param voxel_gi]'s [RID]. @@ -3655,6 +3874,7 @@ + Sets the [member VoxelGIData.interior] value to use on the specified [param voxel_gi]'s [RID]. @@ -3662,6 +3882,7 @@ + Sets the [member VoxelGIData.normal_bias] value to use on the specified [param voxel_gi]'s [RID]. @@ -3669,12 +3890,14 @@ + Sets the [member VoxelGIData.propagation] value to use on the specified [param voxel_gi]'s [RID]. + Sets the [member ProjectSettings.rendering/global_illumination/voxel_gi/quality] value to use when rendering. This parameter is global and cannot be set on a per-VoxelGI basis. @@ -3682,6 +3905,7 @@ + Sets the [member VoxelGIData.use_two_bounces] value to use on the specified [param voxel_gi]'s [RID]. @@ -3716,30 +3940,40 @@ The maximum Z-layer for canvas items. - Max number of glow levels that can be used with glow post-process effect. + The maximum number of glow levels that can be used with the glow post-processing effect. - Unused enum in Godot 3.x. + [i]Deprecated.[/i] This constant is unused. + The maximum number of directional lights that can be rendered at a given time in 2D. + Array of 2-dimensional textures (see [Texture2DArray]). + Cubemap texture (see [Cubemap]). + Array of cubemap textures (see [CubemapArray]). + Left face of a [Cubemap]. + Right face of a [Cubemap]. + Bottom face of a [Cubemap]. + Top face of a [Cubemap]. + Front face of a [Cubemap]. + Back face of a [Cubemap]. Shader is a 3D shader. @@ -3748,13 +3982,13 @@ Shader is a 2D shader. - Shader is a particle shader. + Shader is a particle shader (can be used in both 2D and 3D). - Shader is a sky shader. + Shader is a 3D sky shader. - Shader is a fog shader. + Shader is a 3D fog shader. Represents the size of the [enum ShaderMode] enum. @@ -3766,7 +4000,7 @@ The maximum renderpriority of all materials. - Array is a vertex array. + Array is a vertex position array. Array is a normal array. @@ -3775,21 +4009,25 @@ Array is a tangent array. - Array is a color array. + Array is a vertex color array. Array is an UV coordinates array. - Array is an UV coordinates array for the second UV coordinates. + Array is an UV coordinates array for the second set of UV coordinates. + Array is a custom data array for the first set of custom data. + Array is a custom data array for the second set of custom data. + Array is a custom data array for the third set of custom data. + Array is a custom data array for the fourth set of custom data. Array contains bone information. @@ -3798,33 +4036,43 @@ Array is weight information. - Array is index array. + Array is an index array. Represents the size of the [enum ArrayType] enum. + The number of custom data arrays available ([constant ARRAY_CUSTOM0], [constant ARRAY_CUSTOM1], [constant ARRAY_CUSTOM2], [constant ARRAY_CUSTOM3]). + Custom data array contains 8-bit-per-channel red/green/blue/alpha color data. Values are normalized, unsigned floating-point in the [code][0.0, 1.0][/code] range. + Custom data array contains 8-bit-per-channel red/green/blue/alpha color data. Values are normalized, signed floating-point in the [code][-1.0, 1.0][/code] range. + Custom data array contains 16-bit-per-channel red/green color data. Values are floating-point in half precision. + Custom data array contains 16-bit-per-channel red/green/blue/alpha color data. Values are floating-point in half precision. + Custom data array contains 32-bit-per-channel red color data. Values are floating-point in single precision. + Custom data array contains 32-bit-per-channel red/green color data. Values are floating-point in single precision. + Custom data array contains 32-bit-per-channel red/green/blue color data. Values are floating-point in single precision. + Custom data array contains 32-bit-per-channel red/green/blue/alpha color data. Values are floating-point in single precision. + Represents the size of the [enum ArrayCustomFormat] enum. - Flag used to mark a vertex array. + Flag used to mark a vertex position array. Flag used to mark a normal array. @@ -3833,7 +4081,7 @@ Flag used to mark a tangent array. - Flag used to mark a color array. + Flag used to mark a vertex color array. Flag used to mark an UV coordinates array. @@ -3842,12 +4090,16 @@ Flag used to mark an UV coordinates array for the second UV coordinates. + Flag used to mark an array of custom per-vertex data for the first set of custom data. + Flag used to mark an array of custom per-vertex data for the second set of custom data. + Flag used to mark an array of custom per-vertex data for the third set of custom data. + Flag used to mark an array of custom per-vertex data for the fourth set of custom data. Flag used to mark a bone information array. @@ -3882,6 +4134,7 @@ + Flag used to mark that the array uses 8 bone weighs instead of 4. @@ -3934,13 +4187,13 @@ Linear filter for light projectors (use for non-pixel art light projectors). Anisotropic mipmaps are used for rendering, which means light projectors at a distance will look smooth and sharp when viewed from oblique angles. This looks better compared to isotropic mipmaps, but is slower. The level of anisotropic filtering is defined by [member ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level]. - Is a directional (sun) light. + Directional (sun/moon) light (see [DirectionalLight3D]). - Is an omni light. + Omni light (see [OmniLight3D]). - Is a spot light. + Spot light (see [SpotLight3D]). The light's energy multiplier. @@ -3970,7 +4223,7 @@ The spotlight's attenuation. - Max distance that shadows will be rendered. + The maximum distance for shadow splits. Increasing this value will make directional shadows visible from further away, at the cost of lower overall shadow detail and performance (since more objects need to be included in the directional shadow rendering). Proportion of shadow atlas occupied by the first split. @@ -4005,10 +4258,13 @@ Represents the size of the [enum LightParam] enum. + Light is ignored when baking. This is the fastest mode, but the light will be taken into account when baking global illumination. This mode should generally be used for dynamic lights that change quickly, as the effect of global illumination is less noticeable on those lights. + Light is taken into account in static baking ([VoxelGI], [LightmapGI], SDFGI ([member Environment.sdfgi_enabled])). The light can be moved around or modified, but its global illumination will not update in real-time. This is suitable for subtle changes (such as flickering torches), but generally not large changes such as toggling a light on and off. + Light is taken into account in dynamic baking ([VoxelGI] and SDFGI ([member Environment.sdfgi_enabled]) only). The light can be moved around or modified with global illumination updating in real-time. The light's global illumination appearance will be slightly different compared to [constant LIGHT_BAKE_STATIC]. This has a greater performance cost compared to [constant LIGHT_BAKE_STATIC]. When using SDFGI, the update speed of dynamic lights is affected by [member ProjectSettings.rendering/global_illumination/sdfgi/frames_to_update_lights]. Use a dual paraboloid shadow map for omni lights. @@ -4054,6 +4310,7 @@ Highest low shadow filtering quality (slowest). When using this quality setting, [member Light3D.shadow_blur] is automatically multiplied by 2× to better make use of the high sample count. This increased blur also improves the stability of dynamic object shadows. This multiplier only applies to lights whose [member Light3D.light_size] or [member Light3D.light_angular_distance] is [code]0.0[/code]). + Represents the size of the [enum ShadowQuality] enum. Reflection probe will update reflections once and then stop. @@ -4062,20 +4319,28 @@ Reflection probe will update each frame. This mode is necessary to capture moving objects. + Do not apply any ambient lighting inside the reflection probe's box defined by its size. + Apply automatically-sourced environment lighting inside the reflection probe's box defined by its size. + Apply custom ambient lighting inside the reflection probe's box defined by its size. See [method reflection_probe_set_ambient_color] and [method reflection_probe_set_ambient_energy]. + Albedo texture slot in a decal ([member Decal.texture_albedo]). + Normal map texture slot in a decal ([member Decal.texture_normal]). + Occlusion/Roughness/Metallic texture slot in a decal ([member Decal.texture_orm]). + Emission texture slot in a decal ([member Decal.texture_emission]). + Represents the size of the [enum DecalTexture] enum. Nearest-neighbor filter for decals (use for pixel art decals). No mipmaps are used for rendering, which means decals at a distance will look sharp but grainy. This has roughly the same performance cost as using mipmaps. @@ -4096,12 +4361,16 @@ Linear filter for decals (use for non-pixel art decals). Anisotropic mipmaps are used for rendering, which means decals at a distance will look smooth and sharp when viewed from oblique angles. This looks better compared to isotropic mipmaps, but is slower. The level of anisotropic filtering is defined by [member ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level]. + Low [VoxelGI] rendering quality using 4 cones. + High [VoxelGI] rendering quality using 6 cones. + 2D particles. + 3D particles. @@ -4159,6 +4428,7 @@ + Represents the size of the [enum ParticlesCollisionHeightfieldResolution] enum. [FogVolume] will be shaped like an ellipsoid (stretched sphere). @@ -4176,6 +4446,7 @@ [FogVolume] will have no shape, will cover the whole world and will not be culled. + Represents the size of the [enum FogVolumeShape] enum. Use bilinear scaling for the viewport's 3D buffer. The amount of scaling can be set using [member Viewport.scaling_3d_scale]. Values less than [code]1.0[/code] will result in undersampling while values greater than [code]1.0[/code] will result in supersampling. A value of [code]1.0[/code] disables scaling. @@ -4184,29 +4455,31 @@ Use AMD FidelityFX Super Resolution 1.0 upscaling for the viewport's 3D buffer. The amount of scaling can be set using [member Viewport.scaling_3d_scale]. Values less than [code]1.0[/code] will be result in the viewport being upscaled using FSR. Values greater than [code]1.0[/code] are not supported and bilinear downsampling will be used instead. A value of [code]1.0[/code] disables scaling. + Represents the size of the [enum ViewportScaling3DMode] enum. - Do not update the viewport. + Do not update the viewport's render target. - Update the viewport once then set to disabled. + Update the viewport's render target once, then switch to [constant VIEWPORT_UPDATE_DISABLED]. - Update the viewport whenever it is visible. + Update the viewport's render target only when it is visible. This is the default value. + Update the viewport's render target only when its parent is visible. - Always update the viewport. + Always update the viewport's render target. - The viewport is always cleared before drawing. + Always clear the viewport's render target before drawing. - The viewport is never cleared before drawing. + Never clear the viewport's render target. - The viewport is cleared once, then the clear mode is set to [constant VIEWPORT_CLEAR_NEVER]. + Clear the viewport's render target on the next frame, then switch to [constant VIEWPORT_CLEAR_NEVER]. Disable rendering of 3D environment over 2D canvas. @@ -4215,28 +4488,37 @@ Enable rendering of 3D environment over 2D canvas. - Inherit enable/disable value from parent. If topmost parent is also set to inherit, then this has the same behavior as [constant VIEWPORT_ENVIRONMENT_ENABLED]. + Inherit enable/disable value from parent. If the topmost parent is also set to [constant VIEWPORT_ENVIRONMENT_INHERIT], then this has the same behavior as [constant VIEWPORT_ENVIRONMENT_ENABLED]. - Max value of [enum ViewportEnvironmentMode] enum. + Represents the size of the [enum ViewportEnvironmentMode] enum. + Do not oversize the 2D signed distance field. Occluders may disappear when touching the viewport's edges, and [GPUParticles3D] collision may stop working earlier than intended. This has the lowest GPU requirements. + 2D signed distance field covers 20% of the viewport's size outside the viewport on each side (top, right, bottom, left). + 2D signed distance field covers 50% of the viewport's size outside the viewport on each side (top, right, bottom, left). + 2D signed distance field covers 100% of the viewport's size outside the viewport on each side (top, right, bottom, left). This has the highest GPU requirements. + Represents the size of the [enum ViewportSDFOversize] enum. + Full resolution 2D signed distance field scale. This has the highest GPU requirements. + Half resolution 2D signed distance field scale on each axis (25% of the viewport pixel count). + Quarter resolution 2D signed distance field scale on each axis (6.25% of the viewport pixel count). This has the lowest GPU requirements. + Represents the size of the [enum ViewportSDFScale] enum. Multisample antialiasing for 3D is disabled. This is the default value, and also the fastest setting. @@ -4251,18 +4533,25 @@ Multisample antialiasing uses 8 samples per pixel for 3D. This has a very high impact on performance. Likely unsupported on low-end and older hardware. + Represents the size of the [enum ViewportMSAA] enum. + Do not perform any antialiasing in the full screen post-process. + Use fast approximate antialiasing. FXAA is a popular screen-space antialiasing method, which is fast but will make the image look blurry, especially at lower resolutions. It can still work relatively well at large resolutions such as 1440p and 4K. + Represents the size of the [enum ViewportScreenSpaceAA] enum. + Low occlusion culling BVH build quality (as defined by Embree). Results in the lowest CPU usage, but least effective culling. + Medium occlusion culling BVH build quality (as defined by Embree). + High occlusion culling BVH build quality (as defined by Embree). Results in the highest CPU usage, but most effective culling. Number of objects drawn in a single frame. @@ -4277,10 +4566,13 @@ Represents the size of the [enum ViewportRenderInfo] enum. + Visible render pass (excluding shadows). + Shadow render pass. Objects will be rendered several times depending on the number of amounts of lights with shadows and the number of directional shadow splits. + Represents the size of the [enum ViewportRenderInfoType] enum. Debug draw is disabled. Default setting. @@ -4317,6 +4609,7 @@ Draws the shadow atlas that stores shadows from [DirectionalLight3D]s in the upper left quadrant of the [Viewport]. + Draws the estimated scene luminance. This is a 1×1 texture that is generated when autoexposure is enabled to control the scene's exposure. Draws the screen space ambient occlusion texture instead of the scene so that you can clearly see how it is affecting objects. In order for this display mode to work, you must have [member Environment.ssao_enabled] set in your [WorldEnvironment]. @@ -4328,49 +4621,62 @@ Colors each PSSM split for the [DirectionalLight3D]s in the scene a different color so you can see where the splits are. In order they will be colored red, green, blue, yellow. + Draws the decal atlas that stores decal textures from [Decal]s. + Draws SDFGI cascade data. This is the data structure that is used to bounce lighting against and create reflections. + Draws SDFGI probe data. This is the data structure that is used to give indirect lighting dynamic objects moving within the scene. + Draws the global illumination buffer ([VoxelGI] or SDFGI). + Disable mesh LOD. All meshes are drawn with full detail, which can be used to compare performance. + Draws the [OmniLight3D] cluster. Clustering determines where lights are positioned in screen-space, which allows the engine to only process these portions of the screen for lighting. + Draws the [SpotLight3D] cluster. Clustering determines where lights are positioned in screen-space, which allows the engine to only process these portions of the screen for lighting. + Draws the [Decal] cluster. Clustering determines where decals are positioned in screen-space, which allows the engine to only process these portions of the screen for decals. + Draws the [ReflectionProbe] cluster. Clustering determines where reflection probes are positioned in screen-space, which allows the engine to only process these portions of the screen for reflection probes. + Draws the occlusion culling buffer. This low-resolution occlusion culling buffer is rasterized on the CPU and is used to check whether instances are occluded by other objects. + Draws the motion vectors buffer. This is used by temporal antialiasing to correct for motion that occurs during gameplay. - VRS is disabled. + Variable rate shading is disabled. - VRS uses a texture. Note, for stereoscopic use a texture atlas with a texture for each view. + Variable rate shading uses a texture. Note, for stereoscopic use a texture atlas with a texture for each view. - VRS texture is supplied by the primary [XRInterface]. + Variable rate shading texture is supplied by the primary [XRInterface]. Represents the size of the [enum ViewportVRSMode] enum. + Automatically selects the appropriate process mode based on your sky shader. If your shader uses [code]TIME[/code] or [code]POSITION[/code], this will use [constant SKY_MODE_REALTIME]. If your shader uses any of the [code]LIGHT_*[/code] variables or any custom uniforms, this uses [constant SKY_MODE_INCREMENTAL]. Otherwise, this defaults to [constant SKY_MODE_QUALITY]. - Uses high quality importance sampling to process the radiance map. In general, this results in much higher quality than [constant Sky.PROCESS_MODE_REALTIME] but takes much longer to generate. This should not be used if you plan on changing the sky at runtime. If you are finding that the reflection is not blurry enough and is showing sparkles or fireflies, try increasing [member ProjectSettings.rendering/reflections/sky_reflections/ggx_samples]. + Uses high quality importance sampling to process the radiance map. In general, this results in much higher quality than [constant SKY_MODE_REALTIME] but takes much longer to generate. This should not be used if you plan on changing the sky at runtime. If you are finding that the reflection is not blurry enough and is showing sparkles or fireflies, try increasing [member ProjectSettings.rendering/reflections/sky_reflections/ggx_samples]. + Uses the same high quality importance sampling to process the radiance map as [constant SKY_MODE_QUALITY], but updates over several frames. The number of frames is determined by [member ProjectSettings.rendering/reflections/sky_reflections/roughness_layers]. Use this when you need highest quality radiance maps, but have a sky that updates slowly. - Uses the fast filtering algorithm to process the radiance map. In general this results in lower quality, but substantially faster run times. - [b]Note:[/b] The fast filtering algorithm is limited to 256x256 cubemaps, so [member Sky.radiance_size] must be set to [constant Sky.RADIANCE_SIZE_256]. + Uses the fast filtering algorithm to process the radiance map. In general this results in lower quality, but substantially faster run times. If you need better quality, but still need to update the sky every frame, consider turning on [member ProjectSettings.rendering/reflections/sky_reflections/fast_filter_high_quality]. + [b]Note:[/b] The fast filtering algorithm is limited to 256×256 cubemaps, so [method sky_set_radiance_size] must be set to [code]256[/code]. Otherwise, a warning is printed and the overridden radiance size is ignored. Use the clear color as background. @@ -4485,60 +4791,88 @@ Highest quality screen-space indirect lighting. Uses the adaptive target setting which can be dynamically adjusted to smoothly balance performance and visual quality. + Use 50% scale for SDFGI on the Y (vertical) axis. SDFGI cells will be twice as short as they are wide. This allows providing increased GI detail and reduced light leaking with thin floors and ceilings. This is usually the best choice for scenes that don't feature much verticality. + Use 75% scale for SDFGI on the Y (vertical) axis. This is a balance between the 50% and 100% SDFGI Y scales. + Use 100% scale for SDFGI on the Y (vertical) axis. SDFGI cells will be as tall as they are wide. This is usually the best choice for highly vertical scenes. The downside is that light leaking may become more noticeable with thin floors and ceilings. + Throw 4 rays per frame when converging SDFGI. This has the lowest GPU requirements, but creates the most noisy result. + Throw 8 rays per frame when converging SDFGI. + Throw 16 rays per frame when converging SDFGI. + Throw 32 rays per frame when converging SDFGI. + Throw 64 rays per frame when converging SDFGI. + Throw 96 rays per frame when converging SDFGI. This has high GPU requirements. + Throw 128 rays per frame when converging SDFGI. This has very high GPU requirements, but creates the least noisy result. + Represents the size of the [enum EnvironmentSDFGIRayCount] enum. + Converge SDFGI over 5 frames. This is the most responsive, but creates the most noisy result with a given ray count. + Configure SDFGI to fully converge over 10 frames. + Configure SDFGI to fully converge over 15 frames. + Configure SDFGI to fully converge over 20 frames. + Configure SDFGI to fully converge over 25 frames. + Configure SDFGI to fully converge over 30 frames. This is the least responsive, but creates the least noisy result with a given ray count. + Represents the size of the [enum EnvironmentSDFGIFramesToConverge] enum. + Update indirect light from dynamic lights in SDFGI over 1 frame. This is the most responsive, but has the highest GPU requirements. + Update indirect light from dynamic lights in SDFGI over 2 frames. + Update indirect light from dynamic lights in SDFGI over 4 frames. + Update indirect light from dynamic lights in SDFGI over 8 frames. + Update indirect light from dynamic lights in SDFGI over 16 frames. This is the least responsive, but has the lowest GPU requirements. + Represents the size of the [enum EnvironmentSDFGIFramesToUpdateLight] enum. + Disables subsurface scattering entirely, even on materials that have [member BaseMaterial3D.subsurf_scatter_enabled] set to [code]true[/code]. This has the lowest GPU requirements. + Low subsurface scattering quality. + Medium subsurface scattering quality. + High subsurface scattering quality. This has the highest GPU requirements. Calculate the DOF blur using a box filter. The fastest option, but results in obvious lines in blur pattern. @@ -4574,6 +4908,7 @@ The instance is a particle emitter. + The instance is a GPUParticles collision shape. The instance is a light. @@ -4591,10 +4926,13 @@ The instance is a lightmap. + The instance is an occlusion culling occluder. + The instance is a visible on-screen notifier. + The instance is a fog volume. Represents the size of the [enum InstanceType] enum. @@ -4612,6 +4950,7 @@ When set, manually requests to draw geometry on next frame. + Always draw, even if the instance would be culled by occlusion culling. Does not affect view frustum culling. Represents the size of the [enum InstanceFlags] enum. @@ -4650,10 +4989,13 @@ Index of [Image] in array of [Image]s returned by [method bake_render_uv2]. Image uses [constant Image.FORMAT_RGBAH] and contains emission color in the [code].rgb[/code] channels and nothing in the [code].a[/code] channel. + Diffuse canvas texture ([member CanvasTexture.diffuse_texture]). + Normal map canvas texture ([member CanvasTexture.normal_texture]). + Specular map canvas texture ([member CanvasTexture.specular_texture]). The nine patch gets stretched where needed. @@ -4704,16 +5046,21 @@ Max value for [enum CanvasItemTextureRepeat] enum. + Child draws over parent and is not clipped. + Parent is used for the purposes of clipping only. Child is clipped to the parent's visible area, parent is not drawn. + Parent is used for clipping child, but parent is also drawn underneath child as normal before clipping child to its visible area. + 2D point light (see [PointLight2D]). + 2D directional (sun/moon) light (see [DirectionalLight2D]). Adds light color additive to the canvas. @@ -4746,74 +5093,109 @@ Culling of the canvas occluder is counterclockwise. + Boolean global shader parameter ([code]global uniform bool ...[/code]). + 2-dimensional boolean vector global shader parameter ([code]global uniform bvec2 ...[/code]). + 3-dimensional boolean vector global shader parameter ([code]global uniform bvec3 ...[/code]). + 4-dimensional boolean vector global shader parameter ([code]global uniform bvec4 ...[/code]). + Integer global shader parameter ([code]global uniform int ...[/code]). + 2-dimensional integer vector global shader parameter ([code]global uniform ivec2 ...[/code]). + 3-dimensional integer vector global shader parameter ([code]global uniform ivec3 ...[/code]). + 4-dimensional integer vector global shader parameter ([code]global uniform ivec4 ...[/code]). + 2-dimensional integer rectangle global shader parameter ([code]global uniform ivec4 ...[/code]). Equivalent to [constant GLOBAL_VAR_TYPE_IVEC4] in shader code, but exposed as a [Rect2i] in the editor UI. + Unsigned integer global shader parameter ([code]global uniform uint ...[/code]). + 2-dimensional unsigned integer vector global shader parameter ([code]global uniform uvec2 ...[/code]). + 3-dimensional unsigned integer vector global shader parameter ([code]global uniform uvec3 ...[/code]). + 4-dimensional unsigned integer vector global shader parameter ([code]global uniform uvec4 ...[/code]). + Single-precision floating-point global shader parameter ([code]global uniform float ...[/code]). + 2-dimensional floating-point vector global shader parameter ([code]global uniform vec2 ...[/code]). + 3-dimensional floating-point vector global shader parameter ([code]global uniform vec3 ...[/code]). + 4-dimensional floating-point vector global shader parameter ([code]global uniform vec4 ...[/code]). + Color global shader parameter ([code]global uniform vec4 ...[/code]). Equivalent to [constant GLOBAL_VAR_TYPE_VEC4] in shader code, but exposed as a [Color] in the editor UI. + 2-dimensional floating-point rectangle global shader parameter ([code]global uniform vec4 ...[/code]). Equivalent to [constant GLOBAL_VAR_TYPE_VEC4] in shader code, but exposed as a [Rect2] in the editor UI. + 2×2 matrix global shader parameter ([code]global uniform mat2 ...[/code]). Exposed as a [PackedInt32Array] in the editor UI. + 3×3 matrix global shader parameter ([code]global uniform mat3 ...[/code]). Exposed as a [Basis] in the editor UI. + 4×4 matrix global shader parameter ([code]global uniform mat4 ...[/code]). Exposed as a [Projection] in the editor UI. + 2-dimensional transform global shader parameter ([code]global uniform mat2x3 ...[/code]). Exposed as a [Transform2D] in the editor UI. + 3-dimensional transform global shader parameter ([code]global uniform mat3x4 ...[/code]). Exposed as a [Transform3D] in the editor UI. + 2D sampler global shader parameter ([code]global uniform sampler2D ...[/code]). Exposed as a [Texture2D] in the editor UI. + 2D sampler array global shader parameter ([code]global uniform sampler2DArray ...[/code]). Exposed as a [Texture2DArray] in the editor UI. + 3D sampler global shader parameter ([code]global uniform sampler3D ...[/code]). Exposed as a [Texture3D] in the editor UI. + Cubemap sampler global shader parameter ([code]global uniform samplerCube ...[/code]). Exposed as a [Cubemap] in the editor UI. + Represents the size of the [enum GlobalShaderParameterType] enum. + Number of objects rendered in the current 3D scene. This varies depending on camera position and rotation. + Number of vertices/indices rendered in the current 3D scene. This varies depending on camera position and rotation. + Number of draw calls performed to render in the current 3D scene. This varies depending on camera position and rotation. + Texture memory used (in bytes). + Buffer memory used (in bytes). + Video memory used (in bytes). This is always greater than the sum of [constant RENDERING_INFO_TEXTURE_MEM_USED] and [constant RENDERING_INFO_BUFFER_MEM_USED], since there is miscellaneous data not accounted for by those two metrics. Hardware supports shaders. This enum is currently unused in Godot 3.x. diff --git a/doc/classes/ShaderGlobalsOverride.xml b/doc/classes/ShaderGlobalsOverride.xml index 4c49d104bb..255fc122b9 100644 --- a/doc/classes/ShaderGlobalsOverride.xml +++ b/doc/classes/ShaderGlobalsOverride.xml @@ -1,8 +1,12 @@ + Overrides global shader parameters' values in a specific scene. + Similar to how a [WorldEnvironment] node can be used to override the environment while a specific scene is loaded, [ShaderGlobalsOverride] can be used to override global shader parameters temporarily. Once the node is removed, the project-wide values for the global shader parameters are restored. See the [RenderingServer] [code]global_shader_parameter_*[/code] methods for more information. + [b]Note:[/b] Only one [ShaderGlobalsOverride] can be used per scene. If there is more than one [ShaderGlobalsOverride] node in the scene tree, only the first node (in tree order) will be taken into account. + [b]Note:[/b] All [ShaderGlobalsOverride] nodes are made part of a [code]"shader_overrides_group"[/code] group when they are added to the scene tree. The currently active [ShaderGlobalsOverride] node also has a [code]"shader_overrides_group_active"[/code] group added to it. You can use this to check which [ShaderGlobalsOverride] node is currently active. diff --git a/doc/classes/Sky.xml b/doc/classes/Sky.xml index e14e57a1c4..86589e0fb8 100644 --- a/doc/classes/Sky.xml +++ b/doc/classes/Sky.xml @@ -57,7 +57,7 @@ Uses the fast filtering algorithm to process the radiance map. In general this results in lower quality, but substantially faster run times. If you need better quality, but still need to update the sky every frame, consider turning on [member ProjectSettings.rendering/reflections/sky_reflections/fast_filter_high_quality]. - [b]Note:[/b] The fast filtering algorithm is limited to 256x256 cubemaps, so [member radiance_size] must be set to [constant RADIANCE_SIZE_256]. + [b]Note:[/b] The fast filtering algorithm is limited to 256×256 cubemaps, so [member radiance_size] must be set to [constant RADIANCE_SIZE_256]. Otherwise, a warning is printed and the overridden radiance size is ignored. diff --git a/doc/classes/Viewport.xml b/doc/classes/Viewport.xml index 62413581a9..25ee5a5226 100644 --- a/doc/classes/Viewport.xml +++ b/doc/classes/Viewport.xml @@ -285,6 +285,7 @@ [b]Note:[/b] This setting is disabled by default because of its potential expensive computational cost. + Use 16 bits for the omni/spot shadow depth map. Enabling this results in shadows having less precision and may result in shadow acne, but can lead to performance improvements on some devices. The subdivision amount of the first quadrant on the shadow atlas. @@ -299,8 +300,8 @@ The subdivision amount of the fourth quadrant on the shadow atlas. - The shadow atlas' resolution (used for omni and spot lights). The value will be rounded up to the nearest power of 2. - [b]Note:[/b] If this is set to [code]0[/code], no shadows will be visible at all (including directional shadows). + The shadow atlas' resolution (used for omni and spot lights). The value is rounded up to the nearest power of 2. + [b]Note:[/b] If this is set to [code]0[/code], no positional shadows will be visible at all. This can improve performance significantly on low-end systems by reducing both the CPU and GPU load (as fewer draw calls are needed to draw the scene without shadows). Sets scaling 3d mode. Bilinear scaling renders at different resolution to either undersample or supersample the viewport. FidelityFX Super Resolution 1.0, abbreviated to FSR, is an upscaling technology that produces high quality images at fast framerates by using a spatially aware upscaling algorithm. FSR is slightly more expensive than bilinear, but it produces significantly higher image quality. FSR should be used where possible. -- cgit v1.2.3