include/tdm_backend.h

   1 /**************************************************************************
   2
   3 libtdm
   4
   5 Copyright 2015 Samsung Electronics co., Ltd. All Rights Reserved.
   6
   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>
  13
  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:
  21
  22 The above copyright notice and this permission notice (including the
  23 next paragraph) shall be included in all copies or substantial portions
  24 of the Software.
  25
  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.
  33
  34 **************************************************************************/
  35
  36 #ifndef _TDM_BACKEND_H_
  37 #define _TDM_BACKEND_H_
  38
  39 #include <tbm_surface.h>
  40
  41 #include "tdm_types.h"
  42
  43 #ifdef __cplusplus
  44 extern "C" {
  45 #endif
  46
  47 /**
  48  * @file tdm_backend.h
  49  * @brief The backend header file of TDM to implement a TDM backend module.
  50  * @par Example
  51  * @code
  52    #include <tdm_backend.h>
  53  * @endcode
  54  */
  55
  56 /**
  57  * @brief The backend module data
  58  * @details
  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  * @remark It @b SHOULD be freed in the deinit() function of #tdm_backend_module.
  62  * @see tdm_backend_module, tdm_backend_module
  63  */
  64 typedef void tdm_backend_data;
  65
  66 /**
  67  * @brief The display capabilities structure of a backend module
  68  * @remark A backend module @b SHOULD fill this structure to let frontend know the
  69  * backend display capabilities.
  70  * @see The display_get_capabilitiy() function of #tdm_func_display
  71  */
  72 typedef struct _tdm_caps_display
  73 {
  74     int max_layer_count;    /**< The maximum layer count. -1 means "not defined" */
  75 } tdm_caps_display;
  76
  77 /**
  78  * @brief The capabilities structure of a output object
  79  * @details
  80  * If a output device has the size restriction, a backend module can let a user
  81  * know it with min_w, min_h, max_w, max_h, preferred_align variables.
  82  * @remark A backend module @b SHOULD fill this structure to let frontend know the
  83  * backend output capabilities.
  84  * @see The output_get_capability() function of #tdm_func_display
  85  */
  86 typedef struct _tdm_caps_output
  87 {
  88     tdm_output_conn_status status;  /**< The connection status */
  89     tdm_output_type type;           /**< The connection type */
  90     unsigned int type_id;           /**< The connection type id */
  91
  92     unsigned int mode_count;        /**< The count of available modes */
  93     tdm_output_mode *modes;         /**< The array of available modes */
  94
  95     unsigned int prop_count;        /**< The count of available properties */
  96     tdm_prop *props;                /**< The array of available properties */
  97
  98     unsigned int mmWidth;           /**< The physical width (milimeter) */
  99     unsigned int mmHeight;          /**< The physical height (milimeter) */
 100     unsigned int subpixel;          /**< The subpixel */
 101
 102     int min_w;              /**< The minimun width. -1 means "not defined" */
 103     int min_h;              /**< The minimun height. -1 means "not defined" */
 104     int max_w;              /**< The maximum width. -1 means "not defined" */
 105     int max_h;              /**< The maximum height. -1 means "not defined" */
 106     int preferred_align;    /**< The prefered align. -1 means "not defined" */
 107 } tdm_caps_output;
 108
 109 /**
 110  * @brief The capabilities structure of a layer object
 111  * @remark A backend module @b SHOULD fill this structure to let frontend know the
 112  * backend layer capabilities.
 113  * @see The layer_get_capability() function of #tdm_func_display
 114  */
 115 typedef struct _tdm_caps_layer
 116 {
 117     tdm_layer_capability capabilities;  /**< The capabilities of layer */
 118
 119     /**
 120      * The z-order
 121      * - The zpos of GRAPHIC layers starts from 0, and it is @b non-changeable.\n
 122      * - The zpos of VIDEO layers is less than graphic layers or more than graphic layers.
 123      * ie, -1, -2, 4, 5 (if 0 <= GRAPHIC layer's zpos < 4).. It is @b changeable
 124      * by layer_set_video_pos() function of #tdm_func_display
 125     */
 126     int zpos;
 127
 128     unsigned int format_count;      /**< The count of available formats */
 129     tbm_format *formats;            /**< The array of available formats */
 130
 131     unsigned int prop_count;        /**< The count of available properties */
 132     tdm_prop *props;                /**< The array of available properties */
 133 } tdm_caps_layer;
 134
 135 /**
 136  * @brief The capabilities structure of a pp object
 137  * @details
 138  * If a pp device has the size restriction, a backend module can let a user
 139  * know it with min_w, min_h, max_w, max_h, preferred_align variables.
 140  * @remark A backend module @b SHOULD fill this structure to let frontend know the
 141  * backend pp capabilities if pp is available.
 142  * @see The display_get_pp_capability() function of #tdm_func_display
 143  */
 144 typedef struct _tdm_caps_pp
 145 {
 146     tdm_pp_capability capabilities; /**< The capabilities of pp */
 147
 148     unsigned int format_count;      /**< The count of available formats */
 149     tbm_format *formats;            /**< The array of available formats */
 150
 151     int min_w;              /**< The minimun width. -1 means "not defined" */
 152     int min_h;              /**< The minimun height. -1 means "not defined" */
 153     int max_w;              /**< The maximum width. -1 means "not defined" */
 154     int max_h;              /**< The maximum height. -1 means "not defined" */
 155     int preferred_align;    /**< The prefered align. -1 means "not defined" */
 156 } tdm_caps_pp;
 157
 158 /**
 159  * @brief The capabilities structure of a capture object
 160  * @details
 161  * If a capture device has the size restriction, a backend module can let a user
 162  * know it with min_w, min_h, max_w, max_h, preferred_align variables.
 163  * @remark A backend module @b SHOULD fill this structure to let frontend know the
 164  * backend capture capabilities if capture is available.
 165  * @see The display_get_capture_capability() function of #tdm_func_display
 166  */
 167 typedef struct _tdm_caps_capture
 168 {
 169     tdm_capture_capability capabilities;    /**< The capabilities of capture */
 170
 171     unsigned int format_count;      /**< The count of available formats */
 172     tbm_format *formats;            /**< The array of available formats */
 173
 174     int min_w;              /**< The minimun width. -1 means "not defined" */
 175     int min_h;              /**< The minimun height. -1 means "not defined" */
 176     int max_w;              /**< The maximum width. -1 means "not defined" */
 177     int max_h;              /**< The maximum height. -1 means "not defined" */
 178     int preferred_align;    /**< The prefered align. -1 means "not defined" */
 179 } tdm_caps_capture;
 180
 181 /**
 182  * @brief The display functions for a backend module.
 183  */
 184 typedef struct _tdm_func_display
 185 {
 186     /**
 187      * @brief Get the display capabilities of a backend module
 188      * @details TDM calls this function at the initial time. And at the update time also.
 189      * #tdm_caps_display containes the max layer count information, etc.
 190      * @param[in] bdata The backend module data
 191      * @param[out] caps The display capabilities of a backend module
 192      * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 193      */
 194     tdm_error    (*display_get_capabilitiy)(tdm_backend_data *bdata, tdm_caps_display *caps);
 195
 196     /**
 197      * @brief Get the pp capabilities of a backend module
 198      * @details This function can be NULL if a backend module doesn't have the pp capability.
 199      * TDM calls this function at the initial time if available. And at the update time also.
 200      * #tdm_caps_pp containes avaiable formats, size restriction information, etc.
 201      * @param[in] bdata The backend module data
 202      * @param[out] caps The pp capabilities of a backend module
 203      * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 204      * @see tdm_backend_register_func_pp
 205      */
 206     tdm_error    (*display_get_pp_capability)(tdm_backend_data *bdata, tdm_caps_pp *caps);
 207
 208     /**
 209      * @brief Get the capture capabilities of a backend module
 210      * @details This function can be NULL if a backend module doesn't have the capture capability.
 211      * TDM calls this function at the initial time if available. And at the update time also.
 212      * #tdm_caps_capture containes avaiable formats, size restriction information, etc.
 213      * @param[in] bdata The backend module data
 214      * @param[out] caps The capture capabilities of a backend module
 215      * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 216      * @see tdm_backend_register_func_capture
 217      */
 218     tdm_error    (*display_get_capture_capability)(tdm_backend_data *bdata, tdm_caps_capture *caps);
 219
 220     /**
 221      * @brief Get a output array of a backend module
 222      * @details A backend module @b SHOULD return the newly-allocated output array.
 223      * it will be freed in frontend.
 224      * @param[in] bdata The backend module data
 225      * @param[out] count The count of outputs
 226      * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
 227      * @return A output array which is newly-allocated
 228      * @see tdm_backend_register_func_capture
 229      */
 230     tdm_output **(*display_get_outputs)(tdm_backend_data *bdata, int *count, tdm_error *error);
 231
 232     /**
 233      * @brief Get the file descriptor of a backend module
 234      * @details If a backend module handles one more fds, a backend module can return epoll's fd
 235      * which is watching backend device fds.
 236      * @param[in] bdata The backend module data
 237      * @param[out] fd The fd of a backend module
 238      * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 239      * @see display_handle_events() function of #tdm_func_display
 240      */
 241     tdm_error    (*display_get_fd)(tdm_backend_data *bdata, int *fd);
 242
 243     /**
 244      * @brief Handle the events which happen on the fd of a backend module
 245      * @param[in] bdata The backend module data
 246      * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 247      */
 248     tdm_error    (*display_handle_events)(tdm_backend_data *bdata);
 249
 250     /**
 251      * @brief Create a pp object of a backend module
 252      * @param[in] bdata The backend module data
 253      * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
 254      * @return A pp object
 255      * @see pp_destroy() function of #tdm_func_pp
 256      */
 257     tdm_pp*      (*display_create_pp)(tdm_backend_data *bdata, tdm_error *error);
 258
 259     /**
 260      * @brief Get the capabilities of a output object
 261      * #tdm_caps_output containes connection, modes, avaiable properties, size restriction information, etc.
 262      * @param[in] output A output object
 263      * @param[out] caps The capabilities of a output object
 264      * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 265      */
 266     tdm_error    (*output_get_capability)(tdm_output *output, tdm_caps_output *caps);
 267
 268     /**
 269      * @brief Get a layer array of a output object
 270      * @details A backend module @b SHOULD return the newly-allocated layer array.
 271      * it will be freed in frontend.
 272      * @param[in] output A output object
 273      * @param[out] count The count of layers
 274      * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
 275      * @return A layer array which is newly-allocated
 276      */
 277     tdm_layer  **(*output_get_layers)(tdm_output *output, int *count, tdm_error *error);
 278
 279     /**
 280      * @brief Set the property which has a given id
 281      * @param[in] output A output object
 282      * @param[in] id The property id
 283      * @param[in] value The value
 284      * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 285      */
 286     tdm_error    (*output_set_property)(tdm_output *output, unsigned int id, tdm_value value);
 287
 288     /**
 289      * @brief Get the property which has a given id
 290      * @param[in] output A output object
 291      * @param[in] id The property id
 292      * @param[out] value The value
 293      * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 294      */
 295     tdm_error    (*output_get_property)(tdm_output *output, unsigned int id, tdm_value *value);
 296
 297     /**
 298      * @brief Wait for VBLANK
 299      * @remark After interval vblanks, a backend module @b SHOULD call a user
 300      * vblank handler.
 301      * @param[in] output A output object
 302      * @param[in] interval vblank interval
 303      * @param[in] sync 0: asynchronous, 1:synchronous
 304      * @param[in] user_data The user data
 305      * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 306      * @see #tdm_output_vblank_handler
 307      */
 308     tdm_error    (*output_wait_vblank)(tdm_output *output, int interval, int sync, void *user_data);
 309
 310     /**
 311      * @brief Set a user vblank handler
 312      * @param[in] output A output object
 313      * @param[in] func A user vblank handler
 314      * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 315      */
 316     tdm_error    (*output_set_vblank_handler)(tdm_output *output, tdm_output_vblank_handler func);
 317
 318     /**
 319      * @brief Commit changes for a output object
 320      * @remark After all change of a output object are applied, a backend module
 321      * @b SHOULD call a user commit handler.
 322      * @param[in] output A output object
 323      * @param[in] sync 0: asynchronous, 1:synchronous
 324      * @param[in] user_data The user data
 325      * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 326      */
 327     tdm_error    (*output_commit)(tdm_output *output, int sync, void *user_data);
 328
 329     /**
 330      * @brief Set a user commit handler
 331      * @param[in] output A output object
 332      * @param[in] func A user commit handler
 333      * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 334      */
 335     tdm_error    (*output_set_commit_handler)(tdm_output *output, tdm_output_commit_handler func);
 336
 337     /**
 338      * @brief Set DPMS of a output object
 339      * @param[in] output A output object
 340      * @param[in] dpms_value DPMS value
 341      * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 342      */
 343     tdm_error    (*output_set_dpms)(tdm_output *output, tdm_output_dpms dpms_value);
 344
 345     /**
 346      * @brief Get DPMS of a output object
 347      * @param[in] output A output object
 348      * @param[out] dpms_value DPMS value
 349      * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 350      */
 351     tdm_error    (*output_get_dpms)(tdm_output *output, tdm_output_dpms *dpms_value);
 352
 353     /**
 354      * @brief Set one of available modes of a output object
 355      * @param[in] output A output object
 356      * @param[in] mode A output mode
 357      * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 358      */
 359     tdm_error    (*output_set_mode)(tdm_output *output, const tdm_output_mode *mode);
 360
 361     /**
 362      * @brief Get the mode of a output object
 363      * @param[in] output A output object
 364      * @param[out] mode A output mode
 365      * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 366      */
 367     tdm_error    (*output_get_mode)(tdm_output *output, const tdm_output_mode **mode);
 368
 369     /**
 370      * @brief Create a capture object of a output object
 371      * @param[in] output A output object
 372      * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
 373      * @return A capture object
 374      * @see capture_destroy() function of #tdm_func_capture
 375      */
 376     tdm_capture *(*output_create_capture)(tdm_output *output, tdm_error *error);
 377
 378     /**
 379      * @brief Get the capabilities of a layer object
 380      * #tdm_caps_layer containes avaiable formats/properties, zpos information, etc.
 381      * @param[in] layer A layer object
 382      * @param[out] caps The capabilities of a layer object
 383      * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 384      */
 385     tdm_error    (*layer_get_capability)(tdm_layer *layer, tdm_caps_layer *caps);
 386
 387     /**
 388      * @brief Set the property which has a given id.
 389      * @param[in] layer A layer object
 390      * @param[in] id The property id
 391      * @param[in] value The value
 392      * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 393      */
 394     tdm_error    (*layer_set_property)(tdm_layer *layer, unsigned int id, tdm_value value);
 395
 396     /**
 397      * @brief Get the property which has a given id.
 398      * @param[in] layer A layer object
 399      * @param[in] id The property id
 400      * @param[out] value The value
 401      * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 402      */
 403     tdm_error    (*layer_get_property)(tdm_layer *layer, unsigned int id, tdm_value *value);
 404
 405     /**
 406      * @brief Set the geometry information to a layer object
 407      * @details The geometry information will be applied when the output object
 408      * of a layer object is committed.
 409      * @param[in] layer A layer object
 410      * @param[in] info The geometry information
 411      * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 412      * @see output_commit() function of #tdm_func_display
 413      */
 414     tdm_error    (*layer_set_info)(tdm_layer *layer, tdm_info_layer *info);
 415
 416     /**
 417      * @brief Get the geometry information to a layer object
 418      * @param[in] layer A layer object
 419      * @param[out] info The geometry information
 420      * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 421      */
 422     tdm_error    (*layer_get_info)(tdm_layer *layer, tdm_info_layer *info);
 423
 424     /**
 425      * @brief Set a TDM buffer to a layer object
 426      * @details A TDM buffer will be applied when the output object
 427      * of a layer object is committed.
 428      * @param[in] layer A layer object
 429      * @param[in] buffer A TDM buffer
 430      * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 431      * @see output_commit() function of #tdm_func_display
 432      */
 433     tdm_error    (*layer_set_buffer)(tdm_layer *layer, tbm_surface_h buffer);
 434
 435     /**
 436      * @brief Unset a TDM buffer from a layer object
 437      * @details When this function is called, a current showing buffer will be
 438      * disappeared from screen. Then nothing is showing on a layer object.
 439      * @param[in] layer A layer object
 440      * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 441      */
 442     tdm_error    (*layer_unset_buffer)(tdm_layer *layer);
 443
 444     /**
 445      * @brief Set the zpos for a VIDEO layer object
 446      * @details Especially this function is for a VIDEO layer. The zpos of
 447      * GRAPHIC layers can't be changed.
 448      * @param[in] layer A layer object
 449      * @param[in] zpos z-order
 450      * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 451      * @see @tdm_layer_capability
 452      */
 453     tdm_error    (*layer_set_video_pos)(tdm_layer *layer, int zpos);
 454
 455     /**
 456      * @brief Create a capture object of a layer object
 457      * @param[in] output A output object
 458      * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
 459      * @return A capture object
 460      * @see capture_destroy() function of #tdm_func_capture
 461      */
 462     tdm_capture *(*layer_create_capture)(tdm_layer *layer, tdm_error *error);
 463 } tdm_func_display;
 464
 465 /**
 466  * @brief The done handler of a pp object
 467  */
 468 typedef void (*tdm_pp_done_handler)(tdm_pp *pp, tbm_surface_h src, tbm_surface_h dst, void *user_data);
 469
 470 /**
 471  * @brief The pp functions for a backend module.
 472  */
 473 typedef struct _tdm_func_pp
 474 {
 475     /**
 476      * @brief Destroy a pp object
 477      * @param[in] pp A pp object
 478      * @see display_create_pp() function of #tdm_func_display
 479      */
 480     void         (*pp_destroy)(tdm_pp *pp);
 481
 482     /**
 483      * @brief Set the geometry information to a pp object
 484      * @details The geometry information will be applied when the pp object is committed.
 485      * @param[in] pp A pp object
 486      * @param[in] info The geometry information
 487      * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 488      * @see pp_commit() function of #tdm_func_pp
 489      */
 490     tdm_error    (*pp_set_info)(tdm_pp *pp, tdm_info_pp *info);
 491
 492     /**
 493      * @brief Attach a source buffer and a destination buffer to a pp object
 494      * @details When pp_commit() function is called, a backend module converts
 495      * the image of a source buffer to a destination buffer.
 496      * @param[in] pp A pp object
 497      * @param[in] src A source buffer
 498      * @param[in] dst A destination buffer
 499      * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 500      * @see tdm_pp_done_handler
 501      * @see pp_set_info() function of #tdm_func_pp
 502      * @see pp_commit() function of #tdm_func_pp
 503      */
 504     tdm_error    (*pp_attach)(tdm_pp *pp, tbm_surface_h src, tbm_surface_h dst);
 505
 506     /**
 507      * @brief Commit changes for a pp object
 508      * @param[in] pp A pp object
 509      * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 510      */
 511     tdm_error    (*pp_commit)(tdm_pp *pp);
 512
 513     /**
 514      * @brief Set a user done handler to a pp object
 515      * @param[in] pp A pp object
 516      * @param[in] func A user done handler
 517      * @param[in] user_data user data
 518      * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 519      * @remark When pp operation is done, a backend module @b SHOULD call #tdm_pp_done_handler.
 520      */
 521     tdm_error    (*pp_set_done_handler)(tdm_pp *pp, tdm_pp_done_handler func, void *user_data);
 522 } tdm_func_pp;
 523
 524 /**
 525  * @brief The done handler of a capture object
 526  */
 527 typedef void (*tdm_capture_done_handler)(tdm_capture *capture, tbm_surface_h buffer, void *user_data);
 528
 529 /**
 530  * @brief The capture functions for a backend module.
 531  */
 532 typedef struct _tdm_func_capture
 533 {
 534     /**
 535      * @brief Destroy a capture object
 536      * @param[in] capture A capture object
 537      * @see output_create_capture() function of #tdm_func_display
 538      * @see layer_create_capture() function of #tdm_func_display
 539      */
 540     void         (*capture_destroy)(tdm_capture *capture);
 541
 542     /**
 543      * @brief Set the geometry information to a capture object
 544      * @details The geometry information will be applied when the capture object is committed.
 545      * @param[in] capture A capture object
 546      * @param[in] info The geometry information
 547      * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 548      * @see capture_commit() function of #tdm_func_capture
 549      */
 550     tdm_error    (*capture_set_info)(tdm_capture *capture, tdm_info_capture *info);
 551
 552     /**
 553      * @brief Attach a TDM buffer to a capture object
 554      * @details When capture_commit() function is called, a backend module dumps
 555      * a output or a layer to a TDM buffer.
 556      * @param[in] capture A capture object
 557      * @param[in] buffer A TDM buffer
 558      * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 559      * @see tdm_capture_done_handler
 560      * @see capture_commit() function of #tdm_func_capture
 561      */
 562     tdm_error    (*capture_attach)(tdm_capture *capture, tbm_surface_h buffer);
 563
 564     /**
 565      * @brief Commit changes for a capture object
 566      * @param[in] capture A capture object
 567      * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 568      */
 569     tdm_error    (*capture_commit)(tdm_capture *capture);
 570
 571     /**
 572      * @brief Set a user done handler to a capture object
 573      * @param[in] capture A capture object
 574      * @param[in] func A user done handler
 575      * @param[in] user_data user data
 576      * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 577      * @remark When capture operation is done, a backend module @b SHOULD call #tdm_capture_done_handler.
 578      */
 579     tdm_error    (*capture_set_done_handler)(tdm_capture *capture, tdm_capture_done_handler func, void *user_data);
 580 } tdm_func_capture;
 581
 582 /*
 583  * ABI versions.  Each version has a major and minor revision.  Modules
 584  * using lower minor revisions must work with servers of a higher minor
 585  * revision.  There is no compatibility between different major revisions.
 586  * Whenever the ABI_ANSIC_VERSION is changed, the others must also be
 587  * changed.  The minor revision mask is 0x0000FFFF and the major revision
 588  * mask is 0xFFFF0000.
 589  */
 590 #define TDM_BACKEND_MINOR_VERSION_MASK  0x0000FFFF
 591 #define TDM_BACKEND_MAJOR_VERSION_MASK  0xFFFF0000
 592 #define TDM_BACKEND_GET_ABI_MINOR(v)    ((v) & TDM_BACKEND_MINOR_VERSION_MASK)
 593 #define TDM_BACKEND_GET_ABI_MAJOR(v)    (((v) & TDM_BACKEND_MAJOR_VERSION_MASK) >> 16)
 594
 595 #define SET_TDM_BACKEND_ABI_VERSION(major, minor) \
 596         (((major) << 16) & TDM_BACKEND_MAJOR_VERSION_MASK) | \
 597         ((major) & TDM_BACKEND_MINOR_VERSION_MASK)
 598 #define TDM_BACKEND_ABI_VERSION     SET_TDM_BACKEND_ABI_VERSION(1, 1)
 599
 600 /**
 601  * @brief The backend module information of the entry point to initialize a TDM
 602  * backend module.
 603  * @details
 604  * A backend module @b SHOULD define the global data symbol of which name is
 605  * @b "tdm_backend_module_data". TDM will read this symbol, @b "tdm_backend_module_data",
 606  * at the initial time and call init() function of #tdm_backend_module.
 607  */
 608 typedef struct _tdm_backend_module
 609 {
 610     const char *name;           /**< The module name of a backend module */
 611     const char *vendor;         /**< The vendor name of a backend module */
 612     unsigned long abi_version;  /**< The ABI version of a backend module */
 613
 614     /**
 615      * @brief The init function of a backend module
 616      * @param[in] dpy A display object
 617      * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
 618      * @return The backend module data
 619      * @see tdm_backend_data
 620      */
 621     tdm_backend_data* (*init)(tdm_display *dpy, tdm_error *error);
 622
 623     /**
 624      * @brief The deinit function of a backend module
 625      * @param[in] bdata The backend module data
 626      */
 627     void (*deinit)(tdm_backend_data *bdata);
 628 } tdm_backend_module;
 629
 630 /**
 631  * @brief Register the backend display functions to a display
 632  * @details
 633  * A backend module @b SHOULD set the backend display functions at least.
 634  * @param[in] dpy A display object
 635  * @param[in] func_display display functions
 636  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 637  * @see tdm_backend_register_func_pp, tdm_backend_register_func_capture
 638  */
 639 tdm_error tdm_backend_register_func_display(tdm_display *dpy, tdm_func_display *func_display);
 640
 641 /**
 642  * @brief Register the backend pp functions to a display
 643  * @details
 644  * A backend module can skip to register the backend pp functions
 645  * if hardware device doesn't supports the memory to memory converting.
 646  * @param[in] dpy A display object
 647  * @param[in] func_pp pp functions
 648  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 649  * @see tdm_backend_register_func_display, tdm_backend_register_func_capture
 650  */
 651 tdm_error tdm_backend_register_func_pp(tdm_display *dpy, tdm_func_pp *func_pp);
 652
 653 /**
 654  * @brief Register the backend capture functions to a display
 655  * @details
 656  * A backend module can skip to register the backend capture functions
 657  * if hardware device doesn't supports the memory to memory converting.
 658  * @param[in] dpy A display object
 659  * @param[in] func_capture capture functions
 660  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 661  * @see tdm_backend_register_func_display, tdm_backend_register_func_pp
 662  */
 663 tdm_error tdm_backend_register_func_capture(tdm_display *dpy, tdm_func_capture *func_capture);
 664
 665 /**
 666  * @brief Increase the ref_count of a TDM buffer
 667  * @details
 668  * TDM has its own buffer release mechanism to let an frontend user know when a TDM buffer
 669  * becomes available for a next job. A TDM buffer can be used for TDM to show
 670  * it on screen or to capture an output and a layer. After all operations,
 671  * TDM will release it immediately when TDM doesn't need it any more.
 672  * @param[in] buffer A TDM buffer
 673  * @return A buffer itself. Otherwise, NULL.
 674  * @remark
 675  * - This function @b SHOULD be paired with #tdm_buffer_unref_backend. \n
 676  * - For example, this function @b SHOULD be called in case that a backend module uses the TDM
 677  * buffer of a layer for capturing a output or a layer to avoid tearing issue.
 678  * @see tdm_buffer_unref_backend
 679  */
 680 tbm_surface_h tdm_buffer_ref_backend(tbm_surface_h buffer);
 681
 682 /**
 683  * @brief Decrease the ref_count of a TDM buffer
 684  * @param[in] buffer A TDM buffer
 685  * @see tdm_buffer_ref_backend
 686  */
 687 void          tdm_buffer_unref_backend(tbm_surface_h buffer);
 688
 689 /**
 690  * @brief The destroy handler of a TDM buffer
 691  * @param[in] buffer A TDM buffer
 692  * @param[in] user_data user data
 693  * @see tdm_buffer_add_destroy_handler, tdm_buffer_remove_destroy_handler
 694  */
 695 typedef void (*tdm_buffer_destroy_handler)(tbm_surface_h buffer, void *user_data);
 696
 697 /**
 698  * @brief Add a destroy handler to a TDM buffer
 699  * @details
 700  * A backend module can add a TDM buffer destroy handler to a TDM buffer which
 701  * is a #tbm_surface_h object. When the TDM buffer is destroyed, this handler will
 702  * be called.
 703  * @param[in] buffer A TDM buffer
 704  * @param[in] func A destroy handler
 705  * @param[in] user_data user data
 706  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 707  * @see tdm_buffer_remove_destroy_handler
 708  */
 709 tdm_error     tdm_buffer_add_destroy_handler(tbm_surface_h buffer, tdm_buffer_destroy_handler func, void *user_data);
 710
 711 /**
 712  * @brief Remove a destroy handler from a TDM buffer
 713  * @param[in] buffer A TDM buffer
 714  * @param[in] func A destroy handler
 715  * @param[in] user_data user data
 716  * @see tdm_buffer_add_destroy_handler
 717  */
 718 void          tdm_buffer_remove_destroy_handler(tbm_surface_h buffer, tdm_buffer_destroy_handler func, void *user_data);
 719
 720
 721 #ifdef __cplusplus
 722 }
 723 #endif
 724
 725 #endif /* _TDM_BACKEND_H_ */