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 2.3
  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 (tbm_bufmgr bufmgr, uint32_t **formats, uint32_t *num);
  69
  70 /**
  71  * @brief Creates the tbm_surface with memory type.
  72  * @since_tizen 2.3
  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 (bufmgr, 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 (tbm_bufmgr bufmgr, int width, int height, int format, int flags);
 107
 108 /**
 109  * @brief Creates the tbm_surface with buffer objects.
 110  * @since_tizen 2.3
 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    uint32_t *format;
 129    uint32_t format_num;
 130    tbm_bo bo[2];
 131
 132    bufmgr = tbm_bufmgr_init (bufmgr_fd);
 133    bo[1] = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 134    bo[2] = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
 135    surface = tbm_surface_internal_create_with_bos (bufmgr, 128, 128, TBM_FORMAT_YUV420, TBM_BO_DEFAULT);
 136
 137    ...
 138
 139    tbm_surface_destroy (surface);
 140    tbm_surface_bufmgr_deinit (bufmgr);
 141    @endcode
 142  */
 143 tbm_surface_h tbm_surface_internal_create_with_bos (tbm_bufmgr bufmgr, int width, int height, int format, tbm_bo *bos, int num);
 144
 145 /**
 146  * @brief Gets the number of buffer objects associated with the tbm_surface.
 147  * @since_tizen 2.3
 148  * @param[in] surface : the tbm_surface_h
 149  * @return the number of buffer objects associated with the tbm_surface_h, otherwise -1.
 150  * @par Example
 151    @code
 152    #include <tbm_surface.h>
 153    #include <tbm_surface_internal.h>
 154
 155    tbm_surface_h surface;
 156    int num_bos;
 157
 158    surface = tbm_surface_create (128, 128, TBM_FORMAT_YUV420);
 159    num_bos = tbm_surface_internal_get_num_bos (surface);
 160
 161    ...
 162
 163    tbm_surface_destroy (surface);
 164    @endcode
 165  */
 166 int tbm_surface_internal_get_num_bos (tbm_surface_h surface);
 167
 168 /**
 169  * @brief Gets the buffor object by the bo_index.
 170  * @since_tizen 2.3
 171  * @param[in] surface : the tbm_surface_h
 172  * @param[in] bo_idx : the bo index in the the tbm_surface
 173  * @return the buffer object, otherwise NULL.
 174  * @retval #tbm_bo
 175  * @par Example
 176    @code
 177    #include <tbm_surface.h>
 178    #include <tbm_surface_internal.h>
 179
 180    tbm_surface_h surface;
 181    int num_bos;
 182    tbm_bo bo;
 183
 184    surface = tbm_surface_create (128, 128, TBM_FORMAT_YUV420);
 185    num_bos = tbm_surface_internal_get_num_bos (surface);
 186
 187    for (i=0 ; i < num_bos ; i++)
 188    {
 189        bo = tbm_surface_internal_get_bo (surface, i);
 190
 191    ...
 192
 193    tbm_surface_destroy (surface);
 194    @endcode
 195  */
 196 tbm_bo tbm_surface_internal_get_bo (tbm_surface_h surface, int bo_idx);
 197
 198 /**
 199  * @brief Gets the size of the surface.
 200  * @since_tizen 2.3
 201  * @param[in] surface : the tbm_surface_h
 202  * @return the size of tbm_surface, otherwise -1.
 203  * @par Example
 204    @code
 205    #include <tbm_surface.h>
 206    #include <tbm_surface_internal.h>
 207
 208    tbm_surface_h surface;
 209    int size;
 210
 211    surface = tbm_surface_create (128, 128, TBM_FORMAT_YUV420);
 212    size = tbm_surface_internal_get_size (surface);
 213
 214    tbm_surface_destroy (surface);
 215    @endcode
 216  */
 217 int tbm_surface_internal_get_size (tbm_surface_h surface);
 218
 219 /**
 220  * @brief Gets size, offset and pitch data of plane by the plane_index.
 221  * @since_tizen 2.3
 222  * @param[in] surface : the tbm_surface_h
 223  * @param[in] plane_idx : the bo index in the the tbm_surface
 224  * @param[out] size : the size of plan in tbm_surface
 225  * @param[out] offset : the offset of plan in tbm_surface
 226  * @param[out] pitch : the pitch of plan in tbm_surface
 227  * @return 1 if this function succeeds, otherwise 0.
 228  * @par Example
 229    @code
 230    #include <tbm_surface.h>
 231    #include <tbm_surface_internal.h>
 232
 233    tbm_surface_h surface;
 234    uint32_t size, offset, pitch;
 235    int ret;
 236
 237    surface = tbm_surfacel_create (128, 128, TBM_FORMAT_YUV420);
 238    ret = tbm_surface_internal_get_plane_data (surface, 1, &size, &offset, &pitch);
 239
 240    ...
 241
 242    tbm_surface_destroy (surface);
 243    @endcode
 244  */
 245 int tbm_surface_internal_get_plane_data (tbm_surface_h surface, int plane_idx, uint32_t *size, uint32_t *offset, uint32_t *pitch);
 246
 247 #ifdef __cplusplus
 248 }
 249 #endif
 250
 251 #endif /* _TBM_SURFACE_INTERNAL_H_ */
 252