# qml6gloverlay

`qml6gloverlay` provides a way to render an almost-arbitrary QML scene within GStreamer pipeline using the same OpenGL context that GStreamer uses internally. This avoids attempting to share multiple OpenGL contexts avoiding increased synchronisation points and attempting to share an OpenGL context at runtime which some drivers do not like. The Intel driver on Windows is a notable example of the last point.

`qml6gloverlay` will attempt to retrieve the windowing system display connection that Qt is using (#GstGLDisplay). This may be different to any already existing window system display connection already in use in the pipeline for a number of reasons. A couple of examples of this are:

1. Adding `qml6gloverlay` to an already running pipeline
2. Not having any `qml6gloverlay` (or `qml6glsink`, or `qml6glmixer`) element start up before any other OpenGL-based element in the pipeline.

If one of these scenarios occurs, then there will be multiple OpenGL contexts in use in the pipeline. This means that either the pipeline will fail to start up correctly, a downstream element may reject buffers, or a complete GPU->System memory->GPU transfer is performed for every buffer.

The requirement to avoid this is that all elements share the same GstGLDisplay object and as Qt cannot currently share an existing window system display connection, GStreamer must use the window system display connection provided by Qt. This window system display connection can be retrieved by either a `qml6glsink` element, a `qml6gloverlay`, or a `qml6glmixer` element. The recommended usage is to have either element (`qml6glsink` or `qml6gloverlay` or `qml6glmixer`) be the first to propagate the GstGLDisplay for the entire pipeline to use by setting either element to the READY element state before any other OpenGL element in the pipeline.

In the dynamically adding `qml6gloverlay` (or `qml6glsink`, or `qml6glmixer`) to a pipeline case, there are some considerations for ensuring that the window system display and OpenGL contexts are compatible with Qt. When the `qml6gloverlay` (or `qml6glsink`, or `qml6glmixer`) element is added and brought up to READY, it will propagate it's own GstGLDisplay using the GstContext mechanism regardless of any existing GstGLDisplay used by the pipeline previously. In order for the new GstGLDisplay to be used, the application must then set the provided GstGLDisplay containing GstContext on the pipeline. This may effectively cause each OpenGL element to replace the window system display and also the OpenGL context it is using. As such this process may take a significant amount of time and resources as objects are recreated in the new OpenGL context.

All instances of `qml6gloverlay`, `qml6glsink`, and `qml6glmixer` will return the exact same GstGLDisplay object while the pipeline is running regardless of whether any `qml6gloverlay` or `qml6glsink` elements are added or removed from the pipeline.

The Qml scene will run at the pace of incoming buffers. One input buffer will cause a render of one output buffer. The timestamps on the input buffers are used to drive the animation time.

## Hierarchy

    GObject
        ╰──GInitiallyUnowned
            ╰──GstObject
                ╰──GstElement
                    ╰──GstBaseTransform
                        ╰──GstGLBaseFilter
                            ╰──GstGLFilter
                                ╰──qml6gloverlay

## Factory details

Authors: – Matthew Waters

Classification: – `Filter/QML/Overlay`

Rank – none

Plugin – qml6

Package – GStreamer Good Plug-ins

## Pad Templates

### `sink`

    video/x-raw(ANY):
             format: { RGBA, BGRA, YV12 }
              width: [ 1, 2147483647 ]
             height: [ 1, 2147483647 ]
          framerate: [ 0/1, 2147483647/1 ]
     texture-target: 2D

Presence – always

Direction – sink

Object type – GstPad

### `src`

    video/x-raw(memory:GLMemory):
             format: RGBA
              width: [ 1, 2147483647 ]
             height: [ 1, 2147483647 ]
          framerate: [ 0/1, 2147483647/1 ]
     texture-target: 2D

Presence – always

Direction – src

Object type – GstPad

## Signals

### qml-scene-destroyed

    qml_scene_destroyed_callback (GstElement * param_0,
                                  gpointer udata)

    def qml_scene_destroyed_callback (param_0, udata):
        #python callback for the 'qml-scene-destroyed' signal

    function qml_scene_destroyed_callback(param_0: GstElement * param_0, udata: gpointer udata): {
        // javascript callback for the 'qml-scene-destroyed' signal
    }

Parameters:

`param_0` –
No description available
`udata` –
No description available

Flags: Run Last

### qml-scene-initialized

    qml_scene_initialized_callback (GstElement * param_0,
                                    gpointer udata)

    def qml_scene_initialized_callback (param_0, udata):
        #python callback for the 'qml-scene-initialized' signal

    function qml_scene_initialized_callback(param_0: GstElement * param_0, udata: gpointer udata): {
        // javascript callback for the 'qml-scene-initialized' signal
    }

Parameters:

`param_0` –
No description available
`udata` –
No description available

Flags: Run Last

## Properties

### qml-scene

    “qml-scene” gchararray

The contents of the QML scene

Flags : Read / Write

Default value : NULL

### root-item

    “root-item” gpointer

The root QQuickItem from the qml-scene used to render

Flags : Read

### widget

    “widget” gpointer

The QQuickItem to place the input video in the object hierarchy

Flags : Read / Write

The results of the search are