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