docs/gst/tmpl/gstbufferpool.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 GstBufferPool
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 Create buffers from a pool
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 A bufferpool is used to create buffers in an efficient way. En element
  10 can maintain a bufferpool with a fixed number of buffers. This will reduce
  11 the g_malloc and g_free overhead.
  12 </para>
  13 <para>
  14 A bufferpool can also be used to implement direct access. A bufferpool can be
  15 sent from one element to another so that the latter can directly write into
  16 the memory of the element that maintains the bufferpool. This can greatly reduce
  17 the number of memcpy operations.
  18 </para>
  19 <para>
  20 A bufferpool is created with gst_buffer_pool_new(). You'll have to set the
  21 buffer new and free function afterwards with gst_buffer_pool_set_buffer_new_function() and
  22 gst_buffer_pool_set_buffer_free_function() so that all buffers created
  23 from this pool will be allocated/freed with these functions.
  24 </para>
  25 <para>
  26 Optionally the default buffer copy function of the buffers allocated from this pool
  27 can be overridden with gst_buffer_pool_set_buffer_copy_function().
  28 </para>
  29 <para>
  30 To create a buffer from the bufferpool use gst_buffer_new_from_pool().
  31 </para>
  32 <para>
  33 When the buffer is unreffed and has reached a refcount of 0, the bufferpools free
  34 function is called with the buffer as an argument.
  35 </para>
  36 <para>
  37 A bufferpool can store private data in the buffer it creates with the GST_BUFFER_POOL_PRIVATE()
  38 macro. To check it a buffer was made by a specific bufferpool, use the GST_BUFFER_BUFFERPOOL()
  39 macro to get its bufferpool.
  40 </para>
  41 <para>
  42 Destroy the bufferpool with gst_buffer_pool_destroy(), optional cleanup of the bufferpool can
  43 be triggered in the GstBufferPoolDestroyHook which you can install with
  44 gst_buffer_pool_set_destroy_hook().
  45 </para>
  46 <para>
  47 The owner of the bufferpool can add user data to the pool with
  48 gst_buffer_pool_set_user_data() and gst_buffer_pool_get_user_data().
  49 </para>
  50 <para>
  51 If your plugin is going to need a lot of equally sized memory areas you can use
  52 gst_buffer_pool_get_default() to request a pool that will create buffers of that size.
  53 These bufferpools will be shared with all plugins needing the same size of buffers so it's
  54 quite efficient since it reduces the number of memory allocations.
  55 </para>
  56
  57 <para>
  58 A bufferpool can be requested from a pad with the gst_pad_get_bufferpool() function. This function
  59 is typically used when a plugin wants to write into a memory area provided by another plugin.
  60 </para>
  61
  62 <!-- ##### SECTION See_Also ##### -->
  63 <para>
  64 #GstBuffer, #GstPad
  65 </para>
  66
  67 <!-- ##### STRUCT GstBufferPool ##### -->
  68 <para>
  69
  70 </para>
  71
  72 @lock:
  73 @buffer_free:
  74 @buffer_copy:
  75 @destroy_hook:
  76 @user_data:
  77
  78 <!-- ##### USER_FUNCTION GstBufferPoolBufferNewFunction ##### -->
  79 <para>
  80 The function will be called when a buffer must be allocated from the pool.
  81 </para>
  82
  83 @pool: The pool allocating the buffer
  84 @location: the location (offset) of the buffer to allocate
  85 @size: The size of the allocated buffer
  86 @user_data: user data as set on the bufferpool
  87 @Returns: A new buffer with the given parameters.
  88
  89
  90 <!-- ##### USER_FUNCTION GstBufferPoolDestroyHook ##### -->
  91 <para>
  92 Will be called when the bufferpool is destroyed so that the owner of the pool
  93 can perform necessary cleanup.
  94 </para>
  95
  96 @pool: The pool that is being destroyed
  97 @user_data: user data as set on th bufferpool
  98
  99
 100 <!-- ##### MACRO GST_BUFFER_POOL_UNLOCK ##### -->
 101 <para>
 102 Lock the given bufferpool.
 103 </para>
 104
 105 @pool: The pool to lock.
 106
 107
 108 <!-- ##### MACRO GST_BUFFER_POOL_LOCK ##### -->
 109 <para>
 110 Unlock the given bufferpool.
 111 </para>
 112
 113 @pool: the bufferpool to unlock.
 114
 115
 116 <!-- ##### FUNCTION gst_buffer_pool_new ##### -->
 117 <para>
 118
 119 </para>
 120
 121 @Returns:
 122
 123
 124 <!-- ##### FUNCTION gst_buffer_pool_ref ##### -->
 125 <para>
 126
 127 </para>
 128
 129 @pool:
 130
 131
 132 <!-- ##### FUNCTION gst_buffer_pool_ref_by_count ##### -->
 133 <para>
 134
 135 </para>
 136
 137 @pool:
 138 @count:
 139
 140
 141 <!-- ##### FUNCTION gst_buffer_pool_unref ##### -->
 142 <para>
 143
 144 </para>
 145
 146 @pool:
 147 <!-- # Unused Parameters # -->
 148 @buffer:
 149
 150
 151 <!-- ##### FUNCTION gst_buffer_pool_destroy ##### -->
 152 <para>
 153
 154 </para>
 155
 156 @pool:
 157
 158
 159 <!-- ##### FUNCTION gst_buffer_pool_get_default ##### -->
 160 <para>
 161
 162 </para>
 163
 164 @buffer_size:
 165 @pool_size:
 166 @Returns:
 167 <!-- # Unused Parameters # -->
 168 @oldpool:
 169
 170
 171 <!-- ##### FUNCTION gst_buffer_pool_set_user_data ##### -->
 172 <para>
 173
 174 </para>
 175
 176 @pool:
 177 @user_data:
 178
 179
 180 <!-- ##### FUNCTION gst_buffer_pool_get_user_data ##### -->
 181 <para>
 182
 183 </para>
 184
 185 @pool:
 186 @Returns:
 187 <!-- # Unused Parameters # -->
 188 @user_data:
 189
 190
 191 <!-- ##### FUNCTION gst_buffer_pool_set_buffer_copy_function ##### -->
 192 <para>
 193
 194 </para>
 195
 196 @pool:
 197 @copy:
 198
 199
 200 <!-- ##### FUNCTION gst_buffer_pool_set_buffer_free_function ##### -->
 201 <para>
 202
 203 </para>
 204
 205 @pool:
 206 @destroy:
 207
 208
 209 <!-- ##### FUNCTION gst_buffer_pool_set_buffer_new_function ##### -->
 210 <para>
 211
 212 </para>
 213
 214 @pool:
 215 @create:
 216
 217
 218 <!-- ##### FUNCTION gst_buffer_pool_set_destroy_hook ##### -->
 219 <para>
 220
 221 </para>
 222
 223 @pool:
 224 @destroy:
 225
 226