+4 -4

CONTRIBUTING.md

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

+3 -6

README.md

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

+2 -2

doc/CHANGELOG.md

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

+4 -6

doc/changes/README.md

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

+1 -1

doc/changes/auxiliary/mr.839.1.md

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

+1 -1

doc/changes/misc_features/mr.695.md

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

+1 -1

doc/changes/misc_features/mr.715.md

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

+2 -2

doc/changes/xrt/mr.1258.md

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

+1 -1

doc/changes/xrt/mr.721.4.md

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

+6 -6

doc/conventions.md

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

+2 -2

doc/frame-pacing.md

··· 7 7 8 8 A "brief" overview of the various time-points that a frame goes through, from 9 9 when the application gets go ahead to render the frame to when pixels are turned 10 10 - into photons. This is only a single frame, where all of the timings are hit and 10 10 + into photons. This is only a single frame, where all of the timings are achieved and 11 11 the application is single threaded. The HMD also only turns on the display 12 12 during the vblank period, meaning the pixel to photon transformation is delayed 13 13 from scanout starting to the vblank period (like for the Index). ··· 43 43 * @ref xrt_comp_layer_stereo_projection - This and other layer functions are 44 44 called to list the layers the compositor should render. 45 45 * @ref xrt_comp_layer_commit - The compositor starts to render the frame, 46 46 - trying to hit the **present** time. 46 46 + trying to finish at the **present** time. 47 47 48 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 47 48 48 ## Do gitlab release 49 49 50 50 - The Gitlab UI has a friendly interface, just follow the guide there. 50 50 + The Gitlab UI has a friendly interface, follow the guide there.

+2 -2

doc/howto-remote-driver.md

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

+1 -1

doc/implementing-extensions.md

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

+12 -12

doc/ipc.md

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

+7 -8

doc/targets.md

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

+1 -1

doc/tracing.md

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

+1 -1

doc/vulkan-extensions.md

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

+7 -7

doc/writing-a-new-driver.md

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