12c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk/* 22c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk * Copyright (C) 2016 The Android Open Source Project 32c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk * 42c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk * Licensed under the Apache License, Version 2.0 (the "License"); 52c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk * you may not use this file except in compliance with the License. 62c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk * You may obtain a copy of the License at 72c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk * 82c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk * http://www.apache.org/licenses/LICENSE-2.0 92c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk * 102c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk * Unless required by applicable law or agreed to in writing, software 112c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk * distributed under the License is distributed on an "AS IS" BASIS, 122c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 132c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk * See the License for the specific language governing permissions and 142c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk * limitations under the License. 152c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk */ 162c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk 172c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk#ifndef ANDROID_INCLUDE_HARDWARE_VR_H 182c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk#define ANDROID_INCLUDE_HARDWARE_VR_H 192c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk 202c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk#include <stdbool.h> 212c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk#include <sys/cdefs.h> 222c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk#include <hardware/hardware.h> 232c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk 242c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk__BEGIN_DECLS 252c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk 261b80bf003aa4e6aca2b088b3842e7deaca7d602dRuben Brunk#define VR_HARDWARE_MODULE_ID "vr" 272c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk 282c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk#define VR_MODULE_API_VERSION_1_0 HARDWARE_MODULE_API_VERSION(1, 0) 292c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk 302c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk/** 312c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk * Implement this HAL to receive callbacks when a virtual reality (VR) 322c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk * application is being used. VR applications characteristically have a number 332c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk * of special display and performance requirements, including: 342c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk * - Low sensor latency - Total end-to-end latency from the IMU, accelerometer, 352c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk * and gyro to an application-visible callback must be extremely low (<5ms 362c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk * typically). This is required for HIFI sensor support. 372c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk * - Low display latency - Total end-to-end latency from the GPU draw calls to 38e0eb33f6d555e925d8bb3bb2d02ead5ccc76114bRuben Brunk * the actual display update must be as low as possible. This is achieved by 39e0eb33f6d555e925d8bb3bb2d02ead5ccc76114bRuben Brunk * using SurfaceFlinger in a single-buffered mode, and assuring that draw calls 40e0eb33f6d555e925d8bb3bb2d02ead5ccc76114bRuben Brunk * are synchronized with the display scanout correctly. This behavior is 41e0eb33f6d555e925d8bb3bb2d02ead5ccc76114bRuben Brunk * exposed via an EGL extension to applications. See below for the EGL 42e0eb33f6d555e925d8bb3bb2d02ead5ccc76114bRuben Brunk * extensions needed for this. 432c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk * - Low-persistence display - Display persistence settings must be set as low as 442c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk * possible while still maintaining a reasonable brightness. For a typical 45e0eb33f6d555e925d8bb3bb2d02ead5ccc76114bRuben Brunk * display running at 60Hz, pixels should be illuminated for <=3.5ms to be 46e0eb33f6d555e925d8bb3bb2d02ead5ccc76114bRuben Brunk * considered low-persistence. This avoids ghosting during movements in a VR 47e0eb33f6d555e925d8bb3bb2d02ead5ccc76114bRuben Brunk * setting, and should be enabled from the lights.h HAL when 48e0eb33f6d555e925d8bb3bb2d02ead5ccc76114bRuben Brunk * BRIGHTNESS_MODE_LOW_PERSISTENCE is set. 492c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk * - Consistent performance of the GPU and CPU - When given a mixed GPU/CPU 502c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk * workload for a VR application with bursts of work at regular intervals 51e0eb33f6d555e925d8bb3bb2d02ead5ccc76114bRuben Brunk * several times a frame, the CPU scheduling should ensure that the application 52e0eb33f6d555e925d8bb3bb2d02ead5ccc76114bRuben Brunk * render thread work is run consistently within 1ms of when scheduled, and 53e0eb33f6d555e925d8bb3bb2d02ead5ccc76114bRuben Brunk * completed before the end of the draw window. To this end, a single CPU core 54e0eb33f6d555e925d8bb3bb2d02ead5ccc76114bRuben Brunk * must be reserved for solely for the currently running VR application's render 55e0eb33f6d555e925d8bb3bb2d02ead5ccc76114bRuben Brunk * thread while in VR mode, and made available in the "top-app" cpuset. 56e0eb33f6d555e925d8bb3bb2d02ead5ccc76114bRuben Brunk * Likewise, an appropriate CPU, GPU, and bus clockrate must be maintained to 57e0eb33f6d555e925d8bb3bb2d02ead5ccc76114bRuben Brunk * ensure that the rendering workload finishes within the time allotted to 58e0eb33f6d555e925d8bb3bb2d02ead5ccc76114bRuben Brunk * render each frame when the POWER_HINT_SUSTAINED_PERFORMANCE flag has been 59e0eb33f6d555e925d8bb3bb2d02ead5ccc76114bRuben Brunk * set in the power.h HAL while in VR mode when the device is not being 60e0eb33f6d555e925d8bb3bb2d02ead5ccc76114bRuben Brunk * thermally throttled. 61e0eb33f6d555e925d8bb3bb2d02ead5ccc76114bRuben Brunk * - Required EGL extensions must be present - Any GPU settings required to allow 62e0eb33f6d555e925d8bb3bb2d02ead5ccc76114bRuben Brunk * the above capabilities are required, including the EGL extensions: 63e0eb33f6d555e925d8bb3bb2d02ead5ccc76114bRuben Brunk * EGL_ANDROID_create_native_client_buffer, EGL_ANDROID_front_buffer_auto_refresh, 64e0eb33f6d555e925d8bb3bb2d02ead5ccc76114bRuben Brunk * EGL_EXT_protected_content, EGL_KHR_mutable_render_buffer, 65e0eb33f6d555e925d8bb3bb2d02ead5ccc76114bRuben Brunk * EGL_KHR_reusable_sync, and EGL_KHR_wait_sync. 66e0eb33f6d555e925d8bb3bb2d02ead5ccc76114bRuben Brunk * - Accurate thermal reporting - Accurate thermal temperatures and limits must be 67e0eb33f6d555e925d8bb3bb2d02ead5ccc76114bRuben Brunk * reported in the thermal.h HAL. Specifically, the current skin temperature 68e0eb33f6d555e925d8bb3bb2d02ead5ccc76114bRuben Brunk * must accurately be reported for DEVICE_TEMPERATURE_SKIN and the 69e0eb33f6d555e925d8bb3bb2d02ead5ccc76114bRuben Brunk * vr_throttling_threshold reported for this device must accurately report the 70e0eb33f6d555e925d8bb3bb2d02ead5ccc76114bRuben Brunk * temperature limit above which the device's thermal governor throttles the 71e0eb33f6d555e925d8bb3bb2d02ead5ccc76114bRuben Brunk * CPU, GPU, and/or bus clockrates below the minimum necessary for consistent 72e0eb33f6d555e925d8bb3bb2d02ead5ccc76114bRuben Brunk * performance (see previous bullet point). 732c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk * 74e0eb33f6d555e925d8bb3bb2d02ead5ccc76114bRuben Brunk * In general, vendors implementing this HAL are expected to use set_vr_mode as a 75e0eb33f6d555e925d8bb3bb2d02ead5ccc76114bRuben Brunk * hint to enable VR-specific performance tuning needed for any of the above 76e0eb33f6d555e925d8bb3bb2d02ead5ccc76114bRuben Brunk * requirements, and to turn on any device features optimal for VR display 77e0eb33f6d555e925d8bb3bb2d02ead5ccc76114bRuben Brunk * modes. The set_vr_mode call may simply do nothing if no optimizations are 78e0eb33f6d555e925d8bb3bb2d02ead5ccc76114bRuben Brunk * available or necessary to meet the above requirements. 792c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk * 802c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk * No methods in this HAL will be called concurrently from the Android framework. 812c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk */ 822c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunktypedef struct vr_module { 832c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk /** 842c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk * Common methods of the module. This *must* be the first member of 85e0eb33f6d555e925d8bb3bb2d02ead5ccc76114bRuben Brunk * vr_module as users of this structure may cast a hw_module_t to a 862c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk * vr_module pointer in contexts where it's known that the hw_module_t 872c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk * references a vr_module. 882c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk */ 892c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk struct hw_module_t common; 902c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk 912c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk /** 922c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk * Convenience method for the HAL implementation to set up any state needed 932c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk * at runtime startup. This is called once from the VrManagerService during 942c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk * its boot phase. No methods from this HAL will be called before init. 952c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk */ 962c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk void (*init)(struct vr_module *module); 972c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk 982c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk /** 992c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk * Set the VR mode state. Possible states of the enabled parameter are: 1002c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk * false - VR mode is disabled, turn off all VR-specific settings. 1012c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk * true - VR mode is enabled, turn on all VR-specific settings. 1022c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk * 103e0eb33f6d555e925d8bb3bb2d02ead5ccc76114bRuben Brunk * This is called whenever the the Android system enters or leaves VR mode. 104e0eb33f6d555e925d8bb3bb2d02ead5ccc76114bRuben Brunk * This will typically occur when the user switches to or from a VR application 105e0eb33f6d555e925d8bb3bb2d02ead5ccc76114bRuben Brunk * that is doing stereoscopic rendering. 1062c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk */ 1072c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk void (*set_vr_mode)(struct vr_module *module, bool enabled); 1082c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk 1092c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk /* Reserved for future use. Must be NULL. */ 1102c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk void* reserved[8 - 2]; 1112c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk} vr_module_t; 1122c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk 1132c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk__END_DECLS 1142c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk 1152c84f81cf07326d9bd0abfb4b14f64bcb583e166Ruben Brunk#endif /* ANDROID_INCLUDE_HARDWARE_VR_H */ 116