wlroots/docs/env_vars.md

wlroots reads these environment variables

# wlroots specific

* *WLR_BACKENDS*: comma-separated list of backends to use (available backends:
  libinput, drm, wayland, x11, headless)
* *WLR_NO_HARDWARE_CURSORS*: set to 1 to use software cursors instead of
  hardware cursors
* *WLR_XWAYLAND*: specifies the path to an Xwayland binary to be used (instead
  of following shell search semantics for "Xwayland")
* *WLR_RENDERER*: forces the creation of a specified renderer (available
  renderers: gles2, pixman, vulkan)
* *WLR_RENDER_DRM_DEVICE*: specifies the DRM node to use for
  hardware-accelerated renderers.
* *WLR_EGL_NO_MODIFIERS*: set to 1 to disable format modifiers in EGL, this can
  be used to understand and work around driver bugs.

## DRM backend

* *WLR_DRM_DEVICES*: specifies the DRM devices (as a colon separated list)
  instead of auto probing them. The first existing device in this list is
  considered the primary DRM device.
* *WLR_DRM_NO_ATOMIC*: set to 1 to use legacy DRM interface instead of atomic
  mode setting
* *WLR_DRM_NO_MODIFIERS*: set to 1 to always allocate planes without modifiers,
  this can fix certain modeset failures because of bandwidth restrictions.
* *WLR_DRM_FORCE_LIBLIFTOFF*: set to 1 to force libliftoff (by default,
  libliftoff is never used)

## Headless backend

* *WLR_HEADLESS_OUTPUTS*: when using the headless backend specifies the number
  of outputs

## libinput backend

* *WLR_LIBINPUT_NO_DEVICES*: set to 1 to not fail without any input devices

## Wayland backend

* *WLR_WL_OUTPUTS*: when using the wayland backend specifies the number of outputs

## X11 backend

* *WLR_X11_OUTPUTS*: when using the X11 backend specifies the number of outputs

## gles2 renderer

* *WLR_RENDERER_ALLOW_SOFTWARE*: allows the gles2 renderer to use software
  rendering

## scenes

* *WLR_SCENE_DEBUG_DAMAGE*: specifies debug options for screen damage related
  tasks for compositors that use scenes (available options: none, rerender,
  highlight)
* *WLR_SCENE_DISABLE_DIRECT_SCANOUT*: disables direct scan-out for debugging.
* *WLR_SCENE_DISABLE_VISIBILITY*: If set to 1, the visibility of all scene nodes
  will be considered to be the full node. Intelligent visibility canculations will
  be disabled. Note that direct scanout will not work for most cases when this
  option is set as surfaces that don't contribute to the rendered output will now
  bail direct scanout (desktop background / black rect underneath).
* *WLR_SCENE_HIGHLIGHT_TRANSPARENT_REGION*: Highlights regions of scene buffers
  that are advertised as transparent through wlr_scene_buffer_set_opaque_region().
  This can be used to debug issues with clients advertizing bogus opaque regions
  with scene based compositors.

# Generic

* *DISPLAY*: if set probe X11 backend in `wlr_backend_autocreate`
* *WAYLAND_DISPLAY*, *WAYLAND_SOCKET*: if set probe Wayland backend in
  `wlr_backend_autocreate`
* *XCURSOR_PATH*: directory where xcursors are located
* *XDG_SESSION_ID*: if set, session ID used by the logind session
Document env vars used by wlroots 2018-05-03 10:30:48 +00:00			`wlroots reads these environment variables`

Add FreeRDP backend for remote desktop support 2019-02-22 18:58:52 +00:00			`# wlroots specific`

backend: allow multiple backends in WLR_BACKENDS 2018-05-15 21:10:51 +00:00			`* WLR_BACKENDS: comma-separated list of backends to use (available backends:`
backend: remove noop backend 2021-09-30 14:53:18 +00:00			`libinput, drm, wayland, x11, headless)`
output: introduce WLR_NO_HARDWARE_CURSORS 2018-09-14 16:07:21 +00:00			`* WLR_NO_HARDWARE_CURSORS: set to 1 to use software cursors instead of`
			`hardware cursors`
xwayland: introduce WLR_XWAYLAND for specifying which Xwayland to use When debugging Xwayland-related issues, a common first step in debugging has been to ask the reporter to move their real Xwayland to /usr/bin/Xwayland.bin, and create a shell script starting Xwayland with extra arguments under the original /usr/bin/Xwayland location. Introducing a `WLR_XWAYLAND` environment variable makes this less invasive, by allowing the user to swap out Xwayland without resorting to global system changes (or source patches). 2020-10-03 18:16:54 +00:00			`* WLR_XWAYLAND: specifies the path to an Xwayland binary to be used (instead`
			`of following shell search semantics for "Xwayland")`
render: introduce WLR_RENDERER in wlr_renderer_autocreate_with_drm_fd This env var forces the creation of a specific renderer. If no renderer is specified, the function will try to create all of the renderers one by one until one is created successfuly. 2021-04-20 18:48:52 +00:00			`* WLR_RENDERER: forces the creation of a specified renderer (available`
docs: mention WLR_RENDERER=vulkan. This option was added with commit 8e346922508aa3eaccd6e12f2917f6574f349843. 2021-11-19 02:06:13 +00:00			`renderers: gles2, pixman, vulkan)`
render: introduce WLR_RENDER_DRM_DEVICE This env var allows to override the DRM node used by the GLES2 and Vulkan renderers. It's especially useful to select a DRM node when running with the headless backend. References: https://gitlab.freedesktop.org/wlroots/wlroots/-/merge_requests/2656 2021-11-24 09:52:39 +00:00			`* WLR_RENDER_DRM_DEVICE: specifies the DRM node to use for`
			`hardware-accelerated renderers.`
egl: add WLR_EGL_NO_MODIFIERS Same as WLR_DRM_NO_MODIFIERS but for EGL. For debugging purposes mostly. References: https://gitlab.freedesktop.org/wlroots/wlroots/-/issues/3451 2022-10-19 09:22:14 +00:00			`* WLR_EGL_NO_MODIFIERS: set to 1 to disable format modifiers in EGL, this can`
			`be used to understand and work around driver bugs.`
Document env vars used by wlroots 2018-05-03 10:30:48 +00:00
docs: establish one section per backend 2020-01-14 12:27:22 +00:00			`## DRM backend`

			`* WLR_DRM_DEVICES: specifies the DRM devices (as a colon separated list)`
			`instead of auto probing them. The first existing device in this list is`
			`considered the primary DRM device.`
			`* WLR_DRM_NO_ATOMIC: set to 1 to use legacy DRM interface instead of atomic`
			`mode setting`
backend/drm: add env variable to disable modifiers In some cases modesets fail if the planes are initialized with modifiers. Since in this case possibly all planes need to reinitialized, which is not possible in the current wlroots design, add an environment variable for affected users. 2020-01-24 18:31:39 +00:00			`* WLR_DRM_NO_MODIFIERS: set to 1 to always allocate planes without modifiers,`
			`this can fix certain modeset failures because of bandwidth restrictions.`
backend/drm: add libliftoff interface 2022-08-18 17:17:33 +00:00			`* WLR_DRM_FORCE_LIBLIFTOFF: set to 1 to force libliftoff (by default,`
			`libliftoff is never used)`
docs: establish one section per backend 2020-01-14 12:27:22 +00:00
			`## Headless backend`
Add FreeRDP backend for remote desktop support 2019-02-22 18:58:52 +00:00
			`* WLR_HEADLESS_OUTPUTS: when using the headless backend specifies the number`
			`of outputs`

docs: establish one section per backend 2020-01-14 12:27:22 +00:00			`## libinput backend`

			`* WLR_LIBINPUT_NO_DEVICES: set to 1 to not fail without any input devices`

			`## Wayland backend`
Add FreeRDP backend for remote desktop support 2019-02-22 18:58:52 +00:00
			`* WLR_WL_OUTPUTS: when using the wayland backend specifies the number of outputs`

docs: establish one section per backend 2020-01-14 12:27:22 +00:00			`## X11 backend`
Add FreeRDP backend for remote desktop support 2019-02-22 18:58:52 +00:00
			`* WLR_X11_OUTPUTS: when using the X11 backend specifies the number of outputs`

render/egl: fail to create wlr_egl on software renderer The creation of `wlr_egl` will fail is the device extension EGL_MESA_device_software is defined. The creation process is allowed to continue only if the environment variable `WLR_RENDERER_ALLOW_SOFTWARE` is defined to the value 1. 2021-01-27 02:13:28 +00:00			`## gles2 renderer`

			`* WLR_RENDERER_ALLOW_SOFTWARE: allows the gles2 renderer to use software`
			`rendering`

wlr_scene: Parse out WLR_SCENE_DEBUG_DAMAGE 2022-05-20 22:28:08 +00:00			`## scenes`

			`* WLR_SCENE_DEBUG_DAMAGE: specifies debug options for screen damage related`
docs/env_vars: fix case of WLR_SCENE_DEBUG_DAMAGE values The values are lowercase, not uppercase. 2022-05-27 18:15:00 +00:00			`tasks for compositors that use scenes (available options: none, rerender,`
			`highlight)`
wlr_scene: Add option to disable direct scanout Closes: #3405 Supersedes: !3562 Co-authored-by: Xiao YaoBing <xiaoyaobing@qq.com> 2022-08-08 04:40:21 +00:00			`* WLR_SCENE_DISABLE_DIRECT_SCANOUT: disables direct scan-out for debugging.`
wlr_scene: Account for occlusion by other scene nodes when calculating visibility 2022-06-25 22:34:26 +00:00			`* WLR_SCENE_DISABLE_VISIBILITY: If set to 1, the visibility of all scene nodes`
			`will be considered to be the full node. Intelligent visibility canculations will`
docs: Add notes about WLR_SCENE_DISABLE_VISIBILITY effectively disabling direct scanout. 2024-05-11 15:59:36 +00:00			`be disabled. Note that direct scanout will not work for most cases when this`
			`option is set as surfaces that don't contribute to the rendered output will now`
			`bail direct scanout (desktop background / black rect underneath).`
wlr_scene: Add WLR_SCENE_HIGHLIGHT_TRANSPARENT_REGION env 2024-05-04 23:03:36 +00:00			`* WLR_SCENE_HIGHLIGHT_TRANSPARENT_REGION: Highlights regions of scene buffers`
			`that are advertised as transparent through wlr_scene_buffer_set_opaque_region().`
			`This can be used to debug issues with clients advertizing bogus opaque regions`
			`with scene based compositors.`
wlr_scene: Parse out WLR_SCENE_DEBUG_DAMAGE 2022-05-20 22:28:08 +00:00
Add FreeRDP backend for remote desktop support 2019-02-22 18:58:52 +00:00			`# Generic`

docs/env_vars: document seatd session 2020-12-24 11:19:34 +00:00			* DISPLAY: if set probe X11 backend in `wlr_backend_autocreate`
docs/env_vars: _WAYLAND_DISPLAY isn't used anymore 2020-12-24 11:17:31 +00:00			`* WAYLAND_DISPLAY, WAYLAND_SOCKET: if set probe Wayland backend in`
			`wlr_backend_autocreate`
Document env vars used by wlroots 2018-05-03 10:30:48 +00:00			`* XCURSOR_PATH: directory where xcursors are located`
docs: document XDG_SESSION_ID 2020-01-14 12:34:51 +00:00			`* XDG_SESSION_ID: if set, session ID used by the logind session`