QQuickGraphicsConfiguration Class

int main(int argc, char *argv[])
{
    QGuiApplication app(argc, argv);

    QQuickGraphicsConfiguration config;
    config.setDebugLayer(true);

    QQuickView *view = new QQuickView;
    view->setGraphicsConfiguration(config);

    view->setSource(QUrl::fromLocalFile("myqmlfile.qml"));
    view->show();
    return app.exec();
}

Total time spent on pipeline creation during the lifetime of the QRhi was 123 ms

Attempting to seed pipeline cache from 'filename'

Writing pipeline cache contents to 'filename'

멤버 함수 문서

QQuickGraphicsConfiguration::QQuickGraphicsConfiguration()

씬 그래프가 고려해야 할 추가 설정을 전혀 지정하지 않는 기본 QQuickGraphicsConfiguration 객체를 생성합니다.

[noexcept] QQuickGraphicsConfiguration::~QQuickGraphicsConfiguration()

소멸자.

QByteArrayList QQuickGraphicsConfiguration::deviceExtensions() const

요청된 추가 장치 확장 기능의 목록을 반환합니다.

setDeviceExtensions()도 참조하십시오 .

[since 6.5] bool QQuickGraphicsConfiguration::isAutomaticPipelineCacheEnabled() const

자동 파이프라인 캐시가 활성화되어 있으면 true를 반환합니다.

특정 애플리케이션 속성이나 환경 변수가 설정되어 있지 않은 한, 기본적으로 이 값은 true입니다. 자세한 내용은 The Automatic Pipeline Cache 을 참조하십시오.

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

setAutomaticPipelineCache()도 참조하십시오 .

bool QQuickGraphicsConfiguration::isDebugLayerEnabled() const

디버그/유효성 검사 계층을 활성화해야 하는 경우 true를 반환합니다.

기본값은 false입니다.

setDebugLayer()도 참조하십시오 .

bool QQuickGraphicsConfiguration::isDebugMarkersEnabled() const

디버그 마커가 활성화되어 있으면 true를 반환합니다.

기본값은 false입니다.

setDebugMarkers()도 참조하십시오 .

bool QQuickGraphicsConfiguration::isDepthBufferEnabledFor2D() const

2D 콘텐츠에 대해 깊이 버퍼 사용이 활성화된 경우 true를 반환합니다.

QSG_NO_DEPTH_BUFFER 환경 변수가 설정되어 있지 않은 한, 기본값은 true입니다.

QString QQuickGraphicsConfiguration::pipelineCacheLoadFile() const

파이프라인 캐시를 불러오기 위해 현재 설정된 파일 이름을 반환합니다.

기본적으로 이 값은 빈 문자열입니다.

setPipelineCacheLoadFile()도 참조하십시오 .

QString QQuickGraphicsConfiguration::pipelineCacheSaveFile() const

파이프라인 캐시를 저장하기 위해 현재 설정된 파일 이름을 반환합니다.

기본적으로 이 값은 빈 문자열입니다.

setPipelineCacheSaveFile()도 참조하십시오 .

[static, since 6.1] QByteArrayList QQuickGraphicsConfiguration::preferredInstanceExtensions()

Qt Quick 가 VkInstance에서 활성화되기를 선호하는 Vulkan 인스턴스 확장 기능 목록을 반환합니다.

대부분의 경우 Qt Quick 가 QVulkanInstance 를 생성하는 역할을 담당합니다. 이 경우 이 함수는 관련이 없습니다. 반면, QQuickRenderControl 를 Vulkan 기반 렌더링과 함께 사용하는 경우, QVulkanInstance 를 생성하고 이를 (오프스크린) QQuickWindow 에 연결하는 것은 애플리케이션의 책임입니다. 이 경우, 애플리케이션은 활성화할 인스턴스 확장 기능 목록을 조회하여 QVulkanInstance::create()를 호출하기 전에 QVulkanInstance::setExtensions()에 해당 목록을 전달해야 합니다.

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

bool QQuickGraphicsConfiguration::prefersSoftwareDevice() const

소프트웨어 래스터라이저 기반 그래픽 장치가 우선순위로 지정된 경우 true를 반환합니다.

기본값은 false입니다.

setPreferSoftwareDevice()도 참조하십시오 .

[since 6.5] void QQuickGraphicsConfiguration::setAutomaticPipelineCache(bool enable)

enable 에 따라 자동 파이프라인 캐시의 사용 방식을 변경합니다.

특정 애플리케이션 속성이나 환경 변수가 설정되지 않은 경우 기본값은 true입니다. 자세한 내용은 The Automatic Pipeline Cache 를 참조하십시오.

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

isAutomaticPipelineCacheEnabled()도 참조하십시오 .

[since 6.5] void QQuickGraphicsConfiguration::setDebugLayer(bool enable)

사용 가능한 경우 그래픽 API 구현의 디버그 또는 유효성 검사 계층을 활성화합니다.

실제로는 Vulkan 및 Direct 3D 11에서 이 기능이 지원되며, 필요한 지원 요소(검증 레이어, Windows SDK)가 설치되어 있고 런타임 시 사용할 수 있는 경우에 한합니다. enable 가 true인 경우, Qt는 VkInstance에서 표준 검증 레이어를 활성화하거나 그래픽 장치에서 D3D11_CREATE_DEVICE_DEBUG 를 설정하려고 시도합니다.

macOS의 Metal의 경우, 애플리케이션을 실행하기 전에 METAL_DEVICE_WRAPPER_TYPE=1 환경 변수를 설정해야 합니다.

enable 가 true로 설정된 상태에서 이 함수를 호출하는 것은 환경 변수 QSG_RHI_DEBUG_LAYER 를 0이 아닌 값으로 설정하는 것과 같습니다.

기본값은 false입니다.

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

isDebugLayerEnabled()도 참조하십시오 .

[since 6.5] void QQuickGraphicsConfiguration::setDebugMarkers(bool enable)

해당되는 경우, enable 는 그래픽 명령 스트림에 디버그 마커와 객체 이름을 삽입하는 기능을 제어합니다.

Qt Quick 3D 와 같은 일부 프레임워크는 생성한 그래픽스 객체(버퍼, 텍스처)에 이름을 부여하고, 명령 버퍼 내에서 렌더링 패스의 시작과 끝을 표시하는 기능을 제공합니다. 이러한 정보는 RenderDoc이나 XCode와 같은 도구를 사용하여 캡처한 프레임에서 확인할 수 있습니다.

이 기능이 지원될 것으로 예상되는 그래픽 API로는 Vulkan(VK_EXT_debug_utils가 사용 가능한 경우), Direct 3D 11 및 Metal이 있습니다.

enable 를 true로 설정하고 이 함수를 호출하는 것은 환경 변수 QSG_RHI_PROFILE 를 0이 아닌 값으로 설정하는 것과 동일합니다.

기본값은 false입니다.

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

isDebugMarkersEnabled()도 참조하십시오 .

void QQuickGraphicsConfiguration::setDepthBufferFor2D(bool enable)

2D 콘텐츠에 대한 뎁스 버퍼 사용을 ` enable`로 설정합니다. 비활성화되면 ` Qt Quick ` 장면 그래프는 뎁스 버퍼에 절대 쓰기를 수행하지 않습니다.

QSG_NO_DEPTH_BUFFER 환경 변수가 설정되어 있지 않은 한, 기본값은 true입니다.

기본값인 true는 대다수의 씬에 대해 가장 최적의 설정입니다. 깊이 버퍼 사용을 비활성화하면 씬 그래프의 배치 처리 효율이 저하됩니다.

그러나 2D 콘텐츠가 깊이 버퍼에 쓰도록 허용하는 것이 이상적이지 않은 경우도 있습니다. renderMode 가 Overlay 로 설정된 View3D 를 사용하여 Qt Quick 3D 를 통해 렌더링된 3D 씬을 2D 씬 위에 "오버레이"로 생각해보세요. 이 경우, 깊이 버퍼가 2D 콘텐츠로 채워지면 예상치 못한 결과가 발생할 수 있습니다. 이는 2D 씬 그래프 렌더러가 깊이 값을 생성하고 처리하는 방식이 3D 씬의 작동 방식과 반드시 호환되는 것은 아니기 때문입니다. 이로 인해 깊이 값 충돌, 콜리전, 예상치 못한 깊이 테스트 실패가 발생할 수 있습니다. 따라서, 여기서 안정적인 접근 방식은 ` enable `를 `false`로 설정하고, ` QQuickWindow`에서 2D 콘텐츠에 대한 깊이 버퍼 쓰기를 비활성화한 상태로 이 함수를 호출하는 것입니다.

void QQuickGraphicsConfiguration::setDeviceExtensions(const QByteArrayList &extensions)

그래픽 장치(예: VkDevice)에서 활성화할 추가 extensions 목록을 설정합니다.

이 개념이 적용되지 않는 그래픽 API로 렌더링할 경우, extensions 는 무시됩니다.

deviceExtensions()도 참조하십시오 .

[since 6.5] void QQuickGraphicsConfiguration::setPipelineCacheLoadFile(const QString &filename)

QQuickWindow 가 그래픽/연산 파이프라인 캐시의 초기 내용을 불러올 소스인 filename 를 설정합니다. 기본값은 비어 있으며, 이는 파이프라인 캐시 로딩이 비활성화되었음을 의미합니다.

파이프라인 캐시에 대한 자세한 내용은 Pipeline Cache Save and Load 을 참조하십시오.

파이프라인 캐시를 영구적으로 저장하면 비용이 많이 드는 셰이더 컴파일 및 파이프라인 구축 단계를 피할 수 있으므로, 향후 애플리케이션 실행 시 성능이 향상될 수 있습니다.

파일 내용의 로딩이 발생하는 시점은 정의되어 있지 않으며, QQuickWindow 의 씬그래프 초기화 과정 중 어느 시점에 이루어진다는 점만 알려져 있습니다. 따라서 이 함수를 호출한 후에도 파일이 계속 존재해야 합니다. QQuickGraphicsConfiguration 는 파일 이름만 저장할 뿐, 자체적으로 실제 I/O 및 그래픽 작업을 수행할 수는 없습니다. 실제 작업은 나중에, 아마도 다른 스레드에서 수행될 것입니다.

파이프라인 캐시(또는 셰이더/프로그램 바이너리)를 검색하고 재로드하는 기능이 적용되지 않거나 지원되지 않는 그래픽 API에서 실행할 경우, 이 함수를 호출해도 아무런 효과가 없습니다.

이 함수를 호출하는 것은 환경 변수 ` QSG_RHI_PIPELINE_CACHE_LOAD `을 ` filename`으로 설정하는 것과 대체로 동일하지만, 한 가지 중요한 차이점이 있습니다. 이 함수는 관련 ` QQuickWindow `에 대해서만 파이프라인 캐시 저장을 제어합니다. 따라서 여러 ` QQuickWindow ` 또는 ` QQuickView ` 인스턴스를 가진 애플리케이션은 각 창에 전용 파일을 사용하여 캐시 내용을 저장하고 나중에 다시 불러올 수 있습니다. 환경 변수로는 이러한 작업이 불가능합니다.

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

pipelineCacheLoadFile() 및 setPipelineCacheSaveFile()도 참조하십시오 .

[since 6.5] void QQuickGraphicsConfiguration::setPipelineCacheSaveFile(const QString &filename)

QQuickWindow 가 그래픽/연산 파이프라인 캐시 내용을 저장할 filename 을 설정합니다. 기본값은 비어 있으며, 이는 파이프라인 캐시 로딩이 비활성화되었음을 의미합니다.

파이프라인 캐시에 대한 자세한 내용은 Pipeline Cache Save and Load 을 참조하십시오.

파이프라인 캐시를 영구적으로 저장하면, 비용이 많이 드는 셰이더 컴파일 및 파이프라인 구축 단계를 피할 수 있으므로 향후 애플리케이션 실행 시 성능이 향상될 수 있습니다.

파일 쓰기 작업이 발생하는 시점은 정의되어 있지 않습니다. 창을 닫아 씬그래프(scenegraph)를 해제하는 과정에서 어느 시점에 발생할 가능성이 높습니다. 따라서 애플리케이션은 QQuickWindow 가 완전히 해제될 때까지 해당 파일의 가용성을 가정해서는 안 됩니다. QQuickGraphicsConfiguration 는 파일 이름만 저장할 뿐, 자체적으로 실제 I/O 및 그래픽 작업을 수행하지 않습니다.

파이프라인 캐시(또는 셰이더/프로그램 바이너리)를 가져오는 것이 적용되지 않거나 지원되지 않는 그래픽 API에서 실행할 경우, 이 함수를 호출해도 아무런 효과가 없습니다.

이 함수를 호출하는 것은 환경 변수 QSG_RHI_PIPELINE_CACHE_SAVE 를 filename 로 설정하는 것과 대체로 동일하지만, 한 가지 중요한 차이점이 있습니다. 이 함수는 연관된 QQuickWindow 에 대해서만 파이프라인 캐시 저장을 제어합니다. 따라서 여러 개의 QQuickWindow 또는 QQuickView 인스턴스를 가진 애플리케이션은 각 창에 전용된 파일을 통해 캐시 내용을 저장하고 나중에 다시 불러올 수 있습니다. 환경 변수로는 이를 허용하지 않습니다.

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

pipelineCacheLoadFile() 및 pipelineCacheSaveFile()도 참조하십시오 .

[since 6.5] void QQuickGraphicsConfiguration::setPreferSoftwareDevice(bool enable)

소프트웨어 기반 래스터화를 사용하는 어댑터 또는 물리적 장치를 선택하도록 요청합니다. 이 플래그는 기본 API가 어댑터 열거를 지원하는 경우(예: Direct 3D 또는 Vulkan)에만 적용되며, 그렇지 않은 경우에는 무시됩니다.

그래픽 API 구현에 해당 그래픽 어댑터나 물리 장치가 없는 경우, 이 요청은 무시됩니다. Direct 3D의 경우 WARP 기반 래스터라이저가 항상 사용 가능할 것으로 예상됩니다. Vulkan의 경우, 이 플래그는 Mesa의 lavapipe 또는 VK_PHYSICAL_DEVICE_TYPE_CPU 를 보고하는 다른 물리 장치가 사용 가능한 경우에만 효과가 있습니다.

enable 를 true로 설정하고 이 함수를 호출하는 것은 환경 변수 QSG_RHI_PREFER_SOFTWARE_RENDERER 를 0이 아닌 값으로 설정하는 것과 동일합니다.

기본값은 false입니다.

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

prefersSoftwareDevice()도 참조하십시오 .

[since 6.6] void QQuickGraphicsConfiguration::setTimestamps(bool enable)

이 기능이 활성화되면, 이를 지원하는 플랫폼 및 3D API에서 명령어 버퍼를 통해 GPU 타이밍 데이터가 수집됩니다. 이 데이터는 QSG_RENDER_TIMING 환경 변수나 qt.scenegraph.time.renderloop 와 같은 로깅 범주를 통해 활성화할 수 있는 렌더러 로그에 출력되며, Qt Quick 3D 의 ‘ DebugView ’ 항목과 같은 다른 모듈에서도 확인할 수 있습니다.

기본적으로 이 기능은 비활성화되어 있습니다. 이는 데이터 수집 과정에서 기본 그래픽 API에 따라 명령 스트림에 타임스탬프 쿼리를 삽입하는 등의 추가 작업이 필요할 수 있기 때문입니다. 이 기능을 활성화하려면 enable 을 true로 설정하고 이 함수를 호출하거나, QSG_RHI_PROFILE 환경 변수를 0이 아닌 값으로 설정하십시오.

이 기능이 지원될 것으로 예상되는 그래픽 API로는 Direct 3D 11, Direct 3D 12, Vulkan(기본 Vulkan 구현체가 타임스탬프 쿼리를 지원하는 경우), Metal, 그리고 버전 3.3 이상의 코어 또는 호환성 프로파일 컨텍스트를 사용하는 OpenGL이 있습니다. OpenGL ES에서는 타임스탬프가 지원되지 않습니다.

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

timestampsEnabled() 및 setDebugMarkers()도 참조하십시오 .

[since 6.6] bool QQuickGraphicsConfiguration::timestampsEnabled() const

GPU 타이밍 수집이 활성화되어 있으면 true를 반환합니다.

기본값은 false입니다.

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

setTimestamps()도 참조하십시오 .