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에서 활성화하는 것을 선호하는 벌칸 인스턴스 확장 목록을 반환합니다.

대부분의 경우 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 구현의 디버그 또는 유효성 검사 레이어(사용 가능한 경우)를 활성화합니다.

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

macOS의 Metal의 경우 애플리케이션을 시작하기 전에 환경 변수 METAL_DEVICE_WRAPPER_TYPE=1 를 대신 설정합니다.

enable 을 참으로 설정한 상태에서 이 함수를 호출하는 것은 환경 변수 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 콘텐츠의 뎁스 버퍼 쓰기를 허용하는 것이 이상적이지 않은 경우도 있습니다. Qt Quick 3D 2D 씬 위에 3D 씬을 '오버레이'하고 View3D 을 통해 renderMode 을 Overlay 로 설정하여 렌더링한다고 가정해 보겠습니다. 이 경우 2D 콘텐츠로 뎁스 버퍼를 채우면 예기치 않은 결과가 발생할 수 있습니다. 2D 씬 그래프 렌더러가 깊이 값을 생성하고 처리하는 방식이 3D 씬의 작동 방식과 반드시 호환되는 것은 아니기 때문입니다. 이로 인해 뎁스 값 충돌, 충돌 및 예기치 않은 뎁스 테스트 실패가 발생할 수 있습니다. 따라서 enable 을 false로 설정한 상태에서 이 함수를 호출하고 QQuickWindow 에서 2D 콘텐츠에 대한 뎁스 버퍼 쓰기를 비활성화하는 것이 가장 확실한 방법입니다.

void QQuickGraphicsConfiguration::setDeviceExtensions(const QByteArrayList &extensions)

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

이 개념이 적용되지 않는 그래픽 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 을 참조하세요.

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

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

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

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

이 기능은 Qt 6.5에 도입되었습니다.

pipelineCacheSaveFile(), pipelineCacheLoadFile() 및 setPipelineCacheSaveFile()도 참조하세요 .

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

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

그래픽 API 구현에 이러한 그래픽 어댑터나 물리적 장치가 없는 경우 요청은 무시됩니다. Direct 3D를 사용하면 WARP 기반 래스터라이저를 항상 사용할 수 있다고 예상할 수 있습니다. 벌칸의 경우 이 플래그는 Mesa의 lavapipe 또는 VK_PHYSICAL_DEVICE_TYPE_CPU 을 보고하는 다른 물리적 장치를 사용할 수 있는 경우에만 영향을 미칩니다.

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

기본값은 false입니다.

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

prefersSoftwareDevice()도 참조하십시오 .

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

이 옵션을 활성화하면 GPU 타이밍 데이터가 지원되는 플랫폼 및 3D API의 명령 버퍼에서 수집됩니다. 이 데이터는 QSG_RENDER_TIMING 환경 변수 또는 qt.scenegraph.time.renderloop 과 같은 로깅 카테고리를 통해 활성화할 수 있는 렌더러 로그에 인쇄되며, Qt Quick 3D 의 DebugView 항목과 같은 다른 모듈에도 표시될 수 있습니다.

기본 그래픽 API에 따라 데이터를 수집하려면 명령 스트림에 타임스탬프 쿼리를 삽입하는 등의 추가 작업이 필요할 수 있으므로 기본적으로 이 기능은 비활성화되어 있습니다. 활성화하려면 enable 을 참으로 설정한 상태에서 이 함수를 호출하거나 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()도 참조하십시오 .