Embedded Compositing

Introduction

From Wikipedia:

A compositing window manager is a window manager that provides applications with an off-screen buffer for each window. The window manager composites the window buffers into an image representing the screen and writes the result into the display memory.

Embedded compositing (or nested compositing) enables applications to nest (embed) other applications' surfaces in their own surface.

RAMSES provides an API for embedded compositing. Note that for embedded compositing to work the platform's system compositor has to support the wayland protocol.

The RAMSES renderer as a provider of the compositing service is called the server, while the other applications embedding their surfaces are called clients.

To establish a connection between the server and its client processes a UNIX domain socket (IPC) is used. There are two distinct ways to create and use such a socket on the RAMSES renderer to use the nested compositing functionality.

In the most common way the RAMSES renderer creates the socket file. This can be done by settig the file name in the display configuration. RAMSES will then on startup (if embedded compositing is available) create the unix domain socket. Client applications can connect to the socket created by the renderer using the socket name, the socket file descriptor or the dedicated environment variables as specified by wayland protocol: WAYLAND_DISPLAY or WAYLAND_SOCKET (for more info refer to official Wayland docs).

Letting RAMSES create the socket file implies that all the clients can be started only after the renderer has fully inititalized. The second way to create a unix domain socket to be used for connection between server and client is to create and bind the unix domain socket outside of RAMSES and only pass it's file descriptor to the renderer. This way, the renderer and all clients can be started separately and independently from each other. For more details, check ramses::DisplayConfig::setWaylandEmbeddedCompositingSocketFD.

Configuration

Configuration might happen via command line or via API.

By default none of these options are set. Thus creation and usage of display will not be possible.

Configuration of embedded compositor's socket is strict. You can set either the socket filename (incl. group name) or the socket file descriptor. These settings are exclusive to each other. If you provide both (file name and file descriptor) creation and usage of display will not be possible.

Socket filename

You can set the name of the socket file. The file will be created in the directory pointed to by $XDG_RUNTIME_DIR

Command line

-wse filename
or
--wayland-socket-embedded filename

API in DisplayConfig

status_t setWaylandEmbeddedCompositingSocketName(const char* socketname);

Socket group ownership.

It's possible to set the groupname for the socket file. If this option is set the group ownership of the socket file will be transered to this group.

Command line

-wsegn groupname
or
--wayland-socket-embedded-groupname groupname

API in DisplayConfig : ramses::DisplayConfig::setWaylandEmbeddedCompositingSocketGroup

Socket file descriptor

Instead of the creating the socket file via RAMSES, you can provide the externally created socket file descriptor.

This works via API in DisplayConfig : ramses::DisplayConfig::setWaylandEmbeddedCompositingSocketFD

Embedded Compositing API

The only type available for RAMSES clients to facilitate embedded compositing is ramses::StreamTexture. The notion behind the StreamTexture is that

• objects of this type can be used the same way and in the same places the normal Texture2D is used
• only the platform (pre)defined surface IDs can be used as its source (see type ramses::waylandIviSurfaceId_t)
• if the surface is not available or the platform doesn't support embedded compositing the default fallback texture is used.

To create the StreamTexture object one needs to call ramses::Scene::createStreamTexture(const Texture2D& fallbackTexture, waylandIviSurfaceId_t source, const char* name). The source is an ID of a surface which will be used for nested compositing. In case that surface is not available or the platform doesn't support embedded compositing the default texture (ie. fallbackTexture) will be used.

Example

The following code show the usage of the embedded compositing API in RAMSES. It creates a 2D quad which uses StreamTexture as its face.

ramses-example-basic-compositing/src/main.cpp

    // IMPORTANT NOTE: For simplicity and readability the example code does not check return values from API calls.
    //                 This should not be the case for real applications.
 
    // texture
    ramses::Texture2D* texture =
        ramses::RamsesUtils::CreateTextureResourceFromPng("res/ramses-example-basic-compositing-texture.png", *scene);
 
    // use Texture2D as fallback for StreamTexture
    ramses::StreamTexture* streamTexture = scene->createStreamTexture(*texture, surfaceId, "streamTexture");