Updated Defining volumetric models (markdown)

Defining-volumetric-models.md

@@ -1,43 +1,48 @@
-The files are line oriented, and can include comment lines (that start with '#').  Each block definition starts with line formatted as follows:
+Voumetric models are intended to provide a relatively convenient way to produce relatively complex shapes.  The application of textures to the volumetric models follow the same pattern as is done for simple cubes and for [cubiod models](Defining-cuboid-models) - the texture for each of the 6 faces is applied to the corresponding side of any of the subblocks within the model, with the texture scaled to the full size of the cube face.
 
-    block:id=N,data=D,scale=X
+The volumetric models are based on dividing each dimension of the block by a provided constant (the *scale*), which can be any power-of-2 up to 16 (1, 2, 4, 8, or 16).  This results in the cube being divided into a set of cubes, each of which is 1/*scale* x 1/*scale* x 1/*scale*.  The model is then defined by indicating which of these smaller blocks are filled by the model versus being empty.  
 
-Where:
+The model is defined in a number of lines: the first line is a "block:" line, and has the following attributes:
 
-* _id_ defines the block ID of the block being modeled.  There must be at least one _id=N_ attribute, but there may be as many as are needed (different block often share the same shaped model).
+* *id* - the block ID that the model is to be used for.  At least one *id* attribute is required, but as many as are needed can be used - allowing the same model to be used for multiple blocks.  See [Block ID Numbers](Texture-Definition-Files#block-id-numbers) for details on specifying block ID numbers.
+* *data* - this provides the specific metadata values that the model is to be applied to.  The default, *data=\**, indicates all metadata values for each of the blocks IDs indicated by the *id* attributes.  Otherwise, one or more *data=number* attributes can be used to select specific metadata values for the model.
+* *scale* - this is the number of divisions used for each axis of the model.  This results in the cube being divided into *scale* layers of subblocks, each of which is *scale* by *scale* subblocks.
 
-* _data_ defines the value of the block data for the block being modeled.  There must be at least one _data=D_ attribute, where _D_ can be '*' (meaning all data values - 0-15) or any value from 0 to 15.  There can be as many as are needed.  Note: for certain, special case block types, an additional data value (called the _render data_) is generated and used in preference to the normal _data_ value.  Currently, the special case blocks are those where the block ID and data are insufficient to select the model - chests, redstone wire, and fences.
+For example, the model for the piston extension facing down can be produced by a volumetric model by first dividing the cube into 8 parts on each axis:
 
-* _scale_ defines the scale of the grid of 'sub-blocks' composing the volume of the block.  A scale of X implies that the model for the block is being described relative to an X by X by X grid of cells.  X must be at least 2.  
+     block:id=34,data=0,data=8,scale=8
 
-After the _block_ line, the model can be described in one of two ways: either by describing the layers of cells that compose the block, or by referring to another model and describing a transformation to be applied to that model.
+After the "block:" record, one or more layers of blocks can be defined - ranging from layer 0 (the bottom layer) to layer (*scale*-1) (the top layer).  Each layer is defined by a "layer:" line, which has a comma separated list of numbers indicating which of the layers are being defined (if more than one layer uses the same pattern of subblocks, only the pattern only needs to be defined once).  The next *scale* lines after the "layer:" line define the pattern of the subblocks: each line represents one step of blocks in the Z axis (first is lowest, last is highest), and each has *scale* characters (representing the subblocks from the lowest to the highest on the X axis) - a '*' for a subblock filled by the model, or a '-' for a subblock left empty in the model.  Any layer not specified is assumed to consist of empty subblocks.
 
-To describe the model directly, the _block_ line is followed by one or more sets of _layers_.  These layers describe the cross-sections of the block, starting from the bottom (layer 0) to the top (layer X-1).  Each layer is described by X lines, each containing X characters.  The first line of a given layer is the northern edge of the block, while the last line is the southern edge.  The first character of each line corresponds to the western edge of the block, and the last represents the eastern edge.  Each layer definition is formatted as follows:
+For the piston extension facing down, the full definition is:
 
-    layer:A,B,C,D,...
-    ----
-    -**-
-    -**-
-    ----
+     block:id=34,data=0,data=8,scale=8
+     layer:2,3,4,5,6,7
+     --------
+     --------
+     --------
+     ---**---
+     ---**---
+     --------
+     --------
+     --------
+     layer:0,1
+     ********
+     ********
+     ********
+     ********
+     ********
+     ********
+     ********
+     ********
 
-Where:
+In this case, the cube is cut into 8 x 8 x 8 pieces: 8 layers of 8 x 8 subblocks.  The head of the piston fill the bottom two layers (layer 0 and 1), while the pushrod of the piston occupies the center 1/4 of the other layers (layer 2 to 7).
 
-* _A,B,C,D,..._ represents the one or more layer numbers described by the definition (this allows a given cross-section to be used more than once in the same model).  There must always be at least one layer number, with 0 representing the bottom layer of the model, and (X-1) (for a scale: X model) representing the top.
+## Volumetric Model Rotation
+As an alternative to manually defining additional volumetric models manually, additional volumetric models can be defined by rotating an existing volumetric model around the Y axis by 0, 90, 180, or 270 degrees.
 
-* Exactly _X_ lines follow the _layer_ tag, with exactly _X_ characters for each line.  These define a grid representing the cells of the layer of the model (_X_ by _X_), with the first line representing the north edge, the last representing the south edge, the first column representing the west edge, and the last column representing the east edge.  If a given character is '*', the cell is considered 'full'.  Otherwise, the cell is considered 'empty' (a '-' is used for these characters, by default).  The example shown above is representative of a _scale: 4_ model.
+To define a volumetric model by rotation, add the "block:" line as normal (be sure that the *scale* attribute matches the *scale* from the source model), and add a "rotate:" line immediately following it.  The attributes of the "rotate:" line include:
 
-Any layers that are not defined are assumed to be all empty.
-
-Alternately, the model can be defined by referring to another model, and describing a transform (specifically, a rotation about the vertical axis).  This is done with the _rotate_ tag, as shown below:
-
-    rotate:id=B,data=D,rot=R
-
-Where:
-
-* _id_ is the ID of the block definition being replicated.  This is required, and there can only be one value.
-
-* _data_ is the block data value of the block definition being replicated.  This is required and must be one value.
-
-* _rot_ defines the degrees of rotation around the vertical axis of the model.  _90_ causes the new model to be the same as the replicated model after rotating 90 degrees clockwise.  _180_ represents a 180 degree clockwise rotation.  _270_ represents a 270 degree clockwise (or 90 degree counter-clockwise) rotation.
-
-Note: the _scale_ of a block defined using the _rotate_ tag MUST match the _scale_ of the block model that is being copied and transformed.
+* *id* - the block ID of the source volumetric model (the model to be copied and rotated).  See [Block ID Numbers](Texture-Definition-Files#block-id-numbers) for details on specifying block ID numbers.  One *id* attribute is required.
+* *data*  - the metadata value of the source volumetric model.  One *data* attribute is required, and is required to be a number.
+* *rot* - the rotation value, in degrees around the Y axis.  Valid values are 0, 90, 180, and 270.  The *rot* attribute is required.