include/hardware/vr.h

   1 /*
   2  * Copyright (C) 2016 The Android Open Source Project
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *      http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #ifndef ANDROID_INCLUDE_HARDWARE_VR_H
  18 #define ANDROID_INCLUDE_HARDWARE_VR_H
  19
  20 #include <stdbool.h>
  21 #include <sys/cdefs.h>
  22 #include <hardware/hardware.h>
  23
  24 __BEGIN_DECLS
  25
  26 #define VR_HARDWARE_MODULE_ID "vr"
  27
  28 #define VR_MODULE_API_VERSION_1_0 HARDWARE_MODULE_API_VERSION(1, 0)
  29
  30 /**
  31  * Implement this HAL to receive callbacks when a virtual reality (VR)
  32  * application is being used.  VR applications characteristically have a number
  33  * of special display and performance requirements, including:
  34  * - Low sensor latency - Total end-to-end latency from the IMU, accelerometer,
  35  *   and gyro to an application-visible callback must be extremely low (<5ms
  36  *   typically).  This is required for HIFI sensor support.
  37  * - Low display latency - Total end-to-end latency from the GPU draw calls to
  38  *   the actual display update must be as low as possible.  This is typically
  39  *   achieved by using SurfaceFlinger in a single-buffered mode, and assuring
  40  *   that draw calls are synchronized with the display scanout correctly.  Any
  41  *   GPU settings required to allow consistent performance of this operation
  42  *   are required, including the EGL extensions: EGL_IMG_context_priority, and
  43  *   EGL_XXX_set_render_buffer_mode.
  44  * - Low-persistence display - Display persistence settings must be set as low as
  45  *   possible while still maintaining a reasonable brightness.  For a typical
  46  *   display running at 60Hz, pixels should be illuminated for <4ms to be
  47  *   considered low-persistence (<2ms is desirable).  This avoids ghosting
  48  *   during movements in a VR setting.
  49  * - Consistent performance of the GPU and CPU - When given a mixed GPU/CPU
  50  *   workload for a VR application with bursts of work at regular intervals
  51  *   several times a frame.  CPU scheduling should ensure that the application
  52  *   render thread is run consistently within 1ms of when required for the
  53  *   draw window, and an appropriate clockrate is maintained to ensure the
  54  *   workload finishes within the time alloted to the draw window.  Likewise,
  55  *   GPU scheduling should ensure that work from the application render thread
  56  *   is given priority over other GPU work, and that a high enough clockrate can
  57  *   be maintained to ensure that this completes within the draw window.  CTS
  58  *   tests with example VR workloads will be available to assess performance
  59  *   tuning.
  60  *
  61  * Vendors implementing this HAL are expected to use set_vr_mode as a hint to
  62  * enable VR-specific performance tuning, and to turn on any device features
  63  * optimal for VR display modes (or do nothing if none are available). Devices
  64  * that advertise FEATURE_VR_MODE_HIGH_PERFORMANCE are must pass the additional
  65  * CTS performance tests required for this feature and follow the additional
  66  * guidelines for hardware implementation for "VR Ready" devices.
  67  *
  68  * No methods in this HAL will be called concurrently from the Android framework.
  69  */
  70 typedef struct vr_module {
  71     /**
  72      * Common methods of the  module.  This *must* be the first member of
  73      * vr_module as users of * this structure will cast a hw_module_t to a
  74      * vr_module pointer in contexts where it's known that the hw_module_t
  75      * references a vr_module.
  76      */
  77     struct hw_module_t common;
  78
  79     /**
  80      * Convenience method for the HAL implementation to set up any state needed
  81      * at runtime startup.  This is called once from the VrManagerService during
  82      * its boot phase.  No methods from this HAL will be called before init.
  83      */
  84     void (*init)(struct vr_module *module);
  85
  86     /**
  87      * Set the VR mode state.  Possible states of the enabled parameter are:
  88      * false - VR mode is disabled, turn off all VR-specific settings.
  89      * true - VR mode is enabled, turn on all VR-specific settings.
  90      *
  91      * This is called from the VrManagerService whenever the application(s)
  92      * currently in use enters or leaves VR mode. This will typically occur
  93      * when the user switches or from an application that has indicated to
  94      * system_server that it should run in VR mode.
  95      */
  96     void (*set_vr_mode)(struct vr_module *module, bool enabled);
  97
  98     /* Reserved for future use. Must be NULL. */
  99     void* reserved[8 - 2];
 100 } vr_module_t;
 101
 102 __END_DECLS
 103
 104 #endif /* ANDROID_INCLUDE_HARDWARE_VR_H */