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);
};

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.

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().

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

Since 1.16

Stability Level: Unstable

The "update-priority" property

  "update-priority"          gint                  : Read / Write

Priority of video updates in the thread.

Allowed values: >= -2147483647

Default value: 100

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.

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.

Since 1.16