Merge "set the DEFINE according to the version of capi-base-common" into tizen
[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 /**
39  * \file tbm_bufmgr.h
40  * \brief Tizen Buffer Manager
41  */
42
43 /**
44  * @brief Definition for the tizen buffer manager
45  * @since_tizen 2.3
46  */
47 typedef struct _tbm_bufmgr * tbm_bufmgr;
48
49 /**
50  * @brief Definition for the tizen buffer object
51  * @since_tizen 2.3
52  */
53 typedef struct _tbm_bo *tbm_bo;
54 /**
55  * @brief Definition for the key associated with the buffer object
56  * @since_tizen 2.3
57  */
58 typedef uint32_t tbm_key;
59 /**
60  * @brief Definition for the file descripter of the system buffer manager
61  * @since_tizen 2.3
62  */
63 typedef int32_t tbm_fd;
64
65
66 /* TBM_DEVICE_TYPE */
67
68 /**
69  * @brief Definition for the device type to get the default handle
70  * @since_tizen 2.3
71  */
72 #define TBM_DEVICE_DEFAULT   0
73 /**
74  * @brief Definition for the device type to get the virtual memory
75  * @since_tizen 2.3
76  */
77 #define TBM_DEVICE_CPU       1
78 /**
79  * @brief Definition for the device type to get the 2D memory handle
80  * @since_tizen 2.3
81  */
82 #define TBM_DEVICE_2D        2
83 /**
84  * @brief Definition for the device type to get the 3D memory handle
85  * @since_tizen 2.3
86  */
87 #define TBM_DEVICE_3D        3
88 /**
89  * @brief Definition for the device type to get the multimedia handle
90  * @since_tizen 2.3
91  */
92 #define TBM_DEVICE_MM        4
93
94 /**
95  * @brief Definition for the cache invalidate
96  * @since_tizen 2.3
97  */
98 #define TBM_CACHE_INV            0x01
99 /**
100  * @brief Definition for the cache clean
101  * @since_tizen 2.3
102  */
103 #define TBM_CACHE_CLN            0x02
104
105 /* TBM_OPTION */
106
107 /**
108  * @brief Definition for the access option to read
109  * @since_tizen 2.3
110  */
111 #define TBM_OPTION_READ      (1 << 0)
112 /**
113  * @brief Definition for the access option to write
114  * @since_tizen 2.3
115  */
116 #define TBM_OPTION_WRITE     (1 << 1)
117 /**
118  * @brief Definition for the vendor specific option that depends on the backend
119  * @since_tizen 2.3
120  */
121 #define TBM_OPTION_VENDOR    (0xffff0000)
122
123 /**
124  * @brief tbm_bo_handle abstraction of the memory handle by TBM_DEVICE_TYPE
125  * @since_tizen 2.3
126  */
127 typedef union _tbm_bo_handle
128 {
129    void     *ptr;
130    int32_t  s32;
131    uint32_t u32;
132    int64_t  s64;
133    uint64_t u64;
134 } tbm_bo_handle;
135
136 /**
137  * @brief Enumeration of bo memory type
138  * @since_tizen 2.3
139  */
140 enum TBM_BO_FLAGS
141 {
142     TBM_BO_DEFAULT = 0,            /**< default memory: it depends on the backend         */
143     TBM_BO_SCANOUT = (1<<0),       /**< scanout memory                                    */
144     TBM_BO_NONCACHABLE = (1<<1),   /**< non-cachable memory                               */
145     TBM_BO_WC = (1<<2),            /**< write-combine memory                              */
146     TBM_BO_VENDOR = (0xffff0000), /**< vendor specific memory: it depends on the backend */
147 };
148
149 #ifdef __cplusplus
150 extern "C" {
151 #endif
152
153 /* Functions for buffer manager */
154
155 /**
156  * @brief Initializes the buffer manager.
157  * @details If fd is lower than zero, fd is get drm fd in tbm_bufmgr_init function\n
158  * 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
159  * \n
160  * BUFMGR_LOCK default is once\n
161  * once : The previous bo which is locked is unlock when the new bo is trying to be locked\n
162  * always : The new bo is locked until the previous bo which is locked is unlocked\n
163  * never : Every bo is never locked.\n
164  * \n
165  * BUFMGR_MAP_CACHE default is true\n
166  * true : use map cache flushing\n
167  * false : to use map cache flushing
168  * @since_tizen 2.3
169  * @param[in] fd : file descripter of the system buffer manager
170  * @return a buffer manager
171  * @retval #tbm_bufmgr
172  * @see tbm_bufmgr_deinit();
173  * @par Example
174    @code
175    #include <tbm_bufmgr.h>
176    int bufmgr_fd;
177
178
179    setenv("BUFMGR_LOCK_TYPE", "once", 1);
180    setenv("BUFMGR_MAP_CACHE", "true", 1);
181
182    tbm_bufmgr bufmgr;
183    bufmgr = tbm_bufmgr_init (bufmgr_fd);
184
185    ....
186
187    tbm_bufmgr_deinit (bufmgr);
188    @endcode
189  */
190 tbm_bufmgr tbm_bufmgr_init   (int fd);
191
192 /**
193  * @brief Deinitializes the buffer manager.
194  * @since_tizen 2.3
195  * @param[in] bufmgr : the buffer manager
196  * @see tbm_bufmgr_init()
197  * @par Example
198    @code
199    #include <tbm_bufmgr.h>
200
201    int bufmgr_fd;
202    tbm_bufmgr bufmgr;
203    bufmgr = tbm_bufmgr_init (bufmgr_fd);
204
205    ....
206
207    tbm_bufmgr_deinit (bufmgr);
208    @endcode
209  */
210 void       tbm_bufmgr_deinit (tbm_bufmgr bufmgr);
211
212 /* Functions for bo */
213
214 /**
215  * @brief Allocates the buffer object.
216  * @details This function create tbm_bo and set reference count to 1.\n
217  * The user can craete tbm_bo with memory type flag #TBM_BO_FLAGS\n\n
218  * #TBM_BO_DEFAULT indecates default memory: it depends on the backend\n
219  * #TBM_BO_SCANOUT indecates scanout memory\n
220  * #TBM_BO_NONCACHABLE indecates non-cachable memory\n
221  * #TBM_BO_WC indecates write-combine memory\n
222  * #TBM_BO_VENDOR indecates vendor specific memory: it depends on the tbm backend
223  * @since_tizen 2.3
224  * @param[in] bufmgr : the buffer manager
225  * @param[in] size : the size of buffer object
226  * @param[in] flags : the flags of memory type
227  * @return a buffer object
228  * @retval #tbm_bo
229  * @par Example
230    @code
231    #include <tbm_bufmgr.h>
232
233    int bufmgr_fd;
234    tbm_bufmgr bufmgr;
235    tbm_bo;
236
237    bufmgr = tbm_bufmgr_init (bufmgr_fd);
238    bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
239
240    ....
241
242    tbm_bufmgr_deinit (bufmgr);
243    @endcode
244  */
245 tbm_bo        tbm_bo_alloc      (tbm_bufmgr bufmgr, int size, int flags);
246
247 /**
248  * @brief Increases the reference count of bo.
249  * @since_tizen 2.3
250  * @param[in] bo : the buffer object
251  * @return a buffer object
252  * @retval #tbm_bo
253  * @see tbm_bo_unref()
254  * @par Example
255    @code
256    #include <tbm_bufmgr.h>
257
258    int bufmgr_fd;
259    tbm_bufmgr bufmgr;
260    tbm_bo bo;
261
262    bufmgr = tbm_bufmgr_init (bufmgr_fd);
263    bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
264
265    ...
266
267    bo = tbm_bo_ref (bo);
268
269    ....
270
271    tbm_bufmgr_deinit (bufmgr);
272    @endcode
273  */
274 tbm_bo        tbm_bo_ref        (tbm_bo bo);
275
276 /**
277  * @brief Decreases the reference count of bo
278  * @since_tizen 2.3
279  * @param[in] bo : the buffer object
280  * @see tbm_bo_ref()
281  * @see tbm_bo_alloc()
282  * @par Example
283    @code
284    #include <tbm_bufmgr.h>
285
286    int bufmgr_fd;
287    tbm_bufmgr bufmgr;
288    tbm_bo bo;
289
290    bufmgr = tbm_bufmgr_init (bufmgr_fd);
291    bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
292
293    ...
294
295    tbm_bo_unref (bo);
296    tbm_bufmgr_deinit (bufmgr);
297    @endcode
298  */
299 void          tbm_bo_unref      (tbm_bo bo);
300
301 /**
302  * @brief Maps the buffer object according to the device type and the option.
303  * @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
304  * If the cache flush type of bufmgr set true, the map cache flushing is executed
305  * 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
306  * If the lock type of bufmgr set always, the new bo is locked until the previous bo which is locked is unlocked.\n
307  * If the lock type of bufmgr set never, Every bo is never locked.\n\n
308  * #TBM_DEVICE_DEFAULT indecates the default handle.\n
309  * #TBM_DEVICE_2D indecates the 2D memory handle.\n
310  * #TBM_DEVICE_3D indecates the 3D memory handle.\n
311  * #TBM_DEVICE_CPU indecates the virtual memory handle.\n
312  * #TBM_DEVICE_MM indecates the multimedia handle.\n\n
313  * #TBM_OPTION_READ indecates the accss option to read.\n
314  * #TBM_OPTION_WRITE indecates the access option to write.\n
315  * #TBM_OPTION_VENDOR indecates the vendor specific option that depends on the backend.
316  * @since_tizen 2.3
317  * @param[in] bo : the buffer object
318  * @param[in] device : the device type to get a handle
319  * @param[in] opt : the option to access the buffer object
320  * @return the handle of the buffer object
321  * @retval #tbm_bo
322  * @see tbm_bo_unmap()
323  * @par Example
324    @code
325    #include <tbm_bufmgr.h>
326
327    int bufmgr_fd;
328    tbm_bufmgr bufmgr;
329    tbm_bo bo;
330    tbm_bo_handle handle;
331
332    bufmgr = tbm_bufmgr_init (bufmgr_fd);
333    bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
334
335    ...
336
337    handle = tbm_bo_map (bo, TBM_DEVICE_2D, TBM_OPTION_READ|TBM_OPTION_WRITE);
338
339    ...
340
341    tbm_bo_unmap (bo);
342    tbm_bo_unref (bo);
343    tbm_bufmgr_deinit (bufmgr);
344    @endcode
345  */
346 tbm_bo_handle tbm_bo_map        (tbm_bo bo, int device, int opt);
347
348 /**
349  * @brief Unmaps the buffer object.
350  * @since_tizen 2.3
351  * @param[in] bo : the buffer object
352  * @return 1 if this function succeeds, otherwise 0.
353  * @see tbm_bo_map()
354  * @par Example
355    @code
356    #include <tbm_bufmgr.h>
357
358    int bufmgr_fd;
359    tbm_bufmgr bufmgr;
360    tbm_bo bo
361    tbm_bo_handle handle;
362
363    bufmgr = tbm_bufmgr_init (bufmgr_fd);
364    bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
365
366    ...
367
368    handle = tbm_bo_map (bo, TBM_DEVICE_2D, TBM_OPTION_READ|TBM_OPTION_WRITE);
369
370    ...
371
372    tbm_bo_unmap (bo);
373    tbm_bo_unref (bo);
374    tbm_bufmgr_deinit (bufmgr);
375    @endcode
376  */
377 int           tbm_bo_unmap      (tbm_bo bo);
378
379 /**
380  * @brief Gets the tbm_bo_handle according to the device type.
381  * @details The tbm_bo_handle can be get without the map of the tbm_bo.\n
382  * In this case, TBM does not guarantee the lock and the cache flush of the tbm_bo.\n\n
383  * #TBM_DEVICE_DEFAULT indecates the default handle.\n
384  * #TBM_DEVICE_2D indecates the 2D memory handle.\n
385  * #TBM_DEVICE_3D indecates the 3D memory handle.\n
386  * #TBM_DEVICE_CPU indecates the virtual memory handle.\n
387  * #TBM_DEVICE_MM indecates the multimedia handle.
388  * @since_tizen 2.3
389  * @param[in] bo : the buffer object
390  * @param[in] device : the device type to get a handle
391  * @return the handle of the buffer object
392  * @retval #tbm_bo_handle
393  * @par Example
394    @code
395    #include <tbm_bufmgr.h>
396
397    int bufmgr_fd;
398    tbm_bufmgr bufmgr;
399    tbm_bo bo;
400    tbm_bo_handle handle;
401
402    bufmgr = tbm_bufmgr_init (bufmgr_fd);
403    bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
404
405    ...
406
407    handle = tbm_bo_get_handle (bo, TBM_DEVICE_2D);
408
409    ...
410
411    tbm_bo_unref (bo);
412    tbm_bufmgr_deinit (bufmgr);
413    @endcode
414   */
415 tbm_bo_handle tbm_bo_get_handle (tbm_bo bo, int device);
416
417 /**
418  * @brief Exports the buffer object by key.
419  * @details The tbm_bo can be exported to the anther process with the unique key associated with the the tbm_bo.
420  * @since_tizen 2.3
421  * @param[in] bo : the buffer object
422  * @return key associated with the buffer object
423  * @retval #tbm_key
424  * @see tbm_bo_import()
425  * @par Example
426    @code
427    #include <tbm_bufmgr.h>
428
429    int bufmgr_fd;
430    tbm_bufmgr bufmgr;
431    tbm_bo;
432    tbm_key key;
433
434    bufmgr = tbm_bufmgr_init (bufmgr_fd);
435    bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
436    key = tbm_bo_export (bo);
437
438    ...
439
440    tbm_bo_unref (bo);
441    tbm_bufmgr_deinit (bufmgr);
442    @endcode
443   */
444 tbm_key  tbm_bo_export     (tbm_bo bo);
445
446 /**
447  * @brief Exports the buffer object by fd.
448  * @details The tbm_bo can be exported to the anther process with the unique fd associated with the the tbm_bo.
449  * @since_tizen 2.3
450  * @param[in] bo : the buffer object
451  * @return fd associated with the buffer object
452  * @retval #tbm_fd
453  * @see tbm_bo_import_fd()
454  * @par Example
455    @code
456    #include <tbm_bufmgr.h>
457
458    int bufmgr_fd;
459    tbm_fd bo_fd;
460    tbm_bufmgr bufmgr;
461    tbm_bo;
462
463    bufmgr = tbm_bufmgr_init (bufmgr_fd);
464    bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
465    bo_fd = tbm_bo_export (bo);
466
467    ...
468
469    tbm_bo_unref (bo);
470    tbm_bufmgr_deinit (bufmgr);
471    @endcode
472   */
473 tbm_fd tbm_bo_export_fd (tbm_bo bo);
474
475 /**
476  * @brief Imports the buffer object associated with the key.
477  * @details The reference count of the tbm_bo is 1.
478  * @since_tizen 2.3
479  * @param[in] bufmgr : the buffer manager
480  * @param[in] key : the key associated with the buffer object
481  * @return a buffer object
482  * @retval #tbm_bo
483  * @see tbm_bo_export()
484  * @par Example
485    @code
486    #include <tbm_bufmgr.h>
487
488    int bufmgr_fd;
489    int bo_key;
490    tbm_bufmgr bufmgr;
491    tbm_bo;
492
493    ...
494
495    bufmgr = tbm_bufmgr_init (bufmgr_fd);
496    bo = tbm_bo_import (key);
497
498    ...
499
500    tbm_bo_unref (bo);
501    tbm_bufmgr_deinit (bufmgr);
502    @endcode
503   */
504 tbm_bo        tbm_bo_import     (tbm_bufmgr bufmgr, tbm_key key);
505
506 /**
507  * @brief Imports the buffer object associated with the fd.
508  * @details The reference count of the tbm_bo is 1.
509  * @since_tizen 2.3
510  * @param[in] bufmgr : the buffer manager
511  * @param[in] fd : the fd associated with the buffer object
512  * @return a buffer object
513  * @retval #tbm_bo
514  * @see tbm_bo_export_fd()
515  * @par Example
516    @code
517    #include <tbm_bufmgr.h>
518
519    int bufmgr_fd;
520    tbm_fd bo_fd;
521    tbm_bufmgr bufmgr;
522    tbm_bo bo;
523
524    ...
525
526    bufmgr = tbm_bufmgr_init (bufmgr_fd);
527    bo = tbm_bo_import (bo_fd);
528
529    ...
530
531    tbm_bo_unref (bo);
532    tbm_bufmgr_deinit (bufmgr);
533    @endcode
534   */
535 tbm_bo        tbm_bo_import_fd  (tbm_bufmgr bufmgr, tbm_fd fd);
536
537 /**
538  * @brief Gets the size of a bo.
539  * @since_tizen 2.3
540  * @param[in] bo : the buffer object
541  * @return 1 if this function succeeds, otherwise 0.
542  * @see tbm_bo_alloc()
543  * @par Example
544    @code
545    #include <tbm_bufmgr.h>
546
547    int bufmgr_fd;
548    tbm_bufmgr bufmgr;
549    tbm_bo;
550    int size;
551
552    bufmgr = tbm_bufmgr_init (bufmgr_fd);
553    bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
554    size = tbm_bo_size (bo);
555
556    ...
557
558    tbm_bo_unref (bo);
559    tbm_bufmgr_deinit (bufmgr);
560    @endcode
561   */
562 int           tbm_bo_size       (tbm_bo bo);
563
564 /**
565  * @brief Gets the state where the buffer object is locked.
566  * @since_tizen 2.3
567  * @param[in] bo : the buffer object
568  * @return 1 if this bo is locked, otherwise 0.
569  * @see tbm_bo_map()
570  * @see tbm_bo_unmap()
571  * @par Example
572    @code
573    #include <tbm_bufmgr.h>
574
575    int bufmgr_fd;
576    tbm_bufmgr bufmgr;
577    tbm_bo bo;
578
579    bufmgr = tbm_bufmgr_init (bufmgr_fd);
580    bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
581
582    ...
583
584    if (tbm_bo_locked (bo))
585    {
586
587    ...
588
589    tbm_bo_unref (bo);
590    tbm_bufmgr_deinit (bufmgr);
591    @endcode
592 */
593 int           tbm_bo_locked     (tbm_bo bo);
594
595 /**
596  * @brief Swaps the buffer object.
597  * @since_tizen 2.3
598  * @param[in] bo1 : the buffer object
599  * @param[in] bo2 : the buffer object
600  * @return 1 if this function succeeds, otherwise 0.
601  * @par Example
602    @code
603    #include <tbm_bufmgr.h>
604
605    int bufmgr_fd;
606    tbm_bufmgr bufmgr;
607    tbm_bo bo1;
608    tbm_bo bo2;
609    int ret;
610
611    bufmgr = tbm_bufmgr_init (bufmgr_fd);
612    bo1 = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
613    bo2 = tbm_bo_alloc (bufmgr, 256 * 256, TBM_BO_DEFAULT);
614
615    ...
616
617    ret = tbm_bo_swap (bo1, bo2);
618
619    ...
620
621    tbm_bo_unref (bo1);
622    tbm_bo_unref (bo2);
623    tbm_bufmgr_deinit (bufmgr);
624    @endcode
625  */
626 int           tbm_bo_swap       (tbm_bo bo1, tbm_bo bo2);
627
628
629 /**
630  * @brief Called when the user data is deleted in buffer object.
631  * @since_tizen 2.3
632  * @param[in] user_data User_data to be passed to callback function
633  * @pre The callback must be registered using tbm_bo_add_user_data().\n
634  * tbm_bo_delete_user_data() must be called to invoke this callback.
635  * @see tbm_bo_add_user_data()
636  * @see tbm_bo_delete_user_data()
637  */
638 typedef void (*tbm_data_free)(void *user_data);
639
640 /**
641  * @brief Adds a user_data to the buffer object.
642  * @since_tizen 2.3
643  * @param[in] bo : the buffer object
644  * @param[in] key : the key associated with the user_data
645  * @param[in] data_free_func : the function pointer to free the user_data
646  * @return 1 if this function succeeds, otherwise 0.
647  * @post tbm_data_free() will be called under certain conditions, after calling tbm_bo_delete_user_data().
648  * @see tbm_data_free()
649  * @see tbm_bo_set_user_data()
650  * @see tbm_bo_get_user_data()
651  * @see tbm_bo_delete_user_data()
652  * @par Example
653    @code
654    #include <tbm_bufmgr.h>
655
656    void example_data_free (void *user_data)
657    {
658        char *data = (char*) user_data;
659        free(data);
660    }
661
662    int main()
663    {
664        int bufmgr_fd;
665        tbm_bufmgr bufmgr;
666        tbm_bo bo;
667        char *user_data;
668        char *get_data;
669        int ret;
670
671        bufmgr = tbm_bufmgr_init (bufmgr_fd);
672        bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
673        user_data = (char*) malloc (sizeof(char) * 128);
674
675        ...
676
677        tbm_bo_add_user_data (bo, 1, example_data_free);
678        tbm_bo_set_user_data (bo, 1, user_data);
679
680        ...
681
682        ret = tbm_bo_get_user_data (bo, 1, &get_data);
683        tbm_bo_delete_user_data (bo, 1);
684
685        ...
686
687        tbm_bo_unref (bo);
688        tbm_bufmgr_deinit (bufmgr);
689    }
690    @endcode
691  */
692
693 int tbm_bo_add_user_data    (tbm_bo bo, unsigned long key, tbm_data_free data_free_func);
694
695 /**
696  * @brief Deletes the user_data in the buffer object.
697  * @since_tizen 2.3
698  * @param[in] bo : the buffer object
699  * @param[in] key : the key associated with the user_date
700  * @return 1 if this function succeeds, otherwise 0.
701  * @see tbm_bo_add_user_data()
702  * @see tbm_bo_get_user_data()
703  * @see tbm_bo_delete_user_data()
704  * @par Example
705    @code
706    #include <tbm_bufmgr.h>
707
708    void example_data_free (void *user_data)
709    {
710        char *data = (char*) user_data;
711        free(data);
712    }
713
714    int main()
715    {
716        int bufmgr_fd;
717        tbm_bufmgr bufmgr;
718        tbm_bo bo;
719        char *user_data;
720        char *get_data;
721        int ret;
722
723        bufmgr = tbm_bufmgr_init (bufmgr_fd);
724        bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
725        user_data = (char*) malloc (sizeof(char) * 128);
726
727        ...
728
729        tbm_bo_add_user_data (bo, 1, example_data_free);
730        tbm_bo_set_user_data (bo, 1, user_data);
731
732        ...
733
734        ret = tbm_bo_get_user_data (bo, 1, &get_data);
735        tbm_bo_delete_user_data (bo, 1);
736
737        ...
738
739        tbm_bo_unref (bo);
740        tbm_bufmgr_deinit (bufmgr);
741    }
742    @endcode
743  */
744 int tbm_bo_delete_user_data (tbm_bo bo, unsigned long key);
745
746 /**
747  * @brief Sets a user_date to the buffer object.
748  * @since_tizen 2.3
749  * @param[in] bo : the buffer object
750  * @param[in] key : the key associated with the user_date
751  * @param[in] data : a pointer of the user_data
752  * @return 1 if this function succeeds, otherwise 0.
753  * @see tbm_bo_add_user_data()
754  * @see tbm_bo_set_user_data()
755  * @see tbm_bo_delete_user_data()
756  * @par Example
757    @code
758    #include <tbm_bufmgr.h>
759
760    void example_data_free (void *user_data)
761    {
762        char *data = (char*) user_data;
763        free(data);
764    }
765
766    int main()
767    {
768        int bufmgr_fd;
769        tbm_bufmgr bufmgr;
770        tbm_bo bo;
771        char *user_data;
772        char *get_data;
773        int ret;
774
775        bufmgr = tbm_bufmgr_init (bufmgr_fd);
776        bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
777        user_data = (char*) malloc (sizeof(char) * 128);
778
779        ...
780
781        tbm_bo_add_user_data (bo, 1, example_data_free);
782        tbm_bo_set_user_data (bo, 1, user_data);
783
784        ...
785
786        ret = tbm_bo_get_user_data (bo, 1, &get_data);
787        tbm_bo_delete_user_data (bo, 1);
788
789        ...
790
791        tbm_bo_unref (bo);
792        tbm_bufmgr_deinit (bufmgr);
793    }
794    @endcode
795  */
796 int tbm_bo_set_user_data    (tbm_bo bo, unsigned long key, void* data);
797
798 /**
799  * @brief Gets a user_data from the buffer object with the key.
800  * @since_tizen 2.3
801  * @param[in] bo : the buffer object
802  * @param[in] key : the key associated with the user_date
803  * @param[out] data : to get the user data
804  * @return 1 if this function succeeds, otherwise 0.
805  * @see tbm_bo_add_user_data()
806  * @see tbm_bo_set_user_data()
807  * @see tbm_bo_get_user_data()
808  * @par Example
809    @code
810    #include <tbm_bufmgr.h>
811
812    void example_data_free (void *user_data)
813    {
814        char *data = (char*) user_data;
815        free(data);
816    }
817
818    int main()
819    {
820        int bufmgr_fd;
821        tbm_bufmgr bufmgr;
822        tbm_bo bo;
823        char *user_data;
824        char *get_data;
825        int ret;
826
827        bufmgr = tbm_bufmgr_init (bufmgr_fd);
828        bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
829        user_data = (char*) malloc (sizeof(char) * 128);
830
831        ...
832
833        tbm_bo_add_user_data (bo, 1, example_data_free);
834        tbm_bo_set_user_data (bo, 1, user_data);
835
836        ...
837
838        ret = tbm_bo_get_user_data (bo, 1, &get_data);
839        tbm_bo_delete_user_data (bo, 1);
840
841        ...
842
843        tbm_bo_unref (bo);
844        tbm_bufmgr_deinit (bufmgr);
845    }
846    @endcode
847  */
848 int tbm_bo_get_user_data    (tbm_bo bo, unsigned long key, void** data);
849
850 int tbm_bo_cache_flush  (tbm_bo bo, int flags);
851
852
853 #ifdef __cplusplus
854 }
855 #endif
856
857 #endif /* _TBM_BUFMGR_H_ */
858