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 /*
 786  * ABI versions.  Each version has a major and minor revision.  Modules
 787  * using lower minor revisions must work with servers of a higher minor
 788  * revision.  There is no compatibility between different major revisions.
 789  * Whenever the ABI_ANSIC_VERSION is changed, the others must also be
 790  * changed.  The minor revision mask is 0x0000FFFF and the major revision
 791  * mask is 0xFFFF0000.
 792  */
 793 #define TDM_BACKEND_MINOR_VERSION_MASK  0x0000FFFF
 794 #define TDM_BACKEND_MAJOR_VERSION_MASK  0xFFFF0000
 795 #define TDM_BACKEND_GET_ABI_MINOR(v)    ((v) & TDM_BACKEND_MINOR_VERSION_MASK)
 796 #define TDM_BACKEND_GET_ABI_MAJOR(v)    (((v) & TDM_BACKEND_MAJOR_VERSION_MASK) >> 16)
 797
 798 #define SET_TDM_BACKEND_ABI_VERSION(major, minor) \
 799         (((major) << 16) & TDM_BACKEND_MAJOR_VERSION_MASK) | \
 800         ((major) & TDM_BACKEND_MINOR_VERSION_MASK)
 801 #define TDM_BACKEND_ABI_VERSION     SET_TDM_BACKEND_ABI_VERSION(1, 1)
 802
 803 /**
 804  * @brief The backend module information of the entry point to initialize a TDM
 805  * backend module.
 806  * @remark
 807  * A backend module @b SHOULD define the global data symbol of which name is
 808  * @b "tdm_backend_module_data". TDM will read this symbol, @b "tdm_backend_module_data",
 809  * at the initial time and call init() function of #tdm_backend_module.
 810  */
 811 typedef struct _tdm_backend_module {
 812         const char *name;           /**< The module name of a backend module */
 813         const char *vendor;         /**< The vendor name of a backend module */
 814         unsigned long abi_version;  /**< The ABI version of a backend module */
 815
 816         /**
 817          * @brief The init function of a backend module
 818          * @param[in] dpy A display object
 819          * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
 820          * @return The backend module data
 821          * @see tdm_backend_data
 822          */
 823         tdm_backend_data *(*init)(tdm_display *dpy, tdm_error *error);
 824
 825         /**
 826          * @brief The deinit function of a backend module
 827          * @param[in] bdata The backend module data
 828          */
 829         void (*deinit)(tdm_backend_data *bdata);
 830 } tdm_backend_module;
 831
 832 /**
 833  * @brief Register the backend display functions to a display
 834  * @param[in] dpy A display object
 835  * @param[in] func_display display functions
 836  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 837  * @see tdm_backend_register_func_output, tdm_backend_register_func_layer
 838  * @remarks
 839  * A backend module @b SHOULD set the backend display functions at least.
 840  */
 841 tdm_error
 842 tdm_backend_register_func_display(tdm_display *dpy,
 843                                   tdm_func_display *func_display);
 844
 845 /**
 846  * @brief Register the backend output functions to a display
 847  * @param[in] dpy A display object
 848  * @param[in] func_output output functions
 849  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 850  * @see tdm_backend_register_func_display, tdm_backend_register_func_layer
 851  * @remarks
 852  * A backend module @b SHOULD set the backend output functions at least.
 853  */
 854 tdm_error
 855 tdm_backend_register_func_output(tdm_display *dpy,
 856                                  tdm_func_output *func_output);
 857
 858 /**
 859  * @brief Register the backend layer functions to a display
 860  * @param[in] dpy A display object
 861  * @param[in] func_layer layer functions
 862  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 863  * @see tdm_backend_register_func_display, tdm_backend_register_func_output
 864  * @remarks
 865  * A backend module @b SHOULD set the backend layer functions at least.
 866  */
 867 tdm_error
 868 tdm_backend_register_func_layer(tdm_display *dpy, tdm_func_layer *func_layer);
 869
 870 /**
 871  * @brief Register the backend pp functions to a display
 872  * @param[in] dpy A display object
 873  * @param[in] func_pp pp functions
 874  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 875  * @see tdm_backend_register_func_display, tdm_backend_register_func_capture
 876  * @remark
 877  * A backend module doesn'tcan skip to register the backend pp functions
 878  * if a hardware doesn't have the memory-to-memory converting device.
 879  */
 880 tdm_error
 881 tdm_backend_register_func_pp(tdm_display *dpy, tdm_func_pp *func_pp);
 882
 883 /**
 884  * @brief Register the backend capture functions to a display
 885  * @param[in] dpy A display object
 886  * @param[in] func_capture capture functions
 887  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 888  * @see tdm_backend_register_func_display, tdm_backend_register_func_pp
 889  * @remark
 890  * A backend module can skip to register the backend capture functions
 891  * if a hardware doesn't have the capture device.
 892  */
 893 tdm_error
 894 tdm_backend_register_func_capture(tdm_display *dpy,
 895                                   tdm_func_capture *func_capture);
 896
 897 /**
 898  * @brief Increase the ref_count of a TDM buffer
 899  * @details
 900  * TDM has its own buffer release mechanism to let an frontend user know when a TDM buffer
 901  * becomes available for a next job. A TDM buffer can be used for TDM to show
 902  * it on screen or to capture an output and a layer. After all operations,
 903  * TDM will release it immediately when TDM doesn't need it any more.
 904  * @param[in] buffer A TDM buffer
 905  * @return A buffer itself. Otherwise, NULL.
 906  * @see tdm_buffer_unref_backend
 907  * @remark
 908  * - This function @b SHOULD be paired with #tdm_buffer_unref_backend. \n
 909  * - For example, this function @b SHOULD be called in case that a backend module uses the TDM
 910  * buffer of a layer for capturing a output or a layer to avoid tearing issue.
 911  */
 912 tbm_surface_h
 913 tdm_buffer_ref_backend(tbm_surface_h buffer);
 914
 915 /**
 916  * @brief Decrease the ref_count of a TDM buffer
 917  * @param[in] buffer A TDM buffer
 918  * @see tdm_buffer_ref_backend
 919  */
 920 void
 921 tdm_buffer_unref_backend(tbm_surface_h buffer);
 922
 923 /**
 924  * @brief The destroy handler of a TDM buffer
 925  * @param[in] buffer A TDM buffer
 926  * @param[in] user_data user data
 927  * @see tdm_buffer_add_destroy_handler, tdm_buffer_remove_destroy_handler
 928  */
 929 typedef void (*tdm_buffer_destroy_handler)(tbm_surface_h buffer,
 930                 void *user_data);
 931
 932 /**
 933  * @brief Add a destroy handler to a TDM buffer
 934  * @param[in] buffer A TDM buffer
 935  * @param[in] func A destroy handler
 936  * @param[in] user_data user data
 937  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 938  * @see tdm_buffer_remove_destroy_handler
 939  * @remark
 940  * A backend module can add a TDM buffer destroy handler to a TDM buffer which
 941  * is a #tbm_surface_h object. When the TDM buffer is destroyed, this handler will
 942  * be called.
 943  */
 944 tdm_error
 945 tdm_buffer_add_destroy_handler(tbm_surface_h buffer,
 946                                tdm_buffer_destroy_handler func, void *user_data);
 947
 948 /**
 949  * @brief Remove a destroy handler from 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  * @see tdm_buffer_add_destroy_handler
 954  */
 955 void
 956 tdm_buffer_remove_destroy_handler(tbm_surface_h buffer,
 957                                   tdm_buffer_destroy_handler func, void *user_data);
 958
 959 /**
 960  * @brief Add a FD handler for activity on the given file descriptor
 961  * @param[in] dpy A display object
 962  * @param[in] fd A file descriptor
 963  * @param[in] mask to monitor FD
 964  * @param[in] func A FD handler function
 965  * @param[in] user_data user data
 966  * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
 967  * @return A FD event source
 968  * @see #tdm_event_loop_source_fd_update, #tdm_event_loop_source_remove
 969  */
 970 tdm_event_loop_source*
 971 tdm_event_loop_add_fd_handler(tdm_display *dpy, int fd, tdm_event_loop_mask mask,
 972                          tdm_event_loop_fd_handler func, void *user_data,
 973                          tdm_error *error);
 974
 975 /**
 976  * @brief Update the mask of the given FD event source
 977  * @param[in] source The given FD event source
 978  * @param[in] mask to monitor FD
 979  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 980  */
 981 tdm_error
 982 tdm_event_loop_source_fd_update(tdm_event_loop_source *source, tdm_event_loop_mask mask);
 983
 984 /**
 985  * @brief Add a timer handler
 986  * @param[in] dpy A display object
 987  * @param[in] func A timer handler function
 988  * @param[in] user_data user data
 989  * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
 990  * @return A timer event source
 991  * @see #tdm_event_loop_source_timer_update, #tdm_event_loop_source_remove
 992  */
 993 tdm_event_loop_source*
 994 tdm_event_loop_add_timer_handler(tdm_display *dpy, tdm_event_loop_timer_handler func,
 995                             void *user_data, tdm_error *error);
 996
 997 /**
 998  * @brief Update the millisecond delay time of the given timer event source.
 999  * @param[in] source The given timer event source
1000  * @param[in] ms_delay The millisecond delay time. zero "0" disarms the timer.
1001  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
1002  */
1003 tdm_error
1004 tdm_event_loop_source_timer_update(tdm_event_loop_source *source, unsigned int ms_delay);
1005
1006 /**
1007  * @brief Remove the given event source
1008  * @param[in] source The given event source
1009  * @see #tdm_event_loop_add_fd_handler, #tdm_event_loop_add_timer_handler
1010  */
1011 void
1012 tdm_event_loop_source_remove(tdm_event_loop_source *source);
1013
1014 #ifdef __cplusplus
1015 }
1016 #endif
1017
1018 #endif /* _TDM_BACKEND_H_ */