Add sheen shading support

Author: LiveTrower

doc/classes/BaseMaterial3D.xml

@@ -374,6 +374,24 @@
 		<member name="shadow_to_opacity" type="bool" setter="set_flag" getter="get_flag" default="false">
 			If [code]true[/code], enables the "shadow to opacity" render mode where lighting modifies the alpha so shadowed areas are opaque and non-shadowed areas are transparent. Useful for overlaying shadows onto a camera feed in AR.
 		</member>
+		<member name="sheen" type="float" setter="set_sheen" getter="get_sheen" default="1.0">
+			Sets the strength of the sheen effect. Setting to [code]0[/code] looks the same as disabling the sheen effect.
+		</member>
+		<member name="sheen_color" type="Color" setter="set_sheen_color" getter="get_sheen_color" default="Color(1, 1, 1, 1)">
+			Sets the color of the sheen effect. It should be adjusted according to the color [member albedo_color] or [member albedo_texture].
+			[b]Note:[/b] Taking the luminance of [member albedo_color] as the [member sheen_color] will produce a fairly natural effect that works for common cloth. A dark [member albedo_color] combined with a bright/saturated [member sheen_color] can be used to create velvet.
+		</member>
+		<member name="sheen_enabled" type="bool" setter="set_feature" getter="get_feature" default="false">
+			If [code]true[/code], sheen effect is enabled. Sheen lighting simulate the soft luster and light scattering caused by the fibrous microstructure or fine particles on a material's surface.
+			It is mainly used to give a realistic look to fabrics (like velvet or wool), and it serves as a PBR alternative to [member rim].
+			[b]Note:[/b] Sheen lighting is not visible if the material's [member shading_mode] is [constant SHADING_MODE_UNSHADED].
+		</member>
+		<member name="sheen_roughness" type="float" setter="set_sheen_roughness" getter="get_sheen_roughness" default="0.5">
+			Sets the roughness of the sheen pass. A higher value results in a rougher sheen while a lower value results in a smoother sheen.
+		</member>
+		<member name="sheen_texture" type="Texture2D" setter="set_texture" getter="get_texture">
+			Texture that defines the strength of the sheen effect and the roughness of the sheen. Strength is specified in the red channel while roughness is specified in the green channel.
+		</member>
 		<member name="specular_mode" type="int" setter="set_specular_mode" getter="get_specular_mode" enum="BaseMaterial3D.SpecularMode" default="0">
 			The method for rendering the specular blob.
 			[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.
@@ -512,6 +530,9 @@
 		<constant name="TEXTURE_RIM" value="5" enum="TextureParam">
 			Texture specifying per-pixel rim value.
 		</constant>
+		<constant name="TEXTURE_SHEEN" value="19" enum="TextureParam">
+			Texture specifying per-pixel sheen value.
+		</constant>
 		<constant name="TEXTURE_CLEARCOAT" value="6" enum="TextureParam">
 			Texture specifying per-pixel clearcoat value.
 		</constant>
@@ -548,7 +569,7 @@
 		<constant name="TEXTURE_ORM" value="17" enum="TextureParam">
 			Texture holding ambient occlusion, roughness, and metallic.
 		</constant>
-		<constant name="TEXTURE_MAX" value="19" enum="TextureParam">
+		<constant name="TEXTURE_MAX" value="20" enum="TextureParam">
 			Represents the size of the [enum TextureParam] enum.
 		</constant>
 		<constant name="TEXTURE_FILTER_NEAREST" value="0" enum="TextureFilter">
@@ -647,7 +668,9 @@
 		<constant name="FEATURE_BENT_NORMAL_MAPPING" value="12" enum="Feature">
 			Constant for setting [member bent_normal_enabled].
 		</constant>
-		<constant name="FEATURE_MAX" value="13" enum="Feature">
+		<constant name="FEATURE_SHEEN" value="13" enum="Feature">
+		</constant>
+		<constant name="FEATURE_MAX" value="14" enum="Feature">
 			Represents the size of the [enum Feature] enum.
 		</constant>
 		<constant name="BLEND_MODE_MIX" value="0" enum="BlendMode">

drivers/gles3/storage/material_storage.cpp

@@ -1310,6 +1310,9 @@ MaterialStorage::MaterialStorage() {
 		actions.renames["ROUGHNESS"] = "roughness";
 		actions.renames["RIM"] = "rim";
 		actions.renames["RIM_TINT"] = "rim_tint";
+		actions.renames["SHEEN"] = "sheen";
+		actions.renames["SHEEN_ROUGNESS"] = "sheen_roughness";
+		actions.renames["SHEEN_COLOR"] = "sheen_color";
 		actions.renames["CLEARCOAT"] = "clearcoat";
 		actions.renames["CLEARCOAT_ROUGHNESS"] = "clearcoat_roughness";
 		actions.renames["ANISOTROPY"] = "anisotropy";
@@ -1367,6 +1370,9 @@ MaterialStorage::MaterialStorage() {
 		actions.usage_defines["BINORMAL"] = "@TANGENT";
 		actions.usage_defines["RIM"] = "#define LIGHT_RIM_USED\n";
 		actions.usage_defines["RIM_TINT"] = "@RIM";
+		actions.usage_defines["SHEEN"] = "#define LIGHT_SHEEN_USED\n";
+		actions.usage_defines["SHEEN_ROUGNESS"] = "@SHEEN";
+		actions.usage_defines["SHEEN_COLOR"] = "@SHEEN";
 		actions.usage_defines["CLEARCOAT"] = "#define LIGHT_CLEARCOAT_USED\n";
 		actions.usage_defines["CLEARCOAT_ROUGHNESS"] = "@CLEARCOAT";
 		actions.usage_defines["ANISOTROPY"] = "#define LIGHT_ANISOTROPY_USED\n";
@@ -2986,6 +2992,7 @@ void SceneShaderData::set_code(const String &p_code) {
 	uses_position = false;
 	uses_sss = false;
 	uses_transmittance = false;
+	uses_sheen = false;
 	uses_screen_texture = false;
 	uses_screen_texture_mipmaps = false;
 	uses_depth_texture = false;
@@ -3068,6 +3075,8 @@ void SceneShaderData::set_code(const String &p_code) {
 	actions.usage_flag_pointers["SSS_STRENGTH"] = &uses_sss;
 	actions.usage_flag_pointers["SSS_TRANSMITTANCE_DEPTH"] = &uses_transmittance;
 
+	actions.usage_flag_pointers["SHEEN"] = &uses_sheen;
+
 	actions.usage_flag_pointers["DISCARD"] = &uses_discard;
 	actions.usage_flag_pointers["TIME"] = &uses_time;
 	actions.usage_flag_pointers["ROUGHNESS"] = &uses_roughness;
@@ -3174,6 +3183,10 @@ void SceneShaderData::set_code(const String &p_code) {
 	if (uses_normal_texture) {
 		WARN_PRINT_ONCE_ED("Reading from the normal-roughness texture is only available when using the Forward+ or Mobile renderer.");
 	}
+
+	if (uses_sheen) {
+		WARN_PRINT_ONCE_ED("Sheen shading is only available when using the Forward+ renderer.");
+	}
 #endif
 
 #if 0

drivers/gles3/storage/material_storage.h

@@ -326,6 +326,7 @@ struct SceneShaderData : public ShaderData {
 	bool uses_position;
 	bool uses_sss;
 	bool uses_transmittance;
+	bool uses_sheen;
 	bool uses_screen_texture;
 	bool uses_screen_texture_mipmaps;
 	bool uses_depth_texture;

modules/visual_shader/visual_shader.cpp

@@ -4240,6 +4240,10 @@ const VisualShaderNodeOutput::Port VisualShaderNodeOutput::ports[] = {
 	{ Shader::MODE_SPATIAL, VisualShader::TYPE_FRAGMENT, VisualShaderNode::PORT_TYPE_SCALAR, "Depth", "DEPTH" },
 	{ Shader::MODE_SPATIAL, VisualShader::TYPE_FRAGMENT, VisualShaderNode::PORT_TYPE_VECTOR_3D, "Bent Normal Map", "BENT_NORMAL_MAP" },
 
+	{ Shader::MODE_SPATIAL, VisualShader::TYPE_FRAGMENT, VisualShaderNode::PORT_TYPE_SCALAR, "Sheen", "SHEEN" },
+	{ Shader::MODE_SPATIAL, VisualShader::TYPE_FRAGMENT, VisualShaderNode::PORT_TYPE_SCALAR, "Sheen Roughness", "SHEEN_ROUGHNESS" },
+	{ Shader::MODE_SPATIAL, VisualShader::TYPE_FRAGMENT, VisualShaderNode::PORT_TYPE_VECTOR_3D, "Sheen Color", "SHEEN_COLOR" },
+
 	////////////////////////////////////////////////////////////////////////
 	// Spatial, Light.
 	////////////////////////////////////////////////////////////////////////

scene/resources/material.cpp

@@ -569,6 +569,9 @@ void BaseMaterial3D::init_shaders() {
 	shader_names->normal_scale = "normal_scale";
 	shader_names->rim = "rim";
 	shader_names->rim_tint = "rim_tint";
+	shader_names->sheen = "sheen";
+	shader_names->sheen_roughness = "sheen_roughness";
+	shader_names->sheen_color = "sheen_color";
 	shader_names->clearcoat = "clearcoat";
 	shader_names->clearcoat_roughness = "clearcoat_roughness";
 	shader_names->anisotropy = "anisotropy_ratio";
@@ -604,6 +607,7 @@ void BaseMaterial3D::init_shaders() {
 
 	shader_names->metallic_texture_channel = "metallic_texture_channel";
 	shader_names->ao_texture_channel = "ao_texture_channel";
+	shader_names->sheen_texture_channel = "sheen_texture_channel";
 	shader_names->clearcoat_texture_channel = "clearcoat_texture_channel";
 	shader_names->rim_texture_channel = "rim_texture_channel";
 	shader_names->heightmap_texture_channel = "heightmap_texture_channel";
@@ -620,6 +624,7 @@ void BaseMaterial3D::init_shaders() {
 	shader_names->texture_names[TEXTURE_NORMAL] = "texture_normal";
 	shader_names->texture_names[TEXTURE_BENT_NORMAL] = "texture_bent_normal";
 	shader_names->texture_names[TEXTURE_RIM] = "texture_rim";
+	shader_names->texture_names[TEXTURE_SHEEN] = "texture_sheen";
 	shader_names->texture_names[TEXTURE_CLEARCOAT] = "texture_clearcoat";
 	shader_names->texture_names[TEXTURE_FLOWMAP] = "texture_flowmap";
 	shader_names->texture_names[TEXTURE_AMBIENT_OCCLUSION] = "texture_ambient_occlusion";
@@ -1076,6 +1081,15 @@ uniform sampler2D texture_bent_normal : hint_roughness_normal, %s;
 uniform float rim : hint_range(0.0, 1.0, 0.01);
 uniform float rim_tint : hint_range(0.0, 1.0, 0.01);
 uniform sampler2D texture_rim : hint_default_white, %s;
+)",
+				texfilter_str);
+	}
+	if (features[FEATURE_SHEEN]) {
+		code += vformat(R"(
+uniform float sheen : hint_range(0.0, 1.0, 0.01);
+uniform float sheen_roughness : hint_range(0.0, 1.0, 0.01);
+uniform vec3 sheen_color : source_color;
+uniform sampler2D texture_sheen : hint_default_white, %s;
 )",
 				texfilter_str);
 	}
@@ -1877,6 +1891,21 @@ void fragment() {)";
 )";
 	}
 
+	if (features[FEATURE_SHEEN]) {
+		code += R"(
+	// Sheen: Enabled
+)";
+		if (flags[FLAG_UV1_USE_TRIPLANAR]) {
+			code += "	vec2 sheen_tex = triplanar_texture(texture_sheen, uv1_power_normal, uv1_triplanar_pos).xy;\n";
+		} else {
+			code += "	vec2 sheen_tex = texture(texture_sheen, base_uv).xy;\n";
+		}
+		code += R"(	SHEEN = sheen * sheen_tex.x;
+	SHEEN_ROUGHNESS = sheen_roughness * sheen_tex.y;
+	SHEEN_COLOR = sheen_color;
+)";
+	}
+
 	if (features[FEATURE_CLEARCOAT]) {
 		code += R"(
 	// Clearcoat: Enabled
@@ -2224,6 +2253,33 @@ float BaseMaterial3D::get_ao_light_affect() const {
 	return ao_light_affect;
 }
 
+void BaseMaterial3D::set_sheen(float p_sheen) {
+	sheen = p_sheen;
+	_material_set_param(shader_names->sheen, p_sheen);
+}
+
+float BaseMaterial3D::get_sheen() const {
+	return sheen;
+}
+
+void BaseMaterial3D::set_sheen_roughness(float p_sheen_roughness) {
+	sheen_roughness = p_sheen_roughness;
+	_material_set_param(shader_names->sheen_roughness, p_sheen_roughness);
+}
+
+float BaseMaterial3D::get_sheen_roughness() const {
+	return sheen_roughness;
+}
+
+void BaseMaterial3D::set_sheen_color(const Color &p_sheen_color) {
+	sheen_color = p_sheen_color;
+	_material_set_param(shader_names->sheen_color, p_sheen_color);
+}
+
+Color BaseMaterial3D::get_sheen_color() const {
+	return sheen_color;
+}
+
 void BaseMaterial3D::set_clearcoat(float p_clearcoat) {
 	clearcoat = p_clearcoat;
 	_material_set_param(shader_names->clearcoat, p_clearcoat);
@@ -2703,6 +2759,10 @@ void BaseMaterial3D::_validate_property(PropertyInfo &p_property) const {
 			p_property.usage = PROPERTY_USAGE_NONE;
 		}
 
+		if (p_property.name.begins_with("sheen")) {
+			p_property.usage = PROPERTY_USAGE_NONE;
+		}
+
 		if (p_property.name.begins_with("clearcoat")) {
 			p_property.usage = PROPERTY_USAGE_NONE;
 		}
@@ -3366,6 +3426,15 @@ void BaseMaterial3D::_bind_methods() {
 	ClassDB::bind_method(D_METHOD("set_rim_tint", "rim_tint"), &BaseMaterial3D::set_rim_tint);
 	ClassDB::bind_method(D_METHOD("get_rim_tint"), &BaseMaterial3D::get_rim_tint);
 
+	ClassDB::bind_method(D_METHOD("set_sheen", "sheen"), &BaseMaterial3D::set_sheen);
+	ClassDB::bind_method(D_METHOD("get_sheen"), &BaseMaterial3D::get_sheen);
+
+	ClassDB::bind_method(D_METHOD("set_sheen_roughness", "sheen_roughness"), &BaseMaterial3D::set_sheen_roughness);
+	ClassDB::bind_method(D_METHOD("get_sheen_roughness"), &BaseMaterial3D::get_sheen_roughness);
+
+	ClassDB::bind_method(D_METHOD("set_sheen_color", "sheen_color"), &BaseMaterial3D::set_sheen_color);
+	ClassDB::bind_method(D_METHOD("get_sheen_color"), &BaseMaterial3D::get_sheen_color);
+
 	ClassDB::bind_method(D_METHOD("set_clearcoat", "clearcoat"), &BaseMaterial3D::set_clearcoat);
 	ClassDB::bind_method(D_METHOD("get_clearcoat"), &BaseMaterial3D::get_clearcoat);
 
@@ -3624,6 +3693,13 @@ void BaseMaterial3D::_bind_methods() {
 	ADD_PROPERTY(PropertyInfo(Variant::FLOAT, "rim_tint", PROPERTY_HINT_RANGE, "0,1,0.01"), "set_rim_tint", "get_rim_tint");
 	ADD_PROPERTYI(PropertyInfo(Variant::OBJECT, "rim_texture", PROPERTY_HINT_RESOURCE_TYPE, Texture2D::get_class_static()), "set_texture", "get_texture", TEXTURE_RIM);
 
+	ADD_GROUP("Sheen", "sheen_");
+	ADD_PROPERTYI(PropertyInfo(Variant::BOOL, "sheen_enabled", PROPERTY_HINT_GROUP_ENABLE), "set_feature", "get_feature", FEATURE_SHEEN);
+	ADD_PROPERTY(PropertyInfo(Variant::FLOAT, "sheen", PROPERTY_HINT_RANGE, "0,1,0.01"), "set_sheen", "get_sheen");
+	ADD_PROPERTY(PropertyInfo(Variant::FLOAT, "sheen_roughness", PROPERTY_HINT_RANGE, "0,1,0.01"), "set_sheen_roughness", "get_sheen_roughness");
+	ADD_PROPERTY(PropertyInfo(Variant::COLOR, "sheen_color"), "set_sheen_color", "get_sheen_color");
+	ADD_PROPERTYI(PropertyInfo(Variant::OBJECT, "sheen_texture", PROPERTY_HINT_RESOURCE_TYPE, "Texture2D"), "set_texture", "get_texture", TEXTURE_SHEEN);
+
 	ADD_GROUP("Clearcoat", "clearcoat_");
 	ADD_PROPERTYI(PropertyInfo(Variant::BOOL, "clearcoat_enabled", PROPERTY_HINT_GROUP_ENABLE), "set_feature", "get_feature", FEATURE_CLEARCOAT);
 	ADD_PROPERTY(PropertyInfo(Variant::FLOAT, "clearcoat", PROPERTY_HINT_RANGE, "0,1,0.01"), "set_clearcoat", "get_clearcoat");
@@ -3759,6 +3835,7 @@ void BaseMaterial3D::_bind_methods() {
 	BIND_ENUM_CONSTANT(TEXTURE_NORMAL);
 	BIND_ENUM_CONSTANT(TEXTURE_BENT_NORMAL);
 	BIND_ENUM_CONSTANT(TEXTURE_RIM);
+	BIND_ENUM_CONSTANT(TEXTURE_SHEEN);
 	BIND_ENUM_CONSTANT(TEXTURE_CLEARCOAT);
 	BIND_ENUM_CONSTANT(TEXTURE_FLOWMAP);
 	BIND_ENUM_CONSTANT(TEXTURE_AMBIENT_OCCLUSION);
@@ -3809,6 +3886,7 @@ void BaseMaterial3D::_bind_methods() {
 	BIND_ENUM_CONSTANT(FEATURE_REFRACTION);
 	BIND_ENUM_CONSTANT(FEATURE_DETAIL);
 	BIND_ENUM_CONSTANT(FEATURE_BENT_NORMAL_MAPPING);
+	BIND_ENUM_CONSTANT(FEATURE_SHEEN);
 	BIND_ENUM_CONSTANT(FEATURE_MAX);
 
 	BIND_ENUM_CONSTANT(BLEND_MODE_MIX);
@@ -3918,7 +3996,10 @@ BaseMaterial3D::BaseMaterial3D(bool p_orm) :
 	set_normal_scale(1);
 	set_rim(1.0);
 	set_rim_tint(0.5);
-	set_clearcoat(1);
+	set_sheen(1.0);
+	set_sheen_roughness(0.5);
+	set_sheen_color(Color(1, 1, 1));
+	set_clearcoat(1.0);
 	set_clearcoat_roughness(0.5);
 	set_anisotropy(0);
 	set_heightmap_scale(5.0);

scene/resources/material.h

@@ -164,6 +164,7 @@ class BaseMaterial3D : public Material {
 		TEXTURE_DETAIL_NORMAL,
 		TEXTURE_ORM,
 		TEXTURE_BENT_NORMAL,
+		TEXTURE_SHEEN,
 		TEXTURE_MAX
 	};
 
@@ -220,6 +221,7 @@ class BaseMaterial3D : public Material {
 		FEATURE_REFRACTION,
 		FEATURE_DETAIL,
 		FEATURE_BENT_NORMAL_MAPPING,
+		FEATURE_SHEEN,
 		FEATURE_MAX
 	};
 
@@ -471,6 +473,9 @@ class BaseMaterial3D : public Material {
 		StringName normal_scale;
 		StringName rim;
 		StringName rim_tint;
+		StringName sheen;
+		StringName sheen_roughness;
+		StringName sheen_color;
 		StringName clearcoat;
 		StringName clearcoat_roughness;
 		StringName anisotropy;
@@ -504,6 +509,7 @@ class BaseMaterial3D : public Material {
 
 		StringName metallic_texture_channel;
 		StringName ao_texture_channel;
+		StringName sheen_texture_channel;
 		StringName clearcoat_texture_channel;
 		StringName rim_texture_channel;
 		StringName heightmap_texture_channel;
@@ -545,6 +551,9 @@ class BaseMaterial3D : public Material {
 	float normal_scale = 0.0f;
 	float rim = 0.0f;
 	float rim_tint = 0.0f;
+	float sheen = 0.0f;
+	float sheen_roughness = 0.0f;
+	Color sheen_color;
 	float clearcoat = 0.0f;
 	float clearcoat_roughness = 0.0f;
 	float anisotropy = 0.0f;
@@ -675,6 +684,15 @@ class BaseMaterial3D : public Material {
 	void set_ao_light_affect(float p_ao_light_affect);
 	float get_ao_light_affect() const;
 
+	void set_sheen(float p_sheen);
+	float get_sheen() const;
+
+	void set_sheen_roughness(float p_sheen_roughness);
+	float get_sheen_roughness() const;
+
+	void set_sheen_color(const Color &p_sheen_color);
+	Color get_sheen_color() const;
+
 	void set_clearcoat(float p_clearcoat);
 	float get_clearcoat() const;
 

servers/rendering/renderer_rd/forward_clustered/scene_shader_forward_clustered.cpp

@@ -756,6 +756,9 @@ void SceneShaderForwardClustered::init(const String p_defines) {
 		actions.renames["ROUGHNESS"] = "roughness_highp";
 		actions.renames["RIM"] = "rim";
 		actions.renames["RIM_TINT"] = "rim_tint";
+		actions.renames["SHEEN"] = "sheen";
+		actions.renames["SHEEN_ROUGHNESS"] = "sheen_roughness";
+		actions.renames["SHEEN_COLOR"] = "sheen_color";
 		actions.renames["CLEARCOAT"] = "clearcoat";
 		actions.renames["CLEARCOAT_ROUGHNESS"] = "clearcoat_roughness";
 		actions.renames["ANISOTROPY"] = "anisotropy";
@@ -813,6 +816,9 @@ void SceneShaderForwardClustered::init(const String p_defines) {
 		actions.usage_defines["BINORMAL"] = "@TANGENT";
 		actions.usage_defines["RIM"] = "#define LIGHT_RIM_USED\n";
 		actions.usage_defines["RIM_TINT"] = "@RIM";
+		actions.usage_defines["SHEEN"] = "#define LIGHT_SHEEN_USED\n";
+		actions.usage_defines["SHEEN_ROUGHNESS"] = "@SHEEN";
+		actions.usage_defines["SHEEN_COLOR"] = "@SHEEN";
 		actions.usage_defines["CLEARCOAT"] = "#define LIGHT_CLEARCOAT_USED\n";
 		actions.usage_defines["CLEARCOAT_ROUGHNESS"] = "@CLEARCOAT";
 		actions.usage_defines["ANISOTROPY"] = "#define LIGHT_ANISOTROPY_USED\n";