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 클래스에 의해 관리되며, 캡처된 창은 비디오 미리보기 객체에 표시되거나 파일로 기록될 수 있습니다.
다음 코드 조각은 캡처 가능한 창 중 하나를 선택하고 그 결과를 ` 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) |
알림 신호:
| 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.
