StelGLSLShader Class Reference

GLSL shader program. More...

#include <StelGLSLShader.hpp>

Public Member Functions
virtual	~StelGLSLShader ()
	Destroy the shader program. More...
virtual bool	addVertexShader (const QString &source)=0
	Add a vertex shader from source, compiling it in the process. More...
virtual bool	addFragmentShader (const QString &source)=0
	Add a fragment shader from source, compiling it in the process. More...
virtual bool	addVertexShader (const QString &name, const QString &source)=0
	Add a named (optional) vertex shader. More...
virtual bool	hasVertexShader (const QString &name) const =0
	Has a named vertex shader with specified name been added? More...
virtual void	enableVertexShader (const QString &name)=0
	Enable previously added named vertex shader. More...
virtual void	disableVertexShader (const QString &name)=0
	Disable previously added named vertex shader. More...
virtual bool	build ()=0
	Build the shader program. More...
virtual void	unlock ()=0
	Unlock the shader program for modifications. More...
virtual QString	log () const =0
	Return a string containing the error log of the shader. More...
virtual void	bind ()=0
	Bind the shader, using it for following draw calls. More...
virtual void	release ()=0
	Release a bound shader after use. More...
template<class T >
void	setUniformValue (const char *const name, T value)
	Set value of a uniform shader variable. More...
virtual void	useUnprojectedPositionAttribute ()=0
	Does this shader need the unprojected position attribute? More...

Protected Member Functions
template<class T >
void	setUniformValue_ (const char *const name, T value)
	"Default" overload of setUniformValue() implementation. More...
virtual void	setUniformValue_ (const char *const name, const bool value)=0
	setUniformValue() implementation for type bool. More...
virtual void	setUniformValue_ (const char *const name, const int value)=0
	setUniformValue() implementation for type int. More...
virtual void	setUniformValue_ (const char *const name, const float value)=0
	setUniformValue() implementation for type float. More...
virtual void	setUniformValue_ (const char *const name, const Vec2f value)=0
	setUniformValue() implementation for type Vec2f. More...
virtual void	setUniformValue_ (const char *const name, const Vec3f &value)=0
	setUniformValue() implementation for type Vec3f. More...
virtual void	setUniformValue_ (const char *const name, const Vec4f &value)=0
	setUniformValue() implementation for type Vec4f. More...
virtual void	setUniformValue_ (const char *const name, const Mat4f &value)=0
	setUniformValue() implementation for type Mat4f. More...

Detailed Description

GLSL shader program.

Can be used with Renderer backends that support GLSL, such as the StelQGL2Renderer.

Shader programs are created by StelRenderer. After creation, sources of used vertex and fragment shaders have to be added, and then the shader must be built using the build() member function. After that, the shader can be bound to be used for drawing. It can also be modified by calling the unlock() member function and adding more shaders, and even by disabling or reenabling them. Disabling/reenabling is only supported for vertex shaders, but fragment shader functions can be added when needed.

There is currently no geometry shader support, but it can be added when needed.

Uniform variables are set through the setUniformValue() member function. Only most commonly used data types are supported, but it is easy to add support for more types if needed. Some uniform variables are specified internally and need to be declared in the shader:

• StelProjector's projection matrix: mat4f projectionMatrix
• Global color (only specified if vertex has no color attribute): vec4 globalColor

Vertex attributes can't be set through the API - they are set internally from vertex buffer during drawing.

Any shader that uses StelProjector projection (that is, any shader except of those working with 2D data) must declare and call the project() function to project the vertex position. If vertex projection is done on the CPU, this is a dummy function that simply returns its argument. If it's done on the GPU, it's done in this function.

The project() function must be declared (but not defined), as follows:

vec4 project(in vec4 v);

Usage of the project() function:

gl_Position = projectionMatrix * project(vertex);

Attribute variable names match vertex attribute interpretations as follows:

• Position: vertex
• TexCoord: texCoord
• Normal: normal
• Color: color

If useUnprojectedPositionAttribute() is called, another attribute is added:

• Position before StelProjector projection: unprojectedVertex

Shader program building can fail. After a failure, the shader is invalid and should not be used (should be destroyed).

Shader creation example:

// renderer is a StelRenderer*
if(renderer->isGLSLSupported())
{
    StelGLSLShader* shader = renderer->createGLSLShader();
    if(!shader->addVertexShader(
       "vec4 project(in vec4 v);\n"
       "attribute mediump vec4 vertex;\n"
       "uniform mediump mat4 projectionMatrix;\n"
       "void main(void)\n"
       "{\n"
       "    gl_Position = projectionMatrix * project(vertex);\n"
       "}\n"))
    {
        qWarning() << "Error adding vertex shader: " << shader->log();
        delete shader;
        return false; // Failed creating shader
    }
    if(!shader->addFragmentShader(
       "uniform mediump vec4 globalColor;\n"
       "void main(void)\n"
       "{\n"
       "    gl_FragColor = globalColor;\n"
       "}\n"))
    {
        qWarning() << "Error adding fragment shader: " << shader->log();
        delete shader;
        return false; // Failed creating shader
    }
    if(!shader->build())
    {
        qWarning() << "Error building shader: " << shader->log();
        delete shader;
        return false; // failed creating shader
    }
    // Shader log might contain warnings.
    if(!shader->log().isEmpty())
    {
        qWarning() << "Shader creation log: " << shader->log();
    }
}

Shader usage example:

// shader is a StelGLSLShader*
// renderer is a StelRenderer*
// vertices is a StelVertexBuffer<SomeVertexType>*
// indices is a StelIndexBuffer*
// projector is a StelProjectorP

shader->bind();
shader->setUniformValue("ambientLight", Vec4f(0.1f, 0.1f, 0.1f,0.1f));
renderer->drawVertexBuffer(vertices, indices, projector);
shader->release();

See Also

StelRenderer

Definition at line 145 of file StelGLSLShader.hpp.

Constructor & Destructor Documentation

virtual StelGLSLShader::~StelGLSLShader ( )

inlinevirtual

Destroy the shader program.

StelGLSLShader must be destroyed by the user before its Renderer is destroyed.

Definition at line 151 of file StelGLSLShader.hpp.

Member Function Documentation

virtual bool StelGLSLShader::addFragmentShader ( const QString &  source )

pure virtual

Add a fragment shader from source, compiling it in the process.

This operation can fail. In case of failure, use log() to find out the cause.

The shader must be unlocked when this is called.

Parameters

source

Source code of the shader.

Returns

true if succesfully added and compiled, false otherwise.

Implemented in StelQGLGLSLShader.

virtual bool StelGLSLShader::addVertexShader ( const QString &  source )

pure virtual

Add a vertex shader from source, compiling it in the process.

This operation can fail. In case of failure, use log() to find out the cause.

The shader must be unlocked when this is called.

Parameters

source

Source code of the shader.

Returns

true if succesfully added and compiled, false otherwise.

Implemented in StelQGLGLSLShader.

virtual bool StelGLSLShader::addVertexShader ( const QString &  name, const QString &  source  )

pure virtual

Add a named (optional) vertex shader.

Named vertex shaders can be disabled and reenabled. (Unnamed shaders are always enabled.) This allows to dynamically exchange implementations of functions, making shaders modular. GLSL projection is an example of this.

The shader must be unlocked when this is called.

Parameters

name	Name of the shader.
source	Source code of the shader.

Implemented in StelQGLGLSLShader.

virtual void StelGLSLShader::bind ( )

pure virtual

Bind the shader, using it for following draw calls.

This must be called before setting uniforms. The shader must be built when this is called.

Note that the shader must be released after any draw calls using the shader to allow default shaders to return to use.

Implemented in StelQGLGLSLShader.

virtual bool StelGLSLShader::build ( )

pure virtual

Build the shader program.

This must be called before the shader can be bound.

This operation can fail. In case of failure, use log() to find out the cause. If build() fails, the shader should be assumed to no longer be usable and be destroyed.

Returns

true if succesfully built, false otherwise.

Implemented in StelQGLGLSLShader.

virtual void StelGLSLShader::disableVertexShader ( const QString &  name )

pure virtual

Disable previously added named vertex shader.

The shader must be unlocked when this is called.

Parameters

name	Name of the shader to disable.

Implemented in StelQGLGLSLShader.

virtual void StelGLSLShader::enableVertexShader ( const QString &  name )

pure virtual

Enable previously added named vertex shader.

The shader must be unlocked when this is called.

Parameters

name	Name of the shader to enable.

Implemented in StelQGLGLSLShader.

virtual bool StelGLSLShader::hasVertexShader ( const QString &  name ) const

pure virtual

Has a named vertex shader with specified name been added?

Implemented in StelQGLGLSLShader.

virtual QString StelGLSLShader::log ( ) const

pure virtual

Return a string containing the error log of the shader.

If the shader is succesfully built, it will contain a success message. It might also contain GLSL code warnings.

Implemented in StelQGLGLSLShader.

virtual void StelGLSLShader::release ( )

pure virtual

Release a bound shader after use.

This must be called after using the shader so that the StelRenderer backend can go back to using default shaders.

It also must be called before bind()-ing another StelGLSLShader.

Implemented in StelQGLGLSLShader.

template<class T >

void StelGLSLShader::setUniformValue ( const char *const  name, T  value  )

inline

Set value of a uniform shader variable.

A uniform variable has the same value for each drawn vertex/pixel. This can be used for things such as a transformation matrix, global vertex color and so on.

setUniformValue() supports these data types (GLSL type in parentheses):

bool(bool), int(int), float(float), Vec2f(vec2), Vec3f(vec3), Vec4f(vec4), Mat4f(mat4)

The shader must be bound when this is called.

Note

Due to dynamic shader re-linking needed to support modular shaders, uniforms are cached internally and only uploaded at the draw call when the shader is used. Fixed amount of storage is allocated (currently 512 bytes, which is enough for 8 4x4 matrices). Also only a fixed number of uniforms is supported (currently 32). Both of these limits can be increased if needed (see StelQGLGLSLShader). This storage is written to with each setUniformValue() call, and freed on a call to release().

Parameters

name	Name of the uniform variable. Must match variable name in at least one of the used vertex/fragment shaders. For efficiency reasons, the name is not guaranteed to be copied within the shader backend. Therefore, the name string must exist until a call to release(). (This is easiest to achieve by simply using string literals.)
value	Value to set the variable to.

Definition at line 275 of file StelGLSLShader.hpp.

template<class T >

void StelGLSLShader::setUniformValue_ ( const char *const  name, T  value  )

inlineprotected

"Default" overload of setUniformValue() implementation.

This is called for unsupported uniform types, and results in an error.

Definition at line 295 of file StelGLSLShader.hpp.

virtual void StelGLSLShader::setUniformValue_ ( const char *const  name, const bool  value  )

protectedpure virtual

setUniformValue() implementation for type bool.

Implemented in StelQGLGLSLShader.

virtual void StelGLSLShader::setUniformValue_ ( const char *const  name, const int  value  )

protectedpure virtual

setUniformValue() implementation for type int.

Implemented in StelQGLGLSLShader.

virtual void StelGLSLShader::setUniformValue_ ( const char *const  name, const float  value  )

protectedpure virtual

setUniformValue() implementation for type float.

Implemented in StelQGLGLSLShader.

virtual void StelGLSLShader::setUniformValue_ ( const char *const  name, const Vec2f  value  )

protectedpure virtual

setUniformValue() implementation for type Vec2f.

Implemented in StelQGLGLSLShader.

virtual void StelGLSLShader::setUniformValue_ ( const char *const  name, const Vec3f &  value  )

protectedpure virtual

setUniformValue() implementation for type Vec3f.

Implemented in StelQGLGLSLShader.

virtual void StelGLSLShader::setUniformValue_ ( const char *const  name, const Vec4f &  value  )

protectedpure virtual

setUniformValue() implementation for type Vec4f.

Implemented in StelQGLGLSLShader.

virtual void StelGLSLShader::setUniformValue_ ( const char *const  name, const Mat4f &  value  )

protectedpure virtual

setUniformValue() implementation for type Mat4f.

Implemented in StelQGLGLSLShader.

virtual void StelGLSLShader::unlock ( )

pure virtual

Unlock the shader program for modifications.

Allows to, add, enable, disable vertex/fragment shaders.

This can be called even if the shader is bound (which is used for last-moment modifications, like GLSL projection in renderer backend), but it must be rebuilt before drawing and releasing.

Implemented in StelQGLGLSLShader.

virtual void StelGLSLShader::useUnprojectedPositionAttribute ( )

pure virtual

Does this shader need the unprojected position attribute?

If called, the shader will have to declare another vertex attribute, unprojectedVertex, for vertex position before StelProjector projection. Useful e.g. for lighting.

Implemented in StelQGLGLSLShader.

---

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

• core/renderer/StelGLSLShader.hpp