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 with XTHREAD support, switches continous rendering to event based rendering
 203   Option: -DWITH_XTHREADS=ON or
 204           -DWITH_XTHREADS=OFF
 205
 206 - Build available tests
 207   Option: -DWITH_TESTS=ON or
 208           -DWITH_TESTS=OFF
 209
 210   Remark: Test File are currently not upstreamed.
 211
 212 - Build for different Platforms
 213
 214   You have the choice to use GLXRenderer or X11GLESRenderer.
 215
 216   GLXRenderer (X11Renderer.so) which is normaly used for a Desktop, VMWare Image and GMA500 based Headunits
 217
 218   cmake <source-dir>/ -DWITH_DESKTOP=ON -DWITH_GLX_EXAMPLE=ON -DWITH_XTHREADS=ON -DWITH_TESTS=OFF -DWITH_EGL_EXAMPLE=OFF -DWITH_X11_GLES=OFF
 219
 220   X11GLESRenderer which is used on more embedded device which are supporting EGL and OpenGL ES 2.0
 221
 222   cmake <source-dir>/ -DWITH_DESKTOP=OFF -DWITH_GLX_EXAMPLE=OFF -DWITH_TESTS=OFF -DWITH_EGL_EXAMPLE=ON -DWITH_X11_GLES=ON -DWITH_XTHREADS=ON
 223
 224 Change the Environment during Runtime
 225 =====================================
 226 The following environments can be set to change the runtime behaviour.
 227
 228 LM_PLUGIN_PATH          set the path for the location of communicator and renderer PlugIns
 229                         default : /usr/lib/layermanager
 230                         Example : export LM_PLUGIN_PATH= /usr/local/lib/layermanager
 231
 232 LM_USE_SESSION_BUS      enables the DBUS communication to run on Session bus instead of Systembus
 233                         default : disabled run on system bus
 234                         Example : export LM_USE_SESSION_BUS=enable
 235
 236 Commandline parameter :
 237 LayerManagerService : -w<horizontalresolution> - default 1280
 238                       -h<verticalresolution> - default 480
 239                       -c<console debug level> - default 2 (only errors and info)
 240                       -f<file debug level> - default 0 (disabled) log file location is /tmp/LayerManagerService.log
 241                       possible debug levels :   0 disabled
 242                                                 1 errors
 243                                                 2 info,errors
 244                                                 3 info,errors, warnings
 245                                                 4 info,errors, warnings,debug
 246                       -v shows version of layermanager
 247
 248 Running Testapplications
 249 =====================================
 250
 251 1. Starting the service
 252
 253 precondition :
 254
 255 install prefix is /usr/local
 256 no compositing manager is running like openbox xfce metacity, kill these if needed
 257
 258 run:
 259 #> export DISPLAY=:0
 260 #> export LD_LIBRARY_PATH=/usr/local/lib:/usr/lib
 261 #> export LM_PLUGIN_PATH=/usr/local/lib/layermanager
 262 #> LayerManagerService &
 263
 264 2. Running OpenGL / OpenGL ES 2.0 Example Applications
 265
 266 precondition :
 267
 268 install prefix is /usr/local
 269 LayerManagerService Running
 270
 271 run:
 272 #> export DISPLAY=:0
 273 #> export LD_LIBRARY_PATH=/usr/local/lib:/usr/lib
 274 OpenGL ES Example
 275 #> EGLX11ApplicationExample &
 276 OpenGL Example
 277 #> GLX11ApplicationExample &
 278
 279 3. Running LayerManagerToolBox
 280
 281 The LayerManagerToolbox can be used to change and debug
 282 the runtime behaviour of the service.
 283
 284 Please Call :
 285 LayerManagerToolBox -? to see the expected parameter
 286
 287 Example LayerManagerToolBox --change-surface sid:[0xa],src:[0,0,320,240],dest:[0,0,800,480],o:[1.0],v:[1]
 288
 289 precondition :
 290
 291 install prefix is /usr/local
 292 LayerManagerService Running
 293
 294 run:
 295 #> export DISPLAY=:0
 296 #> export LD_LIBRARY_PATH=/usr/local/lib:/usr/lib
 297 #> LayerManagerToolbox [options]
 298