Shader class (vertex, geometry and fragment) More...
#include <SFML/Graphics/Shader.hpp>
Classes | |
struct | CurrentTextureType |
Special type that can be passed to setUniform(), and that represents the texture of the object being drawn. More... | |
Public Types | |
enum | Type { Vertex , Geometry , Fragment } |
Types of shaders. More... | |
Public Member Functions | |
Shader () | |
Default constructor. | |
~Shader () | |
Destructor. | |
bool | loadFromFile (const std::string &filename, Type type) |
Load the vertex, geometry or fragment shader from a file. | |
bool | loadFromFile (const std::string &vertexShaderFilename, const std::string &fragmentShaderFilename) |
Load both the vertex and fragment shaders from files. | |
bool | loadFromFile (const std::string &vertexShaderFilename, const std::string &geometryShaderFilename, const std::string &fragmentShaderFilename) |
Load the vertex, geometry and fragment shaders from files. | |
bool | loadFromMemory (const std::string &shader, Type type) |
Load the vertex, geometry or fragment shader from a source code in memory. | |
bool | loadFromMemory (const std::string &vertexShader, const std::string &fragmentShader) |
Load both the vertex and fragment shaders from source codes in memory. | |
bool | loadFromMemory (const std::string &vertexShader, const std::string &geometryShader, const std::string &fragmentShader) |
Load the vertex, geometry and fragment shaders from source codes in memory. | |
bool | loadFromStream (InputStream &stream, Type type) |
Load the vertex, geometry or fragment shader from a custom stream. | |
bool | loadFromStream (InputStream &vertexShaderStream, InputStream &fragmentShaderStream) |
Load both the vertex and fragment shaders from custom streams. | |
bool | loadFromStream (InputStream &vertexShaderStream, InputStream &geometryShaderStream, InputStream &fragmentShaderStream) |
Load the vertex, geometry and fragment shaders from custom streams. | |
void | setUniform (const std::string &name, float x) |
Specify value for float uniform. | |
void | setUniform (const std::string &name, const Glsl::Vec2 &vector) |
Specify value for vec2 uniform. | |
void | setUniform (const std::string &name, const Glsl::Vec3 &vector) |
Specify value for vec3 uniform. | |
void | setUniform (const std::string &name, const Glsl::Vec4 &vector) |
Specify value for vec4 uniform. | |
void | setUniform (const std::string &name, int x) |
Specify value for int uniform. | |
void | setUniform (const std::string &name, const Glsl::Ivec2 &vector) |
Specify value for ivec2 uniform. | |
void | setUniform (const std::string &name, const Glsl::Ivec3 &vector) |
Specify value for ivec3 uniform. | |
void | setUniform (const std::string &name, const Glsl::Ivec4 &vector) |
Specify value for ivec4 uniform. | |
void | setUniform (const std::string &name, bool x) |
Specify value for bool uniform. | |
void | setUniform (const std::string &name, const Glsl::Bvec2 &vector) |
Specify value for bvec2 uniform. | |
void | setUniform (const std::string &name, const Glsl::Bvec3 &vector) |
Specify value for bvec3 uniform. | |
void | setUniform (const std::string &name, const Glsl::Bvec4 &vector) |
Specify value for bvec4 uniform. | |
void | setUniform (const std::string &name, const Glsl::Mat3 &matrix) |
Specify value for mat3 matrix. | |
void | setUniform (const std::string &name, const Glsl::Mat4 &matrix) |
Specify value for mat4 matrix. | |
void | setUniform (const std::string &name, const Texture &texture) |
Specify a texture as sampler2D uniform. | |
void | setUniform (const std::string &name, CurrentTextureType) |
Specify current texture as sampler2D uniform. | |
void | setUniformArray (const std::string &name, const float *scalarArray, std::size_t length) |
Specify values for float [] array uniform. | |
void | setUniformArray (const std::string &name, const Glsl::Vec2 *vectorArray, std::size_t length) |
Specify values for vec2 [] array uniform. | |
void | setUniformArray (const std::string &name, const Glsl::Vec3 *vectorArray, std::size_t length) |
Specify values for vec3 [] array uniform. | |
void | setUniformArray (const std::string &name, const Glsl::Vec4 *vectorArray, std::size_t length) |
Specify values for vec4 [] array uniform. | |
void | setUniformArray (const std::string &name, const Glsl::Mat3 *matrixArray, std::size_t length) |
Specify values for mat3 [] array uniform. | |
void | setUniformArray (const std::string &name, const Glsl::Mat4 *matrixArray, std::size_t length) |
Specify values for mat4 [] array uniform. | |
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 3-components vector parameter of the shader. | |
void | setParameter (const std::string &name, const Color &color) |
Change a color parameter of the shader. | |
void | setParameter (const std::string &name, const Transform &transform) |
Change a matrix parameter of the shader. | |
void | setParameter (const std::string &name, const Texture &texture) |
Change a texture parameter of the shader. | |
void | setParameter (const std::string &name, CurrentTextureType) |
Change a texture parameter of the shader. | |
unsigned int | getNativeHandle () const |
Get the underlying OpenGL handle of the shader. | |
Static Public Member Functions | |
static void | bind (const Shader *shader) |
Bind a shader for rendering. | |
static bool | isAvailable () |
Tell whether or not the system supports shaders. | |
static bool | isGeometryAvailable () |
Tell whether or not the system supports geometry shaders. | |
Static Public Attributes | |
static CurrentTextureType | CurrentTexture |
Represents the texture of the object being drawn. | |
Shader class (vertex, geometry and fragment)
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 three kinds of shaders:
A sf::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 SFML.
Like any C/C++ program, a GLSL shader has its own variables called uniforms that you can set from your C++ application. sf::Shader handles different types of uniforms:
float
, int
, bool
Some SFML-specific types can be converted:
vec4
) mat3
or mat4
)Every uniform variable in a shader can be set through one of the setUniform() or setUniformArray() overloads. For example, if you have a shader with the following uniforms:
You can set their values from C++ code as follows, using the types defined in the sf::Glsl namespace:
The old setParameter() overloads are deprecated and will be removed in a future version. You should use their setUniform() equivalents instead.
The special Shader::CurrentTexture argument maps the given sampler2D
uniform to the current texture of the object being drawn (which cannot be known in advance).
To apply a shader to a drawable, you must pass it as an additional parameter to the RenderWindow::draw function:
... which is in fact just a shortcut for this:
In the code above we pass a pointer to the shader, because it may be null (which means "no shader").
Shaders can be used on any drawable, but some combinations are not interesting. For example, using a vertex shader on a sf::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 sf::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.
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 without impacting all the code.
Like sf::Texture that can be used as a raw OpenGL texture, sf::Shader can also be used directly as a raw shader for custom OpenGL geometry.
Definition at line 52 of file Shader.hpp.
enum sf::Shader::Type |
Types of shaders.
Enumerator | |
---|---|
Vertex | Vertex shader |
Geometry | Geometry shader. |
Fragment | Fragment (pixel) shader. |
Definition at line 60 of file Shader.hpp.
sf::Shader::Shader | ( | ) |
Default constructor.
This constructor creates an invalid shader.
sf::Shader::~Shader | ( | ) |
Destructor.
|
static |
Bind a shader for rendering.
This function is not part of the graphics API, it mustn't be used when drawing SFML entities. It must be used only if you mix sf::Shader with OpenGL code.
shader | Shader to bind, can be null to use no shader |
unsigned int sf::Shader::getNativeHandle | ( | ) | const |
Get the underlying OpenGL handle of the shader.
You shouldn't need to use this function, unless you have very specific stuff to implement that SFML doesn't support, or implement a temporary workaround until a bug is fixed.
|
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.
|
static |
Tell whether or not the system supports geometry shaders.
This function should always be called before using the geometry shader features. If it returns false, then any attempt to use sf::Shader geometry shader features will fail.
This function can only return true if isAvailable() would also return true, since shaders in general have to be supported in order for geometry shaders to be supported as well.
Note: The first call to this function, whether by your code or SFML will result in a context switch.
bool sf::Shader::loadFromFile | ( | const std::string & | filename, |
Type | type | ||
) |
Load the vertex, geometry or fragment shader from a file.
This function loads a single shader, vertex, geometry 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.
filename | Path of the vertex, geometry or fragment shader file to load |
type | Type of shader (vertex, geometry or fragment) |
bool sf::Shader::loadFromFile | ( | const std::string & | vertexShaderFilename, |
const std::string & | 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 text files containing 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.
vertexShaderFilename | Path of the vertex shader file to load |
fragmentShaderFilename | Path of the fragment shader file to load |
bool sf::Shader::loadFromFile | ( | const std::string & | vertexShaderFilename, |
const std::string & | geometryShaderFilename, | ||
const std::string & | fragmentShaderFilename | ||
) |
Load the vertex, geometry and fragment shaders from files.
This function loads the vertex, geometry and fragment shaders. If one of them fails to load, the shader is left empty (the valid shader is unloaded). The sources must be text files containing 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.
vertexShaderFilename | Path of the vertex shader file to load |
geometryShaderFilename | Path of the geometry shader file to load |
fragmentShaderFilename | Path of the fragment shader file to load |
bool sf::Shader::loadFromMemory | ( | const std::string & | shader, |
Type | type | ||
) |
Load the vertex, geometry or fragment shader from a source code in memory.
This function loads a single shader, vertex, geometry 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.
shader | String containing the source code of the shader |
type | Type of shader (vertex, geometry or fragment) |
bool sf::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 sources 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.
vertexShader | String containing the source code of the vertex shader |
fragmentShader | String containing the source code of the fragment shader |
bool sf::Shader::loadFromMemory | ( | const std::string & | vertexShader, |
const std::string & | geometryShader, | ||
const std::string & | fragmentShader | ||
) |
Load the vertex, geometry and fragment shaders from source codes in memory.
This function loads the vertex, geometry and fragment shaders. If one of them fails to load, the shader is left empty (the valid shader is unloaded). The sources 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.
vertexShader | String containing the source code of the vertex shader |
geometryShader | String containing the source code of the geometry shader |
fragmentShader | String containing the source code of the fragment shader |
bool sf::Shader::loadFromStream | ( | InputStream & | stream, |
Type | type | ||
) |
Load the vertex, geometry or fragment shader from a custom stream.
This function loads a single shader, vertex, geometry 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.
stream | Source stream to read from |
type | Type of shader (vertex, geometry or fragment) |
bool sf::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.
vertexShaderStream | Source stream to read the vertex shader from |
fragmentShaderStream | Source stream to read the fragment shader from |
bool sf::Shader::loadFromStream | ( | InputStream & | vertexShaderStream, |
InputStream & | geometryShaderStream, | ||
InputStream & | fragmentShaderStream | ||
) |
Load the vertex, geometry and fragment shaders from custom streams.
This function loads the vertex, geometry and 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.
vertexShaderStream | Source stream to read the vertex shader from |
geometryShaderStream | Source stream to read the geometry shader from |
fragmentShaderStream | Source stream to read the fragment shader from |
void sf::Shader::setParameter | ( | const std::string & | name, |
const Color & | color | ||
) |
Change a color parameter of the shader.
void sf::Shader::setParameter | ( | const std::string & | name, |
const Texture & | texture | ||
) |
Change a texture parameter of the shader.
void sf::Shader::setParameter | ( | const std::string & | name, |
const Transform & | transform | ||
) |
Change a matrix parameter of the shader.
void sf::Shader::setParameter | ( | const std::string & | name, |
const Vector2f & | vector | ||
) |
Change a 2-components vector parameter of the shader.
void sf::Shader::setParameter | ( | const std::string & | name, |
const Vector3f & | vector | ||
) |
Change a 3-components vector parameter of the shader.
void sf::Shader::setParameter | ( | const std::string & | name, |
CurrentTextureType | |||
) |
Change a texture parameter of the shader.
void sf::Shader::setParameter | ( | const std::string & | name, |
float | x | ||
) |
Change a float parameter of the shader.
void sf::Shader::setParameter | ( | const std::string & | name, |
float | x, | ||
float | y | ||
) |
Change a 2-components vector parameter of the shader.
void sf::Shader::setParameter | ( | const std::string & | name, |
float | x, | ||
float | y, | ||
float | z | ||
) |
Change a 3-components vector parameter of the shader.
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.
void sf::Shader::setUniform | ( | const std::string & | name, |
bool | x | ||
) |
Specify value for bool
uniform.
name | Name of the uniform variable in GLSL |
x | Value of the bool scalar |
void sf::Shader::setUniform | ( | const std::string & | name, |
const Glsl::Bvec2 & | vector | ||
) |
Specify value for bvec2
uniform.
name | Name of the uniform variable in GLSL |
vector | Value of the bvec2 vector |
void sf::Shader::setUniform | ( | const std::string & | name, |
const Glsl::Bvec3 & | vector | ||
) |
Specify value for bvec3
uniform.
name | Name of the uniform variable in GLSL |
vector | Value of the bvec3 vector |
void sf::Shader::setUniform | ( | const std::string & | name, |
const Glsl::Bvec4 & | vector | ||
) |
Specify value for bvec4
uniform.
name | Name of the uniform variable in GLSL |
vector | Value of the bvec4 vector |
void sf::Shader::setUniform | ( | const std::string & | name, |
const Glsl::Ivec2 & | vector | ||
) |
Specify value for ivec2
uniform.
name | Name of the uniform variable in GLSL |
vector | Value of the ivec2 vector |
void sf::Shader::setUniform | ( | const std::string & | name, |
const Glsl::Ivec3 & | vector | ||
) |
Specify value for ivec3
uniform.
name | Name of the uniform variable in GLSL |
vector | Value of the ivec3 vector |
void sf::Shader::setUniform | ( | const std::string & | name, |
const Glsl::Ivec4 & | vector | ||
) |
Specify value for ivec4
uniform.
This overload can also be called with sf::Color objects that are converted to sf::Glsl::Ivec4.
If color conversions are used, the ivec4 uniform in GLSL will hold the same values as the original sf::Color instance. For example, sf::Color(255, 127, 0, 255) is mapped to ivec4(255, 127, 0, 255).
name | Name of the uniform variable in GLSL |
vector | Value of the ivec4 vector |
void sf::Shader::setUniform | ( | const std::string & | name, |
const Glsl::Mat3 & | matrix | ||
) |
Specify value for mat3
matrix.
name | Name of the uniform variable in GLSL |
matrix | Value of the mat3 matrix |
void sf::Shader::setUniform | ( | const std::string & | name, |
const Glsl::Mat4 & | matrix | ||
) |
Specify value for mat4
matrix.
name | Name of the uniform variable in GLSL |
matrix | Value of the mat4 matrix |
void sf::Shader::setUniform | ( | const std::string & | name, |
const Glsl::Vec2 & | vector | ||
) |
Specify value for vec2
uniform.
name | Name of the uniform variable in GLSL |
vector | Value of the vec2 vector |
void sf::Shader::setUniform | ( | const std::string & | name, |
const Glsl::Vec3 & | vector | ||
) |
Specify value for vec3
uniform.
name | Name of the uniform variable in GLSL |
vector | Value of the vec3 vector |
void sf::Shader::setUniform | ( | const std::string & | name, |
const Glsl::Vec4 & | vector | ||
) |
Specify value for vec4
uniform.
This overload can also be called with sf::Color objects that are converted to sf::Glsl::Vec4.
It is important to note that the components of the color are normalized before being passed to the shader. Therefore, they are converted from range [0 .. 255] to range [0 .. 1]. For example, a sf::Color(255, 127, 0, 255) will be transformed to a vec4(1.0, 0.5, 0.0, 1.0) in the shader.
name | Name of the uniform variable in GLSL |
vector | Value of the vec4 vector |
void sf::Shader::setUniform | ( | const std::string & | name, |
const Texture & | texture | ||
) |
Specify a texture as sampler2D
uniform.
name is the name of the variable to change in the shader. The corresponding parameter in the shader must be a 2D texture (sampler2D
GLSL type).
Example:
It is important to note that texture must remain alive as long as the shader uses it, no copy is made internally.
To use the texture of the object being drawn, which cannot be known in advance, you can pass the special value sf::Shader::CurrentTexture:
name | Name of the texture in the shader |
texture | Texture to assign |
void sf::Shader::setUniform | ( | const std::string & | name, |
CurrentTextureType | |||
) |
Specify current texture as sampler2D
uniform.
This overload maps a shader texture variable to the texture of the object being drawn, which cannot be known in advance. The second argument must be sf::Shader::CurrentTexture. The corresponding parameter in the shader must be a 2D texture (sampler2D
GLSL type).
Example:
name | Name of the texture in the shader |
void sf::Shader::setUniform | ( | const std::string & | name, |
float | x | ||
) |
Specify value for float
uniform.
name | Name of the uniform variable in GLSL |
x | Value of the float scalar |
void sf::Shader::setUniform | ( | const std::string & | name, |
int | x | ||
) |
Specify value for int
uniform.
name | Name of the uniform variable in GLSL |
x | Value of the int scalar |
void sf::Shader::setUniformArray | ( | const std::string & | name, |
const float * | scalarArray, | ||
std::size_t | length | ||
) |
Specify values for float
[] array uniform.
name | Name of the uniform variable in GLSL |
scalarArray | pointer to array of float values |
length | Number of elements in the array |
void sf::Shader::setUniformArray | ( | const std::string & | name, |
const Glsl::Mat3 * | matrixArray, | ||
std::size_t | length | ||
) |
Specify values for mat3
[] array uniform.
name | Name of the uniform variable in GLSL |
matrixArray | pointer to array of mat3 values |
length | Number of elements in the array |
void sf::Shader::setUniformArray | ( | const std::string & | name, |
const Glsl::Mat4 * | matrixArray, | ||
std::size_t | length | ||
) |
Specify values for mat4
[] array uniform.
name | Name of the uniform variable in GLSL |
matrixArray | pointer to array of mat4 values |
length | Number of elements in the array |
void sf::Shader::setUniformArray | ( | const std::string & | name, |
const Glsl::Vec2 * | vectorArray, | ||
std::size_t | length | ||
) |
Specify values for vec2
[] array uniform.
name | Name of the uniform variable in GLSL |
vectorArray | pointer to array of vec2 values |
length | Number of elements in the array |
void sf::Shader::setUniformArray | ( | const std::string & | name, |
const Glsl::Vec3 * | vectorArray, | ||
std::size_t | length | ||
) |
Specify values for vec3
[] array uniform.
name | Name of the uniform variable in GLSL |
vectorArray | pointer to array of vec3 values |
length | Number of elements in the array |
void sf::Shader::setUniformArray | ( | const std::string & | name, |
const Glsl::Vec4 * | vectorArray, | ||
std::size_t | length | ||
) |
Specify values for vec4
[] array uniform.
name | Name of the uniform variable in GLSL |
vectorArray | pointer to array of vec4 values |
length | Number of elements in the array |
|
static |
Represents the texture of the object being drawn.
Definition at line 82 of file Shader.hpp.