GstVaapiFilter: GStreamer VA-API Plugins 1.6 Library Reference Manual

## GstVaapiFilter GstVaapiFilter |

## Functions

GstVaapiFilter * | gst_vaapi_filter_new ()
GstVaapiFilter * | gst_vaapi_filter_ref ()
void | gst_vaapi_filter_unref ()
void | gst_vaapi_filter_replace ()
GPtrArray * | gst_vaapi_filter_get_operations ()
GArray * | gst_vaapi_filter_get_formats ()
gboolean | gst_vaapi_filter_has_operation ()
gboolean | gst_vaapi_filter_use_operation ()
gboolean | gst_vaapi_filter_set_operation ()
gboolean | gst_vaapi_filter_set_format ()
gboolean | gst_vaapi_filter_set_cropping_rectangle ()
gboolean | gst_vaapi_filter_set_target_rectangle ()
gboolean | gst_vaapi_filter_set_denoising_level ()
gboolean | gst_vaapi_filter_set_sharpening_level ()
gboolean | gst_vaapi_filter_set_hue ()
gboolean | gst_vaapi_filter_set_brightness ()
gboolean | gst_vaapi_filter_set_saturation ()
gboolean | gst_vaapi_filter_set_deinterlacing ()
gboolean | gst_vaapi_filter_set_deinterlacing_references ()

## Types and Values

| GstVaapiFilter
enum | GstVaapiFilterOp

## Description

## Functions

### gst_vaapi_filter_new ()

    GstVaapiFilter *
    gst_vaapi_filter_new (GstVaapiDisplay *display);

Creates a new GstVaapiFilter set up to operate in "identity" mode. This means that no other operation than scaling is performed.

#### Parameters

display | a GstVaapiDisplay |

#### Returns

the newly created GstVaapiFilter object

### gst_vaapi_filter_ref ()

    GstVaapiFilter *
    gst_vaapi_filter_ref (GstVaapiFilter *filter);

Atomically increases the reference count of the given `filter` by one.

#### Parameters

filter | a GstVaapiFilter |

#### Returns

The same `filter` argument

### gst_vaapi_filter_unref ()

    void
    gst_vaapi_filter_unref (GstVaapiFilter *filter);

Atomically decreases the reference count of the `filter` by one. If the reference count reaches zero, the filter will be free'd.

#### Parameters

filter | a GstVaapiFilter |

### gst_vaapi_filter_replace ()

    void
    gst_vaapi_filter_replace (GstVaapiFilter **old_filter_ptr,
                              GstVaapiFilter *new_filter);

Atomically replaces the filter held in `old_filter_ptr` with `new_filter` . This means that `old_filter_ptr` shall reference a valid filter. However, `new_filter` can be NULL.

#### Parameters

old_filter_ptr | a pointer to a GstVaapiFilter |
new_filter | a GstVaapiFilter |

### gst_vaapi_filter_get_operations ()

    GPtrArray *
    gst_vaapi_filter_get_operations (GstVaapiFilter *filter);

Determines the set of supported operations for video processing. The caller owns an extra reference to the resulting array of GstVaapiFilterOpInfo elements, so it shall be released with `g_ptr_array_unref()` after usage.

If `filter` is `NULL`, then this function returns the video processing operations supported by this library.

#### Parameters

filter | a GstVaapiFilter, or `NULL` |

#### Returns

the set of supported operations, or `NULL` if an error occurred.

### gst_vaapi_filter_get_formats ()

    GArray *
    gst_vaapi_filter_get_formats (GstVaapiFilter *filter);

Determines the set of supported source or target formats for video processing. The caller owns an extra reference to the resulting array of GstVideoFormat elements, so it shall be released with `g_array_unref()` after usage.

#### Parameters

filter | a GstVaapiFilter |

#### Returns

the set of supported target formats for video processing.

### gst_vaapi_filter_has_operation ()

    gboolean
    gst_vaapi_filter_has_operation (GstVaapiFilter *filter,
                                    GstVaapiFilterOp op);

Determines whether the underlying VA driver advertises support for the supplied operation `op` .

#### Parameters

filter | a GstVaapiFilter |
op | a GstVaapiFilterOp |

#### Returns

`TRUE` if the specified operation may be supported by the underlying hardware, `FALSE` otherwise

### gst_vaapi_filter_use_operation ()

    gboolean
    gst_vaapi_filter_use_operation (GstVaapiFilter *filter,
                                    GstVaapiFilterOp op);

Determines whether the supplied operation `op` was already enabled through a prior call to `gst_vaapi_filter_set_operation()` or any other operation-specific function.

Note: should an operation be set to its default value, this means that it is actually not enabled.

#### Parameters

filter | a GstVaapiFilter |
op | a GstVaapiFilterOp |

#### Returns

`TRUE` if the specified operation was already enabled, `FALSE` otherwise

### gst_vaapi_filter_set_operation ()

    gboolean
    gst_vaapi_filter_set_operation (GstVaapiFilter *filter,
                                    GstVaapiFilterOp op,
                                    const GValue *value);

Enable the specified operation `op` to be performed during video processing, i.e. in `gst_vaapi_filter_process()`. The `value` argument specifies the operation settings. e.g. deinterlacing method for deinterlacing, denoising level for noise reduction, etc.

If `value` is `NULL`, then this function resets the operation settings to their default values.

#### Parameters

filter | a GstVaapiFilter |
op | a GstVaapiFilterOp |
value | the `op` settings |

#### Returns

`TRUE` if the specified operation may be supported, `FALSE` otherwise

### gst_vaapi_filter_set_format ()

    gboolean
    gst_vaapi_filter_set_format (GstVaapiFilter *filter,
                                 GstVideoFormat format);

Sets the desired pixel format of the resulting video processing operations.

If `format` is GST_VIDEO_FORMAT_UNKNOWN, the filter will assume iso format conversion, i.e. no color conversion at all and the target surface format shall match the source surface format.

If `format` is GST_VIDEO_FORMAT_ENCODED, the filter will use the pixel format of the target surface passed to `gst_vaapi_filter_process()`.

#### Parameters

filter | a GstVaapiFilter |
format | the target surface format |

#### Returns

`TRUE` if the color conversion to the specified `format` may be supported, `FALSE` otherwise.

### gst_vaapi_filter_set_cropping_rectangle ()

    gboolean
    gst_vaapi_filter_set_cropping_rectangle
                                   (GstVaapiFilter *filter,
                                    const GstVaapiRectangle *rect);

Sets the source surface cropping rectangle to use during the video processing. If `rect` is `NULL`, the whole source surface will be used.

#### Parameters

filter | a GstVaapiFilter |
rect | the cropping region |

#### Returns

`TRUE` if the operation is supported, `FALSE` otherwise.

### gst_vaapi_filter_set_target_rectangle ()

    gboolean
    gst_vaapi_filter_set_target_rectangle (GstVaapiFilter *filter,
                                           const GstVaapiRectangle *rect);

Sets the region within the target surface where the source surface would be rendered. i.e. where the hardware accelerator would emit the outcome of video processing. If `rect` is `NULL`, the whole source surface will be used.

#### Parameters

filter | a GstVaapiFilter |
rect | the target render region |

#### Returns

`TRUE` if the operation is supported, `FALSE` otherwise.

### gst_vaapi_filter_set_denoising_level ()

    gboolean
    gst_vaapi_filter_set_denoising_level (GstVaapiFilter *filter,
                                          gfloat level);

Sets the noise reduction level to apply. If `level` is 0.0f, this corresponds to disabling the noise reduction algorithm.

#### Parameters

filter | a GstVaapiFilter |
level | the level of noise reduction to apply |

#### Returns

`TRUE` if the operation is supported, `FALSE` otherwise.

### gst_vaapi_filter_set_sharpening_level ()

    gboolean
    gst_vaapi_filter_set_sharpening_level (GstVaapiFilter *filter,
                                           gfloat level);

Enables noise reduction with the specified factor.

#### Parameters

filter | a GstVaapiFilter |
level | the sharpening factor |

#### Returns

`TRUE` if the operation is supported, `FALSE` otherwise.

### gst_vaapi_filter_set_hue ()

    gboolean
    gst_vaapi_filter_set_hue (GstVaapiFilter *filter,
                              gfloat value);

Enables color hue adjustment to the specified value.

#### Parameters

filter | a GstVaapiFilter |
value | the color hue value |

#### Returns

`TRUE` if the operation is supported, `FALSE` otherwise.

### gst_vaapi_filter_set_brightness ()

    gboolean
    gst_vaapi_filter_set_brightness (GstVaapiFilter *filter,
                                     gfloat value);

Enables color brightness adjustment to the specified value.

#### Parameters

filter | a GstVaapiFilter |
value | the color brightness value |

#### Returns

`TRUE` if the operation is supported, `FALSE` otherwise.

### gst_vaapi_filter_set_saturation ()

    gboolean
    gst_vaapi_filter_set_saturation (GstVaapiFilter *filter,
                                     gfloat value);

Enables color saturation adjustment to the specified value.

#### Parameters

filter | a GstVaapiFilter |
value | the color saturation value |

#### Returns

`TRUE` if the operation is supported, `FALSE` otherwise.

### gst_vaapi_filter_set_deinterlacing ()

    gboolean
    gst_vaapi_filter_set_deinterlacing (GstVaapiFilter *filter,
                                        GstVaapiDeinterlaceMethod method,
                                        guint flags);

Applies deinterlacing to the video processing pipeline. If `method` is not `GST_VAAPI_DEINTERLACE_METHOD_NONE` , then `flags` could represent the initial picture structure of the source frame.

#### Parameters

filter | a GstVaapiFilter |
method | the deinterlacing algorithm (see GstVaapiDeinterlaceMethod) |
flags | the additional flags |

#### Returns

`TRUE` if the operation is supported, `FALSE` otherwise.

### gst_vaapi_filter_set_deinterlacing_references ()

    gboolean
    gst_vaapi_filter_set_deinterlacing_references
                                   (GstVaapiFilter *filter,
                                    GstVaapiSurface **forward_references,
                                    guint num_forward_references,
                                    GstVaapiSurface **backward_references,
                                    guint num_backward_references);

Specifies the list of surfaces used for forward or backward reference in advanced deinterlacing mode. The caller is responsible for maintaining the associated surfaces live until `gst_vaapi_filter_process()` completes. e.g. by holding an extra reference to the associated GstVaapiSurfaceProxy.

Temporal ordering is maintained as follows: the shorter index in either array is, the closest the matching surface is relatively to the current source surface to process. e.g. surface in `forward_references` array index 0 represents the immediately preceding surface in display order, surface at index 1 is the one preceding surface at index 0, etc.

The video processing filter will only use the recommended number of surfaces for backward and forward references.

Note: the supplied lists of reference surfaces are not sticky. This means that they are only valid for the next `gst_vaapi_filter_process()` call, and thus needs to be submitted again for subsequent calls.

#### Parameters

filter | a GstVaapiFilter |
forward_references | the set of GstVaapiSurface objects used as forward references |
num_forward_references | the number of elements in the `forward_references` array |
backward_references | the set of GstVaapiSurface objects used as backward references |
num_backward_references | the number of elements in the `backward_references` array |

#### Returns

`TRUE` if the operation is supported, `FALSE` otherwise.

## Types and Values

### GstVaapiFilter

    typedef struct _GstVaapiFilter GstVaapiFilter;

### enum GstVaapiFilterOp

#### Members

GST_VAAPI_FILTER_OP_FORMAT |  |
GST_VAAPI_FILTER_OP_CROP |  |
GST_VAAPI_FILTER_OP_DENOISE |  |
GST_VAAPI_FILTER_OP_SHARPEN |  |
GST_VAAPI_FILTER_OP_HUE |  |
GST_VAAPI_FILTER_OP_SATURATION |  |
GST_VAAPI_FILTER_OP_BRIGHTNESS |  |
GST_VAAPI_FILTER_OP_CONTRAST |  |
GST_VAAPI_FILTER_OP_DEINTERLACING |  |
GST_VAAPI_FILTER_OP_SCALING |  |
GST_VAAPI_FILTER_OP_SKINTONE |  |