############################
The GPU Programming Pipeline
############################

.. toctree::
    :maxdepth: 1
    :titlesonly:
    :hidden:

    bk_bm_wcrs_gpp/bk_bm_custom_custom_gpu_arb
    bk_bm_wcrs_gpp/bk_bm_custom_custom_gpu_glsl


**************************
The Shader Pipeline Stages
**************************

The shader programming pipeline is composed of three customizable stages:

    * The vertex program
    * The geometry program
    * The pixel program

.. figure:: bk_bm_cc_gpu_stages_01.png
    :align: center
    
    **The programming shader pipeline stages**

*Vertex Programs*
=================

The vertex program is the first stage of the pipeline. His goal is:

    * To receive the mesh geometry data (vertex position, normal, etc.). It works on individual vertices
    * To transform the vertex position from world space to clip space using the corresponding matrix: world * view * projection
    * To transfer the pertinent data to the next stage of the pipeline (geometry or pixel program)

*Geometry Programs*
===================

The geometry shaders are executed after the vertex stage and before the pixel stage. They allow to modify the mesh topology by changing the polygons or by creating new ones. The input data of the program is a geometry primitive (point, line or triangle) and it sends one or more other primitives to the next pipeline stage.

.. note:: 

    This stage is optional, if no geometry program is defined, the data will transit directly from the vertex program to the pixel program. 
    
*Pixel Programs*
================

The pixel or fragment shader program is the last step of the pipeline. It receives data of each pixel individually (position, texture coordinates, color, etc.) and its goal is to calculate the final output color of the pixel.

*****************
Shading Languages
*****************

The Red engine may use any version of vertex and pixel shader program that is above the VS and PS 2.0 versions. These programs must be either ARB or GLSL compliant shader programs. A faulty shader programs will pop a warning panel once and then all geometries that must be rendered with it will be ignored.

Available later in this guide is a quick reference for the ARB assembly shader language. Due to the explosive program combinations possible with shaders, we recommend using the ``RED::ShaderString`` class to write a shader program: it packages all the most common operations for all supported RED engine platforms (namely ATI and NVIDIA cards, as of the HOOPS Luminate v1.0) and contains all the necessary code to handle all the possible shader targets. Use of the ``RED::ShaderString`` implies to play with shaders at the assembly level. We recommend using shaders at the assembly level. This may scare you a little but practically, shader assembly is easy to learn, it has the best rendering performances and is the most hardware reliable. Because these programs don't use a compiler, they have no compiler bugs...

.. include:: /tasks/ta_ca/ta_ca_material/tk_writing_a_custom_render_shader.rst
