GstVideoContextInterface

GstVideoContextInterface — Interface to handle video library context

Synopsis

#define             GST_IS_VIDEO_CONTEXT                (obj)
                    GstVideoContext;
struct              GstVideoContextInterface;
GType               gst_video_context_iface_get_type    (void);
void                gst_video_context_set_context       (GstVideoContext *context,
                                                         const gchar *type,
                                                         const GValue *value);
void                gst_video_context_set_context_string
                                                        (GstVideoContext *context,
                                                         const gchar *type,
                                                         const gchar *value);
void                gst_video_context_set_context_pointer
                                                        (GstVideoContext *context,
                                                         const gchar *type,
                                                         gpointer value);
void                gst_video_context_set_context_object
                                                        (GstVideoContext *context,
                                                         const gchar *type,
                                                         GObject *value);
void                gst_video_context_prepare           (GstVideoContext *context,
                                                         const gchar **types);
gboolean            gst_video_context_message_parse_prepare
                                                        (GstMessage *message,
                                                         const gchar ***types,
                                                         GstVideoContext **ctx);
GstQuery *          gst_video_context_query_new         (const gchar **types);
gboolean            gst_video_context_run_query         (GstElement *element,
                                                         GstQuery *query);
const gchar **      gst_video_context_query_get_supported_types
                                                        (GstQuery *query);
void                gst_video_context_query_parse_value (GstQuery *query,
                                                         const gchar **type,
                                                         const GValue **value);
void                gst_video_context_query_set_value   (GstQuery *query,
                                                         const gchar *type,
                                                         GValue *value);
void                gst_video_context_query_set_string  (GstQuery *query,
                                                         const gchar *type,
                                                         const gchar *value);
void                gst_video_context_query_set_pointer (GstQuery *query,
                                                         const gchar *type,
                                                         gpointer value);
void                gst_video_context_query_set_object  (GstQuery *query,
                                                         const gchar *type,
                                                         GObject *value);

Description

The Video Context interface enable sharing video context (such as display name, X11 Display, VA-API Display, etc) between neighboor elements and the application.

Note

The GstVideoContext interface is unstable API and may change in future. One can define GST_USE_UNSTABLE_API to acknowledge and avoid this warning.

For Element

This interface shall be implement by group of elements that need to share a specific video context (like VDPAU, LibVA, OpenGL elements) or by video sink in order to let the application select appropriate display information (like the X11 display name) when those sink are auto-plugged.

Along with implementing the interface, elements will need to query neighboor elements or send message to the application when preparing the context (see gst_video_context_prepare()). They also need to reply to the neighboors element queries, so the context can be shared without the application help.

Elements that are guarantied to have both upstream and downstream neighboors element implementing the GstVideoContext (like the gloverlay element in gst-plugins-opengl) is not required to also implement the interface. Relying on neighboors query shall be sufficient (see gst_video_context_run_query()).

The query is an application query with a structure name set to "prepare-video-context" and an array of supported video context types set in the field named "types". This query shall be send downstream and upstream, iterating the pads in order to find neighboors regardless of a static (sink to src) or a dynamic (src to sink) activation. Element should used the helpers method gst_video_context_prepare() (or gst_video_context_run_query() if no GstVideoContext interface) to correctly execute the query . The result is set using the query helper functions, the structures fields name being "video-context-type" as string and "video-context" as a GValue.

If the query is not handled by any neighboor, the element should ask the application using the "prepare-video-context" message. The application may then use the interface to set the video context information. If no context was set, the element shall create one using default configuration. Elements with multiple src or sink pad shall implement proper locking to prevent the race of parallel queries being replied.

Well known video-context are: "x11-display-name" a string representing the X11 display to use, "x11-display" the X11 Display structure, "va-display", the VADisplay structure and more.

For Application

In the case there is no neighboor element with video context to share, the element will first turn toward the application, by sending a "prepare-video-context" message. This message is sent along with a list of supported display types. The application can optionally reply to this message by calling appropriate setter through the GstVideoContext interface. If the application supports more then one video context type, it should choose the first one to occure in the supported list. It's important to remember that the message is delivered from the streaming thread, and appropriate locking should be considered. If the application does not have a video context to share, the element will simply allocate one base on default settings. Usually, only applications using OpenGL base sink, or running on special X11 display need to share a video context.

Note

Applications sharing X11 Display structure should always initialize the X11 threading support using XInitThreads() as GStreamer will need to manipulate the display from a separeate threads.

Example using ClutterVideoGstVideoSink

This example is for user of ClutterGstVideoSink element, the ClutterGstPlayer object transparently handle this.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54