From 2c99cfb3092f0b4c6c89bda91bb713bcb7e6087d Mon Sep 17 00:00:00 2001
From: Bergmann89 <info@bergmann89.de>
Date: Mon, 21 Sep 2015 16:50:13 +0200
Subject: [PATCH] * [docu] added description and examples for shader file,
 class, procedure, function and main

---
 doc/docu.xhtml                     | 280 +++++++++++++++++++++++++----
 library/header/examples/color.shdr |   3 +
 2 files changed, 250 insertions(+), 33 deletions(-)

diff --git a/doc/docu.xhtml b/doc/docu.xhtml
index 174f636..f4df625 100644
--- a/doc/docu.xhtml
+++ b/doc/docu.xhtml
@@ -5,9 +5,18 @@
         <meta name="generator" content="Railroad Diagram Generator 1.40.1033" />
         <style type="text/css">
             body                            { font-family: 'Calibri', 'Arial'; color: #0F0C00; background: #FFFCF0 }
+            pre                             { margin: 0 }
             .code                           { font-family: 'Courier New' }
             .code.area                      { padding: 5px; background-color: #EEEEEE; font-size: 0.8em }
-            a                               { text-decoration: none; color: #0F0C00 }
+            .code .pre                      { color: #006666; font-weight: bold }
+            .code .comment                  { color: #006600 }
+            .code .buildin                  { color: #6B0000 }
+            .code .func                     { color: #6B0000; font-weight: bold }
+            .code .type                     { color: #000000; font-weight: bold }
+            .code .keyword                  { color: #000099; font-weight: bold }
+            .code .number                   { color: #000099 }
+            .code.area div                  { padding-left: 2em }
+            a                               { text-decoration: none; color: inherit }
             a:hover                         { text-decoration: underline }
             .box .head                      { cursor: pointer }
             .box .head:hover                { background-color: #EEEEEE }
@@ -209,21 +218,9 @@
                     <h4>Description:</h4>
                 </div>
                 <div class="content">
-                    asdasdasd
-                    asdasdasdasd
-                    asdasdasdasdasd
-                    asdasdasdasdasd
-                </div>
-            </div>
-
-            <div class="box closed">
-                <div class="head">
-                    <div class="noselect icon open">+</div>
-                    <div class="noselect icon close">-</div>
-                    <h4>Example:</h4>
-                </div>
-                <div class="content code area">
-                    haghgwpoigh ogpog
+                    Inside the shader file you define every needed OpenGL shader code, meta information and precompiler instructions you need. The precompiler then interprets your code and generate the normal OpenGL shader code for you. It will take care, that only the needed code parts are added to the resulting code, so the shader code is always as simple and small as needed.<br/>
+                    The shader file is also a code generator. It's name is a empty string. So if you pass the empty string to the code generator creator function you will get the code generator for the whole file.<br/>
+                    A class does not need a <a href="#Main">{$MAIN}</a> method.
                 </div>
             </div>
 
@@ -274,6 +271,37 @@
                     </div>
                 </div>
             </div>
+
+            <div class="box closed">
+                <div class="head">
+                    <div class="noselect icon open">+</div>
+                    <div class="noselect icon close">-</div>
+                    <h4>Example:</h4>
+                </div>
+                <div class="content">
+                    "Hello World" example:
+                    <div class="code area">
+                        <span class="pre">{$MAIN}</span>
+                        <br/>
+                        <div>
+                            <span class="buildin">gl_Position</span> = <span class="buildin">gl_ModelViewProjectionMatrix</span> * <span class="buildin">gl_Vertex</span>;<br/>
+                            <span class="buildin">gl_FrontColor</span> = <span class="buildin">gl_Color</span>;<br/>
+                        </div>
+                        <span class="pre">{$END}</span>
+                    </div>
+                    <br/>
+                    resulting code:
+                    <div class="code area">
+                        <span class="type">void</span> main(<span class="type">void</span>)<br/>
+                        {<br/>
+                        <div>
+                            <span class="buildin">gl_Position</span> = <span class="buildin">gl_ModelViewProjectionMatrix</span> * <span class="buildin">gl_Vertex</span>;<br/>
+                            <span class="buildin">gl_FrontColor</span> = <span class="buildin">gl_Color</span>;<br/>
+                        </div>
+                        }
+                    </div>
+                </div>
+            </div>
         </div>
 
         <!-- Class -->
@@ -287,7 +315,9 @@
                     <h4>Description:</h4>
                 </div>
                 <div class="content">
-                    TODO
+                    A class is a logical wrapper to summarize OpenGL shader code, meta information and precompiler instructions. You can inherit a class from other classes using the $EXTENDS token. The precompiler then interprets your code and generate the normal OpenGL shader code for you. It will take care, that only the needed code parts are added to the resulting code, so the shader code is always as simple and small as needed.<br/>
+                    A class is always a generator. If you use the name of class as parameter for the code generator creator function you will get a code generator for the requested class.<br/>
+                    A class or one of its parent classes always needs a <a href="#Main">{$MAIN}</a> method.
                 </div>
             </div>
 
@@ -370,8 +400,106 @@
                     <div class="noselect icon close">-</div>
                     <h4>Example:</h4>
                 </div>
-                <div class="content code area">
-                    TODO
+                <div class="content">
+                    example for a simple shader that uses either a solid color or a texture:
+                    <div class="code area">
+                        <span class="pre">{<a href="#ebnfClass">$CLASS</a> Color}</span>
+                        <br/>
+                        <div>
+                            <span class="pre">{<a href="#ebnfProperty">$PROPERTY</a> UseColorMap 'false'}</span>
+                            <br/>
+                        </div>
+                        <span class="pre">{$END}</span>
+                        <br/>
+                        <br/>
+                        <span class="pre">{<a href="#ebnfClass">$CLASS</a> ColorFrag $EXTENDS Color}</span>
+                        <br/>
+                        <div>
+                            <br/>
+                            <span class="comment">/* you can also define code here. It will be added when the code for the class is generated */</span>
+                            <br/>
+                            <br/>
+                            <span class="pre">{<a href="#ebnfClassFunction">$FUNC</a> 'vec4' GetColor $INLINE}</span>
+                            <br/>
+                            <div>
+                                <span class="pre">{<a href="#ebnfIf">$IF</a> UseColorMap}</span>
+                                <br/>
+                                <div>
+                                    <span class="pre">{<a href="#ebnfVar">$VAR</a> 'vec2' '_texCoord' 'gl_TexCoord[0].st'}</span>
+                                    <br/>
+                                    <span class="pre">{<a href="#ebnfUniform">$UNIFORM</a> 'sampler2D' 'uColorMap'}</span>
+                                    <br/>
+                                    <span class="keyword">return</span>
+                                    <span class="func">texture2D</span>(uColorMap, _texCoord);<br/>
+                                </div>
+                                <span class="pre">{<a href="#ebnfIf">$ELSE</a>}</span>
+                                <br/>
+                                <div>
+                                    <span class="keyword">return</span>
+                                    <span class="buildin">gl_Color</span>;<br/>
+                                </div>
+                                <span class="pre">{$END}</span>
+                                <br/>
+                            </div>
+                            <span class="pre">{$END}</span>
+                            <br/>
+                            <br/>
+                            <span class="pre">{<a href="#ebnfClassMain">$MAIN</a>}</span>
+                            <br/>
+                            <div>
+                                <span class="buildin">gl_FragColor</span> = <span class="pre">{<a href="#ebnfCall">$CALL</a> GetColor}</span>;<br/>
+                            </div>
+                            <span class="pre">{$END}</span>
+                            <br/>
+                        </div>
+                        <span class="pre">{$END}</span>
+                        <br/>
+                        <br/>
+                        <span class="pre">{<a href="#ebnfClass">$CLASS</a> ColorVert $EXTENDS Color}</span>
+                        <br/>
+                        <div>
+                            <span class="pre">{<a href="#ebnfClassMain">$MAIN</a>}</span>
+                            <br/>
+                            <div>
+                                <span class="buildin">gl_Position</span> = <span class="buildin">gl_ModelViewProjectionMatrix</span> * <span class="buildin">gl_Vertex</span>;<br/>
+                                <span class="pre">{<a href="#ebnfIf">$IF</a> UseColorMap}</span>
+                                <br/>
+                                <div>
+                                    <span class="buildin">gl_TexCoord</span>[<span class="number">0</span>] = <span class="buildin">gl_MultiTexCoord0</span>;<br/>
+                                </div>
+                                <span class="pre">{<a href="#ebnfIf">$ELSE</a>}</span>
+                                <br/>
+                                <div>
+                                    <span class="buildin">gl_FrontColor</span> = <span class="buildin">gl_Color</span>;<br/>
+                                    <span class="buildin">gl_BackColor</span> = <span class="buildin">gl_Color</span>;<br/>
+                                </div>
+                                <span class="pre">{$END}</span>
+                                <br/>
+                            </div>
+                            <span class="pre">{$END}</span>
+                            <br/>
+                        </div>
+                        <span class="pre">{$END}</span>
+                        <br/>
+                    </div>
+                    <br/>
+                    resulting code for ColorFrag with UseColorMap = true
+                    <div class="code area">
+                        <span class="comment">/* you can also define code here. It will be added when the code for the class is generated */</span>
+                        <br/>
+                        <br/>
+                        <span class="keyword">uniform</span>
+                        <span class="type">sampler2D</span> uColorMap;<br/>
+                        <br/>
+                        <span class="type">vec2</span> _texCoord = <span class="buildin">gl_TexCoord</span>[<span class="number">0</span>].st;<br/>
+                        <br/>
+                        <span class="type">void</span> main(<span class="type">void</span>)<br/>
+                    {<br/>
+                        <div>
+                            <span class="buildin">gl_FragColor</span> = (<span class="func">texture2D</span>(uColorMap, _texCoord));<br/>
+                        </div>
+                    }
+                    </div>
                 </div>
             </div>
         </div>
@@ -387,7 +515,9 @@
                     <h4>Description:</h4>
                 </div>
                 <div class="content">
-                    TODO
+                    The procedure token will generate a normal procedure in the resulting code, when the procedure is at least used one time inside a <a href="#Call">{$CALL}</a>.
+                    Inside a class you can add the $INLINE token. If the $INLINE token is added the code inside the procedure will be copied and pasted inside the resulting code.<br/>
+                    Be careful with inlined methods, because the precompiler will not check the variable names inside the method, so you maybe have a duplicate variable when it is pasted inside the resulting code.
                 </div>
             </div>
 
@@ -530,8 +660,38 @@
                     <div class="icon close">-</div>
                     <h4>Example:</h4>
                 </div>
-                <div class="content code area">
-                    TODO
+                <div class="content">
+                    simple example:
+                    <div class="code area">
+                        <span class="pre">{$PROC setFragColor 'vec2' 'texCoord'}</span>
+                        <br/>
+                        <div>
+                            <span class="pre">{$UNIFORM 'sampler2D' 'uColorMap'}</span>
+                            <br/>
+                            <span class="type">vec4</span> color = <span class="func">texture2D</span>(uColorMap, texCoord);<br/>
+                            <span class="buildin">gl_FragColor</span> = color;<br/>
+                        </div>
+                        <span class="pre">{$END}</span>
+                        <br/>
+                        <br/>
+                        <span class="pre">{$CALL setFragColor 'gl_TexCoord[0].st'}</span>;
+                    </div>
+                    <br/>
+                    resulting code:
+                    <div class="code area">
+                        <span class="keyword">uniform</span>
+                        <span class="type">sampler2D</span> uColorMap;<br/>
+                        <br/>
+                        <span class="type">void</span> setFragColor(<span class="type">vec2</span> texCoord)<br/>
+                        {<br/>
+                        <div>
+                            <span class="type">vec4</span> color = <span class="func">texture2D</span>(uColorMap, texCoord);<br/>
+                            <span class="buildin">gl_FragColor</span> = color;<br/>
+                        </div>
+                        }<br/>
+                        <br/>
+                        setFragColor(<span class="buildin">gl_TexCoord</span>[<span class="number">0</span>].st);
+                    </div>
                 </div>
             </div>
         </div>
@@ -547,7 +707,9 @@
                     <h4>Description:</h4>
                 </div>
                 <div class="content">
-                    TODO
+                    The function token will generate a normal function in the resulting code, when the function is at least used one time inside a <a href="#Call">{$CALL}</a>.
+                    Inside a class you can add the $INLINE token. If the $INLINE token is added the code inside the function will be copied and pasted inside the resulting code.<br/>
+                    Be careful with inlined methods, because the precompiler will not check the variable names inside the method, so you maybe have a duplicate variable when it is pasted inside the resulting code.
                 </div>
             </div>
 
@@ -695,8 +857,40 @@
                     <div class="icon close">-</div>
                     <h4>Example:</h4>
                 </div>
-                <div class="content code area">
-                    TODO
+                <div class="content">
+                    simple example:
+                    <div class="code area">
+                        <span class="pre">{$FUNC 'vec4' 'getColor'}</span>
+                        <br/>
+                        <div>
+                            <span class="pre">{$UNIFORM 'sampler2D' 'uColorMap'}</span>
+                            <br/>
+                            <span class="type">vec2</span> texCoord = <span class="buildin">gl_TexCoord</span>[<span class="number">0</span>].st;<br/>
+                            <span class="keyword">return</span>
+                            <span class="func">texture2D</span>(uColorMap, texCoord);<br/>
+                        </div>
+                        <span class="pre">{$END}</span>
+                        <br/>
+                        <br/>
+                        <span class="buildin">gl_FragColor</span> = <span class="pre">{$CALL getColor}</span>;
+                    </div>
+                    <br/>
+                    resulting code:
+                    <div class="code area">
+                        <span class="keyword">uniform</span>
+                        <span class="type">sampler2D</span> uColorMap;<br/>
+                        <br/>
+                        <span class="type">vec4</span> getColor()<br/>
+                        {<br/>
+                        <div>
+                            <span class="type">vec2</span> texCoord = <span class="buildin">gl_TexCoord</span>[<span class="number">0</span>].st;<br/>
+                            <span class="keyword">return</span>
+                            <span class="func">texture2D</span>(uColorMap, texCoord);<br/>
+                        </div>
+                        }<br/>
+                        <br/>
+                        <span class="buildin">gl_FragColor</span> = getColor();
+                    </div>
                 </div>
             </div>
         </div>
@@ -712,7 +906,7 @@
                     <h4>Description:</h4>
                 </div>
                 <div class="content">
-                    TODO
+                    The $MAIN token is a special procedure without parameters that will be called automatically by the pre compiler, when the code is generated. The $MAIN token is necessary inside a class and optional inside a shader file.
                 </div>
             </div>
 
@@ -794,15 +988,35 @@
                         </div>
                     </div>
                 </div>
+            </div>
 
-                <div class="box closed">
-                    <div class="head">
-                        <div class="icon open">+</div>
-                        <div class="icon close">-</div>
-                        <h4>Example:</h4>
+            <div class="box closed">
+                <div class="head">
+                    <div class="noselect icon open">+</div>
+                    <div class="noselect icon close">-</div>
+                    <h4>Example:</h4>
+                </div>
+                <div class="content">
+                    simple example:
+                    <div class="code area">
+                        <span class="pre">{$MAIN}</span>
+                        <br/>
+                        <div>
+                            <span class="buildin">gl_Position</span> = <span class="buildin">gl_ModelViewProjectionMatrix</span> * <span class="buildin">gl_Vertex</span>;<br/>
+                            <span class="buildin">gl_FrontColor</span> = <span class="buildin">gl_Color</span>;<br/>
+                        </div>
+                        <span class="pre">{$END}</span>
                     </div>
-                    <div class="content code area">
-                            TODO
+                    <br/>
+                    resulting code:
+                    <div class="code area">
+                        <span class="type">void</span> main(<span class="type">void</span>)<br/>
+                        {<br/>
+                        <div>
+                            <span class="buildin">gl_Position</span> = <span class="buildin">gl_ModelViewProjectionMatrix</span> * <span class="buildin">gl_Vertex</span>;<br/>
+                            <span class="buildin">gl_FrontColor</span> = <span class="buildin">gl_Color</span>;<br/>
+                        </div>
+                        }
                     </div>
                 </div>
             </div>
diff --git a/library/header/examples/color.shdr b/library/header/examples/color.shdr
index 294eeb3..31d7805 100644
--- a/library/header/examples/color.shdr
+++ b/library/header/examples/color.shdr
@@ -3,6 +3,9 @@
 {$END}
 
 {$CLASS ColorFrag $EXTENDS Color}
+    
+    /* you can also define code here. It will be added when the code for the class is generated */
+    
     {$FUNC 'vec4' GetColor $INLINE}
         {$IF UseColorMap}
             {$VAR 'vec2' '_texCoord' 'gl_TexCoord[0].st'}