public Class EXTDebugUtils

XrDebugUtilsMessageSeverityFlagBitsEXT - XrDebugUtilsMessageSeverityFlagBitsEXT

Enum values:

• DEBUG_UTILS_MESSAGE_SEVERITY_VERBOSE_BIT_EXT
• DEBUG_UTILS_MESSAGE_SEVERITY_INFO_BIT_EXT
• DEBUG_UTILS_MESSAGE_SEVERITY_WARNING_BIT_EXT
• DEBUG_UTILS_MESSAGE_SEVERITY_ERROR_BIT_EXT

XrDebugUtilsMessageSeverityFlagBitsEXT - XrDebugUtilsMessageSeverityFlagBitsEXT

Enum values:

• DEBUG_UTILS_MESSAGE_SEVERITY_VERBOSE_BIT_EXT
• DEBUG_UTILS_MESSAGE_SEVERITY_INFO_BIT_EXT
• DEBUG_UTILS_MESSAGE_SEVERITY_WARNING_BIT_EXT
• DEBUG_UTILS_MESSAGE_SEVERITY_ERROR_BIT_EXT

XrDebugUtilsMessageSeverityFlagBitsEXT - XrDebugUtilsMessageSeverityFlagBitsEXT

Enum values:

• DEBUG_UTILS_MESSAGE_SEVERITY_VERBOSE_BIT_EXT
• DEBUG_UTILS_MESSAGE_SEVERITY_INFO_BIT_EXT
• DEBUG_UTILS_MESSAGE_SEVERITY_WARNING_BIT_EXT
• DEBUG_UTILS_MESSAGE_SEVERITY_ERROR_BIT_EXT

XrDebugUtilsMessageSeverityFlagBitsEXT - XrDebugUtilsMessageSeverityFlagBitsEXT

Enum values:

• DEBUG_UTILS_MESSAGE_SEVERITY_VERBOSE_BIT_EXT
• DEBUG_UTILS_MESSAGE_SEVERITY_INFO_BIT_EXT
• DEBUG_UTILS_MESSAGE_SEVERITY_WARNING_BIT_EXT
• DEBUG_UTILS_MESSAGE_SEVERITY_ERROR_BIT_EXT

XrDebugUtilsMessageTypeFlagBitsEXT - XrDebugUtilsMessageTypeFlagBitsEXT

Enum values:

• DEBUG_UTILS_MESSAGE_TYPE_GENERAL_BIT_EXT
• DEBUG_UTILS_MESSAGE_TYPE_VALIDATION_BIT_EXT
• DEBUG_UTILS_MESSAGE_TYPE_PERFORMANCE_BIT_EXT
• DEBUG_UTILS_MESSAGE_TYPE_CONFORMANCE_BIT_EXT

XrDebugUtilsMessageTypeFlagBitsEXT - XrDebugUtilsMessageTypeFlagBitsEXT

Enum values:

• DEBUG_UTILS_MESSAGE_TYPE_GENERAL_BIT_EXT
• DEBUG_UTILS_MESSAGE_TYPE_VALIDATION_BIT_EXT
• DEBUG_UTILS_MESSAGE_TYPE_PERFORMANCE_BIT_EXT
• DEBUG_UTILS_MESSAGE_TYPE_CONFORMANCE_BIT_EXT

XrDebugUtilsMessageTypeFlagBitsEXT - XrDebugUtilsMessageTypeFlagBitsEXT

Enum values:

• DEBUG_UTILS_MESSAGE_TYPE_GENERAL_BIT_EXT
• DEBUG_UTILS_MESSAGE_TYPE_VALIDATION_BIT_EXT
• DEBUG_UTILS_MESSAGE_TYPE_PERFORMANCE_BIT_EXT
• DEBUG_UTILS_MESSAGE_TYPE_CONFORMANCE_BIT_EXT

XrDebugUtilsMessageTypeFlagBitsEXT - XrDebugUtilsMessageTypeFlagBitsEXT

Enum values:

• DEBUG_UTILS_MESSAGE_TYPE_GENERAL_BIT_EXT
• DEBUG_UTILS_MESSAGE_TYPE_VALIDATION_BIT_EXT
• DEBUG_UTILS_MESSAGE_TYPE_PERFORMANCE_BIT_EXT
• DEBUG_UTILS_MESSAGE_TYPE_CONFORMANCE_BIT_EXT

The extension name.

The extension specification version.

Extends XrObjectType.

Extends XrStructureType.

Enum values:

• TYPE_DEBUG_UTILS_OBJECT_NAME_INFO_EXT
• TYPE_DEBUG_UTILS_MESSENGER_CALLBACK_DATA_EXT
• TYPE_DEBUG_UTILS_MESSENGER_CREATE_INFO_EXT
• TYPE_DEBUG_UTILS_LABEL_EXT

Extends XrStructureType.

Enum values:

• TYPE_DEBUG_UTILS_OBJECT_NAME_INFO_EXT
• TYPE_DEBUG_UTILS_MESSENGER_CALLBACK_DATA_EXT
• TYPE_DEBUG_UTILS_MESSENGER_CREATE_INFO_EXT
• TYPE_DEBUG_UTILS_LABEL_EXT

Extends XrStructureType.

Enum values:

• TYPE_DEBUG_UTILS_OBJECT_NAME_INFO_EXT
• TYPE_DEBUG_UTILS_MESSENGER_CALLBACK_DATA_EXT
• TYPE_DEBUG_UTILS_MESSENGER_CREATE_INFO_EXT
• TYPE_DEBUG_UTILS_LABEL_EXT

Extends XrStructureType.

Enum values:

• TYPE_DEBUG_UTILS_OBJECT_NAME_INFO_EXT
• TYPE_DEBUG_UTILS_MESSENGER_CALLBACK_DATA_EXT
• TYPE_DEBUG_UTILS_MESSENGER_CREATE_INFO_EXT
• TYPE_DEBUG_UTILS_LABEL_EXT

Unsafe version of: CreateDebugUtilsMessengerEXT

Unsafe version of: SessionBeginDebugUtilsLabelRegionEXT

Unsafe version of: SessionInsertDebugUtilsLabelEXT

Unsafe version of: SetDebugUtilsObjectNameEXT

Unsafe version of: SubmitDebugUtilsMessageEXT

Creates a debug messenger.

C Specification

XrResult xrCreateDebugUtilsMessengerEXT(
    XrInstance                                  instance,
    const XrDebugUtilsMessengerCreateInfoEXT*   createInfo,
    XrDebugUtilsMessengerEXT*                   messenger);

Valid Usage (Implicit)

• The XR_EXT_debug_utils extension must be enabled prior to calling CreateDebugUtilsMessengerEXT
• instance must be a valid XrInstance handle
• createInfo must be a pointer to a valid XrDebugUtilsMessengerCreateInfoEXT structure
• messenger must be a pointer to an XrDebugUtilsMessengerEXT handle

Thread Safety

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

Return Codes

On success, this command returns

• SUCCESS

On failure, this command returns

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

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 XrDebugUtilsMessengerCreateInfoEXT flags, as described below.

See Also

XrDebugUtilsMessengerCreateInfoEXT, DestroyDebugUtilsMessengerEXT

Parameters

instance:XrInstance

the instance the messenger will be used with.

createInfo:XrDebugUtilsMessengerCreateInfoEXT

points to an XrDebugUtilsMessengerCreateInfoEXT structure, which contains the callback pointer as well as defines the conditions under which this messenger will trigger the callback.

messenger:PointerBuffer

a pointer to which the created XrDebugUtilsMessengerEXT object is returned.

Annotations

@NativeType:XrResult

Destroys a debug messenger.

C Specification

XrResult xrDestroyDebugUtilsMessengerEXT(
    XrDebugUtilsMessengerEXT                    messenger);

Valid Usage (Implicit)

• The XR_EXT_debug_utils extension must be enabled prior to calling DestroyDebugUtilsMessengerEXT
• messenger must be a valid XrDebugUtilsMessengerEXT handle

Thread Safety

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

Return Codes

On success, this command returns

• SUCCESS

On failure, this command returns

• ERROR_FUNCTION_UNSUPPORTED
• ERROR_HANDLE_INVALID

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

CreateDebugUtilsMessengerEXT

Parameters

messenger:XrDebugUtilsMessengerEXT

the XrDebugUtilsMessengerEXT object to destroy. messenger is an externally synchronized object and must not be used on more than one thread at a time. This means that DestroyDebugUtilsMessengerEXT must not be called when a callback is active.

Annotations

@NativeType:XrResult

Session begin debug utils label region.

C Specification

XrResult xrSessionBeginDebugUtilsLabelRegionEXT(
    XrSession                                   session,
    const XrDebugUtilsLabelEXT*                 labelInfo);

Valid Usage (Implicit)

• The XR_EXT_debug_utils extension must be enabled prior to calling SessionBeginDebugUtilsLabelRegionEXT
• session must be a valid XrSession handle
• labelInfo must be a pointer to a valid XrDebugUtilsLabelEXT structure

Return Codes

On success, this command returns

• SUCCESS
• SESSION_LOSS_PENDING

On failure, this command returns

• ERROR_FUNCTION_UNSUPPORTED
• ERROR_VALIDATION_FAILURE
• ERROR_RUNTIME_FAILURE
• ERROR_HANDLE_INVALID
• ERROR_INSTANCE_LOST
• ERROR_SESSION_LOST

The SessionBeginDebugUtilsLabelRegionEXT function begins a label region within session.

See Also

XrDebugUtilsLabelEXT

Parameters

session:XrSession

the XrSession that a label region should be associated with.

labelInfo:XrDebugUtilsLabelEXT

the XrDebugUtilsLabelEXT containing the label information for the region that should be begun.

Annotations

@NativeType:XrResult

Session end debug utils label region.

C Specification

XrResult xrSessionEndDebugUtilsLabelRegionEXT(
    XrSession                                   session);

Valid Usage

• SessionEndDebugUtilsLabelRegionEXT must be called only after a matching SessionBeginDebugUtilsLabelRegionEXT.

Valid Usage (Implicit)

• The XR_EXT_debug_utils extension must be enabled prior to calling SessionEndDebugUtilsLabelRegionEXT
• session must be a valid XrSession handle

Return Codes

On success, this command returns

• SUCCESS
• SESSION_LOSS_PENDING

On failure, this command returns

• ERROR_FUNCTION_UNSUPPORTED
• ERROR_VALIDATION_FAILURE
• ERROR_RUNTIME_FAILURE
• ERROR_HANDLE_INVALID
• ERROR_INSTANCE_LOST
• ERROR_SESSION_LOST

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

Parameters

session:XrSession

the XrSession that a label region should be associated with.

Annotations

@NativeType:XrResult

Session insert debug utils label.

C Specification

XrResult xrSessionInsertDebugUtilsLabelEXT(
    XrSession                                   session,
    const XrDebugUtilsLabelEXT*                 labelInfo);

Valid Usage (Implicit)

• The XR_EXT_debug_utils extension must be enabled prior to calling SessionInsertDebugUtilsLabelEXT
• session must be a valid XrSession handle
• labelInfo must be a pointer to a valid XrDebugUtilsLabelEXT structure

Return Codes

On success, this command returns

• SUCCESS
• SESSION_LOSS_PENDING

On failure, this command returns

• ERROR_FUNCTION_UNSUPPORTED
• ERROR_VALIDATION_FAILURE
• ERROR_RUNTIME_FAILURE
• ERROR_HANDLE_INVALID
• ERROR_INSTANCE_LOST
• ERROR_SESSION_LOST

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

XrDebugUtilsLabelEXT, SessionBeginDebugUtilsLabelRegionEXT, SessionEndDebugUtilsLabelRegionEXT

Parameters

session:XrSession

the XrSession that a label region should be associated with.

labelInfo:XrDebugUtilsLabelEXT

the XrDebugUtilsLabelEXT containing the label information for the region that should be begun.

Annotations

@NativeType:XrResult

Sets debug utils object name.

C Specification

XrResult xrSetDebugUtilsObjectNameEXT(
    XrInstance                                  instance,
    const XrDebugUtilsObjectNameInfoEXT*        nameInfo);

Valid Usage

• In the structure pointed to by nameInfo, XrDebugUtilsObjectNameInfoEXT::objectType must not be OBJECT_TYPE_UNKNOWN
• In the structure pointed to by nameInfo, XrDebugUtilsObjectNameInfoEXT::objectHandle must not be NULL_HANDLE

Valid Usage (Implicit)

• The XR_EXT_debug_utils extension must be enabled prior to calling SetDebugUtilsObjectNameEXT
• instance must be a valid XrInstance handle
• nameInfo must be a pointer to a valid XrDebugUtilsObjectNameInfoEXT structure

Thread Safety

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

Return Codes

On success, this command returns

• SUCCESS

On failure, this command returns

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

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

See Also

XrDebugUtilsObjectNameInfoEXT

Parameters

instance:XrInstance

the XrInstance that the object was created under.

nameInfo:XrDebugUtilsObjectNameInfoEXT

a pointer to an instance of the XrDebugUtilsObjectNameInfoEXT structure specifying the parameters of the name to set on the object.

Annotations

@NativeType:XrResult

Submits debug utils message.

C Specification

XrResult                                    xrSubmitDebugUtilsMessageEXT(
    XrInstance                                  instance,
    XrDebugUtilsMessageSeverityFlagsEXT         messageSeverity,
    XrDebugUtilsMessageTypeFlagsEXT             messageTypes,
    const XrDebugUtilsMessengerCallbackDataEXT* callbackData);

Valid Usage

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

Valid Usage (Implicit)

• The XR_EXT_debug_utils extension must be enabled prior to calling SubmitDebugUtilsMessageEXT
• instance must be a valid XrInstance 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 XrDebugUtilsMessengerCallbackDataEXT structure

Return Codes

On success, this command returns

• SUCCESS

On failure, this command returns

• ERROR_FUNCTION_UNSUPPORTED
• ERROR_VALIDATION_FAILURE
• ERROR_RUNTIME_FAILURE
• ERROR_HANDLE_INVALID
• ERROR_INSTANCE_LOST

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

XrDebugUtilsMessengerCallbackDataEXT

Parameters

instance:XrInstance

the debug stream’s XrInstance.

messageSeverity:long

a single bit value of XrDebugUtilsMessageSeverityFlagsEXT severity of this event/message.

messageTypes:long

an XrDebugUtilsMessageTypeFlagsEXT bitmask of XrDebugUtilsMessageTypeFlagBitsEXT specifying which types of event to identify this message with.

callbackData:XrDebugUtilsMessengerCallbackDataEXT

contains all the callback related data in the XrDebugUtilsMessengerCallbackDataEXT structure.

Annotations

@NativeType:XrResult