XR_ML_system_notifications

Experimental API

This API is still an experimental extension not included in the official OpenXR registry and is subject to change.

MedT

This API is only supported on the Magic Leap 2 Med Tech units.

12.109. XR_ML_system_notifications

Name String

XR_ML_system_notifications

Extension Type

Instance extension

Registered Extension Number

474

Revision

1

Extension and Version Dependencies

OpenXR 1.0

Last Modified Date

2023-09-06

Contributors

Michał Kulągowski, Magic Leap
Ron Bessems, Magic Leap

12.109.1. Overview

This extension provides control over the system notifications. This extension allows system notifications that might obscure the field of view to be disabled.

Note that even when all system notifications have been suppressed, developers can still intercept certain events that allow them to properly react to the underlying reason of system notifications.

Permissions Android applications must have the com.magicleap.permission.SYSTEM_NOTIFICATION permission listed in their manifest to use this extension. (protection level: normal)

12.109.2. Suppressing All System Notifications

Applications can suppress system notifications from being shown while the application has focus by calling xrSetSystemNotificationsML with the properly filled XrSystemNotificationsSetInfoML structure.

The xrSetSystemNotificationsML function is defined as:

// Provided by XR_ML_system_notifications
XrResult xrSetSystemNotificationsML(
    XrInstance                                  instance,
    const XrSystemNotificationsSetInfoML*       info);

Parameter Descriptions

• instance is XrInstance.

• info is a pointer to an XrSystemNotificationsSetInfoMLstructure.

This API will work only on certain SKUs. When called on an incompatible SKU theXR_ERROR_SYSTEM_NOTIFICATION_INCOMPATIBLE_SKU_ML error must be returned.

If the com.magicleap.permission.SYSTEM_NOTIFICATION permission was not granted the runtime must returnXR_ERROR_SYSTEM_NOTIFICATION_PERMISSION_DENIED_ML.

Valid Usage (Implicit)

• The XR_ML_system_notifications extension must be enabled prior to calling xrSetSystemNotificationsML

• instance must be a valid XrInstance handle

• info must be a pointer to a valid XrSystemNotificationsSetInfoML structure

Return Codes

Success

• XR_SUCCESS

Failure

• XR_ERROR_FUNCTION_UNSUPPORTED

• XR_ERROR_VALIDATION_FAILURE

• XR_ERROR_RUNTIME_FAILURE

• XR_ERROR_HANDLE_INVALID

• XR_ERROR_INSTANCE_LOST

• XR_ERROR_SYSTEM_NOTIFICATION_PERMISSION_DENIED_ML

• XR_ERROR_SYSTEM_NOTIFICATION_INCOMPATIBLE_SKU_ML

The XrSystemNotificationsSetInfoML structure is defined as:

// Provided by XR_ML_system_notifications
typedef struct XrSystemNotificationsSetInfoML {
    XrStructureType    type;
    const void*        next;
    XrBool32           suppressNotifications;
} XrSystemNotificationsSetInfoML;

Member Descriptions

• type is the XrStructureType of this structure.

• next is NULL or a pointer to the next structure in a structure chain.

• suppressNotifications is a boolean flag for suppressing all system notifications.

Valid Usage (Implicit)

• The XR_ML_system_notifications extension must be enabled prior to using XrSystemNotificationsSetInfoML

• type must be XR_TYPE_SYSTEM_NOTIFICATIONS_SET_INFO_ML

• next must be NULL or a valid pointer to the next structure in a structure chain

12.109.3. New Commands

• xrSetSystemNotificationsML

12.109.4. New Structures

• XrSystemNotificationsSetInfoML

12.109.5. New Enum Constants

• XR_ML_SYSTEM_NOTIFICATIONS_EXTENSION_NAME

• XR_ML_system_notifications_SPEC_VERSION

• Extending XrResult:

  • XR_ERROR_SYSTEM_NOTIFICATION_INCOMPATIBLE_SKU_ML

  • XR_ERROR_SYSTEM_NOTIFICATION_PERMISSION_DENIED_ML

• Extending XrStructureType:

  • XR_TYPE_SYSTEM_NOTIFICATIONS_SET_INFO_ML

Version History

• Revision 1, 2023-09-06 (Michał Kulągowski)

  • Initial extension description