Video Sink

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

## Functions

ClutterGstVideoSink * | clutter_gst_video_sink_new ()
gboolean | clutter_gst_video_sink_is_ready ()
ClutterGstFrame * | clutter_gst_video_sink_get_frame ()
CoglPipeline * | clutter_gst_video_sink_get_pipeline ()
void | clutter_gst_video_sink_setup_pipeline ()
ClutterGstOverlays * | clutter_gst_video_sink_get_overlays ()

## Properties

gint | update-priority | Read / Write

## Signals

void | new-frame | Run Last
void | new-overlays | Run Last
void | pipeline-ready | Run Last

## Types and Values

struct | ClutterGstVideoSink
struct | ClutterGstVideoSinkClass

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── GstObject
                ╰── GstElement
                    ╰── GstBaseSink
                        ╰── GstVideoSink
                            ╰── ClutterGstVideoSink

## Implemented Interfaces

ClutterGstVideoSink implements GstColorBalance and GstNavigation.

## Description

ClutterGstVideoSink 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 `clutter_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 `clutter_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 `clutter_gst_video_sink_get_pipeline()` or it can create its own pipeline from scratch and ask the sink to configure it with `clutter_gst_video_sink_setup_pipeline()`. If a custom pipeline is created using one of these methods then the application should call `clutter_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 clutter_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. The function returns a vec4 containing a pre-multiplied RGBA color of the pixel within the video.

## Functions

### clutter_gst_video_sink_new ()

    ClutterGstVideoSink *
    clutter_gst_video_sink_new (void);

Creates a new ClutterGstVideoSink

#### Returns

a new ClutterGstVideoSink.

[transfer full]

Since: 3.0

### clutter_gst_video_sink_is_ready ()

    gboolean
    clutter_gst_video_sink_is_ready (ClutterGstVideoSink *sink);

Returns whether the pipeline is ready and so `clutter_gst_video_sink_get_pipeline()` and `clutter_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.

#### Parameters

sink | The ClutterGstVideoSink |

#### Returns

`TRUE` if the sink is ready, else `FALSE`

Since: 3.0

### clutter_gst_video_sink_get_frame ()

    ClutterGstFrame *
    clutter_gst_video_sink_get_frame (ClutterGstVideoSink *sink);

Returns a ClutterGstFrame object suitable to render the current frame of the given video sink. An application is free to make a copy of this pipeline and modify it for custom rendering.

#### Parameters

sink | The ClutterGstVideoSink |

#### Returns

A ClutterGstFrame or NULL if there isn't a frame to be displayed yet.

[transfer none]

Since: 3.0

### clutter_gst_video_sink_get_pipeline ()

    CoglPipeline *
    clutter_gst_video_sink_get_pipeline (ClutterGstVideoSink *sink);

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.

#### Parameters

sink | The ClutterGstVideoSink |

#### Returns

the pipeline for rendering the current frame.

[transfer none]

Since: 3.0

### clutter_gst_video_sink_setup_pipeline ()

    void
    clutter_gst_video_sink_setup_pipeline (ClutterGstVideoSink *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.

#### Parameters

sink | The ClutterGstVideoSink |
pipeline | A CoglPipeline |

Since: 3.0

### clutter_gst_video_sink_get_overlays ()

    ClutterGstOverlays *
    clutter_gst_video_sink_get_overlays (ClutterGstVideoSink *sink);

## Types and Values

### struct ClutterGstVideoSink

    struct ClutterGstVideoSink;

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

Since: 3.0

### struct ClutterGstVideoSinkClass

    struct ClutterGstVideoSinkClass {
      void (* new_frame)      (ClutterGstVideoSink *sink);
      void (* pipeline_ready) (ClutterGstVideoSink *sink);
      void (* new_overlays)   (ClutterGstVideoSink *sink);
    };

#### Members

`new_frame` () | handler for the “new-frame” signal |
`pipeline_ready` () | handler for the “pipeline-ready” signal |
`new_overlays` () |  |

Since: 3.0

## Property Details

### The `“update-priority”` property

      “update-priority”          gint

Priority of video updates in the thread.

Flags: Read / Write

Allowed values: >= -2147483647

Default value: 150

## Signal Details

### The `“new-frame”` signal

    void
    user_function (ClutterGstVideoSink *sink,
                   gpointer             user_data)

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 `clutter_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 `clutter_gst_video_sink_attach_frame()` to attach the textures.

#### Parameters

sink | the ClutterGstVideoSink |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 3.0

### The `“new-overlays”` signal

    void
    user_function (ClutterGstVideoSink *sink,
                   gpointer             user_data)

The sink will emit this signal whenever there are new textures available for set of overlays on the video. After this signal is emitted, an application can call `clutter_gst_video_sink_get_overlays()` to get a set of pipelines suitable for rendering overlays on a video frame.

#### Parameters

sink | the ClutterGstVideoSink |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 3.0

### The `“pipeline-ready”` signal

    void
    user_function (ClutterGstVideoSink *sink,
                   gpointer             user_data)

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 `clutter_gst_video_sink_get_pipeline()` or it can be a completely custom pipeline which is setup using `clutter_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.

#### Parameters

sink | the ClutterGstVideoSink |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 3.0