Copyright | Will Thompson, Iñaki García Etxebarria and Jonas Platte |
---|---|
License | LGPL-2.1 |
Maintainer | Iñaki García Etxebarria (garetxe@gmail.com) |
Safe Haskell | None |
Language | Haskell2010 |
This base class is for filter elements that process data. Elements
that are suitable for implementation using BaseTransform
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: <itemizedlist> <listitem><para>one sinkpad and one srcpad</para></listitem> <listitem><para> Possible formats on sink and source pad implemented with custom transform_caps function. By default uses same format on sink and source. </para></listitem> <listitem><para>Handles state changes</para></listitem> <listitem><para>Does flushing</para></listitem> <listitem><para>Push mode</para></listitem> <listitem><para> Pull mode if the sub-class transform can operate on arbitrary data </para></listitem> </itemizedlist>
<refsect2>
<title>Use Cases</title>
<para>
<orderedlist>
<listitem>
<itemizedlist><title>Passthrough mode</title>
<listitem><para>
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.
</para></listitem>
<listitem><para>
The BaseTransformClass
.passthrough_on_same_caps
variable
will automatically set/unset passthrough based on whether the
element negotiates the same caps on both pads.
</para></listitem>
<listitem><para>
BaseTransformClass
.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)
</para></listitem>
</itemizedlist>
<itemizedlist>
<title>Example elements</title>
<listitem>Level</listitem>
<listitem>Videoscale, audioconvert, videoconvert, audioresample in
certain modes.</listitem>
</itemizedlist>
</listitem>
<listitem>
<itemizedlist>
<title>Modifications in-place - input buffer and output buffer are the
same thing.</title>
<listitem><para>
The element must implement a transform_ip function.
</para></listitem>
<listitem><para>
Output buffer size must <= input buffer size
</para></listitem>
<listitem><para>
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.
</para></listitem>
<listitem><para>
Incoming writable buffers will be passed to the transform_ip function
immediately. </para></listitem>
<listitem><para>
only implementing transform_ip and not transform implies always_in_place
= True
</para></listitem>
</itemizedlist>
<itemizedlist>
<title>Example elements</title>
<listitem>Volume</listitem>
<listitem>Audioconvert in certain modes (signed/unsigned
conversion)</listitem>
<listitem>videoconvert in certain modes (endianness
swapping)</listitem>
</itemizedlist>
</listitem>
<listitem>
<itemizedlist>
<title>Modifications only to the caps/metadata of a buffer</title>
<listitem><para>
The element does not require writable data, but non-writable buffers
should be subbuffered so that the meta-information can be replaced.
</para></listitem>
<listitem><para>
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
</para></listitem>
</itemizedlist>
<itemizedlist>
<title>Example elements</title>
<listitem>Capsfilter when setting caps on outgoing buffers that have
none.</listitem>
<listitem>identity when it is going to re-timestamp buffers by
datarate.</listitem>
</itemizedlist>
</listitem>
<listitem>
<itemizedlist><title>Normal mode</title>
<listitem><para>
always_in_place flag is not set, or there is no transform_ip function
</para></listitem>
<listitem><para>
Element will receive an input buffer and output buffer to operate on.
</para></listitem>
<listitem><para>
Output buffer is allocated by calling the prepare_output_buffer function.
</para></listitem>
</itemizedlist>
<itemizedlist>
<title>Example elements</title>
<listitem>Videoscale, videoconvert, audioconvert when doing
scaling/conversions</listitem>
</itemizedlist>
</listitem>
<listitem>
<itemizedlist><title>Special output buffer allocations</title>
<listitem><para>
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.
</para></listitem>
</itemizedlist>
<itemizedlist>
<title>Example elements</title>
<listitem>efence</listitem>
</itemizedlist>
</listitem>
</orderedlist>
</para>
</refsect2>
<refsect2>
<title>Sub-class settable flags on GstBaseTransform</title>
<para>
<itemizedlist>
<listitem><para>
<itemizedlist><title>passthrough</title>
<listitem><para>
Implies that in the current configuration, the sub-class is not
interested in modifying the buffers.
</para></listitem>
<listitem><para>
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.
</para></listitem>
</itemizedlist>
</para></listitem>
<listitem><para>
<itemizedlist><title>always_in_place</title>
<listitem><para>
Determines whether a non-writable buffer will be copied before passing
to the transform_ip function.
</para></listitem>
<listitem><para>
Implied True
if no transform function is implemented.
</para></listitem>
<listitem><para>
Implied False
if ONLY transform function is implemented.
</para></listitem>
</itemizedlist>
</para></listitem>
</itemizedlist>
</para>
</refsect2>
- newtype BaseTransform = BaseTransform (ManagedPtr BaseTransform)
- class GObject o => IsBaseTransform o
- toBaseTransform :: IsBaseTransform o => o -> IO BaseTransform
- noBaseTransform :: Maybe BaseTransform
- data BaseTransformGetAllocatorMethodInfo
- baseTransformGetAllocator :: (HasCallStack, MonadIO m, IsBaseTransform a) => a -> m (Allocator, AllocationParams)
- data BaseTransformGetBufferPoolMethodInfo
- baseTransformGetBufferPool :: (HasCallStack, MonadIO m, IsBaseTransform a) => a -> m BufferPool
- data BaseTransformIsInPlaceMethodInfo
- baseTransformIsInPlace :: (HasCallStack, MonadIO m, IsBaseTransform a) => a -> m Bool
- data BaseTransformIsPassthroughMethodInfo
- baseTransformIsPassthrough :: (HasCallStack, MonadIO m, IsBaseTransform a) => a -> m Bool
- data BaseTransformIsQosEnabledMethodInfo
- baseTransformIsQosEnabled :: (HasCallStack, MonadIO m, IsBaseTransform a) => a -> m Bool
- data BaseTransformReconfigureSinkMethodInfo
- baseTransformReconfigureSink :: (HasCallStack, MonadIO m, IsBaseTransform a) => a -> m ()
- data BaseTransformReconfigureSrcMethodInfo
- baseTransformReconfigureSrc :: (HasCallStack, MonadIO m, IsBaseTransform a) => a -> m ()
- data BaseTransformSetGapAwareMethodInfo
- baseTransformSetGapAware :: (HasCallStack, MonadIO m, IsBaseTransform a) => a -> Bool -> m ()
- data BaseTransformSetInPlaceMethodInfo
- baseTransformSetInPlace :: (HasCallStack, MonadIO m, IsBaseTransform a) => a -> Bool -> m ()
- data BaseTransformSetPassthroughMethodInfo
- baseTransformSetPassthrough :: (HasCallStack, MonadIO m, IsBaseTransform a) => a -> Bool -> m ()
- data BaseTransformSetPreferPassthroughMethodInfo
- baseTransformSetPreferPassthrough :: (HasCallStack, MonadIO m, IsBaseTransform a) => a -> Bool -> m ()
- data BaseTransformSetQosEnabledMethodInfo
- baseTransformSetQosEnabled :: (HasCallStack, MonadIO m, IsBaseTransform a) => a -> Bool -> m ()
- data BaseTransformUpdateQosMethodInfo
- baseTransformUpdateQos :: (HasCallStack, MonadIO m, IsBaseTransform a) => a -> Double -> Int64 -> Word64 -> m ()
- data BaseTransformUpdateSrcCapsMethodInfo
- baseTransformUpdateSrcCaps :: (HasCallStack, MonadIO m, IsBaseTransform a) => a -> Caps -> m Bool
- data BaseTransformQosPropertyInfo
- baseTransformQos :: AttrLabelProxy "qos"
- constructBaseTransformQos :: IsBaseTransform o => Bool -> IO (GValueConstruct o)
- getBaseTransformQos :: (MonadIO m, IsBaseTransform o) => o -> m Bool
- setBaseTransformQos :: (MonadIO m, IsBaseTransform o) => o -> Bool -> m ()
Exported types
newtype BaseTransform Source #
GObject BaseTransform Source # | |
IsObject BaseTransform Source # | |
IsElement BaseTransform Source # | |
IsObject BaseTransform Source # | |
IsBaseTransform BaseTransform Source # | |
((~) * info (ResolveBaseTransformMethod t BaseTransform), MethodInfo * info BaseTransform p) => IsLabel t (BaseTransform -> p) Source # | |
((~) * info (ResolveBaseTransformMethod t BaseTransform), MethodInfo * info BaseTransform p) => IsLabelProxy t (BaseTransform -> p) Source # | |
HasAttributeList * BaseTransform Source # | |
type AttributeList BaseTransform Source # | |
type SignalList BaseTransform Source # | |
class GObject o => IsBaseTransform o Source #
toBaseTransform :: IsBaseTransform o => o -> IO BaseTransform Source #
Methods
getAllocator
data BaseTransformGetAllocatorMethodInfo Source #
((~) * signature (m (Allocator, AllocationParams)), MonadIO m, IsBaseTransform a) => MethodInfo * BaseTransformGetAllocatorMethodInfo a signature Source # | |
baseTransformGetAllocator Source #
:: (HasCallStack, MonadIO m, IsBaseTransform a) | |
=> a |
|
-> m (Allocator, AllocationParams) |
Lets BaseTransform
sub-classes to know the memory allocator
used by the base class and its params
.
Unref the allocator
after use it.
getBufferPool
data BaseTransformGetBufferPoolMethodInfo Source #
((~) * signature (m BufferPool), MonadIO m, IsBaseTransform a) => MethodInfo * BaseTransformGetBufferPoolMethodInfo a signature Source # | |
baseTransformGetBufferPool Source #
:: (HasCallStack, MonadIO m, IsBaseTransform a) | |
=> a |
|
-> m BufferPool | Returns: the instance of the |
No description available in the introspection data.
isInPlace
data BaseTransformIsInPlaceMethodInfo Source #
((~) * signature (m Bool), MonadIO m, IsBaseTransform a) => MethodInfo * BaseTransformIsInPlaceMethodInfo a signature Source # | |
baseTransformIsInPlace Source #
:: (HasCallStack, MonadIO m, IsBaseTransform a) | |
=> a |
|
-> m Bool | Returns: MT safe. |
See if trans
is configured as a in_place transform.
isPassthrough
data BaseTransformIsPassthroughMethodInfo Source #
((~) * signature (m Bool), MonadIO m, IsBaseTransform a) => MethodInfo * BaseTransformIsPassthroughMethodInfo a signature Source # | |
baseTransformIsPassthrough Source #
:: (HasCallStack, MonadIO m, IsBaseTransform a) | |
=> a |
|
-> m Bool | Returns: MT safe. |
See if trans
is configured as a passthrough transform.
isQosEnabled
data BaseTransformIsQosEnabledMethodInfo Source #
((~) * signature (m Bool), MonadIO m, IsBaseTransform a) => MethodInfo * BaseTransformIsQosEnabledMethodInfo a signature Source # | |
baseTransformIsQosEnabled Source #
:: (HasCallStack, MonadIO m, IsBaseTransform a) | |
=> a |
|
-> m Bool | Returns: MT safe. |
Queries if the transform will handle QoS.
reconfigureSink
data BaseTransformReconfigureSinkMethodInfo Source #
((~) * signature (m ()), MonadIO m, IsBaseTransform a) => MethodInfo * BaseTransformReconfigureSinkMethodInfo a signature Source # | |
baseTransformReconfigureSink Source #
:: (HasCallStack, MonadIO m, IsBaseTransform a) | |
=> a |
|
-> m () |
Instructs trans
to request renegotiation upstream. This function is
typically called after properties on the transform were set that
influence the input format.
reconfigureSrc
data BaseTransformReconfigureSrcMethodInfo Source #
((~) * signature (m ()), MonadIO m, IsBaseTransform a) => MethodInfo * BaseTransformReconfigureSrcMethodInfo a signature Source # | |
baseTransformReconfigureSrc Source #
:: (HasCallStack, MonadIO m, IsBaseTransform a) | |
=> a |
|
-> m () |
Instructs trans
to renegotiate a new downstream transform on the next
buffer. This function is typically called after properties on the transform
were set that influence the output format.
setGapAware
data BaseTransformSetGapAwareMethodInfo Source #
((~) * signature (Bool -> m ()), MonadIO m, IsBaseTransform a) => MethodInfo * BaseTransformSetGapAwareMethodInfo a signature Source # | |
baseTransformSetGapAware Source #
:: (HasCallStack, MonadIO m, IsBaseTransform a) | |
=> a |
|
-> Bool |
|
-> m () |
If gapAware
is False
(the default), output buffers will have the
BufferFlagsGap
flag unset.
If set to True
, the element must handle output buffers with this flag set
correctly, i.e. it can assume that the buffer contains neutral data but must
unset the flag if the output is no neutral data.
MT safe.
setInPlace
data BaseTransformSetInPlaceMethodInfo Source #
((~) * signature (Bool -> m ()), MonadIO m, IsBaseTransform a) => MethodInfo * BaseTransformSetInPlaceMethodInfo a signature Source # | |
baseTransformSetInPlace Source #
:: (HasCallStack, MonadIO m, IsBaseTransform a) | |
=> a |
|
-> Bool |
|
-> m () |
setPassthrough
data BaseTransformSetPassthroughMethodInfo Source #
((~) * signature (Bool -> m ()), MonadIO m, IsBaseTransform a) => MethodInfo * BaseTransformSetPassthroughMethodInfo a signature Source # | |
baseTransformSetPassthrough Source #
:: (HasCallStack, MonadIO m, IsBaseTransform a) | |
=> a |
|
-> Bool |
|
-> m () |
Set passthrough mode for this filter by default. This is mostly useful for filters that do not care about negotiation.
Always True
for filters which don't implement either a transform
or transform_ip method.
MT safe.
setPreferPassthrough
data BaseTransformSetPreferPassthroughMethodInfo Source #
((~) * signature (Bool -> m ()), MonadIO m, IsBaseTransform a) => MethodInfo * BaseTransformSetPreferPassthroughMethodInfo a signature Source # | |
baseTransformSetPreferPassthrough Source #
:: (HasCallStack, MonadIO m, IsBaseTransform a) | |
=> a |
|
-> Bool |
|
-> m () |
If preferPassthrough
is True
(the default), trans
will check and
prefer passthrough caps from the list of caps returned by the
transform_caps vmethod.
If set to False
, the element must order the caps returned from the
transform_caps function in such a way that the preferred format is
first in the list. This can be interesting for transforms that can do
passthrough transforms but prefer to do something else, like a
capsfilter.
MT safe.
Since: 1.0.1
setQosEnabled
data BaseTransformSetQosEnabledMethodInfo Source #
((~) * signature (Bool -> m ()), MonadIO m, IsBaseTransform a) => MethodInfo * BaseTransformSetQosEnabledMethodInfo a signature Source # | |
baseTransformSetQosEnabled Source #
:: (HasCallStack, MonadIO m, IsBaseTransform a) | |
=> a |
|
-> Bool |
|
-> m () |
Enable or disable QoS handling in the transform.
MT safe.
updateQos
data BaseTransformUpdateQosMethodInfo Source #
((~) * signature (Double -> Int64 -> Word64 -> m ()), MonadIO m, IsBaseTransform a) => MethodInfo * BaseTransformUpdateQosMethodInfo a signature Source # | |
baseTransformUpdateQos Source #
:: (HasCallStack, MonadIO m, IsBaseTransform a) | |
=> a |
|
-> Double |
|
-> Int64 |
|
-> Word64 |
|
-> m () |
Set the QoS parameters in the transform. This function is called internally when a QOS event is received but subclasses can provide custom information when needed.
MT safe.
updateSrcCaps
data BaseTransformUpdateSrcCapsMethodInfo Source #
((~) * signature (Caps -> m Bool), MonadIO m, IsBaseTransform a) => MethodInfo * BaseTransformUpdateSrcCapsMethodInfo a signature Source # | |
baseTransformUpdateSrcCaps Source #
:: (HasCallStack, MonadIO m, IsBaseTransform a) | |
=> a |
|
-> Caps |
|
-> m Bool | Returns: |
Updates the srcpad caps and send the caps downstream. This function can be used by subclasses when they have already negotiated their caps but found a change in them (or computed new informations). This way, they can notify downstream about that change without loosing any buffer.
Since: 1.6
Properties
qos
data BaseTransformQosPropertyInfo Source #
baseTransformQos :: AttrLabelProxy "qos" Source #
constructBaseTransformQos :: IsBaseTransform o => Bool -> IO (GValueConstruct o) Source #
getBaseTransformQos :: (MonadIO m, IsBaseTransform o) => o -> m Bool Source #
setBaseTransformQos :: (MonadIO m, IsBaseTransform o) => o -> Bool -> m () Source #