QQuickRhiItemRenderer Class

멤버 함수 문서

QQuickRhiItemRenderer::QQuickRhiItemRenderer()

새로운 렌더러를 생성합니다.

이 함수는 GUI 스레드가 차단된 상태에서 씬 그래프 동기화 단계 중에 렌더링 스레드에서 호출됩니다.

QQuickRhiItem::createRenderer()도 참조하십시오 .

[virtual noexcept] QQuickRhiItemRenderer::~QQuickRhiItemRenderer()

QQuickRhiItem 항목에 대한 씬 그래프 리소스가 정리되면 렌더러가 자동으로 삭제됩니다.

이 함수는 렌더링 스레드에서 호출됩니다.

특정 조건에서는 렌더러 객체가 소멸된 후 다시 생성되는 것이 정상이며 예상되는 현상입니다. 이는 렌더러의 수명이 기본적으로 기본이 되는 씬 그래프 노드를 따르기 때문입니다. 예를 들어, QQuickRhiItem 객체의 부모를 변경하여 다른 QQuickWindow 에 속하게 할 경우, 창 변경으로 인해 씬 그래프 노드가 모두 삭제되고 다시 생성됩니다. 이 과정에서 QQuickRhiItemRenderer 도 삭제되고 새로 생성됩니다.

QRhiWidget 와 달리, QQuickRhiItemRenderer 는 QRhi 를 통해 생성된 그래픽 리소스를 해제(또는 조기 해제)하기 위한 추가 코드 경로를 구현할 필요가 없습니다. 소멸자에서 모든 리소스를 해제하거나 스마트 포인터를 사용하는 것으로 충분합니다.

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

해당 아이템의 색상 버퍼 역할을 하는 텍스처를 반환합니다.

이 함수는 반드시 ` initialize()` 및 ` render()` 내에서만 호출되어야 합니다.

깊이-스텐실 버퍼 및 QRhiRenderTarget 과는 달리, 이 텍스처는 항상 사용할 수 있으며 isAutoRenderTargetEnabled 의 값과 관계없이 QQuickRhiItem 에 의해 관리됩니다.

msaaColorBuffer(), depthStencilBuffer(), renderTarget(), resolveTexture()도 참조하십시오 .

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

해당 아이템의 렌더링에 사용되는 깊이-스텐실 버퍼를 반환합니다.

이 함수는 반드시 initialize() 및 render() 내에서만 호출되어야 합니다.

isAutoRenderTargetEnabled 가 true 인 경우에만 사용할 수 있습니다. 그렇지 않은 경우 반환 값은 nullptr 이며, initialize()의 재구현에서 깊이-스텐실 버퍼와 QRhiTextureRenderTarget 를 생성하고 관리해야 합니다.

colorTexture() 및 renderTarget()도 참조하십시오 .

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

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

QRhi, QRhiTexture 및 기타 관련 객체를 조회하려면 rhi(), colorTexture(), depthStencilBuffer() 및 renderTarget()를 호출하십시오.

항목 크기가 변경될 때, ` QRhi ` 객체, 색상 버퍼 텍스처 및 깊이/스텐실 버퍼 객체는 모두 이전과 동일한 인스턴스(따라서 게터는 동일한 포인터를 반환함)이지만, 색상 및 깊이/스텐실 버퍼는 재구축되었을 가능성이 높으므로, ` size ` 및 그 기반이 되는 네이티브 텍스처 리소스는 마지막 호출 시점과 다를 수 있습니다.

또한 이 함수의 호출 사이에 QRhi 객체와 색상 버퍼 텍스처가 변경될 수 있다는 점을 고려하여 재구현을 준비해야 합니다. 예를 들어, 항목이 새로운 ` QQuickWindow`에 속하도록 부모가 재설정되면, 이 함수를 이후 호출할 때 ` QRhi `와 ` QQuickRhiItem `가 관리하는 모든 관련 리소스는 이전과 다른 인스턴스가 됩니다. 따라서 하위 클래스에서 이전에 생성한 모든 ` QRhi ` 리소스는 더 이상 사용되어서는 안 되는 이전 ` QRhi `에 속하므로, 이를 모두 소멸시키는 것이 중요합니다.

isAutoRenderTargetEnabled 가 true 로 설정된 경우(기본값), colorTexture() (또는 msaaColorBuffer()) 및 심도-스텐실 버퍼와 연관된 depth-stencil QRhiRenderBuffer 와 QRhiTextureRenderTarget 가 자동으로 생성 및 관리됩니다. initialize() 및 render()를 재구현할 경우, depthStencilBuffer() 및 renderTarget()를 통해 해당 객체를 조회할 수 있습니다. isAutoRenderTargetEnabled 가 false 로 설정된 경우, 이러한 객체는 더 이상 자동으로 생성 및 관리되지 않습니다. 대신, 버퍼를 생성하고 렌더 타겟을 적절하게 설정하는 것은 initialize() 구현에 달려 있습니다. 렌더 타깃에 대한 추가 색상 또는 깊이-스텐실 어태치먼트를 수동으로 관리할 경우, 해당 어태치먼트의 크기와 샘플 수는 항상 ` colorTexture()`(또는 ` msaaColorBuffer()`)의 크기와 샘플 수를 따라야 하며, 그렇지 않으면 렌더링 오류나 3D API 유효성 검사 오류가 발생할 수 있습니다.

서브클래스에서 생성된 그래픽 리소스는 서브클래스의 소멸자 구현에서 해제되어야 합니다.

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

이 함수는 렌더 스레드가 존재하는 경우 해당 스레드에서 호출됩니다.

render()도 참조하십시오 .

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

해당 항목의 멀티샘플 컬러 버퍼 역할을 하는 렌더 버퍼를 반환합니다.

이 함수는 반드시 initialize() 및 render() 내에서만 호출되어야 합니다.

sampleCount 가 1보다 커서 멀티샘플 앤티앨리어싱이 활성화된 경우, 반환된 QRhiRenderBuffer 는 이에 상응하는 샘플 수를 가지며 컬러 버퍼 역할을 합니다. 이 버퍼에 렌더링하는 데 사용되는 그래픽 파이프라인은 동일한 샘플 수로 생성되어야 하며, 깊이-스텐실 버퍼의 샘플 수도 일치해야 합니다. 멀티샘플 콘텐츠는 ` resolveTexture()`에서 반환된 텍스처로 변환되어야 합니다. ` isAutoRenderTargetEnabled `가 ` true`일 때, ` renderTarget()`는 이를 수행하도록 자동으로 설정되며, 이때 `msaaColorBuffer()`를 색상 어태치먼트 0의 ` renderbuffer `로, ` resolveTexture()`를 해당 ` resolveTexture`로 설정합니다.

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

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

colorTexture(), depthStencilBuffer(), renderTarget() 및 resolveTexture()도 참조하십시오 .

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

배경색 버퍼의 내용을 업데이트해야 할 때 호출됩니다.

이 함수가 호출되기 전에는 항상 최소 한 번 이상 initialize()이 호출됩니다.

업데이트를 요청하려면, QML 또는 메인/GUI 스레드의 C++ 코드(예: 속성 세터 내)에서 호출할 때는 ` QQuickItem::update()`를, ` QQuickRhiItemRenderer ` 콜백 내에서 호출할 때는 ` update()`를 호출하십시오. `render()` 내부에서 ` QQuickRhiItemRenderer`의 ` update()`를 호출하면 업데이트가 지속적으로 트리거됩니다.

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

이 함수는 렌더 스레드가 존재하는 경우 해당 스레드에서 호출됩니다.

initialize() 및 synchronize()도 참조하십시오 .

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

render() 메서드를 재구현할 때 QRhiCommandBuffer::beginPass()과 함께 사용해야 하는 렌더 타겟 객체를 반환합니다.

이 함수는 반드시 initialize() 및 render() 내에서만 호출되어야 합니다.

isAutoRenderTargetEnabled 가 true 인 경우에만 사용할 수 있습니다. 그렇지 않으면 반환 값은 nullptr 이며, depth-stencil 버퍼와 QRhiTextureRenderTarget 를 생성하고 관리하는 것은 initialize()의 재구현에 달려 있습니다.

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

또한 colorTexture(), depthStencilBuffer() 및 QQuickWindow::effectiveDevicePixelRatio()도 참조하십시오 .

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

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

멀티샘플 앤티앨리어싱이 활성화되지 않은 경우, 반환 값은 ` nullptr `입니다.

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

MSAA가 활성화된 경우, 이 텍스처는 Qt Quick 의 메인 렌더 패스에서 쿼드에 텍스처를 적용할 때 항목의 기본 씬 그래프 노드에서 사용되는 텍스처입니다. 그러나 QQuickRhiItemRenderer 의 렌더링은 msaaColorBuffer()에서 반환된 (멀티샘플) QRhiRenderBuffer 을 대상으로 해야 합니다. isAutoRenderTargetEnabled 가 true 인 경우, 이는 renderTarget()에서 반환된 QRhiRenderTarget 에 의해 처리됩니다. 그렇지 않은 경우, 색상 버퍼와 해상도 텍스처를 모두 포함하여 렌더 타겟 객체를 올바르게 구성하는 것은 하위 클래스 코드의 몫입니다.

colorTexture()도 참조하십시오 .

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

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

이 메서드는 반드시 ` initialize()` 및 ` render()` 내에서만 호출되어야 합니다.

[pure virtual protected] void QQuickRhiItemRenderer::synchronize(QQuickRhiItem *item)

이 함수는 메인/GUI 스레드가 차단된 상태에서, 렌더링 스레드가 존재할 경우 해당 스레드에서 호출됩니다. 이 함수는 the item's synchronize step에서 호출되며, 메인 스레드와 렌더 스레드에 속한 데이터의 읽기 및 쓰기를 허용합니다. 일반적으로 QQuickRhiItem 에 저장된 속성 값은 QQuickRhiItemRenderer 로 복사되어, 이후 렌더 스레드와 메인 스레드가 병렬로 작업을 계속할 때 render()에서 안전하게 읽을 수 있도록 합니다.

initialize() 및 render()도 참조하십시오 .

[protected] void QQuickRhiItemRenderer::update()

오프스크린 컬러 버퍼의 내용을 업데이트해야 할 때 이 함수를 호출하십시오. (즉, ` render()`가 다시 호출되도록 요청하기 위함입니다. 호출은 나중에 이루어지며, 업데이트는 일반적으로 렌더링 속도에 맞춰 제한된다는 점에 유의하십시오.)

이 함수는 render() 내에서 호출하여 업데이트를 예약할 수 있습니다.