nixgl: add NixGL user manual

docs/manual/usage.md

@@ -59,5 +59,6 @@ usage/configuration.md
 usage/rollbacks.md
 usage/dotfiles.md
 usage/graphical.md
+usage/gpu-non-nixos.md
 usage/updating.md
 ```

docs/manual/usage/gpu-non-nixos.md

@@ -0,0 +1,45 @@
+# GPU on non-NixOS systems {#sec-usage-gpu-non-nixos}
+
+To access the GPU, programs need access to system-provided OpenGL and Vulkan
+libraries. While this works transparently on NixOS, it does not on other Linux
+systems. A solution is provided by
+[NixGL](https://github.com/nix-community/nixGL), which can be integrated into
+Home Manager.
+
+To enable the integration, import NixGL into your home configuration, either as
+a channel, or as a flake input passed via `extraSpecialArgs`. Then, set the
+`nixGL.packages` option to the package set provided by NixGL.
+
+Once integration is enabled, it can be used in two ways: as Nix functions for
+wrapping programs installed via Home Manager, and as shell commands for running
+programs installed by other means (such as `nix shell`). In either case, the
+wrappers come in two variants: the Mesa variant for free drivers, and the Nvidia
+variant for Nvidia's proprietary drivers.
+
+**Note:** when using Nvidia wrappers together with flakes, your home
+configuration will not be pure and needs to be built using `home-manager switch
+--impure`. Otherwise, the build will fail, complaining about missing attribute
+`currentTime`.
+
+Below is an abbreviated example for an Optimus laptop that makes use of both
+Mesa and Nvidia wrappers, where the latter is used in dGPU offloading mode. It
+demonstrates how to wrap `mpv` to run on the integrated GPU, wrap FreeCAD to run
+on the dGPU, and how to install the wrapper scripts.
+
+```nix
+{ config, lib, pkgs, nixGL, ... }:
+{
+  nixGL.packages = nixGL.packages;
+  nixGL.nvidiaOffload = true;
+  nixGL.wrapperScripts = "both";
+
+  programs.mpv = {
+    enable = true;
+    package = config.lib.nixGL.wrapMesa pkgs.mpv;
+  };
+
+  home.packages = [
+    (config.lib.nixGL.wrapNvidia pkgs.freecad)
+  ];
+}
+```