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 (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 (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 (int width, int height, int format, tbm_bo *bos, int num);
 144
 145
 146 /**
 147  * @brief Destroy the tbm surface
 148     TODO:
 149  */
 150 void tbm_surface_internal_destroy (tbm_surface_h surface);
 151
 152 /**
 153  * @brief Gets the number of buffer objects associated with the tbm_surface.
 154  * @since_tizen 2.3
 155  * @param[in] surface : the tbm_surface_h
 156  * @return the number of buffer objects associated with the tbm_surface_h, otherwise -1.
 157  * @par Example
 158    @code
 159    #include <tbm_surface.h>
 160    #include <tbm_surface_internal.h>
 161
 162    tbm_surface_h surface;
 163    int num_bos;
 164
 165    surface = tbm_surface_create (128, 128, TBM_FORMAT_YUV420);
 166    num_bos = tbm_surface_internal_get_num_bos (surface);
 167
 168    ...
 169
 170    tbm_surface_destroy (surface);
 171    @endcode
 172  */
 173 int tbm_surface_internal_get_num_bos (tbm_surface_h surface);
 174
 175 /**
 176  * @brief Gets the buffor object by the bo_index.
 177  * @since_tizen 2.3
 178  * @param[in] surface : the tbm_surface_h
 179  * @param[in] bo_idx : the bo index in the the tbm_surface
 180  * @return the buffer object, otherwise NULL.
 181  * @retval #tbm_bo
 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    tbm_bo bo;
 190
 191    surface = tbm_surface_create (128, 128, TBM_FORMAT_YUV420);
 192    num_bos = tbm_surface_internal_get_num_bos (surface);
 193
 194    for (i=0 ; i < num_bos ; i++)
 195    {
 196        bo = tbm_surface_internal_get_bo (surface, i);
 197
 198    ...
 199
 200    tbm_surface_destroy (surface);
 201    @endcode
 202  */
 203 tbm_bo tbm_surface_internal_get_bo (tbm_surface_h surface, int bo_idx);
 204
 205 /**
 206  * @brief Gets the size of the surface.
 207  * @since_tizen 2.3
 208  * @param[in] surface : the tbm_surface_h
 209  * @return the size of tbm_surface, otherwise -1.
 210  * @par Example
 211    @code
 212    #include <tbm_surface.h>
 213    #include <tbm_surface_internal.h>
 214
 215    tbm_surface_h surface;
 216    int size;
 217
 218    surface = tbm_surface_create (128, 128, TBM_FORMAT_YUV420);
 219    size = tbm_surface_internal_get_size (surface);
 220
 221    tbm_surface_destroy (surface);
 222    @endcode
 223  */
 224 int tbm_surface_internal_get_size (tbm_surface_h surface);
 225
 226 /**
 227  * @brief Gets size, offset and pitch data of plane by the plane_index.
 228  * @since_tizen 2.3
 229  * @param[in] surface : the tbm_surface_h
 230  * @param[in] plane_idx : the bo index in the the tbm_surface
 231  * @param[out] size : the size of plan in tbm_surface
 232  * @param[out] offset : the offset of plan in tbm_surface
 233  * @param[out] pitch : the pitch of plan in tbm_surface
 234  * @return 1 if this function succeeds, otherwise 0.
 235  * @par Example
 236    @code
 237    #include <tbm_surface.h>
 238    #include <tbm_surface_internal.h>
 239
 240    tbm_surface_h surface;
 241    uint32_t size, offset, pitch;
 242    int ret;
 243
 244    surface = tbm_surfacel_create (128, 128, TBM_FORMAT_YUV420);
 245    ret = tbm_surface_internal_get_plane_data (surface, 1, &size, &offset, &pitch);
 246
 247    ...
 248
 249    tbm_surface_destroy (surface);
 250    @endcode
 251  */
 252 int tbm_surface_internal_get_plane_data (tbm_surface_h surface, int plane_idx, uint32_t *size, uint32_t *offset, uint32_t *pitch);
 253
 254 #ifdef __cplusplus
 255 }
 256 #endif
 257
 258 #endif /* _TBM_SURFACE_INTERNAL_H_ */
 259