Kanzi Framework  3.9.0
Kanzi Engine 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]

Public Types

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

Public Member Functions

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...
 
 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...
 
string combinedShaderBinaryData
 Combined shader binary data. More...
 
unsigned int combinedShaderBinaryFormat
 Format for combined shader binary. More...
 
string fragmentShaderSource
 Fragment shader source code. More...
 
string programBinaryData
 Program binary data. More...
 
unsigned int programBinaryFormat
 Format for program binary. More...
 
unsigned int separateShaderBinaryFormat
 Format for separate shader binaries. More...
 
string separateShaderBinaryFragmentData
 Fragment shader binary data when using separate shader binaries. More...
 
string separateShaderBinaryVertexData
 Vertex shader binary data when using separate shader binaries. More...
 
UniformContainer uniforms
 Uniforms. More...
 
ShaderAttributeCollection vertexFormat
 Shader vertex attributes. More...
 
string vertexShaderSource
 Vertex shader source code. 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.fragmentShaderSource = testFragmentSource;
createInfo.vertexShaderSource = 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.fragmentShaderSource = testFragmentSource;
createInfo.vertexShaderSource = 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

◆ BindingInfo

◆ BindingContainer

Member Enumeration Documentation

◆ Status

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().

Enumerator
StatusUnsupportedFormat 

Shader binary format is not supported.

StatusCompileError 

Shader fails compilation.

StatusLinkError 

Shader fails linking.

StatusInvalidAttributeLocation 

Shader has invalid vertex attribute locations.

StatusValid 

CreateInfo is valid and can be used to create Shader.

Constructor & Destructor Documentation

◆ CreateInfo()

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

◆ validate()

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.

◆ addUniform() [1/5]

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.

◆ addUniform() [2/5]

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.

◆ addUniform() [3/5]

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.

◆ addUniform() [4/5]

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.

◆ addUniform() [5/5]

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.

Member Data Documentation

◆ vertexShaderSource

string kanzi::ShaderProgram::CreateInfo::vertexShaderSource

Vertex shader source code.

◆ fragmentShaderSource

string kanzi::ShaderProgram::CreateInfo::fragmentShaderSource

Fragment shader source code.

◆ programBinaryFormat

unsigned int kanzi::ShaderProgram::CreateInfo::programBinaryFormat

Format for program binary.

◆ programBinaryData

string kanzi::ShaderProgram::CreateInfo::programBinaryData

Program binary data.

◆ combinedShaderBinaryFormat

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

Format for combined shader binary.

◆ combinedShaderBinaryData

string kanzi::ShaderProgram::CreateInfo::combinedShaderBinaryData

Combined shader binary data.

◆ separateShaderBinaryFormat

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

Format for separate shader binaries.

◆ separateShaderBinaryVertexData

string kanzi::ShaderProgram::CreateInfo::separateShaderBinaryVertexData

Vertex shader binary data when using separate shader binaries.

◆ separateShaderBinaryFragmentData

string kanzi::ShaderProgram::CreateInfo::separateShaderBinaryFragmentData

Fragment shader binary data when using separate shader binaries.

◆ uniforms

UniformContainer kanzi::ShaderProgram::CreateInfo::uniforms

Uniforms.

◆ vertexFormat

ShaderAttributeCollection kanzi::ShaderProgram::CreateInfo::vertexFormat

Shader vertex attributes.

◆ bindings

BindingContainer kanzi::ShaderProgram::CreateInfo::bindings

Bindings.

◆ blendingControl

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: