Commits

Jason McKesson  committed 2c4dc7d

glscene: Scene file format now fully documented.

  • Participants
  • Parent commits d2156f7

Comments (0)

Files changed (7)

File docs/glscene_notepadpp.xml

 <NotepadPlus>
-    <UserLang name="GL Scene Graph" ext="glscene" udlVersion="2.1">
+    <UserLang name="GL Scene Graph" ext="glscene" udlVersion="2.0">
         <Settings>
-            <Global caseIgnored="no" allowFoldOfComments="no" foldCompact="no" forcePureLC="0" decimalSeparator="0" />
+            <Global caseIgnored="no" allowFoldOfComments="no" forceLineCommentsAtBOL="no" foldCompact="no" />
             <Prefix Keywords1="no" Keywords2="no" Keywords3="no" Keywords4="no" Keywords5="no" Keywords6="no" Keywords7="no" Keywords8="no" />
         </Settings>
         <KeywordLists>
-            <Keywords name="Comments">00// 01 02 03 04</Keywords>
-            <Keywords name="Numbers, prefix1"></Keywords>
-            <Keywords name="Numbers, prefix2"></Keywords>
-            <Keywords name="Numbers, extras1"></Keywords>
-            <Keywords name="Numbers, extras2"></Keywords>
-            <Keywords name="Numbers, suffix1"></Keywords>
-            <Keywords name="Numbers, suffix2"></Keywords>
-            <Keywords name="Numbers, range"></Keywords>
-            <Keywords name="Operators1"></Keywords>
-            <Keywords name="Operators2"></Keywords>
-            <Keywords name="Folders in code1, open">resources sampler_res camera_res program_res scene node</Keywords>
-            <Keywords name="Folders in code1, middle"></Keywords>
-            <Keywords name="Folders in code1, close">end</Keywords>
-            <Keywords name="Folders in code2, open"></Keywords>
-            <Keywords name="Folders in code2, middle"></Keywords>
-            <Keywords name="Folders in code2, close"></Keywords>
-            <Keywords name="Folders in comment, open"></Keywords>
-            <Keywords name="Folders in comment, middle"></Keywords>
-            <Keywords name="Folders in comment, close"></Keywords>
-            <Keywords name="Keywords1">compare mag min aniso wrap_s wrap_t wrap_r target orient spin radius radius_delta pos_delta rotation_scale placeholder vert tess_ctrl tess_eval geom frag mtc nmtc nctm sampler image uniform_buffer storage_buffer layer_defs variant_check layers</Keywords>
-            <Keywords name="Keywords2">uniform_res uniform_buffer_res storage_buffer_res texture_res mesh_res</Keywords>
-            <Keywords name="Keywords3"></Keywords>
-            <Keywords name="Keywords4"></Keywords>
-            <Keywords name="Keywords5"></Keywords>
-            <Keywords name="Keywords6"></Keywords>
-            <Keywords name="Keywords7"></Keywords>
-            <Keywords name="Keywords8"></Keywords>
-            <Keywords name="Delimiters">00&lt; 01 02&gt; 03&quot; 04 05&quot; 06&apos; 07 08&apos; 09{ 10 11} 12[ 13 14] 15 16 17 18 19 20 21 22 23</Keywords>
+            <Keywords name="Comments" id="0">00// 01 02 03 04</Keywords>
+            <Keywords name="Numbers, additional" id="1"></Keywords>
+            <Keywords name="Numbers, prefixes" id="2"></Keywords>
+            <Keywords name="Numbers, extras with prefixes" id="3"></Keywords>
+            <Keywords name="Numbers, suffixes" id="4"></Keywords>
+            <Keywords name="Operators1" id="5"></Keywords>
+            <Keywords name="Operators2" id="6"></Keywords>
+            <Keywords name="Folders in code1, open" id="7">resources sampler_res camera_res program_res scene node node_tm object_tm local style program pipeline</Keywords>
+            <Keywords name="Folders in code1, middle" id="8"></Keywords>
+            <Keywords name="Folders in code1, close" id="9">end</Keywords>
+            <Keywords name="Folders in code2, open" id="10"></Keywords>
+            <Keywords name="Folders in code2, middle" id="11"></Keywords>
+            <Keywords name="Folders in code2, close" id="12"></Keywords>
+            <Keywords name="Folders in comment, open" id="13"></Keywords>
+            <Keywords name="Folders in comment, middle" id="14"></Keywords>
+            <Keywords name="Folders in comment, close" id="15"></Keywords>
+            <Keywords name="Keywords1" id="16">compare mag min aniso wrap_s wrap_t wrap_r target orient spin radius radius_delta pos_delta rotation_scale placeholder vert tess_ctrl tess_eval geom frag mtc nmtc nctm sampler image uniform_buffer storage_buffer layer_defs style_check layers scale translate orientation angle_axis matrix using mesh texture uniform_buffer storage_buffer uniform</Keywords>
+            <Keywords name="Keywords2" id="17">uniform_res uniform_buffer_res storage_buffer_res texture_res mesh_res</Keywords>
+            <Keywords name="Keywords3" id="18"></Keywords>
+            <Keywords name="Keywords4" id="19"></Keywords>
+            <Keywords name="Keywords5" id="20"></Keywords>
+            <Keywords name="Keywords6" id="21"></Keywords>
+            <Keywords name="Keywords7" id="22"></Keywords>
+            <Keywords name="Keywords8" id="23"></Keywords>
+            <Keywords name="Delimiters" id="24">00&lt; 01 02&gt; 03&quot; 04 05&quot; 06&apos; 07 08&apos; 09{ 10 11} 12[ 13 14] 15 16 17 18 19 20 21 22 23</Keywords>
         </KeywordLists>
         <Styles>
-            <WordsStyle name="DEFAULT" fgColor="000000" bgColor="FFFFFF" fontName="" fontStyle="0" nesting="0" />
-            <WordsStyle name="COMMENTS" fgColor="000000" bgColor="FFFFFF" fontName="" fontStyle="0" nesting="0" />
-            <WordsStyle name="LINE COMMENTS" fgColor="FF0000" bgColor="FFFFFF" fontName="" fontStyle="0" nesting="0" />
-            <WordsStyle name="NUMBERS" fgColor="000000" bgColor="FFFFFF" fontName="" fontStyle="0" nesting="0" />
-            <WordsStyle name="KEYWORDS1" fgColor="0000FF" bgColor="FFFFFF" fontName="" fontStyle="0" nesting="0" />
-            <WordsStyle name="KEYWORDS2" fgColor="0000FF" bgColor="FFFFFF" fontName="" fontStyle="1" nesting="0" />
-            <WordsStyle name="KEYWORDS3" fgColor="000000" bgColor="FFFFFF" fontName="" fontStyle="0" nesting="0" />
-            <WordsStyle name="KEYWORDS4" fgColor="000000" bgColor="FFFFFF" fontName="" fontStyle="0" nesting="0" />
-            <WordsStyle name="KEYWORDS5" fgColor="000000" bgColor="FFFFFF" fontName="" fontStyle="0" nesting="0" />
-            <WordsStyle name="KEYWORDS6" fgColor="000000" bgColor="FFFFFF" fontName="" fontStyle="0" nesting="0" />
-            <WordsStyle name="KEYWORDS7" fgColor="000000" bgColor="FFFFFF" fontName="" fontStyle="0" nesting="0" />
-            <WordsStyle name="KEYWORDS8" fgColor="000000" bgColor="FFFFFF" fontName="" fontStyle="0" nesting="0" />
-            <WordsStyle name="OPERATORS" fgColor="000000" bgColor="FFFFFF" fontName="" fontStyle="0" nesting="0" />
-            <WordsStyle name="FOLDER IN CODE1" fgColor="0000FF" bgColor="FFFFFF" fontName="" fontStyle="1" nesting="0" />
-            <WordsStyle name="FOLDER IN CODE2" fgColor="000000" bgColor="FFFFFF" fontName="" fontStyle="0" nesting="0" />
-            <WordsStyle name="FOLDER IN COMMENT" fgColor="000000" bgColor="FFFFFF" fontName="" fontStyle="0" nesting="0" />
-            <WordsStyle name="DELIMITERS1" fgColor="7B7BC0" bgColor="FFFFFF" fontName="" fontStyle="0" nesting="0" />
-            <WordsStyle name="DELIMITERS2" fgColor="008000" bgColor="FFFFFF" fontName="" fontStyle="0" nesting="0" />
-            <WordsStyle name="DELIMITERS3" fgColor="00B3B3" bgColor="FFFFFF" fontName="" fontStyle="0" nesting="0" />
-            <WordsStyle name="DELIMITERS4" fgColor="8B0000" bgColor="FFFFFF" fontName="" fontStyle="0" nesting="0" />
-            <WordsStyle name="DELIMITERS5" fgColor="A000A0" bgColor="FFFFFF" fontName="" fontStyle="0" nesting="0" />
-            <WordsStyle name="DELIMITERS6" fgColor="000000" bgColor="FFFFFF" fontName="" fontStyle="0" nesting="0" />
-            <WordsStyle name="DELIMITERS7" fgColor="000000" bgColor="FFFFFF" fontName="" fontStyle="0" nesting="0" />
-            <WordsStyle name="DELIMITERS8" fgColor="000000" bgColor="FFFFFF" fontName="" fontStyle="0" nesting="0" />
+            <WordsStyle name="DEFAULT" styleID="0" fgColor="000000" bgColor="FFFFFF" fontName="" fontStyle="0" nesting="0" />
+            <WordsStyle name="COMMENTS" styleID="1" fgColor="000000" bgColor="FFFFFF" fontName="" fontStyle="0" nesting="0" />
+            <WordsStyle name="LINE COMMENTS" styleID="2" fgColor="FF0000" bgColor="FFFFFF" fontName="" fontStyle="0" nesting="0" />
+            <WordsStyle name="NUMBERS" styleID="3" fgColor="000000" bgColor="FFFFFF" fontName="" fontStyle="0" nesting="0" />
+            <WordsStyle name="KEYWORDS1" styleID="4" fgColor="0000FF" bgColor="FFFFFF" fontName="" fontStyle="0" nesting="0" />
+            <WordsStyle name="KEYWORDS2" styleID="5" fgColor="0000FF" bgColor="FFFFFF" fontName="" fontStyle="1" nesting="0" />
+            <WordsStyle name="KEYWORDS3" styleID="6" fgColor="000000" bgColor="FFFFFF" fontName="" fontStyle="0" nesting="0" />
+            <WordsStyle name="KEYWORDS4" styleID="7" fgColor="000000" bgColor="FFFFFF" fontName="" fontStyle="0" nesting="0" />
+            <WordsStyle name="KEYWORDS5" styleID="8" fgColor="000000" bgColor="FFFFFF" fontName="" fontStyle="0" nesting="0" />
+            <WordsStyle name="KEYWORDS6" styleID="9" fgColor="000000" bgColor="FFFFFF" fontName="" fontStyle="0" nesting="0" />
+            <WordsStyle name="KEYWORDS7" styleID="10" fgColor="000000" bgColor="FFFFFF" fontName="" fontStyle="0" nesting="0" />
+            <WordsStyle name="KEYWORDS8" styleID="11" fgColor="000000" bgColor="FFFFFF" fontName="" fontStyle="0" nesting="0" />
+            <WordsStyle name="OPERATORS" styleID="12" fgColor="000000" bgColor="FFFFFF" fontName="" fontStyle="0" nesting="0" />
+            <WordsStyle name="FOLDER IN CODE1" styleID="13" fgColor="0000FF" bgColor="FFFFFF" fontName="" fontStyle="1" nesting="0" />
+            <WordsStyle name="FOLDER IN CODE2" styleID="14" fgColor="000000" bgColor="FFFFFF" fontName="" fontStyle="0" nesting="0" />
+            <WordsStyle name="FOLDER IN COMMENT" styleID="15" fgColor="000000" bgColor="FFFFFF" fontName="" fontStyle="0" nesting="0" />
+            <WordsStyle name="DELIMITERS1" styleID="16" fgColor="7B7BC0" bgColor="FFFFFF" fontName="" fontStyle="0" nesting="0" />
+            <WordsStyle name="DELIMITERS2" styleID="17" fgColor="008000" bgColor="FFFFFF" fontName="" fontStyle="0" nesting="0" />
+            <WordsStyle name="DELIMITERS3" styleID="18" fgColor="00B3B3" bgColor="FFFFFF" fontName="" fontStyle="0" nesting="0" />
+            <WordsStyle name="DELIMITERS4" styleID="19" fgColor="8B0000" bgColor="FFFFFF" fontName="" fontStyle="0" nesting="0" />
+            <WordsStyle name="DELIMITERS5" styleID="20" fgColor="A000A0" bgColor="FFFFFF" fontName="" fontStyle="0" nesting="0" />
+            <WordsStyle name="DELIMITERS6" styleID="21" fgColor="000000" bgColor="FFFFFF" fontName="" fontStyle="0" nesting="0" />
+            <WordsStyle name="DELIMITERS7" styleID="22" fgColor="000000" bgColor="FFFFFF" fontName="" fontStyle="0" nesting="0" />
+            <WordsStyle name="DELIMITERS8" styleID="23" fgColor="000000" bgColor="FFFFFF" fontName="" fontStyle="0" nesting="0" />
         </Styles>
     </UserLang>
 </NotepadPlus>

File docs/sceneTest.glscene

 	end
 	uniform_buffer_res <projection_matrix> 64 [stream-draw]
 	uniform_buffer_res <lights> 128 placeholder
-	uniform_res <num_lights> [float] 5
-	uniform_res <test_value> [vec3] (2.43 3.4 9.8)
+	uniform_res <num_lights> {lights.numLights} [float] 5
+	uniform_res <test_value> {test} [vec3] (2.43 3.4 9.8)
 	camera_res <main> [left-btn] [left-kbd]
 		target ()
 		orient (quat)
 	//Defines all layers
 	layer_defs 'main' 'shadow1' 'shadow2' 'alt'
 	
-	//List of all legal variant names.
-	variant_check <test>
+	//List of all legal style names.
+	style_check <test>
 
 	node <globals>
 		//Layer for the current node.
 			layers 'shadow1' -'main' +-'alt'
 			
 			node_tm
-				quaternion (0 0.707 0 0.707)
-				translation (0 5 0)
+				orientation (0 0.707 0 0.707)
+				translate (0 5 0)
 			end
-			obj_tm
+			object_tm
 				scale (2)
 			end
 			
 				texture 0 <ship_diffuse_tex> <aniso-repeat>
 			end
 
-			variant <test>
+			style <test>
 				using <matrices> <common>
 
 				program <reflect_shader>

File glscene/Test/test.glscene

 		aniso 1
 	end
 	
-	uniform_res <ident> [vec3] (-5.0)
+	uniform_res <ident> {uniformName} [vec3] (-5.0)
 	
 	camera_res <ident> [left_btn] [left_kbd]
 		target (0 -5 0)
 
 scene
 	layer_defs 'foo' 'bar'
-	variant_check <bla> <blabal> <bol>
+	style_check <bla> <blabal> <bol>
 	
 	node <foo>
 		layers 'foo' -'bar' +'bar' +-'foo'

File glscene/glscene_format.doxy

 Also, note that quaternions in this system do *not* follow GLM's asinine 
 conventions. The W component comes *last*, not first.
 
+# Specification # {#page_glscene_file_format_spec}
+
+Below, commands will be described using the following syntax. For non-compound commands, they will be described as follows:
+
+~~~~
+command param1 param2
+~~~~
+
+The expected type of each `param` is based on what the parameter name is surrounded by. The use of the string qualifiers means that the `param` is a string of that type. So if it is specified as `[param1]`, then `param1` must be an enumerator. The valid enumerant values will be explained in descriptive text.
+
+If a parameter is surrounded by `()`, then it must be a number. These can be a scalar, vector, or matrix; the specific type will be explained in the descriptive text.
+
+Parameter names surrounded with "\`" characters have special types or rules associated with them. These generally can be of multiple types, where each valid type changes what the parameter means.
+
+If a parameter ends with "?", then the parameter is optional. The use of "..." after a parameter name represents a series of parameters of the same type of arbitrary length. Whether the number of such parameters can be 0 or not will be explained in the descriptive text.
+
+Compound commands are denoted by using the `end` keyword, as follows:
+
+\verbatim
+compound param1 param2
+end
+\endverbatim
+
+The valid subcommands of the command will be detailed below, as well as the expected order of such commands.
+
 # Resources # {#page_glscene_file_format_resources}
 
 \verbatim
 ## Uniform Resource ## {#page_glscene_file_format_resources_uniform}
 
 ~~~~
-uniform_res <resource_id> [type] (initial values)?
+uniform_res <resource_id> {uniform name} [type] (initial values)?
 ~~~~
 
-The `uniform_res` command defines a uniform resource, as though by `ResourceRef::DefineUniform`. The resource name defines the 
+The `uniform_res` command defines a uniform resource, as though by `ResourceRef::DefineUniform`. The `resource_id` is the identifier string used to name the uniform. `uniform name` is the GLSL name for the uniform, as to be passed to `glGetUniformLocation` and similar OpenGL functions.
 
 The `type` defines how to interpret the `initial values` part. If the type is a scalar type, then the initial values must be a single number, though it may be in parentheses. If `type` is a vector or matrix type, then the initial values must be a parenthesized list of either a single number or the required number of values.
 
 - `mtc {uniform name}`: Specifies the name of a `mat4` uniform variable in the program that will be given the model-to-camera matrix by the scene graph system. This sub-command may only be specified once.
 - `nmtc {uniform name}`: Specifies the name of a `mat3` uniform variable in the program that will be given the normal`s model-to-camera matrix by the scene graph system. This sub-command may only be specified once.
 - `nctm {uniform name}`: Specifies the name of a `mat3` uniform variable in the program that will be given the normal`s camera-to-model matrix by the scene graph system. This sub-command may only be specified once.
-- `sampler {uniform name} (texture unit)`: Specifies the name of a uniform variable of a sampler type which will be assigned the value `texture unit`. `texture unit` is an unsigned integer.
-- `image {uniform name} (image unit)`: Specifies the name of a uniform variable of an image type which will be assigned the value `image unit`. `image unit` is an unsigned integer.
+- `sampler {uniform name} (texture unit)`: Specifies the name of a uniform variable of a sampler type which will be assigned the value `texture unit`.
+	- `texture unit`: An unsigned integer texture image unit to associate the uniform with.
+- `image {uniform name} (image unit)`: Specifies the name of a uniform variable of an image type which will be assigned the value `image unit`.
+	- `image unit`: An unsigned integer image unit to associate the uniform with.
 - `uniform_buffer {block name} (block binding)`: Specifies that the uniform block named `block name` will be assigned the binding point `block binding`, which is an unsigned integer.
+	- `block binding`: An unsigned integer uniform buffer binding point to assign the named uniform block with.
 - `storage_buffer {block name} (block binding)`: Specifies that the shader storage block named `block name` will be assigned the binding point `block binding`, which is an unsigned integer.
+	- `block binding`: An unsigned integer shader storage buffer binding point to assign the named storage block with.
 
 ## Mesh Resource ## {#page_glscene_file_format_resources_mesh}
 
 The `scene` command is more rigidly structured in its content than the top-level `resources` command. The following commands must be provided, in order. Some of them are optional:
 
 - `layer_defs`: Required. The parameters to this command are a series of graph names. These represent the names of the layers, as provided to glscene::SceneGraph::SceneGraph(), and the order you place them in the list is the order that they will be provided in.
-- `variant_check`: Optional. The parameters to this command are a series of identifier strings. If you provide this command, the use of any variant names not listed here will result in a parse error.
+- `style_check`: Optional. The parameters to this command are a series of identifier strings. If you provide this command, the use of any style names not listed here will result in a parse error.
 - One or more `node` commands, [as described below](\ref page_glscene_file_format_syntax_scene_node).
 
 \par A Word on the Root Node
-The [GL Scene Graph](\ref module_glscene) has a root node. And glscene::SceneGraph freely allows you to fetch this node, add variants to it, change its transforms, and play with it as though it were any other node (mostly). However, the scene graph file format does not expose this functionality. You cannot set any of these things on the root node. This is quite deliberate.
+The [GL Scene Graph](\ref module_glscene) has a root node. And glscene::SceneGraph freely allows you to fetch this node, add styles to it, change its transforms, and play with it as though it were any other node (mostly). However, the scene graph file format does not expose this functionality. You cannot set any of these things on the root node. This is quite deliberate.
 \par
 Becaue the root node is restricted in its functionality, such as re-parenting, deleting, and querying-by-name, the scene file format encourages you to create your own root. This makes it easier for you to move things around dynamically. It also makes it easier for you to change things later, since you can copy node definitions around more freely.
 
 
 The contents of a node are rigidly ordered. The sub-commands must be provided in the following order:
 
-- `layers`: Optional. This provides a list of layers that the node is a member of. This list has some complexities to it, so there is [a section dedicated to them](\ref page_glscene_file_format_syntax_scene_node_layers).
+- `layers`: Optional. This provides a list of layers that the node is a member of. This list has some complex features in it, so there is [a section dedicated to them](\ref page_glscene_file_format_syntax_scene_node_layers).
 - `node_tm` and `object_tm`: Optional. The two commands can be in any order, but they can only be provided once and only before the next group of commands. These define the [node and object transforms](\ref module_glscene_node_transforms) for the node.
+- `local`: A local list of node style commands. These make it easy to have multiple styles and nodes use similar style commands. You may provide zero or more of these.
+- `style`: A style definition. You may provide zero or more of these.
 - `node`: A child node of the current node. You may provide zero or more of them.
 
 ### Node Layers ### {#page_glscene_file_format_syntax_scene_node_layers}
 - `scale (vec3)`: Provides a scaling transform. This is a 3-element floating-point vector, so the elements must be in parentheses.
 - `translate (vec3)`: Provides a translation transform.
 - `orientation (quaternion)`: Provides an orientation transform as a quaternion.
-- `angle_axis (angle) (axis)`: Provides an angle/axis rotation transform as an angle/axis. `axis` is a vec3, while `angle` is a float. `angle` is in *degrees*.
+- `angle_axis (angle) (axis)`: Provides an angle/axis rotation transform as an angle/axis.
+	- `angle`: A floating point angle, in *degrees*.
+	- `axis`: A vec3 axis. It does not need to be normalized.
 - `matrix (mat4)`: Provides an arbitrary matrix transform. This is a full 16-float, column-major matrix.
 
 #### Composed and Decomposed ####
 
 Even though the scale is an identity scale, putting the orientation afterwards will still cause it to be composed.
 
+### Style and Locals ### {#page_glscene_file_format_syntax_scene_node_style}
+
+\verbatim
+local <local_name>
+//definitions
+end
+
+style <style_name>
+//local inclusions
+
+//definitions
+end
+\endverbatim
+
+The `local` and `style` commands have almost identical content, though not identical meaning.
+
+`local` commands create a set of commands that can be included by `style` commands. This helps cut down on the amount of duplication in writing similar `style`s.
+
+The `local_name` and `style_name` are identifier strings. Both identifiers must be unique within the same node, but they have different namespaces. So a `local` and `style` can have the same name within the node. If the scene graph has a `style_check` command, then the `style_name` must be one of the listed styles.
+
+The only difference (in syntax) between the definition of `local` and `style` are that `style` can have a `using` command. If it is present, it must be the first command.
+
+The commands available for `local` and `style` are as follows. They can be in any order, except for `using`, which can only be on `style` and if it is present, it must be the first command. All resource identifier names must have resources of the corresponding type defined by prior `resources` commands.
+
+- `using <local1> <local2> ...`: Optional, and only available for `style`. This defines the list of locals who's commands will be included in this `style`.
+- `mesh <mesh_resource_name> 'mesh_variant_name'`: Optional, and only one can be provided. This defines the mesh resource to use in the `style`/`local`. If `mesh_resource_name` is not a mesh resource name previously defined by the scene graph, this will error.
+	- `mesh_variant_name`: The mesh's variant name. Optional.
+- `program` or `pipeline`: Optional, and only one can be provided. [These commands](\ref page_glscene_file_format_syntax_scene_node_program) set up the program resource(s) to use, as well as any global uniform resources to use with the program. `pipeline` sets up a separable program pipeline.
+- `texture (unit) <texture_resource> <sampler_resource>`: Optional. Multiple `texture`s may be provided. This represents the binding of a texture and sampler object to the given texture image unit.
+	- `unit`: An unsigned integer, and the two resources must name actual resources previously established.
+- `uniform_buffer (binding) <uniform_buffer_resource> (offset)?`: Optional. Multiple `uniform_buffer`s may be provided. This represents the binding of a uniform buffer resource to the given buffer object binding point.
+	- `binding`: An unsigned integer representing the binding point.
+	- `offset`: An optional unsigned integer byte offset for the binding.
+- `storage_buffer (binding) <storage_buffer_resource> (offset)?`: Optional. Multiple `storage_buffer`s may be provided. This represents the binding of a shader storage buffer resource to the given buffer object binding point.
+	- `binding`: An unsigned integer representing the binding point.
+	- `offset`: An optional unsigned integer byte offset for the binding.
+
+#### Style Validity ####
+
+The inclusion mechanism for styles, the ability for a `style` command to include the sub-commands of one or more `local` commands creates a separation between the syntax of a `style` and the semantics of it. Therefore, there are a number of additional rules surrounding styles that must be followed; failure to do so will result in a parse-time error.
+
+Every style must provide a `mesh` and a `program` or `pipeline` command, either directly or indirectly via inclusion. In order to allow inclusions to include these definitions, the `style` command is not required to have one of these. However, a style must define one or include a local that does define one.
+
+Also, a style must not provide more than one `mesh` command, nor may it provide more than one `program` or `pipeline`. And it cannot provide both a `program` or `pipeline` command. The `style` and `local` commands are syntactically prevented from providing multiple commands, but inclusions still make it possible.
+
+A style must not include any two resource binding commands that bind to the same binding point. So if you have multiple texture bindings, eitehr directly or via inclusion, they must all bind to different texture units.
+
+The system will detect these automatically and generate errors for violating these conditions.
+
+#### Inclusion Scoping ####
+
+Styles can include locals defined in the node that the style is defined in. But they can also include locals from *parent* nodes. Indeed, the style's `using` command can include any local from any parent.
+
+Scoping works like C/C++ scoping. So first the current node's is checked, then each parent node from most recent to the farthest, until a match is found. This means that more recent `local`s that use the same name will shadow less recent ones. Consider the following:
+
+\verbatim
+node
+ local <foo>
+  //Stuff
+ end
+ node
+  local <foo>
+  end
+  style <bar>
+   using <foo>
+  end
+ end
+end
+\endverbatim
+
+The `using` command will include the local `<foo>` declared in the current node, not the one declared by the parent.
+
+### Programs and Pipelines ### {#page_glscene_file_format_syntax_scene_node_program}
+
+\verbatim
+program <program_resource>
+  //Uniform commands
+end
+pipeline
+  program <program_resource> [stage1] [stage2]...
+  //Uniform commands
+  end
+end
+\endverbatim
+
+`program` and `pipeline` are subcommands of `local` and `style`. They define a program resource or program pipeline to build for a style, as well as any global uniforms associated with them. The `program_resource` parameter used in these commands must be a previously defined resource.
+
+The `program` command causes the style to use a specific, single program which contains all of the code for all applicable shader stages. The `pipeline` command builds a program pipeline object out of a number of different programs. A `style` or `local` can only define one or the other of these commands, and they cannot have more than one.
+
+The `pipeline` subcommand `program` works almost identically to the higher-level `program` command, except that the `program_resource` is followed by a sequence of `[stage]` enumerators. These enumerators define which stages the given program affects; they are a list and at least one stage must be specified. Multiple `program` subcommands can be listed, but the same stage cannot be specified multiple times. Also, the same `program` subcommand cannot use the same stage twice.
+
+The `program` command (whether within `pipeline` or not) has only one sub-command. It can appear 0 or more times:
+
+- `uniform <uniform_resource>`: Defines a global uniform resource to be used by the program object.
+
+
 **/
 
 

File glscene/source/Parse.cpp

 					ThrowParseError("`layer_defs` members must be '' strings.", curr_throw);
 			}
 
-			if(IsCurrToken(TOK_VARIANT_CHECK))
+			if(IsCurrToken(TOK_STYLE_CHECK))
 			{
 				EatOneToken();
 				while(IsCurrToken(TOK_IDENTIFIER))
 				{
-					std::string variantName = GetStringTokenData();
-					IdString variantId = variantName;
-					if(m_scene.variantChecks.find(variantId) != m_scene.variantChecks.end())
-						ThrowParseError("The variant check '" + variantName + "' has already been defined.", curr_throw);
-					m_scene.variantChecks.insert(variantId);
+					std::string styleName = GetStringTokenData();
+					IdString styleId = styleName;
+					if(m_scene.styleChecks.find(styleId) != m_scene.styleChecks.end())
+						ThrowParseError("The style check '" + styleName + "' has already been defined.", curr_throw);
+					m_scene.styleChecks.insert(styleId);
 					EatOneToken();
 				}
 				if(!IsCurrTokenCategory(KEYWORD_ID_PREFIX))
-					ThrowParseError("`variant_check` members must be identifier strings.", curr_throw);
+					ThrowParseError("`style_check` members must be identifier strings.", curr_throw);
 			}
 
 			if(!IsCurrToken(TOK_NODE))
 			catch(BaseParseError &)
 			{
 				if(IsCurrTokenCategory(KEYWORD_ID_PREFIX))
-					ThrowParseError("Incorrect command or command out of order in `node`.\n`layers` comes first, then transforms, `local`s, `variant`s, and lastly `node`s.", curr_throw);
+					ThrowParseError("Incorrect command or command out of order in `node`.\n`layers` comes first, then transforms, `local`s, `style`s, and lastly `node`s.", curr_throw);
 				else
 					throw;
 			}
 			ParsedUniformDef &uniformDef = m_resources.uniforms[ident];
 			uniformDef.pos = m_posStack.top();
 
+			uniformDef.glslUniformName = ParseGlslIdentifier();
 			int uniformType = ParseEnumerator(g_uniformTypeEnumeration);
 			uniformDef.data = ParseUniformData(uniformType);
 		}
 
 		std::string ParseGlslIdentifier(const Token &owningTok)
 		{
+			return ParseGlslIdentifier();
+		}
+
+		std::string ParseGlslIdentifier()
+		{
 			ExpectToken(TOK_GLSL_IDENT);
 			std::string rawToken = GetTokenText();
 			EatOneToken();

File glscene/source/ParsedData.h

 	struct ParsedUniformDef
 	{
 		FilePosition pos;
+		std::string glslUniformName;
 		UniformData data;
 	};
 
 		FilePosition pos;
 		LayerSet layers;
 		std::vector<std::string> layerOrder;
-		boost::container::flat_set<IdString> variantChecks;
+		boost::container::flat_set<IdString> styleChecks;
 		boost::container::flat_map<IdString, FilePosition> nodeNamePositions;
 		boost::container::stable_vector<ParsedNodeDef> nodes;
 	};

File glscene/source/keywords.incl

 	MAC(TEXTURE_RES,	"texture_res",	"texture resource",			"mesh resource")
 	MAC(SCENE,			"scene",		"scene graph",				"scene graph")
 	MAC(LAYER_DEFS,		"layer_defs",	"layer definition",			"layer definition")
-	MAC(VARIANT_CHECK,	"variant_check",	"variant checking",		"variant checking")
+	MAC(STYLE_CHECK,	"style_check",	"style checking",			"style checking")
 	MAC(NODE,			"node",			"scene graph node",			"scene graph node")
 	MAC(LAYERS,			"layers",		"layer declaration",		"layer declaration")
 	MAC(NODE_TM,		"node_tm",		"node transform",			"node transform")