Skip to content

Add tutorial + example SDF for shadow texture size #2597

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 13 commits into from
Sep 10, 2024
Merged

Add tutorial + example SDF for shadow texture size #2597

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
573f20e
Add tutorial + example SDF
athenaz2 Sep 5, 2024
f4b807e
Clean up whitespace
athenaz2 Sep 5, 2024
391726a
Merge branch 'gz-sim9' into athenaz/texsize_tutorial
azeey Sep 5, 2024
9a28bd1
Merge branch 'gz-sim9' into athenaz/texsize_tutorial
athenaz2 Sep 6, 2024
0bdc2a0
Apply suggestions from code review
athenaz2 Sep 6, 2024
0d21682
Update shadow_texture_size.sdf
athenaz2 Sep 6, 2024
b48725b
Update shadow_texture_size.md
athenaz2 Sep 6, 2024
ba5ca5d
Merge branch 'gz-sim9' into athenaz/texsize_tutorial
athenaz2 Sep 6, 2024
293560f
Update shadow_texture_size.md
athenaz2 Sep 6, 2024
8a75772
Merge branch 'gz-sim9' into athenaz/texsize_tutorial
iche033 Sep 6, 2024
41431c0
Merge branch 'gz-sim9' into athenaz/texsize_tutorial
ahcorde Sep 9, 2024
20891d5
Merge branch 'gz-sim9' into athenaz/texsize_tutorial
ahcorde Sep 9, 2024
a07babe
Merge branch 'gz-sim9' into athenaz/texsize_tutorial
ahcorde Sep 10, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
73 changes: 73 additions & 0 deletions examples/worlds/shadow_texture_size.sdf
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
<?xml version="1.0" ?>
<sdf version="1.9">
<world name="default">
<scene>
<background>0.1 0.1 0.1</background>
<ambient>0.0 0.0 0.0</ambient>
</scene>

<!--GUI plugins-->
<gui>
<plugin filename="MinimalScene" name="3D View">
<engine>ogre2</engine>
<camera_pose>-10 0 7 0 0.5 0</camera_pose>
<shadows>
<texture_size light_type="directional">8192</texture_size>
</shadows>
</plugin>

<plugin filename="GzSceneManager" name="Scene Manager"/>
<plugin filename="InteractiveViewControl" name="Interactive view control"/>
</gui>

<!--lighting-->
<light type="directional" name="sun">
<pose>0 0 8 0 0 0</pose>
<diffuse>1 1 1 1</diffuse>
<specular>0 0 0 0</specular>
<attenuation>
<range>50</range>
<constant>0</constant>
<linear>0</linear>
<quadratic>0</quadratic>
</attenuation>
<cast_shadows>true</cast_shadows>
<direction>-2 2 -1.5</direction>
<intensity>1.0</intensity>
</light>

<!--scene objects-->
<include>
<pose>0 0 0 0 0 -1.57</pose>
<uri>
https://fuel.gazebosim.org/1.0/OpenRobotics/models/Garden Mascot
</uri>
</include>

<model name="floor">
<pose>-5 0 -0.5 0 0 0</pose>
<static>true</static>
<link name="link">
<collision name="collision">
<geometry>
<box>
<size>15 15 1</size>
</box>
</geometry>
</collision>
<visual name="visual">
<geometry>
<box>
<size>15 15 1</size>
</box>
</geometry>
<material>
<ambient>0.8 0.8 0.8 1</ambient>
<diffuse>0.8 0.8 0.8 1</diffuse>
<specular>0.8 0.8 0.8 1</specular>
</material>
</visual>
</link>
</model>
</world>
</sdf>
1 change: 1 addition & 0 deletions tutorials.md.in
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
Binary file added tutorials/files/shadow_texture_size/shadow_texsize_2k_to_16k.gif
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
118 changes: 118 additions & 0 deletions tutorials/shadow_texture_size.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.

<div style="text-align:center;">
\image html files/shadow_texture_size/shadow_texsize_2k_to_16k.gif width=60%
</div>

## 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
<?xml version="1.0" ?>
<sdf version="1.9">
<world name="default">
<scene>
<background>0.1 0.1 0.1</background>
<ambient>0.0 0.0 0.0</ambient>
</scene>

<!--GUI plugins-->
<gui>
<plugin filename="MinimalScene" name="3D View">
<engine>ogre2</engine>
<camera_pose>-10 0 7 0 0.5 0</camera_pose>
</plugin>

<plugin filename="GzSceneManager" name="Scene Manager"/>
<plugin filename="InteractiveViewControl" name="Interactive view control"/>
</gui>

<!--lighting-->
<light type="directional" name="sun">
<pose>0 0 8 0 0 0</pose>
<diffuse>1 1 1 1</diffuse>
<specular>0 0 0 0</specular>
<attenuation>
<range>50</range>
<constant>0</constant>
<linear>0</linear>
<quadratic>0</quadratic>
</attenuation>
<cast_shadows>true</cast_shadows>
<direction>-2 2 -1.5</direction>
<intensity>1.0</intensity>
</light>

<!--scene objects-->
<include>
<pose>0 0 0 0 0 -1.57</pose>
<uri>
https://fuel.gazebosim.org/1.0/OpenRobotics/models/Garden Mascot
</uri>
</include>

<model name="floor">
<pose>-5 0 -0.5 0 0 0</pose>
<static>true</static>
<link name="link">
<collision name="collision">
<geometry>
<box>
<size>15 15 1</size>
</box>
</geometry>
</collision>
<visual name="visual">
<geometry>
<box>
<size>15 15 1</size>
</box>
</geometry>
<material>
<ambient>0.8 0.8 0.8 1</ambient>
<diffuse>0.8 0.8 0.8 1</diffuse>
<specular>0.8 0.8 0.8 1</specular>
</material>
</visual>
</link>
</model>
</world>
</sdf>
```

2) Add the following lines to the Minimal Scene GUI plugin.

```xml
</shadows>
<texture_size light_type="directional">8192</texture_size>
</shadows>
```

The `<texture_size>` 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.
Loading