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] user_data The user data
 331  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 332  * @see #tdm_output_vblank_handler
 333  */
 334 tdm_error    tdm_output_wait_vblank(tdm_output *output, int interval, int sync, tdm_output_vblank_handler func, void *user_data);
 335
 336 /**
 337  * @brief Commit changes for a output object
 338  * @details After all change of a output object are applied, a user commit handler
 339  * will be called.
 340  * @param[in] output A output object
 341  * @param[in] sync 0: asynchronous, 1:synchronous
 342  * @param[in] user_data The user data
 343  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 344  */
 345 tdm_error    tdm_output_commit(tdm_output *output, int sync, tdm_output_commit_handler func, void *user_data);
 346
 347 /**
 348  * @brief Set one of available modes of a output object
 349  * @param[in] output A output object
 350  * @param[in] mode A output mode
 351  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 352  */
 353 tdm_error    tdm_output_set_mode(tdm_output *output, const tdm_output_mode *mode);
 354
 355 /**
 356  * @brief Get the mode of a output object
 357  * @param[in] output A output object
 358  * @param[out] mode A output mode
 359  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 360  */
 361 tdm_error    tdm_output_get_mode(tdm_output *output, const tdm_output_mode **mode);
 362
 363 /**
 364  * @brief Set DPMS of a output object
 365  * @param[in] output A output object
 366  * @param[in] dpms_value DPMS value
 367  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 368  */
 369 tdm_error    tdm_output_set_dpms(tdm_output *output, tdm_output_dpms dpms_value);
 370
 371 /**
 372  * @brief Get DPMS of a output object
 373  * @param[in] output A output object
 374  * @param[out] dpms_value DPMS value
 375  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 376  */
 377 tdm_error    tdm_output_get_dpms(tdm_output *output, tdm_output_dpms *dpms_value);
 378
 379 /**
 380  * @brief Create a capture object of a output object
 381  * @param[in] output A output object
 382  * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
 383  * @return A capture object
 384  * @see tdm_capture_destroy
 385  */
 386 tdm_capture *tdm_output_create_capture(tdm_output *output, tdm_error *error);
 387
 388 /**
 389  * @brief Get the capabilities of a layer object.
 390  * @param[in] layer A layer object
 391  * @param[out] capabilities The capabilities of a layer object
 392  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 393  */
 394 tdm_error    tdm_layer_get_capabilities(tdm_layer *layer, tdm_layer_capability *capabilities);
 395
 396 /**
 397  * @brief Get the available format array of a layer object.
 398  * @param[in] layer A layer object
 399  * @param[out] formats The available format array
 400  * @param[out] count The count of formats
 401  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 402  */
 403 tdm_error    tdm_layer_get_available_formats(tdm_layer *layer, const tbm_format **formats, int *count);
 404
 405 /**
 406  * @brief Get the available property array of a layer object.
 407  * @param[in] layer A layer object
 408  * @param[out] props The available property array
 409  * @param[out] count The count of properties
 410  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 411  */
 412 tdm_error    tdm_layer_get_available_properties(tdm_layer *layer, const tdm_prop **props, int *count);
 413
 414 /**
 415  * @brief Get the zpos of a layer object.
 416  * @details
 417  * - GRAPHIC layers have fixed zpos. It starts from 0. It's @b non-changeable.
 418  * - But the zpos of VIDEO layers will be decided by a backend module side.
 419  * - A frontend user only can set the relative zpos to VIDEO layers via #tdm_layer_set_video_pos
 420  * - The zpos of video layers is less than GRAPHIC layers or more than GRAPHIC
 421  * layers. ie, -1, -2, 4, 5 (if 0 <= GRAPHIC layer's zpos < 4).
 422  * @param[in] layer A layer object
 423  * @param[out] zpos The zpos
 424  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 425  * @see tdm_layer_set_video_pos, tdm_layer_capability
 426  */
 427 tdm_error    tdm_layer_get_zpos(tdm_layer *layer, unsigned int *zpos);
 428
 429 /**
 430  * @brief Set the property which has a given id.
 431  * @param[in] layer A layer object
 432  * @param[in] id The property id
 433  * @param[in] value The value
 434  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 435  */
 436 tdm_error    tdm_layer_set_property(tdm_layer *layer, unsigned int id, tdm_value value);
 437
 438 /**
 439  * @brief Get the property which has a given id.
 440  * @param[in] layer A layer object
 441  * @param[in] id The property id
 442  * @param[out] value The value
 443  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 444  */
 445 tdm_error    tdm_layer_get_property(tdm_layer *layer, unsigned int id, tdm_value *value);
 446
 447 /**
 448  * @brief Set the geometry information to a layer object
 449  * @details The geometry information will be applied when the output object
 450  * of a layer object is committed.
 451  * @param[in] layer A layer object
 452  * @param[in] info The geometry information
 453  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 454  * @see tdm_output_commit
 455  */
 456 tdm_error    tdm_layer_set_info(tdm_layer *layer, tdm_info_layer *info);
 457
 458 /**
 459  * @brief Get the geometry information to a layer object
 460  * @param[in] layer A layer object
 461  * @param[out] info The geometry information
 462  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 463  */
 464 tdm_error    tdm_layer_get_info(tdm_layer *layer, tdm_info_layer *info);
 465
 466 /**
 467  * @brief Set a TDM buffer to a layer object
 468  * @details A TDM buffer will be applied when the output object
 469  * of a layer object is committed.
 470  * @param[in] layer A layer object
 471  * @param[in] buffer A TDM buffer
 472  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 473  * @see tdm_output_commit
 474  */
 475 tdm_error    tdm_layer_set_buffer(tdm_layer *layer, tbm_surface_h buffer);
 476
 477 /**
 478  * @brief Unset a TDM buffer from a layer object
 479  * @details When this function is called, a current showing buffer will be
 480  * disappeared from screen. Then nothing is showing on a layer object.
 481  * @param[in] layer A layer object
 482  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 483  */
 484 tdm_error    tdm_layer_unset_buffer(tdm_layer *layer);
 485
 486 /**
 487  * @brief Check wheter a layer object is available for a frontend user to use.
 488  * @details A layer object is not usable if a TDM buffer is showing on screen
 489  * via this layer object. By calling #tdm_layer_unset_buffer, this layer object
 490  * will become usable.
 491  * @param[in] layer A layer object
 492  * @param[out] usable 1 if usable, 0 if not usable
 493  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 494  */
 495 tdm_error    tdm_layer_is_usable(tdm_layer *layer, unsigned int *usable);
 496
 497 /**
 498  * @brief Set the relative zpos to a VIDEO layer object
 499  * @details The zpos value is less than the minimum zpos of GRAPHIC layers, or
 500  * it is more than the maximum zpos of GRAPHIC layers.
 501  * @param[in] layer A VIDEO layer object
 502  * @param[in] zpos The zpos
 503  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 504  * @see tdm_layer_get_zpos, tdm_layer_capability
 505  */
 506 tdm_error    tdm_layer_set_video_pos(tdm_layer *layer, int zpos);
 507
 508 /**
 509  * @brief Create a capture object of a layer object
 510  * @param[in] output A output object
 511  * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
 512  * @return A capture object
 513  * @see tdm_capture_destroy
 514  */
 515 tdm_capture *tdm_layer_create_capture(tdm_layer *layer, tdm_error *error);
 516
 517 /**
 518  * @brief Destroy a pp object
 519  * @param[in] pp A pp object
 520  * @see tdm_display_create_pp
 521  */
 522 void         tdm_pp_destroy(tdm_pp *pp);
 523
 524 /**
 525  * @brief Set the geometry information to a pp object
 526  * @param[in] pp A pp object
 527  * @param[in] info The geometry information
 528  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 529  * @see tdm_pp_commit
 530  */
 531 tdm_error    tdm_pp_set_info(tdm_pp *pp, tdm_info_pp *info);
 532
 533 /**
 534  * @brief Attach a source buffer and a destination buffer to a pp object
 535  * @param[in] pp A pp object
 536  * @param[in] src A source buffer
 537  * @param[in] dst A destination buffer
 538  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 539  * @see tdm_pp_commit, tdm_buffer_add_release_handler, tdm_buffer_release_handler
 540  */
 541 tdm_error    tdm_pp_attach(tdm_pp *pp, tbm_surface_h src, tbm_surface_h dst);
 542
 543 /**
 544  * @brief Commit changes for a pp object
 545  * @param[in] pp A pp object
 546  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 547  */
 548 tdm_error    tdm_pp_commit(tdm_pp *pp);
 549
 550 /**
 551  * @brief Destroy a capture object
 552  * @param[in] capture A capture object
 553  * @see tdm_output_create_capture, tdm_layer_create_capture
 554  */
 555 void         tdm_capture_destroy(tdm_capture *capture);
 556
 557 /**
 558  * @brief Set the geometry information to a capture object
 559  * @param[in] capture A capture object
 560  * @param[in] info The geometry information
 561  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 562  * @see tdm_capture_commit
 563  */
 564 tdm_error    tdm_capture_set_info(tdm_capture *capture, tdm_info_capture *info);
 565
 566 /**
 567  * @brief Attach a TDM buffer to a capture object
 568  * @param[in] capture A capture object
 569  * @param[in] buffer A TDM buffer
 570  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 571  * @see tdm_capture_commit, tdm_buffer_add_release_handler, tdm_buffer_release_handler
 572  */
 573 tdm_error    tdm_capture_attach(tdm_capture *capture, tbm_surface_h buffer);
 574
 575 /**
 576  * @brief Commit changes for a capture object
 577  * @param[in] capture A capture object
 578  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 579  */
 580 tdm_error    tdm_capture_commit(tdm_capture *capture);
 581
 582 /**
 583  * @brief The release handler of a TDM buffer
 584  * @param[in] buffer A TDM buffer
 585  * @param[in] user_data user data
 586  * @see tdm_buffer_add_release_handler, tdm_buffer_remove_release_handler
 587  */
 588 typedef void (*tdm_buffer_release_handler)(tbm_surface_h buffer, void *user_data);
 589
 590 /**
 591  * @brief Add a release handler to a TDM buffer
 592  * @details
 593  * TDM has its own buffer release mechanism to let an frontend user know when a TDM buffer
 594  * becomes available for a next job. A TDM buffer can be used for TDM to show
 595  * it on screen or to capture an output and a layer. After all operations,
 596  * TDM will release it immediately when TDM doesn't need it any more.
 597  * @param[in] buffer A TDM buffer
 598  * @param[in] func A release handler
 599  * @param[in] user_data user data
 600  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
 601  * @see tdm_buffer_remove_release_handler
 602  */
 603 tdm_error    tdm_buffer_add_release_handler(tbm_surface_h buffer, tdm_buffer_release_handler func, void *user_data);
 604
 605 /**
 606  * @brief Remove a release handler from a TDM buffer
 607  * @param[in] buffer A TDM buffer
 608  * @param[in] func A release handler
 609  * @param[in] user_data user data
 610  * @see tdm_buffer_add_release_handler
 611  */
 612 void         tdm_buffer_remove_release_handler(tbm_surface_h buffer, tdm_buffer_release_handler func, void *user_data);
 613
 614 #ifdef __cplusplus
 615 }
 616 #endif
 617
 618 #endif /* _TDM_H_ */