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