OpenXR 超详细的spec–Instance介绍 - 服务器托管|北京服务器租用|机房托管租用|IDC托管租用|机房机柜带宽租用-价格及费用咨询

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.2Extensions

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

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

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

4.2.1xrEnumerateInstanceExtensionProperties()

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.2XrExtensionProperties

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。

服务器托管，北京服务器托管，服务器租用 http://www.fwqtg.net

相关推荐: OpenHarmony轻量级驱动开发

OpenHarmony轻量级驱动开发思维导图: https://download.csdn.net/download/lanlingxueyu/88817155 GPlO（General-purpose input/output）即通用型输入输出描述 GP…