Commit 7408a0e6 authored by Laszlo Agocs's avatar Laszlo Agocs
Browse files

Add some docs for QShaderDescription

parent 13e5968e
......@@ -131,13 +131,13 @@ QT_BEGIN_NAMESPACE
setting up the translation targets via setGeneratedShaders():
\badcode
baker.setGeneratedShaderVariants({ QBakedShader::NormalShader });
baker.setGeneratedShaderVariants({ QBakedShaderKey::StandardShader });
QVector<QShaderBaker::GeneratedShader> targets;
targets.append({ QBakedShader::SpirvShader, QBakedShader::ShaderSourceVersion(100) });
targets.append({ QBakedShader::GlslShader, QBakedShader::ShaderSourceVersion(100, QBakedShader::ShaderSourceVersion::GlslEs) });
targets.append({ QBakedShader::SpirvShader, QBakedShader::ShaderSourceVersion(120) });
targets.append({ QBakedShader::HlslShader, QBakedShader::ShaderSourceVersion(50) });
targets.append({ QBakedShader::MslShader, QBakedShader::ShaderSourceVersion(12) });
targets.append({ QBakedShaderKey::SpirvShader, QBakedShaderVersion(100) });
targets.append({ QBakedShaderKey::GlslShader, QBakedShaderVersion(100, QBakedShaderVersion::GlslEs) });
targets.append({ QBakedShaderKey::SpirvShader, QBakedShaderVersion(120) });
targets.append({ QBakedShaderKey::HlslShader, QBakedShaderVersion(50) });
targets.append({ QBakedShaderKey::MslShader, QBakedShaderVersion(12) });
baker.setGeneratedShaders(targets);
QBakedShader shaders = baker.bake();
if (!shaders.isValid())
......@@ -278,7 +278,7 @@ void QShaderBaker::setSourceString(const QByteArray &sourceString, QBakedShader:
additional translations to other languages. To request this, do:
\badcode
baker.setGeneratedShaders({ QBakedShader::SpirvShader, QBakedShader::ShaderSourceVersion(100) });
baker.setGeneratedShaders({ QBakedShaderKey::SpirvShader, QBakedShaderVersion(100) });
\endcode
*/
void QShaderBaker::setGeneratedShaders(const QVector<GeneratedShader> &v)
......@@ -290,7 +290,7 @@ void QShaderBaker::setGeneratedShaders(const QVector<GeneratedShader> &v)
Specifies which shader variants are genetated. Each shader version can have
multiple variants in the resulting QBakedShader.
In most cases \a v contains a single entry, QBakedShader::StandardShader.
In most cases \a v contains a single entry, QBakedShaderKey::StandardShader.
\note when no variants are set, the resulting QBakedShader will be empty and
thus invalid.
......
......@@ -44,6 +44,159 @@ QT_BEGIN_NAMESPACE
/*!
\class QShaderDescription
\inmodule QtShaderTools
\brief Describes the interface of a shader.
A shader typically has a set of inputs and outputs. A vertex shader for
example has a number of input variables and may use one or more uniform
buffers to access data (e.g. a modelview matrix) provided by the
application. The shader for the fragment stage receives data from the
vertex stage (in a simple setup) and may also rely on data from uniform
buffers, images, and samplers.
When it comes to vertex inputs and the layout of the uniform buffers (what
are the names of the members? what is there size, offset, and so on),
applications and frameworks may need to discover this dynamically at run
time. This is typical when the shader is not built-in but provided by an
external entity, like the user.
Modern and lean graphics APIs may no longer provide a way to query shader
reflection information at run time. Therefore, such data is now
automatically generated by QShaderBaker and is provided as a
QShaderDescription object for each and every QBakedShader.
Like QBakedShader, QShaderDescription is implicitly shared so its instances
can safely be returned or passed by value.
\section2 Example
Take the following vertex shader:
\snippet color.vert 0
This shader has two inputs: \c position at location 0 with a type of \c
vec4, and \c color at location 1 with a type of \c vec3. It has one output:
\c v_color, although this is typically not interesting for applications.
What is more important, there is a uniform block at binding 0 with a size
of 68 bytes and two members, a 4x4 matrix named \c mvp at offset 0, and a
float \c opacity at offset 64.
All this is described by a QShaderDescription object. QShaderDescription
can also be serialized to JSON and binary JSON, and can be deserialized
from binary JSON. In practice this is rarely needed since QBakedShader
takes care of the associated QShaderDescription automatically, but if the
QShaderDescription of the above shader would be written out as JSON, it
would look like the following:
\badcode
{
"inputs": [
{
"location": 1,
"name": "color",
"type": "vec3"
},
{
"location": 0,
"name": "position",
"type": "vec4"
}
],
"outputs": [
{
"location": 0,
"name": "v_color",
"type": "vec3"
}
],
"uniformBlocks": [
{
"binding": 0,
"blockName": "buf",
"members": [
{
"matrixStride": 16,
"name": "mvp",
"offset": 0,
"size": 64,
"type": "mat4"
},
{
"name": "opacity",
"offset": 64,
"size": 4,
"type": "float"
}
],
"set": 0,
"size": 68,
"structName": "ubuf"
}
]
}
\endcode
The C++ API allows accessing a data structure like the above. For
simplicity the inner structs only contain public data members, also
considering that their layout is unlikely to change in the future.
\sa QShaderBaker, QBakedShader
*/
/*!
\enum QShaderDescription::VarType
Represents the type of a variable or block member.
\value Unknown
\value Float
\value Vec2
\value Vec3
\value Vec4
\value Mat2
\value Mat2x3
\value Mat2x4
\value Mat3
\value Mat3x2
\value Mat3x4
\value Mat4
\value Mat4x2
\value Mat4x3
\value Int
\value Int2
\value Int3
\value Int4
\value Uint
\value Uint2
\value Uint3
\value Uint4
\value Bool
\value Bool2
\value Bool3
\value Bool4
\value Double
\value Double2
\value Double3
\value Double4
\value DMat2
\value DMat2x3
\value DMat2x4
\value DMat3
\value DMat3x2
\value DMat3x4
\value DMat4
\value DMat4x2
\value DMat4x3
\value Sampler1D
\value Sampler2D
\value Sampler2DMS
\value Sampler3D
\value SamplerCube
\value Sampler1DArray
\value Sampler2DArray
\value Sampler2DMSArray
\value Sampler3DArray
\value SamplerCubeArray
\value Struct
*/
/*!
......@@ -66,11 +219,20 @@ QT_BEGIN_NAMESPACE
\inmodule QtShaderTools
*/
/*!
Constructs a new, empty QShaderDescription.
\note Being empty implies that isValid() returns \c false for the
newly constructed instance.
*/
QShaderDescription::QShaderDescription()
: d(new QShaderDescriptionPrivate)
{
}
/*!
\internal
*/
void QShaderDescription::detach()
{
if (d->ref.load() != 1) {
......@@ -81,12 +243,18 @@ void QShaderDescription::detach()
}
}
/*!
\internal
*/
QShaderDescription::QShaderDescription(const QShaderDescription &other)
{
d = other.d;
d->ref.ref();
}
/*!
\internal
*/
QShaderDescription &QShaderDescription::operator=(const QShaderDescription &other)
{
if (d != other.d) {
......@@ -98,27 +266,50 @@ QShaderDescription &QShaderDescription::operator=(const QShaderDescription &othe
return *this;
}
/*!
Destructor.
*/
QShaderDescription::~QShaderDescription()
{
if (!d->ref.deref())
delete d;
}
/*!
\return true if the QShaderDescription contains at least one entry in one of
the variable and block lists.
*/
bool QShaderDescription::isValid() const
{
return !d->inVars.isEmpty() || !d->outVars.isEmpty() || !d->uniformBlocks.isEmpty() || !d->pushConstantBlocks.isEmpty();
}
/*!
\return a serialized binary version of the data.
\sa toJson()
*/
QByteArray QShaderDescription::toBinaryJson() const
{
return d->makeDoc().toBinaryData();
}
/*!
\return a serialized JSON text version of the data.
\note There is no deserialization method provided for JSON text.
\sa toBinaryJson()
*/
QByteArray QShaderDescription::toJson() const
{
return d->makeDoc().toJson();
}
/*!
Deserializes the given binary JSON \a data and returns a new
QShaderDescription.
*/
QShaderDescription QShaderDescription::fromBinaryJson(const QByteArray &data)
{
QShaderDescription desc;
......@@ -126,26 +317,66 @@ QShaderDescription QShaderDescription::fromBinaryJson(const QByteArray &data)
return desc;
}
/*!
\return the list of input variables. This includes vertex inputs (sometimes
called attributes) for the vertex stage, and inputs for other stages
(sometimes called varyings).
*/
QVector<QShaderDescription::InOutVariable> QShaderDescription::inputVariables() const
{
return d->inVars;
}
/*!
\return the list of output variables.
*/
QVector<QShaderDescription::InOutVariable> QShaderDescription::outputVariables() const
{
return d->outVars;
}
/*!
\return the list of uniform blocks.
*/
QVector<QShaderDescription::UniformBlock> QShaderDescription::uniformBlocks() const
{
return d->uniformBlocks;
}
/*!
\return the list of push constant blocks.
\note Avoid relying on push constant blocks for shaders that are to be used
in combination with the Qt Rendering Hardware Interface since that
currently has no support for them.
*/
QVector<QShaderDescription::PushConstantBlock> QShaderDescription::pushConstantBlocks() const
{
return d->pushConstantBlocks;
}
/*!
\return the list of combined image samplers
With GLSL/Vulkan shaders as source a \c{layout(binding = 1) uniform sampler2D tex;}
uniform generates the following: (shown as textual JSON here)
\code
"combinedImageSamplers": [
{
"binding": 1,
"name": "tex",
"set": 0,
"type": "sampler2D"
}
]
\endcode
This does not mean that other language versions of the shader must also use
a combined image sampler, especially considering that the concept may not
exist everywhere. For instance, a HLSL version will likely just use a
Texture2D and SamplerState object with registers t1 and s1, respectively.
*/
QVector<QShaderDescription::InOutVariable> QShaderDescription::combinedImageSamplers() const
{
return d->combinedImageSamplers;
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment