This base class is for filter elements that process data. Elements
that are suitable for implementation using #GstBaseTransform are ones
where the size and caps of the output is known entirely from the input
caps and buffer sizes. These include elements that directly transform
one buffer into another, modify the contents of a buffer in-place, as
well as elements that collate multiple input buffers into one output buffer,
or that expand one input buffer into multiple output buffers. See below
for more concrete use cases.
It provides for:
one sinkpad and one srcpad
Possible formats on sink and source pad implemented
with custom transform_caps function. By default uses
same format on sink and source.
Handles state changes
Does flushing
Push mode
Pull mode if the sub-class transform can operate on arbitrary data
Element has no interest in modifying the buffer. It may want to inspect it,
in which case the element should have a transform_ip function. If there
is no transform_ip function in passthrough mode, the buffer is pushed
intact.
The #GstBaseTransformClass.passthrough_on_same_caps variable
will automatically set/unset passthrough based on whether the
element negotiates the same caps on both pads.
#GstBaseTransformClass.passthrough_on_same_caps on an element that
doesn't implement a transform_caps function is useful for elements that
only inspect data (such as level)
Example elements
Level
Videoscale, audioconvert, videoconvert, audioresample in certain modes.
The element must implement a transform_ip function.
Output buffer size must <= input buffer size
If the always_in_place flag is set, non-writable buffers will be copied
and passed to the transform_ip function, otherwise a new buffer will be
created and the transform function called.
Incoming writable buffers will be passed to the transform_ip function
immediately.
only implementing transform_ip and not transform implies always_in_place = true
Example elements:
Volume
Audioconvert in certain modes (signed/unsigned conversion)
videoconvert in certain modes (endianness swapping)
The element does not require writable data, but non-writable buffers
should be subbuffered so that the meta-information can be replaced.
Elements wishing to operate in this mode should replace the
prepare_output_buffer method to create subbuffers of the input buffer
and set always_in_place to true
Example elements
Capsfilter when setting caps on outgoing buffers that have
none.
identity when it is going to re-timestamp buffers by
datarate.
Elements which need to do special allocation of their output buffers
beyond allocating output buffers via the negotiated allocator or
buffer pool should implement the prepare_output_buffer method.
Example elements:
efence
Sub-class settable flags on GstBaseTransform
passthrough
Implies that in the current configuration, the sub-class is not interested in modifying the buffers.
Elements which are always in passthrough mode whenever the same caps has been negotiated on both pads can set the class variable passthrough_on_same_caps to have this behaviour automatically.
always_in_place
Determines whether a non-writable buffer will be copied before passing
to the transform_ip function.
Implied true if no transform function is implemented.
Implied false if ONLY transform function is implemented.
This base class is for filter elements that process data. Elements that are suitable for implementation using #GstBaseTransform are ones where the size and caps of the output is known entirely from the input caps and buffer sizes. These include elements that directly transform one buffer into another, modify the contents of a buffer in-place, as well as elements that collate multiple input buffers into one output buffer, or that expand one input buffer into multiple output buffers. See below for more concrete use cases.
It provides for:
Use Cases
Passthrough mode
Modifications in-place - input buffer and output buffer are the same thing.
Modifications only to the caps/metadata of a buffer
Normal mode
Special output buffer allocations
Sub-class settable flags on GstBaseTransform