vr_module Struct Reference

vr_module Struct Reference

#include < vr.h >

Data Fields

struct hw_module_t   common
void(*  init )(struct vr_module *module)
void(*  set_vr_mode )(struct vr_module *module, bool enabled)
void *  reserved [8-2]

Detailed Description

Implement this HAL to receive callbacks when a virtual reality (VR) application is being used. VR applications characteristically have a number of special display and performance requirements, including:

  • Low sensor latency - Total end-to-end latency from the IMU, accelerometer, 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 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 <=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, 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).

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.

Definition at line 82 of file vr.h .

Field Documentation

struct hw_module_t common

Common methods of the module. This must be the first member of 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 .

Definition at line 89 of file vr.h .

void(* init)(struct vr_module *module)

Convenience method for the HAL implementation to set up any state needed at runtime startup. This is called once from the VrManagerService during its boot phase. No methods from this HAL will be called before init.

Definition at line 96 of file vr.h .

void* reserved[8-2]

Definition at line 110 of file vr.h .

void(* set_vr_mode)(struct vr_module *module, bool enabled)

Set the VR mode state. Possible states of the enabled parameter are: 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 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.

Definition at line 107 of file vr.h .

The documentation for this struct was generated from the following file:
  • hardware/libhardware/include/hardware/ vr.h