1 /* GStreamer 2 * Copyright (C) 2010 Wim Taymans <wim.taymans@gmail.com> 3 * 4 * gstbufferpool.h: Header for GstBufferPool object 5 * 6 * This library is free software; you can redistribute it and/or 7 * modify it under the terms of the GNU Library General Public 8 * License as published by the Free Software Foundation; either 9 * version 2 of the License, or (at your option) any later version. 10 * 11 * This library is distributed in the hope that it will be useful, 12 * but WITHOUT ANY WARRANTY; without even the implied warranty of 13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14 * Library General Public License for more details. 15 * 16 * You should have received a copy of the GNU Library General Public 17 * License along with this library; if not, write to the 18 * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, 19 * Boston, MA 02110-1301, USA. 20 */ 21 22 23 #ifndef __GST_BUFFER_POOL_H__ 24 #define __GST_BUFFER_POOL_H__ 25 26 #include <gst/gstminiobject.h> 27 #include <gst/gstpad.h> 28 #include <gst/gstbuffer.h> 29 30 G_BEGIN_DECLS 31 32 typedef struct _GstBufferPoolPrivate GstBufferPoolPrivate; 33 typedef struct _GstBufferPoolClass GstBufferPoolClass; 34 35 #define GST_TYPE_BUFFER_POOL (gst_buffer_pool_get_type()) 36 #define GST_IS_BUFFER_POOL(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GST_TYPE_BUFFER_POOL)) 37 #define GST_IS_BUFFER_POOL_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), GST_TYPE_BUFFER_POOL)) 38 #define GST_BUFFER_POOL_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), GST_TYPE_BUFFER_POOL, GstBufferPoolClass)) 39 #define GST_BUFFER_POOL(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), GST_TYPE_BUFFER_POOL, GstBufferPool)) 40 #define GST_BUFFER_POOL_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), GST_TYPE_BUFFER_POOL, GstBufferPoolClass)) 41 #define GST_BUFFER_POOL_CAST(obj) ((GstBufferPool *)(obj)) 42 43 /** 44 * GstBufferPoolAcquireFlags: 45 * @GST_BUFFER_POOL_ACQUIRE_FLAG_NONE: no flags 46 * @GST_BUFFER_POOL_ACQUIRE_FLAG_KEY_UNIT: buffer is keyframe 47 * @GST_BUFFER_POOL_ACQUIRE_FLAG_DONTWAIT: when the bufferpool is empty, acquire_buffer 48 * will by default block until a buffer is released into the pool again. Setting 49 * this flag makes acquire_buffer return #GST_FLOW_EOS instead of blocking. 50 * @GST_BUFFER_POOL_ACQUIRE_FLAG_DISCONT: buffer is discont 51 * @GST_BUFFER_POOL_ACQUIRE_FLAG_LAST: last flag, subclasses can use private flags 52 * starting from this value. 53 * 54 * Additional flags to control the allocation of a buffer 55 */ 56 typedef enum { 57 GST_BUFFER_POOL_ACQUIRE_FLAG_NONE = 0, 58 GST_BUFFER_POOL_ACQUIRE_FLAG_KEY_UNIT = (1 << 0), 59 GST_BUFFER_POOL_ACQUIRE_FLAG_DONTWAIT = (1 << 1), 60 GST_BUFFER_POOL_ACQUIRE_FLAG_DISCONT = (1 << 2), 61 GST_BUFFER_POOL_ACQUIRE_FLAG_LAST = (1 << 16), 62 } GstBufferPoolAcquireFlags; 63 64 typedef struct _GstBufferPoolAcquireParams GstBufferPoolAcquireParams; 65 66 /** 67 * GstBufferPoolAcquireParams: 68 * @format: the format of @start and @stop 69 * @start: the start position 70 * @stop: the stop position 71 * @flags: additional flags 72 * 73 * Parameters passed to the gst_buffer_pool_acquire_buffer() function to control the 74 * allocation of the buffer. 75 * 76 * The default implementation ignores the @start and @stop members but other 77 * implementations can use this extra information to decide what buffer to 78 * return. 79 */ 80 struct _GstBufferPoolAcquireParams { 81 GstFormat format; 82 gint64 start; 83 gint64 stop; 84 GstBufferPoolAcquireFlags flags; 85 86 /*< private >*/ 87 gpointer _gst_reserved[GST_PADDING]; 88 }; 89 90 /** 91 * GST_BUFFER_POOL_IS_FLUSHING: 92 * @pool: a GstBufferPool 93 * 94 * Check if the bufferpool is flushing. Subclasses might want to check the 95 * state of the pool in the acquire function. 96 */ 97 #define GST_BUFFER_POOL_IS_FLUSHING(pool) (g_atomic_int_get (&pool->flushing)) 98 99 /** 100 * GstBufferPool: 101 * 102 * The structure of a #GstBufferPool. Use the associated macros to access the public 103 * variables. 104 */ 105 struct _GstBufferPool { 106 GstObject object; 107 108 /*< protected >*/ 109 gint flushing; 110 111 /*< private >*/ 112 GstBufferPoolPrivate *priv; 113 114 gpointer _gst_reserved[GST_PADDING]; 115 }; 116 117 /** 118 * GstBufferPoolClass: 119 * @object_class: Object parent class 120 * @get_options: get a list of options supported by this pool 121 * @set_config: apply the bufferpool configuration. The default configuration 122 * will parse the default config parameters 123 * @start: start the bufferpool. The default implementation will preallocate 124 * min-buffers buffers and put them in the queue 125 * @stop: stop the bufferpool. the default implementation will free the 126 * preallocated buffers. This function is called when all the buffers are 127 * returned to the pool. 128 * @acquire_buffer: get a new buffer from the pool. The default implementation 129 * will take a buffer from the queue and optionally wait for a buffer to 130 * be released when there are no buffers available. 131 * @alloc_buffer: allocate a buffer. the default implementation allocates 132 * buffers from the configured memory allocator and with the configured 133 * parameters. All metadata that is present on the allocated buffer will 134 * be marked as #GST_META_FLAG_POOLED and #GST_META_FLAG_LOCKED and will 135 * not be removed from the buffer in @reset_buffer. The buffer should 136 * have the GST_BUFFER_FLAG_TAG_MEMORY cleared. 137 * @reset_buffer: reset the buffer to its state when it was freshly allocated. 138 * The default implementation will clear the flags, timestamps and 139 * will remove the metadata without the #GST_META_FLAG_POOLED flag (even 140 * the metadata with #GST_META_FLAG_LOCKED). If the 141 * #GST_BUFFER_FLAG_TAG_MEMORY was set, this function can also try to 142 * restore the memory and clear the #GST_BUFFER_FLAG_TAG_MEMORY again. 143 * @release_buffer: release a buffer back in the pool. The default 144 * implementation will put the buffer back in the queue and notify any 145 * blocking acquire_buffer calls when the #GST_BUFFER_FLAG_TAG_MEMORY 146 * is not set on the buffer. If #GST_BUFFER_FLAG_TAG_MEMORY is set, the 147 * buffer will be freed with @free_buffer. 148 * @free_buffer: free a buffer. The default implementation unrefs the buffer. 149 * @flush_start: enter the flushing state. (Since: 1.4) 150 * @flush_stop: leave the flushign state. (Since: 1.4) 151 * 152 * The GstBufferPool class. 153 */ 154 struct _GstBufferPoolClass { 155 GstObjectClass object_class; 156 157 /*< public >*/ 158 const gchar ** (*get_options) (GstBufferPool *pool); 159 gboolean (*set_config) (GstBufferPool *pool, GstStructure *config); 160 161 gboolean (*start) (GstBufferPool *pool); 162 gboolean (*stop) (GstBufferPool *pool); 163 164 GstFlowReturn (*acquire_buffer) (GstBufferPool *pool, GstBuffer **buffer, 165 GstBufferPoolAcquireParams *params); 166 GstFlowReturn (*alloc_buffer) (GstBufferPool *pool, GstBuffer **buffer, 167 GstBufferPoolAcquireParams *params); 168 void (*reset_buffer) (GstBufferPool *pool, GstBuffer *buffer); 169 void (*release_buffer) (GstBufferPool *pool, GstBuffer *buffer); 170 void (*free_buffer) (GstBufferPool *pool, GstBuffer *buffer); 171 void (*flush_start) (GstBufferPool *pool); 172 void (*flush_stop) (GstBufferPool *pool); 173 174 /*< private >*/ 175 gpointer _gst_reserved[GST_PADDING - 2]; 176 }; 177 178 GST_API 179 GType gst_buffer_pool_get_type (void); 180 181 /* allocation */ 182 183 GST_API 184 GstBufferPool * gst_buffer_pool_new (void); 185 186 /* state management */ 187 188 GST_API 189 gboolean gst_buffer_pool_set_active (GstBufferPool *pool, gboolean active); 190 191 GST_API 192 gboolean gst_buffer_pool_is_active (GstBufferPool *pool); 193 194 GST_API 195 gboolean gst_buffer_pool_set_config (GstBufferPool *pool, GstStructure *config); 196 197 GST_API 198 GstStructure * gst_buffer_pool_get_config (GstBufferPool *pool); 199 200 GST_API 201 const gchar ** gst_buffer_pool_get_options (GstBufferPool *pool); 202 203 GST_API 204 gboolean gst_buffer_pool_has_option (GstBufferPool *pool, const gchar *option); 205 206 GST_API 207 void gst_buffer_pool_set_flushing (GstBufferPool *pool, gboolean flushing); 208 209 /* helpers for configuring the config structure */ 210 211 GST_API 212 void gst_buffer_pool_config_set_params (GstStructure *config, GstCaps *caps, 213 guint size, guint min_buffers, guint max_buffers); 214 215 GST_API 216 gboolean gst_buffer_pool_config_get_params (GstStructure *config, GstCaps **caps, 217 guint *size, guint *min_buffers, guint *max_buffers); 218 219 GST_API 220 void gst_buffer_pool_config_set_allocator (GstStructure *config, GstAllocator *allocator, 221 const GstAllocationParams *params); 222 223 GST_API 224 gboolean gst_buffer_pool_config_get_allocator (GstStructure *config, GstAllocator **allocator, 225 GstAllocationParams *params); 226 227 /* options */ 228 229 GST_API 230 guint gst_buffer_pool_config_n_options (GstStructure *config); 231 232 GST_API 233 void gst_buffer_pool_config_add_option (GstStructure *config, const gchar *option); 234 235 GST_API 236 const gchar * gst_buffer_pool_config_get_option (GstStructure *config, guint index); 237 238 GST_API 239 gboolean gst_buffer_pool_config_has_option (GstStructure *config, const gchar *option); 240 241 GST_API 242 gboolean gst_buffer_pool_config_validate_params (GstStructure *config, GstCaps *caps, 243 guint size, guint min_buffers, guint max_buffers); 244 245 /* buffer management */ 246 247 GST_API 248 GstFlowReturn gst_buffer_pool_acquire_buffer (GstBufferPool *pool, GstBuffer **buffer, 249 GstBufferPoolAcquireParams *params); 250 251 GST_API 252 void gst_buffer_pool_release_buffer (GstBufferPool *pool, GstBuffer *buffer); 253 254 G_END_DECLS 255 256 #endif /* __GST_BUFFER_POOL_H__ */ 257