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