Back to Qt.io
Contact Us Blog Download Qt
이 페이지에서

QCanvasRhiPaintDriver Class

QCanvasRhiPaintDriver 클래스는 QRhi 렌더 타겟 및 오프스크린 캔버스에 대한 QCanvasPainter 기반 렌더링의 하위 레벨 측면을 관리합니다. 더 보기...

헤더: #include <QCanvasRhiPaintDriver>
CMake: find_package(Qt6 REQUIRED COMPONENTS CanvasPainter)
target_link_libraries(mytarget PRIVATE Qt6::CanvasPainter)
이후 Qt 6.11
상태: 기술 미리보기

공용 형

enum class BeginPaintFlag { DepthTest }
flags BeginPaintFlags
enum class EndPaintFlag { DoNotRecordRenderPass }
flags EndPaintFlags

공용 함수

void beginPaint(QCanvasOffscreenCanvas &canvas, QRhiCommandBuffer *cb, QCanvasRhiPaintDriver::BeginPaintFlags flags = {})
void beginPaint(QRhiCommandBuffer *cb, QRhiRenderTarget *rt, const QMatrix4x4 &matrix, QCanvasRhiPaintDriver::BeginPaintFlags flags = {})
void beginPaint(QRhiCommandBuffer *cb, QRhiRenderTarget *rt, const QColor &fillColor = Qt::black, QSize logicalSize = QSize(), float dpr = 1.0f, QCanvasRhiPaintDriver::BeginPaintFlags flags = {})
void endPaint(QCanvasRhiPaintDriver::EndPaintFlags flags = {})
void grabCanvas(const QCanvasOffscreenCanvas &canvas, std::function<void (const QImage &)> callback)
void renderPaint()
void resetForNewFrame()

상세 설명

QCanvasPainter 를 사용하여 QRhi 기반 렌더 대상(예: QRhiTexture 또는 QRhiSwapChain 의 컬러 버퍼)에 렌더링하려는 응용 프로그램은 QCanvasPainterFactory 를 사용하여 QCanvasPainter 및 QRhi 와 관련된 QCanvasRhiPaintDriver를 초기화하고 검색합니다. 그리기 API는 QCanvasPainter 에서 제공하지만 렌더링의 저수준 측면(렌더 대상, 명령 버퍼 등)은 QCanvasRhiPaintDriver에서 제어합니다.

참고: 이 클래스는 QCanvasPainterWidget 또는 QCanvasPainterItem 와 같은 편의 클래스 없이 QCanvasPainter 로 작업할 때만 관련이 있는데, 이는 애플리케이션에 QCanvasPainter 인스턴스를 제공하고 암시적으로 렌더링을 관리하기 때문입니다.

애플리케이션은 QCanvasRhiPaintDriver의 인스턴스를 직접 생성하지 않습니다. 대신 paintDriver()를 호출하여 성공적으로 initialized QCanvasPainterFactory 에서 검색합니다.

다음은 QRhiTexture 에 원을 그리고 결과를 다시 읽은 다음 PNG 파일로 저장하는 거의 완전한 독립형 콘솔 애플리케이션입니다:

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

    // std::unique_ptr<QRhi> rhi(QRhi::create(...));

    std::unique_ptr<QRhiTexture> tex(rhi->newTexture(QRhiTexture::RGBA8, QSize(1280, 720), 1,
                                     QRhiTexture::RenderTarget | QRhiTexture::UsedAsTransferSource));
    tex->create();
    std::unique_ptr<QRhiRenderBuffer> ds(rhi->newRenderBuffer(QRhiRenderBuffer::DepthStencil, QSize(1280, 720)));
    ds->create();
    QRhiTextureRenderTargetDescription rtDesc;
    rtDesc.setColorAttachments({ tex.get() });
    rtDesc.setDepthStencilBuffer(ds.get());
    std::unique_ptr<QRhiTextureRenderTarget> rt(rhi->newTextureRenderTarget(rtDesc));
    std::unique_ptr<QRhiRenderPassDescriptor> rp(rt->newCompatibleRenderPassDescriptor());
    rt->setRenderPassDescriptor(rp.get());
    rt->create();

    std::unique_ptr<QCanvasPainterFactory> factory(new QCanvasPainterFactory);
    QCanvasPainter *painter = factory->create(rhi.get());
    QCanvasRhiPaintDriver *pd = factory->paintDriver();

    QRhiCommandBuffer *cb;
    QRhiReadbackResult readbackResult;

    rhi->beginOffscreenFrame(&cb);
    pd->resetForNewFrame();

    {
        pd->beginPaint(cb, rt.get());

        painter->beginPath();
        painter->circle(640, 360, 180);
        painter->setFillStyle(Qt::red);
        painter->fill();

        pd->endPaint();

        QRhiResourceUpdateBatch *u = rhi->nextResourceUpdateBatch();
        u->readBackTexture({ tex.get() }, &readbackResult);
        cb->resourceUpdate(u);
    }

    rhi->endOffscreenFrame();

    QImage image(reinterpret_cast<const uchar *>(readbackResult.data.constData()),
                    readbackResult.pixelSize.width(),
                    readbackResult.pixelSize.height(),
                    QImage::Format_RGBA8888);
    if (rhi->isYUpInFramebuffer())
        image.flip();

    image.save("result.png");

    return 0;
}

멤버 유형 문서

열거형 클래스 QCanvasRhiPaintDriver::BeginPaintFlag
플래그 QCanvasRhiPaintDriver::BeginPaintFlags

beginPaint()의 플래그를 지정합니다.

Constant값설명
QCanvasRhiPaintDriver::BeginPaintFlag::DepthTest0x01렌더링할 때 뎁스 테스트를 활성화해야 함을 나타냅니다. 일반적으로 QCanvasPainter 은 뎁스 버퍼를 쓰거나 테스트하지 않습니다. 다른 렌더러가 작성한 값에 대해 테스트해야 하는 경우 이 플래그를 설정하세요. 사용되는 뎁스 비교 함수는 Less 입니다.

BeginPaintFlags 유형은 QFlags<BeginPaintFlag>에 대한 typedef입니다. BeginPaintFlag 값의 OR 조합을 저장합니다.

열거형 클래스 QCanvasRhiPaintDriver::EndPaintFlag
flags QCanvasRhiPaintDriver::EndPaintFlags

endPaint()에 대한 플래그를 지정합니다.

Constant값설명
QCanvasRhiPaintDriver::EndPaintFlag::DoNotRecordRenderPass0x01QCanvasPainter 의 생성된 명령을 플러시하고 QRhi 렌더 패스를 기록하는 것이 바람직하지 않음을 나타내며, 이후 renderPaint() 에 대한 명시적 호출이 있을 것이기 때문입니다.

EndPaintFlags 유형은 QFlags<EndPaintFlag>에 대한 typedef입니다. EndPaintFlag 값의 OR 조합을 저장합니다.

멤버 함수 문서

void QCanvasRhiPaintDriver::beginPaint(QCanvasOffscreenCanvas &canvas, QRhiCommandBuffer *cb, QCanvasRhiPaintDriver::BeginPaintFlags flags = {})

지정된 오프스크린 canvas 에 페인팅을 시작하고 렌더링 명령을 명령 버퍼 cb 에 기록합니다.

참고: 시작Paint() 뒤에는 항상 endPaint()가 와야 합니다. 중첩은 현재 지원되지 않습니다.

지우기는 QCanvasOffscreenCanvas::Flag::PreserveContents 플래그가 설정되어 있지 않는 한 fill color set on the canvas 으로 수행되며, 이 경우 지우지 않고 캔버스 콘텐츠가 보존됩니다(기본 GPU 아키텍처에 따라 성능에 영향을 미칠 수 있음).

참고: 연결된 QRhi 은 프레임을 녹화 중이어야 하지만(QRhi::beginFrame() 또는 QRhi::beginOffscreenFrame() 이 함수가 호출될 때 렌더 패스 녹화 상태에 있지 않아야 합니다.

flags 는 렌더링을 제어하는 선택적 플래그를 지정합니다.

이 함수는 오버로드된 함수입니다.

void QCanvasRhiPaintDriver::beginPaint(QRhiCommandBuffer *cb, QRhiRenderTarget *rt, const QMatrix4x4 &matrix, QCanvasRhiPaintDriver::BeginPaintFlags flags = {})

렌더링 대상 rt 에 페인팅을 시작하고 렌더링 명령을 명령 버퍼 cb 에 기록합니다.

이 오버로드는 정점을 변환하는 데 사용되는 사용자 정의 matrix 를 사용합니다. 이 행렬은 좌표가 픽셀 단위로 지정된 정점을 처리하기에 적합해야 합니다. 일반적인 사용 사례는 QSGRenderNode 서브클래스 내에서 QCanvasPainter-페이즈 렌더링을 구현할 때 Qt Quick 의 모델뷰-투영 매트릭스를 전달하는 것입니다.

뷰포트 크기와 디바이스 픽셀 비율은 렌더링 대상에서 가져옵니다.

실제로는 EndPaintFlag::DoNotRecordRenderPass 플래그가 설정된 endPaint()가 뒤에 올 것으로 예상되므로 이 오버로드는 채우기 색을 사용하지 않습니다.

참고: 사용자 지정 매트릭스를 사용하는 경우 클리핑에 대한 지원이 제한됩니다. 매트릭스가 추가 배율이나 회전 없이 직교 투영을 지정하는 경우 직사각형의 변형되지 않은 클립이 지원됩니다. 일반적으로 이 모드에서는 클리핑에 의존하는 그리기를 피하는 것이 좋습니다.

참고: 시작Paint() 뒤에는 항상 endPaint()가 와야 합니다. 중첩은 현재 지원되지 않습니다.

참고: rt 에는 색상 및 깊이 스텐실 어태치먼트가 모두 있어야 합니다. 색상 첨부 파일이 여러 개 있는 경우 첨부 파일 0에 대한 색상 버퍼만 기록됩니다. QCanvasPainter 에는 깊이 스텐실 버퍼가 있어야 합니다. 현재는 스텐실만 사용되며 깊이 테스트 및 쓰기는 항상 비활성화되어 있습니다.

참고: 연결된 QRhi 은 프레임을 녹화 중이어야 하지만(QRhi::beginFrame() 또는 QRhi::beginOffscreenFrame()이 호출되어야 함) 이 함수가 호출될 때 렌더 패스 녹화 상태에 있지 않아야 합니다.

flags 는 렌더링을 제어하는 선택적 플래그를 지정합니다.

이 함수는 오버로드된 함수입니다.

void QCanvasRhiPaintDriver::beginPaint(QRhiCommandBuffer *cb, QRhiRenderTarget *rt, const QColor &fillColor = Qt::black, QSize logicalSize = QSize(), float dpr = 1.0f, QCanvasRhiPaintDriver::BeginPaintFlags flags = {})

렌더링 대상 rt 에 페인팅을 시작하고 렌더링 명령을 명령 버퍼 cb 에 기록합니다.

fillColor 는 색상 버퍼를 지우는 데 사용되는 색상을 지정합니다. endPaint ()의 플래그에 EndPaintFlag::DoNotRecordRenderPass 이 포함된 경우 이 값은 무시됩니다.

참고: 시작Paint() 뒤에는 항상 endPaint()가 와야 합니다. 중첩은 현재 지원되지 않습니다.

참고: rt 에는 색상과 깊이 스텐실 어태치먼트가 모두 있을 것으로 예상됩니다. 색상 첨부 파일이 여러 개 있는 경우 첨부 파일 0에 대한 색상 버퍼만 기록됩니다. QCanvasPainter 에는 깊이 스텐실 버퍼가 있어야 합니다. 현재 스텐실만 사용되며 깊이 테스트 및 쓰기는 항상 비활성화되어 있습니다.

logicalSize 는 선택 사항입니다. 비어 있지 않으면 논리 단위로 뷰포트 크기를 지정합니다. dpr 은 logicalSize 이 내부적으로 픽셀로 변환될 수 있도록 스케일 팩터(디바이스 픽셀 비율)를 지정해야 합니다. 렌더링 대상의 크기가 기본적으로 자동으로 사용되므로 실제로는 거의 필요하지 않습니다.

참고: 연결된 QRhi 은 프레임을 녹화 중이어야 하지만(QRhi::beginFrame() 또는 QRhi::beginOffscreenFrame()이 호출되어야 함) 이 함수가 호출될 때 렌더 패스 녹화 상태에 있지 않아야 합니다.

flags 는 렌더링을 제어하는 선택적 플래그를 지정합니다.

이 함수는 오버로드된 함수입니다.

void QCanvasRhiPaintDriver::endPaint(QCanvasRhiPaintDriver::EndPaintFlags flags = {})

QCanvasPainter 그리기 명령에 의해 생성된 모든 QRhi 렌더링을 플러시하고 기록합니다.

기본적으로 이 함수는 전체 렌더링 패스를 기록하므로 내부적으로 QRhiCommandBuffer::beginPass() 및 QRhiCommandBuffer::endPass()을 호출합니다. 지우기 색은 beginPaint()의 fillColor 인수 또는 화면 밖 캔버스의 채우기 색으로 지정됩니다.

flags 는 렌더링 패스의 기록을 제어하는 데 사용할 수 있는데, 경우에 따라 endPaint()가 시작Pass() - 끝Pass() 시퀀스 전체를 실행하는 것이 바람직하지 않을 수 있기 때문입니다.

다음 두 스니펫은 결과에 있어서는 동일하지만, 애플리케이션이 동일한 렌더링 패스 내에서 더 많은 작업을 수행하려는 경우 두 번째 스니펫이 더 많은 유연성을 제공합니다:

pd->beginPaint(cb, rt, Qt::black);
// painter->...
pd->endPaint();
pd->beginPaint(cb, rt);
// painter->...
pd->endPaint(QCanvasRhiPaintDriver::EndPaintFlag::DoNotRecordRenderPass);

cb->beginPass(rt, Qt::black, { 1.0f, 0 });
pd->renderPaint();
cb->endPass();

beginPaint() 및 renderPaint()도 참조하세요 .

void QCanvasRhiPaintDriver::grabCanvas(const QCanvasOffscreenCanvas &canvas, std::function<void (const QImage &)> callback)

canvas 에 대한 텍스처 읽기백 요청을 발행합니다.

callback 함수가 반환되기 전에 호출되거나, 기본 QRhi 및 3D API 구현에 따라 나중에 호출됩니다. 텍스처 콘텐츠를 다시 읽는 데는 GPU 아키텍처에 따라 GPU->CPU 복사본이 포함될 수 있습니다.

이 함수는 beginPaint() - endPaint() 블록 내부와 외부에서 모두 호출할 수 있습니다. 외부에서 호출하면 내부적으로 QRhi::beginOffscreenFrame() 등을 호출하여 언제든지 그랩을 수행할 수 있습니다.

void QCanvasRhiPaintDriver::renderPaint()

QCanvasPainter 그리기 명령으로 생성된 모든 QRhi 렌더링을 기록합니다. endPaint ()가 DoNotRecordRenderPass 과 함께 호출된 경우에만 이 함수를 호출하세요. 그렇지 않으면 호출해서는 안 됩니다.

이 함수가 호출될 때 연결된 QRhi 에 렌더링 패스가 기록되어 있어야 합니다.

endPaint()도 참조하세요 .

void QCanvasRhiPaintDriver::resetForNewFrame()

페인터 엔진 상태를 초기화합니다. 이 함수는 일반적으로 QRhi::beginFrame() 또는 QRhi::beginOffscreenFrame() 다음에 완전히 새로운 프레임을 시작할 때 한 번 호출됩니다.

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.