Qt Documentation

Contents

QShaderProgram Class

class Qt3DRender::QShaderProgram

Encapsulates a Shader Program. More...

Header: #include <QShaderProgram>
CMake: find_package(Qt6 COMPONENTS 3drender REQUIRED)
target_link_libraries(mytarget PRIVATE Qt6::3drender)
qmake: QT += 3drender
Since: Qt 5.5
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

[since 5.15] enum QShaderProgram::Format

This enum identifies the format of the shader code used.

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

This enum was introduced or modified in Qt 5.15.

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)

[since 5.15] format : Format

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

This property was introduced in Qt 5.15.

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.

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