include/tdm.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_H_
  37 #define _TDM_H_
  38
  39 #include <stdint.h>
  40 #include <tbm_surface.h>
  41 #include <tbm_surface_queue.h>
  42 #include <tbm_surface_internal.h>
  43
  44 #include "tdm_types.h"
  45
  46 #ifdef __cplusplus
  47 extern "C" {
  48 #endif
  49
  50 /**
  51  * @file tdm.h
  52  * @brief The header file for a frontend user.
  53  * @par Example
  54  * @code
  55    #include <tdm.h>    //for a frontend user
  56  * @endcode
  57  */
  58
  59 /**
  60  * @brief The display capability enumeration
  61  */
  62 typedef enum
  63 {
  64         TDM_DISPLAY_CAPABILITY_PP       = (1<<0),   /**< if hardware supports pp operation */
  65         TDM_DISPLAY_CAPABILITY_CAPTURE  = (1<<1),   /**< if hardware supports capture operation */
  66 } tdm_display_capability;
  67
  68 /**
  69  * @brief The output change enumeration of #tdm_output_change_handler
  70  */
  71 typedef enum {
  72         TDM_OUTPUT_CHANGE_CONNECTION    = (1 << 0), /**< connection chagne */
  73         TDM_OUTPUT_CHANGE_DPMS          = (1 << 1), /**< dpms change */
  74 } tdm_output_change_type;
  75
  76 /**
  77  * @brief The output change handler
  78  * @details This handler will be called when the status of a output object is
  79  * changed in runtime.
  80  */
  81 typedef void (*tdm_output_change_handler)(tdm_output *output,
  82                                           tdm_output_change_type type,
  83                                           tdm_value value,
  84                                           void *user_data);
  85
  86 /**
  87  * @brief Initialize a display object
  88  * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
  89  * @return A display object
  90  * @see tdm_display_deinit
  91  */
  92 tdm_display *
  93 tdm_display_init(tdm_error *error);
  94
  95 /**
  96  * @brief Deinitialize a display object
  97  * @param[in] dpy A display object
  98  * @see tdm_display_init
  99  */
 100 void
 101 tdm_display_deinit(tdm_display *dpy);
 102
 103 /**
 104  * @brief Update a display object
 105  * @details
 106  * When new output is connected, a frontend user need to call this function.
 107  * And a frontend user can the new output information with tdm_output_get_xxx functions.
 108  * @param[in] dpy A display object
 109  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 110  */
 111 tdm_error
 112 tdm_display_update(tdm_display *dpy);
 113
 114 /**
 115  * @brief Get the file descriptor
 116  * @details TDM handles the events of fd with #tdm_display_handle_events.
 117  * @param[in] dpy A display object
 118  * @param[out] fd The file descriptor
 119  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 120  * @see tdm_display_handle_events
 121  */
 122 tdm_error
 123 tdm_display_get_fd(tdm_display *dpy, int *fd);
 124
 125 /**
 126  * @brief Handle the events
 127  * @param[in] dpy A display object
 128  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 129  * @see tdm_display_get_fd
 130  */
 131 tdm_error
 132 tdm_display_handle_events(tdm_display *dpy);
 133
 134 /**
 135  * @brief Get the capabilities of a display object.
 136  * @details A frontend user can get whether TDM supports pp/capture functionality with this function.
 137  * @param[in] dpy A display object
 138  * @param[out] capabilities The capabilities of a display object
 139  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 140  */
 141 tdm_error
 142 tdm_display_get_capabilities(tdm_display *dpy,
 143                              tdm_display_capability *capabilities);
 144
 145 /**
 146  * @brief Get the pp capabilities of a display object.
 147  * @param[in] dpy A display object
 148  * @param[out] capabilities The pp capabilities
 149  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 150  */
 151 tdm_error
 152 tdm_display_get_pp_capabilities(tdm_display *dpy,
 153                                 tdm_pp_capability *capabilities);
 154
 155 /**
 156  * @brief Get the pp available format array of a display object.
 157  * @param[in] dpy A display object
 158  * @param[out] formats The pp available format array
 159  * @param[out] count The count of formats
 160  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 161  */
 162 tdm_error
 163 tdm_display_get_pp_available_formats(tdm_display *dpy,
 164                                      const tbm_format **formats, int *count);
 165
 166 /**
 167  * @brief Get the pp available size of a display object.
 168  * @details -1 means that a TDM backend module doesn't define the value.
 169  * @param[in] dpy A display object
 170  * @param[out] min_w The minimum width which TDM can handle
 171  * @param[out] min_h The minimum height which TDM can handle
 172  * @param[out] max_w The maximum width which TDM can handle
 173  * @param[out] max_h The maximum height which TDM can handle
 174  * @param[out] preferred_align The preferred align width which TDM can handle
 175  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 176  */
 177 tdm_error
 178 tdm_display_get_pp_available_size(tdm_display *dpy, int *min_w, int *min_h,
 179                                   int *max_w, int *max_h, int *preferred_align);
 180
 181 /**
 182  * @brief Get the capture capabilities of a display object.
 183  * @param[in] dpy A display object
 184  * @param[out] capabilities The capture capabilities
 185  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 186  */
 187 tdm_error
 188 tdm_display_get_capture_capabilities(tdm_display *dpy,
 189                                      tdm_capture_capability *capabilities);
 190
 191 /**
 192  * @brief Get the capture available format array of a display object.
 193  * @param[in] dpy A display object
 194  * @param[out] formats The capture available format array
 195  * @param[out] count The count of formats
 196  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 197  */
 198 tdm_error
 199 tdm_display_get_catpure_available_formats(tdm_display *dpy,
 200                 const tbm_format **formats, int *count);
 201
 202 /**
 203  * @brief Get the output counts which a display object has.
 204  * @param[in] dpy A display object
 205  * @param[out] count The count of outputs
 206  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 207  * @see tdm_display_get_output
 208  */
 209 tdm_error
 210 tdm_display_get_output_count(tdm_display *dpy, int *count);
 211
 212 /**
 213  * @brief Get a output object which has the given index.
 214  * @param[in] dpy A display object
 215  * @param[in] index The index of a output object
 216  * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
 217  * @return A output object if success. Otherwise, NULL.
 218  * @see tdm_display_get_output_count
 219  */
 220 tdm_output *
 221 tdm_display_get_output(tdm_display *dpy, int index, tdm_error *error);
 222
 223 /**
 224  * @brief Create a pp object.
 225  * @param[in] dpy A display object
 226  * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
 227  * @return A pp object if success. Otherwise, NULL.
 228  * @see tdm_pp_destroy
 229  */
 230 tdm_pp *
 231 tdm_display_create_pp(tdm_display *dpy, tdm_error *error);
 232
 233 /**
 234  * @brief Get the model information of a output object.
 235  * @param[in] output A output object
 236  * @param[out] maker The output maker.
 237  * @param[out] model The output model.
 238  * @param[out] name The output name.
 239  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 240  */
 241 tdm_error
 242 tdm_output_get_model_info(tdm_output *output, const char **maker,
 243                           const char **model, const char **name);
 244
 245 /**
 246  * @brief Get the connection status of a output object.
 247  * @param[in] output A output object
 248  * @param[out] status The connection status.
 249  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 250  */
 251 tdm_error
 252 tdm_output_get_conn_status(tdm_output *output, tdm_output_conn_status *status);
 253
 254 /**
 255  * @brief Add a output change handler
 256  * @details The handler will be called when the status of a
 257  * output object is changed. connection, DPMS, etc.
 258  * @param[in] output A output object
 259  * @param[in] func A output change handler
 260  * @param[in] user_data The user data
 261  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 262  */
 263 tdm_error
 264 tdm_output_add_change_handler(tdm_output *output,
 265                               tdm_output_change_handler func,
 266                               void *user_data);
 267
 268 /**
 269  * @brief Remove a output change handler
 270  * @param[in] output A output object
 271  * @param[in] func A output change handler
 272  * @param[in] user_data The user data
 273  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 274  */
 275 void
 276 tdm_output_remove_change_handler(tdm_output *output,
 277                                  tdm_output_change_handler func,
 278                                  void *user_data);
 279
 280 /**
 281  * @brief Get the connection type of a output object.
 282  * @param[in] output A output object
 283  * @param[out] type The connection type.
 284  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 285  */
 286 tdm_error
 287 tdm_output_get_output_type(tdm_output *output, tdm_output_type *type);
 288
 289 /**
 290  * @brief Get the layer counts which a output object has.
 291  * @param[in] output A output object
 292  * @param[out] count The count of layers
 293  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 294  * @see tdm_output_get_layer
 295  */
 296 tdm_error
 297 tdm_output_get_layer_count(tdm_output *output, int *count);
 298
 299 /**
 300  * @brief Get a layer object which has the given index.
 301  * @param[in] output A output object
 302  * @param[in] index The index of a layer object
 303  * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
 304  * @return A layer object if success. Otherwise, NULL.
 305  * @see tdm_output_get_layer_count
 306  */
 307 tdm_layer *
 308 tdm_output_get_layer(tdm_output *output, int index, tdm_error *error);
 309
 310 /**
 311  * @brief Get the available property array of a output object.
 312  * @param[in] output A output object
 313  * @param[out] props The available property array
 314  * @param[out] count The count of properties
 315  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 316  */
 317 tdm_error
 318 tdm_output_get_available_properties(tdm_output *output, const tdm_prop **props,
 319                                     int *count);
 320
 321 /**
 322  * @brief Get the available mode array of a output object.
 323  * @param[in] output A output object
 324  * @param[out] modes The available mode array
 325  * @param[out] count The count of modes
 326  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 327  */
 328 tdm_error
 329 tdm_output_get_available_modes(tdm_output *output,
 330                                const tdm_output_mode **modes, int *count);
 331
 332 /**
 333  * @brief Get the available size of a output object.
 334  * @details -1 means that a TDM backend module doesn't define the value.
 335  * @param[in] output A output object
 336  * @param[out] min_w The minimum width which TDM can handle
 337  * @param[out] min_h The minimum height which TDM can handle
 338  * @param[out] max_w The maximum width which TDM can handle
 339  * @param[out] max_h The maximum height which TDM can handle
 340  * @param[out] preferred_align The preferred align width which TDM can handle
 341  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 342  */
 343 tdm_error
 344 tdm_output_get_available_size(tdm_output *output, int *min_w, int *min_h,
 345                               int *max_w, int *max_h, int *preferred_align);
 346
 347 /**
 348  * @brief Get the physical size of a output object.
 349  * @param[in] output A output object
 350  * @param[out] mmWidth The milimeter width
 351  * @param[out] mmHeight The milimeter height
 352  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 353  */
 354 tdm_error
 355 tdm_output_get_physical_size(tdm_output *output, unsigned int *mmWidth,
 356                              unsigned int *mmHeight);
 357
 358 /**
 359  * @brief Get the subpixel of a output object.
 360  * @param[in] output A output object
 361  * @param[out] subpixel The subpixel
 362  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 363  */
 364 tdm_error
 365 tdm_output_get_subpixel(tdm_output *output, unsigned int *subpixel);
 366
 367 /**
 368  * @brief Get the pipe of a output object.
 369  * @param[in] output A output object
 370  * @param[out] pipe The pipe
 371  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 372  */
 373 tdm_error
 374 tdm_output_get_pipe(tdm_output *output, unsigned int *pipe);
 375
 376 /**
 377  * @brief Set the property which has a given id.
 378  * @param[in] output A output object
 379  * @param[in] id The property id
 380  * @param[in] value The value
 381  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 382  */
 383 tdm_error
 384 tdm_output_set_property(tdm_output *output, unsigned int id, tdm_value value);
 385
 386 /**
 387  * @brief Get the property which has a given id
 388  * @param[in] output A output object
 389  * @param[in] id The property id
 390  * @param[out] value The value
 391  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 392  */
 393 tdm_error
 394 tdm_output_get_property(tdm_output *output, unsigned int id, tdm_value *value);
 395
 396 /**
 397  * @brief Wait for VBLANK
 398  * @details After interval vblanks, a user vblank handler will be called.
 399  * @param[in] output A output object
 400  * @param[in] interval vblank interval
 401  * @param[in] sync 0: asynchronous, 1:synchronous
 402  * @param[in] func A user vblank handler
 403  * @param[in] user_data The user data
 404  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 405  * @see #tdm_output_vblank_handler
 406  */
 407 tdm_error
 408 tdm_output_wait_vblank(tdm_output *output, int interval, int sync,
 409                        tdm_output_vblank_handler func, void *user_data);
 410
 411 /**
 412  * @brief Commit changes for a output object
 413  * @details After all change of a output object are applied, a user commit handler
 414  * will be called.
 415  * @param[in] output A output object
 416  * @param[in] sync 0: asynchronous, 1:synchronous
 417  * @param[in] func A user commit handler
 418  * @param[in] user_data The user data
 419  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 420  */
 421 tdm_error
 422 tdm_output_commit(tdm_output *output, int sync, tdm_output_commit_handler func,
 423                   void *user_data);
 424
 425 /**
 426  * @brief Set one of available modes of a output object
 427  * @param[in] output A output object
 428  * @param[in] mode A output mode
 429  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 430  */
 431 tdm_error
 432 tdm_output_set_mode(tdm_output *output, const tdm_output_mode *mode);
 433
 434 /**
 435  * @brief Get the mode of a output object
 436  * @param[in] output A output object
 437  * @param[out] mode A output mode
 438  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 439  */
 440 tdm_error
 441 tdm_output_get_mode(tdm_output *output, const tdm_output_mode **mode);
 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
 450 tdm_output_set_dpms(tdm_output *output, tdm_output_dpms dpms_value);
 451
 452 /**
 453  * @brief Get DPMS of a output object
 454  * @param[in] output A output object
 455  * @param[out] dpms_value DPMS value
 456  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 457  */
 458 tdm_error
 459 tdm_output_get_dpms(tdm_output *output, tdm_output_dpms *dpms_value);
 460
 461 /**
 462  * @brief Create a capture object of a output object
 463  * @param[in] output A output object
 464  * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
 465  * @return A capture object
 466  * @see tdm_capture_destroy
 467  */
 468 tdm_capture *
 469 tdm_output_create_capture(tdm_output *output, tdm_error *error);
 470
 471 /**
 472  * @brief Get the capabilities of a layer object.
 473  * @param[in] layer A layer object
 474  * @param[out] capabilities The capabilities of a layer object
 475  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 476  */
 477 tdm_error
 478 tdm_layer_get_capabilities(tdm_layer *layer,
 479                            tdm_layer_capability *capabilities);
 480
 481 /**
 482  * @brief Get the available format array of a layer object.
 483  * @param[in] layer A layer object
 484  * @param[out] formats The available format array
 485  * @param[out] count The count of formats
 486  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 487  */
 488 tdm_error
 489 tdm_layer_get_available_formats(tdm_layer *layer, const tbm_format **formats,
 490                                 int *count);
 491
 492 /**
 493  * @brief Get the available property array of a layer object.
 494  * @param[in] layer A layer object
 495  * @param[out] props The available property array
 496  * @param[out] count The count of properties
 497  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 498  */
 499 tdm_error
 500 tdm_layer_get_available_properties(tdm_layer *layer, const tdm_prop **props,
 501                                    int *count);
 502
 503 /**
 504  * @brief Get the zpos of a layer object.
 505  * @details
 506  * - GRAPHIC layers have fixed zpos. It starts from 0. It's @b non-changeable.
 507  * - But the zpos of VIDEO layers will be decided by a backend module side.
 508  * - A frontend user only can set the relative zpos to VIDEO layers via #tdm_layer_set_video_pos
 509  * - The zpos of video layers is less than GRAPHIC layers or more than GRAPHIC
 510  * layers. ie, ..., -2, -1, 4, 5, ... (if 0 <= GRAPHIC layer's zpos < 4).
 511  * @param[in] layer A layer object
 512  * @param[out] zpos The zpos
 513  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 514  * @see tdm_layer_set_video_pos, tdm_layer_capability
 515  */
 516 tdm_error
 517 tdm_layer_get_zpos(tdm_layer *layer, unsigned int *zpos);
 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
 527 tdm_layer_set_property(tdm_layer *layer, unsigned int id, 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
 537 tdm_layer_get_property(tdm_layer *layer, unsigned int id, tdm_value *value);
 538
 539 /**
 540  * @brief Set the geometry information to a layer object
 541  * @details The geometry information will be applied when the output object
 542  * of a layer object is committed. If a layer has TDM_LAYER_CAPABILITY_NO_CROP
 543  * capability, a layer will ignore the pos(crop) information of #tdm_info_layer's
 544  * src_config.
 545  * @param[in] layer A layer object
 546  * @param[in] info The geometry information
 547  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 548  * @see tdm_output_commit
 549  */
 550 tdm_error
 551 tdm_layer_set_info(tdm_layer *layer, tdm_info_layer *info);
 552
 553 /**
 554  * @brief Get the geometry information to a layer object
 555  * @param[in] layer A layer object
 556  * @param[out] info The geometry information
 557  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 558  */
 559 tdm_error
 560 tdm_layer_get_info(tdm_layer *layer, tdm_info_layer *info);
 561
 562 /**
 563  * @brief Set a TDM buffer to a layer object
 564  * @details A TDM buffer will be applied when the output object
 565  * of a layer object is committed.
 566  * @param[in] layer A layer object
 567  * @param[in] buffer A TDM buffer
 568  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 569  * @see tdm_output_commit
 570  */
 571 tdm_error
 572 tdm_layer_set_buffer(tdm_layer *layer, tbm_surface_h buffer);
 573
 574 /**
 575  * @brief Unset a TDM buffer from a layer object
 576  * @details When this function is called, a current showing buffer will be
 577  * disappeared from screen. Then nothing is showing on a layer object.
 578  * @param[in] layer A layer object
 579  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 580  */
 581 tdm_error
 582 tdm_layer_unset_buffer(tdm_layer *layer);
 583
 584 /**
 585  * @brief Get a displaying TDM buffer from a layer object
 586  * @details A displaying TDM buffer is a current showing buffer on screen
 587  * that is set to layer object and applied output object of a layer object.
 588  * @param[in] layer A layer object
 589  * @return A TDM buffer if success. Otherwise, NULL.
 590  */
 591 tbm_surface_h
 592 tdm_layer_get_displaying_buffer(tdm_layer *layer, tdm_error *error);
 593
 594 /**
 595  * @brief Set a TBM surface_queue to a layer object
 596  * @details A TBM surface_queue will be applied when the output object
 597  * of a layer object is committed. and TDM layer will be automatically updated
 598  * @param[in] layer A layer object
 599  * @param[in] buffer_queue A TBM surface_queue
 600  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 601  * @see tdm_output_commit
 602  */
 603 tdm_error
 604 tdm_layer_set_buffer_queue(tdm_layer *layer, tbm_surface_queue_h buffer_queue);
 605
 606 /**
 607  * @brief Unset a TBM surface_queue from a layer object
 608  * @details When this function is called, a current surface_queue will be
 609  * disappeared from screen. Then nothing is showing on a layer object.
 610  * @param[in] layer A layer object
 611  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 612  */
 613 tdm_error
 614 tdm_layer_unset_buffer_queue(tdm_layer *layer);
 615
 616 /**
 617  * @brief Check wheter a layer object is available for a frontend user to use.
 618  * @details A layer object is not usable if a TDM buffer is showing on screen
 619  * via this layer object. By calling #tdm_layer_unset_buffer, this layer object
 620  * will become usable.
 621  * @param[in] layer A layer object
 622  * @param[out] usable 1 if usable, 0 if not usable
 623  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 624  */
 625 tdm_error
 626 tdm_layer_is_usable(tdm_layer *layer, unsigned int *usable);
 627
 628 /**
 629  * @brief Set the relative zpos to a VIDEO layer object
 630  * @details The zpos value is less than the minimum zpos of GRAPHIC layers, or
 631  * it is more than the maximum zpos of GRAPHIC layers.
 632  * @param[in] layer A VIDEO layer object
 633  * @param[in] zpos The zpos
 634  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 635  * @see tdm_layer_get_zpos, tdm_layer_capability
 636  */
 637 tdm_error
 638 tdm_layer_set_video_pos(tdm_layer *layer, int zpos);
 639
 640 /**
 641  * @brief Create a capture object of a layer object
 642  * @param[in] layer A layer object
 643  * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
 644  * @return A capture object
 645  * @see tdm_capture_destroy
 646  */
 647 tdm_capture *
 648 tdm_layer_create_capture(tdm_layer *layer, tdm_error *error);
 649
 650 /**
 651  * @brief Destroy a pp object
 652  * @param[in] pp A pp object
 653  * @see tdm_display_create_pp
 654  */
 655 void
 656 tdm_pp_destroy(tdm_pp *pp);
 657
 658 /**
 659  * @brief Set the geometry information to a pp object
 660  * @param[in] pp A pp object
 661  * @param[in] info The geometry information
 662  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 663  * @see tdm_pp_commit
 664  */
 665 tdm_error
 666 tdm_pp_set_info(tdm_pp *pp, tdm_info_pp *info);
 667
 668 /**
 669  * @brief Attach a source buffer and a destination buffer to a pp object
 670  * @param[in] pp A pp object
 671  * @param[in] src A source buffer
 672  * @param[in] dst A destination buffer
 673  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 674  * @see tdm_pp_commit, tdm_buffer_add_release_handler, tdm_buffer_release_handler
 675  */
 676 tdm_error
 677 tdm_pp_attach(tdm_pp *pp, tbm_surface_h src, tbm_surface_h dst);
 678
 679 /**
 680  * @brief Commit changes for a pp object
 681  * @param[in] pp A pp object
 682  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 683  */
 684 tdm_error
 685 tdm_pp_commit(tdm_pp *pp);
 686
 687 /**
 688  * @brief Destroy a capture object
 689  * @param[in] capture A capture object
 690  * @see tdm_output_create_capture, tdm_layer_create_capture
 691  */
 692 void
 693 tdm_capture_destroy(tdm_capture *capture);
 694
 695 /**
 696  * @brief Set the geometry information to a capture object
 697  * @param[in] capture A capture object
 698  * @param[in] info The geometry information
 699  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 700  * @see tdm_capture_commit
 701  */
 702 tdm_error
 703 tdm_capture_set_info(tdm_capture *capture, tdm_info_capture *info);
 704
 705 /**
 706  * @brief Attach a TDM buffer to a capture object
 707  * @param[in] capture A capture object
 708  * @param[in] buffer A TDM buffer
 709  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 710  * @see tdm_capture_commit, tdm_buffer_add_release_handler, tdm_buffer_release_handler
 711  */
 712 tdm_error
 713 tdm_capture_attach(tdm_capture *capture, tbm_surface_h buffer);
 714
 715 /**
 716  * @brief Commit changes for a capture object
 717  * @param[in] capture A capture object
 718  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 719  */
 720 tdm_error
 721 tdm_capture_commit(tdm_capture *capture);
 722
 723 /**
 724  * @brief The release handler of a TDM buffer
 725  * @param[in] buffer A TDM buffer
 726  * @param[in] user_data user data
 727  * @see tdm_buffer_add_release_handler, tdm_buffer_remove_release_handler
 728  */
 729 typedef void (*tdm_buffer_release_handler)(tbm_surface_h buffer,
 730                 void *user_data);
 731
 732 /**
 733  * @brief Add a release handler to a TDM buffer
 734  * @details
 735  * TDM has its own buffer release mechanism to let an frontend user know when a TDM buffer
 736  * becomes available for a next job. A TDM buffer can be used for TDM to show
 737  * it on screen or to capture an output and a layer. After all operations,
 738  * TDM will release it immediately when TDM doesn't need it any more.
 739  * @param[in] buffer A TDM buffer
 740  * @param[in] func A release handler
 741  * @param[in] user_data user data
 742  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 743  * @see tdm_buffer_remove_release_handler
 744  */
 745 tdm_error
 746 tdm_buffer_add_release_handler(tbm_surface_h buffer,
 747                                tdm_buffer_release_handler func, void *user_data);
 748
 749 /**
 750  * @brief Remove a release handler from a TDM buffer
 751  * @param[in] buffer A TDM buffer
 752  * @param[in] func A release handler
 753  * @param[in] user_data user data
 754  * @see tdm_buffer_add_release_handler
 755  */
 756 void
 757 tdm_buffer_remove_release_handler(tbm_surface_h buffer,
 758                                   tdm_buffer_release_handler func, void *user_data);
 759
 760 #ifdef __cplusplus
 761 }
 762 #endif
 763
 764 #endif /* _TDM_H_ */