blob: 57bc9ac7879aa1a05e98d2a4222726a111884917 [file] [log] [blame]
An overview of GPU Emulation for Android:
GPU emulation is controlled by the followind AVD hardware properties:
hw.gpu.enabled Boolean indicating whether GPU emulation is enabled.
If 'false', the builtin guest software renderer will be
used instead. Note that the latter is very slow and only
supports GLES 1.x, so most applications will not run with
it properly.
hw.gpu.mode Only used when hw.gpu.enabled is on. This is a string that
describes which emulation mode to support.
At this time, the following modes are supported:
'host' The default mode, uses specific translator libraries to convert
guest EGL/GLES commands into host desktop GL ones. This requires
valid OpenGL drivers installed on the development machine, and
of course a display connection.
Note that on some platforms (Windows in particular), OpenGL drivers
can be buggy, resulting in poor performance, rendering artefacts
or even crashes. To work-around this, use the 'mesa' mode instead.
'mesa' Software-based desktop GL renderer, based on the Mesa3D library.
This is slower than 'host' mode by a large margin, but works
equally well on all supported platforms. This is recommended if
there are issues with 'host' mode.
Another benefit of 'mesa' mode is that it can be run on headless
servers which do not have a GPU, or OpenGL libraries installed.
Alternatively, one can use the '-gpu <mode>' option to force a specific mode.
Values 'on', 'off' and 'auto' are also recognized. See -help-gpu for details.
Host mode libraries are installed at the following locations:
The example above is for Linux, the shared libraries' extension will vary
with the host platform (i.e. .dylib for Darwin, and .dll for Windows).
Please read the distrib/android-emugl/DESIGN document first, which describes
host mode emulation in detail.
The Mesa libraries are built using the android/scripts/ script,
and installed differently, depending on the platform. For Linux, this will be:
gles_mesa/ ->
gles_mesa/ ->
For Windows:
The 'emulator' launcher program works as follows:
- Parse the AVD configuration to see if GPU emulation is enabled.
- If enabled, prepend $EXEC_DIR/<lib>/ to LD_LIBRARY_PATH (or PATH on
Windows). This ensures that the host libraries will always be loaded
properly through dlopen() / LoadLibrary() later.
- If 'mesa' mode is enabled, it will also prepend $EXEC_DIR/<lib>/gles_mesa/
to LD_LIBRARY_PATH / PATH, to ensure the corresponding library is loaded.
Note that on Linux, the mesa sub-directory includes a link from
to The latter is the Mesa rendering library. The former is a link
which is needed because the Android UI uses SDL2 which links against this
specific version of the library.
Without the symlink, creating the UI window will load the system version of, which will later prevent the load of Mesa's
At this time, Mesa doesn't build for OS X, and the resulting library
still depends on XLib / Win32 GDI. This means that for true headless
emulation on Linux, one should run an Xvfb server and set DISPLAY
An experimental feature is the ability to add new "GPU emulation backends".
The 'emulator' program will look for the following libraries:
$EXEC_DIR/<lib>/gles_<name>/ -> desktop EGL library -> desktop GLESv1 library -> desktop GLESv2 library
Where <name> is an arbitrary backend name.
If one of these libraries is defined, then it sets the appropriate environment
ensure that libOpenglRender will use it, instead of the corresponding host
translation library.
The source code related to these features is located under:
android/opengles.c -> GPU emulation low-level initialization which happens
after the emulation engine is started.
android/opengl/ -> GPU emulation support code that is used by 'emulator'
to probe installed backends and select the correct
one based on AVD configuration / command-line
options, as well as setup the environment.