docs: webgpu

refs: https://github.com/wez/wezterm/issues/2756

docs/changelog.md

@@ -197,6 +197,7 @@ As features stabilize some brief notes about them will accumulate here.
   [show_new_tab_button_in_tab_bar](config/lua/config/show_new_tab_button_in_tab_bar.md)
   config options to customize the tab bar appearance.
   [#2082](https://github.com/wez/wezterm/issues/2082)
+* [front_end = "WebGpu"](config/lua/config/front_end.md) enables Metal, Vulkan and DX 12 drivers.
 
 #### Fixed
 * Wayland: key repeat gets stuck after pressing two keys in quick succession.

docs/config/lua/config/front_end.md

@@ -6,9 +6,26 @@ possible values:
 
 * `OpenGL` - use GPU accelerated rasterization (this is the default)
 * `Software` - use CPU-based rasterization.
+* `WebGpu` - use GPU accelerated rasterization (*Since: 20221119-145034-49b9839f*)
 
 You may wish (or need!) to select `Software` if there are issues with your
 GPU/OpenGL drivers.
 
 WezTerm will automatically select `Software` if it detects that it is
 being started in a Remote Desktop environment on Windows.
+
+## WebGpu
+
+*Since: 20221119-145034-49b9839f*
+
+The WebGpu front end allows wezterm to use GPU acceleration provided by
+a number of platform-specific backends:
+
+* Metal (on macOS)
+* Vulkan
+* DirectX 12 (on Windows)
+
+See also:
+* [webgpu_preferred_adapter](webgpu_preferred_adapter.md)
+* [webgpu_power_preference](webgpu_power_preference.md)
+* [webgpu_force_fallback_adapter](webgpu_force_fallback_adapter.md)

docs/config/lua/config/webgpu_force_fallback_adapter.md

@@ -0,0 +1,11 @@
+# `webgpu_force_fallback_adapter = false`
+
+*Since: 20221119-145034-49b9839f*
+
+If set to `true`, forces the use of a fallback software (CPU based) rendering
+backend.  The performance will not be as good as using a GPU.
+
+This option is only applicable when you have configured `front_end = "WebGpu"`.
+
+You can have more fine grained control over which GPU is selected using
+[webgpu_preferred_adapter](webgpu_preferred_adapter.md).

docs/config/lua/config/webgpu_power_preference.md

@@ -0,0 +1,14 @@
+# `webgpu_power_preference = "LowPower"`
+
+*Since: 20221119-145034-49b9839f*
+
+Specifies the power preference when selecting a webgpu GPU instance.
+This option is only applicable when you have configured `front_end = "WebGpu"`.
+
+The possible values are:
+
+* `"LowPower"` - use an integrated GPU
+* `"HighPerformance"` - use a discrete GPU
+
+You can have more fine grained control over which GPU is selected using
+[webgpu_preferred_adapter](webgpu_preferred_adapter.md).

docs/config/lua/config/webgpu_preferred_adapter.md

@@ -0,0 +1,103 @@
+# `webgpu_preferred_adapter`
+
+*Since: 20221119-145034-49b9839f*
+
+Specifies which WebGpu adapter should be used.
+
+This option is only applicable when you have configured `front_end = "WebGpu"`.
+
+You can use the [wezterm.gui.enumerate_gpus()](../wezterm.gui/enumerate_gpus.md) function
+to return a list of GPUs.
+
+If you open the [Debug Overlay](../keyassignment/ShowDebugOverlay.md) (default:
+<kbd>CTRL</kbd> + <kbd>SHIFT</kbd> + <kbd>L</kbd>) you can interactively review
+the list:
+
+```
+> wezterm.gui.enumerate_gpus()
+[
+    {
+        "backend": "Vulkan",
+        "device": 29730,
+        "device_type": "DiscreteGpu",
+        "driver": "radv",
+        "driver_info": "Mesa 22.3.4",
+        "name": "AMD Radeon Pro W6400 (RADV NAVI24)",
+        "vendor": 4098,
+    },
+    {
+        "backend": "Vulkan",
+        "device": 0,
+        "device_type": "Cpu",
+        "driver": "llvmpipe",
+        "driver_info": "Mesa 22.3.4 (LLVM 15.0.7)",
+        "name": "llvmpipe (LLVM 15.0.7, 256 bits)",
+        "vendor": 65541,
+    },
+    {
+        "backend": "Gl",
+        "device": 0,
+        "device_type": "Other",
+        "name": "AMD Radeon Pro W6400 (navi24, LLVM 15.0.7, DRM 3.49, 6.1.9-200.fc37.x86_64)",
+        "vendor": 4098,
+    },
+]
+```
+
+Based on that list, I might choose to explicitly target the discrete Gpu like
+this (but note that this would be the default selection anyway):
+
+```lua
+local wezterm = require 'wezterm'
+
+return {
+  webgpu_preferred_adapter = {
+    backend = 'Vulkan',
+    device = 29730,
+    device_type = 'DiscreteGpu',
+    driver = 'radv',
+    driver_info = 'Mesa 22.3.4',
+    name = 'AMD Radeon Pro W6400 (RADV NAVI24)',
+    vendor = 4098,
+  },
+  front_end = 'WebGpu',
+}
+```
+
+alternatively, I might use:
+
+```lua
+local wezterm = require 'wezterm'
+local gpus = wezterm.gui.enumerate_gpus()
+
+return {
+  webgpu_preferred_adapter = gpus[1],
+  front_end = 'WebGpu',
+}
+```
+
+If you have a more complex situation you can get a bit more elaborate; this
+example will only enable WebGpu if there is an integrated GPU available with
+Vulkan drivers:
+
+```lua
+local wezterm = require 'wezterm'
+local adapter = nil
+local front_end = nil
+
+for _, gpu in ipairs(wezterm.gui.enumerate_gpus()) do
+  if gpu.backend == 'Vulkan' and gpu.device_type == 'Integrated' then
+    adapter = gpu
+    front_end = 'WebGpu'
+    break
+  end
+end
+
+return {
+  webgpu_preferred_adapter = adapter,
+  front_end = front_end,
+}
+```
+
+See also [webgpu_power_preference](webgpu_power_preference.md),
+[webgpu_force_fallback_adapter](webgpu_force_fallback_adapter.md).

docs/config/lua/wezterm.gui/enumerate_gpus.md

@@ -0,0 +1,38 @@
+# `wezterm.gui.enumerate_gpus()`
+
+*Since: 20221119-145034-49b9839f*
+
+Returns the list of available Gpus supported by WebGpu.
+
+This is useful in conjunction with [webgpu_preferred_adapter](../config/webgpu_preferred_adapter.md)
+
+```
+> wezterm.gui.enumerate_gpus()
+[
+    {
+        "backend": "Vulkan",
+        "device": 29730,
+        "device_type": "DiscreteGpu",
+        "driver": "radv",
+        "driver_info": "Mesa 22.3.4",
+        "name": "AMD Radeon Pro W6400 (RADV NAVI24)",
+        "vendor": 4098,
+    },
+    {
+        "backend": "Vulkan",
+        "device": 0,
+        "device_type": "Cpu",
+        "driver": "llvmpipe",
+        "driver_info": "Mesa 22.3.4 (LLVM 15.0.7)",
+        "name": "llvmpipe (LLVM 15.0.7, 256 bits)",
+        "vendor": 65541,
+    },
+    {
+        "backend": "Gl",
+        "device": 0,
+        "device_type": "Other",
+        "name": "AMD Radeon Pro W6400 (navi24, LLVM 15.0.7, DRM 3.49, 6.1.9-200.fc37.x86_64)",
+        "vendor": 4098,
+    },
+]
+```