diff options
author | Pekka Paalanen <pekka.paalanen@collabora.co.uk> | 2016-02-18 16:53:27 +0200 |
---|---|---|
committer | Pekka Paalanen <pekka.paalanen@collabora.co.uk> | 2016-03-07 13:29:27 +0200 |
commit | b00c79b587a4903df576008a64a49f851fed234c (patch) | |
tree | a88bf6fd903de24ed4e4cfb23f8464f6c4e176be /protocol | |
parent | 16d1fa156abd296a69afed0df8588b7d33d6cb0d (diff) | |
download | weston-b00c79b587a4903df576008a64a49f851fed234c.tar.gz |
protocol: migrate to stable presentation-time.xml
Remove the unstable presentation_timing.xml file, and use
presentation-time.xml from wayland-protocols instead to generate all the
Presentation extension bindings.
The following renames are done according to the XML changes:
- generated header includes
- enum constants and macros prefixed with WP_
- interface symbol names prefixed with wp_
- protocol API calls prefixed with wp_
Clients use wp_presentation_interface.name rather than hardcoding the
global interface name: presentation-shm, weston-info, presentation-test.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
Reviewed-by: Bryce Harrington <bryce@osg.samsung.com>
Reviewed-by: Jonas Ådahl <jadahl@gmail.com>
[Pekka: updated wayland-protocols dependency to 1.2]
Diffstat (limited to 'protocol')
-rw-r--r-- | protocol/presentation_timing.xml | 274 |
1 files changed, 0 insertions, 274 deletions
diff --git a/protocol/presentation_timing.xml b/protocol/presentation_timing.xml deleted file mode 100644 index 10a5f14c..00000000 --- a/protocol/presentation_timing.xml +++ /dev/null @@ -1,274 +0,0 @@ -<?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> |