Subversion Repositories Kolibri OS

Rev

Blame | Last modification | View Log | RSS feed

  1. <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
  2. <html lang="en">
  3. <head>
  4.   <meta http-equiv="content-type" content="text/html; charset=utf-8">
  5.   <title>Shading Language Support</title>
  6.   <link rel="stylesheet" type="text/css" href="mesa.css">
  7. </head>
  8. <body>
  9.  
  10. <div class="header">
  11.   <h1>The Mesa 3D Graphics Library</h1>
  12. </div>
  13.  
  14. <iframe src="contents.html"></iframe>
  15. <div class="content">
  16.  
  17. <h1>Shading Language Support</h1>
  18.  
  19. <p>
  20. This page describes the features and status of Mesa's support for the
  21. <a href="http://opengl.org/documentation/glsl/">
  22. OpenGL Shading Language</a>.
  23. </p>
  24.  
  25. <p>
  26. Contents
  27. </p>
  28. <ul>
  29. <li><a href="#envvars">Environment variables</a>
  30. <li><a href="#support">GLSL 1.40 support</a>
  31. <li><a href="#unsup">Unsupported Features</a>
  32. <li><a href="#notes">Implementation Notes</a>
  33. <li><a href="#hints">Programming Hints</a>
  34. <li><a href="#standalone">Stand-alone GLSL Compiler</a>
  35. <li><a href="#implementation">Compiler Implementation</a>
  36. <li><a href="#validation">Compiler Validation</a>
  37. </ul>
  38.  
  39.  
  40. <h2 id="envvars">Environment Variables</h2>
  41.  
  42. <p>
  43. The <b>MESA_GLSL</b> environment variable can be set to a comma-separated
  44. list of keywords to control some aspects of the GLSL compiler and shader
  45. execution.  These are generally used for debugging.
  46. </p>
  47. <ul>
  48. <li><b>dump</b> - print GLSL shader code to stdout at link time
  49. <li><b>log</b> - log all GLSL shaders to files.
  50.    The filenames will be "shader_X.vert" or "shader_X.frag" where X
  51.    the shader ID.
  52. <li><b>nopt</b> - disable compiler optimizations
  53. <li><b>opt</b> - force compiler optimizations
  54. <li><b>uniform</b> - print message to stdout when glUniform is called
  55. <li><b>nopvert</b> - force vertex shaders to be a simple shader that just transforms
  56.    the vertex position with ftransform() and passes through the color and
  57.    texcoord[0] attributes.
  58. <li><b>nopfrag</b> - force fragment shader to be a simple shader that passes
  59.    through the color attribute.
  60. <li><b>useprog</b> - log glUseProgram calls to stderr
  61. </ul>
  62. <p>
  63. Example:  export MESA_GLSL=dump,nopt
  64. </p>
  65.  
  66.  
  67. <h2 id="support">GLSL Version</h2>
  68.  
  69. <p>
  70. The GLSL compiler currently supports version 1.40 of the shading language.
  71. </p>
  72.  
  73. <p>
  74. Several GLSL extensions are also supported:
  75. </p>
  76. <ul>
  77. <li>GL_ARB_draw_buffers
  78. <li>GL_ARB_fragment_coord_conventions
  79. <li>GL_ARB_shader_bit_encoding
  80. </ul>
  81.  
  82.  
  83. <h2 id="unsup">Unsupported Features</h2>
  84.  
  85. <p>XXX update this section</p>
  86.  
  87. <p>
  88. The following features of the shading language are not yet fully supported
  89. in Mesa:
  90. </p>
  91.  
  92. <ul>
  93. <li>Linking of multiple shaders does not always work.  Currently, linking
  94.    is implemented through shader concatenation and re-compiling.  This
  95.    doesn't always work because of some #pragma and preprocessor issues.
  96. <li>The gl_Color and gl_SecondaryColor varying vars are interpolated
  97.     without perspective correction
  98. </ul>
  99.  
  100. <p>
  101. All other major features of the shading language should function.
  102. </p>
  103.  
  104.  
  105. <h2 id="notes">Implementation Notes</h2>
  106.  
  107. <ul>
  108. <li>Shading language programs are compiled into low-level programs
  109.     very similar to those of GL_ARB_vertex/fragment_program.
  110. <li>All vector types (vec2, vec3, vec4, bvec2, etc) currently occupy full
  111.     float[4] registers.
  112. <li>Float constants and variables are packed so that up to four floats
  113.     can occupy one program parameter/register.
  114. <li>All function calls are inlined.
  115. <li>Shaders which use too many registers will not compile.
  116. <li>The quality of generated code is pretty good, register usage is fair.
  117. <li>Shader error detection and reporting of errors (InfoLog) is not
  118.     very good yet.
  119. <li>The ftransform() function doesn't necessarily match the results of
  120.    fixed-function transformation.
  121. </ul>
  122.  
  123. <p>
  124. These issues will be addressed/resolved in the future.
  125. </p>
  126.  
  127.  
  128. <h2 id="hints">Programming Hints</h2>
  129.  
  130. <ul>
  131. <li>Use the built-in library functions whenever possible.
  132.    For example, instead of writing this:
  133. <pre>
  134.        float x = 1.0 / sqrt(y);
  135. </pre>
  136.    Write this:
  137. <pre>
  138.        float x = inversesqrt(y);
  139. </pre>
  140. </li>
  141. </ul>
  142.  
  143.  
  144. <h2 id="standalone">Stand-alone GLSL Compiler</h2>
  145.  
  146. <p>
  147. The stand-alone GLSL compiler program can be used to compile GLSL shaders
  148. into low-level GPU code.
  149. </p>
  150.  
  151. <p>
  152. This tool is useful for:
  153. </p>
  154. <ul>
  155. <li>Inspecting GPU code to gain insight into compilation
  156. <li>Generating initial GPU code for subsequent hand-tuning
  157. <li>Debugging the GLSL compiler itself
  158. </ul>
  159.  
  160. <p>
  161. After building Mesa, the compiler can be found at src/glsl/glsl_compiler
  162. </p>
  163.  
  164. <p>
  165. Here's an example of using the compiler to compile a vertex shader and
  166. emit GL_ARB_vertex_program-style instructions:
  167. </p>
  168. <pre>
  169.     src/glsl/glsl_compiler --dump-ast myshader.vert
  170. </pre>
  171.  
  172. Options include
  173. <ul>
  174. <li><b>--dump-ast</b> - dump GPU code
  175. <li><b>--dump-hir</b> - dump high-level IR code
  176. <li><b>--dump-lir</b> - dump low-level IR code
  177. <li><b>--link</b> - ???
  178. </ul>
  179.  
  180.  
  181. <h2 id="implementation">Compiler Implementation</h2>
  182.  
  183. <p>
  184. The source code for Mesa's shading language compiler is in the
  185. <code>src/glsl/</code> directory.
  186. </p>
  187.  
  188. <p>
  189. XXX provide some info about the compiler....
  190. </p>
  191.  
  192. <p>
  193. The final vertex and fragment programs may be interpreted in software
  194. (see prog_execute.c) or translated into a specific hardware architecture
  195. (see drivers/dri/i915/i915_fragprog.c for example).
  196. </p>
  197.  
  198. <h3>Code Generation Options</h3>
  199.  
  200. <p>
  201. Internally, there are several options that control the compiler's code
  202. generation and instruction selection.
  203. These options are seen in the gl_shader_state struct and may be set
  204. by the device driver to indicate its preferences:
  205.  
  206. <pre>
  207. struct gl_shader_state
  208. {
  209.    ...
  210.    /** Driver-selectable options: */
  211.    GLboolean EmitHighLevelInstructions;
  212.    GLboolean EmitCondCodes;
  213.    GLboolean EmitComments;
  214. };
  215. </pre>
  216.  
  217. <dl>
  218. <dt>EmitHighLevelInstructions</dt>
  219. <dd>
  220. This option controls instruction selection for loops and conditionals.
  221. If the option is set high-level IF/ELSE/ENDIF, LOOP/ENDLOOP, CONT/BRK
  222. instructions will be emitted.
  223. Otherwise, those constructs will be implemented with BRA instructions.
  224. </dd>
  225.  
  226. <dt>EmitCondCodes</dt>
  227. <dd>
  228. If set, condition codes (ala GL_NV_fragment_program) will be used for
  229. branching and looping.
  230. Otherwise, ordinary registers will be used (the IF instruction will
  231. examine the first operand's X component and do the if-part if non-zero).
  232. This option is only relevant if EmitHighLevelInstructions is set.
  233. </dd>
  234.  
  235. <dt>EmitComments</dt>
  236. <dd>
  237. If set, instructions will be annoted with comments to help with debugging.
  238. Extra NOP instructions will also be inserted.
  239. </dd>
  240. </dl>
  241.  
  242.  
  243. <h2 id="validation">Compiler Validation</h2>
  244.  
  245. <p>
  246. Developers working on the GLSL compiler should test frequently to avoid
  247. regressions.
  248. </p>
  249.  
  250. <p>
  251. The <a href="http://piglit.freedesktop.org/">Piglit</a> project
  252. has many GLSL tests.
  253. </p>
  254.  
  255. <p>
  256. The Mesa demos repository also has some good GLSL tests.
  257. </p>
  258.  
  259. </div>
  260. </body>
  261. </html>
  262.