baseparse: add getcaps function
[platform/upstream/gstreamer.git] / libs / gst / base / gstbaseparse.h
1 /* GStreamer
2  * Copyright (C) 2008 Nokia Corporation. All rights reserved.
3  *
4  * Contact: Stefan Kost <stefan.kost@nokia.com>
5  *
6  * This library is free software; you can redistribute it and/or
7  * modify it under the terms of the GNU Library General Public
8  * License as published by the Free Software Foundation; either
9  * version 2 of the License, or (at your option) any later version.
10  *
11  * This library is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
14  * Library General Public License for more details.
15  *
16  * You should have received a copy of the GNU Library General Public
17  * License along with this library; if not, write to the
18  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
19  * Boston, MA 02111-1307, USA.
20  */
21
22 #ifndef __GST_BASE_PARSE_H__
23 #define __GST_BASE_PARSE_H__
24
25 #include <gst/gst.h>
26
27 G_BEGIN_DECLS
28
29 #define GST_TYPE_BASE_PARSE            (gst_base_parse_get_type())
30 #define GST_BASE_PARSE(obj)            (G_TYPE_CHECK_INSTANCE_CAST((obj),GST_TYPE_BASE_PARSE,GstBaseParse))
31 #define GST_BASE_PARSE_CLASS(klass)    (G_TYPE_CHECK_CLASS_CAST((klass),GST_TYPE_BASE_PARSE,GstBaseParseClass))
32 #define GST_BASE_PARSE_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS((obj),GST_TYPE_BASE_PARSE,GstBaseParseClass))
33 #define GST_IS_BASE_PARSE(obj)         (G_TYPE_CHECK_INSTANCE_TYPE((obj),GST_TYPE_BASE_PARSE))
34 #define GST_IS_BASE_PARSE_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass),GST_TYPE_BASE_PARSE))
35 #define GST_BASE_PARSE_CAST(obj)       ((GstBaseParse *)(obj))
36
37 /**
38  * GST_BASE_PARSE_SRC_PAD:
39  * @obj: base parse instance
40  *
41  * Gives the pointer to the source #GstPad object of the element.
42  *
43  * Since: 0.10.33
44  */
45 #define GST_BASE_PARSE_SRC_PAD(obj)    (GST_BASE_PARSE_CAST (obj)->srcpad)
46
47 /**
48  * GST_BASE_PARSE_SINK_PAD:
49  * @obj: base parse instance
50  *
51  * Gives the pointer to the sink #GstPad object of the element.
52  *
53  * Since: 0.10.33
54  */
55 #define GST_BASE_PARSE_SINK_PAD(obj)    (GST_BASE_PARSE_CAST (obj)->sinkpad)
56
57 /**
58  * GST_BASE_PARSE_FLOW_DROPPED:
59  *
60  * A #GstFlowReturn that can be returned from parse_frame to
61  * indicate that no output buffer was generated, or from pre_push_buffer to
62  * to forego pushing buffer.
63  *
64  * Since: 0.10.33
65  */
66 #define GST_BASE_PARSE_FLOW_DROPPED     GST_FLOW_CUSTOM_SUCCESS
67
68 /**
69  * GST_BASE_PARSE_FLOW_QUEUED:
70  *
71  * A #GstFlowReturn that can be returned from parse frame to indicate that
72  * the buffer will be queued to be pushed when the next OK
73  *
74  * Since: 0.10.33
75  */
76 #define GST_BASE_PARSE_FLOW_QUEUED      GST_FLOW_CUSTOM_SUCCESS_1
77
78 /* not public API, use accessor macros below */
79 #define GST_BASE_PARSE_FLAG_LOST_SYNC (1 << 0)
80 #define GST_BASE_PARSE_FLAG_DRAINING  (1 << 1)
81
82 /**
83  * GST_BASE_PARSE_LOST_SYNC:
84  * @parse: base parse instance
85  *
86  * Obtains current sync status.
87  *
88  * Since: 0.10.33
89  */
90 #define GST_BASE_PARSE_LOST_SYNC(parse) (!!(GST_BASE_PARSE_CAST(parse)->flags & GST_BASE_PARSE_FLAG_LOST_SYNC))
91
92 /**
93  * GST_BASE_PARSE_DRAINING:
94  * @parse: base parse instance
95  *
96  * Obtains current drain status (ie. whether EOS has been received and
97  * the parser is now processing the frames at the end of the stream)
98  *
99  * Since: 0.10.33
100  */
101 #define GST_BASE_PARSE_DRAINING(parse)  (!!(GST_BASE_PARSE_CAST(parse)->flags & GST_BASE_PARSE_FLAG_DRAINING))
102
103 /**
104  * GstBaseParseFrameFlags:
105  * @GST_BASE_PARSE_FRAME_FLAG_NONE: no flag
106  * @GST_BASE_PARSE_FRAME_FLAG_NO_FRAME: set to indicate this buffer should not be
107  *   counted as frame, e.g. if this frame is dependent on a previous one.
108  *   As it is not counted as a frame, bitrate increases but frame to time
109  *   conversions are maintained.
110  * @GST_BASE_PARSE_FRAME_FLAG_CLIP: @pre_push_buffer can set this to indicate
111  *    that regular segment clipping can still be performed (as opposed to
112  *    any custom one having been done).
113  *
114  * Flags to be used in a #GstBaseParseFrame.
115  *
116  * Since: 0.10.33
117  */
118 typedef enum {
119   GST_BASE_PARSE_FRAME_FLAG_NONE         = 0,
120   GST_BASE_PARSE_FRAME_FLAG_NO_FRAME     = (1 << 0),
121   GST_BASE_PARSE_FRAME_FLAG_CLIP         = (1 << 1)
122 } GstBaseParseFrameFlags;
123
124 /**
125  * GstBaseParseFrame:
126  * @buffer: data to check for valid frame or parsed frame.
127  *   Subclass is allowed to replace this buffer.
128  * @overhead: subclass can set this to indicates the metadata overhead
129  *   for the given frame, which is then used to enable more accurate bitrate
130  *   computations. If this is -1, it is assumed that this frame should be
131  *   skipped in bitrate calculation.
132  * @flags: a combination of input and output #GstBaseParseFrameFlags that
133  *  convey additional context to subclass or allow subclass to tune
134  *  subsequent #GstBaseParse actions.
135  *
136  * Frame (context) data passed to each frame parsing virtual methods.  In
137  * addition to providing the data to be checked for a valid frame or an already
138  * identified frame, it conveys additional metadata or control information
139  * from and to the subclass w.r.t. the particular frame in question (rather
140  * than global parameters).  Some of these may apply to each parsing stage, others
141  * only to some a particular one.  These parameters are effectively zeroed at start
142  * of each frame's processing, i.e. parsing virtual method invocation sequence.
143  *
144  * Since: 0.10.33
145  */
146 typedef struct {
147   GstBuffer * buffer;
148   guint       flags;
149   gint        overhead;
150   /*< private >*/
151   guint       _gst_reserved_i[2];
152   gpointer    _gst_reserved_p[2];
153   guint       _private_flags;
154 } GstBaseParseFrame;
155
156 typedef struct _GstBaseParse GstBaseParse;
157 typedef struct _GstBaseParseClass GstBaseParseClass;
158 typedef struct _GstBaseParsePrivate GstBaseParsePrivate;
159
160 /**
161  * GstBaseParse:
162  * @element: the parent element.
163  *
164  * The opaque #GstBaseParse data structure.
165  */
166 struct _GstBaseParse {
167   GstElement     element;
168
169   /*< protected >*/
170   /* source and sink pads */
171   GstPad         *sinkpad;
172   GstPad         *srcpad;
173
174   guint           flags;
175
176   /* MT-protected (with STREAM_LOCK) */
177   GstSegment      segment;
178
179   /*< private >*/
180   gpointer       _gst_reserved[GST_PADDING_LARGE];
181   GstBaseParsePrivate *priv;
182 };
183
184 /**
185  * GstBaseParseClass:
186  * @parent_class: the parent class
187  * @start:          Optional.
188  *                  Called when the element starts processing.
189  *                  Allows opening external resources.
190  * @stop:           Optional.
191  *                  Called when the element stops processing.
192  *                  Allows closing external resources.
193  * @set_sink_caps:  allows the subclass to be notified of the actual caps set.
194  * @get_sink_caps:  allows the subclass to do its own sink get caps if needed.
195  * @check_valid_frame:  Check if the given piece of data contains a valid
196  *                      frame.
197  * @parse_frame:    Parse the already checked frame. Subclass need to
198  *                  set the buffer timestamp, duration, caps and possibly
199  *                  other necessary metadata. This is called with srcpad's
200  *                  STREAM_LOCK held.
201  * @convert:        Optional.
202  *                  Convert between formats.
203  * @event:          Optional.
204  *                  Event handler on the sink pad. This function should return
205  *                  TRUE if the event was handled and can be dropped.
206  * @src_event:      Optional.
207  *                  Event handler on the source pad. Should return TRUE
208  *                  if the event was handled and can be dropped.
209  * @pre_push_frame: Optional.
210  *                   Called just prior to pushing a frame (after any pending
211  *                   events have been sent) to give subclass a chance to perform
212  *                   additional actions at this time (e.g. tag sending) or to
213  *                   decide whether this buffer should be dropped or not
214  *                   (e.g. custom segment clipping).
215  *
216  * Subclasses can override any of the available virtual methods or not, as
217  * needed. At minimum @check_valid_frame and @parse_frame needs to be
218  * overridden.
219  */
220 struct _GstBaseParseClass {
221   GstElementClass parent_class;
222
223   /*< public >*/
224   /* virtual methods for subclasses */
225
226   gboolean      (*start)              (GstBaseParse * parse);
227
228   gboolean      (*stop)               (GstBaseParse * parse);
229
230   gboolean      (*set_sink_caps)      (GstBaseParse * parse,
231                                        GstCaps      * caps);
232
233   gboolean      (*check_valid_frame)  (GstBaseParse      * parse,
234                                        GstBaseParseFrame * frame,
235                                        guint             * framesize,
236                                        gint              * skipsize);
237
238   GstFlowReturn (*parse_frame)        (GstBaseParse      * parse,
239                                        GstBaseParseFrame * frame);
240
241   GstFlowReturn (*pre_push_frame)     (GstBaseParse      * parse,
242                                        GstBaseParseFrame * frame);
243
244   gboolean      (*convert)            (GstBaseParse * parse,
245                                        GstFormat      src_format,
246                                        gint64         src_value,
247                                        GstFormat      dest_format,
248                                        gint64       * dest_value);
249
250   gboolean      (*event)              (GstBaseParse * parse,
251                                        GstEvent     * event);
252
253   gboolean      (*src_event)          (GstBaseParse * parse,
254                                        GstEvent     * event);
255
256   GstCaps *     (*get_sink_caps)      (GstBaseParse * parse);
257
258   /*< private >*/
259   gpointer       _gst_reserved[GST_PADDING_LARGE - 1];
260 };
261
262 GType           gst_base_parse_get_type (void);
263
264 GType           gst_base_parse_frame_get_type (void);
265
266 GstBaseParseFrame * gst_base_parse_frame_new  (GstBuffer              * buffer,
267                                                GstBaseParseFrameFlags   flags,
268                                                gint                     overhead);
269
270 void            gst_base_parse_frame_init      (GstBaseParseFrame * frame);
271
272 void            gst_base_parse_frame_free      (GstBaseParseFrame * frame);
273
274 GstFlowReturn   gst_base_parse_push_frame      (GstBaseParse      * parse,
275                                                 GstBaseParseFrame * frame);
276
277 void            gst_base_parse_set_duration    (GstBaseParse      * parse,
278                                                 GstFormat           fmt,
279                                                 gint64              duration,
280                                                 gint                interval);
281
282 void            gst_base_parse_set_average_bitrate (GstBaseParse   * parse,
283                                                     guint            bitrate);
284
285 void            gst_base_parse_set_min_frame_size (GstBaseParse    * parse,
286                                                    guint             min_size);
287
288 void            gst_base_parse_set_has_timing_info (GstBaseParse   * parse,
289                                                     gboolean         has_timing);
290
291 void            gst_base_parse_set_syncable    (GstBaseParse * parse,
292                                                 gboolean       syncable);
293
294 void            gst_base_parse_set_passthrough (GstBaseParse * parse,
295                                                 gboolean       passthrough);
296
297 void            gst_base_parse_set_frame_rate  (GstBaseParse * parse,
298                                                 guint          fps_num,
299                                                 guint          fps_den,
300                                                 guint          lead_in,
301                                                 guint          lead_out);
302
303 void            gst_base_parse_set_latency     (GstBaseParse * parse,
304                                                 GstClockTime min_latency,
305                                                 GstClockTime max_latency);
306
307 gboolean        gst_base_parse_convert_default (GstBaseParse * parse,
308                                                 GstFormat      src_format,
309                                                 gint64         src_value,
310                                                 GstFormat      dest_format,
311                                                 gint64       * dest_value);
312
313 gboolean        gst_base_parse_add_index_entry (GstBaseParse * parse,
314                                                 guint64        offset,
315                                                 GstClockTime   ts,
316                                                 gboolean       key,
317                                                 gboolean       force);
318
319 G_END_DECLS
320
321 #endif /* __GST_BASE_PARSE_H__ */