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