KhronosGroup / KhronosGroup/OpenXR-SDK-Source

Layer usage is poorly documented

Open
#267 4 comments 0 reactions 0 assignees View on GitHub
synced to gitlab
Dominant language
Python
Stars
825
Forks
306
Avg merge
1d 23h
Merged PRs (30d)
1

Description

The main documentation for layers seems to be [api_layer.adoc](https://github.com/KhronosGroup/OpenXR-SDK-Source/blob/master/specification/loader/api_layer.adoc), but this contains a great deal of information (e.g. manifest spec, negotiation) that's not pertinent to the common case of a developer who just wants to install/enable the validation/dump layers. Worse, it doesn't mention `XR_ENABLE_API_LAYERS` at *all*; in fact this critical variable only has [9 google results](https://www.google.com/search?hl=en&q=%22XR_ENABLE_API_LAYERS%22), none of which are official documentation. Finally, it's not actually linked from the README of this or the OpenXR-SDK repository, or from any Khronos pages I could find; I wouldn't have discovered it at all were I not lurking in the Monado discord while it was mentioned by @ChristophHaag. Layer-specific docs are similarly obscure.

It's also confusing that (unlike Vulkan) the layers are not included in the standard SDK build. It's nice that Windows binaries are available in this repo's releases, but it would be nicer if they came standard. End users aren't installing the SDK. That said, it's also convenient to have a lightweight loader-only source archive available for use in build system magic, so maybe the problem here is just one of discoverability.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by reviewing specification/loader/api_layer.adoc, the repository README, and the layer-specific documentation mentioned in the issue. Define the documentation and linking changes needed for developers who want to install or enable validation and dump layers, and record the unresolved question about including layers in the standard SDK build.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.