本页内容

Qt3DRender::QShaderProgram Class

class Qt3DRender::QShaderProgram

封装了一个着色器程序。更多...

头文件: #include <qshaderprogram.h>
CMake: find_package(Qt6 REQUIRED COMPONENTS 3drender)
target_link_libraries(mytarget PRIVATE Qt6::3drender)
qmake: QT += 3drender
在 QML 中: ShaderProgram
继承自: Qt3DCore::QNode
状态: 已弃用

该类已弃用。我们强烈建议不要在新代码中使用它。

公共类型

enum Format { GLSL, SPIRV }
enum ShaderType { Vertex, Fragment, TessellationControl, TessellationEvaluation, Geometry, Compute }
enum Status { NotReady, Ready, Error }

属性

公共函数

QByteArray computeShaderCode() const
Qt3DRender::QShaderProgram::Format format() const
QByteArray fragmentShaderCode() const
QByteArray geometryShaderCode() const
QString log() const
void setFormat(Qt3DRender::QShaderProgram::Format format)
void setShaderCode(Qt3DRender::QShaderProgram::ShaderType type, const QByteArray &shaderCode)
QByteArray shaderCode(Qt3DRender::QShaderProgram::ShaderType type) const
Qt3DRender::QShaderProgram::Status status() const
QByteArray tessellationControlShaderCode() const
QByteArray tessellationEvaluationShaderCode() const
QByteArray vertexShaderCode() const

公共槽位

void setComputeShaderCode(const QByteArray &computeShaderCode)
void setFragmentShaderCode(const QByteArray &fragmentShaderCode)
void setGeometryShaderCode(const QByteArray &geometryShaderCode)
void setTessellationControlShaderCode(const QByteArray &tessellationControlShaderCode)
void setTessellationEvaluationShaderCode(const QByteArray &tessellationEvaluationShaderCode)
void setVertexShaderCode(const QByteArray &vertexShaderCode)

信号

void computeShaderCodeChanged(const QByteArray &computeShaderCode)
void formatChanged(Qt3DRender::QShaderProgram::Format format)
void fragmentShaderCodeChanged(const QByteArray &fragmentShaderCode)
void geometryShaderCodeChanged(const QByteArray &geometryShaderCode)
void logChanged(const QString &log)
void statusChanged(Qt3DRender::QShaderProgram::Status status)
void tessellationControlShaderCodeChanged(const QByteArray &tessellationControlShaderCode)
void tessellationEvaluationShaderCodeChanged(const QByteArray &tessellationEvaluationShaderCode)
void vertexShaderCodeChanged(const QByteArray &vertexShaderCode)

静态公共成员

QByteArray loadSource(const QUrl &sourceUrl)

详细说明

一个着色器程序由几个不同的着色器组成,例如顶点着色器和片段着色器。

如果 Qt3D 在着色器内省阶段遇到了一组默认统一变量,它会自动填充这些变量。

默认统一变量关联的 Qt3D 参数名称GLSL 声明
ModelMatrixmodelMatrixuniform mat4 modelMatrix;
视图矩阵viewMatrixuniform mat4 视图矩阵;
投影矩阵投影矩阵uniform mat4 投影矩阵;
模型视图矩阵modelViewuniform mat4 模型视图矩阵;
视投影矩阵视图投影矩阵uniform mat4 视图投影矩阵;
模型视图投影矩阵modelViewProjection
mvp
uniform mat4 modelViewProjection;
uniform mat4 mvp;
模型矩阵逆逆模型矩阵uniform mat4 逆模型矩阵;
视图矩阵逆矩阵视图矩阵逆矩阵uniform mat4 逆视图矩阵;
投影矩阵逆逆投影矩阵uniform mat4 逆投影矩阵;
模型视图矩阵逆矩阵逆模型视图矩阵uniform mat4 逆模型视图矩阵;
视图投影矩阵逆矩阵逆视图投影矩阵uniform mat4 逆视图投影矩阵;
模型视图投影逆矩阵逆模型视图投影矩阵uniform mat4 模型视图投影逆矩阵;
模型法线矩阵模型法线矩阵uniform mat3 模型法线矩阵;
模型视图法线矩阵模型视图法向量uniform mat3 模型视图法向量;
视口矩阵视口矩阵uniform mat4 视口矩阵;
视口矩阵逆矩阵逆视口矩阵uniform mat4 视口矩阵逆;
AspectRatio
(曲面宽度 / 曲面高度)
aspectRatioxml-ph-0000@deepl.internal(曲面宽度 / 曲面高度)uniform float aspectRatio;
曝光曝光uniform float 曝光量;
伽马伽马均匀浮点伽马;
时间
(单位:纳秒)
timeuniform float time;
EyePositioneyePositionuniform vec3 视点位置;
SkinningPaletteskinningPalette[0]const int maxJoints = 100;
uniform mat4 skinningPalette[maxJoints];

RHI 支持

在编写用于Qt 3D RHI 后端的 GLSL 450 着色器代码时,默认统一变量将作为 2 个统一缓冲区对象提供。

这些统一变量的绑定位置设置为:RenderView 统一变量绑定在 0,Command 统一变量绑定在 1。

#version 450 core

layout(location = 0) in vec3 vertexPosition;

layout(std140, binding = 0) uniform qt3d_render_view_uniforms {
  mat4 viewMatrix;
  mat4 projectionMatrix;
  mat4 uncorrectedProjectionMatrix;
  mat4 clipCorrectionMatrix;
  mat4 viewProjectionMatrix;
  mat4 inverseViewMatrix;
  mat4 inverseProjectionMatrix;
  mat4 inverseViewProjectionMatrix;
  mat4 viewportMatrix;
  mat4 inverseViewportMatrix;
  vec4 textureTransformMatrix;
  vec3 eyePosition;
  float aspectRatio;
  float gamma;
  float exposure;
  float time;
  float yUpInNDC;
  float yUpInFBO;
};

layout(std140, binding = 1) uniform qt3d_command_uniforms {
  mat4 modelMatrix;
  mat4 inverseModelMatrix;
  mat4 modelViewMatrix;
  mat3 modelNormalMatrix;
  mat4 inverseModelViewMatrix;
  mat4 modelViewProjection;
  mat4 inverseModelViewProjectionMatrix;
};

void main()
{
    gl_Position = (projectionMatrix * viewMatrix * modelMatrix * vertexPosition);
}

对于用户定义的uniform缓冲区对象,请使用从2开始的绑定,或使用auto让Qt 3D 自动计算绑定。请确保在不同的着色器阶段之间保持一致。

#version 450 core

layout(std140, binding = auto) uniform my_uniforms {
  vec4 myColor;
};

layout(location=0) out vec4 fragColor;

void main()
{
    fragColor = myColor;
}

向统一变量提供值时,操作方式保持不变。

对于上面的示例,可以这样设置 myColor:

QParameter *parameter = new QParameter();
parameter->setName("myColor");
parameter->setValue(QVariant::fromValue(QColor(Qt::blue)));

纹理仍需定义为独立的uniform。

#version 450 core

layout(binding=0) uniform sampler2D source;

layout(location=0) out vec4 fragColor;

void main()
{
    fragColor = texture(source, vec2(0.5, 0.5));
}

成员类型文档

enum QShaderProgram::Format

此枚举用于标识所用着色器代码的格式。

常量值描述
Qt3DRender::QShaderProgram::GLSL0OpenGL
Qt3DRender::QShaderProgram::SPIRV1Vulkan、OpenGL 5

enum QShaderProgram::ShaderType

此枚举用于标识所用着色器的类型。

常量值描述
Qt3DRender::QShaderProgram::Vertex0顶点着色器
Qt3DRender::QShaderProgram::Fragment1片段着色器
Qt3DRender::QShaderProgram::TessellationControl2曲面细分控制着色器
Qt3DRender::QShaderProgram::TessellationEvaluation3曲面细分评估着色器
Qt3DRender::QShaderProgram::Geometry4几何着色器
Qt3DRender::QShaderProgram::Compute5计算着色器

enum QShaderProgram::Status

此枚举用于标识所用着色器的状态。

常量值描述
Qt3DRender::QShaderProgram::NotReady0着色器尚未编译和链接
Qt3DRender::QShaderProgram::Ready1着色器已成功编译
Qt3DRender::QShaderProgram::Error2在编译着色器时发生错误

属性文档

computeShaderCode : QByteArray

存储该着色器程序所使用的计算着色器代码。

访问函数:

QByteArray computeShaderCode() const
void setComputeShaderCode(const QByteArray &computeShaderCode)

通知信号:

void computeShaderCodeChanged(const QByteArray &computeShaderCode)

format : Format

保存 ShaderProgram 中提供的代码格式。默认值为 ShaderProgram.GLSL

访问函数:

Qt3DRender::QShaderProgram::Format format() const
void setFormat(Qt3DRender::QShaderProgram::Format format)

通知器信号:

void formatChanged(Qt3DRender::QShaderProgram::Format format)

fragmentShaderCode : QByteArray

存储此着色器程序所使用的片段着色器代码。

访问函数:

QByteArray fragmentShaderCode() const
void setFragmentShaderCode(const QByteArray &fragmentShaderCode)

通知器信号:

void fragmentShaderCodeChanged(const QByteArray &fragmentShaderCode)

geometryShaderCode : QByteArray

存储该着色器程序所使用的几何着色器代码。

访问函数:

QByteArray geometryShaderCode() const
void setGeometryShaderCode(const QByteArray &geometryShaderCode)

通知器信号:

void geometryShaderCodeChanged(const QByteArray &geometryShaderCode)

[read-only] log : QString

保存当前着色器程序的日志。这有助于诊断着色器程序的编译失败问题。

访问函数:

QString log() const

通知器信号:

void logChanged(const QString &log)

[read-only] status : Status

保存当前着色器程序的状态。

访问函数:

Qt3DRender::QShaderProgram::Status status() const

通知器信号:

void statusChanged(Qt3DRender::QShaderProgram::Status status)

tessellationControlShaderCode : QByteArray

包含该着色器程序所使用的镶嵌控制着色器代码。

访问函数:

QByteArray tessellationControlShaderCode() const
void setTessellationControlShaderCode(const QByteArray &tessellationControlShaderCode)

通知器信号:

void tessellationControlShaderCodeChanged(const QByteArray &tessellationControlShaderCode)

tessellationEvaluationShaderCode : QByteArray

存储该着色器程序所使用的镶嵌计算着色器代码。

访问函数:

QByteArray tessellationEvaluationShaderCode() const
void setTessellationEvaluationShaderCode(const QByteArray &tessellationEvaluationShaderCode)

通知器信号:

void tessellationEvaluationShaderCodeChanged(const QByteArray &tessellationEvaluationShaderCode)

vertexShaderCode : QByteArray

存储该着色器程序所使用的顶点着色器代码。

访问函数:

QByteArray vertexShaderCode() const
void setVertexShaderCode(const QByteArray &vertexShaderCode)

通知信号:

void vertexShaderCodeChanged(const QByteArray &vertexShaderCode)

成员函数文档

[static invokable] QByteArray QShaderProgram::loadSource(const QUrl &sourceUrl)

返回从sourceUrl 加载的着色器代码。

注意:此 函数可通过元对象系统以及从 QML 中调用。请参阅Q_INVOKABLE 。

void QShaderProgram::setShaderCode(Qt3DRender::QShaderProgram::ShaderType type, const QByteArray &shaderCode)

将着色器中type 的着色器代码设置为shaderCode 。

另请参阅 shaderCode()。

QByteArray QShaderProgram::shaderCode(Qt3DRender::QShaderProgram::ShaderType type) const

返回type 的着色器代码。

另请参阅 setShaderCode()。

Qt3DRender::QShaderProgram::Status QShaderProgram::status() const

返回当前着色器程序的状态。

注意: 此为 status 属性的获取 函数。

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