jax 0.0.0.8 → 0.0.0.9

data/CHANGELOG

@@ -1,3 +1,25 @@
+* 0.0.0.9 *
+
+* Minor bugfixes for Jax.Util.colorize() and Jax.Util.Vectorize(). Specifically,
+  fixes involved correctly processing 3D colors and 2D vectors.
+
+* Switch shader test generator to use SPEC_CONTEXT, which is now defined in the
+  spec_layout and helper files for new applications. This isn't *immediately*
+  app-breaking but you should regenerate these files anyways or the next time you
+  generate a shader will cause a bad day.
+
+* List enum name next to error number for clarity when render errors occur.
+
+* Abstract test suite setup into a separate helper file
+
+* Add a global SPEC_CONTEXT so users don't have to manually create a new context for
+  each spec
+  
+* Specs run on a completely separate context so that they don't cause issues with
+  the visual tests
+
+
+
 * 0.0.0.8 *
 
 * Added +Jax.Shaders.max_vertex_textures+ which tracks the value of

data/Rakefile

@@ -130,9 +130,10 @@ end
 
 namespace :guides do
   # gen doc:js first because we're going to include a direct link to the JS API dox
-  task :generate => 'doc:js' do
+  task :generate do
     rm_rf "guides/output"
     if !ENV["SKIP_API"]
+      Rake::Task['doc:js'].invoke
       mkdir_p "guides/output/api"
       cp_r "doc", "guides/output/api/js"
     end

data/builtin/shaders/functions/noise.ejs

@@ -12,9 +12,6 @@
  * implementation.
  **/
  
-uniform float time; // Used for texture animation
- 
-
 <%if (shader_type != 'vertex' || Jax.Shader.max_vertex_textures > 0) {%>
 
 

data/guides/assets/javascripts/syntaxhighlighter/shBrushCpp.js

@@ -46,7 +46,16 @@
 						'jmp_buf mbstate_t _off_t _onexit_t _PNH ptrdiff_t _purecall_handler ' +
 						'sig_atomic_t size_t _stat __stat64 _stati64 terminate_function ' +
 						'time_t __time64_t _timeb __timeb64 tm uintptr_t _utimbuf ' +
-						'va_list wchar_t wctrans_t wctype_t wint_t signed';
+						'va_list wchar_t wctrans_t wctype_t wint_t signed ' +
+						
+						// glsl
+						'void bool int float vec2 vec3 vec4 bvec2 bvec3 bvec4 ivec2 ivec3 ivec4 mat2 '+
+						'mat3 mat4 sampler2D samplerCube ' +
+						
+						// jax preprocessor
+						'' +
+						
+						'';
 
 		var keywords =	'break case catch class const __finally __exception __try ' +
 						'const_cast continue private public protected __declspec ' +
@@ -56,7 +65,14 @@
 						'register reinterpret_cast return selectany ' +
 						'sizeof static static_cast struct switch template this ' +
 						'thread throw true false try typedef typeid typename union ' +
-						'using uuid virtual void volatile whcar_t while';
+						'using uuid virtual void volatile whcar_t while ' +
+						
+						// glsl
+						'uniform varying attribute ' +
+						
+						// jax preprocessor
+						'shared '
+						;
 					
 		var functions =	'assert isalnum isalpha iscntrl isdigit isgraph islower isprint' +
 						'ispunct isspace isupper isxdigit tolower toupper errno localeconv ' +
@@ -73,7 +89,19 @@
 						'wcstombs wctomb memchr memcmp memcpy memmove memset strcat strchr ' +
 						'strcmp strcoll strcpy strcspn strerror strlen strncat strncmp ' +
 						'strncpy strpbrk strrchr strspn strstr strtok strxfrm asctime ' +
-						'clock ctime difftime gmtime localtime mktime strftime time';
+						'clock ctime difftime gmtime localtime mktime strftime time ' +
+						
+						// glsl
+						'radians degrees sin cos tan asin acos atan pow exp log exp2 log2 sqrt ' +
+						'inversesqrt abs sin floor ceil fract mod min max clamp mix step smoothstep ' +
+						'length distance dot cross normalize faceforward reflect matrixCompMult ' +
+						'lessThan lessThanEqual greaterThan greaterThanEqual equal notEqual '+
+						'any all not texture2D texture2DProj texture2DProjLod textureCube '+
+						'textureCubeLod'
+						
+						// jax preprocessor
+						'import export '
+						;
 
 		this.regexList = [
 			{ regex: SyntaxHighlighter.regexLib.singleLineCComments,	css: 'comments' },			// one line comments

data/guides/jax_guides/common.rb

@@ -1,5 +1,5 @@
 module JaxGuides
-  CODE_ALIASES = %w(yaml shell ruby erb html sql plain js)
+  CODE_ALIASES = %w(yaml shell ruby erb html sql plain js c)
 
   def self.code_aliases
     CODE_ALIASES.join("|")

data/guides/source/index.html.erb

@@ -31,6 +31,10 @@
 
 <dl>
 
+<%= guide("Custom Shaders", 'shaders.html', :work_in_progress => false) do %>
+  <p>This guide shows how to add and use your own shaders to add advanced custom visual effects.</p>
+<% end %>
+
 <%= guide("Materials", 'materials.html', :work_in_progress => true) do %>
   <p>This guide demonstrates how to create, use and dynamically alter Materials in Jax.</p>
 <% end %>
@@ -39,10 +43,6 @@
   <p>This guide shows how to make the most of lighting support in Jax, and outlines potential caveats. It will also discuss how to prevent certain objects from being lit at all, and in what circumstances you'd want to do this.</p>
 <% end %>
 
-<%= guide("Custom Shaders", 'shaders.html', :work_in_progress => true) do %>
-  <p>This guide shows how to add and use your own shaders to add advanced custom visual effects.</p>
-<% end %>
-
 <%= guide("Matrices", "matrices.html", :work_in_progress => true) do%>
   <p>This guide explains all of the various matrices and "spaces", and how they relate to one another. It will help you understand the difference between world space, camera space and object space; and how a 3D object goes from a set of vertices in object space to a translated, rotated and scaled image on your computer screen.</p>
 <% end %>

data/guides/source/shaders.textile

@@ -1,5 +1,499 @@
-h2. This Guide Not Yet Started
+h2. Writing Shaders With Jax
 
-Please come back after I've had time to work on this guide a bit.
+This guide will help you understand the principles of shader design in Jax. It will cover the following topics:
+
+* Generating a Jax shader and understanding the resultant files
+* How your shader interacts with the Jax preprocessor
+* How the Jax preprocessor combines multiple shaders
+* How Material files use your shaders
+* How the Jax preprocessor handles hardware constraints
 
 endprologue.
+
+
+h3. Assumptions
+
+This guide is for people who have already read the "Getting Started Guide":getting_started.html and have perhaps run through a few demos of their own, and reached the limits of what the built-in Jax shaders can do for them. It assumes you are familiar with the fundamentals of JavaScript as well as the "OpenGL Shading Language (GLSL)":http://en.wikipedia.org/wiki/GLSL.
+
+The commands shown in this guide are, unless otherwise noted, executed in the root directory of a Jax application.
+
+
+h3. Generating a Shader
+
+Generating a shader is very similar to any other generator in Jax. The first step is, of course, deciding on a name for it; that's easier to do if we have an idea of what the shader should produce. In this guide, we'll design a shader called _brick_ that draws a procedural brick-like texture onto whichever objects make use of it.
+
+<shell>
+$ jax generate shader brick
+
+  create  app/shaders/brick/common.ejs
+  create  app/shaders/brick/fragment.ejs
+  create  app/shaders/brick/manifest.yml
+  create  app/shaders/brick/material.js
+  create  app/shaders/brick/vertex.ejs
+  create  spec/javascripts/shaders/brick_spec.js
+</shell>
+
+As you can see, six files were generated for us. Two were standard JavaScript files; one was a YAML file; and the remaining three were <em>Embedded JavaScript</em>, or EJS, files. Let's examine them one at a time:
+
+* +spec/javascripts/shaders/brick_spec.js+ -- this is a test file, or <em>spec file</em>, generated by Jax to unit test our shader. If you open it, you'll see that it's quite complete. By default, it will test the shader under two conditions: as a stand-alone shader, and as part of a group of shaders merged together by the Jax preprocessor. More on that later.
+* +app/shaders/brick/manifest.yml+ -- the manifest file contains meta data about your shader. It's not used in the JavaScript that your shader will eventually produce; instead, it is read by the Ruby component of Jax and used primarily for the command-line +material+ generator.
+* +app/shaders/brick/common.ejs+ -- the contents of this file are prepended to both the _vertex_ and _fragment_ shaders. It can contain function definitions, uniform and varying variables, constants and global variables. Attribute variables don't belong here, because attributes cannot appear within fragment shaders.
+* +app/shaders/brick/vertex.ejs+ -- houses the body of your vertex shader.
+* +app/shaders/brick/fragment.ejs+ -- houses the body of your fragment shader.
+* +app/shaders/brick/material.js+ -- the interface between JavaScript and your shader, this file is primarily responsible for setting the values of +uniform+ and +attribute+ variables.
+
+
+h3. The Jax Preprocessor
+
+There are technically two preprocessors at your disposal. The compiler preprocessor is the lower-level one, and is built into WebGL. All WebGL applications support the compiler preprocessor, which is invoked using the '#' character. Directives such as +#ifdef+ and +#version+ make use of the compiler preprocessor.
+
+The Jax preprocessor operates at a much higher level than the compiler processor, and is essentially a glorified string manipulator.
+
+INFO: This is why we must make a distinction between the compiler preprocessor and the Jax preprocessor. While the former operates entirely within the OpenGL drivers, the latter is executed in JavaScript and is primarily responsible for building your shader and controlling when and how your shader is merged with other shaders. We'll discuss all of this in detail.
+
+
+h4. Combining Shaders
+
+WebGL doesn't technically support the arbitrary mixing and matching of shaders. While it does support multiple shader _libraries_, these are analogous to C++ libraries. Lots of files can be plugged in, but only one can define a _main_ function.
+
+This poses a problem in the realm of reusable code. If you have a shader that supports lighting effects, but you want to run a shader that supports lighting _and_ some other effect (for instance, a brick pattern), you have to write an entirely new shader with its own _main_ function. In the easiest case, you'll have to extract the lighting code into a single reusable function library, and then call those functions from the new shader. The list of shaders you must keep and maintain can easily grow into the hundreds or (for large apps) thousands, mostly due to variations of otherwise similar shaders.
+
+Jax addresses this problem by directly manipulating the source code for all shaders. It seeks out the _main_ functions, renames them to something unique based on the particular instance of the particular shader, (a process known as <em>"name mangling":http://en.wikipedia.org/wiki/Name_mangling</em>, which is certainly not unique to Jax), and then constructs its own _main_ function just prior to compiling the code.
+
+
+h4. Shared Variables
+
+The process of combining shaders is entirely automatic and there's no need for the developer to get involved, but it's something the developer _does_ need to be aware of due to the relatively stringent limitations of graphics hardware.
+
+It would be wasteful (and impossible!) to create exact copies of all variables, such as the modelview matrix, the projection matrix, vertex positions, normals, texture coordinates, colors... the list goes on. Instead, the Jax preprocessor introduces the +shared+ keyword. Whenever you use the +shared+ keyword as part of a variable declaration in the global scope, (for instance, in the +app/shaders/brick/common.ejs+ file), Jax will _not_ name mangle the variable in question. This means that as long as all of the shaders use the same name for the variable, it won't be redeclared when those shaders are combined.
+
+Here are some examples of the +shared+ keyword, extracted from the +common.ejs+ file:
+
+<c>
+shared uniform mat3 nMatrix;
+shared uniform mat4 mvMatrix, pMatrix;
+
+shared varying vec2 vTexCoords;
+shared varying vec3 vNormal;
+shared varying vec4 vBaseColor;
+</c>
+
+
+h4. Exports and Imports
+
+Similar to shared variables, _exports_ and _imports_ allow you to share values across shaders. The difference is that they don't need to be predeclared beforehand -- you can use them on-the-fly within your shaders. They also allow you to prepare them with default values in case they haven't been previously exported by another shader.
+
+h5. Exporting a Value
+
+When Jax encounters an export, it will be declared in the global scope as long as it hasn't been already.
+
+There are two ways to export a variable: with an <em>implicit value</em> or with an <em>explicit value</em>. An _implicit_ value simply means that Jax will look for a local variable of the same name as the export, and use it. An _explicit_ value takes the form of a third argument, and represents the value or variable whose value you are assigning. Here are some examples of both:
+
+<c>
+void main(void) {
+  vec4 ambient = vec4(1,1,1,1);
+  
+  // implicit value
+  export(vec4, ambient);
+  
+  // explicit value
+  export(vec4, GlobalAmbientColor, vec4(ambient.rgb * 0.5, 1));
+}
+</c>
+
+h5. Importing a Value
+
+Shaders can import values previously exported by other shaders. If the value has never been exported, the global variable won't exist and the import will be silently ignored. This makes it very easy to use default values for imports, as you'll see in the next code snippet.
+
+Imports always take two arguments. The first is the actual name of the variable to be imported; the second is an expression representing what to do with the import if it can be found.
+
+Here's an example:
+
+<c>
+void main(void) {
+  vec4 color = vec4(1.0, 1.0, 1.0, 1.0);
+  import(ambient, color = ambient);
+}
+</c>
+
+INFO: When the import exists in the above example, we are effectively assigning a value to the +color+ variable and then immediately overwriting that value. This would be inefficient, but the GLSL compiler will be smart enough to optimize the redundancy away for us so that it is not an issue. If the import does _not_ exist, then the +import()+ call is ignored entirely and the color defaults to white.
+
+
+h4. Requiring Supporting Libraries
+
+You can create your own libraries of functions and other reusable code. Just put it in a subdirectory of +app/shaders+ (I like to put my functions in +app/shaders/functions+) and be sure to give the file a +.ejs+ extension.
+
+To make use of your function libraries, use the +require+ directive like so:
+
+<js>
+//= require "functions/name_of_library.ejs"
+</js>
+
+...where _name_of_library_ represents the name of the function library you're trying to import.
+
+INFO: Library requires are performed on the Ruby side of life, so this does not result in an AJAX or similar call. Instead, Ruby performs the lookup while building the JavaScript portion of your shader. This yields not only the runtime advantages of avoiding multiple requests, but is more configurable. You can alter the +Jax.application.config.shader_paths+ variable, which is an array of strings, in the Ruby API to tell Ruby where else to look for function libraries.
+
+INFO: By default, the +Jax.application.config.shader_paths+ variable in Ruby is set to include the +app/shaders+ directory within your own application, as well as the Jax built-in shader path. This allows you to require the various function libraries that ship with Jax for your own use. See "the Wiki":http://github.com/sinisterchipmunk/jax/wiki for more information about what function libraries are available to your shaders, and how to use them.
+
+
+h4. +main+ in the Fragment Shader
+
+Your fragment shader's +main+ function may accept up to 3 _inout_ arguments: _ambient_, _diffuse_ and _specular_, in that order. Each of these is a +vec4+ representing the named color channel. They default to (1, 1, 1, 1) but may be altered by other shaders before being passed into yours. In this way, you can produce cumulative effects on the color of a given fragment by directly altering the color components they represent.
+
+If you define your +main+ function to not accept any arguments (that is, its argument definition is +void+), then Jax will assume you intend to write to +gl_FragColor+ directly. In this case, <strong>all color components are ignored</strong>. This has an effect on the entire shader chain, and is generally not recommended unless you understand the tradeoffs.
+
+WARNING: Most of the built-in shaders are designed to accept the three color components, and these shaders do not pay any attention to +gl_FragColor+.
+
+
+h3. Embedded JavaScript
+
+Because Jax shaders are composed using Embedded JavaScript (EJS), you can easily insert JavaScript code directly into your shader. The JavaScript code is evaluated before any other preprocessors are run, and can be used to manipulate exactly what will ultimately be compiled.
+
+Embedding JavaScript into an EJS file is quite simple. Here's how the built-in Perlin noise functions make use of this feature:
+
+<js>
+<% if (shader_type == 'vertex' && Jax.Shader.max_vertex_textures == 0) { %>
+  // use slower, non-texture-based noise functions
+<% } else { %>
+  // use faster, texture-based noise functions
+<% } %>
+</js>
+
+INFO: In this example, Jax first checks the shader type. If it's a vertex shader, then there's a possibility that the vertex shader does not support texture lookups; if this is true, then texture-based noise in the vertex shader is going to fail to compile. Since Jax tries to support all graphics hardware seamlessly, it uses this information to fall back to a slower, but workable, noise solution that does not rely on texture lookups. If the shader type is 'fragment' or if the graphics hardware _does_ support vertex texture lookups, then the faster noise functions are used instead. This allows the Jax noise functions to be extremely flexible by not forcing the developer to manage many different libraries, or to manually query the capabilities of the graphics hardware, or both.
+
+Another example is for the definition of globals. You can still hard-code global values using the compiler preprocessor like so...
+
+<c>
+#ifndef PI
+#define PI 3.14159...
+#endif
+
+void main(void) {
+  float circle = 2 * PI;
+  // ...
+}
+</c>
+
+Or, you can use Embedded JavaScript to use the values directly in-line while not sacrificing any readability. This allows you to reuse constants at the JavaScript level instead of coding them directly into your shader -- even if you don't necessarily know the exact values of those constants off the top of your head:
+
+<c>
+void main(void) {
+  float circle = 2 * <%=Math.PI%>;
+  // ...
+}
+</c>
+
+h3. Putting it All Together
+
+Let's use what we've learned so far to start building our _bricks_ shader.
+
+h4. Manifest
+
+The first thing we should look at is the Manifest. Its use will become apparent when we test our shader for the first time. Make it look like this:
+
+<yaml>
+description: |
+  Adds a simple brick texture to a mesh
+
+options:
+  brick_color: 
+    red: 1.0
+    green: 0.3
+    blue: 0.2
+
+  mortar_color:
+    red: 0.85
+    green: 0.86
+    blue: 0.84
+
+  brick_size:
+    x: 0.3
+    y: 0.15
+
+  brick_pct:
+    x: 0.9
+    y: 0.85
+</yaml>
+
+The description should be kept as concise as possible. Try to explain the shader in one sentence -- or less. The options are entirely made up by you, and will be passed into your shader as <tt>uniform</tt>s a little later on.
+
+NOTE: See the pipe ("|") following the +description+? In case you're not familiar with YAML syntax, that's telling YAML that the description may span several lines. The description can continue until an empty line is encountered. If you remove the pipe, you'll have to fit the entire description into one line. That's not a bad thing, as long as you're aware of the need to do so.
+
+h4. Common Source
+
+First, open up the +app/shaders/bricks/common.ejs+ file and make it look like this:
+
+<c>
+varying vec2 MCposition;
+
+shared uniform mat4 mvMatrix, pMatrix;
+</c>
+
+We are defining a 2D vector called +MCposition+ which will be used to generate the brick texture. Since both the vertex and fragment shader will make use of this, we can put it in the common code to reduce code repetition. This way, if we need to make changes to it later on, we only need to change it once.
+
+We define +mvMatrix+ and +pMatrix+ for the same reason, but we use the +shared+ preprocessor keyword to tell Jax that these matrices are to be used for _all_ shaders in the chain, and not just this one.
+
+h4. Vertex Shader Source
+
+<c>
+shared attribute vec4 VERTEX_POSITION;
+
+void main(void) {
+  MCposition = VERTEX_POSITION.xy;
+  gl_Position = pMatrix * mvMatrix * VERTEX_POSITION;
+}
+</c>
+
+This is a very simple vertex shader that just passes the X and Y coordinates of +VERTEX_POSITION+ into a varying for use in the fragment shader. Then it sets +gl_Position+, in case no shader before it has done so. We mark +VERTEX_POSITION+ as +shared+ because virtually every shader will make use of +VERTEX_POSITION+, and we don't want Jax to define a new attribute for each shader in the chain.
+
+h4. Fragment Shader Source
+
+Finally, open +app/shaders/bricks/fragment.ejs+ and replace its contents with:
+
+<c>
+uniform vec4 BrickColor, MortarColor;
+uniform vec2 BrickSize, BrickPct;
+
+void main(inout vec4 ambient, inout vec4 diffuse, inout vec4 specular) {
+  vec2 position = MCposition / BrickSize, useBrick;
+  
+  if (fract(position.y * 0.5) > 0.5)
+    position.x += 0.5;
+  
+  position = fract(position);
+  useBrick = step(position, BrickPct);
+  
+  vec3 color = mix(MortarColor.rgb, BrickColor.rgb, useBrick.x * useBrick.y);
+  ambient.rgb *= color;
+  diffuse.rgb *= color;
+}
+</c>
+
+Notice, in this case, that our uniforms are not marked as +shared+. This is because we want the brick color, mortar color, and so on to be unique to this shader. Moreover, we want the colors to be unique to this _instance_ of the shader; that is, if the user decides to use two separate Brick shaders with separate color and size parameters, we don't want the parameters to conflict with each other.
+
+NOTE: Take notice that we didn't do any lighting calculations. In fact, though we could have simply added <tt>//= require "functions/lights"</tt> and called the Jax lighting functions directly, we decided not to do _any_ lighting whatsoever. Why? This is because Jax already has lighting functions; if you write your own, you're effectively reinventing the wheel. While this is OK to do if you're unhappy with the Jax implementation, you should do so in a completely separate shader so that it's easy to toggle lighting effects on and off. In essence, try to keep a shader as "bare-bones" as possible: it should ideally do what its description says, no more, no less. It can be combined with other shaders later on to maximize code reuse.
+
+h4. Material File
+
+The last step before we can test our material out is to tie the uniforms to their actual values. For that, we need to edit the material file in +app/shaders/bricks/material.js+. Make it look like this:
+
+<js>
+Jax.Material.Brick = Jax.Class.create(Jax.Material, {
+  initialize: function($super, options) {
+    options = Jax.Util.normalizeOptions(options, {
+      shader: "brick",
+      brick_color: [1, 0.3, 0.2],
+      mortar_color: [0.85, 0.86, 0.84],
+      brick_size: [0.3, 0.15],
+      brick_pct: [0.9, 0.85]
+    });
+
+    options.brick_color = Jax.Util.colorize(options.brick_color);
+    options.mortar_color = Jax.Util.colorize(options.mortar_color);
+    options.brick_size = Jax.Util.vectorize(options.brick_size);
+    options.brick_pct = Jax.Util.vectorize(options.brick_pct);
+
+    $super(options);
+  },
+
+  setUniforms: function($super, context, mesh, options, uniforms) {
+    uniforms.set('mvMatrix', context.getModelViewMatrix());
+    uniforms.set('nMatrix', context.getNormalMatrix());
+    uniforms.set('pMatrix', context.getProjectionMatrix());
+    uniforms.set('BrickColor', this.brick_color);
+    uniforms.set('MortarColor', this.mortar_color);
+    uniforms.set('BrickSize', this.brick_size);
+    uniforms.set('BrickPct', this.brick_pct);
+  },
+
+  setAttributes: function($super, context, mesh, options, attributes) {
+    attributes.set('VERTEX_POSITION',  mesh.getVertexBuffer());
+  }
+});
+</js>
+
+The +vectorize+ and +colorize+ utility methods called from the constructor are used to normalize the various different forms that a vector or color might take, respectively. This lets users use full words like "red", letters like "r", or just a comma-delimited list inside of their material files, and Jax will still interpret the value correctly.
+
+The rest of the file should be pretty apparent. The +setUniforms+ method is in charge of setting uniform values, while the +setAttributes+ method does the same for attribute values. Both methods are passed a Jax context, mesh, and a set of options built during the render pass.
+
+h3. Test the Shader
+
+We're ready to test it out! Before we go generating any materials, try just loading up the Jax application in your browser. We should make sure those two specs that were generated for us way back at the beginning of this guide are still passing.
+
+All green? Good! Let's generate a controller so we can see our new shader in action!
+
+<shell>
+$ jax generate controller bricks index
+</shell>
+
+IMPORTANT: This is all covered in the "Getting Started Guide":getting_started.html. Don't forget to set the root route in +config/routes.rb+ if you haven't done so already.
+
+With that done, add the following code to the +index+ action of the newly-generated +app/controllers/bricks_controller.js+:
+
+<js>
+this.world.addObject(new Jax.Model({
+  position:[0,0,-5],
+  mesh:new Jax.Mesh.Quad(),
+  material:Material.find("bricks_demo")
+}));
+</js>
+
+h4. Generate a Material
+
+If you remember the "Getting Started Guide":getting_started.html, then you'll know that the above code will cause your application and its tests to fail. The next thing we need to do is generate the +bricks_demo+ material that we referenced in the controller.
+
+Before you go typing in the whole command, type just a little bit:
+
+<shell>
+$ jax generate material
+  ...
+    - brick                : Adds a simple brick texture to a mesh
+</shell>
+
+This is where your +app/shaders/bricks/manifest.yml+ file comes into play. Ruby reads this file in order to know how to help you when you're generating new materials. This becomes very useful when you're dealing with a lot of shaders all at once.
+
+Now, let's complete the command:
+
+<shell>
+$ jax generate material bricks_demo brick
+</shell>
+
+Open up the generated +app/resources/materials/bricks_demo.yml+ file and, at the bottom, you'll see some more interesting tidbits:
+
+<yaml>
+- type: Brick
+  brick_color:
+    red: 1.0
+    green: 0.3
+    blue: 0.2
+  mortar_color:
+    red: 0.85
+    green: 0.86
+    blue: 0.84
+  brick_size:
+    x: 0.3
+    y: 0.15
+  brick_pct:
+    x: 0.9
+    y: 0.85
+</yaml>
+
+These are the options you specified in the manifest file! They are used as defaults for all generated Materials. Users can now edit these options as needed, without having to guess which options are available to them (or refer to documentation).
+
+h3. Combining Shaders
+
+You may have noticed in the +app/resources/material/bricks_demo.yml+ file that it listed +Lighting+ as one of the shader layers. This means Jax is implicitly combining both the Lighting shader and our Bricks shader into one program! You can enable lighting effects by simply adding a light source to the scene. This can be done by adding a light source via the +index+ action in the +app/controllers/bricks_controller.js+, which should now look like this:
+
+<js>
+//= require "application_controller"
+
+var BricksController = (function() {
+  return Jax.Controller.create("bricks", ApplicationController, {
+    index: function() {
+
+      this.world.addObject(new Jax.Model({
+        position:[0,0,-5],
+        mesh:new Jax.Mesh.Quad({
+          material:"bricks_demo"
+        }),
+      }));
+
+      // add a light to show off the lighting effects that our
+      // shader has, "for free"
+      this.world.addLightSource(new Jax.Scene.LightSource({
+        position:[0.5, 0.5, -4],
+        attenuation: { linear: 1.25 },
+        type:Jax.POINT_LIGHT
+      }));
+    }
+  });
+})();
+</js>
+
+h4. Falling Back
+
+Obviously, not all clients are created equal. The sad reality is that you cannot expect everyone to view your application exactly as you do; some devices will perform better than others, and some will have a downright difficult time with apps that include a lot of visual effects.
+
+Some of this must be chalked up to how you design your application. If it does a lot of number crunching on the CPU or has extremely complicated shaders tying up the GPU for extended periods of time, there's only so much Jax can do to compensate. In general, Jax leaves it up to you, the developer, to decide what type of hardware to target and how to improve performance in individual algorithms. As long as it's theoretically _possible_ to run an application as it was originally coded, Jax will not make any changes.
+
+On the other hand, Jax is very good at "dumbing down" to clients that have physical hardware constraints that limit their ability to run your application. If, for instance, a given Material requests a set of shaders that, combined, would use too many +varying+ variables, Jax will begin to make changes to the list of shaders that can be used with the material in question.
+
+h5. Example 1
+
+Following is a step-by-step example, using our new "bricks with lighting" material (above) to demonstrate.
+
+IMPORTANT: We're going to pull numbers from a hat in order to make a point; realistically speaking, all of these are much too low. Virtually any graphics hardware on the market today should run the entire example without issue.
+
+Let's imagine a client visiting our site that has the following specific graphic limitations:
+
+* Uniforms: 32
+* Attributes: 8
+* Varyings: 5
+
+The basic, no-frills, color-only shader for Jax uses 11 uniforms, 5 attributes and 4 varyings. The lighting shader uses 13 uniforms, no additional attributes, and 1 varying. Our own brick shader uses 4 additional uniforms and 1 additional varying. (The rest of the variables are +share+'d with the other shaders, thankfully!)
+
+This means our current list of shaders is asking for a total of 27 uniforms, 5 attributes and 6 varyings. Our shader list exceeds the number of available +varying+ slots by 1.
+
+Jax must now look at the list of shaders, and make an educated guess as to which shaders to keep and which ones to drop. The +basic+ shader is part of the core material and therefore cannot be dropped (although this can be modified; we'll talk about this later). That leaves either +lighting+ or +bricks+, which both use exactly 1 varying.
+
+With little other choice, Jax simply drops the last one to appear in the material: our bricks. But if Jax drops the bricks, then our material becomes a bland, white sheet of plastic! In this case, it's probably desirable to drop lighting in favor of keeping the bricks. We can cause Jax to drop +lighting+ instead of +bricks+ by simply making sure that +bricks+ appears _before_ +lighting+ in the +app/resources/materials/bricks_demo.yml+ file:
+
+<yaml>
+layers:
+  - type: Brick
+    brick_color: 
+    # ... 
+
+  - type: Lighting
+</yaml>
+
+Now, when Jax has to choose between two perfectly valid candidates, it will drop +lighting+ in favor of +bricks+.
+
+
+h5. Example 2
+
+Let's take another example, now. Assume that our client has the following hardware limitations:
+
+* Uniforms: 16
+* Attributes: 8
+* Varyings: 8
+
+Now we have an entirely different scenario. It is immediately obvious to Jax that, since it can't drop the +basic+ shader, it is patently impossible to run the +lighting+ shader on the specified material. It just can't be done, period. There aren't enough +uniform+ slots available.
+
+In this situation, Jax will immediately drop the +lighting+ shader <em>regardless of its position in the material file!</em> By doing so, this opens up just enough +uniform+ slots to make the +brick+ shader run, so Jax stops here.
+
+h5. Example 3: Worst Case
+
+If the hardware were even more limited, Jax would now consider dropping both the +brick+ and +lighting+ shaders, and running on pure color support only. This is almost _never_ what you want Jax to do, but it is a last-ditch effort by Jax to try to run your application on hardware your application wasn't intended for.
+
+Hypothetical numbers:
+
+* Uniforms: 12
+* Attributes: 6
+* Varyings: 4
+
+The +basic+ shader is guaranteed to run on all WebGL-compatible hardware, as long as the hardware follows the OpenGL ES standards for "minimum maximums". However, the +brick+ shader is well within the limits of our latest example <em>if the +basic+ shader is dropped</em>.
+
+This is where the auto-generated spec for "standalone shaders" comes in handy, because it proves that our shader will, at the very least, _compile_, even if the +basic+ shader is omitted. So how can we tell Jax to omit the +basic+ shader and use the +brick+ shader as the default?
+
+Easy! Simply move the +brick+ type (as well as all pertinent options) outside of the +layers+ attribute, making them attributes of the core material itself:
+
+<yaml>
+# ...
+
+type: Brick
+brick_color: 
+  red: 1.0
+  green: 0.3
+  blue: 0.2
+mortar_color: 
+# ...
+
+layers:
+  # remove Lighting to conserve video memory if you don't need/want support for light sources
+  - type: Lighting
+</yaml>
+
+Done! Jax will now completely omit the +basic+ shader, and the +brick+ shader will be marked as "critical", or un-droppable.
+
+WARNING: This last option is a good idea _only_ if you have developed a shader that you are sure will run on all hardware! If Jax encounters an un-droppable shader which cannot feasibly run on the client hardware, it will crash and burn in a rather spectacular way. Avoid this situation by developing critical shaders that are compatible with "least common denominator" hardware!