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