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 Gets the number of buffer objects associated with the tbm_surface.
 165  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 166  * @param[in] surface : the tbm_surface_h
 167  * @return the number of buffer objects associated with the tbm_surface_h, otherwise -1.
 168  * @par Example
 169    @code
 170    #include <tbm_surface.h>
 171    #include <tbm_surface_internal.h>
 172
 173    tbm_surface_h surface;
 174    int num_bos;
 175
 176    surface = tbm_surface_create (128, 128, TBM_FORMAT_YUV420);
 177    num_bos = tbm_surface_internal_get_num_bos (surface);
 178
 179    ...
 180
 181    tbm_surface_destroy (surface);
 182    @endcode
 183  */
 184 int tbm_surface_internal_get_num_bos (tbm_surface_h surface);
 185
 186 /**
 187  * @brief Gets the buffor object by the bo_index.
 188  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 189  * @param[in] surface : the tbm_surface_h
 190  * @param[in] bo_idx : the bo index in the the tbm_surface
 191  * @return the buffer object, otherwise NULL.
 192  * @retval #tbm_bo
 193  * @par Example
 194    @code
 195    #include <tbm_surface.h>
 196    #include <tbm_surface_internal.h>
 197
 198    tbm_surface_h surface;
 199    int num_bos;
 200    tbm_bo bo;
 201
 202    surface = tbm_surface_create (128, 128, TBM_FORMAT_YUV420);
 203    num_bos = tbm_surface_internal_get_num_bos (surface);
 204
 205    for (i=0 ; i < num_bos ; i++)
 206    {
 207        bo = tbm_surface_internal_get_bo (surface, i);
 208
 209    ...
 210
 211    tbm_surface_destroy (surface);
 212    @endcode
 213  */
 214 tbm_bo tbm_surface_internal_get_bo (tbm_surface_h surface, int bo_idx);
 215
 216 /**
 217  * @brief Gets the size of the surface.
 218  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 219  * @param[in] surface : the tbm_surface_h
 220  * @return the size of tbm_surface, otherwise -1.
 221  * @par Example
 222    @code
 223    #include <tbm_surface.h>
 224    #include <tbm_surface_internal.h>
 225
 226    tbm_surface_h surface;
 227    int size;
 228
 229    surface = tbm_surface_create (128, 128, TBM_FORMAT_YUV420);
 230    size = tbm_surface_internal_get_size (surface);
 231
 232    tbm_surface_destroy (surface);
 233    @endcode
 234  */
 235 int tbm_surface_internal_get_size (tbm_surface_h surface);
 236
 237 /**
 238  * @brief Gets size, offset and pitch data of plane by the plane_index.
 239  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 240  * @param[in] surface : the tbm_surface_h
 241  * @param[in] plane_idx : the bo index in the the tbm_surface
 242  * @param[out] size : the size of plan in tbm_surface
 243  * @param[out] offset : the offset of plan in tbm_surface
 244  * @param[out] pitch : the pitch of plan in tbm_surface
 245  * @return 1 if this function succeeds, otherwise 0.
 246  * @par Example
 247    @code
 248    #include <tbm_surface.h>
 249    #include <tbm_surface_internal.h>
 250
 251    tbm_surface_h surface;
 252    uint32_t size, offset, pitch;
 253    int ret;
 254
 255    surface = tbm_surfacel_create (128, 128, TBM_FORMAT_YUV420);
 256    ret = tbm_surface_internal_get_plane_data (surface, 1, &size, &offset, &pitch);
 257
 258    ...
 259
 260    tbm_surface_destroy (surface);
 261    @endcode
 262  */
 263 int tbm_surface_internal_get_plane_data (tbm_surface_h surface, int plane_idx, uint32_t *size, uint32_t *offset, uint32_t *pitch);
 264
 265 /**
 266  * @brief Gets number of planes by the format.
 267  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 268  * @param[in] format : the format of surface
 269  * @return number of planes by the format, otherwise 0.
 270  * @par Example
 271    @code
 272    #include <tbm_surface.h>
 273    #include <tbm_surface_internal.h>
 274
 275    int num;
 276
 277    num = tbm_surface_internal_get_num_planes (TBM_FORMAT_YUV420);
 278
 279    ...
 280
 281    @endcode
 282  */
 283 int tbm_surface_internal_get_num_planes (tbm_format format);
 284
 285 /**
 286  * @brief Gets bpp by the format.
 287  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 288  * @param[in] format : the format of surface
 289  * @return bpp by the format, otherwise 0.
 290  * @par Example
 291    @code
 292    #include <tbm_surface.h>
 293    #include <tbm_surface_internal.h>
 294
 295    int bpp;
 296
 297    bpp = tbm_surface_internal_get_bpp (TBM_FORMAT_YUV420);
 298
 299    ...
 300
 301    @endcode
 302  */
 303 int tbm_surface_internal_get_bpp (tbm_format format);
 304
 305 #ifdef __cplusplus
 306 }
 307 #endif
 308
 309 #endif /* _TBM_SURFACE_INTERNAL_H_ */
 310