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