Debian Codegraph @

libs/gst/base/gstbasesrc.h

raw
1 /* GStreamer
2 * Copyright (C) 1999,2000 Erik Walthinsen <[email protected]>
3 * 2000 Wim Taymans <[email protected]>
4 * 2005 Wim Taymans <[email protected]>
5 *
6 * gstbasesrc.h:
7 *
8 * This library is free software; you can redistribute it and/or
9 * modify it under the terms of the GNU Library General Public
10 * License as published by the Free Software Foundation; either
11 * version 2 of the License, or (at your option) any later version.
12 *
13 * This library is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 * Library General Public License for more details.
17 *
18 * You should have received a copy of the GNU Library General Public
19 * License along with this library; if not, write to the
20 * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
21 * Boston, MA 02110-1301, USA.
22 */
23
24 #ifndef __GST_BASE_SRC_H__
25 #define __GST_BASE_SRC_H__
26
27 #include <gst/gst.h>
28 #include <gst/base/base-prelude.h>
29
30 G_BEGIN_DECLS
31
32 #define GST_TYPE_BASE_SRC (gst_base_src_get_type())
33 #define GST_BASE_SRC(obj) (G_TYPE_CHECK_INSTANCE_CAST((obj),GST_TYPE_BASE_SRC,GstBaseSrc))
34 #define GST_BASE_SRC_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST((klass),GST_TYPE_BASE_SRC,GstBaseSrcClass))
35 #define GST_BASE_SRC_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), GST_TYPE_BASE_SRC, GstBaseSrcClass))
36 #define GST_IS_BASE_SRC(obj) (G_TYPE_CHECK_INSTANCE_TYPE((obj),GST_TYPE_BASE_SRC))
37 #define GST_IS_BASE_SRC_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass),GST_TYPE_BASE_SRC))
38 #define GST_BASE_SRC_CAST(obj) ((GstBaseSrc *)(obj))
39
40 /**
41 * GstBaseSrcFlags:
42 * @GST_BASE_SRC_FLAG_STARTING: has source is starting
43 * @GST_BASE_SRC_FLAG_STARTED: has source been started
44 * @GST_BASE_SRC_FLAG_LAST: offset to define more flags
45 *
46 * The #GstElement flags that a basesrc element may have.
47 */
48 typedef enum {
49 GST_BASE_SRC_FLAG_STARTING = (GST_ELEMENT_FLAG_LAST << 0),
50 GST_BASE_SRC_FLAG_STARTED = (GST_ELEMENT_FLAG_LAST << 1),
51 /* padding */
52 GST_BASE_SRC_FLAG_LAST = (GST_ELEMENT_FLAG_LAST << 6)
53 } GstBaseSrcFlags;
54
55 #define GST_BASE_SRC_IS_STARTING(obj) GST_OBJECT_FLAG_IS_SET ((obj), GST_BASE_SRC_FLAG_STARTING)
56 #define GST_BASE_SRC_IS_STARTED(obj) GST_OBJECT_FLAG_IS_SET ((obj), GST_BASE_SRC_FLAG_STARTED)
57
58 typedef struct _GstBaseSrc GstBaseSrc;
59 typedef struct _GstBaseSrcClass GstBaseSrcClass;
60 typedef struct _GstBaseSrcPrivate GstBaseSrcPrivate;
61
62 /**
63 * GST_BASE_SRC_PAD:
64 * @obj: base source instance
65 *
66 * Gives the pointer to the #GstPad object of the element.
67 */
68 #define GST_BASE_SRC_PAD(obj) (GST_BASE_SRC_CAST (obj)->srcpad)
69
70
71 /**
72 * GstBaseSrc:
73 *
74 * The opaque #GstBaseSrc data structure.
75 */
76 struct _GstBaseSrc {
77 GstElement element;
78
79 /*< protected >*/
80 GstPad *srcpad;
81
82 /* available to subclass implementations */
83 /* MT-protected (with LIVE_LOCK) */
84 GMutex live_lock;
85 GCond live_cond;
86 gboolean is_live;
87 gboolean live_running;
88
89 /* MT-protected (with LOCK) */
90 guint blocksize; /* size of buffers when operating push based */
91 gboolean can_activate_push; /* some scheduling properties */
92 gboolean random_access;
93
94 GstClockID clock_id; /* for syncing */
95
96 /* MT-protected (with STREAM_LOCK *and* OBJECT_LOCK) */
97 GstSegment segment;
98 /* MT-protected (with STREAM_LOCK) */
99 gboolean need_newsegment;
100
101 gint num_buffers;
102 gint num_buffers_left;
103
104 #ifndef GST_REMOVE_DEPRECATED
105 gboolean typefind; /* unused */
106 #endif
107
108 gboolean running;
109 GstEvent *pending_seek;
110
111 GstBaseSrcPrivate *priv;
112
113 /*< private >*/
114 gpointer _gst_reserved[GST_PADDING_LARGE];
115 };
116
117 /**
118 * GstBaseSrcClass:
119 * @parent_class: Element parent class
120 * @get_caps: Called to get the caps to report
121 * @negotiate: Negotiated the caps with the peer.
122 * @fixate: Called during negotiation if caps need fixating. Implement instead of
123 * setting a fixate function on the source pad.
124 * @set_caps: Notify subclass of changed output caps
125 * @decide_allocation: configure the allocation query
126 * @start: Start processing. Subclasses should open resources and prepare
127 * to produce data. Implementation should call gst_base_src_start_complete()
128 * when the operation completes, either from the current thread or any other
129 * thread that finishes the start operation asynchronously.
130 * @stop: Stop processing. Subclasses should use this to close resources.
131 * @get_times: Given a buffer, return the start and stop time when it
132 * should be pushed out. The base class will sync on the clock using
133 * these times.
134 * @get_size: Return the total size of the resource, in the format set by
135 * gst_base_src_set_format().
136 * @is_seekable: Check if the source can seek
137 * @prepare_seek_segment: Prepare the #GstSegment that will be passed to the
138 * #GstBaseSrcClass::do_seek vmethod for executing a seek
139 * request. Sub-classes should override this if they support seeking in
140 * formats other than the configured native format. By default, it tries to
141 * convert the seek arguments to the configured native format and prepare a
142 * segment in that format.
143 * @do_seek: Perform seeking on the resource to the indicated segment.
144 * @unlock: Unlock any pending access to the resource. Subclasses should unblock
145 * any blocked function ASAP. In particular, any `create()` function in
146 * progress should be unblocked and should return GST_FLOW_FLUSHING. Any
147 * future #GstBaseSrcClass::create function call should also return
148 * GST_FLOW_FLUSHING until the #GstBaseSrcClass::unlock_stop function has
149 * been called.
150 * @unlock_stop: Clear the previous unlock request. Subclasses should clear any
151 * state they set during #GstBaseSrcClass::unlock, such as clearing command
152 * queues.
153 * @query: Handle a requested query.
154 * @event: Override this to implement custom event handling.
155 * @create: Ask the subclass to create a buffer with offset and size. When the
156 * subclass returns GST_FLOW_OK, it MUST return a buffer of the requested size
157 * unless fewer bytes are available because an EOS condition is near. No
158 * buffer should be returned when the return value is different from
159 * GST_FLOW_OK. A return value of GST_FLOW_EOS signifies that the end of
160 * stream is reached. The default implementation will call
161 * #GstBaseSrcClass::alloc and then call #GstBaseSrcClass::fill.
162 * @alloc: Ask the subclass to allocate a buffer with for offset and size. The
163 * default implementation will create a new buffer from the negotiated allocator.
164 * @fill: Ask the subclass to fill the buffer with data for offset and size. The
165 * passed buffer is guaranteed to hold the requested amount of bytes.
166 *
167 * Subclasses can override any of the available virtual methods or not, as
168 * needed. At the minimum, the @create method should be overridden to produce
169 * buffers.
170 */
171 struct _GstBaseSrcClass {
172 GstElementClass parent_class;
173
174 /*< public >*/
175 /* virtual methods for subclasses */
176
177 /**
178 * GstBaseSrcClass::get_caps:
179 * @filter: (in) (nullable):
180 *
181 * Called to get the caps to report.
182 */
183 GstCaps* (*get_caps) (GstBaseSrc *src, GstCaps *filter);
184 /* decide on caps */
185 gboolean (*negotiate) (GstBaseSrc *src);
186 /* called if, in negotiation, caps need fixating */
187 /**
188 * GstBaseSrcClass::fixate:
189 * @caps: (transfer full):
190 *
191 * Called if, in negotiation, caps need fixating.
192 *
193 * Returns: (transfer full): the fixated caps
194 */
195 GstCaps * (*fixate) (GstBaseSrc *src, GstCaps *caps);
196 /* notify the subclass of new caps */
197 gboolean (*set_caps) (GstBaseSrc *src, GstCaps *caps);
198
199 /* setup allocation query */
200 gboolean (*decide_allocation) (GstBaseSrc *src, GstQuery *query);
201
202 /* start and stop processing, ideal for opening/closing the resource */
203 gboolean (*start) (GstBaseSrc *src);
204 gboolean (*stop) (GstBaseSrc *src);
205
206 /**
207 * GstBaseSrcClass::get_times:
208 * @start: (out):
209 * @end: (out):
210 *
211 * Given @buffer, return @start and @end time when it should be pushed
212 * out. The base class will sync on the clock using these times.
213 */
214 void (*get_times) (GstBaseSrc *src, GstBuffer *buffer,
215 GstClockTime *start, GstClockTime *end);
216
217 /**
218 * GstBaseSrcClass::get_size:
219 * @size: (out):
220 *
221 * Get the total size of the resource in the format set by
222 * gst_base_src_set_format().
223 *
224 * Returns: %TRUE if the size is available and has been set.
225 */
226 gboolean (*get_size) (GstBaseSrc *src, guint64 *size);
227
228 /* check if the resource is seekable */
229 gboolean (*is_seekable) (GstBaseSrc *src);
230
231 /* Prepare the segment on which to perform do_seek(), converting to the
232 * current basesrc format. */
233 gboolean (*prepare_seek_segment) (GstBaseSrc *src, GstEvent *seek,
234 GstSegment *segment);
235 /* notify subclasses of a seek */
236 gboolean (*do_seek) (GstBaseSrc *src, GstSegment *segment);
237
238 /* unlock any pending access to the resource. subclasses should unlock
239 * any function ASAP. */
240 gboolean (*unlock) (GstBaseSrc *src);
241 /* Clear any pending unlock request, as we succeeded in unlocking */
242 gboolean (*unlock_stop) (GstBaseSrc *src);
243
244 /* notify subclasses of a query */
245 gboolean (*query) (GstBaseSrc *src, GstQuery *query);
246
247 /* notify subclasses of an event */
248 gboolean (*event) (GstBaseSrc *src, GstEvent *event);
249
250 /**
251 * GstBaseSrcClass::create:
252 * @buf: (inout) (nullable):
253 *
254 * Ask the subclass to create a buffer with @offset and @size, the default
255 * implementation will call alloc if no allocated @buf is provided and then call fill.
256 */
257 GstFlowReturn (*create) (GstBaseSrc *src, guint64 offset, guint size,
258 GstBuffer **buf);
259 /**
260 * GstBaseSrcClass::alloc:
261 * @buf: (out) (nullable):
262 *
263 * Ask the subclass to allocate an output buffer with @offset and @size, the default
264 * implementation will use the negotiated allocator.
265 */
266 GstFlowReturn (*alloc) (GstBaseSrc *src, guint64 offset, guint size,
267 GstBuffer **buf);
268 /* ask the subclass to fill the buffer with data from offset and size */
269 GstFlowReturn (*fill) (GstBaseSrc *src, guint64 offset, guint size,
270 GstBuffer *buf);
271
272 /*< private >*/
273 gpointer _gst_reserved[GST_PADDING_LARGE];
274 };
275
276 GST_BASE_API
277 GType gst_base_src_get_type (void);
278
279 GST_BASE_API
280 GstFlowReturn gst_base_src_wait_playing (GstBaseSrc *src);
281
282 GST_BASE_API
283 void gst_base_src_set_live (GstBaseSrc *src, gboolean live);
284
285 GST_BASE_API
286 gboolean gst_base_src_is_live (GstBaseSrc *src);
287
288 GST_BASE_API
289 void gst_base_src_set_format (GstBaseSrc *src, GstFormat format);
290
291 GST_BASE_API
292 void gst_base_src_set_dynamic_size (GstBaseSrc * src, gboolean dynamic);
293
294 GST_BASE_API
295 void gst_base_src_set_automatic_eos (GstBaseSrc * src, gboolean automatic_eos);
296
297 GST_BASE_API
298 void gst_base_src_set_async (GstBaseSrc *src, gboolean async);
299
300 GST_BASE_API
301 gboolean gst_base_src_is_async (GstBaseSrc *src);
302
303 GST_BASE_API
304 gboolean gst_base_src_negotiate (GstBaseSrc *src);
305
306 GST_BASE_API
307 void gst_base_src_start_complete (GstBaseSrc * basesrc, GstFlowReturn ret);
308
309 GST_BASE_API
310 GstFlowReturn gst_base_src_start_wait (GstBaseSrc * basesrc);
311
312 GST_BASE_API
313 gboolean gst_base_src_query_latency (GstBaseSrc *src, gboolean * live,
314 GstClockTime * min_latency,
315 GstClockTime * max_latency);
316 GST_BASE_API
317 void gst_base_src_set_blocksize (GstBaseSrc *src, guint blocksize);
318
319 GST_BASE_API
320 guint gst_base_src_get_blocksize (GstBaseSrc *src);
321
322 GST_BASE_API
323 void gst_base_src_set_do_timestamp (GstBaseSrc *src, gboolean timestamp);
324
325 GST_BASE_API
326 gboolean gst_base_src_get_do_timestamp (GstBaseSrc *src);
327
328 GST_BASE_API
329 gboolean gst_base_src_new_seamless_segment (GstBaseSrc *src, gint64 start, gint64 stop, gint64 time);
330
331 GST_BASE_API
332 gboolean gst_base_src_new_segment (GstBaseSrc *src,
333 const GstSegment * segment);
334
335 GST_BASE_API
336 gboolean gst_base_src_set_caps (GstBaseSrc *src, GstCaps *caps);
337
338 GST_BASE_API
339 GstBufferPool * gst_base_src_get_buffer_pool (GstBaseSrc *src) G_GNUC_WARN_UNUSED_RESULT;
340
341 GST_BASE_API
342 void gst_base_src_get_allocator (GstBaseSrc *src,
343 GstAllocator **allocator,
344 GstAllocationParams *params);
345
346 GST_BASE_API
347 void gst_base_src_submit_buffer_list (GstBaseSrc * src,
348 GstBufferList * buffer_list);
349
350 GST_BASE_API
351 gboolean gst_base_src_push_segment (GstBaseSrc * src,
352 const GstSegment * segment);
353
354 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstBaseSrc, gst_object_unref)
355
356 G_END_DECLS
357
358 #endif /* __GST_BASE_SRC_H__ */