subprojects/gstreamer/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., 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 #ifdef TIZEN_FEATURE_TRUSTZONE
 275   /*tzappsrc patch*/
 276   int (*tz_flush) (GstBaseSrc *src, unsigned int handle);
 277   int (*tz_src_flush) (GstBaseSrc *src);
 278   int (*tz_src_release_handle) (GstBaseSrc *src, GstBuffer *buf);
 279 #endif
 280 };
 281
 282 GST_BASE_API
 283 GType           gst_base_src_get_type (void);
 284
 285 GST_BASE_API
 286 GstFlowReturn   gst_base_src_wait_playing     (GstBaseSrc *src);
 287
 288 GST_BASE_API
 289 void            gst_base_src_set_live         (GstBaseSrc *src, gboolean live);
 290
 291 GST_BASE_API
 292 gboolean        gst_base_src_is_live          (GstBaseSrc *src);
 293
 294 GST_BASE_API
 295 void            gst_base_src_set_format       (GstBaseSrc *src, GstFormat format);
 296
 297 GST_BASE_API
 298 void            gst_base_src_set_dynamic_size (GstBaseSrc * src, gboolean dynamic);
 299
 300 GST_BASE_API
 301 void            gst_base_src_set_automatic_eos (GstBaseSrc * src, gboolean automatic_eos);
 302
 303 GST_BASE_API
 304 void            gst_base_src_set_async        (GstBaseSrc *src, gboolean async);
 305
 306 GST_BASE_API
 307 gboolean        gst_base_src_is_async         (GstBaseSrc *src);
 308
 309 GST_BASE_API
 310 gboolean        gst_base_src_negotiate        (GstBaseSrc *src);
 311
 312 GST_BASE_API
 313 void            gst_base_src_start_complete   (GstBaseSrc * basesrc, GstFlowReturn ret);
 314
 315 GST_BASE_API
 316 GstFlowReturn   gst_base_src_start_wait       (GstBaseSrc * basesrc);
 317
 318 GST_BASE_API
 319 gboolean        gst_base_src_query_latency    (GstBaseSrc *src, gboolean * live,
 320                                                GstClockTime * min_latency,
 321                                                GstClockTime * max_latency);
 322 GST_BASE_API
 323 void            gst_base_src_set_blocksize    (GstBaseSrc *src, guint blocksize);
 324
 325 GST_BASE_API
 326 guint           gst_base_src_get_blocksize    (GstBaseSrc *src);
 327
 328 GST_BASE_API
 329 void            gst_base_src_set_do_timestamp (GstBaseSrc *src, gboolean timestamp);
 330
 331 GST_BASE_API
 332 gboolean        gst_base_src_get_do_timestamp (GstBaseSrc *src);
 333
 334 GST_BASE_API
 335 gboolean        gst_base_src_new_seamless_segment (GstBaseSrc *src, gint64 start, gint64 stop, gint64 time);
 336
 337 GST_BASE_API
 338 gboolean        gst_base_src_new_segment      (GstBaseSrc *src,
 339                                                const GstSegment * segment);
 340
 341 GST_BASE_API
 342 gboolean        gst_base_src_set_caps         (GstBaseSrc *src, GstCaps *caps);
 343
 344 GST_BASE_API
 345 GstBufferPool * gst_base_src_get_buffer_pool  (GstBaseSrc *src);
 346
 347 GST_BASE_API
 348 void            gst_base_src_get_allocator    (GstBaseSrc *src,
 349                                                GstAllocator **allocator,
 350                                                GstAllocationParams *params);
 351
 352 GST_BASE_API
 353 void            gst_base_src_submit_buffer_list (GstBaseSrc    * src,
 354                                                  GstBufferList * buffer_list);
 355
 356 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstBaseSrc, gst_object_unref)
 357
 358 #ifdef TIZEN_PROFILE_TV
 359 GST_BASE_API
 360 void            gst_base_src_update_segment   (GstBaseSrc * src, gint64 timestamp);
 361 #endif
 362
 363 G_END_DECLS
 364
 365 #endif /* __GST_BASE_SRC_H__ */