| <?xml version="1.0" encoding="UTF-8"?> |
| <protocol name="ivi_controller"> |
| |
| <copyright> |
| Copyright (C) 2013 DENSO CORPORATION |
| Copyright (c) 2013 BMW Car IT GmbH |
| |
| Permission is hereby granted, free of charge, to any person obtaining a copy |
| of this software and associated documentation files (the "Software"), to deal |
| in the Software without restriction, including without limitation the rights |
| to use, copy, modify, merge, publish, distribute, sublicense, and/or sell |
| copies of the Software, and to permit persons to whom the Software is |
| furnished to do so, subject to the following conditions: |
| |
| The above copyright notice and this permission notice shall be included in |
| all copies or substantial portions of the Software. |
| |
| THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR |
| IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, |
| FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE |
| AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER |
| LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, |
| OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN |
| THE SOFTWARE. |
| </copyright> |
| |
| <interface name="ivi_controller_surface" version="1"> |
| <description summary="controller interface to surface in ivi compositor"/> |
| |
| <request name="set_visibility"> |
| <description summary="set the visibility of a surface in ivi compositor"> |
| If visibility argument is 0, the surface in the ivi compositor is set to invisible. |
| If visibility argument is not 0, the surface in the ivi compositor is set to visible. |
| </description> |
| <arg name="visibility" type="uint"/> |
| </request> |
| |
| <request name="set_opacity"> |
| <description summary="set the opacity of a surface in ivi compositor"> |
| The valid range for opacity is 0.0 (fully transparent) to 1.0 (fully opaque). |
| </description> |
| <arg name="opacity" type="fixed"/> |
| </request> |
| |
| <request name="set_source_rectangle"> |
| <description summary="set the scanout area of a surface in ivi compositor"> |
| The source rectangle defines the part of the surface content, that is used for |
| compositing the surface. It can be used, if valid content of the surface is smaller |
| than the surface. Effectively it can be used to zoom the content of the surface. |
| x: horizontal start position of scanout area within the surface |
| y: vertical start position of scanout area within the surface |
| width: width of scanout area within the surface |
| height: height of scanout area within the surface |
| </description> |
| <arg name="x" type="int"/> |
| <arg name="y" type="int"/> |
| <arg name="width" type="int"/> |
| <arg name="height" type="int"/> |
| </request> |
| |
| <request name="set_destination_rectangle"> |
| <description summary="Set the destination area of a surface within a layer"> |
| The destination rectangle defines the position and size of a surface on a layer. |
| The surface will be scaled to this rectangle for rendering. |
| x: horizontal start position of surface within the layer |
| y: vertical start position of surface within the layer |
| width : width of surface within the layer |
| height: height of surface within the layer |
| </description> |
| <arg name="x" type="int"/> |
| <arg name="y" type="int"/> |
| <arg name="width" type="int"/> |
| <arg name="height" type="int"/> |
| </request> |
| |
| <request name="set_configuration"> |
| <description summary="request new buffer size for application content"> |
| Request the client providing content for this surface, to resize of the buffers |
| provided as surface content. |
| </description> |
| <arg name="width" type="int"/> |
| <arg name="height" type="int"/> |
| </request> |
| |
| <request name="set_orientation"> |
| <description summary="set the orientation of a surface in ivi compositor"> |
| The orientation of a surface in ivi compositor can be rotated in 90 degree steps, |
| as defined in orientation enum. |
| </description> |
| <arg name="orientation" type="int"/> |
| </request> |
| |
| <request name="screenshot"> |
| <description summary="take screenshot of surface"> |
| Store a screenshot of the surface content in the file provided by argument filename. |
| </description> |
| <arg name="filename" type="string"/> |
| </request> |
| |
| <event name="visibility"> |
| <description summary="the visibility of the surface in ivi compositor has changed"> |
| The new visibility state is provided in argument visibility. |
| If visibility is 0, the surface has become invisible. |
| If visibility is not 0, the surface has become visible. |
| </description> |
| <arg name="visibility" type="int"/> |
| </event> |
| |
| <event name="opacity"> |
| <description summary="the opacity of surface in ivi compositor has changed"> |
| The new opacity state is provided in argument opacity. |
| The valid range for opactiy is 0.0 (fully transparent) to 1.0 (fully opaque). |
| </description> |
| <arg name="opacity" type="fixed"/> |
| </event> |
| |
| <event name="source_rectangle"> |
| <description summary="the source rectangle of surface in ivi compositor has changed"> |
| The scanout region of the surface content has changed. |
| The new values for source rectangle are provided by |
| x: new horizontal start position of scanout area within the surface |
| y: new vertical start position of scanout area within the surface |
| width: new width of scanout area within the surface |
| height: new height of scanout area within the surface |
| </description> |
| <arg name="x" type="int"/> |
| <arg name="y" type="int"/> |
| <arg name="width" type="int"/> |
| <arg name="height" type="int"/> |
| </event> |
| |
| <event name="destination_rectangle"> |
| <description summary="the destination rectangle of surface in ivi compositor has changed"> |
| The new values for source rectangle are provided by |
| x: new horizontal start position of surface within the layer |
| y: new vertical start position of surface within the layer |
| width : new width of surface within the layer |
| height: new height of surface within the layer |
| </description> |
| <arg name="x" type="int"/> |
| <arg name="y" type="int"/> |
| <arg name="width" type="int"/> |
| <arg name="height" type="int"/> |
| </event> |
| |
| <event name="configuration"> |
| <description summary="the configuration of surface in ivi compositor has changed"> |
| The client providing content for this surface was requested to resize the buffer |
| provided as surface content. The requested buffer size is provided by arguments |
| width and height. |
| </description> |
| <arg name="width" type="int"/> |
| <arg name="height" type="int"/> |
| </event> |
| |
| <enum name="orientation"> |
| <description summary="orientation presets in degrees"> |
| The surfaces in ivi controller can be rotated in 90 degrees steps. |
| This enum defines all valid orientations for surfaces. |
| </description> |
| <entry name="0_degrees" value="0" summary="not rotated"/> |
| <entry name="90_degrees" value="1" summary="rotated 90 degrees clockwise"/> |
| <entry name="180_degrees" value="2" summary="rotated 180 degrees clockwise"/> |
| <entry name="270_degrees" value="3" summary="rotated 270 degrees clockwise"/> |
| </enum> |
| |
| <event name="orientation"> |
| <description summary="the orientation of surface in ivi compositor has changed"> |
| The new orientation status is provided by argument orientation. |
| </description> |
| <arg name="orientation" type="int"/> |
| </event> |
| |
| <enum name="pixelformat"> |
| <description summary="pixel format values"> |
| Applications can provide buffers as surface content with differernt buffer |
| properties. This enum defines all supported buffer configurations. |
| </description> |
| <entry name="r_8" value="0" summary="8 bit luminance surface"/> |
| <entry name="rgb_888" value="1" summary="24 bit rgb surface"/> |
| <entry name="rgba_8888" value="2" summary="24 bit rgb surface with 8 bit alpha"/> |
| <entry name="rgb_565" value="3" summary="16 bit rgb surface"/> |
| <entry name="rgba_5551" value="4" summary="16 bit rgb surface with binary mask"/> |
| <entry name="rgba_6661" value="5" summary="18 bit rgb surface with binary mask"/> |
| <entry name="rgba_4444" value="6" summary="12 bit rgb surface with 4 bit alpha"/> |
| <entry name="unknown" value="7" summary="unknown"/> |
| </enum> |
| |
| <event name="pixelformat"> |
| <description summary="pixelformat for surface in ivi compositor has changed"> |
| When client attach buffers as surface content, these buffers have a pixelformat |
| configuration. If the pixelformat of a newly attached buffer is different from |
| the previous buffer configuration, this event is raised. |
| This is also done, when the first buffer is provided by application. |
| </description> |
| <arg name="pixelformat" type="int"/> |
| </event> |
| |
| <event name="layer"> |
| <description summary="surface in ivi compositor was added to a layer"> |
| This surface was added to the render order of the layer defined by argument layer. |
| This is essential for a surface to become visible on screen, since ivi compositors |
| will only render layers (or more precise all surfaces in the render order of a layer). |
| </description> |
| <arg name="layer" type="object" interface="ivi_controller_layer" allow-null="true"/> |
| </event> |
| |
| <request name="send_stats"> |
| <description summary="request statistics for surface in ivi compositor"> |
| These stats contain information required for monitoring, debugging, logging |
| and tracing. |
| </description> |
| </request> |
| |
| <event name="stats"> |
| <description summary="receive updated statistics for surface in ivi compositor"> |
| The information contained in this event is essential for monitoring, debugging, |
| logging and tracing support in IVI systems. |
| </description> |
| <arg name="redraw_count" type="uint"/> |
| <arg name="frame_count" type="uint"/> |
| <arg name="update_count" type="uint"/> |
| <arg name="pid" type="uint"/> |
| <arg name="process_name" type="string" allow-null="true"/> |
| </event> |
| |
| <request name="destroy" type="destructor"> |
| <description summary="destroy ivi_controller_surface"> |
| Request to destroy the ivi_controller_surface. If argument |
| destroy_scene_object id not 0, the surface will be destroyed in |
| ivi compositor. If argument is 0, only the proxy object is destroyed. |
| </description> |
| <arg name="destroy_scene_object" type="int"/> |
| </request> |
| |
| <event name="destroyed"> |
| <description summary="ivi_controller_surface was destroyed"/> |
| </event> |
| |
| <enum name="content_state"> |
| <description summary="all possible states of content for a surface"> |
| This enum defines all possible content states of a surface. This is |
| required, since surfaces in ivi compositor can exist without applications |
| providing content for them. |
| </description> |
| <entry name="content_available" value="1" |
| summary="application provided wl_surface for this surface"/> |
| <entry name="content_removed" value="2" |
| summary="wl_surface was removed for this surface"/> |
| </enum> |
| |
| <event name="content"> |
| <description summary="content state for surface has changed"> |
| Surfaces in ivi compositor can exist without any application or controller |
| referencing it. All surfaces initially have no content. This event indicates |
| when content state has changed. All possible content states are defined |
| in enum content_state. |
| </description> |
| <arg name="content_state" type="int"/> |
| </event> |
| |
| </interface> |
| |
| <interface name="ivi_controller_layer" version="1"> |
| <description summary="controller interface to layer in ivi compositor"/> |
| |
| <request name="set_visibility"> |
| <description summary="set visibility of layer in ivi compositor"> |
| If visibility argument is 0, the layer in the ivi compositor is set to invisible. |
| If visibility argument is not 0, the layer in the ivi compositor is set to visible. |
| </description> |
| <arg name="visibility" type="uint"/> |
| </request> |
| |
| <request name="set_opacity"> |
| <description summary="set opacity of layer in ivi compositor"> |
| The valid range for opacity is 0.0 (fully transparent) to 1.0 (fully opaque). |
| </description> |
| <arg name="opacity" type="fixed"/> |
| </request> |
| |
| <request name="set_source_rectangle"> |
| <description summary="set the scanout area of a layer in ivi compositor"> |
| The source rectangle defines the part of the layer content, that is used for |
| compositing the screen. It can be used, if valid content of the layer is smaller |
| than the layer. Effectively it can be used to zoom the content of the layer. |
| x: horizontal start position of scanout area within the layer |
| y: vertical start position of scanout area within the layer |
| width: width of scanout area within the layer |
| height: height of scanout area within the layer |
| </description> |
| <arg name="x" type="int"/> |
| <arg name="y" type="int"/> |
| <arg name="width" type="int"/> |
| <arg name="height" type="int"/> |
| </request> |
| |
| <request name="set_destination_rectangle"> |
| <description summary="Set the destination area of a layer within a screen"> |
| The destination rectangle defines the position and size of a layer on a screen. |
| The layer will be scaled to this rectangle for rendering. |
| x: horizontal start position of layer within the screen |
| y: vertical start position of layer within the screen |
| width : width of surface within the screen |
| height: height of surface within the screen |
| </description> |
| <arg name="x" type="int"/> |
| <arg name="y" type="int"/> |
| <arg name="width" type="int"/> |
| <arg name="height" type="int"/> |
| </request> |
| |
| <request name="set_configuration"> |
| <description summary="request new size for layer"> |
| Layers are created with an initial size, but they can be resized at runtime. |
| This request changes the widht and height of a layer. |
| </description> |
| <arg name="width" type="int"/> |
| <arg name="height" type="int"/> |
| </request> |
| |
| <request name="set_orientation"> |
| <description summary="set the orientation of a layer in ivi compositor"> |
| The orientation of a layer in ivi compositor can be rotated in 90 degree steps, |
| as defined in orientation enum. |
| </description> |
| <arg name="orientation" type="int"/> |
| </request> |
| |
| <request name="screenshot"> |
| <description summary="take screenshot of layer"> |
| Store a screenshot of the layer content in the file provided by argument filename. |
| </description> |
| <arg name="filename" type="string"/> |
| </request> |
| |
| <request name="clear_surfaces"> |
| <description summary="remove all surfaces from layer render order"> |
| A layer has no content assigned to itself, it is a container for surfaces. |
| This request removes all surfaces from the layer render order. |
| Note: the surfaces are not destroyed, they are just no longer contained by |
| the layer. |
| </description> |
| </request> |
| |
| <request name="add_surface"> |
| <description summary="add a surface to layer render order at nearest z-position"> |
| A layer has no content assigned to itself, it is a container for surfaces. |
| This request adds a surface to the topmost position of the layer render order. |
| The added surface will cover all other surfaces of the layer. |
| </description> |
| <arg name="surface" type="object" interface="ivi_controller_surface"/> |
| </request> |
| |
| <request name="remove_surface"> |
| <description summary="remove a surface from layer render order"> |
| A layer has no content assigned to itself, it is a container for surfaces. |
| This request removes one surfaces from the layer render order. |
| Note: the surface is not destroyed, it is just no longer contained by |
| the layer. |
| </description> |
| <arg name="surface" type="object" interface="ivi_controller_surface"/> |
| </request> |
| |
| <request name="set_render_order"> |
| <description summary="set render order of layer"> |
| A layer has no content assigned to itself, it is a container for surfaces. |
| This request removes all surfaces from the layer render order and set a |
| completely new render order. |
| </description> |
| <arg name="id_surfaces" type="array"/> |
| </request> |
| |
| <event name="visibility"> |
| <description summary="the visibility of the layer in ivi compositor has changed"> |
| The new visibility state is provided in argument visibility. |
| If visibility is 0, the layer has become invisible. |
| If visibility is not 0, the layer has become visible. |
| </description> |
| <arg name="visibility" type="int"/> |
| </event> |
| |
| <event name="opacity"> |
| <description summary="the opacity of layer in ivi compositor has changed"> |
| The new opacity state is provided in argument opacity. |
| The valid range for opactiy is 0.0 (fully transparent) to 1.0 (fully opaque). |
| </description> |
| <arg name="opacity" type="fixed"/> |
| </event> |
| |
| <event name="source_rectangle"> |
| <description summary="the source rectangle of layer in ivi compositor has changed"> |
| The scanout region of the layer content has changed. |
| The new values for source rectangle are provided by |
| x: new horizontal start position of scanout area within the layer |
| y: new vertical start position of scanout area within the layer |
| width: new width of scanout area within the layer |
| height: new height of scanout area within the layer |
| </description> |
| <arg name="x" type="int"/> |
| <arg name="y" type="int"/> |
| <arg name="width" type="int"/> |
| <arg name="height" type="int"/> |
| </event> |
| |
| <event name="destination_rectangle"> |
| <description summary="the destination rectangle of layer in ivi compositor has changed"> |
| The new values for source rectangle are provided by |
| x: new horizontal start position of layer within the screen |
| y: new vertical start position of layer within the screen |
| width : new width of layer within the screen |
| height: new height of layer within the screen |
| </description> |
| <arg name="x" type="int"/> |
| <arg name="y" type="int"/> |
| <arg name="width" type="int"/> |
| <arg name="height" type="int"/> |
| </event> |
| |
| <event name="configuration"> |
| <description summary="the configuration of layer in ivi compositor has changed"> |
| The layer was resized. The new layer size is provided by arguments |
| width and height. |
| </description> |
| <arg name="width" type="int"/> |
| <arg name="height" type="int"/> |
| </event> |
| |
| <event name="orientation"> |
| <description summary="the orientation of layer in ivi compositor has changed"> |
| The new orientation status is provided by argument orientation. |
| </description> |
| <arg name="orientation" type="int"/> |
| </event> |
| |
| <event name="screen"> |
| <description summary="layer in ivi compositor was added to a screen"> |
| This layer was added to the render order of the screen defined by argument screen. |
| This is essential for a layer to become visible on screen, since ivi compositors |
| will only render screens (or more precise all layers in the render order of a screen). |
| </description> |
| <arg name="screen" type="object" interface="wl_output" allow-null="true"/> |
| </event> |
| |
| <request name="destroy" type="destructor"> |
| <description summary="destroy ivi_controller_layer"> |
| Request to destroy the ivi_controller_layer. If argument |
| destroy_scene_object id not 0, the layer will be destroyed in |
| ivi compositor. If argument is 0, only the proxy object is destroyed. |
| </description> |
| <arg name="destroy_scene_object" type="int"/> |
| </request> |
| |
| <event name="destroyed"> |
| <description summary="destroyed layer event"/> |
| </event> |
| |
| </interface> |
| |
| <interface name="ivi_controller_screen" version="1"> |
| <description summary="controller interface to screen in ivi compositor"/> |
| |
| <request name="destroy" type="destructor"> |
| <description summary="destroy ivi_controller_screen"/> |
| </request> |
| |
| <request name="clear"> |
| <description summary="remove all layers from screen render order"> |
| A screen has no content assigned to itself, it is a container for layers. |
| This request removes all layers from the screen render order. |
| Note: the layers are not destroyed, they are just no longer contained by |
| the screen. |
| </description> |
| </request> |
| |
| <request name="add_layer"> |
| <description summary="add a layer to screen render order at nearest z-position"> |
| A screen has no content assigned to itself, it is a container for layers. |
| This request adds a layers to the topmost position of the screen render order. |
| The added layer will cover all other layers of the screen. |
| </description> |
| <arg name="layer" type="object" interface="ivi_controller_layer"/> |
| </request> |
| |
| <request name="screenshot"> |
| <description summary="take screenshot of screen"> |
| Store a screenshot of the screen content in the file provided by argument filename. |
| </description> |
| <arg name="filename" type="string"/> |
| </request> |
| |
| <request name="set_render_order"> |
| <description summary="set render order of screen"> |
| A screen has no content assigned to itself, it is a container for layers. |
| This request removes all layers from the screen render order and set a |
| completely new render order. |
| </description> |
| <arg name="id_layers" type="array"/> |
| </request> |
| |
| </interface> |
| |
| <interface name="ivi_controller" version="1"> |
| <description summary="interface for ivi controllers to use ivi compositor features"/> |
| |
| <request name="commit_changes"> |
| <description summary="commit all changes requested by client"> |
| All requests are not applied directly to scene object, so a controller |
| can set different properties and apply the changes all at once. |
| Note: there's an exception to this. Creation and destruction of |
| scene objects is executed immediately. |
| </description> |
| </request> |
| |
| <event name="screen"> |
| <description summary="new screen is available"> |
| A new screen is announced to the controller. This is typically |
| the case in two cases: |
| 1. controller was just started, ivi compositor announces existing screen |
| 2. a new screen was added to the system at runtime |
| </description> |
| <arg name="id_screen" type="uint"/> |
| <arg name="screen" type="new_id" interface="ivi_controller_screen"/> |
| </event> |
| |
| <request name="layer_create"> |
| <description summary="create layer in ivi compositor"> |
| layer_create will create a new layer with id_layer in ivi compositor, |
| if it does not yet exists. If the layer with id_layer already exists in |
| ivi compositor, a handle to the existing layer is returned and width and |
| height properties are ignored. |
| </description> |
| <arg name="id_layer" type="uint"/> |
| <arg name="width" type="int"/> |
| <arg name="height" type="int"/> |
| <arg name="id" type="new_id" interface="ivi_controller_layer"/> |
| </request> |
| |
| <event name="layer"> |
| <description summary="new layer is available"> |
| A new layer is announced to the controller. |
| </description> |
| <arg name="id_layer" type="uint"/> |
| </event> |
| |
| <request name="surface_create"> |
| <description summary="create surface in ivi compositor"> |
| surface_create will create a new surface with id_surface in ivi compositor, |
| if it does not yet exists. If the surface with id_surface already exists in |
| ivi compositor, a handle to the existing surface is returned. |
| </description> |
| <arg name="id_surface" type="uint"/> |
| <arg name="id" type="new_id" interface="ivi_controller_surface"/> |
| </request> |
| |
| <event name="surface"> |
| <description summary="new surface is available"> |
| A new surface is announced to the controller. |
| </description> |
| <arg name="id_surface" type="uint"/> |
| </event> |
| |
| <enum name="object_type"> |
| <description summary="available object types in ivi compositor scene"> |
| This enum defines all scene object available in ivi compositor. |
| </description> |
| <entry name="surface" value="1" summary="surface object type"/> |
| <entry name="layer" value="2" summary="layer object type"/> |
| <entry name="screen" value="3" summary="screen object type"/> |
| </enum> |
| |
| <enum name="error_code"> |
| <description summary="possible error codes returned in error event"> |
| These error codes define all possible error codes returned by ivi compositor |
| on server-side errors. |
| </description> |
| <entry name="unknown_error" value="1" summary="unknown error encountered"/> |
| <entry name="file_error" value="2" summary="file i/o error encountered"/> |
| </enum> |
| |
| <event name="error"> |
| <description summary="server-side error detected"> |
| The ivi compositor encountered error while processing a request by this |
| controller. The error is defined by argument error_code and optional |
| error_text. Additionally the object type and id is contained in the error |
| event to provide some detailes to handle the error. |
| If the controller requires to associate this error event to a request, |
| it can |
| 1. send request |
| 2. force display roundtrip |
| 3. check, if error event was received |
| but this restricts the controller to have only one open request at a time. |
| </description> |
| <arg name="object_id" type="int"/> |
| <arg name="object_type" type="int"/> |
| <arg name="error_code" type="int"/> |
| <arg name="error_text" type="string" allow-null="true"/> |
| </event> |
| |
| </interface> |
| |
| </protocol> |
| |
