libs/gst/base/gstbasesrc.h

   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., 59 Temple Place - Suite 330,
  21  * Boston, MA 02111-1307, USA.
  22  */
  23
  24 #ifndef __GST_BASE_SRC_H__
  25 #define __GST_BASE_SRC_H__
  26
  27 #include <gst/gst.h>
  28
  29 G_BEGIN_DECLS
  30
  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))
  38
  39 /**
  40  * GstBaseSrcFlags:
  41  * @GST_BASE_SRC_STARTED: has source been started
  42  * @GST_BASE_SRC_FLAG_LAST: offset to define more flags
  43  *
  44  * The #GstElement flags that a basesrc element may have.
  45  */
  46 typedef enum {
  47   GST_BASE_SRC_STARTED           = (GST_ELEMENT_FLAG_LAST << 0),
  48   /* padding */
  49   GST_BASE_SRC_FLAG_LAST         = (GST_ELEMENT_FLAG_LAST << 2)
  50 } GstBaseSrcFlags;
  51
  52 typedef struct _GstBaseSrc GstBaseSrc;
  53 typedef struct _GstBaseSrcClass GstBaseSrcClass;
  54 typedef struct _GstBaseSrcPrivate GstBaseSrcPrivate;
  55
  56 /**
  57  * GST_BASE_SRC_PAD:
  58  * @obj: base source instance
  59  *
  60  * Gives the pointer to the #GstPad object of the element.
  61  */
  62 #define GST_BASE_SRC_PAD(obj)                 (GST_BASE_SRC_CAST (obj)->srcpad)
  63
  64
  65 /**
  66  * GstBaseSrc:
  67  *
  68  * The opaque #GstBaseSrc data structure.
  69  */
  70 struct _GstBaseSrc {
  71   GstElement     element;
  72
  73   /*< protected >*/
  74   GstPad        *srcpad;
  75
  76   /* available to subclass implementations */
  77   /* MT-protected (with LIVE_LOCK) */
  78   GMutex        *live_lock;
  79   GCond         *live_cond;
  80   gboolean       is_live;
  81   gboolean       live_running;
  82
  83   /* MT-protected (with LOCK) */
  84   gint           blocksize;     /* size of buffers when operating push based */
  85   gboolean       can_activate_push;     /* some scheduling properties */
  86   GstActivateMode pad_mode;
  87   gboolean       seekable; /* not used anymore */
  88   gboolean       random_access;
  89
  90   GstClockID     clock_id;      /* for syncing */
  91   GstClockTime   end_time;
  92
  93   /* MT-protected (with STREAM_LOCK *and* OBJECT_LOCK) */
  94   GstSegment     segment;
  95   /* MT-protected (with STREAM_LOCK) */
  96   gboolean       need_newsegment;
  97
  98   guint64        offset;        /* current offset in the resource, unused */
  99   guint64        size;          /* total size of the resource, unused */
 100
 101   gint           num_buffers;
 102   gint           num_buffers_left;
 103
 104   /*< private >*/
 105   union {
 106     struct {
 107       /* FIXME: those fields should be moved into the private struct */
 108       gboolean  typefind;
 109       gboolean  running;
 110       GstEvent *pending_seek;
 111     } ABI;
 112     gpointer       _gst_reserved[GST_PADDING_LARGE-1];
 113   } data;
 114
 115   GstBaseSrcPrivate *priv;
 116 };
 117
 118 /**
 119  * GstBaseSrcClass:
 120  * @parent_class: Element parent class
 121  * @get_caps: Called to get the caps to report
 122  * @set_caps: Notify subclass of changed output caps
 123  * @negotiate: Negotiated the caps with the peer.
 124  * @newsegment: Generate and send a new_segment event (UNUSED)
 125  * @start: Start processing. Subclasses should open resources and prepare
 126  *    to produce data.
 127  * @stop: Stop processing. Subclasses should use this to close resources.
 128  * @get_times: Given a buffer, return the start and stop time when it
 129  *    should be pushed out. The base class will sync on the clock using
 130  *    these times.
 131  * @get_size: Return the total size of the resource, in the configured format.
 132  * @is_seekable: Check if the source can seek
 133  * @unlock: Unlock any pending access to the resource. Subclasses should
 134  *    unblock any blocked function ASAP. In particular, any create() function in
 135  *    progress should be unblocked and should return GST_FLOW_WRONG_STATE. Any
 136  *    future @create<!-- -->() function call should also return GST_FLOW_WRONG_STATE
 137  *    until the @unlock_stop<!-- -->() function has been called.
 138  * @unlock_stop: Clear the previous unlock request. Subclasses should clear
 139  *    any state they set during unlock(), such as clearing command queues.
 140  * @event: Override this to implement custom event handling.
 141  * @create: Ask the subclass to create a buffer with offset and size.
 142  *   When the subclass returns GST_FLOW_OK, it MUST return a buffer of the
 143  *   requested size unless fewer bytes are available because an EOS condition
 144  *   is near. No buffer should be returned when the return value is different
 145  *   from GST_FLOW_OK. A return value of GST_FLOW_UNEXPECTED signifies that the
 146  *   end of stream is reached.
 147  * @do_seek: Perform seeking on the resource to the indicated segment.
 148  * @prepare_seek_segment: Prepare the GstSegment that will be passed to the
 149  *   do_seek vmethod for executing a seek request. Sub-classes should override
 150  *   this if they support seeking in formats other than the configured native
 151  *   format. By default, it tries to convert the seek arguments to the
 152  *   configured native format and prepare a segment in that format.
 153  *   Since: 0.10.13
 154  * @query: Handle a requested query.
 155  * @check_get_range: Check whether the source would support pull-based
 156  *   operation if it were to be opened now. This vfunc is optional, but
 157  *   should be implemented if possible to avoid unnecessary start/stop
 158  *   cycles. The default implementation will open and close the resource
 159  *   to find out whether get_range is supported, and that is usually
 160  *   undesirable.
 161  * @fixate: Called during negotiation if caps need fixating. Implement instead of
 162  *   setting a fixate function on the source pad.
 163  *
 164  * Subclasses can override any of the available virtual methods or not, as
 165  * needed. At the minimum, the @create method should be overridden to produce
 166  * buffers.
 167  */
 168 struct _GstBaseSrcClass {
 169   GstElementClass parent_class;
 170
 171   /*< public >*/
 172   /* virtual methods for subclasses */
 173
 174   /* get caps from subclass */
 175   GstCaps*      (*get_caps)     (GstBaseSrc *src);
 176   /* notify the subclass of new caps */
 177   gboolean      (*set_caps)     (GstBaseSrc *src, GstCaps *caps);
 178
 179   /* decide on caps */
 180   gboolean      (*negotiate)    (GstBaseSrc *src);
 181
 182   /* generate and send a newsegment (UNUSED) */
 183   gboolean      (*newsegment)   (GstBaseSrc *src);
 184
 185   /* start and stop processing, ideal for opening/closing the resource */
 186   gboolean      (*start)        (GstBaseSrc *src);
 187   gboolean      (*stop)         (GstBaseSrc *src);
 188
 189   /* given a buffer, return start and stop time when it should be pushed
 190    * out. The base class will sync on the clock using these times. */
 191   void          (*get_times)    (GstBaseSrc *src, GstBuffer *buffer,
 192                                  GstClockTime *start, GstClockTime *end);
 193
 194   /* get the total size of the resource in bytes */
 195   gboolean      (*get_size)     (GstBaseSrc *src, guint64 *size);
 196
 197   /* check if the resource is seekable */
 198   gboolean      (*is_seekable)  (GstBaseSrc *src);
 199   /* unlock any pending access to the resource. subclasses should unlock
 200    * any function ASAP. */
 201   gboolean      (*unlock)       (GstBaseSrc *src);
 202
 203   /* notify subclasses of an event */
 204   gboolean      (*event)        (GstBaseSrc *src, GstEvent *event);
 205
 206   /* ask the subclass to create a buffer with offset and size */
 207   GstFlowReturn (*create)       (GstBaseSrc *src, guint64 offset, guint size,
 208                                  GstBuffer **buf);
 209
 210   /* additions that change padding... */
 211   /* notify subclasses of a seek */
 212   gboolean      (*do_seek)      (GstBaseSrc *src, GstSegment *segment);
 213   /* notify subclasses of a query */
 214   gboolean      (*query)        (GstBaseSrc *src, GstQuery *query);
 215
 216   /* check whether the source would support pull-based operation if
 217    * it were to be opened now. This vfunc is optional, but should be
 218    * implemented if possible to avoid unnecessary start/stop cycles.
 219    * The default implementation will open and close the resource to
 220    * find out whether get_range is supported and that is usually
 221    * undesirable. */
 222   gboolean      (*check_get_range) (GstBaseSrc *src);
 223
 224   /* called if, in negotiation, caps need fixating */
 225   void          (*fixate)       (GstBaseSrc *src, GstCaps *caps);
 226
 227   /* Clear any pending unlock request, as we succeeded in unlocking */
 228   gboolean      (*unlock_stop)  (GstBaseSrc *src);
 229
 230   /* Prepare the segment on which to perform do_seek(), converting to the
 231    * current basesrc format. */
 232   gboolean      (*prepare_seek_segment) (GstBaseSrc *src, GstEvent *seek,
 233                                          GstSegment *segment);
 234
 235   /*< private >*/
 236   gpointer       _gst_reserved[GST_PADDING_LARGE - 6];
 237 };
 238
 239 GType gst_base_src_get_type (void);
 240
 241 GstFlowReturn   gst_base_src_wait_playing     (GstBaseSrc *src);
 242
 243 void            gst_base_src_set_live         (GstBaseSrc *src, gboolean live);
 244 gboolean        gst_base_src_is_live          (GstBaseSrc *src);
 245
 246 void            gst_base_src_set_format       (GstBaseSrc *src, GstFormat format);
 247
 248 gboolean        gst_base_src_query_latency    (GstBaseSrc *src, gboolean * live,
 249                                                GstClockTime * min_latency,
 250                                                GstClockTime * max_latency);
 251
 252 void            gst_base_src_set_blocksize    (GstBaseSrc *src, gulong blocksize);
 253 gulong          gst_base_src_get_blocksize    (GstBaseSrc *src);
 254
 255 void            gst_base_src_set_do_timestamp (GstBaseSrc *src, gboolean timestamp);
 256 gboolean        gst_base_src_get_do_timestamp (GstBaseSrc *src);
 257
 258 gboolean        gst_base_src_new_seamless_segment (GstBaseSrc *src, gint64 start, gint64 stop, gint64 position);
 259 G_END_DECLS
 260
 261 #endif /* __GST_BASE_SRC_H__ */