QSGRenderNode Class

멤버 함수 문서

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

렌더 노드를 파괴합니다. 파생 클래스는 여기서 releaseResources()와 유사한 정리를 수행할 것으로 예상됩니다.

로우레벨 그래픽 API가 사용 중인 경우, 시나리오그래프는 시나리오그래프의 노드가 삭제되기 전에 GPU가 시나리오그래프의 그래픽 명령 대기열에 제출된 모든 작업을 완료할 때까지 CPU 측 대기 시간을 갖습니다. 따라서 render() 구현에서 추가 명령 대기열을 사용하지 않는 한 여기서 추가 대기를 발행할 필요가 없습니다.

QRhi 및 QRhiBuffer, QRhiTexture, QRhiGraphicsPipeline 등과 같은 리소스에서는 소멸자를 구현할 필요가 없고 소스 코드를 더 간결하게 만들 수 있는 std::unique_ptr과 같은 스마트 포인터를 사용하는 것이 좋은 방법인 경우가 많습니다. 그러나 releaseResources()를 구현하여 고유_ptrs에 대해 여러 번의 reset() 호출을 수행하는 것이 여전히 중요하다는 점에 유의하세요.

releaseResources()도 참조하세요 .

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

기본 렌더링 API가 OpenGL인 경우 이 함수는 render() 함수에 의해 변경된 그래픽 상태를 나타내는 각 비트가 마스크를 반환해야 합니다:

OpenGL 이외의 API를 사용하는 경우 관련 값은 명령 목록/버퍼에 기록된 동적 상태 변화에 해당하는 값뿐입니다. 예를 들어, D3D11의 경우 RSSetViewports, RSSetScissorRects, OMSetBlendState, OMSetDepthStencilState 또는 Vulkan의 경우 vkCmdSetViewport, vkCmdSetScissor, vkCmdSetBlendConstants, vkCmdSetStencilRef와 같은 명령이 QSGRendererInterface를 통해 쿼리한 시나리오의 명령 리스트에 추가된 경우에만 해당합니다:CommandList 리소스 열거형입니다. 파이프라인 상태 오브젝트에 설정된 상태는 여기에 보고할 필요가 없습니다. 마찬가지로 드로우 호출 관련 설정(파이프라인 상태, 설명자 세트, 버텍스 또는 인덱스 버퍼 바인딩, 루트 서명, 설명자 힙 등)은 항상 시나리오 그래프에서 다시 설정되므로 render()에서 자유롭게 변경할 수 있습니다.

RenderTargetState 는 더 이상 Vulkan과 같은 API에서 지원되지 않습니다. 이것은 본질적으로 render()는 Qt Quick 시나리오 그래프의 기본 명령 버퍼가 렌더패스를 기록하는 동안 호출되므로 대상을 변경하고 다른 렌더패스를 시작할 가능성이 없습니다(적어도 해당 명령 버퍼에서는). 따라서 RenderTargetState 설정된 값을 반환하는 것은 적절하지 않습니다.

이 함수는 렌더러가 호출하므로 이 노드를 렌더링한 후 상태를 재설정할 수 있습니다. 이렇게 하면 이러한 상태를 쿼리하고 복원할 필요가 없으므로 render()의 구현이 더 간단해집니다.

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

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()를 호출합니다. 자세한 내용은 {씬 그래프 - 커스텀 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)

이 함수는 렌더러가 호출하며 현재 사용 중인 그래픽 API(OpenGL, Direct3D 등)에서 직접 호출하는 명령으로 이 노드를 페인팅해야 합니다.

유효 불투명도는 inheritedOpacity()로 검색할 수 있습니다.

투영 행렬은 state 를 통해 사용할 수 있으며 모델 뷰 행렬은 matrix()로 가져올 수 있습니다. 그러면 결합된 행렬은 투영 행렬에 모델 보기 행렬을 곱한 값입니다. 투영 행렬은 씬에서 항목의 올바른 스태킹을 보장합니다.

제공된 행렬을 사용할 때 정점 데이터의 좌표계는 일반적인 QQuickItem 규칙을 따릅니다. 왼쪽 위는 (0, 0), 오른쪽 아래는 QQuickItem 의 너비() 및 높이()에서 1을 뺀 값에 해당합니다. 예를 들어, 버텍스 좌표 레이아웃이 두 개의 실수(x-y)라고 가정할 때 항목의 절반을 차지하는 삼각형은 시계 반대 방향을 사용하여 (너비-1, 높이-1), (0, 0), (0, 높이-1)로 지정할 수 있습니다.

클립 정보는 함수가 호출되기 전에 계산됩니다. 클리핑을 고려하려는 구현은 state 에 있는 정보를 기반으로 시소 또는 스텐실을 설정할 수 있습니다. 스텐실 버퍼는 필요한 클립 모양으로 채워지지만, 스텐실 테스트를 활성화하는 것은 구현에 달려 있습니다.

일부 시나리오 백엔드, 특히 소프트웨어는 가위나 스텐실을 사용하지 않습니다. 이 경우 클립 영역은 일반 QRegion 으로 제공됩니다.

QRhi 을 사용하여 렌더링하는 QSGRenderNode 을 구현할 때는 QQuickWindow::rhi()를 통해 QQuickWindow 에서 QRhi 객체를 쿼리하세요. 작업을 제출할 QRhiCommandBuffer 을 얻으려면 commandBuffer()을 호출합니다. 활성 렌더링 대상에 대한 정보를 쿼리하려면 renderTarget()를 호출합니다. 자세한 내용은 {씬 그래프 - 커스텀 QSGRenderNode} 예제를 참조하십시오.

Qt 6 및 QRhi 기반 씬 그래프 렌더러를 사용하면 이 함수를 호출할 때 OpenGL이 사용 중일 때에도 활성(OpenGL) 상태에 대해 가정하지 않아야 합니다. 이 함수가 호출될 때 명령 목록/버퍼에 바인딩된 파이프라인 및 동적 상태에 대해 아무것도 가정하지 마십시오.

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

QSGRendererInterface 및 QQuickWindow::rendererInterface()도 참조하세요 .

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

현재 렌더링 대상을 반환합니다.

이는 주로 QRhiRenderTarget 의 renderPassDescriptor 또는 pixel size 에 액세스하는 QRhi 을 사용하는 prepare() 및 render() 구현을 활성화하기 위해 제공됩니다.

QRhiRenderPassDescriptor 을 제공해야 하는 QRhiGraphicsPipeline 을 빌드하려면 렌더링 대상에서 renderPassDescriptor를 쿼리하세요. 그러나 렌더 타깃은 사용자 정의 QQuickItem 및 QSGRenderNode 의 수명에 따라 변경될 수 있습니다. 예를 들어 항목 또는 그 조상에 layer.enabled: true 를 동적으로 설정하면 어떻게 되는지 생각해 보세요. 이렇게 하면 창에 직접 렌더링하는 것이 아니라 텍스처로 렌더링하므로 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()도 참조하십시오 .