Gamedev Framework (gf)  0.3.0
A C++11 framework for 2D games
Public Types | Public Member Functions | Static Public Member Functions | List of all members
gf::Shader Class Reference

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

#include <gf/Shader.h>

Inheritance diagram for gf::Shader:
Inheritance graph
[legend]

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...
 
Shaderoperator= (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:

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:

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:

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
shaderShader 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
filenamePath of the vertex or fragment shader file to load
typeType 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
vertexShaderFilenamePath of the vertex shader file to load
fragmentShaderFilenamePath 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
shaderString containing the source code of the shader
typeType 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
vertexShaderString containing the source code of the vertex shader
fragmentShaderString 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
streamSource stream to read from
typeType 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
vertexShaderStreamSource stream to read the vertex shader from
fragmentShaderStreamSource 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
nameName of the uniform variable in GLSL
valValue of the float scalar
void gf::Shader::setUniform ( const std::string &  name,
int  val 
)

Specify value for a int uniform.

Parameters
nameName of the uniform variable in GLSL
valValue of the int scalar
void gf::Shader::setUniform ( const std::string &  name,
const Vector2f vec 
)

Specify value for a vec2 uniform.

Parameters
nameName of the uniform variable in GLSL
vecValue of the vec2 vector
void gf::Shader::setUniform ( const std::string &  name,
const Vector3f vec 
)

Specify value for a vec3 uniform.

Parameters
nameName of the uniform variable in GLSL
vecValue of the vec3 vector
void gf::Shader::setUniform ( const std::string &  name,
const Vector4f vec 
)

Specify value for a vec4 uniform.

Parameters
nameName of the uniform variable in GLSL
vecValue of the vec4 vector
void gf::Shader::setUniform ( const std::string &  name,
const Matrix3f mat 
)

Specify value for a mat3 uniform.

Parameters
nameName of the uniform variable in GLSL
matValue of the mat3 matrix
void gf::Shader::setUniform ( const std::string &  name,
const Matrix4f mat 
)

Specify value for a mat4 uniform.

Parameters
nameName of the uniform variable in GLSL
matValue 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
nameName of the uniform variable in GLSL
texValue of the sampler2D texture