[PATCH wayland-protocols 1/4] stable: add presentation-time draft
Pekka Paalanen
ppaalanen at gmail.com
Mon Feb 22 13:34:40 UTC 2016
From: Pekka Paalanen <pekka.paalanen at collabora.co.uk>
This XML file has been copied verbatim from Weston 1.10.0 release,
protocol/presentation_timing.xml. The last behavioral change to that
file was in December 2014, so the behaviour is considered stable.
Interfaces still need to be renamed according wayland-protocols policy.
That will be done in a follow-up patch to clearly show the changes.
Signed-off-by: Pekka Paalanen <pekka.paalanen at collabora.co.uk>
---
stable/presentation-time/README | 5 +
stable/presentation-time/presentation-time.xml | 274 +++++++++++++++++++++++++
2 files changed, 279 insertions(+)
create mode 100644 stable/presentation-time/README
create mode 100644 stable/presentation-time/presentation-time.xml
diff --git a/stable/presentation-time/README b/stable/presentation-time/README
new file mode 100644
index 0000000..c7781ea
--- /dev/null
+++ b/stable/presentation-time/README
@@ -0,0 +1,5 @@
+Presentation time protocol
+
+Maintainers:
+Pekka Paalanen <pekka.paalanen at collabora.co.uk>
+
diff --git a/stable/presentation-time/presentation-time.xml b/stable/presentation-time/presentation-time.xml
new file mode 100644
index 0000000..10a5f14
--- /dev/null
+++ b/stable/presentation-time/presentation-time.xml
@@ -0,0 +1,274 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="presentation_timing">
+<!-- wrap:70 -->
+
+ <copyright>
+ Copyright © 2013-2014 Collabora, Ltd.
+
+ 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="presentation" version="1">
+ <description summary="timed presentation related wl_surface requests">
+
+<!-- Introduction -->
+
+ The main feature of this interface is accurate presentation
+ timing feedback to ensure smooth video playback while maintaining
+ audio/video synchronization. Some features use the concept of a
+ presentation clock, which is defined in presentation.clock_id
+ event.
+
+ Request 'feedback' can be regarded as an additional wl_surface
+ method. It is part of the double-buffered surface state update
+ mechanism, where other requests first set up the state and then
+ wl_surface.commit atomically applies the state into use. In
+ other words, wl_surface.commit submits a content update.
+
+<!-- Completing presentation -->
+
+ When the final realized presentation time is available, e.g.
+ after a framebuffer flip completes, the requested
+ presentation_feedback.presented events are sent. The final
+ presentation time can differ from the compositor's predicted
+ display update time and the update's target time, especially
+ when the compositor misses its target vertical blanking period.
+ </description>
+
+ <enum name="error">
+ <description summary="fatal presentation errors">
+ These fatal protocol errors may be emitted in response to
+ illegal presentation requests.
+ </description>
+ <entry name="invalid_timestamp" value="0"
+ summary="invalid value in tv_nsec"/>
+ <entry name="invalid_flag" value="1"
+ summary="invalid flag"/>
+ </enum>
+
+ <request name="destroy" type="destructor">
+ <description summary="unbind from the presentation interface">
+ Informs the server that the client will not be using this
+ protocol object anymore. This does not affect any existing
+ objects created by this interface.
+ </description>
+ </request>
+
+ <request name="feedback">
+ <description summary="request presentation feedback information">
+ Request presentation feedback for the current content submission
+ on the given surface. This creates a new presentation_feedback
+ object, which will deliver the feedback information once. If
+ multiple presentation_feedback objects are created for the same
+ submission, they will all deliver the same information.
+
+ For details on what information is returned, see
+ presentation_feedback interface.
+ </description>
+
+ <arg name="surface" type="object" interface="wl_surface"
+ summary="target surface"/>
+ <arg name="callback" type="new_id" interface="presentation_feedback"
+ summary="new feedback object"/>
+ </request>
+
+ <event name="clock_id">
+ <description summary="clock ID for timestamps">
+ This event tells the client in which clock domain the
+ compositor interprets the timestamps used by the presentation
+ extension. This clock is called the presentation clock.
+
+ The compositor sends this event when the client binds to the
+ presentation interface. The presentation clock does not change
+ during the lifetime of the client connection.
+
+ The clock identifier is platform dependent. Clients must be
+ able to query the current clock value directly, not by asking
+ the compositor.
+
+ On Linux/glibc, the identifier value is one of the clockid_t
+ values accepted by clock_gettime(). clock_gettime() is defined
+ by POSIX.1-2001.
+
+ Compositors should prefer a clock which does not jump and is
+ not slewed e.g. by NTP. The absolute value of the clock is
+ irrelevant. Precision of one millisecond or better is
+ recommended.
+
+ Timestamps in this clock domain are expressed as tv_sec_hi,
+ tv_sec_lo, tv_nsec triples, each component being an unsigned
+ 32-bit value. Whole seconds are in tv_sec which is a 64-bit
+ value combined from tv_sec_hi and tv_sec_lo, and the
+ additional fractional part in tv_nsec as nanoseconds. Hence,
+ for valid timestamps tv_nsec must be in [0, 999999999].
+
+ Note that clock_id applies only to the presentation clock,
+ and implies nothing about e.g. the timestamps used in the
+ Wayland core protocol input events.
+ </description>
+
+ <arg name="clk_id" type="uint" summary="platform clock identifier"/>
+ </event>
+
+ </interface>
+
+ <interface name="presentation_feedback" version="1">
+ <description summary="presentation time feedback event">
+ A presentation_feedback object returns an indication that a
+ wl_surface content update has become visible to the user.
+ One object corresponds to one content update submission
+ (wl_surface.commit). There are two possible outcomes: the
+ content update is presented to the user, and a presentation
+ timestamp delivered; or, the user did not see the content
+ update because it was superseded or its surface destroyed,
+ and the content update is discarded.
+
+ Once a presentation_feedback object has delivered an 'presented'
+ or 'discarded' event it is automatically destroyed.
+ </description>
+
+ <event name="sync_output">
+ <description summary="presentation synchronized to this output">
+ As presentation can be synchronized to only one output at a
+ time, this event tells which output it was. This event is only
+ sent prior to the presented event.
+
+ As clients may bind to the same global wl_output multiple
+ times, this event is sent for each bound instance that matches
+ the synchronized output. If a client has not bound to the
+ right wl_output global at all, this event is not sent.
+ </description>
+
+ <arg name="output" type="object" interface="wl_output"
+ summary="presentation output"/>
+ </event>
+
+ <enum name="kind">
+ <description summary="bitmask of flags in presented event">
+ These flags provide information about how the presentation of
+ the related content update was done. The intent is to help
+ clients assess the reliability of the feedback and the visual
+ quality with respect to possible tearing and timings. The
+ flags are:
+
+ VSYNC:
+ The presentation was synchronized to the "vertical retrace" by
+ the display hardware such that tearing does not happen.
+ Relying on user space scheduling is not acceptable for this
+ flag. If presentation is done by a copy to the active
+ frontbuffer, then it must guarantee that tearing cannot
+ happen.
+
+ HW_CLOCK:
+ The display hardware provided measurements that the hardware
+ driver converted into a presentation timestamp. Sampling a
+ clock in user space is not acceptable for this flag.
+
+ HW_COMPLETION:
+ The display hardware signalled that it started using the new
+ image content. The opposite of this is e.g. a timer being used
+ to guess when the display hardware has switched to the new
+ image content.
+
+ ZERO_COPY:
+ The presentation of this update was done zero-copy. This means
+ the buffer from the client was given to display hardware as
+ is, without copying it. Compositing with OpenGL counts as
+ copying, even if textured directly from the client buffer.
+ Possible zero-copy cases include direct scanout of a
+ fullscreen surface and a surface on a hardware overlay.
+ </description>
+
+ <entry name="vsync" value="0x1" summary="presentation was vsync'd"/>
+ <entry name="hw_clock" value="0x2"
+ summary="hardware provided the presentation timestamp"/>
+ <entry name="hw_completion" value="0x4"
+ summary="hardware signalled the start of the presentation"/>
+ <entry name="zero_copy" value="0x8"
+ summary="presentation was done zero-copy"/>
+ </enum>
+
+ <event name="presented">
+ <description summary="the content update was displayed">
+ The associated content update was displayed to the user at the
+ indicated time (tv_sec_hi/lo, tv_nsec). For the interpretation of
+ the timestamp, see presentation.clock_id event.
+
+ The timestamp corresponds to the time when the content update
+ turned into light the first time on the surface's main output.
+ Compositors may approximate this from the framebuffer flip
+ completion events from the system, and the latency of the
+ physical display path if known.
+
+ This event is preceded by all related sync_output events
+ telling which output's refresh cycle the feedback corresponds
+ to, i.e. the main output for the surface. Compositors are
+ recommended to choose the output containing the largest part
+ of the wl_surface, or keeping the output they previously
+ chose. Having a stable presentation output association helps
+ clients predict future output refreshes (vblank).
+
+ Argument 'refresh' gives the compositor's prediction of how
+ many nanoseconds after tv_sec, tv_nsec the very next output
+ refresh may occur. This is to further aid clients in
+ predicting future refreshes, i.e., estimating the timestamps
+ targeting the next few vblanks. If such prediction cannot
+ usefully be done, the argument is zero.
+
+ The 64-bit value combined from seq_hi and seq_lo is the value
+ of the output's vertical retrace counter when the content
+ update was first scanned out to the display. This value must
+ be compatible with the definition of MSC in
+ GLX_OML_sync_control specification. Note, that if the display
+ path has a non-zero latency, the time instant specified by
+ this counter may differ from the timestamp's.
+
+ If the output does not have a constant refresh rate, explicit
+ video mode switches excluded, then the refresh argument must
+ be zero.
+
+ If the output does not have a concept of vertical retrace or a
+ refresh cycle, or the output device is self-refreshing without
+ a way to query the refresh count, then the arguments seq_hi
+ and seq_lo must be zero.
+ </description>
+
+ <arg name="tv_sec_hi" type="uint"
+ summary="high 32 bits of the seconds part of the presentation timestamp"/>
+ <arg name="tv_sec_lo" type="uint"
+ summary="low 32 bits of the seconds part of the presentation timestamp"/>
+ <arg name="tv_nsec" type="uint"
+ summary="nanoseconds part of the presentation timestamp"/>
+ <arg name="refresh" type="uint" summary="nanoseconds till next refresh"/>
+ <arg name="seq_hi" type="uint"
+ summary="high 32 bits of refresh counter"/>
+ <arg name="seq_lo" type="uint"
+ summary="low 32 bits of refresh counter"/>
+ <arg name="flags" type="uint" summary="combination of 'kind' values"/>
+ </event>
+
+ <event name="discarded">
+ <description summary="the content update was not displayed">
+ The content update was never displayed to the user.
+ </description>
+ </event>
+ </interface>
+
+</protocol>
--
2.4.10
More information about the wayland-devel
mailing list