1 This directory contains the modules related to hardware OpenGL ES emulation. 2 3 For now, this feature is experimental, and *nothing* will be built unless 4 you define BUILD_EMULATOR_OPENGL in your environment, for example with: 5 6 export BUILD_EMULATOR_OPENGL=true 7 8 You can also define the following to enable the "gralloc" module, which 9 corresponds to system-wide GLES emulation (by default, only a specific set 10 of applications are enabled, see below): 11 12 export BUILD_EMULATOR_OPENGL_DRIVER=true 13 14 15 I. Overview of components: 16 ========================== 17 18 The 'emugen' tool is used to generate several source files related to the 19 EGL/GLES command stream used between the guest and the host during emulation. 20 21 host/tools/emugen -> emugen program 22 23 Note that emugen is capable of generating, from a single set of specification 24 files, three types of auto-generated sources: 25 26 - sources to encode commands into a byte stream. 27 - sources to decode the byte stream into commands. 28 - sources to wrap normal procedural EGL/GLES calls into context-aware ones. 29 30 Modules under the system/ directory corresponds to code that runs on the 31 guest, and implement the marshalling of EGL/GLES commands into a stream of 32 bytes sent to the host through a fast pipe mechanism. 33 34 system/GLESv1_enc -> encoder for GLES 1.1 commands 35 system/GLESv2_enc -> encoder for GLES 2.0 commands 36 system/renderControl_enc -> encoder for rendering control commands 37 system/egl -> emulator-specific guest EGL library 38 system/GLESv1 -> emulator-specific guest GLES 1.1 library 39 system/gralloc -> emulator-specific gralloc module 40 system/OpenglSystemCommon -> library of common routines 41 42 Modules under the host/ directory corresponds to code that runs on the 43 host, and implement the decoding of the command stream, translation of 44 EGL/GLES commands into desktop GL 2.0 ones, and rendering to an off-screen 45 buffer. 46 47 host/libs/GLESv1_dec -> decoder for GLES 1.1 commands 48 host/libs/GLESv2_dec -> decoder for GLES 2.0 commands 49 host/libs/renderControl_dec -> decoder for rendering control commands 50 51 host/libs/Translator/EGL -> translator for EGL commands 52 host/libs/Translator/GLES_CM -> translator for GLES 1.1 commands 53 host/libs/Translator/GLES_V2 -> translator for GLES 2.0 commands 54 host/libs/Translator/GLcommon -> library of common translation routines 55 56 host/libs/libOpenglRender -> rendering library (uses all host libs above) 57 can be used by the 'renderer' program below, 58 or directly linked into the emulator UI program. 59 60 host/renderer/ -> stand-alone renderer program executable. 61 this can run in head-less mode and receive requests from 62 several emulators at the same time. It is the receiving 63 end of all command streams. 64 65 Modules under the test/ directory correspond to test programs that are useful 66 to debug the various modules described above: 67 68 tests/EGL_host_wrapper -> a small library used to dynamically load the 69 desktop libEGL.so or a replacement named by the 70 ANDROID_EGL_LIB environment variable. This lib 71 provides all EGL entry points. 72 73 tests/emulator_test_renderer -> a small program to run the rendering library 74 in a single SDL window on the host desktop. 75 76 tests/gles_android_wrapper -> guest EGL / GLES libraries that are run on 77 the device to run some tests. Replace the 78 system/egl and system/GLESv1 modules for now. 79 80 tests/translator_tests/GLES_CM -> desktop GLESv1 translation unit test 81 tests/translator_tests/GLES_V2 -> desktop GLESv2 translation unit test 82 tests/translator_tests/MacCommon -> used by translation tests on Mac only. 83 84 tests/ut_rendercontrol_enc -> guest library used by tests/ut_renderer 85 tests/ut_rendercontrol_dec -> host library used by tests/ut_renderer 86 tests/ut_renderer -> unit-test for render control and rendering library. 87 88 89 II. Build system considerations: 90 -------------------------------- 91 92 The dependencies on the more than 20 components described in the previous 93 section are pretty sophisticated, involving lots of auto-generated code and 94 non-trivial placement for guest/device libraries. 95 96 To simplify the development and maintenance of these modules, a set of 97 helper GNU Make function is defined in common.mk, and included from the 98 Android.mk in this directory. 99 100 These functions all begin with the "emugl-" prefix, and can be used to 101 declare modules, what information they export to other modules, or import 102 from them, and also what kind of auto-generated sources they depend on. 103 104 Look at the comments inside common.mk and the Android.mk of the modules 105 to better understand what's happening. 106 107
