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
71 int max_layer_count; /**< The maximum layer count. -1 means "not defined" */
75 * @brief The capabilities structure of a output object
76 * @see The output_get_capability() function of #tdm_func_display
78 typedef struct _tdm_caps_output
80 char maker[TDM_NAME_LEN]; /**< The output maker */
81 char model[TDM_NAME_LEN]; /**< The output model */
82 char name[TDM_NAME_LEN]; /**< The output name */
84 tdm_output_conn_status status; /**< The connection status */
85 tdm_output_type type; /**< The connection type */
86 unsigned int type_id; /**< The connection type id */
88 unsigned int mode_count; /**< The count of available modes */
89 tdm_output_mode *modes; /**< The @b newly-allocated array of modes. will be freed in frontend. */
91 unsigned int prop_count; /**< The count of available properties */
92 tdm_prop *props; /**< The @b newly-allocated array of properties. will be freed in frontend. */
94 unsigned int mmWidth; /**< The physical width (milimeter) */
95 unsigned int mmHeight; /**< The physical height (milimeter) */
96 unsigned int subpixel; /**< The subpixel */
98 int min_w; /**< The minimun width. -1 means "not defined" */
99 int min_h; /**< The minimun height. -1 means "not defined" */
100 int max_w; /**< The maximum width. -1 means "not defined" */
101 int max_h; /**< The maximum height. -1 means "not defined" */
102 int preferred_align; /**< The prefered align. -1 means "not defined" */
106 * @brief The capabilities structure of a layer object
107 * @see The layer_get_capability() function of #tdm_func_display
109 typedef struct _tdm_caps_layer
111 tdm_layer_capability capabilities; /**< The capabilities of layer */
115 * GRAPHIC layers are non-changeable. The zpos of GRAPHIC layers starts
116 * from 0. If there are 4 GRAPHIC layers, The zpos SHOULD be 0, 1, 2, 3.\n
117 * But the zpos of VIDEO layer is changeable by layer_set_video_pos() function
118 * of #tdm_func_display. And The zpos of VIDEO layers is less than GRAPHIC
119 * layers or more than GRAPHIC layers.
120 * ie, ..., -2, -1, 4, 5, ... (if 0 <= GRAPHIC layer's zpos < 4).
121 * The zpos of VIDEO layers is @b relative. It doesn't need to start
122 * from -1 or 4. Let's suppose that there are two VIDEO layers.
123 * One has -2 zpos. Another has -4 zpos. Then -2 Video layer is higher
124 * than -4 VIDEO layer.
128 unsigned int format_count; /**< The count of available formats */
129 tbm_format *formats; /**< The @b newly-allocated array of formats. will be freed in frontend. */
131 unsigned int prop_count; /**< The count of available properties */
132 tdm_prop *props; /**< The @b newly-allocated array of properties. will be freed in frontend. */
136 * @brief The capabilities structure of a pp object
137 * @see The display_get_pp_capability() function of #tdm_func_display
139 typedef struct _tdm_caps_pp
141 tdm_pp_capability capabilities; /**< The capabilities of pp */
143 unsigned int format_count; /**< The count of available formats */
144 tbm_format *formats; /**< The @b newly-allocated array. will be freed in frontend. */
146 int min_w; /**< The minimun width. -1 means "not defined" */
147 int min_h; /**< The minimun height. -1 means "not defined" */
148 int max_w; /**< The maximum width. -1 means "not defined" */
149 int max_h; /**< The maximum height. -1 means "not defined" */
150 int preferred_align; /**< The prefered align. -1 means "not defined" */
154 * @brief The capabilities structure of a capture object
155 * @see The display_get_capture_capability() function of #tdm_func_display
157 typedef struct _tdm_caps_capture
159 tdm_capture_capability capabilities; /**< The capabilities of capture */
161 unsigned int format_count; /**< The count of available formats */
162 tbm_format *formats; /**< The @b newly-allocated array of formats. will be freed in frontend. */
164 int min_w; /**< The minimun width. -1 means "not defined" */
165 int min_h; /**< The minimun height. -1 means "not defined" */
166 int max_w; /**< The maximum width. -1 means "not defined" */
167 int max_h; /**< The maximum height. -1 means "not defined" */
168 int preferred_align; /**< The prefered align. -1 means "not defined" */
172 * @brief The display functions for a backend module.
174 typedef struct _tdm_func_display
177 * @brief Get the display capabilities of a backend module
178 * @param[in] bdata The backend module data
179 * @param[out] caps The display capabilities of a backend module
180 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
182 * A backend module @b SHOULD implement this function. TDM calls this function
183 * not only at the initial time, but also at the update time when new output
185 * If a hardware has the restriction of the number of max usable layer count,
186 * a backend module can set the max count to max_layer_count of #tdm_caps_display
187 * structure. Otherwise, set -1.
189 tdm_error (*display_get_capabilitiy)(tdm_backend_data *bdata, tdm_caps_display *caps);
192 * @brief Get the pp capabilities of a backend module
193 * @param[in] bdata The backend module data
194 * @param[out] caps The pp capabilities of a backend module
195 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
196 * @see tdm_backend_register_func_pp
198 * TDM calls this function not only at the initial time, but also at the update
199 * time when new output is connected.\n
200 * A backend module doesn't need to implement this function if a hardware
201 * doesn't have the memory-to-memory converting device. Otherwise, a backend module
202 * @b SHOULD fill the #tdm_caps_pp data. #tdm_caps_pp contains the hardware
203 * restriction information which a converting device can handle. ie, format, size, etc.
205 tdm_error (*display_get_pp_capability)(tdm_backend_data *bdata, tdm_caps_pp *caps);
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, tdm_caps_capture *caps);
224 * @brief Get a output array of a backend module
225 * @param[in] bdata The backend module data
226 * @param[out] count The count of outputs
227 * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
228 * @return A output array which is @b newly-allocated
229 * @see tdm_backend_register_func_capture
231 * A backend module @b SHOULD implement this function. TDM calls this function
232 * not only at the initial time, but also at the update time when new output
234 * A backend module @b SHOULD return the @b newly-allocated array which contains
235 * "tdm_output*" data. It will be freed in frontend.
239 drm_display_get_outputs(tdm_backend_data *bdata, int *count, tdm_error *error)
241 tdm_drm_data *drm_data = bdata;
242 tdm_drm_output_data *output_data = NULL;
243 tdm_output **outputs;
247 LIST_FOR_EACH_ENTRY(output_data, &drm_data->output_list, link)
252 if (error) *error = TDM_ERROR_NONE;
256 // will be freed in frontend
257 outputs = calloc(*count, sizeof(tdm_drm_output_data*));
261 if (error) *error = TDM_ERROR_OUT_OF_MEMORY;
266 LIST_FOR_EACH_ENTRY(output_data, &drm_data->output_list, link)
267 outputs[i++] = output_data;
269 if (error) *error = TDM_ERROR_NONE;
275 tdm_output **(*display_get_outputs)(tdm_backend_data *bdata, int *count, tdm_error *error);
278 * @brief Get the file descriptor of a backend module
279 * @param[in] bdata The backend module data
280 * @param[out] fd The fd of a backend module
281 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
282 * @see display_handle_events() function of #tdm_func_display
284 * A backend module can return epoll's fd which is watching the backend device one more fds.
286 tdm_error (*display_get_fd)(tdm_backend_data *bdata, int *fd);
289 * @brief Handle the events which happens on the fd of a backend module
290 * @param[in] bdata The backend module data
291 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
293 tdm_error (*display_handle_events)(tdm_backend_data *bdata);
296 * @brief Create a pp object of a backend module
297 * @param[in] bdata The backend module data
298 * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
299 * @return A pp object
300 * @see pp_destroy() function of #tdm_func_pp
302 * A backend module doesn't need to implement this function if a hardware
303 * doesn't have the memory-to-memory converting device.
305 tdm_pp* (*display_create_pp)(tdm_backend_data *bdata, tdm_error *error);
307 void (*reserved1)(void);
308 void (*reserved2)(void);
309 void (*reserved3)(void);
310 void (*reserved4)(void);
311 void (*reserved5)(void);
312 void (*reserved6)(void);
313 void (*reserved7)(void);
314 void (*reserved8)(void);
318 * @brief The output functions for a backend module.
320 typedef struct _tdm_func_output
323 * @brief Get the capabilities of a output object
324 * @param[in] output A output object
325 * @param[out] caps The capabilities of a output object
326 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
328 * A backend module @b SHOULD implement this function. TDM calls this function
329 * not only at the initial time, but also at the update time when new output
331 * #tdm_caps_output contains connection status, modes, avaiable properties,
332 * size restriction information, etc.
334 tdm_error (*output_get_capability)(tdm_output *output, tdm_caps_output *caps);
337 * @brief Get a layer array of a output object
338 * @param[in] output A output object
339 * @param[out] count The count of layers
340 * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
341 * @return A layer array which is @b newly-allocated
343 * A backend module @b SHOULD implement this function. TDM calls this function
344 * not only at the initial time, but also at the update time when new output
346 * A backend module @b SHOULD return the @b newly-allocated array which contains
347 * "tdm_layer*" data. It will be freed in frontend.
349 tdm_layer **(*output_get_layers)(tdm_output *output, int *count, tdm_error *error);
352 * @brief Set the property which has a given id
353 * @param[in] output A output object
354 * @param[in] id The property id
355 * @param[in] value The value
356 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
358 tdm_error (*output_set_property)(tdm_output *output, unsigned int id, tdm_value value);
361 * @brief Get the property which has a given id
362 * @param[in] output A output object
363 * @param[in] id The property id
364 * @param[out] value The value
365 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
367 tdm_error (*output_get_property)(tdm_output *output, unsigned int id, tdm_value *value);
370 * @brief Wait for VBLANK
371 * @param[in] output A output object
372 * @param[in] interval vblank interval
373 * @param[in] sync 0: asynchronous, 1:synchronous
374 * @param[in] user_data The user data
375 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
376 * @see output_set_vblank_handler, tdm_output_vblank_handler
378 * A backend module @b SHOULD call a user vblank handler after interval vblanks.
380 tdm_error (*output_wait_vblank)(tdm_output *output, int interval, int sync, void *user_data);
383 * @brief Set a user vblank handler
384 * @param[in] output A output object
385 * @param[in] func A user vblank handler
386 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
388 tdm_error (*output_set_vblank_handler)(tdm_output *output, tdm_output_vblank_handler func);
391 * @brief Commit changes for a output object
392 * @param[in] output A output object
393 * @param[in] sync 0: asynchronous, 1:synchronous
394 * @param[in] user_data The user data
395 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
396 * @see output_set_commit_handler, tdm_output_commit_handler
398 * A backend module @b SHOULD call a user commit handler after all change of
399 * a output object are applied.
401 tdm_error (*output_commit)(tdm_output *output, int sync, void *user_data);
404 * @brief Set a user commit handler
405 * @param[in] output A output object
406 * @param[in] func A user commit handler
407 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
409 tdm_error (*output_set_commit_handler)(tdm_output *output, tdm_output_commit_handler func);
412 * @brief Set DPMS of a output object
413 * @param[in] output A output object
414 * @param[in] dpms_value DPMS value
415 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
417 tdm_error (*output_set_dpms)(tdm_output *output, tdm_output_dpms dpms_value);
420 * @brief Get DPMS of a output object
421 * @param[in] output A output object
422 * @param[out] dpms_value DPMS value
423 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
425 tdm_error (*output_get_dpms)(tdm_output *output, tdm_output_dpms *dpms_value);
428 * @brief Set one of available modes of a output object
429 * @param[in] output A output object
430 * @param[in] mode A output mode
431 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
433 tdm_error (*output_set_mode)(tdm_output *output, const tdm_output_mode *mode);
436 * @brief Get the mode of a output object
437 * @param[in] output A output object
438 * @param[out] mode A output mode
439 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
441 tdm_error (*output_get_mode)(tdm_output *output, const tdm_output_mode **mode);
444 * @brief Create a capture object of a output object
445 * @param[in] output A output object
446 * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
447 * @return A capture object
448 * @see capture_destroy() function of #tdm_func_capture
450 * A backend module doesn't need to implement this function if a hardware
451 * doesn't have the capture device.
453 tdm_capture *(*output_create_capture)(tdm_output *output, tdm_error *error);
455 void (*reserved1)(void);
456 void (*reserved2)(void);
457 void (*reserved3)(void);
458 void (*reserved4)(void);
459 void (*reserved5)(void);
460 void (*reserved6)(void);
461 void (*reserved7)(void);
462 void (*reserved8)(void);
466 * @brief The layer functions for a backend module.
468 typedef struct _tdm_func_layer
471 * @brief Get the capabilities of a layer object
472 * @param[in] layer A layer object
473 * @param[out] caps The capabilities of a layer object
474 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
476 * A backend module @b SHOULD implement this function. TDM calls this function
477 * not only at the initial time, but also at the update time when new output
479 * #tdm_caps_layer contains avaiable formats/properties, zpos information, etc.
481 tdm_error (*layer_get_capability)(tdm_layer *layer, tdm_caps_layer *caps);
484 * @brief Set the property which has a given id.
485 * @param[in] layer A layer object
486 * @param[in] id The property id
487 * @param[in] value The value
488 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
490 tdm_error (*layer_set_property)(tdm_layer *layer, unsigned int id, tdm_value value);
493 * @brief Get the property which has a given id.
494 * @param[in] layer A layer object
495 * @param[in] id The property id
496 * @param[out] value The value
497 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
499 tdm_error (*layer_get_property)(tdm_layer *layer, unsigned int id, tdm_value *value);
502 * @brief Set the geometry information to a layer object
503 * @param[in] layer A layer object
504 * @param[in] info The geometry information
505 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
506 * @see output_commit() function of #tdm_func_display
508 * A backend module would apply the geometry information when the output object
509 * of a layer object is committed.
511 tdm_error (*layer_set_info)(tdm_layer *layer, tdm_info_layer *info);
514 * @brief Get the geometry information to a layer object
515 * @param[in] layer A layer object
516 * @param[out] info The geometry information
517 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
519 tdm_error (*layer_get_info)(tdm_layer *layer, tdm_info_layer *info);
522 * @brief Set a TDM buffer to a layer object
523 * @param[in] layer A layer object
524 * @param[in] buffer A TDM buffer
525 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
526 * @see output_commit() function of #tdm_func_display
528 * A backend module would apply a TDM buffer when the output object
529 * of a layer object is committed.
531 tdm_error (*layer_set_buffer)(tdm_layer *layer, tbm_surface_h buffer);
534 * @brief Unset a TDM buffer from a layer object
535 * @param[in] layer A layer object
536 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
538 * A backend module @b SHOULD hide the current showing buffer from screen.
539 * If needed, cleanup a layer object resource.
541 tdm_error (*layer_unset_buffer)(tdm_layer *layer);
544 * @brief Set the zpos for a VIDEO layer object
545 * @param[in] layer A layer object
546 * @param[in] zpos z-order
547 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
548 * @see tdm_caps_layer, tdm_layer_capability
550 * A backend module doesn't need to implement this function if a backend
551 * module doesn't have VIDEO layers.\n
552 * This function is for VIDEO layers.
553 * GRAPHIC layers are non-changeable. The zpos of GRAPHIC layers starts
554 * from 0. If there are 4 GRAPHIC layers, The zpos SHOULD be 0, 1, 2, 3.\n
555 * But the zpos of VIDEO layer is changeable. And The zpos of VIDEO layers
556 * is less than GRAPHIC layers or more than GRAPHIC layers.
557 * ie, ..., -2, -1, 4, 5, ... (if 0 <= GRAPHIC layer's zpos < 4).
558 * The zpos of VIDEO layers is @b relative. It doesn't need to start
559 * from -1 or 4. Let's suppose that there are two VIDEO layers.
560 * One has -2 zpos. Another has -4 zpos. Then -2 Video layer is higher
561 * than -4 VIDEO layer.
563 tdm_error (*layer_set_video_pos)(tdm_layer *layer, int zpos);
566 * @brief Create a capture object of a layer object
567 * @param[in] output A output object
568 * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
569 * @return A capture object
570 * @see capture_destroy() function of #tdm_func_capture
572 * A backend module doesn't need to implement this function if a hardware
573 * doesn't have the capture device.
575 tdm_capture *(*layer_create_capture)(tdm_layer *layer, tdm_error *error);
577 void (*reserved1)(void);
578 void (*reserved2)(void);
579 void (*reserved3)(void);
580 void (*reserved4)(void);
581 void (*reserved5)(void);
582 void (*reserved6)(void);
583 void (*reserved7)(void);
584 void (*reserved8)(void);
588 * @brief The done handler of a pp object
590 typedef void (*tdm_pp_done_handler)(tdm_pp *pp, tbm_surface_h src, tbm_surface_h dst, void *user_data);
593 * @brief The pp functions for a backend module.
595 typedef struct _tdm_func_pp
598 * @brief Destroy a pp object
599 * @param[in] pp A pp object
600 * @see display_create_pp() function of #tdm_func_display
602 void (*pp_destroy)(tdm_pp *pp);
605 * @brief Set the geometry information to a pp object
606 * @param[in] pp A pp object
607 * @param[in] info The geometry information
608 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
609 * @see pp_commit() function of #tdm_func_pp
611 * A backend module would apply the geometry information when committed.
613 tdm_error (*pp_set_info)(tdm_pp *pp, tdm_info_pp *info);
616 * @brief Attach a source buffer and a destination buffer to a pp object
617 * @param[in] pp A pp object
618 * @param[in] src A source buffer
619 * @param[in] dst A destination buffer
620 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
621 * @see pp_set_info() function of #tdm_func_pp
622 * @see pp_commit() function of #tdm_func_pp
623 * @see pp_set_done_handler, tdm_pp_done_handler
625 * A backend module converts the image of a source buffer to a destination
626 * buffer when committed. The size/crop/transform information is set via
627 * #pp_set_info() of #tdm_func_pp. When done, a backend module @b SHOULD
628 * return the source/destination buffer via tdm_pp_done_handler.
630 tdm_error (*pp_attach)(tdm_pp *pp, tbm_surface_h src, tbm_surface_h dst);
633 * @brief Commit changes for a pp object
634 * @param[in] pp A pp object
635 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
637 tdm_error (*pp_commit)(tdm_pp *pp);
640 * @brief Set a user done handler to a pp object
641 * @param[in] pp A pp object
642 * @param[in] func A user done handler
643 * @param[in] user_data user data
644 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
646 * A backend module @b SHOULD call #tdm_pp_done_handler when converintg a image is done.
648 tdm_error (*pp_set_done_handler)(tdm_pp *pp, tdm_pp_done_handler func, void *user_data);
650 void (*reserved1)(void);
651 void (*reserved2)(void);
652 void (*reserved3)(void);
653 void (*reserved4)(void);
654 void (*reserved5)(void);
655 void (*reserved6)(void);
656 void (*reserved7)(void);
657 void (*reserved8)(void);
661 * @brief The done handler of a capture object
663 typedef void (*tdm_capture_done_handler)(tdm_capture *capture, tbm_surface_h buffer, void *user_data);
666 * @brief The capture functions for a backend module.
668 typedef struct _tdm_func_capture
671 * @brief Destroy a capture object
672 * @param[in] capture A capture object
673 * @see output_create_capture() function of #tdm_func_display
674 * @see layer_create_capture() function of #tdm_func_display
676 void (*capture_destroy)(tdm_capture *capture);
679 * @brief Set the geometry information to a capture object
680 * @param[in] capture A capture object
681 * @param[in] info The geometry information
682 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
683 * @see capture_commit() function of #tdm_func_capture
685 * A backend module would apply the geometry information when committed.
687 tdm_error (*capture_set_info)(tdm_capture *capture, tdm_info_capture *info);
690 * @brief Attach a TDM buffer to a capture object
691 * @details When capture_commit() function is called, a backend module dumps
692 * a output or a layer to a TDM buffer.
693 * @param[in] capture A capture object
694 * @param[in] buffer A TDM buffer
695 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
696 * @see capture_set_info() function of #tdm_func_capture
697 * @see capture_commit() function of #tdm_func_capture
698 * @see capture_set_done_handler, tdm_capture_done_handler
700 * A backend module dumps a output or a layer to to a TDM buffer when
701 * committed. The size/crop/transform information is set via #capture_set_info()
702 * of #tdm_func_capture. When done, a backend module @b SHOULD return the TDM
703 * buffer via tdm_capture_done_handler.
705 tdm_error (*capture_attach)(tdm_capture *capture, tbm_surface_h buffer);
708 * @brief Commit changes for a capture object
709 * @param[in] capture A capture object
710 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
712 tdm_error (*capture_commit)(tdm_capture *capture);
715 * @brief Set a user done handler to a capture object
716 * @param[in] capture A capture object
717 * @param[in] func A user done handler
718 * @param[in] user_data user data
719 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
721 * A backend module @b SHOULD call #tdm_capture_done_handler when capture operation is done.
723 tdm_error (*capture_set_done_handler)(tdm_capture *capture, tdm_capture_done_handler func, void *user_data);
725 void (*reserved1)(void);
726 void (*reserved2)(void);
727 void (*reserved3)(void);
728 void (*reserved4)(void);
729 void (*reserved5)(void);
730 void (*reserved6)(void);
731 void (*reserved7)(void);
732 void (*reserved8)(void);
736 * ABI versions. Each version has a major and minor revision. Modules
737 * using lower minor revisions must work with servers of a higher minor
738 * revision. There is no compatibility between different major revisions.
739 * Whenever the ABI_ANSIC_VERSION is changed, the others must also be
740 * changed. The minor revision mask is 0x0000FFFF and the major revision
741 * mask is 0xFFFF0000.
743 #define TDM_BACKEND_MINOR_VERSION_MASK 0x0000FFFF
744 #define TDM_BACKEND_MAJOR_VERSION_MASK 0xFFFF0000
745 #define TDM_BACKEND_GET_ABI_MINOR(v) ((v) & TDM_BACKEND_MINOR_VERSION_MASK)
746 #define TDM_BACKEND_GET_ABI_MAJOR(v) (((v) & TDM_BACKEND_MAJOR_VERSION_MASK) >> 16)
748 #define SET_TDM_BACKEND_ABI_VERSION(major, minor) \
749 (((major) << 16) & TDM_BACKEND_MAJOR_VERSION_MASK) | \
750 ((major) & TDM_BACKEND_MINOR_VERSION_MASK)
751 #define TDM_BACKEND_ABI_VERSION SET_TDM_BACKEND_ABI_VERSION(1, 1)
754 * @brief The backend module information of the entry point to initialize a TDM
757 * A backend module @b SHOULD define the global data symbol of which name is
758 * @b "tdm_backend_module_data". TDM will read this symbol, @b "tdm_backend_module_data",
759 * at the initial time and call init() function of #tdm_backend_module.
761 typedef struct _tdm_backend_module
763 const char *name; /**< The module name of a backend module */
764 const char *vendor; /**< The vendor name of a backend module */
765 unsigned long abi_version; /**< The ABI version of a backend module */
768 * @brief The init function of a backend module
769 * @param[in] dpy A display object
770 * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
771 * @return The backend module data
772 * @see tdm_backend_data
774 tdm_backend_data* (*init)(tdm_display *dpy, tdm_error *error);
777 * @brief The deinit function of a backend module
778 * @param[in] bdata The backend module data
780 void (*deinit)(tdm_backend_data *bdata);
781 } tdm_backend_module;
784 * @brief Register the backend display functions to a display
785 * @param[in] dpy A display object
786 * @param[in] func_display display functions
787 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
788 * @see tdm_backend_register_func_output, tdm_backend_register_func_layer
790 * A backend module @b SHOULD set the backend display functions at least.
792 tdm_error tdm_backend_register_func_display(tdm_display *dpy, tdm_func_display *func_display);
795 * @brief Register the backend output functions to a display
796 * @param[in] dpy A display object
797 * @param[in] func_output output functions
798 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
799 * @see tdm_backend_register_func_display, tdm_backend_register_func_layer
801 * A backend module @b SHOULD set the backend output functions at least.
803 tdm_error tdm_backend_register_func_output(tdm_display *dpy, tdm_func_output *func_output);
806 * @brief Register the backend layer functions to a display
807 * @param[in] dpy A display object
808 * @param[in] func_layer layer functions
809 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
810 * @see tdm_backend_register_func_display, tdm_backend_register_func_output
812 * A backend module @b SHOULD set the backend layer functions at least.
814 tdm_error tdm_backend_register_func_layer(tdm_display *dpy, tdm_func_layer *func_layer);
817 * @brief Register the backend pp functions to a display
818 * @param[in] dpy A display object
819 * @param[in] func_pp pp functions
820 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
821 * @see tdm_backend_register_func_display, tdm_backend_register_func_capture
823 * A backend module doesn'tcan skip to register the backend pp functions
824 * if a hardware doesn't have the memory-to-memory converting device.
826 tdm_error tdm_backend_register_func_pp(tdm_display *dpy, tdm_func_pp *func_pp);
829 * @brief Register the backend capture functions to a display
830 * @param[in] dpy A display object
831 * @param[in] func_capture capture functions
832 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
833 * @see tdm_backend_register_func_display, tdm_backend_register_func_pp
835 * A backend module can skip to register the backend capture functions
836 * if a hardware doesn't have the capture device.
838 tdm_error tdm_backend_register_func_capture(tdm_display *dpy, tdm_func_capture *func_capture);
841 * @brief Increase the ref_count of a TDM buffer
843 * TDM has its own buffer release mechanism to let an frontend user know when a TDM buffer
844 * becomes available for a next job. A TDM buffer can be used for TDM to show
845 * it on screen or to capture an output and a layer. After all operations,
846 * TDM will release it immediately when TDM doesn't need it any more.
847 * @param[in] buffer A TDM buffer
848 * @return A buffer itself. Otherwise, NULL.
849 * @see tdm_buffer_unref_backend
851 * - This function @b SHOULD be paired with #tdm_buffer_unref_backend. \n
852 * - For example, this function @b SHOULD be called in case that a backend module uses the TDM
853 * buffer of a layer for capturing a output or a layer to avoid tearing issue.
855 tbm_surface_h tdm_buffer_ref_backend(tbm_surface_h buffer);
858 * @brief Decrease the ref_count of a TDM buffer
859 * @param[in] buffer A TDM buffer
860 * @see tdm_buffer_ref_backend
862 void tdm_buffer_unref_backend(tbm_surface_h buffer);
865 * @brief The destroy handler of a TDM buffer
866 * @param[in] buffer A TDM buffer
867 * @param[in] user_data user data
868 * @see tdm_buffer_add_destroy_handler, tdm_buffer_remove_destroy_handler
870 typedef void (*tdm_buffer_destroy_handler)(tbm_surface_h buffer, void *user_data);
873 * @brief Add a destroy handler to a TDM buffer
874 * @param[in] buffer A TDM buffer
875 * @param[in] func A destroy handler
876 * @param[in] user_data user data
877 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
878 * @see tdm_buffer_remove_destroy_handler
880 * A backend module can add a TDM buffer destroy handler to a TDM buffer which
881 * is a #tbm_surface_h object. When the TDM buffer is destroyed, this handler will
884 tdm_error tdm_buffer_add_destroy_handler(tbm_surface_h buffer, tdm_buffer_destroy_handler func, void *user_data);
887 * @brief Remove a destroy handler from a TDM buffer
888 * @param[in] buffer A TDM buffer
889 * @param[in] func A destroy handler
890 * @param[in] user_data user data
891 * @see tdm_buffer_add_destroy_handler
893 void tdm_buffer_remove_destroy_handler(tbm_surface_h buffer, tdm_buffer_destroy_handler func, void *user_data);
900 #endif /* _TDM_BACKEND_H_ */