diff dep/animia/README.md @ 199:9f3534f6b8c4

dep/animia: initial Wayland support, drop non-working kvm fd plugin
author Paper <mrpapersonic@gmail.com>
date Tue, 02 Jan 2024 02:34:27 -0500
parents 0fc126d52de4
children 8a482049b968
line wrap: on
line diff
--- a/dep/animia/README.md	Sun Dec 24 02:59:42 2023 -0500
+++ b/dep/animia/README.md	Tue Jan 02 02:34:27 2024 -0500
@@ -1,27 +1,43 @@
 # Animia
-Animia is a work-in-progress cross-platform hard fork of Anisthesia and part of Minori.
+Animia is a work-in-progress cross-platform hard fork of Anisthesia and part of
+Minori.
 
-Most (if not all) Anisthesia configs should also work in this library as well (at least on Windows).
+Most (if not all) Anisthesia configs should also work in this library as well
+(at least on Windows).
 
 ## Support
-Animia supports Windows, macOS, and Linux when dealing with file descriptors. When enumerating
-windows, it supports Windows, macOS (Quartz), and X11. I'd love to be able to support Wayland, but
-there's nothing I can do to provide an API that literally does not exist.
+Animia supports Windows, macOS, and Linux when dealing with file descriptors.
+When enumerating windows, it supports Windows, macOS (Quartz), X11, and
+Wayland (only via the `ext_foreign_toplevel_handle_v1` interface).
 
-Unlike Anisthesia, Animia currently does not support UI automation, i.e., some web browsers will not
-work properly, if at all.
+Unlike Anisthesia, Animia currently does not support UI automation, i.e., most
+web browsers will not work properly, if at all.
 
 ## Platform-specific quirks
 
+### Windows
+To get the currently opened file handles on Windows, Animia has to use internal
+kernel functions. However, these functions aren't likely to change anytime soon.
+
 ### macOS
-The code to executable names on macOS uses internal functions. However, if these functions
-cannot be found for whatever reason, it falls back to parsing the arguments, and then to calling
-the kernel.
+The code to retrieve executable names on macOS uses internal functions. However,
+if these functions cannot be found for whatever reason, it falls back to parsing
+the arguments, and then to calling the kernel.
 
-macOS doesn't have the concept of "class names", rather, it has bundle identifiers, which are
-a suitable replacement for most use cases.
+Additionally, macOS does not have the concept of class names, rather, it has
+bundle identifiers, which are a suitable replacement in most use cases, and are
+what Animia will try to grab before falling back to the Quartz window name.
 
 ### X11
-X11 has no idea what PID started your window. As a result, we can't provide it. Eventually,
-there'll be support for the XRes extension which provides this possibility. For now, PIDs are
-received using the untrustworthy `_NET_WM_PID` resource.
+If your X server has the XRes extension installed, Animia will use it to get
+PIDs. Otherwise, X11 has no idea what PID started your window. As a result,
+what Animia will give you is from the `_NET_WM_PID` resource, which is
+[very](https://stackoverflow.com/a/49970490)
+[unreliable](https://stackoverflow.com/a/49970271).
+
+### Wayland
+Only Wayland servers that implement the `ext_foreign_toplevel_handle_v1`
+interface will work with Animia. As of 2 January 2024, this means there are no
+server implementations that will work. **However**, it is possible to implement
+support for the wlroots-specific `wlr_foreign_toplevel_management_unstable_v1`
+protocol, which will at least give support to window managers based off of it.