1 /* GStreamer aggregator base class 2 * Copyright (C) 2014 Mathieu Duponchelle <mathieu.duponchelle@oencreed.com> 3 * Copyright (C) 2014 Thibault Saunier <tsaunier@gnome.org> 4 * 5 * This library is free software; you can redistribute it and/or 6 * modify it under the terms of the GNU Library General Public 7 * License as published by the Free Software Foundation; either 8 * version 2 of the License, or (at your option) any later version. 9 * 10 * This library is distributed in the hope that it will be useful, 11 * but WITHOUT ANY WARRANTY; without even the implied warranty of 12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 13 * Library General Public License for more details. 14 * 15 * You should have received a copy of the GNU Library General Public 16 * License along with this library; if not, write to the 17 * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, 18 * Boston, MA 02110-1301, USA. 19 */ 20 21 #ifndef __GST_AGGREGATOR_H__ 22 #define __GST_AGGREGATOR_H__ 23 24 #include <gst/gst.h> 25 #include <gst/base/base-prelude.h> 26 27 G_BEGIN_DECLS 28 29 /************************** 30 * GstAggregator Structs * 31 *************************/ 32 33 typedef struct _GstAggregator GstAggregator; 34 typedef struct _GstAggregatorPrivate GstAggregatorPrivate; 35 typedef struct _GstAggregatorClass GstAggregatorClass; 36 37 /************************ 38 * GstAggregatorPad API * 39 ***********************/ 40 41 #define GST_TYPE_AGGREGATOR_PAD (gst_aggregator_pad_get_type()) 42 #define GST_AGGREGATOR_PAD(obj) (G_TYPE_CHECK_INSTANCE_CAST((obj),GST_TYPE_AGGREGATOR_PAD, GstAggregatorPad)) 43 #define GST_AGGREGATOR_PAD_CAST(obj) ((GstAggregatorPad *)(obj)) 44 #define GST_AGGREGATOR_PAD_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST((klass),GST_TYPE_AGGREGATOR_PAD, GstAggregatorPadClass)) 45 #define GST_AGGREGATOR_PAD_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj),GST_TYPE_AGGREGATOR_PAD, GstAggregatorPadClass)) 46 #define GST_IS_AGGREGATOR_PAD(obj) (G_TYPE_CHECK_INSTANCE_TYPE((obj),GST_TYPE_AGGREGATOR_PAD)) 47 #define GST_IS_AGGREGATOR_PAD_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass),GST_TYPE_AGGREGATOR_PAD)) 48 49 /**************************** 50 * GstAggregatorPad Structs * 51 ***************************/ 52 53 typedef struct _GstAggregatorPad GstAggregatorPad; 54 typedef struct _GstAggregatorPadClass GstAggregatorPadClass; 55 typedef struct _GstAggregatorPadPrivate GstAggregatorPadPrivate; 56 57 /** 58 * GstAggregatorPad: 59 * @segment: last segment received. 60 * 61 * The implementation the GstPad to use with #GstAggregator 62 * 63 * Since: 1.14 64 */ 65 struct _GstAggregatorPad 66 { 67 GstPad parent; 68 69 /*< public >*/ 70 /* Protected by the OBJECT_LOCK */ 71 GstSegment segment; 72 73 /* < private > */ 74 GstAggregatorPadPrivate * priv; 75 76 gpointer _gst_reserved[GST_PADDING]; 77 }; 78 79 /** 80 * GstAggregatorPadClass: 81 * @flush: Optional 82 * Called when the pad has received a flush stop, this is the place 83 * to flush any information specific to the pad, it allows for individual 84 * pads to be flushed while others might not be. 85 * @skip_buffer: Optional 86 * Called before input buffers are queued in the pad, return %TRUE 87 * if the buffer should be skipped. 88 * 89 * Since: 1.14 90 */ 91 struct _GstAggregatorPadClass 92 { 93 GstPadClass parent_class; 94 95 GstFlowReturn (*flush) (GstAggregatorPad * aggpad, GstAggregator * aggregator); 96 gboolean (*skip_buffer) (GstAggregatorPad * aggpad, GstAggregator * aggregator, GstBuffer * buffer); 97 98 /*< private >*/ 99 gpointer _gst_reserved[GST_PADDING_LARGE]; 100 }; 101 102 GST_BASE_API 103 GType gst_aggregator_pad_get_type (void); 104 105 /**************************** 106 * GstAggregatorPad methods * 107 ***************************/ 108 109 GST_BASE_API 110 GstBuffer * gst_aggregator_pad_pop_buffer (GstAggregatorPad * pad); 111 112 GST_BASE_API 113 GstBuffer * gst_aggregator_pad_peek_buffer (GstAggregatorPad * pad); 114 115 GST_BASE_API 116 gboolean gst_aggregator_pad_drop_buffer (GstAggregatorPad * pad); 117 118 GST_BASE_API 119 gboolean gst_aggregator_pad_has_buffer (GstAggregatorPad * pad); 120 121 GST_BASE_API 122 gboolean gst_aggregator_pad_is_eos (GstAggregatorPad * pad); 123 124 /********************* 125 * GstAggregator API * 126 ********************/ 127 128 #define GST_TYPE_AGGREGATOR (gst_aggregator_get_type()) 129 #define GST_AGGREGATOR(obj) (G_TYPE_CHECK_INSTANCE_CAST((obj),GST_TYPE_AGGREGATOR,GstAggregator)) 130 #define GST_AGGREGATOR_CAST(obj) ((GstAggregator *)(obj)) 131 #define GST_AGGREGATOR_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST((klass),GST_TYPE_AGGREGATOR,GstAggregatorClass)) 132 #define GST_AGGREGATOR_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj),GST_TYPE_AGGREGATOR,GstAggregatorClass)) 133 #define GST_IS_AGGREGATOR(obj) (G_TYPE_CHECK_INSTANCE_TYPE((obj),GST_TYPE_AGGREGATOR)) 134 #define GST_IS_AGGREGATOR_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass),GST_TYPE_AGGREGATOR)) 135 136 #define GST_AGGREGATOR_FLOW_NEED_DATA GST_FLOW_CUSTOM_ERROR 137 138 /** 139 * GstAggregator: 140 * @srcpad: the aggregator's source pad 141 * 142 * Aggregator base class object structure. 143 * 144 * Since: 1.14 145 */ 146 struct _GstAggregator 147 { 148 GstElement parent; 149 150 /*< public >*/ 151 GstPad * srcpad; 152 153 /*< private >*/ 154 GstAggregatorPrivate * priv; 155 156 gpointer _gst_reserved[GST_PADDING_LARGE]; 157 }; 158 159 /** 160 * GstAggregatorClass: 161 * @flush: Optional. 162 * Called after a successful flushing seek, once all the flush 163 * stops have been received. Flush pad-specific data in 164 * #GstAggregatorPad->flush. 165 * @clip: Optional. 166 * Called when a buffer is received on a sink pad, the task of 167 * clipping it and translating it to the current segment falls 168 * on the subclass. The function should use the segment of data 169 * and the negotiated media type on the pad to perform 170 * clipping of input buffer. This function takes ownership of 171 * buf and should output a buffer or return NULL in 172 * if the buffer should be dropped. 173 * @finish_buffer: Optional. 174 * Called when a subclass calls gst_aggregator_finish_buffer() 175 * from their aggregate function to push out a buffer. 176 * Subclasses can override this to modify or decorate buffers 177 * before they get pushed out. This function takes ownership 178 * of the buffer passed. Subclasses that override this method 179 * should always chain up to the parent class virtual method. 180 * @sink_event: Optional. 181 * Called when an event is received on a sink pad, the subclass 182 * should always chain up. 183 * @sink_query: Optional. 184 * Called when a query is received on a sink pad, the subclass 185 * should always chain up. 186 * @src_event: Optional. 187 * Called when an event is received on the src pad, the subclass 188 * should always chain up. 189 * @src_query: Optional. 190 * Called when a query is received on the src pad, the subclass 191 * should always chain up. 192 * @src_activate: Optional. 193 * Called when the src pad is activated, it will start/stop its 194 * pad task right after that call. 195 * @aggregate: Mandatory. 196 * Called when buffers are queued on all sinkpads. Classes 197 * should iterate the GstElement->sinkpads and peek or steal 198 * buffers from the #GstAggregatorPads. If the subclass returns 199 * GST_FLOW_EOS, sending of the eos event will be taken care 200 * of. Once / if a buffer has been constructed from the 201 * aggregated buffers, the subclass should call _finish_buffer. 202 * @stop: Optional. 203 * Called when the element goes from PAUSED to READY. 204 * The subclass should free all resources and reset its state. 205 * @start: Optional. 206 * Called when the element goes from READY to PAUSED. 207 * The subclass should get ready to process 208 * aggregated buffers. 209 * @get_next_time: Optional. 210 * Called when the element needs to know the running time of the next 211 * rendered buffer for live pipelines. This causes deadline 212 * based aggregation to occur. Defaults to returning 213 * GST_CLOCK_TIME_NONE causing the element to wait for buffers 214 * on all sink pads before aggregating. 215 * @create_new_pad: Optional. 216 * Called when a new pad needs to be created. Allows subclass that 217 * don't have a single sink pad template to provide a pad based 218 * on the provided information. 219 * @update_src_caps: Lets subclasses update the #GstCaps representing 220 * the src pad caps before usage. The result should end up 221 * in @ret. Return %GST_AGGREGATOR_FLOW_NEED_DATA to indicate that the 222 * element needs more information (caps, a buffer, etc) to 223 * choose the correct caps. Should return ANY caps if the 224 * stream has not caps at all. 225 * @fixate_src_caps: Optional. 226 * Fixate and return the src pad caps provided. The function takes 227 * ownership of @caps and returns a fixated version of 228 * @caps. @caps is not guaranteed to be writable. 229 * @negotiated_src_caps: Optional. 230 * Notifies subclasses what caps format has been negotiated 231 * @decide_allocation: Optional. 232 * Allows the subclass to influence the allocation choices. 233 * Setup the allocation parameters for allocating output 234 * buffers. The passed in query contains the result of the 235 * downstream allocation query. 236 * @propose_allocation: Optional. 237 * Allows the subclass to handle the allocation query from upstream. 238 * 239 * The aggregator base class will handle in a thread-safe way all manners of 240 * concurrent flushes, seeks, pad additions and removals, leaving to the 241 * subclass the responsibility of clipping buffers, and aggregating buffers in 242 * the way the implementor sees fit. 243 * 244 * It will also take care of event ordering (stream-start, segment, eos). 245 * 246 * Basically, a simple implementation will override @aggregate, and call 247 * _finish_buffer from inside that function. 248 * 249 * Since: 1.14 250 */ 251 struct _GstAggregatorClass { 252 GstElementClass parent_class; 253 254 GstFlowReturn (*flush) (GstAggregator * aggregator); 255 256 GstBuffer * (*clip) (GstAggregator * aggregator, 257 GstAggregatorPad * aggregator_pad, 258 GstBuffer * buf); 259 260 GstFlowReturn (*finish_buffer) (GstAggregator * aggregator, 261 GstBuffer * buffer); 262 263 /* sinkpads virtual methods */ 264 gboolean (*sink_event) (GstAggregator * aggregator, 265 GstAggregatorPad * aggregator_pad, 266 GstEvent * event); 267 268 gboolean (*sink_query) (GstAggregator * aggregator, 269 GstAggregatorPad * aggregator_pad, 270 GstQuery * query); 271 272 /* srcpad virtual methods */ 273 gboolean (*src_event) (GstAggregator * aggregator, 274 GstEvent * event); 275 276 gboolean (*src_query) (GstAggregator * aggregator, 277 GstQuery * query); 278 279 gboolean (*src_activate) (GstAggregator * aggregator, 280 GstPadMode mode, 281 gboolean active); 282 283 GstFlowReturn (*aggregate) (GstAggregator * aggregator, 284 gboolean timeout); 285 286 gboolean (*stop) (GstAggregator * aggregator); 287 288 gboolean (*start) (GstAggregator * aggregator); 289 290 GstClockTime (*get_next_time) (GstAggregator * aggregator); 291 292 GstAggregatorPad * (*create_new_pad) (GstAggregator * self, 293 GstPadTemplate * templ, 294 const gchar * req_name, 295 const GstCaps * caps); 296 297 /** 298 * GstAggregatorClass::update_src_caps: 299 * @ret: (out) (allow-none): 300 */ 301 GstFlowReturn (*update_src_caps) (GstAggregator * self, 302 GstCaps * caps, 303 GstCaps ** ret); 304 GstCaps * (*fixate_src_caps) (GstAggregator * self, 305 GstCaps * caps); 306 gboolean (*negotiated_src_caps) (GstAggregator * self, 307 GstCaps * caps); 308 gboolean (*decide_allocation) (GstAggregator * self, 309 GstQuery * query); 310 gboolean (*propose_allocation) (GstAggregator * self, 311 GstAggregatorPad * pad, 312 GstQuery * decide_query, 313 GstQuery * query); 314 /*< private >*/ 315 gpointer _gst_reserved[GST_PADDING_LARGE]; 316 }; 317 318 /************************************ 319 * GstAggregator convenience macros * 320 ***********************************/ 321 322 /** 323 * GST_AGGREGATOR_SRC_PAD: 324 * @agg: a #GstAggregator 325 * 326 * Convenience macro to access the source pad of #GstAggregator 327 * 328 * Since: 1.6 329 */ 330 #define GST_AGGREGATOR_SRC_PAD(agg) (((GstAggregator *)(agg))->srcpad) 331 332 /************************* 333 * GstAggregator methods * 334 ************************/ 335 336 GST_BASE_API 337 GstFlowReturn gst_aggregator_finish_buffer (GstAggregator * aggregator, 338 GstBuffer * buffer); 339 340 GST_BASE_API 341 void gst_aggregator_set_src_caps (GstAggregator * self, 342 GstCaps * caps); 343 344 GST_BASE_API 345 void gst_aggregator_set_latency (GstAggregator * self, 346 GstClockTime min_latency, 347 GstClockTime max_latency); 348 349 GST_BASE_API 350 GType gst_aggregator_get_type(void); 351 352 GST_BASE_API 353 GstClockTime gst_aggregator_get_latency (GstAggregator * self); 354 355 GST_BASE_API 356 GstBufferPool * gst_aggregator_get_buffer_pool (GstAggregator * self); 357 358 GST_BASE_API 359 void gst_aggregator_get_allocator (GstAggregator * self, 360 GstAllocator ** allocator, 361 GstAllocationParams * params); 362 363 GST_BASE_API 364 GstClockTime gst_aggregator_simple_get_next_time (GstAggregator * self); 365 366 367 G_END_DECLS 368 369 #ifdef G_DEFINE_AUTOPTR_CLEANUP_FUNC 370 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstAggregator, gst_object_unref) 371 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstAggregatorPad, gst_object_unref) 372 #endif 373 374 #endif /* __GST_AGGREGATOR_H__ */ 375