OpenVR API

简介：

OpenVR为VR游戏提供统一的数据接口，从而使得VR游戏不用直接与厂商的SDK打交道。因此，它可独立于游戏来添加扩展新外设。也就是说假如要添加一个新手柄或者头显时，只需要修改OpenVR端即可，而不用再去改已经开发好的VR游戏，如果直接使用厂商SDK的话，则每添加一个厂商的外设就需要改一下VR游戏内的接口。

 OpenVR的API都是以C++接口类方式呈现的，而且都是纯虚函数。当应用程序初始化系统时，它会返回该应用程序所使用到的SDK头文件内相匹配的接口。新发布的接口版本会兼容以前的接口版本，因此，应用程序不必更新到最新的SDK也可正常使用。

初始化与注销：

由于OpenVR API使得游戏能够连接任何添加的外设，因此它不是自动初始化。调用函数vr::VR_Init来初始化OpenVR API以及访问接口vr::IVRSystem；调用vr::VR_Shutdown来断开游戏与外设的连接以及释放vr::IVRSystem接口。

vr::IVRSystem *vr::VR_Init( vr::HmdError*peError, vr::EVRApplicationType eApplicationType )

eApplicationType 参数项有：

1.VRApplication_Scene：一个3D应用程序用来画一个虚拟环境

2.VRApplication_Overlay：一个应用程序只是用来与Overlay或者面板进行交互

3.VRApplication_Background：该应用程序不会启动SteamVR，如果它没有运行VR_Init，将会返回错误VRInitError_Init_NoServerForBackgroundApp

4.VRApplication_Utility ：即使没有外设，该应用程序也会启动运行，但是只有IVRSettings和IVRApplications接口能够保证正常工作。该参数项类型适合安装程序使用。

该函数将返回一个vr::IVRSystem类型指针，游戏可通过它来调用其他的OpenVR API方法。如果调用失败，则将返回NULL并且赋给peError一个错误码用来指示错误内容。peError为产生的错误代码或者没有错误时为vr::VRInitError_None。错误码如下：

HmdError_None (0) - 无错误
HmdError_Unknown (1) - 未知错误
HmdError_Init_InstallationNotFound (100) - 在路径注册表中指定的安装文件夹不存在
HmdError_Init_InstallationCorrupt (101) - 在路径注册表中指定的安装文件夹没有bin文件夹
HmdError_Init_VRClientDLLNotFound (102) - bin文件夹中没有vrclient.dll 或系统对应的动态库
HmdError_Init_FileNotFound (103) - 驱动不能加载
HmdError_Init_FactoryNotFound (104) - vrclient.dll中的工厂方法找不到，是vrclient.dll出现异常吗?
HmdError_Init_InterfaceNotFound (105) - VR_Init或VR_GetGenericInterface 请求的接口不存在，是使用的SDK版本比安装的runtime版本更新吗？

HmdError_Init_InvalidInterface (106) - 错误码当前没有被使用 
HmdError_Init_UserConfigDirectoryInvalid (107) - 路径注册表中的配置目录不可写
HmdError_Init_HmdNotFound (108) - HMD没有添加到系统或者HMD没有初始化
HmdError_Init_NotInitialized (109) - 如果VR_GetGenericInterface在VR_Init之前或者在VR_Shutdown之后被调用会返回这个错误 
HmdError_Init_PathRegistryNotFound (110) - VR路径注册文件不能被读。重新安装OpenVR runtime或Steam上的SteamVR应用程序
HmdError_Init_NoConfigPath (111) - 配置路径没有在路径注册表中指定
HmdError_Init_NoLogPath (112) - log路径没有在路径注册表中指定
HmdError_Init_PathRegistryNotWritable (113) - VR路径注册表不可写
HmdError_Driver_Failed (200) - 驱动初始化失败，内部错误
HmdError_Driver_Unknown (201) - 驱动由于位置原因失败，内部错误
HmdError_Driver_HmdUnknown (202) - 驱动未检测到HMD，内部错误
HmdError_Driver_NotLoaded (203) - 在该驱动发出请求前，还没有加载，内部错误
HmdError_Driver_RuntimeOutOfDate (204) - 如果一个驱动自带runtime，那么需要更新它的runtime.
HmdError_Driver_HmdInUse (205) - 另外一个非OpenVR的应用程序正在使用HMD
HmdError_IPC_ServerInitFailed (300) - OpenVR不能够启动vrserver.
HmdError_IPC_ConnectFailed (301) - 多次尝试后，OpenVR不能链接到vrserver或vrcompositor.
HmdError_IPC_SharedStateInitFailed (302) - vrserver或vrcompositor的共享内存不能够打开
HmdError_IPC_CompositorInitFailed (303) - OpenVR不能够启动vrcompositor.
HmdError_IPC_MutexInitFailed (304) - OpenVR不能够创建互斥量来与vrcompositor通信.
HmdError_VendorSpecific_UnableToConnectToOculusRuntime (1000) - 由于未知原因导致到Oculus runtime的连接失败.
HmdError_Steam_SteamInstallationNotFound (2000) - 当前没有使用的错误码.

void vr::VR_Shutdown()

关闭到VR硬件的连接且清除OpenVR API，调用该函数后，由vr::VR_Init返回的vr:IVRSystem指针无效。

接口：

API在vr命名域内被分成了六大主要接口：

1.IVRSystem-主要提供用来处理 显示，畸变，追踪，控制以及事件访问的接口

2.IVRChaperone-主要用来提供访问监护软硬件界限的接口

3.IVRCompositor-允许通过VR混合器来使得一个应用程序渲染3D内容

4.IVROverlay-允许通过VR混合器来使得一个应用程序渲染2D内容

5.IVRRenderModels-允许一个应用程序访问渲染模型

6.IVRScreenshots-允许一个应用程序请求与提交截图

其他函数：

bool vr::VR_IsHmdPresent()

如果系统认为HMD存在系统中，则返回true。该函数比初始化所有的OpenVR API都要快，它仅仅是为了检测HMD。当只想通过HMD展示给用户

一张UI图时，可以使用它。

该函数会在vr::VR_Init()返回NULL情况下返回true。这是一个快速告诉用户现在没有VR硬件的方法，但是还是有一些启动条件必须通过启动系统才能够检测到。

bool vr::VR_IsRuntimeInstalled()

当OpenVR runtime安装在系统上时，返回true。

char *vr::VR_RuntimePath()

返回OpenVR runtime的安装目录

const char *VR_GetVRInitErrorAsSymbol(vr::EVRInitError error)

该函数以字符串的形式返回vr::EVRInitError枚举量的值。它在任何时间都可以被调用，而且与VR系统是否启动无关。

void *VR_GetGenericInterface(const char *pchInterfaceVersion, vr::EVRInitError *peError)

该函数通过OpenVR提供的名字返回一个接口。如果该接口未找到，则它会返回NULL且在peError中回传一个错误码。如果vr::VR_Init()没有成功的被调用，则它会返回NULL。

bool VR_IsInterfaceVersionValid(const char *pchInterfaceVersion)

如果已安装的runtime支持该接口名与版本号时，返回true

参考地址