README
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