diff --git a/examples/worlds/shadow_texture_size.sdf b/examples/worlds/shadow_texture_size.sdf new file mode 100644 index 0000000000..c79a5075c5 --- /dev/null +++ b/examples/worlds/shadow_texture_size.sdf @@ -0,0 +1,73 @@ + + + + + 0.1 0.1 0.1 + 0.0 0.0 0.0 + + + + + + ogre2 + -10 0 7 0 0.5 0 + + 8192 + + + + + + + + + + 0 0 8 0 0 0 + 1 1 1 1 + 0 0 0 0 + + 50 + 0 + 0 + 0 + + true + -2 2 -1.5 + 1.0 + + + + + 0 0 0 0 0 -1.57 + + https://fuel.gazebosim.org/1.0/OpenRobotics/models/Garden Mascot + + + + + -5 0 -0.5 0 0 0 + true + + + + + 15 15 1 + + + + + + + 15 15 1 + + + + 0.8 0.8 0.8 1 + 0.8 0.8 0.8 1 + 0.8 0.8 0.8 1 + + + + + + diff --git a/tutorials.md.in b/tutorials.md.in index e88b8f7137..b6f895ec5d 100644 --- a/tutorials.md.in +++ b/tutorials.md.in @@ -54,6 +54,7 @@ If you are an absolute beginner, start with the Tutorials section. * \subpage logicalaudiosensor "Logical Audio Sensor": Using the LogicalAudioSensor system to mimic logical audio emission and detection in simulation. * \subpage auto_inertia_calculation "Automatic Inertia Calculation": Automatically compute inertia values(mass, mass matrix, center of mass) for SDFormat links. * \subpage jointcontrollers "Joint Controllers": Using available joint controller plugins to control joints. +* \subpage shadow_texture_size "Shadow texture size": Change the texture size of shadows casted by lights. ### Advanced diff --git a/tutorials/files/shadow_texture_size/shadow_texsize_2k_to_16k.gif b/tutorials/files/shadow_texture_size/shadow_texsize_2k_to_16k.gif new file mode 100644 index 0000000000..09cfabbea8 Binary files /dev/null and b/tutorials/files/shadow_texture_size/shadow_texsize_2k_to_16k.gif differ diff --git a/tutorials/shadow_texture_size.md b/tutorials/shadow_texture_size.md new file mode 100644 index 0000000000..b117370deb --- /dev/null +++ b/tutorials/shadow_texture_size.md @@ -0,0 +1,118 @@ +\page shadow_texture_size Shadow Texture Size + +This tutorial showcases how to change the texture size of shadows casted by lights. + +
+ \image html files/shadow_texture_size/shadow_texsize_2k_to_16k.gif width=60% +
+ +## Texture size options + +Supported texture sizes include: 512px, 1024px, 2048px, 4096px, 8192px, 16384px. + +The default shadow texture size for all lights is 2K. The default max texture size is 16K, but for less powerful computers, it may be a lower value, like 8K. + +## Changing shadow texture size + +The shadow texture size can be changed for the GUI with the usage of the Minimal Scene GUI plugin in the SDF. + +Currently, light type is restricted to only directional light. As a scene should typically have at most one directional light (representing the sun), this will ensure that an increase in shadow texture size does not increase VRAM too much. + +### Example usage for the GUI + +Let's change the shadow texture size for directional light with the SDF file below. (The finished SDF file can be viewed [here](https://github.com/gazebosim/gz-sim/tree/gz-sim9/examples/worlds/shadow_texture_size.sdf).) + +1) Save the below in an SDF file named `shadow_texture_size.sdf`: + +```xml + + + + + 0.1 0.1 0.1 + 0.0 0.0 0.0 + + + + + + ogre2 + -10 0 7 0 0.5 0 + + + + + + + + + 0 0 8 0 0 0 + 1 1 1 1 + 0 0 0 0 + + 50 + 0 + 0 + 0 + + true + -2 2 -1.5 + 1.0 + + + + + 0 0 0 0 0 -1.57 + + https://fuel.gazebosim.org/1.0/OpenRobotics/models/Garden Mascot + + + + + -5 0 -0.5 0 0 0 + true + + + + + 15 15 1 + + + + + + + 15 15 1 + + + + 0.8 0.8 0.8 1 + 0.8 0.8 0.8 1 + 0.8 0.8 0.8 1 + + + + + + +``` + +2) Add the following lines to the Minimal Scene GUI plugin. + +```xml + + 8192 + +``` + +The `` value can be changed as per the Texture size options section. + +3) Open the `shadow_texsize_demo.sdf` world with + +```bash +gz sim shadow_texture_size.sdf +``` + +## Impact on VRAM usage + +Keep in mind that the larger the shadow texture size, the more VRAM is used. Thus, in a scene populated with many lights, changing the directional light's shadow texture size should be fine because there is typically only one directional light in a scene. But if the scene has many point lights and the point light's shadow texture size is increased, the VRAM consumption goes up significantly.