Cardboard Unity SDK Reference 翻译版

最近正在准备雅思，趁机翻译了Cardboard的文档，这个文档挂在谷歌官网上，不根本看不了，翻了墙这个网页也很不稳定，经常上不去，所以就搬运了过来，不过我英语水平实在有限，这次翻译也是对自己的一次锻炼，有的地方我自己明白但是也很难表述好，还请大神轻喷。

里面有很多奇怪的词汇查不到，都是我自己猜着翻译的，还有的词查到了也不知道是啥，比如“剔除掩膜”啥的…，翻译工作量也很大，都是我自己挤时间翻译的，还请大神们指出翻译的不好的地方，英文版请见我上一篇博客：http://blog.csdn.net/sunmc1204953974/article/details/47157951

Cardboard Unity SDK Reference中文翻译版,水平有限请以英文版为准。

Plugin Reference

Package 内容

Unity插件包包含以下内容：

脚本

·        Cardboard.cs  -本地代码虚拟现实设备的单例模式连接。

·        CardboardEye.cs  -用于立体相机的视角（eye view）/投影

·        CardboardHead.cs  -用于虚拟现实眼镜的头部视图的变换

·        GazeInputModule.cs  -通过目光（注视点）和点击触发控制uGUI元素。

·        Pose3D.cs  -包含一个旋转和平移。

·        RadialUndistortionEffect.cs  -图像效果虚拟现实校正（双屏）。

*注：这里的distortion我理解为利用双屏变换模拟显示，后同。

·        StereoController.cs  -控制非立体显示（全屏显示）还是立体显示（分屏显示）。

*注：这里的mono/ stereo我理解为全屏显示（VR模式关）与分屏显示（VR模式开）,后同

编辑器脚本

·        CardboardEditor.cs  - Cardboard对象的自定义参数。

·        StereoControllerEditor.cs  -添加了一个按钮来更新立体双眼摄像头。

Prefabs

·        CardboardMain  -一个可直接替代的主相机对象。

·        CardboardHead  -一个可直接替代的其他摄像机。

·        CardboardAdapter  -将立体渲染添加到现有的摄像头。

Shaders

·        RadialUndistortionEffect  -着色器虚拟现实校正（双屏）。

演示

·        DemoScene  -插件的简单演示。

Legacy

这些特性是为了支持现有项目在老版本的Unity上也可以运行，是为统一版本而设计的。

·        CardboardGUI.cs  -采集OnGUI到一个纹理。

·        CardboardGUIWindow.cs  -在场景中的网格上显示OnGUI纹理。

·        CardboardGUIMouse.cs  -用用户的目光控制鼠标; 绘制鼠标指针。

·        CardboardGUI  Prefab -使得可以很容易的在立体视角中通过OnGUI实现显示和交互。

·        SkyboxMesh.cs  -将一个摄像头的skybox转换为一个运行时的网格纹理。

·        StereoLensFlare.cs  -支持方向的镜头耀斑但是存在一定视差。

·        SkyboxMesh  Shader-不发光的纹理背景。

·        GUIScreen  Shader-具有透明度的不发光纹理覆盖。

脚本

这部分包含单个脚本的特定目的和他们如何一起工作，无论是在使用提供的预制件时（prefab）还是如果您自己添加到自己的场景。

Cardboard.cs

提供了去访问底层虚拟现实设备的方法，这是在本地代码中实现的。应该只在其中一个场景中。如果需要的话，一个实例会在运行时产生，如果你想自定义它的初始属性，你也可以通过编辑器添加一个。

枚举

          enum Eye { Left, Right }

两只眼睛之间的区别（左眼右眼）。

enum Distortion { Distorted, Undistorted }

检索投影和视口（Viewport）属性，确定您是希望通过Cardboard眼镜来观看时所需的图像（Distorted，双屏）或如果没有眼镜的存在时所需的图像（Undistorted，全屏）。（注* 视口（ViewPort）是计算机图形学里面的重要概念之一，是与设备相关的一个矩形区域，坐标单位是与设备相关的，简单理解就是你在显示屏幕里能够看到的显示内容.）

 

属性（Properties）

Cardboard SDK [static, read only]

指向该脚本的单一全局实例。如果不是已经存在的话，该实例是按需创建的。

bool DistortionCorrection [default true]

是否虚拟现实校正由插件进行。如果被禁用，则它是由应用程序执行任何它想执行的虚拟现实校正，如果有的话。

bool VRModeEnabled [default true]

确定场景是非立体显示（全屏显示）还是立体显示（分屏显示）。指定这个字段可以自己控制分屏/全屏

bool TapIsTrigger [default false]

当启用时，Cardboard把一个屏幕点击（screen tap）视为一个触发（trigger pull）进行处理。（注* 感觉这里说的trigger是扣Cardboard侧面的磁铁）

bool EnableAlignmentMarker [default true]

启用或禁用立体视图之间呈现的垂直线，以帮助用户将手机屏幕对准Cardboard眼镜的中线。

bool EnableSettingsButton [default true]

启用或禁用Cardboard的设置按钮。它显示为立体视图之间的空白上的一个齿轮图标。这个设置按钮打开谷歌Cardboard app，允许用户配置他们的个人设置和Cardboard的耳机参数。

float NeckModelScale [0..1, default 1]

原生SDK将使用一个颈部偏移的头部跟踪，从而实现一个更逼真的人的头部位置模型。

该控制确定偏移的比例因子。要关闭颈部模型，将其设置为0，将其全部打开，设置为1。中间值可用于动画从开到关，反之亦然。

bool AutoDriftCorrection [default true]

当启用时，会进行陀螺漂移读数的估计和去除（自动漂移修正）。

bool Triggered [read only]

判断是否触发了Cardboard的触发器。在每次触发后为一个十分精确的完整帧。（注* 感觉这里说的trigger是扣Cardboard侧面的磁铁）

bool Tilted [read only]

判断Cardboard使用者是否呈倾斜在其一侧的状态。在每次倾斜后为一个十分精确的完整帧。一些应用程序把它视为一个“返回”或“退出场景”的动作。

RenderTexture StereoScreen

当虚拟现实模式被启用（VR Mode enable）时，立体相机会自动的并排的渲染在这一目标上。每一帧，其结果是经过虚拟现实校正（分屏）的，然后显示出来。请注意，当VR模式被禁用（VR Mode disable）或不支持虚拟现实校正，此属性将返回null。

该属性通常是通过Cardboard自动初始化的，但如果你想自定义纹理，你可以指派它到你的代码中。

Pose3D HeadPose [read only]

当前帧的头部姿态，将头部跟踪系统作为返回值。

Pose3D EyePose(Cardboard.Eye eye)

指定的眼睛相对于头部的姿态。

Matrix4x4 Projection(Cardboard.Eye eye, Distortion distortion [default Distorted])

当前帧的投影矩阵，用于给定的眼睛。该矩阵是一个分别具有1米和1千米的近端和远端剪裁平面的离轴透视投影。 CardboardEye  脚本负责采用调整这个特殊相机的矩阵。

Rect Viewport(Cardboard.Eye eye, Distortion distortion [default Distorted])

指定眼的摄像机会渲染成屏幕空间的视口（Viewport），在虚拟现实的情况下，这将是左或右半边的stereoscreen渲染纹理。在非虚拟现实的情况下，它指的是屏幕上可以看到实际看到的矩形区域。（注* 视口（ViewPort）是计算机图形学里面的重要概念之一，是与设备相关的一个矩形区域，坐标单位是与设备相关的，简单理解就是你在显示屏幕里能够看到的显示内容.）

Vector2 ComfortableViewingRange [read only, default 1-100000 meters]

在现实世界中，一个可以通过设备舒适地观看一个物体的最小和最大距离。

事件

Action OnTrigger

每当触发（Trigger）发生时发生该事件。如果  TapIsTrigger  被启用，那么当一个屏幕点击（screen tap）发生时也会发生该事件。（注* 感觉这里说Trigger的是扣Cardboard侧面的磁铁）

Action OnTilt

每当使用者呈倾斜在其一侧的状态（Tilt）发生该事件。如果  TapIsTrigger被启用，退出键也会成为需要注意的问题：在Android上，Unity会将后退按钮（BackButton）视为退出键。

方法

void UpdateState()

从手机中读取最新的跟踪数据。这必须在访问任何的姿态信息和矩阵之前调用。

每帧多次调用是允许的：后续调用仅仅产生第一次调用的缓存结果。为了最小化延迟，如果可能的话，应该首先在一帧的稍后进行第一次调用（例如，in LateUpdate）

bool Recenter()

使头部追踪器回到中心位置，使手机的当前方向变为正方向。

void CreateStereoScreen()

创建（或重新创建）StereoScreen纹理并使用合理的默认设置。如果不支持虚拟现实校正则没有效果。

---

CardboardEye.cs

渲染同样的视图作为父类StereoController的一个单摄像头，而不是完整的立体眼睛。视图和投影矩阵被连续不断地从Cardboard对象的  EyeView  和  Projection  属性更新。渲染输出被指向到Cardboard的  StereoScreen   渲染纹理，是在左半或右半取决于所选择的眼睛。

渲染  CardboardEye  相机是由StereoController所控制的，而不是由正常的Unity渲染管线所控制的。因此，  CardboardEye  相机一般都将enable设置为false。

在每个帧中，所有的摄像机设置（例如，剔除掩模，视野，近/远剪裁距离，等等）在父类单相机渲染之前被复制。因此，去设置附属于cardboardeye本身的相机的属性是毫无意义的。

属性（Properties）

Cardboard.Eye eye

确定要渲染的立体眼睛，就是去用哪个  EyeOffset  和  Projection  矩阵并且去渲染到屏幕的哪一半。

LayerMask toggleCullingMask

允许你为这个眼睛打开或关闭特定剔除掩模层。掩模是一个触发器：这个眼睛的剔除掩模首先从父单相机复制，然后在此指定的层被启用。每只眼睛有它自己的触发器掩模。

StereoController Controller [read only]

返回  StereoController  来控制这个眼睛。

CardboardHead Head [read only]

返回最近的祖先  CardboardHead。

---

CardboardHead.cs

将此脚本附加到任何与用户头部运动相匹配的游戏对象上。默认情况下，它连续不断地去更新本地转换到  HeadView  的  Cardboard 对象。一个目标对象可以被指定去为运动提供一个可替换的参考系。

如果你需要从原点偏移相机的话，这个脚本通常会直接连接到一个摄像头对象，或者其父类。另外，它可以作为Camera的子类以及CardboardEye  Camera的父类插入 。如果你已经掌控了逻辑驱动的单摄像机（*注：不知道翻译的对不对，原文：if you already have steering logic driving the mono Camera），并希望让用户的头部运动与此相关则需要这样去操作。需要注意的是在后者的设置中，只有当启用VR模式时，头部跟踪才是是可见的。

在某些情况下，你可能需要CardboardHead的两个实例，指的是两个不同的目标（其中之一可以是父类），为了将执行旋转与执行位置偏离分开。在这种情况下，将使用trackRotation  和  trackPosition  的特性。

属性（Properties）

bool trackRotation [default true]

确定是否将用户的头部转动应用到gameobject 的方向。（*注：如果该属性为false，则转动头部和侧歪头部都无效，无法转动视角）

bool trackPosition [default true]

确定是否将用户的头部偏移应用到gameobject 的位置。（*注：类比上个属性）

Transform target [default null]

用户的头部运动将被应用在该对象的参考系，而不是头部对象的父类。一个良好的使用情况下是基于头部转向。通常情况下，将父对象（换言之即身体或车辆）转向用户正在看的方向，head也会跟随附带着，由此创造了一个正反馈回路。使用一个外部的目标对象作为用户注视方向的一个固定参考点。通常情况下，父类的父类或更高的祖先是一个合适的目标。

bool updateEarly [default false]

确定头部跟踪是应用  LateUpdate（）  还是  Update（） 。默认值是LateUpdate（）  ，以减少等待时间。但是，一些脚本需要使用摄像机的方向来影响游戏的玩法，例如在LateUpdate（）  阶段，使用投射光线或者操纵一辆车 。（*注：不知道casting rays是什么鬼，原文：e.g by casting rays or steering a vehicle, during the LateUpdate() phase.）

由于Unity的原因，这可能会导致令人讨厌的抖动，在 LateUpdate（）  阶段，在一些帧中将会优先更新头部对象，而其他的放在第二位。如果你的游戏出现了这些糟糕的情况，请尝试切换头部对象使用  Update（） 。

Ray Gaze [read only]

在确保变换是最新的之后，返回基于头的位置和直视方向的光线。在场景中使用光线投射（注* Physics.Raycast 光线投射）来确定该用户正在查看的对象。

---

GazeInputModule.cs

此脚本提供统一个Unity的BaseInputModule 类的实现，使得Canvas-based UI元素（uGUI）可以通过注视以及磁铁触发或者触摸屏幕这三种方式来选择和使用。请参阅  指南  中有关使用的详细信息。

GazeInputModule  发出以下事件：  进入，  退出，  向下，  向上，  点击，  选择，  取消选择和  选择更新（UpdateSelected）。但不能发出滚动，拖拽，移动，以及提交和取消事件。

属性（Properties）

bool vrModeOnly [default false]

确定目光（注视点）输入是否是只在VR模式下有用（true），或所有的情况下（false）。如果你打算在非VR模式下使用直接的屏幕触击或其他输入方式时，设置为false。

GameObject cursor [default null]

这是一个可选的对象被作为注视点的光标（raycast intersection）放置，担任3D的鼠标光标。  重要提示：  请务必设置所有的光线发射器都忽略这个对象的所在层。

float clickTime [default 0.1]

在通过进行一次触发，指针按下与弹起之间的一段短时间，是UI元素去转换他们的状态的准许时间。

Vector2 hotspot [default (0.5, 0.5)]

在视口（ViewPort）坐标中，通过该像素投射光线。一般地，中心像素是最佳的，假定一个单视场摄像机被选作Canvas的事件相机。（注* 视口（ViewPort）是计算机图形学里面的重要概念之一，是与设备相关的一个矩形区域，坐标单位是与设备相关的，简单理解就是你在显示屏幕里能够看到的显示内容.）

 

---

Pose3D.cs

封装一个旋转和一个平移。这是一个很方便的类，允许构造和值访问无论是通过Matrix4x4或是四元数 + Vector3的类型。

Vector3 Position

pose的translation组件。

Quaternion Orientation

Pose的rotation组件。

Matrix4x4 Matrix

Pose在Unity游戏对象习惯约定下的Matrix4x4矩阵。（左手系）

Matrix4x4 RightHandedMatrix

Pose在右手坐标系下的矩阵。

---

RadialUndistortionEffect.cs

实现了由本地代码执行的相同的桶形变形。它用于在编辑器里去运行一个场景时，能够显示失真校正的效果，并且在本地代码的失真校正为不可用或禁用时进行返回。（注* 一条直线经过镜头拍摄后，变成弯曲的现象，称为歪曲像差。向对角线往外弯的是「枕状变形」（pincushion），向内弯的是「桶状变形」（Barrel）。一支变焦镜头，通常在广角端呈现桶状变形，而在望远程呈现枕状变形。）

---

StereoController.cs

这个脚本必须被添加到任何一个当APP在VR Mode下时可以渲染立体效果（双屏）的相机。这包括画中画窗口，无论它们的内容是否在立体模式下（双屏）：不管什么情况窗口本身必须成双用于立体显示。

对于每一帧，  StereoController  决定是否经由其绑定的摄像机（单摄像机）进行渲染还是使用其控制的立体的eyes（见  CardboardEye）。您可以通过设置Cardboard.SDK.VRModeEnabled的值来立马控制所有摄像机 。

由于技术原因，在帧的起始部分单摄像头保持启用。它只在渲染在  OnPreCull（）的作用下开始时被禁用，并在该帧的末尾再次被重新启用。这将允许使用第三方使用Camera.main的脚本，例如，即使在VR模式被启用的情况下引用该单摄像机。

在启动脚本时请确保有一个完整的立体显示系统，其中包括两个附加了CardboardEye  脚本的子摄像机，以及一个用于头部追踪的在某个父子层级的CardboardHead  脚本。在必要的情况下该系统被创建， CardboardHead  被连接到控制器本身。子摄像机的设置会从单摄像机克隆或更新。

一个 StereoController  包含另一个StereoController作为一个孩子是被允许的。在这种情况下，一个CardboardEye  由其最近的 StereoController  父级控制。

此脚本的Inspector面板包括一个按钮来更新立体摄像机。这会执行与上述启动相同的动作，但是可以在编辑器（Editor）中运行。如果你想要自定义使用的话就这样来产生立体显示系统。这个功能也可以在编辑器的主菜单中的Component- >Cardboard- >Update Stereo Cameras使用，也可以通过该摄像机组件的右键菜单来使用。

属性（Properties）

bool directRender [default true]

如果您想在立体模式下使用延迟渲染或任何图像效果，关闭该选项。

float stereoMultiplier [0..1, default 1]

调整该立体显示系统中实体视觉的等级。请注意，此参数并不是Head的虚拟尺寸—为此使用一个CardboardHead 对象上的尺寸。相反，它是一个对人眼聚散度的控制，换言之，是立体显示系统的视觉重合程度。如果设置为0，将会独立的将此立体显示系统的立体视觉关闭。

float matchMonoFOV [0..1, default 0]

立体摄像机默认使用Cardboard装置的实际光学视野（actual optical FOV），因为否则将会破坏头部运动和场景运动之间的匹配关系，从而影响到虚拟现实的效果。然而，在某些情况下，比如为了特殊效果或艺术原因，去调整视野也是可取的。但在任何情况下都不要让视野与真正的光学视野有很大出入，否则用户可能会感到不适。

这个值决定了单摄像机的视野的匹配。这是一个分数：0意味着没有匹配，1意味着完全匹配，中间的值是一种折衷。不去匹配100%的原因包括保留一些虚拟现实，以及由于镜头畸变，当手机不是在虚拟现实模式时，视野的边缘是不容易看到的。

这个变量的另一个用途是保存在各种Cardboard模型的光学视场的不同场景组成。在所有的情况下，这个值只允许单摄像头在虚拟现实模式中有一定的控制权，就像它在非虚拟现实模式下一样。

float matchByZoom [0..1, default 0]

确定由立体摄像机的视场匹配单摄像机的视场的方法（假设matchmonofov不是0）。默认是移动立体相机（matchByZoom = 0），与之相反的是做一个简单的摄像机缩放（matchByZoom= 1）。中间值为两种行为的混合。

不建议对典型场景组合使用简单的缩放，因为它会与虚拟现实需要匹配用户的头部运动与相应的场景运动的要求相矛盾。这应该作为特殊效果例如当玩家通过望远镜或其它放大镜（以及因此玩家知道VR是要受到影响）来观看场景，或类似的情况下被保留。

值得注意的是，通过移动眼睛的匹配要求centerofinterest对象是非空的，否则会没有效果。

Transform centerOfInterest [default null]

通过移动眼睛来使立体显示（分屏显示）中的单摄像机视野保持一致需要一个指定的“兴趣中心（center ofinterest）”。无论是一个你在场景中放置的空间中的点（空游戏物体）来作为一种“三维光标”，还是一个玩家有可能被吸引的实际的场景实体都可以作为“兴趣中心”。

由于在单摄像机上，其FOV调节是通过移动眼睛的朝向或远离COI来完成的，以便于在屏幕上看起来有相同大小。如果COI为null，该调节将被禁用。

float radiusOfInterest [default 0]

该  “兴趣中心（center of interest）” 通常指的就是空间中的一个点，就像一个三维光标一样。有时候，你将希望它是一个具有明确的大小的实际物体。将此属性设置为该物体的近似半径会帮助视场匹配代码（FOV-matching code）去补偿物体的视野（*注：原文：object's horizon 不知道翻译的对不对）。

bool checkStereoComfort [default true]

当控制器检查  centerOfInterest  在最近和最远舒适的观看距离（见Cardboard）之间，则为真，否则调节立体效果倍率来弥补。如果 centerOfInterest  具有非零的radiusOfInterest，那么近侧将会被检查。该  centerOfInterest  必须为非空时此设置才能生效。

float screenParallax [0..1, default 0]

对于画中画摄像机不填充整个屏幕的问题，可以设置窗口本身的虚拟深度。值为0意味着零视差，这是相当贴近用户的。值为1表示完全视差，这等于瞳距并且相当于视觉上无限远的窗口。这不影响所述窗口部分（以像素为单位）的实际屏幕大小，只影响立体分屏显示的左右图像。

float stereoPaddingX [0..1, default 0]
float stereoPaddingY [0..1, default 0]

对于画中画摄像机，通过移动窗口来远离VR模式中的边缘使其更容易地看到。HMD光学系统会使屏幕边缘很难看到，所以你可以用该属性来​​保持VR模式或非VR模式下的PIP可见。 X值是沿屏幕两边垫起的部分，以及Y值是用于在屏幕的顶部和底部。

CardboardHead Head [read only]

返回最近的影响该控制器的立体摄像机的  CardboardHead。

CardboardEye[] Eyes [read only]

返回一个由该脚本的实例控制的立体摄像机的数组。请注意，为了更快的访问该数组会有一定的缓存。调用  InvalidateEyes（）  ，可以调用  InvalidateEyes（）  。

RenderTexture StereoScreen [read only]

返回eyes将要进行渲染的目标texture。在存在一个的情况下，这是一个单摄像机的目标texture，否则有其他Cardboard.SDK.StereoScreen。

方法

void InvalidateEyes()

清除缓存的  Eyes 数组。只有你改变其活动的游戏对象有被这个StereoController所控制的  CardboardEye组件时，才能调用这个函数。

编辑器脚本

下面的脚本定制了一些Cardboard组件的inspector面板。

CardboardEditor.cs

一个为Cardboard脚本的属性设计的自定义编辑器。它会出现在一个Cardboard对象的inspector窗口中。其目的是为了改变  Cardboard.SDK  对象的属性。特别是，当游戏在Editor中运行时，可以直接对InCardboard  属性的值进行设置，以便去模拟手机被插入Cardboard或从Cardboard中拿出。

StereoControllerEditor.cs

一个为 StereoController  脚本设计的自定义编辑器 。它存在的意义在于向StereoController的Inspector窗口添加一个更新立体相机的按钮，并将该按钮添加进了相应的主菜单项和摄像机的右键菜单。对这些行为的使用说明在stereocontroller.cs以上部分。

预制（Prefabs）

本节描述了由包所提供的预制件。

CardboardMain

这种预制旨在成为一个正常的Unity摄像头的简易替换品，如主相机，前提是当相机很简单时，即还没有挂满脚本的时候。一个全新的Unity项目是一个使用它的好时机。在把他应用于编辑器时，删除上述相机，并将其用该预制的实例来替换。

这种预制含有一个叫做CardboardMain的顶层对象，并且会有一个Cardboard脚本附着于它用来控制VR模式的设置。在它之下有一个Head对象，会有一个 CardboardHead  附着用于跟踪该用户的头部运动。Head之下还有一个  Main Camera  子对象，附着一个StereoController 脚本。这个摄像机被标记为一个  MainCamera  从而使Unity的属性  Camera.main  发现它。最后，在层级的最底部会有左右立体摄像机。

CardboardHead

这种预制是为了替换场景中那些同样需要头部跟踪的其他摄像机。它有含有一个附着CardboardHead  脚本的叫做Head 的顶层对象。在它之下是一个附有  StereoController  脚本的Camera子对象，然后是左，右立体声摄像机。与 CardboardMain不同，Camera在这个预制种不会被标记为  MainCamera。

CardboardAdapter

这种预制是为你希望保留现有的Camera对象时准备的，通常是因为Camera在很大程度上与游戏逻辑相连并且已经完全符合非虚拟现实游戏的玩法了。把这个预制件作为Camera的孩子，然后执行更新立体相机  （或手动附加  StereoController到Camera）来完成配置。

不像其他的预制件那样，这种预置的设置是将头部跟踪节点放置在主摄像的下面。因此，只有立体摄像机受到用户的头部运动的影响。

一般预制注意事项

每个预制被作为用户自定义化的起点提供。这是一个为您的需要而附加额外脚本的框架。Head节点以下的元素将保持在屏幕上的固定位置，就像个平视显示器一样。Head的同级元素会保持一个固定的位置和相对于全局的方向，从而更像一个驾驶舱仪表板。