Warning, /libraries/plasma-wayland-protocols/src/protocols/fullscreen-shell.xml is written in an unsupported language. File is not indexed.
0001 <protocol name="fullscreen_shell"> 0002 <interface name="_wl_fullscreen_shell" version="1"> 0003 <description summary="Displays a single surface per output"> 0004 Displays a single surface per output. 0005 0006 This interface provides a mechanism for a single client to display 0007 simple full-screen surfaces. While there technically may be multiple 0008 clients bound to this interface, only one of those clients should be 0009 shown at a time. 0010 0011 To present a surface, the client uses either the present_surface or 0012 present_surface_for_mode requests. Presenting a surface takes effect 0013 on the next wl_surface.commit. See the individual requests for 0014 details about scaling and mode switches. 0015 0016 The client can have at most one surface per output at any time. 0017 Requesting a surface be presented on an output that already has a 0018 surface replaces the previously presented surface. Presenting a null 0019 surface removes its content and effectively disables the output. 0020 Exactly what happens when an output is "disabled" is 0021 compositor-specific. The same surface may be presented on multiple 0022 outputs simultaneously. 0023 0024 Once a surface is presented on an output, it stays on that output 0025 until either the client removes it or the compositor destroys the 0026 output. This way, the client can update the output's contents by 0027 simply attaching a new buffer. 0028 </description> 0029 0030 <request name="release" type="destructor"> 0031 <description summary="release the wl_fullscreen_shell interface"> 0032 Release the binding from the wl_fullscreen_shell interface 0033 0034 This destroys the server-side object and frees this binding. If 0035 the client binds to wl_fullscreen_shell multiple times, it may wish 0036 to free some of those bindings. 0037 </description> 0038 </request> 0039 0040 <enum name="capability"> 0041 <description summary="capabilities advertised by the compositor"> 0042 Various capabilities that can be advertised by the compositor. They 0043 are advertised one-at-a-time when the wl_fullscreen_shell interface is 0044 bound. See the wl_fullscreen_shell.capability event for more details. 0045 0046 ARBITRARY_MODE: 0047 This is a hint to the client that indicates that the compositor is 0048 capable of setting practically any mode on its outputs. If this 0049 capability is provided, wl_fullscreen_shell.present_surface_for_mode 0050 will almost never fail and clients should feel free to set whatever 0051 mode they like. If the compositor does not advertise this, it may 0052 still support some modes that are not advertised through wl_global.mode 0053 but it is less likely. 0054 0055 CURSOR_PLANE: 0056 This is a hint to the client that indicates that the compositor can 0057 handle a cursor surface from the client without actually compositing. 0058 This may be because of a hardware cursor plane or some other mechanism. 0059 If the compositor does not advertise this capability then setting 0060 wl_pointer.cursor may degrade performance or be ignored entirely. If 0061 CURSOR_PLANE is not advertised, it is recommended that the client draw 0062 its own cursor and set wl_pointer.cursor(NULL). 0063 </description> 0064 <entry name="arbitrary_modes" value="1" summary="compositor is capable of almost any output mode"/> 0065 <entry name="cursor_plane" value="2" summary="compositor has a separate cursor plane"/> 0066 </enum> 0067 0068 <event name="capability"> 0069 <description summary="advertises a capability of the compositor"> 0070 Advertises a single capability of the compositor. 0071 0072 When the wl_fullscreen_shell interface is bound, this event is emitted 0073 once for each capability advertised. Valid capabilities are given by 0074 the wl_fullscreen_shell.capability enum. If clients want to take 0075 advantage of any of these capabilities, they should use a 0076 wl_display.sync request immediately after binding to ensure that they 0077 receive all the capability events. 0078 </description> 0079 <arg name="capability" type="uint"/> 0080 </event> 0081 0082 <enum name="present_method"> 0083 <description summary="different method to set the surface fullscreen"> 0084 Hints to indicate to the compositor how to deal with a conflict 0085 between the dimensions of the surface and the dimensions of the 0086 output. The compositor is free to ignore this parameter. 0087 </description> 0088 <entry name="default" value="0" summary="no preference, apply default policy"/> 0089 <entry name="center" value="1" summary="center the surface on the output"/> 0090 <entry name="zoom" value="2" summary="scale the surface, preserving aspect ratio, to the largest size that will fit on the output" /> 0091 <entry name="zoom_crop" value="3" summary="scale the surface, preserving aspect ratio, to fully fill the output cropping if needed" /> 0092 <entry name="stretch" value="4" summary="scale the surface to the size of the output ignoring aspect ratio" /> 0093 </enum> 0094 0095 <request name="present_surface"> 0096 <description summary="present surface for display"> 0097 Present a surface on the given output. 0098 0099 If the output is null, the compositor will present the surface on 0100 whatever display (or displays) it thinks best. In particular, this 0101 may replace any or all surfaces currently presented so it should 0102 not be used in combination with placing surfaces on specific 0103 outputs. 0104 0105 The method parameter is a hint to the compositor for how the surface 0106 is to be presented. In particular, it tells the compostior how to 0107 handle a size mismatch between the presented surface and the 0108 output. The compositor is free to ignore this parameter. 0109 0110 The "zoom", "zoom_crop", and "stretch" methods imply a scaling 0111 operation on the surface. This will override any kind of output 0112 scaling, so the buffer_scale property of the surface is effectively 0113 ignored. 0114 </description> 0115 <arg name="surface" type="object" interface="wl_surface" allow-null="true"/> 0116 <arg name="method" type="uint"/> 0117 <arg name="output" type="object" interface="wl_output" allow-null="true"/> 0118 </request> 0119 0120 <request name="present_surface_for_mode"> 0121 <description summary="present surface for display at a particular mode"> 0122 Presents a surface on the given output for a particular mode. 0123 0124 If the current size of the output differs from that of the surface, 0125 the compositor will attempt to change the size of the output to 0126 match the surface. The result of the mode-switch operation will be 0127 returned via the provided wl_fullscreen_shell_mode_feedback object. 0128 0129 If the current output mode matches the one requested or if the 0130 compositor successfully switches the mode to match the surface, 0131 then the mode_successful event will be sent and the output will 0132 contain the contents of the given surface. If the compositor 0133 cannot match the output size to the surface size, the mode_failed 0134 will be sent and the output will contain the contents of the 0135 previously presented surface (if any). If another surface is 0136 presented on the given output before either of these has a chance 0137 to happen, the present_cancelled event will be sent. 0138 0139 Due to race conditions and other issues unknown to the client, no 0140 mode-switch operation is guaranteed to succeed. However, if the 0141 mode is one advertised by wl_output.mode or if the compositor 0142 advertises the ARBITRARY_MODES capability, then the client should 0143 expect that the mode-switch operation will usually succeed. 0144 0145 If the size of the presented surface changes, the resulting output 0146 is undefined. The compositor may attempt to change the output mode 0147 to compensate. However, there is no guarantee that a suitable mode 0148 will be found and the client has no way to be notified of success 0149 or failure. 0150 0151 The framerate parameter specifies the desired framerate for the 0152 output in mHz. The compositor is free to ignore this parameter. A 0153 value of 0 indicates that the client has no preference. 0154 0155 If the value of wl_output.scale differs from wl_surface.buffer_scale, 0156 then the compositor may choose a mode that matches either the buffer 0157 size or the surface size. In either case, the surface will fill the 0158 output. 0159 </description> 0160 <arg name="surface" type="object" interface="wl_surface"/> 0161 <arg name="output" type="object" interface="wl_output"/> 0162 <arg name="framerate" type="int"/> 0163 <arg name="feedback" type="new_id" interface="_wl_fullscreen_shell_mode_feedback"/> 0164 </request> 0165 0166 <enum name="error"> 0167 <description summary="wl_fullscreen_shell error values"> 0168 These errors can be emitted in response to wl_fullscreen_shell requests 0169 </description> 0170 <entry name="invalid_method" value="0" summary="present_method is not known"/> 0171 </enum> 0172 </interface> 0173 0174 <interface name="_wl_fullscreen_shell_mode_feedback" version="1"> 0175 <event name="mode_successful"> 0176 <description summary="mode switch succeeded"> 0177 This event indicates that the attempted mode switch operation was 0178 successful. A surface of the size requested in the mode switch 0179 will fill the output without scaling. 0180 0181 Upon receiving this event, the client should destroy the 0182 wl_fullscreen_shell_mode_feedback object. 0183 </description> 0184 </event> 0185 <event name="mode_failed"> 0186 <description summary="mode switch failed"> 0187 This event indicates that the attempted mode switch operation 0188 failed. This may be because the requested output mode is not 0189 possible or it may mean that the compositor does not want to allow it. 0190 0191 Upon receiving this event, the client should destroy the 0192 wl_fullscreen_shell_mode_feedback object. 0193 </description> 0194 </event> 0195 <event name="present_cancelled"> 0196 <description summary="mode switch cancelled"> 0197 This event indicates that the attempted mode switch operation was 0198 cancelled. Most likely this is because the client requested a 0199 second mode switch before the first one completed. 0200 0201 Upon receiving this event, the client should destroy the 0202 wl_fullscreen_shell_mode_feedback object. 0203 </description> 0204 </event> 0205 </interface> 0206 </protocol>