qsyntheticpipewirevideosource_p.h

Go to the documentation of this file.

// Copyright (C) 2026 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GPL-3.0-only
 
#ifndef QSYNTHETICPIPEWIREVIDEOSOURCE_P_H
#define QSYNTHETICPIPEWIREVIDEOSOURCE_P_H
 
//
//  W A R N I N G
//  -------------
//
// This file is not part of the Qt API. It exists purely as an
// implementation detail. This header file may change from version to
// version without notice, or even be removed.
//
// We mean it.
//
 
#include <QtMultimedia/private/qpipewire_support_p.h>
#include <QtCore/qobject.h>
#include <QtCore/qstring.h>
#include <QtCore/private/qexpected_p.h>
 
#include <private/qsyntheticvideoscene_p.h>
 
#include <memory>
 
QT_BEGIN_NAMESPACE
 
/*!
    \internal
    Identity of a synthetic source: what it advertises to the PipeWire graph.
 
    media.role is load-bearing, not cosmetic. It is how the source decides which
    consumers are meant for it -- see QSyntheticPipeWireVideoSource.
*/
struct QSyntheticPipeWireVideoSourceConfig
{
    QByteArray loopName = QByteArrayLiteral("qt-fake-sc");
    QByteArray nodeName = QByteArrayLiteral("qt-fake-screencast");
    QByteArray nodeDescription = QByteArrayLiteral("Qt Multimedia synthetic screen cast source");
    QByteArray mediaClass = QByteArrayLiteral("Stream/Output/Video");
    QByteArray mediaRole = QByteArrayLiteral("Screen");
    QByteArray mediaCategory = QByteArrayLiteral("Capture");
 
    //! A screen-cast source, as xdg-desktop-portal's ScreenCast interface hands out.
    [[nodiscard]] static QSyntheticPipeWireVideoSourceConfig screenCast();
 
    /*!
        A camera source, as the Camera interface hands out: media.class Video/Source
        plus media.role Camera. device.api is deliberately left unset, so that a
        client identifying cameras exercises the media.role branch -- the one a real
        camera portal hits -- rather than the v4l2/libcamera hardware fallback.
    */
    [[nodiscard]] static QSyntheticPipeWireVideoSourceConfig camera(int index = 0);
};
 
/*!
    \internal
 
    A synthetic PipeWire video source: an output pw_stream advertising
    \c {media.class = Stream/Output/Video} that publishes frames rendered by
    paintSyntheticVideoScene(). It stands in for a compositor's screen-cast stream,
    so QPipeWireCaptureHelper can be exercised without a real desktop portal.
 
    The pixel format is fixed to SPA_VIDEO_FORMAT_BGRx, which maps to
    QVideoFrameFormat::Format_BGRX8888 on the consuming side and is byte-identical
    to QImage::Format_RGB32 on little-endian, avoiding a pixel format conversion.
 
    The source also acts as its own session manager: when it is used against a
    private pipewire daemon there is no WirePlumber, so nothing honours
    PW_STREAM_FLAG_AUTOCONNECT and the consumer would sit in "paused" forever.
    The source therefore links itself, via the link-factory, to consumers meant
    for it.
 
    Which consumers are "meant for it" is determined by matching media.role, not
    by the target passed to pw_stream_connect(): PipeWire consumes that target
    internally, and the resulting consumer node advertises neither target.object
    nor node.target. media.role is the one property a consumer does advertise --
    QPipeWireCaptureHelper sets Screen, a camera client sets Camera -- so the
    source links only consumer nodes whose media.role matches its own. This
    matters as soon as one graph holds both a screen-cast and a camera source:
    matching by media.role is what keeps camera frames from being linked to a
    screen-capture client.
*/
class QSyntheticPipeWireVideoSource
{
public:
    QSyntheticPipeWireVideoSource();
    ~QSyntheticPipeWireVideoSource();
 
    Q_DISABLE_COPY_MOVE(QSyntheticPipeWireVideoSource)
 
    /*!
        Connects to the PipeWire daemon and publishes the source. Blocks until the
        node id is known, so that nodeId() is usable as soon as this returns.
    */
    q23::expected<void, QString> start(const SyntheticVideoScene &scene,
                                       const QSyntheticPipeWireVideoSourceConfig &config =
                                               QSyntheticPipeWireVideoSourceConfig::screenCast());
    void stop();
 
    //! The PipeWire node id to hand to a consumer. Valid only after a successful start().
    [[nodiscard]] QtPipeWire::ObjectId nodeId() const;
 
    //! Replaces the published content. Safe to call from any thread.
    void setScene(const SyntheticVideoScene &scene);
 
    //! Renders and publishes the next frame. Safe to call from any thread.
    void renderNextFrame();
 
private:
    class Private;
    std::unique_ptr<Private> d;
};
 
QT_END_NAMESPACE
 
#endif // QSYNTHETICPIPEWIREVIDEOSOURCE_P_H