Add performance_tuning to jetty/tutorials

jetty/index.yaml

@@ -78,6 +78,9 @@ pages:
           - name: sensors
             title: Sensors
             file: sensors.md
+          - name: performance_tuning
+            title: Performance tuning
+            file: performance_tuning.md
           - name: actors
             title: Actors
             file: actors.md

jetty/performance_tuning.md

@@ -0,0 +1,95 @@
+# Performance tuning
+
+If your Jetty simulation is running below real time or the GUI feels slow, start
+by identifying which part of the workload is expensive. A world with many
+contacts is tuned differently from a world dominated by cameras, lidar, or
+rendering.
+
+## Measure first
+
+Before changing settings, enable the world statistics tools described in
+[SDF Worlds](sdf_worlds). In particular, keep an eye on:
+
+* real time factor (RTF)
+* simulation time versus real time
+* whether the slowdown appears when physics, sensors, or rendering load changes
+
+This gives you a baseline before you start trading fidelity for speed.
+
+## Common performance tweaks
+
+### Reduce physics work
+
+* Try less aggressive physics settings in [SDF Worlds](sdf_worlds). Larger
+  `<max_step_size>` values usually reduce computation, but they also reduce
+  accuracy and can change contact behavior.
+* Use simpler collision geometry when possible. [Building your own robot](building_robot)
+  notes that collision geometry does not need to match the visual mesh exactly,
+  and simpler collisions often reduce computation time.
+
+### Reduce sensor work
+
+* Lower `<update_rate>` for sensors that do not need high-frequency data. See
+  [Sensors](sensors).
+* If you do not need the GUI, run only the server with
+  `gz sim -s <world.sdf>`. For individual sensors, set
+  `<visualize>false</visualize>` when the GUI view is not needed.
+* For `gpu_lidar` sensors, reduce `<samples>` or `<resolution>` before
+  increasing scene complexity. See [Sensors](sensors). Lidar availability and
+  performance depend on rendering engine support and your GPU / driver setup.
+
+### Reduce rendering work
+
+* Gazebo uses Ogre 2 by default. If you are forcing Ogre 1, compare it with the
+  default first. If Ogre 2 is unavailable on your machine, [Troubleshooting](troubleshooting)
+  explains the OpenGL requirements and how to fall back to `--render-engine ogre`.
+* Reduce expensive visual effects when they are not needed. For example, disable
+  shadow casting on lights with
+  [`<light><cast_shadows>false</cast_shadows></light>`](http://sdformat.org/spec?ver=1.12&elem=light#light_cast_shadows)
+  or on visuals with
+  [`<visual><cast_shadows>false</cast_shadows></visual>`](http://sdformat.org/spec?ver=1.12&elem=visual#visual_cast_shadows).
+* You can recognize PBR materials by a `<pbr>` block inside a visual's
+  [`<material>`](http://sdformat.org/spec?ver=1.12&elem=material#material_pbr),
+  often with `<metal>` or `<specular>` workflows and texture maps such as
+  `<albedo_map>`, `<normal_map>`, `<metalness_map>`, or `<roughness_map>`. If
+  rendering is the bottleneck, copy the model and replace the PBR block with
+  simpler `<ambient>`, `<diffuse>`, and `<specular>` colors like the examples in
+  [Building your own robot](building_robot), or temporarily remove
+  high-resolution texture maps.
+
+### Use simpler models
+
+* Reduce triangle counts in imported meshes.
+* Use primitive collision shapes such as boxes, spheres, and cylinders whenever
+  possible. If you need collision meshes, keep them convex and watertight.
+* Keep visual meshes and collision meshes separate so collisions can stay simple
+  even when the visual model is detailed.
+* Remove sensors, lights, or plugins from models that are not needed in a given
+  experiment.
+
+### Make sure Gazebo is using the right GPU
+
+* On hybrid systems with both integrated and discrete GPUs, Gazebo may start on
+  the integrated GPU. Check the active OpenGL renderer with
+  `glxinfo | grep "OpenGL"`. [Troubleshooting](troubleshooting) shows how to
+  use PRIME render offload or Nvidia performance mode.
+* If Ogre 2 fails to start, check OpenGL support and driver setup before
+  assuming the simulation itself is slow.
+
+## Advanced and external options
+
+These are worth exploring for specialized workloads, but they are not part of a
+small Jetty-only tuning guide:
+
+* Alternative physics backends such as [Bullet Featherstone](https://github.com/gazebosim/gz-physics/issues/44)
+  may help some articulated systems, but they need workload-specific validation
+  and are not covered by a Jetty how-to yet.
+* Third-party accelerators such as [RGLGazeboPlugin](https://github.com/RobotecAI/RGLGazeboPlugin)
+  or [gz_wgpu_rt_lidar](https://github.com/arjo129/gz_wgpu_rt_lidar/)
+  may be useful when GPU-accelerated sensing is the main bottleneck. Follow the
+  setup and support guidance in those projects.
+
+Start with the documented knobs in Jetty first: physics step size, simpler
+collisions, lower sensor rates, rendering settings, and correct GPU usage.
+Those changes are usually easier to validate and easier to maintain across
+releases.