QQuickWindow Class

멤버 함수 문서

[explicit] QQuickWindow::QQuickWindow(QQuickRenderControl *control)

control 객체가 렌더링을 제어하는 QML 씬을 표시하기 위한 창을 생성합니다. 자세한 내용은 QQuickRenderControl 의 문서를 참조하십시오.

[explicit] QQuickWindow::QQuickWindow(QWindow *parent = nullptr)

parent 를 부모 창으로 하여 QML 씬을 표시하는 창을 생성합니다.

[override virtual noexcept] QQuickWindow::~QQuickWindow()

창을 닫습니다.

[override virtual] QAccessibleInterface *QQuickWindow::accessibleRoot() const

이 창의 접근성 인터페이스를 반환하거나, 해당 인터페이스를 생성할 수 없는 경우 0을 반환합니다.

[signal] void QQuickWindow::afterAnimating()

이 신호는 렌더 스레드에 씬 그래프의 동기화를 수행하도록 요청하기 전에 GUI 스레드에서 발생합니다.

다른 유사한 신호들과 달리, 이 신호는 렌더 스레드가 아닌 GUI 스레드에서 발생합니다. 이 신호를 사용하면 외부 애니메이션 시스템을 QML 콘텐츠와 동기화할 수 있습니다. 동시에 이는 이 신호가 그래픽 작업을 트리거하는 데 적합하지 않음을 의미합니다.

[signal, since 6.0] void QQuickWindow::afterFrameEnd()

이 신호는 씬 그래프가 프레임을 제출했을 때 발생합니다. 이 신호는 afterRendering()와 같은 다른 모든 관련 신호가 발생한 후에 발생합니다. 이는 씬 그래프 렌더링 스레드가 프레임을 렌더링할 때 발생하는 마지막 신호입니다.

이 함수는 Qt 6.0에서 도입되었습니다.

beforeFrameBegin() 및 rendererInterface()도 참조하십시오 .

[signal] void QQuickWindow::afterRenderPassRecording()

이 신호는 씬그래프가 메인 렌더 패스에 대한 명령을 기록한 후, 해당 패스가 아직 명령 버퍼에서 최종 확정되지 않은 시점에 발생합니다.

이 신호는 ` afterRendering()`보다 먼저 발생하며, 프레임뿐만 아니라 씬그래프의 메인 렌더 패스 기록도 여전히 활성 상태임을 보장합니다. 이를 통해 별도의 전체 렌더 패스를 생성하지 않고도(일반적으로 연결된 이미지를 지워버리는 작업) 명령어를 삽입할 수 있습니다. 네이티브 그래픽스 객체는 ` QSGRendererInterface`를 통해 조회할 수 있습니다.

rendererInterface() 및 QML의 ‘씬 그래프 - RHI’항목도 참조하십시오 .

[signal] void QQuickWindow::afterRendering()

이 신호는 씬 그래프가 명령을 명령 버퍼에 추가한 후, 해당 명령 버퍼가 아직 그래픽 큐에 제출되기 전에 발신됩니다. 원하는 경우, 이 신호에 연결된 슬롯 함수는 ` QSGRendererInterface`를 통해 명령 버퍼와 같은 네이티브 리소스를 미리 조회할 수 있습니다. 다만 이 시점에서는 렌더 패스(들)가 이미 기록된 상태이므로, 씬그래프의 패스 내에 명령을 더 추가할 수는 없다는 점에 유의하십시오. 대신, 이를 위해서는 ` afterRenderPassRecording()`를 사용하십시오. 따라서 이 신호는 Qt 5와 달리 Qt 6에서는 사용 범위가 제한적입니다. 오히려 사용자 정의 렌더링의 언더레이 또는 오버레이를 구현하기 위해서는 일반적으로 ` beforeRendering()`와 ` beforeRenderPassRecording()`, 또는 ` beforeRendering()`와 ` afterRenderPassRecording()`의 조합이 사용됩니다.

rendererInterface(), QML 환경의 씬 그래프 - RHI, QML 환경의 씬 그래프 - OpenGL, QML 환경의 씬 그래프 - Metal, QML 환경의 씬 그래프 - Vulkan, QML 환경의 씬 그래프 - Direct3D 11항목도 참조하십시오.

[signal] void QQuickWindow::afterSynchronizing()

이 신호는 씬 그래프가 QML 상태와 동기화된 후에 발생합니다.

이 신호는 GUI 스레드가 여전히 잠겨 있는 상태에서 ` QQuickItem::updatePaintNode()` 호출 후 필요한 준비 작업을 수행하는 데 사용할 수 있습니다.

OpenGL을 사용할 경우, 이 시점에서 씬 그래프의 렌더링에 사용되는 QOpenGLContext 가 바인딩됩니다.

[signal, since 6.0] void QQuickWindow::beforeFrameBegin()

이 신호는 씬 그래프가 프레임 준비를 시작하기 전에 발생합니다. 이는 ` beforeSynchronizing()`이나 ` beforeRendering()`와 같은 신호보다 먼저 발생합니다. 이는 씬 그래프 렌더링 스레드가 새로운 프레임 준비를 시작할 때 발생시키는 가장 초기 단계의 신호입니다.

이 신호는 Qt Quick 이 기본 렌더링 하드웨어 인터페이스 API를 통해 새 프레임의 기록을 시작하지 않은 단계에서 리소스 정리와 같은 특정 작업을 실행해야 하는 저수준 그래픽 프레임워크와 관련이 있습니다.

이 함수는 Qt 6.0에서 도입되었습니다.

afterFrameEnd() 및 rendererInterface()도 참조하십시오 .

[signal] void QQuickWindow::beforeRenderPassRecording()

이 신호는 씬그래프가 메인 렌더 패스에 대한 명령을 기록하기 시작하기 전에 발생합니다. (레이어는 각각 고유한 패스를 가지며, 이 신호가 발생할 때쯤이면 이미 기록이 완료된 상태입니다.) 신호가 발생할 때, 렌더 패스는 이미 명령 버퍼에서 활성화된 상태입니다.

이 신호는 beforeRendering()보다 늦게 발산되며, 프레임뿐만 아니라 씬그래프의 메인 렌더 패스 기록도 활성화되어 있음을 보장합니다. 이를 통해 별도의 전체 렌더 패스를 생성하지 않고도(일반적으로 이 경우 연결된 이미지가 지워집니다) 명령을 삽입할 수 있습니다. 네이티브 그래픽스 객체는 QSGRendererInterface 를 통해 조회할 수 있습니다.

rendererInterface() 및 QML의 ‘씬 그래프 - RHI’항목도 참조하십시오 .

[signal] void QQuickWindow::beforeRendering()

이 신호는 프레임 준비가 완료된 후 전송되며, 이는 해당되는 경우 명령 버퍼가 기록 모드에 있음을 의미합니다. 원하는 경우, 이 신호에 연결된 슬롯 함수는 ` QSGRendererInterface`를 통해 앞서 설명한 명령어와 같은 네이티브 리소스를 조회할 수 있습니다. 다만, 이 시점에서는 메인 렌더 패스의 녹화가 아직 시작되지 않았으며, 해당 패스 내에 명령어를 추가할 수 없다는 점에 유의하십시오. 패스를 시작한다는 것은 색상, 깊이, 스텐실 버퍼를 지우는 것을 의미하므로, 이 신호에만 연결해서는 언더레이(underlay) 유형의 렌더링을 구현할 수 없습니다. 대신 ` beforeRenderPassRecording()`에 연결해야 합니다. 그러나 복사(copy) 유형의 명령어 녹화를 원하는 경우, 해당 명령어는 렌더 패스 내에서 큐에 넣을 수 없으므로 이 신호에 연결하는 것이 여전히 중요합니다.

rendererInterface(), QML 기반 씬 그래프 - RHI, QML 기반 씬 그래프 - OpenGL, QML 기반 씬 그래프 - Metal, QML 기반 씬 그래프 - Vulkan 및 QML 기반 씬 그래프 - Direct3D 11항목도 참조하십시오.

[signal] void QQuickWindow::beforeSynchronizing()

이 신호는 씬 그래프가 QML 상태와 동기화되기 전에 발생합니다.

이 신호는 씬 그래프 렌더링 스레드에서 발산되지만, ` QQuickItem::updatePaintNode()`에서와 마찬가지로 GUI 스레드가 차단되는 것이 보장됩니다. 따라서 ` Qt::DirectConnection`에 연결된 슬롯이나 람다 내에서 GUI 스레드의 데이터에 안전하게 접근할 수 있습니다.

이 신호는 QQuickItem::updatePaintNode()를 호출하기 전에 필요한 모든 준비 작업을 수행하는 데 사용할 수 있습니다.

OpenGL을 사용할 때, 이 시점에서 씬 그래프의 렌더링에 사용되는 ` QOpenGLContext `가 바인딩됩니다.

void QQuickWindow::beginExternalCommands()

원시 그래픽(OpenGL, Vulkan, Metal 등) 명령어를 씬 그래프 렌더링과 혼합할 때는, 씬 그래프가 메인 렌더 패스를 렌더링하는 데 사용하는 명령어 버퍼에 명령어를 기록하기 전에 이 함수를 호출해야 합니다. 이는 상태가 손상되는 것을 방지하기 위함입니다.

실제로 이 함수는 주로 ` beforeRenderPassRecording()` 또는 ` afterRenderPassRecording()` 신호에 연결된 슬롯에서 호출됩니다.

애플리케이션 자체의 명령 버퍼(예: 씬 그래프에서 가져온 것이 아닌, 애플리케이션에서 생성 및 관리하는 VkCommandBuffer 또는 MTLCommandBuffer + MTLRenderCommandEncoder)에 명령을 기록할 때는 이 함수를 호출할 필요가 없습니다. 네이티브 명령 버퍼 개념이 노출되지 않는 그래픽 API(OpenGL, Direct 3D 11)의 경우, beginExternalCommands()와 endExternalCommands()을 함께 사용하면 Qt 5의 resetOpenGLState() 함수를 대체할 수 있습니다.

QSGRenderNode 의 render() 구현 내에서 이 함수와 endExternalCommands()을 호출할 필요는 없습니다. 씬 그래프가 렌더 노드에 대해 필요한 단계를 암시적으로 수행하기 때문입니다.

QSGRendererInterface::getResource()을 통해 네이티브 그래픽스 객체(예: 그래픽스 장치, 명령 버퍼 또는 인코더)에 접근할 수 있습니다.

endExternalCommands() 및 QQuickOpenGLUtils::resetOpenGLState()도 참조하십시오 .

[override virtual protected] void QQuickWindow::closeEvent(QCloseEvent *e)

QWindow::closeEvent(QCloseEvent *ev)를 재구현합니다.

QSGImageNode *QQuickWindow::createImageNode() const

간단한 이미지 노드를 생성합니다. 씬그래프가 초기화되지 않은 경우, 반환 값은 null입니다.

이는 QSGSimpleTextureNode 를 직접 생성하는 방법에 대한 백엔드 간 호환 대안입니다.

QSGImageNode도 참조하십시오 .

QSGNinePatchNode *QQuickWindow::createNinePatchNode() const

나인 패치 노드를 생성합니다. 씬그래프가 초기화되지 않은 경우, 반환 값은 null입니다.

QSGRectangleNode *QQuickWindow::createRectangleNode() const

간단한 직사각형 노드를 생성합니다. 씬그래프가 초기화되지 않은 경우, 반환 값은 null입니다.

이는 ` QSGSimpleRectNode `을 직접 생성하는 방법에 대한 백엔드 간 호환이 가능한 대안입니다.

QSGRectangleNode도 참조하십시오 .

[since 6.7] QSGTextNode *QQuickWindow::createTextNode() const

텍스트 노드를 생성합니다. 씬그래프가 초기화되지 않은 경우, 반환 값은 null입니다.

이 함수는 Qt 6.7에서 도입되었습니다.

QSGTextNode도 참조하십시오 .

QSGTexture *QQuickWindow::createTextureFromImage(const QImage &image, QQuickWindow::CreateTextureOptions options) const

지정된 ` image`를 사용하여 새로운 ` QSGTexture `를 생성합니다. 이미지에 알파 채널이 있는 경우, 해당 텍스처에도 알파 채널이 포함됩니다.

반환된 텍스처를 삭제하는 것은 이 함수를 호출한 측의 책임입니다. 이후 기본이 되는 네이티브 텍스처 객체는 QSGTexture 와 함께 파기됩니다.

options 에 TextureCanUseAtlas 가 포함된 경우, 엔진은 해당 이미지를 텍스처 아틀라스에 배치할 수 있습니다. 아틀라스 내의 텍스처는 기하학적 정보를 얻기 위해 QSGTexture::normalizedTextureSubRect()에 의존해야 하며, QSGTexture::Repeat 를 지원하지 않습니다. CreateTextureOption 의 다른 값들은 무시됩니다.

options 에 TextureIsOpaque 가 포함되어 있으면, 엔진은 QSGTexture::hasAlphaChannel()에 대해 false를 반환하는 RGB 텍스처를 생성합니다. 불투명 텍스처는 대부분의 경우 렌더링 속도가 더 빠릅니다. 이 플래그가 설정되지 않은 경우, 텍스처는 이미지의 형식에 따라 알파 채널을 갖게 됩니다.

options 에 TextureHasMipmaps 가 포함되면, 엔진은 밉맵 필터링을 사용할 수 있는 텍스처를 생성합니다. 밉맵이 적용된 텍스처는 아틀라스에 포함될 수 없습니다.

이 함수의 경우 알파 채널과 블렌딩이 기본값이므로, TextureHasAlphaChannel 를 options 로 설정해도 아무런 효과가 없습니다. 이를 비활성화하려면 TextureIsOpaque 를 설정하십시오.

씬 그래프가 OpenGL을 사용하는 경우, 반환되는 텍스처는 텍스처 타깃으로 ` GL_TEXTURE_2D `을, 내부 형식으로 ` GL_RGBA `을 사용합니다. 다른 그래픽 API를 사용하는 경우, 텍스처 형식은 일반적으로 ` RGBA8`입니다. 다른 매개변수를 사용하여 텍스처를 생성하려면 ` QSGTexture `을 재구현하십시오.

이 함수는 메인 스레드와 렌더링 스레드 모두에서 호출할 수 있습니다.

sceneGraphInitialized() 및 QSGTexture도 참조하십시오 .

QSGTexture *QQuickWindow::createTextureFromImage(const QImage &image) const

[since 6.6] QSGTexture *QQuickWindow::createTextureFromRhiTexture(QRhiTexture *texture, QQuickWindow::CreateTextureOptions options = {}) const

지정된 ` texture`를 기반으로 새로운 ` QSGTexture `를 생성합니다.

options 를 사용하여 텍스처 속성을 사용자 정의할 수 있습니다. 이 함수는 TextureHasAlphaChannel 플래그만 고려합니다. 이 플래그가 설정되면, 결과 QSGTexture 는 장면 그래프 렌더러에 의해 항상 블렌딩이 필요한 것으로 처리됩니다. 완전히 불투명한 텍스처의 경우, 이 플래그를 설정하지 않으면 렌더링 중 알파 블렌딩을 수행하는 데 드는 비용을 절약할 수 있습니다. 이 플래그는 ` QRhiTexture`의 ` format `과 직접적인 대응 관계가 없습니다. 즉, 일반적으로 사용되는 ` QRhiTexture::RGBA8 `와 같은 텍스처 형식을 사용하는 동안 이 플래그를 설정하지 않는 것은 완전히 정상적인 현상입니다.

미프매핑은 options 에 의해 제어되지 않습니다. texture 는 이미 생성되어 있으며, 미프맵의 유무가 미리 내장되어 있기 때문입니다.

반환된 ` QSGTexture `는 ` QRhiTexture`를 소유하고 있으므로, ` texture `는 반환된 ` QSGTexture`와 함께 소멸됩니다.

texture 가 기본이 되는 네이티브 그래픽 리소스(OpenGL 텍스처 객체, Vulkan 이미지 등)를 소유하는지 여부는 QRhiTexture 가 어떻게 생성되었는지에 따라 달라지며(QRhiTexture::create() 또는 QRhiTexture::createFrom()), 이는 이 함수에 의해 제어되거나 변경되지 않습니다.

이 함수는 Qt 6.6에서 도입되었습니다.

createTextureFromImage(), sceneGraphInitialized() 및 QSGTexture도 참조하십시오 .

[signal, since 6.11] void QQuickWindow::devicePixelRatioChanged()

이 신호는 유효 디바이스 픽셀 비율이 변경되었을 때 발생합니다.

이 함수는 Qt 6.11에서 도입되었습니다.

effectiveDevicePixelRatio()도 참조하십시오 .

qreal QQuickWindow::effectiveDevicePixelRatio() const

이 창의 장치 픽셀 비율을 반환합니다.

이 함수는 QWindow::devicePixelRatio()과는 달리, QQuickRenderControl 및 QQuickRenderTarget 를 통한 리디렉션 렌더링을 지원한다는 점에서 다릅니다. QQuickRenderControl 를 사용할 때, QQuickWindow 는 종종 완전히 생성되지 않는데, 이는 해당 창이 표시되지 않을 뿐만 아니라 윈도우 시스템 내에 기본 네이티브 창이 생성되지 않음을 의미합니다. 결과적으로, 디바이스 픽셀 비율과 같은 속성을 조회하면 올바른 결과를 얻을 수 없습니다. 이 함수는 QQuickRenderControl::renderWindowFor()와 QQuickRenderTarget::devicePixelRatio()를 모두 고려합니다. 리디렉션이 적용되지 않은 경우, 결과는 QWindow::devicePixelRatio()와 동일합니다.

QQuickRenderControl, QQuickRenderTarget, setRenderTarget() 및 QWindow::devicePixelRatio()도 참조하십시오 .

void QQuickWindow::endExternalCommands()

원시 그래픽(OpenGL, Vulkan, Metal 등) 명령어를 씬 그래프 렌더링과 혼합하여 사용할 경우, 씬 그래프가 메인 렌더 패스를 렌더링하는 데 사용하는 명령 버퍼에 명령어를 기록한 후 이 함수를 호출해야 합니다. 이는 상태의 손상을 방지하기 위함입니다.

실제로 이 함수는 주로 ` beforeRenderPassRecording()` 또는 ` afterRenderPassRecording()` 신호에 연결된 슬롯에서 호출됩니다.

애플리케이션 자체의 명령 버퍼(예: 씬 그래프에서 가져온 것이 아니라 애플리케이션에서 생성 및 관리하는 VkCommandBuffer 또는 MTLCommandBuffer + MTLRenderCommandEncoder)에 명령을 기록할 때는 이 함수를 호출할 필요가 없습니다. 네이티브 명령 버퍼 개념이 노출되지 않는 그래픽 API(OpenGL, Direct 3D 11)의 경우, beginExternalCommands()과 endExternalCommands()를 함께 사용하면 Qt 5의 resetOpenGLState() 함수를 대체할 수 있습니다.

QSGRenderNode 의 render() 구현 내에서는 이 함수와 beginExternalCommands()을 호출할 필요가 없습니다. 씬 그래프가 렌더 노드에 대해 필요한 단계를 암시적으로 수행하기 때문입니다.

beginExternalCommands() 및 QQuickOpenGLUtils::resetOpenGLState()도 참조하십시오 .

[override virtual protected] bool QQuickWindow::event(QEvent *event)

QWindow::event(QEvent *ev)를 재구현합니다.

[override virtual protected] void QQuickWindow::exposeEvent(QExposeEvent *)

QWindow::exposeEvent(QExposeEvent *ev)를 재구현합니다.

[override virtual protected] void QQuickWindow::focusInEvent(QFocusEvent *ev)

QWindow::focusInEvent(QFocusEvent *ev)를 재구현합니다.

[override virtual protected] void QQuickWindow::focusOutEvent(QFocusEvent *ev)

QWindow::focusOutEvent(QFocusEvent *ev)를 재구현합니다.

[signal] void QQuickWindow::frameSwapped()

이 신호는 프레임이 표시를 위해 큐에 등록되었을 때 발생합니다. 수직 동기화가 활성화된 경우, 지속적으로 애니메이션이 재생되는 장면에서는 이 신호가 vsync 간격당 최대 한 번 발생합니다.

이 신호는 씬 그래프 렌더링 스레드에서 발생합니다.

QImage QQuickWindow::grabWindow()

창의 내용을 가져와 이미지로 반환합니다.

창이 보이지 않는 상태에서도 grabWindow() 함수를 호출할 수 있습니다. 이를 위해서는 창이 created 상태여야 하고 유효한 크기를 가져야 하며, 동일한 프로세스에서 다른 QQuickWindow 인스턴스가 렌더링되고 있지 않아야 합니다.

[static, since 6.0] QSGRendererInterface::GraphicsApi QQuickWindow::graphicsApi()

현재 시점에서 씬 그래프가 초기화되었다면 사용되었을 그래픽 API를 반환합니다.

씬 그래프가 사용하는 API를 조회하는 표준 방법은, 씬 그래프가 초기화된 후(예를 들어 ` sceneGraphInitialized()` 신호가 발산될 때나 그 이후) ` QSGRendererInterface::graphicsApi()`를 사용하는 것입니다. 이 경우, 해당 그래픽 API를 사용하여 모든 것이 올바르게 초기화되었음이 확인되므로, 실제 정확한 결과를 얻을 수 있습니다.

하지만 이것이 항상 편리한 것은 아닙니다. 애플리케이션이 외부 프레임워크를 설정해야 하거나, setGraphicsDevice()를 장면 그래프의 내장 API 선택 논리에 의존하는 방식으로 사용해야 하는 경우, QQuickWindow 가 가시화되거나 QQuickRenderControl::initialize()가 호출된 후까지 이러한 작업을 미루는 것이 항상 가능한 것은 아닙니다.

따라서 이 정적 함수는 ` setGraphicsApi()`의 대응 기능으로 제공됩니다. 이 함수는 언제든지 호출할 수 있으며, 그 결과는 호출 시점에 씬 그래프가 초기화되었다면 어떤 API를 선택했을지를 반영합니다.

이 함수는 Qt 6.0에서 도입되었습니다.

setGraphicsApi()도 참조하십시오 .

[since 6.0] QQuickGraphicsConfiguration QQuickWindow::graphicsConfiguration() const

setGraphicsConfiguration()에 전달된 ` QQuickGraphicsConfiguration `를 반환하거나, 그렇지 않은 경우 기본 생성된 객체를 반환합니다.

이 함수는 Qt 6.0에서 도입되었습니다.

setGraphicsConfiguration()도 참조하십시오 .

[since 6.0] QQuickGraphicsDevice QQuickWindow::graphicsDevice() const

setGraphicsDevice()에 전달된 ` QQuickGraphicsDevice `를 반환하거나, 그렇지 않은 경우 기본 생성된 객체를 반환합니다.

이 함수는 Qt 6.0에서 도입되었습니다.

setGraphicsDevice()도 참조하십시오 .

const QQuickWindow::GraphicsStateInfo &QQuickWindow::graphicsStateInfo()

RHI의 내부 상태 중 일부, 특히 백엔드(예: Vulkan 또는 Metal 통합)의 더블 또는 트리플 버퍼링 상태를 설명하는 ` GraphicsStateInfo ` 구조체에 대한 참조를 반환합니다. 이는 기본 그래픽 API가 Vulkan이나 Metal인 경우, 외부 렌더링 코드가 파이프라인 정지를 방지하기 위해 유니폼 버퍼와 같이 자주 변경되는 리소스에 대해 자체적으로 더블 또는 트리플 버퍼링을 수행하고자 할 때 관련이 있습니다.

[static] bool QQuickWindow::hasDefaultAlphaBuffer()

새로 생성된 창에 알파 투명도를 적용할지 여부를 반환합니다.

setDefaultAlphaBuffer()도 참조하십시오 .

[override virtual protected] void QQuickWindow::hideEvent(QHideEvent *)

QWindow::hideEvent(QHideEvent *ev)를 재구현합니다.

QQmlIncubationController *QQuickWindow::incubationController() const

이 창의 프레임 사이에 인큐베이션을 삽입하는 인큐베이션 컨트롤러를 반환합니다. QQuickView 에서는 이 컨트롤러를 자동으로 설치해 주지만, 그렇지 않은 경우 QQmlEngine::setIncubationController()를 사용하여 직접 설치해야 합니다.

이 컨트롤러는 해당 창이 소유하며, 창이 삭제되면 함께 소멸됩니다.

bool QQuickWindow::isPersistentGraphics() const

QQuickWindow 의 수명 기간 동안 필수 그래픽 리소스를 해제할 수 있는지 여부를 반환합니다.

setPersistentGraphics()도 참조하십시오 .

bool QQuickWindow::isPersistentSceneGraph() const

이 ` QQuickWindow`의 수명 기간 동안 씬 그래프 노드와 리소스를 해제할 수 있는지 여부를 반환합니다.

bool QQuickWindow::isSceneGraphInitialized() const

씬 그래프가 초기화된 경우 true를 반환하고, 그렇지 않으면 false를 반환합니다.

[override virtual protected] void QQuickWindow::keyPressEvent(QKeyEvent *e)

QWindow::keyPressEvent(QKeyEvent *ev)를 재구현합니다.

[override virtual protected] void QQuickWindow::keyReleaseEvent(QKeyEvent *e)

QWindow::keyReleaseEvent(QKeyEvent *ev)를 재구현합니다.

[override virtual protected] void QQuickWindow::mouseDoubleClickEvent(QMouseEvent *event)

QWindow::mouseDoubleClickEvent(QMouseEvent *ev)를 재구현합니다.

[override virtual protected] void QQuickWindow::mouseMoveEvent(QMouseEvent *event)

QWindow::mouseMoveEvent(QMouseEvent *ev)를 재구현합니다.

[override virtual protected] void QQuickWindow::mousePressEvent(QMouseEvent *event)

QWindow::mousePressEvent(QMouseEvent *ev)를 재구현합니다.

[override virtual protected] void QQuickWindow::mouseReleaseEvent(QMouseEvent *event)

QWindow::mouseReleaseEvent(QMouseEvent *ev)를 재구현합니다.

[slot] void QQuickWindow::releaseResources()

이 함수는 현재 QML 씬이 보유하고 있는 불필요한 리소스를 해제하려고 시도합니다.

이 함수를 호출하면 씬 그래프에 그래픽 파이프라인 객체, 셰이더 프로그램 또는 이미지 데이터와 같은 캐시된 그래픽 리소스를 해제하도록 요청합니다.

또한, 사용 중인 렌더 루프에 따라 이 함수를 호출하면 씬 그래프와 모든 창 관련 렌더링 리소스가 해제될 수도 있습니다. 이 경우, ` sceneGraphInvalidated()` 신호가 발산되어 사용자가 직접 그래픽 리소스를 정리할 수 있게 됩니다. 애플리케이션에서 정리 처리가 불가능한 경우, 메모리 사용량이 증가하는 대가로 ` setPersistentGraphics()` 및 ` setPersistentSceneGraph()` 함수를 사용하여 이러한 현상을 방지할 수 있습니다.

참조: sceneGraphInvalidated(), setPersistentGraphics(), setPersistentSceneGraph().

[since 6.0] QQuickRenderTarget QQuickWindow::renderTarget() const

setRenderTarget()에 전달된 ` QQuickRenderTarget `를 반환하거나, 그렇지 않은 경우 기본 생성된 객체를 반환합니다.

이 함수는 Qt 6.0에서 도입되었습니다.

setRenderTarget()도 참조하십시오 .

QSGRendererInterface *QQuickWindow::rendererInterface() const

현재 렌더러 인터페이스를 반환합니다. 이 값은 항상 유효하며 null이 될 수 없습니다.

QSGRenderNode 및 QSGRendererInterface도 참조하십시오 .

[override virtual protected] void QQuickWindow::resizeEvent(QResizeEvent *ev)

QWindow::resizeEvent(QResizeEvent *ev)를 재구현합니다.

[since 6.6] QRhi *QQuickWindow::rhi() const

이 창에서 렌더링에 사용하는 ` QRhi ` 객체를 반환합니다.

이 메서드는 창이 Qt의 3D API 및 셰이딩 언어 추상화를 사용하는 경우에만 사용할 수 있으며, 즉 software 적응형을 사용할 때는 결과가 항상 null입니다.

이 결과는 렌더링이 초기화된 경우에만 유효하며, 이는 ` sceneGraphInitialized()` 신호의 발송으로 표시됩니다. 그 이전에는 반환된 값이 null입니다. 일반적인 온스크린 ` QQuickWindow `의 경우, 시네그래프 초기화는 일반적으로 네이티브 창이 처음 노출(표시)될 때 수행됩니다. QQuickRenderControl 를 사용할 경우, 초기화는 명시적인 initialize() 호출에서 수행됩니다.

실제로 이 함수는 QSGRendererInterface 를 통해 QRhi 를 조회하는 단축 방법입니다.

이 함수는 Qt 6.6에서 도입되었습니다.

[signal] void QQuickWindow::sceneGraphAboutToStop()

이 신호는 씬 그래프가 렌더링을 중단하려 할 때 렌더 스레드에서 발생합니다. 이는 대개 창이 숨겨졌기 때문에 발생합니다.

애플리케이션은 이 신호를 사용하여 리소스를 해제할 수 있지만, 리소스를 신속하게 다시 생성할 준비가 되어 있어야 합니다. 이 시점에서는 씬 그래프와 그래픽 컨텍스트가 해제되지 않습니다.

sceneGraphInvalidated()도 참조하십시오 .

[static] QString QQuickWindow::sceneGraphBackend()

요청된 Qt Quick 시나그래프 백엔드를 반환합니다.

setSceneGraphBackend()도 참조하십시오 .

[signal] void QQuickWindow::sceneGraphError(QQuickWindow::SceneGraphError error, const QString &message)

이 신호는 씬 그래프 초기화 과정에서 ‘ error ’이 발생했을 때 발생합니다.

그래픽 컨텍스트 생성 실패와 같은 오류를 사용자 정의 방식으로 처리하고자 하는 경우, 애플리케이션은 이 신호에 연결해야 합니다. 이 신호에 슬롯이 연결되어 있지 않으면 동작이 달라집니다. Quick은 오류 메시지( message)를 출력하거나 메시지 상자를 표시한 후 애플리케이션을 종료합니다.

이 신호는 GUI 스레드에서 발생합니다.

[signal] void QQuickWindow::sceneGraphInitialized()

이 신호는 씬 그래프가 초기화되었을 때 발생합니다.

이 신호는 씬 그래프 렌더링 스레드에서 발생합니다.

[signal] void QQuickWindow::sceneGraphInvalidated()

이 신호는 씬 그래프가 무효화되었을 때 발생합니다.

이 신호는 사용된 그래픽 렌더링 컨텍스트가 무효화되었으며, 해당 컨텍스트에 연결된 모든 사용자 리소스를 해제해야 함을 의미합니다.

OpenGL로 렌더링할 때, 이 함수가 호출되면 이 창의 렌더링 컨텍스트( QOpenGLContext )가 바인딩됩니다. 유일한 예외는 EGL_CONTEXT_LOST 등을 통해 Qt의 제어 범위를 벗어나 네이티브 OpenGL이 소멸된 경우입니다.

이 신호는 씬 그래프 렌더링 스레드에서 발생합니다.

void QQuickWindow::scheduleRenderJob(QRunnable *job, QQuickWindow::RenderStage stage)

이 창의 렌더링이 지정된 stage 에 도달하면 job 가 실행되도록 예약합니다.

이는 "일회성" 작업에 대해 QQuickWindow 의 동등한 신호들을 편리하게 사용할 수 있도록 하는 기능입니다.

창은 ` job `에 대한 소유권을 가지며, 작업이 완료되면 이를 삭제합니다.

job 가 실행될 기회도 없이 렌더링이 종료되면, 작업이 실행된 후 장면 그래프 정리 과정의 일환으로 삭제됩니다. 창이 표시되지 않고 QQuickWindow 가 소멸되기 전에 렌더링이 발생하지 않으면, 모든 보류 중인 작업은 run() 메서드가 호출되지 않은 채 소멸됩니다.

렌더링이 다른 스레드에서 수행되는 경우, 해당 작업은 렌더링 스레드에서 수행됩니다.

stage 가 NoStage 인 경우, job 는 렌더링 스레드가 프레임 렌더링으로 바쁘지 않을 때 가능한 한 빨리 실행됩니다. 작업이 게시되거나 처리되는 시점에 창이 노출되지 않았거나 렌더링할 수 없는 상태라면, run() 메서드를 실행하지 않고 작업이 삭제됩니다. 스레드가 없는 렌더러를 사용하는 경우, 작업의 run() 메서드는 동기식으로 실행됩니다. OpenGL로 렌더링할 때는 NoStage 작업을 포함한 모든 작업을 실행하기 전에 OpenGL 컨텍스트가 렌더러의 컨텍스트로 변경됩니다.

참조: beforeRendering(), afterRendering(), beforeSynchronizing(), afterSynchronizing(), frameSwapped(), sceneGraphInvalidated().

[static] void QQuickWindow::setDefaultAlphaBuffer(bool useAlpha)

useAlpha 새로 생성되는 창에 알파 투명도를 적용할지 여부를 지정합니다.

반투명 창을 생성할 예정인 모든 애플리케이션에서는 첫 번째 ` QQuickWindow` 객체를 생성하기 전에 이 매개변수를 `true`로 설정해야 합니다. 기본값은 `false`입니다.

hasDefaultAlphaBuffer()도 참조하십시오 .

[static, since 6.0] void QQuickWindow::setGraphicsApi(QSGRendererInterface::GraphicsApi api)

지정된 그래픽스 api 를 요청합니다.

내장된 기본 그래픽스 어댑테이션이 사용될 때, ` api `는 씬 그래프가 렌더링에 사용할 그래픽스 API(OpenGL, Vulkan, Metal 또는 Direct3D)를 지정합니다. 또한, ` software ` 백엔드도 내장되어 있으며, ` api `를 ` QSGRendererInterface::Software`로 설정하여 요청할 수 있습니다.

setSceneGraphBackend() 함수는 (내장되거나 동적으로 로드되는 플러그인으로 설치된) 특정 백엔드만 요청하는 데 사용할 수 있는 반면, 이 함수는 그래픽 API라는 더 높은 수준의 개념을 다룹니다. 이 함수는 Qt Quick 와 함께 제공되는 백엔드를 포함하며, 따라서 QSGRendererInterface::GraphicsApi 열거형에 해당 값들이 정의되어 있습니다.

이 함수가 전혀 호출되지 않고, 이에 상응하는 환경 변수 ` QSG_RHI_BACKEND `도 설정되지 않은 경우, 씬 그래프는 플랫폼에 따라 사용할 그래픽 API를 선택합니다.

이 함수는 특정 API로만 렌더링이 가능하도록 준비된 애플리케이션에서 중요합니다. 예를 들어, 애플리케이션에서 네이티브 OpenGL 또는 Vulkan 렌더링을 수행하는 경우, Qt Quick 도 OpenGL 또는 Vulkan을 사용하여 렌더링되도록 보장해야 합니다. 이러한 애플리케이션은 main() 함수의 초반부에 이 함수를 호출해야 합니다.

씬 그래프가 렌더링에 어떤 그래픽 API를 사용하고 있는지 확인하려면, 씬 그래프의 has initialized 호출 후 QSGRendererInterface::graphicsApi()을 호출하십시오. 이는 일반적으로 창이 처음 표시될 때나 QQuickRenderControl::initialize()이 호출될 때 발생합니다.

씬 그래프가 플랫폼 및 기타 조건에 따라 그래픽 API를 선택하는 기본 동작으로 되돌리려면, api 를 QSGRendererInterface::Unknown 로 설정하십시오.

이 함수는 Qt 6.0에서 도입되었습니다.

graphicsApi()도 참조하십시오 .

[since 6.0] void QQuickWindow::setGraphicsConfiguration(const QQuickGraphicsConfiguration &config)

이 창의 그래픽 구성을 설정합니다. ` config `에는 기본 그래픽 장치 및 컨텍스트를 초기화할 때 씬 그래프가 고려할 수 있는 다양한 설정이 포함되어 있습니다.

예를 들어 Vulkan에서 활성화할 장치 확장 기능을 지정하는 것과 같은 이러한 추가 구성은, 특정 확장 기능에 의존하는 네이티브 그래픽 렌더링 코드를 통합할 때 중요하고 필수적입니다. OpenXR과 같은 외부 3D 또는 VR 엔진과 통합할 때도 마찬가지입니다.

QQuickGraphicsConfiguration 인스턴스는 암시적으로 공유되고 복사 가능하며, 값으로 전달될 수 있습니다.

이 함수는 Qt 6.0에서 도입되었습니다.

graphicsConfiguration()도 참조하십시오 .

[since 6.0] void QQuickWindow::setGraphicsDevice(const QQuickGraphicsDevice &device)

이 창의 그래픽 장치 객체를 설정합니다. 씬그래프는 새로운 객체를 생성하는 대신, device 에서 지정된 기존 장치, 물리적 장치 및 기타 객체를 사용합니다.

이 함수는 Qt Quick 의 렌더링 결과를 텍스처로 리디렉션하기 위해 QQuickRenderControl 및 setRenderTarget()와 함께 매우 자주 사용됩니다.

기본 생성된 QQuickGraphicsDevice 는 기본 동작을 전혀 변경하지 않습니다. QQuickGraphicsDevice::fromDeviceObjects()와 같은 QQuickGraphicsDevice 팩토리 함수 중 하나를 통해 생성된 device 가 전달되고, 씬그래프가 일치하는 그래픽 API(fromDeviceObjects()의 예시에서는 Vulkan)를 사용하는 경우, 씬그래프는 ` QQuickGraphicsDevice`에 캡슐화된 기존 디바이스 객체(Vulkan의 경우 ` VkPhysicalDevice`, ` VkDevice` 및 그래픽스 큐 패밀리 인덱스 등)를 사용하게 됩니다. 이를 통해 동일한 디바이스를 사용할 수 있으며, 따라서 ` Qt Quick `과 네이티브 렌더링 엔진 간에 버퍼 및 텍스처와 같은 리소스를 공유할 수 있습니다.

예를 들어, 이번에는 Direct3D를 기준으로 볼 때 일반적인 사용법은 다음과 같을 것으로 예상됩니다:

// native graphics resources set up by a custom D3D rendering engine
ID3D11Device *device;
ID3D11DeviceContext *context;
ID3D11Texture2D *texture;
...
// now to redirect Qt Quick content into 'texture' we could do the following:
QQuickRenderControl *renderControl = new QQuickRenderControl;
QQuickWindow *window = new QQuickWindow(renderControl); // this window will never be shown on-screen
...
window->setGraphicsDevice(QQuickGraphicsDevice::fromDeviceAndContext(device, context));
renderControl->initialize();
window->setRenderTarget(QQuickRenderTarget::fromD3D11Texture(texture, textureSize);
...

이 함수를 사용할 때 핵심은, 위 예제의 texture 와 같은 리소스나 리소스 핸들이 외부 렌더링 엔진과 씬그래프 렌더러 모두에서 인식되고 사용 가능하도록 보장하는 것입니다. 이를 위해서는 동일한 그래픽 장치(또는 OpenGL의 경우 OpenGL 컨텍스트)를 사용해야 합니다.

QQuickGraphicsDevice 인스턴스는 암시적으로 공유되며, 복사 가능하며, 값으로 전달될 수 있습니다. 인스턴스는 관련 네이티브 객체(예: 예제의 ID3D11Device)를 소유하지 않습니다.

이 함수는 Qt 6.0에서 도입되었습니다.

graphicsDevice(), QQuickRenderControl, setRenderTarget(), setGraphicsApi()도 참조하십시오 .

void QQuickWindow::setPersistentGraphics(bool persistent)

그래픽 리소스(그래픽 장치 또는 컨텍스트, 스왑체인, 버퍼, 텍스처)를 보존할지 여부를 설정하며, 마지막 창이 삭제될 때까지 ` persistent`에 의해 해제될 수 없도록 합니다. 기본값은 `true`입니다.

releaseResources()를 호출하거나 창이 숨겨질 때(더 구체적으로 말하면, 렌더링 불가능한 상태가 될 때), 일부 렌더링 루프는 캐시된 그래픽 리소스뿐만 아니라 모든 그래픽 리소스를 해제할 수 있습니다. 이렇게 하면 일시적으로 메모리를 확보할 수 있지만, 동시에 창이 다시 렌더링되어야 할 때 렌더링 엔진이 리소스에 대한 완전한 재초기화를 수행해야 하므로, 이 과정에서 상당한 비용이 발생할 수 있습니다.

isPersistentGraphics(), setPersistentSceneGraph(), sceneGraphInitialized(), sceneGraphInvalidated(), releaseResources()도 참조하십시오 .

void QQuickWindow::setPersistentSceneGraph(bool persistent)

씬 그래프 노드와 리소스가 ‘ persistent ’인지 여부를 설정합니다. ‘Persistent’는 노드와 리소스가 해제될 수 없음을 의미합니다. 기본값은 ‘ true ’입니다.

releaseResources()를 호출할 때, 창이 숨겨지면(더 구체적으로 말하면 렌더링 불가능한 상태가 되면) 일부 렌더링 루프에서는 씬 그래프 노드와 관련 그래픽 리소스를 해제할 수 있습니다. 이렇게 하면 일시적으로 메모리를 확보할 수 있지만, 다음에 창이 렌더링될 때 씬 그래프를 다시 구축해야 한다는 의미이기도 합니다.

isPersistentSceneGraph(), setPersistentGraphics(), sceneGraphInvalidated(), sceneGraphInitialized(), releaseResources()도 참조하십시오 .

[since 6.0] void QQuickWindow::setRenderTarget(const QQuickRenderTarget &target)

이 창의 렌더 타겟을 ` target`로 설정합니다.

QQuickRenderTarget 는 렌더링 가능한 네이티브 객체(대개 2D 텍스처)와 픽셀 단위의 크기 같은 관련 메타데이터를 나타내는 불투명한 핸들 역할을 합니다.

기본 생성된 ` QQuickRenderTarget `는 리디렉션이 없음을 의미합니다. 반면, 정적 ` QQuickRenderTarget ` 팩토리 함수 중 하나를 통해 생성된 유효한 ` target`는 ` Qt Quick ` 장면의 렌더링 리디렉션을 가능하게 합니다. 즉, 더 이상 창과 연관된 표면의 색상 버퍼를 대상으로 하지 않고, ` target`에 지정된 텍스처나 기타 그래픽 객체를 대상으로 합니다.

예를 들어, 씬그래프가 Vulkan을 사용하여 렌더링한다고 가정할 때, 그 출력을 VkImage 로 리디렉션할 수 있습니다. Vulkan과 같은 그래픽 API의 경우, 이미지 레이아웃도 함께 제공되어야 합니다. QQuickRenderTarget 인스턴스는 암시적으로 공유되며, 복사 가능하고 값으로 전달될 수 있습니다. 그러나 이 인스턴스들은 관련 네이티브 객체(예: 예제의 VkImage)를 소유하지는 않습니다.

QQuickRenderTarget rt = QQuickRenderTarget::fromVulkanImage(vulkanImage, VK_IMAGE_LAYOUT_PREINITIALIZED, pixelSize);
quickWindow->setRenderTarget(rt);

이 함수는 QQuickRenderControl 및 보이지 않는 QQuickWindow 과 함께 매우 자주 사용되며, 이를 통해 Qt Quick 콘텐츠를 텍스처로 렌더링할 때, 해당 QQuickWindow 을 위한 화면상의 네이티브 창을 생성하지 않고도 처리할 수 있습니다.

원하는 대상이나 크기 같은 관련 데이터가 변경되면, 새로운 QQuickRenderTarget 를 사용하여 이 함수를 호출하십시오. QQuickRenderTarget 인스턴스를 생성하고 이 함수를 호출하는 데는 비용이 거의 들지 않지만, 다른 네이티브 객체나 다른 데이터로 새로운 target 를 설정하면 씬그래프가 다음 프레임을 렌더링할 때 잠재적으로 비용이 많이 드는 초기화 단계가 발생할 수 있다는 점에 유의하십시오. 따라서 필요한 경우에만 타깃을 변경하십시오.

이 함수는 Qt 6.0에서 도입되었습니다.

renderTarget(), QQuickRenderControl, setGraphicsDevice() 및 setGraphicsApi()도 참조하십시오 .

[static] void QQuickWindow::setSceneGraphBackend(const QString &backend)

Qt Quick 시나그래프 backend 를 요청합니다. 백엔드는 내장형이거나 동적으로 로드되는 플러그인 형태로 설치될 수 있습니다.

백엔드 목록에 대한 자세한 내용은 ‘애플리케이션에서 어댑테이션 전환’을 참조하십시오. backend 가 유효하지 않거나 오류가 발생하면 요청이 무시됩니다.

참조: sceneGraphBackend().

[static] void QQuickWindow::setTextRenderType(QQuickWindow::TextRenderType renderType)

Qt Quick 에서 텍스트와 유사한 요소의 기본 렌더링 유형을 renderType 로 설정합니다.

textRenderType()도 참조하십시오 .

[override virtual protected] void QQuickWindow::showEvent(QShowEvent *)

QWindow::showEvent(QShowEvent *ev)를 재구현합니다.

[since 6.6] QRhiSwapChain *QQuickWindow::swapChain() const

이 창에서 사용하는 QRhiSwapChain 가 있는 경우, 해당 객체를 반환합니다.

이 함수는 Qt 6.6에서 도입되었습니다.

[override virtual protected] void QQuickWindow::tabletEvent(QTabletEvent *event)

QWindow::tabletEvent(QTabletEvent *ev)를 재구현합니다.

[static] QQuickWindow::TextRenderType QQuickWindow::textRenderType()

Qt Quick 에 포함된 텍스트와 유사한 요소의 렌더링 유형을 반환합니다. 기본값은 QQuickWindow::QtTextRendering 입니다.

setTextRenderType()도 참조하십시오 .

[slot] void QQuickWindow::update()

창이 다음 프레임을 렌더링하도록 예약합니다.

QQuickWindow::update()를 호출하는 것은 QQuickItem::update()를 호출하는 것과 달리, 기본이 되는 씬 그래프의 변경 여부와 관계없이 항상 다시 그리기를 트리거한다는 점에서 다릅니다.

[override virtual protected] void QQuickWindow::wheelEvent(QWheelEvent *event)

QWindow::wheelEvent(QWheelEvent *ev)를 재구현합니다.