support the commit-per-vblank
[platform/core/uifw/libtdm.git] / include / tdm.h
1 /**************************************************************************
2  *
3  * libtdm
4  *
5  * Copyright 2015 Samsung Electronics co., Ltd. All Rights Reserved.
6  *
7  * Contact: Eunchul Kim <chulspro.kim@samsung.com>,
8  *          JinYoung Jeon <jy0.jeon@samsung.com>,
9  *          Taeheon Kim <th908.kim@samsung.com>,
10  *          YoungJun Cho <yj44.cho@samsung.com>,
11  *          SooChan Lim <sc1.lim@samsung.com>,
12  *          Boram Park <sc1.lim@samsung.com>
13  *
14  * Permission is hereby granted, free of charge, to any person obtaining a
15  * copy of this software and associated documentation files (the
16  * "Software"), to deal in the Software without restriction, including
17  * without limitation the rights to use, copy, modify, merge, publish,
18  * distribute, sub license, and/or sell copies of the Software, and to
19  * permit persons to whom the Software is furnished to do so, subject to
20  * the following conditions:
21  *
22  * The above copyright notice and this permission notice (including the
23  * next paragraph) shall be included in all copies or substantial portions
24  * of the Software.
25  *
26  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
27  * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
28  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.
29  * IN NO EVENT SHALL PRECISION INSIGHT AND/OR ITS SUPPLIERS BE LIABLE FOR
30  * ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
31  * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
32  * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
33  *
34 **************************************************************************/
35
36 #ifndef _TDM_H_
37 #define _TDM_H_
38
39 #include <stdint.h>
40 #include <tbm_surface.h>
41 #include <tbm_surface_queue.h>
42 #include <tbm_surface_internal.h>
43
44 #include "tdm_types.h"
45
46 #ifdef __cplusplus
47 extern "C" {
48 #endif
49
50 /**
51  * @file tdm.h
52  * @brief The header file for a frontend user.
53  * @par Example
54  * @code
55  * #include <tdm.h>    //for a frontend user
56  * @endcode
57  */
58
59 /**
60  * @brief The display capability enumeration
61  */
62 typedef enum {
63         TDM_DISPLAY_CAPABILITY_PP       = (1 << 0), /**< if hardware supports pp operation */
64         TDM_DISPLAY_CAPABILITY_CAPTURE  = (1 << 1), /**< if hardware supports capture operation */
65 } tdm_display_capability;
66
67 /**
68  * @brief The output change handler
69  * @details This handler will be called when the status of a output object is
70  * changed in runtime.
71  */
72 typedef void (*tdm_output_change_handler)(tdm_output *output,
73                                                                                   tdm_output_change_type type,
74                                                                                   tdm_value value,
75                                                                                   void *user_data);
76
77 /**
78  * @brief Initialize a display object
79  * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
80  * @return A display object
81  * @see tdm_display_deinit
82  */
83 tdm_display *
84 tdm_display_init(tdm_error *error);
85
86 /**
87  * @brief Deinitialize a display object
88  * @param[in] dpy A display object
89  * @see tdm_display_init
90  */
91 void
92 tdm_display_deinit(tdm_display *dpy);
93
94 /**
95  * @brief Update a display object
96  * @details
97  * When new output is connected, a frontend user need to call this function.
98  * And a frontend user can the new output information with tdm_output_get_xxx functions.
99  * @param[in] dpy A display object
100  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
101  */
102 tdm_error
103 tdm_display_update(tdm_display *dpy);
104
105 /**
106  * @brief Get the file descriptor
107  * @details TDM handles the events of fd with #tdm_display_handle_events.
108  * @param[in] dpy A display object
109  * @param[out] fd The file descriptor
110  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
111  * @see tdm_display_handle_events
112  */
113 tdm_error
114 tdm_display_get_fd(tdm_display *dpy, int *fd);
115
116 /**
117  * @brief Handle the events
118  * @param[in] dpy A display object
119  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
120  * @see tdm_display_get_fd
121  */
122 tdm_error
123 tdm_display_handle_events(tdm_display *dpy);
124
125 /**
126  * @brief Get the information of the TDM backend module.
127  * @param[in] dpy A display object
128  * @param[out] name The name of the TDM backend module
129  * @param[out] vendor The vendor of the TDM backend module
130  * @param[out] version The version of the TDM backend module
131  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
132  */
133 tdm_error
134 tdm_display_get_backend_info(tdm_display *dpy, const char **name,
135                                                          const char **vendor, int *major, int *minor);
136
137 /**
138  * @brief Get the capabilities of a display object.
139  * @details A frontend user can get whether TDM supports pp/capture functionality with this function.
140  * @param[in] dpy A display object
141  * @param[out] capabilities The capabilities of a display object
142  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
143  */
144 tdm_error
145 tdm_display_get_capabilities(tdm_display *dpy,
146                                                          tdm_display_capability *capabilities);
147
148 /**
149  * @brief Get the pp capabilities of a display object.
150  * @param[in] dpy A display object
151  * @param[out] capabilities The pp capabilities
152  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
153  */
154 tdm_error
155 tdm_display_get_pp_capabilities(tdm_display *dpy,
156                                                                 tdm_pp_capability *capabilities);
157
158 /**
159  * @brief Get the pp available format array of a display object.
160  * @param[in] dpy A display object
161  * @param[out] formats The pp available format array
162  * @param[out] count The count of formats
163  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
164  */
165 tdm_error
166 tdm_display_get_pp_available_formats(tdm_display *dpy,
167                                                                          const tbm_format **formats, int *count);
168
169 /**
170  * @brief Get the pp available size of a display object.
171  * @details -1 means that a TDM backend module doesn't define the value.
172  * @param[in] dpy A display object
173  * @param[out] min_w The minimum width which TDM can handle
174  * @param[out] min_h The minimum height which TDM can handle
175  * @param[out] max_w The maximum width which TDM can handle
176  * @param[out] max_h The maximum height which TDM can handle
177  * @param[out] preferred_align The preferred align width which TDM can handle
178  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
179  */
180 tdm_error
181 tdm_display_get_pp_available_size(tdm_display *dpy, int *min_w, int *min_h,
182                                                                   int *max_w, int *max_h, int *preferred_align);
183
184 /**
185  * @brief Get the capture capabilities of a display object.
186  * @param[in] dpy A display object
187  * @param[out] capabilities The capture capabilities
188  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
189  */
190 tdm_error
191 tdm_display_get_capture_capabilities(tdm_display *dpy,
192                                                                          tdm_capture_capability *capabilities);
193
194 /**
195  * @brief Get the capture available format array of a display object.
196  * @param[in] dpy A display object
197  * @param[out] formats The capture available format array
198  * @param[out] count The count of formats
199  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
200  */
201 tdm_error
202 tdm_display_get_catpure_available_formats(tdm_display *dpy,
203                                                                                   const tbm_format **formats, int *count);
204
205 /**
206  * @brief Get the capture available size of a display object.
207  * @details -1 means that a TDM backend module doesn't define the value.
208  * @param[in] dpy A display object
209  * @param[out] min_w The minimum width which TDM can handle
210  * @param[out] min_h The minimum height which TDM can handle
211  * @param[out] max_w The maximum width which TDM can handle
212  * @param[out] max_h The maximum height which TDM can handle
213  * @param[out] preferred_align The preferred align width which TDM can handle
214  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
215  */
216 tdm_error
217 tdm_display_get_capture_available_size(tdm_display *dpy, int *min_w, int *min_h,
218                                                                            int *max_w, int *max_h, int *preferred_align);
219
220 /**
221  * @brief Get the max layer counts which a display object can show on screen.
222  * @details -1 means that a TDM backend module doesn't define the value.
223  * @param[in] dpy A display object
224  * @param[out] count The max count of layers
225  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
226  */
227 tdm_error
228 tdm_display_get_max_layer_count(tdm_display *dpy, int *max_count);
229
230 /**
231  * @brief Get the output counts which a display object has.
232  * @param[in] dpy A display object
233  * @param[out] count The count of outputs
234  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
235  * @see tdm_display_get_output
236  */
237 tdm_error
238 tdm_display_get_output_count(tdm_display *dpy, int *count);
239
240 /**
241  * @brief Get a output object which has the given index.
242  * @param[in] dpy A display object
243  * @param[in] index The index of a output object
244  * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
245  * @return A output object if success. Otherwise, NULL.
246  * @see tdm_display_get_output_count
247  */
248 tdm_output *
249 tdm_display_get_output(tdm_display *dpy, int index, tdm_error *error);
250
251 /**
252  * @brief Create a pp object.
253  * @param[in] dpy A display object
254  * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
255  * @return A pp object if success. Otherwise, NULL.
256  * @see tdm_pp_destroy
257  */
258 tdm_pp *
259 tdm_display_create_pp(tdm_display *dpy, tdm_error *error);
260
261 /**
262  * @brief Get the capabilities of a output object.
263  * @param[in] output A output object
264  * @param[out] capabilities The capabilities of a output object
265  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
266  */
267 tdm_error
268 tdm_output_get_capabilities(tdm_output *output,
269                                                         tdm_output_capability *capabilities);
270
271 /**
272  * @brief Get the model information of a output object.
273  * @param[in] output A output object
274  * @param[out] maker The output maker.
275  * @param[out] model The output model.
276  * @param[out] name The output name.
277  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
278  */
279 tdm_error
280 tdm_output_get_model_info(tdm_output *output, const char **maker,
281                                                   const char **model, const char **name);
282
283 /**
284  * @brief Get the connection status of a output object.
285  * @param[in] output A output object
286  * @param[out] status The connection status.
287  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
288  */
289 tdm_error
290 tdm_output_get_conn_status(tdm_output *output, tdm_output_conn_status *status);
291
292 /**
293  * @brief Add a output change handler
294  * @details The handler will be called when the status of a
295  * output object is changed. connection, DPMS, etc.
296  * @param[in] output A output object
297  * @param[in] func A output change handler
298  * @param[in] user_data The user data
299  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
300  */
301 tdm_error
302 tdm_output_add_change_handler(tdm_output *output,
303                                                           tdm_output_change_handler func,
304                                                           void *user_data);
305
306 /**
307  * @brief Remove a output change handler
308  * @param[in] output A output object
309  * @param[in] func A output change handler
310  * @param[in] user_data The user data
311  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
312  */
313 void
314 tdm_output_remove_change_handler(tdm_output *output,
315                                                                  tdm_output_change_handler func,
316                                                                  void *user_data);
317
318 /**
319  * @brief Get the connection type of a output object.
320  * @param[in] output A output object
321  * @param[out] type The connection type.
322  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
323  */
324 tdm_error
325 tdm_output_get_output_type(tdm_output *output, tdm_output_type *type);
326
327 /**
328  * @brief Get the layer counts which a output object has.
329  * @param[in] output A output object
330  * @param[out] count The count of layers
331  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
332  * @see tdm_output_get_layer
333  */
334 tdm_error
335 tdm_output_get_layer_count(tdm_output *output, int *count);
336
337 /**
338  * @brief Get a layer object which has the given index.
339  * @param[in] output A output object
340  * @param[in] index The index of a layer object
341  * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
342  * @return A layer object if success. Otherwise, NULL.
343  * @see tdm_output_get_layer_count
344  */
345 tdm_layer *
346 tdm_output_get_layer(tdm_output *output, int index, tdm_error *error);
347
348 /**
349  * @brief Get the available property array of a output object.
350  * @param[in] output A output object
351  * @param[out] props The available property array
352  * @param[out] count The count of properties
353  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
354  */
355 tdm_error
356 tdm_output_get_available_properties(tdm_output *output, const tdm_prop **props,
357                                                                         int *count);
358
359 /**
360  * @brief Get the available mode array of a output object.
361  * @param[in] output A output object
362  * @param[out] modes The available mode array
363  * @param[out] count The count of modes
364  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
365  */
366 tdm_error
367 tdm_output_get_available_modes(tdm_output *output,
368                                                            const tdm_output_mode **modes, int *count);
369
370 /**
371  * @brief Get the available size of a output object.
372  * @details -1 means that a TDM backend module doesn't define the value.
373  * @param[in] output A output object
374  * @param[out] min_w The minimum width which TDM can handle
375  * @param[out] min_h The minimum height which TDM can handle
376  * @param[out] max_w The maximum width which TDM can handle
377  * @param[out] max_h The maximum height which TDM can handle
378  * @param[out] preferred_align The preferred align width which TDM can handle
379  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
380  */
381 tdm_error
382 tdm_output_get_available_size(tdm_output *output, int *min_w, int *min_h,
383                                                           int *max_w, int *max_h, int *preferred_align);
384
385 /**
386  * @brief Get the available cursor size of a output object.
387  * @details -1 means that a TDM backend module doesn't define the value.
388  * @param[in] output A output object
389  * @param[out] min_w The minimum width which TDM can handle
390  * @param[out] min_h The minimum height which TDM can handle
391  * @param[out] max_w The maximum width which TDM can handle
392  * @param[out] max_h The maximum height which TDM can handle
393  * @param[out] preferred_align The preferred align width which TDM can handle
394  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
395  */
396 tdm_error
397 tdm_output_get_cursor_available_size(tdm_output *output, int *min_w, int *min_h,
398                                                                          int *max_w, int *max_h, int *preferred_align);
399
400 /**
401  * @brief Get the physical size of a output object.
402  * @param[in] output A output object
403  * @param[out] mmWidth The milimeter width
404  * @param[out] mmHeight The milimeter height
405  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
406  */
407 tdm_error
408 tdm_output_get_physical_size(tdm_output *output, unsigned int *mmWidth,
409                                                          unsigned int *mmHeight);
410
411 /**
412  * @brief Get the subpixel of a output object.
413  * @param[in] output A output object
414  * @param[out] subpixel The subpixel
415  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
416  */
417 tdm_error
418 tdm_output_get_subpixel(tdm_output *output, unsigned int *subpixel);
419
420 /**
421  * @brief Get the pipe of a output object.
422  * @param[in] output A output object
423  * @param[out] pipe The pipe
424  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
425  */
426 tdm_error
427 tdm_output_get_pipe(tdm_output *output, unsigned int *pipe);
428
429 /**
430  * @brief Get the index of a primary layer.
431  * @param[in] output A output object
432  * @param[out] index The primary layer index
433  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
434  */
435 tdm_error
436 tdm_output_get_primary_index(tdm_output *output, int *index);
437
438 /**
439  * @brief Set the property which has a given id.
440  * @param[in] output A output object
441  * @param[in] id The property id
442  * @param[in] value The value
443  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
444  */
445 tdm_error
446 tdm_output_set_property(tdm_output *output, unsigned int id, tdm_value value);
447
448 /**
449  * @brief Get the property which has a given id
450  * @param[in] output A output object
451  * @param[in] id The property id
452  * @param[out] value The value
453  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
454  */
455 tdm_error
456 tdm_output_get_property(tdm_output *output, unsigned int id, tdm_value *value);
457
458 /**
459  * @brief Wait for VBLANK
460  * @details After interval vblanks, a user vblank handler will be called.
461  * @param[in] output A output object
462  * @param[in] interval vblank interval
463  * @param[in] sync 0: asynchronous, 1:synchronous
464  * @param[in] func A user vblank handler
465  * @param[in] user_data The user data
466  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
467  * @see #tdm_output_vblank_handler
468  */
469 tdm_error
470 tdm_output_wait_vblank(tdm_output *output, int interval, int sync,
471                                            tdm_output_vblank_handler func, void *user_data);
472
473 /**
474  * @brief Commit changes for a output object
475  * @details After all change of a output object are applied, a user commit handler
476  * will be called.
477  * @param[in] output A output object
478  * @param[in] sync 0: asynchronous, 1:synchronous
479  * @param[in] func A user commit handler
480  * @param[in] user_data The user data
481  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
482  * @see #tdm_layer_commit
483  */
484 tdm_error
485 tdm_output_commit(tdm_output *output, int sync, tdm_output_commit_handler func,
486                                   void *user_data);
487
488 /**
489  * @brief Set one of available modes of a output object
490  * @param[in] output A output object
491  * @param[in] mode A output mode
492  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
493  */
494 tdm_error
495 tdm_output_set_mode(tdm_output *output, const tdm_output_mode *mode);
496
497 /**
498  * @brief Get the mode of a output object
499  * @param[in] output A output object
500  * @param[out] mode A output mode
501  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
502  */
503 tdm_error
504 tdm_output_get_mode(tdm_output *output, const tdm_output_mode **mode);
505
506 /**
507  * @brief Set DPMS of a output object
508  * @param[in] output A output object
509  * @param[in] dpms_value DPMS value
510  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
511  */
512 tdm_error
513 tdm_output_set_dpms(tdm_output *output, tdm_output_dpms dpms_value);
514
515 /**
516  * @brief Get DPMS of a output object
517  * @param[in] output A output object
518  * @param[out] dpms_value DPMS value
519  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
520  */
521 tdm_error
522 tdm_output_get_dpms(tdm_output *output, tdm_output_dpms *dpms_value);
523
524 /**
525  * @brief Create a capture object of a output object
526  * @param[in] output A output object
527  * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
528  * @return A capture object
529  * @see tdm_capture_destroy
530  */
531 tdm_capture *
532 tdm_output_create_capture(tdm_output *output, tdm_error *error);
533
534 /**
535  * @brief Get the capabilities of a layer object.
536  * @param[in] layer A layer object
537  * @param[out] capabilities The capabilities of a layer object
538  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
539  */
540 tdm_error
541 tdm_layer_get_capabilities(tdm_layer *layer,
542                                                    tdm_layer_capability *capabilities);
543
544 /**
545  * @brief Get the available format array of a layer object.
546  * @param[in] layer A layer object
547  * @param[out] formats The available format array
548  * @param[out] count The count of formats
549  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
550  */
551 tdm_error
552 tdm_layer_get_available_formats(tdm_layer *layer, const tbm_format **formats,
553                                                                 int *count);
554
555 /**
556  * @brief Get the available property array of a layer object.
557  * @param[in] layer A layer object
558  * @param[out] props The available property array
559  * @param[out] count The count of properties
560  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
561  */
562 tdm_error
563 tdm_layer_get_available_properties(tdm_layer *layer, const tdm_prop **props,
564                                                                    int *count);
565
566 /**
567  * @brief Get the zpos of a layer object.
568  * @details
569  * - GRAPHIC layers have fixed zpos. It starts from 0. It's @b non-changeable.
570  * - But the zpos of VIDEO layers will be decided by a backend module side.
571  * - A frontend user only can set the relative zpos to VIDEO layers via #tdm_layer_set_video_pos
572  * - The zpos of video layers is less than GRAPHIC layers or more than GRAPHIC
573  * layers. ie, ..., -2, -1, 4, 5, ... (if 0 <= GRAPHIC layer's zpos < 4).
574  *   -------------------------------- graphic layer  3 <-- top most layer
575  *   -------------------------------- graphic layer  2
576  *   -------------------------------- graphic layer  1
577  *   -------------------------------- graphic layer  0
578  *   -------------------------------- video   layer -1
579  *   -------------------------------- video   layer -2 <-- lowest layer
580  * @param[in] layer A layer object
581  * @param[out] zpos The zpos
582  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
583  * @see tdm_layer_set_video_pos, tdm_layer_capability
584  */
585 tdm_error
586 tdm_layer_get_zpos(tdm_layer *layer, int *zpos);
587
588 /**
589  * @brief Set the property which has a given id.
590  * @param[in] layer A layer object
591  * @param[in] id The property id
592  * @param[in] value The value
593  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
594  */
595 tdm_error
596 tdm_layer_set_property(tdm_layer *layer, unsigned int id, tdm_value value);
597
598 /**
599  * @brief Get the property which has a given id.
600  * @param[in] layer A layer object
601  * @param[in] id The property id
602  * @param[out] value The value
603  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
604  */
605 tdm_error
606 tdm_layer_get_property(tdm_layer *layer, unsigned int id, tdm_value *value);
607
608 /**
609  * @brief Set the geometry information to a layer object
610  * @details The geometry information will be applied when the output object
611  * of a layer object is committed. If a layer has TDM_LAYER_CAPABILITY_NO_CROP
612  * capability, a layer will ignore the pos(crop) information of #tdm_info_layer's
613  * src_config.
614  * @param[in] layer A layer object
615  * @param[in] info The geometry information
616  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
617  * @see tdm_layer_commit
618  */
619 tdm_error
620 tdm_layer_set_info(tdm_layer *layer, tdm_info_layer *info);
621
622 /**
623  * @brief Get the geometry information to a layer object
624  * @param[in] layer A layer object
625  * @param[out] info The geometry information
626  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
627  */
628 tdm_error
629 tdm_layer_get_info(tdm_layer *layer, tdm_info_layer *info);
630
631 /**
632  * @brief Set a TDM buffer to a layer object
633  * @details A TDM buffer will be applied when the output object
634  * of a layer object is committed.
635  * @param[in] layer A layer object
636  * @param[in] buffer A TDM buffer
637  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
638  * @see tdm_layer_commit
639  */
640 tdm_error
641 tdm_layer_set_buffer(tdm_layer *layer, tbm_surface_h buffer);
642
643 /**
644  * @brief Unset a TDM buffer from a layer object
645  * @details When this function is called, a current showing buffer will be
646  * disappeared from screen. Then nothing is showing on a layer object.
647  * @param[in] layer A layer object
648  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
649  */
650 tdm_error
651 tdm_layer_unset_buffer(tdm_layer *layer);
652
653 /**
654  * @brief Commit changes for a layer object
655  * @details After all change of a layer object are applied, a user commit handler
656  * will be called.
657  * @param[in] layer A layer object
658  * @param[in] func A user commit handler
659  * @param[in] user_data The user data
660  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
661  */
662 tdm_error
663 tdm_layer_commit(tdm_layer *layer, tdm_layer_commit_handler func, void *user_data);
664
665 tdm_error
666 tdm_layer_is_committing(tdm_layer *layer, unsigned int *committing);
667
668 /**
669  * @brief Get a displaying TDM buffer from a layer object
670  * @details A displaying TDM buffer is a current showing buffer on screen
671  * that is set to layer object and applied output object of a layer object.
672  * @param[in] layer A layer object
673  * @return A TDM buffer if success. Otherwise, NULL.
674  */
675 tbm_surface_h
676 tdm_layer_get_displaying_buffer(tdm_layer *layer, tdm_error *error);
677
678 /**
679  * @brief Set a TBM surface_queue to a layer object
680  * @details A TBM surface_queue will be applied when the output object
681  * of a layer object is committed. and TDM layer will be automatically updated
682  * @param[in] layer A layer object
683  * @param[in] buffer_queue A TBM surface_queue
684  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
685  * @see tdm_layer_commit
686  */
687 tdm_error
688 tdm_layer_set_buffer_queue(tdm_layer *layer, tbm_surface_queue_h buffer_queue);
689
690 /**
691  * @brief Unset a TBM surface_queue from a layer object
692  * @details When this function is called, a current surface_queue will be
693  * disappeared from screen. Then nothing is showing on a layer object.
694  * @param[in] layer A layer object
695  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
696  */
697 tdm_error
698 tdm_layer_unset_buffer_queue(tdm_layer *layer);
699
700 /**
701  * @brief Check wheter a layer object is available for a frontend user to use.
702  * @details A layer object is not usable if a TDM buffer is showing on screen
703  * via this layer object. By calling #tdm_layer_unset_buffer, this layer object
704  * will become usable.
705  * @param[in] layer A layer object
706  * @param[out] usable 1 if usable, 0 if not usable
707  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
708  */
709 tdm_error
710 tdm_layer_is_usable(tdm_layer *layer, unsigned int *usable);
711
712 /**
713  * @brief Set the relative zpos to a VIDEO layer object
714  * @details The zpos value is less than the minimum zpos of GRAPHIC layers, or
715  * it is more than the maximum zpos of GRAPHIC layers.
716  * @param[in] layer A VIDEO layer object
717  * @param[in] zpos The zpos
718  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
719  * @see tdm_layer_get_zpos, tdm_layer_capability
720  */
721 tdm_error
722 tdm_layer_set_video_pos(tdm_layer *layer, int zpos);
723
724 /**
725  * @brief Create a capture object of a layer object
726  * @param[in] layer A layer object
727  * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
728  * @return A capture object
729  * @see tdm_capture_destroy
730  */
731 tdm_capture *
732 tdm_layer_create_capture(tdm_layer *layer, tdm_error *error);
733
734 /**
735  * @brief Get buffer flags from a layer object
736  * @param[in] layer A layer object
737  * @param[out] flags a buffer flags value
738  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
739  */
740 tdm_error
741 tdm_layer_get_buffer_flags(tdm_layer *layer, unsigned int *flags);
742
743 /**
744  * @brief Destroy a pp object
745  * @param[in] pp A pp object
746  * @see tdm_display_create_pp
747  */
748 void
749 tdm_pp_destroy(tdm_pp *pp);
750
751 /**
752  * @brief Set the geometry information to a pp object
753  * @param[in] pp A pp object
754  * @param[in] info The geometry information
755  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
756  * @see tdm_pp_commit
757  */
758 tdm_error
759 tdm_pp_set_info(tdm_pp *pp, tdm_info_pp *info);
760
761 /**
762  * @brief Set the PP done handler to a pp object
763  * @details
764  * The user PP done handler will be called after converting a source buffer's image
765  * to a destination buffer.
766  * @param[in] pp A pp object
767  * @param[in] func A user PP done handler
768  * @param[in] user_data The user data
769  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
770  */
771 tdm_error
772 tdm_pp_set_done_handler(tdm_pp *pp, tdm_pp_done_handler func, void *user_data);
773
774 /**
775  * @brief Attach a source buffer and a destination buffer to a pp object
776  * @param[in] pp A pp object
777  * @param[in] src A source buffer
778  * @param[in] dst A destination buffer
779  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
780  * @see tdm_pp_commit, tdm_pp_set_done_handler
781  */
782 tdm_error
783 tdm_pp_attach(tdm_pp *pp, tbm_surface_h src, tbm_surface_h dst);
784
785 /**
786  * @brief Commit changes for a pp object
787  * @param[in] pp A pp object
788  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
789  */
790 tdm_error
791 tdm_pp_commit(tdm_pp *pp);
792
793 /**
794  * @brief Destroy a capture object
795  * @param[in] capture A capture object
796  * @see tdm_output_create_capture, tdm_layer_create_capture
797  */
798 void
799 tdm_capture_destroy(tdm_capture *capture);
800
801 /**
802  * @brief Set the geometry information to a capture object
803  * @param[in] capture A capture object
804  * @param[in] info The geometry information
805  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
806  * @see tdm_capture_commit
807  */
808 tdm_error
809 tdm_capture_set_info(tdm_capture *capture, tdm_info_capture *info);
810
811 /**
812  * @brief Set the capture done handler to a capture object
813  * @details
814  * The user capture done handler will be called after capturing a screen into a
815  * buffer.
816  * @param[in] capture A capture object
817  * @param[in] func A user capture done handler
818  * @param[in] user_data The user data
819  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
820  */
821 tdm_error
822 tdm_capture_set_done_handler(tdm_capture *capture, tdm_capture_done_handler func, void *user_data);
823
824 /**
825  * @brief Attach a TDM buffer to a capture object
826  * @param[in] capture A capture object
827  * @param[in] buffer A TDM buffer
828  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
829  * @see tdm_capture_commit, tdm_capture_set_done_handler
830  */
831 tdm_error
832 tdm_capture_attach(tdm_capture *capture, tbm_surface_h buffer);
833
834 /**
835  * @brief Commit changes for a capture object
836  * @param[in] capture A capture object
837  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
838  */
839 tdm_error
840 tdm_capture_commit(tdm_capture *capture);
841
842 /**
843  * @brief The release handler of a TDM buffer
844  * @param[in] buffer A TDM buffer
845  * @param[in] user_data user data
846  * @see tdm_buffer_add_release_handler, tdm_buffer_remove_release_handler
847  */
848 typedef void (*tdm_buffer_release_handler)(tbm_surface_h buffer,
849                                                                                    void *user_data);
850
851 /**
852  * @brief Add a release handler to a TDM buffer
853  * @details
854  * TDM has its own buffer release mechanism to let an frontend user know when a TDM buffer
855  * becomes available for a next job. A TDM buffer can be used for TDM to show
856  * it on screen or to capture an output and a layer. After all operations,
857  * TDM will release it immediately when TDM doesn't need it any more.
858  * @param[in] buffer A TDM buffer
859  * @param[in] func A release handler
860  * @param[in] user_data user data
861  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
862  * @see tdm_buffer_remove_release_handler
863  */
864 tdm_error
865 tdm_buffer_add_release_handler(tbm_surface_h buffer,
866                                                            tdm_buffer_release_handler func, void *user_data);
867
868 /**
869  * @brief Remove a release handler from a TDM buffer
870  * @param[in] buffer A TDM buffer
871  * @param[in] func A release handler
872  * @param[in] user_data user data
873  * @see tdm_buffer_add_release_handler
874  */
875 void
876 tdm_buffer_remove_release_handler(tbm_surface_h buffer,
877                                                                   tdm_buffer_release_handler func, void *user_data);
878
879 /**
880  * @brief The handler of a vblank object
881  * @see #tdm_vblank_wait, #tdm_vblank_wait_seq
882  */
883 typedef void (*tdm_vblank_handler)(tdm_vblank *vblank, tdm_error error, unsigned int sequence,
884                                                                    unsigned int tv_sec, unsigned int tv_usec, void *user_data);
885
886 /**
887  * @brief Create a vblank object
888  * @param[in] dpy A display object
889  * @param[in] output A output object
890  * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
891  * @return A vblank object
892  * @see #tdm_vblank_destroy
893  */
894 tdm_vblank*
895 tdm_vblank_create(tdm_display *dpy, tdm_output *output, tdm_error *error);
896
897 /**
898  * @brief Destroy a vblank object
899  * @param[in] vblank A vblank object
900  * @see #tdm_vblank_create
901  */
902 void
903 tdm_vblank_destroy(tdm_vblank *vblank);
904
905 /**
906  * @brief Set the fps to a vblank object
907  * @details Default is the @b vertical @b refresh @b rate of the given output.
908  * @param[in] vblank A vblank object
909  * @param[in] fps over 0
910  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
911  */
912 tdm_error
913 tdm_vblank_set_fps(tdm_vblank *vblank, unsigned int fps);
914
915 /**
916  * @brief Set the offset(milli-second) to a vblank object
917  * @details Default is @b 0.
918  * @param[in] vblank A vblank object
919  * @param[in] offset the offset(milli-second)
920  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
921  */
922 tdm_error
923 tdm_vblank_set_offset(tdm_vblank *vblank, int offset);
924
925 /**
926  * @brief Enable/Disable the fake vblank to a vblank object
927  * @details
928  * If enable_fake == 0, #tdm_vblank_wait will return TDM_ERROR_DPMS_OFF
929  * when DPMS off. Otherwise, #tdm_vblank_wait will return TDM_ERROR_NONE
930  * as success.
931  * @param[in] vblank A vblank object
932  * @param[in] enable_fake 1:enable, 0:disable
933  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
934  */
935 tdm_error
936 tdm_vblank_set_enable_fake(tdm_vblank *vblank, unsigned int enable_fake);
937
938 /**
939  * @brief Get the fake vblank
940  * @param[in] vblank A vblank object
941  * @return 1 if enable. Otherwise, 0.
942  */
943 unsigned int
944 tdm_vblank_get_enable_fake(tdm_vblank *vblank);
945
946 /**
947  * @brief Wait for a vblank
948  * @details
949  * Once #tdm_vblank_wait returns TDM_ERROR_NONE, the user vblank handler(#tdm_vblank_handler)
950  * SHOULD be called after the given interval. \n
951  * The sequence value of tdm_vblank_handler is the relative value of fps.
952  * If fps = 10, this sequence value should be increased by 10 during 1 second.
953  * @param[in] vblank A vblank object
954  * @param[in] req_sec The vblank request time(second)
955  * @param[in] req_usec The vblank request time(micro-second)
956  * @param[in] interval The vblank interval
957  * @param[in] func The user vblank handler
958  * @param[in] user_data The user data
959  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
960  */
961 tdm_error
962 tdm_vblank_wait(tdm_vblank *vblank, unsigned int req_sec, unsigned int req_usec,
963                                 unsigned int interval, tdm_vblank_handler func, void *user_data);
964
965 /**
966  * @brief Wait for a vblank with the target sequence number
967  * @param[in] vblank A vblank object
968  * @param[in] req_sec The vblank request time(second)
969  * @param[in] req_usec The vblank request time(micro-second)
970  * @param[in] sequence The target sequence number
971  * @param[in] func The user client vblank handler
972  * @param[in] user_data The user data
973  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
974  */
975 tdm_error
976 tdm_vblank_wait_seq(tdm_vblank *vblank, unsigned int req_sec, unsigned int req_usec,
977                                         unsigned int sequence, tdm_vblank_handler func, void *user_data);
978
979 #ifdef __cplusplus
980 }
981 #endif
982
983 #endif /* _TDM_H_ */