gstbasesrc.h 11 KB
Newer Older
1 2 3 4 5
/* GStreamer
 * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
 *                    2000 Wim Taymans <wtay@chello.be>
 *                    2005 Wim Taymans <wim@fluendo.com>
 *
6
 * gstbasesrc.h:
7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Library General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Library General Public License for more details.
 *
 * You should have received a copy of the GNU Library General Public
 * License along with this library; if not, write to the
 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 * Boston, MA 02111-1307, USA.
 */

Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
24 25
#ifndef __GST_BASE_SRC_H__
#define __GST_BASE_SRC_H__
26 27 28 29 30

#include <gst/gst.h>

G_BEGIN_DECLS

Wim Taymans's avatar
Wim Taymans committed
31 32 33
#define GST_TYPE_BASE_SRC               (gst_base_src_get_type())
#define GST_BASE_SRC(obj)               (G_TYPE_CHECK_INSTANCE_CAST((obj),GST_TYPE_BASE_SRC,GstBaseSrc))
#define GST_BASE_SRC_CLASS(klass)       (G_TYPE_CHECK_CLASS_CAST((klass),GST_TYPE_BASE_SRC,GstBaseSrcClass))
Andy Wingo Wingo's avatar
Andy Wingo Wingo committed
34
#define GST_BASE_SRC_GET_CLASS(obj)     (G_TYPE_INSTANCE_GET_CLASS ((obj), GST_TYPE_BASE_SRC, GstBaseSrcClass))
Wim Taymans's avatar
Wim Taymans committed
35 36 37
#define GST_IS_BASE_SRC(obj)            (G_TYPE_CHECK_INSTANCE_TYPE((obj),GST_TYPE_BASE_SRC))
#define GST_IS_BASE_SRC_CLASS(klass)    (G_TYPE_CHECK_CLASS_TYPE((klass),GST_TYPE_BASE_SRC))
#define GST_BASE_SRC_CAST(obj)          ((GstBaseSrc *)(obj))
38

39 40
/**
 * GstBaseSrcFlags:
Wim Taymans's avatar
Wim Taymans committed
41 42
 * @GST_BASE_SRC_FLAG_STARTING: has source is starting
 * @GST_BASE_SRC_FLAG_STARTED: has source been started
43 44 45 46
 * @GST_BASE_SRC_FLAG_LAST: offset to define more flags
 *
 * The #GstElement flags that a basesrc element may have.
 */
47
typedef enum {
Wim Taymans's avatar
Wim Taymans committed
48 49
  GST_BASE_SRC_FLAG_STARTING     = (GST_ELEMENT_FLAG_LAST << 0),
  GST_BASE_SRC_FLAG_STARTED      = (GST_ELEMENT_FLAG_LAST << 1),
50
  /* padding */
Wim Taymans's avatar
Wim Taymans committed
51
  GST_BASE_SRC_FLAG_LAST         = (GST_ELEMENT_FLAG_LAST << 16)
52
} GstBaseSrcFlags;
53

Wim Taymans's avatar
Wim Taymans committed
54 55 56
#define GST_BASE_SRC_IS_STARTING(obj) GST_OBJECT_FLAG_IS_SET ((obj), GST_BASE_SRC_FLAG_STARTING)
#define GST_BASE_SRC_IS_STARTED(obj)  GST_OBJECT_FLAG_IS_SET ((obj), GST_BASE_SRC_FLAG_STARTED)

57 58
typedef struct _GstBaseSrc GstBaseSrc;
typedef struct _GstBaseSrcClass GstBaseSrcClass;
59
typedef struct _GstBaseSrcPrivate GstBaseSrcPrivate;
60

61 62 63 64
/**
 * GST_BASE_SRC_PAD:
 * @obj: base source instance
 *
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
65
 * Gives the pointer to the #GstPad object of the element.
66
 */
67
#define GST_BASE_SRC_PAD(obj)                 (GST_BASE_SRC_CAST (obj)->srcpad)
68

69

Wim Taymans's avatar
Wim Taymans committed
70 71 72 73 74
/**
 * GstBaseSrc:
 *
 * The opaque #GstBaseSrc data structure.
 */
75 76
struct _GstBaseSrc {
  GstElement     element;
Wim Taymans's avatar
Wim Taymans committed
77 78

  /*< protected >*/
Wim Taymans's avatar
Wim Taymans committed
79
  GstPad        *srcpad;
80

81
  /* available to subclass implementations */
82
  /* MT-protected (with LIVE_LOCK) */
Wim Taymans's avatar
Wim Taymans committed
83 84
  GMutex         live_lock;
  GCond          live_cond;
Wim Taymans's avatar
Wim Taymans committed
85 86
  gboolean       is_live;
  gboolean       live_running;
87 88

  /* MT-protected (with LOCK) */
89
  guint          blocksize;     /* size of buffers when operating push based */
Wim Taymans's avatar
Wim Taymans committed
90
  gboolean       can_activate_push;     /* some scheduling properties */
Wim Taymans's avatar
Wim Taymans committed
91 92
  gboolean       random_access;

Wim Taymans's avatar
Wim Taymans committed
93
  GstClockID     clock_id;      /* for syncing */
94

95
  /* MT-protected (with STREAM_LOCK *and* OBJECT_LOCK) */
96
  GstSegment     segment;
97
  /* MT-protected (with STREAM_LOCK) */
Wim Taymans's avatar
Wim Taymans committed
98
  gboolean       need_newsegment;
99

100 101
  gint           num_buffers;
  gint           num_buffers_left;
102

Wim Taymans's avatar
Wim Taymans committed
103 104 105
  gboolean       typefind;
  gboolean       running;
  GstEvent      *pending_seek;
106 107

  GstBaseSrcPrivate *priv;
Wim Taymans's avatar
Wim Taymans committed
108 109 110

  /*< private >*/
  gpointer       _gst_reserved[GST_PADDING_LARGE];
111 112
};

113
/**
114
 * GstBaseSrcClass:
115 116 117
 * @parent_class: Element parent class
 * @get_caps: Called to get the caps to report
 * @negotiate: Negotiated the caps with the peer.
118 119
 * @fixate: Called during negotiation if caps need fixating. Implement instead of
 *   setting a fixate function on the source pad.
Wim Taymans's avatar
Wim Taymans committed
120
 * @set_caps: Notify subclass of changed output caps
Wim Taymans's avatar
Wim Taymans committed
121
 * @decide_allocation: configure the allocation query
122
 * @start: Start processing. Subclasses should open resources and prepare
Wim Taymans's avatar
Wim Taymans committed
123 124 125
 *    to produce data. Implementation should call gst_base_src_start_complete()
 *    when the operation completes, either from the current thread or any other
 *    thread that finishes the start operation asynchronously.
126
 * @stop: Stop processing. Subclasses should use this to close resources.
Wim Taymans's avatar
Wim Taymans committed
127 128 129
 * @get_times: Given a buffer, return the start and stop time when it
 *    should be pushed out. The base class will sync on the clock using
 *    these times.
130 131
 * @get_size: Return the total size of the resource, in the configured format.
 * @is_seekable: Check if the source can seek
132 133 134 135 136 137 138
 * @prepare_seek_segment: Prepare the GstSegment that will be passed to the
 *   do_seek vmethod for executing a seek request. Sub-classes should override
 *   this if they support seeking in formats other than the configured native
 *   format. By default, it tries to convert the seek arguments to the
 *   configured native format and prepare a segment in that format.
 *   Since: 0.10.13
 * @do_seek: Perform seeking on the resource to the indicated segment.
139
 * @unlock: Unlock any pending access to the resource. Subclasses should
140
 *    unblock any blocked function ASAP. In particular, any create() function in
141 142
 *    progress should be unblocked and should return GST_FLOW_FLUSHING. Any
 *    future @create<!-- -->() function call should also return GST_FLOW_FLUSHING
Stefan Kost's avatar
Stefan Kost committed
143
 *    until the @unlock_stop<!-- -->() function has been called.
144
 * @unlock_stop: Clear the previous unlock request. Subclasses should clear
Wim Taymans's avatar
Wim Taymans committed
145
 *    any state they set during unlock(), such as clearing command queues.
146
 * @query: Handle a requested query.
147 148
 * @event: Override this to implement custom event handling.
 * @create: Ask the subclass to create a buffer with offset and size.
149 150 151 152
 *   When the subclass returns GST_FLOW_OK, it MUST return a buffer of the
 *   requested size unless fewer bytes are available because an EOS condition
 *   is near. No buffer should be returned when the return value is different
 *   from GST_FLOW_OK. A return value of GST_FLOW_UNEXPECTED signifies that the
Wim Taymans's avatar
Wim Taymans committed
153 154 155 156
 *   end of stream is reached. The default implementation will call @alloc and
 *   then call @fill.
 * @alloc: Ask the subclass to allocate a buffer with for offset and size. The
 *   default implementation will create a new buffer from the negotiated allocator.
157 158
 * @fill: Ask the subclass to fill the buffer with data for offset and size. The
 *   passed buffer is guaranteed to hold the requested amount of bytes.
159 160 161 162
 *
 * Subclasses can override any of the available virtual methods or not, as
 * needed. At the minimum, the @create method should be overridden to produce
 * buffers.
163
 */
164 165 166
struct _GstBaseSrcClass {
  GstElementClass parent_class;

167
  /*< public >*/
168 169
  /* virtual methods for subclasses */

Wim Taymans's avatar
Wim Taymans committed
170
  /* get caps from subclass */
171
  GstCaps*      (*get_caps)     (GstBaseSrc *src, GstCaps *filter);
172 173
  /* decide on caps */
  gboolean      (*negotiate)    (GstBaseSrc *src);
Wim Taymans's avatar
Wim Taymans committed
174 175
  /* called if, in negotiation, caps need fixating */
  void          (*fixate)       (GstBaseSrc *src, GstCaps *caps);
Wim Taymans's avatar
Wim Taymans committed
176 177 178 179
  /* notify the subclass of new caps */
  gboolean      (*set_caps)     (GstBaseSrc *src, GstCaps *caps);

  /* setup allocation query */
Wim Taymans's avatar
Wim Taymans committed
180
  gboolean      (*decide_allocation)   (GstBaseSrc *src, GstQuery *query);
181

Wim Taymans's avatar
Wim Taymans committed
182
  /* start and stop processing, ideal for opening/closing the resource */
183 184 185
  gboolean      (*start)        (GstBaseSrc *src);
  gboolean      (*stop)         (GstBaseSrc *src);

Wim Taymans's avatar
Wim Taymans committed
186 187
  /* given a buffer, return start and stop time when it should be pushed
   * out. The base class will sync on the clock using these times. */
188 189 190
  void          (*get_times)    (GstBaseSrc *src, GstBuffer *buffer,
                                 GstClockTime *start, GstClockTime *end);

Wim Taymans's avatar
Wim Taymans committed
191
  /* get the total size of the resource in bytes */
192 193
  gboolean      (*get_size)     (GstBaseSrc *src, guint64 *size);

Wim Taymans's avatar
Wim Taymans committed
194
  /* check if the resource is seekable */
195
  gboolean      (*is_seekable)  (GstBaseSrc *src);
196

197 198
  /* Prepare the segment on which to perform do_seek(), converting to the
   * current basesrc format. */
Wim Taymans's avatar
Wim Taymans committed
199 200
  gboolean      (*prepare_seek_segment) (GstBaseSrc *src, GstEvent *seek,
                                         GstSegment *segment);
Wim Taymans's avatar
Wim Taymans committed
201 202 203 204 205 206 207 208 209 210
  /* notify subclasses of a seek */
  gboolean      (*do_seek)      (GstBaseSrc *src, GstSegment *segment);

  /* unlock any pending access to the resource. subclasses should unlock
   * any function ASAP. */
  gboolean      (*unlock)       (GstBaseSrc *src);
  /* Clear any pending unlock request, as we succeeded in unlocking */
  gboolean      (*unlock_stop)  (GstBaseSrc *src);

  /* notify subclasses of a query */
211
  gboolean      (*query)        (GstBaseSrc *src, GstQuery *query);
Wim Taymans's avatar
Wim Taymans committed
212 213 214 215

  /* notify subclasses of an event */
  gboolean      (*event)        (GstBaseSrc *src, GstEvent *event);

216
  /* ask the subclass to create a buffer with offset and size, the default
Wim Taymans's avatar
Wim Taymans committed
217
   * implementation will call alloc and fill. */
Wim Taymans's avatar
Wim Taymans committed
218 219
  GstFlowReturn (*create)       (GstBaseSrc *src, guint64 offset, guint size,
                                 GstBuffer **buf);
Wim Taymans's avatar
Wim Taymans committed
220 221 222 223
  /* ask the subclass to allocate an output buffer. The default implementation
   * will use the negotiated allocator. */
  GstFlowReturn (*alloc)        (GstBaseSrc *src, guint64 offset, guint size,
                                 GstBuffer **buf);
224 225 226
  /* ask the subclass to fill the buffer with data from offset and size */
  GstFlowReturn (*fill)         (GstBaseSrc *src, guint64 offset, guint size,
                                 GstBuffer *buf);
227

228
  /*< private >*/
Wim Taymans's avatar
Wim Taymans committed
229
  gpointer       _gst_reserved[GST_PADDING_LARGE];
230 231
};

232
GType gst_base_src_get_type (void);
233

Wim Taymans's avatar
Wim Taymans committed
234
GstFlowReturn   gst_base_src_wait_playing     (GstBaseSrc *src);
235

Wim Taymans's avatar
Wim Taymans committed
236 237
void            gst_base_src_set_live         (GstBaseSrc *src, gboolean live);
gboolean        gst_base_src_is_live          (GstBaseSrc *src);
238

Wim Taymans's avatar
Wim Taymans committed
239
void            gst_base_src_set_format       (GstBaseSrc *src, GstFormat format);
240

241 242
void            gst_base_src_set_dynamic_size (GstBaseSrc * src, gboolean dynamic);

Wim Taymans's avatar
Wim Taymans committed
243 244 245 246 247 248
void            gst_base_src_set_async        (GstBaseSrc *src, gboolean async);
gboolean        gst_base_src_is_async         (GstBaseSrc *src);

void            gst_base_src_start_complete   (GstBaseSrc * basesrc, GstFlowReturn ret);
GstFlowReturn   gst_base_src_start_wait       (GstBaseSrc * basesrc);

Wim Taymans's avatar
Wim Taymans committed
249 250 251
gboolean        gst_base_src_query_latency    (GstBaseSrc *src, gboolean * live,
                                               GstClockTime * min_latency,
                                               GstClockTime * max_latency);
252

253 254
void            gst_base_src_set_blocksize    (GstBaseSrc *src, guint blocksize);
guint           gst_base_src_get_blocksize    (GstBaseSrc *src);
255

Wim Taymans's avatar
Wim Taymans committed
256 257
void            gst_base_src_set_do_timestamp (GstBaseSrc *src, gboolean timestamp);
gboolean        gst_base_src_get_do_timestamp (GstBaseSrc *src);
258

259
gboolean        gst_base_src_new_seamless_segment (GstBaseSrc *src, gint64 start, gint64 stop, gint64 position);
Wim Taymans's avatar
Wim Taymans committed
260 261 262

gboolean        gst_base_src_set_caps         (GstBaseSrc *src, GstCaps *caps);

263 264
G_END_DECLS

Andy Wingo Wingo's avatar
Andy Wingo Wingo committed
265
#endif /* __GST_BASE_SRC_H__ */