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_t                                    propertyCapacityInput,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 {XrStructureType    type;void*              next;char               layerName[XR_MAX_API_LAYER_NAME_SIZE];XrVersion          specVersion;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.2 Extensions

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

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

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

4.2.1 xrEnumerateInstanceExtensionProperties()

XrResult xrEnumerateInstanceExtensionProperties(const char*                                 layerName,uint32_t                                    propertyCapacityInput,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.2 XrExtensionProperties

typedef struct XrExtensionProperties {XrStructureType    type;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 {XrStructureType          type;const void*              next;XrInstanceCreateFlags    createFlags;XrApplicationInfo        applicationInfo;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;XrVersion    apiVersion;
} XrApplicationInfo;

• applicationName：是一个指定application name的一个非空字符串。
• applicationVersion：是一个指定application版本的无符号整数。
• engineName：是一个创建application的引擎name。
• engineVersion：是一个无符号整数，表示引擎版本。

4.3.4 xrDestroyInstance()

XrResult xrDestroyInstance(XrInstance                                  instance);

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

4.4 Instance Information

4.4.1 xrGetInstanceProperties()

XrResult xrGetInstanceProperties(XrInstance                                  instance,XrInstanceProperties*                       instanceProperties);

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

4.4.2 XrInstanceProperties结构体

typedef struct XrInstanceProperties {XrStructureType    type;void*              next;XrVersion          runtimeVersion;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 {XrStructureType    type;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(XrInstance                                  instance,XrResult                                    value,char                                        buffer[XR_MAX_RESULT_STRING_SIZE]);

• 该函数把XrResult类型转化成对应的string。
• instance：请求string的instance的handle。
• value：要转成string的XrResult。
• buffer：用于返回string的buffer。

4.5.2 xrStructureTypeToString()

XrResult xrStructureTypeToString(XrInstance                                  instance,XrStructureType                             value,char                                        buffer[XR_MAX_STRUCTURE_NAME_SIZE]);

• 该函数把XrStructureType类型转化成对应的string。
• instance：请求string的instance的handle。
• value：要转成string的XrStructureType。
• buffer：用于返回string的buffer。