1 /*
2  * This file is part of gtkD.
3  *
4  * gtkD is free software; you can redistribute it and/or modify
5  * it under the terms of the GNU Lesser General Public License
6  * as published by the Free Software Foundation; either version 3
7  * of the License, or (at your option) any later version, with
8  * some exceptions, please read the COPYING file.
9  *
10  * gtkD is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13  * GNU Lesser General Public License for more details.
14  *
15  * You should have received a copy of the GNU Lesser General Public License
16  * along with gtkD; if not, write to the Free Software
17  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110, USA
18  */
19 
20 // generated automatically - do not change
21 // find conversion definition on APILookup.txt
22 // implement new conversion functionalities on the wrap.utils pakage
23 
24 
25 module gstreamer.BufferPool;
26 
27 private import glib.ConstructionException;
28 private import glib.Str;
29 private import gobject.ObjectG;
30 private import gstreamer.AllocationParams;
31 private import gstreamer.Allocator;
32 private import gstreamer.Buffer;
33 private import gstreamer.Caps;
34 private import gstreamer.ObjectGst;
35 private import gstreamer.Structure;
36 private import gstreamerc.gstreamer;
37 public  import gstreamerc.gstreamertypes;
38 
39 
40 /**
41  * A #GstBufferPool is an object that can be used to pre-allocate and recycle
42  * buffers of the same size and with the same properties.
43  * 
44  * A #GstBufferPool is created with gst_buffer_pool_new().
45  * 
46  * Once a pool is created, it needs to be configured. A call to
47  * gst_buffer_pool_get_config() returns the current configuration structure from
48  * the pool. With gst_buffer_pool_config_set_params() and
49  * gst_buffer_pool_config_set_allocator() the bufferpool parameters and
50  * allocator can be configured. Other properties can be configured in the pool
51  * depending on the pool implementation.
52  * 
53  * A bufferpool can have extra options that can be enabled with
54  * gst_buffer_pool_config_add_option(). The available options can be retrieved
55  * with gst_buffer_pool_get_options(). Some options allow for additional
56  * configuration properties to be set.
57  * 
58  * After the configuration structure has been configured,
59  * gst_buffer_pool_set_config() updates the configuration in the pool. This can
60  * fail when the configuration structure is not accepted.
61  * 
62  * After the a pool has been configured, it can be activated with
63  * gst_buffer_pool_set_active(). This will preallocate the configured resources
64  * in the pool.
65  * 
66  * When the pool is active, gst_buffer_pool_acquire_buffer() can be used to
67  * retrieve a buffer from the pool.
68  * 
69  * Buffers allocated from a bufferpool will automatically be returned to the
70  * pool with gst_buffer_pool_release_buffer() when their refcount drops to 0.
71  * 
72  * The bufferpool can be deactivated again with gst_buffer_pool_set_active().
73  * All further gst_buffer_pool_acquire_buffer() calls will return an error. When
74  * all buffers are returned to the pool they will be freed.
75  * 
76  * Use gst_object_unref() to release the reference to a bufferpool. If the
77  * refcount of the pool reaches 0, the pool will be freed.
78  */
79 public class BufferPool : ObjectGst
80 {
81 	/** the main Gtk struct */
82 	protected GstBufferPool* gstBufferPool;
83 
84 	/** Get the main Gtk struct */
85 	public GstBufferPool* getBufferPoolStruct()
86 	{
87 		return gstBufferPool;
88 	}
89 
90 	/** the main Gtk struct as a void* */
91 	protected override void* getStruct()
92 	{
93 		return cast(void*)gstBufferPool;
94 	}
95 
96 	protected override void setStruct(GObject* obj)
97 	{
98 		gstBufferPool = cast(GstBufferPool*)obj;
99 		super.setStruct(obj);
100 	}
101 
102 	/**
103 	 * Sets our main struct and passes it to the parent class.
104 	 */
105 	public this (GstBufferPool* gstBufferPool, bool ownedRef = false)
106 	{
107 		this.gstBufferPool = gstBufferPool;
108 		super(cast(GstObject*)gstBufferPool, ownedRef);
109 	}
110 
111 
112 	/** */
113 	public static GType getType()
114 	{
115 		return gst_buffer_pool_get_type();
116 	}
117 
118 	/**
119 	 * Creates a new #GstBufferPool instance.
120 	 *
121 	 * Return: a new #GstBufferPool instance
122 	 *
123 	 * Throws: ConstructionException GTK+ fails to create the object.
124 	 */
125 	public this()
126 	{
127 		auto p = gst_buffer_pool_new();
128 		
129 		if(p is null)
130 		{
131 			throw new ConstructionException("null returned by new");
132 		}
133 		
134 		this(cast(GstBufferPool*) p);
135 	}
136 
137 	/**
138 	 * Enabled the option in @config. This will instruct the @bufferpool to enable
139 	 * the specified option on the buffers that it allocates.
140 	 *
141 	 * The supported options by @pool can be retrieved with gst_buffer_pool_get_options().
142 	 *
143 	 * Params:
144 	 *     config = a #GstBufferPool configuration
145 	 *     option = an option to add
146 	 */
147 	public static void configAddOption(Structure config, string option)
148 	{
149 		gst_buffer_pool_config_add_option((config is null) ? null : config.getStructureStruct(), Str.toStringz(option));
150 	}
151 
152 	/**
153 	 * Get the @allocator and @params from @config.
154 	 *
155 	 * Params:
156 	 *     config = a #GstBufferPool configuration
157 	 *     allocator = a #GstAllocator, or %NULL
158 	 *     params = #GstAllocationParams, or %NULL
159 	 *
160 	 * Return: %TRUE, if the values are set.
161 	 */
162 	public static bool configGetAllocator(Structure config, ref Allocator allocator, out AllocationParams params)
163 	{
164 		GstAllocator* outallocator = allocator.getAllocatorStruct();
165 		GstAllocationParams* outparams = gMalloc!GstAllocationParams();
166 		
167 		auto p = gst_buffer_pool_config_get_allocator((config is null) ? null : config.getStructureStruct(), &outallocator, outparams) != 0;
168 		
169 		allocator = ObjectG.getDObject!(Allocator)(outallocator);
170 		params = ObjectG.getDObject!(AllocationParams)(outparams, true);
171 		
172 		return p;
173 	}
174 
175 	/**
176 	 * Parse an available @config and get the option at @index of the options API
177 	 * array.
178 	 *
179 	 * Params:
180 	 *     config = a #GstBufferPool configuration
181 	 *     index = position in the option array to read
182 	 *
183 	 * Return: a #gchar of the option at @index.
184 	 */
185 	public static string configGetOption(Structure config, uint index)
186 	{
187 		return Str.toString(gst_buffer_pool_config_get_option((config is null) ? null : config.getStructureStruct(), index));
188 	}
189 
190 	/**
191 	 * Get the configuration values from @config.
192 	 *
193 	 * Params:
194 	 *     config = a #GstBufferPool configuration
195 	 *     caps = the caps of buffers
196 	 *     size = the size of each buffer, not including prefix and padding
197 	 *     minBuffers = the minimum amount of buffers to allocate.
198 	 *     maxBuffers = the maximum amount of buffers to allocate or 0 for unlimited.
199 	 *
200 	 * Return: %TRUE if all parameters could be fetched.
201 	 */
202 	public static bool configGetParams(Structure config, out Caps caps, out uint size, out uint minBuffers, out uint maxBuffers)
203 	{
204 		GstCaps* outcaps = null;
205 		
206 		auto p = gst_buffer_pool_config_get_params((config is null) ? null : config.getStructureStruct(), &outcaps, &size, &minBuffers, &maxBuffers) != 0;
207 		
208 		caps = ObjectG.getDObject!(Caps)(outcaps);
209 		
210 		return p;
211 	}
212 
213 	/**
214 	 * Check if @config contains @option.
215 	 *
216 	 * Params:
217 	 *     config = a #GstBufferPool configuration
218 	 *     option = an option
219 	 *
220 	 * Return: %TRUE if the options array contains @option.
221 	 */
222 	public static bool configHasOption(Structure config, string option)
223 	{
224 		return gst_buffer_pool_config_has_option((config is null) ? null : config.getStructureStruct(), Str.toStringz(option)) != 0;
225 	}
226 
227 	/**
228 	 * Retrieve the number of values currently stored in the options array of the
229 	 * @config structure.
230 	 *
231 	 * Params:
232 	 *     config = a #GstBufferPool configuration
233 	 *
234 	 * Return: the options array size as a #guint.
235 	 */
236 	public static uint configNOptions(Structure config)
237 	{
238 		return gst_buffer_pool_config_n_options((config is null) ? null : config.getStructureStruct());
239 	}
240 
241 	/**
242 	 * Set the @allocator and @params on @config.
243 	 *
244 	 * One of @allocator and @params can be %NULL, but not both. When @allocator
245 	 * is %NULL, the default allocator of the pool will use the values in @param
246 	 * to perform its allocation. When @param is %NULL, the pool will use the
247 	 * provided @allocator with its default #GstAllocationParams.
248 	 *
249 	 * A call to gst_buffer_pool_set_config() can update the allocator and params
250 	 * with the values that it is able to do. Some pools are, for example, not able
251 	 * to operate with different allocators or cannot allocate with the values
252 	 * specified in @params. Use gst_buffer_pool_get_config() to get the currently
253 	 * used values.
254 	 *
255 	 * Params:
256 	 *     config = a #GstBufferPool configuration
257 	 *     allocator = a #GstAllocator
258 	 *     params = #GstAllocationParams
259 	 */
260 	public static void configSetAllocator(Structure config, Allocator allocator, AllocationParams params)
261 	{
262 		gst_buffer_pool_config_set_allocator((config is null) ? null : config.getStructureStruct(), (allocator is null) ? null : allocator.getAllocatorStruct(), (params is null) ? null : params.getAllocationParamsStruct());
263 	}
264 
265 	/**
266 	 * Configure @config with the given parameters.
267 	 *
268 	 * Params:
269 	 *     config = a #GstBufferPool configuration
270 	 *     caps = caps for the buffers
271 	 *     size = the size of each buffer, not including prefix and padding
272 	 *     minBuffers = the minimum amount of buffers to allocate.
273 	 *     maxBuffers = the maximum amount of buffers to allocate or 0 for unlimited.
274 	 */
275 	public static void configSetParams(Structure config, Caps caps, uint size, uint minBuffers, uint maxBuffers)
276 	{
277 		gst_buffer_pool_config_set_params((config is null) ? null : config.getStructureStruct(), (caps is null) ? null : caps.getCapsStruct(), size, minBuffers, maxBuffers);
278 	}
279 
280 	/**
281 	 * Validate that changes made to @config are still valid in the context of the
282 	 * expected parameters. This function is a helper that can be used to validate
283 	 * changes made by a pool to a config when gst_buffer_pool_set_config()
284 	 * returns %FALSE. This expects that @caps haven't changed and that
285 	 * @min_buffers aren't lower then what we initially expected.
286 	 * This does not check if options or allocator parameters are still valid,
287 	 * won't check if size have changed, since changing the size is valid to adapt
288 	 * padding.
289 	 *
290 	 * Params:
291 	 *     config = a #GstBufferPool configuration
292 	 *     caps = the excepted caps of buffers
293 	 *     size = the expected size of each buffer, not including prefix and padding
294 	 *     minBuffers = the expected minimum amount of buffers to allocate.
295 	 *     maxBuffers = the expect maximum amount of buffers to allocate or 0 for unlimited.
296 	 *
297 	 * Return: %TRUE, if the parameters are valid in this context.
298 	 *
299 	 * Since: 1.4
300 	 */
301 	public static bool configValidateParams(Structure config, Caps caps, uint size, uint minBuffers, uint maxBuffers)
302 	{
303 		return gst_buffer_pool_config_validate_params((config is null) ? null : config.getStructureStruct(), (caps is null) ? null : caps.getCapsStruct(), size, minBuffers, maxBuffers) != 0;
304 	}
305 
306 	/**
307 	 * Acquire a buffer from @pool. @buffer should point to a memory location that
308 	 * can hold a pointer to the new buffer.
309 	 *
310 	 * @params can be %NULL or contain optional parameters to influence the
311 	 * allocation.
312 	 *
313 	 * Params:
314 	 *     buffer = a location for a #GstBuffer
315 	 *     params = parameters.
316 	 *
317 	 * Return: a #GstFlowReturn such as %GST_FLOW_FLUSHING when the pool is
318 	 *     inactive.
319 	 */
320 	public GstFlowReturn acquireBuffer(out Buffer buffer, GstBufferPoolAcquireParams* params)
321 	{
322 		GstBuffer* outbuffer = null;
323 		
324 		auto p = gst_buffer_pool_acquire_buffer(gstBufferPool, &outbuffer, params);
325 		
326 		buffer = ObjectG.getDObject!(Buffer)(outbuffer);
327 		
328 		return p;
329 	}
330 
331 	/**
332 	 * Get a copy of the current configuration of the pool. This configuration
333 	 * can either be modified and used for the gst_buffer_pool_set_config() call
334 	 * or it must be freed after usage.
335 	 *
336 	 * Return: a copy of the current configuration of @pool. use
337 	 *     gst_structure_free() after usage or gst_buffer_pool_set_config().
338 	 */
339 	public Structure getConfig()
340 	{
341 		auto p = gst_buffer_pool_get_config(gstBufferPool);
342 		
343 		if(p is null)
344 		{
345 			return null;
346 		}
347 		
348 		return ObjectG.getDObject!(Structure)(cast(GstStructure*) p, true);
349 	}
350 
351 	/**
352 	 * Get a %NULL terminated array of string with supported bufferpool options for
353 	 * @pool. An option would typically be enabled with
354 	 * gst_buffer_pool_config_add_option().
355 	 *
356 	 * Return: a %NULL terminated array
357 	 *     of strings.
358 	 */
359 	public string[] getOptions()
360 	{
361 		return Str.toStringArray(gst_buffer_pool_get_options(gstBufferPool));
362 	}
363 
364 	/**
365 	 * Check if the bufferpool supports @option.
366 	 *
367 	 * Params:
368 	 *     option = an option
369 	 *
370 	 * Return: %TRUE if the buffer pool contains @option.
371 	 */
372 	public bool hasOption(string option)
373 	{
374 		return gst_buffer_pool_has_option(gstBufferPool, Str.toStringz(option)) != 0;
375 	}
376 
377 	/**
378 	 * Check if @pool is active. A pool can be activated with the
379 	 * gst_buffer_pool_set_active() call.
380 	 *
381 	 * Return: %TRUE when the pool is active.
382 	 */
383 	public bool isActive()
384 	{
385 		return gst_buffer_pool_is_active(gstBufferPool) != 0;
386 	}
387 
388 	/**
389 	 * Release @buffer to @pool. @buffer should have previously been allocated from
390 	 * @pool with gst_buffer_pool_acquire_buffer().
391 	 *
392 	 * This function is usually called automatically when the last ref on @buffer
393 	 * disappears.
394 	 *
395 	 * Params:
396 	 *     buffer = a #GstBuffer
397 	 */
398 	public void releaseBuffer(Buffer buffer)
399 	{
400 		gst_buffer_pool_release_buffer(gstBufferPool, (buffer is null) ? null : buffer.getBufferStruct());
401 	}
402 
403 	/**
404 	 * Control the active state of @pool. When the pool is inactive, new calls to
405 	 * gst_buffer_pool_acquire_buffer() will return with %GST_FLOW_FLUSHING.
406 	 *
407 	 * Activating the bufferpool will preallocate all resources in the pool based on
408 	 * the configuration of the pool.
409 	 *
410 	 * Deactivating will free the resources again when there are no outstanding
411 	 * buffers. When there are outstanding buffers, they will be freed as soon as
412 	 * they are all returned to the pool.
413 	 *
414 	 * Params:
415 	 *     active = the new active state
416 	 *
417 	 * Return: %FALSE when the pool was not configured or when preallocation of the
418 	 *     buffers failed.
419 	 */
420 	public bool setActive(bool active)
421 	{
422 		return gst_buffer_pool_set_active(gstBufferPool, active) != 0;
423 	}
424 
425 	/**
426 	 * Set the configuration of the pool. If the pool is already configured, and
427 	 * the configuration haven't change, this function will return %TRUE. If the
428 	 * pool is active, this method will return %FALSE and active configuration
429 	 * will remain. Buffers allocated form this pool must be returned or else this
430 	 * function will do nothing and return %FALSE.
431 	 *
432 	 * @config is a #GstStructure that contains the configuration parameters for
433 	 * the pool. A default and mandatory set of parameters can be configured with
434 	 * gst_buffer_pool_config_set_params(), gst_buffer_pool_config_set_allocator()
435 	 * and gst_buffer_pool_config_add_option().
436 	 *
437 	 * If the parameters in @config can not be set exactly, this function returns
438 	 * %FALSE and will try to update as much state as possible. The new state can
439 	 * then be retrieved and refined with gst_buffer_pool_get_config().
440 	 *
441 	 * This function takes ownership of @config.
442 	 *
443 	 * Params:
444 	 *     config = a #GstStructure
445 	 *
446 	 * Return: %TRUE when the configuration could be set.
447 	 */
448 	public bool setConfig(Structure config)
449 	{
450 		return gst_buffer_pool_set_config(gstBufferPool, (config is null) ? null : config.getStructureStruct()) != 0;
451 	}
452 
453 	/**
454 	 * Enable or disable the flushing state of a @pool without freeing or
455 	 * allocating buffers.
456 	 *
457 	 * Params:
458 	 *     flushing = whether to start or stop flushing
459 	 *
460 	 * Since: 1.4
461 	 */
462 	public void setFlushing(bool flushing)
463 	{
464 		gst_buffer_pool_set_flushing(gstBufferPool, flushing);
465 	}
466 }