Package org.freedesktop.gstreamer.base

Class Aggregator

java.lang.Object

io.github.jwharm.javagi.base.ProxyInstance

org.gnome.gobject.TypeInstance

org.gnome.gobject.GObject

org.gnome.gobject.InitiallyUnowned

org.freedesktop.gstreamer.gst.GstObject

org.freedesktop.gstreamer.gst.Element

org.freedesktop.gstreamer.base.Aggregator

All Implemented Interfaces:

Proxy

Direct Known Subclasses:

Aggregator.AggregatorImpl, AudioAggregator, VideoAggregator

@Generated("io.github.jwharm.JavaGI")
public abstract class Aggregator
extends Element

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.

• When gst_aggregator_pad_peek_buffer() or gst_aggregator_pad_has_buffer() are called, a reference is taken to the returned buffer, which stays valid until either:

• gst_aggregator_pad_pop_buffer() is called, in which case the caller is guaranteed that the buffer they receive is the same as the peeked buffer.
• gst_aggregator_pad_drop_buffer() is called, in which case the caller is guaranteed that the dropped buffer is the one that was peeked.
• the subclass implementation of GstAggregatorClass.aggregate returns.

Subsequent calls to gst_aggregator_pad_peek_buffer() or gst_aggregator_pad_has_buffer() return / check the same buffer that was returned / checked, until one of the conditions listed above is met.

Subclasses are only allowed to call these methods from the aggregate thread.

• 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. Buffer lists can also be pushed out with gst_aggregator_finish_buffer_list().

• 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. In addition, if the gap event was flagged with GST_GAP_FLAG_MISSING_DATA, a custom meta is added to the resulting gap buffer (GstAggregatorMissingDataMeta).

• 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.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	Aggregator.AggregatorClass	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.
static class	Aggregator.AggregatorImpl	The AggregatorImpl type represents a native instance of the abstract Aggregator class.
static class	Aggregator.Builder<B extends Aggregator.Builder<B>>	Inner class implementing a builder pattern to construct a GObject with properties.
static interface	Aggregator.SamplesSelectedCallback	Functional interface declaration of the SamplesSelectedCallback callback.

Nested classes/interfaces inherited from class org.freedesktop.gstreamer.gst.Element

Element.ElementClass, Element.ElementImpl, Element.NoMorePadsCallback, Element.PadAddedCallback, Element.PadRemovedCallback

Nested classes/interfaces inherited from class org.freedesktop.gstreamer.gst.GstObject

GstObject.DeepNotifyCallback, GstObject.ObjectClass, GstObject.ObjectImpl

Nested classes/interfaces inherited from class org.gnome.gobject.InitiallyUnowned

InitiallyUnowned.InitiallyUnownedClass

Nested classes/interfaces inherited from class org.gnome.gobject.GObject

GObject.NotifyCallback

Constructor Summary

Constructors

Constructor	Description
Aggregator(MemorySegment address)	Create a Aggregator proxy instance for the provided memory address.

Method Summary

Modifier and Type	Method	Description
protected FlowReturn	aggregate(boolean timeout)	Mandatory.
protected Aggregator	asParent()	Returns this instance as if it were its parent type.
static Aggregator.Builder<? extends Aggregator.Builder>	builder()	A Aggregator.Builder object constructs a Aggregator with the specified properties.
protected Buffer	clip(AggregatorPad aggregatorPad, Buffer buf)	Optional.
protected AggregatorPad	createNewPad(PadTemplate templ, String reqName, Caps caps)	Optional.
protected boolean	decideAllocation(Query query)	Optional.
void	emitSamplesSelected(Segment segment, long pts, long dts, long duration, @Nullable Structure info)	Emits the "samples-selected" signal.
FlowReturn	finishBuffer(Buffer buffer)	This method will push the provided output buffer downstream.
FlowReturn	finishBufferList(BufferList bufferlist)	This method will push the provided output buffer list downstream.
protected Caps	fixateSrcCaps(Caps caps)	Optional.
protected FlowReturn	flush()	Optional.
void	getAllocator(@Nullable Out<Allocator> allocator, @Nullable AllocationParams params)	Lets GstAggregator sub-classes get the memory allocator acquired by the base class and its params.
BufferPool	getBufferPool()
boolean	getForceLive()	Subclasses may use the return value to inform whether they should return FlowReturn.EOS from their aggregate implementation.
boolean	getIgnoreInactivePads()
ClockTime	getLatency()	Retrieves the latency values reported by this Aggregator 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.
static MemoryLayout	getMemoryLayout()	The memory layout of the native struct.
protected ClockTime	getNextTime()	Optional.
static Type	getType()	Get the GType of the Aggregator class
boolean	negotiate()	Negotiates src pad caps with downstream elements.
protected boolean	negotiatedSrcCaps(Caps caps)	Optional.
SignalConnection<Aggregator.SamplesSelectedCallback>	onSamplesSelected(Aggregator.SamplesSelectedCallback handler)	Signals that the GstAggregator subclass has selected the next set of input samples it will aggregate.
Sample	peekNextSample(AggregatorPad pad)	Use this function to determine what input buffers will be aggregated to produce the next output buffer.
protected boolean	proposeAllocation(AggregatorPad pad, Query decideQuery, Query query)	Optional.
void	selectedSamples(ClockTime pts, ClockTime dts, ClockTime duration, @Nullable Structure info)	Subclasses should call this when they have prepared the buffers they will aggregate for each of their sink pads, but before using any of the properties of the pads that govern how aggregation should be performed, for example z-index for video aggregators.
void	setForceLive(boolean forceLive)	Subclasses should call this at construction time in order for this Aggregator to aggregate on a timeout even when no live source is connected.
void	setIgnoreInactivePads(boolean ignore)	Subclasses should call this when they don't want to time out waiting for a pad that hasn't yet received any buffers in live mode.
void	setLatency(ClockTime minLatency, ClockTime maxLatency)	Lets GstAggregator sub-classes tell the baseclass what their internal latency is.
void	setSrcCaps(Caps caps)	Sets the caps to be used on the src pad.
ClockTime	simpleGetNextTime()	This is a simple GstAggregatorClass::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.
protected boolean	sinkEvent(AggregatorPad aggregatorPad, Event event)	Optional.
protected FlowReturn	sinkEventPreQueue(AggregatorPad aggregatorPad, Event event)	Optional.
protected boolean	sinkQuery(AggregatorPad aggregatorPad, Query query)	Optional.
protected boolean	sinkQueryPreQueue(AggregatorPad aggregatorPad, Query query)	Optional.
protected boolean	srcActivate(PadMode mode, boolean active)	Optional.
protected boolean	srcEvent(Event event)	Optional.
protected boolean	srcQuery(Query query)	Optional.
protected boolean	start()	Optional.
protected boolean	stop()	Optional.
void	updateSegment(Segment segment)	Subclasses should use this to update the segment on their source pad, instead of directly pushing new segment events downstream.
protected FlowReturn	updateSrcCaps(Caps caps, @Nullable Out<Caps> ret)

Methods inherited from class org.freedesktop.gstreamer.gst.Element

abortState, addPad, addPropertyDeepNotifyWatch, addPropertyNotifyWatch, callAsync, changeState, continueState, createAllPads, decorateStreamId, decorateStreamIdPrintf, emitNoMorePads, emitPadAdded, emitPadRemoved, foreachPad, foreachSinkPad, foreachSrcPad, getBaseTime, getBus, getClock, getCompatiblePad, getCompatiblePadTemplate, getContext, getContexts, getContextUnlocked, getCurrentClockTime, getCurrentRunningTime, getFactory, getMetadata, getPadTemplate, getPadTemplateList, getRequestPad, getStartTime, getState, getStaticPad, isLockedState, iteratePads, iterateSinkPads, iterateSrcPads, link, linkFiltered, linkMany, linkPads, linkPadsFiltered, linkPadsFull, linkPadsFull, lostState, makeFromUri, messageFull, messageFull, messageFullWithDetails, messageFullWithDetails, noMorePads, onNoMorePads, onPadAdded, onPadRemoved, padAdded, padRemoved, postMessage, provideClock, query, queryConvert, queryDuration, queryPosition, register, releasePad, releaseRequestPad, removePad, removePropertyNotifyWatch, requestPad, requestPadSimple, seek, seek, seekSimple, seekSimple, sendEvent, setBaseTime, setBus, setClock, setContext, setLockedState, setStartTime, setState, stateChanged, stateChangeReturnGetName, stateGetName, syncStateWithParent, typeSetSkipDocumentation, unlink, unlinkMany, unlinkPads

Methods inherited from class org.freedesktop.gstreamer.gst.GstObject

addControlBinding, checkUniqueness, deepNotify, defaultDeepNotify, defaultError, emitDeepNotify, getControlBinding, getControlRate, getGValueArray, getName, getParent, getPathString, getValue, getValueArray, hasActiveControlBindings, hasAncestor, hasAsAncestor, hasAsParent, onDeepNotify, ref, refSink, removeControlBinding, replace, setControlBindingDisabled, setControlBindingsDisabled, setControlRate, setName, setParent, suggestNextSync, syncValues, unparent, unref

Methods inherited from class org.gnome.gobject.GObject

addToggleRef, addWeakPointer, bindProperty, bindProperty, bindProperty, bindPropertyFull, bindPropertyFull, bindPropertyWithClosures, bindPropertyWithClosures, compatControl, connect, connect, connect, constructed, disconnect, dispatchPropertiesChanged, dispose, dupData, dupQdata, emit, emitNotify, finalize_, forceFloating, freezeNotify, get, getData, getProperty, getProperty, getProperty, getQdata, getv, interfaceFindProperty, interfaceInstallProperty, interfaceListProperties, isFloating, newInstance, newInstance, newv, notify, notify, notifyByPspec, onNotify, refSink, removeToggleRef, removeWeakPointer, replaceData, replaceQdata, runDispose, set, setData, setDataFull, setProperty, setProperty, setProperty, setQdata, setQdataFull, setv, stealData, stealQdata, takeRef, thawNotify, watchClosure, weakRef, weakUnref, withProperties

Methods inherited from class org.gnome.gobject.TypeInstance

callParent, callParent, getPrivate, readGClass, writeGClass

Methods inherited from class io.github.jwharm.javagi.base.ProxyInstance

equals, handle, hashCode

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Details

Aggregator

public Aggregator(MemorySegment address)

Create a Aggregator proxy instance for the provided memory address.

Parameters:

address - the memory address of the native object

Method Details

getType

public static Type getType()

Get the GType of the Aggregator class

Returns:

the GType

getMemoryLayout

public static MemoryLayout getMemoryLayout()

The memory layout of the native struct.

Returns:

the memory layout

asParent

protected Aggregator asParent()

Returns this instance as if it were its parent type. This is mostly synonymous to the Java super keyword, but will set the native typeclass function pointers to the parent type. When overriding a native virtual method in Java, "chaining up" with super.methodName() doesn't work, because it invokes the overridden function pointer again. To chain up, call asParent().methodName(). This will call the native function pointer of this virtual method in the typeclass of the parent type.

Overrides:

asParent in class Element

finishBuffer

public FlowReturn finishBuffer(Buffer 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:

buffer - the GstBuffer to push.

finishBufferList

public FlowReturn finishBufferList(BufferList bufferlist)

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

Parameters:

bufferlist - the GstBufferList to push.

getAllocator

public void getAllocator(@Nullable
 @Nullable Out<Allocator> allocator,
 @Nullable
 @Nullable AllocationParams params)

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

Unref the allocator after use it.

Parameters:

allocator - the GstAllocator used

params - the GstAllocationParams of allocator

getBufferPool

public BufferPool getBufferPool()

getForceLive

public boolean getForceLive()

Subclasses may use the return value to inform whether they should return FlowReturn.EOS from their aggregate implementation.

Returns:

whether live status was forced on this Aggregator.

getIgnoreInactivePads

public boolean getIgnoreInactivePads()

getLatency

public ClockTime getLatency()

Retrieves the latency values reported by this Aggregator 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.

Returns:

The latency or GST_CLOCK_TIME_NONE if the element does not sync

negotiate

public boolean negotiate()

Negotiates src pad caps with downstream elements. Unmarks GST_PAD_FLAG_NEED_RECONFIGURE in any case. But marks it again if GstAggregatorClass::negotiate fails.

Returns:

true if the negotiation succeeded, else false.

peekNextSample

public Sample peekNextSample(AggregatorPad pad)

Use this function to determine what input buffers will be aggregated to produce the next output buffer. This should only be called from a GstAggregator::samples-selected handler, and can be used to precisely control aggregating parameters for a given set of input samples.

Returns:

The sample that is about to be aggregated. It may hold a GstBuffer or a GstBufferList. The contents of its info structure is subclass-dependent, and documented on a subclass basis. The buffers held by the sample are not writable.

selectedSamples

public void selectedSamples(ClockTime pts,
 ClockTime dts,
 ClockTime duration,
 @Nullable
 @Nullable Structure info)

Subclasses should call this when they have prepared the buffers they will aggregate for each of their sink pads, but before using any of the properties of the pads that govern how aggregation should be performed, for example z-index for video aggregators.

If gst_aggregator_update_segment() is used by the subclass, it MUST be called before gst_aggregator_selected_samples().

This function MUST only be called from the GstAggregatorClass::aggregate() function.

Parameters:

pts - The presentation timestamp of the next output buffer

dts - The decoding timestamp of the next output buffer

duration - The duration of the next output buffer

info - a GstStructure containing additional information

setForceLive

public void setForceLive(boolean forceLive)

Subclasses should call this at construction time in order for this Aggregator to aggregate on a timeout even when no live source is connected.

setIgnoreInactivePads

public void setIgnoreInactivePads(boolean ignore)

Subclasses should call this when they don't want to time out waiting for a pad that hasn't yet received any buffers in live mode.

GstAggregator will still wait once on each newly-added pad, making sure upstream has had a fair chance to start up.

Parameters:

ignore - whether inactive pads should not be waited on

setLatency

public void setLatency(ClockTime minLatency,
 ClockTime maxLatency)

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 if the values changed.

Parameters:

minLatency - minimum latency

maxLatency - maximum latency

setSrcCaps

public void setSrcCaps(Caps caps)

Sets the caps to be used on the src pad.

Parameters:

caps - The GstCaps to set on the src pad.

simpleGetNextTime

public ClockTime simpleGetNextTime()

This is a simple GstAggregatorClass::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.

Returns:

The running time based on the position

updateSegment

public void updateSegment(Segment segment)

Subclasses should use this to update the segment on their source pad, instead of directly pushing new segment events downstream.

Subclasses MUST call this before gst_aggregator_selected_samples(), if it is used at all.

aggregate

protected FlowReturn aggregate(boolean timeout)

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.

clip

protected Buffer clip(AggregatorPad aggregatorPad,
 Buffer buf)

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.

createNewPad

protected AggregatorPad createNewPad(PadTemplate templ,
 String reqName,
 Caps caps)

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.

decideAllocation

protected boolean decideAllocation(Query query)

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.

fixateSrcCaps

protected Caps fixateSrcCaps(Caps 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.

flush

protected FlowReturn flush()

Optional. Called after a successful flushing seek, once all the flush stops have been received. Flush pad-specific data in GstAggregatorPad->flush.

getNextTime

protected ClockTime getNextTime()

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.

negotiatedSrcCaps

protected boolean negotiatedSrcCaps(Caps caps)

Optional. Notifies subclasses what caps format has been negotiated

proposeAllocation

protected boolean proposeAllocation(AggregatorPad pad,
 Query decideQuery,
 Query query)

Optional. Allows the subclass to handle the allocation query from upstream.

sinkEvent

protected boolean sinkEvent(AggregatorPad aggregatorPad,
 Event event)

Optional. Called when an event is received on a sink pad, the subclass should always chain up.

sinkEventPreQueue

protected FlowReturn sinkEventPreQueue(AggregatorPad aggregatorPad,
 Event event)

Optional. Called when an event is received on a sink pad before queueing up serialized events. The subclass should always chain up (Since: 1.18).

sinkQuery

protected boolean sinkQuery(AggregatorPad aggregatorPad,
 Query query)

Optional. Called when a query is received on a sink pad, the subclass should always chain up.

sinkQueryPreQueue

protected boolean sinkQueryPreQueue(AggregatorPad aggregatorPad,
 Query query)

Optional. Called when a query is received on a sink pad before queueing up serialized queries. The subclass should always chain up (Since: 1.18).

srcActivate

protected boolean srcActivate(PadMode mode,
 boolean active)

Optional. Called when the src pad is activated, it will start/stop its pad task right after that call.

srcEvent

protected boolean srcEvent(Event event)

Optional. Called when an event is received on the src pad, the subclass should always chain up.

srcQuery

protected boolean srcQuery(Query query)

Optional. Called when a query is received on the src pad, the subclass should always chain up.

start

protected boolean start()

Optional. Called when the element goes from READY to PAUSED. The subclass should get ready to process aggregated buffers.

stop

protected boolean stop()

Optional. Called when the element goes from PAUSED to READY. The subclass should free all resources and reset its state.

updateSrcCaps

protected FlowReturn updateSrcCaps(Caps caps,
 @Nullable
 @Nullable Out<Caps> ret)

onSamplesSelected

public SignalConnection<Aggregator.SamplesSelectedCallback> onSamplesSelected(Aggregator.SamplesSelectedCallback handler)

Signals that the GstAggregator subclass has selected the next set of input samples it will aggregate. Handlers may call gst_aggregator_peek_next_sample() at that point.

Parameters:

handler - the signal handler

Returns:

a signal handler ID to keep track of the signal connection

See Also:

• Aggregator.SamplesSelectedCallback.run(org.freedesktop.gstreamer.gst.Segment, long, long, long, org.freedesktop.gstreamer.gst.Structure)

emitSamplesSelected

public void emitSamplesSelected(Segment segment,
 long pts,
 long dts,
 long duration,
 @Nullable
 @Nullable Structure info)

Emits the "samples-selected" signal. See onSamplesSelected(org.freedesktop.gstreamer.base.Aggregator.SamplesSelectedCallback).

builder

public static Aggregator.Builder<? extends Aggregator.Builder> builder()

A Aggregator.Builder object constructs a Aggregator with the specified properties. Use the various set...() methods to set properties, and finish construction with Aggregator.Builder.build().