KhronosGroup / KhronosGroup/OpenXR-Docs

clarify lifetime of objects passed to Debug Utils label functions

Open
#152 4 comments 0 reactions 0 assignees View on GitHub
clarification synced to gitlab vendor-extension waiting for reporter
Dominant language
Python
Stars
181
Forks
74
PR merge metrics
No merged PRs in 30d

Description

Example 3 in [12.26. XR_EXT_debug_utils](https://registry.khronos.org/OpenXR/specs/1.0/html/xrspec.html#XR_EXT_debug_utils) describes the data passed to the callback at two different points as

> * [0] = `individual_label` with `labelName` = "WaitFrame"
> * [1] = `session_active_region_label` with `labelName` = "Session active"
and
> * [0] = `individual_label` with `labelName` = "BeginFrame"
> * [1] = `session_frame_region_label` with `labelName` = "Session Frame 123"
> * [2] = `session_active_region_label` with `labelName` = "Session active"

which suggests the callback data contains pointers to the original `XrDebugUtilsLabelEXT ` structures passed to `pfnSessionBeginDebugUtilsLabelRegionEXT` or `pfnSessionInsertDebugUtilsLabelEXT`, rather than a copy owned by the runtime.

If that is the case, it should be reconsidered or made very explicit and the example should probably be changed to allocate `individual_label` on the heap rather than stack since in general `Insert`ed labels will probably last longer than the function that added them.

If the mention of the specific structures was just illustrative and not intended to mean it was actually the same structure, it would be nice to clarify that the pointers to the `XrDebugUtilsLabelEXT` struct and the contained string do not need to remain valid after the call to `Begin` or `Insert` the label (and that those functions _must_ not store them indefinitely.)

Many languages can't easily build long-lived C struct on the stack as in the example, and might need to translate their own native string types, so can be expected to allocate and free both around each call. Even in C, though, I'd probably wrap those functions in something that accepts a string and passes it in a stack-allocated struct local to the wrapper function.

Not sure if any other functions accept similar potentially long-lived data, if so it might be better to put something like that in the implicit validity section.

Contributor guide

No contributing guide indexed for this repository

Research direction

Read Example 3 in section 12.26, XR_EXT_debug_utils, and compare its callback data with pfnSessionBeginDebugUtilsLabelRegionEXT and pfnSessionInsertDebugUtilsLabelEXT. Determine whether the runtime copies the XrDebugUtilsLabelEXT structures and strings or retains pointers, then clarify the validity requirements and update the example or implicit validity section accordingly.

Written by the indexing model from the issue text.

Assessment

Tech stack
c
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.