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 Handle the events which happens on the fd of a backend module
 292          * @param[in] bdata The backend module data
 293          * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 294          */
 295         tdm_error (*display_handle_events)(tdm_backend_data *bdata);
 296
 297         /**
 298          * @brief Create a pp object of a backend module
 299          * @param[in] bdata The backend module data
 300          * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
 301          * @return A pp object
 302          * @see pp_destroy() function of #tdm_func_pp
 303          * @remark
 304          * A backend module doesn't need to implement this function if a hardware
 305          * doesn't have the memory-to-memory converting device.
 306          */
 307         tdm_pp *(*display_create_pp)(tdm_backend_data *bdata, tdm_error *error);
 308
 309         void (*reserved1)(void);
 310         void (*reserved2)(void);
 311         void (*reserved3)(void);
 312         void (*reserved4)(void);
 313         void (*reserved5)(void);
 314         void (*reserved6)(void);
 315         void (*reserved7)(void);
 316         void (*reserved8)(void);
 317 } tdm_func_display;
 318
 319 /**
 320  * @brief The output functions for a backend module.
 321  */
 322 typedef struct _tdm_func_output {
 323         /**
 324          * @brief Get the capabilities of a output object
 325          * @param[in] output A output object
 326          * @param[out] caps The capabilities of a output object
 327          * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 328          * @remark
 329          * A backend module @b SHOULD implement this function. TDM calls this function
 330          * not only at the initial time, but also at the update time when new output
 331          * is connected.\n
 332          * #tdm_caps_output contains connection status, modes, avaiable properties,
 333          * size restriction information, etc.
 334          */
 335         tdm_error (*output_get_capability)(tdm_output *output, tdm_caps_output *caps);
 336
 337         /**
 338          * @brief Get a layer array of a output object
 339          * @param[in] output A output object
 340          * @param[out] count The count of layers
 341          * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
 342          * @return A layer array which is @b newly-allocated
 343          * @remark
 344          * A backend module @b SHOULD implement this function. TDM calls this function
 345          * not only at the initial time, but also at the update time when new output
 346          * is connected.\n
 347          * A backend module @b SHOULD return the @b newly-allocated array which contains
 348          * "tdm_layer*" data. It will be freed in frontend.
 349          */
 350         tdm_layer **(*output_get_layers)(tdm_output *output, int *count,
 351                                          tdm_error *error);
 352
 353         /**
 354          * @brief Set the property which has a given id
 355          * @param[in] output A output object
 356          * @param[in] id The property id
 357          * @param[in] value The value
 358          * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 359          */
 360         tdm_error (*output_set_property)(tdm_output *output, unsigned int id,
 361                                          tdm_value value);
 362
 363         /**
 364          * @brief Get the property which has a given id
 365          * @param[in] output A output object
 366          * @param[in] id The property id
 367          * @param[out] value The value
 368          * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 369          */
 370         tdm_error (*output_get_property)(tdm_output *output, unsigned int id,
 371                                          tdm_value *value);
 372
 373         /**
 374          * @brief Wait for VBLANK
 375          * @param[in] output A output object
 376          * @param[in] interval vblank interval
 377          * @param[in] sync 0: asynchronous, 1:synchronous
 378          * @param[in] user_data The user data
 379          * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 380          * @see output_set_vblank_handler, tdm_output_vblank_handler
 381          * @remark
 382          * A backend module @b SHOULD call a user vblank handler after interval vblanks.
 383          */
 384         tdm_error (*output_wait_vblank)(tdm_output *output, int interval, int sync,
 385                                         void *user_data);
 386
 387         /**
 388          * @brief Set a user vblank handler
 389          * @param[in] output A output object
 390          * @param[in] func A user vblank handler
 391          * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 392          */
 393         tdm_error (*output_set_vblank_handler)(tdm_output *output,
 394                                                tdm_output_vblank_handler func);
 395
 396         /**
 397          * @brief Commit changes for a output object
 398          * @param[in] output A output object
 399          * @param[in] sync 0: asynchronous, 1:synchronous
 400          * @param[in] user_data The user data
 401          * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 402          * @see output_set_commit_handler, tdm_output_commit_handler
 403          * @remark
 404          * A backend module @b SHOULD call a user commit handler after all change of
 405          * a output object are applied.
 406          */
 407         tdm_error (*output_commit)(tdm_output *output, int sync, void *user_data);
 408
 409         /**
 410          * @brief Set a user commit handler
 411          * @param[in] output A output object
 412          * @param[in] func A user commit handler
 413          * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 414          */
 415         tdm_error (*output_set_commit_handler)(tdm_output *output,
 416                                                tdm_output_commit_handler func);
 417
 418         /**
 419          * @brief Set DPMS of a output object
 420          * @param[in] output A output object
 421          * @param[in] dpms_value DPMS value
 422          * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 423          */
 424         tdm_error (*output_set_dpms)(tdm_output *output, tdm_output_dpms dpms_value);
 425
 426         /**
 427          * @brief Get DPMS of a output object
 428          * @param[in] output A output object
 429          * @param[out] dpms_value DPMS value
 430          * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 431          */
 432         tdm_error (*output_get_dpms)(tdm_output *output, tdm_output_dpms *dpms_value);
 433
 434         /**
 435          * @brief Set one of available modes of a output object
 436          * @param[in] output A output object
 437          * @param[in] mode A output mode
 438          * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 439          */
 440         tdm_error (*output_set_mode)(tdm_output *output, const tdm_output_mode *mode);
 441
 442         /**
 443          * @brief Get the mode of a output object
 444          * @param[in] output A output object
 445          * @param[out] mode A output mode
 446          * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 447          */
 448         tdm_error (*output_get_mode)(tdm_output *output, const tdm_output_mode **mode);
 449
 450         /**
 451          * @brief Create a capture object of a output object
 452          * @param[in] output A output object
 453          * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
 454          * @return A capture object
 455          * @see capture_destroy() function of #tdm_func_capture
 456          * @remark
 457          * A backend module doesn't need to implement this function if a hardware
 458          * doesn't have the capture device.
 459          */
 460         tdm_capture *(*output_create_capture)(tdm_output *output, tdm_error *error);
 461
 462         void (*reserved1)(void);
 463         void (*reserved2)(void);
 464         void (*reserved3)(void);
 465         void (*reserved4)(void);
 466         void (*reserved5)(void);
 467         void (*reserved6)(void);
 468         void (*reserved7)(void);
 469         void (*reserved8)(void);
 470 } tdm_func_output;
 471
 472 /**
 473  * @brief The layer functions for a backend module.
 474  */
 475 typedef struct _tdm_func_layer {
 476         /**
 477          * @brief Get the capabilities of a layer object
 478          * @param[in] layer A layer object
 479          * @param[out] caps The capabilities of a layer object
 480          * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 481          * @remark
 482          * A backend module @b SHOULD implement this function. TDM calls this function
 483          * not only at the initial time, but also at the update time when new output
 484          * is connected.\n
 485          * #tdm_caps_layer contains avaiable formats/properties, zpos information, etc.
 486          */
 487         tdm_error (*layer_get_capability)(tdm_layer *layer, tdm_caps_layer *caps);
 488
 489         /**
 490          * @brief Set the property which has a given id.
 491          * @param[in] layer A layer object
 492          * @param[in] id The property id
 493          * @param[in] value The value
 494          * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 495          */
 496         tdm_error (*layer_set_property)(tdm_layer *layer, unsigned int id,
 497                                         tdm_value value);
 498
 499         /**
 500          * @brief Get the property which has a given id.
 501          * @param[in] layer A layer object
 502          * @param[in] id The property id
 503          * @param[out] value The value
 504          * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 505          */
 506         tdm_error (*layer_get_property)(tdm_layer *layer, unsigned int id,
 507                                         tdm_value *value);
 508
 509         /**
 510          * @brief Set the geometry information to a layer object
 511          * @param[in] layer A layer object
 512          * @param[in] info The geometry information
 513          * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 514          * @see output_commit() function of #tdm_func_output
 515          * @remark
 516          * A backend module would apply the geometry information when the output object
 517          * of a layer object is committed.
 518          */
 519         tdm_error (*layer_set_info)(tdm_layer *layer, tdm_info_layer *info);
 520
 521         /**
 522          * @brief Get the geometry information to a layer object
 523          * @param[in] layer A layer object
 524          * @param[out] info The geometry information
 525          * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 526          */
 527         tdm_error (*layer_get_info)(tdm_layer *layer, tdm_info_layer *info);
 528
 529         /**
 530          * @brief Set a TDM buffer to a layer object
 531          * @param[in] layer A layer object
 532          * @param[in] buffer A TDM buffer
 533          * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 534          * @see output_commit() function of #tdm_func_output
 535          * @remark
 536          * A backend module would apply a TDM buffer when the output object
 537          * of a layer object is committed.
 538          */
 539         tdm_error (*layer_set_buffer)(tdm_layer *layer, tbm_surface_h buffer);
 540
 541         /**
 542          * @brief Unset a TDM buffer from a layer object
 543          * @param[in] layer A layer object
 544          * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 545          * @remark
 546          * A backend module @b SHOULD hide the current showing buffer from screen.
 547          * If needed, cleanup a layer object resource.
 548          */
 549         tdm_error (*layer_unset_buffer)(tdm_layer *layer);
 550
 551         /**
 552          * @brief Set the zpos for a VIDEO layer object
 553          * @param[in] layer A layer object
 554          * @param[in] zpos z-order
 555          * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 556          * @see tdm_caps_layer, tdm_layer_capability
 557          * @remark
 558          * A backend module doesn't need to implement this function if a backend
 559          * module doesn't have VIDEO layers.\n
 560          * This function is for VIDEO layers.
 561          * GRAPHIC layers are non-changeable. The zpos of GRAPHIC layers starts
 562          * from 0. If there are 4 GRAPHIC layers, The zpos SHOULD be 0, 1, 2, 3.\n
 563          * But the zpos of VIDEO layer is changeable. And The zpos of VIDEO layers
 564          * is less than GRAPHIC layers or more than GRAPHIC layers.
 565          * ie, ..., -2, -1, 4, 5, ... (if 0 <= GRAPHIC layer's zpos < 4).
 566          * The zpos of VIDEO layers is @b relative. It doesn't need to start
 567          * from -1 or 4. Let's suppose that there are two VIDEO layers.
 568          * One has -2 zpos. Another has -4 zpos. Then -2 Video layer is higher
 569          * than -4 VIDEO layer.
 570          */
 571         tdm_error (*layer_set_video_pos)(tdm_layer *layer, int zpos);
 572
 573         /**
 574          * @brief Create a capture object of a layer object
 575          * @param[in] output A output object
 576          * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
 577          * @return A capture object
 578          * @see capture_destroy() function of #tdm_func_capture
 579          * @remark
 580          * A backend module doesn't need to implement this function if a hardware
 581          * doesn't have the capture device.
 582          */
 583         tdm_capture *(*layer_create_capture)(tdm_layer *layer, tdm_error *error);
 584
 585         void (*reserved1)(void);
 586         void (*reserved2)(void);
 587         void (*reserved3)(void);
 588         void (*reserved4)(void);
 589         void (*reserved5)(void);
 590         void (*reserved6)(void);
 591         void (*reserved7)(void);
 592         void (*reserved8)(void);
 593 } tdm_func_layer;
 594
 595 /**
 596  * @brief The done handler of a pp object
 597  */
 598 typedef void (*tdm_pp_done_handler)(tdm_pp *pp, tbm_surface_h src,
 599                                     tbm_surface_h dst, void *user_data);
 600
 601 /**
 602  * @brief The pp functions for a backend module.
 603  */
 604 typedef struct _tdm_func_pp {
 605         /**
 606          * @brief Destroy a pp object
 607          * @param[in] pp A pp object
 608          * @see display_create_pp() function of #tdm_func_display
 609          */
 610         void         (*pp_destroy)(tdm_pp *pp);
 611
 612         /**
 613          * @brief Set the geometry information to a pp object
 614          * @param[in] pp A pp object
 615          * @param[in] info The geometry information
 616          * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 617          * @see pp_commit() function of #tdm_func_pp
 618          * @remark
 619          * A backend module would apply the geometry information when committed.
 620          */
 621         tdm_error    (*pp_set_info)(tdm_pp *pp, tdm_info_pp *info);
 622
 623         /**
 624          * @brief Attach a source buffer and a destination buffer to a pp object
 625          * @param[in] pp A pp object
 626          * @param[in] src A source buffer
 627          * @param[in] dst A destination buffer
 628          * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 629          * @see pp_set_info() function of #tdm_func_pp
 630          * @see pp_commit() function of #tdm_func_pp
 631          * @see pp_set_done_handler, tdm_pp_done_handler
 632          * @remark
 633          * A backend module converts the image of a source buffer to a destination
 634          * buffer when committed. The size/crop/transform information is set via
 635          * #pp_set_info() of #tdm_func_pp. When done, a backend module @b SHOULD
 636          * return the source/destination buffer via tdm_pp_done_handler.
 637          */
 638         tdm_error    (*pp_attach)(tdm_pp *pp, tbm_surface_h src, tbm_surface_h dst);
 639
 640         /**
 641          * @brief Commit changes for a pp object
 642          * @param[in] pp A pp object
 643          * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 644          */
 645         tdm_error    (*pp_commit)(tdm_pp *pp);
 646
 647         /**
 648          * @brief Set a user done handler to a pp object
 649          * @param[in] pp A pp object
 650          * @param[in] func A user done handler
 651          * @param[in] user_data user data
 652          * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 653          * @remark
 654          * A backend module @b SHOULD call #tdm_pp_done_handler when converintg a image is done.
 655          */
 656         tdm_error    (*pp_set_done_handler)(tdm_pp *pp, tdm_pp_done_handler func,
 657                                             void *user_data);
 658
 659         void (*reserved1)(void);
 660         void (*reserved2)(void);
 661         void (*reserved3)(void);
 662         void (*reserved4)(void);
 663         void (*reserved5)(void);
 664         void (*reserved6)(void);
 665         void (*reserved7)(void);
 666         void (*reserved8)(void);
 667 } tdm_func_pp;
 668
 669 /**
 670  * @brief The done handler of a capture object
 671  */
 672 typedef void (*tdm_capture_done_handler)(tdm_capture *capture,
 673                 tbm_surface_h buffer, void *user_data);
 674
 675 /**
 676  * @brief The capture functions for a backend module.
 677  */
 678 typedef struct _tdm_func_capture {
 679         /**
 680          * @brief Destroy a capture object
 681          * @param[in] capture A capture object
 682          * @see output_create_capture() function of #tdm_func_output
 683          * @see layer_create_capture() function of #tdm_func_layer
 684          */
 685         void         (*capture_destroy)(tdm_capture *capture);
 686
 687         /**
 688          * @brief Set the geometry information to a capture object
 689          * @param[in] capture A capture object
 690          * @param[in] info The geometry information
 691          * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 692          * @see capture_commit() function of #tdm_func_capture
 693          * @remark
 694          * A backend module would apply the geometry information when committed.
 695          */
 696         tdm_error    (*capture_set_info)(tdm_capture *capture, tdm_info_capture *info);
 697
 698         /**
 699          * @brief Attach a TDM buffer to a capture object
 700          * @details When capture_commit() function is called, a backend module dumps
 701          * a output or a layer to a TDM buffer.
 702          * @param[in] capture A capture object
 703          * @param[in] buffer A TDM buffer
 704          * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 705          * @see capture_set_info() function of #tdm_func_capture
 706          * @see capture_commit() function of #tdm_func_capture
 707          * @see capture_set_done_handler, tdm_capture_done_handler
 708          * @remark
 709          * A backend module dumps a output or a layer to to a TDM buffer when
 710          * committed. The size/crop/transform information is set via #capture_set_info()
 711          * of #tdm_func_capture. When done, a backend module @b SHOULD return the TDM
 712          * buffer via tdm_capture_done_handler.
 713          */
 714         tdm_error    (*capture_attach)(tdm_capture *capture, tbm_surface_h buffer);
 715
 716         /**
 717          * @brief Commit changes for a capture object
 718          * @param[in] capture A capture object
 719          * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 720          */
 721         tdm_error    (*capture_commit)(tdm_capture *capture);
 722
 723         /**
 724          * @brief Set a user done handler to a capture object
 725          * @param[in] capture A capture object
 726          * @param[in] func A user done handler
 727          * @param[in] user_data user data
 728          * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 729          * @remark
 730          * A backend module @b SHOULD call #tdm_capture_done_handler when capture operation is done.
 731          */
 732         tdm_error    (*capture_set_done_handler)(tdm_capture *capture,
 733                         tdm_capture_done_handler func, void *user_data);
 734
 735         void (*reserved1)(void);
 736         void (*reserved2)(void);
 737         void (*reserved3)(void);
 738         void (*reserved4)(void);
 739         void (*reserved5)(void);
 740         void (*reserved6)(void);
 741         void (*reserved7)(void);
 742         void (*reserved8)(void);
 743 } tdm_func_capture;
 744
 745 /*
 746  * ABI versions.  Each version has a major and minor revision.  Modules
 747  * using lower minor revisions must work with servers of a higher minor
 748  * revision.  There is no compatibility between different major revisions.
 749  * Whenever the ABI_ANSIC_VERSION is changed, the others must also be
 750  * changed.  The minor revision mask is 0x0000FFFF and the major revision
 751  * mask is 0xFFFF0000.
 752  */
 753 #define TDM_BACKEND_MINOR_VERSION_MASK  0x0000FFFF
 754 #define TDM_BACKEND_MAJOR_VERSION_MASK  0xFFFF0000
 755 #define TDM_BACKEND_GET_ABI_MINOR(v)    ((v) & TDM_BACKEND_MINOR_VERSION_MASK)
 756 #define TDM_BACKEND_GET_ABI_MAJOR(v)    (((v) & TDM_BACKEND_MAJOR_VERSION_MASK) >> 16)
 757
 758 #define SET_TDM_BACKEND_ABI_VERSION(major, minor) \
 759         (((major) << 16) & TDM_BACKEND_MAJOR_VERSION_MASK) | \
 760         ((major) & TDM_BACKEND_MINOR_VERSION_MASK)
 761 #define TDM_BACKEND_ABI_VERSION     SET_TDM_BACKEND_ABI_VERSION(1, 1)
 762
 763 /**
 764  * @brief The backend module information of the entry point to initialize a TDM
 765  * backend module.
 766  * @remark
 767  * A backend module @b SHOULD define the global data symbol of which name is
 768  * @b "tdm_backend_module_data". TDM will read this symbol, @b "tdm_backend_module_data",
 769  * at the initial time and call init() function of #tdm_backend_module.
 770  */
 771 typedef struct _tdm_backend_module {
 772         const char *name;           /**< The module name of a backend module */
 773         const char *vendor;         /**< The vendor name of a backend module */
 774         unsigned long abi_version;  /**< The ABI version of a backend module */
 775
 776         /**
 777          * @brief The init function of a backend module
 778          * @param[in] dpy A display object
 779          * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
 780          * @return The backend module data
 781          * @see tdm_backend_data
 782          */
 783         tdm_backend_data *(*init)(tdm_display *dpy, tdm_error *error);
 784
 785         /**
 786          * @brief The deinit function of a backend module
 787          * @param[in] bdata The backend module data
 788          */
 789         void (*deinit)(tdm_backend_data *bdata);
 790 } tdm_backend_module;
 791
 792 /**
 793  * @brief Register the backend display functions to a display
 794  * @param[in] dpy A display object
 795  * @param[in] func_display display functions
 796  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 797  * @see tdm_backend_register_func_output, tdm_backend_register_func_layer
 798  * @remarks
 799  * A backend module @b SHOULD set the backend display functions at least.
 800  */
 801 tdm_error
 802 tdm_backend_register_func_display(tdm_display *dpy,
 803                                   tdm_func_display *func_display);
 804
 805 /**
 806  * @brief Register the backend output functions to a display
 807  * @param[in] dpy A display object
 808  * @param[in] func_output output functions
 809  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 810  * @see tdm_backend_register_func_display, tdm_backend_register_func_layer
 811  * @remarks
 812  * A backend module @b SHOULD set the backend output functions at least.
 813  */
 814 tdm_error
 815 tdm_backend_register_func_output(tdm_display *dpy,
 816                                  tdm_func_output *func_output);
 817
 818 /**
 819  * @brief Register the backend layer functions to a display
 820  * @param[in] dpy A display object
 821  * @param[in] func_layer layer functions
 822  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 823  * @see tdm_backend_register_func_display, tdm_backend_register_func_output
 824  * @remarks
 825  * A backend module @b SHOULD set the backend layer functions at least.
 826  */
 827 tdm_error
 828 tdm_backend_register_func_layer(tdm_display *dpy, tdm_func_layer *func_layer);
 829
 830 /**
 831  * @brief Register the backend pp functions to a display
 832  * @param[in] dpy A display object
 833  * @param[in] func_pp pp functions
 834  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 835  * @see tdm_backend_register_func_display, tdm_backend_register_func_capture
 836  * @remark
 837  * A backend module doesn'tcan skip to register the backend pp functions
 838  * if a hardware doesn't have the memory-to-memory converting device.
 839  */
 840 tdm_error
 841 tdm_backend_register_func_pp(tdm_display *dpy, tdm_func_pp *func_pp);
 842
 843 /**
 844  * @brief Register the backend capture functions to a display
 845  * @param[in] dpy A display object
 846  * @param[in] func_capture capture functions
 847  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 848  * @see tdm_backend_register_func_display, tdm_backend_register_func_pp
 849  * @remark
 850  * A backend module can skip to register the backend capture functions
 851  * if a hardware doesn't have the capture device.
 852  */
 853 tdm_error
 854 tdm_backend_register_func_capture(tdm_display *dpy,
 855                                   tdm_func_capture *func_capture);
 856
 857 /**
 858  * @brief Increase the ref_count of a TDM buffer
 859  * @details
 860  * TDM has its own buffer release mechanism to let an frontend user know when a TDM buffer
 861  * becomes available for a next job. A TDM buffer can be used for TDM to show
 862  * it on screen or to capture an output and a layer. After all operations,
 863  * TDM will release it immediately when TDM doesn't need it any more.
 864  * @param[in] buffer A TDM buffer
 865  * @return A buffer itself. Otherwise, NULL.
 866  * @see tdm_buffer_unref_backend
 867  * @remark
 868  * - This function @b SHOULD be paired with #tdm_buffer_unref_backend. \n
 869  * - For example, this function @b SHOULD be called in case that a backend module uses the TDM
 870  * buffer of a layer for capturing a output or a layer to avoid tearing issue.
 871  */
 872 tbm_surface_h
 873 tdm_buffer_ref_backend(tbm_surface_h buffer);
 874
 875 /**
 876  * @brief Decrease the ref_count of a TDM buffer
 877  * @param[in] buffer A TDM buffer
 878  * @see tdm_buffer_ref_backend
 879  */
 880 void
 881 tdm_buffer_unref_backend(tbm_surface_h buffer);
 882
 883 /**
 884  * @brief The destroy handler of a TDM buffer
 885  * @param[in] buffer A TDM buffer
 886  * @param[in] user_data user data
 887  * @see tdm_buffer_add_destroy_handler, tdm_buffer_remove_destroy_handler
 888  */
 889 typedef void (*tdm_buffer_destroy_handler)(tbm_surface_h buffer,
 890                 void *user_data);
 891
 892 /**
 893  * @brief Add a destroy handler to a TDM buffer
 894  * @param[in] buffer A TDM buffer
 895  * @param[in] func A destroy handler
 896  * @param[in] user_data user data
 897  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 898  * @see tdm_buffer_remove_destroy_handler
 899  * @remark
 900  * A backend module can add a TDM buffer destroy handler to a TDM buffer which
 901  * is a #tbm_surface_h object. When the TDM buffer is destroyed, this handler will
 902  * be called.
 903  */
 904 tdm_error
 905 tdm_buffer_add_destroy_handler(tbm_surface_h buffer,
 906                                tdm_buffer_destroy_handler func, void *user_data);
 907
 908 /**
 909  * @brief Remove a destroy handler from a TDM buffer
 910  * @param[in] buffer A TDM buffer
 911  * @param[in] func A destroy handler
 912  * @param[in] user_data user data
 913  * @see tdm_buffer_add_destroy_handler
 914  */
 915 void
 916 tdm_buffer_remove_destroy_handler(tbm_surface_h buffer,
 917                                   tdm_buffer_destroy_handler func, void *user_data);
 918
 919
 920 #ifdef __cplusplus
 921 }
 922 #endif
 923
 924 #endif /* _TDM_BACKEND_H_ */