Class OcsfmlGraphics.shader

class shader : ?vertex:'a ShaderSource.source -> ?fragment:'a ShaderSource.source -> unit -> object .. end
Shader class (vertex 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 two kinds of shaders:

Vertex shaders, that process vertices Fragment (pixel) shaders, that process pixels

A OcsfmlGraphics.shader can be composed of either a vertex shader alone, a fragment shader alone, or both combined (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 Caml program, a shader has its own variables that you can set from your Caml application. OcsfmlGraphics.shader handles 4 different types of variables:

The value of the variables can be changed at any time with either the various overloads of the set_* function:
    shader#set_parameter1 "offset" 2.0 ;
    shader#set_parameter3 "color" 0.5 0.8 0.3 ;
    
    (* transform is a OcsfmlGraphics.transform *)
    shader#set_transform "matrix" transform ; 

    (* texture is a OcsfmlGraphics.texture *)
    shader#set_texture "overlay" texture ; 
    shader#set_current_texture "texture" 
    
The special Shader::CurrentTexture argument maps the given texture variable 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 Draw function:

 
    window#draw ~render_states:(mk_render_states ~shader:shader ()) sprite 
    

Shaders can be used on any drawable, but some combinations are not interesting. For example, using a vertex shader on a OcsfmlGraphics.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 OcsfmlGraphics.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. 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 OcsfmlGraphics.texture that can be used as a raw OpenGL texture, OcsfmlGraphics.shader can also be used directly as a raw shader for custom OpenGL geometry.

  
    window#set_active () ;
    shader#bind ;
(* ... render OpenGL geometry ... *)
    shader#unbind 
    


method destroy : unit
method load_from_file : ?vertex:string -> ?fragment:string -> unit -> bool
Load the vertex and/or the fragment shader from files. Warning: At least one of the shaders must be loaded.
Returns True if loading succeeded, false if it failed.
vertex : Path of the vertex shader file to load.
fragment : Path of the fragment shader file to load.
method load_from_memory : ?vertex:string -> ?fragment:string -> unit -> bool
method load_from_stream : 'b.
?vertex:(#OcsfmlSystem.input_stream as 'b) -> ?fragment:'b -> unit -> bool
Load the vertex and/or the fragment shader from custom streams. Warning: At least one of the shaders must be loaded.
Returns True if loading succeeded, false if it failed.
vertex : Source stream to read the vertex shader from.
fragment : Source stream to read the fragment shader from.
method set_color : string -> Color.t -> unit
Change a color parameter of the shader.

The string argument is the name of the variable to change in the shader. The corresponding parameter in the shader must be a 4x1 vector (vec4 GLSL type).

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 OcsfmlGraphics.Color.{r = 255; g = 125; b = 0; a = 255} will be transformed to a vec4(1.0, 0.5, 0.0, 1.0) in the shader.

Example:

uniform vec4 color; // this is the variable in the shader
shader#set_color "color" 
          OcsfmlGraphics.Color.{ r = 255; g = 128; b = 0; a = 255}

method set_current_texture : string -> unit
Change a texture parameter of the shader.

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:

uniform sampler2D current; // this is the variable in the shader
shader#set_current_texture "current"

method set_parameter : string -> ?x:float -> ?y:float -> ?z:float -> float -> unit
method set_parameter1 : string -> float -> unit
Change a float parameter of the shader.

name is the name of the variable to change in the shader. The corresponding parameter in the shader must be a float (float GLSL type).

Example:

uniform float myparam; // this is the variable in the shader
shader#set_parameter1 "myparam" 5.2

method set_parameter2 : string -> float -> float -> unit
Change a 2-components vector parameter of the shader.

The string argument is the name of the variable to change in the shader. The corresponding parameter in the shader must be a 2x1 vector (vec2 GLSL type).

Example:

uniform vec2 myparam; // this is the variable in the shader
shader#set_parameter2 "myparam" 5.2 6.0

method set_parameter2v : string -> float * float -> unit
Change a 2-components vector parameter of the shader.

The string argument is the name of the variable to change in the shader. The corresponding parameter in the shader must be a 2x1 vector (vec2 GLSL type).

Example:

uniform vec2 myparam; // this is the variable in the shader
shader#set_parameter2v "myparam" (5.2, 6.0)

method set_parameter3 : string -> float -> float -> float -> unit
Change a 3-components vector parameter of the shader.

The string argument is the name of the variable to change in the shader. The corresponding parameter in the shader must be a 3x1 vector (vec3 GLSL type).

Example:

uniform vec3 myparam; // this is the variable in the shader
shader#set_parameter3 "myparam" 5.2 6.0 -8.1

method set_parameter3v : string -> float * float * float -> unit
Change a 3-components vector parameter of the shader.

The string argument is the name of the variable to change in the shader. The corresponding parameter in the shader must be a 3x1 vector (vec3 GLSL type).

Example:

uniform vec3 myparam; // this is the variable in the shader
shader#set_parameter3v "myparam" (5.2, 6.0, -8.1)

method set_parameter4 : string -> float -> float -> float -> float -> unit
Change a 4-components vector parameter of the shader.

name is the name of the variable to change in the shader. The corresponding parameter in the shader must be a 4x1 vector (vec4 GLSL type).

Example:

uniform vec4 myparam; // this is the variable in the shader
shader#set_parameter3 "myparam" 5.2 6.0 -8.1 0.4

method set_texture : 'c. string -> (#const_texture as 'c) -> unit
Change a texture parameter of the shader.

The string argument 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:

uniform sampler2D the_texture; // this is the variable in the shader
let texture = new texture ... in
      ...
      shader#set_texture "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.

To use the texture of the object being draw, which cannot be known in advance, you can use set_current_texture:

shader#set_current_texture "the_texture"

method set_transform : string -> transform -> unit
Change a matrix parameter of the shader.

The string argument is the name of the variable to change in the shader. The corresponding parameter in the shader must be a 4x4 matrix (mat4 GLSL type).

Example:

uniform mat4 matrix; // this is the variable in the shader
let transform = new transform in
      transform#translate 5 10 ;
      shader#set_transform "matrix" transform