## GstBaseTransform

GstBaseTransform — Base class for simple transform filters

## Synopsis

    #include <gst/base/gstbasetransform.h>

                        GstBaseTransform;
                        GstBaseTransformClass;
    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);
    gboolean            gst_base_transform_is_qos_enabled   (GstBaseTransform *trans);
    void                gst_base_transform_set_qos_enabled  (GstBaseTransform *trans,
                                                             gboolean enabled);
    void                gst_base_transform_update_qos       (GstBaseTransform *trans,
                                                             gdouble proportion,
                                                             GstClockTimeDiff diff,
                                                             GstClockTime timestamp);
    #define             GST_BASE_TRANSFORM_SINK_NAME
    #define             GST_BASE_TRANSFORM_SRC_NAME
    #define             GST_BASE_TRANSFORM_SINK_PAD         (obj)
    #define             GST_BASE_TRANSFORM_SRC_PAD          (obj)
    #define             GST_BASE_TRANSFORM_FLOW_DROPPED
    #define             GST_BASE_TRANSFORM_LOCK             (obj)
    #define             GST_BASE_TRANSFORM_UNLOCK           (obj)

## Object Hierarchy

      GObject
       +----GstObject
             +----GstElement
                   +----GstBaseTransform

## Properties

      "qos"                      gboolean              : Read / Write

## 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 _GstBaseTransform GstBaseTransform;

The opaque GstBaseTransform data structure.

### GstBaseTransformClass

    typedef struct {
      GstElementClass parent_class;

      /* virtual methods for subclasses */

      GstCaps*	(*transform_caps) (GstBaseTransform *trans,
                                       GstPadDirection direction,
                                       GstCaps *caps);

      void		(*fixate_caps)	  (GstBaseTransform *trans,
                                       GstPadDirection direction, GstCaps *caps,
                                       GstCaps *othercaps);

      gboolean      (*transform_size) (GstBaseTransform *trans,
                                       GstPadDirection direction,
                                       GstCaps *caps, guint size,
                                       GstCaps *othercaps, guint *othersize);

      gboolean      (*get_unit_size)  (GstBaseTransform *trans, GstCaps *caps,
                                       guint *size);

      gboolean      (*set_caps)     (GstBaseTransform *trans, GstCaps *incaps,
                                     GstCaps *outcaps);

      gboolean      (*start)        (GstBaseTransform *trans);
      gboolean      (*stop)         (GstBaseTransform *trans);

      gboolean      (*event)        (GstBaseTransform *trans, GstEvent *event);

      GstFlowReturn (*transform)    (GstBaseTransform *trans, GstBuffer *inbuf,
                                     GstBuffer *outbuf);
      GstFlowReturn (*transform_ip) (GstBaseTransform *trans, GstBuffer *buf);

      /* FIXME: When adjusting the padding, move these to nicer places in the class */
      gboolean       passthrough_on_same_caps;

      GstFlowReturn (*prepare_output_buffer) (GstBaseTransform * trans,
         GstBuffer *input, gint size, GstCaps *caps, GstBuffer **buf);

      /* src event */
      gboolean      (*src_event)      (GstBaseTransform *trans, GstEvent *event);
    } GstBaseTransformClass;

Subclasses can override any of the available virtual methods or not, as needed. At minimum either `transform` or `transform_ip` need to be overridden. If the element can overwrite the input data with the results (data is of the same type and quantity) it should provide `transform_ip`.

GstElementClass `parent_class`; |
`transform_caps` () | Optional. given the pad in this direction and the given caps, what caps are allowed on the other pad in this element ?
`fixate_caps` () | Optional. Given the pad in this direction and the given caps, fixate the caps on the other pad.
`transform_size` () | Optional. given the size of a buffer in the given direction with the given caps, calculate the size in bytes of a buffer on the other pad with the given other caps. The default implementation uses get_unit_size and keeps the number of units the same.
`get_unit_size` () | Required if the transform is not in-place. get the size in bytes of one unit for the given caps.
`set_caps` () | allows the subclass to be notified of the actual caps set.
`start` () | Optional. Called when the element starts processing. Allows opening external resources.
`stop` () | Optional. Called when the element stops processing. Allows closing external resources.
`event` () | Optional. Event handler on the sink pad. This function should return TRUE if the base class should forward the event.
`transform` () | Required if the element does not operate in-place. Transforms one incoming buffer to one outgoing buffer. The function is allowed to change size/timestamp/duration of the outgoing buffer.
`transform_ip` () | Required if the element operates in-place. Transform the incoming buffer in-place.
gboolean `passthrough_on_same_caps`; | If set to TRUE, passthrough mode will be automatically enabled if the caps are the same.
`prepare_output_buffer` () | Optional. Subclasses can override this to do their own allocation of output buffers. Elements that only do analysis can return a subbuffer or even just increment the reference to the input buffer (if in passthrough mode)
`src_event` () | Optional. Event handler on the source pad.

### 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_is_qos_enabled ()

    gboolean            gst_base_transform_is_qos_enabled   (GstBaseTransform *trans);

Queries if the transform will handle QoS.

`trans` : | a GstBaseTransform
Returns : | TRUE if QoS is enabled.

Since 0.10.5 MT safe.

### gst_base_transform_set_qos_enabled ()

    void                gst_base_transform_set_qos_enabled  (GstBaseTransform *trans,
                                                             gboolean enabled);

Enable or disable QoS handling in the transform.

`trans` : | a GstBaseTransform
`enabled` : | new state

Since 0.10.5 MT safe.

### gst_base_transform_update_qos ()

    void                gst_base_transform_update_qos       (GstBaseTransform *trans,
                                                             gdouble proportion,
                                                             GstClockTimeDiff diff,
                                                             GstClockTime timestamp);

Set the QoS parameters in the transform.

`trans` : | a GstBaseTransform
`proportion` : | the proportion
`diff` : | the diff against the clock
`timestamp` : | the timestamp of the buffer generating the QoS

Since 0.10.5 MT safe.

### 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

### GST_BASE_TRANSFORM_SINK_PAD()

    #define GST_BASE_TRANSFORM_SINK_PAD(obj)	(GST_BASE_TRANSFORM_CAST (obj)->sinkpad)

Gives the pointer to the sink GstPad object of the element.

`obj` : | base transform instance

Since 0.10.4

### GST_BASE_TRANSFORM_SRC_PAD()

    #define GST_BASE_TRANSFORM_SRC_PAD(obj)		(GST_BASE_TRANSFORM_CAST (obj)->srcpad)

Gives the pointer to the source GstPad object of the element.

`obj` : | base transform instance

Since 0.10.4

### GST_BASE_TRANSFORM_FLOW_DROPPED

    #define GST_BASE_TRANSFORM_FLOW_DROPPED   GST_FLOW_CUSTOM_SUCCESS

A GstFlowReturn that can be returned from transform and transform_ip to indicate that no output buffer was generated.

Since 0.10.13

### GST_BASE_TRANSFORM_LOCK()

    #define GST_BASE_TRANSFORM_LOCK(obj)   g_mutex_lock (GST_BASE_TRANSFORM_CAST (obj)->transform_lock)

Obtain a lock to protect the transform function from concurrent access.

`obj` : | base transform instance

Since 0.10.13

### GST_BASE_TRANSFORM_UNLOCK()

    #define GST_BASE_TRANSFORM_UNLOCK(obj) g_mutex_unlock (GST_BASE_TRANSFORM_CAST (obj)->transform_lock)

Release the lock that protects the transform function from concurrent access.

`obj` : | base transform instance

Since 0.10.13

## Property Details

### The "`qos`" property

      "qos"                      gboolean              : Read / Write

handle QoS messages.

Default value: FALSE

## See Also

GstBaseSrc, GstBaseSink