| 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 'swiftshader' mode. |
| |
| 'swiftshader' |
| Software OpenGL renderer using the Swiftshader renderer. |
| This is recommended if there are issues with 'host' mode. |
| It is generally slower than -gpu host, but works equally well |
| on all supported platforms. |
| |
| Swiftshader also takes advantage of SIMD on modern CPUs; |
| reducing AVD resolution may result in smoother performance. |
| |
| Another benefit of 'swiftshader' mode is that it can be run on |
| headless servers which do not have a GPU or OpenGL libraries. |
| |
| 'mesa' (DEPRECATED; please use 'swiftshader' mode if possible) |
| Software-based desktop GL renderer, based on the Mesa3D library. |
| This is slower than 'swiftshader' mode, |
| and slower than 'host' mode by a large margin. |
| |
| 'auto' Uses 'host' mode if not remoting (NX or CRD), |
| 'swiftshader' otherwise. |
| |
| 'guest' Use a guest-side OpenGL ES implementation. |
| |
| 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. |