AbstractInclude Class Reference

#include <ImFusion/Core/GL/AbstractInclude.h>

Base class for abstract GLSL includes. More...

Inheritance diagram for AbstractInclude:

Detailed Description

Base class for abstract GLSL includes.

Abstract includes are a way to achieve runtime polymorphism in a shader program. They allow to include a GLSL header (.glh) without knowing its exact implementation during development. In a GLSL program they can be included with:

#pragma abstract_include "<DEFINE_NAME>"

If a definition is set for <DEFINE_NAME>, the corresponding header will be included and <DEFINE_NAME> will be set as a define. Otherwise the define is not set and nothing is included. Define names are expected to be in ALL_CAPS.

Example:

// [RandomHeader.glh]
int getRandomNumber() {
    return 5;
}

// [Random.frag]
#pragma abstract_include "RANDOM"
#ifndef RANDOM
// default implementation if no definition was set
int getRandomNumber() {
    return 4;
}
#endif
 
int main()
{
    getRandomNumber();
}

Instead of defining a default implementation, the call to getRandomNumber() can also be wrapped with the RANDOM define. However, in the former case it is much clearer what the include header is supposed to implement.

On the host side the header is represented by a derived class:

class Random : public AbstractInclude
{
public:
    Random()
        : AbstractInclude("RANDOM", "RandomHeader.glh")
    {}
};

In the code with the Random.frag program, the implementation of getRandomNumber can be now easily exchanged:

AbstractInclude* rand = new Random();
GlProgram p("Random.gl");
p.compute();    // getRandomNumber will return 4
p.addAbstractInclude(rand);
p.compute();    // getRandomNumber will return 5

Note

If the compilation of the shader fails with the abstract include definition, the definition is removed and the previous shader is used.

See also

Program

Classes
struct	Fingerprint
	AbstractIncludes provide a fingerprint to simplify duplicate detection. More...

Public Member Functions
	AbstractInclude (const std::string &defineName, const std::string &includePath)
	Creates a AbstractInclude for the given define and with the corresponding GLSL file at includePath.
const std::string &	defineName () const
	Returns the name of define used by this include.
const std::string &	includePath () const
	Returns the path to the included shader file.
virtual std::function< std::string(const std::string &)>	includeCodeSubstitution () const
	Optionally the abstract include can provide a function to change the shader code.
virtual std::vector< AbstractInclude * >	dependentIncludes () const
	Returns a list of dependent abstract includes that need to be included as well.
virtual Fingerprint	fingerprint () const
	Provides a finger print of the include.

Member Function Documentation

includeCodeSubstitution()

virtual std::function< std::string(const std::string &)> includeCodeSubstitution ( ) const

virtual

Optionally the abstract include can provide a function to change the shader code.

This function will be called after the shader include has been loaded from includePath() and receives the include code as argument. The function can then modify the code and is supposed to return the modified GLSL code. This can be used to include two instances of the same include by for example prefixing every uniform and function. The default implementation returns NULL and therefore does not change the code.

Reimplemented in MultiAbstractIncludeBase, GlPolyRigidDeformation, and GlExpr.

dependentIncludes()

virtual std::vector< AbstractInclude * > dependentIncludes ( ) const

virtual

Returns a list of dependent abstract includes that need to be included as well.

The default implementation returns an empty vector, you may override this method to your needs. The returned vector must be empty or contain valid pointers.

Reimplemented in MultiAbstractIncludeBase, OperandDeformation< T >, and OperandMask< T >.

fingerprint()

virtual Fingerprint fingerprint ( ) const

virtual

Provides a finger print of the include.

If two finger prints are equal this means that the two includes provide the very same code substitution. It does NOT mean that the two includes are equal. In particular the result of setArguments can be different.

Reimplemented in MultiAbstractIncludeBase, and GlExpr.

---

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

• ImFusion/Core/GL/AbstractInclude.h