diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/classes/PanoramaSkyMaterial.xml (renamed from doc/classes/PanoramaSky.xml) | 8 | ||||
| -rw-r--r-- | doc/classes/PhysicalSkyMaterial.xml | 49 | ||||
| -rw-r--r-- | doc/classes/ProceduralSky.xml | 84 | ||||
| -rw-r--r-- | doc/classes/ProceduralSkyMaterial.xml | 52 | ||||
| -rw-r--r-- | doc/classes/ProjectSettings.xml | 4 | ||||
| -rw-r--r-- | doc/classes/Shader.xml | 3 | ||||
| -rw-r--r-- | doc/classes/Sky.xml | 11 | ||||
| -rw-r--r-- | doc/classes/VisualServer.xml | 10 |
8 files changed, 124 insertions, 97 deletions
diff --git a/doc/classes/PanoramaSky.xml b/doc/classes/PanoramaSkyMaterial.xml index 0ddf1cb054..905a2dd506 100644 --- a/doc/classes/PanoramaSky.xml +++ b/doc/classes/PanoramaSkyMaterial.xml @@ -1,10 +1,10 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="PanoramaSky" inherits="Sky" version="4.0"> +<class name="PanoramaSkyMaterial" inherits="Material" version="4.0"> <brief_description> - A type of [Sky] used to draw a background texture. + A [Material] used with [Sky] to draw a background texture. </brief_description> <description> - A resource referenced in an [Environment] that is used to draw a background. The Panorama sky functions similar to skyboxes in other engines, except it uses an equirectangular sky map instead of a cube map. + A resource referenced in a [Sky] that is used to draw a background. The Panorama sky material functions similar to skyboxes in other engines, except it uses an equirectangular sky map instead of a cube map. Using an HDR panorama is strongly recommended for accurate, high-quality reflections. Godot supports the Radiance HDR ([code].hdr[/code]) and OpenEXR ([code].exr[/code]) image formats for this purpose. You can use [url=https://danilw.github.io/GLSL-howto/cubemap_to_panorama_js/cubemap_to_panorama.html]this tool[/url] to convert a cube map to an equirectangular sky map. </description> @@ -14,7 +14,7 @@ </methods> <members> <member name="panorama" type="Texture2D" setter="set_panorama" getter="get_panorama"> - [Texture2D] to be applied to the PanoramaSky. + [Texture2D] to be applied to the [PanoramaSkyMaterial]. </member> </members> <constants> diff --git a/doc/classes/PhysicalSkyMaterial.xml b/doc/classes/PhysicalSkyMaterial.xml new file mode 100644 index 0000000000..705c063257 --- /dev/null +++ b/doc/classes/PhysicalSkyMaterial.xml @@ -0,0 +1,49 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<class name="PhysicalSkyMaterial" inherits="Material" version="4.0"> + <brief_description> + [Sky] [Material] used for a physically based sky. + </brief_description> + <description> + The [PhysicalSkyMaterial] uses the Preetham analytic daylight model to draw a sky based on physical properties. This results in a substantially more realistic sky than the [ProceduralSkyMaterial], but it is slightly slower and less flexible. + The [PhysicalSkyMaterial] only supports one sun. The color, energy, and direction of the sun are taken from the first [DirectionalLight] in the scene tree. + As it is based on a daylight model, the sky fades to black as the sunset ends. If you want a full day/night cycle, you will have to add a night sky by converting this to a [ShaderMaterial] and adding a night sky directly into the resulting shader. + </description> + <tutorials> + </tutorials> + <methods> + </methods> + <members> + <member name="dither_strength" type="float" setter="set_dither_strength" getter="get_dither_strength" default="1.0"> + Sets the amount of dithering to use. Dithering helps reduce banding that appears from the smooth changes in color in the sky. Use the lowest value possible, higher amounts may add fuzziness to the sky. + </member> + <member name="exposure" type="float" setter="set_exposure" getter="get_exposure" default="0.1"> + Sets the exposure of the sky. Higher exposure values make the entire sky brighter. + </member> + <member name="ground_color" type="Color" setter="set_ground_color" getter="get_ground_color" default="Color( 1, 1, 1, 1 )"> + Modulates the [Color] on the bottom half of the sky to represent the ground. + </member> + <member name="mie_coefficient" type="float" setter="set_mie_coefficient" getter="get_mie_coefficient" default="0.005"> + Controls the strength of mie scattering for the sky. Mie scattering results from light colliding with larger particles (like water). On earth, mie scattering results in a whiteish color around the sun and horizon. + </member> + <member name="mie_color" type="Color" setter="set_mie_color" getter="get_mie_color" default="Color( 0.36, 0.56, 0.82, 1 )"> + Controls the [Color] of the mie scattering effect. While not physically accurate, this allows for the creation of alien looking planets. + </member> + <member name="mie_eccentricity" type="float" setter="set_mie_eccentricity" getter="get_mie_eccentricity" default="0.8"> + Controls the direction of the mie scattering. A value of [code]1[/code] means that when light hits a particle it passing through straight forward. A value of [code]-1[/code] means that all light is scatter backwards. + </member> + <member name="rayleigh_coefficient" type="float" setter="set_rayleigh_coefficient" getter="get_rayleigh_coefficient" default="2.0"> + Controls the strength of the rayleigh scattering. Rayleigh scattering results from light colliding with small particles. It is responsible for the blue color of the sky. + </member> + <member name="rayleigh_color" type="Color" setter="set_rayleigh_color" getter="get_rayleigh_color" default="Color( 0.056, 0.14, 0.3, 1 )"> + Controls the [Color] of the rayleigh scattering. While not physically accurate, this allows for the creation of alien looking planets. For example, setting this to a red [Color] results in a mars looking atmosphere with a corresponding blue sunset. + </member> + <member name="sun_disk_scale" type="float" setter="set_sun_disk_scale" getter="get_sun_disk_scale" default="1.0"> + Sets the size of the sun disk. Default value is based on Sol's perceived size from Earth. + </member> + <member name="turbidity" type="float" setter="set_turbidity" getter="get_turbidity" default="10.0"> + Sets the thickness of the atmosphere. High turbidity creates a foggy looking atmosphere, while a low turbidity results in a clearer atmosphere. + </member> + </members> + <constants> + </constants> +</class> diff --git a/doc/classes/ProceduralSky.xml b/doc/classes/ProceduralSky.xml deleted file mode 100644 index 9a61fac63a..0000000000 --- a/doc/classes/ProceduralSky.xml +++ /dev/null @@ -1,84 +0,0 @@ -<?xml version="1.0" encoding="UTF-8" ?> -<class name="ProceduralSky" inherits="Sky" version="4.0"> - <brief_description> - Type of [Sky] that is generated procedurally based on user input parameters. - </brief_description> - <description> - ProceduralSky provides a way to create an effective background quickly by defining procedural parameters for the sun, the sky and the ground. The sky and ground are very similar, they are defined by a color at the horizon, another color, and finally an easing curve to interpolate between these two colors. Similarly, the sun is described by a position in the sky, a color, and an easing curve. However, the sun also defines a minimum and maximum angle, these two values define at what distance the easing curve begins and ends from the sun, and thus end up defining the size of the sun in the sky. - The ProceduralSky is updated on the CPU after the parameters change. It is stored in a texture and then displayed as a background in the scene. This makes it relatively unsuitable for real-time updates during gameplay. However, with a small enough texture size, it can still be updated relatively frequently, as it is updated on a background thread when multi-threading is available. - </description> - <tutorials> - </tutorials> - <methods> - </methods> - <members> - <member name="ground_bottom_color" type="Color" setter="set_ground_bottom_color" getter="get_ground_bottom_color" default="Color( 0.156863, 0.184314, 0.211765, 1 )"> - Color of the ground at the bottom. - </member> - <member name="ground_curve" type="float" setter="set_ground_curve" getter="get_ground_curve" default="0.02"> - How quickly the [member ground_horizon_color] fades into the [member ground_bottom_color]. - </member> - <member name="ground_energy" type="float" setter="set_ground_energy" getter="get_ground_energy" default="1.0"> - Amount of energy contribution from the ground. - </member> - <member name="ground_horizon_color" type="Color" setter="set_ground_horizon_color" getter="get_ground_horizon_color" default="Color( 0.423529, 0.396078, 0.372549, 1 )"> - Color of the ground at the horizon. - </member> - <member name="sky_curve" type="float" setter="set_sky_curve" getter="get_sky_curve" default="0.09"> - How quickly the [member sky_horizon_color] fades into the [member sky_top_color]. - </member> - <member name="sky_energy" type="float" setter="set_sky_energy" getter="get_sky_energy" default="1.0"> - Amount of energy contribution from the sky. - </member> - <member name="sky_horizon_color" type="Color" setter="set_sky_horizon_color" getter="get_sky_horizon_color" default="Color( 0.839216, 0.917647, 0.980392, 1 )"> - Color of the sky at the horizon. - </member> - <member name="sky_top_color" type="Color" setter="set_sky_top_color" getter="get_sky_top_color" default="Color( 0.647059, 0.839216, 0.945098, 1 )"> - Color of the sky at the top. - </member> - <member name="sun_angle_max" type="float" setter="set_sun_angle_max" getter="get_sun_angle_max" default="100.0"> - Distance from center of sun where it fades out completely. - </member> - <member name="sun_angle_min" type="float" setter="set_sun_angle_min" getter="get_sun_angle_min" default="1.0"> - Distance from sun where it goes from solid to starting to fade. - </member> - <member name="sun_color" type="Color" setter="set_sun_color" getter="get_sun_color" default="Color( 1, 1, 1, 1 )"> - The sun's color. - </member> - <member name="sun_curve" type="float" setter="set_sun_curve" getter="get_sun_curve" default="0.05"> - How quickly the sun fades away between [member sun_angle_min] and [member sun_angle_max]. - </member> - <member name="sun_energy" type="float" setter="set_sun_energy" getter="get_sun_energy" default="1.0"> - Amount of energy contribution from the sun. - </member> - <member name="sun_latitude" type="float" setter="set_sun_latitude" getter="get_sun_latitude" default="35.0"> - The sun's height using polar coordinates. - </member> - <member name="sun_longitude" type="float" setter="set_sun_longitude" getter="get_sun_longitude" default="0.0"> - The direction of the sun using polar coordinates. - </member> - <member name="texture_size" type="int" setter="set_texture_size" getter="get_texture_size" enum="ProceduralSky.TextureSize" default="2"> - Size of [Texture2D] that the ProceduralSky will generate. The size is set using [enum TextureSize]. - </member> - </members> - <constants> - <constant name="TEXTURE_SIZE_256" value="0" enum="TextureSize"> - Sky texture will be 256x128. - </constant> - <constant name="TEXTURE_SIZE_512" value="1" enum="TextureSize"> - Sky texture will be 512x256. - </constant> - <constant name="TEXTURE_SIZE_1024" value="2" enum="TextureSize"> - Sky texture will be 1024x512. This is the default size. - </constant> - <constant name="TEXTURE_SIZE_2048" value="3" enum="TextureSize"> - Sky texture will be 2048x1024. - </constant> - <constant name="TEXTURE_SIZE_4096" value="4" enum="TextureSize"> - Sky texture will be 4096x2048. - </constant> - <constant name="TEXTURE_SIZE_MAX" value="5" enum="TextureSize"> - Represents the size of the [enum TextureSize] enum. - </constant> - </constants> -</class> diff --git a/doc/classes/ProceduralSkyMaterial.xml b/doc/classes/ProceduralSkyMaterial.xml new file mode 100644 index 0000000000..dec0cbc120 --- /dev/null +++ b/doc/classes/ProceduralSkyMaterial.xml @@ -0,0 +1,52 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<class name="ProceduralSkyMaterial" inherits="Material" version="4.0"> + <brief_description> + A [Material] used with [Sky] to generate a background based on user input parameters. + </brief_description> + <description> + ProceduralSkyMaterial provides a way to create an effective background quickly by defining procedural parameters for the sun, the sky and the ground. The sky and ground are very similar, they are defined by a color at the horizon, another color, and finally an easing curve to interpolate between these two colors. Similarly, the sun is described by a position in the sky, a color, and an easing curve. However, the sun also defines a minimum and maximum angle, these two values define at what distance the easing curve begins and ends from the sun, and thus end up defining the size of the sun in the sky. + The [ProceduralSkyMaterial] uses a lightweight shader to draw the sky and is thus suited for real time updates. When you do not need a quick sky that is not realistic, this is a good option. + The [ProceduralSkyMaterial] supports up to 4 suns. Each sun takes its color, energy, and direction from the corresponding [DirectionalLight] in the scene. + </description> + <tutorials> + </tutorials> + <methods> + </methods> + <members> + <member name="ground_bottom_color" type="Color" setter="set_ground_bottom_color" getter="get_ground_bottom_color" default="Color( 0.12, 0.12, 0.13, 1 )"> + Color of the ground at the bottom. Blends with [member ground_horizon_color]. + </member> + <member name="ground_curve" type="float" setter="set_ground_curve" getter="get_ground_curve" default="0.02"> + How quickly the [member ground_horizon_color] fades into the [member ground_bottom_color]. + </member> + <member name="ground_energy" type="float" setter="set_ground_energy" getter="get_ground_energy" default="1.0"> + Amount of energy contribution from the ground. + </member> + <member name="ground_horizon_color" type="Color" setter="set_ground_horizon_color" getter="get_ground_horizon_color" default="Color( 0.37, 0.33, 0.31, 1 )"> + Color of the ground at the horizon. Blends with [member ground_bottom_color]. + </member> + <member name="sky_curve" type="float" setter="set_sky_curve" getter="get_sky_curve" default="0.09"> + How quickly the [member sky_horizon_color] fades into the [member sky_top_color]. + </member> + <member name="sky_energy" type="float" setter="set_sky_energy" getter="get_sky_energy" default="1.0"> + Amount of energy contribution from the sky. + </member> + <member name="sky_horizon_color" type="Color" setter="set_sky_horizon_color" getter="get_sky_horizon_color" default="Color( 0.55, 0.69, 0.81, 1 )"> + Color of the sky at the horizon. Blends with [member sky_top_color]. + </member> + <member name="sky_top_color" type="Color" setter="set_sky_top_color" getter="get_sky_top_color" default="Color( 0.35, 0.46, 0.71, 1 )"> + Color of the sky at the top. Blends with [member sky_horizon_color]. + </member> + <member name="sun_angle_max" type="float" setter="set_sun_angle_max" getter="get_sun_angle_max" default="100.0"> + Distance from center of sun where it fades out completely. + </member> + <member name="sun_angle_min" type="float" setter="set_sun_angle_min" getter="get_sun_angle_min" default="1.0"> + Distance from sun where it goes from solid to starting to fade. + </member> + <member name="sun_curve" type="float" setter="set_sun_curve" getter="get_sun_curve" default="0.05"> + How quickly the sun fades away between [member sun_angle_min] and [member sun_angle_max]. + </member> + </members> + <constants> + </constants> +</class> diff --git a/doc/classes/ProjectSettings.xml b/doc/classes/ProjectSettings.xml index 76674dcef8..79d5ffa2e7 100644 --- a/doc/classes/ProjectSettings.xml +++ b/doc/classes/ProjectSettings.xml @@ -1036,7 +1036,7 @@ <member name="rendering/quality/reflection_atlas/reflection_count" type="int" setter="" getter="" default="64"> Number of cubemaps to store in the reflection atlas. The number of [ReflectionProbe]s in a scene will be limited by this amount. A higher number requires more VRAM. </member> - <member name="rendering/quality/reflection_atlas/reflection_size" type="int" setter="" getter="" default="128"> + <member name="rendering/quality/reflection_atlas/reflection_size" type="int" setter="" getter="" default="256"> Size of cubemap faces for [ReflectionProbe]s. A higher number requires more VRAM and may make reflection probe updating slower. </member> <member name="rendering/quality/reflection_atlas/reflection_size.mobile" type="int" setter="" getter="" default="128"> @@ -1051,7 +1051,7 @@ <member name="rendering/quality/reflections/ggx_samples.mobile" type="int" setter="" getter="" default="128"> Lower-end override for [member rendering/quality/reflections/ggx_samples] on mobile devices, due to performance concerns or driver support. </member> - <member name="rendering/quality/reflections/roughness_layers" type="int" setter="" getter="" default="6"> + <member name="rendering/quality/reflections/roughness_layers" type="int" setter="" getter="" default="8"> Limits the number of layers to use in radiance maps when using importance sampling. A lower number will be slightly faster and take up less VRAM. </member> <member name="rendering/quality/reflections/texture_array_reflections" type="bool" setter="" getter="" default="true"> diff --git a/doc/classes/Shader.xml b/doc/classes/Shader.xml index 14c5d7a03c..109c500a63 100644 --- a/doc/classes/Shader.xml +++ b/doc/classes/Shader.xml @@ -66,5 +66,8 @@ <constant name="MODE_PARTICLES" value="2" enum="Mode"> Mode used to calculate particle information on a per-particle basis. Not used for drawing. </constant> + <constant name="MODE_SKY" value="3" enum="Mode"> + Mode used for drawing skies. Only works with shaders attached to [Sky] objects. + </constant> </constants> </class> diff --git a/doc/classes/Sky.xml b/doc/classes/Sky.xml index ba9c5ee661..f574f42431 100644 --- a/doc/classes/Sky.xml +++ b/doc/classes/Sky.xml @@ -1,10 +1,10 @@ <?xml version="1.0" encoding="UTF-8" ?> <class name="Sky" inherits="Resource" version="4.0"> <brief_description> - The base class for [PanoramaSky] and [ProceduralSky]. + Background that uses a [Material] to draw a sky. </brief_description> <description> - The base class for [PanoramaSky] and [ProceduralSky]. + The [Sky] class uses a [Material] to draw the background and update the reflection/radiance cubemaps. </description> <tutorials> </tutorials> @@ -14,11 +14,14 @@ <member name="process_mode" type="int" setter="set_process_mode" getter="get_process_mode" enum="Sky.ProcessMode" default="0"> Sets the method for generating the radiance map from the sky. The radiance map is a cubemap with increasingly blurry versions of the sky corresponding to different levels of roughness. Radiance maps can be expensive to calculate. See [enum ProcessMode] for options. </member> - <member name="radiance_size" type="int" setter="set_radiance_size" getter="get_radiance_size" enum="Sky.RadianceSize" default="2"> + <member name="radiance_size" type="int" setter="set_radiance_size" getter="get_radiance_size" enum="Sky.RadianceSize" default="3"> The [Sky]'s radiance map size. The higher the radiance map size, the more detailed the lighting from the [Sky] will be. See [enum RadianceSize] constants for values. [b]Note:[/b] Some hardware will have trouble with higher radiance sizes, especially [constant RADIANCE_SIZE_512] and above. Only use such high values on high-end hardware. </member> + <member name="sky_material" type="Material" setter="set_material" getter="get_material"> + [Material] used to draw the background. Can be [PanoramaSkyMaterial], [ProceduralSkyMaterial], [PhysicalSkyMaterial], or even a [ShaderMaterial] if you want to use your own custom shader. + </member> </members> <constants> <constant name="RADIANCE_SIZE_32" value="0" enum="RadianceSize"> @@ -50,7 +53,7 @@ </constant> <constant name="PROCESS_MODE_REALTIME" value="1" enum="ProcessMode"> 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 128x128 cubemaps, so [member radiance_size] must be set to [constant RADIANCE_SIZE_128]. + [b]Note:[/b] The fast filtering algorithm is limited to 256x256 cubemaps, so [member radiance_size] must be set to [constant RADIANCE_SIZE_256]. </constant> </constants> </class> diff --git a/doc/classes/VisualServer.xml b/doc/classes/VisualServer.xml index ca2058ddbb..00e0b7cdc9 100644 --- a/doc/classes/VisualServer.xml +++ b/doc/classes/VisualServer.xml @@ -2744,14 +2744,15 @@ Once finished with your RID, you will want to free the RID using the VisualServer's [method free_rid] static method. </description> </method> - <method name="sky_set_texture"> + <method name="sky_set_material"> <return type="void"> </return> <argument index="0" name="sky" type="RID"> </argument> - <argument index="1" name="panorama" type="RID"> + <argument index="1" name="material" type="RID"> </argument> <description> + Sets the material that the sky uses to render the background and reflection maps. </description> </method> <method name="spot_light_create"> @@ -3155,7 +3156,10 @@ <constant name="SHADER_PARTICLES" value="2" enum="ShaderMode"> Shader is a particle shader. </constant> - <constant name="SHADER_MAX" value="3" enum="ShaderMode"> + <constant name="SHADER_SKY" value="3" enum="ShaderMode"> + Shader is a sky shader. + </constant> + <constant name="SHADER_MAX" value="4" enum="ShaderMode"> Represents the size of the [enum ShaderMode] enum. </constant> <constant name="ARRAY_VERTEX" value="0" enum="ArrayType"> |