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 /** 246 * GstBaseParseClass::handle_frame: 247 * @skipsize: (out): 248 * 249 * Parses the input data into valid frames as defined by subclass 250 * which should be passed to gst_base_parse_finish_frame(). 251 * The frame's input buffer is guaranteed writable, 252 * whereas the input frame ownership is held by caller 253 * (so subclass should make a copy if it needs to hang on). 254 * Input buffer (data) is provided by baseclass with as much 255 * metadata set as possible by baseclass according to upstream 256 * information and/or subclass settings, 257 * though subclass may still set buffer timestamp and duration 258 * if desired. 259 */ 260 GstFlowReturn (*handle_frame) (GstBaseParse * parse, 261 GstBaseParseFrame * frame, 262 gint * skipsize); 263 264 GstFlowReturn (*pre_push_frame) (GstBaseParse * parse, 265 GstBaseParseFrame * frame); 266 267 gboolean (*convert) (GstBaseParse * parse, 268 GstFormat src_format, 269 gint64 src_value, 270 GstFormat dest_format, 271 gint64 * dest_value); 272 273 gboolean (*sink_event) (GstBaseParse * parse, 274 GstEvent * event); 275 276 gboolean (*src_event) (GstBaseParse * parse, 277 GstEvent * event); 278 279 GstCaps * (*get_sink_caps) (GstBaseParse * parse, 280 GstCaps * filter); 281 282 GstFlowReturn (*detect) (GstBaseParse * parse, 283 GstBuffer * buffer); 284 285 gboolean (*sink_query) (GstBaseParse * parse, 286 GstQuery * query); 287 288 gboolean (*src_query) (GstBaseParse * parse, 289 GstQuery * query); 290 291 /*< private >*/ 292 gpointer _gst_reserved[GST_PADDING_LARGE - 2]; 293 }; 294 295 GST_BASE_API 296 GType gst_base_parse_get_type (void); 297 298 GST_BASE_API 299 GType gst_base_parse_frame_get_type (void); 300 301 GST_BASE_API 302 GstBaseParseFrame * gst_base_parse_frame_new (GstBuffer * buffer, 303 GstBaseParseFrameFlags flags, 304 gint overhead); 305 GST_BASE_API 306 void gst_base_parse_frame_init (GstBaseParseFrame * frame); 307 308 GST_BASE_API 309 GstBaseParseFrame * gst_base_parse_frame_copy (GstBaseParseFrame * frame); 310 GST_BASE_API 311 void gst_base_parse_frame_free (GstBaseParseFrame * frame); 312 313 GST_BASE_API 314 GstFlowReturn gst_base_parse_push_frame (GstBaseParse * parse, 315 GstBaseParseFrame * frame); 316 GST_BASE_API 317 GstFlowReturn gst_base_parse_finish_frame (GstBaseParse * parse, 318 GstBaseParseFrame * frame, 319 gint size); 320 GST_BASE_API 321 void gst_base_parse_set_duration (GstBaseParse * parse, 322 GstFormat fmt, 323 gint64 duration, 324 gint interval); 325 GST_BASE_API 326 void gst_base_parse_set_average_bitrate (GstBaseParse * parse, 327 guint bitrate); 328 GST_BASE_API 329 void gst_base_parse_set_min_frame_size (GstBaseParse * parse, 330 guint min_size); 331 GST_BASE_API 332 void gst_base_parse_set_has_timing_info (GstBaseParse * parse, 333 gboolean has_timing); 334 GST_BASE_API 335 void gst_base_parse_drain (GstBaseParse * parse); 336 337 GST_BASE_API 338 void gst_base_parse_set_syncable (GstBaseParse * parse, 339 gboolean syncable); 340 GST_BASE_API 341 void gst_base_parse_set_passthrough (GstBaseParse * parse, 342 gboolean passthrough); 343 GST_BASE_API 344 void gst_base_parse_set_pts_interpolation (GstBaseParse * parse, 345 gboolean pts_interpolate); 346 GST_BASE_API 347 void gst_base_parse_set_infer_ts (GstBaseParse * parse, 348 gboolean infer_ts); 349 GST_BASE_API 350 void gst_base_parse_set_frame_rate (GstBaseParse * parse, 351 guint fps_num, 352 guint fps_den, 353 guint lead_in, 354 guint lead_out); 355 GST_BASE_API 356 void gst_base_parse_set_latency (GstBaseParse * parse, 357 GstClockTime min_latency, 358 GstClockTime max_latency); 359 GST_BASE_API 360 gboolean gst_base_parse_convert_default (GstBaseParse * parse, 361 GstFormat src_format, 362 gint64 src_value, 363 GstFormat dest_format, 364 gint64 * dest_value); 365 GST_BASE_API 366 gboolean gst_base_parse_add_index_entry (GstBaseParse * parse, 367 guint64 offset, 368 GstClockTime ts, 369 gboolean key, 370 gboolean force); 371 GST_BASE_API 372 void gst_base_parse_set_ts_at_offset (GstBaseParse *parse, 373 gsize offset); 374 GST_BASE_API 375 void gst_base_parse_merge_tags (GstBaseParse * parse, 376 GstTagList * tags, 377 GstTagMergeMode mode); 378 379 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstBaseParseFrame, gst_base_parse_frame_free) 380 381 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstBaseParse, gst_object_unref) 382 383 G_END_DECLS 384 385 #endif /* __GST_BASE_PARSE_H__ */ 386