4. Instance

OpenXR instance是一个允许OpenXR application和runtime进行通信的句柄对象。application通过调用xrCreateInstance()和接收一个XrInstance对应的handle完成通信。

XrInstance对象存储和追踪OpenXR相关应用的状态，不需要在application的全局地址空间中存储任何这样的状态。由于instance对象对于application是不透明的，因此application可以创建多个instance，并安全封装application的OpenXR state。

OpenXR runtime可能会限制同时创建和使用XrInstance对象的数量，但他们必须支持每个进程至少创建和使用一个XrInstance对象。

4.1 API layers

API layers或者扩展层可以提供附加功能。API Layer禁止添加或者修改OpenXR function的定义，而扩展层（extensions）可以。

API layers函数集的使能要在创建instance时指定，这些API layers能够拦截（intercept）任何分发给该instance或者它的子类对象的函数。

API layers示例可以包含（但不限制于）：

  • dump out OpenXR API的调用
  • 执行OpenXR校验。

4.1.1.xrEnumerateApiLayerProperties()

XrResult xrEnumerateApiLayerProperties(uint32_tpropertyCapacityInput,uint32_t* propertyCountOutput,XrApiLayerProperties* properties);
  • 该函数决定哪些API layers集是可用的。
  • 参数propertyCapacityInput是属性array的容量值，0表示请求检索需要的capacity。
  • 参数propertyCountOutput是指向要写入属性数量的指针，或者是指向所需capacity的指针，以防propertyCapacityInput不足的情况。
  • 属性是指向XrApiLayerProperties结构体数组的指针，如果propertyCapacityInput=0，则可以为NULL。
  • 由于Runtime的外部操作，layers的可用列表在任何时间可能变化，因此该方法的使用相同的参数调用两次，返回结果可能不同。

一旦创建了instance，使能的layers在该instance的有效生命周期内都会继续enabled和valid，即使其中一些layer对未来的instance不可用。

4.1.2. XrApiLayerProperties结构体

typedef struct XrApiLayerProperties {XrStructureTypetype;void*next;char layerName[XR_MAX_API_LAYER_NAME_SIZE];XrVersionspecVersion;uint32_t layerVersion;char description[XR_MAX_API_LAYER_DESCRIPTION_SIZE];} XrApiLayerProperties;
  • type：必须是XR_TYPE_API_LAYER_PROPERTIES才是有效的。
  • next: NULL 或者指向结构链中下一个结构体的指针。OpenXR core中没有定义该类结构体。
  • layerName：是指定API layer名称的string。可以在XrInstanceCreateInfo::enabledApiLayerNames数组中使用该name为instance enable该API。

当创建XrInstance对象时，为了enable一个layer，必须把该layer的name添加到XrInstanceCreateInfo::enabledApiLayerNames数组。这种启动API layer的方式称为显示enabled。Loader也可以提供隐式enabled API layer的机制，两种机制只是在enable方式上有所不同，其他都一样。

4.2Extensions

Instance extensions能够影响instance和它子类对象的操作。extensions可以扩展OpenXR API，并提供新的功能或者增强行为。

extension 示例包括（但不限制于）

  • 包含OpenXR functions来与新的图形API一起使用
  • 通过callback公开debug信息

4.2.1xrEnumerateInstanceExtensionProperties()

XrResult xrEnumerateInstanceExtensionProperties(const char* layerName,uint32_tpropertyCapacityInput,uint32_t* propertyCountOutput,XrExtensionProperties*properties);
  • application可以通过调用该函数决定instance的哪些extensions可用。
  • layerName: NULL或者是由xrEnumerateApiLayerProperties()从extensions中检索返回的API layer的name。
  • propertyCapacityInput：属性数组的大小，0表示请求检索所需要的容量。
  • propertyCountOutput：执行写入属性计数的指针，或者是一个在propertyCapacityInput不足的情况下指向所需容量的指针。
  • properties：是一个指向XrExtensionProperties结构体数组的指针。当propertyCapacityInput=0时，则为NULL。

4.2.2XrExtensionProperties

typedef struct XrExtensionProperties {XrStructureTypetype;void*next;char extensionName[XR_MAX_EXTENSION_NAME_SIZE];uint32_t extensionVersion;} XrExtensionProperties;

extensionName：是一个extension的name字符串。

4.3 Instance 生命周期

4.3.1 xrCreateInstance()

XrResult xrCreateInstance(const XrInstanceCreateInfo* createInfo,XrInstance* instance);
  • createInfo：是一个指向控制instance创建的XrInstanceCreateInfo实例的指针。
  • instance：指向返回的XrInstance的handle。
  • 该方法创建XrInstance实例，并enable和初始化application请求的全局API layers和extensions。

4.3.2 XrInstanceCreateInfo结构体

typedef struct XrInstanceCreateInfo {XrStructureTypetype;const void*next;XrInstanceCreateFlagscreateFlags;XrApplicationInfoapplicationInfo;uint32_t enabledApiLayerCount;const char* const* enabledApiLayerNames;uint32_t enabledExtensionCount;const char* const* enabledExtensionNames;} XrInstanceCreateInfo;
  • type：必须是XR_TYPE_INSTANCE_CREATE_INFO。
  • createFlags是XrInstanceCreateFlags的一个bitmask（位掩码），标识用于创建时的选项。目前没有相关flags的定义，保留字段，因此必须是0。
  • applicationInfo是一个XRApplicationInfo的实例。该信息有助于Runtime识别application类的内在行为。
  • enabledApiLayerCount：enable全局API layers的数目。
  • enabledApiLayerNames：指向创建instance要enable的包含API layers name的数组。该数组长度是enabledApiLayerCount。
  • enabledExtensionCount：要enable的全局extensions的数目。
  • enabledExtensionNames：指向包含要enable的extensions name的数组，该数组长度是enabledExtensionCount。

4.3.3 XrApplicationInfo结构体

typedef struct XrApplicationInfo {char applicationName[XR_MAX_APPLICATION_NAME_SIZE];uint32_t applicationVersion;char engineName[XR_MAX_ENGINE_NAME_SIZE];uint32_t engineVersion;XrVersionapiVersion;} XrApplicationInfo;
  • applicationName：是一个指定application name的一个非空字符串。
  • applicationVersion：是一个指定application版本的无符号整数。
  • engineName：是一个创建application的引擎name。
  • engineVersion：是一个无符号整数，表示引擎版本。

4.3.4 xrDestroyInstance()

XrResult xrDestroyInstance(XrInstanceinstance);
  • 该函数是用来destroy指定的instance。当一个XrInstance被销毁，她所有子类的handle也都会被销毁。

4.4 Instance Information

4.4.1 xrGetInstanceProperties()

XrResult xrGetInstanceProperties(XrInstanceinstance,XrInstanceProperties* instanceProperties);
  • instance：是由函数xrCreateInstance()创建的XrInstance的一个handle，该handle必须是有效的。
  • instanceProperties：指向描述该instance的XrInstanceProperties类型指针。该参数是由Runtime响应该函数调用时赋值。

4.4.2 XrInstanceProperties结构体

typedef struct XrInstanceProperties {XrStructureTypetype;void*next;XrVersionruntimeVersion;char runtimeName[XR_MAX_RUNTIME_NAME_SIZE];} XrInstanceProperties;

该结构体可以看出是描述Runtime信息的，所以Instance是与Runtime绑定的。

4.5 特定平台的Instance创建

创建实例所需要的一些数据是通过extensions中定义的链式结构体来公开（exposed）。这些结构体可以是可选的，也可以是特定平台创建instance所必要的。把特定平台的功能分离到extension的结构中可以避免XrInstanceCreateInfo结构体因为没必要的信息变得臃肿。

4.5.1 Instance Loss Error（Instance丢失错误）

XR_ERROR_INSTANCE_LOST错误表示XrInstance已经不可用。一旦返回该error，在该instance被销毁之前所有涉及到该XrIntance或者其子类的函数都必须返回该error。application会从创建新的XrInstance开始创建所有相关的OpenXR对象。当检测到instance loss时，Runtime会生成一个XrEventDataInstanceLossPending的事件。

出现该error的场景有：

  • 如果关键的Runtime进程中止。
  • 如果与Runtime的连接不可用，
  • 如果Runtime在任何函数执行过程中发生错误，从而无法支持进一步的函数执行时。

4.5.2 XrEventDataInstanceLossPending

typedef struct XrEventDataInstanceLossPending {XrStructureTypetype;const void*next;XrTime lossTime;} XrEventDataInstanceLossPending;
  • 收到该事件表示application可能会丢失该XrInstance。因此application应该调用xrDestoryInstance()并释放资源。例如软件更新会触发该事件。
  • 当application销毁所有与该instance相关的并等待超过指定时间，它可能就尝试调用xrCreateInstance()来创建新的instance。
  • XrTime：是该instance被认为lost和变得不可用的绝对时间。

4.5 Instance枚举字符串类型函数

application通常会将Runtime的某些枚举值转化为string类型，用在log信息中、UI本地化或者其他原因。OpenXR为application提供了常见的Enums类型转化成UTF-8 String类型的函数。

4.5.1 xrResultToString()

XrResult xrResultToString(XrInstanceinstance,XrResultvalue,charbuffer[XR_MAX_RESULT_STRING_SIZE]);
  • 该函数把XrResult类型转化成对应的string。
  • instance：请求string的instance的handle。
  • value：要转成string的XrResult。
  • buffer：用于返回string的buffer。

4.5.2 xrStructureTypeToString()

XrResult xrStructureTypeToString(XrInstanceinstance,XrStructureType value,charbuffer[XR_MAX_STRUCTURE_NAME_SIZE]);
  • 该函数把XrStructureType类型转化成对应的string。
  • instance：请求string的instance的handle。
  • value：要转成string的XrStructureType。
  • buffer：用于返回string的buffer。