이 페이지에서

QShader Class

여러 셰이딩 언어로 변환된 셰이더의 여러 버전이 리플렉션 메타데이터와 함께 포함되어 있습니다. 더 보기...

헤더: #include <qshader.h>
CMake: find_package(Qt6 REQUIRED COMPONENTS Gui)
target_link_libraries(mytarget PRIVATE Qt6::Gui)
qmake: QT += gui
다음부터: Qt 6.6부터

공개 유형

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, HdrCapableFragmentShader }

공개 함수

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 등)에서만 이루어질 예정입니다. 애플리케이션에서 이러한 클래스를 사용하려면, CMake를 사용하는 경우 Qt::GuiPrivate 에 링크하고, rhi 접두사가 붙은 헤더 파일(예: #include <rhi/qshader.h>)을 포함시켜야 합니다.

QShader 인스턴스는 기본적으로 비어 있으므로 유효하지 않습니다. 유효한 인스턴스를 얻으려면 다음 두 가지 일반적인 방법이 있습니다.

  • qsb 명령줄 도구를 사용하여 빌드 시점이나 그 이전에 오프라인으로 내용을 생성합니다. 그 결과로 생성된 바이너리 파일은 애플리케이션과 함께 배포되며, QIODevice::readAll()를 통해 읽은 후 fromSerialized()를 통해 역직렬화됩니다. 자세한 내용은 QShaderBaker 를 참조하십시오.
  • QShaderBaker 를 통해 런타임에 생성합니다. 이 작업은 비용이 많이 들지만, 애플리케이션이 사용자가 제공하거나 동적으로 생성된 셰이더 소스 문자열을 사용할 수 있게 해줍니다.

Qt 렌더링 하드웨어 인터페이스 및 QRhiGraphicsPipeline 과 같은 관련 클래스와 함께 사용할 경우, 그래픽 파이프라인의 특정 단계에 셰이더를 지정해야 할 때마다 해당 클래스가 QShader를 처리할 준비가 되어 있으므로 애플리케이션 측에서 별도의 조치가 필요하지 않습니다.

또는 애플리케이션은

  • QShader에 포함된 모든 셰이딩 언어 버전의 소스 또는 바이트 코드에 접근할 수 있으며,
  • 셰이더의 엔트리 포인트 이름,
  • 셰이더의 입력, 출력 및 유니폼 블록과 같은 리소스에 대한 설명이 포함된 리플렉션 메타데이터에 접근할 수 있습니다. 이는 애플리케이션이나 프레임워크가 셰이더가 사용하는 정점 속성이나 유니폼 버퍼의 레이아웃에 대한 사전 지식이 없어 런타임에 셰이더의 입력을 파악해야 할 때 필수적입니다.

QShader는 그 안에 포함된 다양한 버전과 변형을 생성하는 데 소스로 사용된 셰이딩 언어에 대해 어떠한 가정도 하지 않습니다.

QShader는 많은 Qt Core 유형과 유사하게 암시적 공유를 사용하므로, 값으로 반환되거나 전달될 수 있습니다. 세터 호출 시 암시적으로 분리(detach)가 발생합니다.

참고로, 일반적인 이식 가능한 QRhi 는 모든 백엔드에 적합한 QShader가 최소한 다음을 포함할 것으로 기대합니다. (여기에는 코어 프로파일 OpenGL 컨텍스트에 대한 지원이 제외되며, 이를 위해서는 GLSL 150 이상을 추가해야 합니다)

  • Vulkan 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 바이트코드
  • Metal 1.2 이상에 적합한 Metal Shading Language 1.2 소스 코드 또는 해당 바이트코드

QShaderBaker도 참조하십시오 .

멤버 유형 설명서

[alias] QShader::NativeResourceBindingMap

QMap<int, std::pair<int, int>>의 동의어입니다.

QRhi 가 가정하는 리소스 바인딩 모델은 SPIR-V를 기반으로 합니다. 즉, 유니폼 버퍼, 스토리지 버퍼, 결합된 이미지 샘플러 및 스토리지 이미지는 공통의 바인딩 포인트 공간을 공유합니다. QShaderDescription 및 QRhiShaderResourceBinding 의 바인딩 번호는 Vulkan 호환 GLSL 셰이더의 binding 레이아웃 한정자와 일치해야 합니다.

Vulkan 이외의 그래픽 API는 이와 완전히 호환되지 않는 리소스 바인딩 모델을 사용할 수 있습니다. SPIR-V에서 변환된 셰이더 코드 생성기는 여러 가지 이유로 SPIR-V 바인딩 한정자를 고려하지 않을 수 있습니다. 예를 들어, SPIRV-Cross의 Metal 백엔드가 바로 이러한 경우입니다. 또한, 자동적이고 암시적인 변환이 대부분 가능한 경우(예: SPIR-V 바인딩 포인트를 HLSL 리소스 레지스터 인덱스로 사용하는 경우)라 하더라도, SPIR-V 바인딩 포인트의 제약 없이 리소스 바인딩을 할당하는 것이 더 나은 결과를 가져올 수 있습니다.

따라서 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::Latest0현재 Qt 버전
QShader::SerializedFormatVersion::Qt_6_51Qt 6.5
QShader::SerializedFormatVersion::Qt_6_42Qt 6.4

enum QShader::Source

참가작에 어떤 종류의 셰이더 코드가 포함되어 있는지 설명합니다.

상수값설명
QShader::SpirvShader0SPIR-V
QShader::GlslShader1GLSL
QShader::HlslShader2HLSL
QShader::DxbcShader3Direct3D 바이트코드 ( fxc 로 컴파일된 HLSL)
QShader::MslShader4Metal 셰이딩 언어
QShader::DxilShader5Direct3D 바이트코드 ( dxc 에 의해 컴파일된 HLSL)
QShader::MetalLibShader6사전 컴파일된 Metal 바이트코드
QShader::WgslShader7WGSL

enum QShader::Stage

셰이더가 적용 가능한 그래픽 파이프라인의 단계를 설명합니다.

상수값설명
QShader::VertexStage0버텍스 셰이더
QShader::TessellationControlStage1테셀레이션 제어(헐) 셰이더
QShader::TessellationEvaluationStage2테셀레이션 평가(도메인) 셰이더
QShader::GeometryStage3지오메트리 셰이더
QShader::FragmentStage4프래그먼트(픽셀) 셰이더
QShader::ComputeStage5컴퓨트 셰이더

enum QShader::Variant

참가작에 어떤 종류의 셰이더 코드가 포함되어 있는지 설명합니다.

상수값설명
QShader::StandardShader0수정되지 않은 기본 버전의 셰이더 코드입니다.
QShader::BatchableVertexShader1Qt Quick 시네그래프 배치 처리에 적합하도록 재작성된 버텍스 셰이더입니다.
QShader::UInt16IndexedVertexAsComputeShader2uint16 인덱스 버퍼에서 인덱스 데이터를 가져오는 인덱스 드로우 호출과 함께 테셀레이션이 포함된 Metal 파이프라인에서 사용하도록 설계된 버텍스 셰이더입니다. Metal 테셀레이션 파이프라인을 지원하기 위해, 버텍스 셰이더는 드로우 콜에서 인덱스 버퍼 사용에 의존할 수 있는 컴퓨트 셰이더로 변환됩니다(예: 셰이더가 gl_VertexIndex를 사용하는 경우). 따라서 세 가지 전용 변형이 필요합니다.
QShader::UInt32IndexedVertexAsComputeShader3uint32 인덱스 버퍼에서 인덱스 데이터를 가져오는 인덱스 드로우 콜과 함께 테셀레이션이 포함된 Metal 파이프라인에서 사용하도록 설계된 버텍스 셰이더입니다. Metal 테셀레이션 파이프라인을 지원하기 위해, 버텍스 셰이더는 드로우 콜 내 인덱스 버퍼 사용 여부에 따라 달라질 수 있는 컴퓨트 셰이더로 변환됩니다(예: 셰이더가 gl_VertexIndex를 사용하는 경우). 따라서 세 가지 전용 변형이 필요합니다.
QShader::NonIndexedVertexAsComputeShader4테셀레이션이 포함된 Metal 파이프라인에서 인덱스가 없는 드로우 콜과 함께 사용하도록 설계된 버텍스 셰이더입니다. Metal 테셀레이션 파이프라인을 지원하기 위해, 버텍스 셰이더는 드로우 콜 내 인덱스 버퍼 사용에 의존할 수 있는 컴퓨트 셰이더로 변환됩니다(예: 셰이더가 gl_VertexIndex를 사용하는 경우). 따라서 세 가지 전용 변형이 필요합니다.
QShader::HdrCapableFragmentShader (since Qt 6.10)5Qt Quick 시나그래프에서 고동적 범위(HDR) 렌더링을 지원하도록 재작성된 프래그먼트 셰이더입니다.

멤버 함수 문서

QShader::QShader()

새롭고 빈(따라서 유효하지 않은) QShader 인스턴스를 생성합니다.

QShader::QShader(const QShader &other)

other 의 복사본을 생성합니다.

[noexcept, since 6.7] QShader::QShader(QShader &&other)

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 를 성공적으로 역직렬화할 수 없는 경우, 결과는 기본 생성된 QShader 가 되며, 이 객체에 대해 isValid()를 호출하면 false 가 반환됩니다.

경고: 파일 시스템에 있는 ` .qsb ` 파일을 포함한셰이더 패키지는 신뢰할 수 있는 콘텐츠로 간주됩니다. 애플리케이션 개발자는 애플리케이션의 일부가 아닌 사용자가 제공한 콘텐츠의 로딩을 허용하기 전에 잠재적인 영향을 신중하게 고려해야 합니다.

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)

lhs 와 rhs 라는 두 개의 ` QShader ` 객체가 동일할 경우, 즉 동일한 스테이지에 속하며 셰이더 소스 코드 또는 바이너리 코드 세트가 일치할 경우 ` true `를 반환합니다.

© 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.