README

   1 Sections in this file describe:
   2 - Introduction
   3 - Component Overview
   4 - Required platform capabilities
   5 - How to build on different platforms
   6
   7
   8 Introduction
   9 ====================================
  10 In the automotive domain, the most HMI systems are using their own window manager implementation.
  11 Many applications (e.g. navigation, reversing camera) are implemented standalone and
  12 therefore one service is used to composite all applications to the final image on the screen. This Service
  13 is also know as LayerManagement.
  14 This Component provides a common API and a proof-of-concept implementation for the Layer Management Service.
  15 This service should improve the existing vendor-specific layer management implementations
  16 which have the following features :
  17
  18     * Fixed number of hardware layers
  19     * Hardware accelerated compositing
  20     * Platform dependent
  21     * Number of layers not extensible during runtime
  22     * Vendor-specific implementation
  23     * No standardized interface
  24     * Hardware dependent
  25     * No change during runtime possible
  26
  27 The IVI Layer Management have the following enhancements :
  28
  29     * Well-defined interface
  30     * Standardized compositing
  31     * Convenient and consistent access to hardware accelerated modules
  32     * Separation of HMI and Layer Management
  33     * Dynamically Extensions during runtime
  34     * Low integration complexity
  35     * Reduced dependency on hardware
  36
  37 Component Overview
  38 ====================================
  39 The IVI Layer Management consist of three subcomponents.
  40
  41 The LayerManagementService
  42 ===
  43 This is the main component which controls and handles
  44 the different layers with its content. Furthermore he
  45 will execute the commands which are deployed by the corresponding
  46 communicator. The content of the different layers are deployed to the
  47 renderer.
  48
  49 The LayerManagementCommunicator
  50 ===
  51 This subcomponent will handle the LayerManagement API messages. Generally
  52 a communicator will establish the communication between application and the
  53 LayerManagementService. The concept behind the communicator is to abstract
  54 the required ipc mechanism on the target platform.
  55
  56 The LayerManagementRenderer
  57 ===
  58 This subcomponent will handle the rendering of the different layers and its content on the
  59 final used target platform. The concept behind the renderer is to abstract
  60 the required rendering mechanism on the target platform.
  61
  62 Required Platform capabilities
  63 ====================================
  64
  65 Platform with X11 and OpenGL ES 2.0
  66 ===
  67
  68 If you have choosen the X11GLESRenderer as rendering backend, then the following
  69 Extensions have to be supported by the TargetPlatform :
  70
  71 X11 Extensions:
  72
  73 x-composite : This extension should support redirecting of egl Surfaces to x11 pixmaps too.
  74 x-damage
  75
  76 EGL / OpenGL ES 2.0:
  77
  78 EGL_IMAGE_KHR :
  79 The following functions should be supported by the vendor specific graphic driver
  80 glEGLImageTargetTexture2DOES
  81 eglCreateImageKHR
  82 eglDestroyImageKHR
  83 Furthermore it should be supported to create an egl image from an x11 pixmap.
  84
  85 Platform with X11 and OpenGL
  86 ===
  87
  88 If you have choosen the GLXRenderer as rendering backend, then the following
  89 Extensions have to be supported by the TargetPlatform :
  90
  91 X11 Extensions:
  92
  93 x-composite : This extension should support redirecting of egl Surfaces to x11 pixmaps too.
  94 x-damage    : This extension is required to render surfaces only, if there content has changed.
  95
  96 GLX / OpenGL :
  97
  98 GLX_TEXTURE_FROM_PIXMAP :
  99 The following functions should be supported by the vendor specific graphic driver
 100 Furthermore it should be supported to create an texture from an x11 pixmap.
 101
 102
 103 Beagle board platform
 104 ===
 105
 106 If you have choosen the BeagleRenderer as rendering backend, than the following
 107 kernel module must be available too :
 108
 109 CMEM Module is needed, it can be downloaded from
 110
 111 http://software-dl.ti.com/dsps/dsps_public_sw/sdo_sb/targetcontent/linuxutils/index.html
 112
 113 The EGL implementation on the beagle board should support the following egl config:
 114
 115 EGL_SURFACE_TYPE = EGL_WINDOW_BIT | EGL_PIXMAP_BIT
 116 EGL_RENDERABLE_TYPE = EGL_OPENGL_ES2_BIT,
 117 EGL_RED_SIZE = 8
 118 EGL_ALPHA_SIZE = 8
 119 EGL_BIND_TO_TEXTURE_RGBA = EGL_TRUE
 120
 121 Furthermore the application which should be rendered by the layermanagement, should initialize egl
 122 by the following steps:
 123
 124 1. Get EGL Display
 125 2. Initialize EGL
 126 3. Bind API
 127 4. Choose EGL Config
 128 5. Allocate native pixmap Structure
 129 6. Allocate native pixmap space by CMEM_alloc
 130 7. Get physical address of native pixmap using the CMEM module, and assign the address to the native pixmap structure.
 131 8. Create egl pixmap surface using the allocated native pixmap.
 132 9. Create egl context.
 133 10. Make egl context with the surface as current.
 134
 135
 136 How to build on different platforms
 137 ====================================
 138
 139 These conditions need to be met in order to build the LayerManager component:
 140
 141 - CMake required (version 2.6 or higher)
 142
 143 Building the LayerManager breaks down to the following steps:
 144
 145 1. Pull the current codebase from the git repository to your target source directory [referred to as <source-dir>]
 146
 147    Example: git clone https://git.genivi.org/srv/git/layer_management
 148
 149    This should give you a directory called "layer_management" in your current directory.
 150
 151 2. Create a build directory, e.g. IVILayerManagement_build [referred to as <build-dir>]
 152
 153    Example: mkdir IVILayerManagement_build
 154
 155 3. In <build-dir> Generate build system for your platform using CMake.
 156    This step provides some customization options to configure build options.
 157
 158    Example: cd <build-dir>
 159             cmake <source-dir> [optional_build_options]
 160
 161    For a full list of available build options in [optional_build_options] see "Supported Build Options"
 162
 163 4. Start the build.
 164
 165    Example: make
 166
 167 5. Install LayerManager on local system.
 168    Note: This step will require root priviledges on most systems.
 169
 170    Example: sudo make install
 171
 172 The LayerManager may now be started by calling "LayerManagerService".
 173
 174 Needed Libraries
 175 ===
 176
 177 You need both development packages and libraries for
 178
 179 LayerManagerService
 180 --
 181 libdbus
 182
 183 X11GLESRenderer:
 184 --
 185 Core X11 libraries
 186 X11 Composite libraries
 187
 188 Vendor specific EGL 1.4 Libraries, which are support the EGL_IMAGE_KHR Extension including
 189 build an EGL Image from X11Pixmap
 190 Vendor specific OpenGL ES 2.0 Libraries, with JIT compiler to support shader which are
 191 delivered as source code
 192
 193 X11Renderer:
 194 ---
 195 Core X11 libraries
 196 X11 Composite libraries
 197
 198 OpenGL 1.1
 199 GLX
 200
 201 Supported Build Options
 202 ===
 203
 204 - Build configuration:
 205   Option: -DCMAKE_BUILD_TYPE=DEBUG or
 206           -DCMAKE_BUILD_TYPE=RELEASE
 207
 208 - Build for X11 Desktop with GLX Renderer
 209   Option: -DWITH_DESKTOP=ON or
 210           -DWITH_DESKTOP=OFF
 211
 212 - Build for X11 with OpenGL ES 2.0 Renderer
 213   Option: -DWITH_X11_GLES=ON or
 214           -DWITH_X11_GLES=OFF
 215
 216 - Build EGL examples
 217   Option: -DWITH_EGL_EXAMPLE=ON or
 218           -DWITH_EGL_EXAMPLE=OFF
 219
 220 - Build GLX examples
 221   Option: -DWITH_GLX_EXAMPLE=ON or
 222           -DWITH_GLX_EXAMPLE=OFF
 223
 224 - Build available tests
 225   Option: -DWITH_TESTS=ON or
 226           -DWITH_TESTS=OFF
 227
 228   Remark: Test File are currently not upstreamed.
 229
 230 - Build for diferent Platforms
 231
 232   You have the choice to use GLXRenderer or X11GLESRenderer.
 233
 234   GLXRenderer (X11Renderer.so) which is normaly used for a Desktop, VMWare Image and GMA500 based Headunits
 235
 236   cmake <source-dir>/ -DWITH_DESKTOP=ON -DWITH_GLX_EXAMPLE=ON -DWITH_TESTS=OFF -DWITH_EGL_EXAMPLE=OFF -DWITH_X11_GLES=OFF
 237
 238   X11GLESRenderer which is used on more embedded device which are supporting EGL and OpenGL ES 2.0
 239
 240   cmake <source-dir>/ -DWITH_DESKTOP=OFF -DWITH_GLX_EXAMPLE=OFF -DWITH_TESTS=OFF -DWITH_EGL_EXAMPLE=ON -DWITH_X11_GLES=ON
 241
 242