Google Cardboard入门指南

入门指南

本文档介绍如何使用实验性的 Cardboard SDK for Android 创建您自己的虚拟实境 (VR) 体验。

Android 演示版应用：Treasure Hunt

本教程中的代码示例摘自“Treasure Hunt”Android 演示版应用。
Cardboard 是一个简单的设备，可让智能手机发挥虚拟实境平台的威力。 Cardboard 可与手机配合使用，从而在双眼中呈现三维场景、跟踪响应头部移动以及通过磁铁输入与应用进行交互。 演示版应用“Treasure Hunt”可展示上述功能。 在此游戏中，用户在数字化的世界里四处观望，目的是尽快寻找和搜集物品。 这是一款很基本的游戏，但它展示了 Cardboard 的核心功能。

游戏特性

“Treasure Hunt”一开场是以三维立体文字呈现的游戏说明。 当用户发现物品后，系统会指示用户拉动磁铁。

cube1.png

这就是屏幕上显示的内容。 在 Cardboard 中观看时，这些将以三维场景呈现。
当用户在屏幕中间的中心位置发现立方体时，立方体通过将其颜色更改为黄色进行指示。 用户在立方体变为黄色时拉动磁铁，用户的得分就会增加，随后立方体将移动到新的位置。

cube2.png

此应用使用 OpenGL ES 2.0 显示物品。 它演示了一些基本的功能，如灯光、在空间的移动和着色。 展示了如何使用磁铁作为输入、如何知道用户是否正在看某样东西，以及如何通过为每只眼睛提供不同的视图来呈现图像。
现在，我们看下如何构建演示版应用，并在手机上运行它。

打开并运行 Treasure Hunt

开始前的准备工作

构建演示版应用需要：

• Android Studio 1.0 或更高版本
• Android SDK 19 版本
• 运行 Android 16 (Jelly Bean) 或更高版本的 Android 物理设备

下载示例代码

通过运行以下命令，从cardboard-java
GitHub 存储库克隆演示版应用

git clone https://github.com/googlesamples/cardboard-java.git```
###构建演示版应用
1. 打开 Android Studio，在 **Welcome** 页面上，选择**Import Non-Android Studio Project**。 选择位于您刚下载的示例代码文件根目录处的 **build.gradle** 文件，然后点击 **OK**。
这会在编辑器视图中打开一个名为 CardboardSample 的项目，其包含我们上面介绍的 Treasure Hunt 示例应用。
2. 将手机连接到装置上，点击**Run**，然后**运行“CardboardSample”**以在手机上编译和运行应用。

###代码概览
清单文件
Cardboard SDK 需要以下清单文件标签：
```xml

   
   
   
... 
   
     
     
... 
         
           
           
           
         
       
    
```
请注意以下事项：
```xml
```
 表示设备必须运行 API 级别 16 (Jellybean) 或更高版本。
```xml
```
 表示应用针对的是 API 级别 19 (KitKat)。
```xml
```
 表示设备必须支持 OpenGL ES 2.0 才能运行演示版应用。
```xml
android:screenOrientation="landscape"```
 表示 Activity 要求屏幕方向为"横向。" 您必须将 VR 应用的方向设为横向。 Cardboard SDK 使用的视图、 [CardboardView](https://developers.google.com/cardboard/android/latest/reference/com/google/vrtoolkit/cardboard/CardboardView)
只能在全屏和横向（landscape、reverseLandscape、sensorLandscape）模式下呈现。
另外，推荐使用设置 android:configChanges="orientation|keyboardHidden"，但并不强制。
Cardboard SDK 需要具有 android.permission.NFC 权限才能访问 Cardboard 的 NFC 标签。
```android.permission.READ_EXTERNAL_STORAGE``` 和 ```android.permission.WRITE_EXTERNAL_STORAGE```。Cardboard SDK 需要具有这些权限才能将用户的手机和他们的 VR 查看器进行配对。
演示版应用需要具有 ```android.permission.VIBRATE``` 权限才能使手机发生震动，以通知用户发生了一些事。
intent-filter，特别是 ```com.google.intent.category.CARDBOARD```，声明此 Activity 与类似Cardboard 的查看器兼容。 [Cardboard 应用](https://play.google.com/store/apps/details?id=com.google.samples.apps.cardboarddemo)使用此类别列出用户手机上安装的兼容应用。

##扩展 CardboardActivity
[CardboardActivity](https://developers.google.com/cardboard/android/latest/reference/com/google/vrtoolkit/cardboard/CardboardActivity) 是对 Cardboard 应用进行编码的起点。 CardboardActivity 是一个基础 Activity，可与 Cardboard 设备轻松集成。 它将事件公开，以便与 Cardboard 进行交互，并处理为 VR 呈现创建 Activity 时通常要求的众多细节。
请注意，CardboardActivity 使用粘滞的沉浸模式，在该模式下，系统 UI 处于隐藏状态，且内容会占用整个屏幕。 这是对 VR 应用的一项要求，原因是 CardboardView 仅在 Activity 处于全屏模式时才会呈现。 有关此功能的更多讨论，请参见[使用沉浸式全屏模式](http://developer.android.com/training/system-ui/immersive.html#sticky)。
演示版应用的 MainActivity 可扩展 [CardboardActivity](https://developers.google.com/cardboard/android/latest/reference/com/google/vrtoolkit/cardboard/CardboardActivity)。 MainActivity 可实现以下界面：
- [CardboardView.StereoRenderer](https://developers.google.com/cardboard/android/latest/reference/com/google/vrtoolkit/cardboard/CardboardView.StereoRenderer)：渲染器界面，将所有立体影像渲染细节分配到视图。 实现者在渲染视图时，采用的方式应与以往一样（使用提供的变换参数）。 所有的立体影像呈现和失真校正细节都是从渲染器提取的，并通过视图在内部管理。

###定义 CardboardView
Android 应用中的所有用户界面元素都是使用视图构建的。 Cardboard SDK for Android 可提供自己的视图[CardboardView](https://developers.google.com/cardboard/android/latest/reference/com/google/vrtoolkit/cardboard/CardboardView)，这是[GLSurfaceView](http://developer.android.com/reference/android/opengl/GLSurfaceView.html)的简单扩展，可用于 VR 呈现。 CardboardView 使内容呈现出立体感。 您可以查看演示版应用如何通过以下方式将 CardboardView
 定义到其 Activity 布局 xml 文件中：
```xml
```
然后，它在主 Activity 类中初始化 CardboardView（以 onCreate() 方法）：
```java
**
  * Sets the view to our CardboardView and initializes the transformation matrices we will use 
  * to render our scene. 
  * @param savedInstanceState 
  */@Override
  public void onCreate(Bundle savedInstanceState) {
      super.onCreate(savedInstanceState); 
      setContentView(R.layout.common_ui); 
      CardboardView cardboardView = (CardboardView) findViewById(R.id.cardboard_view); 
      // Associate a CardboardView.StereoRenderer with cardboardView.
      cardboardView.setRenderer(this); 
      // Associate the cardboardView with this activity. 
      setCardboardView(cardboardView); 
      // Initialize other objects here
      ....
  }```
###呈现视图
在获得 CardboardView 后，将其与渲染器关联，然后将 CardboardView 与 Activity 进行关联。 Cardboard 支持两类渲染器，但入门的最快方式是使用 CardboardView.StereoRenderer，这是演示版本应用使用的内容。
CardboardView.StereoRenderer
 包括以下两个关键方法：
- [onNewFrame()](https://developers.google.com/cardboard/android/latest/reference/com/google/vrtoolkit/cardboard/CardboardView.StereoRenderer#onNewFrame(com.google.vrtoolkit.cardboard.HeadTransform))，应用每次进行渲染时调用。
- [onDrawEye()](https://developers.google.com/cardboard/android/latest/reference/com/google/vrtoolkit/cardboard/CardboardView.StereoRenderer#onDrawEye(com.google.vrtoolkit.cardboard.Eye))，针对眼睛参数不同的每只眼睛进行调用。

实现这些的方法与针对 OpenGL 应用的普遍做法相似。 将在后面的部分中详细阐述这些方法。
###实现 onNewFrame
在呈现到人眼之前，使用 onNewFrame() 方法对呈现逻辑进行编码。任何不属于单个视图特有的按帧操作都应在此处进行。此处非常适合更新您的模型。在此代码段中，变量 mHeadView 包含头部的位置。 需要保存此值以便日后使用（用于了解用户是否正在寻宝）：
```java
/** 
  * Prepares OpenGL ES before we draw a frame. 
  * @param headTransform The head transformation in the new frame. 
*/
@Override
public void onNewFrame(HeadTransform headTransform) {
  ... 
  headTransform.getHeadView(mHeadView, 0);
  ...
}```
###实现 onDrawEye
实现 onDrawEye() 以执行每只眼睛的配置。
这是呈现代码的重要部分，与构建常见的 OpenGL ES2 应用非常相似。 以下代码段显示如何获取视图变换矩阵，也称为透视变换矩阵。 您必须确保低延时呈现。 Eye 对象包含眼睛的变换和投影矩阵。 以下是事件的顺序：
- 宝物进入眼睛的空间。
- 应用投影矩阵。 这可以提供为指定的眼睛呈现的场景。
- Cardboard SDK 自动应用失真，以呈现最终的场景。

```java
/** 
* Draws a frame for an eye. 
*
* @param eye The eye to render. Includes all required transformations. 
*/
@Override
public void onDrawEye(Eye eye) {
  GLES20.glClear(GLES20.GL_COLOR_BUFFER_BIT | GLES20.GL_DEPTH_BUFFER_BIT);
  ... 
  // Apply the eye transformation to the camera. 
  Matrix.multiplyMM(mView, 0, eye.getEyeView(), 0, mCamera, 0); 
  // Set the position of the light 
  Matrix.multiplyMV(mLightPosInEyeSpace, 0, mView, 0, LIGHT_POS_IN_WORLD_SPACE, 0); 
  // Build the ModelView and ModelViewProjection matrices 
  // for calculating cube position and light. 
  float[] perspective = eye.getPerspective(Z_NEAR, Z_FAR); 
  Matrix.multiplyMM(mModelView, 0, mView, 0, mModelCube, 0);
  Matrix.multiplyMM(mModelViewProjection, 0, perspective, 0, mModelView, 0); 
  drawCube(); 
  // Draw rest of the scene
  ...
}```
###处理输入
Cardboard 观片器包含一个使用磁铁的按钮。 推动磁铁时，磁场会发生变化，而手机的磁力计可以检测到这种变化。 因此，Cardboard SDK 可以为您检测到这些磁铁事件。
若要提供用户拉动磁铁时的自定义行为，请在应用的 Activity 中重写CardboardActivity.onCardboardTrigger()。 在 treasure hunt 应用中，如果您发现了宝物并拉动磁铁，您就可以留下宝物：
```java
/** 
  * Increment the score, hide the object, and give feedback if the user pulls the magnet while 
  * looking at the object. Otherwise, remind the user what to do. 
  */@Override
  public void onCardboardTrigger() {
    if (isLookingAtObject()) { 
      mScore++; 
      mOverlayView.show3DToast("Found it! Look around for another one.\nScore = " + mScore);
      ... 
    } else { 
      mOverlayView.show3DToast("Look around to find the object!");
    } 
    // Always give user feedback 
    mVibrator.vibrate(50);
  }```
##开始创建您自己的项目
现在，您对 Cardboard SDK for Android 有了更多的了解，可以创建您自己的应用了。
无论是从头开始创建一个新项目还是使用现有项目，均应按照以下步骤操作：
首先，从示例的 **libs** 文件夹（或 [从此处进行下载](https://developers.google.com/cardboard/android/download)）采集所有 jar 文件，并将其复制到项目的 **app/libs** 文件夹。
然后，确保项目的 **app/build.gradle** 文件中存在下列行：
```gradle
dependencies { 
... 
  compile fileTree(dir: 'libs', include: ['*.jar']) 
}```
现在，您可以使用 Cardboard SDK for Android 了！