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 output status handler
67 * @details This handler will be called when the status of a output object is
70 typedef void (*tdm_output_status_handler)(tdm_output *output,
71 tdm_output_conn_status status,
75 * @brief The display capabilities structure of a backend module
76 * @see The display_get_capabilitiy() function of #tdm_func_display
78 typedef struct _tdm_caps_display {
79 int max_layer_count; /**< The maximum layer count. -1 means "not defined" */
83 * @brief The capabilities structure of a output object
84 * @see The output_get_capability() function of #tdm_func_output
86 typedef struct _tdm_caps_output {
87 char maker[TDM_NAME_LEN]; /**< The output maker */
88 char model[TDM_NAME_LEN]; /**< The output model */
89 char name[TDM_NAME_LEN]; /**< The output name */
91 tdm_output_conn_status status; /**< The connection status */
92 tdm_output_type type; /**< The connection type */
93 unsigned int type_id; /**< The connection type id */
95 unsigned int mode_count; /**< The count of available modes */
97 *modes; /**< The @b newly-allocated array of modes. will be freed in frontend. */
99 unsigned int prop_count; /**< The count of available properties */
100 tdm_prop *props; /**< The @b newly-allocated array of properties. will be freed in frontend. */
102 unsigned int mmWidth; /**< The physical width (milimeter) */
103 unsigned int mmHeight; /**< The physical height (milimeter) */
104 unsigned int subpixel; /**< The subpixel */
106 int min_w; /**< The minimun width. -1 means "not defined" */
107 int min_h; /**< The minimun height. -1 means "not defined" */
108 int max_w; /**< The maximum width. -1 means "not defined" */
109 int max_h; /**< The maximum height. -1 means "not defined" */
110 int preferred_align; /**< The prefered align. -1 means "not defined" */
114 * @brief The capabilities structure of a layer object
115 * @see The layer_get_capability() function of #tdm_func_layer
117 typedef struct _tdm_caps_layer {
118 tdm_layer_capability capabilities; /**< The capabilities of layer */
122 * GRAPHIC layers are non-changeable. The zpos of GRAPHIC layers starts
123 * from 0. If there are 4 GRAPHIC layers, The zpos SHOULD be 0, 1, 2, 3.\n
124 * But the zpos of VIDEO layer is changeable by layer_set_video_pos() function
125 * of #tdm_func_layer. And The zpos of VIDEO layers is less than GRAPHIC
126 * layers or more than GRAPHIC layers.
127 * ie, ..., -2, -1, 4, 5, ... (if 0 <= GRAPHIC layer's zpos < 4).
128 * The zpos of VIDEO layers is @b relative. It doesn't need to start
129 * from -1 or 4. Let's suppose that there are two VIDEO layers.
130 * One has -2 zpos. Another has -4 zpos. Then -2 Video layer is higher
131 * than -4 VIDEO layer.
135 unsigned int format_count; /**< The count of available formats */
137 *formats; /**< The @b newly-allocated array of formats. will be freed in frontend. */
139 unsigned int prop_count; /**< The count of available properties */
140 tdm_prop *props; /**< The @b newly-allocated array of properties. will be freed in frontend. */
144 * @brief The capabilities structure of a pp object
145 * @see The display_get_pp_capability() function of #tdm_func_display
147 typedef struct _tdm_caps_pp {
148 tdm_pp_capability capabilities; /**< The capabilities of pp */
150 unsigned int format_count; /**< The count of available formats */
152 *formats; /**< The @b newly-allocated array. will be freed in frontend. */
154 int min_w; /**< The minimun width. -1 means "not defined" */
155 int min_h; /**< The minimun height. -1 means "not defined" */
156 int max_w; /**< The maximum width. -1 means "not defined" */
157 int max_h; /**< The maximum height. -1 means "not defined" */
158 int preferred_align; /**< The prefered align. -1 means "not defined" */
160 int max_attach_count; /**< The attach count which a PP object can handle.
161 * -1 means "not defined".
167 * @brief The capabilities structure of a capture object
168 * @see The display_get_capture_capability() function of #tdm_func_display
170 typedef struct _tdm_caps_capture {
171 tdm_capture_capability capabilities; /**< The capabilities of capture */
173 unsigned int format_count; /**< The count of available formats */
175 *formats; /**< The @b newly-allocated array of formats. will be freed in frontend. */
177 int min_w; /**< The minimun width. -1 means "not defined" */
178 int min_h; /**< The minimun height. -1 means "not defined" */
179 int max_w; /**< The maximum width. -1 means "not defined" */
180 int max_h; /**< The maximum height. -1 means "not defined" */
181 int preferred_align; /**< The prefered align. -1 means "not defined" */
183 int max_attach_count; /**< The attach count which a capture object can handle.
184 * -1 means "not defined".
190 * @brief The display functions for a backend module.
192 typedef struct _tdm_func_display {
194 * @brief Get the display capabilities of a backend module
195 * @param[in] bdata The backend module data
196 * @param[out] caps The display capabilities of a backend module
197 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
199 * A backend module @b SHOULD implement this function. TDM calls this function
200 * not only at the initial time, but also at the update time when new output
202 * If a hardware has the restriction of the number of max usable layer count,
203 * a backend module can set the max count to max_layer_count of #tdm_caps_display
204 * structure. Otherwise, set -1.
206 tdm_error (*display_get_capabilitiy)(tdm_backend_data *bdata,
207 tdm_caps_display *caps);
210 * @brief Get the pp capabilities of a backend module
211 * @param[in] bdata The backend module data
212 * @param[out] caps The pp capabilities of a backend module
213 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
214 * @see tdm_backend_register_func_pp
216 * TDM calls this function not only at the initial time, but also at the update
217 * time when new output is connected.\n
218 * A backend module doesn't need to implement this function if a hardware
219 * doesn't have the memory-to-memory converting device. Otherwise, a backend module
220 * @b SHOULD fill the #tdm_caps_pp data. #tdm_caps_pp contains the hardware
221 * restriction information which a converting device can handle. ie, format, size, etc.
223 tdm_error (*display_get_pp_capability)(tdm_backend_data *bdata,
227 * @brief Get the capture capabilities of a backend module
228 * @param[in] bdata The backend module data
229 * @param[out] caps The capture capabilities of a backend module
230 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
231 * @see tdm_backend_register_func_capture
233 * TDM calls this function not only at the initial time, but also at the update
234 * time when new output is connected.\n
235 * A backend module doesn't need to implement this function if a hardware
236 * doesn't have the capture device. Otherwise, a backend module @b SHOULD fill the
237 * #tdm_caps_capture data. #tdm_caps_capture contains the hardware restriction
238 * information which a capture device can handle. ie, format, size, etc.
240 tdm_error (*display_get_capture_capability)(tdm_backend_data *bdata,
241 tdm_caps_capture *caps);
244 * @brief Get a output array of a backend module
245 * @param[in] bdata The backend module data
246 * @param[out] count The count of outputs
247 * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
248 * @return A output array which is @b newly-allocated
249 * @see tdm_backend_register_func_capture
251 * A backend module @b SHOULD implement this function. TDM calls this function
252 * not only at the initial time, but also at the update time when new output
254 * A backend module @b SHOULD return the @b newly-allocated array which contains
255 * "tdm_output*" data. It will be freed in frontend.
259 drm_display_get_outputs(tdm_backend_data *bdata, int *count, tdm_error *error)
261 tdm_drm_data *drm_data = bdata;
262 tdm_drm_output_data *output_data = NULL;
263 tdm_output **outputs;
267 LIST_FOR_EACH_ENTRY(output_data, &drm_data->output_list, link)
272 if (error) *error = TDM_ERROR_NONE;
276 // will be freed in frontend
277 outputs = calloc(*count, sizeof(tdm_drm_output_data*));
281 if (error) *error = TDM_ERROR_OUT_OF_MEMORY;
286 LIST_FOR_EACH_ENTRY(output_data, &drm_data->output_list, link)
287 outputs[i++] = output_data;
289 if (error) *error = TDM_ERROR_NONE;
295 tdm_output **(*display_get_outputs)(tdm_backend_data *bdata, int *count,
299 * @brief Get the file descriptor of a backend module
300 * @param[in] bdata The backend module data
301 * @param[out] fd The fd of a backend module
302 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
303 * @see display_handle_events() function of #tdm_func_display
305 * A backend module can return epoll's fd which is watching the backend device one more fds.
307 tdm_error (*display_get_fd)(tdm_backend_data *bdata, int *fd);
310 * @brief Handle the events which happens on the fd of a backend module
311 * @param[in] bdata The backend module data
312 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
314 tdm_error (*display_handle_events)(tdm_backend_data *bdata);
317 * @brief Create a pp object of a backend module
318 * @param[in] bdata The backend module data
319 * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
320 * @return A pp object
321 * @see pp_destroy() function of #tdm_func_pp
323 * A backend module doesn't need to implement this function if a hardware
324 * doesn't have the memory-to-memory converting device.
326 tdm_pp *(*display_create_pp)(tdm_backend_data *bdata, tdm_error *error);
328 void (*reserved1)(void);
329 void (*reserved2)(void);
330 void (*reserved3)(void);
331 void (*reserved4)(void);
332 void (*reserved5)(void);
333 void (*reserved6)(void);
334 void (*reserved7)(void);
335 void (*reserved8)(void);
339 * @brief The output functions for a backend module.
341 typedef struct _tdm_func_output {
343 * @brief Get the capabilities of a output object
344 * @param[in] output A output object
345 * @param[out] caps The capabilities of a output object
346 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
348 * A backend module @b SHOULD implement this function. TDM calls this function
349 * not only at the initial time, but also at the update time when new output
351 * #tdm_caps_output contains connection status, modes, avaiable properties,
352 * size restriction information, etc.
354 tdm_error (*output_get_capability)(tdm_output *output, tdm_caps_output *caps);
357 * @brief Get a layer array of a output object
358 * @param[in] output A output object
359 * @param[out] count The count of layers
360 * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
361 * @return A layer array which is @b newly-allocated
363 * A backend module @b SHOULD implement this function. TDM calls this function
364 * not only at the initial time, but also at the update time when new output
366 * A backend module @b SHOULD return the @b newly-allocated array which contains
367 * "tdm_layer*" data. It will be freed in frontend.
369 tdm_layer **(*output_get_layers)(tdm_output *output, int *count,
373 * @brief Set the property which has a given id
374 * @param[in] output A output object
375 * @param[in] id The property id
376 * @param[in] value The value
377 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
379 tdm_error (*output_set_property)(tdm_output *output, unsigned int id,
383 * @brief Get the property which has a given id
384 * @param[in] output A output object
385 * @param[in] id The property id
386 * @param[out] value The value
387 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
389 tdm_error (*output_get_property)(tdm_output *output, unsigned int id,
393 * @brief Wait for VBLANK
394 * @param[in] output A output object
395 * @param[in] interval vblank interval
396 * @param[in] sync 0: asynchronous, 1:synchronous
397 * @param[in] user_data The user data
398 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
399 * @see output_set_vblank_handler, tdm_output_vblank_handler
401 * If this function returns TDM_ERROR_NONE, a backend module @b SHOULD call
402 * a user vblank handler with the user data of this function after interval
405 tdm_error (*output_wait_vblank)(tdm_output *output, int interval, int sync,
409 * @brief Set a user vblank handler
410 * @param[in] output A output object
411 * @param[in] func A user vblank handler
412 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
414 tdm_error (*output_set_vblank_handler)(tdm_output *output,
415 tdm_output_vblank_handler func);
418 * @brief Commit changes for a output object
419 * @param[in] output A output object
420 * @param[in] sync 0: asynchronous, 1:synchronous
421 * @param[in] user_data The user data
422 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
423 * @see output_set_commit_handler, tdm_output_commit_handler
425 * When this function is called, a backend module @b SHOULD apply the all
426 * changes of the given output object to screen as well as the layer changes
428 * If this function returns TDM_ERROR_NONE, a backend module @b SHOULD call
429 * a user commit handler with the user data of this function after all
430 * changes of the given output object are applied.
432 tdm_error (*output_commit)(tdm_output *output, int sync, void *user_data);
435 * @brief Set a user commit handler
436 * @param[in] output A output object
437 * @param[in] func A user commit handler
438 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
440 tdm_error (*output_set_commit_handler)(tdm_output *output,
441 tdm_output_commit_handler func);
444 * @brief Set DPMS of a output object
445 * @param[in] output A output object
446 * @param[in] dpms_value DPMS value
447 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
449 tdm_error (*output_set_dpms)(tdm_output *output, tdm_output_dpms dpms_value);
452 * @brief Get DPMS of a output object
453 * @param[in] output A output object
454 * @param[out] dpms_value DPMS value
455 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
457 tdm_error (*output_get_dpms)(tdm_output *output, tdm_output_dpms *dpms_value);
460 * @brief Set one of available modes of a output object
461 * @param[in] output A output object
462 * @param[in] mode A output mode
463 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
465 tdm_error (*output_set_mode)(tdm_output *output, const tdm_output_mode *mode);
468 * @brief Get the mode of a output object
469 * @param[in] output A output object
470 * @param[out] mode A output mode
471 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
473 tdm_error (*output_get_mode)(tdm_output *output, const tdm_output_mode **mode);
476 * @brief Create a capture object of a output object
477 * @param[in] output A output object
478 * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
479 * @return A capture object
480 * @see capture_destroy() function of #tdm_func_capture
482 * A backend module doesn't need to implement this function if a hardware
483 * doesn't have the capture device.
485 tdm_capture *(*output_create_capture)(tdm_output *output, tdm_error *error);
488 * @brief Set a output connection status handler
489 * @details A backend module need to call the output status handler when the
490 * output connection status has been changed to let the TDM frontend know
492 * @param[in] output A output object
493 * @param[in] func A output status handler
494 * @param[in] user_data The user data
495 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
498 tdm_error (*output_set_status_handler)(tdm_output *output,
499 tdm_output_status_handler func,
502 void (*reserved1)(void);
503 void (*reserved2)(void);
504 void (*reserved3)(void);
505 void (*reserved4)(void);
506 void (*reserved5)(void);
507 void (*reserved6)(void);
508 void (*reserved7)(void);
509 void (*reserved8)(void);
513 * @brief The layer functions for a backend module.
515 typedef struct _tdm_func_layer {
517 * @brief Get the capabilities of a layer object
518 * @param[in] layer A layer object
519 * @param[out] caps The capabilities of a layer object
520 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
522 * A backend module @b SHOULD implement this function. TDM calls this function
523 * not only at the initial time, but also at the update time when new output
525 * #tdm_caps_layer contains avaiable formats/properties, zpos information, etc.
527 tdm_error (*layer_get_capability)(tdm_layer *layer, tdm_caps_layer *caps);
530 * @brief Set the property which has a given id.
531 * @param[in] layer A layer object
532 * @param[in] id The property id
533 * @param[in] value The value
534 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
536 tdm_error (*layer_set_property)(tdm_layer *layer, unsigned int id,
540 * @brief Get the property which has a given id.
541 * @param[in] layer A layer object
542 * @param[in] id The property id
543 * @param[out] value The value
544 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
546 tdm_error (*layer_get_property)(tdm_layer *layer, unsigned int id,
550 * @brief Set the geometry information to a layer object
551 * @param[in] layer A layer object
552 * @param[in] info The geometry information
553 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
554 * @see output_commit() function of #tdm_func_output
556 * A backend module would apply the geometry information when the output object
557 * of a layer object is committed.
559 tdm_error (*layer_set_info)(tdm_layer *layer, tdm_info_layer *info);
562 * @brief Get the geometry information to a layer object
563 * @param[in] layer A layer object
564 * @param[out] info The geometry information
565 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
567 tdm_error (*layer_get_info)(tdm_layer *layer, tdm_info_layer *info);
570 * @brief Set a TDM buffer to a layer object
571 * @param[in] layer A layer object
572 * @param[in] buffer A TDM buffer
573 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
574 * @see output_commit() function of #tdm_func_output
576 * A backend module would apply a TDM buffer when the output object
577 * of a layer object is committed.
579 tdm_error (*layer_set_buffer)(tdm_layer *layer, tbm_surface_h buffer);
582 * @brief Unset a TDM buffer from a layer object
583 * @param[in] layer A layer object
584 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
586 * A backend module @b SHOULD hide the current showing buffer from screen.
587 * If needed, cleanup a layer object resource.
589 tdm_error (*layer_unset_buffer)(tdm_layer *layer);
592 * @brief Set the zpos for a VIDEO layer object
593 * @param[in] layer A layer object
594 * @param[in] zpos z-order
595 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
596 * @see tdm_caps_layer, tdm_layer_capability
598 * A backend module doesn't need to implement this function if a backend
599 * module doesn't have VIDEO layers.\n
600 * This function is for VIDEO layers.
601 * GRAPHIC layers are non-changeable. The zpos of GRAPHIC layers starts
602 * from 0. If there are 4 GRAPHIC layers, The zpos SHOULD be 0, 1, 2, 3.\n
603 * But the zpos of VIDEO layer is changeable. And The zpos of VIDEO layers
604 * is less than GRAPHIC layers or more than GRAPHIC layers.
605 * ie, ..., -2, -1, 4, 5, ... (if 0 <= GRAPHIC layer's zpos < 4).
606 * The zpos of VIDEO layers is @b relative. It doesn't need to start
607 * from -1 or 4. Let's suppose that there are two VIDEO layers.
608 * One has -2 zpos. Another has -4 zpos. Then -2 Video layer is higher
609 * than -4 VIDEO layer.
611 tdm_error (*layer_set_video_pos)(tdm_layer *layer, int zpos);
614 * @brief Create a capture object of a layer object
615 * @param[in] output A output object
616 * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
617 * @return A capture object
618 * @see capture_destroy() function of #tdm_func_capture
620 * A backend module doesn't need to implement this function if a hardware
621 * doesn't have the capture device.
623 tdm_capture *(*layer_create_capture)(tdm_layer *layer, tdm_error *error);
625 void (*reserved1)(void);
626 void (*reserved2)(void);
627 void (*reserved3)(void);
628 void (*reserved4)(void);
629 void (*reserved5)(void);
630 void (*reserved6)(void);
631 void (*reserved7)(void);
632 void (*reserved8)(void);
636 * @brief The done handler of a pp object
638 typedef void (*tdm_pp_done_handler)(tdm_pp *pp, tbm_surface_h src,
639 tbm_surface_h dst, void *user_data);
642 * @brief The pp functions for a backend module.
644 typedef struct _tdm_func_pp {
646 * @brief Destroy a pp object
647 * @param[in] pp A pp object
648 * @see display_create_pp() function of #tdm_func_display
650 void (*pp_destroy)(tdm_pp *pp);
653 * @brief Set the geometry information to a pp object
654 * @param[in] pp A pp object
655 * @param[in] info The geometry information
656 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
657 * @see pp_commit() function of #tdm_func_pp
659 * A backend module would apply the geometry information when committed.
661 tdm_error (*pp_set_info)(tdm_pp *pp, tdm_info_pp *info);
664 * @brief Attach a source buffer and a destination buffer to a pp object
665 * @param[in] pp A pp object
666 * @param[in] src A source buffer
667 * @param[in] dst A destination buffer
668 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
669 * @see pp_set_info() function of #tdm_func_pp
670 * @see pp_commit() function of #tdm_func_pp
671 * @see pp_set_done_handler, tdm_pp_done_handler
673 * A backend module converts the image of a source buffer to a destination
674 * buffer when committed. The size/crop/transform information is set via
675 * #pp_set_info() of #tdm_func_pp. When done, a backend module @b SHOULD
676 * return the source/destination buffer via tdm_pp_done_handler.
678 tdm_error (*pp_attach)(tdm_pp *pp, tbm_surface_h src, tbm_surface_h dst);
681 * @brief Commit changes for a pp object
682 * @param[in] pp A pp object
683 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
685 tdm_error (*pp_commit)(tdm_pp *pp);
688 * @brief Set a user done handler to a pp object
689 * @param[in] pp A pp object
690 * @param[in] func A user done handler
691 * @param[in] user_data user data
692 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
694 * A backend module @b SHOULD call #tdm_pp_done_handler when converintg a image is done.
696 tdm_error (*pp_set_done_handler)(tdm_pp *pp, tdm_pp_done_handler func,
699 void (*reserved1)(void);
700 void (*reserved2)(void);
701 void (*reserved3)(void);
702 void (*reserved4)(void);
703 void (*reserved5)(void);
704 void (*reserved6)(void);
705 void (*reserved7)(void);
706 void (*reserved8)(void);
710 * @brief The done handler of a capture object
712 typedef void (*tdm_capture_done_handler)(tdm_capture *capture,
713 tbm_surface_h buffer, void *user_data);
716 * @brief The capture functions for a backend module.
718 typedef struct _tdm_func_capture {
720 * @brief Destroy a capture object
721 * @param[in] capture A capture object
722 * @see output_create_capture() function of #tdm_func_output
723 * @see layer_create_capture() function of #tdm_func_layer
725 void (*capture_destroy)(tdm_capture *capture);
728 * @brief Set the geometry information to a capture object
729 * @param[in] capture A capture object
730 * @param[in] info The geometry information
731 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
732 * @see capture_commit() function of #tdm_func_capture
734 * A backend module would apply the geometry information when committed.
736 tdm_error (*capture_set_info)(tdm_capture *capture, tdm_info_capture *info);
739 * @brief Attach a TDM buffer to a capture object
740 * @details When capture_commit() function is called, a backend module starts
741 * to dump a output or a layer to a TDM buffer.
742 * @param[in] capture A capture object
743 * @param[in] buffer A TDM buffer
744 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
745 * @see capture_set_info() function of #tdm_func_capture
746 * @see capture_commit() function of #tdm_func_capture
747 * @see capture_set_done_handler, tdm_capture_done_handler
749 * A backend module starts to dump a output or a layer to to a TDM buffer when
750 * committed. The size/crop/transform information is set via #capture_set_info()
751 * of #tdm_func_capture. When done, a backend module @b SHOULD return the TDM
752 * buffer via tdm_capture_done_handler.
754 tdm_error (*capture_attach)(tdm_capture *capture, tbm_surface_h buffer);
757 * @brief Commit changes for a capture object
758 * @param[in] capture A capture object
759 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
761 tdm_error (*capture_commit)(tdm_capture *capture);
764 * @brief Set a user done handler to a capture object
765 * @param[in] capture A capture object
766 * @param[in] func A user done handler
767 * @param[in] user_data user data
768 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
770 * A backend module @b SHOULD call #tdm_capture_done_handler when capture operation is done.
772 tdm_error (*capture_set_done_handler)(tdm_capture *capture,
773 tdm_capture_done_handler func, void *user_data);
775 void (*reserved1)(void);
776 void (*reserved2)(void);
777 void (*reserved3)(void);
778 void (*reserved4)(void);
779 void (*reserved5)(void);
780 void (*reserved6)(void);
781 void (*reserved7)(void);
782 void (*reserved8)(void);
785 #define TDM_BACKEND_MINOR_VERSION_MASK 0x0000FFFF
786 #define TDM_BACKEND_MAJOR_VERSION_MASK 0xFFFF0000
787 #define TDM_BACKEND_GET_ABI_MINOR(v) ((v) & TDM_BACKEND_MINOR_VERSION_MASK)
788 #define TDM_BACKEND_GET_ABI_MAJOR(v) (((v) & TDM_BACKEND_MAJOR_VERSION_MASK) >> 16)
792 * The ABI version of TDM backend module. It has a major and minor revision.
793 * Modules using lower minor revisions will work with TDM frontend of a higher
794 * minor revision. There is no compatibility between different major revisions.
795 * The minor revision mask is 0x0000FFFF and the major revision mask is 0xFFFF0000.
798 tdm_backend_module tdm_backend_module_data = {
801 TDM_BACKEND_SET_ABI_VERSION(1,1),
807 #define TDM_BACKEND_SET_ABI_VERSION(major, minor) \
808 (((major) << 16) & TDM_BACKEND_MAJOR_VERSION_MASK) | \
809 ((major) & TDM_BACKEND_MINOR_VERSION_MASK)
813 * This MACRO is deprecated since 1.2.0. Use TDM_BACKEND_SET_ABI_VERSION instead of this.
815 * Use #TDM_BACKEND_SET_ABI_VERSION macro instead of this macro.
817 #define TDM_BACKEND_ABI_VERSION TDM_BACKEND_SET_ABI_VERSION(1, 1)
820 * @brief The backend module information of the entry point to initialize a TDM
823 * A backend module @b SHOULD define the global data symbol of which name is
824 * @b "tdm_backend_module_data". TDM will read this symbol, @b "tdm_backend_module_data",
825 * at the initial time and call init() function of #tdm_backend_module.
827 typedef struct _tdm_backend_module {
828 const char *name; /**< The module name of a backend module */
829 const char *vendor; /**< The vendor name of a backend module */
830 unsigned long abi_version; /**< The ABI version of a backend module */
833 * @brief The init function of a backend module
834 * @param[in] dpy A display object
835 * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
836 * @return The backend module data
837 * @see tdm_backend_data
839 tdm_backend_data *(*init)(tdm_display *dpy, tdm_error *error);
842 * @brief The deinit function of a backend module
843 * @param[in] bdata The backend module data
845 void (*deinit)(tdm_backend_data *bdata);
846 } tdm_backend_module;
849 * @brief Register the backend display functions to a display
850 * @param[in] dpy A display object
851 * @param[in] func_display display functions
852 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
853 * @see tdm_backend_register_func_output, tdm_backend_register_func_layer
855 * A backend module @b SHOULD set the backend display functions at least.
858 tdm_backend_register_func_display(tdm_display *dpy,
859 tdm_func_display *func_display);
862 * @brief Register the backend output functions to a display
863 * @param[in] dpy A display object
864 * @param[in] func_output output functions
865 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
866 * @see tdm_backend_register_func_display, tdm_backend_register_func_layer
868 * A backend module @b SHOULD set the backend output functions at least.
871 tdm_backend_register_func_output(tdm_display *dpy,
872 tdm_func_output *func_output);
875 * @brief Register the backend layer functions to a display
876 * @param[in] dpy A display object
877 * @param[in] func_layer layer functions
878 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
879 * @see tdm_backend_register_func_display, tdm_backend_register_func_output
881 * A backend module @b SHOULD set the backend layer functions at least.
884 tdm_backend_register_func_layer(tdm_display *dpy, tdm_func_layer *func_layer);
887 * @brief Register the backend pp functions to a display
888 * @param[in] dpy A display object
889 * @param[in] func_pp pp functions
890 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
891 * @see tdm_backend_register_func_display, tdm_backend_register_func_capture
893 * A backend module doesn'tcan skip to register the backend pp functions
894 * if a hardware doesn't have the memory-to-memory converting device.
897 tdm_backend_register_func_pp(tdm_display *dpy, tdm_func_pp *func_pp);
900 * @brief Register the backend capture functions to a display
901 * @param[in] dpy A display object
902 * @param[in] func_capture capture functions
903 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
904 * @see tdm_backend_register_func_display, tdm_backend_register_func_pp
906 * A backend module can skip to register the backend capture functions
907 * if a hardware doesn't have the capture device.
910 tdm_backend_register_func_capture(tdm_display *dpy,
911 tdm_func_capture *func_capture);
914 * @brief Increase the ref_count of a TDM buffer
916 * TDM has its own buffer release mechanism to let an frontend user know when a TDM buffer
917 * becomes available for a next job. A TDM buffer can be used for TDM to show
918 * it on screen or to capture an output and a layer. After all operations,
919 * TDM will release it immediately when TDM doesn't need it any more.
920 * @param[in] buffer A TDM buffer
921 * @return A buffer itself. Otherwise, NULL.
922 * @see tdm_buffer_unref_backend
924 * - This function @b SHOULD be paired with #tdm_buffer_unref_backend. \n
925 * - For example, this function @b SHOULD be called in case that a backend module uses the TDM
926 * buffer of a layer for capturing a output or a layer to avoid tearing issue.
929 tdm_buffer_ref_backend(tbm_surface_h buffer);
932 * @brief Decrease the ref_count of a TDM buffer
933 * @param[in] buffer A TDM buffer
934 * @see tdm_buffer_ref_backend
937 tdm_buffer_unref_backend(tbm_surface_h buffer);
940 * @brief The destroy handler of a TDM buffer
941 * @param[in] buffer A TDM buffer
942 * @param[in] user_data user data
943 * @see tdm_buffer_add_destroy_handler, tdm_buffer_remove_destroy_handler
945 typedef void (*tdm_buffer_destroy_handler)(tbm_surface_h buffer,
949 * @brief Add a destroy handler to a TDM buffer
950 * @param[in] buffer A TDM buffer
951 * @param[in] func A destroy handler
952 * @param[in] user_data user data
953 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
954 * @see tdm_buffer_remove_destroy_handler
956 * A backend module can add a TDM buffer destroy handler to a TDM buffer which
957 * is a #tbm_surface_h object. When the TDM buffer is destroyed, this handler will
961 tdm_buffer_add_destroy_handler(tbm_surface_h buffer,
962 tdm_buffer_destroy_handler func, void *user_data);
965 * @brief Remove a destroy handler from a TDM buffer
966 * @param[in] buffer A TDM buffer
967 * @param[in] func A destroy handler
968 * @param[in] user_data user data
969 * @see tdm_buffer_add_destroy_handler
972 tdm_buffer_remove_destroy_handler(tbm_surface_h buffer,
973 tdm_buffer_destroy_handler func, void *user_data);
976 * @brief Add a FD handler for activity on the given file descriptor
977 * @param[in] dpy A display object
978 * @param[in] fd A file descriptor
979 * @param[in] mask to monitor FD
980 * @param[in] func A FD handler function
981 * @param[in] user_data user data
982 * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
983 * @return A FD event source
984 * @see #tdm_event_loop_source_fd_update, #tdm_event_loop_source_remove
986 tdm_event_loop_source*
987 tdm_event_loop_add_fd_handler(tdm_display *dpy, int fd, tdm_event_loop_mask mask,
988 tdm_event_loop_fd_handler func, void *user_data,
992 * @brief Update the mask of the given FD event source
993 * @param[in] source The given FD event source
994 * @param[in] mask to monitor FD
995 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
998 tdm_event_loop_source_fd_update(tdm_event_loop_source *source, tdm_event_loop_mask mask);
1001 * @brief Add a timer handler
1002 * @param[in] dpy A display object
1003 * @param[in] func A timer handler function
1004 * @param[in] user_data user data
1005 * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
1006 * @return A timer event source
1007 * @see #tdm_event_loop_source_timer_update, #tdm_event_loop_source_remove
1009 tdm_event_loop_source*
1010 tdm_event_loop_add_timer_handler(tdm_display *dpy, tdm_event_loop_timer_handler func,
1011 void *user_data, tdm_error *error);
1014 * @brief Update the millisecond delay time of the given timer event source.
1015 * @param[in] source The given timer event source
1016 * @param[in] ms_delay The millisecond delay time. zero "0" disarms the timer.
1017 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
1020 tdm_event_loop_source_timer_update(tdm_event_loop_source *source, unsigned int ms_delay);
1023 * @brief Remove the given event source
1024 * @param[in] source The given event source
1025 * @see #tdm_event_loop_add_fd_handler, #tdm_event_loop_add_timer_handler
1028 tdm_event_loop_source_remove(tdm_event_loop_source *source);
1034 #endif /* _TDM_BACKEND_H_ */