GstAggregator: GStreamer 1.0 Library Reference Manual

## GstAggregator GstAggregator — Base class for mixers and muxers, manages a set of input pads and aggregates their streams |

## Functions

#define | GST_AGGREGATOR_SRC_PAD()
GstFlowReturn | gst_aggregator_finish_buffer ()
void | gst_aggregator_set_src_caps ()
GstClockTime | gst_aggregator_get_latency ()
void | gst_aggregator_set_latency ()
GstBufferPool * | gst_aggregator_get_buffer_pool ()
void | gst_aggregator_get_allocator ()
GstClockTime | gst_aggregator_simple_get_next_time ()

## Properties

guint64 | latency | Read / Write
guint64 | min-upstream-latency | Read / Write
guint64 | start-time | Read / Write
GstAggregatorStartTimeSelection | start-time-selection | Read / Write

## Types and Values

struct | GstAggregator
struct | GstAggregatorClass
#define | GST_AGGREGATOR_FLOW_NEED_DATA

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── GstObject
                ╰── GstElement
                    ╰── GstAggregator

## Includes

    #include <gst/base/base.h>

## Description

Manages a set of pads with the purpose of aggregating their buffers. Control is given to the subclass when all pads have data.

- Base class for mixers and muxers. Subclasses should at least implement the `GstAggregatorClass.aggregate()` virtual method.

- Installs a GstPadChainFunction, a GstPadEventFullFunction and a GstPadQueryFunction to queue all serialized data packets per sink pad. Subclasses should not overwrite those, but instead implement `GstAggregatorClass.sink_event()` and `GstAggregatorClass.sink_query()` as needed.

- When data is queued on all pads, the aggregate vmethod is called.

- One can peek at the data on any given GstAggregatorPad with the `gst_aggregator_pad_peek_buffer()` method, and remove it from the pad with the `gst_aggregator_pad_pop_buffer()` method. When a buffer has been taken with `pop_buffer()`, a new buffer can be queued on that pad.

- If the subclass wishes to push a buffer downstream in its aggregate implementation, it should do so through the `gst_aggregator_finish_buffer()` method. This method will take care of sending and ordering mandatory events such as stream start, caps and segment.

- Same goes for EOS events, which should not be pushed directly by the subclass, it should instead return GST_FLOW_EOS in its aggregate implementation.

- Note that the aggregator logic regarding gap event handling is to turn these into gap buffers with matching PTS and duration. It will also flag these buffers with GST_BUFFER_FLAG_GAP and GST_BUFFER_FLAG_DROPPABLE to ease their identification and subsequent processing.

- Subclasses must use (a subclass of) GstAggregatorPad for both their sink and source pads. See `gst_element_class_add_static_pad_template_with_gtype()`.

This class used to live in gst-plugins-bad and was moved to core.

## Functions

### GST_AGGREGATOR_SRC_PAD()

    #define GST_AGGREGATOR_SRC_PAD(agg) (((GstAggregator *)(agg))->srcpad)

Convenience macro to access the source pad of GstAggregator

#### Parameters

agg | a GstAggregator |

Since: 1.6

### gst_aggregator_finish_buffer ()

    GstFlowReturn
    gst_aggregator_finish_buffer (GstAggregator *aggregator,
                                  GstBuffer *buffer);

This method will push the provided output buffer downstream. If needed, mandatory events such as stream-start, caps, and segment events will be sent before pushing the buffer.

#### Parameters

aggregator | The GstAggregator |
buffer | the GstBuffer to push. | [transfer full]

### gst_aggregator_set_src_caps ()

    void
    gst_aggregator_set_src_caps (GstAggregator *self,
                                 GstCaps *caps);

Sets the caps to be used on the src pad.

#### Parameters

self | The GstAggregator |
caps | The GstCaps to set on the src pad. |

### gst_aggregator_get_latency ()

    GstClockTime
    gst_aggregator_get_latency (GstAggregator *self);

Retrieves the latency values reported by `self` in response to the latency query, or `GST_CLOCK_TIME_NONE` if there is not live source connected and the element will not wait for the clock.

Typically only called by subclasses.

#### Parameters

self | a GstAggregator |

#### Returns

The latency or `GST_CLOCK_TIME_NONE` if the element does not sync

### gst_aggregator_set_latency ()

    void
    gst_aggregator_set_latency (GstAggregator *self,
                                GstClockTime min_latency,
                                GstClockTime max_latency);

Lets GstAggregator sub-classes tell the baseclass what their internal latency is. Will also post a LATENCY message on the bus so the pipeline can reconfigure its global latency.

#### Parameters

self | a GstAggregator |
min_latency | minimum latency |
max_latency | maximum latency |

### gst_aggregator_get_buffer_pool ()

    GstBufferPool *
    gst_aggregator_get_buffer_pool (GstAggregator *self);

#### Parameters

self | a GstAggregator |

#### Returns

the instance of the GstBufferPool used by `trans` ; free it after use it.

[transfer full]

### gst_aggregator_get_allocator ()

    void
    gst_aggregator_get_allocator (GstAggregator *self,
                                  GstAllocator **allocator,
                                  GstAllocationParams *params);

Lets GstAggregator sub-classes get the memory `allocator` acquired by the base class and its `params` .

Unref the `allocator` after use it.

#### Parameters

self | a GstAggregator |
allocator | the GstAllocator used. | [out][allow-none][transfer full]
params | the GstAllocationParams of `allocator` . | [out][allow-none][transfer full]

### gst_aggregator_simple_get_next_time ()

    GstClockTime
    gst_aggregator_simple_get_next_time (GstAggregator *self);

This is a simple “get_next_time” implementation that just looks at the GstSegment on the srcpad of the aggregator and bases the next time on the running time there.

This is the desired behaviour in most cases where you have a live source and you have a dead line based aggregator subclass.

#### Parameters

self | A GstAggregator |

#### Returns

The running time based on the position

Since: 1.16

## Types and Values

### struct GstAggregator

    struct GstAggregator {
      GstPad                *  srcpad;
    };

Aggregator base class object structure.

#### Members

GstPad *`srcpad`; | the aggregator's source pad |

### struct GstAggregatorClass

    struct GstAggregatorClass {
      GstElementClass   parent_class;

      GstFlowReturn     (*flush)          (GstAggregator    *  aggregator);

      GstBuffer *       (*clip)           (GstAggregator    *  aggregator,
                                           GstAggregatorPad *  aggregator_pad,
                                           GstBuffer        *  buf);

      GstFlowReturn     (*finish_buffer)  (GstAggregator    * aggregator,
                                           GstBuffer        * buffer);

      /* sinkpads virtual methods */
      gboolean          (*sink_event)     (GstAggregator    *  aggregator,
                                           GstAggregatorPad *  aggregator_pad,
                                           GstEvent         *  event);

      gboolean          (*sink_query)     (GstAggregator    *  aggregator,
                                           GstAggregatorPad *  aggregator_pad,
                                           GstQuery         *  query);

      /* srcpad virtual methods */
      gboolean          (*src_event)      (GstAggregator    *  aggregator,
                                           GstEvent         *  event);

      gboolean          (*src_query)      (GstAggregator    *  aggregator,
                                           GstQuery         *  query);

      gboolean          (*src_activate)   (GstAggregator    *  aggregator,
                                           GstPadMode          mode,
                                           gboolean            active);

      GstFlowReturn     (*aggregate)      (GstAggregator    *  aggregator,
                                           gboolean            timeout);

      gboolean          (*stop)           (GstAggregator    *  aggregator);

      gboolean          (*start)          (GstAggregator    *  aggregator);

      GstClockTime      (*get_next_time)  (GstAggregator    *  aggregator);

      GstAggregatorPad * (*create_new_pad) (GstAggregator  * self,
                                            GstPadTemplate * templ,
                                            const gchar    * req_name,
                                            const GstCaps  * caps);

      /**
       * GstAggregatorClass::update_src_caps:
       * @ret: (out) (allow-none):
       */
      GstFlowReturn     (*update_src_caps) (GstAggregator *  self,
                                            GstCaps       *  caps,
                                            GstCaps       ** ret);
      GstCaps *         (*fixate_src_caps) (GstAggregator *  self,
                                            GstCaps       *  caps);
      gboolean          (*negotiated_src_caps) (GstAggregator *  self,
                                                GstCaps      *  caps);
      gboolean          (*decide_allocation) (GstAggregator * self,
                                              GstQuery * query);
      gboolean          (*propose_allocation) (GstAggregator * self,
                                               GstAggregatorPad * pad,
                                               GstQuery * decide_query,
                                               GstQuery * query);
    };

The aggregator base class will handle in a thread-safe way all manners of concurrent flushes, seeks, pad additions and removals, leaving to the subclass the responsibility of clipping buffers, and aggregating buffers in the way the implementor sees fit.

It will also take care of event ordering (stream-start, segment, eos).

Basically, a simple implementation will override `aggregate` , and call _finish_buffer from inside that function.

#### Members

`flush` () | Optional. Called after a successful flushing seek, once all the flush stops have been received. Flush pad-specific data in GstAggregatorPad->flush. |
`clip` () | Optional. Called when a buffer is received on a sink pad, the task of clipping it and translating it to the current segment falls on the subclass. The function should use the segment of data and the negotiated media type on the pad to perform clipping of input buffer. This function takes ownership of buf and should output a buffer or return NULL in if the buffer should be dropped. |
`finish_buffer` () | Optional. Called when a subclass calls `gst_aggregator_finish_buffer()` from their aggregate function to push out a buffer. Subclasses can override this to modify or decorate buffers before they get pushed out. This function takes ownership of the buffer passed. Subclasses that override this method should always chain up to the parent class virtual method. |
`sink_event` () | Optional. Called when an event is received on a sink pad, the subclass should always chain up. |
`sink_query` () | Optional. Called when a query is received on a sink pad, the subclass should always chain up. |
`src_event` () | Optional. Called when an event is received on the src pad, the subclass should always chain up. |
`src_query` () | Optional. Called when a query is received on the src pad, the subclass should always chain up. |
`src_activate` () | Optional. Called when the src pad is activated, it will start/stop its pad task right after that call. |
`aggregate` () | Mandatory. Called when buffers are queued on all sinkpads. Classes should iterate the GstElement->sinkpads and peek or steal buffers from the GstAggregatorPads. If the subclass returns GST_FLOW_EOS, sending of the eos event will be taken care of. Once / if a buffer has been constructed from the aggregated buffers, the subclass should call _finish_buffer. |
`stop` () | Optional. Called when the element goes from PAUSED to READY. The subclass should free all resources and reset its state. |
`start` () | Optional. Called when the element goes from READY to PAUSED. The subclass should get ready to process aggregated buffers. |
`get_next_time` () | Optional. Called when the element needs to know the running time of the next rendered buffer for live pipelines. This causes deadline based aggregation to occur. Defaults to returning GST_CLOCK_TIME_NONE causing the element to wait for buffers on all sink pads before aggregating. |
`create_new_pad` () | Optional. Called when a new pad needs to be created. Allows subclass that don't have a single sink pad template to provide a pad based on the provided information. |
`update_src_caps` () | Lets subclasses update the GstCaps representing the src pad caps before usage. The result should end up in `ret` . Return `GST_AGGREGATOR_FLOW_NEED_DATA` to indicate that the element needs more information (caps, a buffer, etc) to choose the correct caps. Should return ANY caps if the stream has not caps at all. |
`fixate_src_caps` () | Optional. Fixate and return the src pad caps provided. The function takes ownership of `caps` and returns a fixated version of `caps` . `caps` is not guaranteed to be writable. |
`negotiated_src_caps` () | Optional. Notifies subclasses what caps format has been negotiated |
`decide_allocation` () | Optional. Allows the subclass to influence the allocation choices. Setup the allocation parameters for allocating output buffers. The passed in query contains the result of the downstream allocation query. |
`propose_allocation` () | Optional. Allows the subclass to handle the allocation query from upstream. |

### GST_AGGREGATOR_FLOW_NEED_DATA

    #define GST_AGGREGATOR_FLOW_NEED_DATA             GST_FLOW_CUSTOM_ERROR

## Property Details

### The `“latency”` property

      “latency”                  guint64

Additional latency in live mode to allow upstream to take longer to produce buffers for the current position (in nanoseconds).

Flags: Read / Write

Default value: 0

### The `“min-upstream-latency”` property

      “min-upstream-latency”     guint64

Force minimum upstream latency (in nanoseconds). When sources with a higher latency are expected to be plugged in dynamically after the aggregator has started playing, this allows overriding the minimum latency reported by the initial source(s). This is only taken into account when larger than the actually reported minimum latency.

Flags: Read / Write

Default value: 0

Since: 1.16

### The `“start-time”` property

      “start-time”               guint64

Start time to use if start-time-selection=set.

Flags: Read / Write

Default value: 18446744073709551615

### The `“start-time-selection”` property

      “start-time-selection”     GstAggregatorStartTimeSelection

Decides which start time is output.

Flags: Read / Write

Default value: Start at 0 running time (default)

## See Also

gstcollectpads for historical reasons.