Kanzi  3.9.9
Kanzi Engine C++ API
kanzi::ShaderProgram::CreateInfo Struct Reference

Struct that contains all the parameters that Kanzi needs to create a ShaderProgram. More...

#include <kanzi/core.ui/platform/graphics_backend/gl/shader_create_info.hpp>

Inheritance diagram for kanzi::ShaderProgram::CreateInfo:
[legend]

Classes

struct  BinaryShaderStage
 One shader stage in binary format. More...
 
struct  ShaderStage
 One shader stage in source code format. More...
 

Public Types

using BindingContainer = ShaderProgram::BindingContainer
 Binding container type. More...
 
using BindingInfo = ShaderProgram::BindingInfo
 Binding info. More...
 
enum  Status {
  StatusUnsupportedFormat, StatusCompileError, StatusLinkError, StatusInvalidAttributeLocation,
  StatusMissingShaderStage, StatusValid
}
 Status tells if shader creation parameters can be used to create a shader. More...
 

Public Member Functions

void addBinaryShader (ShaderType type, ConstByteSpan binary)
 Adds a binary shader to the program. More...
 
void addFixedUniform (string_view name)
 Adds a fixed uniform to a shader. More...
 
void addFixedUniform (string_view name, ShaderProgram::UniformTransformation transformation)
 Adds a fixed uniform to a shader. More...
 
void addFixedUniform (string_view name, ShaderProgram::FixedUniform uniform)
 Adds a fixed uniform to a shader. More...
 
void addFixedUniform (string_view name, ShaderProgram::FixedUniform uniform, ShaderProgram::UniformTransformation transformation)
 Adds a fixed uniform to a shader. More...
 
void addSourceShader (ShaderType type, string_view source)
 Adds a source shader to the program. More...
 
void addSourceShader (ShaderType type, const char *source)
 Adds a source shader to the program. More...
 
void addUniform (string_view name, PropertyDataType dataType, unsigned int elementCount, optional< AbstractPropertyType > propertyType, UniformBindingType bindingType, optional< FixedUniform > fixedOperation, FixedUniformFunction func, UniformTransformation transform)
 Adds an uniform to shader. More...
 
void addUniform (AbstractPropertyType propertyType, PropertyDataType dataType, unsigned int elementCount, ShaderProgram::UniformTransformation transformation)
 Adds a property type uniform to shader. More...
 
void addUniform (AbstractPropertyType propertyType, PropertyDataType dataType, unsigned int elementCount)
 Adds a property type uniform to shader. More...
 
void addUniform (AbstractPropertyType propertyType, ShaderProgram::UniformTransformation transformation)
 Adds a property type uniform to shader. More...
 
void addUniform (AbstractPropertyType propertyType)
 Adds a property type uniform to shader. More...
 
void addUniformAndBinding (AbstractPropertyType propertyType, ShaderProgram::UniformTransformation transformation)
 Adds a property type uniform to a shader with a given uniform transformation and creates for that uniform a default render value binding. More...
 
void addUniformAndBinding (AbstractPropertyType propertyType)
 Adds a property type uniform to a shader and creates for that uniform a default render value binding. More...
 
 CreateInfo ()
 Constructs empty create info structure for shader program creation. More...
 
Status validate (const Renderer &renderer) const
 Perform validation of shader creation parameters. More...
 

Public Attributes

BindingContainer bindings
 Bindings. More...
 
bool blendingControl
 Indicates whether ShaderProgram created from this createInfo should be able to change blending mode. More...
 
vector< bytecombinedShaderBinaryData
 Combined shader binary data. More...
 
unsigned int combinedShaderBinaryFormat
 Format for combined shader binary. More...
 
vector< byteprogramBinaryData
 Program binary data. More...
 
unsigned int programBinaryFormat
 Format for program binary. More...
 
unsigned int separateShaderBinaryFormat
 Format for separate shader binaries. More...
 
vector< BinaryShaderStageshaderBinaries
 All shader stages in binary format. More...
 
vector< ShaderStageshaderSources
 All shader stages in source code format. More...
 
UniformContainer uniforms
 Uniforms. More...
 
ShaderAttributeCollection vertexFormat
 Shader vertex attributes. More...
 

Detailed Description

Struct that contains all the parameters that Kanzi needs to create a ShaderProgram.

Kanzi loads ShaderProgram::CreateInfo from the kzb file as part of shader creation. You can also use ShaderProgram::CreateInfo to create shaders manually in code.

To define a shader, you must set these fields of the CreateInfo struct:

  • Vertex shader code.
  • Fragment shader code.
  • Binary shader data and format (if applicable).
  • Uniform information for each uniform.
  • Vertex attribute information for each attribute.
  • Render value bindings for uniform data.

Examples

To create a shader whose bindings are in the default state:

// This example shows how to create a shader whose bindings are in the default state.
// Specify a simple shader that lights nodes with diffuse lighting and emissive base only.
const string testFragmentSource(""
"uniform mediump vec4 Diffuse;\n"
"uniform mediump vec4 Emissive;\n"
"uniform mediump vec4 DirectionalLightColor[3];\n"
"uniform mediump vec3 DirectionalLightDirection[3];\n"
"varying mediump vec3 vNormal;\n"
"void main()\n"
"{"
" precision lowp float;\n"
" vec4 color = vec4(0.0);\n"
" vec3 nor = normalize(vNormal);\n"
" for (int it = 0; it < 3; ++it)\n"
" {\n"
" float angle = max(dot(nor, normalize(DirectionalLightDirection[it])), 0.0);\n"
" color += angle * (DirectionalLightColor[it] * Diffuse);\n"
" }\n"
" gl_FragColor = Emissive + color;\n"
"}");
const string testVertexSource(""
"attribute vec3 kzPosition;\n"
"attribute vec3 kzNormal;\n"
"uniform highp mat4 kzNormalMatrix;\n"
"uniform highp mat4 kzProjectionCameraWorldMatrix;\n"
"varying mediump vec3 vNormal;\n"
"void main()\n"
"{\n"
" precision mediump float;\n"
" vNormal = (kzNormalMatrix * vec4(kzNormal, 1.0)).xyz;\n"
" gl_Position = kzProjectionCameraWorldMatrix * vec4(kzPosition.xyz, 1.0);\n"
"}");
// Declare create info and set the sources.
ShaderProgram::CreateInfo createInfo;
createInfo.addSourceShader(ShaderTypeFragment, testFragmentSource);
createInfo.addSourceShader(ShaderTypeVertex, testVertexSource);
// Turn on blending control, default is still opaque.
createInfo.blendingControl = true;
// Add vertex attribute information.
createInfo.vertexFormat.emplace_back("kzPosition", VertexAttribute::SemanticPosition, 0u, GraphicsElementTypeFLOAT, 1u, 3u, 0, 0u);
createInfo.vertexFormat.emplace_back("kzNormal", VertexAttribute::SemanticNormal, 0u, GraphicsElementTypeFLOAT, 1u, 3u, 1, 0u);
// Add uniforms.
// First add the uniforms with available fixed operations.
// Then add the uniforms that are property values.
createInfo.addUniform(StandardMaterial::DiffuseProperty);
createInfo.addUniform(StandardMaterial::EmissiveProperty);
// Light uniforms must declare array size as set in the source.
createInfo.addUniform("DirectionalLightColor", PropertyDataTypeColor, 3u, AbstractPropertyType(Light::DirectionalLightColorProperty), ShaderProgram::UniformBindingTypeDefault, nullopt, nullptr, ShaderProgram::UniformTransformationPassThrough);
createInfo.addUniform("DirectionalLightDirection", PropertyDataTypeVector3, 3u, AbstractPropertyType(Light::DirectionalLightDirectionProperty), ShaderProgram::UniformBindingTypeDefault, nullopt, nullptr, ShaderProgram::UniformTransformationPassThrough);
// Create default bindings for the simple property bindings.
{
createInfo.bindings.emplace_back(info->binding, info->targetDataType, info->targetRenderValue);
}
{
createInfo.bindings.emplace_back(info->binding, info->targetDataType, info->targetRenderValue);
}
// Create default bindings for the light bindings.
{
optional<BindingLoadInfo> info = createDefaultRenderValueBinding(domain, AbstractPropertyType(Light::DirectionalLightColorProperty), "DirectionalLightColor", PropertyDataTypeColor, 3u, ShaderProgram::UniformTransformationPassThrough);
createInfo.bindings.emplace_back(info->binding, info->targetDataType, info->targetRenderValue);
}
{
optional<BindingLoadInfo> info = createDefaultRenderValueBinding(domain, AbstractPropertyType(Light::DirectionalLightDirectionProperty), "DirectionalLightDirection", PropertyDataTypeVector3, 3u, ShaderProgram::UniformTransformationPassThrough);
createInfo.bindings.emplace_back(info->binding, info->targetDataType, info->targetRenderValue);
}
// Create shader program and use it to create a material.
ShaderProgramSharedPtr shaderProgram = ShaderProgram::create(domain, createInfo, "Example shader");
MaterialSharedPtr material = Material::create(domain, "Example material", shaderProgram);

When you want to override binding information, instead of relying on the default states for the bindings, create the bindings manually. To manually create bindings for shaders:

// This example shows how to create a shader that has some manually specified bindings.
// Specify a simple shader that lights nodes with diffuse lighting base only.
const string testFragmentSource(""
"uniform mediump vec4 Diffuse;\n"
"uniform mediump vec4 DirectionalLightColor[3];\n"
"uniform mediump vec3 DirectionalLightDirection[3];\n"
"varying mediump vec3 vNormal;\n"
"void main()\n"
"{"
" precision lowp float;\n"
" vec4 color = vec4(0.0);\n"
" vec3 nor = normalize(vNormal);\n"
" for (int it = 0; it < 3; ++it)\n"
" {\n"
" float angle = max(dot(nor, normalize(DirectionalLightDirection[it])), 0.0);\n"
" color += angle * (DirectionalLightColor[it] * Diffuse);\n"
" }\n"
" gl_FragColor = color;\n"
"}");
const string testVertexSource(""
"attribute vec3 kzPosition;\n"
"attribute vec3 kzNormal;\n"
"uniform highp mat4 kzNormalMatrix;\n"
"uniform highp mat4 kzProjectionCameraWorldMatrix;\n"
"varying mediump vec3 vNormal;\n"
"void main()\n"
"{\n"
" precision mediump float;\n"
" vNormal = (kzNormalMatrix * vec4(kzNormal, 1.0)).xyz;\n"
" gl_Position = kzProjectionCameraWorldMatrix * vec4(kzPosition.xyz, 1.0);\n"
"}");
// Declare create info and set the sources.
ShaderProgram::CreateInfo createInfo;
createInfo.addSourceShader(ShaderTypeFragment, testFragmentSource);
createInfo.addSourceShader(ShaderTypeVertex, testVertexSource);
// Turn on blending control, default is still opaque.
createInfo.blendingControl = true;
// Add vertex attribute information.
createInfo.vertexFormat.emplace_back("kzPosition", VertexAttribute::SemanticPosition, 0u, GraphicsElementTypeFLOAT, 1u, 3u, 0, 0u);
createInfo.vertexFormat.emplace_back("kzNormal", VertexAttribute::SemanticNormal, 0u, GraphicsElementTypeFLOAT, 1u, 3u, 1, 0u);
// Add uniforms.
// First add the uniforms with available fixed operations.
// Most of the time you have no reason to declare a binding for these operations.
// Then add the uniforms that are property values.
// Note that emissive property is not added, even if it's read in bindings.
createInfo.addUniform(StandardMaterial::DiffuseProperty);
// Light uniforms must declare array size as set in the source.
createInfo.addUniform("DirectionalLightColor", PropertyDataTypeColor, 3u, AbstractPropertyType(Light::DirectionalLightColorProperty), ShaderProgram::UniformBindingTypeDefault, nullopt, nullptr, ShaderProgram::UniformTransformationPassThrough);
createInfo.addUniform("DirectionalLightDirection", PropertyDataTypeVector3, 3u, AbstractPropertyType(Light::DirectionalLightDirectionProperty), ShaderProgram::UniformBindingTypeDefault, nullopt, nullptr, ShaderProgram::UniformTransformationPassThrough);
// Create a binding that multiplies the Diffuse Color by Emissive Color.
{
vector<Variant>(), 1u);
AbstractBindingSharedPtr binding = ExpressionBinding::create(kanzi::move(bindingSource));
createInfo.bindings.emplace_back(binding, PropertyDataTypeColor, StandardMaterial::DiffuseProperty.getUnqualifiedName());
}
// Create a binding that multiplies Directional Light Color by the Opacity of the Light node.
{
vector<Variant> constants;
constants.emplace_back(3);
// Create views and execute the processors processor.
operations.emplace_back(static_cast<KzuExpressionValidatorOperation>(static_cast<int>(KZU_EXPRESSION_VALIDATOR_OPERATION_PROCESSOR) + 0));
operations.emplace_back(static_cast<KzuExpressionValidatorOperation>(static_cast<int>(KZU_EXPRESSION_VALIDATOR_OPERATION_PROCESSOR) + 1));
BindingSourcePtr bindingSource = ExpressionBindingSource::create(operations, processors, sources,
constants, 4u);
AbstractBindingSharedPtr binding = ExpressionBinding::create(kanzi::move(bindingSource));
createInfo.bindings.emplace_back(binding, PropertyDataTypeColor, Light::DirectionalLightColorProperty.getUnqualifiedName());
}
// Create a default binding for the Directional Light Direction.
{
optional<BindingLoadInfo> info = createDefaultRenderValueBinding(domain, AbstractPropertyType(Light::DirectionalLightDirectionProperty), "DirectionalLightDirection", PropertyDataTypeVector3, 3u, ShaderProgram::UniformTransformationPassThrough);
EXPECT_EQ(true, static_cast<bool>(info));
createInfo.bindings.emplace_back(info->binding, info->targetDataType, info->targetRenderValue);
}
// Create shader program and use it to create a material.
ShaderProgramSharedPtr shaderProgram = ShaderProgram::create(domain, createInfo, "Example shader");
MaterialSharedPtr material = Material::create(domain, "Example material", shaderProgram);

Member Typedef Documentation

Member Enumeration Documentation

Status tells if shader creation parameters can be used to create a shader.

If status is not StatusValid, create info must not be passed to ShaderProgram::create().

Since
Kanzi 3.9.6 StatusMissingShaderStage.
Enumerator
StatusUnsupportedFormat 

Shader binary format is not supported.

StatusCompileError 

Shader fails compilation.

StatusLinkError 

Shader fails linking.

StatusInvalidAttributeLocation 

Shader has invalid vertex attribute locations.

StatusMissingShaderStage 

Shader is missing required shader stage.

StatusValid 

CreateInfo is valid and can be used to create Shader.

Constructor & Destructor Documentation

kanzi::ShaderProgram::CreateInfo::CreateInfo ( )
explicit

Constructs empty create info structure for shader program creation.

Members of the structure must be filled in before the structure can be used in ShaderProgram::create().

Member Function Documentation

Status kanzi::ShaderProgram::CreateInfo::validate ( const Renderer renderer) const

Perform validation of shader creation parameters.

You can call validate() to see if shader creation parameters are valid before you pass create info to ShaderProgram::create().

Parameters
rendererRenderer to validate with.
Returns
StatusValid if these creation parameters can be used to create a shader. Otherwise a reason code for why this CreateInfo cannot be used to create a shader.
void kanzi::ShaderProgram::CreateInfo::addUniform ( string_view  name,
PropertyDataType  dataType,
unsigned int  elementCount,
optional< AbstractPropertyType propertyType,
UniformBindingType  bindingType,
optional< FixedUniform fixedOperation,
FixedUniformFunction  func,
UniformTransformation  transform 
)
inline

Adds an uniform to shader.

All properties are listed.

Parameters
nameUniform name.
dataTypeUniform data type.
elementCountNumber of elements in the uniform.
propertyTypeOptional property type.
bindingTypeThe type of binding associated with the shader uniform.
fixedOperationOptional fixed uniform id.
funcFixed function for the uniform, may be nullptr.
transformUniform transformation. See UniformTransformation.
void kanzi::ShaderProgram::CreateInfo::addUniform ( AbstractPropertyType  propertyType,
PropertyDataType  dataType,
unsigned int  elementCount,
ShaderProgram::UniformTransformation  transformation 
)
inline

Adds a property type uniform to shader.

Parameters
propertyTypeOptional property type.
dataTypeUniform data type.
elementCountNumber of elements in the uniform.
transformationUniform transformation.
void kanzi::ShaderProgram::CreateInfo::addUniform ( AbstractPropertyType  propertyType,
PropertyDataType  dataType,
unsigned int  elementCount 
)
inline

Adds a property type uniform to shader.

Uniform transformation is set to pass-through.

Parameters
propertyTypeOptional property type.
dataTypeUniform data type.
elementCountNumber of elements in the uniform.
void kanzi::ShaderProgram::CreateInfo::addUniform ( AbstractPropertyType  propertyType,
ShaderProgram::UniformTransformation  transformation 
)
inline

Adds a property type uniform to shader.

Data type is inferred from property. Element count is set to one.

Parameters
propertyTypeProperty type.
transformationUniform transformation.
See also
addUniformAndBinding(AbstractPropertyType propertyType, ShaderProgram::UniformTransformation transformation)
void kanzi::ShaderProgram::CreateInfo::addUniform ( AbstractPropertyType  propertyType)
inline

Adds a property type uniform to shader.

Data type is inferred from property. Element count is set to one. Uniform transformation is set to pass-through.

Parameters
propertyTypeProperty type.
See also
addUniformAndBinding(AbstractPropertyType propertyType)
void kanzi::ShaderProgram::CreateInfo::addUniformAndBinding ( AbstractPropertyType  propertyType,
ShaderProgram::UniformTransformation  transformation 
)

Adds a property type uniform to a shader with a given uniform transformation and creates for that uniform a default render value binding.

Infers the data type from the property type. Sets the element count to one.

Parameters
propertyTypeProperty type.
transformationUniform transformation.
Since
Kanzi 3.9.6
void kanzi::ShaderProgram::CreateInfo::addUniformAndBinding ( AbstractPropertyType  propertyType)
inline

Adds a property type uniform to a shader and creates for that uniform a default render value binding.

Infers the data type from the property type. Sets the element count to one. Sets the uniform transformation to pass-through.

Parameters
propertyTypeProperty type.
Since
Kanzi 3.9.6
void kanzi::ShaderProgram::CreateInfo::addFixedUniform ( string_view  name)
inline

Adds a fixed uniform to a shader.

Parameters
nameThe name of the uniform.
Since
Kanzi 3.9.6
void kanzi::ShaderProgram::CreateInfo::addFixedUniform ( string_view  name,
ShaderProgram::UniformTransformation  transformation 
)

Adds a fixed uniform to a shader.

Parameters
nameThe name of the uniform.
transformationUniform transformation.
Since
Kanzi 3.9.6
void kanzi::ShaderProgram::CreateInfo::addFixedUniform ( string_view  name,
ShaderProgram::FixedUniform  uniform 
)
inline

Adds a fixed uniform to a shader.

Parameters
nameThe name of the uniform.
uniformThe fixed uniform to use.
Since
Kanzi 3.9.6
void kanzi::ShaderProgram::CreateInfo::addFixedUniform ( string_view  name,
ShaderProgram::FixedUniform  uniform,
ShaderProgram::UniformTransformation  transformation 
)

Adds a fixed uniform to a shader.

Parameters
nameThe name of the uniform.
uniformThe fixed uniform to use.
transformationUniform transformation.
Since
Kanzi 3.9.6
void kanzi::ShaderProgram::CreateInfo::addSourceShader ( ShaderType  type,
string_view  source 
)
inline

Adds a source shader to the program.

Parameters
typeShader type.
sourceShader source code.
Since
Kanzi 3.9.6
void kanzi::ShaderProgram::CreateInfo::addSourceShader ( ShaderType  type,
const char *  source 
)
inline

Adds a source shader to the program.

Parameters
typeShader type.
sourceShader source code.
Since
Kanzi 3.9.6
void kanzi::ShaderProgram::CreateInfo::addBinaryShader ( ShaderType  type,
ConstByteSpan  binary 
)
inline

Adds a binary shader to the program.

Parameters
typeShader type.
binaryShader binary data.
Since
Kanzi 3.9.6

Member Data Documentation

vector<ShaderStage> kanzi::ShaderProgram::CreateInfo::shaderSources

All shader stages in source code format.

Since
Kanzi 3.9.6
unsigned int kanzi::ShaderProgram::CreateInfo::programBinaryFormat

Format for program binary.

vector<byte> kanzi::ShaderProgram::CreateInfo::programBinaryData

Program binary data.

unsigned int kanzi::ShaderProgram::CreateInfo::combinedShaderBinaryFormat

Format for combined shader binary.

vector<byte> kanzi::ShaderProgram::CreateInfo::combinedShaderBinaryData

Combined shader binary data.

unsigned int kanzi::ShaderProgram::CreateInfo::separateShaderBinaryFormat

Format for separate shader binaries.

vector<BinaryShaderStage> kanzi::ShaderProgram::CreateInfo::shaderBinaries

All shader stages in binary format.

Since
Kanzi 3.9.6
UniformContainer kanzi::ShaderProgram::CreateInfo::uniforms

Uniforms.

ShaderAttributeCollection kanzi::ShaderProgram::CreateInfo::vertexFormat

Shader vertex attributes.

BindingContainer kanzi::ShaderProgram::CreateInfo::bindings

Bindings.

bool kanzi::ShaderProgram::CreateInfo::blendingControl

Indicates whether ShaderProgram created from this createInfo should be able to change blending mode.

When blending control is enabled, materials using a ShaderProgram can set renderer blend mode. If blending control is disabled, materials using a ShaderProgram will leave blend mode unchanged.


The documentation for this struct was generated from the following file: