QShaderProgram Class

class Qt3DRender::QShaderProgram

Encapsulates a Shader Program. More...

Header: #include <QShaderProgram>
CMake: find_package(Qt6 REQUIRED COMPONENTS 3drender)
target_link_libraries(mytarget PRIVATE Qt6::3drender)
qmake: QT += 3drender
Instantiated By: ShaderProgram
Inherits: Qt3DCore::QNode

Public Types

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

Properties

Public Functions

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

Public Slots

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)

Signals

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)

Static Public Members

QByteArray loadSource(const QUrl &sourceUrl)

Detailed Description

A shader program consists of several different shaders, such as vertex and fragment shaders.

Qt3D will automatically populate a set of default uniforms if they are encountered during the shader instrospection phase.

Default UniformAssociated Qt3D Parameter nameGLSL declaration
ModelMatrixmodelMatrixuniform mat4 modelMatrix;
ViewMatrixviewMatrixuniform mat4 viewMatrix;
ProjectionMatrixprojectionMatrixuniform mat4 projectionMatrix;
ModelViewMatrixmodelViewuniform mat4 modelView;
ViewProjectionMatrixviewProjectionMatrixuniform mat4 viewProjectionMatrix;
ModelViewProjectionMatrixmodelViewProjection
mvp
uniform mat4 modelViewProjection;
uniform mat4 mvp;
InverseModelMatrixinverseModelMatrixuniform mat4 inverseModelMatrix;
InverseViewMatrixinverseViewMatrixuniform mat4 inverseViewMatrix;
InverseProjectionMatrixinverseProjectionMatrixuniform mat4 inverseProjectionMatrix;
InverseModelViewMatrixinverseModelViewuniform mat4 inverseModelView;
InverseViewProjectionMatrixinverseViewProjectionMatrixuniform mat4 inverseViewProjectionMatrix;
InverseModelViewProjectionMatrixinverseModelViewProjectionuniform mat4 inverseModelViewProjection;
ModelNormalMatrixmodelNormalMatrixuniform mat3 modelNormalMatrix;
ModelViewNormalMatrixmodelViewNormaluniform mat3 modelViewNormal;
ViewportMatrixviewportMatrixuniform mat4 viewportMatrix;
InverseViewportMatrixinverseViewportMatrixuniform mat4 inverseViewportMatrix;
AspectRatio
(surface width / surface height)
aspectRatiouniform float aspectRatio;
Exposureexposureuniform float exposure;
Gammagammauniform float gamma;
Time
(in nano seconds)
timeuniform float time;
EyePositioneyePositionuniform vec3 eyePosition;
SkinningPaletteskinningPalette[0]const int maxJoints = 100;
uniform mat4 skinningPalette[maxJoints];

RHI Support

When writing GLSL 450 shader code to use with Qt 3D's RHI backend, the default uniforms will be provided as 2 uniform buffer objects.

The binding locations for these is set to bindings 0 for RenderView uniforms and 1 for Command uniforms.

 #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);
 }

For user defined uniform buffer object, use binding starting at 2 or auto to let Qt 3D work out the binding automatically. Make sure to remain consistent between the different shader stages.

 #version 450 core

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

 layout(location=0) out vec4 fragColor;

 void main()
 {
     fragColor = myColor;
 }

There is no change involved when it comes to feeding values to uniforms.

For the above example, setting myColor could be done with:

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

Textures still have to be defined as standalone uniforms.

 #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));
 }

Member Type Documentation

enum QShaderProgram::Format

This enum identifies the format of the shader code used.

ConstantValueDescription
Qt3DRender::QShaderProgram::GLSL0OpenGL
Qt3DRender::QShaderProgram::SPIRV1Vulkan, OpenGL 5

enum QShaderProgram::ShaderType

This enum identifies the type of shader used.

ConstantValueDescription
Qt3DRender::QShaderProgram::Vertex0Vertex shader
Qt3DRender::QShaderProgram::Fragment1Fragment shader
Qt3DRender::QShaderProgram::TessellationControl2Tesselation control shader
Qt3DRender::QShaderProgram::TessellationEvaluation3Tesselation evaluation shader
Qt3DRender::QShaderProgram::Geometry4Geometry shader
Qt3DRender::QShaderProgram::Compute5Compute shader

enum QShaderProgram::Status

This enum identifies the status of shader used.

ConstantValueDescription
Qt3DRender::QShaderProgram::NotReady0The shader hasn't been compiled and linked yet
Qt3DRender::QShaderProgram::Ready1The shader was successfully compiled
Qt3DRender::QShaderProgram::Error2An error occurred while compiling the shader

Property Documentation

computeShaderCode : QByteArray

Holds the compute shader code used by this shader program.

Access functions:

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

Notifier signal:

void computeShaderCodeChanged(const QByteArray &computeShaderCode)

format : Format

Holds the format of the code provided on the ShaderProgram. The default is ShaderProgram.GLSL

Access functions:

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

Notifier signal:

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

fragmentShaderCode : QByteArray

Holds the fragment shader code used by this shader program.

Access functions:

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

Notifier signal:

void fragmentShaderCodeChanged(const QByteArray &fragmentShaderCode)

geometryShaderCode : QByteArray

Holds the geometry shader code used by this shader program.

Access functions:

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

Notifier signal:

void geometryShaderCodeChanged(const QByteArray &geometryShaderCode)

[read-only] log : const QString

Holds the log of the current shader program. This is useful to diagnose a compilation failure of the shader program.

Access functions:

QString log() const

Notifier signal:

void logChanged(const QString &log)

[read-only] status : const Status

Holds the status of the current shader program.

Access functions:

Qt3DRender::QShaderProgram::Status status() const

Notifier signal:

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

tessellationControlShaderCode : QByteArray

Holds the tesselation control shader code used by this shader program.

Access functions:

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

Notifier signal:

void tessellationControlShaderCodeChanged(const QByteArray &tessellationControlShaderCode)

tessellationEvaluationShaderCode : QByteArray

Holds the tesselation evaluation shader code used by this shader program.

Access functions:

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

Notifier signal:

void tessellationEvaluationShaderCodeChanged(const QByteArray &tessellationEvaluationShaderCode)

vertexShaderCode : QByteArray

Holds the vertex shader code used by this shader program.

Access functions:

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

Notifier signal:

void vertexShaderCodeChanged(const QByteArray &vertexShaderCode)

Member Function Documentation

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

Returns the shader code loaded from sourceUrl.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

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

Sets the shader code for type of shader to the shaderCode.

See also shaderCode().

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

Returns the shader code for type.

See also setShaderCode().

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

Returns the status of the current shader program.

Note: Getter function for property status.