# qmlglsink

qmlglsink provides a way to render a video stream as a Qml object inside the Qml scene graph. This is achieved by providing the incoming OpenGL textures to Qt as a scene graph object.

qmlglsink 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 qmlglsink to an already running pipeline
2. Not having any qmlglsink (or qmlgloverlay) 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 qmlglsink element or a qmlgloverlay element. The recommended usage is to have either element (qmlglsink or qmlgloverlay) 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 a dynamically adding qmlglsink (or qmlgloverlay) to a pipeline case, there are some considerations for ensuring that the window system display and OpenGL contexts are compatible with Qt. When the qmlgloverlay (or qmlglsink) 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 qmlglsink and qmlgloverlay will return the exact same GstGLDisplay object while the pipeline is running regardless of whether any qmlglsink or qmlgloverlay elements are added or removed from the pipeline.

## Hierarchy

    GObject
        ╰──GInitiallyUnowned
            ╰──GstObject
                ╰──GstElement
                    ╰──GstBaseSink
                        ╰──GstVideoSink
                            ╰──qmlglsink

## Implemented interfaces

    GstNavigation

## Factory details

Authors: – Matthew Waters

Classification: – `Sink/Video`

Rank – none

Plugin – qmlgl

Package – GStreamer Good Plug-ins

## Pad Templates

### `sink`

    video/x-raw(memory:GLMemory):
             format: { RGB, RGBA, RGB16, BGRA, BGR16, YV12, NV12 }
              width: [ 1, 2147483647 ]
             height: [ 1, 2147483647 ]
          framerate: [ 0/1, 2147483647/1 ]
     texture-target: { (string)2D, (string)external-oes }

Presence – always

Direction – sink

Object type – GstPad

## Properties

### async

    “async” gboolean

Go asynchronously to PAUSED

Flags : Read / Write

Default value : true

### blocksize

    “blocksize” guint

Size in bytes to pull per buffer (0 = default)

Flags : Read / Write

Default value : 4096

### enable-last-sample

    “enable-last-sample” gboolean

Enable the last-sample property

Flags : Read / Write

Default value : true

### force-aspect-ratio

    “force-aspect-ratio” gboolean

When enabled, scaling will respect original aspect ratio

Flags : Read / Write

Default value : true

### last-sample

    “last-sample” GstSample *

The last sample received in the sink

Flags : Read

### max-bitrate

    “max-bitrate” guint64

The maximum bits per second to render (0 = disabled)

Flags : Read / Write

Default value : 0

### max-lateness

    “max-lateness” gint64

Maximum number of nanoseconds that a buffer can be late before it is dropped (-1 unlimited)

Flags : Read / Write

Default value : 5000000

### pixel-aspect-ratio

    “pixel-aspect-ratio” GstFraction *

The pixel aspect ratio of the device

Flags : Read / Write

Default value : 0/1

### processing-deadline

    “processing-deadline” guint64

Maximum processing time for a buffer in nanoseconds

Flags : Read / Write

Default value : 15000000

### qos

    “qos” gboolean

Generate Quality-of-Service events upstream

Flags : Read / Write

Default value : true

### render-delay

    “render-delay” guint64

Additional render delay of the sink in nanoseconds

Flags : Read / Write

Default value : 0

### show-preroll-frame

    “show-preroll-frame” gboolean

Whether to render video frames during preroll

Flags : Read / Write / Construct

Default value : true

### stats

    “stats” GstStructure *

Sink Statistics

Flags : Read

Default value :

    application/x-gst-base-sink-stats, average-rate=(double)0, dropped=(guint64)0, rendered=(guint64)0;

### sync

    “sync” gboolean

Sync on the clock

Flags : Read / Write

Default value : true

### throttle-time

    “throttle-time” guint64

The time to keep between rendered buffers (0 = disabled)

Flags : Read / Write

Default value : 0

### ts-offset

    “ts-offset” gint64

Timestamp offset in nanoseconds

Flags : Read / Write

Default value : 0

### widget

    “widget” gpointer

The QQuickItem to place in the object hierarchy

Flags : Read / Write

The results of the search are