xrSetDebugUtilsObjectNameEXT - Sets debug utils object name

Valid Usage

• In the structure pointed to by nameInfo, DebugUtilsObjectNameInfoEXT::objectType must not be OBJECT_TYPE_UNKNOWN

• In the structure pointed to by nameInfo, DebugUtilsObjectNameInfoEXT::objectHandle must not be XR_NULL_HANDLE

Valid Usage (Implicit)

• The @@ extension must be enabled prior to calling setDebugUtilsObjectNameEXT

• instance must be a valid Instance handle
• nameInfo must be a pointer to a valid DebugUtilsObjectNameInfoEXT structure

Thread Safety

• Access to the objectHandle member of the nameInfo parameter must be externally synchronized

Return Codes

Success

• SUCCESS

Failure

• ERROR_OUT_OF_MEMORY
• ERROR_VALIDATION_FAILURE
• ERROR_RUNTIME_FAILURE
• ERROR_HANDLE_INVALID
• ERROR_INSTANCE_LOST
• ERROR_FUNCTION_UNSUPPORTED

Applications may change the name associated with an object simply by calling setDebugUtilsObjectNameEXT again with a new string. If DebugUtilsObjectNameInfoEXT::objectName is an empty string, then any previously set name is removed.

See Also

DebugUtilsObjectNameInfoEXT, Instance

xrCreateDebugUtilsMessengerEXT - Creates a debug messenger

Valid Usage (Implicit)

• The @@ extension must be enabled prior to calling createDebugUtilsMessengerEXT

• instance must be a valid Instance handle
• createInfo must be a pointer to a valid DebugUtilsMessengerCreateInfoEXT structure
• messenger must be a pointer to an DebugUtilsMessengerEXT handle

Thread Safety

• Access to instance, and any child handles, must be externally synchronized

Return Codes

Success

• SUCCESS

Failure

• ERROR_OUT_OF_MEMORY
• ERROR_VALIDATION_FAILURE
• ERROR_RUNTIME_FAILURE
• ERROR_LIMIT_REACHED
• ERROR_HANDLE_INVALID
• ERROR_INSTANCE_LOST
• ERROR_FUNCTION_UNSUPPORTED

The application must ensure that createDebugUtilsMessengerEXT is not executed in parallel with any OpenXR function that is also called with instance or child of instance.

When an event of interest occurs a debug messenger calls its createInfo->userCallback with a debug message from the producer of the event. Additionally, the debug messenger must filter out any debug messages that the application’s callback is not interested in based on DebugUtilsMessengerCreateInfoEXT flags, as described below.

See Also

DebugUtilsMessengerCreateInfoEXT, DebugUtilsMessengerEXT, Instance, destroyDebugUtilsMessengerEXT

A convenience wrapper to make a compatible pair of calls to createDebugUtilsMessengerEXT and destroyDebugUtilsMessengerEXT

To ensure that destroyDebugUtilsMessengerEXT is always called: pass bracket (or the allocate function from your favourite resource management library) as the last argument. To just extract the pair pass (,) as the last argument.

xrDestroyDebugUtilsMessengerEXT - Destroys a debug messenger

Valid Usage (Implicit)

• The @@ extension must be enabled prior to calling destroyDebugUtilsMessengerEXT

• messenger must be a valid DebugUtilsMessengerEXT handle

Thread Safety

• Access to messenger must be externally synchronized

• Access to the Instance used to create messenger, and all of its child handles must be externally synchronized

Return Codes

Success

• SUCCESS

Failure

• ERROR_HANDLE_INVALID
• ERROR_FUNCTION_UNSUPPORTED

The application must ensure that destroyDebugUtilsMessengerEXT is not executed in parallel with any OpenXR function that is also called with the instance or child of instance that it was created with.

See Also

DebugUtilsMessengerEXT, createDebugUtilsMessengerEXT

xrSubmitDebugUtilsMessageEXT - Submits debug utils message

Valid Usage

• For each structure in objects found in callbackData, the value of DebugUtilsObjectNameInfoEXT::objectType must not be OBJECT_TYPE_UNKNOWN

Valid Usage (Implicit)

• The @@ extension must be enabled prior to calling submitDebugUtilsMessageEXT

• instance must be a valid Instance handle
• messageSeverity must be a valid combination of XrDebugUtilsMessageSeverityFlagBitsEXT values
• messageSeverity must not be 0
• messageTypes must be a valid combination of XrDebugUtilsMessageTypeFlagBitsEXT values
• messageTypes must not be 0
• callbackData must be a pointer to a valid DebugUtilsMessengerCallbackDataEXT structure

Return Codes

Success

• SUCCESS

Failure

• ERROR_HANDLE_INVALID
• ERROR_INSTANCE_LOST
• ERROR_RUNTIME_FAILURE
• ERROR_VALIDATION_FAILURE
• ERROR_FUNCTION_UNSUPPORTED

The application can also produce a debug message, and submit it into the OpenXR messaging system.

The call will propagate through the layers and generate callback(s) as indicated by the message’s flags. The parameters are passed on to the callback in addition to the userData value that was defined at the time the messenger was created.

See Also

DebugUtilsMessageSeverityFlagsEXT, DebugUtilsMessageTypeFlagsEXT, DebugUtilsMessengerCallbackDataEXT, Instance

xrSessionBeginDebugUtilsLabelRegionEXT - Session begin debug utils label region

Valid Usage (Implicit)

• The @@ extension must be enabled prior to calling sessionBeginDebugUtilsLabelRegionEXT

• session must be a valid Session handle
• labelInfo must be a pointer to a valid DebugUtilsLabelEXT structure

Return Codes

Success

• SUCCESS
• SESSION_LOSS_PENDING

Failure

• ERROR_SESSION_LOST
• ERROR_HANDLE_INVALID
• ERROR_VALIDATION_FAILURE
• ERROR_RUNTIME_FAILURE
• ERROR_FUNCTION_UNSUPPORTED

The sessionBeginDebugUtilsLabelRegionEXT function begins a label region within session.

See Also

DebugUtilsLabelEXT, Session

xrSessionEndDebugUtilsLabelRegionEXT - Session end debug utils label region

Valid Usage

• sessionEndDebugUtilsLabelRegionEXT must be called only after a matching sessionBeginDebugUtilsLabelRegionEXT.

Valid Usage (Implicit)

• The @@ extension must be enabled prior to calling sessionEndDebugUtilsLabelRegionEXT

• session must be a valid Session handle

Return Codes

Success

• SUCCESS
• SESSION_LOSS_PENDING

Failure

• ERROR_SESSION_LOST
• ERROR_HANDLE_INVALID
• ERROR_VALIDATION_FAILURE
• ERROR_RUNTIME_FAILURE
• ERROR_FUNCTION_UNSUPPORTED

This function ends the last label region begun with the sessionBeginDebugUtilsLabelRegionEXT function within the same session.

See Also

Session

xrSessionInsertDebugUtilsLabelEXT - Session insert debug utils label

Valid Usage (Implicit)

• The @@ extension must be enabled prior to calling sessionInsertDebugUtilsLabelEXT

• session must be a valid Session handle
• labelInfo must be a pointer to a valid DebugUtilsLabelEXT structure

Return Codes

Success

• SUCCESS
• SESSION_LOSS_PENDING

Failure

• ERROR_SESSION_LOST
• ERROR_HANDLE_INVALID
• ERROR_VALIDATION_FAILURE
• ERROR_RUNTIME_FAILURE
• ERROR_FUNCTION_UNSUPPORTED

The sessionInsertDebugUtilsLabelEXT function inserts an individual label within session. The individual labels are useful for different reasons based on the type of debugging scenario. When used with something active like a profiler or debugger, it identifies a single point of time. When used with logging, the individual label identifies that a particular location has been passed at the point the log message is triggered. Because of this usage, individual labels only exist in a log until the next call to any of the label functions:

• sessionBeginDebugUtilsLabelRegionEXT
• sessionEndDebugUtilsLabelRegionEXT
• sessionInsertDebugUtilsLabelEXT

See Also

DebugUtilsLabelEXT, Session, sessionBeginDebugUtilsLabelRegionEXT, sessionEndDebugUtilsLabelRegionEXT

XrDebugUtilsObjectNameInfoEXT - Debug utils object name info

Valid Usage

• If objectType is OBJECT_TYPE_UNKNOWN, objectHandle must not be XR_NULL_HANDLE

• If objectType is not OBJECT_TYPE_UNKNOWN, objectHandle must be XR_NULL_HANDLE or an OpenXR handle of the type associated with objectType

Valid Usage (Implicit)

• The @@ extension must be enabled prior to using DebugUtilsObjectNameInfoEXT

• type must be TYPE_DEBUG_UTILS_OBJECT_NAME_INFO_EXT
• next must be NULL or a valid pointer to the next structure in a structure chain
• objectType must be a valid ObjectType value
• If objectName is not NULL, objectName must be a null-terminated UTF-8 string

See Also

DebugUtilsMessengerCallbackDataEXT, ObjectType, StructureType, setDebugUtilsObjectNameEXT

XrDebugUtilsLabelEXT - Debug Utils Label

Valid Usage (Implicit)

• The @@ extension must be enabled prior to using DebugUtilsLabelEXT

• type must be TYPE_DEBUG_UTILS_LABEL_EXT
• next must be NULL or a valid pointer to the next structure in a structure chain
• labelName must be a null-terminated UTF-8 string

See Also

DebugUtilsMessengerCallbackDataEXT, StructureType, sessionBeginDebugUtilsLabelRegionEXT, sessionInsertDebugUtilsLabelEXT

XrDebugUtilsMessengerCallbackDataEXT - Debug utils messenger callback data

Valid Usage (Implicit)

• The @@ extension must be enabled prior to using DebugUtilsMessengerCallbackDataEXT

• type must be TYPE_DEBUG_UTILS_MESSENGER_CALLBACK_DATA_EXT
• next must be NULL or a valid pointer to the next structure in a structure chain
• messageId must be a null-terminated UTF-8 string
• functionName must be a null-terminated UTF-8 string
• message must be a null-terminated UTF-8 string

An DebugUtilsMessengerCallbackDataEXT is a messenger object that handles passing along debug messages to a provided debug callback.

Note

This structure should only be considered valid during the lifetime of the triggered callback.

The labels listed inside sessionLabels are organized in time order, with the most recently generated label appearing first, and the oldest label appearing last.

See Also

DebugUtilsLabelEXT, DebugUtilsObjectNameInfoEXT, StructureType, submitDebugUtilsMessageEXT

XrDebugUtilsMessengerCreateInfoEXT - Debug utils messenger create info

Valid Usage

• userCallback must be a valid PFN_xrDebugUtilsMessengerCallbackEXT

Valid Usage (Implicit)

• The @@ extension must be enabled prior to using DebugUtilsMessengerCreateInfoEXT

• type must be TYPE_DEBUG_UTILS_MESSENGER_CREATE_INFO_EXT
• next must be NULL or a valid pointer to the next structure in a structure chain
• messageSeverities must be a valid combination of XrDebugUtilsMessageSeverityFlagBitsEXT values
• messageSeverities must not be 0
• messageTypes must be a valid combination of XrDebugUtilsMessageTypeFlagBitsEXT values
• messageTypes must not be 0
• userCallback must be a valid PFN_xrDebugUtilsMessengerCallbackEXT value

For each DebugUtilsMessengerEXT that is created the DebugUtilsMessengerCreateInfoEXT::messageSeverities and DebugUtilsMessengerCreateInfoEXT::messageTypes determine when that DebugUtilsMessengerCreateInfoEXT::userCallback is called. The process to determine if the user’s userCallback is triggered when an event occurs is as follows:

• The runtime will perform a bitwise AND of the event’s XrDebugUtilsMessageSeverityFlagBitsEXT with the DebugUtilsMessengerCreateInfoEXT::messageSeverities provided during creation of the DebugUtilsMessengerEXT object.
• If this results in 0, the message is skipped.
• The runtime will perform bitwise AND of the event’s XrDebugUtilsMessageTypeFlagBitsEXT with the DebugUtilsMessengerCreateInfoEXT::messageTypes provided during the creation of the DebugUtilsMessengerEXT object.
• If this results in 0, the message is skipped.
• If the message of the current event is not skipped, the callback will be called with the message.

The callback will come directly from the component that detected the event, unless some other layer intercepts the calls for its own purposes (filter them in a different way, log to a system error log, etc.).

See Also

PFN_xrDebugUtilsMessengerCallbackEXT, DebugUtilsMessageSeverityFlagsEXT, DebugUtilsMessageTypeFlagsEXT, StructureType, createDebugUtilsMessengerEXT

XrDebugUtilsMessageSeverityFlagsEXT - XrDebugUtilsMessageSeverityFlagsEXT

See Also

DebugUtilsMessengerCreateInfoEXT, submitDebugUtilsMessageEXT

XrDebugUtilsMessageTypeFlagsEXT - XrDebugUtilsMessageTypeFlagsEXT

See Also

DebugUtilsMessengerCreateInfoEXT, submitDebugUtilsMessageEXT

PFN_xrDebugUtilsMessengerCallbackEXT - Type of callback function invoked by the debug utils

Parameter Descriptions

Description

The callback must not call destroyDebugUtilsMessengerEXT.

The callback returns an https://www.khronos.org/registry/OpenXR/specs/1.0/html/xrspec.html#XrBool32 that indicates to the calling layer the application’s desire to abort the call. A value of TRUE indicates that the application wants to abort this call. If the application returns FALSE, the function must not be aborted. Applications should always return FALSE so that they see the same behavior with and without validation layers enabled.

If the application returns TRUE from its callback and the OpenXR call being aborted returns an Result, the layer will return ERROR_VALIDATION_FAILURE.

The object pointed to by callbackData (and any pointers in it recursively) must be valid during the lifetime of the triggered callback. It may become invalid afterwards.

See Also

DebugUtilsMessengerCreateInfoEXT, createDebugUtilsMessengerEXT

XrDebugUtilsMessengerEXT - Callback for debug data

Description

DebugUtilsMessengerEXT represents a callback function and associated filters registered with the runtime.

See Also

createDebugUtilsMessengerEXT, destroyDebugUtilsMessengerEXT