Merge pull request #22818 from cbscribe/kcc_doc_spatialmat

[DOCS] SpatialMaterial descriptions

1 files changed, 70 insertions, 0 deletions

diff --git a/doc/classes/SpatialMaterial.xml b/doc/classes/SpatialMaterial.xml
index 354c6686bb..57fb267e91 100644
--- a/doc/classes/SpatialMaterial.xml
+++ b/doc/classes/SpatialMaterial.xml
@@ -1,8 +1,10 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="SpatialMaterial" inherits="Material" category="Core" version="3.1">
 	<brief_description>
+		Default 3D rendering material.
 	</brief_description>
 	<description>
+		This provides a default material with a wide variety of rendering features and properties without the need to write shader code. See the tutorial below for details.
 	</description>
 	<tutorials>
 		<link>http://docs.godotengine.org/en/3.0/tutorials/3d/spatial_material.html</link>
@@ -13,16 +15,20 @@
 	</methods>
 	<members>
 		<member name="albedo_color" type="Color" setter="set_albedo" getter="get_albedo">
+			The material's base color.
 		</member>
 		<member name="albedo_texture" type="Texture" setter="set_texture" getter="get_texture">
 		</member>
 		<member name="anisotropy" type="float" setter="set_anisotropy" getter="get_anisotropy">
+			The strength of the anisotropy effect.
 		</member>
 		<member name="anisotropy_enabled" type="bool" setter="set_feature" getter="get_feature">
+			If [code]true[/code] anisotropy is enabled. Changes the shape of the specular blob and aligns it to tangent space. Default value: [code]false[/code].
 		</member>
 		<member name="anisotropy_flowmap" type="Texture" setter="set_texture" getter="get_texture">
 		</member>
 		<member name="ao_enabled" type="bool" setter="set_feature" getter="get_feature">
+			If [code]true[/code] ambient occlusion is enabled.
 		</member>
 		<member name="ao_light_affect" type="float" setter="set_ao_light_affect" getter="get_ao_light_affect">
 		</member>
@@ -35,6 +41,7 @@
 		<member name="clearcoat" type="float" setter="set_clearcoat" getter="get_clearcoat">
 		</member>
 		<member name="clearcoat_enabled" type="bool" setter="set_feature" getter="get_feature">
+			If [code]true[/code] clearcoat rendering is enabled. Adds a secondary transparent pass to the material. Default value: [code]false[/code].
 		</member>
 		<member name="clearcoat_gloss" type="float" setter="set_clearcoat_gloss" getter="get_clearcoat_gloss">
 		</member>
@@ -43,6 +50,7 @@
 		<member name="depth_deep_parallax" type="bool" setter="set_depth_deep_parallax" getter="is_depth_deep_parallax_enabled">
 		</member>
 		<member name="depth_enabled" type="bool" setter="set_feature" getter="get_feature">
+			If [code]true[/code] Depth mapping is enabled. See also [member normal_enabled].
 		</member>
 		<member name="depth_max_layers" type="int" setter="set_depth_deep_parallax_max_layers" getter="get_depth_deep_parallax_max_layers">
 		</member>
@@ -71,10 +79,13 @@
 		<member name="distance_fade_mode" type="int" setter="set_distance_fade" getter="get_distance_fade" enum="SpatialMaterial.DistanceFadeMode">
 		</member>
 		<member name="emission" type="Color" setter="set_emission" getter="get_emission">
+			The emitted light's color. See [member emission_enabled].
 		</member>
 		<member name="emission_enabled" type="bool" setter="set_feature" getter="get_feature">
+			If [code]true[/code] the body emits light.
 		</member>
 		<member name="emission_energy" type="float" setter="set_emission_energy" getter="get_emission_energy">
+			The emitted light's strength. See [member emission_enabled].
 		</member>
 		<member name="emission_on_uv2" type="bool" setter="set_flag" getter="get_flag">
 		</member>
@@ -85,36 +96,49 @@
 		<member name="flags_albedo_tex_force_srgb" type="bool" setter="set_flag" getter="get_flag">
 		</member>
 		<member name="flags_disable_ambient_light" type="bool" setter="set_flag" getter="get_flag">
+			If [code]true[/code] the object receives no ambient light. Default value: [code]false[/code].
 		</member>
 		<member name="flags_do_not_receive_shadows" type="bool" setter="set_flag" getter="get_flag">
+			If [code]true[/code] the object receives no shadow that would otherwise be cast onto it. Default value: [code]false[/code].
 		</member>
 		<member name="flags_ensure_correct_normals" type="bool" setter="set_flag" getter="get_flag">
 		</member>
 		<member name="flags_fixed_size" type="bool" setter="set_flag" getter="get_flag">
+			If [code]true[/code] the object is rendered at the same size regardless of distance. Default value: [code]false[/code].
 		</member>
 		<member name="flags_no_depth_test" type="bool" setter="set_flag" getter="get_flag">
+			If [code]true[/code] depth testing is disabled and the object will be drawn in render order.
 		</member>
 		<member name="flags_transparent" type="bool" setter="set_feature" getter="get_feature">
+			If [code]true[/code] transparency is enabled on the body. Default value: [code]false[/code]. See also [member params_blend_mode].
 		</member>
 		<member name="flags_unshaded" type="bool" setter="set_flag" getter="get_flag">
+			If [code]true[/code] the object is unaffected by lighting. Default value: [code]false[/code].
 		</member>
 		<member name="flags_use_point_size" type="bool" setter="set_flag" getter="get_flag">
+			If [code]true[/code] render point size can be changed. Note: this is only effective for objects whose geometry is point-based rather than triangle-based. See also [member params_point_size].
 		</member>
 		<member name="flags_vertex_lighting" type="bool" setter="set_flag" getter="get_flag">
+			If [code]true[/code] lighting is calculated per vertex rather than per pixel. This may increase performance on low-end devices. Default value: [code]false[/code].
 		</member>
 		<member name="flags_world_triplanar" type="bool" setter="set_flag" getter="get_flag">
+			If [code]true[/code] triplanar mapping is calculated in world space rather than object local space. See also [member uv1_triplanar]. Default value: [code]false[/code].
 		</member>
 		<member name="metallic" type="float" setter="set_metallic" getter="get_metallic">
+			The reflectivity of the object's surface. The higher the value the more light is reflected.
 		</member>
 		<member name="metallic_specular" type="float" setter="set_specular" getter="get_specular">
+			General reflectivity amount. Note: unlike [member metallic], this is not energy-conserving, so it should be left at [code]0.5[/code] in most cases.  See also [member roughness].
 		</member>
 		<member name="metallic_texture" type="Texture" setter="set_texture" getter="get_texture">
 		</member>
 		<member name="metallic_texture_channel" type="int" setter="set_metallic_texture_channel" getter="get_metallic_texture_channel" enum="SpatialMaterial.TextureChannel">
 		</member>
 		<member name="normal_enabled" type="bool" setter="set_feature" getter="get_feature">
+			If [code]true[/code] normal mapping is enabled.
 		</member>
 		<member name="normal_scale" type="float" setter="set_normal_scale" getter="get_normal_scale">
+			The strength of the normal map's effect.
 		</member>
 		<member name="normal_texture" type="Texture" setter="set_texture" getter="get_texture">
 		</member>
@@ -123,40 +147,55 @@
 		<member name="params_billboard_keep_scale" type="bool" setter="set_flag" getter="get_flag">
 		</member>
 		<member name="params_billboard_mode" type="int" setter="set_billboard_mode" getter="get_billboard_mode" enum="SpatialMaterial.BillboardMode">
+			Controls how the object faces the camera. See [enum BillboardMode].
 		</member>
 		<member name="params_blend_mode" type="int" setter="set_blend_mode" getter="get_blend_mode" enum="SpatialMaterial.BlendMode">
+			The material's blend mode. Note that values other than [code]Mix[/code] force the object into the transparent pipeline. See [enum BlendMode].
 		</member>
 		<member name="params_cull_mode" type="int" setter="set_cull_mode" getter="get_cull_mode" enum="SpatialMaterial.CullMode">
+			Which side of the object is not drawn when backfaces are rendered. See [enum CullMode].
 		</member>
 		<member name="params_depth_draw_mode" type="int" setter="set_depth_draw_mode" getter="get_depth_draw_mode" enum="SpatialMaterial.DepthDrawMode">
+			Determines when depth rendering takes place. See [enum DepthDrawMode]. See also [member flags_transparent].
 		</member>
 		<member name="params_diffuse_mode" type="int" setter="set_diffuse_mode" getter="get_diffuse_mode" enum="SpatialMaterial.DiffuseMode">
+			The algorithm used for diffuse light scattering. See [enum DiffuseMode].
 		</member>
 		<member name="params_grow" type="bool" setter="set_grow_enabled" getter="is_grow_enabled">
+			If [code]true[/code] enables the vertex grow setting. See [member params_grow_amount].
 		</member>
 		<member name="params_grow_amount" type="float" setter="set_grow" getter="get_grow">
+			Grows object vertices in the direction of their normals.
 		</member>
 		<member name="params_line_width" type="float" setter="set_line_width" getter="get_line_width">
 		</member>
 		<member name="params_point_size" type="float" setter="set_point_size" getter="get_point_size">
+			The point size in pixels. See [member flags_use_point_size].
 		</member>
 		<member name="params_specular_mode" type="int" setter="set_specular_mode" getter="get_specular_mode" enum="SpatialMaterial.SpecularMode">
+			The method for rendering the specular blob. See [enum SpecularMode].
 		</member>
 		<member name="params_use_alpha_scissor" type="bool" setter="set_flag" getter="get_flag">
 		</member>
 		<member name="particles_anim_h_frames" type="int" setter="set_particles_anim_h_frames" getter="get_particles_anim_h_frames">
+			The number of horizontal frames in the particle spritesheet. Only enabled when using [code]BillboardMode.BILLBOARD_PARTICLES[/code]. See [member params_billboard_mode].
 		</member>
 		<member name="particles_anim_loop" type="int" setter="set_particles_anim_loop" getter="get_particles_anim_loop">
+			If [code]true[/code] particle animations are looped. Only enabled when using [code]BillboardMode.BILLBOARD_PARTICLES[/code]. See [member params_billboard_mode].
 		</member>
 		<member name="particles_anim_v_frames" type="int" setter="set_particles_anim_v_frames" getter="get_particles_anim_v_frames">
+			The number of vertical frames in the particle spritesheet. Only enabled when using [code]BillboardMode.BILLBOARD_PARTICLES[/code]. See [member params_billboard_mode].
 		</member>
 		<member name="proximity_fade_distance" type="float" setter="set_proximity_fade_distance" getter="get_proximity_fade_distance">
 		</member>
 		<member name="proximity_fade_enable" type="bool" setter="set_proximity_fade" getter="is_proximity_fade_enabled">
+			If [code]true[/code] the proximity and distance fade effect is enabled. Default value: [code]false[/code].
 		</member>
 		<member name="refraction_enabled" type="bool" setter="set_feature" getter="get_feature">
+			If [code]true[/code] the refraction effect is enabled. Distorts transparency based on light from behind the object. Default value: [code]false[/code].
 		</member>
 		<member name="refraction_scale" type="float" setter="set_refraction" getter="get_refraction">
+			The strength of the refraction effect.
 		</member>
 		<member name="refraction_texture" type="Texture" setter="set_texture" getter="get_texture">
 		</member>
@@ -165,26 +204,33 @@
 		<member name="rim" type="float" setter="set_rim" getter="get_rim">
 		</member>
 		<member name="rim_enabled" type="bool" setter="set_feature" getter="get_feature">
+			If [code]true[/code] rim effect is enabled. Default value: [code]false[/code].
 		</member>
 		<member name="rim_texture" type="Texture" setter="set_texture" getter="get_texture">
 		</member>
 		<member name="rim_tint" type="float" setter="set_rim_tint" getter="get_rim_tint">
+			The amount of to blend light and albedo color when rendering rim effect. If [code]0[/code] the light color is used, while [code]1[/code] means albedo color is used. An intermediate value generally works best.
 		</member>
 		<member name="roughness" type="float" setter="set_roughness" getter="get_roughness">
+			Surface reflection. A value of [code]0[/code] represents a perfect mirror while a value of [code]1[/code] completely blurs the reflection. See also [member metallic].
 		</member>
 		<member name="roughness_texture" type="Texture" setter="set_texture" getter="get_texture">
 		</member>
 		<member name="roughness_texture_channel" type="int" setter="set_roughness_texture_channel" getter="get_roughness_texture_channel" enum="SpatialMaterial.TextureChannel">
 		</member>
 		<member name="subsurf_scatter_enabled" type="bool" setter="set_feature" getter="get_feature">
+			If [code]true[/code] subsurface scattering is enabled. Emulates light that penetrates an object's surface, is scattered, and then emerges.
 		</member>
 		<member name="subsurf_scatter_strength" type="float" setter="set_subsurface_scattering_strength" getter="get_subsurface_scattering_strength">
+			The strength of the subsurface scattering effect.
 		</member>
 		<member name="subsurf_scatter_texture" type="Texture" setter="set_texture" getter="get_texture">
 		</member>
 		<member name="transmission" type="Color" setter="set_transmission" getter="get_transmission">
+			The color used by the transmission effect. Represents the light passing through an object.
 		</member>
 		<member name="transmission_enabled" type="bool" setter="set_feature" getter="get_feature">
+			If [code]true[/code] the transmission effect is enabled. Default value: [code]false[/code].
 		</member>
 		<member name="transmission_texture" type="Texture" setter="set_texture" getter="get_texture">
 		</member>
@@ -205,8 +251,10 @@
 		<member name="uv2_triplanar_sharpness" type="float" setter="set_uv2_triplanar_blend_sharpness" getter="get_uv2_triplanar_blend_sharpness">
 		</member>
 		<member name="vertex_color_is_srgb" type="bool" setter="set_flag" getter="get_flag">
+			If [code]true[/code] the model's vertex colors are processed as sRGB mode. Default value: [code]false[/code].
 		</member>
 		<member name="vertex_color_use_as_albedo" type="bool" setter="set_flag" getter="get_flag">
+			If [code]true[/code] the vertex color is used as albedo color. Default value: [code]false[/code].
 		</member>
 	</members>
 	<constants>
@@ -275,6 +323,7 @@
 		<constant name="FEATURE_MAX" value="12" enum="Feature">
 		</constant>
 		<constant name="BLEND_MODE_MIX" value="0" enum="BlendMode">
+			Default blend mode.
 		</constant>
 		<constant name="BLEND_MODE_ADD" value="1" enum="BlendMode">
 		</constant>
@@ -283,18 +332,25 @@
 		<constant name="BLEND_MODE_MUL" value="3" enum="BlendMode">
 		</constant>
 		<constant name="DEPTH_DRAW_OPAQUE_ONLY" value="0" enum="DepthDrawMode">
+			Default depth draw mode. Depth is drawn only for opaque objects.
 		</constant>
 		<constant name="DEPTH_DRAW_ALWAYS" value="1" enum="DepthDrawMode">
+			Depth draw is calculated for both opaque and transparent objects.
 		</constant>
 		<constant name="DEPTH_DRAW_DISABLED" value="2" enum="DepthDrawMode">
+			No depth draw.
 		</constant>
 		<constant name="DEPTH_DRAW_ALPHA_OPAQUE_PREPASS" value="3" enum="DepthDrawMode">
+			For transparent objects, an opaque pass is made first with the opaque parts, then transparency is drawn.
 		</constant>
 		<constant name="CULL_BACK" value="0" enum="CullMode">
+			Default cull mode. The back of the object is culled when not visible.
 		</constant>
 		<constant name="CULL_FRONT" value="1" enum="CullMode">
+			The front of the object is culled when not visible.
 		</constant>
 		<constant name="CULL_DISABLED" value="2" enum="CullMode">
+			No culling is performed.
 		</constant>
 		<constant name="FLAG_UNSHADED" value="0" enum="Flags">
 		</constant>
@@ -335,32 +391,46 @@
 		<constant name="FLAG_MAX" value="18" enum="Flags">
 		</constant>
 		<constant name="DIFFUSE_BURLEY" value="0" enum="DiffuseMode">
+			Default diffuse scattering algorithm.
 		</constant>
 		<constant name="DIFFUSE_LAMBERT" value="1" enum="DiffuseMode">
+			Diffuse scattering ignores roughness.
 		</constant>
 		<constant name="DIFFUSE_LAMBERT_WRAP" value="2" enum="DiffuseMode">
+			Extends Lambert to cover more than 90 degrees when roughness increases.
 		</constant>
 		<constant name="DIFFUSE_OREN_NAYAR" value="3" enum="DiffuseMode">
+			Attempts to use roughness to emulate microsurfacing.
 		</constant>
 		<constant name="DIFFUSE_TOON" value="4" enum="DiffuseMode">
+			Uses a hard cut for lighting, with smoothing affected by roughness.
 		</constant>
 		<constant name="SPECULAR_SCHLICK_GGX" value="0" enum="SpecularMode">
+			Default specular blob.
 		</constant>
 		<constant name="SPECULAR_BLINN" value="1" enum="SpecularMode">
+			Older specular algorithm, included for compatibility.
 		</constant>
 		<constant name="SPECULAR_PHONG" value="2" enum="SpecularMode">
+			Older specular algorithm, included for compatibility.
 		</constant>
 		<constant name="SPECULAR_TOON" value="3" enum="SpecularMode">
+			Toon blob which changes size based on roughness.
 		</constant>
 		<constant name="SPECULAR_DISABLED" value="4" enum="SpecularMode">
+			No specular blob.
 		</constant>
 		<constant name="BILLBOARD_DISABLED" value="0" enum="BillboardMode">
+			Default value.
 		</constant>
 		<constant name="BILLBOARD_ENABLED" value="1" enum="BillboardMode">
+			The object's z-axis will always face the camera.
 		</constant>
 		<constant name="BILLBOARD_FIXED_Y" value="2" enum="BillboardMode">
+			The object's x-axis will always face the camera.
 		</constant>
 		<constant name="BILLBOARD_PARTICLES" value="3" enum="BillboardMode">
+			Used for particle systems. Enables particle animation options.
 		</constant>
 		<constant name="TEXTURE_CHANNEL_RED" value="0" enum="TextureChannel">
 		</constant>