.. index::
    pair: Shader; Pipeline

===================
The Shader Pipeline
===================

We support conversion of the `CgFX <http://http.developer.nvidia.com/CgTutorial/cg_tutorial_appendix_c.html>`_ shader file format to our internal format.
For the broadest compatiblity we recommend targeting the `OpenGL ES 2.0 feature set <http://www.khronos.org/opengles/2_X/>`_
in order to be compatible with the WebGL and our compatibility mode.

We provide a tool for :ref:`converting CGFX shaders <convert-cgfx-2json>` to the Turbulenz Engine Shader format.

For a given CgFX file the :ref:`cgfx2json <cgfx2json>` tool will create a JSON file containing a shader definition:

* Techniques
* Programs code
* Render states
* Sampler states
* Global shader parameters
* Input semantics for vertex programs

Shader parameter semantics are ignored by the :ref:`cgfx2json <cgfx2json>` tool,
parameters will be matched at runtime by the variable name.

It is recommended that the CgFX file compiles program code either into GLSL profiles or into 'latest'.

For more information about the CgFX file format please read the `NVidia tutorial <http://http.developer.nvidia.com/CgTutorial/cg_tutorial_appendix_c.html>`_.

For more information about JSON please visit `json.org <http://json.org/>`_.

---------
Workflows
---------

Loading a shader definition file
--------------------------------

1. Create CgFX file with shader editor.
2. Execute :ref:`cgfx2json <cgfx2json>` on each CgFX file to generate a JSON file containing the shader definition.
3. Load contents of JSON file at runtime as a JSON string.
4. Execute ``JSON.parse`` on the JSON string to create a JavaScript object.
5. Create runtime Shader object by passing the JavaScript object to ``GraphicsDevice.createShader``.

Inlining a shader definition
----------------------------

Steps 1 and 2 as on the loading case.

3. Copy and paste contents of JSON file to your JavaScript code assigning it to a variable.
4. Create runtime Shader object by passing the variable to ``GraphicsDevice.createShader``.

This workflow is less flexible than loading the shader definition file at runtime but it avoids the added latency
of requesting the file.
The CPU cost of parsing the JSON string from the JSON file to create a JavaScript object
is about the same as the cost of parsing and executing the JavaScript code that contains the shader definition.