OpenGLES

OpenGL is a cross-platform graphics API that specifies a standard software interface for 3D graphics processing hardware. OpenGL ES is a subset of the OpenGL specification for embedded devices.

To be Android compatible, devices need to provide drivers for EGL, OpenGL ES 1.x, and OpenGL ES 2.0. Support for OpenGL ES 3.x is optional. Key considerations include:

• Ensuring that the GL driver is robust and conforms to OpenGL ES standards.
• Allowing an unlimited number of GL contexts. Because Android allows apps in the background and tries to keep GL contexts alive, you shouldn't limit the number of contexts in your driver.
• Being mindful of the amount of memory allocated for each context, because it's common to have 20–30 active GL contexts at once.
• Supporting the YV12 image format and other YUV image formats that come from other components in the system, such as media codecs or the camera.
• Supporting the mandatory extensions EGL_KHR_wait_sync, GL_OES_texture_external, EGL_ANDROID_image_native_buffer, and EGL_ANDROID_recordable. Additionally, Hardware Composer v1.1 and higher require the EGL_ANDROID_framebuffer_target extension.

It's highly recommended to also support EGL_ANDROID_blob_cache, EGL_KHR_fence_sync, and EGL_ANDROID_native_fence_sync.

Android 10 implements the EGL 1.5 interface. For information on new features in EGL 1.5, see the Khronos Releases 1.5 Specification.

Driver loading

Android expects the GPUs available to the system to be known when the system image is built. The preferred paths for 32-bit and 64-bit OpenGL ES drivers are /vendor/lib/egl and /vendor/lib64/egl respectively. The loader uses two system properties, ro.hardware.egl and ro.board.platform, or the exact name to discover and load the system drivers. The OpenGL ES driver must be shipped in either one binary or split into three binaries. If the OpenGL ES driver is shipped in one binary, use one of the following names:

libGLES_${ro.hardware.egl}.so
libGLES_${ro.board.platform}.so
libGLES.so

If the OpenGL ES driver is shipped into three binaries, use one of the following name sets:

libEGL_${ro.hardware.egl}.so
libGLESv1_CM_${ro.hardware.egl}.so
libGLESv2_${ro.hardware.egl}.so

libEGL_${ro.board.platform}.so
libGLESv1_CM_${ro.board.platform}.so
libGLESv2_${ro.board.platform}.so

libEGL.so
libGLESv1_CM.so
libGLESv2.so

OpenGL ES layers

Android 10 introduces a layering system for GLES 2.0+. GLES layers are shared objects available from within apps or provided by tools. GLES layers enable debuggable apps to discover and load layers using the same setup mechanisms as Vulkan.

GLES LayerLoader, a component within the EGL loader, identifies GLES layers. For each layer the GLES LayerLoader finds, the GLES LayerLoader calls AndroidGLESLayer_Initialize, walks libEGL's function lists, and calls AndroidGLESLayer_GetProcAddress for all known functions. If the layer intercepts a function, it tracks the function's address. If the layer doesn't intercept a function, AndroidGLESLayer_GetProcAddress returns the same function address it was passed. The LayerLoader then updates the function hook list to point to the layer's entry point.

Enabling layers

You can enable GLES layers either per app or globally. Per-app settings persist across reboots, while global properties are cleared on reboot.

To enable layers per app:

# Enable layers
adb shell settings put global enable_gpu_debug_layers 1

# Specify target app
adb shell settings put global gpu_debug_app package_name

# Specify layer list (from top to bottom)
adb shell settings put global gpu_debug_layers_gles layer1:layer2:...:layerN

# Specify packages to search for layers
adb shell settings put global gpu_debug_layer_app package1:package2:...:packageN

To disable layers per app:

adb shell settings delete global enable_gpu_debug_layers
adb shell settings delete global gpu_debug_app
adb shell settings delete global gpu_debug_layer_app

To enable layers globally:

# Attempts to load layers for all applications, including native executables
adb shell setprop debug.gles.layers layer1:layer2:...:layerN

Testing layers

GLES layers are backed by Android CTS and are required to pass CTS tests for compatible devices. To identify if layers are working on a device, run $ atest CtsGpuToolsHostTestCases.