sf::Shader Class Reference
[Graphics module]

Pixel/fragment shader class. More...

#include <Shader.hpp>

Inheritance diagram for sf::Shader:
sf::GlResource

List of all members.

Public Member Functions

 Shader ()
 Default constructor.
 Shader (const Shader &copy)
 Copy constructor.
 ~Shader ()
 Destructor.
bool LoadFromFile (const std::string &filename)
 Load the shader from a file.
bool LoadFromMemory (const std::string &shader)
 Load the shader from a source code in memory.
bool LoadFromStream (InputStream &stream)
 Load the shader from a custom stream.
void SetParameter (const std::string &name, float x)
 Change a float parameter of the shader.
void SetParameter (const std::string &name, float x, float y)
 Change a 2-components vector parameter of the shader.
void SetParameter (const std::string &name, float x, float y, float z)
 Change a 3-components vector parameter of the shader.
void SetParameter (const std::string &name, float x, float y, float z, float w)
 Change a 4-components vector parameter of the shader.
void SetParameter (const std::string &name, const Vector2f &vector)
 Change a 2-components vector parameter of the shader.
void SetParameter (const std::string &name, const Vector3f &vector)
 Change a 2-components vector parameter of the shader.
void SetTexture (const std::string &name, const Texture &texture)
 Change a texture parameter of the shader.
void SetCurrentTexture (const std::string &name)
 Set the current object texture in the shader.
void Bind () const
 Bind the shader for rendering (activate it).
void Unbind () const
 Unbind the shader (deactivate it).
Shaderoperator= (const Shader &right)
 Overload of assignment operator.

Static Public Member Functions

static bool IsAvailable ()
 Tell whether or not the system supports shaders.

Static Private Member Functions

static void EnsureGlContext ()

Friends

class Renderer

Detailed Description

Pixel/fragment shader class.

Pixel shaders (or fragment shaders) are programs written using a specific language, executed directly by the graphics card and allowing to apply per-pixel real-time operations to the rendered entities.

Pixel 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 SFML.

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

The value of the variables can be changed at any time with either Shader::SetParameter or Shader::SetTexture:

 shader.SetParameter("offset", 2.f);
 shader.SetParameter("color", 0.5f, 0.8f, 0.3f);
 shader.SetTexture("overlay", texture); // texture is a sf::Texture
 shader.SetCurrentTexture("texture");

Shader::SetCurrentTexture maps the given texture variable to the current texture of the object being drawn.

To apply a shader to a drawable, you must pass it as an additional parameter to the Draw function:

 window.Draw(sprite, shader);

Shaders can be used on any drawable, but they are mainly made for sf::Sprite. Using a shader on a sf::String is more limited, because 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. Using a shader with sf::Shape is even more limited, as shapes don't use any texture.

Shaders can also be used to apply global post-effects to the current contents of the target (like the old sf::PostFx class in SFML 1). This can be done in two different ways:

The first technique is more optimized because it doesn't involve retrieving the target's pixels to system memory, but the second one doesn't impact the rendering process and can be easily inserted anywhere.

Like sf::Texture that can be used as a raw OpenGL texture, sf::Shader can also be used directly as a raw fragment shader for custom OpenGL geometry.

 window.SetActive();
 shader.Bind();
 ... render OpenGL geometry ...
 shader.Unbind();

Definition at line 48 of file Shader.hpp.


Constructor & Destructor Documentation

sf::Shader::Shader (  ) 

Default constructor.

This constructor creates an invalid shader

sf::Shader::Shader ( const Shader copy  ) 

Copy constructor.

Parameters:
copy Instance to copy
sf::Shader::~Shader (  ) 

Destructor.


Member Function Documentation

void sf::Shader::Bind (  )  const

Bind the shader for rendering (activate it).

This function is normally for internal use only, unless you want to use the shader with a custom OpenGL rendering instead of a SFML drawable.

 window.SetActive();
 shader.Bind();
 ... render OpenGL geometry ...
 shader.Unbind();
See also:
Unbind
static bool sf::Shader::IsAvailable (  )  [static]

Tell whether or not the system supports shaders.

This function should always be called before using the shader features. If it returns false, then any attempt to use sf::Shader will fail.

Returns:
True if shaders are supported, false otherwise
bool sf::Shader::LoadFromFile ( const std::string &  filename  ) 

Load the shader from a file.

The source must be a text file containing a valid fragment 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 shader file to load
Returns:
True if loading succeeded, false if it failed
See also:
LoadFromMemory, LoadFromStream
bool sf::Shader::LoadFromMemory ( const std::string &  shader  ) 

Load the shader from a source code in memory.

The source code must be a valid fragment 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
Returns:
True if loading succeeded, false if it failed
See also:
LoadFromFile, LoadFromStream
bool sf::Shader::LoadFromStream ( InputStream stream  ) 

Load the shader from a custom stream.

The source code must be a valid fragment 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
Returns:
True if loading succeeded, false if it failed
See also:
LoadFromFile, LoadFromMemory
Shader& sf::Shader::operator= ( const Shader right  ) 

Overload of assignment operator.

Parameters:
right Instance to assign
Returns:
Reference to self
void sf::Shader::SetCurrentTexture ( const std::string &  name  ) 

Set the current object texture in the shader.

This function maps a shader texture variable to the texture of the object being drawn. Example:

 // This is the variable in the pixel shader
 uniform sampler2D current;
 shader.SetCurrentTexture("current");
Parameters:
name Name of the texture in the shader
See also:
SetParameter, SetTexture
void sf::Shader::SetParameter ( const std::string &  name,
const Vector3f vector 
)

Change a 2-components vector parameter of the shader.

name is the name of the variable to change in the shader. For example:

 uniform vec3 myparam; // this is the variable in the pixel shader
 shader.SetParameter("myparam", sf::Vector3f(5.2f, 6.0f, -8.1f));
Parameters:
name Name of the parameter in the shader
vector Vector to assign
See also:
SetTexture, SetCurrentTexture
void sf::Shader::SetParameter ( const std::string &  name,
const Vector2f vector 
)

Change a 2-components vector parameter of the shader.

name is the name of the variable to change in the shader. For example:

 uniform vec2 myparam; // this is the variable in the pixel shader
 shader.SetParameter("myparam", sf::Vector2f(5.2f, 6.0f));
Parameters:
name Name of the parameter in the shader
vector Vector to assign
See also:
SetTexture, SetCurrentTexture
void sf::Shader::SetParameter ( const std::string &  name,
float  x,
float  y,
float  z,
float  w 
)

Change a 4-components vector parameter of the shader.

name is the name of the variable to change in the shader. For example:

 uniform vec4 myparam; // this is the variable in the pixel shader
 shader.SetParameter("myparam", 5.2f, 6.0f, -8.1f, 0.4f);
Parameters:
name Name of the parameter in the shader
x First component of the value to assign
y Second component of the value to assign
z Third component of the value to assign
w Fourth component of the value to assign
See also:
SetTexture, SetCurrentTexture
void sf::Shader::SetParameter ( const std::string &  name,
float  x,
float  y,
float  z 
)

Change a 3-components vector parameter of the shader.

name is the name of the variable to change in the shader. For example:

 uniform vec3 myparam; // this is the variable in the pixel shader
 shader.SetParameter("myparam", 5.2f, 6.0f, -8.1f);
Parameters:
name Name of the parameter in the shader
x First component of the value to assign
y Second component of the value to assign
z Third component of the value to assign
See also:
SetTexture, SetCurrentTexture
void sf::Shader::SetParameter ( const std::string &  name,
float  x,
float  y 
)

Change a 2-components vector parameter of the shader.

name is the name of the variable to change in the shader. For example:

 uniform vec2 myparam; // this is the variable in the pixel shader
 shader.SetParameter("myparam", 5.2f, 6.0f);
Parameters:
name Name of the parameter in the shader
x First component of the value to assign
y Second component of the value to assign
See also:
SetTexture, SetCurrentTexture
void sf::Shader::SetParameter ( const std::string &  name,
float  x 
)

Change a float parameter of the shader.

name is the name of the variable to change in the shader. For example:

 uniform float myparam; // this is the variable in the pixel shader
 shader.SetParameter("myparam", 5.2f);
Parameters:
name Name of the parameter in the shader
x Value to assign
See also:
SetTexture, SetCurrentTexture
void sf::Shader::SetTexture ( const std::string &  name,
const Texture texture 
)

Change a texture parameter of the shader.

name is the name of the texture to change in the shader. This function maps an external texture to the given shader variable; to use the current texture of the object being drawn, use SetCurrentTexture instead. Example:

 // These are the variables in the pixel shader
 uniform sampler2D the_texture;
 sf::Texture texture;
 ...
 shader.SetTexture("the_texture", texture);

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

Parameters:
name Name of the texture in the shader
texture Texture to assign
See also:
SetParameter, SetCurrentTexture
void sf::Shader::Unbind (  )  const

Unbind the shader (deactivate it).

This function is normally for internal use only, unless you want to use the shader with a custom OpenGL rendering instead of a SFML drawable.

See also:
Bind

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