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