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