143 lines
6.6 KiB
XML
143 lines
6.6 KiB
XML
|
<?xml version="1.0" encoding="UTF-8"?>
|
||
|
<protocol name="gamescope_tearing_control_unstable_v1">
|
||
|
|
||
|
<copyright>
|
||
|
Copyright © 2021 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="gamescope_tearing_control_v1" version="1">
|
||
|
<description summary="protocol for tearing control">
|
||
|
This global is a factory interface, allowing clients to request
|
||
|
the compositor to use asynchronous page flips on a per-surface basis.
|
||
|
|
||
|
Graphics APIs, like EGL or Vulkan, that manage the buffer queue and
|
||
|
commits of a wl_surface themselves, are likely to be using this
|
||
|
extension internally. If a client is using such an API for a
|
||
|
wl_surface, it should not directly use this extension on that surface,
|
||
|
to avoid raising a tearing_control_exists protocol error.
|
||
|
|
||
|
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>
|
||
|
|
||
|
<request name="destroy" type="destructor">
|
||
|
<description summary="destroy tearing control factory object">
|
||
|
Destroy this tearing control factory object. Other objects, including
|
||
|
gamescope_surface_tearing_control_v1 objects created by this factory,
|
||
|
shall not be affected by this request.
|
||
|
</description>
|
||
|
</request>
|
||
|
|
||
|
<enum name="error">
|
||
|
<entry name="tearing_control_exists" value="0"
|
||
|
summary="the surface already has a tearing object associated"/>
|
||
|
</enum>
|
||
|
|
||
|
<request name="get_tearing_control">
|
||
|
<description summary="extend surface interface for tearing control">
|
||
|
Instantiate an interface extension for the given wl_surface to
|
||
|
request asynchronous page flips for presentation.
|
||
|
|
||
|
If the given wl_surface already has a gamescope_surface_tearing_control_v1
|
||
|
object associated, the tearing_control_exists protocol error is raised.
|
||
|
</description>
|
||
|
|
||
|
<arg name="id" type="new_id"
|
||
|
interface="gamescope_surface_tearing_control_v1"
|
||
|
summary="the new surface tearing interface id"/>
|
||
|
<arg name="surface" type="object" interface="wl_surface"
|
||
|
summary="the surface"/>
|
||
|
</request>
|
||
|
</interface>
|
||
|
|
||
|
<interface name="gamescope_surface_tearing_control_v1" version="1">
|
||
|
<description summary="per-surface tearing control request">
|
||
|
An additional interface to a wl_surface object, which allows the client
|
||
|
to hint to the compositor if and when it should use asynchronous page
|
||
|
flips for presentation.
|
||
|
</description>
|
||
|
|
||
|
<enum name="presentation_hint">
|
||
|
<description summary="presentation hint values">
|
||
|
This enum provides information for if and when submitted frames from
|
||
|
the client may be presented with tearing. The possible values are:
|
||
|
|
||
|
VSYNC:
|
||
|
Presentation should be synchronized to the vertical retrace by the
|
||
|
display hardware so that tearing doesn't happen.
|
||
|
|
||
|
VSYNC_RELAXED:
|
||
|
Presentation should be synchronized to the vertical retrace by the
|
||
|
display hardware so that tearing doesn't happen as long as the client
|
||
|
submits new frame fast enough. If a frame is late for presentation,
|
||
|
that is, if more than one vertical retrace has occurred since the last
|
||
|
commit then the compositor should use asynchronous page flips to
|
||
|
immediately present the frame. This may cause visible tearing.
|
||
|
The compositor is encouraged to send requested frame callbacks as soon
|
||
|
as possible after such a late commit to make sure clients have as much
|
||
|
time as possible to render their next frame.
|
||
|
|
||
|
ASYNC:
|
||
|
Presentation should not be synchronized to the vertical retrace,
|
||
|
committed frames are meant to be immediately presented with asynchronous
|
||
|
page flips with as little delay as possible. Tearing will be visible.
|
||
|
The compositor is encouraged to send requested frame callbacks as soon
|
||
|
as possible after every commit.
|
||
|
</description>
|
||
|
<entry name="vsync" value="0"
|
||
|
summary="tearing-free presentation"/>
|
||
|
<entry name="vsync_relaxed" value="1"
|
||
|
summary="async pageflips on missed presentation deadline"/>
|
||
|
<entry name="async" value="2"
|
||
|
summary="async pageflips for all frames"/>
|
||
|
</enum>
|
||
|
|
||
|
<request name="set_presentation_hint">
|
||
|
<description summary="set presentation hint">
|
||
|
Set the presentation hint for the associated wl_surface. See
|
||
|
presentation_hint for the description. This state is double-buffered
|
||
|
and is applied on the next wl_surface.commit.
|
||
|
|
||
|
The compositor is free to dynamically respect or ignore this hint based
|
||
|
on various conditions, including GPU capabilities and surface window
|
||
|
state.
|
||
|
</description>
|
||
|
<arg name="hint" type="uint" enum="presentation_hint"/>
|
||
|
</request>
|
||
|
|
||
|
<request name="destroy" type="destructor">
|
||
|
<description summary="destroy synchronization object">
|
||
|
Destroy this surface tearing object and remove the presentation hint.
|
||
|
The change will be applied on the next wl_surface.commit.
|
||
|
</description>
|
||
|
</request>
|
||
|
</interface>
|
||
|
|
||
|
</protocol>
|
||
|
|