변경 사항 Qt Quick

Qt 6의 변경 사항은 프레임워크를 더 효율적이고 사용하기 쉽게 만들기 위한 의도적인 노력의 결과입니다.

저희는 각 릴리스에서 모든 공개 API에 대해 바이너리 및 소스 호환성을 유지하려고 노력합니다. 하지만 Qt를 더 나은 프레임워크로 만들기 위한 노력의 일환으로 일부 변경 사항은 불가피했습니다.

이 주제에서는 Qt Quick 의 변경 사항을 요약하고, 이를 처리하는 방법에 대한 지침을 제공합니다.

Qt Quick 의 변경 사항 QML 유형

font.weight의 유형 변경

font.weight 의 유형이 int 로 변경되었습니다. 미리 정의된 굵기 클래스는 여전히 존재하지만, 이제 임의의 정수를 사용하여 이러한 굵기 클래스 중 어느 것과도 일치하지 않는 글꼴을 선택할 수 있습니다. 이는 글꼴 굵기를 임의의 정수로 표현하는 것이 항상 가능했던 C++ API와의 일관성을 보장합니다.

문자열에서 열거형 값으로의 암시적 변환이 사용된 경우를 제외하면, 대부분의 코드는 이 변경 사항의 영향을 받지 않습니다.

font.weight: "Bold"

이러한 코드는 더 이상 올바르게 파싱되지 않으므로, 아래 예시와 같이 이에 상응하는 열거형 값으로 대체해야 합니다.

font.weight: Font.Bold

FontLoader.name은 이제 읽기 전용 속성입니다

Qt 5에서 FontLoader 의 name 속성은 쓰기 가능했으며, 설정 시 해당 항목의 source 속성을 재정의했습니다. 이로 인해 이 속성의 용도에 대한 혼란이 있었으며, 상충되는 속성의 세터 간에 경합 조건이 발생할 경우 예측 불가능한 동작을 유발할 수 있었습니다.

이는 다음과 같은 코드가 더 이상 작동하지 않음을 의미합니다.

FontLoader {
    id: fontLoader
    name: "Helvetica"
}

Text {
    font.family: fontLoader.name
    text: "Foobar"
}

대신, 사용자 정의 속성을 사용하여 글꼴 패밀리 이름을 저장하십시오.

property string fontName: "Helvetica"

Text {
    font.family: fontName
    text: "Foobar"
}

OpenGLInfo QML 유형이 제거되었습니다

Qt 5.8에서 OpenGLInfo는 더 이상 사용되지 않게 되었으며, Qt 6에서는 제거되었습니다. 대신 GraphicsInfo 를 사용하십시오.

ShaderEffect는 더 이상 인라인 GLSL 셰이더 문자열을 지원하지 않습니다.

custom materials 와 마찬가지로, 이펙트는 더 이상 GLSL 셰이더 문자열의 형태로 지정되지 않습니다. 대신, 셰이더는 qsb 명령줄 도구와 같은 Qt Shader Tools 모듈의 도구를 통해 사전 처리되어야 하며, 이를 통해 런타임에 어떤 그래픽 API(Vulkan, Metal, OpenGL 또는 Direct 3D)가 사용되든 상관없이 셰이더 자산을 사용할 수 있게 됩니다. ShaderEffect 항목은 결과물인 .qsb 파일을 참조해야 합니다.

ShaderEffect 소스 속성이 이제 URL로 변경되었습니다

ShaderEffect 의 속성인 vertexShader 및 fragmentShader 의 유형이 QByteArray 대신 QUrl 로 변경되었습니다. 따라서 이 속성들의 동작은 Image.source 와 같은 다른 유사한 속성과 동일합니다. file 또는 qrc 스키마를 통해 파일을 참조하는 기존 코드는 그대로 작동합니다. 또한, 이 변경 사항으로 인해 컴포넌트(.qml 파일)의 위치를 기준으로 한 상대 경로로 파일을 참조할 수 있게 되었습니다. 따라서 이제 file: 방식을 지정하는 것은 선택 사항입니다.

Qt Quick C++ API 변경 사항

QQuickItem의 변경 사항

QQuickItem의 geometryChanged() 함수는 geometryChange()로 이름이 변경되었습니다.

QQuick* API의 변경 사항

• 자체 Vulkan, Metal 또는 Direct3D 렌더링 명령 세트를 통합하려는 애플리케이션은 QQuickWindow::beforeRendering() 및 afterRendering() 외에도 새로운 QQuickWindow 신호를 유의해야 합니다. 기존 Qt 5에서 사용하던 `just beforeRendering` 또는 `afterRendering`에만 연결하는 방식만으로는 더 이상 충분하지 않은 경우가 많으며, ` beforeRenderPassRecording()`이나 ` afterRenderPassRecording()`과 같은 추가 신호에 연결하여 보완해야 할 가능성이 높습니다.
• QQuickWindow::beforeRendering() 또는 afterRendering() 신호를 이용하여 자체 OpenGL 렌더링 명령 세트를 실행하는 애플리케이션은, OpenGL 호출 전에 QQuickWindow::beginExternalCommands()를, 호출 후에 QQuickWindow::endExternalCommands()를 호출해야 합니다. 이렇게 하면 애플리케이션 코드에서 수행한 상태 변경이 씬 그래프 렌더러가 자체적으로 캐시한 상태와 혼동을 일으키지 않도록 보장할 수 있습니다. 그러나 Qt 5와 마찬가지로, Qt Quick 렌더러에서 사용되지 않는 OpenGL 3.x 또는 4.x 상태를 변경하면 여전히 예기치 않은 문제가 발생할 수 있으므로, 애플리케이션은 이러한 신호에 연결된 슬롯이나 람다에서 반환하기 전에 해당 OpenGL 상태를 기본값으로 재설정하는 것이 좋습니다.
• 기존의 ` QQuickWindow::setRenderTarget()` 오버로드와 관련 게터는 제거되었으며, ` QQuickRenderTarget`를 매개변수로 받는 새로운 함수로 대체되었습니다. ` QQuickRenderControl `와 함께 리디렉션 렌더링을 수행하는 애플리케이션은 이제 OpenGL에 종속되지 않는 방식으로 렌더 타겟을 지정하기 위해 이 새로운 함수를 사용해야 합니다.
• QSGRendererInterface::GraphicsApi 인수를 받는 QQuickWindow::setSceneGraphBackend() 오버로드는 setGraphicsApi()로 이름이 변경되었습니다.
• QQuickWindow 의 setPersistentOpenGLContext 및 isPersistentOpenGLContext 함수는 이름이 변경되어, 이제 QQuickWindow::setPersistentGraphics() 및 QQuickWindow::isPersistentGraphics()이 되었습니다.
• QQuickWindow 에서 setClearBeforeRendering() 및 clearBeforeRendering()이 제거되었습니다. Qt 6에서는 컬러 버퍼 지우기를 건너뛸 수 있는 옵션이 없습니다. Qt 5에서는 언더레이와 함께 사용할 때, Qt Quick 가 컬러 버퍼에 렌더링된 내용을 지우는 것을 방지하기 위해 setClearBeforeRendering()을 호출해야 하는 경우가 많았습니다. Qt 6에서는 더 안정적인 접근 방식이 제공됩니다. 바로 지우기 작업이 완료된 후, Qt Quick 의 콘텐츠가 렌더링되기 전에 발송되는 beforeRenderPassRecording() 신호에 연결하는 방법입니다.
• QQuickWindow::openglContext() 함수는 제거되었습니다. 애플리케이션에서 씬 그래프가 렌더링에 OpenGL을 사용하도록 설정했다면, QSGRendererInterface::getResource()을 통해 QOpenGLContext 를 조회할 수 있습니다.
• QQuickWindow::openglContextCreated() 신호가 제거되었습니다.
• 더 이상 사용되지 않는 QQuickWindow::createTextureFromId() 함수가 제거되었습니다. 대신 QPlatformInterface::QSGOpenGLTexture, QPlatformInterface::QSGVulkanTexture, QPlatformInterface::QSGD3D11Texture 또는 QPlatformInterface::QSGMetalTexture의 fromNative() 함수를 사용하십시오.
• QQuickFramebufferObject 클래스는 API가 변경되지 않은 상태로 사용할 수 있지만, 씬그래프가 OpenGL로 렌더링될 때만 작동합니다. Vulkan이나 Metal과 같은 다른 그래픽 API를 사용할 때는 작동하지 않습니다. QQuickFramebufferObject 에 의존하는 애플리케이션은 main() 함수에서 QQuickWindow::setGraphicsApi(QSGRendererInterface::OpenGL) 를 호출하여 OpenGL 사용을 강제해야 합니다.
• QQuickRenderControl API가 약간 변경되었습니다. grab() 함수가 제거되었으며, 해당되는 경우 대신 QQuickWindow::grabWindow()을 사용하십시오. initialize() 함수는 더 이상 QOpenGLContext 를 매개변수로 받지 않습니다. 또한 애플리케이션은 상황에 따라 QQuickRenderControl::beginFrame() 및 QQuickRenderControl::endFrame()을 호출해야 합니다. 멀티샘플링을 원하는 경우, 샘플 수를 지정하기 위해 새로운 함수 QQuickRenderControl::setSamples()을 호출해야 합니다.
• 기존의 네이티브 그래픽 장치나 컨텍스트 객체와 함께 Qt Quick 렌더링을 수행하려는 애플리케이션은 QQuickRenderControl 가 더 이상 initialize(QOpenGLContext*) 함수를 제공하지 않으므로, 새로운 QQuickWindow::setGraphicsDevice() 함수를 사용해야 합니다.
• QQuickPaintedItem 및 Context2D 를 Framebuffer 모드로 설정해도 아무런 효과가 없습니다. 모드가 기본 Image 모드로 설정된 것처럼 동작합니다.
• Qt 6.0에서는 QSG_NO_DEPTH_BUFFER 환경 변수가 여전히 지원되지만, 이를 사용하는 대신 QQuickGraphicsConfiguration 객체에 setDepthBufferFor2D()을 호출한 후 해당 객체를 QQuickWindow 에 연결하는 방식으로 대체하는 것이 권장됩니다.

QSG* API의 변경 사항

• QSGMaterialShader 인터페이스가 변경되었습니다. 구현체는 더 이상 OpenGL에 의존해서는 안 되며, 현재 제거된 updateState()와 같은 함수가 QOpenGLContext 객체가 활성화된 상태에서 호출된다고 가정해서는 안 됩니다. 새로운 데이터 중심 인터페이스에서는 updateState()가 updateUniformData(), updateSampledImage() 및 updateGraphicsPipelineState()로 대체되었습니다. 문자열로 제공되던 GLSL 셰이더 코드 대신, 이제 셰이더는 qsb 명령줄 도구와 같은 Qt의 Shader Tools 모듈에 포함된 도구들을 통해 사전 처리되어야 합니다. 이를 통해 런타임에 어떤 그래픽 API(Vulkan, Metal, OpenGL 또는 Direct 3D)가 사용되든 상관없이 셰이더 자산을 사용할 수 있게 됩니다.
• QSGEngine이 제거되었습니다. 이 클래스를 사용하는 애플리케이션이 있을 경우(그럴 가능성은 희박하지만), 대신 QQuickRenderControl 를 사용하도록 포팅하는 것이 권장됩니다.
• QSGAbstractRenderer는 더 이상 public이 아닙니다. 이 클래스의 사용은 QSGEngine과 함께 사용할 때만 의미가 있었으며, 해당 클래스가 제거됨에 따라 QSGAbstractRenderer는 다시 private으로 변경되었습니다.
• 편의 클래스인 QSGSimpleMaterial이 제거되었습니다. 애플리케이션에서는 대신 개정된 OpenGL 독립형 QSGMaterial API를 사용해야 합니다.
• QSGTexture 의 기본 네이티브 텍스처 객체에 접근하기 위해 textureId()를 더 이상 사용할 수 없습니다. 대신, QPlatformInterface::QSGOpenGLTexture, QPlatformInterface::QSGVulkanTexture, QPlatformInterface::QSGD3D11Texture 또는 QPlatformInterface::QSGMetalTexture와 함께 QSGTexture::platformInterface()를 사용하십시오.
• 이제 QSGImageNode 의 서브클래스는 setAnisotropyLevel() 및 anisotropyLevel()과 같은 새로운 추가 가상 함수를 오버라이드해야 합니다.
• QSGTexture 의 하위 클래스는 재설계가 필요할 가능성이 높습니다. bind()나 updateBindOptions()와 같은 일부 OpenGL 전용 가상 함수는 더 이상 존재하지 않는 반면, comparisonKey()와 같이 구현이 필수적인 새로운 가상 함수들이 추가되었습니다.

OpenGL 사용 관련 변경 사항 Qt Quick

많은 애플리케이션에 호환성 문제가 발생하지는 않겠지만, 애플리케이션 개발자는 Qt 6에서 Qt Quick 렌더링 시 OpenGL이 더 이상 항상 기본 선택 사항이 아니라는 점을 유의해야 합니다. software 백엔드를 사용하지 않는 한, Qt Quick 애플리케이션은 런타임에 OpenGL, Vulkan, Metal 또는 Direct3D 11을 사용할 수 있습니다. QSG_RHI_BACKEND 환경 변수나 QQuickWindow::setSceneGraphBackend() 함수를 통해 명시적인 요청이 없는 경우, Qt Quick 에 의해 플랫폼별 기본값이 선택됩니다.

자세한 내용은 Qt Quick 의 ‘씬 그래프’ 및 Qt Quick 의 ‘씬 그래프 기본 렌더러’ 페이지를 참조하십시오.