1 /* GStreamer 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> 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 GstCaps * (*fixate) (GstBaseSrc *src, GstCaps *caps); 188 /* notify the subclass of new caps */ 189 gboolean (*set_caps) (GstBaseSrc *src, GstCaps *caps); 190 191 /* setup allocation query */ 192 gboolean (*decide_allocation) (GstBaseSrc *src, GstQuery *query); 193 194 /* start and stop processing, ideal for opening/closing the resource */ 195 gboolean (*start) (GstBaseSrc *src); 196 gboolean (*stop) (GstBaseSrc *src); 197 198 /** 199 * GstBaseSrcClass::get_times: 200 * @start: (out): 201 * @end: (out): 202 * 203 * Given @buffer, return @start and @end time when it should be pushed 204 * out. The base class will sync on the clock using these times. 205 */ 206 void (*get_times) (GstBaseSrc *src, GstBuffer *buffer, 207 GstClockTime *start, GstClockTime *end); 208 209 /** 210 * GstBaseSrcClass::get_size: 211 * @size: (out): 212 * 213 * Get the total size of the resource in the format set by 214 * gst_base_src_set_format(). 215 * 216 * Returns: %TRUE if the size is available and has been set. 217 */ 218 gboolean (*get_size) (GstBaseSrc *src, guint64 *size); 219 220 /* check if the resource is seekable */ 221 gboolean (*is_seekable) (GstBaseSrc *src); 222 223 /* Prepare the segment on which to perform do_seek(), converting to the 224 * current basesrc format. */ 225 gboolean (*prepare_seek_segment) (GstBaseSrc *src, GstEvent *seek, 226 GstSegment *segment); 227 /* notify subclasses of a seek */ 228 gboolean (*do_seek) (GstBaseSrc *src, GstSegment *segment); 229 230 /* unlock any pending access to the resource. subclasses should unlock 231 * any function ASAP. */ 232 gboolean (*unlock) (GstBaseSrc *src); 233 /* Clear any pending unlock request, as we succeeded in unlocking */ 234 gboolean (*unlock_stop) (GstBaseSrc *src); 235 236 /* notify subclasses of a query */ 237 gboolean (*query) (GstBaseSrc *src, GstQuery *query); 238 239 /* notify subclasses of an event */ 240 gboolean (*event) (GstBaseSrc *src, GstEvent *event); 241 242 /** 243 * GstBaseSrcClass::create: 244 * @buf: (inout): 245 * 246 * Ask the subclass to create a buffer with @offset and @size, the default 247 * implementation will call alloc if no allocated @buf is provided and then call fill. 248 */ 249 GstFlowReturn (*create) (GstBaseSrc *src, guint64 offset, guint size, 250 GstBuffer **buf); 251 /** 252 * GstBaseSrcClass::alloc: 253 * @buf: (out): 254 * 255 * Ask the subclass to allocate an output buffer with @offset and @size, the default 256 * implementation will use the negotiated allocator. 257 */ 258 GstFlowReturn (*alloc) (GstBaseSrc *src, guint64 offset, guint size, 259 GstBuffer **buf); 260 /* ask the subclass to fill the buffer with data from offset and size */ 261 GstFlowReturn (*fill) (GstBaseSrc *src, guint64 offset, guint size, 262 GstBuffer *buf); 263 264 /*< private >*/ 265 gpointer _gst_reserved[GST_PADDING_LARGE]; 266 }; 267 268 GST_BASE_API 269 GType gst_base_src_get_type (void); 270 271 GST_BASE_API 272 GstFlowReturn gst_base_src_wait_playing (GstBaseSrc *src); 273 274 GST_BASE_API 275 void gst_base_src_set_live (GstBaseSrc *src, gboolean live); 276 277 GST_BASE_API 278 gboolean gst_base_src_is_live (GstBaseSrc *src); 279 280 GST_BASE_API 281 void gst_base_src_set_format (GstBaseSrc *src, GstFormat format); 282 283 GST_BASE_API 284 void gst_base_src_set_dynamic_size (GstBaseSrc * src, gboolean dynamic); 285 286 GST_BASE_API 287 void gst_base_src_set_automatic_eos (GstBaseSrc * src, gboolean automatic_eos); 288 289 GST_BASE_API 290 void gst_base_src_set_async (GstBaseSrc *src, gboolean async); 291 292 GST_BASE_API 293 gboolean gst_base_src_is_async (GstBaseSrc *src); 294 295 GST_BASE_API 296 gboolean gst_base_src_negotiate (GstBaseSrc *src); 297 298 GST_BASE_API 299 void gst_base_src_start_complete (GstBaseSrc * basesrc, GstFlowReturn ret); 300 301 GST_BASE_API 302 GstFlowReturn gst_base_src_start_wait (GstBaseSrc * basesrc); 303 304 GST_BASE_API 305 gboolean gst_base_src_query_latency (GstBaseSrc *src, gboolean * live, 306 GstClockTime * min_latency, 307 GstClockTime * max_latency); 308 GST_BASE_API 309 void gst_base_src_set_blocksize (GstBaseSrc *src, guint blocksize); 310 311 GST_BASE_API 312 guint gst_base_src_get_blocksize (GstBaseSrc *src); 313 314 GST_BASE_API 315 void gst_base_src_set_do_timestamp (GstBaseSrc *src, gboolean timestamp); 316 317 GST_BASE_API 318 gboolean gst_base_src_get_do_timestamp (GstBaseSrc *src); 319 320 GST_BASE_API 321 gboolean gst_base_src_new_seamless_segment (GstBaseSrc *src, gint64 start, gint64 stop, gint64 time); 322 323 GST_BASE_API 324 gboolean gst_base_src_new_segment (GstBaseSrc *src, 325 const GstSegment * segment); 326 327 GST_BASE_API 328 gboolean gst_base_src_set_caps (GstBaseSrc *src, GstCaps *caps); 329 330 GST_BASE_API 331 GstBufferPool * gst_base_src_get_buffer_pool (GstBaseSrc *src); 332 333 GST_BASE_API 334 void gst_base_src_get_allocator (GstBaseSrc *src, 335 GstAllocator **allocator, 336 GstAllocationParams *params); 337 338 GST_BASE_API 339 void gst_base_src_submit_buffer_list (GstBaseSrc * src, 340 GstBufferList * buffer_list); 341 342 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstBaseSrc, gst_object_unref) 343 344 G_END_DECLS 345 346 #endif /* __GST_BASE_SRC_H__ */ 347