From: Ruben Brunk Date: Tue, 3 May 2016 02:29:57 +0000 (-0700) Subject: Update VR HAL docs. X-Git-Tag: android-x86-7.1-r1~9^2~12^2 X-Git-Url: http://git.osdn.net/view?a=commitdiff_plain;h=e0eb33f6d555e925d8bb3bb2d02ead5ccc76114b;p=android-x86%2Fhardware-libhardware.git Update VR HAL docs. Bug: 28526281 Change-Id: If9673af47962f6fadd10f8a622e9587245f7ffb6 --- diff --git a/include/hardware/lights.h b/include/hardware/lights.h index b426caf..b3d28b0 100644 --- a/include/hardware/lights.h +++ b/include/hardware/lights.h @@ -110,15 +110,20 @@ __BEGIN_DECLS * persistence that is intended to be used when the device is being treated as a * head mounted display (HMD). The actual display brightness in this mode is * implementation dependent, and any value set for color in light_state may be - * overriden by the HAL implementation. + * overridden by the HAL implementation. * - * For an optimal HMD viewing experience, the display should meet the following + * For an optimal HMD viewing experience, the display must meet the following * criteria in this mode: - * - Less than 2ms display persistence. + * - Gray-to-Gray, White-to-Black, and Black-to-White switching time must be ≤ 3 ms. + * - The display must support low-persistence with ≤ 3.5 ms persistence. + * Persistence is defined as the amount of time for which a pixel is + * emitting light for a single frame. * - Any "smart panel" or other frame buffering options that increase display * latency are disabled. * - Display brightness is set so that the display is still visible to the user * under normal indoor lighting. + * - The display must update at 60 Hz at least, but higher refresh rates are + * recommended for low latency. * * This mode will only be used with light devices of type LIGHT_ID_BACKLIGHT, * and will only be called by the Android framework for light_device_t diff --git a/include/hardware/thermal.h b/include/hardware/thermal.h index e7189e2..b5b6e1d 100644 --- a/include/hardware/thermal.h +++ b/include/hardware/thermal.h @@ -82,8 +82,8 @@ typedef struct { float shutdown_threshold; /** - * Threshold temperature at which VR mode clockrate minumums cannot be - * maintained for this device temperature type. + * Threshold temperature above which the VR mode clockrate minimums cannot + * be maintained for this device. * If not available, set by HAL to UNKNOWN_TEMPERATURE. */ float vr_throttling_threshold; diff --git a/include/hardware/vr.h b/include/hardware/vr.h index 17a0606..69f8654 100644 --- a/include/hardware/vr.h +++ b/include/hardware/vr.h @@ -35,42 +35,54 @@ __BEGIN_DECLS * and gyro to an application-visible callback must be extremely low (<5ms * typically). This is required for HIFI sensor support. * - Low display latency - Total end-to-end latency from the GPU draw calls to - * the actual display update must be as low as possible. This is typically - * achieved by using SurfaceFlinger in a single-buffered mode, and assuring - * that draw calls are synchronized with the display scanout correctly. Any - * GPU settings required to allow consistent performance of this operation - * are required, including the EGL extensions: EGL_IMG_context_priority, and - * EGL_XXX_set_render_buffer_mode. + * the actual display update must be as low as possible. This is achieved by + * using SurfaceFlinger in a single-buffered mode, and assuring that draw calls + * are synchronized with the display scanout correctly. This behavior is + * exposed via an EGL extension to applications. See below for the EGL + * extensions needed for this. * - Low-persistence display - Display persistence settings must be set as low as * possible while still maintaining a reasonable brightness. For a typical - * display running at 60Hz, pixels should be illuminated for <4ms to be - * considered low-persistence (<2ms is desirable). This avoids ghosting - * during movements in a VR setting. + * display running at 60Hz, pixels should be illuminated for <=3.5ms to be + * considered low-persistence. This avoids ghosting during movements in a VR + * setting, and should be enabled from the lights.h HAL when + * BRIGHTNESS_MODE_LOW_PERSISTENCE is set. * - Consistent performance of the GPU and CPU - When given a mixed GPU/CPU * workload for a VR application with bursts of work at regular intervals - * several times a frame. CPU scheduling should ensure that the application - * render thread is run consistently within 1ms of when required for the - * draw window, and an appropriate clockrate is maintained to ensure the - * workload finishes within the time alloted to the draw window. Likewise, - * GPU scheduling should ensure that work from the application render thread - * is given priority over other GPU work, and that a high enough clockrate can - * be maintained to ensure that this completes within the draw window. CTS - * tests with example VR workloads will be available to assess performance - * tuning. + * several times a frame, the CPU scheduling should ensure that the application + * render thread work is run consistently within 1ms of when scheduled, and + * completed before the end of the draw window. To this end, a single CPU core + * must be reserved for solely for the currently running VR application's render + * thread while in VR mode, and made available in the "top-app" cpuset. + * Likewise, an appropriate CPU, GPU, and bus clockrate must be maintained to + * ensure that the rendering workload finishes within the time allotted to + * render each frame when the POWER_HINT_SUSTAINED_PERFORMANCE flag has been + * set in the power.h HAL while in VR mode when the device is not being + * thermally throttled. + * - Required EGL extensions must be present - Any GPU settings required to allow + * the above capabilities are required, including the EGL extensions: + * EGL_ANDROID_create_native_client_buffer, EGL_ANDROID_front_buffer_auto_refresh, + * EGL_EXT_protected_content, EGL_KHR_mutable_render_buffer, + * EGL_KHR_reusable_sync, and EGL_KHR_wait_sync. + * - Accurate thermal reporting - Accurate thermal temperatures and limits must be + * reported in the thermal.h HAL. Specifically, the current skin temperature + * must accurately be reported for DEVICE_TEMPERATURE_SKIN and the + * vr_throttling_threshold reported for this device must accurately report the + * temperature limit above which the device's thermal governor throttles the + * CPU, GPU, and/or bus clockrates below the minimum necessary for consistent + * performance (see previous bullet point). * - * Vendors implementing this HAL are expected to use set_vr_mode as a hint to - * enable VR-specific performance tuning, and to turn on any device features - * optimal for VR display modes (or do nothing if none are available). Devices - * that advertise FEATURE_VR_MODE_HIGH_PERFORMANCE are must pass the additional - * CTS performance tests required for this feature and follow the additional - * guidelines for hardware implementation for "VR Ready" devices. + * In general, vendors implementing this HAL are expected to use set_vr_mode as a + * hint to enable VR-specific performance tuning needed for any of the above + * requirements, and to turn on any device features optimal for VR display + * modes. The set_vr_mode call may simply do nothing if no optimizations are + * available or necessary to meet the above requirements. * * No methods in this HAL will be called concurrently from the Android framework. */ typedef struct vr_module { /** * Common methods of the module. This *must* be the first member of - * vr_module as users of * this structure will cast a hw_module_t to a + * vr_module as users of this structure may cast a hw_module_t to a * vr_module pointer in contexts where it's known that the hw_module_t * references a vr_module. */ @@ -88,10 +100,9 @@ typedef struct vr_module { * false - VR mode is disabled, turn off all VR-specific settings. * true - VR mode is enabled, turn on all VR-specific settings. * - * This is called from the VrManagerService whenever the application(s) - * currently in use enters or leaves VR mode. This will typically occur - * when the user switches or from an application that has indicated to - * system_server that it should run in VR mode. + * This is called whenever the the Android system enters or leaves VR mode. + * This will typically occur when the user switches to or from a VR application + * that is doing stereoscopic rendering. */ void (*set_vr_mode)(struct vr_module *module, bool enabled);