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., 51 Franklin St, Fifth Floor, 19 * Boston, MA 02110-1301, USA. 20 */ 21 22 #ifndef __GST_BASE_PARSE_H__ 23 #define __GST_BASE_PARSE_H__ 24 25 #include <gst/gst.h> 26 #include <gst/base/base-prelude.h> 27 28 G_BEGIN_DECLS 29 30 #define GST_TYPE_BASE_PARSE (gst_base_parse_get_type()) 31 #define GST_BASE_PARSE(obj) (G_TYPE_CHECK_INSTANCE_CAST((obj),GST_TYPE_BASE_PARSE,GstBaseParse)) 32 #define GST_BASE_PARSE_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST((klass),GST_TYPE_BASE_PARSE,GstBaseParseClass)) 33 #define GST_BASE_PARSE_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS((obj),GST_TYPE_BASE_PARSE,GstBaseParseClass)) 34 #define GST_IS_BASE_PARSE(obj) (G_TYPE_CHECK_INSTANCE_TYPE((obj),GST_TYPE_BASE_PARSE)) 35 #define GST_IS_BASE_PARSE_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass),GST_TYPE_BASE_PARSE)) 36 #define GST_BASE_PARSE_CAST(obj) ((GstBaseParse *)(obj)) 37 38 /** 39 * GST_BASE_PARSE_SRC_PAD: 40 * @obj: base parse instance 41 * 42 * Gives the pointer to the source #GstPad object of the element. 43 */ 44 #define GST_BASE_PARSE_SRC_PAD(obj) (GST_BASE_PARSE_CAST (obj)->srcpad) 45 46 /** 47 * GST_BASE_PARSE_SINK_PAD: 48 * @obj: base parse instance 49 * 50 * Gives the pointer to the sink #GstPad object of the element. 51 */ 52 #define GST_BASE_PARSE_SINK_PAD(obj) (GST_BASE_PARSE_CAST (obj)->sinkpad) 53 54 /** 55 * GST_BASE_PARSE_FLOW_DROPPED: 56 * 57 * A #GstFlowReturn that can be returned from 58 * #GstBaseParseClass.handle_frame() to indicate that no output buffer was 59 * generated, or from #GstBaseParseClass.pre_push_frame() to to forego 60 * pushing buffer. 61 */ 62 #define GST_BASE_PARSE_FLOW_DROPPED GST_FLOW_CUSTOM_SUCCESS 63 64 /* not public API, use accessor macros below */ 65 #define GST_BASE_PARSE_FLAG_LOST_SYNC (1 << 0) 66 #define GST_BASE_PARSE_FLAG_DRAINING (1 << 1) 67 68 /** 69 * GST_BASE_PARSE_LOST_SYNC: 70 * @parse: base parse instance 71 * 72 * Obtains current sync status. 73 */ 74 #define GST_BASE_PARSE_LOST_SYNC(parse) (!!(GST_BASE_PARSE_CAST(parse)->flags & GST_BASE_PARSE_FLAG_LOST_SYNC)) 75 76 /** 77 * GST_BASE_PARSE_DRAINING: 78 * @parse: base parse instance 79 * 80 * Obtains current drain status (ie. whether EOS has been received and 81 * the parser is now processing the frames at the end of the stream) 82 */ 83 #define GST_BASE_PARSE_DRAINING(parse) (!!(GST_BASE_PARSE_CAST(parse)->flags & GST_BASE_PARSE_FLAG_DRAINING)) 84 85 /** 86 * GstBaseParseFrameFlags: 87 * @GST_BASE_PARSE_FRAME_FLAG_NONE: no flag 88 * @GST_BASE_PARSE_FRAME_FLAG_NEW_FRAME: set by baseclass if current frame 89 * is passed for processing to the subclass for the first time 90 * (and not set on subsequent calls with same data). 91 * @GST_BASE_PARSE_FRAME_FLAG_NO_FRAME: set to indicate this buffer should not be 92 * counted as frame, e.g. if this frame is dependent on a previous one. 93 * As it is not counted as a frame, bitrate increases but frame to time 94 * conversions are maintained. 95 * @GST_BASE_PARSE_FRAME_FLAG_CLIP: @pre_push_frame can set this to indicate 96 * that regular segment clipping can still be performed (as opposed to 97 * any custom one having been done). 98 * @GST_BASE_PARSE_FRAME_FLAG_DROP: indicates to @finish_frame that the 99 * the frame should be dropped (and might be handled internally by subclass) 100 * @GST_BASE_PARSE_FRAME_FLAG_QUEUE: indicates to @finish_frame that the 101 * the frame should be queued for now and processed fully later 102 * when the first non-queued frame is finished 103 * 104 * Flags to be used in a #GstBaseParseFrame. 105 */ 106 typedef enum { 107 GST_BASE_PARSE_FRAME_FLAG_NONE = 0, 108 GST_BASE_PARSE_FRAME_FLAG_NEW_FRAME = (1 << 0), 109 GST_BASE_PARSE_FRAME_FLAG_NO_FRAME = (1 << 1), 110 GST_BASE_PARSE_FRAME_FLAG_CLIP = (1 << 2), 111 GST_BASE_PARSE_FRAME_FLAG_DROP = (1 << 3), 112 GST_BASE_PARSE_FRAME_FLAG_QUEUE = (1 << 4) 113 } GstBaseParseFrameFlags; 114 115 /** 116 * GstBaseParseFrame: 117 * @buffer: input data to be parsed for frames. 118 * @out_buffer: output data. 119 * @offset: media specific offset of input frame 120 * Note that a converter may have a different one on the frame's buffer. 121 * @overhead: subclass can set this to indicates the metadata overhead 122 * for the given frame, which is then used to enable more accurate bitrate 123 * computations. If this is -1, it is assumed that this frame should be 124 * skipped in bitrate calculation. 125 * @flags: a combination of input and output #GstBaseParseFrameFlags that 126 * convey additional context to subclass or allow subclass to tune 127 * subsequent #GstBaseParse actions. 128 * 129 * Frame (context) data passed to each frame parsing virtual methods. In 130 * addition to providing the data to be checked for a valid frame or an already 131 * identified frame, it conveys additional metadata or control information 132 * from and to the subclass w.r.t. the particular frame in question (rather 133 * than global parameters). Some of these may apply to each parsing stage, others 134 * only to some a particular one. These parameters are effectively zeroed at start 135 * of each frame's processing, i.e. parsing virtual method invocation sequence. 136 */ 137 typedef struct { 138 GstBuffer * buffer; 139 GstBuffer * out_buffer; 140 guint flags; 141 guint64 offset; 142 gint overhead; 143 /*< private >*/ 144 gint size; 145 guint _gst_reserved_i[2]; 146 gpointer _gst_reserved_p[2]; 147 guint _private_flags; 148 } GstBaseParseFrame; 149 150 typedef struct _GstBaseParse GstBaseParse; 151 typedef struct _GstBaseParseClass GstBaseParseClass; 152 typedef struct _GstBaseParsePrivate GstBaseParsePrivate; 153 154 /** 155 * GstBaseParse: 156 * @element: the parent element. 157 * 158 * The opaque #GstBaseParse data structure. 159 */ 160 struct _GstBaseParse { 161 /*< public >*/ 162 GstElement element; 163 164 /*< protected >*/ 165 /* source and sink pads */ 166 GstPad *sinkpad; 167 GstPad *srcpad; 168 169 guint flags; 170 171 /* MT-protected (with STREAM_LOCK) */ 172 GstSegment segment; 173 174 /*< private >*/ 175 gpointer _gst_reserved[GST_PADDING_LARGE]; 176 GstBaseParsePrivate *priv; 177 }; 178 179 /** 180 * GstBaseParseClass: 181 * @parent_class: the parent class 182 * @start: Optional. 183 * Called when the element starts processing. 184 * Allows opening external resources. 185 * @stop: Optional. 186 * Called when the element stops processing. 187 * Allows closing external resources. 188 * @set_sink_caps: Optional. 189 * Allows the subclass to be notified of the actual caps set. 190 * @get_sink_caps: Optional. 191 * Allows the subclass to do its own sink get caps if needed. 192 * @handle_frame: Parses the input data into valid frames as defined by subclass 193 * which should be passed to gst_base_parse_finish_frame(). 194 * The frame's input buffer is guaranteed writable, 195 * whereas the input frame ownership is held by caller 196 * (so subclass should make a copy if it needs to hang on). 197 * Input buffer (data) is provided by baseclass with as much 198 * metadata set as possible by baseclass according to upstream 199 * information and/or subclass settings, 200 * though subclass may still set buffer timestamp and duration 201 * if desired. 202 * @convert: Optional. 203 * Convert between formats. 204 * @sink_event: Optional. 205 * Event handler on the sink pad. This function should chain 206 * up to the parent implementation to let the default handler 207 * run. 208 * @src_event: Optional. 209 * Event handler on the source pad. Should chain up to the 210 * parent to let the default handler run. 211 * @pre_push_frame: Optional. 212 * Called just prior to pushing a frame (after any pending 213 * events have been sent) to give subclass a chance to perform 214 * additional actions at this time (e.g. tag sending) or to 215 * decide whether this buffer should be dropped or not 216 * (e.g. custom segment clipping). 217 * @detect: Optional. 218 * Called until it doesn't return GST_FLOW_OK anymore for 219 * the first buffers. Can be used by the subclass to detect 220 * the stream format. 221 * @sink_query: Optional. 222 * Query handler on the sink pad. This function should chain 223 * up to the parent implementation to let the default handler 224 * run (Since: 1.2) 225 * @src_query: Optional. 226 * Query handler on the source pad. Should chain up to the 227 * parent to let the default handler run (Since: 1.2) 228 * 229 * Subclasses can override any of the available virtual methods or not, as 230 * needed. At minimum @handle_frame needs to be overridden. 231 */ 232 struct _GstBaseParseClass { 233 GstElementClass parent_class; 234 235 /*< public >*/ 236 /* virtual methods for subclasses */ 237 238 gboolean (*start) (GstBaseParse * parse); 239 240 gboolean (*stop) (GstBaseParse * parse); 241 242 gboolean (*set_sink_caps) (GstBaseParse * parse, 243 GstCaps * caps); 244 245 GstFlowReturn (*handle_frame) (GstBaseParse * parse, 246 GstBaseParseFrame * frame, 247 gint * skipsize); 248 249 GstFlowReturn (*pre_push_frame) (GstBaseParse * parse, 250 GstBaseParseFrame * frame); 251 252 gboolean (*convert) (GstBaseParse * parse, 253 GstFormat src_format, 254 gint64 src_value, 255 GstFormat dest_format, 256 gint64 * dest_value); 257 258 gboolean (*sink_event) (GstBaseParse * parse, 259 GstEvent * event); 260 261 gboolean (*src_event) (GstBaseParse * parse, 262 GstEvent * event); 263 264 GstCaps * (*get_sink_caps) (GstBaseParse * parse, 265 GstCaps * filter); 266 267 GstFlowReturn (*detect) (GstBaseParse * parse, 268 GstBuffer * buffer); 269 270 gboolean (*sink_query) (GstBaseParse * parse, 271 GstQuery * query); 272 273 gboolean (*src_query) (GstBaseParse * parse, 274 GstQuery * query); 275 276 /*< private >*/ 277 gpointer _gst_reserved[GST_PADDING_LARGE - 2]; 278 }; 279 280 GST_BASE_API 281 GType gst_base_parse_get_type (void); 282 283 GST_BASE_API 284 GType gst_base_parse_frame_get_type (void); 285 286 GST_BASE_API 287 GstBaseParseFrame * gst_base_parse_frame_new (GstBuffer * buffer, 288 GstBaseParseFrameFlags flags, 289 gint overhead); 290 GST_BASE_API 291 void gst_base_parse_frame_init (GstBaseParseFrame * frame); 292 293 GST_BASE_API 294 GstBaseParseFrame * gst_base_parse_frame_copy (GstBaseParseFrame * frame); 295 GST_BASE_API 296 void gst_base_parse_frame_free (GstBaseParseFrame * frame); 297 298 GST_BASE_API 299 GstFlowReturn gst_base_parse_push_frame (GstBaseParse * parse, 300 GstBaseParseFrame * frame); 301 GST_BASE_API 302 GstFlowReturn gst_base_parse_finish_frame (GstBaseParse * parse, 303 GstBaseParseFrame * frame, 304 gint size); 305 GST_BASE_API 306 void gst_base_parse_set_duration (GstBaseParse * parse, 307 GstFormat fmt, 308 gint64 duration, 309 gint interval); 310 GST_BASE_API 311 void gst_base_parse_set_average_bitrate (GstBaseParse * parse, 312 guint bitrate); 313 GST_BASE_API 314 void gst_base_parse_set_min_frame_size (GstBaseParse * parse, 315 guint min_size); 316 GST_BASE_API 317 void gst_base_parse_set_has_timing_info (GstBaseParse * parse, 318 gboolean has_timing); 319 GST_BASE_API 320 void gst_base_parse_drain (GstBaseParse * parse); 321 322 GST_BASE_API 323 void gst_base_parse_set_syncable (GstBaseParse * parse, 324 gboolean syncable); 325 GST_BASE_API 326 void gst_base_parse_set_passthrough (GstBaseParse * parse, 327 gboolean passthrough); 328 GST_BASE_API 329 void gst_base_parse_set_pts_interpolation (GstBaseParse * parse, 330 gboolean pts_interpolate); 331 GST_BASE_API 332 void gst_base_parse_set_infer_ts (GstBaseParse * parse, 333 gboolean infer_ts); 334 GST_BASE_API 335 void gst_base_parse_set_frame_rate (GstBaseParse * parse, 336 guint fps_num, 337 guint fps_den, 338 guint lead_in, 339 guint lead_out); 340 GST_BASE_API 341 void gst_base_parse_set_latency (GstBaseParse * parse, 342 GstClockTime min_latency, 343 GstClockTime max_latency); 344 GST_BASE_API 345 gboolean gst_base_parse_convert_default (GstBaseParse * parse, 346 GstFormat src_format, 347 gint64 src_value, 348 GstFormat dest_format, 349 gint64 * dest_value); 350 GST_BASE_API 351 gboolean gst_base_parse_add_index_entry (GstBaseParse * parse, 352 guint64 offset, 353 GstClockTime ts, 354 gboolean key, 355 gboolean force); 356 GST_BASE_API 357 void gst_base_parse_set_ts_at_offset (GstBaseParse *parse, 358 gsize offset); 359 GST_BASE_API 360 void gst_base_parse_merge_tags (GstBaseParse * parse, 361 GstTagList * tags, 362 GstTagMergeMode mode); 363 364 #ifdef G_DEFINE_AUTOPTR_CLEANUP_FUNC 365 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstBaseParseFrame, gst_base_parse_frame_free) 366 #endif 367 368 #ifdef G_DEFINE_AUTOPTR_CLEANUP_FUNC 369 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstBaseParse, gst_object_unref) 370 #endif 371 372 G_END_DECLS 373 374 #endif /* __GST_BASE_PARSE_H__ */ 375