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);
304 * @brief Get the capabilities of a output object
305 * @param[in] output A output object
306 * @param[out] caps The capabilities of a output object
307 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
309 * A backend module @b SHOULD implement this function. TDM calls this function
310 * not only at the initial time, but also at the update time when new output
312 * #tdm_caps_output contains connection status, modes, avaiable properties,
313 * size restriction information, etc.
315 tdm_error (*output_get_capability)(tdm_output *output, tdm_caps_output *caps);
318 * @brief Get a layer array of a output object
319 * @param[in] output A output object
320 * @param[out] count The count of layers
321 * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
322 * @return A layer array which is @b newly-allocated
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 * A backend module @b SHOULD return the @b newly-allocated array which contains
328 * "tdm_layer*" data. It will be freed in frontend.
330 tdm_layer **(*output_get_layers)(tdm_output *output, int *count, tdm_error *error);
333 * @brief Set the property which has a given id
334 * @param[in] output A output object
335 * @param[in] id The property id
336 * @param[in] value The value
337 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
339 tdm_error (*output_set_property)(tdm_output *output, unsigned int id, tdm_value value);
342 * @brief Get the property which has a given id
343 * @param[in] output A output object
344 * @param[in] id The property id
345 * @param[out] value The value
346 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
348 tdm_error (*output_get_property)(tdm_output *output, unsigned int id, tdm_value *value);
351 * @brief Wait for VBLANK
352 * @param[in] output A output object
353 * @param[in] interval vblank interval
354 * @param[in] sync 0: asynchronous, 1:synchronous
355 * @param[in] user_data The user data
356 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
357 * @see output_set_vblank_handler, tdm_output_vblank_handler
359 * A backend module @b SHOULD call a user vblank handler after interval vblanks.
361 tdm_error (*output_wait_vblank)(tdm_output *output, int interval, int sync, void *user_data);
364 * @brief Set a user vblank handler
365 * @param[in] output A output object
366 * @param[in] func A user vblank handler
367 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
369 tdm_error (*output_set_vblank_handler)(tdm_output *output, tdm_output_vblank_handler func);
372 * @brief Commit changes for a output object
373 * @param[in] output A output object
374 * @param[in] sync 0: asynchronous, 1:synchronous
375 * @param[in] user_data The user data
376 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
377 * @see output_set_commit_handler, tdm_output_commit_handler
379 * A backend module @b SHOULD call a user commit handler after all change of
380 * a output object are applied.
382 tdm_error (*output_commit)(tdm_output *output, int sync, void *user_data);
385 * @brief Set a user commit handler
386 * @param[in] output A output object
387 * @param[in] func A user commit handler
388 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
390 tdm_error (*output_set_commit_handler)(tdm_output *output, tdm_output_commit_handler func);
393 * @brief Set DPMS of a output object
394 * @param[in] output A output object
395 * @param[in] dpms_value DPMS value
396 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
398 tdm_error (*output_set_dpms)(tdm_output *output, tdm_output_dpms dpms_value);
401 * @brief Get DPMS of a output object
402 * @param[in] output A output object
403 * @param[out] dpms_value DPMS value
404 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
406 tdm_error (*output_get_dpms)(tdm_output *output, tdm_output_dpms *dpms_value);
409 * @brief Set one of available modes of a output object
410 * @param[in] output A output object
411 * @param[in] mode A output mode
412 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
414 tdm_error (*output_set_mode)(tdm_output *output, const tdm_output_mode *mode);
417 * @brief Get the mode of a output object
418 * @param[in] output A output object
419 * @param[out] mode A output mode
420 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
422 tdm_error (*output_get_mode)(tdm_output *output, const tdm_output_mode **mode);
425 * @brief Create a capture object of a output object
426 * @param[in] output A output object
427 * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
428 * @return A capture object
429 * @see capture_destroy() function of #tdm_func_capture
431 * A backend module doesn't need to implement this function if a hardware
432 * doesn't have the capture device.
434 tdm_capture *(*output_create_capture)(tdm_output *output, tdm_error *error);
437 * @brief Get the capabilities of a layer object
438 * @param[in] layer A layer object
439 * @param[out] caps The capabilities of a layer object
440 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
442 * A backend module @b SHOULD implement this function. TDM calls this function
443 * not only at the initial time, but also at the update time when new output
445 * #tdm_caps_layer contains avaiable formats/properties, zpos information, etc.
447 tdm_error (*layer_get_capability)(tdm_layer *layer, tdm_caps_layer *caps);
450 * @brief Set the property which has a given id.
451 * @param[in] layer A layer object
452 * @param[in] id The property id
453 * @param[in] value The value
454 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
456 tdm_error (*layer_set_property)(tdm_layer *layer, unsigned int id, tdm_value value);
459 * @brief Get the property which has a given id.
460 * @param[in] layer A layer object
461 * @param[in] id The property id
462 * @param[out] value The value
463 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
465 tdm_error (*layer_get_property)(tdm_layer *layer, unsigned int id, tdm_value *value);
468 * @brief Set the geometry information to a layer object
469 * @param[in] layer A layer object
470 * @param[in] info The geometry information
471 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
472 * @see output_commit() function of #tdm_func_display
474 * A backend module would apply the geometry information when the output object
475 * of a layer object is committed.
477 tdm_error (*layer_set_info)(tdm_layer *layer, tdm_info_layer *info);
480 * @brief Get the geometry information to a layer object
481 * @param[in] layer A layer object
482 * @param[out] info The geometry information
483 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
485 tdm_error (*layer_get_info)(tdm_layer *layer, tdm_info_layer *info);
488 * @brief Set a TDM buffer to a layer object
489 * @param[in] layer A layer object
490 * @param[in] buffer A TDM buffer
491 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
492 * @see output_commit() function of #tdm_func_display
494 * A backend module would apply a TDM buffer when the output object
495 * of a layer object is committed.
497 tdm_error (*layer_set_buffer)(tdm_layer *layer, tbm_surface_h buffer);
500 * @brief Unset a TDM buffer from a layer object
501 * @param[in] layer A layer object
502 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
504 * A backend module @b SHOULD hide the current showing buffer from screen.
505 * If needed, cleanup a layer object resource.
507 tdm_error (*layer_unset_buffer)(tdm_layer *layer);
510 * @brief Set the zpos for a VIDEO layer object
511 * @param[in] layer A layer object
512 * @param[in] zpos z-order
513 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
514 * @see tdm_caps_layer, tdm_layer_capability
516 * A backend module doesn't need to implement this function if a backend
517 * module doesn't have VIDEO layers.\n
518 * This function is for VIDEO layers.
519 * GRAPHIC layers are non-changeable. The zpos of GRAPHIC layers starts
520 * from 0. If there are 4 GRAPHIC layers, The zpos SHOULD be 0, 1, 2, 3.\n
521 * But the zpos of VIDEO layer is changeable. And The zpos of VIDEO layers
522 * is less than GRAPHIC layers or more than GRAPHIC layers.
523 * ie, ..., -2, -1, 4, 5, ... (if 0 <= GRAPHIC layer's zpos < 4).
524 * The zpos of VIDEO layers is @b relative. It doesn't need to start
525 * from -1 or 4. Let's suppose that there are two VIDEO layers.
526 * One has -2 zpos. Another has -4 zpos. Then -2 Video layer is higher
527 * than -4 VIDEO layer.
529 tdm_error (*layer_set_video_pos)(tdm_layer *layer, int zpos);
532 * @brief Create a capture object of a layer object
533 * @param[in] output A output object
534 * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
535 * @return A capture object
536 * @see capture_destroy() function of #tdm_func_capture
538 * A backend module doesn't need to implement this function if a hardware
539 * doesn't have the capture device.
541 tdm_capture *(*layer_create_capture)(tdm_layer *layer, tdm_error *error);
545 * @brief The done handler of a pp object
547 typedef void (*tdm_pp_done_handler)(tdm_pp *pp, tbm_surface_h src, tbm_surface_h dst, void *user_data);
550 * @brief The pp functions for a backend module.
552 typedef struct _tdm_func_pp
555 * @brief Destroy a pp object
556 * @param[in] pp A pp object
557 * @see display_create_pp() function of #tdm_func_display
559 void (*pp_destroy)(tdm_pp *pp);
562 * @brief Set the geometry information to a pp object
563 * @param[in] pp A pp object
564 * @param[in] info The geometry information
565 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
566 * @see pp_commit() function of #tdm_func_pp
568 * A backend module would apply the geometry information when committed.
570 tdm_error (*pp_set_info)(tdm_pp *pp, tdm_info_pp *info);
573 * @brief Attach a source buffer and a destination buffer to a pp object
574 * @param[in] pp A pp object
575 * @param[in] src A source buffer
576 * @param[in] dst A destination buffer
577 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
578 * @see pp_set_info() function of #tdm_func_pp
579 * @see pp_commit() function of #tdm_func_pp
580 * @see pp_set_done_handler, tdm_pp_done_handler
582 * A backend module converts the image of a source buffer to a destination
583 * buffer when committed. The size/crop/transform information is set via
584 * #pp_set_info() of #tdm_func_pp. When done, a backend module @b SHOULD
585 * return the source/destination buffer via tdm_pp_done_handler.
587 tdm_error (*pp_attach)(tdm_pp *pp, tbm_surface_h src, tbm_surface_h dst);
590 * @brief Commit changes for a pp object
591 * @param[in] pp A pp object
592 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
594 tdm_error (*pp_commit)(tdm_pp *pp);
597 * @brief Set a user done handler to a pp object
598 * @param[in] pp A pp object
599 * @param[in] func A user done handler
600 * @param[in] user_data user data
601 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
603 * A backend module @b SHOULD call #tdm_pp_done_handler when converintg a image is done.
605 tdm_error (*pp_set_done_handler)(tdm_pp *pp, tdm_pp_done_handler func, void *user_data);
609 * @brief The done handler of a capture object
611 typedef void (*tdm_capture_done_handler)(tdm_capture *capture, tbm_surface_h buffer, void *user_data);
614 * @brief The capture functions for a backend module.
616 typedef struct _tdm_func_capture
619 * @brief Destroy a capture object
620 * @param[in] capture A capture object
621 * @see output_create_capture() function of #tdm_func_display
622 * @see layer_create_capture() function of #tdm_func_display
624 void (*capture_destroy)(tdm_capture *capture);
627 * @brief Set the geometry information to a capture object
628 * @param[in] capture A capture object
629 * @param[in] info The geometry information
630 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
631 * @see capture_commit() function of #tdm_func_capture
633 * A backend module would apply the geometry information when committed.
635 tdm_error (*capture_set_info)(tdm_capture *capture, tdm_info_capture *info);
638 * @brief Attach a TDM buffer to a capture object
639 * @details When capture_commit() function is called, a backend module dumps
640 * a output or a layer to a TDM buffer.
641 * @param[in] capture A capture object
642 * @param[in] buffer A TDM buffer
643 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
644 * @see capture_set_info() function of #tdm_func_capture
645 * @see capture_commit() function of #tdm_func_capture
646 * @see capture_set_done_handler, tdm_capture_done_handler
648 * A backend module dumps a output or a layer to to a TDM buffer when
649 * committed. The size/crop/transform information is set via #capture_set_info()
650 * of #tdm_func_capture. When done, a backend module @b SHOULD return the TDM
651 * buffer via tdm_capture_done_handler.
653 tdm_error (*capture_attach)(tdm_capture *capture, tbm_surface_h buffer);
656 * @brief Commit changes for a capture object
657 * @param[in] capture A capture object
658 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
660 tdm_error (*capture_commit)(tdm_capture *capture);
663 * @brief Set a user done handler to a capture object
664 * @param[in] capture A capture object
665 * @param[in] func A user done handler
666 * @param[in] user_data user data
667 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
669 * A backend module @b SHOULD call #tdm_capture_done_handler when capture operation is done.
671 tdm_error (*capture_set_done_handler)(tdm_capture *capture, tdm_capture_done_handler func, void *user_data);
675 * ABI versions. Each version has a major and minor revision. Modules
676 * using lower minor revisions must work with servers of a higher minor
677 * revision. There is no compatibility between different major revisions.
678 * Whenever the ABI_ANSIC_VERSION is changed, the others must also be
679 * changed. The minor revision mask is 0x0000FFFF and the major revision
680 * mask is 0xFFFF0000.
682 #define TDM_BACKEND_MINOR_VERSION_MASK 0x0000FFFF
683 #define TDM_BACKEND_MAJOR_VERSION_MASK 0xFFFF0000
684 #define TDM_BACKEND_GET_ABI_MINOR(v) ((v) & TDM_BACKEND_MINOR_VERSION_MASK)
685 #define TDM_BACKEND_GET_ABI_MAJOR(v) (((v) & TDM_BACKEND_MAJOR_VERSION_MASK) >> 16)
687 #define SET_TDM_BACKEND_ABI_VERSION(major, minor) \
688 (((major) << 16) & TDM_BACKEND_MAJOR_VERSION_MASK) | \
689 ((major) & TDM_BACKEND_MINOR_VERSION_MASK)
690 #define TDM_BACKEND_ABI_VERSION SET_TDM_BACKEND_ABI_VERSION(1, 1)
693 * @brief The backend module information of the entry point to initialize a TDM
696 * A backend module @b SHOULD define the global data symbol of which name is
697 * @b "tdm_backend_module_data". TDM will read this symbol, @b "tdm_backend_module_data",
698 * at the initial time and call init() function of #tdm_backend_module.
700 typedef struct _tdm_backend_module
702 const char *name; /**< The module name of a backend module */
703 const char *vendor; /**< The vendor name of a backend module */
704 unsigned long abi_version; /**< The ABI version of a backend module */
707 * @brief The init function of a backend module
708 * @param[in] dpy A display object
709 * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
710 * @return The backend module data
711 * @see tdm_backend_data
713 tdm_backend_data* (*init)(tdm_display *dpy, tdm_error *error);
716 * @brief The deinit function of a backend module
717 * @param[in] bdata The backend module data
719 void (*deinit)(tdm_backend_data *bdata);
720 } tdm_backend_module;
723 * @brief Register the backend display functions to a display
724 * @param[in] dpy A display object
725 * @param[in] func_display display functions
726 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
727 * @see tdm_backend_register_func_pp, tdm_backend_register_func_capture
729 * A backend module @b SHOULD set the backend display functions at least.
731 tdm_error tdm_backend_register_func_display(tdm_display *dpy, tdm_func_display *func_display);
734 * @brief Register the backend pp functions to a display
735 * @param[in] dpy A display object
736 * @param[in] func_pp pp functions
737 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
738 * @see tdm_backend_register_func_display, tdm_backend_register_func_capture
740 * A backend module doesn'tcan skip to register the backend pp functions
741 * if a hardware doesn't have the memory-to-memory converting device.
743 tdm_error tdm_backend_register_func_pp(tdm_display *dpy, tdm_func_pp *func_pp);
746 * @brief Register the backend capture functions to a display
747 * @param[in] dpy A display object
748 * @param[in] func_capture capture functions
749 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
750 * @see tdm_backend_register_func_display, tdm_backend_register_func_pp
752 * A backend module can skip to register the backend capture functions
753 * if a hardware doesn't have the capture device.
755 tdm_error tdm_backend_register_func_capture(tdm_display *dpy, tdm_func_capture *func_capture);
758 * @brief Increase the ref_count of a TDM buffer
760 * TDM has its own buffer release mechanism to let an frontend user know when a TDM buffer
761 * becomes available for a next job. A TDM buffer can be used for TDM to show
762 * it on screen or to capture an output and a layer. After all operations,
763 * TDM will release it immediately when TDM doesn't need it any more.
764 * @param[in] buffer A TDM buffer
765 * @return A buffer itself. Otherwise, NULL.
766 * @see tdm_buffer_unref_backend
768 * - This function @b SHOULD be paired with #tdm_buffer_unref_backend. \n
769 * - For example, this function @b SHOULD be called in case that a backend module uses the TDM
770 * buffer of a layer for capturing a output or a layer to avoid tearing issue.
772 tbm_surface_h tdm_buffer_ref_backend(tbm_surface_h buffer);
775 * @brief Decrease the ref_count of a TDM buffer
776 * @param[in] buffer A TDM buffer
777 * @see tdm_buffer_ref_backend
779 void tdm_buffer_unref_backend(tbm_surface_h buffer);
782 * @brief The destroy handler of a TDM buffer
783 * @param[in] buffer A TDM buffer
784 * @param[in] user_data user data
785 * @see tdm_buffer_add_destroy_handler, tdm_buffer_remove_destroy_handler
787 typedef void (*tdm_buffer_destroy_handler)(tbm_surface_h buffer, void *user_data);
790 * @brief Add a destroy handler to a TDM buffer
791 * @param[in] buffer A TDM buffer
792 * @param[in] func A destroy handler
793 * @param[in] user_data user data
794 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
795 * @see tdm_buffer_remove_destroy_handler
797 * A backend module can add a TDM buffer destroy handler to a TDM buffer which
798 * is a #tbm_surface_h object. When the TDM buffer is destroyed, this handler will
801 tdm_error tdm_buffer_add_destroy_handler(tbm_surface_h buffer, tdm_buffer_destroy_handler func, void *user_data);
804 * @brief Remove a destroy handler from a TDM buffer
805 * @param[in] buffer A TDM buffer
806 * @param[in] func A destroy handler
807 * @param[in] user_data user data
808 * @see tdm_buffer_add_destroy_handler
810 void tdm_buffer_remove_destroy_handler(tbm_surface_h buffer, tdm_buffer_destroy_handler func, void *user_data);
817 #endif /* _TDM_BACKEND_H_ */