Allow non-toplevel native widgets to be translucent

The requirement

A number of use cases call for semi-transparent Qt content to be overlaid on top of native content. The types of native content on which overlays may need to be displayed include:

• Video playback
• Camera viewfinder
• 3D content

Existing Qt features

Qt provides two facilities which relevant to these use cases:

• Native widgets
  This allows a native window handle to be created for a non-toplevel widget. This in turn means that native rendering APIs can be used to direct content (e.g. video, camera or 3D) into a given widget.
• Translucent windows
  Marking a top-level window as translucent basically means that (a) its backing store gets an alpha channel, and (b) the contents of this alpha channel are respected by the compositing window manager when the window is displayed.

So Qt allows native content to be rendered into a window handle associated with a node in the widget tree, and it allows Qt content to be translucent. It seems therefore as if we should be able to achieve the use cases above by creating a widget tree like the following:

Tree #1

Application (top-level)
|
+-- X (native, targetted by non-Qt rendering API)
    |
    +-- Overlay (native, translucent)

In this way, Qt content could be rendered to the Overlay widget and composed with the non-Qt content which is rendered into X's window handle.

The problem is that, as documented, window translucency is only supported for TLWs, not for native child widgets. This means that the above widget tree must be rewritten as:

Tree #2

Application (top-level)
|
+-- X (native, targetted by non-Qt rendering API)

Overlay (toplevel, translucent)

The problems

1. When Qt is using the OpenVG or OpenGL graphics system, the backing store which it creates for a top-level widget is an EGL window surface. The contents of this backing store can therefore only appear in the native window handle associated with the top-level widget. In tree #1 above, this means that the native content X appears above both the Application and the Overlay content (this is the root cause of QTBUG-12607).
2. The requirement that a translucent overlay widget must be top-level means that it cannot be part of a Qt layout. This in turn means that the application must manually manage the overlay's visibility, z-order, position and size. For example, if the video widget on which an overlay is displayed changes position, the overlay should be moved accordingly. This leads to two issues:
   • Extra burden is put on the application developer. It is possible to use Qt event filters to track the changes listed above, but this can be quite cumbersome - for example, detecting changes in the absolute screen position of a given widget requires event filters to be installed on that widget and all of its ancestors.
   • Updates to overlay position are not synchronised with updates to the position of the content on which the overlay should be placed. Because the overlay window is top-level, it has no relationship (from the POV of the window manager) to the native content window (X in tree #1 above). Each one must therefore be updated independently, leading to visual artefacts. For example, if video content is embedded in a QWebView, and translucent controls placed on top, then as the web page is panned, the overlay will lag behind the video content.

Potential solutions

Using an FBO or pixel buffer instead of an EGL window surface, for the OpenVG / OpenGL backing store, would address problem 1 above.

In order to address problem 2 however, it is necessary to allow non-toplevel native widgets to have their own backing store. The reason for this can easily be seen by considering what happens if the content rendered to X in tree #1 is translucent. In this case, the full extent of the top-level widget can become visible, and child widgets can therefore no longer share the top-level widget's backing store.