2 * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
3 * 2000 Wim Taymans <wtay@chello.be>
4 * 2005 Wim Taymans <wim@fluendo.com>
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.
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.
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.
24 #ifndef __GST_BASE_SRC_H__
25 #define __GST_BASE_SRC_H__
31 #define GST_TYPE_BASE_SRC (gst_base_src_get_type())
32 #define GST_BASE_SRC(obj) (G_TYPE_CHECK_INSTANCE_CAST((obj),GST_TYPE_BASE_SRC,GstBaseSrc))
33 #define GST_BASE_SRC_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST((klass),GST_TYPE_BASE_SRC,GstBaseSrcClass))
34 #define GST_BASE_SRC_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), GST_TYPE_BASE_SRC, GstBaseSrcClass))
35 #define GST_IS_BASE_SRC(obj) (G_TYPE_CHECK_INSTANCE_TYPE((obj),GST_TYPE_BASE_SRC))
36 #define GST_IS_BASE_SRC_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass),GST_TYPE_BASE_SRC))
37 #define GST_BASE_SRC_CAST(obj) ((GstBaseSrc *)(obj))
41 * @GST_BASE_SRC_FLAG_STARTING: has source is starting
42 * @GST_BASE_SRC_FLAG_STARTED: has source been started
43 * @GST_BASE_SRC_FLAG_LAST: offset to define more flags
45 * The #GstElement flags that a basesrc element may have.
48 GST_BASE_SRC_FLAG_STARTING = (GST_ELEMENT_FLAG_LAST << 0),
49 GST_BASE_SRC_FLAG_STARTED = (GST_ELEMENT_FLAG_LAST << 1),
51 GST_BASE_SRC_FLAG_LAST = (GST_ELEMENT_FLAG_LAST << 6)
54 #define GST_BASE_SRC_IS_STARTING(obj) GST_OBJECT_FLAG_IS_SET ((obj), GST_BASE_SRC_FLAG_STARTING)
55 #define GST_BASE_SRC_IS_STARTED(obj) GST_OBJECT_FLAG_IS_SET ((obj), GST_BASE_SRC_FLAG_STARTED)
57 typedef struct _GstBaseSrc GstBaseSrc;
58 typedef struct _GstBaseSrcClass GstBaseSrcClass;
59 typedef struct _GstBaseSrcPrivate GstBaseSrcPrivate;
63 * @obj: base source instance
65 * Gives the pointer to the #GstPad object of the element.
67 #define GST_BASE_SRC_PAD(obj) (GST_BASE_SRC_CAST (obj)->srcpad)
73 * The opaque #GstBaseSrc data structure.
81 /* available to subclass implementations */
82 /* MT-protected (with LIVE_LOCK) */
86 gboolean live_running;
88 /* MT-protected (with LOCK) */
89 guint blocksize; /* size of buffers when operating push based */
90 gboolean can_activate_push; /* some scheduling properties */
91 gboolean random_access;
93 GstClockID clock_id; /* for syncing */
95 /* MT-protected (with STREAM_LOCK *and* OBJECT_LOCK) */
97 /* MT-protected (with STREAM_LOCK) */
98 gboolean need_newsegment;
101 gint num_buffers_left;
103 #ifndef GST_REMOVE_DEPRECATED
104 gboolean typefind; /* unused */
108 GstEvent *pending_seek;
110 GstBaseSrcPrivate *priv;
113 gpointer _gst_reserved[GST_PADDING_LARGE];
118 * @parent_class: Element parent class
119 * @get_caps: Called to get the caps to report
120 * @negotiate: Negotiated the caps with the peer.
121 * @fixate: Called during negotiation if caps need fixating. Implement instead of
122 * setting a fixate function on the source pad.
123 * @set_caps: Notify subclass of changed output caps
124 * @decide_allocation: configure the allocation query
125 * @start: Start processing. Subclasses should open resources and prepare
126 * to produce data. Implementation should call gst_base_src_start_complete()
127 * when the operation completes, either from the current thread or any other
128 * thread that finishes the start operation asynchronously.
129 * @stop: Stop processing. Subclasses should use this to close resources.
130 * @get_times: Given a buffer, return the start and stop time when it
131 * should be pushed out. The base class will sync on the clock using
133 * @get_size: Return the total size of the resource, in the format set by
134 * gst_base_src_set_format().
135 * @is_seekable: Check if the source can seek
136 * @prepare_seek_segment: Prepare the #GstSegment that will be passed to the
137 * #GstBaseSrcClass.do_seek() vmethod for executing a seek
138 * request. Sub-classes should override this if they support seeking in
139 * formats other than the configured native format. By default, it tries to
140 * convert the seek arguments to the configured native format and prepare a
141 * segment in that format.
142 * @do_seek: Perform seeking on the resource to the indicated segment.
143 * @unlock: Unlock any pending access to the resource. Subclasses should unblock
144 * any blocked function ASAP. In particular, any create() function in
145 * progress should be unblocked and should return GST_FLOW_FLUSHING. Any
146 * future #GstBaseSrcClass.create() function call should also return
147 * GST_FLOW_FLUSHING until the #GstBaseSrcClass.unlock_stop() function has
149 * @unlock_stop: Clear the previous unlock request. Subclasses should clear any
150 * state they set during #GstBaseSrcClass.unlock(), such as clearing command
152 * @query: Handle a requested query.
153 * @event: Override this to implement custom event handling.
154 * @create: Ask the subclass to create a buffer with offset and size. When the
155 * subclass returns GST_FLOW_OK, it MUST return a buffer of the requested size
156 * unless fewer bytes are available because an EOS condition is near. No
157 * buffer should be returned when the return value is different from
158 * GST_FLOW_OK. A return value of GST_FLOW_EOS signifies that the end of
159 * stream is reached. The default implementation will call
160 * #GstBaseSrcClass.alloc() and then call #GstBaseSrcClass.fill().
161 * @alloc: Ask the subclass to allocate a buffer with for offset and size. The
162 * default implementation will create a new buffer from the negotiated allocator.
163 * @fill: Ask the subclass to fill the buffer with data for offset and size. The
164 * passed buffer is guaranteed to hold the requested amount of bytes.
166 * Subclasses can override any of the available virtual methods or not, as
167 * needed. At the minimum, the @create method should be overridden to produce
170 struct _GstBaseSrcClass {
171 GstElementClass parent_class;
174 /* virtual methods for subclasses */
176 /* get caps from subclass */
177 GstCaps* (*get_caps) (GstBaseSrc *src, GstCaps *filter);
179 gboolean (*negotiate) (GstBaseSrc *src);
180 /* called if, in negotiation, caps need fixating */
181 GstCaps * (*fixate) (GstBaseSrc *src, GstCaps *caps);
182 /* notify the subclass of new caps */
183 gboolean (*set_caps) (GstBaseSrc *src, GstCaps *caps);
185 /* setup allocation query */
186 gboolean (*decide_allocation) (GstBaseSrc *src, GstQuery *query);
188 /* start and stop processing, ideal for opening/closing the resource */
189 gboolean (*start) (GstBaseSrc *src);
190 gboolean (*stop) (GstBaseSrc *src);
193 * GstBaseSrcClass::get_times:
197 * Given @buffer, return @start and @end time when it should be pushed
198 * out. The base class will sync on the clock using these times.
200 void (*get_times) (GstBaseSrc *src, GstBuffer *buffer,
201 GstClockTime *start, GstClockTime *end);
203 /* get the total size of the resource in the format set by
204 * gst_base_src_set_format() */
205 gboolean (*get_size) (GstBaseSrc *src, guint64 *size);
207 /* check if the resource is seekable */
208 gboolean (*is_seekable) (GstBaseSrc *src);
210 /* Prepare the segment on which to perform do_seek(), converting to the
211 * current basesrc format. */
212 gboolean (*prepare_seek_segment) (GstBaseSrc *src, GstEvent *seek,
213 GstSegment *segment);
214 /* notify subclasses of a seek */
215 gboolean (*do_seek) (GstBaseSrc *src, GstSegment *segment);
217 /* unlock any pending access to the resource. subclasses should unlock
218 * any function ASAP. */
219 gboolean (*unlock) (GstBaseSrc *src);
220 /* Clear any pending unlock request, as we succeeded in unlocking */
221 gboolean (*unlock_stop) (GstBaseSrc *src);
223 /* notify subclasses of a query */
224 gboolean (*query) (GstBaseSrc *src, GstQuery *query);
226 /* notify subclasses of an event */
227 gboolean (*event) (GstBaseSrc *src, GstEvent *event);
230 * GstBaseSrcClass::create:
233 * Ask the subclass to create a buffer with @offset and @size, the default
234 * implementation will call alloc and fill.
236 GstFlowReturn (*create) (GstBaseSrc *src, guint64 offset, guint size,
238 /* ask the subclass to allocate an output buffer. The default implementation
239 * will use the negotiated allocator. */
240 GstFlowReturn (*alloc) (GstBaseSrc *src, guint64 offset, guint size,
242 /* ask the subclass to fill the buffer with data from offset and size */
243 GstFlowReturn (*fill) (GstBaseSrc *src, guint64 offset, guint size,
247 gpointer _gst_reserved[GST_PADDING_LARGE];
251 GType gst_base_src_get_type (void);
254 GstFlowReturn gst_base_src_wait_playing (GstBaseSrc *src);
257 void gst_base_src_set_live (GstBaseSrc *src, gboolean live);
260 gboolean gst_base_src_is_live (GstBaseSrc *src);
263 void gst_base_src_set_format (GstBaseSrc *src, GstFormat format);
266 void gst_base_src_set_dynamic_size (GstBaseSrc * src, gboolean dynamic);
269 void gst_base_src_set_automatic_eos (GstBaseSrc * src, gboolean automatic_eos);
272 void gst_base_src_set_async (GstBaseSrc *src, gboolean async);
275 gboolean gst_base_src_is_async (GstBaseSrc *src);
278 void gst_base_src_start_complete (GstBaseSrc * basesrc, GstFlowReturn ret);
281 GstFlowReturn gst_base_src_start_wait (GstBaseSrc * basesrc);
284 gboolean gst_base_src_query_latency (GstBaseSrc *src, gboolean * live,
285 GstClockTime * min_latency,
286 GstClockTime * max_latency);
288 void gst_base_src_set_blocksize (GstBaseSrc *src, guint blocksize);
291 guint gst_base_src_get_blocksize (GstBaseSrc *src);
294 void gst_base_src_set_do_timestamp (GstBaseSrc *src, gboolean timestamp);
297 gboolean gst_base_src_get_do_timestamp (GstBaseSrc *src);
300 gboolean gst_base_src_new_seamless_segment (GstBaseSrc *src, gint64 start, gint64 stop, gint64 time);
303 gboolean gst_base_src_set_caps (GstBaseSrc *src, GstCaps *caps);
306 GstBufferPool * gst_base_src_get_buffer_pool (GstBaseSrc *src);
309 void gst_base_src_get_allocator (GstBaseSrc *src,
310 GstAllocator **allocator,
311 GstAllocationParams *params);
314 void gst_base_src_submit_buffer_list (GstBaseSrc * src,
315 GstBufferList * buffer_list);
317 #ifdef G_DEFINE_AUTOPTR_CLEANUP_FUNC
318 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstBaseSrc, gst_object_unref)
323 #endif /* __GST_BASE_SRC_H__ */