1 /**************************************************************************
5 Copyright 2014 Samsung Electronics co., Ltd. All Rights Reserved.
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>
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:
19 The above copyright notice and this permission notice (including the
20 next paragraph) shall be included in all copies or substantial portions
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.
31 **************************************************************************/
33 #ifndef _TBM_SURFACE_INTERNAL_H_
34 #define _TBM_SURFACE_INTERNAL_H_
36 #include <tbm_bufmgr.h>
37 #include <tbm_error.h>
44 * @brief Queries formats which the system can support.
45 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
46 * @remarks The formats must be released using free().
47 * @param[in] bufmgr : the buffer manager
48 * @param[out] *formats : format array which the system can support. This pointer has to be freed by user.
49 * @param[out] num : the number of formats.
50 * @return a tbm_surface_h if this function succeeds, otherwise NULL
53 #include <tbm_surface.h>
54 #include <tbm_surface_internal.h>
60 bufmgr = tbm_bufmgr_create (-1);
61 ret = tbm_surface_internal_query_surpported_foramts (bufmgr, &formats, &format_num);
66 tbm_surface_bufmgr_deinit (bufmgr);
69 int tbm_surface_internal_query_supported_formats(uint32_t **formats,
73 * @brief Creates the tbm_surface with memory type.
74 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
76 * #TBM_BO_DEFAULT is default memory: it depends on the backend\n
77 * #TBM_BO_SCANOUT is scanout memory\n
78 * #TBM_BO_NONCACHABLE is non-cachable memory\n
79 * #TBM_BO_WC is write-combine memory\n
80 * #TBM_BO_VENDOR vendor specific memory: it depends on the tbm backend\n
81 * @param[in] bufmgr : the buffer manager
82 * @param[in] width : the width of surface
83 * @param[in] height : the height of surface
84 * @param[in] format : the format of surface
85 * @param[in] flags : the flags of memory type
86 * @return a tbm_surface_h if this function succeeds, otherwise NULL
87 * @retval #tbm_surface_h
90 #include <tbm_surface.h>
91 #include <tbm_surface_internal.h>
95 tbm_surface_h surface;
99 bufmgr = tbm_bufmgr_create (bufmgr_fd);
100 surface = tbm_surface_internal_create_with_flags (128, 128, TBM_FORMAT_YUV420, TBM_BO_DEFAULT);
104 tbm_surface_destroy (surface);
105 tbm_surface_bufmgr_deinit (bufmgr);
108 tbm_surface_h tbm_surface_internal_create_with_flags(int width, int height,
109 int format, int flags);
112 * @brief Creates the tbm_surface with buffer objects.
113 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
114 * @param[in] bufmgr : the buffer manager
115 * @param[in] width : the width of surface
116 * @param[in] height : the height of surface
117 * @param[in] format : the format of surface
118 * @param[in] *bos : the array pointer of buffer objects
119 * @param[in] num : the number of buffer objects
120 * @return a tbm_surface_h if this function succeeds, otherwise NULL
121 * @retval #tbm_surface_h
124 #include <tbm_bufmgr.h>
125 #include <tbm_surface.h>
126 #include <tbm_surface_internal.h>
130 tbm_surface_h surface;
131 tbm_surface_info_s info;
136 bufmgr = tbm_bufmgr_init (bufmgr_fd);
137 bo[0] = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
141 info.format = TBM_FORMAT_ARGB8888;
145 info.planes[0].size = 65536;
146 info.planes[0].offset = 0;
147 info.planes[0].stride = 512;
149 surface = tbm_surface_internal_create_with_bos (&info, bo, 1);
153 tbm_surface_destroy (surface);
154 tbm_surface_bufmgr_deinit (bufmgr);
157 tbm_surface_h tbm_surface_internal_create_with_bos(tbm_surface_info_s *info,
158 tbm_bo *bos, int num);
161 * @brief Destroy the tbm surface
164 void tbm_surface_internal_destroy(tbm_surface_h surface);
167 * @brief reference the tbm surface
170 void tbm_surface_internal_ref(tbm_surface_h surface);
173 * @brief unreference the tbm surface
176 void tbm_surface_internal_unref(tbm_surface_h surface);
179 * @brief Gets the number of buffer objects associated with the tbm_surface.
180 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
181 * @param[in] surface : the tbm_surface_h
182 * @return the number of buffer objects associated with the tbm_surface_h, otherwise 0.
185 #include <tbm_surface.h>
186 #include <tbm_surface_internal.h>
188 tbm_surface_h surface;
191 surface = tbm_surface_create (128, 128, TBM_FORMAT_YUV420);
192 num_bos = tbm_surface_internal_get_num_bos (surface);
196 tbm_surface_destroy (surface);
199 int tbm_surface_internal_get_num_bos(tbm_surface_h surface);
202 * @brief Gets the buffor object by the bo_index.
203 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
204 * @param[in] surface : the tbm_surface_h
205 * @param[in] bo_idx : the bo index in the the tbm_surface
206 * @return the buffer object, otherwise NULL.
210 #include <tbm_surface.h>
211 #include <tbm_surface_internal.h>
213 tbm_surface_h surface;
217 surface = tbm_surface_create (128, 128, TBM_FORMAT_YUV420);
218 num_bos = tbm_surface_internal_get_num_bos (surface);
220 for (i=0 ; i < num_bos ; i++)
222 bo = tbm_surface_internal_get_bo (surface, i);
226 tbm_surface_destroy (surface);
229 tbm_bo tbm_surface_internal_get_bo(tbm_surface_h surface, int bo_idx);
232 * @brief Gets the size of the surface.
233 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
234 * @param[in] surface : the tbm_surface_h
235 * @return the size of tbm_surface, otherwise 0.
238 #include <tbm_surface.h>
239 #include <tbm_surface_internal.h>
241 tbm_surface_h surface;
244 surface = tbm_surface_create (128, 128, TBM_FORMAT_YUV420);
245 size = tbm_surface_internal_get_size (surface);
247 tbm_surface_destroy (surface);
250 unsigned int tbm_surface_internal_get_size(tbm_surface_h surface);
253 * @brief Gets size, offset and pitch data of plane by the plane_index.
254 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
255 * @param[in] surface : the tbm_surface_h
256 * @param[in] plane_idx : the bo index in the the tbm_surface
257 * @param[out] size : the size of plane in tbm_surface
258 * @param[out] offset : the offset of plane in tbm_surface
259 * @param[out] pitch : the pitch of plane in tbm_surface
260 * @return 1 if this function succeeds, otherwise 0.
263 #include <tbm_surface.h>
264 #include <tbm_surface_internal.h>
266 tbm_surface_h surface;
267 uint32_t size, offset, pitch;
270 surface = tbm_surface_create (128, 128, TBM_FORMAT_YUV420);
271 ret = tbm_surface_internal_get_plane_data (surface, 1, &size, &offset, &pitch);
275 tbm_surface_destroy (surface);
278 int tbm_surface_internal_get_plane_data(tbm_surface_h surface, int plane_idx,
279 uint32_t *size, uint32_t *offset, uint32_t *pitch);
282 * @brief Gets number of planes by the format.
283 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
284 * @param[in] format : the format of surface
285 * @return number of planes by the format, otherwise 0.
288 #include <tbm_surface.h>
289 #include <tbm_surface_internal.h>
293 num = tbm_surface_internal_get_num_planes (TBM_FORMAT_YUV420);
299 int tbm_surface_internal_get_num_planes(tbm_format format);
302 * @brief Gets bpp by the format.
303 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
304 * @param[in] format : the format of surface
305 * @return bpp by the format, otherwise 0.
308 #include <tbm_surface.h>
309 #include <tbm_surface_internal.h>
313 bpp = tbm_surface_internal_get_bpp (TBM_FORMAT_YUV420);
319 int tbm_surface_internal_get_bpp(tbm_format format);
322 * @brief Gets bo index of plane.
324 * @param[in] surface : the tbm_surface_h
325 * @param[in] plane_idx : the bo index in the tbm_surface
326 * @return bo index of plane, otherwise 0.
329 #include <tbm_surface.h>
330 #include <tbm_surface_internal.h>
333 tbm_surface_h surface;
335 surface = tbm_surface_create (128, 128, TBM_FORMAT_YUV420);
336 bo_idx = tbm_surface_internal_get_plane_bo_idx (surface, 0);
342 int tbm_surface_internal_get_plane_bo_idx(tbm_surface_h surface, int plane_idx);
345 * @brief Set the pid to the tbm_surface for debugging.
347 * @param[in] surface : the tbm_surface_h
348 * @param[in] pid : the pid
350 void tbm_surface_internal_set_debug_pid(tbm_surface_h surface,
354 * @brief Set the string value to the tbm_surface for debugging.
356 * @param[in] surface : the tbm_surface_h
357 * @param[in] key : the key for debugging
358 * @param[in] value : the value for debugging
360 int tbm_surface_internal_set_debug_data(tbm_surface_h surface,
361 char *key, char *value);
364 * @brief Adds a user_data to the tbm surface.
366 * @param[in] surface : the tbm surface.
367 * @param[in] key : the key associated with the user_data
368 * @param[in] data_free_func : the function pointer to free the user_data
369 * @return 1 if this function succeeds, otherwise 0.
370 * @post the tbm_surface_data_free() will be called under certain conditions, after calling tbm_surface_internal_delete_user_data().
371 * @see tbm_surface_free()
372 * @see tbm_surface_set_user_data()
373 * @see tbm_surface_get_user_data()
374 * @see tbm_surface_delete_user_data()
376 int tbm_surface_internal_add_user_data(tbm_surface_h surface, unsigned long key,
377 tbm_data_free data_free_func);
380 * @brief Sets a user_date to the tbm surface.
382 * @param[in] surface : the tbm surface.
383 * @param[in] key : the key associated with the user_date
384 * @param[in] data : a pointer of the user_data
385 * @return 1 if this function succeeds, otherwise 0.
387 int tbm_surface_internal_set_user_data(tbm_surface_h surface, unsigned long key,
391 * @brief Gets a user_data from the tbm surface with the key.
393 * @param[in] surface : the tbm surface.
394 * @param[in] key : the key associated with the user_date
395 * @param[out] data : to get the user data
396 * @return 1 if this function succeeds, otherwise 0.
398 int tbm_surface_internal_get_user_data(tbm_surface_h surface, unsigned long key,
402 * @brief Deletes the user_data in the tbm surface.
404 * @param[in] surface : the tbm surface.
405 * @param[in] key : the key associated with the user_date
406 * @return 1 if this function succeeds, otherwise 0.
408 int tbm_surface_internal_delete_user_data(tbm_surface_h surface,
412 * @brief Start the dump debugging.
414 * @param[in] path : the given dump path
415 * @param[in] w : the width of dump image
416 * @param[in] h : the height of dump image
417 * @param[in] count : the dump count number
418 * @see #tdm_helper_dump_stop()
420 void tbm_surface_internal_dump_start(char *path, int w, int h, int count);
423 * @brief Start the dump with scale debugging.
425 * Dump with scale supports only if a buffer has below formats.
426 * - TBM_FORMAT_ARGB8888
427 * - TBM_FORMAT_XRGB8888
429 * @param[in] path : the given dump path
430 * @param[in] w : the width of dump image
431 * @param[in] h : the height of dump image
432 * @param[in] count : the dump count number
433 * @param[in] scale : the scale factor
434 * @see #tdm_helper_dump_stop()
436 void tbm_surface_internal_dump_with_scale_start(char *path, int w, int h,
437 int count, double scale);
440 * @brief End the dump debugging.
442 * @see #tdm_helper_dump_start()
444 void tbm_surface_internal_dump_end(void);
447 * @brief Dump a buffer
449 * This function supports only if a buffer has below formats.
450 * - TBM_FORMAT_ARGB8888
451 * - TBM_FORMAT_XRGB8888
452 * - TBM_FORMAT_YVU420
453 * - TBM_FORMAT_YUV420
458 * The filename extension should be "png" for TBM_FORMAT_ARGB8888 and TBM_FORMAT_XRGB8888
459 * or "yuv" for YUV formats.
460 * @param[in] surface : a tbm surface
461 * @param[in] name : a string used by a file name
463 void tbm_surface_internal_dump_buffer(tbm_surface_h surface, const char *name);
466 * @brief Dump a shared memory buffer
468 * This function supports shared memory buffer dump.
469 * @param[in] ptr : a pointer of dump buffer
470 * @param[in] w : a width of dump buffer
471 * @param[in] h : a height of dump buffer
472 * @param[in] stride : a stride of dump buffer
473 * @param[in] name : a string used by a file name
475 void tbm_surface_internal_dump_shm_buffer(void *ptr, int w, int h, int stride, const char *name);
478 * @brief check valid tbm surface.
480 * @param[in] surface : the tbm surface.
481 * @return 1 if surface is valid, otherwise 0.
483 int tbm_surface_internal_is_valid(tbm_surface_h surface);
486 * @brief Capture a buffer
488 * This function supports only if a buffer has below formats.
489 * - TBM_FORMAT_ARGB8888
490 * - TBM_FORMAT_XRGB8888
491 * - TBM_FORMAT_YVU420
492 * - TBM_FORMAT_YUV420
497 * The type should be "png" for TBM_FORMAT_ARGB8888 and TBM_FORMAT_XRGB8888
498 * or "yuv" for YUV formats.
499 * @param[in] surface : a tbm surface
500 * @param[in] path : the given dump path
501 * @param[in] name : a string used by a file name
502 * @param[in] type : a string used by a file type ex)png, yuv
503 * @return 1 if success, otherwise 0.
505 int tbm_surface_internal_capture_buffer(tbm_surface_h surface, const char *path,
506 const char *name, const char *type);
509 * @brief Capture a shared memory buffer
511 * This function supports shared memory buffer dump.
512 * The type should be "png".
513 * @param[in] ptr : a pointer of dump buffer
514 * @param[in] w : a width of dump buffer
515 * @param[in] h : a height of dump buffer
516 * @param[in] stride : a stride of dump buffer
517 * @param[in] path : the given dump path
518 * @param[in] name : a string used by a file name
519 * @param[in] type : a string used by a file type ex)png, yuv
520 * @return 1 if success, otherwise 0.
522 int tbm_surface_internal_capture_shm_buffer(void *ptr, int w, int h, int stride,
523 const char *path, const char *name, const char *type);
528 #endif /* _TBM_SURFACE_INTERNAL_H_ */