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  * @see tdm_backend_module, tdm_backend_module
  62  */
  63 typedef void tdm_backend_data;
  64
  65 /**
  66  * @brief The output status handler
  67  * @details This handler will be called when the status of a output object is
  68  * changed in runtime.
  69  */
  70 typedef void (*tdm_output_status_handler)(tdm_output *output,
  71                                           tdm_output_conn_status status,
  72                                           void *user_data);
  73
  74 /**
  75  * @brief The display capabilities structure of a backend module
  76  * @see The display_get_capabilitiy() function of #tdm_func_display
  77  */
  78 typedef struct _tdm_caps_display {
  79         int max_layer_count;    /**< The maximum layer count. -1 means "not defined" */
  80 } tdm_caps_display;
  81
  82 /**
  83  * @brief The capabilities structure of a output object
  84  * @see The output_get_capability() function of #tdm_func_output
  85  */
  86 typedef struct _tdm_caps_output {
  87         char maker[TDM_NAME_LEN];       /**< The output maker */
  88         char model[TDM_NAME_LEN];       /**< The output model */
  89         char name[TDM_NAME_LEN];        /**< The output name */
  90
  91         tdm_output_conn_status status;  /**< The connection status */
  92         tdm_output_type type;           /**< The connection type */
  93         unsigned int type_id;           /**< The connection type id */
  94
  95         unsigned int mode_count;        /**< The count of available modes */
  96         tdm_output_mode
  97         *modes;         /**< The @b newly-allocated array of modes. will be freed in frontend. */
  98
  99         unsigned int prop_count;        /**< The count of available properties */
 100         tdm_prop *props;                /**< The @b newly-allocated array of properties. will be freed in frontend. */
 101
 102         unsigned int mmWidth;           /**< The physical width (milimeter) */
 103         unsigned int mmHeight;          /**< The physical height (milimeter) */
 104         unsigned int subpixel;          /**< The subpixel */
 105
 106         int min_w;              /**< The minimun width. -1 means "not defined" */
 107         int min_h;              /**< The minimun height. -1 means "not defined" */
 108         int max_w;              /**< The maximum width. -1 means "not defined" */
 109         int max_h;              /**< The maximum height. -1 means "not defined" */
 110         int preferred_align;    /**< The prefered align. -1 means "not defined" */
 111 } tdm_caps_output;
 112
 113 /**
 114  * @brief The capabilities structure of a layer object
 115  * @see The layer_get_capability() function of #tdm_func_layer
 116  */
 117 typedef struct _tdm_caps_layer {
 118         tdm_layer_capability capabilities;  /**< The capabilities of layer */
 119
 120         /**
 121          * The z-order
 122          * GRAPHIC layers are non-changeable. The zpos of GRAPHIC layers starts
 123          * from 0. If there are 4 GRAPHIC layers, The zpos SHOULD be 0, 1, 2, 3.\n
 124          * But the zpos of VIDEO layer is changeable by layer_set_video_pos() function
 125          * of #tdm_func_layer. And The zpos of VIDEO layers is less than GRAPHIC
 126          * layers or more than GRAPHIC layers.
 127          * ie, ..., -2, -1, 4, 5, ... (if 0 <= GRAPHIC layer's zpos < 4).
 128          * The zpos of VIDEO layers is @b relative. It doesn't need to start
 129          * from -1 or 4. Let's suppose that there are two VIDEO layers.
 130          * One has -2 zpos. Another has -4 zpos. Then -2 Video layer is higher
 131          * than -4 VIDEO layer.
 132         */
 133         int zpos;
 134
 135         unsigned int format_count;      /**< The count of available formats */
 136         tbm_format
 137         *formats;            /**< The @b newly-allocated array of formats. will be freed in frontend. */
 138
 139         unsigned int prop_count;        /**< The count of available properties */
 140         tdm_prop *props;                /**< The @b newly-allocated array of properties. will be freed in frontend. */
 141 } tdm_caps_layer;
 142
 143 /**
 144  * @brief The capabilities structure of a pp object
 145  * @see The display_get_pp_capability() function of #tdm_func_display
 146  */
 147 typedef struct _tdm_caps_pp {
 148         tdm_pp_capability capabilities; /**< The capabilities of pp */
 149
 150         unsigned int format_count;      /**< The count of available formats */
 151         tbm_format
 152         *formats;            /**< The @b newly-allocated array. will be freed in frontend. */
 153
 154         int min_w;              /**< The minimun width. -1 means "not defined" */
 155         int min_h;              /**< The minimun height. -1 means "not defined" */
 156         int max_w;              /**< The maximum width. -1 means "not defined" */
 157         int max_h;              /**< The maximum height. -1 means "not defined" */
 158         int preferred_align;    /**< The prefered align. -1 means "not defined" */
 159 } tdm_caps_pp;
 160
 161 /**
 162  * @brief The capabilities structure of a capture object
 163  * @see The display_get_capture_capability() function of #tdm_func_display
 164  */
 165 typedef struct _tdm_caps_capture {
 166         tdm_capture_capability capabilities;    /**< The capabilities of capture */
 167
 168         unsigned int format_count;      /**< The count of available formats */
 169         tbm_format
 170         *formats;            /**< The @b newly-allocated array of formats. will be freed in frontend. */
 171
 172         int min_w;              /**< The minimun width. -1 means "not defined" */
 173         int min_h;              /**< The minimun height. -1 means "not defined" */
 174         int max_w;              /**< The maximum width. -1 means "not defined" */
 175         int max_h;              /**< The maximum height. -1 means "not defined" */
 176         int preferred_align;    /**< The prefered align. -1 means "not defined" */
 177 } tdm_caps_capture;
 178
 179 /**
 180  * @brief The display functions for a backend module.
 181  */
 182 typedef struct _tdm_func_display {
 183         /**
 184          * @brief Get the display capabilities of a backend module
 185          * @param[in] bdata The backend module data
 186          * @param[out] caps The display capabilities of a backend module
 187          * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 188          * @remark
 189          * A backend module @b SHOULD implement this function. TDM calls this function
 190          * not only at the initial time, but also at the update time when new output
 191          * is connected.\n
 192          * If a hardware has the restriction of the number of max usable layer count,
 193          * a backend module can set the max count to max_layer_count of #tdm_caps_display
 194          * structure. Otherwise, set -1.
 195          */
 196         tdm_error (*display_get_capabilitiy)(tdm_backend_data *bdata,
 197                                              tdm_caps_display *caps);
 198
 199         /**
 200          * @brief Get the pp capabilities of a backend module
 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          * @remark
 206          * TDM calls this function not only at the initial time, but also at the update
 207          * time when new output is connected.\n
 208          * A backend module doesn't need to implement this function if a hardware
 209          * doesn't have the memory-to-memory converting device. Otherwise, a backend module
 210          * @b SHOULD fill the #tdm_caps_pp data. #tdm_caps_pp contains the hardware
 211          * restriction information which a converting device can handle. ie, format, size, etc.
 212          */
 213         tdm_error (*display_get_pp_capability)(tdm_backend_data *bdata,
 214                                                tdm_caps_pp *caps);
 215
 216         /**
 217          * @brief Get the capture capabilities of a backend module
 218          * @param[in] bdata The backend module data
 219          * @param[out] caps The capture capabilities of a backend module
 220          * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 221          * @see tdm_backend_register_func_capture
 222          * @remark
 223          * TDM calls this function not only at the initial time, but also at the update
 224          * time when new output is connected.\n
 225          * A backend module doesn't need to implement this function if a hardware
 226          * doesn't have the capture device. Otherwise, a backend module @b SHOULD fill the
 227          * #tdm_caps_capture data. #tdm_caps_capture contains the hardware restriction
 228          * information which a capture device can handle. ie, format, size, etc.
 229          */
 230         tdm_error (*display_get_capture_capability)(tdm_backend_data *bdata,
 231                         tdm_caps_capture *caps);
 232
 233         /**
 234          * @brief Get a output array of a backend module
 235          * @param[in] bdata The backend module data
 236          * @param[out] count The count of outputs
 237          * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
 238          * @return A output array which is @b newly-allocated
 239          * @see tdm_backend_register_func_capture
 240          * @remark
 241          * A backend module @b SHOULD implement this function. TDM calls this function
 242          * not only at the initial time, but also at the update time when new output
 243          * is connected.\n
 244          * A backend module @b SHOULD return the @b newly-allocated array which contains
 245          * "tdm_output*" data. It will be freed in frontend.
 246          * @par Example
 247          * @code
 248             tdm_output**
 249             drm_display_get_outputs(tdm_backend_data *bdata, int *count, tdm_error *error)
 250             {
 251                 tdm_drm_data *drm_data = bdata;
 252                 tdm_drm_output_data *output_data = NULL;
 253                 tdm_output **outputs;
 254                 int i;
 255
 256                 (*count) = 0;
 257                 LIST_FOR_EACH_ENTRY(output_data, &drm_data->output_list, link)
 258                     (*count)++;
 259
 260                 if ((*count) == 0)
 261                 {
 262                     if (error) *error = TDM_ERROR_NONE;
 263                     return NULL;
 264                 }
 265
 266                 // will be freed in frontend
 267                 outputs = calloc(*count, sizeof(tdm_drm_output_data*));
 268                 if (!outputs)
 269                 {
 270                     (*count) = 0;
 271                     if (error) *error = TDM_ERROR_OUT_OF_MEMORY;
 272                     return NULL;
 273                 }
 274
 275                 i = 0;
 276                 LIST_FOR_EACH_ENTRY(output_data, &drm_data->output_list, link)
 277                     outputs[i++] = output_data;
 278
 279                 if (error) *error = TDM_ERROR_NONE;
 280
 281                 return outputs;
 282             }
 283          * @endcode
 284          */
 285         tdm_output **(*display_get_outputs)(tdm_backend_data *bdata, int *count,
 286                                             tdm_error *error);
 287
 288         /**
 289          * @brief Get the file descriptor of a backend module
 290          * @param[in] bdata The backend module data
 291          * @param[out] fd The fd of a backend module
 292          * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 293          * @see display_handle_events() function of #tdm_func_display
 294          * @remark
 295          * A backend module can return epoll's fd which is watching the backend device one more fds.
 296          */
 297         tdm_error (*display_get_fd)(tdm_backend_data *bdata, int *fd);
 298
 299         /**
 300          * @brief Handle the events which happens on the fd of a backend module
 301          * @param[in] bdata The backend module data
 302          * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 303          */
 304         tdm_error (*display_handle_events)(tdm_backend_data *bdata);
 305
 306         /**
 307          * @brief Create a pp object of a backend module
 308          * @param[in] bdata The backend module data
 309          * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
 310          * @return A pp object
 311          * @see pp_destroy() function of #tdm_func_pp
 312          * @remark
 313          * A backend module doesn't need to implement this function if a hardware
 314          * doesn't have the memory-to-memory converting device.
 315          */
 316         tdm_pp *(*display_create_pp)(tdm_backend_data *bdata, tdm_error *error);
 317
 318         void (*reserved1)(void);
 319         void (*reserved2)(void);
 320         void (*reserved3)(void);
 321         void (*reserved4)(void);
 322         void (*reserved5)(void);
 323         void (*reserved6)(void);
 324         void (*reserved7)(void);
 325         void (*reserved8)(void);
 326 } tdm_func_display;
 327
 328 /**
 329  * @brief The output functions for a backend module.
 330  */
 331 typedef struct _tdm_func_output {
 332         /**
 333          * @brief Get the capabilities of a output object
 334          * @param[in] output A output object
 335          * @param[out] caps The capabilities of a output object
 336          * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 337          * @remark
 338          * A backend module @b SHOULD implement this function. TDM calls this function
 339          * not only at the initial time, but also at the update time when new output
 340          * is connected.\n
 341          * #tdm_caps_output contains connection status, modes, avaiable properties,
 342          * size restriction information, etc.
 343          */
 344         tdm_error (*output_get_capability)(tdm_output *output, tdm_caps_output *caps);
 345
 346         /**
 347          * @brief Get a layer array of a output object
 348          * @param[in] output A output object
 349          * @param[out] count The count of layers
 350          * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
 351          * @return A layer array which is @b newly-allocated
 352          * @remark
 353          * A backend module @b SHOULD implement this function. TDM calls this function
 354          * not only at the initial time, but also at the update time when new output
 355          * is connected.\n
 356          * A backend module @b SHOULD return the @b newly-allocated array which contains
 357          * "tdm_layer*" data. It will be freed in frontend.
 358          */
 359         tdm_layer **(*output_get_layers)(tdm_output *output, int *count,
 360                                          tdm_error *error);
 361
 362         /**
 363          * @brief Set the property which has a given id
 364          * @param[in] output A output object
 365          * @param[in] id The property id
 366          * @param[in] value The value
 367          * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 368          */
 369         tdm_error (*output_set_property)(tdm_output *output, unsigned int id,
 370                                          tdm_value value);
 371
 372         /**
 373          * @brief Get the property which has a given id
 374          * @param[in] output A output object
 375          * @param[in] id The property id
 376          * @param[out] value The value
 377          * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 378          */
 379         tdm_error (*output_get_property)(tdm_output *output, unsigned int id,
 380                                          tdm_value *value);
 381
 382         /**
 383          * @brief Wait for VBLANK
 384          * @param[in] output A output object
 385          * @param[in] interval vblank interval
 386          * @param[in] sync 0: asynchronous, 1:synchronous
 387          * @param[in] user_data The user data
 388          * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 389          * @see output_set_vblank_handler, tdm_output_vblank_handler
 390          * @remark
 391          * A backend module @b SHOULD call a user vblank handler after interval vblanks.
 392          */
 393         tdm_error (*output_wait_vblank)(tdm_output *output, int interval, int sync,
 394                                         void *user_data);
 395
 396         /**
 397          * @brief Set a user vblank handler
 398          * @param[in] output A output object
 399          * @param[in] func A user vblank handler
 400          * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 401          */
 402         tdm_error (*output_set_vblank_handler)(tdm_output *output,
 403                                                tdm_output_vblank_handler func);
 404
 405         /**
 406          * @brief Commit changes for a output object
 407          * @param[in] output A output object
 408          * @param[in] sync 0: asynchronous, 1:synchronous
 409          * @param[in] user_data The user data
 410          * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 411          * @see output_set_commit_handler, tdm_output_commit_handler
 412          * @remark
 413          * A backend module @b SHOULD call a user commit handler after all change of
 414          * a output object are applied.
 415          */
 416         tdm_error (*output_commit)(tdm_output *output, int sync, void *user_data);
 417
 418         /**
 419          * @brief Set a user commit handler
 420          * @param[in] output A output object
 421          * @param[in] func A user commit handler
 422          * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 423          */
 424         tdm_error (*output_set_commit_handler)(tdm_output *output,
 425                                                tdm_output_commit_handler func);
 426
 427         /**
 428          * @brief Set DPMS of a output object
 429          * @param[in] output A output object
 430          * @param[in] dpms_value DPMS value
 431          * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 432          */
 433         tdm_error (*output_set_dpms)(tdm_output *output, tdm_output_dpms dpms_value);
 434
 435         /**
 436          * @brief Get DPMS of a output object
 437          * @param[in] output A output object
 438          * @param[out] dpms_value DPMS value
 439          * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 440          */
 441         tdm_error (*output_get_dpms)(tdm_output *output, tdm_output_dpms *dpms_value);
 442
 443         /**
 444          * @brief Set one of available modes of a output object
 445          * @param[in] output A output object
 446          * @param[in] mode A output mode
 447          * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 448          */
 449         tdm_error (*output_set_mode)(tdm_output *output, const tdm_output_mode *mode);
 450
 451         /**
 452          * @brief Get the mode of a output object
 453          * @param[in] output A output object
 454          * @param[out] mode A output mode
 455          * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 456          */
 457         tdm_error (*output_get_mode)(tdm_output *output, const tdm_output_mode **mode);
 458
 459         /**
 460          * @brief Create a capture object of a output object
 461          * @param[in] output A output object
 462          * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
 463          * @return A capture object
 464          * @see capture_destroy() function of #tdm_func_capture
 465          * @remark
 466          * A backend module doesn't need to implement this function if a hardware
 467          * doesn't have the capture device.
 468          */
 469         tdm_capture *(*output_create_capture)(tdm_output *output, tdm_error *error);
 470
 471         /**
 472          * @brief Set a output connection status handler
 473          * @details The handler will be called when the connection status of a
 474          * output object is changed.
 475          * @param[in] output A output object
 476          * @param[in] func A output status handler
 477          * @param[in] user_data The user data
 478          * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 479          */
 480         tdm_error (*output_set_status_handler)(tdm_output *output,
 481                                                tdm_output_status_handler func,
 482                                                void *user_data);
 483
 484         void (*reserved1)(void);
 485         void (*reserved2)(void);
 486         void (*reserved3)(void);
 487         void (*reserved4)(void);
 488         void (*reserved5)(void);
 489         void (*reserved6)(void);
 490         void (*reserved7)(void);
 491         void (*reserved8)(void);
 492 } tdm_func_output;
 493
 494 /**
 495  * @brief The layer functions for a backend module.
 496  */
 497 typedef struct _tdm_func_layer {
 498         /**
 499          * @brief Get the capabilities of a layer object
 500          * @param[in] layer A layer object
 501          * @param[out] caps The capabilities of a layer object
 502          * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 503          * @remark
 504          * A backend module @b SHOULD implement this function. TDM calls this function
 505          * not only at the initial time, but also at the update time when new output
 506          * is connected.\n
 507          * #tdm_caps_layer contains avaiable formats/properties, zpos information, etc.
 508          */
 509         tdm_error (*layer_get_capability)(tdm_layer *layer, tdm_caps_layer *caps);
 510
 511         /**
 512          * @brief Set the property which has a given id.
 513          * @param[in] layer A layer object
 514          * @param[in] id The property id
 515          * @param[in] value The value
 516          * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 517          */
 518         tdm_error (*layer_set_property)(tdm_layer *layer, unsigned int id,
 519                                         tdm_value value);
 520
 521         /**
 522          * @brief Get the property which has a given id.
 523          * @param[in] layer A layer object
 524          * @param[in] id The property id
 525          * @param[out] value The value
 526          * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 527          */
 528         tdm_error (*layer_get_property)(tdm_layer *layer, unsigned int id,
 529                                         tdm_value *value);
 530
 531         /**
 532          * @brief Set the geometry information to a layer object
 533          * @param[in] layer A layer object
 534          * @param[in] info The geometry information
 535          * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 536          * @see output_commit() function of #tdm_func_output
 537          * @remark
 538          * A backend module would apply the geometry information when the output object
 539          * of a layer object is committed.
 540          */
 541         tdm_error (*layer_set_info)(tdm_layer *layer, tdm_info_layer *info);
 542
 543         /**
 544          * @brief Get the geometry information to a layer object
 545          * @param[in] layer A layer object
 546          * @param[out] info The geometry information
 547          * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 548          */
 549         tdm_error (*layer_get_info)(tdm_layer *layer, tdm_info_layer *info);
 550
 551         /**
 552          * @brief Set a TDM buffer to a layer object
 553          * @param[in] layer A layer object
 554          * @param[in] buffer A TDM buffer
 555          * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 556          * @see output_commit() function of #tdm_func_output
 557          * @remark
 558          * A backend module would apply a TDM buffer when the output object
 559          * of a layer object is committed.
 560          */
 561         tdm_error (*layer_set_buffer)(tdm_layer *layer, tbm_surface_h buffer);
 562
 563         /**
 564          * @brief Unset a TDM buffer from a layer object
 565          * @param[in] layer A layer object
 566          * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 567          * @remark
 568          * A backend module @b SHOULD hide the current showing buffer from screen.
 569          * If needed, cleanup a layer object resource.
 570          */
 571         tdm_error (*layer_unset_buffer)(tdm_layer *layer);
 572
 573         /**
 574          * @brief Set the zpos for a VIDEO layer object
 575          * @param[in] layer A layer object
 576          * @param[in] zpos z-order
 577          * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 578          * @see tdm_caps_layer, tdm_layer_capability
 579          * @remark
 580          * A backend module doesn't need to implement this function if a backend
 581          * module doesn't have VIDEO layers.\n
 582          * This function is for VIDEO layers.
 583          * GRAPHIC layers are non-changeable. The zpos of GRAPHIC layers starts
 584          * from 0. If there are 4 GRAPHIC layers, The zpos SHOULD be 0, 1, 2, 3.\n
 585          * But the zpos of VIDEO layer is changeable. And The zpos of VIDEO layers
 586          * is less than GRAPHIC layers or more than GRAPHIC layers.
 587          * ie, ..., -2, -1, 4, 5, ... (if 0 <= GRAPHIC layer's zpos < 4).
 588          * The zpos of VIDEO layers is @b relative. It doesn't need to start
 589          * from -1 or 4. Let's suppose that there are two VIDEO layers.
 590          * One has -2 zpos. Another has -4 zpos. Then -2 Video layer is higher
 591          * than -4 VIDEO layer.
 592          */
 593         tdm_error (*layer_set_video_pos)(tdm_layer *layer, int zpos);
 594
 595         /**
 596          * @brief Create a capture object of a layer object
 597          * @param[in] output A output object
 598          * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
 599          * @return A capture object
 600          * @see capture_destroy() function of #tdm_func_capture
 601          * @remark
 602          * A backend module doesn't need to implement this function if a hardware
 603          * doesn't have the capture device.
 604          */
 605         tdm_capture *(*layer_create_capture)(tdm_layer *layer, tdm_error *error);
 606
 607         void (*reserved1)(void);
 608         void (*reserved2)(void);
 609         void (*reserved3)(void);
 610         void (*reserved4)(void);
 611         void (*reserved5)(void);
 612         void (*reserved6)(void);
 613         void (*reserved7)(void);
 614         void (*reserved8)(void);
 615 } tdm_func_layer;
 616
 617 /**
 618  * @brief The done handler of a pp object
 619  */
 620 typedef void (*tdm_pp_done_handler)(tdm_pp *pp, tbm_surface_h src,
 621                                     tbm_surface_h dst, void *user_data);
 622
 623 /**
 624  * @brief The pp functions for a backend module.
 625  */
 626 typedef struct _tdm_func_pp {
 627         /**
 628          * @brief Destroy a pp object
 629          * @param[in] pp A pp object
 630          * @see display_create_pp() function of #tdm_func_display
 631          */
 632         void         (*pp_destroy)(tdm_pp *pp);
 633
 634         /**
 635          * @brief Set the geometry information to a pp object
 636          * @param[in] pp A pp object
 637          * @param[in] info The geometry information
 638          * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 639          * @see pp_commit() function of #tdm_func_pp
 640          * @remark
 641          * A backend module would apply the geometry information when committed.
 642          */
 643         tdm_error    (*pp_set_info)(tdm_pp *pp, tdm_info_pp *info);
 644
 645         /**
 646          * @brief Attach a source buffer and a destination buffer to a pp object
 647          * @param[in] pp A pp object
 648          * @param[in] src A source buffer
 649          * @param[in] dst A destination buffer
 650          * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 651          * @see pp_set_info() function of #tdm_func_pp
 652          * @see pp_commit() function of #tdm_func_pp
 653          * @see pp_set_done_handler, tdm_pp_done_handler
 654          * @remark
 655          * A backend module converts the image of a source buffer to a destination
 656          * buffer when committed. The size/crop/transform information is set via
 657          * #pp_set_info() of #tdm_func_pp. When done, a backend module @b SHOULD
 658          * return the source/destination buffer via tdm_pp_done_handler.
 659          */
 660         tdm_error    (*pp_attach)(tdm_pp *pp, tbm_surface_h src, tbm_surface_h dst);
 661
 662         /**
 663          * @brief Commit changes for a pp object
 664          * @param[in] pp A pp object
 665          * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 666          */
 667         tdm_error    (*pp_commit)(tdm_pp *pp);
 668
 669         /**
 670          * @brief Set a user done handler to a pp object
 671          * @param[in] pp A pp object
 672          * @param[in] func A user done handler
 673          * @param[in] user_data user data
 674          * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 675          * @remark
 676          * A backend module @b SHOULD call #tdm_pp_done_handler when converintg a image is done.
 677          */
 678         tdm_error    (*pp_set_done_handler)(tdm_pp *pp, tdm_pp_done_handler func,
 679                                             void *user_data);
 680
 681         void (*reserved1)(void);
 682         void (*reserved2)(void);
 683         void (*reserved3)(void);
 684         void (*reserved4)(void);
 685         void (*reserved5)(void);
 686         void (*reserved6)(void);
 687         void (*reserved7)(void);
 688         void (*reserved8)(void);
 689 } tdm_func_pp;
 690
 691 /**
 692  * @brief The done handler of a capture object
 693  */
 694 typedef void (*tdm_capture_done_handler)(tdm_capture *capture,
 695                 tbm_surface_h buffer, void *user_data);
 696
 697 /**
 698  * @brief The capture functions for a backend module.
 699  */
 700 typedef struct _tdm_func_capture {
 701         /**
 702          * @brief Destroy a capture object
 703          * @param[in] capture A capture object
 704          * @see output_create_capture() function of #tdm_func_output
 705          * @see layer_create_capture() function of #tdm_func_layer
 706          */
 707         void         (*capture_destroy)(tdm_capture *capture);
 708
 709         /**
 710          * @brief Set the geometry information to a capture object
 711          * @param[in] capture A capture object
 712          * @param[in] info The geometry information
 713          * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 714          * @see capture_commit() function of #tdm_func_capture
 715          * @remark
 716          * A backend module would apply the geometry information when committed.
 717          */
 718         tdm_error    (*capture_set_info)(tdm_capture *capture, tdm_info_capture *info);
 719
 720         /**
 721          * @brief Attach a TDM buffer to a capture object
 722          * @details When capture_commit() function is called, a backend module dumps
 723          * a output or a layer to a TDM buffer.
 724          * @param[in] capture A capture object
 725          * @param[in] buffer A TDM buffer
 726          * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 727          * @see capture_set_info() function of #tdm_func_capture
 728          * @see capture_commit() function of #tdm_func_capture
 729          * @see capture_set_done_handler, tdm_capture_done_handler
 730          * @remark
 731          * A backend module dumps a output or a layer to to a TDM buffer when
 732          * committed. The size/crop/transform information is set via #capture_set_info()
 733          * of #tdm_func_capture. When done, a backend module @b SHOULD return the TDM
 734          * buffer via tdm_capture_done_handler.
 735          */
 736         tdm_error    (*capture_attach)(tdm_capture *capture, tbm_surface_h buffer);
 737
 738         /**
 739          * @brief Commit changes for a capture object
 740          * @param[in] capture A capture object
 741          * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 742          */
 743         tdm_error    (*capture_commit)(tdm_capture *capture);
 744
 745         /**
 746          * @brief Set a user done handler to a capture object
 747          * @param[in] capture A capture object
 748          * @param[in] func A user done handler
 749          * @param[in] user_data user data
 750          * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 751          * @remark
 752          * A backend module @b SHOULD call #tdm_capture_done_handler when capture operation is done.
 753          */
 754         tdm_error    (*capture_set_done_handler)(tdm_capture *capture,
 755                         tdm_capture_done_handler func, void *user_data);
 756
 757         void (*reserved1)(void);
 758         void (*reserved2)(void);
 759         void (*reserved3)(void);
 760         void (*reserved4)(void);
 761         void (*reserved5)(void);
 762         void (*reserved6)(void);
 763         void (*reserved7)(void);
 764         void (*reserved8)(void);
 765 } tdm_func_capture;
 766
 767 /*
 768  * ABI versions.  Each version has a major and minor revision.  Modules
 769  * using lower minor revisions must work with servers of a higher minor
 770  * revision.  There is no compatibility between different major revisions.
 771  * Whenever the ABI_ANSIC_VERSION is changed, the others must also be
 772  * changed.  The minor revision mask is 0x0000FFFF and the major revision
 773  * mask is 0xFFFF0000.
 774  */
 775 #define TDM_BACKEND_MINOR_VERSION_MASK  0x0000FFFF
 776 #define TDM_BACKEND_MAJOR_VERSION_MASK  0xFFFF0000
 777 #define TDM_BACKEND_GET_ABI_MINOR(v)    ((v) & TDM_BACKEND_MINOR_VERSION_MASK)
 778 #define TDM_BACKEND_GET_ABI_MAJOR(v)    (((v) & TDM_BACKEND_MAJOR_VERSION_MASK) >> 16)
 779
 780 #define SET_TDM_BACKEND_ABI_VERSION(major, minor) \
 781         (((major) << 16) & TDM_BACKEND_MAJOR_VERSION_MASK) | \
 782         ((major) & TDM_BACKEND_MINOR_VERSION_MASK)
 783 #define TDM_BACKEND_ABI_VERSION     SET_TDM_BACKEND_ABI_VERSION(1, 1)
 784
 785 /**
 786  * @brief The backend module information of the entry point to initialize a TDM
 787  * backend module.
 788  * @remark
 789  * A backend module @b SHOULD define the global data symbol of which name is
 790  * @b "tdm_backend_module_data". TDM will read this symbol, @b "tdm_backend_module_data",
 791  * at the initial time and call init() function of #tdm_backend_module.
 792  */
 793 typedef struct _tdm_backend_module {
 794         const char *name;           /**< The module name of a backend module */
 795         const char *vendor;         /**< The vendor name of a backend module */
 796         unsigned long abi_version;  /**< The ABI version of a backend module */
 797
 798         /**
 799          * @brief The init function of a backend module
 800          * @param[in] dpy A display object
 801          * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
 802          * @return The backend module data
 803          * @see tdm_backend_data
 804          */
 805         tdm_backend_data *(*init)(tdm_display *dpy, tdm_error *error);
 806
 807         /**
 808          * @brief The deinit function of a backend module
 809          * @param[in] bdata The backend module data
 810          */
 811         void (*deinit)(tdm_backend_data *bdata);
 812 } tdm_backend_module;
 813
 814 /**
 815  * @brief Register the backend display functions to a display
 816  * @param[in] dpy A display object
 817  * @param[in] func_display display functions
 818  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 819  * @see tdm_backend_register_func_output, tdm_backend_register_func_layer
 820  * @remarks
 821  * A backend module @b SHOULD set the backend display functions at least.
 822  */
 823 tdm_error
 824 tdm_backend_register_func_display(tdm_display *dpy,
 825                                   tdm_func_display *func_display);
 826
 827 /**
 828  * @brief Register the backend output functions to a display
 829  * @param[in] dpy A display object
 830  * @param[in] func_output output functions
 831  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 832  * @see tdm_backend_register_func_display, tdm_backend_register_func_layer
 833  * @remarks
 834  * A backend module @b SHOULD set the backend output functions at least.
 835  */
 836 tdm_error
 837 tdm_backend_register_func_output(tdm_display *dpy,
 838                                  tdm_func_output *func_output);
 839
 840 /**
 841  * @brief Register the backend layer functions to a display
 842  * @param[in] dpy A display object
 843  * @param[in] func_layer layer functions
 844  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 845  * @see tdm_backend_register_func_display, tdm_backend_register_func_output
 846  * @remarks
 847  * A backend module @b SHOULD set the backend layer functions at least.
 848  */
 849 tdm_error
 850 tdm_backend_register_func_layer(tdm_display *dpy, tdm_func_layer *func_layer);
 851
 852 /**
 853  * @brief Register the backend pp functions to a display
 854  * @param[in] dpy A display object
 855  * @param[in] func_pp pp functions
 856  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 857  * @see tdm_backend_register_func_display, tdm_backend_register_func_capture
 858  * @remark
 859  * A backend module doesn'tcan skip to register the backend pp functions
 860  * if a hardware doesn't have the memory-to-memory converting device.
 861  */
 862 tdm_error
 863 tdm_backend_register_func_pp(tdm_display *dpy, tdm_func_pp *func_pp);
 864
 865 /**
 866  * @brief Register the backend capture functions to a display
 867  * @param[in] dpy A display object
 868  * @param[in] func_capture capture functions
 869  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 870  * @see tdm_backend_register_func_display, tdm_backend_register_func_pp
 871  * @remark
 872  * A backend module can skip to register the backend capture functions
 873  * if a hardware doesn't have the capture device.
 874  */
 875 tdm_error
 876 tdm_backend_register_func_capture(tdm_display *dpy,
 877                                   tdm_func_capture *func_capture);
 878
 879 /**
 880  * @brief Increase the ref_count of a TDM buffer
 881  * @details
 882  * TDM has its own buffer release mechanism to let an frontend user know when a TDM buffer
 883  * becomes available for a next job. A TDM buffer can be used for TDM to show
 884  * it on screen or to capture an output and a layer. After all operations,
 885  * TDM will release it immediately when TDM doesn't need it any more.
 886  * @param[in] buffer A TDM buffer
 887  * @return A buffer itself. Otherwise, NULL.
 888  * @see tdm_buffer_unref_backend
 889  * @remark
 890  * - This function @b SHOULD be paired with #tdm_buffer_unref_backend. \n
 891  * - For example, this function @b SHOULD be called in case that a backend module uses the TDM
 892  * buffer of a layer for capturing a output or a layer to avoid tearing issue.
 893  */
 894 tbm_surface_h
 895 tdm_buffer_ref_backend(tbm_surface_h buffer);
 896
 897 /**
 898  * @brief Decrease the ref_count of a TDM buffer
 899  * @param[in] buffer A TDM buffer
 900  * @see tdm_buffer_ref_backend
 901  */
 902 void
 903 tdm_buffer_unref_backend(tbm_surface_h buffer);
 904
 905 /**
 906  * @brief The destroy handler of a TDM buffer
 907  * @param[in] buffer A TDM buffer
 908  * @param[in] user_data user data
 909  * @see tdm_buffer_add_destroy_handler, tdm_buffer_remove_destroy_handler
 910  */
 911 typedef void (*tdm_buffer_destroy_handler)(tbm_surface_h buffer,
 912                 void *user_data);
 913
 914 /**
 915  * @brief Add a destroy handler to a TDM buffer
 916  * @param[in] buffer A TDM buffer
 917  * @param[in] func A destroy handler
 918  * @param[in] user_data user data
 919  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 920  * @see tdm_buffer_remove_destroy_handler
 921  * @remark
 922  * A backend module can add a TDM buffer destroy handler to a TDM buffer which
 923  * is a #tbm_surface_h object. When the TDM buffer is destroyed, this handler will
 924  * be called.
 925  */
 926 tdm_error
 927 tdm_buffer_add_destroy_handler(tbm_surface_h buffer,
 928                                tdm_buffer_destroy_handler func, void *user_data);
 929
 930 /**
 931  * @brief Remove a destroy handler from a TDM buffer
 932  * @param[in] buffer A TDM buffer
 933  * @param[in] func A destroy handler
 934  * @param[in] user_data user data
 935  * @see tdm_buffer_add_destroy_handler
 936  */
 937 void
 938 tdm_buffer_remove_destroy_handler(tbm_surface_h buffer,
 939                                   tdm_buffer_destroy_handler func, void *user_data);
 940
 941
 942 tdm_event_loop_source*
 943 tdm_event_loop_add_fd_handler(tdm_display *dpy, int fd, tdm_event_loop_mask mask,
 944                          tdm_event_loop_fd_handler func, void *user_data,
 945                          tdm_error *error);
 946
 947 tdm_error
 948 tdm_event_loop_source_fd_update(tdm_event_loop_source *source, tdm_event_loop_mask mask);
 949
 950 tdm_event_loop_source*
 951 tdm_event_loop_add_timer_handler(tdm_display *dpy, tdm_event_loop_timer_handler func,
 952                             void *user_data, tdm_error *error);
 953
 954 tdm_error
 955 tdm_event_loop_source_timer_update(tdm_event_loop_source *source, int ms_delay);
 956
 957 void
 958 tdm_event_loop_source_remove(tdm_event_loop_source *source);
 959
 960 #ifdef __cplusplus
 961 }
 962 #endif
 963
 964 #endif /* _TDM_BACKEND_H_ */