README

   1 Sections in this file describe:
   2 - Introduction
   3 - Component Overview
   4 - Required platform capabilities
   5 - How to build on different platforms
   6 - Change the environment during Runtime
   7 - Running Testapplications
   8
   9
  10 Introduction
  11 ====================================
  12 In the automotive domain, the most HMI systems are using their own window manager implementation.
  13 Many applications (e.g. navigation, reversing camera) are implemented standalone and
  14 therefore one service is used to composite all applications to the final image on the screen. This Service
  15 is also know as LayerManagement.
  16 This Component provides a common API and a proof-of-concept implementation for the Layer Management Service.
  17 This service should improve the existing vendor-specific layer management implementations
  18 which have the following features :
  19
  20     * Fixed number of hardware layers
  21     * Hardware accelerated compositing
  22     * Platform dependent
  23     * Number of layers not extensible during runtime
  24     * Vendor-specific implementation
  25     * No standardized interface
  26     * Hardware dependent
  27     * No change during runtime possible
  28
  29 The IVI Layer Management have the following enhancements :
  30
  31     * Well-defined interface
  32     * Standardized compositing
  33     * Convenient and consistent access to hardware accelerated modules
  34     * Separation of HMI and Layer Management
  35     * Dynamically Extensions during runtime
  36     * Low integration complexity
  37     * Reduced dependency on hardware
  38
  39 Component Overview
  40 ====================================
  41 The IVI Layer Management consist of three subcomponents.
  42
  43 The LayerManagementService
  44 ===
  45 This is the main component which controls and handles
  46 the different layers with its content. Furthermore he
  47 will execute the commands which are deployed by the corresponding
  48 communicator. The content of the different layers are deployed to the
  49 renderer.
  50
  51 The LayerManagementCommunicator
  52 ===
  53 This subcomponent will handle the LayerManagement API messages. Generally
  54 a communicator will establish the communication between application and the
  55 LayerManagementService. The concept behind the communicator is to abstract
  56 the required ipc mechanism on the target platform.
  57
  58 The LayerManagementRenderer
  59 ===
  60 This subcomponent will handle the rendering of the different layers and its content on the
  61 final used target platform. The concept behind the renderer is to abstract
  62 the required rendering mechanism on the target platform.
  63
  64 Required Platform capabilities
  65 ====================================
  66
  67 Platform with X11 and OpenGL ES 2.0
  68 ===
  69
  70 If you have choosen the X11GLESRenderer as rendering backend, then the following
  71 Extensions have to be supported by the TargetPlatform :
  72
  73 X11 Extensions:
  74
  75 x-composite : This extension should support redirecting of egl Surfaces to x11 pixmaps too.
  76 x-damage
  77
  78 EGL / OpenGL ES 2.0:
  79
  80 EGL_IMAGE_KHR :
  81 The following functions should be supported by the vendor specific graphic driver
  82 glEGLImageTargetTexture2DOES
  83 eglCreateImageKHR
  84 eglDestroyImageKHR
  85 Furthermore it should be supported to create an egl image from an x11 pixmap.
  86
  87 Platform with X11 and OpenGL
  88 ===
  89
  90 If you have choosen the GLXRenderer as rendering backend, then the following
  91 Extensions have to be supported by the TargetPlatform :
  92
  93 X11 Extensions:
  94
  95 x-composite : This extension should support redirecting of egl Surfaces to x11 pixmaps too.
  96 x-damage    : This extension is required to render surfaces only, if there content has changed.
  97
  98 GLX / OpenGL :
  99
 100 GLX_TEXTURE_FROM_PIXMAP :
 101 The following functions should be supported by the vendor specific graphic driver
 102 Furthermore it should be supported to create an texture from an x11 pixmap.
 103
 104
 105 How to build on different platforms
 106 ====================================
 107
 108 These conditions need to be met in order to build the LayerManager component:
 109
 110 - CMake required (version 2.6 or higher)
 111
 112 Building the LayerManager breaks down to the following steps:
 113
 114 1. Pull the current codebase from the git repository to your target source directory [referred to as <source-dir>]
 115
 116    Example: git clone https://git.genivi.org/srv/git/layer_management
 117
 118    This should give you a directory called "layer_management" in your current directory.
 119
 120 2. Create a build directory, e.g. IVILayerManagement_build [referred to as <build-dir>]
 121
 122    Example: mkdir IVILayerManagement_build
 123
 124 3. In <build-dir> Generate build system for your platform using CMake.
 125    This step provides some customization options to configure build options.
 126
 127    Example: cd <build-dir>
 128             cmake <source-dir> [optional_build_options]
 129
 130    For a full list of available build options in [optional_build_options] see "Supported Build Options"
 131
 132 4. Start the build.
 133
 134    Example: make
 135
 136 5. Install LayerManager on local system.
 137    Note: This step will require root priviledges on most systems.
 138
 139    Example: sudo make install
 140
 141 The LayerManager may now be started by calling "LayerManagerService".
 142
 143 Needed Libraries
 144 ===
 145
 146 You need both development packages and libraries for
 147
 148 LayerManagerService
 149 --
 150 libdbus-1-dev
 151
 152 X11GLESRenderer:
 153 --
 154 Core X11 libraries
 155 X11 Composite libraries
 156
 157 Vendor specific EGL 1.4 Libraries, which are support the EGL_IMAGE_KHR Extension including
 158 build an EGL Image from X11Pixmap
 159 Vendor specific OpenGL ES 2.0 Libraries, with JIT compiler to support shader which are
 160 delivered as source code
 161
 162 X11Renderer:
 163 ---
 164 Core X11 libraries
 165 X11 Composite libraries
 166
 167 OpenGL 1.1
 168 GLX
 169
 170 Supported Build Options
 171 ===
 172
 173 - Build configuration:
 174   Option: -DCMAKE_BUILD_TYPE=Debug or
 175           -DCMAKE_BUILD_TYPE=Release
 176
 177 - Build for X11 Desktop with OpenGL / GLX Renderer
 178   Option: -DWITH_DESKTOP=ON or
 179           -DWITH_DESKTOP=OFF
 180
 181 - Build for X11 with OpenGL ES 2.0 Renderer
 182   Option: -DWITH_X11_GLES=ON or
 183           -DWITH_X11_GLES=OFF
 184
 185 - Build EGL examples
 186   Option: -DWITH_EGL_EXAMPLE=ON or
 187           -DWITH_EGL_EXAMPLE=OFF
 188
 189 - Build OpenGL / GLX examples
 190   Option: -DWITH_GLX_EXAMPLE=ON or
 191           -DWITH_GLX_EXAMPLE=OFF
 192
 193 - Build Client examples
 194   Option: -DWITH_CLIENT_EXAMPLES=ON or
 195           -DWITH_CLIENT_EXAMPLES=OFF
 196
 197 - Build with copy of textures for target platform which does not support the
 198   GLX_TEXTURE_FROM_PIXMAP or EGL_IMAGE_KHR on X11 pixmaps Extensions
 199   Option: -DWITH_FORCE_COPY=ON or
 200           -DWITH_FORCE_COPY=OFF
 201
 202 - Build available tests
 203   Option: -DWITH_TESTS=ON or
 204           -DWITH_TESTS=OFF
 205
 206   Remark: Test File are currently not upstreamed.
 207
 208 - Build for different Platforms
 209
 210   You have the choice to use GLXRenderer or X11GLESRenderer.
 211
 212   GLXRenderer (X11Renderer.so) which is normaly used for a Desktop, VMWare Image and GMA500 based Headunits
 213
 214   cmake <source-dir>/ -DWITH_DESKTOP=ON -DWITH_GLX_EXAMPLE=ON -DWITH_TESTS=OFF -DWITH_EGL_EXAMPLE=OFF -DWITH_X11_GLES=OFF
 215
 216   X11GLESRenderer which is used on more embedded device which are supporting EGL and OpenGL ES 2.0
 217
 218   cmake <source-dir>/ -DWITH_DESKTOP=OFF -DWITH_GLX_EXAMPLE=OFF -DWITH_TESTS=OFF -DWITH_EGL_EXAMPLE=ON -DWITH_X11_GLES=ON
 219
 220 Change the Environment during Runtime
 221 =====================================
 222 The following environments can be set to change the runtime behaviour.
 223
 224 LM_PLUGIN_PATH          set the path for the location of communicator and renderer PlugIns
 225                         default : /usr/lib/layermanager
 226                         Example : export LM_PLUGIN_PATH= /usr/local/lib/layermanager
 227
 228 LM_USE_SESSION_BUS      enables the DBUS communication to run on Session bus instead of Systembus
 229                         default : disabled run on system bus
 230                         Example : export LM_USE_SESSION_BUS=enable
 231
 232 Commandline parameter :
 233 LayerManagerService : -w<horizontalresolution> - default 1280
 234                       -h<verticalresolution> - default 480
 235                       -c<console debug level> - default 2 (only errors and info)
 236                       -f<file debug level> - default 0 (disabled) log file location is /tmp/LayerManagerService.log
 237                       possible debug levels :   0 disabled
 238                                                 1 errors
 239                                                 2 info,errors
 240                                                 3 info,errors, warnings
 241                                                 4 info,errors, warnings,debug
 242                       -v shows version of layermanager
 243
 244 Running Testapplications
 245 =====================================
 246
 247 1. Starting the service
 248
 249 precondition :
 250
 251 install prefix is /usr/local
 252 no compositing manager is running like openbox xfce metacity, kill these if needed
 253
 254 run:
 255 #> export DISPLAY=:0
 256 #> export LD_LIBRARY_PATH=/usr/local/lib:/usr/lib
 257 #> export LM_PLUGIN_PATH=/usr/local/lib/layermanager
 258 #> LayerManagerService &
 259
 260 2. Running OpenGL / OpenGL ES 2.0 Example Applications
 261
 262 precondition :
 263
 264 install prefix is /usr/local
 265 LayerManagerService Running
 266
 267 run:
 268 #> export DISPLAY=:0
 269 #> export LD_LIBRARY_PATH=/usr/local/lib:/usr/lib
 270 OpenGL ES Example
 271 #> EGLX11ApplicationExample &
 272 OpenGL Example
 273 #> GLX11ApplicationExample &
 274
 275 3. Running LayerManagerControl
 276
 277 The LayerManagerControl can be used to change and debug
 278 the runtime behaviour of the service.
 279
 280 Please Call :
 281 LayerManagerControl without arguments to see a list of supported commands
 282
 283 Examples
 284         LayerManagerControl get scene
 285         LayerManagerControl get layers
 286         LayerManagerControl get layer 1000
 287         LayerManagerControl get surfaces
 288         LayerManagerControl get surface 0xa
 289         LayerManagerControl analyze surface 10
 290         LayerManagerControl scatter
 291         LayerManagerControl watch surface 0xa
 292
 293 precondition :
 294
 295 install prefix is /usr/local
 296 LayerManagerService Running
 297
 298 run:
 299 #> export DISPLAY=:0
 300 #> export LD_LIBRARY_PATH=/usr/local/lib:/usr/lib
 301 #> LayerManagerControl [command]
 302