SDK SampleCode 接口注释 https://www.khronos.org/registry/OpenXR/specs/1.0/html/xrspec.html

# 基础数据结构

对于运行时实现者来说，OpenXR 是一组函数，它们控制 XR 系统的操作并建立 XR 应用程序的生命周期。 实现者的任务是在实现 OpenXR API 的主机上提供一个软件库，同时根据设备的能力将每个 OpenXR 函数的工作映射到图形硬件上。

# 基础

# API 版本

typedef uint64_t XrVersion; 版本号有三个部分，major version,minor version,patch version

# 字符串编码

这个 API 使用字符串作为一些函数的输入和输出。除非另有说明，否则所有这些字符串都是以 NULL 结尾的 UTF-8 编码的大小写敏感字符数组。

# 外部同步参数

一些销毁方法

The instance parameter, and any child handles, in xrDestroyInstance The session parameter, and any child handles, in xrDestroySession The space parameter, and any child handles, in xrDestroySpace The swapchain parameter, and any child handles, in xrDestroySwapchain The actionSet parameter, and any child handles, in xrDestroyActionSet The action parameter, and any child handles, in xrDestroyAction The objectHandle member of the nameInfo parameter in xrSetDebugUtilsObjectNameEXT The instance parameter, and any child handles, in xrCreateDebugUtilsMessengerEXT The messenger parameter in xrDestroyDebugUtilsMessengerEXT The handTracker parameter, and any child handles, in xrDestroyHandTrackerEXT

# 扩展命名规则

OpenXR 扩展命名的前缀是 XR_ KHR 是 Khronos 公司提供的扩展
EXT 是非 Khronos 公司提供的扩展

例如:

XR_KHR_composition_layer_cube 是一个 OpenXR 扩展，由 Khronos (KHR) OpenXR 工作组创建，以支持多维数据集组合层。

# API 层

OpenXR 被设计成一个分层的 API，这意味着用户或应用程序可以在应用程序和运行时实现之间插入 API 层。这些 API 层提供了额外的功能，从上面的层拦截 OpenXR 函数，然后执行与没有该层时不同的操作。在最简单的情况下，该层只是使用相同的参数调用下一层，但更复杂的层可能实现在其下面的层或运行时中不存在的 API 功能。这种机制本质上是一种被设计到 OpenXR 中的 “函数 shimming” 或 “intercept” 特性，旨在取代更为非正式的 “挂钩” API 调用的方法。

# API 层举例

# 验证层

OpenXR 采用的分层 API 方法允许在 “验证” 层中实现对正确使用 API 的昂贵验证。这一层允许应用程序开发人员在激活验证层的情况下开发其应用程序，以确保应用程序正确地使用了 API。验证层确认应用程序正确地设置了对象状态，为每个函数提供了所需的数据，确保所需的资源可用，等等。如果验证层检测到一个问题，它将发出一个可以被记录或捕获的错误消息

# API Logging Layer

API 层的另一个例子是 API 日志层，它以文本格式将所有 API 调用序列化到输出接收器，包括打印出参数值和结构内容。

# API 跟踪 Layer

相关的 API 跟踪层生成一个跟踪文件，该文件包含提供给 API 的所有信息，以便可以通过重播程序回放跟踪文件。

# 命名 API 层

命名规则:

XR_APILAYER_<VENDOR-TAG>_short_name 比如: XR_APILAYER_ACME_check_best_practices

# 激活 API 层

# 应用激活

应用程序可以通过调用 xrEnumerateApiLayerProperties 函数来确定它们可用的 API 层，以获得可用 API 层的列表。然后，应用程序可以从这个列表中选择所需的 API 层，并在创建实例时将它们提供给 xrCreateInstance 函数。

# API 层扩展

API 层可能实现底层运行时可能支持也可能不支持的 OpenXR 函数。为了公开这些新特性，API 层必须以 OpenXR 扩展的形式公开这些功能。它不能公开没有相关扩展的新的 OpenXR 函数。
例如，OpenXR API-logging API 层可能会公开一个 API 函数，允许应用程序仅在其执行的一部分打开日志记录。由于新函数必须通过扩展公开，所以供应商创建了一个名为 XR_ACME_logging_on_off 的扩展来包含这些新函数。应用程序应该查询 API 层是否支持扩展，然后 (只有当它存在时) 在 xrCreateInstance 期间通过名称启用扩展和 API 层。
要找出 API 层支持的扩展，应用程序必须首先通过调用 xrEnumerateApiLayerProperties 来验证 API 层是否存在于当前系统中。验证了感兴趣的 API 层存在之后，应用程序应该调用 xrEnumerateInstanceExtensionProperties ，并提供 API 层名称作为第一个参数。这将返回在该 API 层内部实现的扩展列表。

# 基础结构

# XrBaseInStructure:

1
2
3
4

typedef struct XrBaseInStructure{
    XrStructureType type;
    const struct XrBaseInStructure* next;
}XrBaseInStructure;

structureType 标记这个结构是什么类型的 这是个链表，next 指向下一个。但核心 OpenXR 结构中未定义类似的结构 这个结构可以方便的定义 只读 指针链

# XrBaseOutStructure

1
2
3
4

typedef struct XrBaseOutStructure{
    XrStructureType type;
    struct XrBaseOutStructure*    next;
} XrBaseOutStructure;

结构基本同上 XrBaseOutStructure 可用于简化遍历结构指针链，该指针链将数据返回给应用程序。

# 下一个链结构的唯一性

应用程序应该 确保它们在给定的next链中创建和插入 每种类型 的 扩展结构的次数不超过一次 。OpenXR 的其他组件 (比如 OpenXR 加载器或 API 层) 可能会将重复的结构插入到这个链中。这为这些组件提供了更新下一个链中出现的结构的能力，方法是对同一结构进行修改，并将新版本放置在链的开头。

# 返回值

# 成功码

# 错误代码

# 方便的宏

# 句柄

句柄唯一标识一个应用程序的实例，其寿命由应用程序通过创建和销毁功能控制。实例句柄包括: XrInstance,XrSession,XrSwapchain 等 句柄是一个层次结构，子句柄从属于父句柄的生命周期，比如：要创建一个 XrSwapChain 句柄，程序必须调用 XrCreateSwapchain 并传递 XrSession , 因此 XrSwapchain 是 XrSession 的子句柄

# 对象句柄类型

1
2
3

typedef enum XrObjectType{

}

其中每一个值对应的一个特定的 OpenXR 的句柄类型.

# 色彩

1
2
3
4
5
6

typedef struct XrColor4f {
    float    r;
    float    g;
    float    b;
    float    a;
} XrColor4f;

# 坐标系

# 二维矢量

1
2
3
4

typedef struct XrVector2f {
    float    x;
    float    y;
} XrVector2f;

# 三维向量

1
2
3
4
5

typedef struct XrVector3f {
    float    x;
    float    y;
    float    z;
} XrVector3f;

# 四维

1
2
3
4
5
6

typedef struct XrVector4f {
    float    x;
    float    y;
    float    z;
    float    w;
} XrVector4f;

# 四元数

1
2
3
4
5
6

typedef struct XrQuaternionf {
    float    x;
    float    y;
    float    z;
    float    w;
} XrQuaternionf;

# 姿势

1
2
3
4

typedef struct XrPosef {
    XrQuaternionf    orientation;
    XrVector3f       position;
} XrPosef;

包含方向与位置

# 浮点偏移量

1
2
3
4

typedef struct XrOffset2Df {
    float    x;
    float    y;
} XrOffset2Df;

# 视场角度

1
2
3
4
5
6

typedef struct XrFovf {
    float    angleLeft;
    float    angleRight;
    float    angleUp;
    float    angleDown;
} XrFovf;

angleLeft 是视场左侧的角度。对于对称视场，此值为负。 angleRight 是视场右侧的角度。 angleUp 是视场顶部的角度。 angleDown 是视场底部的角度。对于对称视场，此值为负。

# 布尔值

typedef uint32_t XrBool32;

1
2

XR_TRUE 代表真实值
XR_FALSE 代表一个假值

# 事件

# 事件轮训