## GstFilter helper functions GstFilter helper functions — Helper functions for writing a filter |

## Synopsis

    #include <gst/filters/gst-filter-helper.h>

    #define             GST_FILTER_GET_LOCK                 (obj)
    #define             GST_FILTER_LOCK                     (obj)
    #define             GST_FILTER_TRYLOCK                  (obj)
    #define             GST_FILTER_UNLOCK                   (obj)
    #define             GST_DEFINE_FILTER                   (type,
                                                             filter_name)
    gboolean            gst_filter_add_element              (GstBin *bin,
                                                             GstPad *pad,
                                                             GstElement *element,
                                                             GstPad *element_pad);
    GstElement *        gst_filter_add_element_by_name      (GstBin *bin,
                                                             GstPad *pad,
                                                             const gchar *element_name,
                                                             const gchar *pad_name,
                                                             const gchar *out_pad_name,
                                                             GstPad **out_pad);
    GstElement *        gst_filter_add_element_by_name_default
                                                            (GstBin *bin,
                                                             GstPad *pad,
                                                             const gchar *element_name,
                                                             GstPad **out_pad);
    GstElement *        gst_filter_add_element_by_description
                                                            (GstBin *bin,
                                                             GstPad *pad,
                                                             const gchar *description,
                                                             GstPad **out_pad);
    GstPad *            gst_filter_apply_element_by_name    (GstBin *bin,
                                                             GstPad *pad,
                                                             const gchar *element_name,
                                                             const gchar *pad_name,
                                                             const gchar *out_pad_name,
                                                             GstElement **element,
                                                             GList **elements);
    GstPad *            gst_filter_apply_element_by_name_default
                                                            (GstBin *bin,
                                                             GstPad *pad,
                                                             const gchar *element_name,
                                                             GstElement **element,
                                                             GList **elements);
    GstPad *            gst_filter_apply_element_by_description
                                                            (GstBin *bin,
                                                             GstPad *pad,
                                                             const gchar *description,
                                                             GstElement **element,
                                                             GList **elements);
    GstPad *            gst_filter_revert_element           (GstBin *bin,
                                                             GstPad *pad,
                                                             const gchar *applied_pad_name,
                                                             GList **elements);
    GstPad *            gst_filter_revert_element_default   (GstBin *bin,
                                                             GstPad *pad,
                                                             GList **elements);

## Description

These helper functions allow for an easy way to write new filters by simply specifying what elements the filter provides and it will automatically take care of creating/adding the elements to the bin and check for any errors.

See also: GstFilter

## Details

### GST_FILTER_GET_LOCK()

    #define GST_FILTER_GET_LOCK(obj)      (GST_FILTER(obj)->lock)

Acquire a reference to the mutex of this filter.

`obj` : | a GstFilter

### GST_FILTER_LOCK()

    #define GST_FILTER_LOCK(obj)	       g_mutex_lock(GST_FILTER_GET_LOCK(obj))

This macro will obtain a lock on the filter, making serialization possible. It blocks until the lock can be obtained. All virtual methods get called with the mutex locked so filters do not need to bother with threading. However, if the filter needs to lock the mutex to do something outside of the virtual methods (like in a g_object_set or in a timer), then it should lock the filter's mutex by calling this macro.

See also: `GST_FILTER_UNLOCK()`

`obj` : | a GstFilter to lock

### GST_FILTER_TRYLOCK()

    #define GST_FILTER_TRYLOCK(obj)	       g_mutex_trylock(GST_FILTER_GET_LOCK(obj))

This macro will try to obtain a lock on the filter, but will return with FALSE if it can't get it immediately.

`obj` : | a GstFilter.

### GST_FILTER_UNLOCK()

    #define GST_FILTER_UNLOCK(obj)         g_mutex_unlock(GST_FILTER_GET_LOCK(obj))

This macro releases a lock on the filter. All virtual methods get called with the mutex locked so filters do not need to bother with threading. However, if the filter needs to lock the mutex to do something outside of the virtual methods (like in a g_object_set or in a timer), then it should call `GST_FILTER_LOCK()` then unlock it's mutex by calling this macro.

See also: `GST_FILTER_LOCK()`

`obj` : | a GstFilter to unlock.

### GST_DEFINE_FILTER()

    #define             GST_DEFINE_FILTER(type, filter_name)

This will define a new GstFilter derived class by calling `G_DEFINE_TYPE()` and by declaring and setting the apply, revert and name fields of the GstFilter parent class. The defined apply/revert methods will be gst_$(filter_name)_filter_apply and gst_$(filter_name)_filter_revert

`type` : | The type of the class to be defined
`filter_name` : | The name of the filter to define

### gst_filter_add_element ()

    gboolean            gst_filter_add_element              (GstBin *bin,
                                                             GstPad *pad,
                                                             GstElement *element,
                                                             GstPad *element_pad);

This helper function will add an element to the `bin` and link it's `element_pad` with the `pad`. Make sure the `pad` and `element_pad` pads have the correct directions and can be linked together. This will sink the reference on the element on success.

`bin` : | The GstBin to add the element to. [in]
`pad` : | The GstPad to link the element to. [in]
`element` : | The GstElement to add. [in]
`element_pad` : | The GstPad from the `element` to link to the `pad`. [in]
Returns : | TRUE if successful, FALSE if an error occured

### gst_filter_add_element_by_name ()

    GstElement *        gst_filter_add_element_by_name      (GstBin *bin,
                                                             GstPad *pad,
                                                             const gchar *element_name,
                                                             const gchar *pad_name,
                                                             const gchar *out_pad_name,
                                                             GstPad **out_pad);

This helper function will create a new GstElement by name (`element_name`) and add it to the `bin` and link it's pad (`pad_name`) with the `pad`. It will also return the output pad from the element through `out_pad` if set by using the `out_pad_name`. Make sure the `pad_name` specifies the correct pad direction to link with `pad`

`bin` : | The GstBin to add the element to. [in]
`pad` : | The GstPad to link the element to. [in]
`element_name` : | The name of the element to create and add. [in]
`pad_name` : | The name of the pad to get from the `element` to link to the `pad`. [in]
`out_pad_name` : | The name of the `out_pad` to get from the element. [in]
`out_pad` : | The output pad from the added element. Can be set to NULL if no output pad is needed. [out][allow-none]
Returns : | The GstElement created or NULL if an error occured. `gst_object_unref()` the returned element if not needed. [transfer full]

### gst_filter_add_element_by_name_default ()

    GstElement *        gst_filter_add_element_by_name_default
                                                            (GstBin *bin,
                                                             GstPad *pad,
                                                             const gchar *element_name,
                                                             GstPad **out_pad);

This helper function will create a new GstElement by name (`element_name`) and add it to the `bin`. It is equivalent to `gst_filter_add_element_by_name()` but uses "src" for the source pad's name and "sink" for the sink pad's name. The name is dependent on the direction of the pad it needs to link to.

See also: `gst_filter_add_element_by_name()`

`bin` : | The GstBin to add the element to. [in]
`pad` : | The GstPad to link the element to. [in]
`element_name` : | The name of the element to create and add. [in]
`out_pad` : | The output pad from the added element. Can be set to NULL if no output pad is needed. [out][allow-none]
Returns : | The GstElement created or NULL if an error occured. `gst_object_unref()` the returned element if not needed. [transfer full]

### gst_filter_add_element_by_description ()

    GstElement *        gst_filter_add_element_by_description
                                                            (GstBin *bin,
                                                             GstPad *pad,
                                                             const gchar *description,
                                                             GstPad **out_pad);

This helper function will create a new GstElement described the the pipeline description in `description` and add it to the `bin` and link it's pad with the `pad`. It will also return the output pad from the element through `out_pad` if set. Since `gst_parse_bin_from_description()` is used, it already knows the name of the source and sink pads, so it is unnecessary to specify them. It will also use the pad direction from `pad` to know in which direction to link.

`bin` : | The GstBin to add the element to. [in]
`pad` : | The GstPad to link the element to. [in]
`description` : | The pipeline description of the bin to create and add. [in]
`out_pad` : | The output pad from the created bin. Can be set to NULL if no output pad is needed. [out][allow-none]
Returns : | The GstElement created or NULL if an error occured. `gst_object_unref()` the returned element if not needed. [transfer full]

### gst_filter_apply_element_by_name ()

    GstPad *            gst_filter_apply_element_by_name    (GstBin *bin,
                                                             GstPad *pad,
                                                             const gchar *element_name,
                                                             const gchar *pad_name,
                                                             const gchar *out_pad_name,
                                                             GstElement **element,
                                                             GList **elements);

This helper function will create a new GstElement by its name and add it to the `bin` and link it's appropriate pad with the `pad` and return the applied pad. It will call `gst_filter_add_element_by_name()`, unref the returned element or add it to the `element` pointer, and return the output pad.

`bin` : | The GstBin to add the element to. [in]
`pad` : | The GstPad to link the element to. [in]
`element_name` : | The name of the standard element to create and add. [in]
`pad_name` : | The name of the pad to get from the element to link to the `pad`. [in]
`out_pad_name` : | The name of the `out_pad` to get from the element. [out]
`element` : | A pointer to store the created element. Can be NULL if the element is not needed. [out][allow-none]
`elements` : | A list to which to add the created element or NULL if not needed. If the element is added to the list, it will hold a reference to it. [inout][element-type Gst.Element][allow-none]
Returns : | The output GstPad from the element or NULL if an error occured. `gst_object_unref()` the returned pad if not needed as well as the returned element if `element` is set. [transfer full]

### gst_filter_apply_element_by_name_default ()

    GstPad *            gst_filter_apply_element_by_name_default
                                                            (GstBin *bin,
                                                             GstPad *pad,
                                                             const gchar *element_name,
                                                             GstElement **element,
                                                             GList **elements);

This helper function will create a new GstElement by its name and add it to the `bin` and link it's appropriate pad with the `pad` and return the applied pad. It will call `gst_filter_add_element_by_name()`, unref the returned element or add it to the `element` pointer, and return the output pad. The difference between this and `gst_filter_apply_element_by_name()` is that this expects the created element to have its pads names with the default 'src' and a 'sink' names for the source and sink pads respectively. Both pads would need to be ALWAYS pads.

`bin` : | The GstBin to add the element to. [in]
`pad` : | The GstPad to link the element to. [in]
`element_name` : | The name of the standard element to create and add. [in]
`element` : | A pointer to store the created element. Can be NULL if the element is not needed. [out][allow-none]
`elements` : | A list to which to add the created element or NULL if not needed. If the element is added to the list, it will hold a reference to it. [inout][element-type Gst.Element][allow-none]
Returns : | The output GstPad from the element or NULL if an error occured. `gst_object_unref()` the returned pad if not needed as well as the returned element if `element` is set. [transfer full]

### gst_filter_apply_element_by_description ()

    GstPad *            gst_filter_apply_element_by_description
                                                            (GstBin *bin,
                                                             GstPad *pad,
                                                             const gchar *description,
                                                             GstElement **element,
                                                             GList **elements);

This helper function will create a new GstElement described the the pipeline description in `description` and add it to the `bin` and return the applied pad. Since `gst_parse_bin_from_description()` is used, it already knows the name of the source and sink pads, so it is unnecessary to specify them. It will also use the pad direction from `pad` to know in which direction to link.

`bin` : | The GstBin to add the element to. [in]
`pad` : | The GstPad to link the element to. [in]
`description` : | The name of the standard element to create and add. [in]
`element` : | A pointer to store the created element. Can be NULL if the element is not needed. [out][allow-none]
`elements` : | A list to which to add the created element or NULL if not needed. If the element is added to the list, it will hold a reference to it. [inout][element-type Gst.Element][allow-none]
Returns : | The output GstPad from the element or NULL if an error occured. `gst_object_unref()` the returned pad if not needed as well as the returned element if `element` is set. [transfer full]

### gst_filter_revert_element ()

    GstPad *            gst_filter_revert_element           (GstBin *bin,
                                                             GstPad *pad,
                                                             const gchar *applied_pad_name,
                                                             GList **elements);

This helper function will automatically revert a GstElement from the `bin` and return the expected output pad. It will get the element the `pad` belongs to, and revert that element, while returning the `gst_peer_pad()` of the `applied_pad_name` of the element. If it finds the element in the `elements` list, it will unref it and remove it from the list.

`bin` : | The GstBin to revert the element from. [in]
`pad` : | The GstPad from the element to revert. [in]
`applied_pad_name` : | The name of the pad the element got applied to. [in]
`elements` : | A list to which the element was previously added in order to gst_object_unref it and remove it from the list. Can be set to NULL if not needed. [inout][element-type Gst.Element][allow-none]
Returns : | The applied GstPad from the reverted element or NULL if an error occured. `gst_object_unref()` the returned pad if not needed. [transfer full]

### gst_filter_revert_element_default ()

    GstPad *            gst_filter_revert_element_default   (GstBin *bin,
                                                             GstPad *pad,
                                                             GList **elements);

This helper function will automatically revert an element or bin previously created by `gst_filter_apply_element_by_description()` or `gst_filter_apply_element_by_name_default()` from the `bin` and return the expected output pad.

`bin` : | The GstBin to revert the bin from. [in]
`pad` : | The GstPad from the bin to revert. [in]
`elements` : | A list to which the element was previously added in order to gst_object_unref it and remove it from the list. Can be set to NULL if not needed. [inout][element-type Gst.Element][allow-none]
Returns : | The output GstPad from the reverted element/bin or NULL if an error occured. `gst_object_unref()` the returned pad if not needed. [transfer full]