diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8019fdf5e..bd788f1b5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -9,7 +9,7 @@ SPDX-License-Identifier: CC-BY-4.0 There are plenty of valid reasons why someone might not be able to follow all of the guidelines in this section, and that's OK, especially for new contributors or those new to open source entirely. -Just let us know and we'll figure out a way to help you get involved successfully. +Let us know and we'll figure out a way to help you get involved successfully. > Important note: Unlike the guidelines here, the Code of Conduct, > available at , @@ -25,11 +25,11 @@ Just let us know and we'll figure out a way to help you get involved successfull to begin a discussion and help smooth the acceptance of your contribution. - If you are able, please make sure to run clang-format - (ideally version 7 or newer) before each commit, + (ideally version 11 or newer) before each commit, so that you only commit things that are cleanly styled. Consistent, machine-performed formatting improves readability and makes it easier for others to contribute. It also makes it easier to review changes. - If you can't run clang-format, just mention this fact in your request and we'd be happy to help, + If you can't run clang-format, mention this fact in your request and we'd be happy to help, either in a single "Clean up formatting." commit on top of your work, or by "re-writing history" (with your permission and leaving your commit authorship intact), revising each commit to apply formatting. @@ -52,7 +52,7 @@ Just let us know and we'll figure out a way to help you get involved successfull please help by making sure your changes build cleanly (and pass all tests). When on compilers that take warning flags like gcc and clang do, the build system automatically turns on quite a few of them. - If a warning stumps you, just mention it in the request so we can figure it out together. + If you can't figure out a warning, mention it in the request so we can figure it out together. ### Issues diff --git a/README.md b/README.md index bdeecdf01..1b79dc650 100644 --- a/README.md +++ b/README.md @@ -21,8 +21,7 @@ and AR on mobile, PC/desktop, and any other device come up with a lot of weird hardware). Monado aims to be a complete and conforming implementation of the OpenXR API made by Khronos. -The project currently is being developed for GNU/Linux -and aims to support other operating systems in the near future. +The project is primarily developed on GNU/Linux, but also runs on Android and Windows. "Monado" has no specific meaning and is just a name. ## Monado source tree @@ -248,10 +247,8 @@ scripts/format-project.sh You can optionally put something like `CLANG_FORMAT=clang-format-7` before that command if your clang-format binary isn't named `clang-format`. **Note that you'll typically prefer** to use something like `git clang-format` -to just re-format your changes, in case version differences in tools result in overall format changes. -The CI "style" job currently runs on Debian Buster, so it has clang-format-7. -We will probably update that job to Bullseye or Ubuntu 20.10, which will allow -using clang-format-11 by default, soon. +to re-format only your changes, in case version differences in tools result in overall format changes. +The CI "style" job currently runs on Debian Bullseye, so it has clang-format-11. [OpenHMD]: http://openhmd.net [drm-lease]: https://haagch.frickel.club/#!drmlease%2Emd diff --git a/doc/CHANGELOG.md b/doc/CHANGELOG.md index 75fcc07e4..e69479380 100644 --- a/doc/CHANGELOG.md +++ b/doc/CHANGELOG.md @@ -566,12 +566,12 @@ SPDX-FileCopyrightText: 2020 Collabora, Ltd. and the Monado contributors - comp: Set a compositor window title. ([!418](https://gitlab.freedesktop.org/monado/monado/merge_requests/418)) - IPC - - server: Almost completely overhaul the handling of swapchain life cycle + - server: Almost completely overhaul the handling of swapchain lifecycle including: correctly track which swapchains are alive; reuse ids; enforce the maximum number of swapchains; and destroy underlying swapchains when they are destroyed by the client. ([!359](https://gitlab.freedesktop.org/monado/monado/merge_requests/359)) - - util: Make sure to not access NULL control messages, say in the case of the + - util: Make sure to not dereference NULL control messages, say in the case of the server failing to create a swapchain. Also add a whole bunch of paranoia when it comes to the alignment of the control message buffers. ([!359](https://gitlab.freedesktop.org/monado/monado/merge_requests/359)) diff --git a/doc/changes/README.md b/doc/changes/README.md index d334e5f23..21fae973d 100644 --- a/doc/changes/README.md +++ b/doc/changes/README.md @@ -55,14 +55,12 @@ Each change should add a changelog fragment file, whose contents are Markdown-formatted text describing the change briefly. Reference metadata will be used to automatically add links to associated issues/merge requests/pull requests, so no need to add these in your fragment text. The simplest changelog -fragment just contains one line of Markdown text describing the change: +fragment contains one line of Markdown text describing the change: ```md Here the author of a change has written some text about it. ``` -(If you change the template in your Proclamation config file, your project can use a different markup format than Markdown.) - ### References The changelog fragment system revolves around "references" - these are issue @@ -95,7 +93,7 @@ extension added. (You can also use `.rst` or `.txt` as your extension in your project.) To specify additional references in a file, prefix the contents of the changelog -fragment with a block delimited above and below by `---`, with one reference on +fragment with a block delimited before and after by `---`, with one reference on each line. (This can be seen as a very minimal subset of "YAML Front Matter", if you're familiar with that concept.) For example: @@ -109,7 +107,7 @@ Here the author of a change has written some text about it. There are provisions for providing your own reference parser if this format is entirely unusable, but they're underdeveloped. (Most use cases found by the -original author can actually be accommodated just by changing the template and +original author can actually be accommodated by changing the template and specifying `.`-delimited fields in references.) If this functionality is interesting to you, get involved in the development of Proclamation and help finish it! @@ -166,7 +164,7 @@ elaborate use-cases than this.) - `insert_point_pattern` - Useful mainly if you're not using the default template. The first match of this regex will be considered the first line of a release entry, and your new release will be put in your changelog file - above it. Default works with the default template (looks for a second-level + before it. Default works with the default template (looks for a second-level Markdown heading). - `extra_data` - Any extra data you'd like to pass along to your custom template. diff --git a/doc/changes/auxiliary/mr.839.1.md b/doc/changes/auxiliary/mr.839.1.md index d3a39d013..a01e9a4b2 100644 --- a/doc/changes/auxiliary/mr.839.1.md +++ b/doc/changes/auxiliary/mr.839.1.md @@ -1,4 +1,4 @@ util: added `u_device_2d_extents` and `u_setup_2d_extents_split_side_by_side` - this is hopefully to eliminate confusion: the FOV you had to give to -`u_device_split_side_by_side` was just a dummy value, but some people thought +`u_device_split_side_by_side` was a placeholder value, but some people thought it was the actual headset's FOV. diff --git a/doc/changes/misc_features/mr.695.md b/doc/changes/misc_features/mr.695.md index ca3847532..937e68e72 100644 --- a/doc/changes/misc_features/mr.695.md +++ b/doc/changes/misc_features/mr.695.md @@ -1 +1 @@ -Implement tracking overrides via wrapper devices and add a tracking override configuration gui. +Implement tracking overrides using wrapper devices and add a tracking override configuration gui. diff --git a/doc/changes/misc_features/mr.715.md b/doc/changes/misc_features/mr.715.md index c8facc4e1..170a303b7 100644 --- a/doc/changes/misc_features/mr.715.md +++ b/doc/changes/misc_features/mr.715.md @@ -1,3 +1,3 @@ -a/gst: Add a small and fairly dumb framework for integrating gstreamer pipelines +a/gst: Add a small and fairly naive framework for integrating gstreamer pipelines into Monado pipelines. Enough to be able to push frames into it and use various encoder elements. diff --git a/doc/changes/xrt/mr.1258.md b/doc/changes/xrt/mr.1258.md index 37bdab7c2..28e7ad9a6 100644 --- a/doc/changes/xrt/mr.1258.md +++ b/doc/changes/xrt/mr.1258.md @@ -1,3 +1,3 @@ xrt: Add xrt_swapchain_create_properties to allow client compositors and IPC -code to query the main compositor how many images to create on a swapchain -(and in the future or properties as needed). +code to query the main compositor how many images to create on a swapchain, +and provide an extension point for more properties as needed. diff --git a/doc/changes/xrt/mr.721.4.md b/doc/changes/xrt/mr.721.4.md index b3811a302..59b8ac1d8 100644 --- a/doc/changes/xrt/mr.721.4.md +++ b/doc/changes/xrt/mr.721.4.md @@ -1,4 +1,4 @@ Add `xrt_multi_compositor_control` that allows the `xrt_system_compositor` to expose a interface that the IPC layer can use to manage multiple clients without having to do the rendering. This allows us to move a lot of the code -out the IPC layer and make it more about just passing calls. +out the IPC layer and make it more about passing calls. diff --git a/doc/conventions.md b/doc/conventions.md index 704cb5958..08c4ca4e4 100644 --- a/doc/conventions.md +++ b/doc/conventions.md @@ -1,7 +1,7 @@ # Code Style and Conventions {#conventions} @@ -19,7 +19,7 @@ Here are some general code style guidelines we follow. ## APIs Internal APIs, when it makes sense, should be C APIs. Headers that define -general communication interfaces between modules (not just use of utilities) +general communication interfaces between modules (not only use of utilities) belong in the `xrt/include/xrt` directory, and should not depend on any other module outside that directory. (As a historical note: this directory gets its name from a compressed version of the phrase "XR RunTime", a generic term for Monado and an @@ -161,8 +161,8 @@ are gradually migrating those that don't fit this pattern. If you call a destroy function that does not take a pointer-to-a-pointer, make sure to do null checks before calling and set it to null after it returns. -Also note: when an interface includes a "destroy" function pointer, it just -takes the normal pointer to an object: The free function wrapper is the one that -takes a pointer-to-a-pointer and handles the null checks. See for example @ref +Also note: when an interface includes a "destroy" function pointer, it takes the +normal pointer to an object: The free function wrapper is the one that takes a +pointer-to-a-pointer and handles the null checks. See for example @ref xrt_instance_destroy takes the pointer-to-a-pointer, while the interface method -@ref xrt_instance::destroy takes just the single pointer. +@ref xrt_instance::destroy takes the single pointer. diff --git a/doc/frame-pacing.md b/doc/frame-pacing.md index 890f3f824..6503d4076 100644 --- a/doc/frame-pacing.md +++ b/doc/frame-pacing.md @@ -7,7 +7,7 @@ SPDX-License-Identifier: BSL-1.0 A "brief" overview of the various time-points that a frame goes through, from when the application gets go ahead to render the frame to when pixels are turned -into photons. This is only a single frame, where all of the timings are hit and +into photons. This is only a single frame, where all of the timings are achieved and the application is single threaded. The HMD also only turns on the display during the vblank period, meaning the pixel to photon transformation is delayed from scanout starting to the vblank period (like for the Index). @@ -43,6 +43,6 @@ information. * @ref xrt_comp_layer_stereo_projection - This and other layer functions are called to list the layers the compositor should render. * @ref xrt_comp_layer_commit - The compositor starts to render the frame, - trying to hit the **present** time. + trying to finish at the **present** time. [`VK_GOOGLE_display_timing`]: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_GOOGLE_display_timing.html diff --git a/doc/howto-release.md b/doc/howto-release.md index 4a8fbe6fa..9ca7349e7 100644 --- a/doc/howto-release.md +++ b/doc/howto-release.md @@ -47,4 +47,4 @@ git tag v21.0.0 -m"v21.0.0" ## Do gitlab release -The Gitlab UI has a friendly interface, just follow the guide there. +The Gitlab UI has a friendly interface, follow the guide there. diff --git a/doc/howto-remote-driver.md b/doc/howto-remote-driver.md index 39ba958ec..957f3ec85 100644 --- a/doc/howto-remote-driver.md +++ b/doc/howto-remote-driver.md @@ -5,11 +5,11 @@ Copyright 2022, Collabora, Ltd. and the Monado contributors SPDX-License-Identifier: BSL-1.0 --> -## Prerequisites +## Prerequisites Before proceeding you will need to have monado installed (or built) and capable of running applications. If you do not have any hardware this should still work -with the dummy driver. For those building Monado themselves you have to make +with the simulated driver. For those building Monado themselves you have to make sure the GUI is built. In short the commands `monado-gui` and `monado-service` are needed. diff --git a/doc/implementing-extensions.md b/doc/implementing-extensions.md index fa2241c8a..01ea69fd0 100644 --- a/doc/implementing-extensions.md +++ b/doc/implementing-extensions.md @@ -23,7 +23,7 @@ The general steps to implement an OpenXR extension in Monado are as follows. * Implement the `oxr_` Monado internal functions in an appropriate source file `src/state_trackers/oxr/oxr_api_*.c`. Trivial functions can be implemented right there along with the usual parameter checks. More complex functions that - access more internal monado state should call functions implemented in the + use more internal Monado state should call functions implemented in the relevant `oxr_*.c` file (without `_api_`). The definitions for those functions go into `src/xrt/state_trackers/oxr/oxr_objects.h`. * Monado internal implementations of "objects" (think XrSession or diff --git a/doc/ipc.md b/doc/ipc.md index 38c169d2d..6b92572b6 100644 --- a/doc/ipc.md +++ b/doc/ipc.md @@ -17,10 +17,10 @@ There are three main communication needs: any, to start communication. (Auto-starting, where available, is handled by platform-specific mechanisms: the client currently has no code to explicitly start up the service.) -- The client and service must share a dedicated channel for IPC calls (aka - **RPC** - remote procedure call), typically a socket. -- The service must share access to device data updating at various rates, shared - by all clients. This is typically done with a form of **shared memory**. +- The client and service must share a dedicated channel for IPC calls (also + known as **RPC** - remote procedure call), typically a socket. +- The service must share device data updating at various rates, shared by all + clients. This is typically done with a form of **shared memory**. Each platform's implementation has a way of meeting each of these needs. The specific way each need is met is highlighted below. @@ -47,7 +47,7 @@ descriptor to the client, so it has (read) access to this data. ## Android Platform Details -On Android, in order to pass platform objects, allow for service activation, and +On Android, to pass platform objects, allow for service activation, and fit better within the idioms of the platform, Monado provides a Binder/AIDL service instead of a named socket. (The named sockets we typically use are not permitted by the platform, and "abstract" named sockets are currently available, @@ -90,11 +90,11 @@ From there, the native-code mainloop starts when this service received a valid `Surface`. By default, the JVM code will signal the mainloop to shut down a short time after the last client disconnects, to work best within the platform. -At startup, just as on Linux, the shared memory segment is created. The -[ashmem][] API is used to create/destroy an anonymous **shared memory** segment -on Android, instead of standard POSIX shared memory, but is otherwise treated -and used exactly the same as on standard Linux: file descriptors are duplicated -and passed through IPC calls, etc. +At startup, as on Linux, the shared memory segment is created. The [ashmem][] +API is used to create/destroy an anonymous **shared memory** segment on Android, +instead of standard POSIX shared memory, but is otherwise treated and used +exactly the same as on standard Linux: file descriptors are duplicated and +passed through IPC calls, etc. When the client side starts up, it creates an __anonymous socket pair__ to use for IPC calls (the **RPC** function) later. It then passes one of the two file @@ -123,8 +123,8 @@ multiple clients and client transition without shutdown. ### Synchronization Synchronization of new client connections is a special challenge on the Android -platform, since new clients arrive via calls into JVM code while the mainloop is -native code. Unlike Linux, we cannot simply use epoll to check if there are new +platform, since new clients arrive using calls into JVM code while the mainloop is +C/C++ code. Unlike Linux, we cannot simply use epoll to check if there are new connections to our locating socket. We have the following design goals/constraints: diff --git a/doc/targets.md b/doc/targets.md index 960e47157..51b082e4c 100644 --- a/doc/targets.md +++ b/doc/targets.md @@ -37,14 +37,13 @@ executable, or the well-known symbol name if it's a shared library. In some cases, the entry point might be provided by one of the modules being combined to form the target. For instance, an OpenXR runtime must expose `xrNegotiateLoaderRuntimeInterface`: this function is provided by the OpenXR -state tracker `st_oxr`, so the OpenXR runtime target just has to link the state -tracker in and ensure that symbol is present and visible in the final build -product. +state tracker `st_oxr`, so the OpenXR runtime target links the state tracker in +and ensures that symbol is present and visible in the final build product. -Then, the target must provide access to the collection of devices desired. -Target device access is provided by implementing the `xrt_instance` interface in -your target and providing a definition of `xrt_instance_create` that -instantiates your implementation. +Then, the target must provide an interface to the collection of devices desired. +This is done by implementing the `xrt_instance` interface in your target and +providing a definition of `xrt_instance_create` that instantiates your +implementation. All methods of `xrt_instance` are required, though the `get_prober` method may output a null pointer if the instance is not using a prober, and targets that do @@ -85,6 +84,6 @@ Note that in this case, there are two processes involved, which have different - The runtime has a "stub" or "client proxy" implementation that delegates to the service over the IPC. - The service has a normal or complete instance implementation that actually - provides access to devices, etc. + provides hardware device interaction, etc. ![Out-of-process OpenXR runtime diagram](images/out-of-proc.drawio.svg) diff --git a/doc/tracing.md b/doc/tracing.md index 62b5d3471..f23d82262 100644 --- a/doc/tracing.md +++ b/doc/tracing.md @@ -54,7 +54,7 @@ Then run the following commands before launching Monado. # Start the daemon ftrace probes daemon. # Only needs to be run once and keeps running. -# Not needed with the above config. +# Not needed with the preceding config. ./perfetto/out/linux_clang_release/traced_probes & # When you want to run a capture do and then run Monado. diff --git a/doc/vulkan-extensions.md b/doc/vulkan-extensions.md index d46da2f15..16ca5114d 100644 --- a/doc/vulkan-extensions.md +++ b/doc/vulkan-extensions.md @@ -48,7 +48,7 @@ minimize frustration. ## Notes -Kept out of the table above to limit its width. +Kept out of the preceding table to limit its width. * Server type: * a: Windowed diff --git a/doc/writing-a-new-driver.md b/doc/writing-a-new-driver.md index fc21b7d0f..794ec6a74 100644 --- a/doc/writing-a-new-driver.md +++ b/doc/writing-a-new-driver.md @@ -88,10 +88,10 @@ Monado are in `src/xrt/targets/common/target_lists.c`. These are shared by the various targets (OpenXR runtime shared library, service executable, utility executables) also found in `src/xrt/targets`. If you're using Monado as a toolkit or component rather than as a standalone runtime and service, you can -replicate whatever portions of the target lists in your own target, or just -directly implement the @ref xrt_instance interface more directly, linking in -only those drivers and components you need. **Note**, however, that Monado is -intended to not expose any external API other than the OpenXR API: the @ref -xrt_iface are subject to change as required so those writing drivers or other -software on those interfaces are encouraged to upstream as much as possible to -minimize maintenance burden. +replicate whatever portions of the target lists in your own target, or directly +implement the @ref xrt_instance interface more directly, linking in only those +drivers and components you need. **Note**, however, that Monado is intended to +not expose any external API other than the OpenXR API: the @ref xrt_iface are +subject to change as required so those writing drivers or other software on +those interfaces are encouraged to upstream as much as possible to minimize +maintenance burden.