matrixfurry.com
The open source OpenXR runtime
1# Understanding and Writing Targets: Connecting the Pieces {#understanding-targets}
2
3<!--
4Copyright 2018-2020, Collabora, Ltd. and the Monado contributors
5SPDX-License-Identifier: BSL-1.0
6-->
7
8Monado is designed to be a collection of related but independent modules. In a
9sense, the Monado project is almost more of a "runtime construction kit" than a
10single monolithic runtime. This makes it easy for adaptation and modification,
11as well as extension, but it also means that any call in an OpenXR application
12goes through quite a few modules before e.g. talking with the driver or the
13compositor.
14
15The final build product that brings all the desired
16components together, potentially with additional code, is called the "target".
17There are several targets included in the Monado source tree (in
18`src/xrt/targets/`) including:
19
20- `cli` - builds `monado-cli` executable
21- `openxr` - builds `libopenxr-monado.so` OpenXR runtime shared object
22- `gui` - builds `monado-gui` executable
23- `service` - builds `monado-service` executable (if `XRT_FEATURE_SERVICE` is
24 enabled)
25
26There is also a directory `common` which builds two static libraries. Because
27the "target" is responsible for pulling in all the desired drivers, etc. it can
28lead to some repetition if multiple targets want the same driver collection. For
29this reason, the "all drivers" code shared between many targets is located here,
30though you could consider it a part of the individual targets. See this section
31for details on how the targets find the drivers to probe: @ref writing-driver
32
33## Requirements of a Target
34
35A target must first provide the entry point desired: `int main()` if it's an
36executable, or the well-known symbol name if it's a shared library. In some
37cases, the entry point might be provided by one of the modules being combined to
38form the target. For instance, an OpenXR runtime must expose
39`xrNegotiateLoaderRuntimeInterface`: this function is provided by the OpenXR
40state tracker `st_oxr`, so the OpenXR runtime target links the state tracker in
41and ensures that symbol is present and visible in the final build product.
42
43Then, the target must provide an interface to the collection of devices desired.
44This is done by implementing the `xrt_instance` interface in your target and
45providing a definition of `xrt_instance_create` that instantiates your
46implementation.
47
48All methods of `xrt_instance` are required, though the `get_prober` method may
49output a null pointer if the instance is not using a prober, and targets that do
50not need compositing may stub out the `create_native_compositor` method to
51always return an error. A fully-featured implementation is in
52`src/targets/common/target_instance.c`, which calls
53`xrt_prober_create_with_lists` passing the common `target_lists` variable to
54include all supported devices.
55
56For more detailed information on this interface, see the documentation for @ref
57xrt_instance.
58
59## Sample Call Trees
60
61For clarity, call trees are included below for the OpenXR runtime in two general
62cases: `XRT_FEATURE_SERVICE` disabled, and `XRT_FEATURE_SERVICE` enabled.
63
64Note that even with `XRT_FEATURE_SERVICE` enabled, the other targets (cli, gui)
65more closely resembler the `XRT_FEATURE_SERVICE` disabled diagram: they contain
66the device drivers internally rather than contacting the service. They use a
67modified version of the in-process target instance without compositor support.
68
69### XRT_FEATURE_SERVICE disabled
70
71This is the simplest architecture. It is also the architecture used by the
72various extra targets like `monado-cli` even when building with
73`XRT_FEATURE_SERVICE` enabled. (The CLI and GUI link against a slightly modified
74version, `target_instance_no_comp`, which stubs out the compositor creation
75call, but are otherwise the same.)
76
77
78
79### XRT_FEATURE_SERVICE enabled
80
81Note that in this case, there are two processes involved, which have different
82`xrt_instance` implementations.
83
84- The runtime has a "stub" or "client proxy" implementation that delegates to
85 the service over the IPC.
86- The service has a normal or complete instance implementation that actually
87 provides hardware device interaction, etc.
88
89