QQuickRenderControl Class

멤버 함수 문서

[explicit] QQuickRenderControl::QQuickRenderControl(QObject *parent = nullptr)

parent 를 부모 객체로 하는 QQuickRenderControl 객체를 생성합니다.

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

인스턴스를 삭제합니다. 모든 씬그래프 리소스를 해제합니다.

invalidate()도 참조하십시오 .

[since 6.0] void QQuickRenderControl::beginFrame()

그래픽 프레임의 시작을 지정합니다. ` sync()` 또는 ` render()` 호출은 반드시 `beginFrame()` 및 ` endFrame()` 호출 사이에 포함되어야 합니다.

Qt 5의 초기 버전처럼 Qt OpenGL만 지원하던 환경과 달리, 다른 그래픽 API를 사용한 렌더링에서는 프레임의 시작과 끝 지점을 보다 명확하게 정의해야 합니다. QQuickRenderControl 을 통해 렌더링 루프를 수동으로 제어할 경우, 이제 QQuickRenderControl 의 사용자가 이러한 지점을 명시해야 합니다.

기존 텍스처에 대한 렌더링 초기화를 포함하는 일반적인 업데이트 단계는 다음과 같을 수 있습니다. 이 예제 코드 조각은 Direct3D 11을 가정하고 있지만, 동일한 개념이 다른 그래픽 API에도 적용됩니다.

if (!m_quickInitialized) {
    m_quickWindow->setGraphicsDevice(QQuickGraphicsDevice::fromDeviceAndContext(m_engine->device(), m_engine->context()));

    if (!m_renderControl->initialize())
        qWarning("Failed to initialize redirected Qt Quick rendering");

    m_quickWindow->setRenderTarget(QQuickRenderTarget::fromNativeTexture({ quint64(m_res.texture), 0 },
                                                                         QSize(QML_WIDTH, QML_HEIGHT),
                                                                         SAMPLE_COUNT));

    m_quickInitialized = true;
}

m_renderControl->polishItems();

m_renderControl->beginFrame();
m_renderControl->sync();
m_renderControl->render();
m_renderControl->endFrame(); // Qt Quick 의 렌더링 명령은 여기서 디바이스 컨텍스트로 전송됩니다.

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

endFrame(), initialize(), sync(), render(), QQuickGraphicsDevice 및 QQuickRenderTarget도 참조하십시오 .

[since 6.6] QRhiCommandBuffer *QQuickRenderControl::commandBuffer() const

현재 명령 버퍼를 반환합니다.

beginFrame()가 호출되면 QRhiCommandBuffer 가 자동으로 설정됩니다. 이는 Qt Quick 시네그래프가 사용하는 명령 버퍼이지만, 경우에 따라 애플리케이션에서도 리소스 업데이트(예: 텍스처 리드백)를 수행하기 위해 이를 조회해야 할 수 있습니다.

반환된 명령 버퍼 참조는 beginFrame()과 endFrame() 사이에서만 사용해야 합니다. 단, endFrame() 직후이지만 다음 beginFrame() 이전인 시점에 명령 버퍼에 대해 lastCompletedGpuTime()를 호출하는 경우와 같이 유효한 예외가 있습니다.

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

참조: rhi(), beginFrame(), endFrame().

[since 6.0] void QQuickRenderControl::endFrame()

그래픽 프레임의 끝을 지정합니다. ` sync()` 또는 ` render()` 호출은 반드시 ` beginFrame()` 및 `endFrame()` 호출 사이에 포함되어야 합니다.

이 함수가 호출되면, 시네그래프에 의해 큐에 추가된 모든 그래픽 명령이 해당되는 경우 컨텍스트 또는 명령 큐로 제출됩니다.

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

beginFrame(), initialize(), sync(), render(), QQuickGraphicsDevice 및 QQuickRenderTarget도 참조하십시오 .

[since 6.0] bool QQuickRenderControl::initialize()

씬 그래프 리소스를 초기화합니다. Qt Quick 렌더링을 위해 Vulkan, Metal, OpenGL 또는 Direct3D와 같은 그래픽 API를 사용할 경우, 이 함수가 호출되면 QQuickRenderControl 가 적절한 렌더링 엔진을 설정합니다. 이 렌더링 인프라는 QQuickRenderControl 가 존재하는 한 유지됩니다.

Qt Quick 가 사용할 그래픽 API를 제어하려면, QSGRendererInterface:GraphicsApi 상수 중 하나를 인수로 전달하여 QQuickWindow::setGraphicsApi()를 호출하십시오. 이 작업은 본 함수를 호출하기 전에 수행해야 합니다.

씬그래프가 자체적인 디바이스 및 컨텍스트 객체를 생성하지 못하도록 하려면, QQuickWindow::setGraphicsDevice()를 호출하여 기존 그래픽 객체를 감싸는 적절한 QQuickGraphicsDevice 를 지정하십시오.

활성화할 디바이스 확장 기능(예: Vulkan용)을 구성하려면, 이 함수를 호출하기 전에 QQuickWindow::setGraphicsConfiguration()를 호출하십시오.

성공 시 true 를 반환하고, 그렇지 않은 경우 false 를 반환합니다.

기본 Qt Quick 변환을 사용하는 경우, 이 함수는 QQuickRenderControl 가 사용되지 않았을 때 화면상의 QQuickWindow 에서 발생하는 것과 유사하게 새로운 QRhi 객체를 생성합니다. 이 새로운 QRhi 객체가 기존 장치 또는 컨텍스트 리소스를 채택하도록 하려면(예: 새로운 QOpenGLContext 을 생성하는 대신 기존 을 사용), 위에서 언급한 대로 QQuickWindow::setGraphicsDevice()을 사용하십시오. 애플리케이션에서 Qt Quick 렌더링에 이미 존재하는 QRhi 객체를 사용하고자 할 경우, QQuickGraphicsDevice::fromRhi()을 통해 이를 구현할 수 있습니다. 이미 존재하는 QRhi 을 참조하는 QQuickGraphicsDevice 가 설정되면, initialize()에서 새로운 전용 QRhi 객체가 생성되지 않습니다.

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

QQuickRenderTarget, QQuickGraphicsDevice 및 QQuickGraphicsConfiguration::preferredInstanceExtensions()도 참조하십시오 .

void QQuickRenderControl::invalidate()

렌더링을 중지하고 리소스를 해제합니다.

이는 실제 ` QQuickWindow `에서 창이 숨겨질 때 수행되는 정리 작업과 동일합니다.

이 함수는 소멸자에서 호출됩니다. 따라서 일반적으로 이 함수를 직접 호출할 필요는 없습니다.

invalidate()가 호출된 후에는 initialize()를 다시 호출하여 QQuickRenderControl 인스턴스를 재사용할 수 있습니다.

void QQuickRenderControl::polishItems()

이 함수는 ` sync()`이 호출되기 직전, 가능한 한 늦은 시점에 호출되어야 합니다. 스레드가 있는 환경에서는 이 함수가 실행되는 동안 렌더링이 병렬로 진행될 수 있습니다.

void QQuickRenderControl::prepareThread(QThread *targetThread)

GUI 스레드 외부에서 ‘ Qt Quick ’ 씬의 렌더링을 준비합니다.

targetThread 동기화 및 렌더링이 수행될 스레드를 지정합니다. 단일 스레드 환경에서는 이 함수를 호출할 필요가 없습니다.

void QQuickRenderControl::render()

현재 컨텍스트를 사용하여 씬그래프를 렌더링합니다.

[signal] void QQuickRenderControl::renderRequested()

이 신호는 씬 그래프를 렌더링해야 할 때 발생합니다. ` sync()`를 호출할 필요는 없습니다.

[virtual] QWindow *QQuickRenderControl::renderWindow(QPoint *offset)

이 렌더링 컨트롤이 실제로 렌더링하고 있는 창을 반환하도록 하위 클래스에서 재구현되었습니다.

offset 가 null이 아닌 경우, 이 값은 창 내부의 컨트롤 오프셋으로 설정됩니다.

[static] QWindow *QQuickRenderControl::renderWindowFor(QQuickWindow *win, QPoint *offset = nullptr)

win 가 렌더링되고 있는 실제 창이 있는 경우, 해당 창을 반환합니다.

offset 가 null이 아닌 경우, 해당 창 내부의 렌더링 오프셋으로 설정됩니다.

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

이 QQuickRenderControl 와 연관된 QRhi 를 반환합니다.

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

참조: commandBuffer(), beginFrame(), endFrame().

[since 6.0] int QQuickRenderControl::samples() const

현재 샘플 수를 반환합니다. 1 또는 0은 멀티샘플링이 없음을 의미합니다.

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

setSamples()도 참조하십시오 .

[signal] void QQuickRenderControl::sceneChanged()

이 신호는 씬 그래프가 업데이트될 때 발생하며, 이는 ` polishItems()` 및 ` sync()`를 호출해야 함을 의미합니다. ` sync()`가 `true`를 반환하면 ` render()`를 호출해야 합니다.

[since 6.0] void QQuickRenderControl::setSamples(int sampleCount)

멀티샘플링에 사용할 샘플 수를 설정합니다. ` sampleCount `가 0이거나 1인 경우, 멀티샘플링이 비활성화됩니다.

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

samples(), initialize(), QQuickRenderTarget도 참조하십시오 .

bool QQuickRenderControl::sync()

이 함수는 QML 씬을 렌더링 씬 그래프와 동기화하는 데 사용됩니다.

전용 렌더링 스레드를 사용하는 경우, 이 호출이 진행되는 동안 GUI 스레드는 차단되어야 합니다.

동기화로 인해 씬 그래프가 변경된 경우 true를 반환합니다.

[since 6.0] QQuickWindow *QQuickRenderControl::window() const

이 QQuickRenderControl 와 연관된 QQuickWindow 를 반환합니다.

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