QSGRenderNode Class

멤버 함수 문서

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

렌더 노드를 파괴합니다. 파생 클래스는 여기서 releaseResources()와 유사한 정리를 수행해야 합니다.

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

releaseResources()도 참조하세요 .

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

이 함수는 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)

이 함수는 렌더러에 의해 호출되며 QRhi 또는 기본 그래픽 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()도 참조하십시오 .