QWindowCapture Class
このクラスは、ウィンドウを取得するために使用されます。詳細...
| ヘッダー: | #include <QWindowCapture> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Multimedia) target_link_libraries(mytarget PRIVATE Qt6::Multimedia) |
| qmake: | QT += multimedia |
| 以下のように: | Qt 6.6 |
| QML における: | WindowCapture |
| 継承元: | QObject |
パブリック型
| enum | Error { NoError, InternalError, CapturingNotSupported, CaptureFailed, NotFound } |
プロパティ
|
|
パブリック関数
| QWindowCapture(QObject *parent = nullptr) | |
| virtual | ~QWindowCapture() override |
| QMediaCaptureSession * | captureSession() const |
| QWindowCapture::Error | error() const |
| QString | errorString() const |
| bool | isActive() const |
| std::optional<qreal> | maximumFrameRate() const |
| void | setMaximumFrameRate(std::optional<qreal> frameRate) |
| void | setWindow(QCapturableWindow window) |
| QCapturableWindow | window() const |
パブリックスロット
シグナル
| void | activeChanged(bool) |
| void | errorChanged() |
| void | errorOccurred(QWindowCapture::Error error, const QString &errorString) |
| void | maximumFrameRateChanged() |
| void | windowChanged(QCapturableWindow window) |
静的パブリックメンバー
| QList<QCapturableWindow> | capturableWindows() |
詳細な説明
このクラスはウィンドウをキャプチャします。これはQMediaCaptureSession クラスによって管理され、キャプチャされたウィンドウをビデオプレビューオブジェクトに表示したり、ファイルに記録したりすることができます。
以下のスニペットは、キャプチャ可能なウィンドウの1つを選択し、その結果をQVideoWidget に表示する方法を示しています：
QMediaCaptureSession session;
QWindowCapture windowCapture;
session.setWindowCapture(&windowCapture);
QVideoWidget videoWidget;
session.setVideoOutput(&videoWidget);
videoWidget.show();
// A window must be selected before capturing can start.
const QList<QCapturableWindow> windows = QWindowCapture::capturableWindows();
if (!windows.isEmpty()) {
windowCapture.setWindow(windows.first());
windowCapture.start();
}ウィンドウキャプチャの制限事項
QWindowCaptureの使用には、以下の制限事項が適用されます：
- QWindowCaptureはFFmpegバックエンドでのみサポートされています。
- 一部のプラットフォームでは、キャプチャされたウィンドウの内容が変更されない限り、新しいビデオフレームは出力されません。したがって、アプリケーションは、要求されたフレームレートでフレームの連続したストリームを受信できることを前提にしてはなりません。
X11システムでQWindowCapture を使用する場合、以下の制限が適用されます：
- Linux X11 システムにおいて、ウィンドウが画面の可視領域から部分的に外れた場合、可視領域のみがキャプチャされます。その結果、出力されるビデオフレームのサイズは、ウィンドウのジオメトリよりも小さくなる場合があります。
- 表示可能な画面領域の外側にあるウィンドウはキャプチャできず、その場合はエラー信号が出力されます。
- 最小化されたウィンドウや、非表示の仮想ワークスペース上にあるウィンドウの挙動は、ウィンドウマネージャによって異なります。たとえば、GNOME ではそのようなウィンドウをキャプチャできますが、WindowMaker や Xfwm ではキャプチャが許可されておらず、ウィンドウキャプチャインスタンスはエラーを発生させます。
QMediaCaptureSession およびQCapturableWindowも参照してください 。
メンバ型のドキュメント
enum QWindowCapture::Error
QWindowCapture クラスによって通知される可能性のあるエラーコードを列挙します。errorString()は、エラーの原因に関する詳細情報を提供します。
| 定数 | 値 | 説明 |
|---|---|---|
QWindowCapture::NoError | 0 | エラーなし |
QWindowCapture::InternalError | 1 | 内部ウィンドウキャプチャドライバエラー |
QWindowCapture::CapturingNotSupported | 2 | ウィンドウキャプチャはサポートされていません |
QWindowCapture::CaptureFailed | 4 | ウィンドウのキャプチャに失敗しました |
QWindowCapture::NotFound | 5 | 選択したウィンドウが見つかりません |
プロパティのドキュメント
active : bool
このプロパティは、キャプチャが現在アクティブであるかどうかを示します。
アクセス関数：
| bool | isActive() const |
| void | setActive(bool active) |
通知シグナル：
| void | activeChanged(bool) |
[read-only] error : Error
このプロパティには、直近のエラーのコードが格納されます。
アクセス関数：
| QWindowCapture::Error | error() const |
通知シグナル：
| void | errorChanged() |
[read-only] errorString : QString
このプロパティには、エラーの原因を説明する、人間が読み取れる文字列が格納されています。
アクセス関数：
| QString | errorString() const |
通知シグナル:
| void | errorChanged() |
[since 6.12] maximumFrameRate : std::optional<qreal>
このプロパティは、ウィンドウキャプチャのフレームレートの上限を指定します。
これは、例えばディスプレイのリフレッシュレートに基づいてデフォルトで使用されるキャプチャフレームレートを上書きするように設定できますが、ウィンドウキャプチャは可変レートでフレームを生成するため、あくまで上限値としてのみ機能します。これをディスプレイのリフレッシュレートよりも高く設定することは推奨されず、エラーの原因となる可能性があります。
このプロパティへの変更は、QWindowCapture が次にアクティブになったときに反映されます。
この列挙型は Qt 6.12 で導入されました。
アクセス関数：
| std::optional<qreal> | maximumFrameRate() const |
| void | setMaximumFrameRate(std::optional<qreal> frameRate) |
Notifierシグナル:
| void | maximumFrameRateChanged() |
window : QCapturableWindow
このプロパティは、キャプチャ対象のウィンドウを保持します。
アクティブなQWindowCapture 上で、このプロパティを無効なウィンドウに設定すると、そのウィンドウは非アクティブ状態になり、エラーが発生します。
アクセス関数：
| QCapturableWindow | window() const |
| void | setWindow(QCapturableWindow window) |
Notifierシグナル:
| void | windowChanged(QCapturableWindow window) |
「QWindowCapture::capturableWindows」も参照してください 。
メンバ関数のドキュメント
[explicit] QWindowCapture::QWindowCapture(QObject *parent = nullptr)
parent を使用して、新しい QWindowCapture オブジェクトを作成します。
[override virtual noexcept] QWindowCapture::~QWindowCapture()
そのオブジェクトを破棄します。
[static invokable] QList<QCapturableWindow> QWindowCapture::capturableWindows()
現在キャプチャ可能なQCapturableWindow オブジェクトのリストを返します。
注：macOSでは 、このメソッドを呼び出すと「画面録画」の権限ダイアログが表示されます。まだ権限が付与されていない場合、このメソッドは空のリストを返します。複数回呼び出すと、このダイアログが最前面に表示されます。
注：この関数は 、メタオブジェクトシステムやQMLから呼び出すことができます。Q_INVOKABLE を参照してください。
QMediaCaptureSession *QWindowCapture::captureSession() const
このQWindowCapture が接続されているキャプチャセッションを返します。
QMediaCaptureSession::setWindowCapture() を使用して、ウィンドウキャプチャをセッションに接続します。
[signal] void QWindowCapture::errorChanged()
このシグナルは、error またはerrorString プロパティが変更されたときに発生します。
同一のエラーが複数回発生した場合、このシグナルは発火しません。そのようなエラーを追跡するには、errorOccurred シグナルを使用してください。
注： プロパティerror およびerrorString に対する通知 シグナルです。
[signal] void QWindowCapture::errorOccurred(QWindowCapture::Error error, const QString &errorString)
error が発生した際に、errorString と共にシグナルを発します。
[slot] void QWindowCapture::start()
window のキャプチャを開始します。
これは、active プロパティを true に設定することと同じです。
[slot] void QWindowCapture::stop()
キャプチャを停止します。
これは、active プロパティをfalseに設定するのと同じ効果があります。
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.
