| 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: |
| |
| $EXEC_DIR/lib/ |
| libOpenglRender.so |
| libEGL_translator.so |
| libGLES_CM_translator.so |
| libGLESv2_translator.so |
| |
| $EXEC_DIR/lib64/ |
| lib64OpenglRender.so |
| lib64EGL_translator.so |
| lib64GLES_CM_translator.so |
| lib64GLESv2_translator.so |
| |
| 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/build-mesa.sh script, |
| and installed differently, depending on the platform. For Linux, this will be: |
| |
| $EXEC_DIR/lib/ |
| gles_mesa/ |
| libGL.so |
| libGL.so.1 -> libGL.so |
| |
| $EXEC_DIR/lib64/ |
| gles_mesa/ |
| libGL.so |
| libGL.so.1 -> libGL.so |
| |
| For Windows: |
| |
| $EXEC_DIR/lib/ |
| gles_mesa/ |
| opengl32.dll |
| |
| $EXEC_DIR/lib64/ |
| gles_mesa/ |
| opengl32.dll |
| |
| |
| 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 libGL.so.1 |
| to libGL.so. 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 |
| libGL.so.1, which will later prevent the load of Mesa's libGL.so. |
| |
| IMPORTANT NOTE: |
| |
| 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 |
| appropriately. |
| |
| |
| 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>/ |
| libEGL.so -> desktop EGL library |
| libGLES_CM.so -> desktop GLESv1 library |
| libGLESv2.co -> desktop GLESv2 library |
| |
| Where <name> is an arbitrary backend name. |
| |
| If one of these libraries is defined, then it sets the appropriate environment |
| variable (e.g. ANDROID_EGL_LIB / ANDROID_GLESv1_LIB / ANDROID_GLESv2_LIB) to |
| 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. |