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, uint32_t * num);
  69
  70 /**
  71  * @brief Creates the tbm_surface with memory type.
  72  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  73  * @details
  74  * #TBM_BO_DEFAULT is default memory: it depends on the backend\n
  75  * #TBM_BO_SCANOUT is scanout memory\n
  76  * #TBM_BO_NONCACHABLE is non-cachable memory\n
  77  * #TBM_BO_WC is write-combine memory\n
  78  * #TBM_BO_VENDOR vendor specific memory: it depends on the tbm backend\n
  79  * @param[in] bufmgr : the buffer manager
  80  * @param[in] width  : the width of surface
  81  * @param[in] height : the height of surface
  82  * @param[in] format : the format of surface
  83  * @param[in] flags  : the flags of memory type
  84  * @return a tbm_surface_h if this function succeeds, otherwise NULL
  85  * @retval #tbm_surface_h
  86  * @par Example
  87    @code
  88    #include <tbm_surface.h>
  89    #include <tbm_surface_internal.h>
  90
  91    int bufmgr_fd
  92    tbm_bufmgr bufmgr;
  93    tbm_surface_h surface;
  94    uint32_t *format;
  95    uint32_t format_num;
  96
  97    bufmgr = tbm_bufmgr_create (bufmgr_fd);
  98    surface = tbm_surface_internal_create_with_flags (128, 128, TBM_FORMAT_YUV420, TBM_BO_DEFAULT);
  99
 100    ...
 101
 102    tbm_surface_destroy (surface);
 103    tbm_surface_bufmgr_deinit (bufmgr);
 104    @endcode
 105  */
 106 tbm_surface_h tbm_surface_internal_create_with_flags(int width, int height, int format, int flags);
 107
 108 /**
 109  * @brief Creates the tbm_surface with buffer objects.
 110  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 111  * @param[in] bufmgr : the buffer manager
 112  * @param[in] width  : the width of surface
 113  * @param[in] height : the height of surface
 114  * @param[in] format : the format of surface
 115  * @param[in] *bos   : the array pointer of buffer objects
 116  * @param[in] num    : the number of buffer objects
 117  * @return a tbm_surface_h if this function succeeds, otherwise NULL
 118  * @retval #tbm_surface_h
 119  * @par Example
 120    @code
 121    #include <tbm_bufmgr.h>
 122    #include <tbm_surface.h>
 123    #include <tbm_surface_internal.h>
 124
 125    int bufmgr_fd
 126    tbm_bufmgr bufmgr;
 127    tbm_surface_h surface;
 128    tbm_surface_info_s info;
 129    uint32_t *format;
 130    uint32_t format_num;
 131    tbm_bo bo[1];
 132
 133    bufmgr = tbm_bufmgr_init (bufmgr_fd);
 134    bo[0] = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 135
 136    info.width = 128;
 137    info.height = 128;
 138    info.format = TBM_FORMAT_ARGB8888;
 139    info.bpp = 32;
 140    info.size = 65536;
 141    info.num_planes = 1;
 142    info.planes[0].size = 65536;
 143    info.planes[0].offset = 0;
 144    info.planes[0].stride = 512;
 145
 146    surface = tbm_surface_internal_create_with_bos (&info, bo, 1);
 147
 148    ...
 149
 150    tbm_surface_destroy (surface);
 151    tbm_surface_bufmgr_deinit (bufmgr);
 152    @endcode
 153  */
 154 tbm_surface_h tbm_surface_internal_create_with_bos(tbm_surface_info_s * info, tbm_bo * bos, int num);
 155
 156 /**
 157  * @brief Destroy the tbm surface
 158     TODO:
 159  */
 160 void tbm_surface_internal_destroy(tbm_surface_h surface);
 161
 162 /**
 163  * @brief reference the tbm surface
 164     TODO:
 165  */
 166 void tbm_surface_internal_ref(tbm_surface_h surface);
 167
 168 /**
 169  * @brief unreference the tbm surface
 170     TODO:
 171  */
 172 void tbm_surface_internal_unref(tbm_surface_h surface);
 173
 174 /**
 175  * @brief Gets the number of buffer objects associated with the tbm_surface.
 176  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 177  * @param[in] surface : the tbm_surface_h
 178  * @return the number of buffer objects associated with the tbm_surface_h, otherwise -1.
 179  * @par Example
 180    @code
 181    #include <tbm_surface.h>
 182    #include <tbm_surface_internal.h>
 183
 184    tbm_surface_h surface;
 185    int num_bos;
 186
 187    surface = tbm_surface_create (128, 128, TBM_FORMAT_YUV420);
 188    num_bos = tbm_surface_internal_get_num_bos (surface);
 189
 190    ...
 191
 192    tbm_surface_destroy (surface);
 193    @endcode
 194  */
 195 int tbm_surface_internal_get_num_bos(tbm_surface_h surface);
 196
 197 /**
 198  * @brief Gets the buffor object by the bo_index.
 199  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 200  * @param[in] surface : the tbm_surface_h
 201  * @param[in] bo_idx : the bo index in the the tbm_surface
 202  * @return the buffer object, otherwise NULL.
 203  * @retval #tbm_bo
 204  * @par Example
 205    @code
 206    #include <tbm_surface.h>
 207    #include <tbm_surface_internal.h>
 208
 209    tbm_surface_h surface;
 210    int num_bos;
 211    tbm_bo bo;
 212
 213    surface = tbm_surface_create (128, 128, TBM_FORMAT_YUV420);
 214    num_bos = tbm_surface_internal_get_num_bos (surface);
 215
 216    for (i=0 ; i < num_bos ; i++)
 217    {
 218        bo = tbm_surface_internal_get_bo (surface, i);
 219
 220    ...
 221
 222    tbm_surface_destroy (surface);
 223    @endcode
 224  */
 225 tbm_bo tbm_surface_internal_get_bo(tbm_surface_h surface, int bo_idx);
 226
 227 /**
 228  * @brief Gets the size of the surface.
 229  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 230  * @param[in] surface : the tbm_surface_h
 231  * @return the size of tbm_surface, otherwise -1.
 232  * @par Example
 233    @code
 234    #include <tbm_surface.h>
 235    #include <tbm_surface_internal.h>
 236
 237    tbm_surface_h surface;
 238    int size;
 239
 240    surface = tbm_surface_create (128, 128, TBM_FORMAT_YUV420);
 241    size = tbm_surface_internal_get_size (surface);
 242
 243    tbm_surface_destroy (surface);
 244    @endcode
 245  */
 246 int tbm_surface_internal_get_size(tbm_surface_h surface);
 247
 248 /**
 249  * @brief Gets size, offset and pitch data of plane by the plane_index.
 250  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 251  * @param[in] surface : the tbm_surface_h
 252  * @param[in] plane_idx : the bo index in the the tbm_surface
 253  * @param[out] size : the size of plane in tbm_surface
 254  * @param[out] offset : the offset of plane in tbm_surface
 255  * @param[out] pitch : the pitch of plane in tbm_surface
 256  * @return 1 if this function succeeds, otherwise 0.
 257  * @par Example
 258    @code
 259    #include <tbm_surface.h>
 260    #include <tbm_surface_internal.h>
 261
 262    tbm_surface_h surface;
 263    uint32_t size, offset, pitch;
 264    int ret;
 265
 266    surface = tbm_surface_create (128, 128, TBM_FORMAT_YUV420);
 267    ret = tbm_surface_internal_get_plane_data (surface, 1, &size, &offset, &pitch);
 268
 269    ...
 270
 271    tbm_surface_destroy (surface);
 272    @endcode
 273  */
 274 int tbm_surface_internal_get_plane_data(tbm_surface_h surface, int plane_idx, uint32_t * size, uint32_t * offset, uint32_t * pitch);
 275
 276 /**
 277  * @brief Gets number of planes by the format.
 278  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 279  * @param[in] format : the format of surface
 280  * @return number of planes by the format, otherwise 0.
 281  * @par Example
 282    @code
 283    #include <tbm_surface.h>
 284    #include <tbm_surface_internal.h>
 285
 286    int num;
 287
 288    num = tbm_surface_internal_get_num_planes (TBM_FORMAT_YUV420);
 289
 290    ...
 291
 292    @endcode
 293  */
 294 int tbm_surface_internal_get_num_planes(tbm_format format);
 295
 296 /**
 297  * @brief Gets bpp by the format.
 298  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 299  * @param[in] format : the format of surface
 300  * @return bpp by the format, otherwise 0.
 301  * @par Example
 302    @code
 303    #include <tbm_surface.h>
 304    #include <tbm_surface_internal.h>
 305
 306    int bpp;
 307
 308    bpp = tbm_surface_internal_get_bpp (TBM_FORMAT_YUV420);
 309
 310    ...
 311
 312    @endcode
 313  */
 314 int tbm_surface_internal_get_bpp(tbm_format format);
 315
 316 /**
 317  * @brief Gets bo index of plane.
 318  * @since_tizen 2.4
 319  * @param[in] surface : the tbm_surface_h
 320  * @param[in] plane_idx : the bo index in the tbm_surface
 321  * @return bo index of plane, otherwise -1.
 322  * @par Example
 323    @code
 324    #include <tbm_surface.h>
 325    #include <tbm_surface_internal.h>
 326
 327    int bo_idx;
 328    tbm_surface_h surface;
 329
 330    surface = tbm_surface_create (128, 128, TBM_FORMAT_YUV420);
 331    bo_idx = tbm_surface_internal_get_plane_bo_idx (surface, 0);
 332
 333    ...
 334
 335    @endcode
 336  */
 337 int tbm_surface_internal_get_plane_bo_idx(tbm_surface_h surface, int plane_idx);
 338
 339 /**
 340  * @brief Set the pid to the tbm_surface for debugging.
 341  * @since_tizen 3.0
 342  * @param[in] surface : the tbm_surface_h
 343  * @param[in] pid : the pid
 344  */
 345 void tbm_surface_internal_set_debug_pid(tbm_surface_h surface, unsigned int pid);
 346
 347 /**
 348  * @brief Adds a user_data to the tbm surface.
 349  * @since_tizen 3.0
 350  * @param[in] surface : the tbm surface.
 351  * @param[in] key : the key associated with the user_data
 352  * @param[in] data_free_func : the function pointer to free the user_data
 353  * @return 1 if this function succeeds, otherwise 0.
 354  * @post the tbm_surface_data_free() will be called under certain conditions, after calling tbm_surface_internal_delete_user_data().
 355  * @see tbm_surface_free()
 356  * @see tbm_surface_set_user_data()
 357  * @see tbm_surface_get_user_data()
 358  * @see tbm_surface_delete_user_data()
 359  */
 360 int tbm_surface_internal_add_user_data(tbm_surface_h surface, unsigned long key, tbm_data_free data_free_func);
 361
 362 /**
 363  * @brief Sets a user_date to the tbm surface.
 364  * @since_tizen 3.0
 365  * @param[in] surface : the tbm surface.
 366  * @param[in] key : the key associated with the user_date
 367  * @param[in] data : a pointer of the user_data
 368  * @return 1 if this function succeeds, otherwise 0.
 369  */
 370 int tbm_surface_internal_set_user_data(tbm_surface_h surface, unsigned long key, void *data);
 371
 372 /**
 373  * @brief Gets a user_data from the tbm surface with the key.
 374  * @since_tizen 3.0
 375  * @param[in] surface : the tbm surface.
 376  * @param[in] key : the key associated with the user_date
 377  * @param[out] data : to get the user data
 378  * @return 1 if this function succeeds, otherwise 0.
 379  */
 380 int tbm_surface_internal_get_user_data(tbm_surface_h surface, unsigned long key, void **data);
 381
 382 /**
 383  * @brief Deletes the user_data in the tbm surface.
 384  * @since_tizen 3.0
 385  * @param[in] surface : the tbm surface.
 386  * @param[in] key : the key associated with the user_date
 387  * @return 1 if this function succeeds, otherwise 0.
 388  */
 389 int tbm_surface_internal_delete_user_data(tbm_surface_h surface, unsigned long key);
 390
 391 #ifdef __cplusplus
 392 }
 393 #endif
 394 #endif                                                  /* _TBM_SURFACE_INTERNAL_H_ */