1 /**************************************************************************
5 Copyright 2015 Samsung Electronics co., Ltd. All Rights Reserved.
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>
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:
22 The above copyright notice and this permission notice (including the
23 next paragraph) shall be included in all copies or substantial portions
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.
34 **************************************************************************/
36 #ifndef _TDM_BACKEND_H_
37 #define _TDM_BACKEND_H_
39 #include <tbm_surface.h>
41 #include "tdm_types.h"
49 * @brief The backend header file of TDM to implement a TDM backend module.
52 #include <tdm_backend.h>
57 * @brief The backend module data
59 * The init() function of #tdm_backend_module returns the backend module data.
60 * And it will be passed to display functions of #tdm_func_display.
61 * @see tdm_backend_module, tdm_backend_module
63 typedef void tdm_backend_data;
66 * @brief The display capabilities structure of a backend module
67 * @see The display_get_capabilitiy() function of #tdm_func_display
69 typedef struct _tdm_caps_display {
70 int max_layer_count; /**< The maximum layer count. -1 means "not defined" */
74 * @brief The capabilities structure of a output object
75 * @see The output_get_capability() function of #tdm_func_output
77 typedef struct _tdm_caps_output {
78 char maker[TDM_NAME_LEN]; /**< The output maker */
79 char model[TDM_NAME_LEN]; /**< The output model */
80 char name[TDM_NAME_LEN]; /**< The output name */
82 tdm_output_conn_status status; /**< The connection status */
83 tdm_output_type type; /**< The connection type */
84 unsigned int type_id; /**< The connection type id */
86 unsigned int mode_count; /**< The count of available modes */
88 *modes; /**< The @b newly-allocated array of modes. will be freed in frontend. */
90 unsigned int prop_count; /**< The count of available properties */
91 tdm_prop *props; /**< The @b newly-allocated array of properties. will be freed in frontend. */
93 unsigned int mmWidth; /**< The physical width (milimeter) */
94 unsigned int mmHeight; /**< The physical height (milimeter) */
95 unsigned int subpixel; /**< The subpixel */
97 int min_w; /**< The minimun width. -1 means "not defined" */
98 int min_h; /**< The minimun height. -1 means "not defined" */
99 int max_w; /**< The maximum width. -1 means "not defined" */
100 int max_h; /**< The maximum height. -1 means "not defined" */
101 int preferred_align; /**< The prefered align. -1 means "not defined" */
105 * @brief The capabilities structure of a layer object
106 * @see The layer_get_capability() function of #tdm_func_layer
108 typedef struct _tdm_caps_layer {
109 tdm_layer_capability capabilities; /**< The capabilities of layer */
113 * GRAPHIC layers are non-changeable. The zpos of GRAPHIC layers starts
114 * from 0. If there are 4 GRAPHIC layers, The zpos SHOULD be 0, 1, 2, 3.\n
115 * But the zpos of VIDEO layer is changeable by layer_set_video_pos() function
116 * of #tdm_func_layer. And The zpos of VIDEO layers is less than GRAPHIC
117 * layers or more than GRAPHIC layers.
118 * ie, ..., -2, -1, 4, 5, ... (if 0 <= GRAPHIC layer's zpos < 4).
119 * The zpos of VIDEO layers is @b relative. It doesn't need to start
120 * from -1 or 4. Let's suppose that there are two VIDEO layers.
121 * One has -2 zpos. Another has -4 zpos. Then -2 Video layer is higher
122 * than -4 VIDEO layer.
126 unsigned int format_count; /**< The count of available formats */
128 *formats; /**< The @b newly-allocated array of formats. will be freed in frontend. */
130 unsigned int prop_count; /**< The count of available properties */
131 tdm_prop *props; /**< The @b newly-allocated array of properties. will be freed in frontend. */
135 * @brief The capabilities structure of a pp object
136 * @see The display_get_pp_capability() function of #tdm_func_display
138 typedef struct _tdm_caps_pp {
139 tdm_pp_capability capabilities; /**< The capabilities of pp */
141 unsigned int format_count; /**< The count of available formats */
143 *formats; /**< The @b newly-allocated array. will be freed in frontend. */
145 int min_w; /**< The minimun width. -1 means "not defined" */
146 int min_h; /**< The minimun height. -1 means "not defined" */
147 int max_w; /**< The maximum width. -1 means "not defined" */
148 int max_h; /**< The maximum height. -1 means "not defined" */
149 int preferred_align; /**< The prefered align. -1 means "not defined" */
153 * @brief The capabilities structure of a capture object
154 * @see The display_get_capture_capability() function of #tdm_func_display
156 typedef struct _tdm_caps_capture {
157 tdm_capture_capability capabilities; /**< The capabilities of capture */
159 unsigned int format_count; /**< The count of available formats */
161 *formats; /**< The @b newly-allocated array of formats. will be freed in frontend. */
163 int min_w; /**< The minimun width. -1 means "not defined" */
164 int min_h; /**< The minimun height. -1 means "not defined" */
165 int max_w; /**< The maximum width. -1 means "not defined" */
166 int max_h; /**< The maximum height. -1 means "not defined" */
167 int preferred_align; /**< The prefered align. -1 means "not defined" */
171 * @brief The display functions for a backend module.
173 typedef struct _tdm_func_display {
175 * @brief Get the display capabilities of a backend module
176 * @param[in] bdata The backend module data
177 * @param[out] caps The display capabilities of a backend module
178 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
180 * A backend module @b SHOULD implement this function. TDM calls this function
181 * not only at the initial time, but also at the update time when new output
183 * If a hardware has the restriction of the number of max usable layer count,
184 * a backend module can set the max count to max_layer_count of #tdm_caps_display
185 * structure. Otherwise, set -1.
187 tdm_error (*display_get_capabilitiy)(tdm_backend_data *bdata,
188 tdm_caps_display *caps);
191 * @brief Get the pp capabilities of a backend module
192 * @param[in] bdata The backend module data
193 * @param[out] caps The pp capabilities of a backend module
194 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
195 * @see tdm_backend_register_func_pp
197 * TDM calls this function not only at the initial time, but also at the update
198 * time when new output is connected.\n
199 * A backend module doesn't need to implement this function if a hardware
200 * doesn't have the memory-to-memory converting device. Otherwise, a backend module
201 * @b SHOULD fill the #tdm_caps_pp data. #tdm_caps_pp contains the hardware
202 * restriction information which a converting device can handle. ie, format, size, etc.
204 tdm_error (*display_get_pp_capability)(tdm_backend_data *bdata,
208 * @brief Get the capture capabilities of a backend module
209 * @param[in] bdata The backend module data
210 * @param[out] caps The capture capabilities of a backend module
211 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
212 * @see tdm_backend_register_func_capture
214 * TDM calls this function not only at the initial time, but also at the update
215 * time when new output is connected.\n
216 * A backend module doesn't need to implement this function if a hardware
217 * doesn't have the capture device. Otherwise, a backend module @b SHOULD fill the
218 * #tdm_caps_capture data. #tdm_caps_capture contains the hardware restriction
219 * information which a capture device can handle. ie, format, size, etc.
221 tdm_error (*display_get_capture_capability)(tdm_backend_data *bdata,
222 tdm_caps_capture *caps);
225 * @brief Get a output array of a backend module
226 * @param[in] bdata The backend module data
227 * @param[out] count The count of outputs
228 * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
229 * @return A output array which is @b newly-allocated
230 * @see tdm_backend_register_func_capture
232 * A backend module @b SHOULD implement this function. TDM calls this function
233 * not only at the initial time, but also at the update time when new output
235 * A backend module @b SHOULD return the @b newly-allocated array which contains
236 * "tdm_output*" data. It will be freed in frontend.
240 drm_display_get_outputs(tdm_backend_data *bdata, int *count, tdm_error *error)
242 tdm_drm_data *drm_data = bdata;
243 tdm_drm_output_data *output_data = NULL;
244 tdm_output **outputs;
248 LIST_FOR_EACH_ENTRY(output_data, &drm_data->output_list, link)
253 if (error) *error = TDM_ERROR_NONE;
257 // will be freed in frontend
258 outputs = calloc(*count, sizeof(tdm_drm_output_data*));
262 if (error) *error = TDM_ERROR_OUT_OF_MEMORY;
267 LIST_FOR_EACH_ENTRY(output_data, &drm_data->output_list, link)
268 outputs[i++] = output_data;
270 if (error) *error = TDM_ERROR_NONE;
276 tdm_output **(*display_get_outputs)(tdm_backend_data *bdata, int *count,
280 * @brief Get the file descriptor of a backend module
281 * @param[in] bdata The backend module data
282 * @param[out] fd The fd of a backend module
283 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
284 * @see display_handle_events() function of #tdm_func_display
286 * A backend module can return epoll's fd which is watching the backend device one more fds.
288 tdm_error (*display_get_fd)(tdm_backend_data *bdata, int *fd);
291 * @brief Handle the events which happens on the fd of a backend module
292 * @param[in] bdata The backend module data
293 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
295 tdm_error (*display_handle_events)(tdm_backend_data *bdata);
298 * @brief Create a pp object of a backend module
299 * @param[in] bdata The backend module data
300 * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
301 * @return A pp object
302 * @see pp_destroy() function of #tdm_func_pp
304 * A backend module doesn't need to implement this function if a hardware
305 * doesn't have the memory-to-memory converting device.
307 tdm_pp *(*display_create_pp)(tdm_backend_data *bdata, tdm_error *error);
309 void (*reserved1)(void);
310 void (*reserved2)(void);
311 void (*reserved3)(void);
312 void (*reserved4)(void);
313 void (*reserved5)(void);
314 void (*reserved6)(void);
315 void (*reserved7)(void);
316 void (*reserved8)(void);
320 * @brief The output functions for a backend module.
322 typedef struct _tdm_func_output {
324 * @brief Get the capabilities of a output object
325 * @param[in] output A output object
326 * @param[out] caps The capabilities of a output object
327 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
329 * A backend module @b SHOULD implement this function. TDM calls this function
330 * not only at the initial time, but also at the update time when new output
332 * #tdm_caps_output contains connection status, modes, avaiable properties,
333 * size restriction information, etc.
335 tdm_error (*output_get_capability)(tdm_output *output, tdm_caps_output *caps);
338 * @brief Get a layer array of a output object
339 * @param[in] output A output object
340 * @param[out] count The count of layers
341 * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
342 * @return A layer array which is @b newly-allocated
344 * A backend module @b SHOULD implement this function. TDM calls this function
345 * not only at the initial time, but also at the update time when new output
347 * A backend module @b SHOULD return the @b newly-allocated array which contains
348 * "tdm_layer*" data. It will be freed in frontend.
350 tdm_layer **(*output_get_layers)(tdm_output *output, int *count,
354 * @brief Set the property which has a given id
355 * @param[in] output A output object
356 * @param[in] id The property id
357 * @param[in] value The value
358 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
360 tdm_error (*output_set_property)(tdm_output *output, unsigned int id,
364 * @brief Get the property which has a given id
365 * @param[in] output A output object
366 * @param[in] id The property id
367 * @param[out] value The value
368 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
370 tdm_error (*output_get_property)(tdm_output *output, unsigned int id,
374 * @brief Wait for VBLANK
375 * @param[in] output A output object
376 * @param[in] interval vblank interval
377 * @param[in] sync 0: asynchronous, 1:synchronous
378 * @param[in] user_data The user data
379 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
380 * @see output_set_vblank_handler, tdm_output_vblank_handler
382 * A backend module @b SHOULD call a user vblank handler after interval vblanks.
384 tdm_error (*output_wait_vblank)(tdm_output *output, int interval, int sync,
388 * @brief Set a user vblank handler
389 * @param[in] output A output object
390 * @param[in] func A user vblank handler
391 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
393 tdm_error (*output_set_vblank_handler)(tdm_output *output,
394 tdm_output_vblank_handler func);
397 * @brief Commit changes for a output object
398 * @param[in] output A output object
399 * @param[in] sync 0: asynchronous, 1:synchronous
400 * @param[in] user_data The user data
401 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
402 * @see output_set_commit_handler, tdm_output_commit_handler
404 * A backend module @b SHOULD call a user commit handler after all change of
405 * a output object are applied.
407 tdm_error (*output_commit)(tdm_output *output, int sync, void *user_data);
410 * @brief Set a user commit handler
411 * @param[in] output A output object
412 * @param[in] func A user commit handler
413 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
415 tdm_error (*output_set_commit_handler)(tdm_output *output,
416 tdm_output_commit_handler func);
419 * @brief Set DPMS of a output object
420 * @param[in] output A output object
421 * @param[in] dpms_value DPMS value
422 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
424 tdm_error (*output_set_dpms)(tdm_output *output, tdm_output_dpms dpms_value);
427 * @brief Get DPMS of a output object
428 * @param[in] output A output object
429 * @param[out] dpms_value DPMS value
430 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
432 tdm_error (*output_get_dpms)(tdm_output *output, tdm_output_dpms *dpms_value);
435 * @brief Set one of available modes of a output object
436 * @param[in] output A output object
437 * @param[in] mode A output mode
438 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
440 tdm_error (*output_set_mode)(tdm_output *output, const tdm_output_mode *mode);
443 * @brief Get the mode of a output object
444 * @param[in] output A output object
445 * @param[out] mode A output mode
446 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
448 tdm_error (*output_get_mode)(tdm_output *output, const tdm_output_mode **mode);
451 * @brief Create a capture object of a output object
452 * @param[in] output A output object
453 * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
454 * @return A capture object
455 * @see capture_destroy() function of #tdm_func_capture
457 * A backend module doesn't need to implement this function if a hardware
458 * doesn't have the capture device.
460 tdm_capture *(*output_create_capture)(tdm_output *output, tdm_error *error);
462 void (*reserved1)(void);
463 void (*reserved2)(void);
464 void (*reserved3)(void);
465 void (*reserved4)(void);
466 void (*reserved5)(void);
467 void (*reserved6)(void);
468 void (*reserved7)(void);
469 void (*reserved8)(void);
473 * @brief The layer functions for a backend module.
475 typedef struct _tdm_func_layer {
477 * @brief Get the capabilities of a layer object
478 * @param[in] layer A layer object
479 * @param[out] caps The capabilities of a layer object
480 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
482 * A backend module @b SHOULD implement this function. TDM calls this function
483 * not only at the initial time, but also at the update time when new output
485 * #tdm_caps_layer contains avaiable formats/properties, zpos information, etc.
487 tdm_error (*layer_get_capability)(tdm_layer *layer, tdm_caps_layer *caps);
490 * @brief Set the property which has a given id.
491 * @param[in] layer A layer object
492 * @param[in] id The property id
493 * @param[in] value The value
494 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
496 tdm_error (*layer_set_property)(tdm_layer *layer, unsigned int id,
500 * @brief Get the property which has a given id.
501 * @param[in] layer A layer object
502 * @param[in] id The property id
503 * @param[out] value The value
504 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
506 tdm_error (*layer_get_property)(tdm_layer *layer, unsigned int id,
510 * @brief Set the geometry information to a layer object
511 * @param[in] layer A layer object
512 * @param[in] info The geometry information
513 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
514 * @see output_commit() function of #tdm_func_output
516 * A backend module would apply the geometry information when the output object
517 * of a layer object is committed.
519 tdm_error (*layer_set_info)(tdm_layer *layer, tdm_info_layer *info);
522 * @brief Get the geometry information to a layer object
523 * @param[in] layer A layer object
524 * @param[out] info The geometry information
525 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
527 tdm_error (*layer_get_info)(tdm_layer *layer, tdm_info_layer *info);
530 * @brief Set a TDM buffer to a layer object
531 * @param[in] layer A layer object
532 * @param[in] buffer A TDM buffer
533 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
534 * @see output_commit() function of #tdm_func_output
536 * A backend module would apply a TDM buffer when the output object
537 * of a layer object is committed.
539 tdm_error (*layer_set_buffer)(tdm_layer *layer, tbm_surface_h buffer);
542 * @brief Unset a TDM buffer from a layer object
543 * @param[in] layer A layer object
544 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
546 * A backend module @b SHOULD hide the current showing buffer from screen.
547 * If needed, cleanup a layer object resource.
549 tdm_error (*layer_unset_buffer)(tdm_layer *layer);
552 * @brief Set the zpos for a VIDEO layer object
553 * @param[in] layer A layer object
554 * @param[in] zpos z-order
555 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
556 * @see tdm_caps_layer, tdm_layer_capability
558 * A backend module doesn't need to implement this function if a backend
559 * module doesn't have VIDEO layers.\n
560 * This function is for VIDEO layers.
561 * GRAPHIC layers are non-changeable. The zpos of GRAPHIC layers starts
562 * from 0. If there are 4 GRAPHIC layers, The zpos SHOULD be 0, 1, 2, 3.\n
563 * But the zpos of VIDEO layer is changeable. And The zpos of VIDEO layers
564 * is less than GRAPHIC layers or more than GRAPHIC layers.
565 * ie, ..., -2, -1, 4, 5, ... (if 0 <= GRAPHIC layer's zpos < 4).
566 * The zpos of VIDEO layers is @b relative. It doesn't need to start
567 * from -1 or 4. Let's suppose that there are two VIDEO layers.
568 * One has -2 zpos. Another has -4 zpos. Then -2 Video layer is higher
569 * than -4 VIDEO layer.
571 tdm_error (*layer_set_video_pos)(tdm_layer *layer, int zpos);
574 * @brief Create a capture object of a layer object
575 * @param[in] output A output object
576 * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
577 * @return A capture object
578 * @see capture_destroy() function of #tdm_func_capture
580 * A backend module doesn't need to implement this function if a hardware
581 * doesn't have the capture device.
583 tdm_capture *(*layer_create_capture)(tdm_layer *layer, tdm_error *error);
585 void (*reserved1)(void);
586 void (*reserved2)(void);
587 void (*reserved3)(void);
588 void (*reserved4)(void);
589 void (*reserved5)(void);
590 void (*reserved6)(void);
591 void (*reserved7)(void);
592 void (*reserved8)(void);
596 * @brief The done handler of a pp object
598 typedef void (*tdm_pp_done_handler)(tdm_pp *pp, tbm_surface_h src,
599 tbm_surface_h dst, void *user_data);
602 * @brief The pp functions for a backend module.
604 typedef struct _tdm_func_pp {
606 * @brief Destroy a pp object
607 * @param[in] pp A pp object
608 * @see display_create_pp() function of #tdm_func_display
610 void (*pp_destroy)(tdm_pp *pp);
613 * @brief Set the geometry information to a pp object
614 * @param[in] pp A pp object
615 * @param[in] info The geometry information
616 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
617 * @see pp_commit() function of #tdm_func_pp
619 * A backend module would apply the geometry information when committed.
621 tdm_error (*pp_set_info)(tdm_pp *pp, tdm_info_pp *info);
624 * @brief Attach a source buffer and a destination buffer to a pp object
625 * @param[in] pp A pp object
626 * @param[in] src A source buffer
627 * @param[in] dst A destination buffer
628 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
629 * @see pp_set_info() function of #tdm_func_pp
630 * @see pp_commit() function of #tdm_func_pp
631 * @see pp_set_done_handler, tdm_pp_done_handler
633 * A backend module converts the image of a source buffer to a destination
634 * buffer when committed. The size/crop/transform information is set via
635 * #pp_set_info() of #tdm_func_pp. When done, a backend module @b SHOULD
636 * return the source/destination buffer via tdm_pp_done_handler.
638 tdm_error (*pp_attach)(tdm_pp *pp, tbm_surface_h src, tbm_surface_h dst);
641 * @brief Commit changes for a pp object
642 * @param[in] pp A pp object
643 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
645 tdm_error (*pp_commit)(tdm_pp *pp);
648 * @brief Set a user done handler to a pp object
649 * @param[in] pp A pp object
650 * @param[in] func A user done handler
651 * @param[in] user_data user data
652 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
654 * A backend module @b SHOULD call #tdm_pp_done_handler when converintg a image is done.
656 tdm_error (*pp_set_done_handler)(tdm_pp *pp, tdm_pp_done_handler func,
659 void (*reserved1)(void);
660 void (*reserved2)(void);
661 void (*reserved3)(void);
662 void (*reserved4)(void);
663 void (*reserved5)(void);
664 void (*reserved6)(void);
665 void (*reserved7)(void);
666 void (*reserved8)(void);
670 * @brief The done handler of a capture object
672 typedef void (*tdm_capture_done_handler)(tdm_capture *capture,
673 tbm_surface_h buffer, void *user_data);
676 * @brief The capture functions for a backend module.
678 typedef struct _tdm_func_capture {
680 * @brief Destroy a capture object
681 * @param[in] capture A capture object
682 * @see output_create_capture() function of #tdm_func_output
683 * @see layer_create_capture() function of #tdm_func_layer
685 void (*capture_destroy)(tdm_capture *capture);
688 * @brief Set the geometry information to a capture object
689 * @param[in] capture A capture object
690 * @param[in] info The geometry information
691 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
692 * @see capture_commit() function of #tdm_func_capture
694 * A backend module would apply the geometry information when committed.
696 tdm_error (*capture_set_info)(tdm_capture *capture, tdm_info_capture *info);
699 * @brief Attach a TDM buffer to a capture object
700 * @details When capture_commit() function is called, a backend module dumps
701 * a output or a layer to a TDM buffer.
702 * @param[in] capture A capture object
703 * @param[in] buffer A TDM buffer
704 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
705 * @see capture_set_info() function of #tdm_func_capture
706 * @see capture_commit() function of #tdm_func_capture
707 * @see capture_set_done_handler, tdm_capture_done_handler
709 * A backend module dumps a output or a layer to to a TDM buffer when
710 * committed. The size/crop/transform information is set via #capture_set_info()
711 * of #tdm_func_capture. When done, a backend module @b SHOULD return the TDM
712 * buffer via tdm_capture_done_handler.
714 tdm_error (*capture_attach)(tdm_capture *capture, tbm_surface_h buffer);
717 * @brief Commit changes for a capture object
718 * @param[in] capture A capture object
719 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
721 tdm_error (*capture_commit)(tdm_capture *capture);
724 * @brief Set a user done handler to a capture object
725 * @param[in] capture A capture object
726 * @param[in] func A user done handler
727 * @param[in] user_data user data
728 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
730 * A backend module @b SHOULD call #tdm_capture_done_handler when capture operation is done.
732 tdm_error (*capture_set_done_handler)(tdm_capture *capture,
733 tdm_capture_done_handler func, void *user_data);
735 void (*reserved1)(void);
736 void (*reserved2)(void);
737 void (*reserved3)(void);
738 void (*reserved4)(void);
739 void (*reserved5)(void);
740 void (*reserved6)(void);
741 void (*reserved7)(void);
742 void (*reserved8)(void);
746 * ABI versions. Each version has a major and minor revision. Modules
747 * using lower minor revisions must work with servers of a higher minor
748 * revision. There is no compatibility between different major revisions.
749 * Whenever the ABI_ANSIC_VERSION is changed, the others must also be
750 * changed. The minor revision mask is 0x0000FFFF and the major revision
751 * mask is 0xFFFF0000.
753 #define TDM_BACKEND_MINOR_VERSION_MASK 0x0000FFFF
754 #define TDM_BACKEND_MAJOR_VERSION_MASK 0xFFFF0000
755 #define TDM_BACKEND_GET_ABI_MINOR(v) ((v) & TDM_BACKEND_MINOR_VERSION_MASK)
756 #define TDM_BACKEND_GET_ABI_MAJOR(v) (((v) & TDM_BACKEND_MAJOR_VERSION_MASK) >> 16)
758 #define SET_TDM_BACKEND_ABI_VERSION(major, minor) \
759 (((major) << 16) & TDM_BACKEND_MAJOR_VERSION_MASK) | \
760 ((major) & TDM_BACKEND_MINOR_VERSION_MASK)
761 #define TDM_BACKEND_ABI_VERSION SET_TDM_BACKEND_ABI_VERSION(1, 1)
764 * @brief The backend module information of the entry point to initialize a TDM
767 * A backend module @b SHOULD define the global data symbol of which name is
768 * @b "tdm_backend_module_data". TDM will read this symbol, @b "tdm_backend_module_data",
769 * at the initial time and call init() function of #tdm_backend_module.
771 typedef struct _tdm_backend_module {
772 const char *name; /**< The module name of a backend module */
773 const char *vendor; /**< The vendor name of a backend module */
774 unsigned long abi_version; /**< The ABI version of a backend module */
777 * @brief The init function of a backend module
778 * @param[in] dpy A display object
779 * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
780 * @return The backend module data
781 * @see tdm_backend_data
783 tdm_backend_data *(*init)(tdm_display *dpy, tdm_error *error);
786 * @brief The deinit function of a backend module
787 * @param[in] bdata The backend module data
789 void (*deinit)(tdm_backend_data *bdata);
790 } tdm_backend_module;
793 * @brief Register the backend display functions to a display
794 * @param[in] dpy A display object
795 * @param[in] func_display display functions
796 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
797 * @see tdm_backend_register_func_output, tdm_backend_register_func_layer
799 * A backend module @b SHOULD set the backend display functions at least.
802 tdm_backend_register_func_display(tdm_display *dpy,
803 tdm_func_display *func_display);
806 * @brief Register the backend output functions to a display
807 * @param[in] dpy A display object
808 * @param[in] func_output output functions
809 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
810 * @see tdm_backend_register_func_display, tdm_backend_register_func_layer
812 * A backend module @b SHOULD set the backend output functions at least.
815 tdm_backend_register_func_output(tdm_display *dpy,
816 tdm_func_output *func_output);
819 * @brief Register the backend layer functions to a display
820 * @param[in] dpy A display object
821 * @param[in] func_layer layer functions
822 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
823 * @see tdm_backend_register_func_display, tdm_backend_register_func_output
825 * A backend module @b SHOULD set the backend layer functions at least.
828 tdm_backend_register_func_layer(tdm_display *dpy, tdm_func_layer *func_layer);
831 * @brief Register the backend pp functions to a display
832 * @param[in] dpy A display object
833 * @param[in] func_pp pp functions
834 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
835 * @see tdm_backend_register_func_display, tdm_backend_register_func_capture
837 * A backend module doesn'tcan skip to register the backend pp functions
838 * if a hardware doesn't have the memory-to-memory converting device.
841 tdm_backend_register_func_pp(tdm_display *dpy, tdm_func_pp *func_pp);
844 * @brief Register the backend capture functions to a display
845 * @param[in] dpy A display object
846 * @param[in] func_capture capture functions
847 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
848 * @see tdm_backend_register_func_display, tdm_backend_register_func_pp
850 * A backend module can skip to register the backend capture functions
851 * if a hardware doesn't have the capture device.
854 tdm_backend_register_func_capture(tdm_display *dpy,
855 tdm_func_capture *func_capture);
858 * @brief Increase the ref_count of a TDM buffer
860 * TDM has its own buffer release mechanism to let an frontend user know when a TDM buffer
861 * becomes available for a next job. A TDM buffer can be used for TDM to show
862 * it on screen or to capture an output and a layer. After all operations,
863 * TDM will release it immediately when TDM doesn't need it any more.
864 * @param[in] buffer A TDM buffer
865 * @return A buffer itself. Otherwise, NULL.
866 * @see tdm_buffer_unref_backend
868 * - This function @b SHOULD be paired with #tdm_buffer_unref_backend. \n
869 * - For example, this function @b SHOULD be called in case that a backend module uses the TDM
870 * buffer of a layer for capturing a output or a layer to avoid tearing issue.
873 tdm_buffer_ref_backend(tbm_surface_h buffer);
876 * @brief Decrease the ref_count of a TDM buffer
877 * @param[in] buffer A TDM buffer
878 * @see tdm_buffer_ref_backend
881 tdm_buffer_unref_backend(tbm_surface_h buffer);
884 * @brief The destroy handler of a TDM buffer
885 * @param[in] buffer A TDM buffer
886 * @param[in] user_data user data
887 * @see tdm_buffer_add_destroy_handler, tdm_buffer_remove_destroy_handler
889 typedef void (*tdm_buffer_destroy_handler)(tbm_surface_h buffer,
893 * @brief Add a destroy handler to a TDM buffer
894 * @param[in] buffer A TDM buffer
895 * @param[in] func A destroy handler
896 * @param[in] user_data user data
897 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
898 * @see tdm_buffer_remove_destroy_handler
900 * A backend module can add a TDM buffer destroy handler to a TDM buffer which
901 * is a #tbm_surface_h object. When the TDM buffer is destroyed, this handler will
905 tdm_buffer_add_destroy_handler(tbm_surface_h buffer,
906 tdm_buffer_destroy_handler func, void *user_data);
909 * @brief Remove a destroy handler from a TDM buffer
910 * @param[in] buffer A TDM buffer
911 * @param[in] func A destroy handler
912 * @param[in] user_data user data
913 * @see tdm_buffer_add_destroy_handler
916 tdm_buffer_remove_destroy_handler(tbm_surface_h buffer,
917 tdm_buffer_destroy_handler func, void *user_data);
921 tdm_event_add_fd_handler(tdm_display *dpy, int fd, tdm_event_mask mask,
922 tdm_event_fd_handler func, void *user_data,
926 tdm_event_source_fd_update(tdm_event_source *source, tdm_event_mask mask);
929 tdm_event_add_timer_handler(tdm_display *dpy, tdm_event_timer_handler func,
930 void *user_data, tdm_error *error);
933 tdm_event_source_timer_update(tdm_event_source *source, int ms_delay);
936 tdm_event_source_remove(tdm_event_source *source);
942 #endif /* _TDM_BACKEND_H_ */