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_int.h>
40 * \brief Tizen Buffer Object
47 /* Functions for buffer object */
50 * @brief Allocates the buffer object.
51 * @details This function create tbm_bo and set reference count to 1.\n
52 * The user can craete tbm_bo with memory type flag #TBM_BO_FLAGS\n\n
53 * #TBM_BO_DEFAULT indecates default memory: it depends on the backend\n
54 * #TBM_BO_SCANOUT indecates scanout memory\n
55 * #TBM_BO_NONCACHABLE indecates non-cachable memory\n
56 * #TBM_BO_WC indecates write-combine memory\n
57 * #TBM_BO_VENDOR indecates vendor specific memory: it depends on the tbm backend
58 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
59 * @param[in] bufmgr : the buffer manager
60 * @param[in] size : the size of buffer object
61 * @param[in] flags : the flags of memory type
62 * @return a buffer object
66 #include <tbm_bufmgr.h>
73 bufmgr = tbm_bufmgr_init (bufmgr_fd);
74 bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
77 error = tbm_get_last_error ();
83 tbm_bufmgr_deinit (bufmgr);
86 tbm_bo tbm_bo_alloc(tbm_bufmgr bufmgr, int size, int flags);
89 * @brief Increases the reference count of bo.
90 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
91 * @param[in] bo : the buffer object
92 * @return a buffer object
97 #include <tbm_bufmgr.h>
103 bufmgr = tbm_bufmgr_init (bufmgr_fd);
104 bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
108 bo = tbm_bo_ref (bo);
112 tbm_bufmgr_deinit (bufmgr);
115 tbm_bo tbm_bo_ref(tbm_bo bo);
118 * @brief Decreases the reference count of bo
119 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
120 * @param[in] bo : the buffer object
122 * @see tbm_bo_alloc()
125 #include <tbm_bufmgr.h>
131 bufmgr = tbm_bufmgr_init (bufmgr_fd);
132 bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
137 tbm_bufmgr_deinit (bufmgr);
140 void tbm_bo_unref(tbm_bo bo);
143 * @brief Maps the buffer object according to the device type and the option.
144 * @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
145 * If the cache flush type of bufmgr set true, the map cache flushing is executed
146 * 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
147 * If the lock type of bufmgr set always, the new bo is locked until the previous bo which is locked is unlocked.\n
148 * If the lock type of bufmgr set never, Every bo is never locked.\n\n
149 * #TBM_DEVICE_DEFAULT indecates the default handle.\n
150 * #TBM_DEVICE_2D indecates the 2D memory handle.\n
151 * #TBM_DEVICE_3D indecates the 3D memory handle.\n
152 * #TBM_DEVICE_CPU indecates the virtual memory handle.\n
153 * #TBM_DEVICE_MM indecates the multimedia handle.\n\n
154 * #TBM_OPTION_READ indecates the accss option to read.\n
155 * #TBM_OPTION_WRITE indecates the access option to write.\n
156 * #TBM_OPTION_VENDOR indecates the vendor specific option that depends on the backend.
157 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
158 * @param[in] bo : the buffer object
159 * @param[in] device : the device type to get a handle
160 * @param[in] opt : the option to access the buffer object
161 * @return the handle of the buffer object
162 * @exception #TBM_ERROR_NONE Success
163 * @exception #TBM_ERROR_BO_LOCK_FAILED tbm_bo lock failed
164 * @exception #TBM_ERROR_BO_MAP_FAILED tbm_bo map failed
166 * @see tbm_bo_unmap()
169 #include <tbm_bufmgr.h>
174 tbm_bo_handle handle;
177 bufmgr = tbm_bufmgr_init (bufmgr_fd);
178 bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
182 handle = tbm_bo_map (bo, TBM_DEVICE_2D, TBM_OPTION_READ|TBM_OPTION_WRITE);
183 if (handle.ptr == NULL)
185 error = tbm_get_last_error ();
193 tbm_bufmgr_deinit (bufmgr);
196 tbm_bo_handle tbm_bo_map(tbm_bo bo, int device, int opt);
199 * @brief Unmaps the buffer object.
200 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
201 * @param[in] bo : the buffer object
202 * @return 1 if this function succeeds, otherwise 0.
206 #include <tbm_bufmgr.h>
211 tbm_bo_handle handle;
213 bufmgr = tbm_bufmgr_init (bufmgr_fd);
214 bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
218 handle = tbm_bo_map (bo, TBM_DEVICE_2D, TBM_OPTION_READ|TBM_OPTION_WRITE);
224 tbm_bufmgr_deinit (bufmgr);
227 int tbm_bo_unmap(tbm_bo bo);
230 * @brief Gets the tbm_bo_handle according to the device type.
231 * @details The tbm_bo_handle can be get without the map of the tbm_bo.\n
232 * In this case, TBM does not guarantee the lock and the cache flush of the tbm_bo.\n\n
233 * #TBM_DEVICE_DEFAULT indecates the default handle.\n
234 * #TBM_DEVICE_2D indecates the 2D memory handle.\n
235 * #TBM_DEVICE_3D indecates the 3D memory handle.\n
236 * #TBM_DEVICE_CPU indecates the virtual memory handle.\n
237 * #TBM_DEVICE_MM indecates the multimedia handle.
238 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
239 * @param[in] bo : the buffer object
240 * @param[in] device : the device type to get a handle
241 * @return the handle of the buffer object
242 * @retval #tbm_bo_handle
245 #include <tbm_bufmgr.h>
250 tbm_bo_handle handle;
253 bufmgr = tbm_bufmgr_init (bufmgr_fd);
254 bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
258 handle = tbm_bo_get_handle (bo, TBM_DEVICE_2D);
259 if (handle.ptr == NULL)
261 error = tbm_get_last_error ();
268 tbm_bufmgr_deinit (bufmgr);
271 tbm_bo_handle tbm_bo_get_handle(tbm_bo bo, int device);
274 * @brief Exports the buffer object by key.
275 * @details The tbm_bo can be exported to the anther process with the unique key associated with the the tbm_bo.
276 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
277 * @param[in] bo : the buffer object
278 * @return key associated with the buffer object
280 * @see tbm_bo_import()
283 #include <tbm_bufmgr.h>
291 bufmgr = tbm_bufmgr_init (bufmgr_fd);
292 bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
293 key = tbm_bo_export (bo);
296 error = tbm_get_last_error ();
303 tbm_bufmgr_deinit (bufmgr);
306 tbm_key tbm_bo_export(tbm_bo bo);
309 * @brief Exports the buffer object by fd.
310 * @details The tbm_bo can be exported to the anther process with the unique fd associated with the the tbm_bo.
311 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
312 * @remarks You must release the fd using close().
313 * @param[in] bo : the buffer object
314 * @return fd associated with the buffer object
316 * @see tbm_bo_import_fd()
319 #include <tbm_bufmgr.h>
327 bufmgr = tbm_bufmgr_init (bufmgr_fd);
328 bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
329 bo_fd = tbm_bo_export (bo);
332 error = tbm_get_last_error ();
339 tbm_bufmgr_deinit (bufmgr);
342 tbm_fd tbm_bo_export_fd(tbm_bo bo);
345 * @brief Imports the buffer object associated with the key.
346 * @details The reference count of the tbm_bo is 1.
347 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
348 * @param[in] bufmgr : the buffer manager
349 * @param[in] key : the key associated with the buffer object
350 * @return a buffer object
352 * @see tbm_bo_export()
355 #include <tbm_bufmgr.h>
365 bufmgr = tbm_bufmgr_init (bufmgr_fd);
366 bo = tbm_bo_import (bufmgr, key);
369 error = tbm_get_last_error ();
376 tbm_bufmgr_deinit (bufmgr);
379 tbm_bo tbm_bo_import(tbm_bufmgr bufmgr, tbm_key key);
382 * @brief Imports the buffer object associated with the fd.
383 * @details The reference count of the tbm_bo is 1.
384 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
385 * @remarks You must release the fd using close().
386 * @param[in] bufmgr : the buffer manager
387 * @param[in] fd : the fd associated with the buffer object
388 * @return a buffer object
390 * @see tbm_bo_export_fd()
393 #include <tbm_bufmgr.h>
403 bufmgr = tbm_bufmgr_init (bufmgr_fd);
404 bo = tbm_bo_import_fd (bo_fd);
407 error = tbm_get_last_error ();
414 tbm_bufmgr_deinit (bufmgr);
417 tbm_bo tbm_bo_import_fd(tbm_bufmgr bufmgr, tbm_fd fd);
420 * @brief Gets the size of a bo.
421 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
422 * @param[in] bo : the buffer object
423 * @return 1 if this function succeeds, otherwise 0.
424 * @see tbm_bo_alloc()
427 #include <tbm_bufmgr.h>
434 bufmgr = tbm_bufmgr_init (bufmgr_fd);
435 bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
436 size = tbm_bo_size (bo);
441 tbm_bufmgr_deinit (bufmgr);
444 int tbm_bo_size(tbm_bo bo);
447 * @brief Gets the state where the buffer object is locked.
448 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
449 * @param[in] bo : the buffer object
450 * @return 1 if this bo is locked, otherwise 0.
452 * @see tbm_bo_unmap()
455 #include <tbm_bufmgr.h>
461 bufmgr = tbm_bufmgr_init (bufmgr_fd);
462 bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
466 if (tbm_bo_locked (bo))
472 tbm_bufmgr_deinit (bufmgr);
475 int tbm_bo_locked(tbm_bo bo);
478 * @brief Swaps the buffer object.
479 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
480 * @param[in] bo1 : the buffer object
481 * @param[in] bo2 : the buffer object
482 * @return 1 if this function succeeds, otherwise 0.
485 #include <tbm_bufmgr.h>
494 bufmgr = tbm_bufmgr_init (bufmgr_fd);
495 bo1 = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
496 bo2 = tbm_bo_alloc (bufmgr, 256 * 256, TBM_BO_DEFAULT);
500 ret = tbm_bo_swap (bo1, bo2);
503 error = tbm_get_last_error ();
511 tbm_bufmgr_deinit (bufmgr);
514 int tbm_bo_swap(tbm_bo bo1, tbm_bo bo2);
517 * @brief Adds a user_data to the buffer object.
518 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
519 * @param[in] bo : the buffer object
520 * @param[in] key : the key associated with the user_data
521 * @param[in] data_free_func : the function pointer to free the user_data
522 * @return 1 if this function succeeds, otherwise 0.
523 * @post tbm_data_free() will be called under certain conditions, after calling tbm_bo_delete_user_data().
524 * @see tbm_data_free()
525 * @see tbm_bo_set_user_data()
526 * @see tbm_bo_get_user_data()
527 * @see tbm_bo_delete_user_data()
530 #include <tbm_bufmgr.h>
532 void example_data_free (void *user_data)
534 char *data = (char*) user_data;
547 bufmgr = tbm_bufmgr_init (bufmgr_fd);
548 bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
549 user_data = (char*) malloc (sizeof(char) * 128);
553 tbm_bo_add_user_data (bo, 1, example_data_free);
554 tbm_bo_set_user_data (bo, 1, user_data);
558 ret = tbm_bo_get_user_data (bo, 1, &get_data);
559 tbm_bo_delete_user_data (bo, 1);
564 tbm_bufmgr_deinit (bufmgr);
569 int tbm_bo_add_user_data(tbm_bo bo, unsigned long key,
570 tbm_data_free data_free_func);
573 * @brief Deletes the user_data in the buffer object.
574 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
575 * @param[in] bo : the buffer object
576 * @param[in] key : the key associated with the user_date
577 * @return 1 if this function succeeds, otherwise 0.
578 * @see tbm_bo_add_user_data()
579 * @see tbm_bo_get_user_data()
580 * @see tbm_bo_delete_user_data()
583 #include <tbm_bufmgr.h>
585 void example_data_free (void *user_data)
587 char *data = (char*) user_data;
600 bufmgr = tbm_bufmgr_init (bufmgr_fd);
601 bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
602 user_data = (char*) malloc (sizeof(char) * 128);
606 tbm_bo_add_user_data (bo, 1, example_data_free);
607 tbm_bo_set_user_data (bo, 1, user_data);
611 ret = tbm_bo_get_user_data (bo, 1, &get_data);
612 tbm_bo_delete_user_data (bo, 1);
617 tbm_bufmgr_deinit (bufmgr);
621 int tbm_bo_delete_user_data(tbm_bo bo, unsigned long key);
624 * @brief Sets a user_date to the buffer object.
625 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
626 * @param[in] bo : the buffer object
627 * @param[in] key : the key associated with the user_date
628 * @param[in] data : a pointer of the user_data
629 * @return 1 if this function succeeds, otherwise 0.
630 * @see tbm_bo_add_user_data()
631 * @see tbm_bo_set_user_data()
632 * @see tbm_bo_delete_user_data()
635 #include <tbm_bufmgr.h>
637 void example_data_free (void *user_data)
639 char *data = (char*) user_data;
652 bufmgr = tbm_bufmgr_init (bufmgr_fd);
653 bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
654 user_data = (char*) malloc (sizeof(char) * 128);
658 tbm_bo_add_user_data (bo, 1, example_data_free);
659 tbm_bo_set_user_data (bo, 1, user_data);
663 ret = tbm_bo_get_user_data (bo, 1, &get_data);
664 tbm_bo_delete_user_data (bo, 1);
669 tbm_bufmgr_deinit (bufmgr);
673 int tbm_bo_set_user_data(tbm_bo bo, unsigned long key, void *data);
676 * @brief Gets a user_data from the buffer object with the key.
677 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
678 * @param[in] bo : the buffer object
679 * @param[in] key : the key associated with the user_date
680 * @param[out] data : to get the user data
681 * @return 1 if this function succeeds, otherwise 0.
682 * @see tbm_bo_add_user_data()
683 * @see tbm_bo_set_user_data()
684 * @see tbm_bo_get_user_data()
687 #include <tbm_bufmgr.h>
689 void example_data_free (void *user_data)
691 char *data = (char*) user_data;
704 bufmgr = tbm_bufmgr_init (bufmgr_fd);
705 bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
706 user_data = (char*) malloc (sizeof(char) * 128);
710 tbm_bo_add_user_data (bo, 1, example_data_free);
711 tbm_bo_set_user_data (bo, 1, user_data);
715 ret = tbm_bo_get_user_data (bo, 1, &get_data);
716 tbm_bo_delete_user_data (bo, 1);
721 tbm_bufmgr_deinit (bufmgr);
725 int tbm_bo_get_user_data(tbm_bo bo, unsigned long key, void **data);
728 * @brief Gets the latest tbm_error.
730 * @return the latest tbm_error
733 #include <tbm_bufmgr.h>
738 tbm_bo_handle handle;
741 bufmgr = tbm_bufmgr_init (bufmgr_fd);
742 bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
745 error = tbm_get_last_error ();
751 handle = tbm_bo_map (bo, TBM_DEVICE_2D, TBM_OPTION_READ|TBM_OPTION_WRITE);
752 if (handle.ptr == NULL)
754 error = tbm_get_last_error ();
762 tbm_bufmgr_deinit (bufmgr);
765 tbm_error_e tbm_get_last_error(void);
768 * @brief Gets the tbm bo flags.
770 * @param[in] bo : the buffer object
771 * @return the tbm bo flags
775 #include <tbm_bufmgr.h>
782 bufmgr = tbm_bufmgr_init (bufmgr_fd);
783 bo = tbm_bo_alloc (bufmgr, 128 * 128, TBM_BO_DEFAULT);
784 flags = tbm_bo_get_flags (bo);
789 tbm_bufmgr_deinit (bufmgr);
793 int tbm_bo_get_flags(tbm_bo bo);
798 #endif /* _TBM_BO_H_ */