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 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. 43 * - Low-persistence display - Display persistence settings must be set as low as 44 * possible while still maintaining a reasonable brightness. For a typical 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. 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, 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). 73 * 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. 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 85 * vr_module as users of this structure may cast a hw_module_t to a 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 * 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. 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 */ 116