mutter/cogl-gst/cogl-gst-video-sink.h
Robert Bragg 4d5af45d99 cogl-gst: adds _sink_is_ready() api
This adds a cogl_gst_video_sink_is_ready() for code to be able to
check if it's safe to call cogl_gst_video_sink_get_pipeline() or
cogl_gst_video_sink_setup_pipeline() without causing an error.
Normally an application can listen for the pipeline-ready signal but
sometimes a sink can be passed between components that didn't have an
opportunity to connect a signal handler, so they need a way to
directly check the status.

Reviewed-by: Neil Roberts <neil@linux.intel.com>

(cherry picked from commit 9e7db391a87beee7c448f2a67b3e7202779ce9b2)
2013-07-25 16:46:18 +01:00

448 lines
15 KiB
C

/*
* Cogl-GStreamer.
*
* GStreamer integration library for Cogl.
*
* cogl-gst-video-sink.h - Gstreamer Video Sink that renders to a
* Cogl Pipeline.
*
* Authored by Jonathan Matthew <jonathan@kaolin.wh9.net>,
* Chris Lord <chris@openedhand.com>
* Damien Lespiau <damien.lespiau@intel.com>
* Matthew Allum <mallum@openedhand.com>
* Plamena Manolova <plamena.n.manolova@intel.com>
*
* Copyright (C) 2007, 2008 OpenedHand
* Copyright (C) 2009, 2010, 2013 Intel Corporation
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the
* Free Software Foundation, Inc., 59 Temple Place - Suite 330,
* Boston, MA 02111-1307, USA.
*/
#ifndef __COGL_GST_VIDEO_SINK_H__
#define __COGL_GST_VIDEO_SINK_H__
#include <glib-object.h>
#include <gst/base/gstbasesink.h>
#include <cogl/cogl.h>
/**
* SECTION:cogl-gst-video-sink
* @short_description: A video sink for integrating a GStreamer
* pipeline with a Cogl pipeline.
*
* #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 #CoglGstVideoSink::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
* #CoglGstVideoSink::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.
*
* Since: 1.16
*/
G_BEGIN_DECLS
#define COGL_GST_TYPE_VIDEO_SINK cogl_gst_video_sink_get_type()
#define COGL_GST_VIDEO_SINK(obj) \
(G_TYPE_CHECK_INSTANCE_CAST ((obj), \
COGL_GST_TYPE_VIDEO_SINK, CoglGstVideoSink))
#define COGL_GST_VIDEO_SINK_CLASS(klass) \
(G_TYPE_CHECK_CLASS_CAST ((klass), \
COGL_GST_TYPE_VIDEO_SINK, CoglGstVideoSinkClass))
#define COGL_GST_IS_VIDEO_SINK(obj) \
(G_TYPE_CHECK_INSTANCE_TYPE ((obj), \
COGL_GST_TYPE_VIDEO_SINK))
#define COGL_GST_IS_VIDEO_SINK_CLASS(klass) \
(G_TYPE_CHECK_CLASS_TYPE ((klass), \
COGL_GST_TYPE_VIDEO_SINK))
#define COGL_GST_VIDEO_SINK_GET_CLASS(obj) \
(G_TYPE_INSTANCE_GET_CLASS ((obj), \
COGL_GST_TYPE_VIDEO_SINK, CoglGstVideoSinkClass))
typedef struct _CoglGstVideoSink CoglGstVideoSink;
typedef struct _CoglGstVideoSinkClass CoglGstVideoSinkClass;
typedef struct _CoglGstVideoSinkPrivate CoglGstVideoSinkPrivate;
/**
* CoglGstVideoSink:
*
* The #CoglGstVideoSink structure contains only private data and
* should be accessed using the provided API.
*
* Since: 1.16
*/
struct _CoglGstVideoSink
{
/*< private >*/
GstBaseSink parent;
CoglGstVideoSinkPrivate *priv;
};
/**
* CoglGstVideoSinkClass:
* @new_frame: handler for the #CoglGstVideoSink::new-frame signal
* @pipeline_ready: handler for the #CoglGstVideoSink::pipeline-ready signal
*
* Since: 1.16
*/
/**
* CoglGstVideoSink::new-frame:
* @sink: the #CoglGstVideoSink
*
* 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
*/
/**
* CoglGstVideoSink::pipeline-ready:
* @sink: the #CoglGstVideoSink
*
* 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 #CoglGstVideoSink::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
*/
struct _CoglGstVideoSinkClass
{
/*< private >*/
GstBaseSinkClass parent_class;
/*< public >*/
void (* new_frame) (CoglGstVideoSink *sink);
void (* pipeline_ready) (CoglGstVideoSink *sink);
/*< private >*/
void *_padding_dummy[8];
};
GType
cogl_gst_video_sink_get_type (void) G_GNUC_CONST;
/**
* cogl_gst_video_sink_new:
* @ctx: The #CoglContext
*
* Creates a new #CoglGstVideoSink which will create resources for use
* with the given context.
*
* Return value: a new #CoglGstVideoSink
* Since: 1.16
*/
CoglGstVideoSink *
cogl_gst_video_sink_new (CoglContext *ctx);
/**
* cogl_gst_video_sink_is_ready:
* @sink: The #CoglGstVideoSink
*
* 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
* #CoglGstVideoSink::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.
*
* Return value: %TRUE if the sink is ready, else %FALSE
* Since: 1.16
*/
CoglBool
cogl_gst_video_sink_is_ready (CoglGstVideoSink *sink);
/**
* cogl_gst_video_sink_get_pipeline:
* @vt: The #CoglGstVideoSink
*
* 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
* #CoglGstVideoSink::pipeline-ready signal is emitted.
*
* Return value: the pipeline for rendering the current frame
* Since: 1.16
*/
CoglPipeline *
cogl_gst_video_sink_get_pipeline (CoglGstVideoSink *vt);
/**
* cogl_gst_video_sink_set_context:
* @vt: The #CoglGstVideoSink
* @ctx: The #CoglContext for the sink to use
*
* 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
*/
void
cogl_gst_video_sink_set_context (CoglGstVideoSink *vt,
CoglContext *ctx);
/**
* cogl_gst_video_sink_get_free_layer:
* @sink: The #CoglGstVideoSink
*
* 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.
*
* Return value: the index of the next available layer after the
* sink's internal layers.
* Since: 1.16
*/
int
cogl_gst_video_sink_get_free_layer (CoglGstVideoSink *sink);
/**
* cogl_gst_video_sink_attach_frame:
* @sink: The #CoglGstVideoSink
* @pln: A #CoglPipeline
*
* 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 #CoglGstVideoSink::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
*/
void
cogl_gst_video_sink_attach_frame (CoglGstVideoSink *sink,
CoglPipeline *pln);
/**
* cogl_gst_video_sink_set_first_layer:
* @sink: The #CoglGstVideoSink
* @first_layer: The new 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
*/
void
cogl_gst_video_sink_set_first_layer (CoglGstVideoSink *sink,
int first_layer);
/**
* cogl_gst_video_sink_set_default_sample:
* @sink: The #CoglGstVideoSink
* @default_sample: Whether to add the default sampling
*
* 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
*/
void
cogl_gst_video_sink_set_default_sample (CoglGstVideoSink *sink,
CoglBool default_sample);
/**
* cogl_gst_video_sink_setup_pipeline:
* @sink: The #CoglGstVideoSink
* @pipeline: A #CoglPipeline
*
* 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
* #CoglGstVideoSink::pipeline-ready signal.
*
* Note: it is considered an error to call this function before the
* #CoglGstVideoSink::pipeline-ready signal is emitted.
*
* Since: 1.16
*/
void
cogl_gst_video_sink_setup_pipeline (CoglGstVideoSink *sink,
CoglPipeline *pipeline);
/**
* cogl_gst_video_sink_get_aspect:
* @sink: A #CoglGstVideoSink
*
* 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.
*
* Return value: a width-for-height aspect ratio
*
* Since: 1.16
* Stability: unstable
*/
float
cogl_gst_video_sink_get_aspect (CoglGstVideoSink *sink);
/**
* cogl_gst_video_sink_get_width_for_height:
* @sink: A #CoglGstVideoSink
* @height: A specific output @height
*
* Calculates a suitable output width for a specific output @height
* that will maintain the video's aspect ratio.
*
* Return value: An output width for the given output @height.
*
* Since: 1.16
* Stability: unstable
*/
float
cogl_gst_video_sink_get_width_for_height (CoglGstVideoSink *sink,
float height);
/**
* cogl_gst_video_sink_get_height_for_width:
* @sink: A #CoglGstVideoSink
* @width: A specific output @width
*
* Calculates a suitable output height for a specific output @width
* that will maintain the video's aspect ratio.
*
* Return value: An output height for the given output @width.
*
* Since: 1.16
* Stability: unstable
*/
float
cogl_gst_video_sink_get_height_for_width (CoglGstVideoSink *sink,
float width);
/**
* CoglGstRectangle:
* @x: The X coordinate of the top left of the rectangle
* @y: The Y coordinate of the top left of the rectangle
* @width: The width of the rectangle
* @height: The height of the rectangle
*
* Describes a rectangle that can be used for video output.
*/
typedef struct _CoglGstRectangle
{
float x;
float y;
float width;
float height;
} CoglGstRectangle;
/**
* cogl_gst_video_sink_fit_size:
* @sink: A #CoglGstVideoSink
* @available: The space available for video output
* @output: The return location for the calculated output position
*
* 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: unstable
*/
void
cogl_gst_video_sink_fit_size (CoglGstVideoSink *sink,
const CoglGstRectangle *available,
CoglGstRectangle *output);
G_END_DECLS
#endif