src/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
  38 #ifdef __cplusplus
  39 extern "C" {
  40 #endif
  41
  42 /**
  43  * @brief Queries formats which the system can support.
  44  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  45  * @remarks The formats must be released using free().
  46  * @param[in] bufmgr : the buffer manager
  47  * @param[out] *formats : format array which the system can support. This pointer has to be freed by user.
  48  * @param[out] num : the number of formats.
  49  * @return a tbm_surface_h if this function succeeds, otherwise NULL
  50  * @par Example
  51    @code
  52    #include <tbm_surface.h>
  53    #include <tbm_surface_internal.h>
  54
  55    tbm_bufmgr bufmgr;
  56    uint32_t *formats;
  57    uint32_t format_num;
  58
  59    bufmgr = tbm_bufmgr_create (-1);
  60    ret = tbm_surface_internal_query_surpported_foramts (bufmgr, &formats, &format_num);
  61
  62    ...
  63
  64    free (foramts);
  65    tbm_surface_bufmgr_deinit (bufmgr);
  66    @endcode
  67  */
  68 int tbm_surface_internal_query_supported_formats(uint32_t **formats,
  69                                                  uint32_t *num);
  70
  71 /**
  72  * @brief Creates the tbm_surface with memory type.
  73  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  74  * @details
  75  * #TBM_BO_DEFAULT is default memory: it depends on the backend\n
  76  * #TBM_BO_SCANOUT is scanout memory\n
  77  * #TBM_BO_NONCACHABLE is non-cachable memory\n
  78  * #TBM_BO_WC is write-combine memory\n
  79  * #TBM_BO_VENDOR vendor specific memory: it depends on the tbm backend\n
  80  * @param[in] bufmgr : the buffer manager
  81  * @param[in] width  : the width of surface
  82  * @param[in] height : the height of surface
  83  * @param[in] format : the format of surface
  84  * @param[in] flags  : the flags of memory type
  85  * @return a tbm_surface_h if this function succeeds, otherwise NULL
  86  * @retval #tbm_surface_h
  87  * @par Example
  88    @code
  89    #include <tbm_surface.h>
  90    #include <tbm_surface_internal.h>
  91
  92    int bufmgr_fd
  93    tbm_bufmgr bufmgr;
  94    tbm_surface_h surface;
  95    uint32_t *format;
  96    uint32_t format_num;
  97
  98    bufmgr = tbm_bufmgr_create (bufmgr_fd);
  99    surface = tbm_surface_internal_create_with_flags (128, 128, TBM_FORMAT_YUV420, TBM_BO_DEFAULT);
 100
 101    ...
 102
 103    tbm_surface_destroy (surface);
 104    tbm_surface_bufmgr_deinit (bufmgr);
 105    @endcode
 106  */
 107 tbm_surface_h tbm_surface_internal_create_with_flags(int width, int height,
 108                                                      int format, int flags);
 109
 110 /**
 111  * @brief Creates the tbm_surface with buffer objects.
 112  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 113  * @param[in] bufmgr : the buffer manager
 114  * @param[in] width  : the width of surface
 115  * @param[in] height : the height of surface
 116  * @param[in] format : the format of surface
 117  * @param[in] *bos   : the array pointer of buffer objects
 118  * @param[in] num    : the number of buffer objects
 119  * @return a tbm_surface_h if this function succeeds, otherwise NULL
 120  * @retval #tbm_surface_h
 121  * @par Example
 122    @code
 123    #include <tbm_bufmgr.h>
 124    #include <tbm_surface.h>
 125    #include <tbm_surface_internal.h>
 126
 127    int bufmgr_fd
 128    tbm_bufmgr bufmgr;
 129    tbm_surface_h surface;
 130    tbm_surface_info_s info;
 131    uint32_t *format;
 132    uint32_t format_num;
 133    tbm_bo bo[1];
 134
 135    bufmgr = tbm_bufmgr_init (bufmgr_fd);
 136    bo[0] = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 137
 138    info.width = 128;
 139    info.height = 128;
 140    info.format = TBM_FORMAT_ARGB8888;
 141    info.bpp = 32;
 142    info.size = 65536;
 143    info.num_planes = 1;
 144    info.planes[0].size = 65536;
 145    info.planes[0].offset = 0;
 146    info.planes[0].stride = 512;
 147
 148    surface = tbm_surface_internal_create_with_bos (&info, bo, 1);
 149
 150    ...
 151
 152    tbm_surface_destroy (surface);
 153    tbm_surface_bufmgr_deinit (bufmgr);
 154    @endcode
 155  */
 156 tbm_surface_h tbm_surface_internal_create_with_bos(tbm_surface_info_s *info,
 157                                                    tbm_bo *bos, int num);
 158
 159 /**
 160  * @brief Destroy the tbm surface
 161     TODO:
 162  */
 163 void tbm_surface_internal_destroy(tbm_surface_h surface);
 164
 165 /**
 166  * @brief reference the tbm surface
 167     TODO:
 168  */
 169 void tbm_surface_internal_ref(tbm_surface_h surface);
 170
 171 /**
 172  * @brief unreference the tbm surface
 173     TODO:
 174  */
 175 void tbm_surface_internal_unref(tbm_surface_h surface);
 176
 177 /**
 178  * @brief Gets the number of buffer objects associated with the tbm_surface.
 179  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 180  * @param[in] surface : the tbm_surface_h
 181  * @return the number of buffer objects associated with the tbm_surface_h, otherwise -1.
 182  * @par Example
 183    @code
 184    #include <tbm_surface.h>
 185    #include <tbm_surface_internal.h>
 186
 187    tbm_surface_h surface;
 188    int num_bos;
 189
 190    surface = tbm_surface_create (128, 128, TBM_FORMAT_YUV420);
 191    num_bos = tbm_surface_internal_get_num_bos (surface);
 192
 193    ...
 194
 195    tbm_surface_destroy (surface);
 196    @endcode
 197  */
 198 int tbm_surface_internal_get_num_bos(tbm_surface_h surface);
 199
 200 /**
 201  * @brief Gets the buffor object by the bo_index.
 202  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 203  * @param[in] surface : the tbm_surface_h
 204  * @param[in] bo_idx : the bo index in the the tbm_surface
 205  * @return the buffer object, otherwise NULL.
 206  * @retval #tbm_bo
 207  * @par Example
 208    @code
 209    #include <tbm_surface.h>
 210    #include <tbm_surface_internal.h>
 211
 212    tbm_surface_h surface;
 213    int num_bos;
 214    tbm_bo bo;
 215
 216    surface = tbm_surface_create (128, 128, TBM_FORMAT_YUV420);
 217    num_bos = tbm_surface_internal_get_num_bos (surface);
 218
 219    for (i=0 ; i < num_bos ; i++)
 220    {
 221        bo = tbm_surface_internal_get_bo (surface, i);
 222
 223    ...
 224
 225    tbm_surface_destroy (surface);
 226    @endcode
 227  */
 228 tbm_bo tbm_surface_internal_get_bo(tbm_surface_h surface, int bo_idx);
 229
 230 /**
 231  * @brief Gets the size of the surface.
 232  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 233  * @param[in] surface : the tbm_surface_h
 234  * @return the size of tbm_surface, otherwise -1.
 235  * @par Example
 236    @code
 237    #include <tbm_surface.h>
 238    #include <tbm_surface_internal.h>
 239
 240    tbm_surface_h surface;
 241    int size;
 242
 243    surface = tbm_surface_create (128, 128, TBM_FORMAT_YUV420);
 244    size = tbm_surface_internal_get_size (surface);
 245
 246    tbm_surface_destroy (surface);
 247    @endcode
 248  */
 249 int tbm_surface_internal_get_size(tbm_surface_h surface);
 250
 251 /**
 252  * @brief Gets size, offset and pitch data of plane by the plane_index.
 253  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 254  * @param[in] surface : the tbm_surface_h
 255  * @param[in] plane_idx : the bo index in the the tbm_surface
 256  * @param[out] size : the size of plane in tbm_surface
 257  * @param[out] offset : the offset of plane in tbm_surface
 258  * @param[out] pitch : the pitch of plane in tbm_surface
 259  * @return 1 if this function succeeds, otherwise 0.
 260  * @par Example
 261    @code
 262    #include <tbm_surface.h>
 263    #include <tbm_surface_internal.h>
 264
 265    tbm_surface_h surface;
 266    uint32_t size, offset, pitch;
 267    int ret;
 268
 269    surface = tbm_surface_create (128, 128, TBM_FORMAT_YUV420);
 270    ret = tbm_surface_internal_get_plane_data (surface, 1, &size, &offset, &pitch);
 271
 272    ...
 273
 274    tbm_surface_destroy (surface);
 275    @endcode
 276  */
 277 int tbm_surface_internal_get_plane_data(tbm_surface_h surface, int plane_idx,
 278                                         uint32_t *size, uint32_t *offset, uint32_t *pitch);
 279
 280 /**
 281  * @brief Gets number of planes by the format.
 282  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 283  * @param[in] format : the format of surface
 284  * @return number of planes by the format, otherwise 0.
 285  * @par Example
 286    @code
 287    #include <tbm_surface.h>
 288    #include <tbm_surface_internal.h>
 289
 290    int num;
 291
 292    num = tbm_surface_internal_get_num_planes (TBM_FORMAT_YUV420);
 293
 294    ...
 295
 296    @endcode
 297  */
 298 int tbm_surface_internal_get_num_planes(tbm_format format);
 299
 300 /**
 301  * @brief Gets bpp by the format.
 302  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 303  * @param[in] format : the format of surface
 304  * @return bpp by the format, otherwise 0.
 305  * @par Example
 306    @code
 307    #include <tbm_surface.h>
 308    #include <tbm_surface_internal.h>
 309
 310    int bpp;
 311
 312    bpp = tbm_surface_internal_get_bpp (TBM_FORMAT_YUV420);
 313
 314    ...
 315
 316    @endcode
 317  */
 318 int tbm_surface_internal_get_bpp(tbm_format format);
 319
 320 /**
 321  * @brief Gets bo index of plane.
 322  * @since_tizen 2.4
 323  * @param[in] surface : the tbm_surface_h
 324  * @param[in] plane_idx : the bo index in the tbm_surface
 325  * @return bo index of plane, otherwise -1.
 326  * @par Example
 327    @code
 328    #include <tbm_surface.h>
 329    #include <tbm_surface_internal.h>
 330
 331    int bo_idx;
 332    tbm_surface_h surface;
 333
 334    surface = tbm_surface_create (128, 128, TBM_FORMAT_YUV420);
 335    bo_idx = tbm_surface_internal_get_plane_bo_idx (surface, 0);
 336
 337    ...
 338
 339    @endcode
 340  */
 341 int tbm_surface_internal_get_plane_bo_idx(tbm_surface_h surface, int plane_idx);
 342
 343 /**
 344  * @brief Set the pid to the tbm_surface for debugging.
 345  * @since_tizen 3.0
 346  * @param[in] surface : the tbm_surface_h
 347  * @param[in] pid : the pid
 348  */
 349 void tbm_surface_internal_set_debug_pid(tbm_surface_h surface,
 350                                         unsigned int pid);
 351
 352 /**
 353  * @brief Adds a user_data to the tbm surface.
 354  * @since_tizen 3.0
 355  * @param[in] surface : the tbm surface.
 356  * @param[in] key : the key associated with the user_data
 357  * @param[in] data_free_func : the function pointer to free the user_data
 358  * @return 1 if this function succeeds, otherwise 0.
 359  * @post the tbm_surface_data_free() will be called under certain conditions, after calling tbm_surface_internal_delete_user_data().
 360  * @see tbm_surface_free()
 361  * @see tbm_surface_set_user_data()
 362  * @see tbm_surface_get_user_data()
 363  * @see tbm_surface_delete_user_data()
 364  */
 365 int tbm_surface_internal_add_user_data(tbm_surface_h surface, unsigned long key,
 366                                        tbm_data_free data_free_func);
 367
 368 /**
 369  * @brief Sets a user_date to the tbm surface.
 370  * @since_tizen 3.0
 371  * @param[in] surface : the tbm surface.
 372  * @param[in] key : the key associated with the user_date
 373  * @param[in] data : a pointer of the user_data
 374  * @return 1 if this function succeeds, otherwise 0.
 375  */
 376 int tbm_surface_internal_set_user_data(tbm_surface_h surface, unsigned long key,
 377                                        void *data);
 378
 379 /**
 380  * @brief Gets a user_data from the tbm surface with the key.
 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[out] data : to get the user data
 385  * @return 1 if this function succeeds, otherwise 0.
 386  */
 387 int tbm_surface_internal_get_user_data(tbm_surface_h surface, unsigned long key,
 388                                        void **data);
 389
 390 /**
 391  * @brief Deletes the user_data in the tbm surface.
 392  * @since_tizen 3.0
 393  * @param[in] surface : the tbm surface.
 394  * @param[in] key : the key associated with the user_date
 395  * @return 1 if this function succeeds, otherwise 0.
 396  */
 397 int tbm_surface_internal_delete_user_data(tbm_surface_h surface,
 398                                           unsigned long key);
 399
 400 /**
 401  * @brief Start the dump debugging.
 402  * @since_tizen 3.0
 403  * @param[in] path : the given dump path
 404  * @param[in] w : the width of dump image
 405  * @param[in] h : the height of dump image
 406  * @param[in] count : the dump count number
 407  * @see #tdm_helper_dump_stop()
 408  */
 409 void tbm_surface_internal_dump_start(char *path, int w, int h, int count);
 410
 411 /**
 412  * @brief End the dump debugging.
 413  * @since_tizen 3.0
 414  * @see #tdm_helper_dump_start()
 415  */
 416 void tbm_surface_internal_dump_end(void);
 417
 418 /**
 419  * @brief Dump a buffer
 420  * @details
 421  * This function supports only if a buffer has below formats.
 422  * - TBM_FORMAT_ARGB8888
 423  * - TBM_FORMAT_XRGB8888
 424  * - TBM_FORMAT_YVU420
 425  * - TBM_FORMAT_YUV420
 426  * - TBM_FORMAT_NV12
 427  * - TBM_FORMAT_NV21
 428  * - TBM_FORMAT_YUYV
 429  * - TBM_FORMAT_UYVY
 430  * The filename extension should be "png" for TBM_FORMAT_ARGB8888 and TBM_FORMAT_XRGB8888
 431  * or "yuv" for YUV formats.
 432  * @param[in] surface : a tbm surface
 433  * @param[in] type : a string used by a file name
 434  */
 435 void tbm_surface_internal_dump_buffer(tbm_surface_h surface, const char *type);
 436
 437 /**
 438  * @brief Dump a shared memory buffer
 439  * @details
 440  * This function supports shared memory buffer dump.
 441  * @param[in] ptr : a pointer of dump buffer
 442  * @param[in] w : a width of dump buffer
 443  * @param[in] h : a height of dump buffer
 444  * @param[in] stride : a stride of dump buffer
 445  * @param[in] type : a string used by a file name
 446  */
 447 void tbm_surface_internal_dump_shm_buffer(void *ptr, int w, int h, int stride, const char *type);
 448
 449 /**
 450  * @brief check valid tbm surface.
 451  * @since_tizen 3.0
 452  * @param[in] surface : the tbm surface.
 453  * @return 1 if surface is valid, otherwise 0.
 454  */
 455 int tbm_surface_internal_is_valid(tbm_surface_h surface);
 456
 457 #ifdef __cplusplus
 458 }
 459 #endif
 460 #endif                                                  /* _TBM_SURFACE_INTERNAL_H_ */