QShader Class
여러 셰이딩 언어로 번역된 셰이더의 여러 버전과 리플렉션 메타데이터가 포함되어 있습니다. 더 보기...
| 헤더: | #include <QShader> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Gui)target_link_libraries(mytarget PRIVATE Qt6::Gui) |
| qmake: | QT += gui |
| 이후: | Qt 6.6 |
- 상속된 멤버를 포함한 모든 멤버 목록
- QShader는 3D 렌더링의 일부입니다.
공용 유형
| struct | NativeShaderInfo |
| struct | SeparateToCombinedImageSamplerMapping |
| NativeResourceBindingMap | |
| SeparateToCombinedImageSamplerMappingList | |
| enum class | SerializedFormatVersion { Latest, Qt_6_5, Qt_6_4 } |
| enum | Source { SpirvShader, GlslShader, HlslShader, DxbcShader, MslShader, …, WgslShader } |
| enum | Stage { VertexStage, TessellationControlStage, TessellationEvaluationStage, GeometryStage, FragmentStage, ComputeStage } |
| enum | Variant { StandardShader, BatchableVertexShader, UInt16IndexedVertexAsComputeShader, UInt32IndexedVertexAsComputeShader, NonIndexedVertexAsComputeShader } |
공용 함수
| QShader() | |
| QShader(const QShader &other) | |
(since 6.7) | QShader(QShader &&other) |
| ~QShader() | |
| QList<QShaderKey> | availableShaders() const |
| QShaderDescription | description() const |
| bool | isValid() const |
| QShader::NativeResourceBindingMap | nativeResourceBindingMap(const QShaderKey &key) const |
| QShader::NativeShaderInfo | nativeShaderInfo(const QShaderKey &key) const |
| void | removeNativeShaderInfo(const QShaderKey &key) |
| void | removeResourceBindingMap(const QShaderKey &key) |
| void | removeSeparateToCombinedImageSamplerMappingList(const QShaderKey &key) |
| void | removeShader(const QShaderKey &key) |
| QShader::SeparateToCombinedImageSamplerMappingList | separateToCombinedImageSamplerMappingList(const QShaderKey &key) const |
| QByteArray | serialized(QShader::SerializedFormatVersion version = SerializedFormatVersion::Latest) const |
| void | setDescription(const QShaderDescription &desc) |
| void | setNativeShaderInfo(const QShaderKey &key, const QShader::NativeShaderInfo &info) |
| void | setResourceBindingMap(const QShaderKey &key, const QShader::NativeResourceBindingMap &map) |
| void | setSeparateToCombinedImageSamplerMappingList(const QShaderKey &key, const QShader::SeparateToCombinedImageSamplerMappingList &list) |
| void | setShader(const QShaderKey &key, const QShaderCode &shader) |
| void | setStage(QShader::Stage stage) |
| QShaderCode | shader(const QShaderKey &key) const |
| QShader::Stage | stage() const |
(since 6.7) void | swap(QShader &other) |
(since 6.7) QShader & | operator=(QShader &&other) |
| QShader & | operator=(const QShader &other) |
정적 공용 멤버
| QShader | fromSerialized(const QByteArray &data) |
관련 비회원
| size_t | qHash(const QShader &key, size_t seed = 0) |
| bool | operator!=(const QShader &lhs, const QShader &rhs) |
| bool | operator==(const QShader &lhs, const QShader &rhs) |
상세 설명
QShader는 그래픽 API에 구애받지 않는 Qt 세계에서 셰이더 코드의 진입점입니다. Qt 5.x의 관례처럼 GLSL 셰이더 소스를 사용하는 대신, Vulkan, Metal, Direct3D 및 OpenGL과 같은 여러 그래픽 API용 백엔드를 갖춘 새로운 그래픽 시스템은 셰이더를 지정해야 할 때마다 QShader를 입력으로 받습니다.
경고: QShader 및 QShaderDescription 을 포함한 Qt GUI 모듈의 QRhi 클래스 제품군은 제한된 호환성을 보장합니다. 이러한 클래스에 대한 소스 또는 바이너리 호환성 보장은 없으므로 API는 애플리케이션이 개발된 Qt 버전에서만 작동하도록 보장됩니다. 그러나 소스와 호환되지 않는 변경은 최소한으로 유지하는 것을 목표로 하며 마이너 릴리스(6.7, 6.8 등)에서만 이루어질 것입니다. 애플리케이션에서 이러한 클래스를 사용하려면 Qt::GuiPrivate (CMake를 사용하는 경우)에 링크하고 헤더에 rhi 접두사(예: #include <rhi/qshader.h>)를 포함하세요.
QShader 인스턴스는 비어 있으므로 기본적으로 유효하지 않습니다. 유용한 인스턴스를 얻으려면 두 가지 일반적인 방법이 있습니다:
- 빌드 시간 또는 그 이전에
qsb명령줄 도구를 사용하여 오프라인으로 콘텐츠를 생성합니다. 그 결과는 애플리케이션과 함께 제공되는 바이너리 파일로, QIODevice::readAll()를 통해 읽은 다음 fromSerialized()를 통해 역직렬화됩니다. 자세한 내용은 QShaderBaker 을 참조하세요. - QShaderBaker 을 통해 런타임에 생성합니다. 이 작업은 비용이 많이 들지만 애플리케이션이 사용자 제공 또는 동적으로 생성된 셰이더 소스 문자열을 사용할 수 있습니다.
Qt 렌더링 하드웨어 인터페이스와 QRhiGraphicsPipeline 와 같은 클래스를 함께 사용하면 그래픽 파이프라인의 특정 단계에서 셰이더를 지정해야 할 때마다 이러한 클래스가 QShader를 사용할 준비가 되어 있으므로 애플리케이션 측에서 추가 조치가 필요하지 않습니다.
또는 애플리케이션이
- QShader에 포함된 셰이딩 언어 버전의 소스 또는 바이트 코드,
- 셰이더의 진입점 이름,
- 셰이더의 입력, 출력 및 균일 블록과 같은 리소스에 대한 설명이 포함된 리플렉션 메타데이터에 액세스할 수 있습니다. 이는 애플리케이션이나 프레임워크가 셰이더가 사용하는 버텍스 속성이나 균일 버퍼의 레이아웃에 대한 사전 지식이 없어 런타임에 셰이더의 입력을 검색해야 할 때 필수적입니다.
QShader는 셰이더에 포함된 다양한 버전과 배리언트를 생성하는 소스로 사용된 셰이딩 언어에 대해 가정하지 않습니다.
QShader는 많은 Qt Core 유형과 유사하게 암시적 공유를 사용하므로 반환되거나 값으로 전달될 수 있습니다. 디태치는 세터를 호출할 때 암시적으로 발생합니다.
참고로, 일반적인 이식 가능한 QRhi 은 모든 백엔드에 적합한 QShader에 최소한 다음이 포함될 것으로 예상합니다. (핵심 프로파일 OpenGL 컨텍스트에 대한 지원은 제외되며, 이를 위해서는 GLSL 150 이상을 추가해야 합니다).
- 벌칸 1.0 이상에 적합한 SPIR-V 1.0 바이트코드
- OpenGL ES 2.0 이상에 적합한 GLSL/ES 100 소스 코드
- OpenGL 2.1 이상에 적합한 GLSL 120 소스 코드
- Direct3D 11/12에 적합한 HLSL 셰이더 모델 5.0 소스 코드 또는 해당 DXBC 바이트코드
- 메탈 셰이딩 언어 1.2 소스 코드 또는 메탈 1.2 이상에 적합한 해당 바이트코드
QShaderBaker 를참조하십시오 .
멤버 유형 문서
[alias] QShader::NativeResourceBindingMap
QMap<int, QPair<int, int>>와 동의어입니다.
리소스 바인딩 모델 QRhi 은 SPIR-V를 기반으로 한다고 가정합니다. 즉, 유니폼 버퍼, 스토리지 버퍼, 결합 이미지 샘플러, 스토리지 이미지가 공통 바인딩 포인트 공간을 공유한다는 의미입니다. QShaderDescription 및 QRhiShaderResourceBinding 의 바인딩 번호는 Vulkan 호환 GLSL 셰이더의 binding 레이아웃 한정자와 일치할 것으로 예상됩니다.
Vulkan 이외의 그래픽 API는 이와 완전히 호환되지 않는 리소스 바인딩 모델을 사용할 수 있습니다. SPIR-V에서 변환된 셰이더 코드의 생성기는 여러 가지 이유로 SPIR-V 바인딩 한정자를 고려하지 않을 수 있습니다. 예를 들어 SPIRV-Cross의 Metal 백엔드가 이에 해당합니다. 또한 자동 암시적 번역이 대부분 가능한 경우에도(예: SPIR-V 바인딩 포인트를 HLSL 리소스 레지스터 인덱스로 사용하는 경우) SPIR-V 바인딩 포인트에 제약을 받지 않고 리소스 바인딩을 할당하면 더 나은 결과를 얻을 수 있습니다.
따라서 QShader 에는 주어진 SPIR-V 바인딩의 기본 바인딩 포인트가 무엇인지 설명하는 추가 맵이 노출될 수 있습니다. 이와 관련된 QRhi 백엔드는 이 맵을 적절하게 자동으로 사용할 것으로 예상됩니다. 결합된 이미지 샘플러는 일부 셰이딩 언어에서 두 개의 기본 리소스(텍스처와 샘플러)에 매핑될 수 있으므로 값은 한 쌍입니다. 이 경우 두 번째 값은 샘플러를 나타냅니다.
참고: 셰이더에 리소스에 대한 활성 바인딩이 없는 경우 네이티브 바인딩은 -1이 될 수 있습니다. (예를 들어 선언된 유니폼 블록이 있지만 셰이더 코드에서 사용되지 않는 경우) 맵은 항상 완전하므로 선언된 모든 유니폼 블록, 스토리지 블록, 이미지 객체 및 결합된 샘플러에 대한 항목이 있지만 셰이더 함수에서 실제로 참조되지 않는 항목의 값은 -1이 됩니다.
[alias] QShader::SeparateToCombinedImageSamplerMappingList
QList<QShader::SeparateToCombinedImageSamplerMapping>의 동의어입니다.
enum class QShader::SerializedFormatVersion
QShader 를 직렬화할 때 원하는 출력 형식을 설명합니다.
serialized()의 version 인수의 기본값은 Latest 입니다. 대부분의 경우 이 값으로 충분합니다. 다른 값을 지정하는 것은 이전 Qt 버전에서 로드할 수 있는 직렬화된 데이터를 생성하려는 의도가 있는 경우에만 필요합니다. 예를 들어 qsb 도구는 --qsbversion 명령줄 인수가 주어질 때 이러한 열거형 값을 사용합니다.
참고: 이전 버전을 타겟팅하면 생성된 에셋에서 특정 기능이 작동하지 않습니다. 이는 지정된 이전 Qt 버전에서 에셋을 사용할 때는 문제가 되지 않는데, 해당 Qt 버전에는 QShader 및 직렬화된 데이터 스트림에서 생성된 추가 데이터에 의존하는 최신 Qt 버전의 최신 기능이 없기 때문이지만 생성된 에셋을 최신 Qt 버전에서 사용할 경우 문제가 될 수 있습니다.
| 상수 | 값 | 설명 |
|---|---|---|
QShader::SerializedFormatVersion::Latest | 0 | 현재 Qt 버전 |
QShader::SerializedFormatVersion::Qt_6_5 | 1 | Qt 6.5 |
QShader::SerializedFormatVersion::Qt_6_4 | 2 | Qt 6.4 |
enum QShader::Source
항목에 포함된 셰이더 코드의 종류를 설명합니다.
| Constant | 값 | 설명 |
|---|---|---|
QShader::SpirvShader | 0 | SPIR-V |
QShader::GlslShader | 1 | GLSL |
QShader::HlslShader | 2 | HLSL |
QShader::DxbcShader | 3 | Direct3D 바이트코드( fxc 에서 컴파일한 HLSL) |
QShader::MslShader | 4 | 메탈 셰이딩 언어 |
QShader::DxilShader | 5 | Direct3D 바이트코드( dxc 에서 컴파일한 HLSL) |
QShader::MetalLibShader | 6 | 미리 컴파일된 메탈 바이트코드 |
QShader::WgslShader | 7 | WGSL |
enum QShader::Stage
셰이더가 적합한 그래픽 파이프라인의 단계를 설명합니다.
| Constant | 값 | 설명 |
|---|---|---|
QShader::VertexStage | 0 | 버텍스 셰이더 |
QShader::TessellationControlStage | 1 | 테셀레이션 제어(헐) 셰이더 |
QShader::TessellationEvaluationStage | 2 | 테셀레이션 평가(도메인) 셰이더 |
QShader::GeometryStage | 3 | 지오메트리 셰이더 |
QShader::FragmentStage | 4 | 프래그먼트(픽셀) 셰이더 |
QShader::ComputeStage | 5 | 계산 셰이더 |
enum QShader::Variant
항목에 포함된 셰이더 코드의 종류를 설명합니다.
| Constant | 값 | 설명 |
|---|---|---|
QShader::StandardShader | 0 | 셰이더 코드의 수정되지 않은 일반 버전입니다. |
QShader::BatchableVertexShader | 1 | Qt Quick 시나리오 배치에 적합하도록 재작성된 버텍스 셰이더입니다. |
QShader::UInt16IndexedVertexAsComputeShader | 2 | 메탈 파이프라인에서 테셀레이션과 함께 인덱스 드로우 호출과 함께 사용하기 위한 버텍스 셰이더로, uint16 인덱스 버퍼에서 인덱스 데이터를 소싱합니다. Metal 테셀레이션 파이프라인을 지원하기 위해 버텍스 셰이더는 드로 콜의 인덱스 버퍼 사용량에 따라 달라질 수 있는 계산 셰이더로 변환되므로(예: 셰이더가 gl_VertexIndex를 사용하는 경우) 세 가지 전용 변형이 필요합니다. |
QShader::UInt32IndexedVertexAsComputeShader | 3 | 메탈 파이프라인에서 테셀레이션과 함께 인덱스 드로우 콜을 사용하여 uint32 인덱스 버퍼에서 인덱스 데이터를 소싱하는 버텍스 셰이더를 사용하기 위한 것입니다. Metal 테셀레이션 파이프라인을 지원하기 위해 버텍스 셰이더는 드로 콜의 인덱스 버퍼 사용량에 따라 달라질 수 있는 계산 셰이더로 변환되므로(예: 셰이더가 gl_VertexIndex를 사용하는 경우) 세 가지 전용 변형이 필요합니다. |
QShader::NonIndexedVertexAsComputeShader | 4 | 인덱스가 없는 드로우 호출과 함께 테셀레이션이 있는 Metal 파이프라인에서 사용하기 위한 버텍스 셰이더입니다. Metal 테셀레이션 파이프라인을 지원하기 위해 버텍스 셰이더는 드로 콜의 인덱스 버퍼 사용량에 따라 달라질 수 있는 계산 셰이더로 변환되므로(예: 셰이더가 gl_VertexIndex를 사용하는 경우) 세 가지 전용 배리언트가 필요합니다. |
멤버 함수 문서
QShader::QShader()
새 비어있는 (따라서 유효하지 않은) QShader 인스턴스를 생성합니다.
QShader::QShader(const QShader &other)
other 의 복사본을 생성합니다.
[noexcept, since 6.7] QShader::QShader(QShader &&other)
Move - other 에서 새 QShader를 생성합니다.
참고: 이동한 개체 other 는 부분적으로 형성된 상태로 배치되며, 유효한 작업은 소멸과 새 값 할당뿐입니다.
이 함수는 Qt 6.7에 도입되었습니다.
[noexcept] QShader::~QShader()
파괴자.
QList<QShaderKey> QShader::availableShaders() const
사용 가능한 셰이더 버전 목록을 반환합니다.
QShaderDescription QShader::description() const
셰이더의 리플렉션 메타데이터를 반환합니다.
setDescription()도 참조하세요 .
[static] QShader QShader::fromSerialized(const QByteArray &data)
주어진 data 에서 새 QShader 인스턴스를 생성합니다.
data 를 성공적으로 역직렬화할 수 없으면 isValid()가 false 를 반환하는 기본 구성 QShader 이 생성됩니다.
serialized()도 참조하세요 .
bool QShader::isValid() const
QShader 에 셰이더 버전이 하나 이상 포함되어 있으면 true를 반환합니다.
QShader::NativeResourceBindingMap QShader::nativeResourceBindingMap(const QShaderKey &key) const
key 에 대한 네이티브 바인딩 맵을 반환합니다. key 에 사용할 수 있는 매핑이 없는 경우(예: key 에 설명된 API 및 셰이딩 언어에 맵이 적용되지 않기 때문) 맵은 비어 있습니다.
QShader::NativeShaderInfo QShader::nativeShaderInfo(const QShaderKey &key) const
key 에 대한 네이티브 셰이더 정보 구조체를 반환하거나 셰이딩 언어 또는 셰이더 단계에 해당 매핑이 적용되지 않아 key 에 사용할 수 있는 데이터가 없는 경우 빈 객체를 반환합니다.
setNativeShaderInfo()도 참조하세요 .
void QShader::removeNativeShaderInfo(const QShaderKey &key)
key 에 대한 네이티브 셰이더 정보를 제거합니다.
void QShader::removeResourceBindingMap(const QShaderKey &key)
key 에 대한 네이티브 리소스 바인딩 맵을 제거합니다.
void QShader::removeSeparateToCombinedImageSamplerMappingList(const QShaderKey &key)
key 에 대한 결합된 이미지 샘플러 매핑 목록을 제거합니다.
void QShader::removeShader(const QShaderKey &key)
주어진 key 에 대한 소스 또는 바이너리 셰이더 코드를 제거합니다. 발견되지 않으면 아무 작업도 수행하지 않습니다.
QShader::SeparateToCombinedImageSamplerMappingList QShader::separateToCombinedImageSamplerMappingList(const QShaderKey &key) const
key 에 대한 결합된 이미지 샘플러 매핑 목록을 반환하거나, 셰이딩 언어에 해당 매핑이 적용되지 않아 key 에 사용할 수 있는 데이터가 없는 경우 빈 목록을 반환합니다.
setSeparateToCombinedImageSamplerMappingList()도 참조하세요 .
QByteArray QShader::serialized(QShader::SerializedFormatVersion version = SerializedFormatVersion::Latest) const
QShader 에 저장된 모든 데이터의 직렬화된 바이너리 버전을 반환하며, 파일이나 기타 I/O 장치에 쓰기에 적합합니다.
기본적으로 최신 직렬화 형식이 사용됩니다. 호환성 Qt 버전으로 직렬화하려면 version 파라미터를 사용합니다. 생성된 데이터 스트림이 해당 Qt 버전 이후에 도입된 기능과 호환되지 않는 대신 이전 Qt 버전과 호환되도록 만들어야 하는 경우에만 다른 값(예: Qt 6.5의 경우 Qt_6_5 )을 사용해야 합니다.
fromSerialized()도 참조하세요 .
void QShader::setDescription(const QShaderDescription &desc)
리플렉션 메타데이터를 desc 로 설정합니다.
description()도 참조하세요 .
void QShader::setNativeShaderInfo(const QShaderKey &key, const QShader::NativeShaderInfo &info)
key 과 연결된 지정된 네이티브 셰이더 info 를 저장합니다.
nativeShaderInfo()도 참조하세요 .
void QShader::setResourceBindingMap(const QShaderKey &key, const QShader::NativeResourceBindingMap &map)
key 과 연결된 지정된 네이티브 리소스 바인딩 map 을 저장합니다.
nativeResourceBindingMap()도 참조하세요 .
void QShader::setSeparateToCombinedImageSamplerMappingList(const QShaderKey &key, const QShader::SeparateToCombinedImageSamplerMappingList &list)
key 과 연결된 지정된 결합 이미지 샘플러 매핑 list 을 저장합니다.
separateToCombinedImageSamplerMappingList()도 참조하세요 .
void QShader::setShader(const QShaderKey &key, const QShaderCode &shader)
key 에 지정된 셰이더 버전에 대한 소스 또는 바이너리 shader 코드를 저장합니다.
shader()도 참조하세요 .
void QShader::setStage(QShader::Stage stage)
파이프라인을 설정합니다 stage.
stage()도 참조하세요 .
QShaderCode QShader::shader(const QShaderKey &key) const
key 에 지정된 셰이더 버전에 대한 소스 또는 바이너리 코드를 반환합니다.
setShader()도 참조하세요 .
QShader::Stage QShader::stage() const
셰이더의 파이프라인 스테이지를 반환합니다.
setStage()도 참조하세요 .
[noexcept, since 6.7] void QShader::swap(QShader &other)
이 셰이더를 other 로 바꿉니다. 이 작업은 매우 빠르며 실패하지 않습니다.
이 함수는 Qt 6.7에 도입되었습니다.
[noexcept, since 6.7] QShader &QShader::operator=(QShader &&other)
이동 - other 을 이 QShader 인스턴스에 할당합니다.
참고: 이동된 객체 other 는 부분적으로 형성된 상태로 배치되며, 유효한 작업은 소멸과 새 값 할당뿐입니다.
이 함수는 Qt 6.7에 도입되었습니다.
QShader &QShader::operator=(const QShader &other)
이 개체에 other 을 할당합니다.
관련 비회원
[noexcept] size_t qHash(const QShader &key, size_t seed = 0)
seed 을 사용하여 key 에 대한 해시값을 반환합니다.
[noexcept] bool operator!=(const QShader &lhs, const QShader &rhs)
두 개의 QShader 객체 lhs 와 rhs 의 값이 같으면 false 를 반환하고, 그렇지 않으면 true 를 반환합니다.
[noexcept] bool operator==(const QShader &lhs, const QShader &rhs)
두 개의 QShader 객체 lhs 와 rhs 가 동일한 경우, 즉 셰이더 소스 또는 바이너리 코드 세트가 일치하는 동일한 스테이지용인 경우 true 를 반환합니다.
© 2025 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.
