gf::Shader Class Reference

An OpenGL vertex and/or fragment shader. More...

#include <gf/Shader.h>

Inheritance diagram for gf::Shader:

Public Types
enum	Type {   Vertex,   Fragment }
	Type of shaders. More...

Public Member Functions
	Shader ()
	Default constructor. More...
	~Shader ()
	Destructor. More...
	Shader (const Shader &)=delete
	Deleted copy constructor. More...
Shader &	operator= (const Shader &)=delete
	Deleted copy assignment. More...
Loading
bool	loadFromFile (const Path &filename, Type type)
	Load the vertex of fragment shader from a file. More...
bool	loadFromFile (const Path &vertexShaderFilename, const Path &fragmentShaderFilename)
	Load both the vertex and fragment shaders from files. More...
bool	loadFromMemory (StringRef shader, Type type)
	Load the vertex or fragment shader from a source code in memory. More...
bool	loadFromMemory (StringRef vertexShader, StringRef fragmentShader)
	Load both the vertex and fragment shaders from source codes in memory. More...
bool	loadFromStream (InputStream &stream, Type type)
	Load the vertex or fragment shader from a custom stream. More...
bool	loadFromStream (InputStream &vertexShaderStream, InputStream &fragmentShaderStream)
	Load both the vertex and fragment shaders from custom streams. More...
Uniform setting
void	setUniform (StringRef name, float val)
	Specify value for a float uniform. More...
void	setUniform (StringRef name, int val)
	Specify value for a int uniform. More...
void	setUniform (StringRef name, const Vector2f &vec)
	Specify value for a vec2 uniform. More...
void	setUniform (StringRef name, const Vector3f &vec)
	Specify value for a vec3 uniform. More...
void	setUniform (StringRef name, const Vector4f &vec)
	Specify value for a vec4 uniform. More...
void	setUniform (StringRef name, const Matrix3f &mat)
	Specify value for a mat3 uniform. More...
void	setUniform (StringRef name, const Matrix4f &mat)
	Specify value for a mat4 uniform. More...
void	setUniform (StringRef name, const BareTexture &tex)
	Specify a texture for a sampler2D uniform. More...

Static Public Member Functions
static void	bind (const Shader *shader)
	Bind a shader for rendering. More...

Detailed Description

An OpenGL vertex and/or fragment shader.

Shaders are programs written using a specific language, executed directly by the graphics card and allowing to apply real-time operations to the rendered entities.

There are two kinds of shaders:

• vertex shaders, that process vertices
• fragment (or pixel) shaders, that process pixels

A gf::Shader can be composed of either a vertex shader alone, a geometry shader alone, a fragment shader alone, or any combination of them. (see the variants of the load functions).

Shaders are written in GLSL, which is a C-like language dedicated to OpenGL shaders. You'll probably need to learn its basics before writing your own shaders for gf. See also How to write your own shader.

Like any C/C++ program, a GLSL shader has its own variables called uniforms that you can set from your C++ application. gf::Shader handles different types of uniforms:

• scalars: float, int
• vectors (2, 3 or 4 components)
• matrices (3x3 or 4x4)
• samplers (textures)

Every uniform variable in a shader can be set through one of the setUniform() overloads. For example, if you have a shader with the following uniforms:

uniform float offset;
uniform vec3 point;
uniform vec4 color;
uniform mat3 matrix;
uniform sampler2D overlay;

You can set their values from C++ code as follows:

shader.setUniform("offset", 2.0f);
shader.setUniform("point", gf::Vector3f(0.5f, 0.8f, 0.3f));
shader.setUniform("color", color); // color is a gf::Color4f
shader.setUniform("matrix", trans); // trans is a gf::Matrix3f
shader.setUniform("overlay", texture); // texture is a gf::Texture

To apply a shader to a drawable, you must pass it as part of the gf::RenderStates in the call to RenderTarget::draw() function:

gf::RenderStates states;
states.shader = &shader;
renderer.draw(sprite, states);

In the code above we pass a pointer to the shader, because it may be null (which means "default shader").

Shaders can be used on any drawable, but some combinations are not interesting. For example, using a vertex shader on a gf::Sprite is limited because there are only 4 vertices, the sprite would have to be subdivided in order to apply wave effects. Another bad example is a fragment shader with gf::Text: the texture of the text is not the actual text that you see on screen, it is a big texture containing all the characters of the font in an arbitrary order; thus, texture lookups on pixels other than the current one may not give you the expected result.

Member Enumeration Documentation

Type

enum gf::Shader::Type

Type of shaders.

Enumerator
Vertex	Type for a vertex shader.
Fragment	Type for a fragment (or pixel) shader.

Constructor & Destructor Documentation

Shader() [1/2]

gf::Shader::Shader

(

)

Default constructor.

This constructor creates an invalid shader.

~Shader()

gf::Shader::~Shader

(

)

Destructor.

Shader() [2/2]

gf::Shader::Shader ( const Shader &  )

delete

Deleted copy constructor.

Member Function Documentation

bind()

static void gf::Shader::bind ( const Shader *  shader )

static

Bind a shader for rendering.

This function is for internal use only.

Parameters

shader

Shader to bind, can be null to use no shader

loadFromFile() [1/2]

bool gf::Shader::loadFromFile	(	const Path &	filename,
		Type	type
	)

Load the vertex of fragment shader from a file.

This function loads a single shader, vertex or fragment, identified by the second argument.

The source must be a text file containing a valid shader in GLSL language. GLSL is a C-like language dedicated to OpenGL shaders; you'll probably need to read a good documentation for it before writing your own shaders.

Parameters

filename	Path of the vertex or fragment shader file to load
type	Type of shader (vertex or fragment)

Returns

True if loading succeeded, false if it failed

See also

loadFromMemory(), loadFromStream()

loadFromFile() [2/2]

bool gf::Shader::loadFromFile	(	const Path &	vertexShaderFilename,
		const Path &	fragmentShaderFilename
	)

Load both the vertex and fragment shaders from files.

This function loads both the vertex and the fragment shaders. If one of them fails to load, the shader is left empty (the valid shader is unloaded).

The sources must be a text files containing a valid shader in GLSL language. GLSL is a C-like language dedicated to OpenGL shaders; you'll probably need to read a good documentation for it before writing your own shaders.

Parameters

vertexShaderFilename	Path of the vertex shader file to load
fragmentShaderFilename	Path of the fragment shader file to load

Returns

True if loading succeeded, false if it failed

See also

loadFromMemory(), loadFromStream()

loadFromMemory() [1/2]

bool gf::Shader::loadFromMemory	(	StringRef	shader,
		Type	type
	)

Load the vertex or fragment shader from a source code in memory.

This function loads a single shader, vertex or fragment, identified by the second argument.

The source code must be a valid shader in GLSL language. GLSL is a C-like language dedicated to OpenGL shaders; you'll probably need to read a good documentation for it before writing your own shaders.

Parameters

shader	String containing the source code of the shader
type	Type of shader (vertex or fragment)

Returns

True if loading succeeded, false if it failed

See also

loadFromFile(), loadFromStream()

loadFromMemory() [2/2]

bool gf::Shader::loadFromMemory	(	StringRef	vertexShader,
		StringRef	fragmentShader
	)

Load both the vertex and fragment shaders from source codes in memory.

This function loads both the vertex and the fragment shaders. If one of them fails to load, the shader is left empty (the valid shader is unloaded).

The source codes must be a valid shaders in GLSL language. GLSL is a C-like language dedicated to OpenGL shaders; you'll probably need to read a good documentation for it before writing your own shaders.

Parameters

vertexShader	String containing the source code of the vertex shader
fragmentShader	String containing the source code of the fragment shader

Returns

True if loading succeeded, false if it failed

See also

loadFromFile(), loadFromStream()

loadFromStream() [1/2]

bool gf::Shader::loadFromStream	(	InputStream &	stream,
		Type	type
	)

Load the vertex or fragment shader from a custom stream.

This function loads a single shader, vertex or fragment, identified by the second argument.

The source code must be a valid shader in GLSL language. GLSL is a C-like language dedicated to OpenGL shaders; you'll probably need to read a good documentation for it before writing your own shaders.

Parameters

stream	Source stream to read from
type	Type of shader (vertex, geometry or fragment)

Returns

True if loading succeeded, false if it failed

See also

loadFromFile(), loadFromMemory()

loadFromStream() [2/2]

bool gf::Shader::loadFromStream	(	InputStream &	vertexShaderStream,
		InputStream &	fragmentShaderStream
	)

Load both the vertex and fragment shaders from custom streams.

This function loads both the vertex and the fragment shaders. If one of them fails to load, the shader is left empty (the valid shader is unloaded).

The source codes must be valid shaders in GLSL language. GLSL is a C-like language dedicated to OpenGL shaders; you'll probably need to read a good documentation for it before writing your own shaders.

Parameters

vertexShaderStream	Source stream to read the vertex shader from
fragmentShaderStream	Source stream to read the fragment shader from

Returns

True if loading succeeded, false if it failed

See also

loadFromFile(), loadFromMemory()

operator=()

Shader& gf::Shader::operator= ( const Shader &  )

delete

Deleted copy assignment.

setUniform() [1/8]

void gf::Shader::setUniform	(	StringRef	name,
		float	val
	)

Specify value for a float uniform.

Parameters

name	Name of the uniform variable in GLSL
val	Value of the float scalar

setUniform() [2/8]

void gf::Shader::setUniform	(	StringRef	name,
		int	val
	)

Specify value for a int uniform.

Parameters

name	Name of the uniform variable in GLSL
val	Value of the int scalar

setUniform() [3/8]

void gf::Shader::setUniform	(	StringRef	name,
		const Vector2f &	vec
	)

Specify value for a vec2 uniform.

Parameters

name	Name of the uniform variable in GLSL
vec	Value of the vec2 vector

setUniform() [4/8]

void gf::Shader::setUniform	(	StringRef	name,
		const Vector3f &	vec
	)

Specify value for a vec3 uniform.

Parameters

name	Name of the uniform variable in GLSL
vec	Value of the vec3 vector

setUniform() [5/8]

void gf::Shader::setUniform	(	StringRef	name,
		const Vector4f &	vec
	)

Specify value for a vec4 uniform.

Parameters

name	Name of the uniform variable in GLSL
vec	Value of the vec4 vector

setUniform() [6/8]

void gf::Shader::setUniform	(	StringRef	name,
		const Matrix3f &	mat
	)

Specify value for a mat3 uniform.

Parameters

name	Name of the uniform variable in GLSL
mat	Value of the mat3 matrix

setUniform() [7/8]

void gf::Shader::setUniform	(	StringRef	name,
		const Matrix4f &	mat
	)

Specify value for a mat4 uniform.

Parameters

name	Name of the uniform variable in GLSL
mat	Value of the mat4 matrix

setUniform() [8/8]

void gf::Shader::setUniform	(	StringRef	name,
		const BareTexture &	tex
	)

Specify a texture for a sampler2D uniform.

The corresponding parameter in the shader must be a 2D texture, i.e. a sampler2D GLSL type.

In the shader code:

uniform sampler2D the_texture; // this is the variable in the shader

In the source code:

gf::Texture texture;

shader.setUniform("the_texture", texture);

It is important to note that the texture must remain alive as long as the shader uses it, no copy is made internally.

Parameters

name	Name of the uniform variable in GLSL
tex	Value of the sampler2D texture