本文主要是介绍OpenXR 超详细的spec--Instance介绍，希望对大家解决编程问题提供一定的参考价值，需要的开发者们随着小编来一起学习吧！
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的定义，而扩展层可以。
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和变得不可用的绝对时间。
这篇关于OpenXR 超详细的spec--Instance介绍的文章就介绍到这儿，希望我们推荐的文章对编程师们有所帮助！
