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

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

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

output :

The return location for the calculated output position

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