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.with = 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 /**
 158  * @brief Destroy the tbm surface
 159     TODO:
 160  */
 161 void tbm_surface_internal_destroy (tbm_surface_h surface);
 162
 163 /**
 164  * @brief reference the tbm surface
 165     TODO:
 166  */
 167 void tbm_surface_internal_ref (tbm_surface_h surface);
 168
 169 /**
 170  * @brief unreference the tbm surface
 171     TODO:
 172  */
 173 void tbm_surface_internal_unref (tbm_surface_h surface);
 174
 175 /**
 176  * @brief Gets the number of buffer objects associated with the tbm_surface.
 177  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 178  * @param[in] surface : the tbm_surface_h
 179  * @return the number of buffer objects associated with the tbm_surface_h, otherwise -1.
 180  * @par Example
 181    @code
 182    #include <tbm_surface.h>
 183    #include <tbm_surface_internal.h>
 184
 185    tbm_surface_h surface;
 186    int num_bos;
 187
 188    surface = tbm_surface_create (128, 128, TBM_FORMAT_YUV420);
 189    num_bos = tbm_surface_internal_get_num_bos (surface);
 190
 191    ...
 192
 193    tbm_surface_destroy (surface);
 194    @endcode
 195  */
 196 int tbm_surface_internal_get_num_bos (tbm_surface_h surface);
 197
 198 /**
 199  * @brief Gets the buffor object by the bo_index.
 200  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 201  * @param[in] surface : the tbm_surface_h
 202  * @param[in] bo_idx : the bo index in the the tbm_surface
 203  * @return the buffer object, otherwise NULL.
 204  * @retval #tbm_bo
 205  * @par Example
 206    @code
 207    #include <tbm_surface.h>
 208    #include <tbm_surface_internal.h>
 209
 210    tbm_surface_h surface;
 211    int num_bos;
 212    tbm_bo bo;
 213
 214    surface = tbm_surface_create (128, 128, TBM_FORMAT_YUV420);
 215    num_bos = tbm_surface_internal_get_num_bos (surface);
 216
 217    for (i=0 ; i < num_bos ; i++)
 218    {
 219        bo = tbm_surface_internal_get_bo (surface, i);
 220
 221    ...
 222
 223    tbm_surface_destroy (surface);
 224    @endcode
 225  */
 226 tbm_bo tbm_surface_internal_get_bo (tbm_surface_h surface, int bo_idx);
 227
 228 /**
 229  * @brief Gets the size of the surface.
 230  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 231  * @param[in] surface : the tbm_surface_h
 232  * @return the size of tbm_surface, otherwise -1.
 233  * @par Example
 234    @code
 235    #include <tbm_surface.h>
 236    #include <tbm_surface_internal.h>
 237
 238    tbm_surface_h surface;
 239    int size;
 240
 241    surface = tbm_surface_create (128, 128, TBM_FORMAT_YUV420);
 242    size = tbm_surface_internal_get_size (surface);
 243
 244    tbm_surface_destroy (surface);
 245    @endcode
 246  */
 247 int tbm_surface_internal_get_size (tbm_surface_h surface);
 248
 249 /**
 250  * @brief Gets size, offset and pitch data of plane by the plane_index.
 251  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 252  * @param[in] surface : the tbm_surface_h
 253  * @param[in] plane_idx : the bo index in the the tbm_surface
 254  * @param[out] size : the size of plan in tbm_surface
 255  * @param[out] offset : the offset of plan in tbm_surface
 256  * @param[out] pitch : the pitch of plan in tbm_surface
 257  * @return 1 if this function succeeds, otherwise 0.
 258  * @par Example
 259    @code
 260    #include <tbm_surface.h>
 261    #include <tbm_surface_internal.h>
 262
 263    tbm_surface_h surface;
 264    uint32_t size, offset, pitch;
 265    int ret;
 266
 267    surface = tbm_surfacel_create (128, 128, TBM_FORMAT_YUV420);
 268    ret = tbm_surface_internal_get_plane_data (surface, 1, &size, &offset, &pitch);
 269
 270    ...
 271
 272    tbm_surface_destroy (surface);
 273    @endcode
 274  */
 275 int tbm_surface_internal_get_plane_data (tbm_surface_h surface, int plane_idx, uint32_t *size, uint32_t *offset, uint32_t *pitch);
 276
 277 /**
 278  * @brief Gets number of planes by the format.
 279  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 280  * @param[in] format : the format of surface
 281  * @return number of planes by the format, otherwise 0.
 282  * @par Example
 283    @code
 284    #include <tbm_surface.h>
 285    #include <tbm_surface_internal.h>
 286
 287    int num;
 288
 289    num = tbm_surface_internal_get_num_planes (TBM_FORMAT_YUV420);
 290
 291    ...
 292
 293    @endcode
 294  */
 295 int tbm_surface_internal_get_num_planes (tbm_format format);
 296
 297 /**
 298  * @brief Gets bpp by the format.
 299  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 300  * @param[in] format : the format of surface
 301  * @return bpp by the format, otherwise 0.
 302  * @par Example
 303    @code
 304    #include <tbm_surface.h>
 305    #include <tbm_surface_internal.h>
 306
 307    int bpp;
 308
 309    bpp = tbm_surface_internal_get_bpp (TBM_FORMAT_YUV420);
 310
 311    ...
 312
 313    @endcode
 314  */
 315 int tbm_surface_internal_get_bpp (tbm_format format);
 316
 317 /**
 318  * @brief Gets bo index of plane.
 319  * @since_tizen 2.4
 320  * @param[in] surface : the tbm_surface_h
 321  * @param[in] plane_idx : the bo index in the the tbm_surface
 322  * @return bo index of plane, otherwise -1.
 323  * @par Example
 324    @code
 325    #include <tbm_surface.h>
 326    #include <tbm_surface_internal.h>
 327
 328    int bo_idx;
 329    tbm_surface_h surface;
 330
 331    surface = tbm_surfacel_create (128, 128, TBM_FORMAT_YUV420);
 332    bo_idx = tbm_surface_internal_get_plane_bo_idx (surface, 0);
 333
 334    ...
 335
 336    @endcode
 337  */
 338 int tbm_surface_internal_get_plane_bo_idx (tbm_surface_h surface, int plane_idx);
 339
 340 /**
 341  * @brief Set the pid to the tbm_surface for debugging.
 342  * @since_tizen 3.0
 343  * @param[in] surface : the tbm_surface_h
 344  * @param[in] pid : the pid
 345  */
 346 void tbm_surface_internal_set_debug_pid(tbm_surface_h surface, unsigned int pid);
 347
 348 #ifdef __cplusplus
 349 }
 350 #endif
 351
 352 #endif /* _TBM_SURFACE_INTERNAL_H_ */
 353