OpenVR之IVROverlay

IVROverlay允许应用程序通过VR混合器渲染2D内容。

vr::IVROverlay接口提供在3D场景中绘制2D图像的方法，与特定应用程序运行无关。所提供的函数运行应用程序来控制每个overlay的程序方式，包含的内容，以及接收的事件。

最常用的类型就是Dashboard overlay，它添加一个选项卡到VR控制面板，用户选择一个活动选项卡同时通知应用程序。在控制面板上来自用户的指向一个追踪控制器的模拟鼠标通过事件形式发送到应用程序。helloworldoverlay实例参考。

每个overlay由一个句柄VROverlayHandle_t表示。该句柄用来设置属性，接收事件，以及渲染到overlay，有一些环境overlay不为人所知或者无效。若是如此，则该句柄相当于k_ulOverlayHandleInvalid。

接口函数：

vr::IVROverlay接口提供以下函数：

·Overlay管理：

FindOverlay:

VROverlayError FindOverlay( const char *pchOverlayKey, VROverlayHandle_t * pOverlayHandle )

通过指定的key值找到一个已经存在的overlay。若不能找到该overlay，则将pOverlayHandle设为k_ulOverlayHandleInvalid同时返回VROverlayError_UnknownOverlay。

const char *pchOverlayKey - 要搜索的overlay

VROverlayHandle_t *pOverlayHandle - 若找到则用来返回overlay句柄

CreateOverlay:

VROverlayError CreateOverlay( const char *pchOverlayKey, const char *pchOverlayFriendlyName, VROverlayHandle_t * pOverlayHandle )

创建一个命名的overlay。所有的overlay开始隐藏且带默认设置。

const char *pchOverlayKey - 创建overlay的key值。key值必须是全局唯一的且不能比k_unVROverlayMaxKeyLength所指定的长度更长（长度包含终止符null）。

const char *pchOverlayFriendlyName - overlay友好的用户可见的名字。如果合适应该在当前系统语言内以UTF-8格式提供名字。该名字不能比k_unVROverlayMaxNameLength更长（长度包含终止符null）。

VROverlayHandle_t *pOverlayHandle - 接收新的被创建的overlay句柄。

描述：

创建一个非VR的控制面板overlay。若要创建一个在VR控制面板中显示的overlay，可参考一下IVROverlay::CreateDashboardOverlay

DestroyOverlay:

VROverlayError DestroyOverlay( VROverlayHandle_t ulOverlayHandle )

销毁指定的overlay。当一个应用程序调用VR_Shutdown后，由应用程序创建的所有overlay都会自动销毁。应用程序只能够销毁在同一个进程内创建的overlay。

VROverlayHandle_t ulOverlayHandle - 要销毁的overlay句柄

SetHighQualityOverlay:

VROverlayError SetHighQualityOverlay( VROverlayHandle_t ulOverlayHandle )

指定特定overlay使用高质量渲染通道。

VROverlayHandle_t ulOverlayHandle

描述：

指定某个overlay使用高质量渲染通道。该overlay会在畸变阶段被混合，这会导致它被绘制在其他任何界面之上，但是在一个更高质量时由于不是首先光栅化进每只眼睛的渲染纹理内而是直接对源纹理采样。因此，在任何给定时间内只支持其中之一。对overlay来说期望占有用户的大多数视野是最有用的（比如，视频流）。

Note:VR控制面板overlay可能不使用高质量通道

GetHighQualityOverlay:

VROverlayHandle_t GetHighQualityOverlay()

返回当前使用单个高质量overlay渲染通道的正在被渲染的overlay句柄，否则返回k_ulOverlayHandleInvalid。

GetOverlayKey:

uint32_t GetOverlayKey( VROverlayHandle_t ulOverlayHandle, VR_OUT_STRING() char *pchValue, uint32_t unBufferSize, VROverlayError *pError = 0L )

从指定的overlay获取字符串key

VROverlayHandle_t ulOverlayHandle - 要获取key的overlay的句柄

char *pchValue - 应用程序提供的用于放入key值的缓冲

uint32_t unBufferSize - 提供的缓冲尺寸。k_unVROverlayMaxKeyLength长度足够满足该字符串长度。

VROverlayError *pError - 包含该请求的结果代码

描述：

使用overlay的字符串key填充提供的缓冲。返回保存key的缓冲大小，包含结束符null。k_unVROverlayMaxKeyLength足够满足字符串大小。
GetOverlayName:

uint32_t GetOverlayName( VROverlayHandle_t ulOverlayHandle, char *pchValue, uint32_t unBufferSize, VROverlayError *pError = 0L )

从指定的overlay获取字符串名：

VROverlayHandle_t ulOverlayHandle - 要获取名字的overlay句柄

char *pchValue - 要放入名字的缓冲

uint32_t unBufferSize - 提供的缓冲的尺寸。k_unVROverlayMaxNameLength长度足够满足字符串长度

VROverlayError *pError - 包含该请求的结果代码

描述：

使用overlay的字符串名字填充提供的缓冲。返回要存储名字的缓冲大小，包含结束符null。k_unVROverlayMaxNameLength长度足够满足字符串长度。

GetOverlayImageData:

VROverlayError GetOverlayImageData( VROverlayHandle_t ulOverlayHandle, void *pvBuffer, uint32_t unBufferSize, uint32_t *punWidth, uint32_t *punHeight )

从overlay获取原始图像数据：

VROverlayHandle_t ulOverlayHandle - 要获取图像数据的overlay

void *pvBuffer - 放入获取到的图像数据的缓冲

uint32_t unBufferSize - 缓冲的字节数大小

uint32_t *punWidth - overlay图像的宽度像素大小

uint32_t *punHeight - over图像的高度像素大小

描述：

从overlay获取raw图像数据，overlay图像数据总是以RGBA数据格式返回，每个像素占4字节。若缓冲不够大，则宽度和高度会被设置同时返回VROverlayError_ArrayTooSmall。

GetOverlayErrorNameFromEnum:

const char *GetOverlayErrorNameFromEnum( VROverlayError error )

返回对应指定overlay错误的字符串。该字符串为所有有效错误代码的枚举值的名字。

VROverlayError error - 要获取的名字对应的错误代码。

Overlay渲染：

SetOverlayFlag:

VROverlayError SetOverlayFlag( VROverlayHandle_t ulOverlayHandle, VROverlayFlags eOverlayFlag, bool bEnabled )

VROverlayError GetOverlayFlag( VROverlayHandle_t ulOverlayHandle, VROverlayFlags eOverlayFlag, bool *pbEnabled )

为某个overlay设置或获取指定flag。

VROverlayHandle_t ulOverlayHandle - 要获取/设置flag的overlay的句柄

VROverlayFlags eOverlayFlag - 要获取或设置的flag

bool bEnabled - 要设置的flag值

bool *pbEnabled - 接收flag值

SetOverlayColor:

VROverlayError SetOverlayColor( VROverlayHandle_t ulOverlayHandle, float fRed, float fGreen, float fBlue )

VROverlayError GetOverlayColor( VROverlayHandle_t ulOverlayHandle, float *pfRed, float *pfGreen, float *pfBlue )

设置/获取overlay四边形的色彩。每个通道使用0.0到1.0的值。

VROverlayHandle_t ulOverlayHandle - 要和颜色交互的overlay句柄

float fRed - 要设置的介于0到1之间的Red值

float fBlue - 要设置的介于0到1之间的Blue值

float fGreen - 要设置的介于0到1之间的Green值

float *pfRed - 接收介于0到1之间的红色值

float *pfBlue - 接收介于0到1之间的蓝色值

float *pfGreen - 接收介于0到1之间的绿色值

SetOverlayAlpha:

VROverlayError SetOverlayAlpha( VROverlayHandle_t ulOverlayHandle, float fAlpha )

VROverlayError GetOverlayAlpha( VROverlayHandle_t ulOverlayHandle, float *pfAlpha )

设置/接收overlay四边的alpha值。使用从百分之1.0到百分之100不透明并且0.0为透明。

VROverlayHandle_t ulOverlayHandle - 要获取/设置alpha的overlay值

float fAlpha - 要设置的alpha值。这是一个介于0（完全透明）和1（完全不透明）之间的值。

float *pfAlpha - 接收overlay当前的alpha值。

SetOverlayWidthInMeters:

VROverlayError SetOverlayWidthInMeters( VROverlayHandle_t ulOverlayHandle, float fWidthInMeters )

VROverlayError GetOverlayWidthInMeters( VROverlayHandle_t ulOverlayHandle, float *pfWidthInMeters )

设置/获取overlay四边的米数

VROverlayHandle_t ulOverlayHandle - 要设置/获取宽度的overlay句柄

float fWidthInMeters - overlay宽度的米数

float *pfWidthInMeters - 接收overlay宽度的米数

描述：

设置/获取overlay四边宽度的米数。默认overlay渲染到四边形为1米宽。

overlay以其底层的纹理和纹理边界的宽高比渲染。高度为宽度的因子构成宽高比，一个overlay为1.6米宽且有一个高位0.9米的1920x1080的纹理

SetOverlayAutoCurveDistanceRangeInMeters:

VROverlayError SetOverlayAutoCurveDistanceRangeInMeters( VROverlayHandle_t ulOverlayHandle, float fMinDistanceInMeters, float fMaxDistanceInMeters )

VROverlayError GetOverlayAutoCurveDistanceRangeInMeters( VROverlayHandle_t ulOverlayHandle, float *pfMinDistanceInMeters, float *pfMaxDistanceInMeters )

设置/获取距离范围的米数用于弯曲视野周围的overlay。只在高质量overlay中被使用。

VROverlayHandle_t ulOverlayHandle - 要设置/获取范围的overlay句柄

float fMinDistanceInMeters - overlay最弯曲的距离值

float fMaxDistanceInMeters - overlay最不弯曲的距离值

float *pfMinDistanceInMeters - 接收overlay最弯曲的距离值

float *pfMaxDistanceInMeters - 接收overlay最不完全的距离值

描述：

只针对高质量弯曲overlay，从overlay设置距离范围米数值用于自动完全视野周围的界面。Min为当界面最弯曲时的距离，Max为最不弯曲时的距离。

SetOverlayTextureBounds:

VROverlayError SetOverlayTextureBounds( VROverlayHandle_t ulOverlayHandle, const VRTextureBounds_t *pOverlayTextureBounds )

VROverlayError GetOverlayTextureBounds( VROverlayHandle_t ulOverlayHandle, VRTextureBounds_t *pOverlayTextureBounds )

设置/获取overlay要用的纹理部分：

VROverlayHandle_t ulOverlayHandle - 要获取/设置纹理范围的overlay句柄

VRTextureBounds_t *pOverlayTextureBounds - 要获取/设置的范围

设置overlay要用的纹理部分。UV最小为左上角，UV最大为右下角。默认overlay使用整个纹理。

GetOverlayTransformType:

VROverlayError GetOverlayTransformType( VROverlayHandle_t ulOverlayHandle, VROverlayTransformType *peTransformType )

获取overlay的变换类型。

VROverlayHandle_t ulOverlayHandle - 要获取变换类型的overlay句柄
VROverlayTransformType *peTransformType - 获取的变换类型

描述：

变换类型下面之一：

VROverlayTransform_Absolute - Overlay位于空间中某个绝对位置

VROverlayTransform_TrackedDeviceRelative - Overlay相关联的追踪设备

VROverlayTransform_SystemOverlay - Overlay为控制面板部分且与控制面板的其余分布一同被定位

SetOverlayTransformAbsolute:

VROverlayError SetOverlayTransformAbsolute( VROverlayHandle_t ulOverlayHandle, TrackingUniverseOrigin eTrackingOrigin, const HmdMatrix34_t *pmatTrackingOriginToOverlayTransform )

VROverlayError GetOverlayTransformAbsolute( VROverlayHandle_t ulOverlayHandle, TrackingUniverseOrigin *peTrackingOrigin, HmdMatrix34_t *pmatTrackingOriginToOverlayTransform )

设置overlay为一个绝对变换或获取当前绝对变换。

VROverlayHandle_t ulOverlayHandle - 要设置/获取绝对变化的overlay句柄

TrackingUniverseOrigin eTrackingOrigin - 与要设置变换相关联的追踪原点

TrackingUnigerseOrigin *peTrackingOrigin - 获取与变换相关联的追踪原点
HmdMatrix34_t *pmatTrackingOriginToOverlayTransform - 与特定追踪原点相关的变换

描述：

设置overlay为一个绝对变换或获取当前绝对变换。若overlay变换不是VROverlayTransform_Absolute, Get会返回一个错误。

SetOverlayTransformTrackedDeviceRelative:

VROverlayError SetOverlayTransformTrackedDeviceRelative( VROverlayHandle_t ulOverlayHandle, TrackedDeviceIndex_t unTrackedDevice, const HmdMatrix34_t *pmatTrackedDeviceToOverlayTransform )

VROverlayError GetOverlayTransformTrackedDeviceRelative( VROverlayHandle_t ulOverlayHandle, TrackedDeviceIndex_t *punTrackedDevice, HmdMatrix34_t *pmatTrackedDeviceToOverlayTransform )

设置与特定追踪设备相关联的变换或获取已经存在的追踪设备相关联的变换。

VROverlayHandle_t ulOverlayHandle - 要交互的overlay句柄

TrackedDeviceIndex_t unTrackedDevice - 要移动的overlay相关联的追踪设备

TrackedDeviceIndex_t *punTrackedDevice - 接收与overlay移动相关的追踪设备索引

HmdMatrix34_t *pmatTrackedDeviceToOverlayTransform - 与追踪设备相关的overlay的变换

描述：

使用这些函数配置一个overlay如一个追踪设备一样四处移动。当追踪设备移动时，overlay更深层次的变换更新会自动发生。

若变换类型不是VROverlayTransform_TrackedDeviceRelative，则Get会返回错误

ShowOverlay:

VROverlayError ShowOverlay( VROverlayHandle_t ulOverlayHandle )

VROverlayError HideOverlay( VROverlayHandle_t ulOverlayHandle )

显示或隐藏overlay。对VR控制面板overlay来说，只有控制面板管理器才允许调用这些函数。

VROverlayHandle_t ulOverlayHandle - 要显示或隐藏的overlay的句柄

IsOverlayVIsible:

bool IsOverlayVisible( VROverlayHandle_t ulOverlayHandle )

若overlay为潜在可见的，则返回true。若overlay在用户后面或者被另外的overlay朦胧覆盖，则该方法仍然返回true。

VROverlayHandle_t ulOverlayHandle - 要测试可见性的overlay句柄

·Overlay输入：

PollNextOverlayEvent:

bool PollNextOverlayEvent( VROverlayHandle_t ulOverlayHandle, VREvent_t *pEvent )

若存在事件，则返回true同时用overlay上的事件队列中的下一个事件填充。若在方法中午事件，则返回false。

VROverlayHandle_t ulOverlayHanlde - 要获取事件的overlay句柄

VREvent_t *pEvent - 接收队列中的下一个事件

SetOverlayInputMethod:

VROverlayError SetOverlayInputMethod( VROverlayHandle_t ulOverlayHandle, VROverlayInputMethod eInputMethod )

VROverlayError GetOverlayInputMethod( VROverlayHandle_t ulOverlayHandle, VROverlayInputMethod *peInputMethod )

为指定的overlay获取或设置输入配置。

VROverlayHandle_t ulOverlayHandle - 要获取/设置输入配置的overlay句柄

VROverlayInputMethod eInputMethod - 要设置的输入方法

VROverlayInputMethod *peInputMethod - 接收overlay的输入方法

描述：

控制面板overlay始终为VROverlayInputMethod_Mouse。其他overlay默认为VROverlayInputMethod_None，但是通过这个方法可设置为使用自动的鼠标交互。

SetOverlayMouseScale:

VROverlayError SetOverlayMouseScale( VROverlayHandle_t ulOverlayHandle, const HmdVector2_t *pvecMouseScale )

VROverlayError GetOverlayMouseScale( VROverlayHandle_t ulOverlayHandle, HmdVector2_t *pvecMouseScale )

设置/获取用于鼠标事件的鼠标比例因子。实际纹理可能是一个不同的尺寸，但是一般这是潜在UI像素尺寸。

VROverlayHandle_t ulOverlayHandle - 要获取/设置鼠标比例的overlay句柄

HmdVector2_t *pvecMouseScale - 要获取/设置的鼠标比例

ComputeOverlayIntersection:

bool ComputeOverlayIntersection( VROverlayHandle_t ulOverlayHandle, const VROverlayIntersectionParams_t *pParams, VROverlayIntersectionResults_t *pResults )

计算射线与overlay交叉点的overlay空间像素坐标系。若无交叉，则返回false。

VROverlayHandle_t ulOverlayHandle - 要测试交叉的overlay句柄

const VROverlayIntersectionParams_t *pParams - 要测试交叉的射线

VROverlayIntersectionResults_t *pResults - 返回的详细结果

描述：

使用三个参数块来测试交叉：

struct VROverlayIntersectionParams_t
{
	HmdVector3_t vSource;
	HmdVector3_t vDirection;
	TrackingUniverseOrigin eOrigin;
};

struct VROverlayIntersectionResults_t
{
	HmdVector3_t vPoint;
	HmdVector3_t vNormal;
	HmdVector2_t vUVs;
	float fDistance;
};

HandleControllerOverlayInteractionAsMouse:

bool HandleControllerOverlayInteractionAsMouse( VROverlayHandle_t ulOverlayHandle, TrackedDeviceIndex_t unControllerDeviceIndex )

处理指定控制器的鼠标输入，就像指向overlay的鼠标一样。

VROverlayHandle_t ulOverlayHandle - 要测试的控制器相关的overlay句柄

TrackedDeviceIndex_t unControllerDeviceIndex - 要测试的控制器的设备索引

描述：

处理特定控制器的鼠标输入，就像鼠标指向overlay一样。控制器被当做一个类似在-z轴上的激光。激光指向与overlay相交点为鼠标位置，扳机键为左鼠标，且定位面板为右鼠标。

若控制器指向overlay同时生产事件，则返回true。

设置Overlay纹理：

SetOverlayTexture:

VROverlayError SetOverlayTexture( VROverlayHandle_t ulOverlayHandle, GraphicsAPIConvention eTextureType, void* pTexture )

为overlay绘制纹理：

VROverlayHandle_t ulOverlayHandle - 要设置纹理的overlay句柄

GraphicsAPIConvention eTextureType - 根据纹理指针指向来决定是为API_DirectX或API_OpenGL

void* pTexture - 纹理指针，参考下面的描述

描述：

为overlay设置一个已经存在的应用程序创建的图像资源作为纹理。pTexture类型依赖于eTextureType参数：

API_DirectX - pTexture必须为下面的指针之一：

ID3D10Texture*

ID3D11Texture*

API_OpenGL - pTexture必须为纹理的GLuint

ClearOverlayTexture:

VROverlayError ClearOverlayTexture( VROverlayHandle_t ulOverlayHandle )

使用这个函数告诉overlay系统为该overlay释放纹理系列。

VROverlayHandle_t ulOverlayHandle - 要清除纹理的overlay句柄

SetOverlayRaw:

VROverlayError SetOverlayRaw( VROverlayHandle_t ulOverlayHandle, void *pvBuffer, uint32_t unWidth, uint32_t unHeight, uint32_t unDepth )

在系统内存中从raw字节开始设置overlay的纹理

VROverlayHandle_t ulOverlayHandle - 要设置纹理的overlay句柄

void *pvBuffer - 指向纹理数据的指针

uint32_t unWidth - 纹理的像素宽度

uint32_t unHeight - 纹理的像素高度

uint32_t unDepth - 纹理的像素深度

描述：

从raw字节开始在系统内存内设置overlay的纹理。若可能的话，应当尽可能的使用SetOverlayTexture而不是SetOverlayRaw。

SetOverlayRaw：

VROverlayError SetOverlayRaw( VROverlayHandle_t ulOverlayHandle, void *pvBuffer, uint32_t unWidth, uint32_t unHeight, uint32_t unDepth )

在系统内存内从raw字节开始设置overlay的纹理

VROverlayHandle_t ulOverlayHandle - 要设置纹理的overlay句柄

void *pvBuffer - 指向纹理数据的指针

uint32_t unWidth - 纹理的像素宽度

uint32_t unHeight - 纹理的像素高度

uint32_t unDepth - 纹理的像素深度

描述：

在系统内存内从raw字节开始设置overlay的纹理，若可能，尽可能使用SetOverlayTexture而不要使用SetOverlayRaw。

SetOverlayFromFile:

VROverlayError SetOverlayFromFile( VROverlayHandle_t ulOverlayHandle, const char *pchFilePath )

通过图片文件设置overlay图片。

VROverlayHandle_t ulOverlayHandle - 要设置纹理的overlay句柄

const char *pchFilePath - 图片文件路径。若通过的是相对路径，则假设是相对于OpenVR运行时的资源目录

描述：

加载指定文件并设置纹理作为overlay的内容，纹理可上达1920x1080i大小。支持24或32位的PNG，JPG和TGA文件。

控制面板Overlay:

CreateDashboardOverlay:

VROverlayError CreateDashboardOverlay( const char *pchOverlayKey, const char *pchOverlayFriendlyName, VROverlayHandle_t * pMainHandle, VROverlayHandle_t *pThumbnailHandle )

创建一个VR控制面板overlay并返回它的句柄。

const char *pchOverlayKey - 为新overlay使用的key。必须独一无二的

const char *pchOverlayFriendlyName - VR控制面板内的overlay选项的名字

VROverlayHandle_t *pMainHandle - 接收主overlay视图的句柄

VROverlayHandle_t *pThumbnailHandle - 接收图标overlay的句柄

描述：

当用户在控制器上（手柄）点击系统按钮时，创建一个用户可见的overlay。主句柄应该被设置到UI视图。为该overlay将缩略图句柄设置到图标。
可参看实例helloworldoverlay来理解如何使用QT来实现VR控制面板overlay。

IsDashboardVisible:

bool IsDashboardVisible()

若控制面板可见，则返回true。

IsActiveDashboardOverlay:

bool IsActiveDashboardOverlay( VROverlayHandle_t ulOverlayHandle )

若dashboard可见则返回true，且指定的overlay为活动系统overlay。

VROverlayHandle_t ulOverlayHandle - 要测试的overlay句柄

SetDashboardOverlaySceneProcess:

VROverlayError SetDashboardOverlaySceneProcess( VROverlayHandle_t ulOverlayHandle, uint32_t unProcessId )

VROverlayError GetDashboardOverlaySceneProcess( VROverlayHandle_t ulOverlayHandle, uint32_t *punProcessId )

设置或获取控制面板overlay，这些overlay只在指定进程ID有场景聚焦时显示。

VROverlayHandle_t ulOverlayHandle - 要设置/获取场景进程的overlay句柄

uint32_t unProcessId - 为该场景进程提供的控制面板overlay

uint32_t *punProcessId - 接收控制面板overlay提供的进程ID

ShowDashboard:

显示指定overlay的VR控制面板。

void ShowDashboard( const char *pchOverlayToShow )

const char *pchOverlayToShow - 要显示的overlay key。若这为NULL或空字符串，该VR控制面板会保持在它最后一次显示时的状态。

参考网址