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