1<?xml version="1.0" encoding="UTF-8"?> 2<protocol name="ivi_wm"> 3 4 <copyright> 5 Copyright (C) 2017 Advanced Driver Information Technology Joint Venture GmbH 6 7 Permission is hereby granted, free of charge, to any person obtaining a copy 8 of this software and associated documentation files (the "Software"), to deal 9 in the Software without restriction, including without limitation the rights 10 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 11 copies of the Software, and to permit persons to whom the Software is 12 furnished to do so, subject to the following conditions: 13 14 The above copyright notice and this permission notice shall be included in 15 all copies or substantial portions of the Software. 16 17 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 18 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 19 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 20 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 21 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 22 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 23 THE SOFTWARE. 24 </copyright> 25 26 <interface name="ivi_wm_screen" version="1"> 27 <description summary="controller interface to screen in ivi compositor"/> 28 29 <request name="destroy" type="destructor"> 30 <description summary="destroy ivi_wm_screen"> 31 Request to destroy the ivi_wm_screen. 32 </description> 33 </request> 34 35 <request name="clear"> 36 <description summary="remove all layers from screen render order"> 37 A screen has no content assigned to itself, it is a container for layers. 38 This request removes all layers from the screen render order. 39 Note: the layers are not destroyed, they are just no longer contained by 40 the screen. 41 </description> 42 </request> 43 44 <request name="add_layer"> 45 <description summary="add a layer to screen render order at nearest z-position"> 46 A screen has no content assigned to itself, it is a container for layers. 47 This request adds a layers to the topmost position of the screen render order. 48 The added layer will cover all other layers of the screen. 49 </description> 50 <arg name="layer_id" type="uint"/> 51 </request> 52 53 <request name="remove_layer"> 54 <description summary="remove a layer to screen render order"> 55 A screen has no content assigned to itself, it is a container for layers. 56 This request removes a layer. 57 </description> 58 <arg name="layer_id" type="uint"/> 59 </request> 60 61 <request name="screenshot"> 62 <description summary="take screenshot of screen"> 63 An ivi_screenshot object is created which will receive the screenshot 64 data of the specified output. 65 </description> 66 <arg name="screenshot" type="new_id" interface="ivi_screenshot"/> 67 </request> 68 69 <request name="get"> 70 <description summary="get a parameter of a screen in ivi compositor"> 71 After this request, compositor sends the requested parameter. 72 </description> 73 <arg name="param" type="int"/> 74 </request> 75 76 <event name="screen_id"> 77 <description summary="advertise server side id of the ivi-screen"> 78 Sent immediately after creating the ivi_wm_screen object. 79 </description> 80 <arg name="id" type="uint"/> 81 </event> 82 83 <event name="layer_added"> 84 <description summary="update render order of the screen"> 85 A layer is added to the render order lisf of the screen 86 </description> 87 <arg name="layer_id" type="uint"/> 88 </event> 89 90 <event name="connector_name"> 91 <description summary="advertise connector name of the corresponding output"> 92 Sent immediately after creating the ivi_wm_screen object. 93 </description> 94 <arg name="process_name" type="string"/> 95 </event> 96 97 <enum name="error"> 98 <entry name="no_layer" value="0" 99 summary="the layer with given id does not exist"/> 100 <entry name="no_screen" value="1" 101 summary="the output is already destroyed"/> 102 <entry name="bad_param" value="2" 103 summary="the given parameter is not valid"/> 104 </enum> 105 106 <event name="error"> 107 <description summary="error event"> 108 The error event is sent out when an error has occurred. 109 </description> 110 <arg name="error" type="uint" summary="error code"/> 111 <arg name="message" type="string" summary="error description"/> 112 </event> 113 </interface> 114 115 <interface name="ivi_screenshot" version="1"> 116 <description summary="screenshot of an output or a surface"> 117 An ivi_screenshot object receives a single "done" or "error" event. 118 The server will destroy this resource after the event has been send, 119 so the client shall then destroy its proxy too. 120 </description> 121 122 <event name="done"> 123 <description summary="screenshot finished"> 124 This event contains a filedescriptor for a file with raw image data. 125 Furthermore size, stride, format and timestamp of screenshot are 126 provided. 127 </description> 128 <arg name="fd" type="fd" summary="fd for file containing image data"/> 129 <arg name="width" type="int" summary="image width in pixels"/> 130 <arg name="height" type="int" summary="image height in pixels"/> 131 <arg name="stride" type="int" summary="number of bytes per pixel row"/> 132 <arg name="format" type="uint" summary="image format of type wl_shm.format"/> 133 <arg name="timestamp" type="uint" summary="timestamp in milliseconds"/> 134 </event> 135 136 <enum name="error"> 137 <entry name="io_error" value="0" 138 summary="screenshot file could not be created"/> 139 <entry name="not_supported" value="1" 140 summary="screenshot can not be read"/> 141 <entry name="no_output" value="2" 142 summary="output has been destroyed"/> 143 <entry name="no_surface" value="3" 144 summary="surface has been destroyed"/> 145 <entry name="no_content" value="4" 146 summary="surface has no content"/> 147 </enum> 148 149 <event name="error"> 150 <description summary="error event"> 151 The error event is sent when the screenshot could not be created. 152 </description> 153 <arg name="error" type="uint" enum="error" summary="error code"/> 154 <arg name="message" type="string" summary="error description"/> 155 </event> 156 </interface> 157 158 <interface name="ivi_wm" version="1"> 159 <description summary="interface for ivi managers to use ivi compositor features"/> 160 161 <request name="commit_changes"> 162 <description summary="commit all changes requested by client"> 163 All requests are not applied directly to scene object, so a controller 164 can set different properties and apply the changes all at once. 165 Note: there's an exception to this. Creation and destruction of 166 scene objects is executed immediately. 167 </description> 168 </request> 169 170 <request name="create_screen"> 171 <description summary="create a screen in ivi-compositor"> 172 Ask the ivi-wm to create a ivi-screen for given wl_output. 173 </description> 174 <arg name="output" type="object" interface="wl_output"/> 175 <arg name="id" type="new_id" interface="ivi_wm_screen" summary="the new ivi-screen"/> 176 </request> 177 178 <request name="create_screen2"> 179 <description summary="create a screen in ivi-compositor"> 180 Ask the ivi-wm to create a ivi-screen for given wl_output. 181 </description> 182 <arg name="screen_id" type="uint"/> 183 <arg name="id" type="new_id" interface="ivi_wm_screen" summary="the new ivi-screen"/> 184 </request> 185 186 <request name="set_surface_visibility"> 187 <description summary="set the visibility of a surface in ivi compositor"> 188 If visibility argument is 0, the surface in the ivi compositor is set to invisible. 189 If visibility argument is not 0, the surface in the ivi compositor is set to visible. 190 </description> 191 <arg name="surface_id" type="uint"/> 192 <arg name="visibility" type="uint"/> 193 </request> 194 195 <request name="set_layer_visibility"> 196 <description summary="set visibility of layer in ivi compositor"> 197 If visibility argument is 0, the layer in the ivi compositor is set to invisible. 198 If visibility argument is not 0, the layer in the ivi compositor is set to visible. 199 </description> 200 <arg name="layer_id" type="uint"/> 201 <arg name="visibility" type="uint"/> 202 </request> 203 204 <request name="set_surface_opacity"> 205 <description summary="set the opacity of a surface in ivi compositor"> 206 The valid range for opacity is 0.0 (fully transparent) to 1.0 (fully opaque). 207 </description> 208 <arg name="surface_id" type="uint"/> 209 <arg name="opacity" type="fixed"/> 210 </request> 211 212 <request name="set_layer_opacity"> 213 <description summary="set opacity of layer in ivi compositor"> 214 The valid range for opacity is 0.0 (fully transparent) to 1.0 (fully opaque). 215 </description> 216 <arg name="layer_id" type="uint"/> 217 <arg name="opacity" type="fixed"/> 218 </request> 219 220 <request name="set_surface_source_rectangle"> 221 <description summary="set the scanout area of a surface in ivi compositor"> 222 The source rectangle defines the part of the surface content, that is used for 223 compositing the surface. It can be used, if valid content of the surface is smaller 224 than the surface. Effectively it can be used to zoom the content of the surface. 225 If a parameter is less than 0, that value is not changed. 226 x: horizontal start position of scanout area within the surface 227 y: vertical start position of scanout area within the surface 228 width: width of scanout area within the surface 229 height: height of scanout area within the surface 230 </description> 231 <arg name="surface_id" type="uint"/> 232 <arg name="x" type="int"/> 233 <arg name="y" type="int"/> 234 <arg name="width" type="int"/> 235 <arg name="height" type="int"/> 236 </request> 237 238 <request name="set_layer_source_rectangle"> 239 <description summary="set the scanout area of a layer in ivi compositor"> 240 The source rectangle defines the part of the layer content, that is used for 241 compositing the screen. It can be used, if valid content of the layer is smaller 242 than the layer. Effectively it can be used to zoom the content of the layer. 243 If a parameter is less than 0, that value is not changed. 244 x: horizontal start position of scanout area within the layer 245 y: vertical start position of scanout area within the layer 246 width: width of scanout area within the layer 247 height: height of scanout area within the layer 248 </description> 249 <arg name="layer_id" type="uint"/> 250 <arg name="x" type="int"/> 251 <arg name="y" type="int"/> 252 <arg name="width" type="int"/> 253 <arg name="height" type="int"/> 254 </request> 255 256 <request name="set_surface_destination_rectangle"> 257 <description summary="Set the destination area of a surface within a layer"> 258 The destination rectangle defines the position and size of a surface on a layer. 259 The surface will be scaled to this rectangle for rendering. 260 If a parameter is less than 0, that value is not changed. 261 x: horizontal start position of surface within the layer 262 y: vertical start position of surface within the layer 263 width : width of surface within the layer 264 height: height of surface within the layer 265 </description> 266 <arg name="surface_id" type="uint"/> 267 <arg name="x" type="int"/> 268 <arg name="y" type="int"/> 269 <arg name="width" type="int"/> 270 <arg name="height" type="int"/> 271 </request> 272 273 <request name="set_layer_destination_rectangle"> 274 <description summary="Set the destination area of a layer within a screen"> 275 The destination rectangle defines the position and size of a layer on a screen. 276 The layer will be scaled to this rectangle for rendering. 277 If a parameter is less than 0, that value is not changed. 278 x: horizontal start position of layer within the screen 279 y: vertical start position of layer within the screen 280 width : width of surface within the screen 281 height: height of surface within the screen 282 </description> 283 <arg name="layer_id" type="uint"/> 284 <arg name="x" type="int"/> 285 <arg name="y" type="int"/> 286 <arg name="width" type="int"/> 287 <arg name="height" type="int"/> 288 </request> 289 290 <enum name="sync"> 291 <description summary="sync request states"> 292 </description> 293 <entry name="add" value="0"/> 294 <entry name="remove" value="1"/> 295 </enum> 296 297 <request name="surface_sync"> 298 <description summary="request to synchronize of a surface in ivi compositor"> 299 After this request, compositor sends the properties of the surface. 300 If sync_state argument is 0, compositor sends the properties continously. 301 If sync_state argument is not 0, compositor stops sending the properties 302 continously. 303 </description> 304 <arg name="surface_id" type="uint"/> 305 <arg name="sync_state" type="int"/> 306 </request> 307 308 <request name="layer_sync"> 309 <description summary="request to synchronize of a layer in ivi compositor"> 310 After this request, compositor sends the properties of the layer. 311 If sync_state argument is 0, compositor sends the properties continously. 312 If sync_state argument is not 0, compositor stops sending the properties 313 continously. 314 </description> 315 <arg name="layer_id" type="uint"/> 316 <arg name="sync_state" type="int"/> 317 </request> 318 319 <enum name="param" bitfield="true"> 320 <description summary="parameter types"> 321 The HMI controller can request different types of parameters of an 322 ivi-object. 323 </description> 324 <entry name="opacity" value="1"/> 325 <entry name="visibility" value="2"/> 326 <entry name="size" value="4"/> 327 <entry name="render_order" value="8"/> 328 </enum> 329 330 <request name="surface_get"> 331 <description summary="get a parameter of an ivi_layout_surface in ivi compositor"> 332 After this request, compositor sends the requested parameter. 333 </description> 334 <arg name="surface_id" type="uint"/> 335 <arg name="param" type="int"/> 336 </request> 337 338 <request name="layer_get"> 339 <description summary="get a parameter of an ivi_layout_layer in ivi compositor"> 340 After this request, compositor sends the requested parameter. 341 </description> 342 <arg name="layer_id" type="uint"/> 343 <arg name="param" type="int"/> 344 </request> 345 346 <request name="surface_screenshot"> 347 <description summary="take screenshot of surface"> 348 An ivi_screenshot object is created which will receive an image of the 349 buffer currently attached to the surface with the given id. If there 350 is no surface with such name the server will respond with an 351 ivi_screenshot.error event. 352 </description> 353 <arg name="screenshot" type="new_id" interface="ivi_screenshot"/> 354 <arg name="surface_id" type="uint"/> 355 </request> 356 357 <enum name="surface_type"> 358 <description summary="hint for the compositor"> 359 If a surface is restricted type, visible contents of the surface is strictly 360 controlled by the compositor. Its content is not allowed to be go out of 361 its destination region. If the application resizes its buffers or uses 362 wp_viewporter protocol to scale its contents, the old destination region 363 would causes visible glitches. 364 To avoid these issues, the controller process mark a surface as desktop 365 compatible. Source and destination regions of a desktop compatible 366 surface will be modified accordingly,when application sends a request 367 for resizing or scaling its contents. Therefore, applications contents 368 will be drawn according to application's wishes. 369 On the other hand, source and destination regions will be strictly 370 enforced, when the surface's type is restricted. The default type for 371 a surface is ivi. 372 </description> 373 <entry name="restricted" value="0" summary="strictly controlled"/> 374 <entry name="desktop" value="1" summary="free to resize and scale"/> 375 </enum> 376 377 <request name="set_surface_type"> 378 <description summary="request to set a type for the surface in ivi compositor"> 379 After this request, compositor changes the type of the surface. 380 </description> 381 <arg name="surface_id" type="uint"/> 382 <arg name="type" type="int"/> 383 </request> 384 385 <request name="layer_clear"> 386 <description summary="remove all surfaces from layer render order"> 387 A layer has no content assigned to itself, it is a container for surfaces. 388 This request removes all surfaces from the layer render order. 389 </description> 390 <arg name="layer_id" type="uint"/> 391 </request> 392 393 <request name="layer_add_surface"> 394 <description summary="add a surface to layer render order at nearest z-position"> 395 A layer has no content assigned to itself, it is a container for surfaces. 396 This request adds a surface to the topmost position of the layer render order. 397 The added surface will cover all other surfaces of the layer. 398 </description> 399 <arg name="layer_id" type="uint"/> 400 <arg name="surface_id" type="uint"/> 401 </request> 402 403 <request name="layer_remove_surface"> 404 <description summary="remove a surface from layer render order"> 405 A layer has no content assigned to itself, it is a container for surfaces. 406 This request removes one surfaces from the layer render order. 407 Note: the surface is not destroyed, it is just no longer contained by 408 the layer. 409 </description> 410 <arg name="layer_id" type="uint"/> 411 <arg name="surface_id" type="uint"/> 412 </request> 413 414 <request name="create_layout_layer"> 415 <description summary="create an ivi_layout_layer in ivi compositor"> 416 After this request, compositor creates an ivi_layout_layer 417 </description> 418 <arg name="layer_id" type="uint"/> 419 <arg name="width" type="int"/> 420 <arg name="height" type="int"/> 421 </request> 422 423 <request name="destroy_layout_layer"> 424 <description summary="destroy an ivi_layout_layer in ivi compositor"> 425 After this request, compositor destroyes an existing ivi_layout_layer. 426 </description> 427 <arg name="layer_id" type="uint"/> 428 </request> 429 430 <event name="surface_visibility"> 431 <description summary="the visibility of the surface in ivi compositor has changed"> 432 The new visibility state is provided in argument visibility. 433 If visibility is 0, the surface has become invisible. 434 If visibility is not 0, the surface has become visible. 435 </description> 436 <arg name="surface_id" type="uint"/> 437 <arg name="visibility" type="int"/> 438 </event> 439 440 <event name="layer_visibility"> 441 <description summary="the visibility of the layer in ivi compositor has changed"> 442 The new visibility state is provided in argument visibility. 443 If visibility is 0, the layer has become invisible. 444 If visibility is not 0, the layer has become visible. 445 </description> 446 <arg name="layer_id" type="uint"/> 447 <arg name="visibility" type="int"/> 448 </event> 449 450 <event name="surface_opacity"> 451 <description summary="the opacity of surface in ivi compositor has changed"> 452 The new opacity state is provided in argument opacity. 453 The valid range for opactiy is 0.0 (fully transparent) to 1.0 (fully opaque). 454 </description> 455 <arg name="surface_id" type="uint"/> 456 <arg name="opacity" type="fixed"/> 457 </event> 458 459 <event name="layer_opacity"> 460 <description summary="the opacity of layer in ivi compositor has changed"> 461 The new opacity state is provided in argument opacity. 462 The valid range for opactiy is 0.0 (fully transparent) to 1.0 (fully opaque). 463 </description> 464 <arg name="layer_id" type="uint"/> 465 <arg name="opacity" type="fixed"/> 466 </event> 467 468 <event name="surface_source_rectangle"> 469 <description summary="the source rectangle of surface in ivi compositor has changed"> 470 The scanout region of the surface content has changed. 471 The new values for source rectangle are provided by 472 x: new horizontal start position of scanout area within the surface 473 y: new vertical start position of scanout area within the surface 474 width: new width of scanout area within the surface 475 height: new height of scanout area within the surface 476 </description> 477 <arg name="surface_id" type="uint"/> 478 <arg name="x" type="int"/> 479 <arg name="y" type="int"/> 480 <arg name="width" type="int"/> 481 <arg name="height" type="int"/> 482 </event> 483 484 <event name="layer_source_rectangle"> 485 <description summary="the source rectangle of layer in ivi compositor has changed"> 486 The scanout region of the layer content has changed. 487 The new values for source rectangle are provided by 488 x: new horizontal start position of scanout area within the layer 489 y: new vertical start position of scanout area within the layer 490 width: new width of scanout area within the layer 491 height: new height of scanout area within the layer 492 </description> 493 <arg name="layer_id" type="uint"/> 494 <arg name="x" type="int"/> 495 <arg name="y" type="int"/> 496 <arg name="width" type="int"/> 497 <arg name="height" type="int"/> 498 </event> 499 500 <event name="surface_destination_rectangle"> 501 <description summary="the destination rectangle of surface in ivi compositor has changed"> 502 The new values for source rectangle are provided by 503 x: new horizontal start position of surface within the layer 504 y: new vertical start position of surface within the layer 505 width : new width of surface within the layer 506 height: new height of surface within the layer 507 </description> 508 <arg name="surface_id" type="uint"/> 509 <arg name="x" type="int"/> 510 <arg name="y" type="int"/> 511 <arg name="width" type="int"/> 512 <arg name="height" type="int"/> 513 </event> 514 515 <event name="layer_destination_rectangle"> 516 <description summary="the destination rectangle of layer in ivi compositor has changed"> 517 The new values for source rectangle are provided by 518 x: new horizontal start position of layer within the screen 519 y: new vertical start position of layer within the screen 520 width : new width of layer within the screen 521 height: new height of layer within the screen 522 </description> 523 <arg name="layer_id" type="uint"/> 524 <arg name="x" type="int"/> 525 <arg name="y" type="int"/> 526 <arg name="width" type="int"/> 527 <arg name="height" type="int"/> 528 </event> 529 530 <event name="surface_created"> 531 <description summary="ivi_layout_surface was created"/> 532 <arg name="surface_id" type="uint"/> 533 </event> 534 535 <event name="layer_created"> 536 <description summary="ivi_layout_layer was created"/> 537 <arg name="layer_id" type="uint"/> 538 </event> 539 540 <event name="surface_destroyed"> 541 <description summary="ivi_layout_surface was destroyed"/> 542 <arg name="surface_id" type="uint"/> 543 </event> 544 545 <event name="layer_destroyed"> 546 <description summary="ivi_layout_layer was destroyed"/> 547 <arg name="layer_id" type="uint"/> 548 </event> 549 550 <enum name="surface_error"> 551 <entry name="no_surface" value="0" 552 summary="the surface with given id does not exist"/> 553 <entry name="bad_param" value="1" 554 summary="the given parameter is not valid"/> 555 <entry name="not_supported" value="2" 556 summary="the request is not supported"/> 557 </enum> 558 559 <event name="surface_error"> 560 <description summary="error event"> 561 The error event is sent out when an error has occurred. 562 </description> 563 <arg name="object_id" type="uint" summary="id of a layer or surface"/> 564 <arg name="error" type="uint" summary="error code"/> 565 <arg name="message" type="string" summary="error description"/> 566 </event> 567 568 <enum name="layer_error"> 569 <entry name="no_surface" value="0" 570 summary="the surface with given id does not exist"/> 571 <entry name="no_layer" value="1" 572 summary="the layer with given id does not exist"/> 573 <entry name="bad_param" value="2" 574 summary="the given parameter is not valid"/> 575 </enum> 576 577 <event name="layer_error"> 578 <description summary="error event"> 579 The error event is sent out when an error has occurred. 580 </description> 581 <arg name="object_id" type="uint" summary="id of a layer or surface"/> 582 <arg name="error" type="uint" summary="error code"/> 583 <arg name="message" type="string" summary="error description"/> 584 </event> 585 586 <event name="surface_size"> 587 <description summary="the surface size in ivi compositor has changed"> 588 The client providing content for this surface modified size of the surface. 589 The modified surface size is provided by arguments width and height. 590 </description> 591 <arg name="surface_id" type="uint"/> 592 <arg name="width" type="int"/> 593 <arg name="height" type="int"/> 594 </event> 595 596 <event name="surface_stats"> 597 <description summary="receive updated statistics for surface in ivi compositor"> 598 The information contained in this event is essential for monitoring, debugging, 599 logging and tracing support in IVI systems. 600 </description> 601 <arg name="surface_id" type="uint"/> 602 <arg name="frame_count" type="uint"/> 603 <arg name="pid" type="uint"/> 604 </event> 605 606 <event name="layer_surface_added"> 607 <description summary="update render order of the layer"> 608 A surface is added to the render order of the layer 609 </description> 610 <arg name="layer_id" type="uint"/> 611 <arg name="surface_id" type="uint"/> 612 </event> 613 </interface> 614 615</protocol> 616 617