John Kessenich | a0af473 | 2012-12-12 21:15:54 +0000 | [diff] [blame^] | 1 | OpenGL Shading Language source readme for Window and Linux |
| 2 | |
| 3 | Version: Sept 20, 2005 |
| 4 | |
| 5 | |
| 6 | Source Copyright |
| 7 | ---------------- |
| 8 | |
| 9 | |
| 10 | Copyright (C) 2002-2005 3Dlabs Inc. Ltd. |
| 11 | All rights reserved. |
| 12 | |
| 13 | Redistribution and use in source and binary forms, with or without |
| 14 | modification, are permitted provided that the following conditions |
| 15 | are met: |
| 16 | |
| 17 | Redistributions of source code must retain the above copyright |
| 18 | notice, this list of conditions and the following disclaimer. |
| 19 | |
| 20 | Redistributions in binary form must reproduce the above |
| 21 | copyright notice, this list of conditions and the following |
| 22 | disclaimer in the documentation and/or other materials provided |
| 23 | with the distribution. |
| 24 | |
| 25 | Neither the name of 3Dlabs Inc. Ltd. nor the names of its |
| 26 | contributors may be used to endorse or promote products derived |
| 27 | from this software without specific prior written permission. |
| 28 | |
| 29 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS |
| 30 | "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT |
| 31 | LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS |
| 32 | FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE |
| 33 | COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, |
| 34 | INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, |
| 35 | BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; |
| 36 | LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER |
| 37 | CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT |
| 38 | LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN |
| 39 | ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE |
| 40 | POSSIBILITY OF SUCH DAMAGE. |
| 41 | |
| 42 | Changes since June 2005 Release |
| 43 | ------------------------------- |
| 44 | - Some infrastructure is simplified, improved, and cleaned up. Details follow. |
| 45 | |
| 46 | - TPublicType is easier to setup and extend. |
| 47 | |
| 48 | - Constant values know their own types. Methods are added to set the |
| 49 | constant values as the data members are now protected instead of public. |
| 50 | Lots of code was cleaned up because of that. |
| 51 | |
| 52 | - Added support for an array object extension. Array constructors are |
| 53 | allowed. Constant arrays can be declared and parse time constant folding |
| 54 | and propagation is done through array objects. Extension GL_3DL_array_objects |
| 55 | must be enabled to use the array objects. |
| 56 | |
| 57 | - Arrays and structures are handled more uniformly. Sizing is simplified and improved. |
| 58 | |
| 59 | - Changed the implementation of the way constants values were stored in |
| 60 | the parse tree. Constants are now always flattened out. Constructors with |
| 61 | constant values are represented with constant values directly. Example mat2(1) |
| 62 | is stored as a constant node with values 1.0, 0.0, 0.0, 1.0. Earlier this |
| 63 | was stored as an aggregate node with correct operator and a single constant |
| 64 | value 1.0. This change caused a lot of code to be cleaned up and simplified. |
| 65 | |
| 66 | - Renamed ARB texture rectangle functions to match the final version of the specification. |
| 67 | |
| 68 | |
| 69 | Changes since Feb 2005 Release |
| 70 | ------------------------------ |
| 71 | - Source now compiles on gcc 3.4.4. |
| 72 | - Fixed constant folding for ternary operator. |
| 73 | - Non-dereferenced arrays not allowed in constructors. Other semantic |
| 74 | error checking on arrays such as ++array, array1 = array2. |
| 75 | - Max allowed index for gl_TexCoord is gl_MaxTextureCoords - 1. |
| 76 | - Raise an error when one of the string passed to the parser is a NULL |
| 77 | pointer. |
| 78 | - Parser code tested to be portable on STLport stl. |
| 79 | - Detect error when preprocessor directives does not begin at the start |
| 80 | of the line. |
| 81 | |
| 82 | Please feel free to submit any fixes to the parser code. |
| 83 | |
| 84 | |
| 85 | Changes since Jan 2005 Release |
| 86 | ------------------------------ |
| 87 | - Relaxed grammar rules for ?: (ternary operator) to allow assignment |
| 88 | expressions after the ':'. |
| 89 | - Fixed the correct parsing of empty shader source string. |
| 90 | - No longer raise an error when gl_Position is not written in a vertex |
| 91 | shader. This is link time functionality. |
| 92 | - Added some basic support for MSVC++6.0 to the extent that C++ standards |
| 93 | are not violated. |
| 94 | |
| 95 | |
| 96 | Changes since Sept 2004 Release |
| 97 | ------------------------------- |
| 98 | - Memory usage by builtIn symbol table level is reduced to 1/4th of what |
| 99 | was used earlier. |
| 100 | - Built In symbol table level is split into two, the first level contains |
| 101 | symbols that do not change and the second level is constructed per compile, |
| 102 | based on the resource values specified by the driver. This required ShCompile |
| 103 | method to take in a pointer to the resource values. |
| 104 | - Correct handling of pragmas. |
| 105 | - Fixed defects such as comma operator folding, swizzling allowed only with |
| 106 | offsets from same set, texture look up functions appropriately split between |
| 107 | vertex and fragment shaders, ternary operator type checking, preprocessor |
| 108 | directives etc. |
| 109 | - Linux build now use flex version 2.5.4 that comes with Redhat 9.0 |
| 110 | |
| 111 | |
| 112 | Changes since July 2004 Release |
| 113 | ------------------------------- |
| 114 | - Structures when initialized both as a constant and a non constant were broken. |
| 115 | |
| 116 | |
| 117 | Changes Since Apr 2004 Release |
| 118 | ------------------------------- |
| 119 | - Added support for #extension and #version preprocessor directives. |
| 120 | - Removed printf statements and instead dump messages on InfoSink. |
| 121 | - Most of the source code is now thread safe except for some of the |
| 122 | preprocessor code. Also For Linux, the per thread data clean up is yet to be |
| 123 | implemented as it is not exactly known when the thread exits. |
| 124 | - Fixed comma operator when used with constant initializer. |
| 125 | - Added folding when constructors are called with constant values. |
| 126 | - Correctly updated builtIn names for texture functions from |
| 127 | texture{1|2}DShadow[Proj][Lod] to shadow{1|2}D[Proj][Lod]. |
| 128 | - Updated the built-in constant names as per latest GL2 specs. |
| 129 | - Portable across more platforms. |
| 130 | |
| 131 | |
| 132 | Changes Since Oct 2003 Release |
| 133 | ------------------------------- |
| 134 | - Added new reserved keywords. Also reserved %=. |
| 135 | - Fixed some bugs and memory leaks in the preprocessor. |
| 136 | - Fixed name mangling for function names. Names also now include array sizes. |
| 137 | - Fixed implementation of unsized arrays. |
| 138 | - Constructors: Disallow matrices constructed from matrices, and unused |
| 139 | arguments. |
| 140 | Also fixed some cases like float(vec2) that were not working right. |
| 141 | - TILDA -> TILDE. |
| 142 | - Fixed structure qualifier semantics: they apply to variables declared, |
| 143 | not the structure definition. |
| 144 | |
| 145 | |
| 146 | Changes since May 2003 Release |
| 147 | ------------------------------- |
| 148 | |
| 149 | - Corrected some bugs in preprocessor. |
| 150 | - Keeping track of maximum size of the array used in the source code. |
| 151 | - Parameter passing during function call and keeping track of inout and out |
| 152 | parameters. |
| 153 | - Added some more built in functions. |
| 154 | - Portability to Linux |
| 155 | |
| 156 | |
| 157 | Changes Since April 2002 Release |
| 158 | -------------------------------- |
| 159 | |
| 160 | * Semantic changes to bring the implementation and spec closer together, |
| 161 | and support issue resolution. |
| 162 | |
| 163 | * Some minor functionality completeness. |
| 164 | |
| 165 | - User function calls are more complete, |
| 166 | - added the ^^ operator (logical exclusive or) |
| 167 | - fixed variable scoping in if-else |
| 168 | - no declarations in if-conditions |
| 169 | - improved typing of field selectors |
| 170 | - removed suffixes from literal constants |
| 171 | - many smaller semantic changes to be in line with the current spec |
| 172 | - added preprocessor |
| 173 | - added non-scalar constants |
| 174 | - added structures |
| 175 | |
| 176 | |
| 177 | Changes since July 2002 Release |
| 178 | ------------------------------- |
| 179 | |
| 180 | Brought up to date with version 1.051 of the OpenGL Shading Language |
| 181 | Specification. It is now almost complete. The list of detailed |
| 182 | changes would be long, as the specification has changed extensively, |
| 183 | and all missing functionality has been added. |
| 184 | |
| 185 | |
| 186 | Procedure to Build on Windows |
| 187 | ----------------------------- |
| 188 | |
| 189 | Put this project in a path name without spaces. |
| 190 | |
| 191 | procedure To build using MS visual studio .Net. |
| 192 | |
| 193 | It has two projects. |
| 194 | The glslang project must be compiled first, followed by the |
| 195 | StandAlone project. |
| 196 | |
| 197 | 1. The solution is StandAlone.sln. The two necessary |
| 198 | projects are glslang.vcproj and StandAlone.vcproj, |
| 199 | which devstudio will automatically open. |
| 200 | |
| 201 | 2. You may have a missing header file, unistd.h. Create an empty one in |
| 202 | some standard devstudio or SDK system include directory. (Bison/flex |
| 203 | generate a #include <unistd.h>, this makes them happy.) |
| 204 | |
| 205 | 3. Build the glslang project (in devstudio, right click the glslang project |
| 206 | and build). This creates the glslang.dll and glslang.lib files needed to |
| 207 | make the StandAlone compiler run. It leaves them in the StandAlone |
| 208 | directory. |
| 209 | |
| 210 | 4. Build the StandAlone project if you want to run the tests or run the |
| 211 | compiler stand-alone. |
| 212 | |
| 213 | |
| 214 | Running Stand Alone on Windows |
| 215 | ------------------------------ |
| 216 | |
| 217 | The build process should create glslang.dll and StandAlone.exe. glslang.dll |
| 218 | has an interface suitable for integration with an ICD. StandAlone.exe uses |
| 219 | this interface to create a version of the compiler that can run outside |
| 220 | the ICD environment. |
| 221 | |
| 222 | The stand-alone compiler is a Win32 console application, best executed |
| 223 | from a command prompt. |
| 224 | |
| 225 | cd into the StandAlone directory, or a directory you've installed |
| 226 | StandAlone.exe, the OglBuiltIns subdirectory, and glslang.dll into. |
| 227 | |
| 228 | The normal case will be to compile and link a pair of shaders like this: |
| 229 | |
| 230 | StandAlone -i <vertex-file>.vert <fragment-file>.frag |
| 231 | |
| 232 | where the following command line options are possible for StandAlone: |
| 233 | i - dump parse tree |
| 234 | m - dump linker output (nothing dumped in the source code provided) |
| 235 | a - dump assembly code (nothing dumped in the source code provided) |
| 236 | |
| 237 | The applied compilation-language is based on the file extension. |
| 238 | Give the full name of the files containing the shader source code. |
| 239 | The output from running this will contain compile and link errors, as |
| 240 | well as a textual version of the intermediate representation. |
| 241 | |
| 242 | |
| 243 | Procedure to build and run on Linux |
| 244 | ----------------------------------- |
| 245 | |
| 246 | A simple bash script "BuildLinux.sh" is provided to do the build and run the test |
| 247 | cases, or you may run the steps manually as described below: |
| 248 | |
| 249 | "cd" into StandAlone directory and run make. It will build all the dependency |
| 250 | directories also. You can also go to the specific directories and do a make for each |
| 251 | directory individually. Make sure that there exists a lib directory at the given |
| 252 | path: glslang/MachineIndependent/lib where libglslang.so is stored. |
| 253 | |
| 254 | To compile glslang.l, flex version 2.5.31 is required. An executable of flex is |
| 255 | provided in tools directory. To compile glslang.y, bison version 1.35 or higher is |
| 256 | required. Most versions of Red Hat comes with bison 1.35. |
| 257 | |
| 258 | Once the executable is generated, it needs to be dynamically linked with the |
| 259 | shared object created in lib directory. To achieve that, we need to "cd" to |
| 260 | StandAlone directory to update the LD_LIBRARY_PATH as follows |
| 261 | |
| 262 | export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:./../glslang/MachineIndependent/lib |
| 263 | |
| 264 | You can also update LD_LIBRARY_PATH in the .cshrc or .bashrc file, depending on |
| 265 | the shell you are using. You will need to give the complete path of "lib" directory |
| 266 | in .cshrc or .bashrc files. |
| 267 | |
| 268 | The normal case will be to compile and link a pair of shaders like this: |
| 269 | |
| 270 | ./StandAlone -i <vertex-file>.vert <fragment-file>.frag |
| 271 | |
| 272 | where the following command line options are possible for StandAlone: |
| 273 | i - dump parse tree |
| 274 | m - dump linker output (nothing dumped in the source code provided) |
| 275 | a - dump assembly code (nothing dumped in the source code provided) |
| 276 | |
| 277 | The applied compilation-language is based on the file extension. |
| 278 | Give the full name of the files containing the shader source code. |
| 279 | The output from running this will contain compile and link errors, as |
| 280 | well as a textual version of the intermediate representation. |
| 281 | |
| 282 | To generate the dependencies, you can run "make depend". |
| 283 | This step has already been done and need not be done again by the user. |
| 284 | |
| 285 | To clean the ".o"s, ".a"s and ".so" generated by make, you can use "make clean". |
| 286 | |
| 287 | |
| 288 | Notes for Understanding/Modifying the Code |
| 289 | ------------------------------------------ |
| 290 | |
| 291 | * This is completely machine independent code. We have a working |
| 292 | back-end card-specific compiler that is not present. Instead, a trivial |
| 293 | back-end compiler is in the directory GenericCodeGen. |
| 294 | |
| 295 | * The main directory for parsing and intermediate representation is |
| 296 | MachineIndependent. |
| 297 | |
| 298 | * Header files shared between machine independent parsing and the |
| 299 | machine dependent compiling and linking are in include. |
| 300 | |
| 301 | * Header files shared between the compiler and an ICD are in public. |
| 302 | |
| 303 | * Merging with future updates will be easiest if initially you confine |
| 304 | your changes to the GenericCodeGen directory. |
| 305 | |
| 306 | * To write a back-end compiler, see the next section on Basic Design. |
| 307 | |
| 308 | |
| 309 | Basic Design |
| 310 | ------------ |
| 311 | |
| 312 | 1. Code is parsed by flex/bison, with the aid of a symbol table and an |
| 313 | intermediate representation. The symbol table is not passed on to |
| 314 | the back-end; the intermediate representation stands on its own. |
| 315 | |
| 316 | 2. The intermediate representation is very high-level, and represented |
| 317 | as an in-memory tree. This serves to lose no information from the |
| 318 | original program, and to have efficient transfer of the result from |
| 319 | parsing to the back-end. In the intermediate representation, |
| 320 | constants are propogated and folded, and some dead code is eliminated. |
| 321 | |
| 322 | 3. The primary algorithm of the back-end compiler is to traverse the |
| 323 | tree (high-level intermediate representation), and create an internal |
| 324 | object code representation. There is a query in the compiler interface |
| 325 | to the ICD for retrieval of this object code. |
| 326 | |
| 327 | 4. Reduction of the tree to a linear byte-code style low-level intermediate |
| 328 | representation is likely a good way to generate fully optimized code. |
| 329 | There is some possibility of standardizing such a byte code. |
| 330 | |
| 331 | See these files to get started: |
| 332 | |
| 333 | * IntermOut.cpp: this shows traversing the tree to generate output. |
| 334 | * CodeGen.cpp: this shows the basic interface to the back-end compiler. |
| 335 | * Link.cpp: this shows the basic interface to the linker. |
| 336 | * Intermediate.h: to see the data structures backing the tree. |
| 337 | |