include/tbm_surface_internal.h

   1 /**************************************************************************
   2
   3 libtbm
   4
   5 Copyright 2014 Samsung Electronics co., Ltd. All Rights Reserved.
   6
   7 Contact: SooChan Lim <sc1.lim@samsung.com>, Sangjin Lee <lsj119@samsung.com>
   8 Inpyo Kang <mantiger@samsung.com>, Dongyeon Kim <dy5.kim@samsung.com>
   9 Boram Park <boram1288.park@samsung.com>, Changyeon Lee <cyeon.lee@samsung.com>
  10
  11 Permission is hereby granted, free of charge, to any person obtaining a
  12 copy of this software and associated documentation files (the
  13 "Software"), to deal in the Software without restriction, including
  14 without limitation the rights to use, copy, modify, merge, publish,
  15 distribute, sub license, and/or sell copies of the Software, and to
  16 permit persons to whom the Software is furnished to do so, subject to
  17 the following conditions:
  18
  19 The above copyright notice and this permission notice (including the
  20 next paragraph) shall be included in all copies or substantial portions
  21 of the Software.
  22
  23 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
  24 OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  25 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.
  26 IN NO EVENT SHALL PRECISION INSIGHT AND/OR ITS SUPPLIERS BE LIABLE FOR
  27 ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
  28 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
  29 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  30
  31 **************************************************************************/
  32
  33 #ifndef _TBM_SURFACE_INTERNAL_H_
  34 #define _TBM_SURFACE_INTERNAL_H_
  35
  36 #include <tbm_bufmgr.h>
  37 #include <tbm_error.h>
  38
  39 #ifdef __cplusplus
  40 extern "C" {
  41 #endif
  42
  43 /**
  44  * @brief Queries formats which the system can support.
  45  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  46  * @remarks The formats must be released using free().
  47  * @param[in] bufmgr : the buffer manager
  48  * @param[out] *formats : format array which the system can support. This pointer has to be freed by user.
  49  * @param[out] num : the number of formats.
  50  * @return a tbm_surface_h if this function succeeds, otherwise NULL
  51  * @par Example
  52    @code
  53    #include <tbm_surface.h>
  54    #include <tbm_surface_internal.h>
  55
  56    tbm_bufmgr bufmgr;
  57    uint32_t *formats;
  58    uint32_t format_num;
  59
  60    bufmgr = tbm_bufmgr_create (-1);
  61    ret = tbm_surface_internal_query_surpported_foramts (bufmgr, &formats, &format_num);
  62
  63    ...
  64
  65    free (foramts);
  66    tbm_surface_bufmgr_deinit (bufmgr);
  67    @endcode
  68  */
  69 int tbm_surface_internal_query_supported_formats(uint32_t **formats,
  70                                                  uint32_t *num);
  71
  72 /**
  73  * @brief Creates the tbm_surface with memory type.
  74  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  75  * @details
  76  * #TBM_BO_DEFAULT is default memory: it depends on the backend\n
  77  * #TBM_BO_SCANOUT is scanout memory\n
  78  * #TBM_BO_NONCACHABLE is non-cachable memory\n
  79  * #TBM_BO_WC is write-combine memory\n
  80  * #TBM_BO_VENDOR vendor specific memory: it depends on the tbm backend\n
  81  * @param[in] bufmgr : the buffer manager
  82  * @param[in] width  : the width of surface
  83  * @param[in] height : the height of surface
  84  * @param[in] format : the format of surface
  85  * @param[in] flags  : the flags of memory type
  86  * @return a tbm_surface_h if this function succeeds, otherwise NULL
  87  * @retval #tbm_surface_h
  88  * @par Example
  89    @code
  90    #include <tbm_surface.h>
  91    #include <tbm_surface_internal.h>
  92
  93    int bufmgr_fd
  94    tbm_bufmgr bufmgr;
  95    tbm_surface_h surface;
  96    uint32_t *format;
  97    uint32_t format_num;
  98
  99    bufmgr = tbm_bufmgr_create (bufmgr_fd);
 100    surface = tbm_surface_internal_create_with_flags (128, 128, TBM_FORMAT_YUV420, TBM_BO_DEFAULT);
 101
 102    ...
 103
 104    tbm_surface_destroy (surface);
 105    tbm_surface_bufmgr_deinit (bufmgr);
 106    @endcode
 107  */
 108 tbm_surface_h tbm_surface_internal_create_with_flags(int width, int height,
 109                                                      int format, int flags);
 110
 111 /**
 112  * @brief Creates the tbm_surface with buffer objects.
 113  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 114  * @param[in] bufmgr : the buffer manager
 115  * @param[in] width  : the width of surface
 116  * @param[in] height : the height of surface
 117  * @param[in] format : the format of surface
 118  * @param[in] *bos   : the array pointer of buffer objects
 119  * @param[in] num    : the number of buffer objects
 120  * @return a tbm_surface_h if this function succeeds, otherwise NULL
 121  * @retval #tbm_surface_h
 122  * @par Example
 123    @code
 124    #include <tbm_bufmgr.h>
 125    #include <tbm_surface.h>
 126    #include <tbm_surface_internal.h>
 127
 128    int bufmgr_fd
 129    tbm_bufmgr bufmgr;
 130    tbm_surface_h surface;
 131    tbm_surface_info_s info;
 132    uint32_t *format;
 133    uint32_t format_num;
 134    tbm_bo bo[1];
 135
 136    bufmgr = tbm_bufmgr_init (bufmgr_fd);
 137    bo[0] = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 138
 139    info.width = 128;
 140    info.height = 128;
 141    info.format = TBM_FORMAT_ARGB8888;
 142    info.bpp = 32;
 143    info.size = 65536;
 144    info.num_planes = 1;
 145    info.planes[0].size = 65536;
 146    info.planes[0].offset = 0;
 147    info.planes[0].stride = 512;
 148
 149    surface = tbm_surface_internal_create_with_bos (&info, bo, 1);
 150
 151    ...
 152
 153    tbm_surface_destroy (surface);
 154    tbm_surface_bufmgr_deinit (bufmgr);
 155    @endcode
 156  */
 157 tbm_surface_h tbm_surface_internal_create_with_bos(tbm_surface_info_s *info,
 158                                                    tbm_bo *bos, int num);
 159
 160 /**
 161  * @brief Destroy the tbm surface
 162     TODO:
 163  */
 164 void tbm_surface_internal_destroy(tbm_surface_h surface);
 165
 166 /**
 167  * @brief reference the tbm surface
 168     TODO:
 169  */
 170 void tbm_surface_internal_ref(tbm_surface_h surface);
 171
 172 /**
 173  * @brief unreference the tbm surface
 174     TODO:
 175  */
 176 void tbm_surface_internal_unref(tbm_surface_h surface);
 177
 178 /**
 179  * @brief Gets the number of buffer objects associated with the tbm_surface.
 180  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 181  * @param[in] surface : the tbm_surface_h
 182  * @return the number of buffer objects associated with the tbm_surface_h, otherwise 0.
 183  * @par Example
 184    @code
 185    #include <tbm_surface.h>
 186    #include <tbm_surface_internal.h>
 187
 188    tbm_surface_h surface;
 189    int num_bos;
 190
 191    surface = tbm_surface_create (128, 128, TBM_FORMAT_YUV420);
 192    num_bos = tbm_surface_internal_get_num_bos (surface);
 193
 194    ...
 195
 196    tbm_surface_destroy (surface);
 197    @endcode
 198  */
 199 int tbm_surface_internal_get_num_bos(tbm_surface_h surface);
 200
 201 /**
 202  * @brief Gets the buffor object by the bo_index.
 203  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 204  * @param[in] surface : the tbm_surface_h
 205  * @param[in] bo_idx : the bo index in the the tbm_surface
 206  * @return the buffer object, otherwise NULL.
 207  * @retval #tbm_bo
 208  * @par Example
 209    @code
 210    #include <tbm_surface.h>
 211    #include <tbm_surface_internal.h>
 212
 213    tbm_surface_h surface;
 214    int num_bos;
 215    tbm_bo bo;
 216
 217    surface = tbm_surface_create (128, 128, TBM_FORMAT_YUV420);
 218    num_bos = tbm_surface_internal_get_num_bos (surface);
 219
 220    for (i=0 ; i < num_bos ; i++)
 221    {
 222        bo = tbm_surface_internal_get_bo (surface, i);
 223
 224    ...
 225
 226    tbm_surface_destroy (surface);
 227    @endcode
 228  */
 229 tbm_bo tbm_surface_internal_get_bo(tbm_surface_h surface, int bo_idx);
 230
 231 /**
 232  * @brief Gets the size of the surface.
 233  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 234  * @param[in] surface : the tbm_surface_h
 235  * @return the size of tbm_surface, otherwise 0.
 236  * @par Example
 237    @code
 238    #include <tbm_surface.h>
 239    #include <tbm_surface_internal.h>
 240
 241    tbm_surface_h surface;
 242    int size;
 243
 244    surface = tbm_surface_create (128, 128, TBM_FORMAT_YUV420);
 245    size = tbm_surface_internal_get_size (surface);
 246
 247    tbm_surface_destroy (surface);
 248    @endcode
 249  */
 250 unsigned int tbm_surface_internal_get_size(tbm_surface_h surface);
 251
 252 /**
 253  * @brief Gets size, offset and pitch data of plane by the plane_index.
 254  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 255  * @param[in] surface : the tbm_surface_h
 256  * @param[in] plane_idx : the bo index in the the tbm_surface
 257  * @param[out] size : the size of plane in tbm_surface
 258  * @param[out] offset : the offset of plane in tbm_surface
 259  * @param[out] pitch : the pitch of plane in tbm_surface
 260  * @return 1 if this function succeeds, otherwise 0.
 261  * @par Example
 262    @code
 263    #include <tbm_surface.h>
 264    #include <tbm_surface_internal.h>
 265
 266    tbm_surface_h surface;
 267    uint32_t size, offset, pitch;
 268    int ret;
 269
 270    surface = tbm_surface_create (128, 128, TBM_FORMAT_YUV420);
 271    ret = tbm_surface_internal_get_plane_data (surface, 1, &size, &offset, &pitch);
 272
 273    ...
 274
 275    tbm_surface_destroy (surface);
 276    @endcode
 277  */
 278 int tbm_surface_internal_get_plane_data(tbm_surface_h surface, int plane_idx,
 279                                         uint32_t *size, uint32_t *offset, uint32_t *pitch);
 280
 281 /**
 282  * @brief Gets number of planes by the format.
 283  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 284  * @param[in] format : the format of surface
 285  * @return number of planes by the format, otherwise 0.
 286  * @par Example
 287    @code
 288    #include <tbm_surface.h>
 289    #include <tbm_surface_internal.h>
 290
 291    int num;
 292
 293    num = tbm_surface_internal_get_num_planes (TBM_FORMAT_YUV420);
 294
 295    ...
 296
 297    @endcode
 298  */
 299 int tbm_surface_internal_get_num_planes(tbm_format format);
 300
 301 /**
 302  * @brief Gets bpp by the format.
 303  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 304  * @param[in] format : the format of surface
 305  * @return bpp by the format, otherwise 0.
 306  * @par Example
 307    @code
 308    #include <tbm_surface.h>
 309    #include <tbm_surface_internal.h>
 310
 311    int bpp;
 312
 313    bpp = tbm_surface_internal_get_bpp (TBM_FORMAT_YUV420);
 314
 315    ...
 316
 317    @endcode
 318  */
 319 int tbm_surface_internal_get_bpp(tbm_format format);
 320
 321 /**
 322  * @brief Gets bo index of plane.
 323  * @since_tizen 2.4
 324  * @param[in] surface : the tbm_surface_h
 325  * @param[in] plane_idx : the bo index in the tbm_surface
 326  * @return bo index of plane, otherwise 0.
 327  * @par Example
 328    @code
 329    #include <tbm_surface.h>
 330    #include <tbm_surface_internal.h>
 331
 332    int bo_idx;
 333    tbm_surface_h surface;
 334
 335    surface = tbm_surface_create (128, 128, TBM_FORMAT_YUV420);
 336    bo_idx = tbm_surface_internal_get_plane_bo_idx (surface, 0);
 337
 338    ...
 339
 340    @endcode
 341  */
 342 int tbm_surface_internal_get_plane_bo_idx(tbm_surface_h surface, int plane_idx);
 343
 344 /**
 345  * @brief Set the pid to the tbm_surface for debugging.
 346  * @since_tizen 3.0
 347  * @param[in] surface : the tbm_surface_h
 348  * @param[in] pid : the pid
 349  */
 350 void tbm_surface_internal_set_debug_pid(tbm_surface_h surface,
 351                                         unsigned int pid);
 352
 353 /**
 354  * @brief Set the string value to the tbm_surface for debugging.
 355  * @since_tizen 3.0
 356  * @param[in] surface : the tbm_surface_h
 357  * @param[in] key : the key for debugging
 358  * @param[in] value : the value for debugging
 359  */
 360 int tbm_surface_internal_set_debug_data(tbm_surface_h surface,
 361                                         char *key, char *value);
 362
 363 /**
 364  * @brief Adds a user_data to the tbm surface.
 365  * @since_tizen 3.0
 366  * @param[in] surface : the tbm surface.
 367  * @param[in] key : the key associated with the user_data
 368  * @param[in] data_free_func : the function pointer to free the user_data
 369  * @return 1 if this function succeeds, otherwise 0.
 370  * @post the tbm_surface_data_free() will be called under certain conditions, after calling tbm_surface_internal_delete_user_data().
 371  * @see tbm_surface_free()
 372  * @see tbm_surface_set_user_data()
 373  * @see tbm_surface_get_user_data()
 374  * @see tbm_surface_delete_user_data()
 375  */
 376 int tbm_surface_internal_add_user_data(tbm_surface_h surface, unsigned long key,
 377                                        tbm_data_free data_free_func);
 378
 379 /**
 380  * @brief Sets a user_date to the tbm surface.
 381  * @since_tizen 3.0
 382  * @param[in] surface : the tbm surface.
 383  * @param[in] key : the key associated with the user_date
 384  * @param[in] data : a pointer of the user_data
 385  * @return 1 if this function succeeds, otherwise 0.
 386  */
 387 int tbm_surface_internal_set_user_data(tbm_surface_h surface, unsigned long key,
 388                                        void *data);
 389
 390 /**
 391  * @brief Gets a user_data from the tbm surface with the key.
 392  * @since_tizen 3.0
 393  * @param[in] surface : the tbm surface.
 394  * @param[in] key : the key associated with the user_date
 395  * @param[out] data : to get the user data
 396  * @return 1 if this function succeeds, otherwise 0.
 397  */
 398 int tbm_surface_internal_get_user_data(tbm_surface_h surface, unsigned long key,
 399                                        void **data);
 400
 401 /**
 402  * @brief Deletes the user_data in the tbm surface.
 403  * @since_tizen 3.0
 404  * @param[in] surface : the tbm surface.
 405  * @param[in] key : the key associated with the user_date
 406  * @return 1 if this function succeeds, otherwise 0.
 407  */
 408 int tbm_surface_internal_delete_user_data(tbm_surface_h surface,
 409                                           unsigned long key);
 410
 411 /**
 412  * @brief Start the dump debugging.
 413  * @since_tizen 3.0
 414  * @param[in] path : the given dump path
 415  * @param[in] w : the width of dump image
 416  * @param[in] h : the height of dump image
 417  * @param[in] count : the dump count number
 418  * @see #tdm_helper_dump_stop()
 419  */
 420 void tbm_surface_internal_dump_start(char *path, int w, int h, int count);
 421
 422 /**
 423  * @brief Start the dump with scale debugging.
 424  * @details
 425  * Dump with scale supports only if a buffer has below formats.
 426  * - TBM_FORMAT_ARGB8888
 427  * - TBM_FORMAT_XRGB8888
 428  * @since_tizen 4.0
 429  * @param[in] path : the given dump path
 430  * @param[in] w : the width of dump image
 431  * @param[in] h : the height of dump image
 432  * @param[in] count : the dump count number
 433  * @param[in] scale : the scale factor
 434  * @see #tdm_helper_dump_stop()
 435  */
 436 void tbm_surface_internal_dump_with_scale_start(char *path, int w, int h,
 437                                           int count, double scale);
 438
 439 /**
 440  * @brief End the dump debugging.
 441  * @since_tizen 3.0
 442  * @see #tdm_helper_dump_start()
 443  */
 444 void tbm_surface_internal_dump_end(void);
 445
 446 /**
 447  * @brief Dump a buffer
 448  * @details
 449  * This function supports only if a buffer has below formats.
 450  * - TBM_FORMAT_ARGB8888
 451  * - TBM_FORMAT_XRGB8888
 452  * - TBM_FORMAT_YVU420
 453  * - TBM_FORMAT_YUV420
 454  * - TBM_FORMAT_NV12
 455  * - TBM_FORMAT_NV21
 456  * - TBM_FORMAT_YUYV
 457  * - TBM_FORMAT_UYVY
 458  * The filename extension should be "png" for TBM_FORMAT_ARGB8888 and TBM_FORMAT_XRGB8888
 459  * or "yuv" for YUV formats.
 460  * @param[in] surface : a tbm surface
 461  * @param[in] name : a string used by a file name
 462  */
 463 void tbm_surface_internal_dump_buffer(tbm_surface_h surface, const char *name);
 464
 465 /**
 466  * @brief Dump a shared memory buffer
 467  * @details
 468  * This function supports shared memory buffer dump.
 469  * @param[in] ptr : a pointer of dump buffer
 470  * @param[in] w : a width of dump buffer
 471  * @param[in] h : a height of dump buffer
 472  * @param[in] stride : a stride of dump buffer
 473  * @param[in] name : a string used by a file name
 474  */
 475 void tbm_surface_internal_dump_shm_buffer(void *ptr, int w, int h, int stride, const char *name);
 476
 477 /**
 478  * @brief check valid tbm surface.
 479  * @since_tizen 3.0
 480  * @param[in] surface : the tbm surface.
 481  * @return 1 if surface is valid, otherwise 0.
 482  */
 483 int tbm_surface_internal_is_valid(tbm_surface_h surface);
 484
 485 /**
 486  * @brief Capture a buffer
 487  * @details
 488  * This function supports only if a buffer has below formats.
 489  * - TBM_FORMAT_ARGB8888
 490  * - TBM_FORMAT_XRGB8888
 491  * - TBM_FORMAT_YVU420
 492  * - TBM_FORMAT_YUV420
 493  * - TBM_FORMAT_NV12
 494  * - TBM_FORMAT_NV21
 495  * - TBM_FORMAT_YUYV
 496  * - TBM_FORMAT_UYVY
 497  * The type should be "png" for TBM_FORMAT_ARGB8888 and TBM_FORMAT_XRGB8888
 498  * or "yuv" for YUV formats.
 499  * @param[in] surface : a tbm surface
 500  * @param[in] path : the given dump path
 501  * @param[in] name : a string used by a file name
 502  * @param[in] type : a string used by a file type ex)png, yuv
 503  * @return 1 if success, otherwise 0.
 504  */
 505 int tbm_surface_internal_capture_buffer(tbm_surface_h surface, const char *path,
 506                                        const char *name, const char *type);
 507
 508 /**
 509  * @brief Capture a shared memory buffer
 510  * @details
 511  * This function supports shared memory buffer dump.
 512  * The type should be "png".
 513  * @param[in] ptr : a pointer of dump buffer
 514  * @param[in] w : a width of dump buffer
 515  * @param[in] h : a height of dump buffer
 516  * @param[in] stride : a stride of dump buffer
 517  * @param[in] path : the given dump path
 518  * @param[in] name : a string used by a file name
 519  * @param[in] type : a string used by a file type ex)png, yuv
 520  * @return 1 if success, otherwise 0.
 521  */
 522 int tbm_surface_internal_capture_shm_buffer(void *ptr, int w, int h, int stride,
 523                                        const char *path, const char *name, const char *type);
 524
 525 /**
 526  * @brief Set damage to surface
 527  * @param[in] surface : a tbm surface
 528  * @param[in] x : a x coordinate of damage
 529  * @param[in] y : a y coordinate of damage
 530  * @param[in] with : a width of damage rectangle
 531  * @param[in] height : a height of damage rectangle
 532  * @return 1 if success, otherwise 0.
 533  */
 534 int tbm_surface_internal_set_damage(tbm_surface_h surface, int x, int y, int width, int height);
 535
 536 /**
 537  * @brief Get damage of surface
 538  * @param[in] surface : a tbm surface
 539  * @param[out] x : a x coordinate of damage
 540  * @param[out] y : a y coordinate of damage
 541  * @param[out] with : a width of damage rectangle
 542  * @param[out] height : a height of damage rectangle
 543  * @return 1 if success, otherwise 0.
 544  */
 545 int tbm_surface_internal_get_damage(tbm_surface_h surface, int *x, int *y, int *width, int *height);
 546
 547 #ifdef __cplusplus
 548 }
 549 #endif
 550 #endif                                                  /* _TBM_SURFACE_INTERNAL_H_ */