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