这份教程专门针对 **WSL2 (Ubuntu 24.04/22.04) + NVIDIA RTX 50/40/30 系列显卡** 用户编写。由于 RTX 5080 架构极新，配置时必须确保 Mesa 驱动和环境变量精准匹配。

首先查看一下OpenGL的配置

glxinfo | grep "OpenGL renderer"

---

若显示llvmpipe说明此时仍然是cpu加速。因此需要按下面的教程进行配置，强制gazebo通过gpu进行渲染。

🚀 Gazebo 硬件加速配置教程 (WSL2 + NVIDIA RTX 5080)

本教程旨在解决 WSL2 环境下 Gazebo 运行黑屏、卡顿或无法识别离散显卡的问题，实现 OpenGL -> Direct3D 12 (D3D12) 的高性能映射。

📋 前置条件

1. Windows 版本：Windows 11 (建议版本 22H2 及以上)。
2. 显卡驱动：Windows 端已安装最新版 NVIDIA Game Ready 驱动。
3. WSL 版本：WSL2 (通过 wsl --version 确认已安装 WSLg)。
4. 打开wsl命令行界面

第一步：安装必要的英伟达支持软件

在wsl界面中安装英伟达支持软件

sudo apt install nvidia-cuda-toolkit

然后重启wsl。重启wsl需要在wsl中用exit退出到powershell
powershell输入关闭wsl指令。

wsl --shutdown

等待10秒左右，再次打开wsl

进入wsl后，用nvidia-smi命令查看显卡情况
若输出类似于如下的监视窗口，说明已经装好了。

第二步：更新核心图形库 (Mesa)

RTX 5080 需要较新版本的 Mesa 库才能完美支持 D3D12 映射。

# 添加最新稳定版 Mesa 驱动源
sudo add-apt-repository ppa:kisak/kisak-mesa
sudo apt update && sudo apt upgrade -y

# 安装必要的工具包
sudo apt install mesa-utils libegl1-mesa libgl1-mesa-dri -y

---

第三步：配置环境变量 (核心步骤)

通过环境变量强制 Gazebo 调用 NVIDIA 显卡并解决 WSLg 兼容性黑屏。

1. 临时测试

在终端执行以下命令（当前窗口有效）：

# 1. 启用 D3D12 映射（WSL2 硬件加速的核心）
export GALLIUM_DRIVER=d3d12

# 2. 强制指定使用 NVIDIA 显卡
export MESA_D3D12_DEFAULT_ADAPTER_NAME=NVIDIA

# 3. 解决 Qt 共享内存导致的黑屏（WSLg 必配）
export QT_X11_NO_MITSHM=1

# 4. 强制 Gazebo 使用 Ogre2 渲染引擎
export GZ_RENDERING_ENGINE_GUESS=ogre2

2. 永久生效

将上述配置写入 ~/.bashrc，避免每次重启失效：

cat << EOF >> ~/.bashrc

# --- Gazebo & NVIDIA GPU Acceleration ---
export GALLIUM_DRIVER=d3d12
export MESA_D3D12_DEFAULT_ADAPTER_NAME=NVIDIA
export QT_X11_NO_MITSHM=1
export GZ_RENDERING_ENGINE_GUESS=ogre2
# ----------------------------------------
EOF

source ~/.bashrc

---

第四步：验证硬件加速状态

在运行 Gazebo 前，必须确认显卡已被正确识别。

执行命令：

glxinfo -B

✅ 成功标志：

• Device: D3D12 (NVIDIA GeForce RTX 5080)
• Accelerated: yes
• Video memory: XXXX MB

---

第五步：Gazebo 运行优化建议

1. 离线运行 (避免网络导致的黑屏)

Gazebo 启动时会自动从 Fuel 云端下载模型，国内网络环境极易导致 SSL 报错并卡死渲染线程。
建议方法： 直接指向本地 SDF 文件启动。

gz sim -v 4 shapes.sdf

2. 清理渲染缓存

如果更换过显卡驱动或配置后依然黑屏，请尝试清理 Gazebo 的 GUI 缓存：

rm -rf ~/.gz/sim/display.json
rm -rf ~/.cache/mesa_shader_cache

3. Windows 端设置 (可选)

如果帧率不稳定，请在 Windows 中：

1. 打开 系统设置 -> 屏幕 -> 图形。
2. 找到 C:\Windows\System32\wsl.exe。
3. 将其选项设置为 “高性能” (NVIDIA GPU)。

---

🛠️ 常见问题排查 (Troubleshooting)

现象	可能原因	解决方法
启动后全黑，没有任何 UI	代理设置错误	执行 unset http_proxy https_proxy
可以看到 UI 但 3D 视图黑色	正在下载模型或 Shader 编译中	查看终端日志，等待 Created file 刷屏结束
提示 Permission denied	WSLg 权限 Bug	执行 sudo chmod 700 /mnt/wslg/runtime-dir
显卡识别为 llvmpipe	Mesa 版本过低或驱动未加载	参考第一步更新 Mesa，并确保 Windows 驱动已安装

---