1 /*************************************************************************** 2 * 3 * Copyright 2010,2011 BMW Car IT GmbH 4 * Copyright (c) 2012, NVIDIA CORPORATION. All rights reserved. 5 * 6 * 7 * Licensed under the Apache License, Version 2.0 (the "License"); 8 * you may not use this file except in compliance with the License. 9 * You may obtain a copy of the License at 10 * 11 * http://www.apache.org/licenses/LICENSE-2.0 12 * 13 * Unless required by applicable law or agreed to in writing, software 14 * distributed under the License is distributed on an "AS IS" BASIS, 15 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 16 * See the License for the specific language governing permissions and 17 * limitations under the License. 18 * 19 ****************************************************************************/ 20 #ifndef _ILM_CONTROL_H_ 21 #define _ILM_CONTROL_H_ 22 23 #ifdef __cplusplus 24 extern "C" { 25 #endif /* __cplusplus */ 26 27 #include "ilm_common.h" 28 29 /** 30 * \brief Get the surface properties from the Layermanagement 31 * \ingroup ilmControl 32 * \param[in] surfaceID surface Indentifier as a Number from 0 .. MaxNumber of Surfaces 33 * \param[out] pSurfaceProperties pointer where the surface properties should be stored 34 * \return ILM_SUCCESS if the method call was successful 35 * \return ILM_FAILED if the client can not get the resolution. 36 */ 37 ilmErrorTypes ilm_getPropertiesOfSurface(t_ilm_uint surfaceID, struct ilmSurfaceProperties* pSurfaceProperties); 38 39 /** 40 * \brief Get the layer properties from the Layermanagement 41 * \ingroup ilmControl 42 * \param[in] layerID layer Indentifier as a Number from 0 .. MaxNumber of Layer 43 * \param[out] pLayerProperties pointer where the layer properties should be stored 44 * \return ILM_SUCCESS if the method call was successful 45 * \return ILM_FAILED if the client can not get the resolution. 46 */ 47 ilmErrorTypes ilm_getPropertiesOfLayer(t_ilm_uint layerID, struct ilmLayerProperties* pLayerProperties); 48 49 /** 50 * \brief Get the screen properties from the Layermanagement 51 * \ingroup ilmControl 52 * \param[in] screenID screen Indentifier 53 * \param[out] pScreenProperties pointer where the screen properties should be stored 54 * \return ILM_SUCCESS if the method call was successful 55 * \return ILM_FAILED if the client can not get the resolution. 56 */ 57 ilmErrorTypes ilm_getPropertiesOfScreen(t_ilm_display screenID, struct ilmScreenProperties* pScreenProperties); 58 59 /** 60 * \brief Get the screen Ids 61 * \ingroup ilmControl 62 * \param[out] pNumberOfIDs pointer where the number of Screen Ids should be returned 63 * \param[out] ppIDs pointer to array where the IDs should be stored, 64 * memory for ppIDs is internally allocated with malloc 65 * \return ILM_SUCCESS if the method call was successful 66 * \return ILM_FAILED if the client can not get the resolution. 67 */ 68 ilmErrorTypes ilm_getScreenIDs(t_ilm_uint* pNumberOfIDs, t_ilm_uint** ppIDs); 69 70 /** 71 * \brief Get the screen resolution of a specific screen from the Layermanagement 72 * \ingroup ilmClient 73 * \param[in] screenID Screen Indentifier as a Number from 0 .. MaxNumber of Screens 74 * \param[out] pWidth pointer where width of screen should be stored 75 * \param[out] pHeight pointer where height of screen should be stored 76 * \return ILM_SUCCESS if the method call was successful 77 * \return ILM_FAILED if the client can not get the resolution. 78 */ 79 ilmErrorTypes ilm_getScreenResolution(t_ilm_uint screenID, t_ilm_uint* pWidth, t_ilm_uint* pHeight); 80 81 /** 82 * \brief Get all LayerIds which are currently registered and managed by the service 83 * \ingroup ilmControl 84 * \param[out] pLength Pointer where length of ids array should be stored 85 * \param[out] ppArray Array where the ids should be stored, 86 * memory for ppIDs is internally allocated with malloc 87 * \return ILM_SUCCESS if the method call was successful 88 * \return ILM_FAILED if the client can not call the method on the service. 89 */ 90 ilmErrorTypes ilm_getLayerIDs(t_ilm_int* pLength, t_ilm_layer** ppArray); 91 92 /** 93 * \brief Get all LayerIds of the given screen 94 * \ingroup ilmControl 95 * \param[in] screenID The id of the screen to get the layer IDs of 96 * \param[out] pLength Pointer where length of ids array should be stored 97 * \param[out] ppArray Array where the ids should be stored, 98 * the array will be allocated inside 99 * \return ILM_SUCCESS if the method call was successful 100 * \return ILM_FAILED if the client can not call the method on the service. 101 */ 102 ilmErrorTypes ilm_getLayerIDsOnScreen(t_ilm_uint screenID, t_ilm_int* pLength, t_ilm_layer** ppArray); 103 104 /** 105 * \brief Get all SurfaceIDs which are currently registered and managed by the service 106 * \ingroup ilmControl 107 * \param[out] pLength Pointer where length of ids array should be stored 108 * \param[out] ppArray Array where the ids should be stored, 109 * memory for ppIDs is internally allocated with malloc 110 * \return ILM_SUCCESS if the method call was successful 111 * \return ILM_FAILED if the client can not call the method on the service. 112 */ 113 ilmErrorTypes ilm_getSurfaceIDs(t_ilm_int* pLength, t_ilm_surface** ppArray); 114 115 /** 116 * \brief Get all SurfaceIds which are currently registered to a given layer and are managed by the service 117 * \ingroup ilmControl 118 * \param[in] layer Id of the Layer whose surfaces are to be returned 119 * \param[out] pLength Pointer where the array length of ids should be stored 120 * \param[out] ppArray Array where the surface id should be stored, 121 * memory for ppIDs is internally allocated with malloc 122 * \return ILM_SUCCESS if the method call was successful 123 * \return ILM_FAILED if the client can not call the method on the service. 124 */ 125 ilmErrorTypes ilm_getSurfaceIDsOnLayer(t_ilm_layer layer, t_ilm_int* pLength, t_ilm_surface** ppArray); 126 127 /** 128 * \brief Create a layer which should be managed by the service 129 * \ingroup ilmControl 130 * \param[out] pLayerId pointer where the id should be passed 131 * \param[in] width horizontal dimension of the layer 132 * \param[in] height vertical dimension of the layer 133 * \return ILM_SUCCESS if the method call was successful 134 * \return ILM_FAILED if the client can not call the method on the service. 135 */ 136 ilmErrorTypes ilm_layerCreateWithDimension(t_ilm_layer* pLayerId, t_ilm_uint width, t_ilm_uint height); 137 138 /** 139 * \brief Removes a layer which is currently managed by the service 140 * \ingroup ilmControl 141 * \param[in] layerId Layer to be removed 142 * \return ILM_SUCCESS if the method call was successful 143 * \return ILM_FAILED if the client can not call the method on the service. 144 */ 145 ilmErrorTypes ilm_layerRemove(t_ilm_layer layerId); 146 147 /** 148 * \brief Add a surface to a layer which is currently managed by the service 149 * \ingroup ilmClient 150 * \param[in] layerId Id of layer which should host the surface. 151 * \param[in] surfaceId Id of surface which should be added to the layer. 152 * \return ILM_SUCCESS if the method call was successful 153 * \return ILM_FAILED if the client can not call the method on the service. 154 */ 155 ilmErrorTypes ilm_layerAddSurface(t_ilm_layer layerId, t_ilm_surface surfaceId); 156 157 /** 158 * \brief Removes a surface from a layer which is currently managed by the service 159 * \ingroup ilmClient 160 * \param[in] layerId Id of the layer which contains the surface. 161 * \param[in] surfaceId Id of the surface which should be removed from the layer. 162 * \return ILM_SUCCESS if the method call was successful 163 * \return ILM_FAILED if the client can not call the method on the service. 164 */ 165 ilmErrorTypes ilm_layerRemoveSurface(t_ilm_layer layerId, t_ilm_surface surfaceId); 166 167 /** 168 * \brief Set the visibility of a layer. If a layer is not visible, the layer and its 169 * surfaces will not be rendered. 170 * \ingroup ilmControl 171 * \param[in] layerId Id of the layer. 172 * \param[in] newVisibility ILM_TRUE sets layer visible, ILM_FALSE disables the visibility. 173 * \return ILM_SUCCESS if the method call was successful 174 * \return ILM_FAILED if the client can not call the method on the service. 175 */ 176 ilmErrorTypes ilm_layerSetVisibility(t_ilm_layer layerId, t_ilm_bool newVisibility); 177 178 /** 179 * \brief Get the visibility of a layer. If a layer is not visible, the layer and its 180 * surfaces will not be rendered. 181 * \ingroup ilmControl 182 * \param[in] layerId Id of layer. 183 * \param[out] pVisibility pointer where the visibility of the layer should be stored 184 * ILM_TRUE if the Layer is visible, 185 * ILM_FALSE if the visibility is disabled. 186 * \return ILM_SUCCESS if the method call was successful 187 * \return ILM_FAILED if the client can not call the method on the service. 188 */ 189 ilmErrorTypes ilm_layerGetVisibility(t_ilm_layer layerId, t_ilm_bool *pVisibility); 190 191 /** 192 * \brief Set the opacity of a layer. 193 * \ingroup ilmControl 194 * \param[in] layerId Id of the layer. 195 * \param[in] opacity 0.0 means the layer is fully transparent, 196 * 1.0 means the layer is fully opaque 197 * \return ILM_SUCCESS if the method call was successful 198 * \return ILM_FAILED if the client can not call the method on the service. 199 */ 200 ilmErrorTypes ilm_layerSetOpacity(t_ilm_layer layerId, t_ilm_float opacity); 201 202 /** 203 * \brief Get the opacity of a layer. 204 * \ingroup ilmControl 205 * \param[in] layerId Id of the layer to obtain the opacity of. 206 * \param[out] pOpacity pointer where the layer opacity should be stored. 207 * 0.0 means the layer is fully transparent, 208 * 1.0 means the layer is fully opaque 209 * \return ILM_SUCCESS if the method call was successful 210 * \return ILM_FAILED if the client can not call the method on the service. 211 */ 212 ilmErrorTypes ilm_layerGetOpacity(t_ilm_layer layerId, t_ilm_float *pOpacity); 213 214 /** 215 * \brief Set the area of a layer which should be used for the rendering. Only this part will be visible. 216 * \ingroup ilmControl 217 * \param[in] layerId Id of the layer. 218 * \param[in] x horizontal start position of the used area 219 * \param[in] y vertical start position of the used area 220 * \param[in] width width of the area 221 * \param[in] height height of the area 222 * \return ILM_SUCCESS if the method call was successful 223 * \return ILM_FAILED if the client can not call the method on the service. 224 */ 225 ilmErrorTypes ilm_layerSetSourceRectangle(t_ilm_layer layerId, t_ilm_uint x, t_ilm_uint y, t_ilm_uint width, t_ilm_uint height); 226 227 /** 228 * \brief Set the destination area on the display for a layer. The layer will be scaled and positioned to this rectangle for rendering 229 * \ingroup ilmControl 230 * \param[in] layerId Id of the layer. 231 * \param[in] x horizontal start position of the used area 232 * \param[in] y vertical start position of the used area 233 * \param[in] width width of the area 234 * \param[in] height height of the area 235 * \return ILM_SUCCESS if the method call was successful 236 * \return ILM_FAILED if the client can not call the method on the service. 237 */ 238 ilmErrorTypes ilm_layerSetDestinationRectangle(t_ilm_layer layerId, t_ilm_int x, t_ilm_int y, t_ilm_int width, t_ilm_int height); 239 240 /** 241 * \brief Sets render order of surfaces within one layer 242 * \ingroup ilmControl 243 * \param[in] layerId Id of layer. 244 * \param[in] pSurfaceId array of surface ids 245 * \param[in] number Number of elements in the given array of ids 246 * \return ILM_SUCCESS if the method call was successful 247 * \return ILM_FAILED if the client can not call the method on the service. 248 */ 249 ilmErrorTypes ilm_layerSetRenderOrder(t_ilm_layer layerId, t_ilm_layer *pSurfaceId, t_ilm_int number); 250 251 /** 252 * \brief Set the visibility of a surface. If a surface is not visible it will not be rendered. 253 * \ingroup ilmControl 254 * \param[in] surfaceId Id of the surface to set the visibility of 255 * \param[in] newVisibility ILM_TRUE sets surface visible, ILM_FALSE disables the visibility. 256 * \return ILM_SUCCESS if the method call was successful 257 * \return ILM_FAILED if the client can not call the method on the service. 258 */ 259 ilmErrorTypes ilm_surfaceSetVisibility(t_ilm_surface surfaceId, t_ilm_bool newVisibility); 260 261 /** 262 * \brief Get the visibility of a surface. If a surface is not visible, the surface 263 * will not be rendered. 264 * \ingroup ilmClient 265 * \param[in] surfaceId Id of the surface to get the visibility of. 266 * \param[out] pVisibility pointer where the visibility of a surface should be stored 267 * ILM_TRUE if the surface is visible, 268 * ILM_FALSE if the visibility is disabled. 269 * \return ILM_SUCCESS if the method call was successful 270 * \return ILM_FAILED if the client can not call the method on the service. 271 */ 272 ilmErrorTypes ilm_surfaceGetVisibility(t_ilm_surface surfaceId, t_ilm_bool *pVisibility); 273 274 /** 275 * \brief Set the opacity of a surface. 276 * \ingroup ilmControl 277 * \param surfaceId Id of the surface to set the opacity of. 278 * \param opacity 0.0 means the surface is fully transparent, 279 * 1.0 means the surface is fully opaque 280 * \return ILM_SUCCESS if the method call was successful 281 * \return ILM_FAILED if the client can not call the method on the service. 282 */ 283 ilmErrorTypes ilm_surfaceSetOpacity(const t_ilm_surface surfaceId, t_ilm_float opacity); 284 285 /** 286 * \brief Get the opacity of a surface. 287 * \ingroup ilmControl 288 * \param[in] surfaceId Id of the surface to get the opacity of. 289 * \param[out] pOpacity pointer where the surface opacity should be stored. 290 * 0.0 means the surface is fully transparent, 291 * 1.0 means the surface is fully opaque 292 * \return ILM_SUCCESS if the method call was successful 293 * \return ILM_FAILED if the client can not call the method on the service. 294 */ 295 ilmErrorTypes ilm_surfaceGetOpacity(const t_ilm_surface surfaceId, t_ilm_float *pOpacity); 296 297 /** 298 * \brief Set the area of a surface which should be used for the rendering. 299 * \ingroup ilmControl 300 * \param[in] surfaceId Id of surface. 301 * \param[in] x horizontal start position of the used area 302 * \param[in] y vertical start position of the used area 303 * \param[in] width width of the area 304 * \param[in] height height of the area 305 * \return ILM_SUCCESS if the method call was successful 306 * \return ILM_FAILED if the client can not call the method on the service. 307 */ 308 ilmErrorTypes ilm_surfaceSetSourceRectangle(t_ilm_surface surfaceId, t_ilm_int x, t_ilm_int y, t_ilm_int width, t_ilm_int height); 309 310 /** 311 * \brief Set the destination area of a surface within a layer for rendering. The surface will be scaled to this rectangle for rendering. 312 * \ingroup ilmControl 313 * \param[in] surfaceId Id of surface. 314 * \param[in] x horizontal start position of the used area 315 * \param[in] y vertical start position of the used area 316 * \param[in] width width of the area 317 * \param[in] height height of the area 318 * \return ILM_SUCCESS if the method call was successful 319 * \return ILM_FAILED if the client can not call the method on the service. 320 */ 321 ilmErrorTypes ilm_surfaceSetDestinationRectangle(t_ilm_surface surfaceId, t_ilm_int x, t_ilm_int y, t_ilm_int width, t_ilm_int height); 322 323 /** 324 * \brief Set the type of a surface. If a surface is not visible it will not be rendered. 325 * If a surface is restricted type, visible contents of the surface is strictly 326 * controlled by the compositor. Its content is not allowed to be go out of 327 * its destination region. If the application resizes its buffers or uses 328 * wp_viewporter protocol to scale its contents, the old destination region 329 * would causes visible glitches. 330 * To avoid these issues, the controller process mark a surface as desktop 331 * compatible. Source and destination regions of a desktop compatible 332 * surface will be modified accordingly,when application sends a request 333 * for resizing or scaling its contents. Therefore, applications contents 334 * will be drawn according to application's wishes. 335 * On the other hand, source and destination regions will be strictly 336 * enforced, when the surface's type is restricted. The default type for 337 * a surface is restricted. 338 * \ingroup ilmControl 339 * \param[in] surfaceId Id of the surface to set the type of 340 * \param[in] type Type of the surface 341 * \return ILM_SUCCESS if the method call was successful 342 * \return ILM_FAILED if the client can not call the method on the service. 343 */ 344 ilmErrorTypes ilm_surfaceSetType(t_ilm_surface surfaceId, ilmSurfaceType type); 345 346 /** 347 * \brief Sets render order of layers on a display 348 * \ingroup ilmControl 349 * \param[in] display Id of display to set the given order of layers. 350 * \param[in] pLayerId array of layer ids 351 * \param[in] number number of layerids in the given array 352 * \return ILM_SUCCESS if the method call was successful 353 * \return ILM_FAILED if the client can not call the method on the service. 354 */ 355 ilmErrorTypes ilm_displaySetRenderOrder(t_ilm_display display, t_ilm_layer *pLayerId, const t_ilm_uint number); 356 357 /** 358 * \brief Take a screenshot from the current displayed layer scene. 359 * The screenshot is saved as bmp file with the corresponding filename. 360 * \ingroup ilmControl 361 * \param[in] screen Id of screen where screenshot should be taken 362 * \param[in] filename Location where the screenshot should be stored 363 * \return ILM_SUCCESS if the method call was successful 364 * \return ILM_FAILED if the client can not call the method on the service. 365 */ 366 ilmErrorTypes ilm_takeScreenshot(t_ilm_uint screen, t_ilm_const_string filename); 367 368 /** 369 * \brief Take a screenshot of a certain surface 370 * The screenshot is saved as bmp file with the corresponding filename. 371 * \ingroup ilmControl 372 * \param[in] filename Location where the screenshot should be stored 373 * \param[in] surfaceid Identifier of the surface to take the screenshot of 374 * \return ILM_SUCCESS if the method call was successful 375 * \return ILM_FAILED if the client can not call the method on the service. 376 */ 377 ilmErrorTypes ilm_takeSurfaceScreenshot(t_ilm_const_string filename, t_ilm_surface surfaceid); 378 379 /** 380 * \brief Take a screenshot from the current displayed layer scene. 381 * The screenshot return immage data buffer. 382 * \ingroup ilmControl 383 * \param[in] screen Id of screen where screenshot should be taken 384 * \param[in] doneCb pointer of callback when shot done and return buffer 385 * \return ILM_SUCCESS if the method call was successful 386 * \return ILM_FAILED if the client can not call the method on the service. 387 */ 388 ilmErrorTypes ilm_takeScreenshot_buffer(t_ilm_uint screen, shotdoneNotificationFunc doneCb); 389 390 /** 391 * \brief Take a screenshot of a certain surface 392 * The screenshot The screenshot return immage data buffer.. 393 * \ingroup ilmControl 394 * \param[in] surfaceid Identifier of the surface to take the screenshot of 395 * \param[in] doneCb pointer of callback when shot done and return buffer 396 * \return ILM_SUCCESS if the method call was successful 397 * \return ILM_FAILED if the client can not call the method on the service. 398 */ 399 ilmErrorTypes ilm_takeSurfaceScreenshot_buffer(t_ilm_surface surfaceid, shotdoneNotificationFunc doneCb); 400 401 /** 402 * \brief register for notification on property changes of layer 403 * \ingroup ilmControl 404 * \param[in] layer id of layer to register for notification 405 * \param[in] callback pointer to function to be called for notification 406 * \return ILM_SUCCESS if the method call was successful 407 * \return ILM_FAILED if the client can not call the method on the service. 408 * \return ILM_ERROR_INVALID_ARGUMENT if the given layer already has notification callback registered 409 */ 410 ilmErrorTypes ilm_layerAddNotification(t_ilm_layer layer, layerNotificationFunc callback); 411 412 /** 413 * \brief remove notification on property changes of layer 414 * \ingroup ilmControl 415 * \param[in] layer id of layer to remove notification 416 * \return ILM_SUCCESS if the method call was successful 417 * \return ILM_FAILED if the client can not call the method on the service. 418 * \return ILM_ERROR_INVALID_ARGUMENT if the given layer has no notification callback registered 419 */ 420 ilmErrorTypes ilm_layerRemoveNotification(t_ilm_layer layer); 421 422 /** 423 * \brief register for notification on property changes of surface 424 * \ingroup ilmControl 425 * \param[in] surface id of surface to register for notification 426 * \param[in] callback pointer to function to be called for notification 427 * \return ILM_SUCCESS if the method call was successful 428 * \return ILM_FAILED if the client can not call the method on the service. 429 * \return ILM_ERROR_INVALID_ARGUMENT if the given surface already has notification callback registered 430 */ 431 ilmErrorTypes ilm_surfaceAddNotification(t_ilm_surface surface, surfaceNotificationFunc callback); 432 433 /** 434 * \brief remove notification on property changes of surface 435 * \ingroup ilmControl 436 * \param[in] surface id of surface to remove notification 437 * \return ILM_SUCCESS if the method call was successful 438 * \return ILM_FAILED if the client can not call the method on the service. 439 * \return ILM_ERROR_INVALID_ARGUMENT if the given surface has no notification callback registered 440 */ 441 ilmErrorTypes ilm_surfaceRemoveNotification(t_ilm_surface surface); 442 443 /** 444 * \brief register notification callback for creation/deletion of ilm surfaces/layers 445 * \ingroup ilmControl 446 * \param[in] callback pointer to function to be called for notification 447 callback function is defined as: 448 void cb(ilmObjectType o, t_ilm_uint id, t_ilm_bool created, void *user_data) 449 * \param[in] user_data pointer to data which will be passed to a notification callback 450 * \return ILM_SUCCESS if the method call was successful 451 * \return ILM_FAILED if the client can not call the method on the service. 452 */ 453 ilmErrorTypes ilm_registerNotification(notificationFunc callback, void *user_data); 454 455 /** 456 * \brief unregister notification for creation/deletion events of ilm surfaces/layers 457 * \ingroup ilmControl 458 * \return ILM_SUCCESS if the method call was successful 459 * \return ILM_FAILED if the client can not call the method on the service. 460 */ 461 ilmErrorTypes ilm_unregisterNotification(); 462 463 /** 464 * \brief returns the global error flag. 465 * When compositor sends an error, the error flag is set to appropriate error code 466 * value. No other errors are recorded until ilm_getError is called. Calling this 467 * API sets the error flag to ILM_SUCCESS. 468 * \ingroup ilmControl 469 * \return ILM_SUCCESS if there is no error 470 * \return ILM_FAILED if the method call has failed 471 * \return ILM_ERROR_INVALID_ARGUMENTS, if an invalid arguments error has occurred 472 * \return ILM_ERROR_ON_CONNECTION, if a connection error has occurred 473 * \return ILM_ERROR_RESOURCE_ALREADY_INUSE, if resource is already in use 474 * \return ILM_ERROR_RESOURCE_NOT_FOUND, if resource was not found 475 * \return ILM_ERROR_NOT_IMPLEMENTED, if feature is not implemented 476 * \return ILM_ERROR_UNEXPECTED_MESSAGE, if received message has unexpected type 477 */ 478 ilmErrorTypes ilm_getError(); 479 #ifdef __cplusplus 480 } /**/ 481 #endif /* __cplusplus */ 482 483 #endif /* _ILM_CONTROL_H_ */ 484