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 tdm_output_conn_status status; /**< The connection status */
81 tdm_output_type type; /**< The connection type */
82 unsigned int type_id; /**< The connection type id */
84 unsigned int mode_count; /**< The count of available modes */
85 tdm_output_mode *modes; /**< The @b newly-allocated array of modes. will be freed in frontend. */
87 unsigned int prop_count; /**< The count of available properties */
88 tdm_prop *props; /**< The @b newly-allocated array of properties. will be freed in frontend. */
90 unsigned int mmWidth; /**< The physical width (milimeter) */
91 unsigned int mmHeight; /**< The physical height (milimeter) */
92 unsigned int subpixel; /**< The subpixel */
94 int min_w; /**< The minimun width. -1 means "not defined" */
95 int min_h; /**< The minimun height. -1 means "not defined" */
96 int max_w; /**< The maximum width. -1 means "not defined" */
97 int max_h; /**< The maximum height. -1 means "not defined" */
98 int preferred_align; /**< The prefered align. -1 means "not defined" */
102 * @brief The capabilities structure of a layer object
103 * @see The layer_get_capability() function of #tdm_func_display
105 typedef struct _tdm_caps_layer
107 tdm_layer_capability capabilities; /**< The capabilities of layer */
111 * GRAPHIC layers are non-changeable. The zpos of GRAPHIC layers starts
112 * from 0. If there are 4 GRAPHIC layers, The zpos SHOULD be 0, 1, 2, 3.\n
113 * But the zpos of VIDEO layer is changeable by layer_set_video_pos() function
114 * of #tdm_func_display. And The zpos of VIDEO layers is less than GRAPHIC
115 * layers or more than GRAPHIC layers.
116 * ie, ..., -2, -1, 4, 5, ... (if 0 <= GRAPHIC layer's zpos < 4).
117 * The zpos of VIDEO layers is @b relative. It doesn't need to start
118 * from -1 or 4. Let's suppose that there are two VIDEO layers.
119 * One has -2 zpos. Another has -4 zpos. Then -2 Video layer is higher
120 * than -4 VIDEO layer.
124 unsigned int format_count; /**< The count of available formats */
125 tbm_format *formats; /**< The @b newly-allocated array of formats. will be freed in frontend. */
127 unsigned int prop_count; /**< The count of available properties */
128 tdm_prop *props; /**< The @b newly-allocated array of properties. will be freed in frontend. */
132 * @brief The capabilities structure of a pp object
133 * @see The display_get_pp_capability() function of #tdm_func_display
135 typedef struct _tdm_caps_pp
137 tdm_pp_capability capabilities; /**< The capabilities of pp */
139 unsigned int format_count; /**< The count of available formats */
140 tbm_format *formats; /**< The @b newly-allocated array. will be freed in frontend. */
142 int min_w; /**< The minimun width. -1 means "not defined" */
143 int min_h; /**< The minimun height. -1 means "not defined" */
144 int max_w; /**< The maximum width. -1 means "not defined" */
145 int max_h; /**< The maximum height. -1 means "not defined" */
146 int preferred_align; /**< The prefered align. -1 means "not defined" */
150 * @brief The capabilities structure of a capture object
151 * @see The display_get_capture_capability() function of #tdm_func_display
153 typedef struct _tdm_caps_capture
155 tdm_capture_capability capabilities; /**< The capabilities of capture */
157 unsigned int format_count; /**< The count of available formats */
158 tbm_format *formats; /**< The @b newly-allocated array of formats. will be freed in frontend. */
160 int min_w; /**< The minimun width. -1 means "not defined" */
161 int min_h; /**< The minimun height. -1 means "not defined" */
162 int max_w; /**< The maximum width. -1 means "not defined" */
163 int max_h; /**< The maximum height. -1 means "not defined" */
164 int preferred_align; /**< The prefered align. -1 means "not defined" */
168 * @brief The display functions for a backend module.
170 typedef struct _tdm_func_display
173 * @brief Get the display capabilities of a backend module
174 * @param[in] bdata The backend module data
175 * @param[out] caps The display capabilities of a backend module
176 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
178 * A backend module @b SHOULD implement this function. TDM calls this function
179 * not only at the initial time, but also at the update time when new output
181 * If a hardware has the restriction of the number of max usable layer count,
182 * a backend module can set the max count to max_layer_count of #tdm_caps_display
183 * structure. Otherwise, set -1.
185 tdm_error (*display_get_capabilitiy)(tdm_backend_data *bdata, tdm_caps_display *caps);
188 * @brief Get the pp capabilities of a backend module
189 * @param[in] bdata The backend module data
190 * @param[out] caps The pp capabilities of a backend module
191 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
192 * @see tdm_backend_register_func_pp
194 * TDM calls this function not only at the initial time, but also at the update
195 * time when new output is connected.\n
196 * A backend module doesn't need to implement this function if a hardware
197 * doesn't have the memory-to-memory converting device. Otherwise, a backend module
198 * @b SHOULD fill the #tdm_caps_pp data. #tdm_caps_pp contains the hardware
199 * restriction information which a converting device can handle. ie, format, size, etc.
201 tdm_error (*display_get_pp_capability)(tdm_backend_data *bdata, tdm_caps_pp *caps);
204 * @brief Get the capture capabilities of a backend module
205 * @param[in] bdata The backend module data
206 * @param[out] caps The capture capabilities of a backend module
207 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
208 * @see tdm_backend_register_func_capture
210 * TDM calls this function not only at the initial time, but also at the update
211 * time when new output is connected.\n
212 * A backend module doesn't need to implement this function if a hardware
213 * doesn't have the capture device. Otherwise, a backend module @b SHOULD fill the
214 * #tdm_caps_capture data. #tdm_caps_capture contains the hardware restriction
215 * information which a capture device can handle. ie, format, size, etc.
217 tdm_error (*display_get_capture_capability)(tdm_backend_data *bdata, tdm_caps_capture *caps);
220 * @brief Get a output array of a backend module
221 * @param[in] bdata The backend module data
222 * @param[out] count The count of outputs
223 * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
224 * @return A output array which is @b newly-allocated
225 * @see tdm_backend_register_func_capture
227 * A backend module @b SHOULD implement this function. TDM calls this function
228 * not only at the initial time, but also at the update time when new output
230 * A backend module @b SHOULD return the @b newly-allocated array which contains
231 * "tdm_output*" data. It will be freed in frontend.
235 drm_display_get_outputs(tdm_backend_data *bdata, int *count, tdm_error *error)
237 tdm_drm_data *drm_data = bdata;
238 tdm_drm_output_data *output_data = NULL;
239 tdm_output **outputs;
243 LIST_FOR_EACH_ENTRY(output_data, &drm_data->output_list, link)
248 if (error) *error = TDM_ERROR_NONE;
252 // will be freed in frontend
253 outputs = calloc(*count, sizeof(tdm_drm_output_data*));
257 if (error) *error = TDM_ERROR_OUT_OF_MEMORY;
262 LIST_FOR_EACH_ENTRY(output_data, &drm_data->output_list, link)
263 outputs[i++] = output_data;
265 if (error) *error = TDM_ERROR_NONE;
271 tdm_output **(*display_get_outputs)(tdm_backend_data *bdata, int *count, tdm_error *error);
274 * @brief Get the file descriptor of a backend module
275 * @param[in] bdata The backend module data
276 * @param[out] fd The fd of a backend module
277 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
278 * @see display_handle_events() function of #tdm_func_display
280 * A backend module can return epoll's fd which is watching the backend device one more fds.
282 tdm_error (*display_get_fd)(tdm_backend_data *bdata, int *fd);
285 * @brief Handle the events which happens on the fd of a backend module
286 * @param[in] bdata The backend module data
287 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
289 tdm_error (*display_handle_events)(tdm_backend_data *bdata);
292 * @brief Create a pp object of a backend module
293 * @param[in] bdata The backend module data
294 * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
295 * @return A pp object
296 * @see pp_destroy() function of #tdm_func_pp
298 * A backend module doesn't need to implement this function if a hardware
299 * doesn't have the memory-to-memory converting device.
301 tdm_pp* (*display_create_pp)(tdm_backend_data *bdata, tdm_error *error);
303 void (*reserved1)(void);
304 void (*reserved2)(void);
305 void (*reserved3)(void);
306 void (*reserved4)(void);
307 void (*reserved5)(void);
308 void (*reserved6)(void);
309 void (*reserved7)(void);
310 void (*reserved8)(void);
314 * @brief The output functions for a backend module.
316 typedef struct _tdm_func_output
319 * @brief Get the capabilities of a output object
320 * @param[in] output A output object
321 * @param[out] caps The capabilities of a output object
322 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
324 * A backend module @b SHOULD implement this function. TDM calls this function
325 * not only at the initial time, but also at the update time when new output
327 * #tdm_caps_output contains connection status, modes, avaiable properties,
328 * size restriction information, etc.
330 tdm_error (*output_get_capability)(tdm_output *output, tdm_caps_output *caps);
333 * @brief Get a layer array of a output object
334 * @param[in] output A output object
335 * @param[out] count The count of layers
336 * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
337 * @return A layer array which is @b newly-allocated
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 * A backend module @b SHOULD return the @b newly-allocated array which contains
343 * "tdm_layer*" data. It will be freed in frontend.
345 tdm_layer **(*output_get_layers)(tdm_output *output, int *count, tdm_error *error);
348 * @brief Set the property which has a given id
349 * @param[in] output A output object
350 * @param[in] id The property id
351 * @param[in] value The value
352 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
354 tdm_error (*output_set_property)(tdm_output *output, unsigned int id, tdm_value value);
357 * @brief Get the property which has a given id
358 * @param[in] output A output object
359 * @param[in] id The property id
360 * @param[out] value The value
361 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
363 tdm_error (*output_get_property)(tdm_output *output, unsigned int id, tdm_value *value);
366 * @brief Wait for VBLANK
367 * @param[in] output A output object
368 * @param[in] interval vblank interval
369 * @param[in] sync 0: asynchronous, 1:synchronous
370 * @param[in] user_data The user data
371 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
372 * @see output_set_vblank_handler, tdm_output_vblank_handler
374 * A backend module @b SHOULD call a user vblank handler after interval vblanks.
376 tdm_error (*output_wait_vblank)(tdm_output *output, int interval, int sync, void *user_data);
379 * @brief Set a user vblank handler
380 * @param[in] output A output object
381 * @param[in] func A user vblank handler
382 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
384 tdm_error (*output_set_vblank_handler)(tdm_output *output, tdm_output_vblank_handler func);
387 * @brief Commit changes for a output object
388 * @param[in] output A output object
389 * @param[in] sync 0: asynchronous, 1:synchronous
390 * @param[in] user_data The user data
391 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
392 * @see output_set_commit_handler, tdm_output_commit_handler
394 * A backend module @b SHOULD call a user commit handler after all change of
395 * a output object are applied.
397 tdm_error (*output_commit)(tdm_output *output, int sync, void *user_data);
400 * @brief Set a user commit handler
401 * @param[in] output A output object
402 * @param[in] func A user commit handler
403 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
405 tdm_error (*output_set_commit_handler)(tdm_output *output, tdm_output_commit_handler func);
408 * @brief Set DPMS of a output object
409 * @param[in] output A output object
410 * @param[in] dpms_value DPMS value
411 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
413 tdm_error (*output_set_dpms)(tdm_output *output, tdm_output_dpms dpms_value);
416 * @brief Get DPMS of a output object
417 * @param[in] output A output object
418 * @param[out] dpms_value DPMS value
419 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
421 tdm_error (*output_get_dpms)(tdm_output *output, tdm_output_dpms *dpms_value);
424 * @brief Set one of available modes of a output object
425 * @param[in] output A output object
426 * @param[in] mode A output mode
427 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
429 tdm_error (*output_set_mode)(tdm_output *output, const tdm_output_mode *mode);
432 * @brief Get the mode of a output object
433 * @param[in] output A output object
434 * @param[out] mode A output mode
435 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
437 tdm_error (*output_get_mode)(tdm_output *output, const tdm_output_mode **mode);
440 * @brief Create a capture object of a output object
441 * @param[in] output A output object
442 * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
443 * @return A capture object
444 * @see capture_destroy() function of #tdm_func_capture
446 * A backend module doesn't need to implement this function if a hardware
447 * doesn't have the capture device.
449 tdm_capture *(*output_create_capture)(tdm_output *output, tdm_error *error);
451 void (*reserved1)(void);
452 void (*reserved2)(void);
453 void (*reserved3)(void);
454 void (*reserved4)(void);
455 void (*reserved5)(void);
456 void (*reserved6)(void);
457 void (*reserved7)(void);
458 void (*reserved8)(void);
462 * @brief The layer functions for a backend module.
464 typedef struct _tdm_func_layer
467 * @brief Get the capabilities of a layer object
468 * @param[in] layer A layer object
469 * @param[out] caps The capabilities of a layer object
470 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
472 * A backend module @b SHOULD implement this function. TDM calls this function
473 * not only at the initial time, but also at the update time when new output
475 * #tdm_caps_layer contains avaiable formats/properties, zpos information, etc.
477 tdm_error (*layer_get_capability)(tdm_layer *layer, tdm_caps_layer *caps);
480 * @brief Set the property which has a given id.
481 * @param[in] layer A layer object
482 * @param[in] id The property id
483 * @param[in] value The value
484 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
486 tdm_error (*layer_set_property)(tdm_layer *layer, unsigned int id, tdm_value value);
489 * @brief Get the property which has a given id.
490 * @param[in] layer A layer object
491 * @param[in] id The property id
492 * @param[out] value The value
493 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
495 tdm_error (*layer_get_property)(tdm_layer *layer, unsigned int id, tdm_value *value);
498 * @brief Set the geometry information to a layer object
499 * @param[in] layer A layer object
500 * @param[in] info The geometry information
501 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
502 * @see output_commit() function of #tdm_func_display
504 * A backend module would apply the geometry information when the output object
505 * of a layer object is committed.
507 tdm_error (*layer_set_info)(tdm_layer *layer, tdm_info_layer *info);
510 * @brief Get the geometry information to a layer object
511 * @param[in] layer A layer object
512 * @param[out] info The geometry information
513 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
515 tdm_error (*layer_get_info)(tdm_layer *layer, tdm_info_layer *info);
518 * @brief Set a TDM buffer to a layer object
519 * @param[in] layer A layer object
520 * @param[in] buffer A TDM buffer
521 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
522 * @see output_commit() function of #tdm_func_display
524 * A backend module would apply a TDM buffer when the output object
525 * of a layer object is committed.
527 tdm_error (*layer_set_buffer)(tdm_layer *layer, tbm_surface_h buffer);
530 * @brief Unset a TDM buffer from a layer object
531 * @param[in] layer A layer object
532 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
534 * A backend module @b SHOULD hide the current showing buffer from screen.
535 * If needed, cleanup a layer object resource.
537 tdm_error (*layer_unset_buffer)(tdm_layer *layer);
540 * @brief Set the zpos for a VIDEO layer object
541 * @param[in] layer A layer object
542 * @param[in] zpos z-order
543 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
544 * @see tdm_caps_layer, tdm_layer_capability
546 * A backend module doesn't need to implement this function if a backend
547 * module doesn't have VIDEO layers.\n
548 * This function is for VIDEO layers.
549 * GRAPHIC layers are non-changeable. The zpos of GRAPHIC layers starts
550 * from 0. If there are 4 GRAPHIC layers, The zpos SHOULD be 0, 1, 2, 3.\n
551 * But the zpos of VIDEO layer is changeable. And The zpos of VIDEO layers
552 * is less than GRAPHIC layers or more than GRAPHIC layers.
553 * ie, ..., -2, -1, 4, 5, ... (if 0 <= GRAPHIC layer's zpos < 4).
554 * The zpos of VIDEO layers is @b relative. It doesn't need to start
555 * from -1 or 4. Let's suppose that there are two VIDEO layers.
556 * One has -2 zpos. Another has -4 zpos. Then -2 Video layer is higher
557 * than -4 VIDEO layer.
559 tdm_error (*layer_set_video_pos)(tdm_layer *layer, int zpos);
562 * @brief Create a capture object of a layer object
563 * @param[in] output A output object
564 * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
565 * @return A capture object
566 * @see capture_destroy() function of #tdm_func_capture
568 * A backend module doesn't need to implement this function if a hardware
569 * doesn't have the capture device.
571 tdm_capture *(*layer_create_capture)(tdm_layer *layer, tdm_error *error);
573 void (*reserved1)(void);
574 void (*reserved2)(void);
575 void (*reserved3)(void);
576 void (*reserved4)(void);
577 void (*reserved5)(void);
578 void (*reserved6)(void);
579 void (*reserved7)(void);
580 void (*reserved8)(void);
584 * @brief The done handler of a pp object
586 typedef void (*tdm_pp_done_handler)(tdm_pp *pp, tbm_surface_h src, tbm_surface_h dst, void *user_data);
589 * @brief The pp functions for a backend module.
591 typedef struct _tdm_func_pp
594 * @brief Destroy a pp object
595 * @param[in] pp A pp object
596 * @see display_create_pp() function of #tdm_func_display
598 void (*pp_destroy)(tdm_pp *pp);
601 * @brief Set the geometry information to a pp object
602 * @param[in] pp A pp object
603 * @param[in] info The geometry information
604 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
605 * @see pp_commit() function of #tdm_func_pp
607 * A backend module would apply the geometry information when committed.
609 tdm_error (*pp_set_info)(tdm_pp *pp, tdm_info_pp *info);
612 * @brief Attach a source buffer and a destination buffer to a pp object
613 * @param[in] pp A pp object
614 * @param[in] src A source buffer
615 * @param[in] dst A destination buffer
616 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
617 * @see pp_set_info() function of #tdm_func_pp
618 * @see pp_commit() function of #tdm_func_pp
619 * @see pp_set_done_handler, tdm_pp_done_handler
621 * A backend module converts the image of a source buffer to a destination
622 * buffer when committed. The size/crop/transform information is set via
623 * #pp_set_info() of #tdm_func_pp. When done, a backend module @b SHOULD
624 * return the source/destination buffer via tdm_pp_done_handler.
626 tdm_error (*pp_attach)(tdm_pp *pp, tbm_surface_h src, tbm_surface_h dst);
629 * @brief Commit changes for a pp object
630 * @param[in] pp A pp object
631 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
633 tdm_error (*pp_commit)(tdm_pp *pp);
636 * @brief Set a user done handler to a pp object
637 * @param[in] pp A pp object
638 * @param[in] func A user done handler
639 * @param[in] user_data user data
640 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
642 * A backend module @b SHOULD call #tdm_pp_done_handler when converintg a image is done.
644 tdm_error (*pp_set_done_handler)(tdm_pp *pp, tdm_pp_done_handler func, void *user_data);
646 void (*reserved1)(void);
647 void (*reserved2)(void);
648 void (*reserved3)(void);
649 void (*reserved4)(void);
650 void (*reserved5)(void);
651 void (*reserved6)(void);
652 void (*reserved7)(void);
653 void (*reserved8)(void);
657 * @brief The done handler of a capture object
659 typedef void (*tdm_capture_done_handler)(tdm_capture *capture, tbm_surface_h buffer, void *user_data);
662 * @brief The capture functions for a backend module.
664 typedef struct _tdm_func_capture
667 * @brief Destroy a capture object
668 * @param[in] capture A capture object
669 * @see output_create_capture() function of #tdm_func_display
670 * @see layer_create_capture() function of #tdm_func_display
672 void (*capture_destroy)(tdm_capture *capture);
675 * @brief Set the geometry information to a capture object
676 * @param[in] capture A capture object
677 * @param[in] info The geometry information
678 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
679 * @see capture_commit() function of #tdm_func_capture
681 * A backend module would apply the geometry information when committed.
683 tdm_error (*capture_set_info)(tdm_capture *capture, tdm_info_capture *info);
686 * @brief Attach a TDM buffer to a capture object
687 * @details When capture_commit() function is called, a backend module dumps
688 * a output or a layer to a TDM buffer.
689 * @param[in] capture A capture object
690 * @param[in] buffer A TDM buffer
691 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
692 * @see capture_set_info() function of #tdm_func_capture
693 * @see capture_commit() function of #tdm_func_capture
694 * @see capture_set_done_handler, tdm_capture_done_handler
696 * A backend module dumps a output or a layer to to a TDM buffer when
697 * committed. The size/crop/transform information is set via #capture_set_info()
698 * of #tdm_func_capture. When done, a backend module @b SHOULD return the TDM
699 * buffer via tdm_capture_done_handler.
701 tdm_error (*capture_attach)(tdm_capture *capture, tbm_surface_h buffer);
704 * @brief Commit changes for a capture object
705 * @param[in] capture A capture object
706 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
708 tdm_error (*capture_commit)(tdm_capture *capture);
711 * @brief Set a user done handler to a capture object
712 * @param[in] capture A capture object
713 * @param[in] func A user done handler
714 * @param[in] user_data user data
715 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
717 * A backend module @b SHOULD call #tdm_capture_done_handler when capture operation is done.
719 tdm_error (*capture_set_done_handler)(tdm_capture *capture, tdm_capture_done_handler func, void *user_data);
721 void (*reserved1)(void);
722 void (*reserved2)(void);
723 void (*reserved3)(void);
724 void (*reserved4)(void);
725 void (*reserved5)(void);
726 void (*reserved6)(void);
727 void (*reserved7)(void);
728 void (*reserved8)(void);
732 * ABI versions. Each version has a major and minor revision. Modules
733 * using lower minor revisions must work with servers of a higher minor
734 * revision. There is no compatibility between different major revisions.
735 * Whenever the ABI_ANSIC_VERSION is changed, the others must also be
736 * changed. The minor revision mask is 0x0000FFFF and the major revision
737 * mask is 0xFFFF0000.
739 #define TDM_BACKEND_MINOR_VERSION_MASK 0x0000FFFF
740 #define TDM_BACKEND_MAJOR_VERSION_MASK 0xFFFF0000
741 #define TDM_BACKEND_GET_ABI_MINOR(v) ((v) & TDM_BACKEND_MINOR_VERSION_MASK)
742 #define TDM_BACKEND_GET_ABI_MAJOR(v) (((v) & TDM_BACKEND_MAJOR_VERSION_MASK) >> 16)
744 #define SET_TDM_BACKEND_ABI_VERSION(major, minor) \
745 (((major) << 16) & TDM_BACKEND_MAJOR_VERSION_MASK) | \
746 ((major) & TDM_BACKEND_MINOR_VERSION_MASK)
747 #define TDM_BACKEND_ABI_VERSION SET_TDM_BACKEND_ABI_VERSION(1, 1)
750 * @brief The backend module information of the entry point to initialize a TDM
753 * A backend module @b SHOULD define the global data symbol of which name is
754 * @b "tdm_backend_module_data". TDM will read this symbol, @b "tdm_backend_module_data",
755 * at the initial time and call init() function of #tdm_backend_module.
757 typedef struct _tdm_backend_module
759 const char *name; /**< The module name of a backend module */
760 const char *vendor; /**< The vendor name of a backend module */
761 unsigned long abi_version; /**< The ABI version of a backend module */
764 * @brief The init function of a backend module
765 * @param[in] dpy A display object
766 * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
767 * @return The backend module data
768 * @see tdm_backend_data
770 tdm_backend_data* (*init)(tdm_display *dpy, tdm_error *error);
773 * @brief The deinit function of a backend module
774 * @param[in] bdata The backend module data
776 void (*deinit)(tdm_backend_data *bdata);
777 } tdm_backend_module;
780 * @brief Register the backend display functions to a display
781 * @param[in] dpy A display object
782 * @param[in] func_display display functions
783 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
784 * @see tdm_backend_register_func_output, tdm_backend_register_func_layer
786 * A backend module @b SHOULD set the backend display functions at least.
788 tdm_error tdm_backend_register_func_display(tdm_display *dpy, tdm_func_display *func_display);
791 * @brief Register the backend output functions to a display
792 * @param[in] dpy A display object
793 * @param[in] func_output output functions
794 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
795 * @see tdm_backend_register_func_display, tdm_backend_register_func_layer
797 * A backend module @b SHOULD set the backend output functions at least.
799 tdm_error tdm_backend_register_func_output(tdm_display *dpy, tdm_func_output *func_output);
802 * @brief Register the backend layer functions to a display
803 * @param[in] dpy A display object
804 * @param[in] func_layer layer functions
805 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
806 * @see tdm_backend_register_func_display, tdm_backend_register_func_output
808 * A backend module @b SHOULD set the backend layer functions at least.
810 tdm_error tdm_backend_register_func_layer(tdm_display *dpy, tdm_func_layer *func_layer);
813 * @brief Register the backend pp functions to a display
814 * @param[in] dpy A display object
815 * @param[in] func_pp pp functions
816 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
817 * @see tdm_backend_register_func_display, tdm_backend_register_func_capture
819 * A backend module doesn'tcan skip to register the backend pp functions
820 * if a hardware doesn't have the memory-to-memory converting device.
822 tdm_error tdm_backend_register_func_pp(tdm_display *dpy, tdm_func_pp *func_pp);
825 * @brief Register the backend capture functions to a display
826 * @param[in] dpy A display object
827 * @param[in] func_capture capture functions
828 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
829 * @see tdm_backend_register_func_display, tdm_backend_register_func_pp
831 * A backend module can skip to register the backend capture functions
832 * if a hardware doesn't have the capture device.
834 tdm_error tdm_backend_register_func_capture(tdm_display *dpy, tdm_func_capture *func_capture);
837 * @brief Increase the ref_count of a TDM buffer
839 * TDM has its own buffer release mechanism to let an frontend user know when a TDM buffer
840 * becomes available for a next job. A TDM buffer can be used for TDM to show
841 * it on screen or to capture an output and a layer. After all operations,
842 * TDM will release it immediately when TDM doesn't need it any more.
843 * @param[in] buffer A TDM buffer
844 * @return A buffer itself. Otherwise, NULL.
845 * @see tdm_buffer_unref_backend
847 * - This function @b SHOULD be paired with #tdm_buffer_unref_backend. \n
848 * - For example, this function @b SHOULD be called in case that a backend module uses the TDM
849 * buffer of a layer for capturing a output or a layer to avoid tearing issue.
851 tbm_surface_h tdm_buffer_ref_backend(tbm_surface_h buffer);
854 * @brief Decrease the ref_count of a TDM buffer
855 * @param[in] buffer A TDM buffer
856 * @see tdm_buffer_ref_backend
858 void tdm_buffer_unref_backend(tbm_surface_h buffer);
861 * @brief The destroy handler of a TDM buffer
862 * @param[in] buffer A TDM buffer
863 * @param[in] user_data user data
864 * @see tdm_buffer_add_destroy_handler, tdm_buffer_remove_destroy_handler
866 typedef void (*tdm_buffer_destroy_handler)(tbm_surface_h buffer, void *user_data);
869 * @brief Add a destroy handler to a TDM buffer
870 * @param[in] buffer A TDM buffer
871 * @param[in] func A destroy handler
872 * @param[in] user_data user data
873 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
874 * @see tdm_buffer_remove_destroy_handler
876 * A backend module can add a TDM buffer destroy handler to a TDM buffer which
877 * is a #tbm_surface_h object. When the TDM buffer is destroyed, this handler will
880 tdm_error tdm_buffer_add_destroy_handler(tbm_surface_h buffer, tdm_buffer_destroy_handler func, void *user_data);
883 * @brief Remove a destroy handler from a TDM buffer
884 * @param[in] buffer A TDM buffer
885 * @param[in] func A destroy handler
886 * @param[in] user_data user data
887 * @see tdm_buffer_add_destroy_handler
889 void tdm_buffer_remove_destroy_handler(tbm_surface_h buffer, tdm_buffer_destroy_handler func, void *user_data);
896 #endif /* _TDM_BACKEND_H_ */