GstBaseTransform

GstBaseTransform — Base class for simple transform filters

Synopsis


#include <gst/base/gstbasetransform.h>


            GstBaseTransform;
gboolean    gst_base_transform_is_passthrough
                                            (GstBaseTransform *trans);
void        gst_base_transform_set_passthrough
                                            (GstBaseTransform *trans,
                                             gboolean passthrough);
gboolean    gst_base_transform_is_in_place  (GstBaseTransform *trans);
void        gst_base_transform_set_in_place (GstBaseTransform *trans,
                                             gboolean in_place);
#define     GST_BASE_TRANSFORM_SINK_NAME
#define     GST_BASE_TRANSFORM_SRC_NAME


Description

This base class is for filter elements that process data.

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

Use Cases:

  1. Passthrough mode

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

    • On the GstBaseTransformClass is the passthrough_on_same_caps variable which will automatically set/unset passthrough based on whether the element negotiates the same caps on both pads.

    • 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, ffmpegcolorspace, audioresample in certain modes.
  2. Modifications in-place - input buffer and output buffer are the same thing.

    • 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)
    • ffmpegcolorspace in certain modes (endianness swapping)
  3. Modifications only to the caps/metadata of a buffer

    • 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.
  4. Normal mode

    • always_in_place flag is not set, or there is no transform_ip function

    • Element will receive an input buffer and output buffer to operate on.

    • Output buffer is allocated by calling the prepare_output_buffer function.

    Example elements

    • Videoscale, ffmpegcolorspace, audioconvert when doing scaling/conversions
  5. Special output buffer allocations

    • Elements which need to do special allocation of their output buffers other than what gst_buffer_pad_alloc allows should implement a prepare_output_buffer method, which calls the parent implementation and passes the newly allocated buffer.

    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.

Details

GstBaseTransform

typedef struct {
  GstElement	 element;
} GstBaseTransform;

The opaque GstBaseTransform data structure.

GstElement element; the parent element.

gst_base_transform_is_passthrough ()

gboolean    gst_base_transform_is_passthrough
                                            (GstBaseTransform *trans);

See if trans is configured as a passthrough transform.

trans : the GstBaseTransform to query
Returns : TRUE is the transform is configured in passthrough mode. MT safe.

gst_base_transform_set_passthrough ()

void        gst_base_transform_set_passthrough
                                            (GstBaseTransform *trans,
                                             gboolean passthrough);

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.

trans : the GstBaseTransform to set
passthrough : boolean indicating passthrough mode.

gst_base_transform_is_in_place ()

gboolean    gst_base_transform_is_in_place  (GstBaseTransform *trans);

See if trans is configured as a in_place transform.

trans : the GstBaseTransform to query
Returns : TRUE is the transform is configured in in_place mode. MT safe.

gst_base_transform_set_in_place ()

void        gst_base_transform_set_in_place (GstBaseTransform *trans,
                                             gboolean in_place);

Determines whether a non-writable buffer will be copied before passing to the transform_ip function.

  • Always TRUE if no transform function is implemented.
  • Always FALSE if ONLY transform_ip function is implemented.

MT safe.

trans : the GstBaseTransform to modify
in_place : Boolean value indicating that we would like to operate on in_place buffers.

GST_BASE_TRANSFORM_SINK_NAME

#define GST_BASE_TRANSFORM_SINK_NAME	"sink"

the name of the templates for the sink pad


GST_BASE_TRANSFORM_SRC_NAME

#define GST_BASE_TRANSFORM_SRC_NAME	"src"

the name of the templates for the source pad

See Also

GstBaseSrc, GstBaseSink