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:

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.
    createInfo.addUniform("kzProjectionCameraWorldMatrix", PropertyDataTypeMatrix4x4, 1u, nullopt, ShaderProgram::UniformBindingTypeDefault, ShaderProgram::FixedUniform::ProjectionCameraWorldMatrix, getFixedUniformFunction("kzProjectionCameraWorldMatrix"), ShaderProgram::UniformTransformationPassThrough);
    createInfo.addUniform("kzNormalMatrix", PropertyDataTypeMatrix4x4, 1u, nullopt, ShaderProgram::UniformBindingTypeDefault, ShaderProgram::FixedUniform::NormalMatrix, getFixedUniformFunction("kzProjectionCameraWorldMatrix"), ShaderProgram::UniformTransformationPassThrough);

    // 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.
    {
        optional<BindingLoadInfo> info = createDefaultRenderValueBinding(domain, AbstractPropertyType(StandardMaterial::DiffuseProperty), StandardMaterial::DiffuseProperty.getUnqualifiedName(), PropertyDataTypeColor, 1u, ShaderProgram::UniformTransformationPassThrough);
        createInfo.bindings.emplace_back(info->binding, info->targetDataType, info->targetRenderValue);
    }
    {
        optional<BindingLoadInfo> info = createDefaultRenderValueBinding(domain, AbstractPropertyType(StandardMaterial::EmissiveProperty), StandardMaterial::EmissiveProperty.getUnqualifiedName(), PropertyDataTypeColor, 1u, ShaderProgram::UniformTransformationPassThrough);
        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.
    createInfo.addUniform("kzProjectionCameraWorldMatrix", PropertyDataTypeMatrix4x4, 1u, nullopt, ShaderProgram::UniformBindingTypeDefault, ShaderProgram::FixedUniform::ProjectionCameraWorldMatrix, getFixedUniformFunction("kzProjectionCameraWorldMatrix"), ShaderProgram::UniformTransformationPassThrough);
    createInfo.addUniform("kzNormalMatrix", PropertyDataTypeMatrix4x4, 1u, nullopt, ShaderProgram::UniformBindingTypeDefault, ShaderProgram::FixedUniform::NormalMatrix, getFixedUniformFunction("kzProjectionCameraWorldMatrix"), ShaderProgram::UniformTransformationPassThrough);

    // 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.
    {
        ExpressionBindingSource::ValueSourceContainer valueSources;
        valueSources.push_back(RenderPropertyExpressionValueSource::create(".", StandardMaterial::DiffuseProperty));
        valueSources.push_back(RenderPropertyExpressionValueSource::create(".", StandardMaterial::EmissiveProperty));
        ExpressionBindingSource::BindingOperationContainer operations;
        operations.emplace_back(BindingExpressionArgumentTypeSourceRegister0, PropertyFieldWhole,
                                BindingExpressionArgumentTypeSourceRegister1, PropertyFieldWhole,
                                KZU_EXPRESSION_VALIDATOR_OPERATION_MULTIPLY, 0, PropertyFieldWhole);
        BindingSourcePtr bindingSource = ExpressionBindingSource::create(operations, valueSources, ExpressionBindingSource::ValueSourceContainer(),
                                                                         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.
    {
        ExpressionBindingSource::ValueSourceContainer sources;
        sources.emplace_back(ObjectPropertyExpressionValueSource::create("##RenderPass", DrawObjectsRenderPass::DirectionalLightsProperty));

        vector<Variant> constants;
        constants.emplace_back(3);

        AbstractBinding::BindingProcessorContainer processors;
        processors.push_back(RangeBindingProcessor::create(domain, BindingExpressionArgumentTypeTemporaryRegister1, Light::DirectionalLightColorProperty, 2u));
        processors.push_back(RangeBindingProcessor::create(domain, BindingExpressionArgumentTypeTemporaryRegister1, Node::OpacityProperty, 3u));

        // Create views and execute the processors processor.
        ExpressionBindingSource::BindingOperationContainer operations;
        operations.emplace_back(BindingExpressionArgumentTypeSourceRegister0, PropertyFieldWhole,
                                BindingExpressionArgumentTypeConstantRegister0, PropertyFieldWhole,
                                KZU_EXPRESSION_VALIDATOR_OPERATION_CREATE_VIEW, 1u, PropertyFieldWhole);
        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));
        operations.emplace_back(BindingExpressionArgumentTypeTemporaryRegister2, PropertyFieldWhole,
                                BindingExpressionArgumentTypeTemporaryRegister3, PropertyFieldWhole,
                                KZU_EXPRESSION_VALIDATOR_OPERATION_MULTIPLY, 0u, PropertyFieldWhole);

        BindingSourcePtr bindingSource = ExpressionBindingSource::create(operations, processors, sources,
                                                                         ExpressionBindingSource::ValueSourceContainer(),
                                                                         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

using kanzi::ShaderProgram::CreateInfo::BindingInfo = ShaderProgram::BindingInfo

Binding info.

BindingContainer

using kanzi::ShaderProgram::CreateInfo::BindingContainer = ShaderProgram::BindingContainer

Binding container type.

Member Enumeration Documentation

Status

enum kanzi::ShaderProgram::CreateInfo::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

renderer

Renderer 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

name	Uniform name.
dataType	Uniform data type.
elementCount	Number of elements in the uniform.
propertyType	Optional property type.
bindingType	The type of binding associated with the shader uniform.
fixedOperation	Optional fixed uniform id.
func	Fixed function for the uniform, may be nullptr.
transform	Uniform 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

propertyType	Optional property type.
dataType	Uniform data type.
elementCount	Number of elements in the uniform.
transformation	Uniform 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

propertyType	Optional property type.
dataType	Uniform data type.
elementCount	Number 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

propertyType	Property type.
transformation	Uniform 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

propertyType

Property 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:

• kanzi/core.ui/platform/graphics_backend/gl/shader_create_info.hpp