Always perform color correction and debanding on nonlinear sRGB values.

Fixes #107730

Co-authored-by: LuoZhihao <[email protected]>

Author: allenwp

doc/classes/ProjectSettings.xml

@@ -2744,9 +2744,9 @@
 			[b]Note:[/b] This property is only read when the project starts. There is currently no way to change this setting at run-time.
 		</member>
 		<member name="rendering/anti_aliasing/quality/use_debanding" type="bool" setter="" getter="" default="false">
-			If [code]true[/code], uses a fast post-processing filter to make banding significantly less visible in 3D. 2D rendering is [i]not[/i] affected by debanding unless the [member Environment.background_mode] is [constant Environment.BG_CANVAS].
+			If [code]true[/code], uses a fast post-processing filter to make banding significantly less visible. This setting affects both [member Viewport.use_debanding] and [member RenderingServer.use_global_debanding] and behaves slightly differently based on [member rendering/viewport/hdr_2d]: When [member rendering/viewport/hdr_2d] is [code]false[/code], [Viewport] debanding will be used. When [member rendering/viewport/hdr_2d] is [code]true[/code], global debanding will be used.
 			In some cases, debanding may introduce a slightly noticeable dithering pattern. It's recommended to enable debanding only when actually needed since the dithering pattern will make lossless-compressed screenshots larger.
-			[b]Note:[/b] This property is only read when the project starts. To set debanding at runtime, set [member Viewport.use_debanding] on the root [Viewport] instead, or use [method RenderingServer.viewport_set_use_debanding].
+			[b]Note:[/b] This property is only read when the project starts. To set debanding at runtime, set [member Viewport.use_debanding] on the root [Viewport] if this viewport has [member Viewport.use_hdr_2d] set to [code]false[/code] or set [member RenderingServer.use_global_debanding] if [member Viewport.use_hdr_2d] of the root [Viewport] is [code]true[/code].
 		</member>
 		<member name="rendering/anti_aliasing/quality/use_taa" type="bool" setter="" getter="" default="false">
 			Enables temporal antialiasing for the default screen [Viewport]. TAA works by jittering the camera and accumulating the images of the last rendered frames, motion vector rendering is used to account for camera and object motion. Enabling TAA can make the image blurrier, which is partially counteracted by automatically using a negative mipmap LOD bias (see [member rendering/textures/default_filters/texture_mipmap_bias]).

doc/classes/RenderingServer.xml

@@ -4232,7 +4232,7 @@
 			<param index="0" name="viewport" type="RID" />
 			<param index="1" name="enable" type="bool" />
 			<description>
-				If [code]true[/code], enables debanding on the specified viewport. Equivalent to [member ProjectSettings.rendering/anti_aliasing/quality/use_debanding] or [member Viewport.use_debanding].
+				If [code]true[/code], enables debanding on the specified viewport. Equivalent to [member Viewport.use_debanding]. See also [member ProjectSettings.rendering/anti_aliasing/quality/use_debanding].
 			</description>
 		</method>
 		<method name="viewport_set_use_hdr_2d">
@@ -4450,6 +4450,12 @@
 		<member name="render_loop_enabled" type="bool" setter="set_render_loop_enabled" getter="is_render_loop_enabled">
 			If [code]false[/code], disables rendering completely, but the engine logic is still being processed. You can call [method force_draw] to draw a frame even with rendering disabled.
 		</member>
+		<member name="use_global_debanding" type="bool" setter="set_use_global_debanding" getter="get_use_global_debanding">
+			If [code]true[/code] and [member Viewport.use_hdr_2d] of the root [Viewport] is [code]true[/code], uses a fast post-processing filter to make banding significantly less visible. All 3D and 2D rendering, including canvas items, is affected by global debanding.
+			In some cases, debanding may introduce a slightly noticeable dithering pattern. It's recommended to enable debanding only when actually needed since the dithering pattern will make lossless-compressed screenshots larger.
+			See also [member ProjectSettings.rendering/anti_aliasing/quality/use_debanding] and [method RenderingServer.viewport_set_use_debanding].
+			[b]Note:[/b] [member use_global_debanding] will only have an effect when [member Viewport.use_hdr_2d] of the root [Viewport] is [code]true[/code]. To enable debanding when [member Viewport.use_hdr_2d] is [code]false[/code], configure debanding in your project settings with [member ProjectSettings.rendering/anti_aliasing/quality/use_debanding] or use [member Viewport.use_debanding].
+		</member>
 	</members>
 	<signals>
 		<signal name="frame_post_draw">

doc/classes/Viewport.xml

@@ -444,9 +444,10 @@
 			If [code]true[/code], the viewport should render its background as transparent.
 		</member>
 		<member name="use_debanding" type="bool" setter="set_use_debanding" getter="is_using_debanding" default="false">
-			If [code]true[/code], uses a fast post-processing filter to make banding significantly less visible in 3D. 2D rendering is [i]not[/i] affected by debanding unless the [member Environment.background_mode] is [constant Environment.BG_CANVAS].
+			If [code]true[/code] and [member use_hdr_2d] is [code]false[/code], uses a fast post-processing filter to make banding significantly less visible in 3D. 2D rendering is [i]not[/i] affected by debanding unless the [member Environment.background_mode] is [constant Environment.BG_CANVAS].
 			In some cases, debanding may introduce a slightly noticeable dithering pattern. It's recommended to enable debanding only when actually needed since the dithering pattern will make lossless-compressed screenshots larger.
 			See also [member ProjectSettings.rendering/anti_aliasing/quality/use_debanding] and [method RenderingServer.viewport_set_use_debanding].
+			[b]Note:[/b] [member use_debanding] will only have an effect when [member use_hdr_2d] is [code]false[/code]. To enable debanding when [member use_hdr_2d] is [code]true[/code], configure debanding in your project settings with [member ProjectSettings.rendering/anti_aliasing/quality/use_debanding] or use [member RenderingServer.use_global_debanding].
 		</member>
 		<member name="use_hdr_2d" type="bool" setter="set_use_hdr_2d" getter="is_using_hdr_2d" default="false">
 			If [code]true[/code], 2D rendering will use a high dynamic range (HDR) format framebuffer matching the bit depth of the 3D framebuffer. When using the Forward+ renderer this will be an [code]RGBA16[/code] framebuffer, while when using the Mobile renderer it will be an [code]RGB10_A2[/code] framebuffer. Additionally, 2D rendering will take place in linear color space and will be converted to sRGB space immediately before blitting to the screen (if the Viewport is attached to the screen). Practically speaking, this means that the end result of the Viewport will not be clamped into the [code]0-1[/code] range and can be used in 3D rendering without color space adjustments. This allows 2D rendering to take advantage of effects requiring high dynamic range (e.g. 2D glow) as well as substantially improves the appearance of effects requiring highly detailed gradients.

editor/scene/3d/node_3d_editor_plugin.cpp

@@ -100,6 +100,7 @@
 #include "scene/resources/3d/sky_material.h"
 #include "scene/resources/packed_scene.h"
 #include "scene/resources/surface_tool.h"
+#include "servers/rendering/renderer_compositor.h"
 
 constexpr real_t DISTANCE_DEFAULT = 4;
 
@@ -2933,7 +2934,8 @@ void Node3DEditorViewport::_project_settings_changed() {
 	viewport->set_use_hdr_2d(use_hdr_2d);
 
 	const bool use_debanding = GLOBAL_GET("rendering/anti_aliasing/quality/use_debanding");
-	viewport->set_use_debanding(use_debanding);
+	viewport->set_use_debanding_warn(use_debanding, false);
+	RendererCompositor::get_singleton()->set_use_global_debanding(use_debanding);
 
 	const bool use_occlusion_culling = GLOBAL_GET("rendering/occlusion_culling/use_occlusion_culling");
 	viewport->set_use_occlusion_culling(use_occlusion_culling);

scene/main/scene_tree.cpp

@@ -2073,7 +2073,7 @@ SceneTree::SceneTree() {
 	root->set_use_taa(use_taa);
 
 	const bool use_debanding = GLOBAL_DEF("rendering/anti_aliasing/quality/use_debanding", false);
-	root->set_use_debanding(use_debanding);
+	root->set_use_debanding_warn(use_debanding, false);
 
 	const bool use_occlusion_culling = GLOBAL_DEF("rendering/occlusion_culling/use_occlusion_culling", false);
 	root->set_use_occlusion_culling(use_occlusion_culling);

scene/main/viewport.cpp

@@ -3715,12 +3715,20 @@ bool Viewport::is_using_taa() const {
 }
 
 void Viewport::set_use_debanding(bool p_use_debanding) {
+	set_use_debanding_warn(p_use_debanding, true);
+}
+
+void Viewport::set_use_debanding_warn(bool p_use_debanding, bool p_warn_no_effect) {
 	ERR_MAIN_THREAD_GUARD;
 	if (use_debanding == p_use_debanding) {
 		return;
 	}
 	use_debanding = p_use_debanding;
 	RS::get_singleton()->viewport_set_use_debanding(viewport, p_use_debanding);
+
+	if (p_warn_no_effect && use_hdr_2d) {
+		WARN_PRINT("Attempting to set viewport debanding when HDR 2D is enabled. This will have no effect; use RenderingServer.use_global_debanding instead.");
+	}
 }
 
 bool Viewport::is_using_debanding() const {

scene/main/viewport.h

@@ -603,6 +603,7 @@ class Viewport : public Node {
 	AnisotropicFiltering get_anisotropic_filtering_level() const;
 
 	void set_use_debanding(bool p_use_debanding);
+	void set_use_debanding_warn(bool p_use_debanding, bool p_warn_no_effect);
 	bool is_using_debanding() const;
 
 	void set_mesh_lod_threshold(float p_pixels);

servers/rendering/renderer_compositor.cpp

@@ -49,10 +49,20 @@ bool RendererCompositor::is_xr_enabled() const {
 	return xr_enabled;
 }
 
+bool RendererCompositor::get_use_global_debanding() const {
+	return use_global_debanding;
+}
+
+void RendererCompositor::set_use_global_debanding(bool p_enable) {
+	use_global_debanding = p_enable;
+}
+
 RendererCompositor::RendererCompositor() {
 	ERR_FAIL_COND_MSG(singleton != nullptr, "A RendererCompositor singleton already exists.");
 	singleton = this;
 
+	use_global_debanding = GLOBAL_DEF("rendering/anti_aliasing/quality/use_debanding", false);
+
 #ifndef XR_DISABLED
 	if (XRServer::get_xr_mode() == XRServer::XRMODE_DEFAULT) {
 		xr_enabled = GLOBAL_GET("xr/shaders/enabled");

servers/rendering/renderer_compositor.h

@@ -71,6 +71,7 @@ class RendererCompositor {
 protected:
 	static RendererCompositor *(*_create_func)();
 	bool back_end = false;
+	bool use_global_debanding = false;
 	static bool low_end;
 
 public:
@@ -105,6 +106,8 @@ class RendererCompositor {
 
 	static bool is_low_end() { return low_end; }
 	virtual bool is_xr_enabled() const;
+	virtual bool get_use_global_debanding() const;
+	virtual void set_use_global_debanding(bool p_enable);
 
 	static RendererCompositor *get_singleton() { return singleton; }
 	RendererCompositor();

servers/rendering/renderer_rd/effects/tone_mapper.cpp

@@ -123,7 +123,8 @@ void ToneMapper::tonemapper(RID p_source_color, RID p_dst_framebuffer, const Ton
 	tonemap.push_constant.flags |= p_settings.use_color_correction ? TONEMAP_FLAG_USE_COLOR_CORRECTION : 0;
 
 	tonemap.push_constant.flags |= p_settings.use_fxaa ? TONEMAP_FLAG_USE_FXAA : 0;
-	tonemap.push_constant.flags |= p_settings.use_debanding ? TONEMAP_FLAG_USE_DEBANDING : 0;
+	// When convert_to_srgb is false: postpone debanding until blit.
+	tonemap.push_constant.flags |= (p_settings.use_debanding && p_settings.convert_to_srgb) ? TONEMAP_FLAG_USE_DEBANDING : 0;
 	tonemap.push_constant.pixel_size[0] = 1.0 / p_settings.texture_size.x;
 	tonemap.push_constant.pixel_size[1] = 1.0 / p_settings.texture_size.y;
 
@@ -207,8 +208,8 @@ void ToneMapper::tonemapper(RD::DrawListID p_subpass_draw_list, RID p_source_col
 	tonemap.push_constant.auto_exposure_scale = p_settings.auto_exposure_scale;
 
 	tonemap.push_constant.flags |= p_settings.use_color_correction ? TONEMAP_FLAG_USE_COLOR_CORRECTION : 0;
-
-	tonemap.push_constant.flags |= p_settings.use_debanding ? TONEMAP_FLAG_USE_DEBANDING : 0;
+	// When convert_to_srgb is false: postpone debanding until blit.
+	tonemap.push_constant.flags |= (p_settings.use_debanding && p_settings.convert_to_srgb) ? TONEMAP_FLAG_USE_DEBANDING : 0;
 	tonemap.push_constant.luminance_multiplier = p_settings.luminance_multiplier;
 
 	tonemap.push_constant.flags |= p_settings.convert_to_srgb ? TONEMAP_FLAG_CONVERT_TO_SRGB : 0;