Ruben Brunk | 2c84f81 | 2016-01-25 23:45:53 -0800 | [diff] [blame] | 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 | |
Ruben Brunk | 1b80bf0 | 2016-02-11 12:15:33 -0800 | [diff] [blame] | 26 | #define VR_HARDWARE_MODULE_ID "vr" |
Ruben Brunk | 2c84f81 | 2016-01-25 23:45:53 -0800 | [diff] [blame] | 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 |
Ruben Brunk | e0eb33f | 2016-05-02 19:29:57 -0700 | [diff] [blame] | 38 | * the actual display update must be as low as possible. This is achieved by |
| 39 | * using SurfaceFlinger in a single-buffered mode, and assuring that draw calls |
| 40 | * are synchronized with the display scanout correctly. This behavior is |
| 41 | * exposed via an EGL extension to applications. See below for the EGL |
| 42 | * extensions needed for this. |
Ruben Brunk | 2c84f81 | 2016-01-25 23:45:53 -0800 | [diff] [blame] | 43 | * - Low-persistence display - Display persistence settings must be set as low as |
| 44 | * possible while still maintaining a reasonable brightness. For a typical |
Ruben Brunk | e0eb33f | 2016-05-02 19:29:57 -0700 | [diff] [blame] | 45 | * display running at 60Hz, pixels should be illuminated for <=3.5ms to be |
| 46 | * considered low-persistence. This avoids ghosting during movements in a VR |
| 47 | * setting, and should be enabled from the lights.h HAL when |
| 48 | * BRIGHTNESS_MODE_LOW_PERSISTENCE is set. |
Ruben Brunk | 2c84f81 | 2016-01-25 23:45:53 -0800 | [diff] [blame] | 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 |
Ruben Brunk | e0eb33f | 2016-05-02 19:29:57 -0700 | [diff] [blame] | 51 | * several times a frame, the CPU scheduling should ensure that the application |
| 52 | * render thread work is run consistently within 1ms of when scheduled, and |
| 53 | * completed before the end of the draw window. To this end, a single CPU core |
| 54 | * must be reserved for solely for the currently running VR application's render |
| 55 | * thread while in VR mode, and made available in the "top-app" cpuset. |
| 56 | * Likewise, an appropriate CPU, GPU, and bus clockrate must be maintained to |
| 57 | * ensure that the rendering workload finishes within the time allotted to |
| 58 | * render each frame when the POWER_HINT_SUSTAINED_PERFORMANCE flag has been |
| 59 | * set in the power.h HAL while in VR mode when the device is not being |
| 60 | * thermally throttled. |
| 61 | * - Required EGL extensions must be present - Any GPU settings required to allow |
| 62 | * the above capabilities are required, including the EGL extensions: |
| 63 | * EGL_ANDROID_create_native_client_buffer, EGL_ANDROID_front_buffer_auto_refresh, |
| 64 | * EGL_EXT_protected_content, EGL_KHR_mutable_render_buffer, |
| 65 | * EGL_KHR_reusable_sync, and EGL_KHR_wait_sync. |
| 66 | * - Accurate thermal reporting - Accurate thermal temperatures and limits must be |
| 67 | * reported in the thermal.h HAL. Specifically, the current skin temperature |
| 68 | * must accurately be reported for DEVICE_TEMPERATURE_SKIN and the |
| 69 | * vr_throttling_threshold reported for this device must accurately report the |
| 70 | * temperature limit above which the device's thermal governor throttles the |
| 71 | * CPU, GPU, and/or bus clockrates below the minimum necessary for consistent |
| 72 | * performance (see previous bullet point). |
Ruben Brunk | 2c84f81 | 2016-01-25 23:45:53 -0800 | [diff] [blame] | 73 | * |
Ruben Brunk | e0eb33f | 2016-05-02 19:29:57 -0700 | [diff] [blame] | 74 | * In general, vendors implementing this HAL are expected to use set_vr_mode as a |
| 75 | * hint to enable VR-specific performance tuning needed for any of the above |
| 76 | * requirements, and to turn on any device features optimal for VR display |
| 77 | * modes. The set_vr_mode call may simply do nothing if no optimizations are |
| 78 | * available or necessary to meet the above requirements. |
Ruben Brunk | 2c84f81 | 2016-01-25 23:45:53 -0800 | [diff] [blame] | 79 | * |
| 80 | * No methods in this HAL will be called concurrently from the Android framework. |
| 81 | */ |
| 82 | typedef struct vr_module { |
| 83 | /** |
| 84 | * Common methods of the module. This *must* be the first member of |
Ruben Brunk | e0eb33f | 2016-05-02 19:29:57 -0700 | [diff] [blame] | 85 | * vr_module as users of this structure may cast a hw_module_t to a |
Ruben Brunk | 2c84f81 | 2016-01-25 23:45:53 -0800 | [diff] [blame] | 86 | * vr_module pointer in contexts where it's known that the hw_module_t |
| 87 | * references a vr_module. |
| 88 | */ |
| 89 | struct hw_module_t common; |
| 90 | |
| 91 | /** |
| 92 | * Convenience method for the HAL implementation to set up any state needed |
| 93 | * at runtime startup. This is called once from the VrManagerService during |
| 94 | * its boot phase. No methods from this HAL will be called before init. |
| 95 | */ |
| 96 | void (*init)(struct vr_module *module); |
| 97 | |
| 98 | /** |
| 99 | * Set the VR mode state. Possible states of the enabled parameter are: |
| 100 | * false - VR mode is disabled, turn off all VR-specific settings. |
| 101 | * true - VR mode is enabled, turn on all VR-specific settings. |
| 102 | * |
Ruben Brunk | e0eb33f | 2016-05-02 19:29:57 -0700 | [diff] [blame] | 103 | * This is called whenever the the Android system enters or leaves VR mode. |
| 104 | * This will typically occur when the user switches to or from a VR application |
| 105 | * that is doing stereoscopic rendering. |
Ruben Brunk | 2c84f81 | 2016-01-25 23:45:53 -0800 | [diff] [blame] | 106 | */ |
| 107 | void (*set_vr_mode)(struct vr_module *module, bool enabled); |
| 108 | |
| 109 | /* Reserved for future use. Must be NULL. */ |
| 110 | void* reserved[8 - 2]; |
| 111 | } vr_module_t; |
| 112 | |
| 113 | __END_DECLS |
| 114 | |
| 115 | #endif /* ANDROID_INCLUDE_HARDWARE_VR_H */ |