QSGRenderNode Class

멤버 함수 문서

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

렌더 노드를 삭제합니다. 파생 클래스는 이 메서드 내에서 releaseResources()과 유사한 정리 작업을 수행해야 합니다.

QRhi 및 QRhiBuffer, QRhiTexture, QRhiGraphicsPipeline 등과 같은 리소스를 다룰 때는 std::unique_ptr과 같은 스마트 포인터를 사용하는 것이 종종 권장되는 관행입니다. 이를 통해 소멸자 구현의 필요성을 피할 수 있으며, 소스 코드를 더 간결하게 만들 수 있습니다. 그러나 unique_ptr에 대한 여러 번의 reset() 호출을 포함할 가능성이 높은 releaseResources()을 구현하는 것은 여전히 중요하다는 점을 명심하십시오.

releaseResources()도 참조하십시오 .

[virtual] QSGRenderNode::StateFlags QSGRenderNode::changedStates() const

이 함수는 render() 함수에 의해 변경된 그래픽 상태를 각 비트로 나타내는 마스크를 반환해야 합니다.

기본 구현은 0을 반환하며, 이는 render()에서 관련 상태가 변경되지 않았음을 의미합니다.

const QSGClipNode *QSGRenderNode::clipList() const

현재 클립 목록을 반환합니다.

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

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

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

renderTarget()도 참조하십시오 .

[virtual] QSGRenderNode::RenderingFlags QSGRenderNode::flags() const

이 렌더 노드의 동작을 설명하는 플래그를 반환합니다.

기본 구현은 0을 반환합니다.

RenderingFlag 및 rect()도 참조하십시오 .

qreal QSGRenderNode::inheritedOpacity() const

현재 유효한 불투명도를 반환합니다.

const QMatrix4x4 *QSGRenderNode::matrix() const

현재 모델-뷰 행렬에 대한 포인터를 반환합니다.

[virtual, since 6.0] void QSGRenderNode::prepare()

프레임 준비 단계에서 호출됩니다. render()가 호출되기 전마다 이 함수가 호출됩니다.

render()와 달리, 이 함수는 씬그래프가 기본 명령 버퍼에 현재 프레임에 대한 렌더링 패스를 기록하기 전에 호출됩니다. 이는 Vulkan과 같은 그래픽 API를 사용하여 렌더링할 때, 렌더링 패스 전에 복사 유형의 작업을 기록해야 하는 경우에 유용합니다.

기본 구현은 비어 있습니다.

QRhi 를 사용하여 렌더링하는 QSGRenderNode 를 구현할 때는, QQuickWindow::rhi()를 통해 QQuickWindow 에서 QRhi 객체를 조회하십시오. 작업을 제출할 QRhiCommandBuffer 를 얻으려면 commandBuffer()를 호출하십시오. 활성 렌더 타깃에 대한 정보를 조회하려면 renderTarget()를 호출하십시오. 자세한 내용은 {Scene Graph - Custom QSGRenderNode} 예제를 참조하십시오.

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

[since 6.5] const QMatrix4x4 *QSGRenderNode::projectionMatrix() const

현재 투영 행렬에 대한 포인터를 반환합니다.

render() 함수에서 이 행렬은 RenderState::projectionMatrix() 함수에서 반환되는 행렬과 동일합니다. 이 게터가 존재하는 이유는 prepare() 함수에서도 투영 행렬을 조회할 수 있는 방법을 제공하기 위함입니다.

최신 그래픽 API나 Qt 고유의 그래픽 추상화 계층을 사용할 때, *projectionMatrix() * *matrix() 를 유니폼 버퍼에 로드하고 싶어 할 가능성이 매우 높습니다. 하지만 이는 prepare() 내에서, 즉 렌더 패스 기록 과정 밖에서 수행되어야 합니다. 이 때문에 두 행렬 모두 prepare() 및 render()에서 QSGRenderNode 를 통해 직접 조회할 수 있습니다.

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

[virtual] QRectF QSGRenderNode::rect() const

render()가 접촉하는 영역에 대한 항목 좌표계의 경계 사각형을 반환합니다. 이 값은 flags()에 BoundedRectRendering 가 포함된 경우에만 사용되며, 그렇지 않은 경우에는 무시됩니다.

BoundedRectRendering 와 함께 사각형을 보고하는 것은 software 백엔드에서 특히 중요합니다. 그렇지 않으면 씬 내에 렌더노드가 존재하는 것만으로도 전체 화면 업데이트가 트리거되어, 모든 부분 업데이트 최적화가 건너뛰어지기 때문입니다.

해당 QQuickItem 의 전체 영역을 덮는 렌더 노드의 경우, 반환 값은 (0, 0, item->width(), item->height())가 됩니다.

flags()도 참조하십시오 .

[virtual] void QSGRenderNode::releaseResources()

이 함수는 해당 노드가 할당한 모든 사용자 정의 그래픽 리소스를 즉시 해제해야 할 때 호출됩니다. 노드가 사용 중인 그래픽 API를 통해 그래픽 리소스(버퍼, 텍스처, 렌더 타겟, 펜스 등)를 직접 할당하지 않는 경우, 이 함수에서 수행할 작업은 없습니다.

모든 사용자 정의 리소스를 해제하지 못하면, 일부 시스템에서 그래픽 장치 손실 시나리오 발생 시 그래픽 시스템의 후속 재초기화가 실패할 수 있으므로 비정상적인 동작이 발생할 수 있습니다.

소멸자와는 달리, render()는 releaseResources() 호출 후에 호출될 때 필요한 모든 리소스를 재초기화할 수 있어야 합니다.

OpenGL의 경우, 소멸자와 이 함수를 호출할 때 모두 씬그래프의 OpenGL 컨텍스트가 현재 컨텍스트로 유지됩니다.

[pure virtual] void QSGRenderNode::render(const QSGRenderNode::RenderState *state)

이 함수는 렌더러에 의해 호출되며, ` QRhi `을 통해 명령을 직접 호출하거나 기본 그래픽 API(OpenGL, Direct3D 등)를 직접 사용하여 이 노드를 렌더링해야 합니다.

실제 불투명도는 inheritedOpacity()을 통해 가져올 수 있습니다.

투영 행렬은 state 를 통해 사용할 수 있으며, 모델-뷰 행렬은 matrix()를 통해 가져올 수 있습니다. 결합된 행렬은 투영 행렬에 모델-뷰 행렬을 곱한 것입니다. 씬 내 항목들의 올바른 중첩 순서는 투영 행렬에 의해 보장됩니다.

제공된 행렬을 사용할 때, 정점 데이터의 좌표계는 일반적인 QQuickItem 규약을 따릅니다. 즉, 왼쪽 상단은 (0, 0)이고, 오른쪽 하단은 해당 QQuickItem 의 width()와 height()에서 1을 뺀 값입니다. 예를 들어, 정점당 두 개의 부동소수점 수(x-y) 좌표 배열을 가정할 때, 아이템의 절반을 덮는 삼각형은 반시계 방향 기준 (width - 1, height - 1), (0, 0), (0, height - 1)로 지정할 수 있습니다.

클립 정보는 함수가 호출되기 전에 계산됩니다. 클리핑을 고려하고자 하는 구현체는 state 에 있는 정보를 바탕으로 시저링(scissoring)이나 스텐실을 설정할 수 있습니다. 스텐실 버퍼에는 필요한 클립 모양이 채워지지만, 스텐실 테스트를 활성화할지는 구현체에 달려 있습니다.

일부 씬그래프 백엔드, 특히 소프트웨어 기반 백엔드는 시저링이나 스텐실을 사용하지 않습니다. 이 경우 클립 영역은 일반적인 ` QRegion`로 제공됩니다.

QRhi 를 사용하여 렌더링하는 QSGRenderNode 를 구현할 때는, QQuickWindow::rhi()를 통해 QQuickWindow 에서 QRhi 객체를 조회해야 합니다. 작업을 제출할 QRhiCommandBuffer 를 얻으려면 commandBuffer()를 호출하십시오. 활성 렌더 타겟에 대한 정보를 조회하려면 renderTarget()를 호출하십시오. 자세한 내용은 {Scene Graph - Custom QSGRenderNode} 예제를 참조하십시오.

Qt 6 및 QRhi 를 기반으로 하는 씬 그래프 렌더러를 사용하는 경우, OpenGL을 사용 중이라 하더라도 이 함수가 호출될 때 활성(OpenGL) 상태에 대해 어떠한 가정도 해서는 안 됩니다. 이 함수가 호출될 때 명령어 목록/버퍼에 바인딩된 파이프라인 및 동적 상태에 대해서도 어떠한 가정도 하지 마십시오.

QRhi 를 직접 사용하는 경우를 포함하여 일부 그래픽 API에서는 prepare()를 추가로 재구현하거나, 또는 QQuickWindow::beforeRendering() 신호에 연결해야 할 수도 있습니다. 이러한 호출/발생은 명령 버퍼에 렌더 패스의 시작을 기록하기 전(Vulkan의 경우 vkCmdBeginRenderPass, Metal의 경우 MTLRenderCommandEncoder를 통해 인코딩을 시작하기 전)에 이루어집니다. 이러한 API를 사용하는 경우, render() 내부에서는 복사 작업을 기록할 수 없습니다. 대신, prepare()에서 해당 작업을 수행하거나, beforeRendering에 연결된 슬롯(DirectConnection 사용 시)에서 수행해야 합니다.

QSGRendererInterface 및 QQuickWindow::rendererInterface()도 참조하십시오 .

[since 6.6] QRhiRenderTarget *QSGRenderNode::renderTarget() const

현재 렌더 타겟을 반환합니다.

이 메서드는 주로 ` prepare()` 및 ` render()` 구현체에서 ` QRhi `를 사용하여 ` QRhiRenderTarget`의 ` renderPassDescriptor ` 또는 ` pixel size`에 접근할 수 있도록 하기 위해 제공됩니다.

QRhiGraphicsPipeline 를 생성하려면(이는 QRhiRenderPassDescriptor 를 제공해야 함을 의미합니다), 렌더 타겟에서 renderPassDescriptor를 조회하십시오. 그러나 사용자 정의 렌더 타겟( QQuickItem )과 렌더 패스( QSGRenderNode)의 수명 주기 동안 렌더 타겟이 변경될 수 있다는 점에 유의하십시오. 예를 들어, 항목(item)이나 그 상위 노드에서 layer.enabled: true 을 동적으로 설정할 때 어떤 일이 발생하는지 고려해 보십시오. 이는 창(window)에 직접 렌더링하는 것이 아니라 텍스처(texture)로 렌더링하도록 트리거하며, 이는 QSGRenderNode 이 그 시점부터 다른 렌더 타겟과 함께 작동하게 됨을 의미합니다. 새로운 렌더 타깃은 픽셀 형식이 다를 수 있으며, 이로 인해 이미 구축된 그래픽 파이프라인이 호환되지 않을 수 있습니다. 이는 다음과 같은 로직을 통해 처리할 수 있습니다:

if (m_pipeline && renderTarget()->renderPassDescriptor()->serializedFormat() != m_renderPassFormat) {
    delete m_pipeline;
    m_pipeline = nullptr;
}
if (!m_pipeline) {
    // Build a new QRhiGraphicsPipeline.
    // ...
    // Store the serialized format for fast and simple comparisons later on.
    m_renderPassFormat = renderTarget()->renderPassDescriptor()->serializedFormat();
}

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

commandBuffer()도 참조하십시오 .