LOVE/megasource
1
0
Fork 0
mirror of https://github.com/love2d/megasource.git synced 2026-08-20 04:30:45 +02:00
Code Issues Packages Projects Releases Wiki Activity

update SDL3 to latest commit

Browse Source
This commit is contained in:
Sasha Szpakowski
2024-10-06 20:30:44 -03:00
parent 1b0fdc338b
commit 9e5eb1b018
1426 changed files with 242456 additions and 103496 deletions
Download Patch File Download Diff File Expand all files Collapse all files
libs/SDL3/wayland-protocols/alpha-modifier-v1.xml
+103
View File
@@ -0,0 +1,103 @@
<?xml version="1.0" encoding="UTF-8"?>
<protocol name="alpha_modifier_v1">
<copyright>
Copyright © 2024 Xaver Hugl
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 (including the next
paragraph) 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="wp_alpha_modifier_v1" version="1">
<description summary="surface alpha modifier manager">
This interface allows a client to set a factor for the alpha values on a
surface, which can be used to offload such operations to the compositor,
which can in turn for example offload them to KMS.
Warning! The protocol described in this file is currently in the testing
phase. Backward compatible changes may be added together with the
corresponding interface version bump. Backward incompatible changes can
only be done by creating a new major version of the extension.
</description>
<request name="destroy" type="destructor">
<description summary="destroy the alpha modifier manager object">
Destroy the alpha modifier manager. This doesn't destroy objects
created with the manager.
</description>
</request>
<enum name="error">
<entry name="already_constructed" value="0"
summary="wl_surface already has a alpha modifier object"/>
</enum>
<request name="get_surface">
<description summary="create a new toplevel decoration object">
Create a new alpha modifier surface object associated with the
given wl_surface. If there is already such an object associated with
the wl_surface, the already_constructed error will be raised.
</description>
<arg name="id" type="new_id" interface="wp_alpha_modifier_surface_v1"/>
<arg name="surface" type="object" interface="wl_surface"/>
</request>
</interface>
<interface name="wp_alpha_modifier_surface_v1" version="1">
<description summary="alpha modifier object for a surface">
This interface allows the client to set a factor for the alpha values on
a surface, which can be used to offload such operations to the compositor.
The default factor is UINT32_MAX.
This object has to be destroyed before the associated wl_surface. Once the
wl_surface is destroyed, all request on this object will raise the
no_surface error.
</description>
<enum name="error">
<entry name="no_surface" value="0" summary="wl_surface was destroyed"/>
</enum>
<request name="destroy" type="destructor">
<description summary="destroy the alpha modifier object">
This destroys the object, and is equivalent to set_multiplier with
a value of UINT32_MAX, with the same double-buffered semantics as
set_multiplier.
</description>
</request>
<request name="set_multiplier">
<description summary="specify the alpha multiplier">
Sets the alpha multiplier for the surface. The alpha multiplier is
double-buffered state, see wl_surface.commit for details.
This factor is applied in the compositor's blending space, as an
additional step after the processing of per-pixel alpha values for the
wl_surface. The exact meaning of the factor is thus undefined, unless
the blending space is specified in a different extension.
This multiplier is applied even if the buffer attached to the
wl_surface doesn't have an alpha channel; in that case an alpha value
of one is used instead.
Zero means completely transparent, UINT32_MAX means completely opaque.
</description>
<arg name="factor" type="uint"/>
</request>
</interface>
</protocol>
libs/SDL3/wayland-protocols/frog-color-management-v1.xml
+356
View File
@@ -0,0 +1,356 @@
<?xml version="1.0" encoding="UTF-8"?>
<protocol name="frog_color_management_v1">
<copyright>
Copyright © 2023 Joshua Ashton for Valve Software
Copyright © 2023 Xaver Hugl
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 (including the next
paragraph) 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>
<description summary="experimental color management protocol">
The aim of this color management extension is to get HDR games working quickly,
and have an easy way to test implementations in the wild before the upstream
protocol is ready to be merged.
For that purpose it's intentionally limited and cut down and does not serve
all uses cases.
</description>
<interface name="frog_color_management_factory_v1" version="1">
<description summary="color management factory">
The color management factory singleton creates color managed surface objects.
</description>
<request name="destroy" type="destructor"></request>
<request name="get_color_managed_surface">
<description summary="create color management interface for surface">
</description>
<arg name="surface" type="object" interface="wl_surface"
summary="target surface"/>
<arg name="callback" type="new_id" interface="frog_color_managed_surface"
summary="new color managed surface object"/>
</request>
</interface>
<interface name="frog_color_managed_surface" version="1">
<description summary="color managed surface">
Interface for changing surface color management and HDR state.
An implementation must: support every part of the version
of the frog_color_managed_surface interface it exposes.
Including all known enums associated with a given version.
</description>
<request name="destroy" type="destructor">
<description summary="destroy color managed surface">
Destroying the color managed surface resets all known color
state for the surface back to 'undefined' implementation-specific
values.
</description>
</request>
<enum name="transfer_function">
<description summary="known transfer functions">
Extended information on the transfer functions described
here can be found in the Khronos Data Format specification:
https://registry.khronos.org/DataFormat/specs/1.3/dataformat.1.3.html
</description>
<entry name="undefined" value="0" summary="specifies undefined, implementation-specific handling of the surface's transfer function."/>
<entry name="srgb" value="1" summary="specifies the sRGB non-linear EOTF. An implementation may: display this as Gamma 2.2 for the purposes of being consistent with content rendering across displays, rendering_intent and user expectations."/>
<entry name="gamma_22" value="2" summary="specifies gamma 2.2 power curve as the EOTF"/>
<entry name="st2084_pq" value="3" summary="specifies the SMPTE ST2084 Perceptual Quantizer (PQ) EOTF"/>
<entry name="scrgb_linear" value="4" summary="specifies the scRGB (extended sRGB) linear EOTF. Note: Primaries outside the gamut triangle specified can be expressed with negative values for this transfer function."/>
</enum>
<request name="set_known_transfer_function">
<description summary="sets a known transfer function for a surface"/>
<arg name="transfer_function" type="uint" enum="transfer_function" summary="transfer function for the surface"/>
</request>
<enum name="primaries">
<description summary="known primaries"/>
<entry name="undefined" value="0" summary="specifies undefined, implementation-specific handling"/>
<entry name="rec709" value="1" summary="specifies Rec.709/sRGB primaries with D65 white point"/>
<entry name="rec2020" value="2" summary="specifies Rec.2020/HDR10 primaries with D65 white point"/>
</enum>
<request name="set_known_container_color_volume">
<description summary="sets the container color volume (primaries) for a surface"/>
<arg name="primaries" type="uint" enum="primaries" summary="primaries for the surface"/>
</request>
<enum name="render_intent">
<description summary="known render intents">
Extended information on render intents described
here can be found in ICC.1:2022:
https://www.color.org/specification/ICC.1-2022-05.pdf
</description>
<entry name="perceptual" value="0" summary="perceptual"/>
</enum>
<request name="set_render_intent">
<description summary="sets the render intent for a surface">
NOTE: On a surface with "perceptual" (default) render intent, handling of the container's color volume
is implementation-specific, and may differ between different transfer functions it is paired with:
ie. sRGB + 709 rendering may have it's primaries widened to more of the available display's gamut
to be be more pleasing for the viewer.
Compared to scRGB Linear + 709 being treated faithfully as 709
(including utilizing negatives out of the 709 gamut triangle)
</description>
<arg name="render_intent" type="uint" enum="render_intent" summary="render intent for the surface"/>
</request>
<request name="set_hdr_metadata">
<description summary="set HDR metadata for a surface">
Forwards HDR metadata from the client to the compositor.
HDR Metadata Infoframe as per CTA 861.G spec.
Usage of this HDR metadata is implementation specific and
outside of the scope of this protocol.
</description>
<arg name="mastering_display_primary_red_x" type="uint">
<description summary="red primary x coordinate">
Mastering Red Color Primary X Coordinate of the Data.
Coded as unsigned 16-bit values in units of
0.00002, where 0x0000 represents zero and 0xC350
represents 1.0000.
</description>
</arg>
<arg name="mastering_display_primary_red_y" type="uint">
<description summary="red primary y coordinate">
Mastering Red Color Primary Y Coordinate of the Data.
Coded as unsigned 16-bit values in units of
0.00002, where 0x0000 represents zero and 0xC350
represents 1.0000.
</description>
</arg>
<arg name="mastering_display_primary_green_x" type="uint">
<description summary="green primary x coordinate">
Mastering Green Color Primary X Coordinate of the Data.
Coded as unsigned 16-bit values in units of
0.00002, where 0x0000 represents zero and 0xC350
represents 1.0000.
</description>
</arg>
<arg name="mastering_display_primary_green_y" type="uint">
<description summary="green primary y coordinate">
Mastering Green Color Primary Y Coordinate of the Data.
Coded as unsigned 16-bit values in units of
0.00002, where 0x0000 represents zero and 0xC350
represents 1.0000.
</description>
</arg>
<arg name="mastering_display_primary_blue_x" type="uint">
<description summary="blue primary x coordinate">
Mastering Blue Color Primary X Coordinate of the Data.
Coded as unsigned 16-bit values in units of
0.00002, where 0x0000 represents zero and 0xC350
represents 1.0000.
</description>
</arg>
<arg name="mastering_display_primary_blue_y" type="uint">
<description summary="blue primary y coordinate">
Mastering Blue Color Primary Y Coordinate of the Data.
Coded as unsigned 16-bit values in units of
0.00002, where 0x0000 represents zero and 0xC350
represents 1.0000.
</description>
</arg>
<arg name="mastering_white_point_x" type="uint">
<description summary="white point x coordinate">
Mastering White Point X Coordinate of the Data.
These are coded as unsigned 16-bit values in units of
0.00002, where 0x0000 represents zero and 0xC350
represents 1.0000.
</description>
</arg>
<arg name="mastering_white_point_y" type="uint">
<description summary="white point y coordinate">
Mastering White Point Y Coordinate of the Data.
These are coded as unsigned 16-bit values in units of
0.00002, where 0x0000 represents zero and 0xC350
represents 1.0000.
</description>
</arg>
<arg name="max_display_mastering_luminance" type="uint">
<description summary="max display mastering luminance">
Max Mastering Display Luminance.
This value is coded as an unsigned 16-bit value in units of 1 cd/m2,
where 0x0001 represents 1 cd/m2 and 0xFFFF represents 65535 cd/m2.
</description>
</arg>
<arg name="min_display_mastering_luminance" type="uint">
<description summary="min display mastering luminance">
Min Mastering Display Luminance.
This value is coded as an unsigned 16-bit value in units of
0.0001 cd/m2, where 0x0001 represents 0.0001 cd/m2 and 0xFFFF
represents 6.5535 cd/m2.
</description>
</arg>
<arg name="max_cll" type="uint">
<description summary="max content light level">
Max Content Light Level.
This value is coded as an unsigned 16-bit value in units of 1 cd/m2,
where 0x0001 represents 1 cd/m2 and 0xFFFF represents 65535 cd/m2.
</description>
</arg>
<arg name="max_fall" type="uint">
<description summary="max frame average light level">
Max Frame Average Light Level.
This value is coded as an unsigned 16-bit value in units of 1 cd/m2,
where 0x0001 represents 1 cd/m2 and 0xFFFF represents 65535 cd/m2.
</description>
</arg>
</request>
<event name="preferred_metadata">
<description summary="preferred metadata for a surface">
Current preferred metadata for a surface.
The application should use this information to tone-map its buffers
to this target before committing.
This metadata does not necessarily correspond to any physical output, but
rather what the compositor thinks would be best for a given surface.
</description>
<arg name="transfer_function" type="uint" enum="transfer_function">
<description summary="output's current transfer function">
Specifies a known transfer function that corresponds to the
output the surface is targeting.
</description>
</arg>
<arg name="output_display_primary_red_x" type="uint">
<description summary="red primary x coordinate">
Output Red Color Primary X Coordinate of the Data.
Coded as unsigned 16-bit values in units of
0.00002, where 0x0000 represents zero and 0xC350
represents 1.0000.
</description>
</arg>
<arg name="output_display_primary_red_y" type="uint">
<description summary="red primary y coordinate">
Output Red Color Primary Y Coordinate of the Data.
Coded as unsigned 16-bit values in units of
0.00002, where 0x0000 represents zero and 0xC350
represents 1.0000.
</description>
</arg>
<arg name="output_display_primary_green_x" type="uint">
<description summary="green primary x coordinate">
Output Green Color Primary X Coordinate of the Data.
Coded as unsigned 16-bit values in units of
0.00002, where 0x0000 represents zero and 0xC350
represents 1.0000.
</description>
</arg>
<arg name="output_display_primary_green_y" type="uint">
<description summary="green primary y coordinate">
Output Green Color Primary Y Coordinate of the Data.
Coded as unsigned 16-bit values in units of
0.00002, where 0x0000 represents zero and 0xC350
represents 1.0000.
</description>
</arg>
<arg name="output_display_primary_blue_x" type="uint">
<description summary="blue primary x coordinate">
Output Blue Color Primary X Coordinate of the Data.
Coded as unsigned 16-bit values in units of
0.00002, where 0x0000 represents zero and 0xC350
represents 1.0000.
</description>
</arg>
<arg name="output_display_primary_blue_y" type="uint">
<description summary="blue primary y coordinate">
Output Blue Color Primary Y Coordinate of the Data.
Coded as unsigned 16-bit values in units of
0.00002, where 0x0000 represents zero and 0xC350
represents 1.0000.
</description>
</arg>
<arg name="output_white_point_x" type="uint">
<description summary="white point x coordinate">
Output White Point X Coordinate of the Data.
These are coded as unsigned 16-bit values in units of
0.00002, where 0x0000 represents zero and 0xC350
represents 1.0000.
</description>
</arg>
<arg name="output_white_point_y" type="uint">
<description summary="white point y coordinate">
Output White Point Y Coordinate of the Data.
These are coded as unsigned 16-bit values in units of
0.00002, where 0x0000 represents zero and 0xC350
represents 1.0000.
</description>
</arg>
<arg name="max_luminance" type="uint">
<description summary="maximum luminance">
Max Output Luminance
The max luminance in nits that the output is capable of rendering in small areas.
Content should: not exceed this value to avoid clipping.
This value is coded as an unsigned 16-bit value in units of 1 cd/m2,
where 0x0001 represents 1 cd/m2 and 0xFFFF represents 65535 cd/m2.
</description>
</arg>
<arg name="min_luminance" type="uint">
<description summary="minimum luminance">
Min Output Luminance
The min luminance that the output is capable of rendering.
Content should: not exceed this value to avoid clipping.
This value is coded as an unsigned 16-bit value in units of
0.0001 cd/m2, where 0x0001 represents 0.0001 cd/m2 and 0xFFFF
represents 6.5535 cd/m2.
</description>
</arg>
<arg name="max_full_frame_luminance" type="uint">
<description summary="maximum full frame luminance">
Max Full Frame Luminance
The max luminance in nits that the output is capable of rendering for the
full frame sustained.
This value is coded as an unsigned 16-bit value in units of 1 cd/m2,
where 0x0001 represents 1 cd/m2 and 0xFFFF represents 65535 cd/m2.
</description>
</arg>
</event>
</interface>
</protocol>
libs/SDL3/wayland-protocols/tablet-unstable-v2.xml → libs/SDL3/wayland-protocols/tablet-v2.xml
+13 -13
View File
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="UTF-8"?>
<protocol name="tablet_unstable_v2">
<protocol name="tablet_v2">
<copyright>
Copyright 2014 © Stephen "Lyude" Chandler Paul
@@ -104,15 +104,6 @@
compositor-specific policy when a tool can be removed. Common approaches
will likely include some form of removing a tool when all tablets the
tool was used on are removed.
Warning! The protocol described in this file is experimental and
backward incompatible changes may be made. Backward compatible changes
may be added together with the corresponding interface version bump.
Backward incompatible changes are done by bumping the version number in
the protocol and interface names and resetting the interface version.
Once the protocol is to be declared stable, the 'z' prefix and the
version number in the protocol and interface names are removed and the
interface version number is reset.
</description>
<interface name="zwp_tablet_manager_v2" version="1">
@@ -247,7 +238,7 @@
previously been used as cursor surface for a different tool, a
protocol error is raised.
</description>
<arg name="serial" type="uint" summary="serial of the enter event"/>
<arg name="serial" type="uint" summary="serial of the proximity_in event"/>
<arg name="surface" type="object" interface="wl_surface" allow-null="true"/>
<arg name="hotspot_x" type="int" summary="surface-local x coordinate"/>
<arg name="hotspot_y" type="int" summary="surface-local y coordinate"/>
@@ -596,14 +587,23 @@
<event name="name">
<description summary="tablet device name">
A descriptive name for the tablet device.
If the device has no descriptive name, this event is not sent.
This event is sent in the initial burst of events before the
wp_tablet.done event.
wp_tablet.done event.
</description>
<arg name="name" type="string" summary="the device name"/>
</event>
<event name="id">
<description summary="tablet device USB vendor/product id">
The USB vendor and product IDs for the tablet device.
If the device has no USB vendor/product ID, this event is not sent.
This can happen for virtual devices or non-USB devices, for instance.
This event is sent in the initial burst of events before the
wp_tablet.done event.
</description>
@@ -1156,7 +1156,7 @@
</event>
<event name="leave">
<description summary="enter event">
<description summary="leave event">
Notification that this pad is no longer focused on the specified
surface.
</description>
libs/SDL3/wayland-protocols/xdg-dialog-v1.xml
+110
View File
@@ -0,0 +1,110 @@
<?xml version="1.0" encoding="UTF-8"?>
<protocol name="xdg_dialog_v1">
<copyright>
Copyright © 2023 Carlos Garnacho
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 (including the next
paragraph) 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="xdg_wm_dialog_v1" version="1">
<description summary="create dialogs related to other toplevels">
The xdg_wm_dialog_v1 interface is exposed as a global object allowing
to register surfaces with a xdg_toplevel role as "dialogs" relative to
another toplevel.
The compositor may let this relation influence how the surface is
placed, displayed or interacted with.
Warning! The protocol described in this file is currently in the testing
phase. Backward compatible changes may be added together with the
corresponding interface version bump. Backward incompatible changes can
only be done by creating a new major version of the extension.
</description>
<enum name="error">
<entry name="already_used" value="0"
summary="the xdg_toplevel object has already been used to create a xdg_dialog_v1"/>
</enum>
<request name="destroy" type="destructor">
<description summary="destroy the dialog manager object">
Destroys the xdg_wm_dialog_v1 object. This does not affect
the xdg_dialog_v1 objects generated through it.
</description>
</request>
<request name="get_xdg_dialog">
<description summary="create a dialog object">
Creates a xdg_dialog_v1 object for the given toplevel. See the interface
description for more details.
Compositors must raise an already_used error if clients attempt to
create multiple xdg_dialog_v1 objects for the same xdg_toplevel.
</description>
<arg name="id" type="new_id" interface="xdg_dialog_v1"/>
<arg name="toplevel" type="object" interface="xdg_toplevel"/>
</request>
</interface>
<interface name="xdg_dialog_v1" version="1">
<description summary="dialog object">
A xdg_dialog_v1 object is an ancillary object tied to a xdg_toplevel. Its
purpose is hinting the compositor that the toplevel is a "dialog" (e.g. a
temporary window) relative to another toplevel (see
xdg_toplevel.set_parent). If the xdg_toplevel is destroyed, the xdg_dialog_v1
becomes inert.
Through this object, the client may provide additional hints about
the purpose of the secondary toplevel. This interface has no effect
on toplevels that are not attached to a parent toplevel.
</description>
<request name="destroy" type="destructor">
<description summary="destroy the dialog object">
Destroys the xdg_dialog_v1 object. If this object is destroyed
before the related xdg_toplevel, the compositor should unapply its
effects.
</description>
</request>
<request name="set_modal">
<description summary="mark dialog as modal">
Hints that the dialog has "modal" behavior. Modal dialogs typically
require to be fully addressed by the user (i.e. closed) before resuming
interaction with the parent toplevel, and may require a distinct
presentation.
Clients must implement the logic to filter events in the parent
toplevel on their own.
Compositors may choose any policy in event delivery to the parent
toplevel, from delivering all events unfiltered to using them for
internal consumption.
</description>
</request>
<request name="unset_modal">
<description summary="mark dialog as not modal">
Drops the hint that this dialog has "modal" behavior. See
xdg_dialog_v1.set_modal for more details.
</description>
</request>
</interface>
</protocol>
libs/SDL3/wayland-protocols/xdg-toplevel-icon-v1.xml
+203
View File
@@ -0,0 +1,203 @@
<?xml version="1.0" encoding="UTF-8"?>
<protocol name="xdg_toplevel_icon_v1">
<copyright>
Copyright © 2023-2024 Matthias Klumpp
Copyright © 2024 David Edmundson
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 (including the next
paragraph) 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>
<description summary="protocol to assign icons to toplevels">
This protocol allows clients to set icons for their toplevel surfaces
either via the XDG icon stock (using an icon name), or from pixel data.
A toplevel icon represents the individual toplevel (unlike the application
or launcher icon, which represents the application as a whole), and may be
shown in window switchers, window overviews and taskbars that list
individual windows.
This document adheres to RFC 2119 when using words like "must",
"should", "may", etc.
Warning! The protocol described in this file is currently in the testing
phase. Backward compatible changes may be added together with the
corresponding interface version bump. Backward incompatible changes can
only be done by creating a new major version of the extension.
</description>
<interface name="xdg_toplevel_icon_manager_v1" version="1">
<description summary="interface to manage toplevel icons">
This interface allows clients to create toplevel window icons and set
them on toplevel windows to be displayed to the user.
</description>
<request name="destroy" type="destructor">
<description summary="destroy the toplevel icon manager">
Destroy the toplevel icon manager.
This does not destroy objects created with the manager.
</description>
</request>
<request name="create_icon">
<description summary="create a new icon instance">
Creates a new icon object. This icon can then be attached to a
xdg_toplevel via the 'set_icon' request.
</description>
<arg name="id" type="new_id" interface="xdg_toplevel_icon_v1"/>
</request>
<request name="set_icon">
<description summary="set an icon on a toplevel window">
This request assigns the icon 'icon' to 'toplevel', or clears the
toplevel icon if 'icon' was null.
This state is double-buffered and is applied on the next
wl_surface.commit of the toplevel.
After making this call, the xdg_toplevel_icon_v1 provided as 'icon'
can be destroyed by the client without 'toplevel' losing its icon.
The xdg_toplevel_icon_v1 is immutable from this point, and any
future attempts to change it must raise the
'xdg_toplevel_icon_v1.immutable' protocol error.
The compositor must set the toplevel icon from either the pixel data
the icon provides, or by loading a stock icon using the icon name.
See the description of 'xdg_toplevel_icon_v1' for details.
If 'icon' is set to null, the icon of the respective toplevel is reset
to its default icon (usually the icon of the application, derived from
its desktop-entry file, or a placeholder icon).
If this request is passed an icon with no pixel buffers or icon name
assigned, the icon must be reset just like if 'icon' was null.
</description>
<arg name="toplevel" type="object" interface="xdg_toplevel" summary="the toplevel to act on"/>
<arg name="icon" type="object" interface="xdg_toplevel_icon_v1" allow-null="true"/>
</request>
<event name="icon_size">
<description summary="describes a supported &amp; preferred icon size">
This event indicates an icon size the compositor prefers to be
available if the client has scalable icons and can render to any size.
When the 'xdg_toplevel_icon_manager_v1' object is created, the
compositor may send one or more 'icon_size' events to describe the list
of preferred icon sizes. If the compositor has no size preference, it
may not send any 'icon_size' event, and it is up to the client to
decide a suitable icon size.
A sequence of 'icon_size' events must be finished with a 'done' event.
If the compositor has no size preferences, it must still send the
'done' event, without any preceding 'icon_size' events.
</description>
<arg name="size" type="int"
summary="the edge size of the square icon in surface-local coordinates, e.g. 64"/>
</event>
<event name="done">
<description summary="all information has been sent">
This event is sent after all 'icon_size' events have been sent.
</description>
</event>
</interface>
<interface name="xdg_toplevel_icon_v1" version="1">
<description summary="a toplevel window icon">
This interface defines a toplevel icon.
An icon can have a name, and multiple buffers.
In order to be applied, the icon must have either a name, or at least
one buffer assigned. Applying an empty icon (with no buffer or name) to
a toplevel should reset its icon to the default icon.
It is up to compositor policy whether to prefer using a buffer or loading
an icon via its name. See 'set_name' and 'add_buffer' for details.
</description>
<enum name="error">
<entry name="invalid_buffer"
summary="the provided buffer does not satisfy requirements"
value="1"/>
<entry name="immutable"
summary="the icon has already been assigned to a toplevel and must not be changed"
value="2"/>
<entry name="no_buffer"
summary="the provided buffer has been destroyed before the toplevel icon"
value="3"/>
</enum>
<request name="destroy" type="destructor">
<description summary="destroy the icon object">
Destroys the 'xdg_toplevel_icon_v1' object.
The icon must still remain set on every toplevel it was assigned to,
until the toplevel icon is reset explicitly.
</description>
</request>
<request name="set_name">
<description summary="set an icon name">
This request assigns an icon name to this icon.
Any previously set name is overridden.
The compositor must resolve 'icon_name' according to the lookup rules
described in the XDG icon theme specification[1] using the
environment's current icon theme.
If the compositor does not support icon names or cannot resolve
'icon_name' according to the XDG icon theme specification it must
fall back to using pixel buffer data instead.
If this request is made after the icon has been assigned to a toplevel
via 'set_icon', a 'immutable' error must be raised.
[1]: https://specifications.freedesktop.org/icon-theme-spec/icon-theme-spec-latest.html
</description>
<arg name="icon_name" type="string"/>
</request>
<request name="add_buffer">
<description summary="add icon data from a pixel buffer">
This request adds pixel data supplied as wl_buffer to the icon.
The client should add pixel data for all icon sizes and scales that
it can provide, or which are explicitly requested by the compositor
via 'icon_size' events on xdg_toplevel_icon_manager_v1.
The wl_buffer supplying pixel data as 'buffer' must be backed by wl_shm
and must be a square (width and height being equal).
If any of these buffer requirements are not fulfilled, a 'invalid_buffer'
error must be raised.
If this icon instance already has a buffer of the same size and scale
from a previous 'add_buffer' request, data from the last request
overrides the preexisting pixel data.
The wl_buffer must be kept alive for as long as the xdg_toplevel_icon
it is associated with is not destroyed, otherwise a 'no_buffer' error
is raised. The buffer contents must not be modified after it was
assigned to the icon.
If this request is made after the icon has been assigned to a toplevel
via 'set_icon', a 'immutable' error must be raised.
</description>
<arg name="buffer" type="object" interface="wl_buffer"/>
<arg name="scale" type="int"
summary="the scaling factor of the icon, e.g. 1"/>
</request>
</interface>
</protocol>