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_display
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_display
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_display. 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 Get the file descriptor for the memory-management framework of a backend module
292 * @param[in] bdata The backend module data
293 * @param[out] fd The fd of a backend module
294 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
295 * @see display_handle_events() function of #tdm_func_display
296 * This buffer fd will be passed to tbm_bufmgr_init.
298 tdm_error (*display_get_buffer_fd)(tdm_backend_data *bdata, int *fd);
301 * @brief Handle the events which happens on the fd of a backend module
302 * @param[in] bdata The backend module data
303 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
305 tdm_error (*display_handle_events)(tdm_backend_data *bdata);
308 * @brief Create a pp object of a backend module
309 * @param[in] bdata The backend module data
310 * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
311 * @return A pp object
312 * @see pp_destroy() function of #tdm_func_pp
314 * A backend module doesn't need to implement this function if a hardware
315 * doesn't have the memory-to-memory converting device.
317 tdm_pp *(*display_create_pp)(tdm_backend_data *bdata, tdm_error *error);
319 void (*reserved1)(void);
320 void (*reserved2)(void);
321 void (*reserved3)(void);
322 void (*reserved4)(void);
323 void (*reserved5)(void);
324 void (*reserved6)(void);
325 void (*reserved7)(void);
326 void (*reserved8)(void);
330 * @brief The output functions for a backend module.
332 typedef struct _tdm_func_output {
334 * @brief Get the capabilities of a output object
335 * @param[in] output A output object
336 * @param[out] caps The capabilities of a output object
337 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
339 * A backend module @b SHOULD implement this function. TDM calls this function
340 * not only at the initial time, but also at the update time when new output
342 * #tdm_caps_output contains connection status, modes, avaiable properties,
343 * size restriction information, etc.
345 tdm_error (*output_get_capability)(tdm_output *output, tdm_caps_output *caps);
348 * @brief Get a layer array of a output object
349 * @param[in] output A output object
350 * @param[out] count The count of layers
351 * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
352 * @return A layer array which is @b newly-allocated
354 * A backend module @b SHOULD implement this function. TDM calls this function
355 * not only at the initial time, but also at the update time when new output
357 * A backend module @b SHOULD return the @b newly-allocated array which contains
358 * "tdm_layer*" data. It will be freed in frontend.
360 tdm_layer **(*output_get_layers)(tdm_output *output, int *count,
364 * @brief Set the property which has a given id
365 * @param[in] output A output object
366 * @param[in] id The property id
367 * @param[in] value The value
368 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
370 tdm_error (*output_set_property)(tdm_output *output, unsigned int id,
374 * @brief Get the property which has a given id
375 * @param[in] output A output object
376 * @param[in] id The property id
377 * @param[out] value The value
378 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
380 tdm_error (*output_get_property)(tdm_output *output, unsigned int id,
384 * @brief Wait for VBLANK
385 * @param[in] output A output object
386 * @param[in] interval vblank interval
387 * @param[in] sync 0: asynchronous, 1:synchronous
388 * @param[in] user_data The user data
389 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
390 * @see output_set_vblank_handler, tdm_output_vblank_handler
392 * A backend module @b SHOULD call a user vblank handler after interval vblanks.
394 tdm_error (*output_wait_vblank)(tdm_output *output, int interval, int sync,
398 * @brief Set a user vblank handler
399 * @param[in] output A output object
400 * @param[in] func A user vblank handler
401 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
403 tdm_error (*output_set_vblank_handler)(tdm_output *output,
404 tdm_output_vblank_handler func);
407 * @brief Commit changes for a output object
408 * @param[in] output A output object
409 * @param[in] sync 0: asynchronous, 1:synchronous
410 * @param[in] user_data The user data
411 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
412 * @see output_set_commit_handler, tdm_output_commit_handler
414 * A backend module @b SHOULD call a user commit handler after all change of
415 * a output object are applied.
417 tdm_error (*output_commit)(tdm_output *output, int sync, void *user_data);
420 * @brief Set a user commit handler
421 * @param[in] output A output object
422 * @param[in] func A user commit handler
423 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
425 tdm_error (*output_set_commit_handler)(tdm_output *output,
426 tdm_output_commit_handler func);
429 * @brief Set DPMS of a output object
430 * @param[in] output A output object
431 * @param[in] dpms_value DPMS value
432 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
434 tdm_error (*output_set_dpms)(tdm_output *output, tdm_output_dpms dpms_value);
437 * @brief Get DPMS of a output object
438 * @param[in] output A output object
439 * @param[out] dpms_value DPMS value
440 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
442 tdm_error (*output_get_dpms)(tdm_output *output, tdm_output_dpms *dpms_value);
445 * @brief Set one of available modes of a output object
446 * @param[in] output A output object
447 * @param[in] mode A output mode
448 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
450 tdm_error (*output_set_mode)(tdm_output *output, const tdm_output_mode *mode);
453 * @brief Get the mode of a output object
454 * @param[in] output A output object
455 * @param[out] mode A output mode
456 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
458 tdm_error (*output_get_mode)(tdm_output *output, const tdm_output_mode **mode);
461 * @brief Create a capture object of a output object
462 * @param[in] output A output object
463 * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
464 * @return A capture object
465 * @see capture_destroy() function of #tdm_func_capture
467 * A backend module doesn't need to implement this function if a hardware
468 * doesn't have the capture device.
470 tdm_capture *(*output_create_capture)(tdm_output *output, tdm_error *error);
472 void (*reserved1)(void);
473 void (*reserved2)(void);
474 void (*reserved3)(void);
475 void (*reserved4)(void);
476 void (*reserved5)(void);
477 void (*reserved6)(void);
478 void (*reserved7)(void);
479 void (*reserved8)(void);
483 * @brief The layer functions for a backend module.
485 typedef struct _tdm_func_layer {
487 * @brief Get the capabilities of a layer object
488 * @param[in] layer A layer object
489 * @param[out] caps The capabilities of a layer object
490 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
492 * A backend module @b SHOULD implement this function. TDM calls this function
493 * not only at the initial time, but also at the update time when new output
495 * #tdm_caps_layer contains avaiable formats/properties, zpos information, etc.
497 tdm_error (*layer_get_capability)(tdm_layer *layer, tdm_caps_layer *caps);
500 * @brief Set the property which has a given id.
501 * @param[in] layer A layer object
502 * @param[in] id The property id
503 * @param[in] value The value
504 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
506 tdm_error (*layer_set_property)(tdm_layer *layer, unsigned int id,
510 * @brief Get the property which has a given id.
511 * @param[in] layer A layer object
512 * @param[in] id The property id
513 * @param[out] value The value
514 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
516 tdm_error (*layer_get_property)(tdm_layer *layer, unsigned int id,
520 * @brief Set the geometry information to a layer object
521 * @param[in] layer A layer object
522 * @param[in] info The geometry information
523 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
524 * @see output_commit() function of #tdm_func_display
526 * A backend module would apply the geometry information when the output object
527 * of a layer object is committed.
529 tdm_error (*layer_set_info)(tdm_layer *layer, tdm_info_layer *info);
532 * @brief Get the geometry information to a layer object
533 * @param[in] layer A layer object
534 * @param[out] info The geometry information
535 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
537 tdm_error (*layer_get_info)(tdm_layer *layer, tdm_info_layer *info);
540 * @brief Set a TDM buffer to a layer object
541 * @param[in] layer A layer object
542 * @param[in] buffer A TDM buffer
543 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
544 * @see output_commit() function of #tdm_func_display
546 * A backend module would apply a TDM buffer when the output object
547 * of a layer object is committed.
549 tdm_error (*layer_set_buffer)(tdm_layer *layer, tbm_surface_h buffer);
552 * @brief Unset a TDM buffer from a layer object
553 * @param[in] layer A layer object
554 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
556 * A backend module @b SHOULD hide the current showing buffer from screen.
557 * If needed, cleanup a layer object resource.
559 tdm_error (*layer_unset_buffer)(tdm_layer *layer);
562 * @brief Set the zpos for a VIDEO layer object
563 * @param[in] layer A layer object
564 * @param[in] zpos z-order
565 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
566 * @see tdm_caps_layer, tdm_layer_capability
568 * A backend module doesn't need to implement this function if a backend
569 * module doesn't have VIDEO layers.\n
570 * This function is for VIDEO layers.
571 * GRAPHIC layers are non-changeable. The zpos of GRAPHIC layers starts
572 * from 0. If there are 4 GRAPHIC layers, The zpos SHOULD be 0, 1, 2, 3.\n
573 * But the zpos of VIDEO layer is changeable. And The zpos of VIDEO layers
574 * is less than GRAPHIC layers or more than GRAPHIC layers.
575 * ie, ..., -2, -1, 4, 5, ... (if 0 <= GRAPHIC layer's zpos < 4).
576 * The zpos of VIDEO layers is @b relative. It doesn't need to start
577 * from -1 or 4. Let's suppose that there are two VIDEO layers.
578 * One has -2 zpos. Another has -4 zpos. Then -2 Video layer is higher
579 * than -4 VIDEO layer.
581 tdm_error (*layer_set_video_pos)(tdm_layer *layer, int zpos);
584 * @brief Create a capture object of a layer object
585 * @param[in] output A output object
586 * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
587 * @return A capture object
588 * @see capture_destroy() function of #tdm_func_capture
590 * A backend module doesn't need to implement this function if a hardware
591 * doesn't have the capture device.
593 tdm_capture *(*layer_create_capture)(tdm_layer *layer, tdm_error *error);
595 void (*reserved1)(void);
596 void (*reserved2)(void);
597 void (*reserved3)(void);
598 void (*reserved4)(void);
599 void (*reserved5)(void);
600 void (*reserved6)(void);
601 void (*reserved7)(void);
602 void (*reserved8)(void);
606 * @brief The done handler of a pp object
608 typedef void (*tdm_pp_done_handler)(tdm_pp *pp, tbm_surface_h src,
609 tbm_surface_h dst, void *user_data);
612 * @brief The pp functions for a backend module.
614 typedef struct _tdm_func_pp {
616 * @brief Destroy a pp object
617 * @param[in] pp A pp object
618 * @see display_create_pp() function of #tdm_func_display
620 void (*pp_destroy)(tdm_pp *pp);
623 * @brief Set the geometry information to a pp object
624 * @param[in] pp A pp object
625 * @param[in] info The geometry information
626 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
627 * @see pp_commit() function of #tdm_func_pp
629 * A backend module would apply the geometry information when committed.
631 tdm_error (*pp_set_info)(tdm_pp *pp, tdm_info_pp *info);
634 * @brief Attach a source buffer and a destination buffer to a pp object
635 * @param[in] pp A pp object
636 * @param[in] src A source buffer
637 * @param[in] dst A destination buffer
638 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
639 * @see pp_set_info() function of #tdm_func_pp
640 * @see pp_commit() function of #tdm_func_pp
641 * @see pp_set_done_handler, tdm_pp_done_handler
643 * A backend module converts the image of a source buffer to a destination
644 * buffer when committed. The size/crop/transform information is set via
645 * #pp_set_info() of #tdm_func_pp. When done, a backend module @b SHOULD
646 * return the source/destination buffer via tdm_pp_done_handler.
648 tdm_error (*pp_attach)(tdm_pp *pp, tbm_surface_h src, tbm_surface_h dst);
651 * @brief Commit changes for a pp object
652 * @param[in] pp A pp object
653 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
655 tdm_error (*pp_commit)(tdm_pp *pp);
658 * @brief Set a user done handler to a pp object
659 * @param[in] pp A pp object
660 * @param[in] func A user done handler
661 * @param[in] user_data user data
662 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
664 * A backend module @b SHOULD call #tdm_pp_done_handler when converintg a image is done.
666 tdm_error (*pp_set_done_handler)(tdm_pp *pp, tdm_pp_done_handler func,
669 void (*reserved1)(void);
670 void (*reserved2)(void);
671 void (*reserved3)(void);
672 void (*reserved4)(void);
673 void (*reserved5)(void);
674 void (*reserved6)(void);
675 void (*reserved7)(void);
676 void (*reserved8)(void);
680 * @brief The done handler of a capture object
682 typedef void (*tdm_capture_done_handler)(tdm_capture *capture,
683 tbm_surface_h buffer, void *user_data);
686 * @brief The capture functions for a backend module.
688 typedef struct _tdm_func_capture {
690 * @brief Destroy a capture object
691 * @param[in] capture A capture object
692 * @see output_create_capture() function of #tdm_func_display
693 * @see layer_create_capture() function of #tdm_func_display
695 void (*capture_destroy)(tdm_capture *capture);
698 * @brief Set the geometry information to a capture object
699 * @param[in] capture A capture object
700 * @param[in] info The geometry information
701 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
702 * @see capture_commit() function of #tdm_func_capture
704 * A backend module would apply the geometry information when committed.
706 tdm_error (*capture_set_info)(tdm_capture *capture, tdm_info_capture *info);
709 * @brief Attach a TDM buffer to a capture object
710 * @details When capture_commit() function is called, a backend module dumps
711 * a output or a layer to a TDM buffer.
712 * @param[in] capture A capture object
713 * @param[in] buffer A TDM buffer
714 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
715 * @see capture_set_info() function of #tdm_func_capture
716 * @see capture_commit() function of #tdm_func_capture
717 * @see capture_set_done_handler, tdm_capture_done_handler
719 * A backend module dumps a output or a layer to to a TDM buffer when
720 * committed. The size/crop/transform information is set via #capture_set_info()
721 * of #tdm_func_capture. When done, a backend module @b SHOULD return the TDM
722 * buffer via tdm_capture_done_handler.
724 tdm_error (*capture_attach)(tdm_capture *capture, tbm_surface_h buffer);
727 * @brief Commit changes for a capture object
728 * @param[in] capture A capture object
729 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
731 tdm_error (*capture_commit)(tdm_capture *capture);
734 * @brief Set a user done handler to a capture object
735 * @param[in] capture A capture object
736 * @param[in] func A user done handler
737 * @param[in] user_data user data
738 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
740 * A backend module @b SHOULD call #tdm_capture_done_handler when capture operation is done.
742 tdm_error (*capture_set_done_handler)(tdm_capture *capture,
743 tdm_capture_done_handler func, void *user_data);
745 void (*reserved1)(void);
746 void (*reserved2)(void);
747 void (*reserved3)(void);
748 void (*reserved4)(void);
749 void (*reserved5)(void);
750 void (*reserved6)(void);
751 void (*reserved7)(void);
752 void (*reserved8)(void);
756 * ABI versions. Each version has a major and minor revision. Modules
757 * using lower minor revisions must work with servers of a higher minor
758 * revision. There is no compatibility between different major revisions.
759 * Whenever the ABI_ANSIC_VERSION is changed, the others must also be
760 * changed. The minor revision mask is 0x0000FFFF and the major revision
761 * mask is 0xFFFF0000.
763 #define TDM_BACKEND_MINOR_VERSION_MASK 0x0000FFFF
764 #define TDM_BACKEND_MAJOR_VERSION_MASK 0xFFFF0000
765 #define TDM_BACKEND_GET_ABI_MINOR(v) ((v) & TDM_BACKEND_MINOR_VERSION_MASK)
766 #define TDM_BACKEND_GET_ABI_MAJOR(v) (((v) & TDM_BACKEND_MAJOR_VERSION_MASK) >> 16)
768 #define SET_TDM_BACKEND_ABI_VERSION(major, minor) \
769 (((major) << 16) & TDM_BACKEND_MAJOR_VERSION_MASK) | \
770 ((major) & TDM_BACKEND_MINOR_VERSION_MASK)
771 #define TDM_BACKEND_ABI_VERSION SET_TDM_BACKEND_ABI_VERSION(1, 1)
774 * @brief The backend module information of the entry point to initialize a TDM
777 * A backend module @b SHOULD define the global data symbol of which name is
778 * @b "tdm_backend_module_data". TDM will read this symbol, @b "tdm_backend_module_data",
779 * at the initial time and call init() function of #tdm_backend_module.
781 typedef struct _tdm_backend_module {
782 const char *name; /**< The module name of a backend module */
783 const char *vendor; /**< The vendor name of a backend module */
784 unsigned long abi_version; /**< The ABI version of a backend module */
787 * @brief The init function of a backend module
788 * @param[in] dpy A display object
789 * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
790 * @return The backend module data
791 * @see tdm_backend_data
793 tdm_backend_data *(*init)(tdm_display *dpy, tdm_error *error);
796 * @brief The deinit function of a backend module
797 * @param[in] bdata The backend module data
799 void (*deinit)(tdm_backend_data *bdata);
800 } tdm_backend_module;
803 * @brief Register the backend display functions to a display
804 * @param[in] dpy A display object
805 * @param[in] func_display display functions
806 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
807 * @see tdm_backend_register_func_output, tdm_backend_register_func_layer
809 * A backend module @b SHOULD set the backend display functions at least.
812 tdm_backend_register_func_display(tdm_display *dpy,
813 tdm_func_display *func_display);
816 * @brief Register the backend output functions to a display
817 * @param[in] dpy A display object
818 * @param[in] func_output output functions
819 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
820 * @see tdm_backend_register_func_display, tdm_backend_register_func_layer
822 * A backend module @b SHOULD set the backend output functions at least.
825 tdm_backend_register_func_output(tdm_display *dpy,
826 tdm_func_output *func_output);
829 * @brief Register the backend layer functions to a display
830 * @param[in] dpy A display object
831 * @param[in] func_layer layer functions
832 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
833 * @see tdm_backend_register_func_display, tdm_backend_register_func_output
835 * A backend module @b SHOULD set the backend layer functions at least.
838 tdm_backend_register_func_layer(tdm_display *dpy, tdm_func_layer *func_layer);
841 * @brief Register the backend pp functions to a display
842 * @param[in] dpy A display object
843 * @param[in] func_pp pp functions
844 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
845 * @see tdm_backend_register_func_display, tdm_backend_register_func_capture
847 * A backend module doesn'tcan skip to register the backend pp functions
848 * if a hardware doesn't have the memory-to-memory converting device.
851 tdm_backend_register_func_pp(tdm_display *dpy, tdm_func_pp *func_pp);
854 * @brief Register the backend capture functions to a display
855 * @param[in] dpy A display object
856 * @param[in] func_capture capture functions
857 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
858 * @see tdm_backend_register_func_display, tdm_backend_register_func_pp
860 * A backend module can skip to register the backend capture functions
861 * if a hardware doesn't have the capture device.
864 tdm_backend_register_func_capture(tdm_display *dpy,
865 tdm_func_capture *func_capture);
868 * @brief Increase the ref_count of a TDM buffer
870 * TDM has its own buffer release mechanism to let an frontend user know when a TDM buffer
871 * becomes available for a next job. A TDM buffer can be used for TDM to show
872 * it on screen or to capture an output and a layer. After all operations,
873 * TDM will release it immediately when TDM doesn't need it any more.
874 * @param[in] buffer A TDM buffer
875 * @return A buffer itself. Otherwise, NULL.
876 * @see tdm_buffer_unref_backend
878 * - This function @b SHOULD be paired with #tdm_buffer_unref_backend. \n
879 * - For example, this function @b SHOULD be called in case that a backend module uses the TDM
880 * buffer of a layer for capturing a output or a layer to avoid tearing issue.
883 tdm_buffer_ref_backend(tbm_surface_h buffer);
886 * @brief Decrease the ref_count of a TDM buffer
887 * @param[in] buffer A TDM buffer
888 * @see tdm_buffer_ref_backend
891 tdm_buffer_unref_backend(tbm_surface_h buffer);
894 * @brief The destroy handler of a TDM buffer
895 * @param[in] buffer A TDM buffer
896 * @param[in] user_data user data
897 * @see tdm_buffer_add_destroy_handler, tdm_buffer_remove_destroy_handler
899 typedef void (*tdm_buffer_destroy_handler)(tbm_surface_h buffer,
903 * @brief Add a destroy handler to a TDM buffer
904 * @param[in] buffer A TDM buffer
905 * @param[in] func A destroy handler
906 * @param[in] user_data user data
907 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
908 * @see tdm_buffer_remove_destroy_handler
910 * A backend module can add a TDM buffer destroy handler to a TDM buffer which
911 * is a #tbm_surface_h object. When the TDM buffer is destroyed, this handler will
915 tdm_buffer_add_destroy_handler(tbm_surface_h buffer,
916 tdm_buffer_destroy_handler func, void *user_data);
919 * @brief Remove a destroy handler from a TDM buffer
920 * @param[in] buffer A TDM buffer
921 * @param[in] func A destroy handler
922 * @param[in] user_data user data
923 * @see tdm_buffer_add_destroy_handler
926 tdm_buffer_remove_destroy_handler(tbm_surface_h buffer,
927 tdm_buffer_destroy_handler func, void *user_data);
934 #endif /* _TDM_BACKEND_H_ */