1 /**************************************************************************
5 Copyright 2012 Samsung Electronics co., Ltd. All Rights Reserved.
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>
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:
18 The above copyright notice and this permission notice (including the
19 next paragraph) shall be included in all copies or substantial portions
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.
30 **************************************************************************/
36 #include <tbm_type_common.h>
37 #include <tbm_error.h>
41 * \brief Tizen Buffer Object
48 /* Functions for buffer object */
51 * @brief Allocates the buffer object.
52 * @details This function create tbm_bo and set reference count to 1.\n
53 * The user can craete tbm_bo with memory type flag #TBM_BO_FLAGS\n\n
54 * #TBM_BO_DEFAULT indicates default memory: it depends on the backend\n
55 * #TBM_BO_SCANOUT indicates scanout memory\n
56 * #TBM_BO_NONCACHABLE indicates non-cachable memory\n
57 * #TBM_BO_WC indicates write-combine memory\n
58 * #TBM_BO_VENDOR indicates vendor specific memory: it depends on the tbm backend
59 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
60 * @param[in] bufmgr : the buffer manager
61 * @param[in] size : the size of buffer object
62 * @param[in] flags : the flags of memory type
63 * @return a buffer object
67 #include <tbm_bufmgr.h>
74 bufmgr = tbm_bufmgr_init (bufmgr_fd);
75 bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
78 error = tbm_get_last_error ();
84 tbm_bufmgr_deinit (bufmgr);
87 tbm_bo tbm_bo_alloc(tbm_bufmgr bufmgr, int size, int flags);
90 * @brief Increases the reference count of bo.
91 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
92 * @param[in] bo : the buffer object
93 * @return a buffer object
98 #include <tbm_bufmgr.h>
104 bufmgr = tbm_bufmgr_init (bufmgr_fd);
105 bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
109 bo = tbm_bo_ref (bo);
113 tbm_bufmgr_deinit (bufmgr);
116 tbm_bo tbm_bo_ref(tbm_bo bo);
119 * @brief Decreases the reference count of bo
120 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
121 * @param[in] bo : the buffer object
123 * @see tbm_bo_alloc()
126 #include <tbm_bufmgr.h>
132 bufmgr = tbm_bufmgr_init (bufmgr_fd);
133 bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
138 tbm_bufmgr_deinit (bufmgr);
141 void tbm_bo_unref(tbm_bo bo);
144 * @brief Maps the buffer object according to the device type and the option.
145 * @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
146 * If the cache flush type of bufmgr set true, the map cache flushing is executed
147 * 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
148 * If the lock type of bufmgr set always, the new bo is locked until the previous bo which is locked is unlocked.\n
149 * If the lock type of bufmgr set never, Every bo is never locked.\n\n
150 * #TBM_DEVICE_DEFAULT indicates the default handle.\n
151 * #TBM_DEVICE_2D indicates the 2D memory handle.\n
152 * #TBM_DEVICE_3D indicates the 3D memory handle.\n
153 * #TBM_DEVICE_CPU indicates the virtual memory handle.\n
154 * #TBM_DEVICE_MM indicates the multimedia handle.\n\n
155 * #TBM_OPTION_READ indicates the accss option to read.\n
156 * #TBM_OPTION_WRITE indicates the access option to write.\n
157 * #TBM_OPTION_VENDOR indicates the vendor specific option that depends on the backend.
158 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
159 * @param[in] bo : the buffer object
160 * @param[in] device : the device type to get a handle
161 * @param[in] opt : the option to access the buffer object
162 * @return the handle of the buffer object
163 * @exception #TBM_ERROR_NONE Success
164 * @exception #TBM_ERROR_BO_LOCK_FAILED tbm_bo lock failed
165 * @exception #TBM_ERROR_BO_MAP_FAILED tbm_bo map failed
167 * @see tbm_bo_unmap()
170 #include <tbm_bufmgr.h>
175 tbm_bo_handle handle;
178 bufmgr = tbm_bufmgr_init (bufmgr_fd);
179 bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
183 handle = tbm_bo_map (bo, TBM_DEVICE_2D, TBM_OPTION_READ|TBM_OPTION_WRITE);
184 if (handle.ptr == NULL)
186 error = tbm_get_last_error ();
194 tbm_bufmgr_deinit (bufmgr);
197 tbm_bo_handle tbm_bo_map(tbm_bo bo, int device, int opt);
200 * @brief Unmaps the buffer object.
201 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
202 * @param[in] bo : the buffer object
203 * @return 1 if this function succeeds, otherwise 0.
207 #include <tbm_bufmgr.h>
212 tbm_bo_handle handle;
214 bufmgr = tbm_bufmgr_init (bufmgr_fd);
215 bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
219 handle = tbm_bo_map (bo, TBM_DEVICE_2D, TBM_OPTION_READ|TBM_OPTION_WRITE);
225 tbm_bufmgr_deinit (bufmgr);
228 int tbm_bo_unmap(tbm_bo bo);
231 * @brief Gets the tbm_bo_handle according to the device type.
232 * @details The tbm_bo_handle can be get without the map of the tbm_bo.\n
233 * In this case, TBM does not guarantee the lock and the cache flush of the tbm_bo.\n\n
234 * #TBM_DEVICE_DEFAULT indicates the default handle.\n
235 * #TBM_DEVICE_2D indicates the 2D memory handle.\n
236 * #TBM_DEVICE_3D indicates the 3D memory handle.\n
237 * #TBM_DEVICE_CPU indicates the virtual memory handle.\n
238 * #TBM_DEVICE_MM indicates the multimedia handle.
239 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
240 * @param[in] bo : the buffer object
241 * @param[in] device : the device type to get a handle
242 * @return the handle of the buffer object
243 * @retval #tbm_bo_handle
246 #include <tbm_bufmgr.h>
251 tbm_bo_handle handle;
254 bufmgr = tbm_bufmgr_init (bufmgr_fd);
255 bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
259 handle = tbm_bo_get_handle (bo, TBM_DEVICE_2D);
260 if (handle.ptr == NULL)
262 error = tbm_get_last_error ();
269 tbm_bufmgr_deinit (bufmgr);
272 tbm_bo_handle tbm_bo_get_handle(tbm_bo bo, int device);
275 * @brief Exports the buffer object by key.
276 * @details The tbm_bo can be exported to the anther process with the unique key associated with the the tbm_bo.
277 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
278 * @param[in] bo : the buffer object
279 * @return key associated with the buffer object
281 * @see tbm_bo_import()
284 #include <tbm_bufmgr.h>
292 bufmgr = tbm_bufmgr_init (bufmgr_fd);
293 bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
294 key = tbm_bo_export (bo);
297 error = tbm_get_last_error ();
304 tbm_bufmgr_deinit (bufmgr);
307 tbm_key tbm_bo_export(tbm_bo bo);
310 * @brief Exports the buffer object by fd.
311 * @details The tbm_bo can be exported to the anther process with the unique fd associated with the the tbm_bo.
312 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
313 * @remarks You must release the fd using close().
314 * @param[in] bo : the buffer object
315 * @return fd associated with the buffer object
317 * @see tbm_bo_import_fd()
320 #include <tbm_bufmgr.h>
328 bufmgr = tbm_bufmgr_init (bufmgr_fd);
329 bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
330 bo_fd = tbm_bo_export (bo);
333 error = tbm_get_last_error ();
340 tbm_bufmgr_deinit (bufmgr);
343 tbm_fd tbm_bo_export_fd(tbm_bo bo);
346 * @brief Imports the buffer object associated with the key.
347 * @details The reference count of the tbm_bo is 1.
348 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
349 * @param[in] bufmgr : the buffer manager
350 * @param[in] key : the key associated with the buffer object
351 * @return a buffer object
353 * @see tbm_bo_export()
356 #include <tbm_bufmgr.h>
366 bufmgr = tbm_bufmgr_init (bufmgr_fd);
367 bo = tbm_bo_import (bufmgr, key);
370 error = tbm_get_last_error ();
377 tbm_bufmgr_deinit (bufmgr);
380 tbm_bo tbm_bo_import(tbm_bufmgr bufmgr, tbm_key key);
383 * @brief Imports the buffer object associated with the fd.
384 * @details The reference count of the tbm_bo is 1.
385 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
386 * @remarks You must release the fd using close().
387 * @param[in] bufmgr : the buffer manager
388 * @param[in] fd : the fd associated with the buffer object
389 * @return a buffer object
391 * @see tbm_bo_export_fd()
394 #include <tbm_bufmgr.h>
404 bufmgr = tbm_bufmgr_init (bufmgr_fd);
405 bo = tbm_bo_import_fd (bo_fd);
408 error = tbm_get_last_error ();
415 tbm_bufmgr_deinit (bufmgr);
418 tbm_bo tbm_bo_import_fd(tbm_bufmgr bufmgr, tbm_fd fd);
421 * @brief Gets the size of a bo.
422 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
423 * @param[in] bo : the buffer object
424 * @return 1 if this function succeeds, otherwise 0.
425 * @see tbm_bo_alloc()
428 #include <tbm_bufmgr.h>
435 bufmgr = tbm_bufmgr_init (bufmgr_fd);
436 bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
437 size = tbm_bo_size (bo);
442 tbm_bufmgr_deinit (bufmgr);
445 int tbm_bo_size(tbm_bo bo);
448 * @brief Gets the state where the buffer object is locked.
449 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
450 * @param[in] bo : the buffer object
451 * @return 1 if this bo is locked, otherwise 0.
453 * @see tbm_bo_unmap()
456 #include <tbm_bufmgr.h>
462 bufmgr = tbm_bufmgr_init (bufmgr_fd);
463 bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
467 if (tbm_bo_locked (bo))
473 tbm_bufmgr_deinit (bufmgr);
476 int tbm_bo_locked(tbm_bo bo);
479 * @brief Swaps the buffer object.
480 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
481 * @param[in] bo1 : the buffer object
482 * @param[in] bo2 : the buffer object
483 * @return 1 if this function succeeds, otherwise 0.
486 #include <tbm_bufmgr.h>
495 bufmgr = tbm_bufmgr_init (bufmgr_fd);
496 bo1 = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
497 bo2 = tbm_bo_alloc (bufmgr, 256 * 256, TBM_BO_DEFAULT);
501 ret = tbm_bo_swap (bo1, bo2);
504 error = tbm_get_last_error ();
512 tbm_bufmgr_deinit (bufmgr);
515 int tbm_bo_swap(tbm_bo bo1, tbm_bo bo2);
518 * @brief Adds a user_data to the buffer object.
519 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
520 * @param[in] bo : the buffer object
521 * @param[in] key : the key associated with the user_data
522 * @param[in] data_free_func : the function pointer to free the user_data
523 * @return 1 if this function succeeds, otherwise 0.
524 * @post tbm_data_free() will be called under certain conditions, after calling tbm_bo_delete_user_data().
525 * @see tbm_data_free()
526 * @see tbm_bo_set_user_data()
527 * @see tbm_bo_get_user_data()
528 * @see tbm_bo_delete_user_data()
531 #include <tbm_bufmgr.h>
533 void example_data_free (void *user_data)
535 char *data = (char*) user_data;
548 bufmgr = tbm_bufmgr_init (bufmgr_fd);
549 bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
550 user_data = (char*) malloc (sizeof(char) * 128);
554 tbm_bo_add_user_data (bo, 1, example_data_free);
555 tbm_bo_set_user_data (bo, 1, user_data);
559 ret = tbm_bo_get_user_data (bo, 1, &get_data);
560 tbm_bo_delete_user_data (bo, 1);
565 tbm_bufmgr_deinit (bufmgr);
570 int tbm_bo_add_user_data(tbm_bo bo, unsigned long key,
571 tbm_data_free data_free_func);
574 * @brief Deletes the user_data in the buffer object.
575 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
576 * @param[in] bo : the buffer object
577 * @param[in] key : the key associated with the user_date
578 * @return 1 if this function succeeds, otherwise 0.
579 * @see tbm_bo_add_user_data()
580 * @see tbm_bo_get_user_data()
581 * @see tbm_bo_delete_user_data()
584 #include <tbm_bufmgr.h>
586 void example_data_free (void *user_data)
588 char *data = (char*) user_data;
601 bufmgr = tbm_bufmgr_init (bufmgr_fd);
602 bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
603 user_data = (char*) malloc (sizeof(char) * 128);
607 tbm_bo_add_user_data (bo, 1, example_data_free);
608 tbm_bo_set_user_data (bo, 1, user_data);
612 ret = tbm_bo_get_user_data (bo, 1, &get_data);
613 tbm_bo_delete_user_data (bo, 1);
618 tbm_bufmgr_deinit (bufmgr);
622 int tbm_bo_delete_user_data(tbm_bo bo, unsigned long key);
625 * @brief Sets a user_date to the buffer object.
626 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
627 * @param[in] bo : the buffer object
628 * @param[in] key : the key associated with the user_date
629 * @param[in] data : a pointer of the user_data
630 * @return 1 if this function succeeds, otherwise 0.
631 * @see tbm_bo_add_user_data()
632 * @see tbm_bo_set_user_data()
633 * @see tbm_bo_delete_user_data()
636 #include <tbm_bufmgr.h>
638 void example_data_free (void *user_data)
640 char *data = (char*) user_data;
653 bufmgr = tbm_bufmgr_init (bufmgr_fd);
654 bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
655 user_data = (char*) malloc (sizeof(char) * 128);
659 tbm_bo_add_user_data (bo, 1, example_data_free);
660 tbm_bo_set_user_data (bo, 1, user_data);
664 ret = tbm_bo_get_user_data (bo, 1, &get_data);
665 tbm_bo_delete_user_data (bo, 1);
670 tbm_bufmgr_deinit (bufmgr);
674 int tbm_bo_set_user_data(tbm_bo bo, unsigned long key, void *data);
677 * @brief Gets a user_data from the buffer object with the key.
678 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
679 * @param[in] bo : the buffer object
680 * @param[in] key : the key associated with the user_date
681 * @param[out] data : to get the user data
682 * @return 1 if this function succeeds, otherwise 0.
683 * @see tbm_bo_add_user_data()
684 * @see tbm_bo_set_user_data()
685 * @see tbm_bo_get_user_data()
688 #include <tbm_bufmgr.h>
690 void example_data_free (void *user_data)
692 char *data = (char*) user_data;
705 bufmgr = tbm_bufmgr_init (bufmgr_fd);
706 bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
707 user_data = (char*) malloc (sizeof(char) * 128);
711 tbm_bo_add_user_data (bo, 1, example_data_free);
712 tbm_bo_set_user_data (bo, 1, user_data);
716 ret = tbm_bo_get_user_data (bo, 1, &get_data);
717 tbm_bo_delete_user_data (bo, 1);
722 tbm_bufmgr_deinit (bufmgr);
726 int tbm_bo_get_user_data(tbm_bo bo, unsigned long key, void **data);
729 * @brief Gets the tbm bo flags.
731 * @param[in] bo : the buffer object
732 * @return the tbm bo flags
736 #include <tbm_bufmgr.h>
743 bufmgr = tbm_bufmgr_init (bufmgr_fd);
744 bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
745 flags = tbm_bo_get_flags (bo);
750 tbm_bufmgr_deinit (bufmgr);
754 int tbm_bo_get_flags(tbm_bo bo);
759 #endif /* _TBM_BO_H_ */