Changeset View
Changeset View
Standalone View
Standalone View
src/client/protocols/xdg-output-unstable-v1.xml
- This file was added.
1 | <?xml version="1.0" encoding="UTF-8"?> | ||||
---|---|---|---|---|---|
2 | <protocol name="xdg_output_unstable_v1"> | ||||
3 | | ||||
4 | <copyright> | ||||
5 | Copyright © 2017 Red Hat Inc. | ||||
6 | | ||||
7 | Permission is hereby granted, free of charge, to any person obtaining a | ||||
8 | copy of this software and associated documentation files (the "Software"), | ||||
9 | to deal in the Software without restriction, including without limitation | ||||
10 | the rights to use, copy, modify, merge, publish, distribute, sublicense, | ||||
11 | and/or sell copies of the Software, and to permit persons to whom the | ||||
12 | Software is furnished to do so, subject to the following conditions: | ||||
13 | | ||||
14 | The above copyright notice and this permission notice (including the next | ||||
15 | paragraph) shall be included in all copies or substantial portions of the | ||||
16 | Software. | ||||
17 | | ||||
18 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR | ||||
19 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, | ||||
20 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL | ||||
21 | THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER | ||||
22 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING | ||||
23 | FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER | ||||
24 | DEALINGS IN THE SOFTWARE. | ||||
25 | </copyright> | ||||
26 | | ||||
27 | <description summary="Protocol to describe output regions"> | ||||
28 | This protocol aims at describing outputs in a way which is more in line | ||||
29 | with the concept of an output on desktop oriented systems. | ||||
30 | | ||||
31 | Some information are more specific to the concept of an output for | ||||
32 | a desktop oriented system and may not make sense in other applications, | ||||
33 | such as IVI systems for example. | ||||
34 | | ||||
35 | Typically, the global compositor space on a desktop system is made of | ||||
36 | a contiguous or overlapping set of rectangular regions. | ||||
37 | | ||||
38 | Some of the information provided in this protocol might be identical | ||||
39 | to their counterparts already available from wl_output, in which case | ||||
40 | the information provided by this protocol should be preferred to their | ||||
41 | equivalent in wl_output. The goal is to move the desktop specific | ||||
42 | concepts (such as output location within the global compositor space, | ||||
43 | the connector name and types, etc.) out of the core wl_output protocol. | ||||
44 | | ||||
45 | Warning! The protocol described in this file is experimental and | ||||
46 | backward incompatible changes may be made. Backward compatible | ||||
47 | changes may be added together with the corresponding interface | ||||
48 | version bump. | ||||
49 | Backward incompatible changes are done by bumping the version | ||||
50 | number in the protocol and interface names and resetting the | ||||
51 | interface version. Once the protocol is to be declared stable, | ||||
52 | the 'z' prefix and the version number in the protocol and | ||||
53 | interface names are removed and the interface version number is | ||||
54 | reset. | ||||
55 | </description> | ||||
56 | | ||||
57 | <interface name="zxdg_output_manager_v1" version="1"> | ||||
58 | <description summary="manage xdg_output objects"> | ||||
59 | A global factory interface for xdg_output objects. | ||||
60 | </description> | ||||
61 | | ||||
62 | <request name="destroy" type="destructor"> | ||||
63 | <description summary="destroy the xdg_output_manager object"> | ||||
64 | Using this request a client can tell the server that it is not | ||||
65 | going to use the xdg_output_manager object anymore. | ||||
66 | | ||||
67 | Any objects already created through this instance are not affected. | ||||
68 | </description> | ||||
69 | </request> | ||||
70 | | ||||
71 | <request name="get_xdg_output"> | ||||
72 | <description summary="create an xdg output from a wl_output"> | ||||
73 | This creates a new xdg_output object for the given wl_output. | ||||
74 | </description> | ||||
75 | <arg name="id" type="new_id" interface="zxdg_output_v1"/> | ||||
76 | <arg name="output" type="object" interface="wl_output"/> | ||||
77 | </request> | ||||
78 | </interface> | ||||
79 | | ||||
80 | <interface name="zxdg_output_v1" version="1"> | ||||
81 | <description summary="compositor logical output region"> | ||||
82 | An xdg_output describes part of the compositor geometry. | ||||
83 | | ||||
84 | This typically corresponds to a monitor that displays part of the | ||||
85 | compositor space. | ||||
86 | </description> | ||||
87 | | ||||
88 | <request name="destroy" type="destructor"> | ||||
89 | <description summary="destroy the xdg_output object"> | ||||
90 | Using this request a client can tell the server that it is not | ||||
91 | going to use the xdg_output object anymore. | ||||
92 | </description> | ||||
93 | </request> | ||||
94 | | ||||
95 | <event name="logical_position"> | ||||
96 | <description summary="position of the output within the global compositor space"> | ||||
97 | The position event describes the location of the wl_output within | ||||
98 | the global compositor space. | ||||
99 | | ||||
100 | The logical_position event is sent after creating an xdg_output | ||||
101 | (see xdg_output_manager.get_xdg_output) and whenever the location | ||||
102 | of the output changes within the global compositor space. | ||||
103 | </description> | ||||
104 | <arg name="x" type="int" | ||||
105 | summary="x position within the global compositor space"/> | ||||
106 | <arg name="y" type="int" | ||||
107 | summary="y position within the global compositor space"/> | ||||
108 | </event> | ||||
109 | | ||||
110 | <event name="logical_size"> | ||||
111 | <description summary="size of the output in the global compositor space"> | ||||
112 | The logical_size event describes the size of the output in the | ||||
113 | global compositor space. | ||||
114 | | ||||
115 | For example, a surface without any buffer scale, transformation | ||||
116 | nor rotation set, with the size matching the logical_size will | ||||
117 | have the same size as the corresponding output when displayed. | ||||
118 | | ||||
119 | Most regular Wayland clients should not pay attention to the | ||||
120 | logical size and would rather rely on xdg_shell interfaces. | ||||
121 | | ||||
122 | Some clients such as Xwayland, however, need this to configure | ||||
123 | their surfaces in the global compositor space as the compositor | ||||
124 | may apply a different scale from what is advertised by the output | ||||
125 | scaling property (to achieve fractional scaling, for example). | ||||
126 | | ||||
127 | For example, for a wl_output mode 3840×2160 and a scale factor 2: | ||||
128 | | ||||
129 | - A compositor not scaling the surface buffers will advertise a | ||||
130 | logical size of 3840×2160, | ||||
131 | | ||||
132 | - A compositor automatically scaling the surface buffers will | ||||
133 | advertise a logical size of 1920×1080, | ||||
134 | | ||||
135 | - A compositor using a fractional scale of 1.5 will advertise a | ||||
136 | logical size to 2560×1620. | ||||
137 | | ||||
138 | The logical_size event is sent after creating an xdg_output | ||||
139 | (see xdg_output_manager.get_xdg_output) and whenever the logical | ||||
140 | size of the output changes, either as a result of a change in the | ||||
141 | applied scale or because of a change in the corresponding output | ||||
142 | mode(see wl_output.mode) or transform (see wl_output.transform). | ||||
143 | </description> | ||||
144 | <arg name="width" type="int" | ||||
145 | summary="width in global compositor space"/> | ||||
146 | <arg name="height" type="int" | ||||
147 | summary="height in global compositor space"/> | ||||
148 | </event> | ||||
149 | | ||||
150 | <event name="done"> | ||||
151 | <description summary="all information about the output have been sent"> | ||||
152 | This event is sent after all other properties of an xdg_output | ||||
153 | have been sent. | ||||
154 | | ||||
155 | This allows changes to the xdg_output properties to be seen as | ||||
156 | atomic, even if they happen via multiple events. | ||||
157 | </description> | ||||
158 | </event> | ||||
159 | | ||||
160 | </interface> | ||||
161 | </protocol> |