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