tbm_bufmgr_debug: change signature of tbm_bufmgr_debug_tbm_info_get
[platform/core/uifw/libtbm.git] / src / tbm_bufmgr.h
1 /**************************************************************************
2
3 libtbm
4
5 Copyright 2012 Samsung Electronics co., Ltd. All Rights Reserved.
6
7 Contact: SooChan Lim <sc1.lim@samsung.com>, Sangjin Lee <lsj119@samsung.com>
8 Boram Park <boram1288.park@samsung.com>, Changyeon Lee <cyeon.lee@samsung.com>
9
10 Permission is hereby granted, free of charge, to any person obtaining a
11 copy of this software and associated documentation files (the
12 "Software"), to deal in the Software without restriction, including
13 without limitation the rights to use, copy, modify, merge, publish,
14 distribute, sub license, and/or sell copies of the Software, and to
15 permit persons to whom the Software is furnished to do so, subject to
16 the following conditions:
17
18 The above copyright notice and this permission notice (including the
19 next paragraph) shall be included in all copies or substantial portions
20 of the Software.
21
22 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
23 OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
24 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.
25 IN NO EVENT SHALL PRECISION INSIGHT AND/OR ITS SUPPLIERS BE LIABLE FOR
26 ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
27 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
28 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
29
30 **************************************************************************/
31
32 #ifndef _TBM_BUFMGR_H_
33 #define _TBM_BUFMGR_H_
34
35 #include <tbm_type.h>
36 #include <stdint.h>
37
38 /* tbm error base : this error base is same as TIZEN_ERROR_TBM in tizen_error.h */
39 #ifndef TBM_ERROR_BASE
40 #define TBM_ERROR_BASE                  -0x02830000
41 #endif
42
43 /**
44  * \file tbm_bufmgr.h
45  * \brief Tizen Buffer Manager
46  */
47
48 /**
49  * @brief Definition for the tizen buffer manager
50  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
51  */
52 typedef struct _tbm_bufmgr *tbm_bufmgr;
53
54 /**
55  * @brief Definition for the tizen buffer object
56  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
57  */
58 typedef struct _tbm_bo *tbm_bo;
59 /**
60  * @brief Definition for the key associated with the buffer object
61  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
62  */
63 typedef uint32_t tbm_key;
64 /**
65  * @brief Definition for the file descripter of the system buffer manager
66  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
67  */
68 typedef int32_t tbm_fd;
69
70 /* TBM_DEVICE_TYPE */
71
72 /**
73  * @brief Definition for the device type to get the default handle
74  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
75  */
76 #define TBM_DEVICE_DEFAULT   0
77 /**
78  * @brief Definition for the device type to get the virtual memory
79  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
80  */
81 #define TBM_DEVICE_CPU       1
82 /**
83  * @brief Definition for the device type to get the 2D memory handle
84  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
85  */
86 #define TBM_DEVICE_2D        2
87 /**
88  * @brief Definition for the device type to get the 3D memory handle
89  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
90  */
91 #define TBM_DEVICE_3D        3
92 /**
93  * @brief Definition for the device type to get the multimedia handle
94  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
95  */
96 #define TBM_DEVICE_MM        4
97
98 /* TBM_OPTION */
99
100 /**
101  * @brief Definition for the access option to read
102  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
103  */
104 #define TBM_OPTION_READ      (1 << 0)
105 /**
106  * @brief Definition for the access option to write
107  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
108  */
109 #define TBM_OPTION_WRITE     (1 << 1)
110 /**
111  * @brief Definition for the vendor specific option that depends on the backend
112  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
113  */
114 #define TBM_OPTION_VENDOR    (0xffff0000)
115
116 /**
117  * @brief tbm_bo_handle abstraction of the memory handle by TBM_DEVICE_TYPE
118  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
119  */
120 typedef union _tbm_bo_handle {
121         void *ptr;
122         int32_t s32;
123         uint32_t u32;
124         int64_t s64;
125         uint64_t u64;
126 } tbm_bo_handle;
127
128 /**
129  * @brief Enumeration of bo memory type
130  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
131  */
132 enum TBM_BO_FLAGS {
133         TBM_BO_DEFAULT = 0,                        /**< default memory: it depends on the backend         */
134         TBM_BO_SCANOUT = (1 << 0),         /**< scanout memory                                    */
135         TBM_BO_NONCACHABLE = (1 << 1), /**< non-cachable memory                               */
136         TBM_BO_WC = (1 << 2),              /**< write-combine memory                              */
137         TBM_BO_VENDOR = (0xffff0000), /**< vendor specific memory: it depends on the backend */
138 };
139
140 /**
141  * @brief Enumeration for tbm error type.
142  * @since_tizen 2.4
143  */
144 typedef enum {
145         TBM_ERROR_NONE = 0,                                             /**< Successful */
146         TBM_BO_ERROR_GET_FD_FAILED = TBM_ERROR_BASE | 0x0101,     /**< failed to get fd failed */
147         TBM_BO_ERROR_HEAP_ALLOC_FAILED = TBM_ERROR_BASE | 0x0102, /**< failed to allocate the heap memory */
148         TBM_BO_ERROR_LOAD_MODULE_FAILED = TBM_ERROR_BASE | 0x0103,/**< failed to load module*/
149         TBM_BO_ERROR_THREAD_INIT_FAILED = TBM_ERROR_BASE | 0x0104,/**< failed to initialize the pthread */
150         TBM_BO_ERROR_BO_ALLOC_FAILED = TBM_ERROR_BASE | 0x0105,   /**< failed to allocate tbm_bo */
151         TBM_BO_ERROR_INIT_STATE_FAILED = TBM_ERROR_BASE | 0x0106, /**< failed to initialize the state of tbm_bo */
152         TBM_BO_ERROR_IMPORT_FAILED = TBM_ERROR_BASE | 0x0107,     /**< failed to import the handle of tbm_bo */
153         TBM_BO_ERROR_IMPORT_FD_FAILED = TBM_ERROR_BASE | 0x0108,  /**< failed to import fd of tbm_bo */
154         TBM_BO_ERROR_EXPORT_FAILED = TBM_ERROR_BASE | 0x0109,     /**< failed to export the handle of the tbm_bo */
155         TBM_BO_ERROR_EXPORT_FD_FAILED = TBM_ERROR_BASE | 0x01010, /**< failed to export fd of tbm_bo */
156         TBM_BO_ERROR_GET_HANDLE_FAILED = TBM_ERROR_BASE | 0x0111, /**< failed to get the tbm_bo_handle */
157         TBM_BO_ERROR_LOCK_FAILED = TBM_ERROR_BASE | 0x0112,               /**< failed to lock the tbm_bo */
158         TBM_BO_ERROR_MAP_FAILED = TBM_ERROR_BASE | 0x0113,                /**< failed to map the tbm_bo to get the tbm_bo_handle */
159         TBM_BO_ERROR_UNMAP_FAILED = TBM_ERROR_BASE | 0x0114,      /**< failed to unmap the tbm_bo */
160         TBM_BO_ERROR_SWAP_FAILED = TBM_ERROR_BASE | 0x0115,               /**< failed to swap the tbm_bos */
161         TBM_BO_ERROR_DUP_FD_FAILED = TBM_ERROR_BASE | 0x0116,     /**< failed to duplicate fd */
162 } tbm_error_e;
163
164 /**
165  * @brief Enumeration of tbm buffer manager capability.
166  * @since_tizen 2.4
167  */
168 enum TBM_BUFMGR_CAPABILITY {
169         TBM_BUFMGR_CAPABILITY_NONE = 0,                                 /**< Not Support capability*/
170         TBM_BUFMGR_CAPABILITY_SHARE_KEY = (1 << 0),             /**< Support sharing buffer by tbm key */
171         TBM_BUFMGR_CAPABILITY_SHARE_FD = (1 << 1),              /**< Support sharing buffer by tbm fd */
172         TBM_BUFMGR_CAPABILITY_TBM_SYNC = (1 << 2),              /**< Support tbm sync */
173 };
174
175 #ifdef __cplusplus
176 extern "C" {
177 #endif
178
179 /* Functions for buffer manager */
180
181 /**
182  * @brief Initializes the buffer manager.
183  * @details If fd is lower than zero, fd is get drm fd in tbm_bufmgr_init function\n
184  * The user can decide the lock type and cache flush type with the environment variables, which are BUFMGR_LOCK_TYPE and BUFMGR_MAP_CACHE.\n
185  * \n
186  * BUFMGR_LOCK default is once\n
187  * once : The previous bo which is locked is unlock when the new bo is trying to be locked\n
188  * always : The new bo is locked until the previous bo which is locked is unlocked\n
189  * never : Every bo is never locked.\n
190  * \n
191  * BUFMGR_MAP_CACHE default is true\n
192  * true : use map cache flushing\n
193  * false : to use map cache flushing
194  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
195  * @param[in] fd : file descripter of the system buffer manager
196  * @return a buffer manager
197  * @retval #tbm_bufmgr
198  * @see tbm_bufmgr_deinit();
199  * @par Example
200    @code
201    #include <tbm_bufmgr.h>
202    int bufmgr_fd;
203
204    setenv("BUFMGR_LOCK_TYPE", "once", 1);
205    setenv("BUFMGR_MAP_CACHE", "true", 1);
206
207    tbm_bufmgr bufmgr;
208    bufmgr = tbm_bufmgr_init (bufmgr_fd);
209
210    ....
211
212    tbm_bufmgr_deinit (bufmgr);
213    @endcode
214  */
215 tbm_bufmgr tbm_bufmgr_init(int fd);
216
217 /**
218  * @brief Deinitializes the buffer manager.
219  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
220  * @param[in] bufmgr : the buffer manager
221  * @see tbm_bufmgr_init()
222  * @par Example
223    @code
224    #include <tbm_bufmgr.h>
225
226    int bufmgr_fd;
227    tbm_bufmgr bufmgr;
228    tbm_error_e error;
229    bufmgr = tbm_bufmgr_init (bufmgr_fd);
230    if (!bufmgr)
231    {
232       error = tbm_get_last_error ();
233       ...
234    }
235
236    ....
237
238    tbm_bufmgr_deinit (bufmgr);
239    @endcode
240  */
241 void tbm_bufmgr_deinit(tbm_bufmgr bufmgr);
242
243 /* Functions for bo */
244
245 /**
246  * @brief Allocates the buffer object.
247  * @details This function create tbm_bo and set reference count to 1.\n
248  * The user can craete tbm_bo with memory type flag #TBM_BO_FLAGS\n\n
249  * #TBM_BO_DEFAULT indecates default memory: it depends on the backend\n
250  * #TBM_BO_SCANOUT indecates scanout memory\n
251  * #TBM_BO_NONCACHABLE indecates non-cachable memory\n
252  * #TBM_BO_WC indecates write-combine memory\n
253  * #TBM_BO_VENDOR indecates vendor specific memory: it depends on the tbm backend
254  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
255  * @param[in] bufmgr : the buffer manager
256  * @param[in] size : the size of buffer object
257  * @param[in] flags : the flags of memory type
258  * @return a buffer object
259  * @retval #tbm_bo
260  * @par Example
261    @code
262    #include <tbm_bufmgr.h>
263
264    int bufmgr_fd;
265    tbm_bufmgr bufmgr;
266    tbm_bo;
267    tbm_error_e error;
268
269    bufmgr = tbm_bufmgr_init (bufmgr_fd);
270    bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
271    if (!bo)
272    {
273       error = tbm_get_last_error ();
274       ...
275    }
276
277    ....
278
279    tbm_bufmgr_deinit (bufmgr);
280    @endcode
281  */
282 tbm_bo tbm_bo_alloc(tbm_bufmgr bufmgr, int size, int flags);
283
284 /**
285  * @brief Increases the reference count of bo.
286  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
287  * @param[in] bo : the buffer object
288  * @return a buffer object
289  * @retval #tbm_bo
290  * @see tbm_bo_unref()
291  * @par Example
292    @code
293    #include <tbm_bufmgr.h>
294
295    int bufmgr_fd;
296    tbm_bufmgr bufmgr;
297    tbm_bo bo;
298
299    bufmgr = tbm_bufmgr_init (bufmgr_fd);
300    bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
301
302    ...
303
304    bo = tbm_bo_ref (bo);
305
306    ....
307
308    tbm_bufmgr_deinit (bufmgr);
309    @endcode
310  */
311 tbm_bo tbm_bo_ref(tbm_bo bo);
312
313 /**
314  * @brief Decreases the reference count of bo
315  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
316  * @param[in] bo : the buffer object
317  * @see tbm_bo_ref()
318  * @see tbm_bo_alloc()
319  * @par Example
320    @code
321    #include <tbm_bufmgr.h>
322
323    int bufmgr_fd;
324    tbm_bufmgr bufmgr;
325    tbm_bo bo;
326
327    bufmgr = tbm_bufmgr_init (bufmgr_fd);
328    bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
329
330    ...
331
332    tbm_bo_unref (bo);
333    tbm_bufmgr_deinit (bufmgr);
334    @endcode
335  */
336 void tbm_bo_unref(tbm_bo bo);
337
338 /**
339  * @brief Maps the buffer object according to the device type and the option.
340  * @details Cache flushing and Locking is executed, while tbm_bo is mapping in the proper condition according to the device type and the access option.\n
341  * If the cache flush type of bufmgr set true, the map cache flushing is executed
342  * If the lock type of bufmgr set once, the previous bo which is locked is unlock when the new bo is trying to be locked.\n
343  * If the lock type of bufmgr set always, the new bo is locked until the previous bo which is locked is unlocked.\n
344  * If the lock type of bufmgr set never, Every bo is never locked.\n\n
345  * #TBM_DEVICE_DEFAULT indecates the default handle.\n
346  * #TBM_DEVICE_2D indecates the 2D memory handle.\n
347  * #TBM_DEVICE_3D indecates the 3D memory handle.\n
348  * #TBM_DEVICE_CPU indecates the virtual memory handle.\n
349  * #TBM_DEVICE_MM indecates the multimedia handle.\n\n
350  * #TBM_OPTION_READ indecates the accss option to read.\n
351  * #TBM_OPTION_WRITE indecates the access option to write.\n
352  * #TBM_OPTION_VENDOR indecates the vendor specific option that depends on the backend.
353  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
354  * @param[in] bo : the buffer object
355  * @param[in] device : the device type to get a handle
356  * @param[in] opt : the option to access the buffer object
357  * @return the handle of the buffer object
358  * @exception #TBM_ERROR_NONE            Success
359  * @exception #TBM_ERROR_BO_LOCK_FAILED  tbm_bo lock failed
360  * @exception #TBM_ERROR_BO_MAP_FAILED   tbm_bo map failed
361  * @retval #tbm_bo
362  * @see tbm_bo_unmap()
363  * @par Example
364    @code
365    #include <tbm_bufmgr.h>
366
367    int bufmgr_fd;
368    tbm_bufmgr bufmgr;
369    tbm_bo bo;
370    tbm_bo_handle handle;
371    tbm_error_e error;
372
373    bufmgr = tbm_bufmgr_init (bufmgr_fd);
374    bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
375
376    ...
377
378    handle = tbm_bo_map (bo, TBM_DEVICE_2D, TBM_OPTION_READ|TBM_OPTION_WRITE);
379    if (handle.ptr == NULL)
380    {
381       error = tbm_get_last_error ();
382       ...
383    }
384
385    ...
386
387    tbm_bo_unmap (bo);
388    tbm_bo_unref (bo);
389    tbm_bufmgr_deinit (bufmgr);
390    @endcode
391  */
392 tbm_bo_handle tbm_bo_map(tbm_bo bo, int device, int opt);
393
394 /**
395  * @brief Unmaps the buffer object.
396  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
397  * @param[in] bo : the buffer object
398  * @return 1 if this function succeeds, otherwise 0.
399  * @see tbm_bo_map()
400  * @par Example
401    @code
402    #include <tbm_bufmgr.h>
403
404    int bufmgr_fd;
405    tbm_bufmgr bufmgr;
406    tbm_bo bo
407    tbm_bo_handle handle;
408
409    bufmgr = tbm_bufmgr_init (bufmgr_fd);
410    bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
411
412    ...
413
414    handle = tbm_bo_map (bo, TBM_DEVICE_2D, TBM_OPTION_READ|TBM_OPTION_WRITE);
415
416    ...
417
418    tbm_bo_unmap (bo);
419    tbm_bo_unref (bo);
420    tbm_bufmgr_deinit (bufmgr);
421    @endcode
422  */
423 int tbm_bo_unmap(tbm_bo bo);
424
425 /**
426  * @brief Gets the tbm_bo_handle according to the device type.
427  * @details The tbm_bo_handle can be get without the map of the tbm_bo.\n
428  * In this case, TBM does not guarantee the lock and the cache flush of the tbm_bo.\n\n
429  * #TBM_DEVICE_DEFAULT indecates the default handle.\n
430  * #TBM_DEVICE_2D indecates the 2D memory handle.\n
431  * #TBM_DEVICE_3D indecates the 3D memory handle.\n
432  * #TBM_DEVICE_CPU indecates the virtual memory handle.\n
433  * #TBM_DEVICE_MM indecates the multimedia handle.
434  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
435  * @param[in] bo : the buffer object
436  * @param[in] device : the device type to get a handle
437  * @return the handle of the buffer object
438  * @retval #tbm_bo_handle
439  * @par Example
440    @code
441    #include <tbm_bufmgr.h>
442
443    int bufmgr_fd;
444    tbm_bufmgr bufmgr;
445    tbm_bo bo;
446    tbm_bo_handle handle;
447    tbm_error_e error;
448
449    bufmgr = tbm_bufmgr_init (bufmgr_fd);
450    bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
451
452    ...
453
454    handle = tbm_bo_get_handle (bo, TBM_DEVICE_2D);
455    if (handle.ptr == NULL)
456    {
457       error = tbm_get_last_error ();
458       ...
459    }
460
461    ...
462
463    tbm_bo_unref (bo);
464    tbm_bufmgr_deinit (bufmgr);
465    @endcode
466   */
467 tbm_bo_handle tbm_bo_get_handle(tbm_bo bo, int device);
468
469 /**
470  * @brief Exports the buffer object by key.
471  * @details The tbm_bo can be exported to the anther process with the unique key associated with the the tbm_bo.
472  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
473  * @param[in] bo : the buffer object
474  * @return key associated with the buffer object
475  * @retval #tbm_key
476  * @see tbm_bo_import()
477  * @par Example
478    @code
479    #include <tbm_bufmgr.h>
480
481    int bufmgr_fd;
482    tbm_bufmgr bufmgr;
483    tbm_bo;
484    tbm_key key;
485    tbm_error_e error;
486
487    bufmgr = tbm_bufmgr_init (bufmgr_fd);
488    bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
489    key = tbm_bo_export (bo);
490    if (key == 0)
491    {
492       error = tbm_get_last_error ();
493       ...
494    }
495
496    ...
497
498    tbm_bo_unref (bo);
499    tbm_bufmgr_deinit (bufmgr);
500    @endcode
501   */
502 tbm_key tbm_bo_export(tbm_bo bo);
503
504 /**
505  * @brief Exports the buffer object by fd.
506  * @details The tbm_bo can be exported to the anther process with the unique fd associated with the the tbm_bo.
507  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
508  * @remarks You must release the fd using close().
509  * @param[in] bo : the buffer object
510  * @return fd associated with the buffer object
511  * @retval #tbm_fd
512  * @see tbm_bo_import_fd()
513  * @par Example
514    @code
515    #include <tbm_bufmgr.h>
516
517    int bufmgr_fd;
518    tbm_fd bo_fd;
519    tbm_bufmgr bufmgr;
520    tbm_bo;
521    tbm_error_e error;
522
523    bufmgr = tbm_bufmgr_init (bufmgr_fd);
524    bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
525    bo_fd = tbm_bo_export (bo);
526    if (bo_fd == 0)
527    {
528       error = tbm_get_last_error ();
529       ...
530    }
531
532    ...
533
534    tbm_bo_unref (bo);
535    tbm_bufmgr_deinit (bufmgr);
536    @endcode
537   */
538 tbm_fd tbm_bo_export_fd(tbm_bo bo);
539
540 /**
541  * @brief Imports the buffer object associated with the key.
542  * @details The reference count of the tbm_bo is 1.
543  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
544  * @param[in] bufmgr : the buffer manager
545  * @param[in] key : the key associated with the buffer object
546  * @return a buffer object
547  * @retval #tbm_bo
548  * @see tbm_bo_export()
549  * @par Example
550    @code
551    #include <tbm_bufmgr.h>
552
553    int bufmgr_fd;
554    int bo_key;
555    tbm_bufmgr bufmgr;
556    tbm_bo;
557    tbm_error_e error;
558
559    ...
560
561    bufmgr = tbm_bufmgr_init (bufmgr_fd);
562    bo = tbm_bo_import (bufmgr, key);
563    if (bo == NULL)
564    {
565       error = tbm_get_last_error ();
566       ...
567    }
568
569    ...
570
571    tbm_bo_unref (bo);
572    tbm_bufmgr_deinit (bufmgr);
573    @endcode
574   */
575 tbm_bo tbm_bo_import(tbm_bufmgr bufmgr, tbm_key key);
576
577 /**
578  * @brief Imports the buffer object associated with the fd.
579  * @details The reference count of the tbm_bo is 1.
580  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
581  * @remarks You must release the fd using close().
582  * @param[in] bufmgr : the buffer manager
583  * @param[in] fd : the fd associated with the buffer object
584  * @return a buffer object
585  * @retval #tbm_bo
586  * @see tbm_bo_export_fd()
587  * @par Example
588    @code
589    #include <tbm_bufmgr.h>
590
591    int bufmgr_fd;
592    tbm_fd bo_fd;
593    tbm_bufmgr bufmgr;
594    tbm_bo bo;
595    tbm_error_e error;
596
597    ...
598
599    bufmgr = tbm_bufmgr_init (bufmgr_fd);
600    bo = tbm_bo_import_fd (bo_fd);
601    if (bo == 0)
602    {
603       error = tbm_get_last_error ();
604       ...
605    }
606
607    ...
608
609    tbm_bo_unref (bo);
610    tbm_bufmgr_deinit (bufmgr);
611    @endcode
612   */
613 tbm_bo tbm_bo_import_fd(tbm_bufmgr bufmgr, tbm_fd fd);
614
615 /**
616  * @brief Gets the size of a bo.
617  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
618  * @param[in] bo : the buffer object
619  * @return 1 if this function succeeds, otherwise 0.
620  * @see tbm_bo_alloc()
621  * @par Example
622    @code
623    #include <tbm_bufmgr.h>
624
625    int bufmgr_fd;
626    tbm_bufmgr bufmgr;
627    tbm_bo;
628    int size;
629
630    bufmgr = tbm_bufmgr_init (bufmgr_fd);
631    bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
632    size = tbm_bo_size (bo);
633
634    ...
635
636    tbm_bo_unref (bo);
637    tbm_bufmgr_deinit (bufmgr);
638    @endcode
639   */
640 int tbm_bo_size(tbm_bo bo);
641
642 /**
643  * @brief Gets the state where the buffer object is locked.
644  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
645  * @param[in] bo : the buffer object
646  * @return 1 if this bo is locked, otherwise 0.
647  * @see tbm_bo_map()
648  * @see tbm_bo_unmap()
649  * @par Example
650    @code
651    #include <tbm_bufmgr.h>
652
653    int bufmgr_fd;
654    tbm_bufmgr bufmgr;
655    tbm_bo bo;
656
657    bufmgr = tbm_bufmgr_init (bufmgr_fd);
658    bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
659
660    ...
661
662    if (tbm_bo_locked (bo))
663    {
664
665    ...
666
667    tbm_bo_unref (bo);
668    tbm_bufmgr_deinit (bufmgr);
669    @endcode
670 */
671 int tbm_bo_locked(tbm_bo bo);
672
673 /**
674  * @brief Swaps the buffer object.
675  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
676  * @param[in] bo1 : the buffer object
677  * @param[in] bo2 : the buffer object
678  * @return 1 if this function succeeds, otherwise 0.
679  * @par Example
680    @code
681    #include <tbm_bufmgr.h>
682
683    int bufmgr_fd;
684    tbm_bufmgr bufmgr;
685    tbm_bo bo1;
686    tbm_bo bo2;
687    int ret;
688    tbm_error_e error;
689
690    bufmgr = tbm_bufmgr_init (bufmgr_fd);
691    bo1 = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
692    bo2 = tbm_bo_alloc (bufmgr, 256 * 256, TBM_BO_DEFAULT);
693
694    ...
695
696    ret = tbm_bo_swap (bo1, bo2);
697    if (ret == 0)
698    {
699       error = tbm_get_last_error ();
700       ...
701    }
702
703    ...
704
705    tbm_bo_unref (bo1);
706    tbm_bo_unref (bo2);
707    tbm_bufmgr_deinit (bufmgr);
708    @endcode
709  */
710 int tbm_bo_swap(tbm_bo bo1, tbm_bo bo2);
711
712 /**
713  * @brief Called when the user data is deleted in buffer object.
714  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
715  * @param[in] user_data User_data to be passed to callback function
716  * @pre The callback must be registered using tbm_bo_add_user_data().\n
717  * tbm_bo_delete_user_data() must be called to invoke this callback.
718  * @see tbm_bo_add_user_data()
719  * @see tbm_bo_delete_user_data()
720  */
721 typedef void (*tbm_data_free) (void *user_data);
722
723 /**
724  * @brief Adds a user_data to the buffer object.
725  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
726  * @param[in] bo : the buffer object
727  * @param[in] key : the key associated with the user_data
728  * @param[in] data_free_func : the function pointer to free the user_data
729  * @return 1 if this function succeeds, otherwise 0.
730  * @post tbm_data_free() will be called under certain conditions, after calling tbm_bo_delete_user_data().
731  * @see tbm_data_free()
732  * @see tbm_bo_set_user_data()
733  * @see tbm_bo_get_user_data()
734  * @see tbm_bo_delete_user_data()
735  * @par Example
736    @code
737    #include <tbm_bufmgr.h>
738
739    void example_data_free (void *user_data)
740    {
741        char *data = (char*) user_data;
742        free(data);
743    }
744
745    int main()
746    {
747        int bufmgr_fd;
748        tbm_bufmgr bufmgr;
749        tbm_bo bo;
750        char *user_data;
751        char *get_data;
752        int ret;
753
754        bufmgr = tbm_bufmgr_init (bufmgr_fd);
755        bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
756        user_data = (char*) malloc (sizeof(char) * 128);
757
758        ...
759
760        tbm_bo_add_user_data (bo, 1, example_data_free);
761        tbm_bo_set_user_data (bo, 1, user_data);
762
763        ...
764
765        ret = tbm_bo_get_user_data (bo, 1, &get_data);
766        tbm_bo_delete_user_data (bo, 1);
767
768        ...
769
770        tbm_bo_unref (bo);
771        tbm_bufmgr_deinit (bufmgr);
772    }
773    @endcode
774  */
775
776 int tbm_bo_add_user_data(tbm_bo bo, unsigned long key,
777                          tbm_data_free data_free_func);
778
779 /**
780  * @brief Deletes the user_data in the buffer object.
781  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
782  * @param[in] bo : the buffer object
783  * @param[in] key : the key associated with the user_date
784  * @return 1 if this function succeeds, otherwise 0.
785  * @see tbm_bo_add_user_data()
786  * @see tbm_bo_get_user_data()
787  * @see tbm_bo_delete_user_data()
788  * @par Example
789    @code
790    #include <tbm_bufmgr.h>
791
792    void example_data_free (void *user_data)
793    {
794        char *data = (char*) user_data;
795        free(data);
796    }
797
798    int main()
799    {
800        int bufmgr_fd;
801        tbm_bufmgr bufmgr;
802        tbm_bo bo;
803        char *user_data;
804        char *get_data;
805        int ret;
806
807        bufmgr = tbm_bufmgr_init (bufmgr_fd);
808        bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
809        user_data = (char*) malloc (sizeof(char) * 128);
810
811        ...
812
813        tbm_bo_add_user_data (bo, 1, example_data_free);
814        tbm_bo_set_user_data (bo, 1, user_data);
815
816        ...
817
818        ret = tbm_bo_get_user_data (bo, 1, &get_data);
819        tbm_bo_delete_user_data (bo, 1);
820
821        ...
822
823        tbm_bo_unref (bo);
824        tbm_bufmgr_deinit (bufmgr);
825    }
826    @endcode
827  */
828 int tbm_bo_delete_user_data(tbm_bo bo, unsigned long key);
829
830 /**
831  * @brief Sets a user_date to the buffer object.
832  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
833  * @param[in] bo : the buffer object
834  * @param[in] key : the key associated with the user_date
835  * @param[in] data : a pointer of the user_data
836  * @return 1 if this function succeeds, otherwise 0.
837  * @see tbm_bo_add_user_data()
838  * @see tbm_bo_set_user_data()
839  * @see tbm_bo_delete_user_data()
840  * @par Example
841    @code
842    #include <tbm_bufmgr.h>
843
844    void example_data_free (void *user_data)
845    {
846        char *data = (char*) user_data;
847        free(data);
848    }
849
850    int main()
851    {
852        int bufmgr_fd;
853        tbm_bufmgr bufmgr;
854        tbm_bo bo;
855        char *user_data;
856        char *get_data;
857        int ret;
858
859        bufmgr = tbm_bufmgr_init (bufmgr_fd);
860        bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
861        user_data = (char*) malloc (sizeof(char) * 128);
862
863        ...
864
865        tbm_bo_add_user_data (bo, 1, example_data_free);
866        tbm_bo_set_user_data (bo, 1, user_data);
867
868        ...
869
870        ret = tbm_bo_get_user_data (bo, 1, &get_data);
871        tbm_bo_delete_user_data (bo, 1);
872
873        ...
874
875        tbm_bo_unref (bo);
876        tbm_bufmgr_deinit (bufmgr);
877    }
878    @endcode
879  */
880 int tbm_bo_set_user_data(tbm_bo bo, unsigned long key, void *data);
881
882 /**
883  * @brief Gets a user_data from the buffer object with the key.
884  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
885  * @param[in] bo : the buffer object
886  * @param[in] key : the key associated with the user_date
887  * @param[out] data : to get the user data
888  * @return 1 if this function succeeds, otherwise 0.
889  * @see tbm_bo_add_user_data()
890  * @see tbm_bo_set_user_data()
891  * @see tbm_bo_get_user_data()
892  * @par Example
893    @code
894    #include <tbm_bufmgr.h>
895
896    void example_data_free (void *user_data)
897    {
898        char *data = (char*) user_data;
899        free(data);
900    }
901
902    int main()
903    {
904        int bufmgr_fd;
905        tbm_bufmgr bufmgr;
906        tbm_bo bo;
907        char *user_data;
908        char *get_data;
909        int ret;
910
911        bufmgr = tbm_bufmgr_init (bufmgr_fd);
912        bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
913        user_data = (char*) malloc (sizeof(char) * 128);
914
915        ...
916
917        tbm_bo_add_user_data (bo, 1, example_data_free);
918        tbm_bo_set_user_data (bo, 1, user_data);
919
920        ...
921
922        ret = tbm_bo_get_user_data (bo, 1, &get_data);
923        tbm_bo_delete_user_data (bo, 1);
924
925        ...
926
927        tbm_bo_unref (bo);
928        tbm_bufmgr_deinit (bufmgr);
929    }
930    @endcode
931  */
932 int tbm_bo_get_user_data(tbm_bo bo, unsigned long key, void **data);
933
934 /**
935  * @brief Gets the latest tbm_error.
936  * @since_tizen 2.4
937  * @return the latest tbm_error
938  * @par Example
939    @code
940    #include <tbm_bufmgr.h>
941
942    int bufmgr_fd;
943    tbm_bufmgr bufmgr;
944    tbm_bo bo;
945    tbm_bo_handle handle;
946    tbm_error_e error;
947
948    bufmgr = tbm_bufmgr_init (bufmgr_fd);
949    bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
950    if (!bo)
951    {
952       error = tbm_get_last_error ();
953       ...
954    }
955
956    ...
957
958    handle = tbm_bo_map (bo, TBM_DEVICE_2D, TBM_OPTION_READ|TBM_OPTION_WRITE);
959    if (handle.ptr == NULL)
960    {
961       error = tbm_get_last_error ();
962       ...
963    }
964
965    ...
966
967    tbm_bo_unmap (bo);
968    tbm_bo_unref (bo);
969    tbm_bufmgr_deinit (bufmgr);
970    @endcode
971  */
972 tbm_error_e tbm_get_last_error(void);
973
974 /**
975  * @brief Gets the tbm buffer capability.
976  * @since_tizen 2.4
977  * @param[in] bufmgr : the buffer manager
978  * @return the tbm bufmgr capability
979  * @par Example
980    @code
981    #include <tbm_bufmgr.h>
982
983    int bufmgr_fd;
984    tbm_bufmgr bufmgr;
985    unsigned int capability;
986
987    bufmgr = tbm_bufmgr_init (bufmgr_fd);
988
989    capability = tbm_bufmgr_get_capability (bufmgr);
990
991    tbm_bufmgr_deinit (bufmgr);
992    @endcode
993  */
994 unsigned int tbm_bufmgr_get_capability(tbm_bufmgr bufmgr);
995
996 /**
997  * @brief Gets the tbm bo flags.
998  * @since_tizen 2.4
999  * @param[in] bo : the buffer object
1000  * @return the tbm bo flags
1001  * @see TBM_BO_FLAGS
1002  * @par Example
1003    @code
1004    #include <tbm_bufmgr.h>
1005
1006    int bufmgr_fd;
1007    tbm_bufmgr bufmgr;
1008    tbm_bo;
1009    int flags;
1010
1011    bufmgr = tbm_bufmgr_init (bufmgr_fd);
1012    bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
1013    flags = tbm_bo_get_flags (bo);
1014
1015    ...
1016
1017    tbm_bo_unref (bo);
1018    tbm_bufmgr_deinit (bufmgr);
1019
1020    @endcode
1021  */
1022 int tbm_bo_get_flags(tbm_bo bo);
1023
1024 /**
1025  * @brief Print out the information of tbm_bos.
1026  * @since_tizen 3.0
1027  * @param[in] bufmgr : the buffer manager
1028  */
1029 void tbm_bufmgr_debug_show(tbm_bufmgr bufmgr);
1030
1031 /**
1032  * @brief Get string with the information of tbm_bos.
1033  * @since_tizen 3.0
1034  * @param[in] bufmgr : the buffer manager
1035  * @return sting with info if this function succeeds, otherwise NULL. It has to be free by user.
1036  */
1037 char * tbm_bufmgr_debug_tbm_info_get(tbm_bufmgr bufmgr);
1038
1039 /**
1040  * @brief Print out the trace of tbm_bos.
1041  * @since_tizen 3.0
1042  * @param[in] bufmgr : the buffer manager
1043  * @param[in] onoff : 1 is on, and 0 is off
1044  */
1045 void tbm_bufmgr_debug_trace(tbm_bufmgr bufmgr, int onoff);
1046
1047 /**
1048  * @brief Dump all tbm surfaces
1049  * @param[in] path : the given dump path
1050  * @return 1 if this function succeeds, otherwise 0.
1051  */
1052 int tbm_bufmgr_debug_dump_all(char *path);
1053
1054 /**
1055  * @brief Start the dump debugging for queue.
1056  * @since_tizen 3.0
1057  * @param[in] path : the given dump path
1058  * @param[in] count : the dump count number
1059  * @param[in] onoff : 1 is on, and 0 is off, if onoff==0 path and count are ignored
1060  * @return 1 if this function succeeds, otherwise 0.
1061  */
1062 int tbm_bufmgr_debug_queue_dump(char *path, int count, int onoff);
1063
1064 /**
1065  * @brief Set scale factor for the nearest calling tbm_bufmgr_debug_dump_all() or tbm_bufmgr_debug_queue_dump()
1066  * @since_tizen 3.0
1067  * @param[in] scale : the scale factor, 0 - disable scaling
1068  * @par Example
1069    @code
1070    #include <tbm_bufmgr.h>
1071
1072    // Dump all surface with scale factor 0.5
1073    tbm_bufmgr_debug_dump_set_scale(0.5);
1074    tbm_bufmgr_debug_dump_all("/tmp/");
1075
1076    // Start the dump debugging for queue with scale factor 0.5
1077    tbm_bufmgr_debug_dump_set_scale(0.2);
1078    tbm_bufmgr_debug_queue_dump("/tmp/", 10, 1);
1079
1080    @endcode
1081  */
1082 void tbm_bufmgr_debug_dump_set_scale(double scale);
1083
1084 int tbm_bufmgr_bind_native_display(tbm_bufmgr bufmgr, void *NativeDisplay);
1085
1086 #ifdef __cplusplus
1087 }
1088 #endif
1089 #endif                                                  /* _TBM_BUFMGR_H_ */