CoglGstVideoSink

## CoglGstVideoSink CoglGstVideoSink — A video sink for integrating a GStreamer pipeline with a Cogl pipeline. |

## Synopsis

    struct              CoglGstVideoSink;
    struct              CoglGstVideoSinkClass;
    CoglGstVideoSink *  cogl_gst_video_sink_new             (CoglContext *ctx);
    void                cogl_gst_video_sink_set_context     (CoglGstVideoSink *vt,
                                                             CoglContext *ctx);
    CoglPipeline *      cogl_gst_video_sink_get_pipeline    (CoglGstVideoSink *vt);
    void                cogl_gst_video_sink_attach_frame    (CoglGstVideoSink *sink,
                                                             CoglPipeline *pln);
    void                cogl_gst_video_sink_setup_pipeline  (CoglGstVideoSink *sink,
                                                             CoglPipeline *pipeline);
    int                 cogl_gst_video_sink_get_free_layer  (CoglGstVideoSink *sink);
    void                cogl_gst_video_sink_set_first_layer (CoglGstVideoSink *sink,
                                                             int first_layer);
    void                cogl_gst_video_sink_set_default_sample
                                                            (CoglGstVideoSink *sink,
                                                             CoglBool default_sample);
    CoglBool            cogl_gst_video_sink_is_ready        (CoglGstVideoSink *sink);
    float               cogl_gst_video_sink_get_aspect      (CoglGstVideoSink *sink);
    float               cogl_gst_video_sink_get_width_for_height
                                                            (CoglGstVideoSink *sink,
                                                             float height);
    float               cogl_gst_video_sink_get_height_for_width
                                                            (CoglGstVideoSink *sink,
                                                             float width);
    void                cogl_gst_video_sink_fit_size        (CoglGstVideoSink *sink,
                                                             const CoglGstRectangle *available,
                                                             CoglGstRectangle *output);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----GstObject
                   +----GstElement
                         +----GstBaseSink
                               +----CoglGstVideoSink

## Properties

      "update-priority"          gint                  : Read / Write

## Signals

      "new-frame"                                      : Run Last
      "pipeline-ready"                                 : Run Last

## Description

CoglGstVideoSink is a subclass of GstBaseSink which can be used to create a CoglPipeline for rendering the frames of the video.

To create a basic video player, an application can create a GstPipeline as normal using `gst_pipeline_new()` and set the sink on it to one created with `cogl_gst_video_sink_new()`. The application can then listen for the "new-frame" signal which will be emitted whenever there are new textures ready for rendering. For simple rendering, the application can just call `cogl_gst_video_sink_get_pipeline()` in the signal handler and use the returned pipeline to paint the new frame.

An application is also free to do more advanced rendering by customizing the pipeline. In that case it should listen for the "pipeline-ready" signal which will be emitted as soon as the sink has determined enough information about the video to know how it should be rendered. In the handler for this signal, the application can either make modifications to a copy of the pipeline returned by `cogl_gst_video_sink_get_pipeline()` or it can create its own pipeline from scratch and ask the sink to configure it with `cogl_gst_video_sink_setup_pipeline()`. If a custom pipeline is created using one of these methods then the application should call `cogl_gst_video_sink_attach_frame()` on the pipeline before rendering in order to update the textures on the pipeline's layers.

If the `COGL_FEATURE_ID_GLSL` feature is available then the pipeline used by the sink will have a shader snippet with a function in it called cogl_gst_sample_video0 which takes a single vec2 argument. This can be used by custom snippets set the by the application to sample from the video. The vec2 argument represents the normalised coordinates within the video.

## Details

### struct CoglGstVideoSink

    struct CoglGstVideoSink;

The CoglGstVideoSink structure contains only private data and should be accessed using the provided API.

Since 1.16

### struct CoglGstVideoSinkClass

    struct CoglGstVideoSinkClass {
      void (* new_frame) (CoglGstVideoSink *sink);
      void (* pipeline_ready) (CoglGstVideoSink *sink);
    };

`new_frame` () | handler for the "new-frame" signal
`pipeline_ready` () | handler for the "pipeline-ready" signal

Since 1.16

### cogl_gst_video_sink_new ()

    CoglGstVideoSink *  cogl_gst_video_sink_new             (CoglContext *ctx);

Creates a new CoglGstVideoSink which will create resources for use with the given context.

`ctx` : | The CoglContext
Returns : | a new CoglGstVideoSink. [transfer full]

Since 1.16

### cogl_gst_video_sink_set_context ()

    void                cogl_gst_video_sink_set_context     (CoglGstVideoSink *vt,
                                                             CoglContext *ctx);

Sets the CoglContext that the video sink should use for creating any resources. This function would normally only be used if the sink was constructed via `gst_element_factory_make()` instead of `cogl_gst_video_sink_new()`.

`vt` : | The CoglGstVideoSink
`ctx` : | The CoglContext for the sink to use

Since 1.16

### cogl_gst_video_sink_get_pipeline ()

    CoglPipeline *      cogl_gst_video_sink_get_pipeline    (CoglGstVideoSink *vt);

Returns a pipeline suitable for rendering the current frame of the given video sink. The pipeline will already have the textures for the frame attached. For simple rendering, an application will typically call this function immediately before it paints the video. It can then just paint a rectangle using the returned pipeline.

An application is free to make a copy of this pipeline and modify it for custom rendering.

Note: it is considered an error to call this function before the "pipeline-ready" signal is emitted.

`vt` : | The CoglGstVideoSink
Returns : | the pipeline for rendering the current frame. [transfer none]

Since 1.16

### cogl_gst_video_sink_attach_frame ()

    void                cogl_gst_video_sink_attach_frame    (CoglGstVideoSink *sink,
                                                             CoglPipeline *pln);

Updates the given pipeline with the textures for the current frame. This can be used if the application wants to customize the rendering using its own pipeline. Typically this would be called in response to the "new-frame" signal which is emitted whenever the new textures are available. The application would then make a copy of its template pipeline and call this to set the textures.

`sink` : | The CoglGstVideoSink
`pln` : | A CoglPipeline

Since 1.16

### cogl_gst_video_sink_setup_pipeline ()

    void                cogl_gst_video_sink_setup_pipeline  (CoglGstVideoSink *sink,
                                                             CoglPipeline *pipeline);

Configures the given pipeline so that will be able to render the video for the `sink`. This should only be used if the application wants to perform some custom rendering using its own pipeline. Typically an application will call this in response to the "pipeline-ready" signal.

Note: it is considered an error to call this function before the "pipeline-ready" signal is emitted.

`sink` : | The CoglGstVideoSink
`pipeline` : | A CoglPipeline

Since 1.16

### cogl_gst_video_sink_get_free_layer ()

    int                 cogl_gst_video_sink_get_free_layer  (CoglGstVideoSink *sink);

This can be used when doing specialised rendering of the video by customizing the pipeline. CoglGstVideoSink may use up to three private layers on the pipeline in order to attach the textures of the video frame. This function will return the index of the next available unused layer after the sink's internal layers. This can be used by the application to add additional layers, for example to blend in another color in the fragment processing.

`sink` : | The CoglGstVideoSink
Returns : | the index of the next available layer after the sink's internal layers.

Since 1.16

### cogl_gst_video_sink_set_first_layer ()

    void                cogl_gst_video_sink_set_first_layer (CoglGstVideoSink *sink,
                                                             int first_layer);

Sets the index of the first layer that the sink will use for its rendering. This is useful if the application wants to have custom layers that appear before the layers added by the sink. In that case by default the sink's layers will be modulated with the result of the application's layers that come before `first_layer`.

Note that if this function is called then the name of the function to call in the shader snippets to sample the video will also change. For example, if `first_layer` is three then the function will be cogl_gst_sample_video3.

`sink` : | The CoglGstVideoSink
`first_layer` : | The new first layer

Since 1.16

### cogl_gst_video_sink_set_default_sample ()

    void                cogl_gst_video_sink_set_default_sample
                                                            (CoglGstVideoSink *sink,
                                                             CoglBool default_sample);

By default the pipeline generated by `cogl_gst_video_sink_setup_pipeline()` and `cogl_gst_video_sink_get_pipeline()` will have a layer with a shader snippet that automatically samples the video. If the application wants to sample the video in a completely custom way using its own shader snippet it can set `default_sample` to `FALSE` to avoid this default snippet being added. In that case the application's snippet can call cogl_gst_sample_video0 to sample the texture itself.

`sink` : | The CoglGstVideoSink
`default_sample` : | Whether to add the default sampling

Since 1.16

### cogl_gst_video_sink_is_ready ()

    CoglBool            cogl_gst_video_sink_is_ready        (CoglGstVideoSink *sink);

Returns whether the pipeline is ready and so `cogl_gst_video_sink_get_pipeline()` and `cogl_gst_video_sink_setup_pipeline()` can be called without causing error.

Note: Normally an application will wait until the "pipeline-ready" signal is emitted instead of polling the ready status with this api, but sometimes when a sink is passed between components that didn't have an opportunity to connect a signal handler this can be useful.

`sink` : | The CoglGstVideoSink
Returns : | `TRUE` if the sink is ready, else `FALSE`

Since 1.16

### cogl_gst_video_sink_get_aspect ()

    float               cogl_gst_video_sink_get_aspect      (CoglGstVideoSink *sink);

Returns a width-for-height aspect ratio that lets you calculate a suitable width for displaying your video based on a given height by multiplying your chosen height by the returned aspect ratio.

This aspect ratio is calculated based on the underlying size of the video buffers and the current pixel-aspect-ratio.

`sink` : | A CoglGstVideoSink
Returns : | a width-for-height aspect ratio

Since 1.16

Stability Level: Unstable

### cogl_gst_video_sink_get_width_for_height ()

    float               cogl_gst_video_sink_get_width_for_height
                                                            (CoglGstVideoSink *sink,
                                                             float height);

Calculates a suitable output width for a specific output `height` that will maintain the video's aspect ratio.

`sink` : | A CoglGstVideoSink
`height` : | A specific output `height`
Returns : | An output width for the given output `height`.

Since 1.16

Stability Level: Unstable

### cogl_gst_video_sink_get_height_for_width ()

    float               cogl_gst_video_sink_get_height_for_width
                                                            (CoglGstVideoSink *sink,
                                                             float width);

Calculates a suitable output height for a specific output `width` that will maintain the video's aspect ratio.

`sink` : | A CoglGstVideoSink
`width` : | A specific output `width`
Returns : | An output height for the given output `width`.

Since 1.16

Stability Level: Unstable

### cogl_gst_video_sink_fit_size ()

    void                cogl_gst_video_sink_fit_size        (CoglGstVideoSink *sink,
                                                             const CoglGstRectangle *available,
                                                             CoglGstRectangle *output);

Calculates a suitable `output` rectangle that can fit inside the `available` space while maintaining the aspect ratio of the current video.

Applications would typically use this api for "letterboxing" by using this api to position a video inside a fixed screen space and filling the remaining space with black borders.

`sink` : | A CoglGstVideoSink
`available` : | The space available for video output. [in]
`output` : | The return location for the calculated output position. [inout]

Since 1.16

Stability Level: Unstable

## Property Details

### The `"update-priority"` property

      "update-priority"          gint                  : Read / Write

Priority of video updates in the thread.

Allowed values: >= -2147483647

Default value: 100

## Signal Details

### The `"new-frame"` signal

    void                user_function                      (CoglGstVideoSink *sink,
                                                            gpointer          user_data)      : Run Last

The sink will emit this signal whenever there are new textures available for a new frame of the video. After this signal is emitted, an application can call `cogl_gst_video_sink_get_pipeline()` to get a pipeline suitable for rendering the frame. If the application is using a custom pipeline it can alternatively call `cogl_gst_video_sink_attach_frame()` to attach the textures.

`sink` : | the CoglGstVideoSink
`user_data` : | user data set when the signal handler was connected.

Since 1.16

### The `"pipeline-ready"` signal

    void                user_function                      (CoglGstVideoSink *sink,
                                                            gpointer          user_data)      : Run Last

The sink will emit this signal as soon as it has gathered enough information from the video to configure a pipeline. If the application wants to do some customized rendering, it can setup its pipeline after this signal is emitted. The application's pipeline will typically either be a copy of the one returned by `cogl_gst_video_sink_get_pipeline()` or it can be a completely custom pipeline which is setup using `cogl_gst_video_sink_setup_pipeline()`.

Note that it is an error to call either of those functions before this signal is emitted. The "new-frame" signal will only be emitted after the pipeline is ready so the application could also create its pipeline in the handler for that.

`sink` : | the CoglGstVideoSink
`user_data` : | user data set when the signal handler was connected.

Since 1.16