QRhiWidget Class

class ExampleRhiWidget : public QRhiWidget
{
public:
    ExampleRhiWidget(QWidget *parent = nullptr) : QRhiWidget(parent) { }
    void initialize(QRhiCommandBuffer *cb) override;
    void render(QRhiCommandBuffer *cb) override;
private:
    QRhi *m_rhi = nullptr;
    std::unique_ptr<QRhiBuffer> m_vbuf;
    std::unique_ptr<QRhiBuffer> m_ubuf;
    std::unique_ptr<QRhiShaderResourceBindings> m_srb;
    std::unique_ptr<QRhiGraphicsPipeline> m_pipeline;
    QMatrix4x4 m_viewProjection;
    float m_rotation = 0.0f;
};

float vertexData[] = {
     0.0f,   0.5f,     1.0f, 0.0f, 0.0f,
    -0.5f,  -0.5f,     0.0f, 1.0f, 0.0f,
     0.5f,  -0.5f,     0.0f, 0.0f, 1.0f,
};

QShader getShader(const QString &name)
{
    QFile f(name);
    return f.open(QIODevice::ReadOnly) ? QShader::fromSerialized(f.readAll()) : QShader();
}

void ExampleRhiWidget::initialize(QRhiCommandBuffer *cb)
{
    if (m_rhi != rhi()) {
        m_pipeline.reset();
        m_rhi = rhi();
    }

    if (!m_pipeline) {
        m_vbuf.reset(m_rhi->newBuffer(QRhiBuffer::Immutable, QRhiBuffer::VertexBuffer, sizeof(vertexData)));
        m_vbuf->create();

        m_ubuf.reset(m_rhi->newBuffer(QRhiBuffer::Dynamic, QRhiBuffer::UniformBuffer, 64));
        m_ubuf->create();

        m_srb.reset(m_rhi->newShaderResourceBindings());
        m_srb->setBindings({
            QRhiShaderResourceBinding::uniformBuffer(0, QRhiShaderResourceBinding::VertexStage, m_ubuf.get()),
        });
        m_srb->create();

        m_pipeline.reset(m_rhi->newGraphicsPipeline());
        m_pipeline->setShaderStages({
            { QRhiShaderStage::Vertex, getShader(QLatin1String(":/shader_assets/color.vert.qsb")) },
            { QRhiShaderStage::Fragment, getShader(QLatin1String(":/shader_assets/color.frag.qsb")) }
        });
        QRhiVertexInputLayout inputLayout;
        inputLayout.setBindings({
            { 5 * sizeof(float) }
        });
        inputLayout.setAttributes({
            { 0, 0, QRhiVertexInputAttribute::Float2, 0 },
            { 0, 1, QRhiVertexInputAttribute::Float3, 2 * sizeof(float) }
        });
        m_pipeline->setVertexInputLayout(inputLayout);
        m_pipeline->setShaderResourceBindings(m_srb.get());
        m_pipeline->setRenderPassDescriptor(renderTarget()->renderPassDescriptor());
        m_pipeline->create();

        QRhiResourceUpdateBatch *resourceUpdates = m_rhi->nextResourceUpdateBatch();
        resourceUpdates->uploadStaticBuffer(m_vbuf.get(), vertexData);
        cb->resourceUpdate(resourceUpdates);
    }

    const QSize outputSize = colorTexture()->pixelSize();
    m_viewProjection = m_rhi->clipSpaceCorrMatrix();
    m_viewProjection.perspective(45.0f, outputSize.width() / (float) outputSize.height(), 0.01f, 1000.0f);
    m_viewProjection.translate(0, 0, -4);
}

void ExampleRhiWidget::render(QRhiCommandBuffer *cb)
{
    QRhiResourceUpdateBatch *resourceUpdates = m_rhi->nextResourceUpdateBatch();
    m_rotation += 1.0f;
    QMatrix4x4 modelViewProjection = m_viewProjection;
    modelViewProjection.rotate(m_rotation, 0, 1, 0);
    resourceUpdates->updateDynamicBuffer(m_ubuf.get(), 0, 64, modelViewProjection.constData());

    const QColor clearColor = QColor::fromRgbF(0.4f, 0.7f, 0.0f, 1.0f);
    cb->beginPass(renderTarget(), clearColor, { 1.0f, 0 }, resourceUpdates);

    cb->setGraphicsPipeline(m_pipeline.get());
    const QSize outputSize = colorTexture()->pixelSize();
    cb->setViewport(QRhiViewport(0, 0, outputSize.width(), outputSize.height()));
    cb->setShaderResources();
    const QRhiCommandBuffer::VertexInput vbufBinding(m_vbuf.get(), 0);
    cb->setVertexInput(0, 1, &vbufBinding);
    cb->draw(3);

    cb->endPass();

    update();
}

#version 440
layout(location = 0) in vec4 position;
layout(location = 1) in vec3 color;
layout(location = 0) out vec3 v_color;
layout(std140, binding = 0) uniform buf {
    mat4 mvp;
};

void main()
{
    v_color = color;
    gl_Position = mvp * position;
}

#version 440
layout(location = 0) in vec3 v_color;
layout(location = 0) out vec4 fragColor;

void main()
{
    fragColor = vec4(v_color, 1.0);
}

멤버 함수 문서

[explicit] QRhiWidget::QRhiWidget(QWidget *parent = nullptr, Qt::WindowFlags f = {})

위젯 플래그가 f 으로 설정된 parent 의 자식인 위젯을 생성합니다.

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

파괴자.

QRhiWidget::Api QRhiWidget::api() const

현재 설정된 그래픽 API(QRhi 백엔드)를 반환합니다.

setApi()도 참조하세요 .

[protected] QRhiTexture *QRhiWidget::colorTexture() const

위젯의 컬러 버퍼 역할을 하는 텍스처를 반환합니다.

initialize() 및 render()에서만 호출해야 합니다.

뎁스 스텐실 버퍼 및 QRhiRenderTarget 와 달리 이 텍스처는 항상 사용 가능하며 autoRenderTarget 의 값과 관계없이 QRhiWidget 에서 관리합니다.

msaaColorBuffer(), depthStencilBuffer(), renderTarget() 및 resolveTexture()도 참조하세요 .

[protected] QRhiRenderBuffer *QRhiWidget::depthStencilBuffer() const

위젯의 렌더링에 사용되는 뎁스 스텐실 버퍼를 반환합니다.

initialize() 및 render()에서만 호출해야 합니다.

autoRenderTarget 가 true 일 때만 사용할 수 있습니다. 그렇지 않으면 반환되는 값은 nullptr 이며 initialize()를 다시 구현하여 깊이 스텐실 버퍼와 QRhiTextureRenderTarget 를 생성하고 관리해야 합니다.

colorTexture() 및 renderTarget()도 참조하세요 .

[override virtual protected] bool QRhiWidget::event(QEvent *e)

다시 구현합니다: QWidget::event(QEvent * 이벤트).

[signal] void QRhiWidget::frameSubmitted()

이 신호는 위젯의 최상위 창이 구성을 완료하고 submitted a frame.

QImage QRhiWidget::grabFramebuffer() const

새 프레임을 렌더링하고 텍스처의 내용을 다시 읽은 다음 QImage 로 반환합니다.

오류가 발생하면 null QImage 이 반환됩니다.

반환된 QImage 은 colorBufferFormat()에 따라 QImage::Format_RGBA8888, QImage::Format_RGBA16FPx4, QImage::Format_RGBA32FPx4 또는 QImage::Format_BGR30 의 형식을 갖습니다.

QRhiWidget 는 렌더러의 블렌딩 및 컴포지션 방식을 알지 못하므로 출력에 RGB 색상 값에 알파가 미리 곱해져 있는지 알 수 없습니다. 따라서 _Premultiplied QImage 형식은 적절한 경우에도 반환된 QImage 에 사용되지 않습니다. 결과 데이터를 적절하게 재해석하는 것은 호출자의 몫입니다.

이 함수는 QOpenGLWidget 및 QQuickWidget 과의 일관성을 위해 grabFramebuffer()로 명명되었습니다. QRhiWidget 의 콘텐츠에서 CPU 측 이미지 데이터를 가져오는 유일한 방법은 아닙니다. QRhiWidget 또는 그 조상에서 QWidget::grab()를 호출하는 것도 작동합니다( QPixmap 반환). QImage 로 직접 작업하는 것 외에도 grabFramebuffer()의 또 다른 장점은 나머지 QWidget 인프라를 거칠 필요 없이 바로 새 프레임 렌더링을 트리거한 다음 읽기백을 수행할 수 있기 때문에 성능이 약간 더 좋을 수 있다는 것입니다.

setColorBufferFormat()도 참조하세요 .

[virtual protected] void QRhiWidget::initialize(QRhiCommandBuffer *cb)

위젯이 처음 초기화될 때, 연결된 텍스처의 크기, 형식 또는 샘플 수가 변경될 때, 또는 QRhi 및 텍스처가 어떤 이유로든 변경될 때 호출됩니다. 이 함수는 render()의 렌더링 코드에서 사용하는 그래픽 리소스를 유지(아직 생성되지 않은 경우 생성, 크기가 변경된 경우 조정 및 다시 빌드)해야 합니다.

QRhi, QRhiTexture, 기타 관련 객체를 쿼리하려면 rhi(), colorTexture(), depthStencilBuffer(), renderTarget()를 호출하세요.

위젯 크기가 변경되면 QRhi 객체, 색상 버퍼 텍스처 및 깊이 스텐실 버퍼 객체는 모두 이전과 동일한 인스턴스(따라서 게터는 동일한 포인터를 반환)이지만 색상 및 깊이/스텐실 버퍼는 다시 빌드되었을 가능성이 있으므로 size 및 기본 네이티브 텍스처 리소스가 마지막 호출 때와 다를 수 있습니다.

또한 이 함수를 호출할 때마다 QRhi 객체와 컬러 버퍼 텍스처가 변경될 수 있으므로 재구현을 준비해야 합니다. 객체가 달라지는 한 가지 특별한 경우는 아직 표시되지 않은 위젯으로 grabFramebuffer()를 수행한 다음 최상위 위젯 내에서 위젯을 화면에 표시하는 경우입니다. 이 경우 전용 QRhi 으로 그랩이 이루어지며, 이후 초기화() 및 render() 호출에서 최상위 창에 연결된 QRhi 으로 대체됩니다. 또 다른 일반적인 경우는 위젯이 새로운 최상위 창에 속하도록 부모를 다시 지정하는 경우입니다. 이 경우 QRhi 및 QRhiWidget 에서 관리하는 모든 관련 리소스는 이후 이 함수를 호출할 때 이전과 다른 인스턴스가 됩니다. 그러면 이전에 하위 클래스에 의해 생성된 모든 기존 QRhi 리소스는 더 이상 위젯에서 사용해서는 안 되는 이전 QRhi 에 속하기 때문에 파괴됩니다.

autoRenderTarget 가 기본값인 true 인 경우, colorTexture() (또는 msaaColorBuffer()) 및 깊이 스텐실 버퍼와 연결된 QRhiRenderBuffer 및 QRhiTextureRenderTarget 가 자동으로 생성되고 관리됩니다. 초기화() 및 render()의 재구현은 depthStencilBuffer() 및 renderTarget()를 통해 해당 객체를 쿼리할 수 있습니다. autoRenderTarget 가 false 로 설정되면 이러한 객체는 더 이상 자동으로 생성 및 관리되지 않습니다. 대신 초기화() 구현에서 버퍼를 생성하고 렌더링 대상을 적절하게 설정해야 합니다. 렌더링 대상에 대한 추가 색상 또는 깊이 스텐실 첨부 파일을 수동으로 관리할 때 크기와 샘플 수는 항상 colorTexture() / msaaColorBuffer()의 크기와 샘플 수를 따라야 하며, 그렇지 않으면 렌더링 또는 3D API 유효성 검사 오류가 발생할 수 있습니다.

서브클래스에서 생성된 그래픽 리소스는 서브클래스의 디스트럭터 구현에서 해제될 것으로 예상됩니다.

cb 는 위젯의 현재 프레임에 대한 QRhiCommandBuffer 입니다. 이 함수는 프레임이 기록되고 있지만 활성 렌더 패스가 없는 상태에서 호출됩니다. 명령 버퍼는 주로 render()로 지연시키지 않고 resource updates 을 큐에 넣을 수 있도록 하기 위해 제공됩니다.

render()도 참조하세요 .

bool QRhiWidget::isDebugLayerEnabled() const

사용 중인 그래픽 API에 해당되는 경우 디버그 또는 유효성 검사 레이어가 요청될 경우 true를 반환합니다.

setDebugLayerEnabled()도 참조하세요 .

[protected] QRhiRenderBuffer *QRhiWidget::msaaColorBuffer() const

위젯의 멀티샘플 컬러 버퍼 역할을 하는 렌더버퍼를 반환합니다.

initialize() 및 render()에서만 호출해야 합니다.

sampleCount 이 1보다 커서 멀티샘플 안티앨리어싱이 활성화된 경우 반환된 QRhiRenderBuffer 은 샘플 수가 일치하며 컬러 버퍼로 사용됩니다. 이 버퍼로 렌더링하는 데 사용되는 그래픽 파이프라인은 동일한 샘플 수로 생성되어야 하며 깊이 스텐실 버퍼의 샘플 수 역시 일치해야 합니다. 멀티 샘플 콘텐츠는 resolveTexture()에서 반환된 텍스처로 해석될 것으로 예상됩니다. autoRenderTarget 가 true 인 경우 renderTarget()는 이를 위해 자동으로 설정되며, msaaColorBuffer()를 색상 첨부 0의 renderbuffer 로 설정하고 resolveTexture()를 해당 resolveTexture 로 설정합니다.

MSAA를 사용하지 않는 경우 반환 값은 nullptr 입니다. 대신 colorTexture()를 사용하십시오.

기본 3D 그래픽 API에 따라 샘플 수가 1보다 큰 멀티샘플 텍스처와 컬러 렌더버퍼 간에 실질적인 차이가 없을 수 있습니다(QRhi 는 둘 다 동일한 기본 리소스 유형에 매핑할 수 있습니다). 그러나 일부 구형 API는 텍스처와 렌더버퍼를 구분할 수 있습니다. 멀티샘플 렌더버퍼는 사용할 수 있지만 멀티샘플 텍스처는 사용할 수 없는 OpenGL ES 3.0을 지원하기 위해 QRhiWidget 에서는 항상 멀티샘플 QRhiRenderBuffer 을 색상 어태치먼트로 사용하여 MSAA를 수행합니다(멀티샘플 QRhiTexture 은 사용하지 않음).

colorTexture(), depthStencilBuffer(), renderTarget() 및 resolveTexture()도 참조하세요 .

[override virtual protected] void QRhiWidget::paintEvent(QPaintEvent *e)

다시 구현합니다: QWidget::paintEvent(QPaintEvent * 이벤트).

페인트 이벤트를 처리합니다.

QWidget::update()를 호출하면 페인트 이벤트 e 를 전송하여 이 함수를 호출합니다. 이벤트 전송은 비동기식이며 update()에서 반환된 후 어느 시점에 발생합니다. 그러면 이 함수는 약간의 준비 과정을 거쳐 가상 render()를 호출하여 QRhiWidget 의 연관된 텍스처의 내용을 업데이트합니다. 그러면 위젯의 최상위 창이 텍스처를 나머지 창과 합성합니다.

[virtual protected] void QRhiWidget::releaseResources()

그래픽 리소스를 조기 릴리스해야 할 필요가 있을 때 호출됩니다.

일반적으로 최상위 위젯의 하위 계층 구조에 추가되어 해당 위젯과 최상위 위젯의 나머지 수명 기간 동안 유지되는 QRhiWidget 에는 이런 일이 발생하지 않습니다. 따라서 애플리케이션에 최상위 위젯(기본 창)이 하나만 있는 경우 등 많은 경우 이 기능을 다시 구현할 필요가 없습니다. 그러나 위젯(또는 위젯의 조상)의 리패런팅이 필요한 경우, 견고하고 잘 작성된 QRhiWidget 서브클래스에서 이 함수를 다시 구현해야 합니다.

이 함수가 호출되면 구현은 모든 QRhi 리소스(QRhiBuffer, QRhiTexture 등 객체)를 소멸자에서 예상되는 방식과 유사하게 소멸할 것으로 예상됩니다. 결국 initialize()가 나중에 호출될 것이므로 널링 아웃, 스마트 포인터 사용 또는 resources-invalid 플래그 설정도 필요합니다. 그러나 리소스 릴리스를 후속 initialize()로 연기하는 것은 잘못된 방법입니다. 이 함수가 호출되면 리소스가 반환되기 전에 삭제되어야 합니다. 또한 이 함수를 구현해도 클래스 소멸자(또는 스마트 포인터)가 대체되지 않으므로 그래픽 리소스는 여전히 둘 다에서 해제되어야 합니다.

실제 예제는 큐브 RHI 위젯 예제를 참조하세요. 여기서 QRhiWidget 을 자식 위젯(부모 위젯이 있기 때문에)과 최상위 위젯(부모 위젯이 없기 때문에)으로 전환하는 버튼은 QRhiWidget 의 수명 동안 연결된 최상위 위젯, 기본 창 및 QRhi 이 모두 변경되고 이전에 사용된 QRhi 이 소멸되므로 아직 살아있는 QRhiWidget 에서 관리하는 관련 리소스가 조기 해제되므로 이 함수 호출을 트리거합니다 .

이 함수가 호출되는 또 다른 경우는 grabFramebuffer()가 보이는 창에 추가되지 않은 QRhiWidget 과 함께 사용되는 경우, 즉 렌더링이 화면 밖에서 수행되는 경우입니다. 나중에 QRhiWidget 이 표시되거나 표시되는 위젯 계층 구조에 추가되면 관련 QRhi 이 화면 밖 렌더링에 사용되는 임시에서 창 전용으로 변경되어 이 함수도 트리거됩니다.

initialize()도 참조하세요 .

[virtual protected] void QRhiWidget::render(QRhiCommandBuffer *cb)

위젯 콘텐츠(즉, 텍스처의 콘텐츠)를 업데이트해야 할 때 호출됩니다.

이 함수가 호출되기 전에 항상 initialize()를 한 번 이상 호출합니다.

업데이트를 요청하려면 QWidget::update()를 호출합니다. render() 내에서 update()를 호출하면 vsync에 의해 스로틀링되어 지속적으로 업데이트됩니다.

cb 는 위젯의 현재 프레임에 대한 QRhiCommandBuffer 입니다. 이 함수는 프레임이 기록되고 있지만 활성 렌더 패스가 없는 상태에서 호출됩니다.

initialize()도 참조하세요 .

[signal] void QRhiWidget::renderFailed()

이 신호는 위젯이 백그라운드 텍스처로 렌더링해야 하는데( widget update 또는 grabFramebuffer() 호출로 인해) 그래픽 구성과 관련된 문제로 인해 위젯이 사용할 QRhi 이 없을 때마다 발생합니다.

이 신호는 문제가 발생할 때 여러 번 발생할 수 있습니다. 한 번만 발생한다고 가정하지 마세요. 오류 처리 코드가 한 번만 알림을 받으려면 Qt::SingleShotConnection 에 연결하세요.

[protected] QRhiRenderTarget *QRhiWidget::renderTarget() const

render()의 재구현에서 QRhiCommandBuffer::beginPass()와 함께 사용해야 하는 렌더링 대상 객체를 반환합니다.

initialize() 및 render()에서만 호출해야 합니다.

autoRenderTarget 가 true 일 때만 사용할 수 있습니다. 그렇지 않으면 반환되는 값은 nullptr 이며 initialize()의 재구현에 따라 깊이 스텐실 버퍼와 QRhiTextureRenderTarget 를 생성하고 관리합니다.

graphics pipelines 을 생성할 때는 QRhiRenderPassDescriptor 이 필요합니다. 반환된 QRhiTextureRenderTarget 에서 renderPassDescriptor()을 호출하여 쿼리할 수 있습니다.

colorTexture() 및 depthStencilBuffer()도 참조하세요 .

[override virtual protected] void QRhiWidget::resizeEvent(QResizeEvent *e)

다시 구현합니다: QWidget::resizeEvent(QResizeEvent * 이벤트).

e 이벤트 매개변수로 전달된 크기 조정 이벤트를 처리합니다. 가상 함수 initialize()를 호출합니다.

[protected] QRhiTexture *QRhiWidget::resolveTexture() const

멀티샘플 콘텐츠가 해결되는 비멀티샘플 텍스처를 반환합니다.

멀티샘플 앤티앨리어싱이 활성화되지 않은 경우 결과는 nullptr 입니다.

initialize() 및 render()에서만 호출해야 합니다.

MSAA가 활성화된 경우 이 텍스처가 화면의 나머지 QWidget 콘텐츠와 합성됩니다. 그러나 QRhiWidget 의 렌더링은 msaaColorBuffer()에서 반환된 (멀티샘플) QRhiRenderBuffer 을 대상으로 해야 합니다. autoRenderTarget 가 true 인 경우 이는 renderTarget()에서 반환된 QRhiRenderTarget 에 의해 처리됩니다. 그렇지 않으면 서브클래스 코드가 컬러 버퍼와 리졸브 텍스처를 모두 사용하여 렌더링 대상 객체를 올바르게 구성해야 합니다.

colorTexture()도 참조하세요 .

[protected] QRhi *QRhiWidget::rhi() const

현재 QRhi 객체를 반환합니다.

initialize() 및 render()에서만 호출해야 합니다.

void QRhiWidget::setApi(QRhiWidget::Api api)

사용할 그래픽 API 및 QRhi 백엔드를 api 으로 설정합니다.

기본값은 플랫폼에 따라 다릅니다: macOS 및 iOS의 경우 Metal, Windows의 경우 Direct 3D 11, 그 외의 경우 OpenGL입니다.

api 은 위젯과 그 최상위 창에 대해 한 번만 설정할 수 있으며, 설정이 완료되고 적용되면 창은 해당 API와 QRhi 백엔드만 사용하여 렌더링할 수 있습니다. 다른 값을 설정하거나 다른 api 을 사용하여 QRhiWidget 을 추가하려고 시도하면 예상대로 작동하지 않습니다.

setColorBufferFormat(), setDebugLayerEnabled() 및 api()도 참조하세요 .

[protected] void QRhiWidget::setAutoRenderTarget(bool enabled)

위젯에서 깊이 스텐실 QRhiRenderBuffer 및 QRhiTextureRenderTarget 을 자동으로 생성하고 유지 관리할지 여부를 제어합니다. 기본값은 true 입니다.

자동 모드에서는 뎁스 스텐실 버퍼의 크기와 샘플 수가 컬러 버퍼 텍스처의 설정을 따릅니다. 비자동 모드에서 renderTarget() 및 depthStencilBuffer()은 항상 nullptr 을 반환하며, 이러한 객체를 설정하고 관리하는 것은 애플리케이션의 initialize() 구현에 달려 있습니다.

자동 모드를 비활성화하려면 파생 클래스의 생성자 등에서 enabled 을 false 으로 설정한 상태에서 이 함수를 호출하세요.

void QRhiWidget::setDebugLayerEnabled(bool enable)

enable 이 참이면 기본 그래픽 API의 디버그 또는 유효성 검사 계층을 요청합니다.

벌칸 및 다이렉트 3D에 적용됩니다.

기본적으로 이 기능은 비활성화되어 있습니다.

setApi() 및 isDebugLayerEnabled()도 참조하세요 .