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 <tbm_type_int.h>
  37
  38 /**
  39  * \file tbm_bufmgr.h
  40  * \brief Tizen Buffer Manager
  41  */
  42
  43 #ifdef __cplusplus
  44 extern "C" {
  45 #endif
  46
  47 /* Functions for buffer manager */
  48
  49 /**
  50  * @brief Initializes the buffer manager.
  51  * @details If fd is lower than zero, fd is get drm fd in tbm_bufmgr_init function\n
  52  * 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
  53  * \n
  54  * BUFMGR_LOCK default is once\n
  55  * once : The previous bo which is locked is unlock when the new bo is trying to be locked\n
  56  * always : The new bo is locked until the previous bo which is locked is unlocked\n
  57  * never : Every bo is never locked.\n
  58  * \n
  59  * BUFMGR_MAP_CACHE default is true\n
  60  * true : use map cache flushing\n
  61  * false : to use map cache flushing
  62  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  63  * @param[in] fd : file descripter of the system buffer manager
  64  * @return a buffer manager
  65  * @retval #tbm_bufmgr
  66  * @see tbm_bufmgr_deinit();
  67  * @par Example
  68    @code
  69    #include <tbm_bufmgr.h>
  70    int bufmgr_fd;
  71
  72    setenv("BUFMGR_LOCK_TYPE", "once", 1);
  73    setenv("BUFMGR_MAP_CACHE", "true", 1);
  74
  75    tbm_bufmgr bufmgr;
  76    bufmgr = tbm_bufmgr_init (bufmgr_fd);
  77
  78    ....
  79
  80    tbm_bufmgr_deinit (bufmgr);
  81    @endcode
  82  */
  83 tbm_bufmgr tbm_bufmgr_init(int fd);
  84
  85 /**
  86  * @brief Deinitializes the buffer manager.
  87  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  88  * @param[in] bufmgr : the buffer manager
  89  * @see tbm_bufmgr_init()
  90  * @par Example
  91    @code
  92    #include <tbm_bufmgr.h>
  93
  94    int bufmgr_fd;
  95    tbm_bufmgr bufmgr;
  96    tbm_error_e error;
  97    bufmgr = tbm_bufmgr_init (bufmgr_fd);
  98    if (!bufmgr)
  99    {
 100       error = tbm_get_last_error ();
 101       ...
 102    }
 103
 104    ....
 105
 106    tbm_bufmgr_deinit (bufmgr);
 107    @endcode
 108  */
 109 void tbm_bufmgr_deinit(tbm_bufmgr bufmgr);
 110
 111 /**
 112  * @brief Gets the tbm buffer capability.
 113  * @since_tizen 2.4
 114  * @param[in] bufmgr : the buffer manager
 115  * @return the tbm bufmgr capability
 116  * @par Example
 117    @code
 118    #include <tbm_bufmgr.h>
 119
 120    int bufmgr_fd;
 121    tbm_bufmgr bufmgr;
 122    unsigned int capability;
 123
 124    bufmgr = tbm_bufmgr_init (bufmgr_fd);
 125
 126    capability = tbm_bufmgr_get_capability (bufmgr);
 127
 128    tbm_bufmgr_deinit (bufmgr);
 129    @endcode
 130  */
 131 unsigned int tbm_bufmgr_get_capability(tbm_bufmgr bufmgr);
 132
 133 /**
 134  * @brief bind the native_display.
 135  * @since_tizen 3.0
 136  * @param[in] bufmgr : the buffer manager
 137  * @param[in] native_display : the native_display
 138  */
 139 int tbm_bufmgr_bind_native_display(tbm_bufmgr bufmgr, void *native_display);
 140
 141 /**
 142  * @brief Initializes the buffer manager at the display server.
 143  * @details use this api to initialize the tbm_bufmgr at the display server.
 144  * @since_tizen 5.0
 145  */
 146 tbm_bufmgr tbm_bufmgr_server_init(void);
 147
 148 /**
 149  * @brief Set the bo_lock_type of the bufffer manager.
 150  * @details set the bo_lock_type
 151  * @since_tizen 5.0
 152  */
 153 int tbm_bufmgr_set_bo_lock_type(tbm_bufmgr bufmgr, tbm_bufmgr_bo_lock_type bo_lock_type);
 154
 155 /**
 156  * @brief Print out the information of tbm_bos.
 157  * @since_tizen 3.0
 158  * @param[in] bufmgr : the buffer manager
 159  */
 160 void tbm_bufmgr_debug_show(tbm_bufmgr bufmgr);
 161
 162 /**
 163  * @brief Get string with the information of tbm_bos.
 164  * @since_tizen 3.0
 165  * @param[in] bufmgr : the buffer manager
 166  * @return sting with info if this function succeeds, otherwise NULL. It has to be free by user.
 167  */
 168 char * tbm_bufmgr_debug_tbm_info_get(tbm_bufmgr bufmgr);
 169
 170 /**
 171  * @brief Print out the trace of tbm_bos.
 172  * @since_tizen 3.0
 173  * @param[in] bufmgr : the buffer manager
 174  * @param[in] onoff : 1 is on, and 0 is off
 175  */
 176 void tbm_bufmgr_debug_trace(tbm_bufmgr bufmgr, int onoff);
 177
 178 /**
 179  * @brief Dump all tbm surfaces
 180  * @param[in] path : the given dump path
 181  * @return 1 if this function succeeds, otherwise 0.
 182  */
 183 int tbm_bufmgr_debug_dump_all(char *path);
 184
 185 /**
 186  * @brief Start the dump debugging for queue.
 187  * @since_tizen 3.0
 188  * @param[in] path : the given dump path
 189  * @param[in] count : the dump count number
 190  * @param[in] onoff : 1 is on, and 0 is off, if onoff==0 path and count are ignored
 191  * @return 1 if this function succeeds, otherwise 0.
 192  */
 193 int tbm_bufmgr_debug_queue_dump(char *path, int count, int onoff);
 194
 195 /**
 196  * @brief Set scale factor for the nearest calling tbm_bufmgr_debug_dump_all() or tbm_bufmgr_debug_queue_dump()
 197  * @since_tizen 3.0
 198  * @param[in] scale : the scale factor, 0 - disable scaling
 199  * @par Example
 200    @code
 201    #include <tbm_bufmgr.h>
 202
 203    // Dump all surface with scale factor 0.5
 204    tbm_bufmgr_debug_dump_set_scale(0.5);
 205    tbm_bufmgr_debug_dump_all("/tmp/");
 206
 207    // Start the dump debugging for queue with scale factor 0.5
 208    tbm_bufmgr_debug_dump_set_scale(0.2);
 209    tbm_bufmgr_debug_queue_dump("/tmp/", 10, 1);
 210
 211    @endcode
 212  */
 213 void tbm_bufmgr_debug_dump_set_scale(double scale);
 214
 215 /**
 216  * @brief Get ref_count of a global tbm_bufmgr
 217  * @since_tizen 5.0
 218  */
 219 int tbm_bufmgr_debug_get_ref_count(void);
 220
 221 #ifdef __cplusplus
 222 }
 223 #endif
 224 #endif                                                  /* _TBM_BUFMGR_H_ */