1 /* Generated by wayland-scanner 1.22.0 */
2
3 #ifndef PRESENTATION_TIME_CLIENT_PROTOCOL_H
4 #define PRESENTATION_TIME_CLIENT_PROTOCOL_H
5
6 #include <stdint.h>
7 #include <stddef.h>
8 #include "wayland-client.h"
9
10 #ifdef __cplusplus
11 extern "C" {
12 #endif
13
14 /**
15 * @page page_presentation_time The presentation_time protocol
16 * @section page_ifaces_presentation_time Interfaces
17 * - @subpage page_iface_wp_presentation - timed presentation related wl_surface requests
18 * - @subpage page_iface_wp_presentation_feedback - presentation time feedback event
19 * @section page_copyright_presentation_time Copyright
20 * <pre>
21 *
22 * Copyright © 2013-2014 Collabora, Ltd.
23 *
24 * Permission is hereby granted, free of charge, to any person obtaining a
25 * copy of this software and associated documentation files (the "Software"),
26 * to deal in the Software without restriction, including without limitation
27 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
28 * and/or sell copies of the Software, and to permit persons to whom the
29 * Software is furnished to do so, subject to the following conditions:
30 *
31 * The above copyright notice and this permission notice (including the next
32 * paragraph) shall be included in all copies or substantial portions of the
33 * Software.
34 *
35 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
36 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
37 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
38 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
39 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
40 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
41 * DEALINGS IN THE SOFTWARE.
42 * </pre>
43 */
44 struct wl_output;
45 struct wl_surface;
46 struct wp_presentation;
47 struct wp_presentation_feedback;
48
49 #ifndef WP_PRESENTATION_INTERFACE
50 #define WP_PRESENTATION_INTERFACE
51 /**
52 * @page page_iface_wp_presentation wp_presentation
53 * @section page_iface_wp_presentation_desc Description
54 *
55 *
56 *
57 *
58 * The main feature of this interface is accurate presentation
59 * timing feedback to ensure smooth video playback while maintaining
60 * audio/video synchronization. Some features use the concept of a
61 * presentation clock, which is defined in the
62 * presentation.clock_id event.
63 *
64 * A content update for a wl_surface is submitted by a
65 * wl_surface.commit request. Request 'feedback' associates with
66 * the wl_surface.commit and provides feedback on the content
67 * update, particularly the final realized presentation time.
68 *
69 *
70 *
71 * When the final realized presentation time is available, e.g.
72 * after a framebuffer flip completes, the requested
73 * presentation_feedback.presented events are sent. The final
74 * presentation time can differ from the compositor's predicted
75 * display update time and the update's target time, especially
76 * when the compositor misses its target vertical blanking period.
77 * @section page_iface_wp_presentation_api API
78 * See @ref iface_wp_presentation.
79 */
80 /**
81 * @defgroup iface_wp_presentation The wp_presentation interface
82 *
83 *
84 *
85 *
86 * The main feature of this interface is accurate presentation
87 * timing feedback to ensure smooth video playback while maintaining
88 * audio/video synchronization. Some features use the concept of a
89 * presentation clock, which is defined in the
90 * presentation.clock_id event.
91 *
92 * A content update for a wl_surface is submitted by a
93 * wl_surface.commit request. Request 'feedback' associates with
94 * the wl_surface.commit and provides feedback on the content
95 * update, particularly the final realized presentation time.
96 *
97 *
98 *
99 * When the final realized presentation time is available, e.g.
100 * after a framebuffer flip completes, the requested
101 * presentation_feedback.presented events are sent. The final
102 * presentation time can differ from the compositor's predicted
103 * display update time and the update's target time, especially
104 * when the compositor misses its target vertical blanking period.
105 */
106 extern const struct wl_interface wp_presentation_interface;
107 #endif
108 #ifndef WP_PRESENTATION_FEEDBACK_INTERFACE
109 #define WP_PRESENTATION_FEEDBACK_INTERFACE
110 /**
111 * @page page_iface_wp_presentation_feedback wp_presentation_feedback
112 * @section page_iface_wp_presentation_feedback_desc Description
113 *
114 * A presentation_feedback object returns an indication that a
115 * wl_surface content update has become visible to the user.
116 * One object corresponds to one content update submission
117 * (wl_surface.commit). There are two possible outcomes: the
118 * content update is presented to the user, and a presentation
119 * timestamp delivered; or, the user did not see the content
120 * update because it was superseded or its surface destroyed,
121 * and the content update is discarded.
122 *
123 * Once a presentation_feedback object has delivered a 'presented'
124 * or 'discarded' event it is automatically destroyed.
125 * @section page_iface_wp_presentation_feedback_api API
126 * See @ref iface_wp_presentation_feedback.
127 */
128 /**
129 * @defgroup iface_wp_presentation_feedback The wp_presentation_feedback interface
130 *
131 * A presentation_feedback object returns an indication that a
132 * wl_surface content update has become visible to the user.
133 * One object corresponds to one content update submission
134 * (wl_surface.commit). There are two possible outcomes: the
135 * content update is presented to the user, and a presentation
136 * timestamp delivered; or, the user did not see the content
137 * update because it was superseded or its surface destroyed,
138 * and the content update is discarded.
139 *
140 * Once a presentation_feedback object has delivered a 'presented'
141 * or 'discarded' event it is automatically destroyed.
142 */
143 extern const struct wl_interface wp_presentation_feedback_interface;
144 #endif
145
146 #ifndef WP_PRESENTATION_ERROR_ENUM
147 #define WP_PRESENTATION_ERROR_ENUM
148 /**
149 * @ingroup iface_wp_presentation
150 * fatal presentation errors
151 *
152 * These fatal protocol errors may be emitted in response to
153 * illegal presentation requests.
154 */
155 enum wp_presentation_error {
156 /**
157 * invalid value in tv_nsec
158 */
159 WP_PRESENTATION_ERROR_INVALID_TIMESTAMP = 0,
160 /**
161 * invalid flag
162 */
163 WP_PRESENTATION_ERROR_INVALID_FLAG = 1,
164 };
165 #endif /* WP_PRESENTATION_ERROR_ENUM */
166
167 /**
168 * @ingroup iface_wp_presentation
169 * @struct wp_presentation_listener
170 */
171 struct wp_presentation_listener {
172 /**
173 * clock ID for timestamps
174 *
175 * This event tells the client in which clock domain the
176 * compositor interprets the timestamps used by the presentation
177 * extension. This clock is called the presentation clock.
178 *
179 * The compositor sends this event when the client binds to the
180 * presentation interface. The presentation clock does not change
181 * during the lifetime of the client connection.
182 *
183 * The clock identifier is platform dependent. On Linux/glibc, the
184 * identifier value is one of the clockid_t values accepted by
185 * clock_gettime(). clock_gettime() is defined by POSIX.1-2001.
186 *
187 * Timestamps in this clock domain are expressed as tv_sec_hi,
188 * tv_sec_lo, tv_nsec triples, each component being an unsigned
189 * 32-bit value. Whole seconds are in tv_sec which is a 64-bit
190 * value combined from tv_sec_hi and tv_sec_lo, and the additional
191 * fractional part in tv_nsec as nanoseconds. Hence, for valid
192 * timestamps tv_nsec must be in [0, 999999999].
193 *
194 * Note that clock_id applies only to the presentation clock, and
195 * implies nothing about e.g. the timestamps used in the Wayland
196 * core protocol input events.
197 *
198 * Compositors should prefer a clock which does not jump and is not
199 * slewed e.g. by NTP. The absolute value of the clock is
200 * irrelevant. Precision of one millisecond or better is
201 * recommended. Clients must be able to query the current clock
202 * value directly, not by asking the compositor.
203 * @param clk_id platform clock identifier
204 */
205 void (*clock_id)(void *data,
206 struct wp_presentation *wp_presentation,
207 uint32_t clk_id);
208 };
209
210 /**
211 * @ingroup iface_wp_presentation
212 */
213 static inline int
wp_presentation_add_listener(struct wp_presentation * wp_presentation,const struct wp_presentation_listener * listener,void * data)214 wp_presentation_add_listener(struct wp_presentation *wp_presentation,
215 const struct wp_presentation_listener *listener, void *data)
216 {
217 return wl_proxy_add_listener((struct wl_proxy *) wp_presentation,
218 (void (**)(void)) listener, data);
219 }
220
221 #define WP_PRESENTATION_DESTROY 0
222 #define WP_PRESENTATION_FEEDBACK 1
223
224 /**
225 * @ingroup iface_wp_presentation
226 */
227 #define WP_PRESENTATION_CLOCK_ID_SINCE_VERSION 1
228
229 /**
230 * @ingroup iface_wp_presentation
231 */
232 #define WP_PRESENTATION_DESTROY_SINCE_VERSION 1
233 /**
234 * @ingroup iface_wp_presentation
235 */
236 #define WP_PRESENTATION_FEEDBACK_SINCE_VERSION 1
237
238 /** @ingroup iface_wp_presentation */
239 static inline void
wp_presentation_set_user_data(struct wp_presentation * wp_presentation,void * user_data)240 wp_presentation_set_user_data(struct wp_presentation *wp_presentation, void *user_data)
241 {
242 wl_proxy_set_user_data((struct wl_proxy *) wp_presentation, user_data);
243 }
244
245 /** @ingroup iface_wp_presentation */
246 static inline void *
wp_presentation_get_user_data(struct wp_presentation * wp_presentation)247 wp_presentation_get_user_data(struct wp_presentation *wp_presentation)
248 {
249 return wl_proxy_get_user_data((struct wl_proxy *) wp_presentation);
250 }
251
252 static inline uint32_t
wp_presentation_get_version(struct wp_presentation * wp_presentation)253 wp_presentation_get_version(struct wp_presentation *wp_presentation)
254 {
255 return wl_proxy_get_version((struct wl_proxy *) wp_presentation);
256 }
257
258 /**
259 * @ingroup iface_wp_presentation
260 *
261 * Informs the server that the client will no longer be using
262 * this protocol object. Existing objects created by this object
263 * are not affected.
264 */
265 static inline void
wp_presentation_destroy(struct wp_presentation * wp_presentation)266 wp_presentation_destroy(struct wp_presentation *wp_presentation)
267 {
268 wl_proxy_marshal_flags((struct wl_proxy *) wp_presentation,
269 WP_PRESENTATION_DESTROY, NULL, wl_proxy_get_version((struct wl_proxy *) wp_presentation), WL_MARSHAL_FLAG_DESTROY);
270 }
271
272 /**
273 * @ingroup iface_wp_presentation
274 *
275 * Request presentation feedback for the current content submission
276 * on the given surface. This creates a new presentation_feedback
277 * object, which will deliver the feedback information once. If
278 * multiple presentation_feedback objects are created for the same
279 * submission, they will all deliver the same information.
280 *
281 * For details on what information is returned, see the
282 * presentation_feedback interface.
283 */
284 static inline struct wp_presentation_feedback *
wp_presentation_feedback(struct wp_presentation * wp_presentation,struct wl_surface * surface)285 wp_presentation_feedback(struct wp_presentation *wp_presentation, struct wl_surface *surface)
286 {
287 struct wl_proxy *callback;
288
289 callback = wl_proxy_marshal_flags((struct wl_proxy *) wp_presentation,
290 WP_PRESENTATION_FEEDBACK, &wp_presentation_feedback_interface, wl_proxy_get_version((struct wl_proxy *) wp_presentation), 0, surface, NULL);
291
292 return (struct wp_presentation_feedback *) callback;
293 }
294
295 #ifndef WP_PRESENTATION_FEEDBACK_KIND_ENUM
296 #define WP_PRESENTATION_FEEDBACK_KIND_ENUM
297 /**
298 * @ingroup iface_wp_presentation_feedback
299 * bitmask of flags in presented event
300 *
301 * These flags provide information about how the presentation of
302 * the related content update was done. The intent is to help
303 * clients assess the reliability of the feedback and the visual
304 * quality with respect to possible tearing and timings.
305 */
306 enum wp_presentation_feedback_kind {
307 /**
308 * presentation was vsync'd
309 *
310 * The presentation was synchronized to the "vertical retrace" by
311 * the display hardware such that tearing does not happen. Relying
312 * on user space scheduling is not acceptable for this flag. If
313 * presentation is done by a copy to the active frontbuffer, then
314 * it must guarantee that tearing cannot happen.
315 */
316 WP_PRESENTATION_FEEDBACK_KIND_VSYNC = 0x1,
317 /**
318 * hardware provided the presentation timestamp
319 *
320 * The display hardware provided measurements that the hardware
321 * driver converted into a presentation timestamp. Sampling a clock
322 * in user space is not acceptable for this flag.
323 */
324 WP_PRESENTATION_FEEDBACK_KIND_HW_CLOCK = 0x2,
325 /**
326 * hardware signalled the start of the presentation
327 *
328 * The display hardware signalled that it started using the new
329 * image content. The opposite of this is e.g. a timer being used
330 * to guess when the display hardware has switched to the new image
331 * content.
332 */
333 WP_PRESENTATION_FEEDBACK_KIND_HW_COMPLETION = 0x4,
334 /**
335 * presentation was done zero-copy
336 *
337 * The presentation of this update was done zero-copy. This means
338 * the buffer from the client was given to display hardware as is,
339 * without copying it. Compositing with OpenGL counts as copying,
340 * even if textured directly from the client buffer. Possible
341 * zero-copy cases include direct scanout of a fullscreen surface
342 * and a surface on a hardware overlay.
343 */
344 WP_PRESENTATION_FEEDBACK_KIND_ZERO_COPY = 0x8,
345 };
346 #endif /* WP_PRESENTATION_FEEDBACK_KIND_ENUM */
347
348 /**
349 * @ingroup iface_wp_presentation_feedback
350 * @struct wp_presentation_feedback_listener
351 */
352 struct wp_presentation_feedback_listener {
353 /**
354 * presentation synchronized to this output
355 *
356 * As presentation can be synchronized to only one output at a
357 * time, this event tells which output it was. This event is only
358 * sent prior to the presented event.
359 *
360 * As clients may bind to the same global wl_output multiple times,
361 * this event is sent for each bound instance that matches the
362 * synchronized output. If a client has not bound to the right
363 * wl_output global at all, this event is not sent.
364 * @param output presentation output
365 */
366 void (*sync_output)(void *data,
367 struct wp_presentation_feedback *wp_presentation_feedback,
368 struct wl_output *output);
369 /**
370 * the content update was displayed
371 *
372 * The associated content update was displayed to the user at the
373 * indicated time (tv_sec_hi/lo, tv_nsec). For the interpretation
374 * of the timestamp, see presentation.clock_id event.
375 *
376 * The timestamp corresponds to the time when the content update
377 * turned into light the first time on the surface's main output.
378 * Compositors may approximate this from the framebuffer flip
379 * completion events from the system, and the latency of the
380 * physical display path if known.
381 *
382 * This event is preceded by all related sync_output events telling
383 * which output's refresh cycle the feedback corresponds to, i.e.
384 * the main output for the surface. Compositors are recommended to
385 * choose the output containing the largest part of the wl_surface,
386 * or keeping the output they previously chose. Having a stable
387 * presentation output association helps clients predict future
388 * output refreshes (vblank).
389 *
390 * The 'refresh' argument gives the compositor's prediction of how
391 * many nanoseconds after tv_sec, tv_nsec the very next output
392 * refresh may occur. This is to further aid clients in predicting
393 * future refreshes, i.e., estimating the timestamps targeting the
394 * next few vblanks. If such prediction cannot usefully be done,
395 * the argument is zero.
396 *
397 * If the output does not have a constant refresh rate, explicit
398 * video mode switches excluded, then the refresh argument must be
399 * zero.
400 *
401 * The 64-bit value combined from seq_hi and seq_lo is the value of
402 * the output's vertical retrace counter when the content update
403 * was first scanned out to the display. This value must be
404 * compatible with the definition of MSC in GLX_OML_sync_control
405 * specification. Note, that if the display path has a non-zero
406 * latency, the time instant specified by this counter may differ
407 * from the timestamp's.
408 *
409 * If the output does not have a concept of vertical retrace or a
410 * refresh cycle, or the output device is self-refreshing without a
411 * way to query the refresh count, then the arguments seq_hi and
412 * seq_lo must be zero.
413 * @param tv_sec_hi high 32 bits of the seconds part of the presentation timestamp
414 * @param tv_sec_lo low 32 bits of the seconds part of the presentation timestamp
415 * @param tv_nsec nanoseconds part of the presentation timestamp
416 * @param refresh nanoseconds till next refresh
417 * @param seq_hi high 32 bits of refresh counter
418 * @param seq_lo low 32 bits of refresh counter
419 * @param flags combination of 'kind' values
420 */
421 void (*presented)(void *data,
422 struct wp_presentation_feedback *wp_presentation_feedback,
423 uint32_t tv_sec_hi,
424 uint32_t tv_sec_lo,
425 uint32_t tv_nsec,
426 uint32_t refresh,
427 uint32_t seq_hi,
428 uint32_t seq_lo,
429 uint32_t flags);
430 /**
431 * the content update was not displayed
432 *
433 * The content update was never displayed to the user.
434 */
435 void (*discarded)(void *data,
436 struct wp_presentation_feedback *wp_presentation_feedback);
437 };
438
439 /**
440 * @ingroup iface_wp_presentation_feedback
441 */
442 static inline int
wp_presentation_feedback_add_listener(struct wp_presentation_feedback * wp_presentation_feedback,const struct wp_presentation_feedback_listener * listener,void * data)443 wp_presentation_feedback_add_listener(struct wp_presentation_feedback *wp_presentation_feedback,
444 const struct wp_presentation_feedback_listener *listener, void *data)
445 {
446 return wl_proxy_add_listener((struct wl_proxy *) wp_presentation_feedback,
447 (void (**)(void)) listener, data);
448 }
449
450 /**
451 * @ingroup iface_wp_presentation_feedback
452 */
453 #define WP_PRESENTATION_FEEDBACK_SYNC_OUTPUT_SINCE_VERSION 1
454 /**
455 * @ingroup iface_wp_presentation_feedback
456 */
457 #define WP_PRESENTATION_FEEDBACK_PRESENTED_SINCE_VERSION 1
458 /**
459 * @ingroup iface_wp_presentation_feedback
460 */
461 #define WP_PRESENTATION_FEEDBACK_DISCARDED_SINCE_VERSION 1
462
463
464 /** @ingroup iface_wp_presentation_feedback */
465 static inline void
wp_presentation_feedback_set_user_data(struct wp_presentation_feedback * wp_presentation_feedback,void * user_data)466 wp_presentation_feedback_set_user_data(struct wp_presentation_feedback *wp_presentation_feedback, void *user_data)
467 {
468 wl_proxy_set_user_data((struct wl_proxy *) wp_presentation_feedback, user_data);
469 }
470
471 /** @ingroup iface_wp_presentation_feedback */
472 static inline void *
wp_presentation_feedback_get_user_data(struct wp_presentation_feedback * wp_presentation_feedback)473 wp_presentation_feedback_get_user_data(struct wp_presentation_feedback *wp_presentation_feedback)
474 {
475 return wl_proxy_get_user_data((struct wl_proxy *) wp_presentation_feedback);
476 }
477
478 static inline uint32_t
wp_presentation_feedback_get_version(struct wp_presentation_feedback * wp_presentation_feedback)479 wp_presentation_feedback_get_version(struct wp_presentation_feedback *wp_presentation_feedback)
480 {
481 return wl_proxy_get_version((struct wl_proxy *) wp_presentation_feedback);
482 }
483
484 /** @ingroup iface_wp_presentation_feedback */
485 static inline void
wp_presentation_feedback_destroy(struct wp_presentation_feedback * wp_presentation_feedback)486 wp_presentation_feedback_destroy(struct wp_presentation_feedback *wp_presentation_feedback)
487 {
488 wl_proxy_destroy((struct wl_proxy *) wp_presentation_feedback);
489 }
490
491 #ifdef __cplusplus
492 }
493 #endif
494
495 #endif
496