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 (const std::string &shader, Type type)
	Load the vertex or fragment shader from a source code in memory. More...

bool	loadFromMemory (const std::string &vertexShader, const std::string &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 (const std::string &name, float val)
	Specify value for a `float` uniform. More...

void	setUniform (const std::string &name, int val)
	Specify value for a `int` uniform. More...

void	setUniform (const std::string &name, const Vector2f &vec)
	Specify value for a `vec2` uniform. More...

void	setUniform (const std::string &name, const Vector3f &vec)
	Specify value for a `vec3` uniform. More...

void	setUniform (const std::string &name, const Vector4f &vec)
	Specify value for a `vec4` uniform. More...

void	setUniform (const std::string &name, const Matrix3f &mat)
	Specify value for a `mat3` uniform. More...

void	setUniform (const std::string &name, const Matrix4f &mat)
	Specify value for a `mat4` uniform. More...

void	setUniform (const std::string &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.

Constructor & Destructor Documentation

gf::Shader::Shader ( )

Default constructor.

This constructor creates an invalid shader.

gf::Shader::~Shader ( )

Destructor.

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

delete

Deleted copy constructor.

Member Function Documentation

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

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

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

bool gf::Shader::loadFromMemory	(	const std::string &	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()

bool gf::Shader::loadFromMemory	(	const std::string &	vertexShader,
		const std::string &	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()

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

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

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

delete

Deleted copy assignment.

void gf::Shader::setUniform	(	const std::string &	name,
		float	val
	)

Specify value for a float uniform.

Parameters

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

void gf::Shader::setUniform	(	const std::string &	name,
		int	val
	)

Specify value for a int uniform.

Parameters

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

void gf::Shader::setUniform	(	const std::string &	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

void gf::Shader::setUniform	(	const std::string &	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

void gf::Shader::setUniform	(	const std::string &	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

void gf::Shader::setUniform	(	const std::string &	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

void gf::Shader::setUniform	(	const std::string &	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

void gf::Shader::setUniform	(	const std::string &	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

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation