QSGRendererInterface Class
씬그래프의 그래픽 API 관련 내부 기능 중 일부에 대한 접근을 제공하는 인터페이스입니다. 더 보기...
| 헤더: | #include <QSGRendererInterface> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Quick) target_link_libraries(mytarget PRIVATE Qt6::Quick) |
| qmake: | QT += quick |
공개 유형
| enum | GraphicsApi { Unknown, Software, OpenVG, OpenGL, Direct3D11, …, Null } |
| enum | RenderMode { RenderMode2D, RenderMode2DNoDepthBuffer, RenderMode3D } |
| enum | Resource { DeviceResource, CommandQueueResource, CommandListResource, PainterResource, RhiResource, …, GraphicsQueueIndexResource } |
| enum | ShaderCompilationType { RuntimeCompilation, OfflineCompilation } |
| flags | ShaderCompilationTypes |
| enum | ShaderSourceType { ShaderSourceString, ShaderSourceFile, ShaderByteCode } |
| flags | ShaderSourceTypes |
| enum | ShaderType { UnknownShadingLanguage, GLSL, HLSL, RhiShader } |
공개 함수
| virtual void * | getResource(QQuickWindow *window, QSGRendererInterface::Resource resource) const |
| virtual void * | getResource(QQuickWindow *window, const char *resource) const |
| virtual QSGRendererInterface::GraphicsApi | graphicsApi() const = 0 |
| virtual QSGRendererInterface::ShaderCompilationTypes | shaderCompilationType() const = 0 |
| virtual QSGRendererInterface::ShaderSourceTypes | shaderSourceType() const = 0 |
| virtual QSGRendererInterface::ShaderType | shaderType() const = 0 |
정적 공용 멤버
| bool | isApiRhiBased(QSGRendererInterface::GraphicsApi api) |
상세 설명
렌더러 인터페이스를 사용하면 씬그래프 내에서 그래픽 API 고유의 기능에 접근할 수 있습니다. 이러한 내부 기능은 일반적으로 노출되지 않습니다. 그러나 예를 들어 QSGRenderNode 를 통해 사용자 정의 렌더링을 통합할 때, 씬그래프에서 사용하는 그래픽 장치(예: Direct3D 또는 Vulkan 장치)와 같은 특정 값을 조회해야 할 필요가 생길 수 있습니다.
QSGRendererInterface의 함수들은 사용 가능 여부가 다양합니다. graphicsApi()이나 shaderType()과 같은 API 및 언어 쿼리는 항상 사용할 수 있습니다. 즉, QQuickWindow 또는 QQuickView 를 생성하기만 하면 되며, 그 직후 QQuickWindow::rendererInterface()을 통해 사용 중인 그래픽 API나 셰이딩 언어를 조회할 수 있습니다. 이를 통해 GraphicsInfo QML 유형과 같은 유틸리티는, 예를 들어 shaderType()에 의존하는 조건부 속성 값이 예상치 못한 값으로 평가되는 일 없이, 가능한 한 빨리 정확한 값을 보고할 수 있습니다.
그러나 getResource()과 같은 엔진별 액세서는 시네그래프가 초기화된 후에만 사용할 수 있습니다. 또한, 이러한 함수를 호출할 수 있는 시기에 대해 백엔드별 제한 사항이 있을 수 있습니다. 성공이 보장되는 유일한 방법은 노드의 렌더링(즉, 다음 프레임에 대한 명령 목록 준비)이 진행 중일 때 해당 함수를 호출하는 것입니다. 실제로는 대개 QSGRenderNode::render()를 의미합니다.
멤버 유형 문서
enum QSGRendererInterface::GraphicsApi
| 상수 | 값 | 설명 |
|---|---|---|
QSGRendererInterface::Unknown | 0 | 알 수 없는 그래픽 API가 사용 중입니다 |
QSGRendererInterface::Software | 1 | Qt Quick 2D 렌더러가 사용 중입니다 |
QSGRendererInterface::OpenVG | 2 | EGL을 통한 OpenVG |
QSGRendererInterface::OpenGL (since Qt 5.14) | 3 | 그래픽 추상화 계층을 통한 OpenGL ES 2.0 이상. |
QSGRendererInterface::Direct3D11 (since Qt 5.14) | 4 | 그래픽 추상화 계층을 통한 Direct3D 11. |
QSGRendererInterface::Direct3D12 (since Qt 6.6) | 8 | 그래픽 추상화 계층을 통한 Direct3D 12. |
QSGRendererInterface::Vulkan (since Qt 5.14) | 5 | 그래픽 추상화 계층을 통한 Vulkan 1.0. |
QSGRendererInterface::Metal (since Qt 5.14) | 6 | 그래픽 추상화 계층을 통한 Metal. |
QSGRendererInterface::Null (since Qt 5.14) | 7 | 그래픽 추상화 계층을 통한 Null(출력 없음). |
enum QSGRendererInterface::RenderMode
| 상수 | 값 | 설명 |
|---|---|---|
QSGRendererInterface::RenderMode2D | 0 | 일반 2D 렌더링 |
QSGRendererInterface::RenderMode2DNoDepthBuffer | 1 | 깊이 버퍼가 비활성화된 일반 2D 렌더링 |
QSGRendererInterface::RenderMode3D | 2 | 씬이 3D 그래프의 일부로 렌더링됨 |
enum QSGRendererInterface::Resource
| 상수 | 값 | 설명 |
|---|---|---|
QSGRendererInterface::DeviceResource | 0 | 해당 리소스는 해당되는 경우 그래픽 장치에 대한 포인터입니다. 예를 들어, VkDevice *, MTLDevice * 또는 ID3D11Device * 등이 있습니다. Vulkan의 경우 반환되는 값은 핸들 자체가 아니라 VkDevice에 대한 포인터라는 점에 유의하십시오. 이는 Vulkan 핸들이 포인터가 아닐 수 있으며, 아키텍처의 포인터 크기와 다른 크기를 사용할 수 있으므로 단순히 void * 로 형변환하거나 그 반대의 형변환을 하는 것은 잘못된 방법이기 때문입니다. |
QSGRendererInterface::CommandQueueResource | 1 | 리소스는 해당되는 경우, 씬그래프에서 사용하는 그래픽 명령 큐에 대한 포인터입니다. 예를 들어, VkQueue * 또는 MTLCommandQueue * 등이 있습니다. Vulkan의 경우 반환되는 값은 핸들 자체가 아니라 VkQueue에 대한 포인터라는 점에 유의하십시오. |
QSGRendererInterface::CommandListResource | 2 | 이 리소스는 해당되는 경우, 씬그래프가 사용하는 명령 목록 또는 버퍼에 대한 포인터입니다. 예를 들어, VkCommandBuffer * 또는 MTLCommandBuffer * 등이 있습니다. 이 객체는 유효 기간이 제한되어 있으며, 씬그래프가 다음 프레임을 준비하는 동안에만 유효합니다. Vulkan의 경우 반환되는 값은 핸들 자체가 아니라 VkCommandBuffer에 대한 포인터라는 점에 유의하십시오. |
QSGRendererInterface::PainterResource | 3 | 이 리소스는 소프트웨어 백엔드로 실행될 때, 씬 그래프가 사용하는 활성 QPainter 에 대한 포인터입니다. |
QSGRendererInterface::RhiResource (since Qt 5.14) | 4 | 해당 리소스는 해당되는 경우, 씬그래프에서 사용하는 QRhi 인스턴스에 대한 포인터입니다. |
QSGRendererInterface::RhiSwapchainResource (since Qt 6.0) | 5 | 이 리소스는 창과 연관된 QRhiSwapchain 인스턴스에 대한 포인터입니다. 창이 QQuickRenderControl 와 함께 사용되는 경우 값은 null입니다. |
QSGRendererInterface::RhiRedirectCommandBuffer (since Qt 6.0) | 6 | 이 리소스는 창 및 해당 QQuickRenderControl 과 연결된 QRhiCommandBuffer 인스턴스에 대한 포인터입니다. 창이 QQuickRenderControl 과 연결되어 있지 않은 경우 값은 null입니다. |
QSGRendererInterface::RhiRedirectRenderTarget (since Qt 6.0) | 7 | 이 리소스는 창 및 해당 QQuickRenderControl 와 연관된 QRhiTextureRenderTarget 인스턴스에 대한 포인터입니다. 창이 QQuickRenderControl 와 연관되어 있지 않을 경우 값은 null입니다. 이 값은 항상 메인 텍스처 렌더 타겟을 반영하며, Qt Quick 장면에 의존하지 않는다는 점에 유의하십시오. 즉, ShaderEffect 또는 QQuickItem 레이어에 의해 생성된 추가적인 텍스처 타겟팅 렌더 패스는 고려되지 않습니다. |
QSGRendererInterface::PhysicalDeviceResource (since Qt 5.14) | 8 | 이 리소스는 해당되는 경우, 씬그래프에서 사용하는 물리적 장치 객체에 대한 포인터입니다. 예를 들어, VkPhysicalDevice * 입니다. Vulkan의 경우 반환된 값은 핸들 자체가 아니라 VkPhysicalDevice에 대한 포인터라는 점에 유의하십시오. |
QSGRendererInterface::OpenGLContextResource (since Qt 5.14) | 9 | 이 리소스는 해당되는 경우, 씬그래프가(렌더 스레드에서) 사용하는 QOpenGLContext 에 대한 포인터입니다. |
QSGRendererInterface::DeviceContextResource (since Qt 5.14) | 10 | 이 리소스는 해당되는 경우, 씬그래프가 사용하는 디바이스 컨텍스트에 대한 포인터입니다. 예를 들어, ` ID3D11DeviceContext *`가 있습니다. |
QSGRendererInterface::CommandEncoderResource (since Qt 5.14) | 11 | 해당 리소스는 해당되는 경우, 씬그래프가 사용하는 현재 활성화된 렌더 명령 인코더 객체에 대한 포인터입니다. 예를 들어, ` MTLRenderCommandEncoder *`입니다. 이 객체는 유효 기간이 제한되어 있으며, 씬그래프가 다음 프레임에 대한 렌더 패스를 기록하는 동안에만 유효합니다. |
QSGRendererInterface::VulkanInstanceResource (since Qt 5.14) | 12 | 이 리소스는 해당되는 경우, 씬그래프가 사용하는 QVulkanInstance 에 대한 포인터입니다. |
QSGRendererInterface::RenderPassResource (since Qt 5.14) | 13 | 이 리소스는 씬그래프가 사용하는 메인 렌더 패스에 대한 포인터로, 색상 및 깊이/스텐실 어태치먼트와 그 사용 방법을 설명합니다. 예를 들어, VkRenderPass * 등이 있습니다. 이 값은 항상 메인 렌더 타깃(화면상의 창이나 QQuickRenderControl 가 리디렉션하는 텍스처)을 반영하며, Qt Quick 장면에 의존하지 않는다는 점에 유의하십시오. 즉, ShaderEffect 또는 QQuickItem 레이어에 의해 생성된 추가적인 텍스처 타겟팅 렌더 패스는 고려되지 않습니다. |
QSGRendererInterface::RedirectPaintDevice (since Qt 6.4) | 14 | 이 리소스는 창 및 해당 QQuickRenderControl 과 연관된 QPaintDevice 인스턴스에 대한 포인터입니다. 창이 QQuickRenderControl 과 연관되어 있지 않은 경우 이 값은 null입니다. |
QSGRendererInterface::GraphicsQueueFamilyIndexResource (since Qt 6.6) | 15 | 이 리소스는 해당되는 경우, 씬그래프가 사용하는 그래픽 큐 패밀리 인덱스에 대한 포인터입니다. Vulkan의 경우, 이는 uint32_t 인덱스 값에 대한 포인터입니다. |
QSGRendererInterface::GraphicsQueueIndexResource (since Qt 6.6) | 16 | 이 리소스는 해당되는 경우, 씬그래프가 사용하는 그래픽 큐 인덱스(uint32_t)에 대한 포인터입니다. Vulkan의 경우, 이는 uint32_t 인덱스 값에 대한 포인터이며, 실제로는 CommandQueueResource 에 대해 보고된 VkQueue의 인덱스입니다. |
enum QSGRendererInterface::ShaderCompilationType
flags QSGRendererInterface::ShaderCompilationTypes
| 상수 | 값 | 설명 |
|---|---|---|
QSGRendererInterface::RuntimeCompilation | 0x01 | 셰이더 소스 코드의 런타임 컴파일이 지원됩니다 |
QSGRendererInterface::OfflineCompilation | 0x02 | 사전 컴파일된 바이트코드 지원 |
ShaderCompilationTypes 유형은 QFlags<ShaderCompilationType>에 대한 typedef입니다. 이 유형은 ShaderCompilationType 값들의 OR 조합을 저장합니다.
enum QSGRendererInterface::ShaderSourceType
flags QSGRendererInterface::ShaderSourceTypes
| 상수 | 값 | 설명 |
|---|---|---|
QSGRendererInterface::ShaderSourceString | 0x01 | 셰이더 소스 코드는 다음의 해당 속성에 문자열로 지정할 수 있습니다. ShaderEffect |
QSGRendererInterface::ShaderSourceFile | 0x02 | 셰이더 소스 코드가 포함된 로컬 또는 리소스 파일이 지원됩니다 |
QSGRendererInterface::ShaderByteCode | 0x04 | 셰이더 바이트코드가 포함된 로컬 또는 리소스 파일이 지원됩니다 |
ShaderSourceTypes 유형은 QFlags<ShaderSourceType>에 대한 typedef입니다. 이 유형은 ShaderSourceType 값들의 OR 조합을 저장합니다.
enum QSGRendererInterface::ShaderType
| 상수 | 값 | 설명 |
|---|---|---|
QSGRendererInterface::UnknownShadingLanguage | 0 | 연관된 윈도우 및 씬그래프가 없어 아직 알 수 없음 |
QSGRendererInterface::GLSL | 1 | GLSL 또는 GLSL ES |
QSGRendererInterface::HLSL | 2 | HLSL |
QSGRendererInterface::RhiShader (since Qt 5.14) | 3 | 여러 대상 언어 및 중간 형식에 대한 셰이더 변형이 포함된 ` QShader ` 인스턴스를 사용합니다. |
멤버 함수 문서
[virtual] void *QSGRendererInterface::getResource(QQuickWindow *window, QSGRendererInterface::Resource resource) const
window 에 있는 그래픽 리소스 resource 를 조회합니다. 해당 리소스가 지원되지 않거나 사용할 수 없는 경우 null을 반환합니다.
성공 시, 반환되는 포인터는 인터페이스에 대한 직접 포인터이거나, 먼저 역참조해야 하는 불투명 핸들(예: VkDevice dev = *static_cast<VkDevice *>(result))에 대한 포인터입니다. 이러한 핸들은 포인터와 크기가 다를 수 있으므로 후자의 방식이 필요합니다.
참고: 반환된 포인터의소유권은 호출자에게 절대 이전되지 않습니다.
참고: 이 함수는 렌더링 스레드에서만 호출해야 합니다.
[virtual] void *QSGRendererInterface::getResource(QQuickWindow *window, const char *resource) const
그래픽 리소스에 대한 정보를 조회합니다. ` resource `는 백엔드별 키입니다. 이를 통해 `Resource` 열거형에 나열되지 않은 향후 추가될 리소스도 지원할 수 있습니다.
참고: 반환된 포인터의소유권은 호출자에게 절대 양도되지 않습니다.
참고: 이 함수는 렌더링 스레드에서만 호출해야 합니다.
[pure virtual] QSGRendererInterface::GraphicsApi QSGRendererInterface::graphicsApi() const
Qt Quick 의 씬그래프에서 사용 중인 그래픽 API를 반환합니다.
참고: 이 함수는 어떤 스레드에서나 호출할 수 있습니다.
[static] bool QSGRendererInterface::isApiRhiBased(QSGRendererInterface::GraphicsApi api)
api 가 네이티브 그래픽 API를 직접 호출하는 대신 그래픽 추상화 계층(QRhi)을 기반으로 하는 경우 true를 반환합니다.
참고: 이 함수는 어떤 스레드에서든 호출할 수 있습니다.
[pure virtual] QSGRendererInterface::ShaderCompilationTypes QSGRendererInterface::shaderCompilationType() const
애플리케이션이 사용 중인 Qt Quick 백엔드에서 지원하는 셰이더 컴파일 방식에 대한 비트 마스크를 반환합니다.
참고: 이 함수는 어떤 스레드에서든 호출할 수 있습니다.
QtQuick::GraphicsInfo도 참조하십시오 .
[pure virtual] QSGRendererInterface::ShaderSourceTypes QSGRendererInterface::shaderSourceType() const
ShaderEffect 항목에서 셰이더 소스를 제공하는 지원되는 방식에 대한 비트 마스크를 반환합니다.
참고: 이 함수는 어떤 스레드에서나 호출할 수 있습니다.
QtQuick::GraphicsInfo도 참조하십시오 .
[pure virtual] QSGRendererInterface::ShaderType QSGRendererInterface::shaderType() const
애플리케이션이 사용 중인 Qt Quick 백엔드에서 지원하는 셰이딩 언어를 반환합니다.
참고: 이 함수는 어떤 스레드에서나 호출할 수 있습니다.
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.
