===== orxSHADER structure =====

Shader module. Allows the definition of shader information (code + parameters). 

==== Summary ====

<code ini>[ShaderTemplate]
Code = "// Shader code
  void main()
  {
   // Do stuff
  }"
CodeList       = CodeKey1 # ... # CodeKeyN 
ParamList      = Param1 # ... # ParamN
ParamFloat     = <float>
ParamVector    = <vector>
ParamTexture   = path/to/texture
UseCustomParam = <bool>
KeepInCache    = <bool>
</code>


==== Details ====

Here's a list of the available properties for an ''orxSHADER'' structure:
  * ''Code'': Used to declare a monolithic shader. Will be ignored if CodeList is defined. This block ((delimited by double quotes (") as seen in the [[en:orx:config:syntax|syntax page]])) contains the code that will be executed. It needs to be provided and be valid [[wp>glsl|GLSL]] fragment shader code.
  * ''CodeList'': The values of this list will be used as config keys from this section to reconstruct, in the given order, a multi-part shader. If not defined, Code will be used instead.
  * ''KeepInCache'': Defines if the shader code should be kept in memory even if no shader of this type is currently in use. This saves time (reading from disk + compiling) but costs memory. Its default value is ''false''.
  * ParamList: Define all the parameters your shader code needs. Defined params then must have a default value to guess their type: textures, vectors and floats are supported. If none is provided, type defaults to texture and will use shader's owner texture as value. If an invalid path is provided for a parameter, or the parameter isn't defined at all, the owner's texture will be used ((if the owner is a viewport, it will be its associated texture; if it's an object, it's current graphic/animation key's texture will be used)). **If an explicit list is provided for any parameter, the shader variable will be an array of this parameter type (instead of a regular variable) and its size will be the number of items in the list.**
  * ''UseCustomParam'': When set to true, an event will be sent to override params values at runtime as well as the automated "time" value. Defaults to false, ie. no runtime override unless "time" is used for a float param.

Here's a simple example of a non-interactive shader as seen in the [[en:tutorials:spawners:spawner|spawner/shader tutorial]].

<code ini>[Decompose]
Code = "void main()
{
  float fRed, fGreen, fBlue;

  // Computes positions with offsets
  vec2 vRedPos    = vec2(gl_TexCoord[0].x + offset.x, gl_TexCoord[0].y + offset.y);
  vec2 vGreenPos  = vec2(gl_TexCoord[0].x, gl_TexCoord[0].y);
  vec2 vBluePos   = vec2(gl_TexCoord[0].x - offset.x, gl_TexCoord[0].y - offset.y);

  // Red pixel inside texture?
  if((vRedPos.x >= 0.0) && (vRedPos.x <= 1.0) && (vRedPos.y >= 0.0) && (vRedPos.y <= 1.0))
  {
    // Gets its value
    fRed = texture2D(texture, vRedPos).r;
  }

  // Green  pixel inside texture?
  if((vGreenPos.x >= 0.0) && (vGreenPos.x <= 1.0) && (vGreenPos.y >= 0.0) && (vGreenPos.y <= 1.0))
  {
    // Gets its value
    fGreen = texture2D(texture, vGreenPos).g;
  }

  // Blue pixel inside texture?
  if((vBluePos.x >= 0.0) && (vBluePos.x <= 1.0) && (vBluePos.y >= 0.0) && (vBluePos.y <= 1.0))
  {
    // Gets its value
    fBlue = texture2D(texture, vBluePos).b;
  }

  // Outputs the final decomposed pixel
  gl_FragColor = vec4(fRed, fGreen, fBlue, 1.0);
}"
ParamList = texture # offset
offset    = (-0.05, -0.05, 0.0) ~ (0.05, 0.05, 0.0); <= Let's take some random offset</code>

Please see the [[en:tutorials:main#spawners|Shader Tutorials]] and [[en:examples:shaders:main|Shader Examples]] for more information.

=== Overriding Parameters at Runtime with UseCustomParam ===

Shader parameters can be defined on the fly if 
<code>UseCustomParam = true</code> 
is set in your shader.  An event of type ''orxEVENT_TYPE_SHADER'' and ID ''orxSHADER_EVENT_SET_PARAM'' will be fired for all parameters and its payload will contain the name of the param and its default value. Event handler can then modify that value if need be, and it'll get used by the shader.

However, when UseCustomParam is defined to true, those objects can't be batched at rendering, making the rendering phase more expensive.
The severity of the processing penalty depends on how many affected objects are displayed.
See the test/playground code, orxBounce, for an example on how to set those shader parameters on the fly.

==== Shader Execution Environment ====

=== Using built-in 'time' keyword as parameter argument ===

"time" is a keyword recognized by orx: the parameter value will be the object's "age", in seconds. Example:

<code ini>
ParamList = fTime
fTime = time 
</code>

=== Using the internal 'pixel' texture ===

There is an internal texture called ''pixel''. It can be used to specify an image of arbitrary size when used with the Scale property of the object:

<code ini>
[Object]
Graphic = MyTexture
Scale = (16, 16, 1)
 
[MyTexture]
Texture = pixel
</code>

In the example above, an Object has a Graphic that will span over 16x16 pixels.


=== Coordinate System ===

Shaders contain implicit parameters containing owner's texture coordinates. For example:

<code ini>
[GameObject]
Graphic = @
Texture = ObjectTexture.png 
TextureOrigin = (16, 16, 0)
TextureSize = (8, 8, 0)
ShaderList = Shader

[Shader]
ParamList = MyTexture # ...
Code = ...
</code>

Then orx will generate extra parameters behind the scene regarding the texture MyTexture. The names follow the pattern:
<code>
<NameOfTexture>_top, <NameOfTexture>_left,
<NameOfTexture>_bottom, <NameOfTexture>_right
</code>

In the above example, the names will then be:
<code>
MyTexture_top, MyTexture_left, MyTexture_bottom, MyTexture_right
</code>

If MyTexture's dimensions are 32x32, we'd then get:
<code>
MyTexture_top = 16 / 32 => 0.5
MyTexture_left = 16 / 32 => 0.5
MyTexture_bottom = (16 + 8) / 32 => 0.75
MyTexture_right = (16 + 8) / 32 => 0.75
</code>


==== Latest config settings for the Development Version ====
{{section>en:orx:config:developmentversion#&noheader&nofooter&noeditbutton}}