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 gst.app.AppSrc;
26 
27 private import gobject.ObjectG;
28 private import gobject.Signals;
29 private import gst.app.c.functions;
30 public  import gst.app.c.types;
31 private import gst.base.BaseSrc;
32 private import gstreamer.Buffer;
33 private import gstreamer.BufferList;
34 private import gstreamer.Caps;
35 private import gstreamer.Sample;
36 private import gstreamer.URIHandlerIF;
37 private import gstreamer.URIHandlerT;
38 private import std.algorithm;
39 
40 
41 /**
42  * The appsrc element can be used by applications to insert data into a
43  * GStreamer pipeline. Unlike most GStreamer elements, appsrc provides
44  * external API functions.
45  * 
46  * appsrc can be used by linking with the libgstapp library to access the
47  * methods directly or by using the appsrc action signals.
48  * 
49  * Before operating appsrc, the caps property must be set to fixed caps
50  * describing the format of the data that will be pushed with appsrc. An
51  * exception to this is when pushing buffers with unknown caps, in which case no
52  * caps should be set. This is typically true of file-like sources that push raw
53  * byte buffers. If you don't want to explicitly set the caps, you can use
54  * gst_app_src_push_sample. This method gets the caps associated with the
55  * sample and sets them on the appsrc replacing any previously set caps (if
56  * different from sample's caps).
57  * 
58  * The main way of handing data to the appsrc element is by calling the
59  * gst_app_src_push_buffer() method or by emitting the push-buffer action signal.
60  * This will put the buffer onto a queue from which appsrc will read from in its
61  * streaming thread. It is important to note that data transport will not happen
62  * from the thread that performed the push-buffer call.
63  * 
64  * The "max-bytes" property controls how much data can be queued in appsrc
65  * before appsrc considers the queue full. A filled internal queue will always
66  * signal the "enough-data" signal, which signals the application that it should
67  * stop pushing data into appsrc. The "block" property will cause appsrc to
68  * block the push-buffer method until free data becomes available again.
69  * 
70  * When the internal queue is running out of data, the "need-data" signal is
71  * emitted, which signals the application that it should start pushing more data
72  * into appsrc.
73  * 
74  * In addition to the "need-data" and "enough-data" signals, appsrc can emit the
75  * "seek-data" signal when the "stream-mode" property is set to "seekable" or
76  * "random-access". The signal argument will contain the new desired position in
77  * the stream expressed in the unit set with the "format" property. After
78  * receiving the seek-data signal, the application should push-buffers from the
79  * new position.
80  * 
81  * These signals allow the application to operate the appsrc in two different
82  * ways:
83  * 
84  * The push mode, in which the application repeatedly calls the push-buffer/push-sample
85  * method with a new buffer/sample. Optionally, the queue size in the appsrc
86  * can be controlled with the enough-data and need-data signals by respectively
87  * stopping/starting the push-buffer/push-sample calls. This is a typical
88  * mode of operation for the stream-type "stream" and "seekable". Use this
89  * mode when implementing various network protocols or hardware devices.
90  * 
91  * The pull mode, in which the need-data signal triggers the next push-buffer call.
92  * This mode is typically used in the "random-access" stream-type. Use this
93  * mode for file access or other randomly accessable sources. In this mode, a
94  * buffer of exactly the amount of bytes given by the need-data signal should be
95  * pushed into appsrc.
96  * 
97  * In all modes, the size property on appsrc should contain the total stream
98  * size in bytes. Setting this property is mandatory in the random-access mode.
99  * For the stream and seekable modes, setting this property is optional but
100  * recommended.
101  * 
102  * When the application has finished pushing data into appsrc, it should call
103  * gst_app_src_end_of_stream() or emit the end-of-stream action signal. After
104  * this call, no more buffers can be pushed into appsrc until a flushing seek
105  * occurs or the state of the appsrc has gone through READY.
106  */
107 public class AppSrc : BaseSrc, URIHandlerIF
108 {
109 	/** the main Gtk struct */
110 	protected GstAppSrc* gstAppSrc;
111 
112 	/** Get the main Gtk struct */
113 	public GstAppSrc* getAppSrcStruct(bool transferOwnership = false)
114 	{
115 		if (transferOwnership)
116 			ownedRef = false;
117 		return gstAppSrc;
118 	}
119 
120 	/** the main Gtk struct as a void* */
121 	protected override void* getStruct()
122 	{
123 		return cast(void*)gstAppSrc;
124 	}
125 
126 	/**
127 	 * Sets our main struct and passes it to the parent class.
128 	 */
129 	public this (GstAppSrc* gstAppSrc, bool ownedRef = false)
130 	{
131 		this.gstAppSrc = gstAppSrc;
132 		super(cast(GstBaseSrc*)gstAppSrc, ownedRef);
133 	}
134 
135 	// add the URIHandler capabilities
136 	mixin URIHandlerT!(GstAppSrc);
137 
138 
139 	/** */
140 	public static GType getType()
141 	{
142 		return gst_app_src_get_type();
143 	}
144 
145 	/**
146 	 * Indicates to the appsrc element that the last buffer queued in the
147 	 * element is the last buffer of the stream.
148 	 *
149 	 * Returns: #GST_FLOW_OK when the EOS was successfuly queued.
150 	 *     #GST_FLOW_FLUSHING when @appsrc is not PAUSED or PLAYING.
151 	 */
152 	public GstFlowReturn endOfStream()
153 	{
154 		return gst_app_src_end_of_stream(gstAppSrc);
155 	}
156 
157 	/**
158 	 * Get the configured caps on @appsrc.
159 	 *
160 	 * Returns: the #GstCaps produced by the source. gst_caps_unref() after usage.
161 	 */
162 	public Caps getCaps()
163 	{
164 		auto p = gst_app_src_get_caps(gstAppSrc);
165 
166 		if(p is null)
167 		{
168 			return null;
169 		}
170 
171 		return ObjectG.getDObject!(Caps)(cast(GstCaps*) p, true);
172 	}
173 
174 	/**
175 	 * Get the number of currently queued bytes inside @appsrc.
176 	 *
177 	 * Returns: The number of currently queued bytes.
178 	 *
179 	 * Since: 1.2
180 	 */
181 	public ulong getCurrentLevelBytes()
182 	{
183 		return gst_app_src_get_current_level_bytes(gstAppSrc);
184 	}
185 
186 	/**
187 	 * Get the duration of the stream in nanoseconds. A value of GST_CLOCK_TIME_NONE means that the duration is
188 	 * not known.
189 	 *
190 	 * Returns: the duration of the stream previously set with gst_app_src_set_duration();
191 	 *
192 	 * Since: 1.10
193 	 */
194 	public GstClockTime getDuration()
195 	{
196 		return gst_app_src_get_duration(gstAppSrc);
197 	}
198 
199 	/**
200 	 * Check if appsrc will emit the "new-preroll" and "new-buffer" signals.
201 	 *
202 	 * Returns: %TRUE if @appsrc is emitting the "new-preroll" and "new-buffer"
203 	 *     signals.
204 	 */
205 	public bool getEmitSignals()
206 	{
207 		return gst_app_src_get_emit_signals(gstAppSrc) != 0;
208 	}
209 
210 	/**
211 	 * Retrieve the min and max latencies in @min and @max respectively.
212 	 *
213 	 * Params:
214 	 *     min = the min latency
215 	 *     max = the max latency
216 	 */
217 	public void getLatency(out ulong min, out ulong max)
218 	{
219 		gst_app_src_get_latency(gstAppSrc, &min, &max);
220 	}
221 
222 	/**
223 	 * Get the maximum amount of bytes that can be queued in @appsrc.
224 	 *
225 	 * Returns: The maximum amount of bytes that can be queued.
226 	 */
227 	public ulong getMaxBytes()
228 	{
229 		return gst_app_src_get_max_bytes(gstAppSrc);
230 	}
231 
232 	/**
233 	 * Get the size of the stream in bytes. A value of -1 means that the size is
234 	 * not known.
235 	 *
236 	 * Returns: the size of the stream previously set with gst_app_src_set_size();
237 	 */
238 	public long getSize()
239 	{
240 		return gst_app_src_get_size(gstAppSrc);
241 	}
242 
243 	/**
244 	 * Get the stream type. Control the stream type of @appsrc
245 	 * with gst_app_src_set_stream_type().
246 	 *
247 	 * Returns: the stream type.
248 	 */
249 	public GstAppStreamType getStreamType()
250 	{
251 		return gst_app_src_get_stream_type(gstAppSrc);
252 	}
253 
254 	/**
255 	 * Adds a buffer to the queue of buffers that the appsrc element will
256 	 * push to its source pad.  This function takes ownership of the buffer.
257 	 *
258 	 * When the block property is TRUE, this function can block until free
259 	 * space becomes available in the queue.
260 	 *
261 	 * Params:
262 	 *     buffer = a #GstBuffer to push
263 	 *
264 	 * Returns: #GST_FLOW_OK when the buffer was successfuly queued.
265 	 *     #GST_FLOW_FLUSHING when @appsrc is not PAUSED or PLAYING.
266 	 *     #GST_FLOW_EOS when EOS occured.
267 	 */
268 	public GstFlowReturn pushBuffer(Buffer buffer)
269 	{
270 		return gst_app_src_push_buffer(gstAppSrc, (buffer is null) ? null : buffer.getBufferStruct());
271 	}
272 
273 	/**
274 	 * Adds a buffer list to the queue of buffers and buffer lists that the
275 	 * appsrc element will push to its source pad.  This function takes ownership
276 	 * of @buffer_list.
277 	 *
278 	 * When the block property is TRUE, this function can block until free
279 	 * space becomes available in the queue.
280 	 *
281 	 * Params:
282 	 *     bufferList = a #GstBufferList to push
283 	 *
284 	 * Returns: #GST_FLOW_OK when the buffer list was successfuly queued.
285 	 *     #GST_FLOW_FLUSHING when @appsrc is not PAUSED or PLAYING.
286 	 *     #GST_FLOW_EOS when EOS occured.
287 	 *
288 	 * Since: 1.14
289 	 */
290 	public GstFlowReturn pushBufferList(BufferList bufferList)
291 	{
292 		return gst_app_src_push_buffer_list(gstAppSrc, (bufferList is null) ? null : bufferList.getBufferListStruct());
293 	}
294 
295 	/**
296 	 * Extract a buffer from the provided sample and adds it to the queue of
297 	 * buffers that the appsrc element will push to its source pad. Any
298 	 * previous caps that were set on appsrc will be replaced by the caps
299 	 * associated with the sample if not equal.
300 	 *
301 	 * When the block property is TRUE, this function can block until free
302 	 * space becomes available in the queue.
303 	 *
304 	 * Params:
305 	 *     sample = a #GstSample from which buffer and caps may be
306 	 *         extracted
307 	 *
308 	 * Returns: #GST_FLOW_OK when the buffer was successfuly queued.
309 	 *     #GST_FLOW_FLUSHING when @appsrc is not PAUSED or PLAYING.
310 	 *     #GST_FLOW_EOS when EOS occured.
311 	 *
312 	 * Since: 1.6
313 	 */
314 	public GstFlowReturn pushSample(Sample sample)
315 	{
316 		return gst_app_src_push_sample(gstAppSrc, (sample is null) ? null : sample.getSampleStruct());
317 	}
318 
319 	/**
320 	 * Set callbacks which will be executed when data is needed, enough data has
321 	 * been collected or when a seek should be performed.
322 	 * This is an alternative to using the signals, it has lower overhead and is thus
323 	 * less expensive, but also less flexible.
324 	 *
325 	 * If callbacks are installed, no signals will be emitted for performance
326 	 * reasons.
327 	 *
328 	 * Params:
329 	 *     callbacks = the callbacks
330 	 *     userData = a user_data argument for the callbacks
331 	 *     notify = a destroy notify function
332 	 */
333 	public void setCallbacks(GstAppSrcCallbacks* callbacks, void* userData, GDestroyNotify notify)
334 	{
335 		gst_app_src_set_callbacks(gstAppSrc, callbacks, userData, notify);
336 	}
337 
338 	/**
339 	 * Set the duration of the stream in nanoseconds. A value of GST_CLOCK_TIME_NONE means that the duration is
340 	 * not known.
341 	 *
342 	 * Params:
343 	 *     duration = the duration to set
344 	 *
345 	 * Since: 1.10
346 	 */
347 	public void setDuration(GstClockTime duration)
348 	{
349 		gst_app_src_set_duration(gstAppSrc, duration);
350 	}
351 
352 	/**
353 	 * Make appsrc emit the "new-preroll" and "new-buffer" signals. This option is
354 	 * by default disabled because signal emission is expensive and unneeded when
355 	 * the application prefers to operate in pull mode.
356 	 *
357 	 * Params:
358 	 *     emit = the new state
359 	 */
360 	public void setEmitSignals(bool emit)
361 	{
362 		gst_app_src_set_emit_signals(gstAppSrc, emit);
363 	}
364 
365 	/**
366 	 * Configure the @min and @max latency in @src. If @min is set to -1, the
367 	 * default latency calculations for pseudo-live sources will be used.
368 	 *
369 	 * Params:
370 	 *     min = the min latency
371 	 *     max = the max latency
372 	 */
373 	public void setLatency(ulong min, ulong max)
374 	{
375 		gst_app_src_set_latency(gstAppSrc, min, max);
376 	}
377 
378 	/**
379 	 * Set the maximum amount of bytes that can be queued in @appsrc.
380 	 * After the maximum amount of bytes are queued, @appsrc will emit the
381 	 * "enough-data" signal.
382 	 *
383 	 * Params:
384 	 *     max = the maximum number of bytes to queue
385 	 */
386 	public void setMaxBytes(ulong max)
387 	{
388 		gst_app_src_set_max_bytes(gstAppSrc, max);
389 	}
390 
391 	/**
392 	 * Set the size of the stream in bytes. A value of -1 means that the size is
393 	 * not known.
394 	 *
395 	 * Params:
396 	 *     size = the size to set
397 	 */
398 	public void setSize(long size)
399 	{
400 		gst_app_src_set_size(gstAppSrc, size);
401 	}
402 
403 	/**
404 	 * Set the stream type on @appsrc. For seekable streams, the "seek" signal must
405 	 * be connected to.
406 	 *
407 	 * A stream_type stream
408 	 *
409 	 * Params:
410 	 *     type = the new state
411 	 */
412 	public void setStreamType(GstAppStreamType type)
413 	{
414 		gst_app_src_set_stream_type(gstAppSrc, type);
415 	}
416 
417 	/**
418 	 * Notify @appsrc that no more buffer are available.
419 	 */
420 	gulong addOnEndOfStream(GstFlowReturn delegate(AppSrc) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
421 	{
422 		return Signals.connect(this, "end-of-stream", dlg, connectFlags ^ ConnectFlags.SWAPPED);
423 	}
424 
425 	/**
426 	 * Signal that the source has enough data. It is recommended that the
427 	 * application stops calling push-buffer until the need-data signal is
428 	 * emitted again to avoid excessive buffer queueing.
429 	 */
430 	gulong addOnEnoughData(void delegate(AppSrc) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
431 	{
432 		return Signals.connect(this, "enough-data", dlg, connectFlags ^ ConnectFlags.SWAPPED);
433 	}
434 
435 	/**
436 	 * Signal that the source needs more data. In the callback or from another
437 	 * thread you should call push-buffer or end-of-stream.
438 	 *
439 	 * @length is just a hint and when it is set to -1, any number of bytes can be
440 	 * pushed into @appsrc.
441 	 *
442 	 * You can call push-buffer multiple times until the enough-data signal is
443 	 * fired.
444 	 *
445 	 * Params:
446 	 *     length = the amount of bytes needed.
447 	 */
448 	gulong addOnNeedData(void delegate(uint, AppSrc) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
449 	{
450 		return Signals.connect(this, "need-data", dlg, connectFlags ^ ConnectFlags.SWAPPED);
451 	}
452 
453 	/**
454 	 * Adds a buffer to the queue of buffers that the appsrc element will
455 	 * push to its source pad. This function does not take ownership of the
456 	 * buffer so the buffer needs to be unreffed after calling this function.
457 	 *
458 	 * When the block property is TRUE, this function can block until free space
459 	 * becomes available in the queue.
460 	 *
461 	 * Params:
462 	 *     buffer = a buffer to push
463 	 */
464 	gulong addOnPushBuffer(GstFlowReturn delegate(Buffer, AppSrc) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
465 	{
466 		return Signals.connect(this, "push-buffer", dlg, connectFlags ^ ConnectFlags.SWAPPED);
467 	}
468 
469 	/**
470 	 * Adds a buffer list to the queue of buffers and buffer lists that the
471 	 * appsrc element will push to its source pad. This function does not take
472 	 * ownership of the buffer list so the buffer list needs to be unreffed
473 	 * after calling this function.
474 	 *
475 	 * When the block property is TRUE, this function can block until free space
476 	 * becomes available in the queue.
477 	 *
478 	 * Params:
479 	 *     bufferList = a buffer list to push
480 	 *
481 	 * Since: 1.14
482 	 */
483 	gulong addOnPushBufferList(GstFlowReturn delegate(BufferList, AppSrc) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
484 	{
485 		return Signals.connect(this, "push-buffer-list", dlg, connectFlags ^ ConnectFlags.SWAPPED);
486 	}
487 
488 	/**
489 	 * Extract a buffer from the provided sample and adds the extracted buffer
490 	 * to the queue of buffers that the appsrc element will
491 	 * push to its source pad. This function set the appsrc caps based on the caps
492 	 * in the sample and reset the caps if they change.
493 	 * Only the caps and the buffer of the provided sample are used and not
494 	 * for example the segment in the sample.
495 	 * This function does not take ownership of the
496 	 * sample so the sample needs to be unreffed after calling this function.
497 	 *
498 	 * When the block property is TRUE, this function can block until free space
499 	 * becomes available in the queue.
500 	 *
501 	 * Params:
502 	 *     sample = a sample from which extract buffer to push
503 	 *
504 	 * Since: 1.6
505 	 */
506 	gulong addOnPushSample(GstFlowReturn delegate(Sample, AppSrc) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
507 	{
508 		return Signals.connect(this, "push-sample", dlg, connectFlags ^ ConnectFlags.SWAPPED);
509 	}
510 
511 	/**
512 	 * Seek to the given offset. The next push-buffer should produce buffers from
513 	 * the new @offset.
514 	 * This callback is only called for seekable stream types.
515 	 *
516 	 * Params:
517 	 *     offset = the offset to seek to
518 	 *
519 	 * Returns: %TRUE if the seek succeeded.
520 	 */
521 	gulong addOnSeekData(bool delegate(ulong, AppSrc) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
522 	{
523 		return Signals.connect(this, "seek-data", dlg, connectFlags ^ ConnectFlags.SWAPPED);
524 	}
525 
526 	/**
527 	 * Set the capabilities on the appsrc element.  This function takes
528 	 * a copy of the caps structure. After calling this method, the source will
529 	 * only produce caps that match @caps. @caps must be fixed and the caps on the
530 	 * buffers must match the caps or left NULL.
531 	 *
532 	 * Params:
533 	 *     caps = caps to set
534 	 */
535 	public void appSrcSetCaps(Caps caps)
536 	{
537 		gst_app_src_set_caps(gstAppSrc, (caps is null) ? null : caps.getCapsStruct());
538 	}
539 }