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 Initialize a display object
  70  * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
  71  * @return A display object
  72  * @see tdm_display_deinit
  73  */
  74 tdm_display* tdm_display_init(tdm_error *error);
  75
  76 /**
  77  * @brief Deinitialize a display object
  78  * @param[in] dpy A display object
  79  * @see tdm_display_init
  80  */
  81 void         tdm_display_deinit(tdm_display *dpy);
  82
  83 /**
  84  * @brief Update a display object
  85  * @details
  86  * When new output is connected, a frontend user need to call this function.
  87  * And a frontend user can the new output information with tdm_output_get_xxx functions.
  88  * @param[in] dpy A display object
  89  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
  90  */
  91 tdm_error    tdm_display_update(tdm_display *dpy);
  92
  93 /**
  94  * @brief Get the file descriptor
  95  * @details TDM handles the events of fd with #tdm_display_handle_events.
  96  * @param[in] dpy A display object
  97  * @param[out] fd The file descriptor
  98  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
  99  * @see tdm_display_handle_events
 100  */
 101 tdm_error    tdm_display_get_fd(tdm_display *dpy, int *fd);
 102
 103 /**
 104  * @brief Handle the events
 105  * @param[in] dpy A display object
 106  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 107  * @see tdm_display_get_fd
 108  */
 109 tdm_error    tdm_display_handle_events(tdm_display *dpy);
 110
 111 /**
 112  * @brief Get the capabilities of a display object.
 113  * @details A frontend user can get whether TDM supports pp/capture functionality with this function.
 114  * @param[in] dpy A display object
 115  * @param[out] capabilities The capabilities of a display object
 116  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 117  */
 118 tdm_error    tdm_display_get_capabilities(tdm_display *dpy, tdm_display_capability *capabilities);
 119
 120 /**
 121  * @brief Get the pp capabilities of a display object.
 122  * @param[in] dpy A display object
 123  * @param[out] capabilities The pp capabilities
 124  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 125  */
 126 tdm_error    tdm_display_get_pp_capabilities(tdm_display *dpy, tdm_pp_capability *capabilities);
 127
 128 /**
 129  * @brief Get the pp available format array of a display object.
 130  * @param[in] dpy A display object
 131  * @param[out] formats The pp available format array
 132  * @param[out] count The count of formats
 133  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 134  */
 135 tdm_error    tdm_display_get_pp_available_formats(tdm_display *dpy, const tbm_format **formats, int *count);
 136
 137 /**
 138  * @brief Get the pp available size of a display object.
 139  * @details -1 means that a TDM backend module doesn't define the value.
 140  * @param[in] dpy A display object
 141  * @param[out] min_w The minimum width which TDM can handle
 142  * @param[out] min_h The minimum height which TDM can handle
 143  * @param[out] max_w The maximum width which TDM can handle
 144  * @param[out] max_h The maximum height which TDM can handle
 145  * @param[out] preferred_align The preferred align width which TDM can handle
 146  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 147  */
 148 tdm_error    tdm_display_get_pp_available_size(tdm_display *dpy, int *min_w, int *min_h, int *max_w, int *max_h, int *preferred_align);
 149
 150 /**
 151  * @brief Get the capture capabilities of a display object.
 152  * @param[in] dpy A display object
 153  * @param[out] capabilities The capture capabilities
 154  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 155  */
 156 tdm_error    tdm_display_get_capture_capabilities(tdm_display *dpy, tdm_capture_capability *capabilities);
 157
 158 /**
 159  * @brief Get the capture available format array of a display object.
 160  * @param[in] dpy A display object
 161  * @param[out] formats The capture available format array
 162  * @param[out] count The count of formats
 163  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 164  */
 165 tdm_error    tdm_display_get_catpure_available_formats(tdm_display *dpy, const tbm_format **formats, int *count);
 166
 167 /**
 168  * @brief Get the output counts which a display object has.
 169  * @param[in] dpy A display object
 170  * @param[out] count The count of outputs
 171  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 172  * @see tdm_display_get_output
 173  */
 174 tdm_error    tdm_display_get_output_count(tdm_display *dpy, int *count);
 175
 176 /**
 177  * @brief Get a output object which has the given index.
 178  * @param[in] dpy A display object
 179  * @param[in] index The index of a output object
 180  * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
 181  * @return A output object if success. Otherwise, NULL.
 182  * @see tdm_display_get_output_count
 183  */
 184 tdm_output*  tdm_display_get_output(tdm_display *dpy, int index, tdm_error *error);
 185
 186 /**
 187  * @brief Create a pp object.
 188  * @param[in] dpy A display object
 189  * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
 190  * @return A pp object if success. Otherwise, NULL.
 191  * @see tdm_pp_destroy
 192  */
 193 tdm_pp*      tdm_display_create_pp(tdm_display *dpy, tdm_error *error);
 194
 195 /**
 196  * @brief Get the model information of a output object.
 197  * @param[in] output A output object
 198  * @param[out] maker The output maker.
 199  * @param[out] model The output model.
 200  * @param[out] name The output name.
 201  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 202  */
 203 tdm_error    tdm_output_get_model_info(tdm_output *output, const char **maker, const char **model, const char **name);
 204
 205 /**
 206  * @brief Get the connection status of a output object.
 207  * @param[in] output A output object
 208  * @param[out] status The connection status.
 209  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 210  */
 211 tdm_error    tdm_output_get_conn_status(tdm_output *output, tdm_output_conn_status *status);
 212
 213 /**
 214  * @brief Get the connection type of a output object.
 215  * @param[in] output A output object
 216  * @param[out] type The connection type.
 217  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 218  */
 219 tdm_error    tdm_output_get_output_type(tdm_output *output, tdm_output_type *type);
 220
 221 /**
 222  * @brief Get the layer counts which a output object has.
 223  * @param[in] output A output object
 224  * @param[out] count The count of layers
 225  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 226  * @see tdm_output_get_layer
 227  */
 228 tdm_error    tdm_output_get_layer_count(tdm_output *output, int *count);
 229
 230 /**
 231  * @brief Get a layer object which has the given index.
 232  * @param[in] output A output object
 233  * @param[in] index The index of a layer object
 234  * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
 235  * @return A layer object if success. Otherwise, NULL.
 236  * @see tdm_output_get_layer_count
 237  */
 238 tdm_layer*   tdm_output_get_layer(tdm_output *output, int index, tdm_error *error);
 239
 240 /**
 241  * @brief Get the available property array of a output object.
 242  * @param[in] output A output object
 243  * @param[out] props The available property array
 244  * @param[out] count The count of properties
 245  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 246  */
 247 tdm_error    tdm_output_get_available_properties(tdm_output *output, const tdm_prop **props, int *count);
 248
 249 /**
 250  * @brief Get the available mode array of a output object.
 251  * @param[in] output A output object
 252  * @param[out] modes The available mode array
 253  * @param[out] count The count of modes
 254  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 255  */
 256 tdm_error    tdm_output_get_available_modes(tdm_output *output, const tdm_output_mode **modes, int *count);
 257
 258 /**
 259  * @brief Get the available size of a output object.
 260  * @details -1 means that a TDM backend module doesn't define the value.
 261  * @param[in] output A output object
 262  * @param[out] min_w The minimum width which TDM can handle
 263  * @param[out] min_h The minimum height which TDM can handle
 264  * @param[out] max_w The maximum width which TDM can handle
 265  * @param[out] max_h The maximum height which TDM can handle
 266  * @param[out] preferred_align The preferred align width which TDM can handle
 267  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 268  */
 269 tdm_error    tdm_output_get_available_size(tdm_output *output, int *min_w, int *min_h, int *max_w, int *max_h, int *preferred_align);
 270
 271 /**
 272  * @brief Get the physical size of a output object.
 273  * @param[in] output A output object
 274  * @param[out] mmWidth The milimeter width
 275  * @param[out] mmHeight The milimeter height
 276  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 277  */
 278 tdm_error    tdm_output_get_physical_size(tdm_output *output, unsigned int *mmWidth, unsigned int *mmHeight);
 279
 280 /**
 281  * @brief Get the subpixel of a output object.
 282  * @param[in] output A output object
 283  * @param[out] subpixel The subpixel
 284  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 285  */
 286 tdm_error    tdm_output_get_subpixel(tdm_output *output, unsigned int *subpixel);
 287
 288 /**
 289  * @brief Get the pipe of a output object.
 290  * @param[in] output A output object
 291  * @param[out] pipe The pipe
 292  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 293  */
 294 tdm_error    tdm_output_get_pipe(tdm_output *output, unsigned int *pipe);
 295
 296 /**
 297  * @brief Set the property which has a given id.
 298  * @param[in] output A output object
 299  * @param[in] id The property id
 300  * @param[in] value The value
 301  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 302  */
 303 tdm_error    tdm_output_set_property(tdm_output *output, unsigned int id, tdm_value value);
 304
 305 /**
 306  * @brief Get the property which has a given id
 307  * @param[in] output A output object
 308  * @param[in] id The property id
 309  * @param[out] value The value
 310  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 311  */
 312 tdm_error    tdm_output_get_property(tdm_output *output, unsigned int id, tdm_value *value);
 313
 314 /**
 315  * @brief Wait for VBLANK
 316  * @details After interval vblanks, a user vblank handler will be called.
 317  * @param[in] output A output object
 318  * @param[in] interval vblank interval
 319  * @param[in] sync 0: asynchronous, 1:synchronous
 320  * @param[in] func A user vblank handler
 321  * @param[in] user_data The user data
 322  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 323  * @see #tdm_output_vblank_handler
 324  */
 325 tdm_error    tdm_output_wait_vblank(tdm_output *output, int interval, int sync, tdm_output_vblank_handler func, void *user_data);
 326
 327 /**
 328  * @brief Commit changes for a output object
 329  * @details After all change of a output object are applied, a user commit handler
 330  * will be called.
 331  * @param[in] output A output object
 332  * @param[in] sync 0: asynchronous, 1:synchronous
 333  * @param[in] func A user commit handler
 334  * @param[in] user_data The user data
 335  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 336  */
 337 tdm_error    tdm_output_commit(tdm_output *output, int sync, tdm_output_commit_handler func, void *user_data);
 338
 339 /**
 340  * @brief Set one of available modes of a output object
 341  * @param[in] output A output object
 342  * @param[in] mode A output mode
 343  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 344  */
 345 tdm_error    tdm_output_set_mode(tdm_output *output, const tdm_output_mode *mode);
 346
 347 /**
 348  * @brief Get the mode of a output object
 349  * @param[in] output A output object
 350  * @param[out] mode A output mode
 351  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 352  */
 353 tdm_error    tdm_output_get_mode(tdm_output *output, const tdm_output_mode **mode);
 354
 355 /**
 356  * @brief Set DPMS of a output object
 357  * @param[in] output A output object
 358  * @param[in] dpms_value DPMS value
 359  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 360  */
 361 tdm_error    tdm_output_set_dpms(tdm_output *output, tdm_output_dpms dpms_value);
 362
 363 /**
 364  * @brief Get DPMS of a output object
 365  * @param[in] output A output object
 366  * @param[out] dpms_value DPMS value
 367  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 368  */
 369 tdm_error    tdm_output_get_dpms(tdm_output *output, tdm_output_dpms *dpms_value);
 370
 371 /**
 372  * @brief Create a capture object of a output object
 373  * @param[in] output A output object
 374  * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
 375  * @return A capture object
 376  * @see tdm_capture_destroy
 377  */
 378 tdm_capture *tdm_output_create_capture(tdm_output *output, tdm_error *error);
 379
 380 /**
 381  * @brief Get the capabilities of a layer object.
 382  * @param[in] layer A layer object
 383  * @param[out] capabilities The capabilities of a layer object
 384  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 385  */
 386 tdm_error    tdm_layer_get_capabilities(tdm_layer *layer, tdm_layer_capability *capabilities);
 387
 388 /**
 389  * @brief Get the available format array of a layer object.
 390  * @param[in] layer A layer object
 391  * @param[out] formats The available format array
 392  * @param[out] count The count of formats
 393  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 394  */
 395 tdm_error    tdm_layer_get_available_formats(tdm_layer *layer, const tbm_format **formats, int *count);
 396
 397 /**
 398  * @brief Get the available property array of a layer object.
 399  * @param[in] layer A layer object
 400  * @param[out] props The available property array
 401  * @param[out] count The count of properties
 402  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 403  */
 404 tdm_error    tdm_layer_get_available_properties(tdm_layer *layer, const tdm_prop **props, int *count);
 405
 406 /**
 407  * @brief Get the zpos of a layer object.
 408  * @details
 409  * - GRAPHIC layers have fixed zpos. It starts from 0. It's @b non-changeable.
 410  * - But the zpos of VIDEO layers will be decided by a backend module side.
 411  * - A frontend user only can set the relative zpos to VIDEO layers via #tdm_layer_set_video_pos
 412  * - The zpos of video layers is less than GRAPHIC layers or more than GRAPHIC
 413  * layers. ie, ..., -2, -1, 4, 5, ... (if 0 <= GRAPHIC layer's zpos < 4).
 414  * @param[in] layer A layer object
 415  * @param[out] zpos The zpos
 416  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 417  * @see tdm_layer_set_video_pos, tdm_layer_capability
 418  */
 419 tdm_error    tdm_layer_get_zpos(tdm_layer *layer, unsigned int *zpos);
 420
 421 /**
 422  * @brief Set the property which has a given id.
 423  * @param[in] layer A layer object
 424  * @param[in] id The property id
 425  * @param[in] value The value
 426  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 427  */
 428 tdm_error    tdm_layer_set_property(tdm_layer *layer, unsigned int id, tdm_value value);
 429
 430 /**
 431  * @brief Get the property which has a given id.
 432  * @param[in] layer A layer object
 433  * @param[in] id The property id
 434  * @param[out] value The value
 435  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 436  */
 437 tdm_error    tdm_layer_get_property(tdm_layer *layer, unsigned int id, tdm_value *value);
 438
 439 /**
 440  * @brief Set the geometry information to a layer object
 441  * @details The geometry information will be applied when the output object
 442  * of a layer object is committed.
 443  * @param[in] layer A layer object
 444  * @param[in] info The geometry information
 445  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 446  * @see tdm_output_commit
 447  */
 448 tdm_error    tdm_layer_set_info(tdm_layer *layer, tdm_info_layer *info);
 449
 450 /**
 451  * @brief Get the geometry information to a layer object
 452  * @param[in] layer A layer object
 453  * @param[out] info The geometry information
 454  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 455  */
 456 tdm_error    tdm_layer_get_info(tdm_layer *layer, tdm_info_layer *info);
 457
 458 /**
 459  * @brief Set a TDM buffer to a layer object
 460  * @details A TDM buffer will be applied when the output object
 461  * of a layer object is committed.
 462  * @param[in] layer A layer object
 463  * @param[in] buffer A TDM buffer
 464  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 465  * @see tdm_output_commit
 466  */
 467 tdm_error    tdm_layer_set_buffer(tdm_layer *layer, tbm_surface_h buffer);
 468
 469 /**
 470  * @brief Unset a TDM buffer from a layer object
 471  * @details When this function is called, a current showing buffer will be
 472  * disappeared from screen. Then nothing is showing on a layer object.
 473  * @param[in] layer A layer object
 474  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 475  */
 476 tdm_error    tdm_layer_unset_buffer(tdm_layer *layer);
 477
 478 /**
 479  * @brief Set a TBM surface_queue to a layer object
 480  * @details A TBM surface_queue will be applied when the output object
 481  * of a layer object is committed. and TDM layer will be automatically updated
 482  * @param[in] layer A layer object
 483  * @param[in] buffer_queue A TBM surface_queue
 484  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 485  * @see tdm_output_commit
 486  */
 487 tdm_error    tdm_layer_set_buffer_queue(tdm_layer *layer, tbm_surface_queue_h buffer_queue);
 488
 489 /**
 490  * @brief Unset a TBM surface_queue from a layer object
 491  * @details When this function is called, a current surface_queue will be
 492  * disappeared from screen. Then nothing is showing on a layer object.
 493  * @param[in] layer A layer object
 494  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 495  */
 496 tdm_error    tdm_layer_unset_buffer_queue(tdm_layer *layer);
 497
 498 /**
 499  * @brief Check wheter a layer object is available for a frontend user to use.
 500  * @details A layer object is not usable if a TDM buffer is showing on screen
 501  * via this layer object. By calling #tdm_layer_unset_buffer, this layer object
 502  * will become usable.
 503  * @param[in] layer A layer object
 504  * @param[out] usable 1 if usable, 0 if not usable
 505  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 506  */
 507 tdm_error    tdm_layer_is_usable(tdm_layer *layer, unsigned int *usable);
 508
 509 /**
 510  * @brief Set the relative zpos to a VIDEO layer object
 511  * @details The zpos value is less than the minimum zpos of GRAPHIC layers, or
 512  * it is more than the maximum zpos of GRAPHIC layers.
 513  * @param[in] layer A VIDEO layer object
 514  * @param[in] zpos The zpos
 515  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 516  * @see tdm_layer_get_zpos, tdm_layer_capability
 517  */
 518 tdm_error    tdm_layer_set_video_pos(tdm_layer *layer, int zpos);
 519
 520 /**
 521  * @brief Create a capture object of a layer object
 522  * @param[in] layer A layer object
 523  * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
 524  * @return A capture object
 525  * @see tdm_capture_destroy
 526  */
 527 tdm_capture *tdm_layer_create_capture(tdm_layer *layer, tdm_error *error);
 528
 529 /**
 530  * @brief Destroy a pp object
 531  * @param[in] pp A pp object
 532  * @see tdm_display_create_pp
 533  */
 534 void         tdm_pp_destroy(tdm_pp *pp);
 535
 536 /**
 537  * @brief Set the geometry information to a pp object
 538  * @param[in] pp A pp object
 539  * @param[in] info The geometry information
 540  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 541  * @see tdm_pp_commit
 542  */
 543 tdm_error    tdm_pp_set_info(tdm_pp *pp, tdm_info_pp *info);
 544
 545 /**
 546  * @brief Attach a source buffer and a destination buffer to a pp object
 547  * @param[in] pp A pp object
 548  * @param[in] src A source buffer
 549  * @param[in] dst A destination buffer
 550  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 551  * @see tdm_pp_commit, tdm_buffer_add_release_handler, tdm_buffer_release_handler
 552  */
 553 tdm_error    tdm_pp_attach(tdm_pp *pp, tbm_surface_h src, tbm_surface_h dst);
 554
 555 /**
 556  * @brief Commit changes for a pp object
 557  * @param[in] pp A pp object
 558  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 559  */
 560 tdm_error    tdm_pp_commit(tdm_pp *pp);
 561
 562 /**
 563  * @brief Destroy a capture object
 564  * @param[in] capture A capture object
 565  * @see tdm_output_create_capture, tdm_layer_create_capture
 566  */
 567 void         tdm_capture_destroy(tdm_capture *capture);
 568
 569 /**
 570  * @brief Set the geometry information to a capture object
 571  * @param[in] capture A capture object
 572  * @param[in] info The geometry information
 573  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 574  * @see tdm_capture_commit
 575  */
 576 tdm_error    tdm_capture_set_info(tdm_capture *capture, tdm_info_capture *info);
 577
 578 /**
 579  * @brief Attach a TDM buffer to a capture object
 580  * @param[in] capture A capture object
 581  * @param[in] buffer A TDM buffer
 582  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 583  * @see tdm_capture_commit, tdm_buffer_add_release_handler, tdm_buffer_release_handler
 584  */
 585 tdm_error    tdm_capture_attach(tdm_capture *capture, tbm_surface_h buffer);
 586
 587 /**
 588  * @brief Commit changes for a capture object
 589  * @param[in] capture A capture object
 590  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 591  */
 592 tdm_error    tdm_capture_commit(tdm_capture *capture);
 593
 594 /**
 595  * @brief The release handler of a TDM buffer
 596  * @param[in] buffer A TDM buffer
 597  * @param[in] user_data user data
 598  * @see tdm_buffer_add_release_handler, tdm_buffer_remove_release_handler
 599  */
 600 typedef void (*tdm_buffer_release_handler)(tbm_surface_h buffer, void *user_data);
 601
 602 /**
 603  * @brief Add a release handler to a TDM buffer
 604  * @details
 605  * TDM has its own buffer release mechanism to let an frontend user know when a TDM buffer
 606  * becomes available for a next job. A TDM buffer can be used for TDM to show
 607  * it on screen or to capture an output and a layer. After all operations,
 608  * TDM will release it immediately when TDM doesn't need it any more.
 609  * @param[in] buffer A TDM buffer
 610  * @param[in] func A release handler
 611  * @param[in] user_data user data
 612  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 613  * @see tdm_buffer_remove_release_handler
 614  */
 615 tdm_error    tdm_buffer_add_release_handler(tbm_surface_h buffer, tdm_buffer_release_handler func, void *user_data);
 616
 617 /**
 618  * @brief Remove a release handler from a TDM buffer
 619  * @param[in] buffer A TDM buffer
 620  * @param[in] func A release handler
 621  * @param[in] user_data user data
 622  * @see tdm_buffer_add_release_handler
 623  */
 624 void         tdm_buffer_remove_release_handler(tbm_surface_h buffer, tdm_buffer_release_handler func, void *user_data);
 625
 626 #ifdef __cplusplus
 627 }
 628 #endif
 629
 630 #endif /* _TDM_H_ */