[docs] guide: document current Looking Glass features

doc/display.rst

@@ -0,0 +1,95 @@
+.. _client_display:
+
+Display and image quality
+#########################
+
+The EGL renderer is the supported client renderer and is selected
+automatically. The older OpenGL renderer is deprecated, does not provide direct
+DMA imports or native HDR, and should only be used to diagnose a compatibility
+problem.
+
+Wayland and X11 are both built by default. Automatic selection prefers Wayland
+when ``WAYLAND_DISPLAY`` is set, then X11 when ``DISPLAY`` is set. To force X11
+from a Wayland session for diagnosis, preserve ``DISPLAY`` and unset
+``WAYLAND_DISPLAY`` for the client process.
+
+Window and guest resolution
+---------------------------
+
+With the IDD, ``win:setGuestRes=yes`` asks Windows to match the client viewport
+when its size changes. Press :kbd:`ScrLk` + :kbd:`=` to request the current
+size immediately. The IDD creates this as its dynamic ExtraMode using the
+default refresh configured in the IDD helper.
+
+If a requested resolution does not fit in IVSHMEM, the IDD refuses it and the
+helper reports the required size. See :ref:`libvirt_determining_memory`.
+
+Useful window options include:
+
+``win:autoResize``
+   Resize the client window when the guest resolution changes.
+
+``win:keepAspect``
+   Preserve the guest aspect ratio while resizing.
+
+``win:fullScreen``
+   Start in borderless full-screen mode.
+
+``win:rotate``
+   Rotate the image by 0, 90, 180 or 270 degrees.
+
+Scaling and filters
+-------------------
+
+The overlay's **EGL filters** page controls scaling, sharpening and custom
+processing. Filters run from top to bottom and can be reordered. Save useful
+combinations as named presets, then select one at startup with ``egl:preset``.
+
+The built-in filters include:
+
+* a configurable downscaler;
+* AMD FidelityFX Super Resolution (FSR); and
+* AMD FidelityFX Contrast Adaptive Sharpening (CAS).
+
+The ``egl:scale`` option selects automatic, nearest-neighbor or linear
+scaling when a filter does not provide the required scaling. Additional
+mpv-style GLSL shaders may be loaded from ``eglFilter:glslPath``. The
+`Anime4K <https://github.com/bloc97/Anime4K>`_ project provides compatible
+GLSL filters.
+
+.. _client_hdr:
+
+HDR
+---
+
+The IDD exposes HDR only when the Windows runtime provides the required IddCx
+interfaces and the IDD is using a hardware render adapter. This normally means
+a compatible Windows 11 guest. Windows 10 and IDD software processing remain
+on the SDR path.
+
+Native HDR output on Linux requires all of the following:
+
+* the EGL renderer;
+* a Wayland compositor with ``color-management-v1`` support;
+* an HDR-capable monitor and output configuration; and
+* a host graphics driver that can present the required color format.
+
+With ``egl:mapHDRtoSDR=yes`` the client tone-maps HDR frames for an SDR desktop.
+Use ``egl:peakLuminance`` to describe the SDR display target and
+``egl:maxCLL`` to limit the assumed content light level.
+
+X11 presentation is SDR. The EGL renderer tone-maps HDR to SDR there by
+default. Native Wayland PQ output also requires compositor support for ST 2084
+and BT.2020, while scRGB requires compositor scRGB support.
+
+Presentation latency
+--------------------
+
+The defaults favor low latency rather than conventional buffered rendering.
+Do not enable ``egl:vsync`` or ``egl:doubleBuffer`` merely to chase a reported
+frame-rate number; either can add presentation delay. Use the timing graphs to
+confirm the result on the actual compositor and GPU.
+
+``win:jitRender`` delays rendering toward the expected presentation deadline.
+It can reduce the age of a frame at display time, but depends on stable timing.
+Leave it disabled while diagnosing stalls or an unstable refresh cadence.