+4 -4

CONTRIBUTING.md

··· 9 There are plenty of valid reasons why someone might not be able 10 to follow all of the guidelines in this section, and that's OK, 11 especially for new contributors or those new to open source entirely. 12 - Just let us know and we'll figure out a way to help you get involved successfully. 13 14 > Important note: Unlike the guidelines here, the Code of Conduct, 15 > available at <https://www.freedesktop.org/wiki/CodeOfConduct/>, ··· 25 to begin a discussion and help smooth the acceptance of your contribution. 26 27 - If you are able, please make sure to run clang-format 28 - (ideally version 7 or newer) before each commit, 29 so that you only commit things that are cleanly styled. 30 Consistent, machine-performed formatting improves readability and makes it easier for others to contribute. 31 It also makes it easier to review changes. 32 - If you can't run clang-format, just mention this fact in your request and we'd be happy to help, 33 either in a single "Clean up formatting." commit on top of your work, 34 or by "re-writing history" (with your permission and leaving your commit authorship intact), 35 revising each commit to apply formatting. ··· 52 please help by making sure your changes build cleanly (and pass all tests). 53 When on compilers that take warning flags like gcc and clang do, 54 the build system automatically turns on quite a few of them. 55 - If a warning stumps you, just mention it in the request so we can figure it out together. 56 57 ### Issues 58

··· 9 There are plenty of valid reasons why someone might not be able 10 to follow all of the guidelines in this section, and that's OK, 11 especially for new contributors or those new to open source entirely. 12 + Let us know and we'll figure out a way to help you get involved successfully. 13 14 > Important note: Unlike the guidelines here, the Code of Conduct, 15 > available at <https://www.freedesktop.org/wiki/CodeOfConduct/>, ··· 25 to begin a discussion and help smooth the acceptance of your contribution. 26 27 - If you are able, please make sure to run clang-format 28 + (ideally version 11 or newer) before each commit, 29 so that you only commit things that are cleanly styled. 30 Consistent, machine-performed formatting improves readability and makes it easier for others to contribute. 31 It also makes it easier to review changes. 32 + If you can't run clang-format, mention this fact in your request and we'd be happy to help, 33 either in a single "Clean up formatting." commit on top of your work, 34 or by "re-writing history" (with your permission and leaving your commit authorship intact), 35 revising each commit to apply formatting. ··· 52 please help by making sure your changes build cleanly (and pass all tests). 53 When on compilers that take warning flags like gcc and clang do, 54 the build system automatically turns on quite a few of them. 55 + If you can't figure out a warning, mention it in the request so we can figure it out together. 56 57 ### Issues 58

+3 -6

README.md

··· 21 come up with a lot of weird hardware). 22 Monado aims to be a complete and conforming implementation 23 of the OpenXR API made by Khronos. 24 - The project currently is being developed for GNU/Linux 25 - and aims to support other operating systems in the near future. 26 "Monado" has no specific meaning and is just a name. 27 28 ## Monado source tree ··· 248 You can optionally put something like `CLANG_FORMAT=clang-format-7` before that command 249 if your clang-format binary isn't named `clang-format`. 250 **Note that you'll typically prefer** to use something like `git clang-format` 251 - to just re-format your changes, in case version differences in tools result in overall format changes. 252 - The CI "style" job currently runs on Debian Buster, so it has clang-format-7. 253 - We will probably update that job to Bullseye or Ubuntu 20.10, which will allow 254 - using clang-format-11 by default, soon. 255 256 [OpenHMD]: http://openhmd.net 257 [drm-lease]: https://haagch.frickel.club/#!drmlease%2Emd

··· 21 come up with a lot of weird hardware). 22 Monado aims to be a complete and conforming implementation 23 of the OpenXR API made by Khronos. 24 + The project is primarily developed on GNU/Linux, but also runs on Android and Windows. 0 25 "Monado" has no specific meaning and is just a name. 26 27 ## Monado source tree ··· 247 You can optionally put something like `CLANG_FORMAT=clang-format-7` before that command 248 if your clang-format binary isn't named `clang-format`. 249 **Note that you'll typically prefer** to use something like `git clang-format` 250 + to re-format only your changes, in case version differences in tools result in overall format changes. 251 + The CI "style" job currently runs on Debian Bullseye, so it has clang-format-11. 0 0 252 253 [OpenHMD]: http://openhmd.net 254 [drm-lease]: https://haagch.frickel.club/#!drmlease%2Emd

+2 -2

doc/CHANGELOG.md

··· 566 - comp: Set a compositor window title. 567 ([!418](https://gitlab.freedesktop.org/monado/monado/merge_requests/418)) 568 - IPC 569 - - server: Almost completely overhaul the handling of swapchain life cycle 570 including: correctly track which swapchains are alive; reuse ids; enforce the 571 maximum number of swapchains; and destroy underlying swapchains when they are 572 destroyed by the client. 573 ([!359](https://gitlab.freedesktop.org/monado/monado/merge_requests/359)) 574 - - util: Make sure to not access NULL control messages, say in the case of the 575 server failing to create a swapchain. Also add a whole bunch of paranoia when 576 it comes to the alignment of the control message buffers. 577 ([!359](https://gitlab.freedesktop.org/monado/monado/merge_requests/359))

··· 566 - comp: Set a compositor window title. 567 ([!418](https://gitlab.freedesktop.org/monado/monado/merge_requests/418)) 568 - IPC 569 + - server: Almost completely overhaul the handling of swapchain lifecycle 570 including: correctly track which swapchains are alive; reuse ids; enforce the 571 maximum number of swapchains; and destroy underlying swapchains when they are 572 destroyed by the client. 573 ([!359](https://gitlab.freedesktop.org/monado/monado/merge_requests/359)) 574 + - util: Make sure to not dereference NULL control messages, say in the case of the 575 server failing to create a swapchain. Also add a whole bunch of paranoia when 576 it comes to the alignment of the control message buffers. 577 ([!359](https://gitlab.freedesktop.org/monado/monado/merge_requests/359))

+4 -6

doc/changes/README.md

··· 55 Markdown-formatted text describing the change briefly. Reference metadata will 56 be used to automatically add links to associated issues/merge requests/pull 57 requests, so no need to add these in your fragment text. The simplest changelog 58 - fragment just contains one line of Markdown text describing the change: 59 60 ```md 61 Here the author of a change has written some text about it. 62 ``` 63 - 64 - (If you change the template in your Proclamation config file, your project can use a different markup format than Markdown.) 65 66 ### References 67 ··· 95 project.) 96 97 To specify additional references in a file, prefix the contents of the changelog 98 - fragment with a block delimited above and below by `---`, with one reference on 99 each line. (This can be seen as a very minimal subset of "YAML Front Matter", if 100 you're familiar with that concept.) For example: 101 ··· 109 110 There are provisions for providing your own reference parser if this format is 111 entirely unusable, but they're underdeveloped. (Most use cases found by the 112 - original author can actually be accommodated just by changing the template and 113 specifying `.`-delimited fields in references.) If this functionality is 114 interesting to you, get involved in the development of Proclamation and help 115 finish it! ··· 166 - `insert_point_pattern` - Useful mainly if you're not using the default 167 template. The first match of this regex will be considered the first line of 168 a release entry, and your new release will be put in your changelog file 169 - above it. Default works with the default template (looks for a second-level 170 Markdown heading). 171 - `extra_data` - Any extra data you'd like to pass along to your custom 172 template.

··· 55 Markdown-formatted text describing the change briefly. Reference metadata will 56 be used to automatically add links to associated issues/merge requests/pull 57 requests, so no need to add these in your fragment text. The simplest changelog 58 + fragment contains one line of Markdown text describing the change: 59 60 ```md 61 Here the author of a change has written some text about it. 62 ``` 0 0 63 64 ### References 65 ··· 93 project.) 94 95 To specify additional references in a file, prefix the contents of the changelog 96 + fragment with a block delimited before and after by `---`, with one reference on 97 each line. (This can be seen as a very minimal subset of "YAML Front Matter", if 98 you're familiar with that concept.) For example: 99 ··· 107 108 There are provisions for providing your own reference parser if this format is 109 entirely unusable, but they're underdeveloped. (Most use cases found by the 110 + original author can actually be accommodated by changing the template and 111 specifying `.`-delimited fields in references.) If this functionality is 112 interesting to you, get involved in the development of Proclamation and help 113 finish it! ··· 164 - `insert_point_pattern` - Useful mainly if you're not using the default 165 template. The first match of this regex will be considered the first line of 166 a release entry, and your new release will be put in your changelog file 167 + before it. Default works with the default template (looks for a second-level 168 Markdown heading). 169 - `extra_data` - Any extra data you'd like to pass along to your custom 170 template.

+1 -1

doc/changes/auxiliary/mr.839.1.md

··· 1 util: added `u_device_2d_extents` and `u_setup_2d_extents_split_side_by_side` - 2 this is hopefully to eliminate confusion: the FOV you had to give to 3 - `u_device_split_side_by_side` was just a dummy value, but some people thought 4 it was the actual headset's FOV.

··· 1 util: added `u_device_2d_extents` and `u_setup_2d_extents_split_side_by_side` - 2 this is hopefully to eliminate confusion: the FOV you had to give to 3 + `u_device_split_side_by_side` was a placeholder value, but some people thought 4 it was the actual headset's FOV.

+1 -1

doc/changes/misc_features/mr.695.md

··· 1 - Implement tracking overrides via wrapper devices and add a tracking override configuration gui.

··· 1 + Implement tracking overrides using wrapper devices and add a tracking override configuration gui.

+1 -1

doc/changes/misc_features/mr.715.md

··· 1 - a/gst: Add a small and fairly dumb framework for integrating gstreamer pipelines 2 into Monado pipelines. Enough to be able to push frames into it and use various 3 encoder elements.

··· 1 + a/gst: Add a small and fairly naive framework for integrating gstreamer pipelines 2 into Monado pipelines. Enough to be able to push frames into it and use various 3 encoder elements.

+2 -2

doc/changes/xrt/mr.1258.md

··· 1 xrt: Add xrt_swapchain_create_properties to allow client compositors and IPC 2 - code to query the main compositor how many images to create on a swapchain 3 - (and in the future or properties as needed).

··· 1 xrt: Add xrt_swapchain_create_properties to allow client compositors and IPC 2 + code to query the main compositor how many images to create on a swapchain, 3 + and provide an extension point for more properties as needed.

+1 -1

doc/changes/xrt/mr.721.4.md

··· 1 Add `xrt_multi_compositor_control` that allows the `xrt_system_compositor` to 2 expose a interface that the IPC layer can use to manage multiple clients 3 without having to do the rendering. This allows us to move a lot of the code 4 - out the IPC layer and make it more about just passing calls.

··· 1 Add `xrt_multi_compositor_control` that allows the `xrt_system_compositor` to 2 expose a interface that the IPC layer can use to manage multiple clients 3 without having to do the rendering. This allows us to move a lot of the code 4 + out the IPC layer and make it more about passing calls.

+6 -6

doc/conventions.md

··· 1 # Code Style and Conventions {#conventions} 2 3 <!-- 4 - Copyright 2021, Collabora, Ltd. and the Monado contributors 5 SPDX-License-Identifier: BSL-1.0 6 --> 7 ··· 19 ## APIs 20 21 Internal APIs, when it makes sense, should be C APIs. Headers that define 22 - general communication interfaces between modules (not just use of utilities) 23 belong in the `xrt/include/xrt` directory, and should not depend on any other module outside 24 that directory. (As a historical note: this directory gets its name from a 25 compressed version of the phrase "XR RunTime", a generic term for Monado and an ··· 161 destroy function that does not take a pointer-to-a-pointer, make sure to do 162 null checks before calling and set it to null after it returns. 163 164 - Also note: when an interface includes a "destroy" function pointer, it just 165 - takes the normal pointer to an object: The free function wrapper is the one that 166 - takes a pointer-to-a-pointer and handles the null checks. See for example @ref 167 xrt_instance_destroy takes the pointer-to-a-pointer, while the interface method 168 - @ref xrt_instance::destroy takes just the single pointer.

··· 1 # Code Style and Conventions {#conventions} 2 3 <!-- 4 + Copyright 2021-2022, Collabora, Ltd. and the Monado contributors 5 SPDX-License-Identifier: BSL-1.0 6 --> 7 ··· 19 ## APIs 20 21 Internal APIs, when it makes sense, should be C APIs. Headers that define 22 + general communication interfaces between modules (not only use of utilities) 23 belong in the `xrt/include/xrt` directory, and should not depend on any other module outside 24 that directory. (As a historical note: this directory gets its name from a 25 compressed version of the phrase "XR RunTime", a generic term for Monado and an ··· 161 destroy function that does not take a pointer-to-a-pointer, make sure to do 162 null checks before calling and set it to null after it returns. 163 164 + Also note: when an interface includes a "destroy" function pointer, it takes the 165 + normal pointer to an object: The free function wrapper is the one that takes a 166 + pointer-to-a-pointer and handles the null checks. See for example @ref 167 xrt_instance_destroy takes the pointer-to-a-pointer, while the interface method 168 + @ref xrt_instance::destroy takes the single pointer.

+2 -2

doc/frame-pacing.md

··· 7 8 A "brief" overview of the various time-points that a frame goes through, from 9 when the application gets go ahead to render the frame to when pixels are turned 10 - into photons. This is only a single frame, where all of the timings are hit and 11 the application is single threaded. The HMD also only turns on the display 12 during the vblank period, meaning the pixel to photon transformation is delayed 13 from scanout starting to the vblank period (like for the Index). ··· 43 * @ref xrt_comp_layer_stereo_projection - This and other layer functions are 44 called to list the layers the compositor should render. 45 * @ref xrt_comp_layer_commit - The compositor starts to render the frame, 46 - trying to hit the **present** time. 47 48 [`VK_GOOGLE_display_timing`]: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_GOOGLE_display_timing.html

··· 7 8 A "brief" overview of the various time-points that a frame goes through, from 9 when the application gets go ahead to render the frame to when pixels are turned 10 + into photons. This is only a single frame, where all of the timings are achieved and 11 the application is single threaded. The HMD also only turns on the display 12 during the vblank period, meaning the pixel to photon transformation is delayed 13 from scanout starting to the vblank period (like for the Index). ··· 43 * @ref xrt_comp_layer_stereo_projection - This and other layer functions are 44 called to list the layers the compositor should render. 45 * @ref xrt_comp_layer_commit - The compositor starts to render the frame, 46 + trying to finish at the **present** time. 47 48 [`VK_GOOGLE_display_timing`]: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_GOOGLE_display_timing.html

+1 -1

doc/howto-release.md

··· 47 48 ## Do gitlab release 49 50 - The Gitlab UI has a friendly interface, just follow the guide there.

··· 47 48 ## Do gitlab release 49 50 + The Gitlab UI has a friendly interface, follow the guide there.

+2 -2

doc/howto-remote-driver.md

··· 5 SPDX-License-Identifier: BSL-1.0 6 --> 7 8 - ## Prerequisites 9 10 Before proceeding you will need to have monado installed (or built) and capable 11 of running applications. If you do not have any hardware this should still work 12 - with the dummy driver. For those building Monado themselves you have to make 13 sure the GUI is built. In short the commands `monado-gui` and `monado-service` 14 are needed. 15

··· 5 SPDX-License-Identifier: BSL-1.0 6 --> 7 8 + ## Prerequisites 9 10 Before proceeding you will need to have monado installed (or built) and capable 11 of running applications. If you do not have any hardware this should still work 12 + with the simulated driver. For those building Monado themselves you have to make 13 sure the GUI is built. In short the commands `monado-gui` and `monado-service` 14 are needed. 15

+1 -1

doc/implementing-extensions.md

··· 23 * Implement the `oxr_` Monado internal functions in an appropriate source file 24 `src/state_trackers/oxr/oxr_api_*.c`. Trivial functions can be implemented 25 right there along with the usual parameter checks. More complex functions that 26 - access more internal monado state should call functions implemented in the 27 relevant `oxr_*.c` file (without `_api_`). The definitions for those functions 28 go into `src/xrt/state_trackers/oxr/oxr_objects.h`. 29 * Monado internal implementations of "objects" (think XrSession or

··· 23 * Implement the `oxr_` Monado internal functions in an appropriate source file 24 `src/state_trackers/oxr/oxr_api_*.c`. Trivial functions can be implemented 25 right there along with the usual parameter checks. More complex functions that 26 + use more internal Monado state should call functions implemented in the 27 relevant `oxr_*.c` file (without `_api_`). The definitions for those functions 28 go into `src/xrt/state_trackers/oxr/oxr_objects.h`. 29 * Monado internal implementations of "objects" (think XrSession or

+12 -12

doc/ipc.md

··· 17 any, to start communication. (Auto-starting, where available, is handled by 18 platform-specific mechanisms: the client currently has no code to explicitly 19 start up the service.) 20 - - The client and service must share a dedicated channel for IPC calls (aka 21 - **RPC** - remote procedure call), typically a socket. 22 - - The service must share access to device data updating at various rates, shared 23 - by all clients. This is typically done with a form of **shared memory**. 24 25 Each platform's implementation has a way of meeting each of these needs. The 26 specific way each need is met is highlighted below. ··· 47 48 ## Android Platform Details 49 50 - On Android, in order to pass platform objects, allow for service activation, and 51 fit better within the idioms of the platform, Monado provides a Binder/AIDL 52 service instead of a named socket. (The named sockets we typically use are not 53 permitted by the platform, and "abstract" named sockets are currently available, ··· 90 `Surface`. By default, the JVM code will signal the mainloop to shut down a short 91 time after the last client disconnects, to work best within the platform. 92 93 - At startup, just as on Linux, the shared memory segment is created. The 94 - [ashmem][] API is used to create/destroy an anonymous **shared memory** segment 95 - on Android, instead of standard POSIX shared memory, but is otherwise treated 96 - and used exactly the same as on standard Linux: file descriptors are duplicated 97 - and passed through IPC calls, etc. 98 99 When the client side starts up, it creates an __anonymous socket pair__ to use 100 for IPC calls (the **RPC** function) later. It then passes one of the two file ··· 123 ### Synchronization 124 125 Synchronization of new client connections is a special challenge on the Android 126 - platform, since new clients arrive via calls into JVM code while the mainloop is 127 - native code. Unlike Linux, we cannot simply use epoll to check if there are new 128 connections to our locating socket. 129 130 We have the following design goals/constraints:

··· 17 any, to start communication. (Auto-starting, where available, is handled by 18 platform-specific mechanisms: the client currently has no code to explicitly 19 start up the service.) 20 + - The client and service must share a dedicated channel for IPC calls (also 21 + known as **RPC** - remote procedure call), typically a socket. 22 + - The service must share device data updating at various rates, shared by all 23 + clients. This is typically done with a form of **shared memory**. 24 25 Each platform's implementation has a way of meeting each of these needs. The 26 specific way each need is met is highlighted below. ··· 47 48 ## Android Platform Details 49 50 + On Android, to pass platform objects, allow for service activation, and 51 fit better within the idioms of the platform, Monado provides a Binder/AIDL 52 service instead of a named socket. (The named sockets we typically use are not 53 permitted by the platform, and "abstract" named sockets are currently available, ··· 90 `Surface`. By default, the JVM code will signal the mainloop to shut down a short 91 time after the last client disconnects, to work best within the platform. 92 93 + At startup, as on Linux, the shared memory segment is created. The [ashmem][] 94 + API is used to create/destroy an anonymous **shared memory** segment on Android, 95 + instead of standard POSIX shared memory, but is otherwise treated and used 96 + exactly the same as on standard Linux: file descriptors are duplicated and 97 + passed through IPC calls, etc. 98 99 When the client side starts up, it creates an __anonymous socket pair__ to use 100 for IPC calls (the **RPC** function) later. It then passes one of the two file ··· 123 ### Synchronization 124 125 Synchronization of new client connections is a special challenge on the Android 126 + platform, since new clients arrive using calls into JVM code while the mainloop is 127 + C/C++ code. Unlike Linux, we cannot simply use epoll to check if there are new 128 connections to our locating socket. 129 130 We have the following design goals/constraints:

+7 -8

doc/targets.md

··· 37 cases, the entry point might be provided by one of the modules being combined to 38 form the target. For instance, an OpenXR runtime must expose 39 `xrNegotiateLoaderRuntimeInterface`: this function is provided by the OpenXR 40 - state tracker `st_oxr`, so the OpenXR runtime target just has to link the state 41 - tracker in and ensure that symbol is present and visible in the final build 42 - product. 43 44 - Then, the target must provide access to the collection of devices desired. 45 - Target device access is provided by implementing the `xrt_instance` interface in 46 - your target and providing a definition of `xrt_instance_create` that 47 - instantiates your implementation. 48 49 All methods of `xrt_instance` are required, though the `get_prober` method may 50 output a null pointer if the instance is not using a prober, and targets that do ··· 85 - The runtime has a "stub" or "client proxy" implementation that delegates to 86 the service over the IPC. 87 - The service has a normal or complete instance implementation that actually 88 - provides access to devices, etc. 89 90 

··· 37 cases, the entry point might be provided by one of the modules being combined to 38 form the target. For instance, an OpenXR runtime must expose 39 `xrNegotiateLoaderRuntimeInterface`: this function is provided by the OpenXR 40 + state tracker `st_oxr`, so the OpenXR runtime target links the state tracker in 41 + and ensures that symbol is present and visible in the final build product. 0 42 43 + Then, the target must provide an interface to the collection of devices desired. 44 + This is done by implementing the `xrt_instance` interface in your target and 45 + providing a definition of `xrt_instance_create` that instantiates your 46 + implementation. 47 48 All methods of `xrt_instance` are required, though the `get_prober` method may 49 output a null pointer if the instance is not using a prober, and targets that do ··· 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 

+1 -1

doc/tracing.md

··· 54 55 # Start the daemon ftrace probes daemon. 56 # Only needs to be run once and keeps running. 57 - # Not needed with the above config. 58 ./perfetto/out/linux_clang_release/traced_probes & 59 60 # When you want to run a capture do and then run Monado.

··· 54 55 # Start the daemon ftrace probes daemon. 56 # Only needs to be run once and keeps running. 57 + # Not needed with the preceding config. 58 ./perfetto/out/linux_clang_release/traced_probes & 59 60 # When you want to run a capture do and then run Monado.

+1 -1

doc/vulkan-extensions.md

··· 48 49 ## Notes 50 51 - Kept out of the table above to limit its width. 52 53 * Server type: 54 * a: Windowed

··· 48 49 ## Notes 50 51 + Kept out of the preceding table to limit its width. 52 53 * Server type: 54 * a: Windowed

+7 -7

doc/writing-a-new-driver.md

··· 88 various targets (OpenXR runtime shared library, service executable, utility 89 executables) also found in `src/xrt/targets`. If you're using Monado as a 90 toolkit or component rather than as a standalone runtime and service, you can 91 - replicate whatever portions of the target lists in your own target, or just 92 - directly implement the @ref xrt_instance interface more directly, linking in 93 - only those drivers and components you need. **Note**, however, that Monado is 94 - intended to not expose any external API other than the OpenXR API: the @ref 95 - xrt_iface are subject to change as required so those writing drivers or other 96 - software on those interfaces are encouraged to upstream as much as possible to 97 - minimize maintenance burden.

··· 88 various targets (OpenXR runtime shared library, service executable, utility 89 executables) also found in `src/xrt/targets`. If you're using Monado as a 90 toolkit or component rather than as a standalone runtime and service, you can 91 + replicate whatever portions of the target lists in your own target, or directly 92 + implement the @ref xrt_instance interface more directly, linking in only those 93 + drivers and components you need. **Note**, however, that Monado is intended to 94 + not expose any external API other than the OpenXR API: the @ref xrt_iface are 95 + subject to change as required so those writing drivers or other software on 96 + those interfaces are encouraged to upstream as much as possible to minimize 97 + maintenance burden.