wip: XR docs + improvements

docs/methods.md

@@ -496,4 +496,115 @@ unit tests.
 You can use `ReflectionHelper.getIntConstantName` to search for
 an `int` constant in a class that has the given value, and the
 right prefix and/or suffix. This is used to figure out the
-name of Vulkan error codes (like `VK_ERROR_DEVICE_LOST`).
+name of Vulkan error codes (like `VK_ERROR_DEVICE_LOST`).
+
+## Virtual reality
+`vk-boiler` supports OpenXR integration. OpenXR is a Khronos
+standard (just like Vulkan) for virtual reality and augmented
+reality. OpenXR applications can choose from several rendering
+APIs, where Vulkan is just 1 of them. Unfortunately, this
+integration between Vulkan and OpenXR is very verbose. That's
+why `vk-boiler` helps during instance creation, and provides
+many helper functions.
+
+### Enabling virtual reality support
+First of all, you need to chain `.xr(...)` to the `BoilerBuilder`
+(see [the initialization documentation](./initialization.md))
+for more information. Obviously, this will only work if a
+virtual reality headset is connected to the computer that runs
+the application (or has some emulator).
+
+### Creating the OpenXR session
+After creating the `BoilerInstance`, the next step in a virtual
+reality application is typically creating the `XrSession`. You
+can do this using `boiler.xr().createSession(...)`. This will
+return a `VkbSession` (which wraps an `XrSession`). The
+`VkbSession` class provides some potentially useful instance
+methods, which will be explained later.
+
+### Creating the OpenXR swapchain
+Before creating the swapchain, you need to choose a swapchain
+image format. You can use
+`session.chooseSwapchainFormat(preferredFormats...)`
+for this, but you can also call `xrEnumerateSwapchainFormats`
+yourself.
+
+You also need to choose the size of the swapchain. You can use
+`boiler.xr().getViewConfigurationViews(...)` to query the
+minimum, maximum, and recommended swapchain size. Alternatively,
+you can call `xrEnumerateViewConfigurationViews` yourself.
+
+To create the swapchain, you can use
+`session.createSwapchain(...)`, or call `xrCreateSwapchain`
+yourself.
+
+You will probably also want to create swapchain image views
+and depth images. Since this is regular Vulkan stuff, you can
+use the methods of `boiler.images`.
+
+### Creating OpenXR actions
+You can use `boiler.xr().actions.createSet(...)` to create an
+`XrActionSet`. This method will simply call `xrCreateActionSet`
+under the hood, but using this should take fewer lines of code.
+
+You can use `boiler.xr().actions.getPath(stack, "/path/string")`
+to convert a path string to an `XrPath`. This method will simply
+call `xrStringToPath`, but should be slightly more convenient.
+
+You can use `boiler.xr().actions.create(...)` to create an
+`XrAction` without subactions, and you can use
+`boiler.xr().actions.createWithSubactions` to create an
+`XrAction` with subactions. Both methods will just call
+`xrCreateAction`, but should be more convenient for you.
+
+### Suggesting interaction profile bindings
+After creating actions, you should suggest bindings for the
+controllers you intend to support. Since using raw
+`XrActionSuggestedBinding`s is quite verbose, I made a
+`SuggestedBindingsBuilder` class to lighten the work.
+
+Start by creating an instance, which should look like this:
+```java
+var bindingsBuilder = new SuggestedBindingsBuilder(
+	boiler.xr(), 
+	"/interaction_profiles/khr/simple_controller"
+);
+```
+The second parameter is the interaction profile for which
+you want to suggest bindings.
+
+Then add some suggested bindings, like this:
+```java
+bindingsBuilder.add(
+	handPoseAction, "/user/hand/right/input/aim/pose"
+);
+bindingsBuilder.add(
+	handClickAction, "/user/hand/left/input/select/click"
+);
+```
+The first parameter is the `XrAction` to bind, and the
+second parameter is the path to which you want to bind it.
+Once you have suggested all bindings, call
+`bindingsBuilder.finish()` (which will actually call
+`xrSuggestInteractionProfileBindings`).
+
+### Creating OpenXR spaces
+You can call `session.createReferenceSpace(...)` to create a
+reference space of the given `XrReferenceSpaceType`. This
+is just a convenience method that will call
+`xrCreateReferenceSpace` under the hood.
+
+You can call `session.createActionSpace(...)` to create
+an action space for the given (sub)action. This is also a
+convenience method, and will simply call `xrCreateActionSpace`
+under the hood.
+
+Note that both methods will use the identity pose as
+`poseInReferenceSpace`/`poseInActionSpace`.
+
+### Attaching action sets to the session
+You can call `session.attach(stack, actionSet)` to attach a
+single `XrActionSet` to the `XrSession` (using
+`xrAttachSessionActionSets`). If you wish to attach multiple
+action sets at the same time, you will have to call
+`xrAttachSessionActionSets` yourself.