protocol/ivi-wm.xml

   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="set_surface_visibility">
 179       <description summary="set the visibility of a surface in ivi compositor">
 180         If visibility argument is 0, the surface in the ivi compositor is set to invisible.
 181         If visibility argument is not 0, the surface in the ivi compositor is set to visible.
 182       </description>
 183       <arg name="surface_id" type="uint"/>
 184       <arg name="visibility" type="uint"/>
 185     </request>
 186
 187     <request name="set_layer_visibility">
 188       <description summary="set visibility of layer in ivi compositor">
 189         If visibility argument is 0, the layer in the ivi compositor is set to invisible.
 190         If visibility argument is not 0, the layer in the ivi compositor is set to visible.
 191       </description>
 192       <arg name="layer_id" type="uint"/>
 193       <arg name="visibility" type="uint"/>
 194     </request>
 195
 196     <request name="set_surface_opacity">
 197       <description summary="set the opacity of a surface in ivi compositor">
 198         The valid range for opacity is 0.0 (fully transparent) to 1.0 (fully opaque).
 199       </description>
 200       <arg name="surface_id" type="uint"/>
 201       <arg name="opacity" type="fixed"/>
 202     </request>
 203
 204     <request name="set_layer_opacity">
 205       <description summary="set opacity of layer in ivi compositor">
 206         The valid range for opacity is 0.0 (fully transparent) to 1.0 (fully opaque).
 207       </description>
 208       <arg name="layer_id" type="uint"/>
 209       <arg name="opacity" type="fixed"/>
 210     </request>
 211
 212     <request name="set_surface_source_rectangle">
 213       <description summary="set the scanout area of a surface in ivi compositor">
 214         The source rectangle defines the part of the surface content, that is used for
 215         compositing the surface. It can be used, if valid content of the surface is smaller
 216         than the surface. Effectively it can be used to zoom the content of the surface.
 217         If a parameter is less than 0, that value is not changed.
 218         x:      horizontal start position of scanout area within the surface
 219         y:      vertical start position of scanout area within the surface
 220         width:  width of scanout area within the surface
 221         height: height of scanout area within the surface
 222       </description>
 223       <arg name="surface_id" type="uint"/>
 224       <arg name="x" type="int"/>
 225       <arg name="y" type="int"/>
 226       <arg name="width" type="int"/>
 227       <arg name="height" type="int"/>
 228     </request>
 229
 230     <request name="set_layer_source_rectangle">
 231       <description summary="set the scanout area of a layer in ivi compositor">
 232         The source rectangle defines the part of the layer content, that is used for
 233         compositing the screen. It can be used, if valid content of the layer is smaller
 234         than the layer. Effectively it can be used to zoom the content of the layer.
 235         If a parameter is less than 0, that value is not changed.
 236         x:      horizontal start position of scanout area within the layer
 237         y:      vertical start position of scanout area within the layer
 238         width:  width of scanout area within the layer
 239         height: height of scanout area within the layer
 240       </description>
 241       <arg name="layer_id" type="uint"/>
 242       <arg name="x" type="int"/>
 243       <arg name="y" type="int"/>
 244       <arg name="width" type="int"/>
 245       <arg name="height" type="int"/>
 246     </request>
 247
 248     <request name="set_surface_destination_rectangle">
 249       <description summary="Set the destination area of a surface within a layer">
 250         The destination rectangle defines the position and size of a surface on a layer.
 251         The surface will be scaled to this rectangle for rendering.
 252         If a parameter is less than 0, that value is not changed.
 253         x:      horizontal start position of surface within the layer
 254         y:      vertical start position of surface within the layer
 255         width : width of surface within the layer
 256         height: height of surface within the layer
 257       </description>
 258       <arg name="surface_id" type="uint"/>
 259       <arg name="x" type="int"/>
 260       <arg name="y" type="int"/>
 261       <arg name="width" type="int"/>
 262       <arg name="height" type="int"/>
 263     </request>
 264
 265     <request name="set_layer_destination_rectangle">
 266       <description summary="Set the destination area of a layer within a screen">
 267         The destination rectangle defines the position and size of a layer on a screen.
 268         The layer will be scaled to this rectangle for rendering.
 269         If a parameter is less than 0, that value is not changed.
 270         x:      horizontal start position of layer within the screen
 271         y:      vertical start position of layer within the screen
 272         width : width of surface within the screen
 273         height: height of surface within the screen
 274       </description>
 275       <arg name="layer_id" type="uint"/>
 276       <arg name="x" type="int"/>
 277       <arg name="y" type="int"/>
 278       <arg name="width" type="int"/>
 279       <arg name="height" type="int"/>
 280     </request>
 281
 282     <enum name="sync">
 283       <description summary="sync request states">
 284       </description>
 285       <entry name="add"  value="0"/>
 286       <entry name="remove" value="1"/>
 287     </enum>
 288
 289     <request name="surface_sync">
 290       <description summary="request to synchronize of a surface in ivi compositor">
 291         After this request, compositor sends the properties of the surface.
 292         If sync_state argument is 0, compositor sends the properties continously.
 293         If sync_state argument is not 0, compositor stops sending the properties
 294         continously.
 295       </description>
 296       <arg name="surface_id" type="uint"/>
 297       <arg name="sync_state" type="int"/>
 298     </request>
 299
 300     <request name="layer_sync">
 301       <description summary="request to synchronize of a layer in ivi compositor">
 302         After this request, compositor sends the properties of the layer.
 303         If sync_state argument is 0, compositor sends the properties continously.
 304         If sync_state argument is not 0, compositor stops sending the properties
 305         continously.
 306       </description>
 307       <arg name="layer_id" type="uint"/>
 308       <arg name="sync_state" type="int"/>
 309     </request>
 310
 311     <enum name="param" bitfield="true">
 312       <description summary="parameter types">
 313           The HMI controller can request different types of parameters of an
 314           ivi-object.
 315       </description>
 316       <entry name="opacity"   value="1"/>
 317       <entry name="visibility"  value="2"/>
 318       <entry name="size" value="4"/>
 319       <entry name="render_order" value="8"/>
 320     </enum>
 321
 322     <request name="surface_get">
 323       <description summary="get a parameter of an ivi_layout_surface in ivi compositor">
 324         After this request, compositor sends the requested parameter.
 325       </description>
 326       <arg name="surface_id" type="uint"/>
 327       <arg name="param" type="int"/>
 328     </request>
 329
 330     <request name="layer_get">
 331       <description summary="get a parameter of an ivi_layout_layer in ivi compositor">
 332         After this request, compositor sends the requested parameter.
 333       </description>
 334       <arg name="layer_id" type="uint"/>
 335       <arg name="param" type="int"/>
 336     </request>
 337
 338     <request name="surface_screenshot">
 339       <description summary="take screenshot of surface">
 340         An ivi_screenshot object is created which will receive an image of the
 341         buffer currently attached to the surface with the given id. If there
 342         is no surface with such name the server will respond with an
 343         ivi_screenshot.error event.
 344       </description>
 345       <arg name="screenshot" type="new_id" interface="ivi_screenshot"/>
 346       <arg name="surface_id" type="uint"/>
 347     </request>
 348
 349     <enum name="surface_type">
 350       <description summary="hint for the compositor">
 351         If a surface is restricted type, visible contents of the surface is strictly
 352         controlled by the compositor. Its content is not allowed to be go out of
 353         its destination region. If the application resizes its buffers or uses
 354         wp_viewporter protocol to scale its contents, the old destination region
 355         would causes visible glitches.
 356         To avoid these issues, the controller process mark a surface as desktop
 357         compatible. Source and destination regions of a desktop compatible
 358         surface will be modified accordingly,when application sends a request
 359         for resizing or scaling its contents. Therefore, applications contents
 360         will be drawn according to application's wishes.
 361         On the other hand, source and destination regions will be strictly
 362         enforced, when the surface's type is restricted. The default type for
 363         a surface is ivi.
 364       </description>
 365       <entry name="restricted"  value="0" summary="strictly controlled"/>
 366       <entry name="desktop"  value="1" summary="free to resize and scale"/>
 367     </enum>
 368
 369     <request name="set_surface_type">
 370       <description summary="request to set a type for the surface in ivi compositor">
 371         After this request, compositor changes the type of the surface.
 372       </description>
 373       <arg name="surface_id" type="uint"/>
 374       <arg name="type" type="int"/>
 375     </request>
 376
 377     <request name="layer_clear">
 378       <description summary="remove all surfaces from layer render order">
 379         A layer has no content assigned to itself, it is a container for surfaces.
 380         This request removes all surfaces from the layer render order.
 381       </description>
 382       <arg name="layer_id" type="uint"/>
 383     </request>
 384
 385     <request name="layer_add_surface">
 386       <description summary="add a surface to layer render order at nearest z-position">
 387         A layer has no content assigned to itself, it is a container for surfaces.
 388         This request adds a surface to the topmost position of the layer render order.
 389         The added surface will cover all other surfaces of the layer.
 390       </description>
 391       <arg name="layer_id" type="uint"/>
 392       <arg name="surface_id" type="uint"/>
 393     </request>
 394
 395     <request name="layer_remove_surface">
 396       <description summary="remove a surface from layer render order">
 397         A layer has no content assigned to itself, it is a container for surfaces.
 398         This request removes one surfaces from the layer render order.
 399         Note: the surface is not destroyed, it is just no longer contained by
 400         the layer.
 401       </description>
 402       <arg name="layer_id" type="uint"/>
 403       <arg name="surface_id" type="uint"/>
 404     </request>
 405
 406     <request name="create_layout_layer">
 407       <description summary="create an ivi_layout_layer in ivi compositor">
 408         After this request, compositor creates an ivi_layout_layer
 409       </description>
 410       <arg name="layer_id" type="uint"/>
 411       <arg name="width" type="int"/>
 412       <arg name="height" type="int"/>
 413     </request>
 414
 415     <request name="destroy_layout_layer">
 416       <description summary="destroy an ivi_layout_layer in ivi compositor">
 417         After this request, compositor destroyes an existing ivi_layout_layer.
 418       </description>
 419       <arg name="layer_id" type="uint"/>
 420     </request>
 421
 422     <event name="surface_visibility">
 423       <description summary="the visibility of the surface in ivi compositor has changed">
 424         The new visibility state is provided in argument visibility.
 425         If visibility is 0, the surface has become invisible.
 426         If visibility is not 0, the surface has become visible.
 427       </description>
 428       <arg name="surface_id" type="uint"/>
 429       <arg name="visibility" type="int"/>
 430     </event>
 431
 432     <event name="layer_visibility">
 433       <description summary="the visibility of the layer in ivi compositor has changed">
 434         The new visibility state is provided in argument visibility.
 435         If visibility is 0, the layer has become invisible.
 436         If visibility is not 0, the layer has become visible.
 437       </description>
 438       <arg name="layer_id" type="uint"/>
 439       <arg name="visibility" type="int"/>
 440     </event>
 441
 442     <event name="surface_opacity">
 443       <description summary="the opacity of surface in ivi compositor has changed">
 444         The new opacity state is provided in argument opacity.
 445         The valid range for opactiy is 0.0 (fully transparent) to 1.0 (fully opaque).
 446       </description>
 447       <arg name="surface_id" type="uint"/>
 448       <arg name="opacity" type="fixed"/>
 449     </event>
 450
 451     <event name="layer_opacity">
 452       <description summary="the opacity of layer in ivi compositor has changed">
 453         The new opacity state is provided in argument opacity.
 454         The valid range for opactiy is 0.0 (fully transparent) to 1.0 (fully opaque).
 455       </description>
 456       <arg name="layer_id" type="uint"/>
 457       <arg name="opacity" type="fixed"/>
 458     </event>
 459
 460     <event name="surface_source_rectangle">
 461       <description summary="the source rectangle of surface in ivi compositor has changed">
 462         The scanout region of the surface content has changed.
 463         The new values for source rectangle are provided by
 464         x:      new horizontal start position of scanout area within the surface
 465         y:      new vertical start position of scanout area within the surface
 466         width:  new width of scanout area within the surface
 467         height: new height of scanout area within the surface
 468       </description>
 469       <arg name="surface_id" type="uint"/>
 470       <arg name="x" type="int"/>
 471       <arg name="y" type="int"/>
 472       <arg name="width" type="int"/>
 473       <arg name="height" type="int"/>
 474     </event>
 475
 476     <event name="layer_source_rectangle">
 477       <description summary="the source rectangle of layer in ivi compositor has changed">
 478         The scanout region of the layer content has changed.
 479         The new values for source rectangle are provided by
 480         x:      new horizontal start position of scanout area within the layer
 481         y:      new vertical start position of scanout area within the layer
 482         width:  new width of scanout area within the layer
 483         height: new height of scanout area within the layer
 484       </description>
 485       <arg name="layer_id" type="uint"/>
 486       <arg name="x" type="int"/>
 487       <arg name="y" type="int"/>
 488       <arg name="width" type="int"/>
 489       <arg name="height" type="int"/>
 490     </event>
 491
 492     <event name="surface_destination_rectangle">
 493       <description summary="the destination rectangle of surface in ivi compositor has changed">
 494         The new values for source rectangle are provided by
 495         x:      new horizontal start position of surface within the layer
 496         y:      new vertical start position of surface within the layer
 497         width : new width of surface within the layer
 498         height: new height of surface within the layer
 499       </description>
 500       <arg name="surface_id" type="uint"/>
 501       <arg name="x" type="int"/>
 502       <arg name="y" type="int"/>
 503       <arg name="width" type="int"/>
 504       <arg name="height" type="int"/>
 505     </event>
 506
 507     <event name="layer_destination_rectangle">
 508       <description summary="the destination rectangle of layer in ivi compositor has changed">
 509         The new values for source rectangle are provided by
 510         x:      new horizontal start position of layer within the screen
 511         y:      new vertical start position of layer within the screen
 512         width : new width of layer within the screen
 513         height: new height of layer within the screen
 514       </description>
 515       <arg name="layer_id" type="uint"/>
 516       <arg name="x" type="int"/>
 517       <arg name="y" type="int"/>
 518       <arg name="width" type="int"/>
 519       <arg name="height" type="int"/>
 520     </event>
 521
 522     <event name="surface_created">
 523       <description summary="ivi_layout_surface was created"/>
 524       <arg name="surface_id" type="uint"/>
 525     </event>
 526
 527     <event name="layer_created">
 528       <description summary="ivi_layout_layer was created"/>
 529       <arg name="layer_id" type="uint"/>
 530     </event>
 531
 532     <event name="surface_destroyed">
 533       <description summary="ivi_layout_surface was destroyed"/>
 534       <arg name="surface_id" type="uint"/>
 535     </event>
 536
 537     <event name="layer_destroyed">
 538       <description summary="ivi_layout_layer was destroyed"/>
 539       <arg name="layer_id" type="uint"/>
 540     </event>
 541
 542     <enum name="surface_error">
 543        <entry name="no_surface" value="0"
 544               summary="the surface with given id does not exist"/>
 545        <entry name="bad_param" value="1"
 546               summary="the given parameter is not valid"/>
 547        <entry name="not_supported" value="2"
 548               summary="the request is not supported"/>
 549      </enum>
 550
 551      <event name="surface_error">
 552        <description summary="error event">
 553          The error event is sent out when an error has occurred.
 554        </description>
 555        <arg name="object_id" type="uint" summary="id of a layer or surface"/>
 556        <arg name="error" type="uint" summary="error code"/>
 557        <arg name="message" type="string" summary="error description"/>
 558      </event>
 559
 560     <enum name="layer_error">
 561        <entry name="no_surface" value="0"
 562               summary="the surface with given id does not exist"/>
 563        <entry name="no_layer" value="1"
 564               summary="the layer with given id does not exist"/>
 565        <entry name="bad_param" value="2"
 566               summary="the given parameter is not valid"/>
 567      </enum>
 568
 569      <event name="layer_error">
 570        <description summary="error event">
 571          The error event is sent out when an error has occurred.
 572        </description>
 573        <arg name="object_id" type="uint" summary="id of a layer or surface"/>
 574        <arg name="error" type="uint" summary="error code"/>
 575        <arg name="message" type="string" summary="error description"/>
 576      </event>
 577
 578     <event name="surface_size">
 579       <description summary="the surface size in ivi compositor has changed">
 580         The client providing content for this surface modified size of the surface.
 581         The modified surface size is provided by arguments width and height.
 582       </description>
 583       <arg name="surface_id" type="uint"/>
 584       <arg name="width" type="int"/>
 585       <arg name="height" type="int"/>
 586     </event>
 587
 588     <event name="surface_stats">
 589       <description summary="receive updated statistics for surface in ivi compositor">
 590         The information contained in this event is essential for monitoring, debugging,
 591         logging and tracing support in IVI systems.
 592       </description>
 593       <arg name="surface_id" type="uint"/>
 594       <arg name="frame_count" type="uint"/>
 595       <arg name="pid" type="uint"/>
 596     </event>
 597
 598     <event name="layer_surface_added">
 599       <description summary="update render order of the layer">
 600         A surface is added to the render order of the layer
 601       </description>
 602       <arg name="layer_id" type="uint"/>
 603       <arg name="surface_id" type="uint"/>
 604     </event>
 605   </interface>
 606
 607 </protocol>
 608