Created Defining custom shaders (markdown)

Defining-custom-shaders.md

@@ -0,0 +1,50 @@
+There are currently three basic classes of shaders, any of which can be used to define a custom shader:
+
+- **org.dynmap.hdmap.DefaultHDShader** - this shader supports the equivalents of the FlatMap and KzedMap color models, including the use of colorschemes, and various biome-based coloring
+
+- **org.dynmap.hdmap.CaveHDShader** - this shader supports the cave-based coloring scheme
+
+- **org.dynmap.hdmap.TexturePackHDShader** - this shader allows the use of Minecraft Texture Packs, including the default texture pack for the Minecraft client
+
+## Defining a custom DefaultHDShader shader
+The DefaultHDShader class supports the following configuration settings:
+
+    shaders:
+      - class: org.dynmap.hdmap.DefaultHDShader
+        name: myshadername
+        colorscheme: ovocean
+
+As with other definitions, the _name_ attribute is required and must be unique.  If a custom shader definition provided in the **custom-shaders.txt** file has the same name as a standard shader, the standard shader will be replaced.
+
+The additional attributes are all optional, with corresponding default behaviors:
+
+- _colorscheme_ : this defines which colorscheme is used for coloring data.  These correspond to the files found in the **colorschemes/** directory, and include **default**, **ovocean**, **flames**, and **sk89q**.  These files define coloring data for both normal block coloring, or the various biome-based coloring options.  The default value is **default**.
+
+- _biomecolored_ : this defines what biome-data based coloring is done, if any.  The defined values include **none** (the default, which results in blocks being colored based on their block type), **biome** (which colors the blocks based on their biome type), **temperature** (which colors the blocks based on the raw biome temperature data), or **rainfall** (which colors the blocks based on the raw biome rainfall/humidity data).
+
+- _transparency_ : this controls whether transparency information is used or ignored.  Defined values are **true** (the default, where transparency is processed normally) or **false** (where all blocks are treated as opaque).
+
+## Defining a custom CaveHDShader shader
+The CaveHDShader currently supports no options beyond the name of the shader, so defining a custom CaveHDShader currently serves no useful purpose.  Future Dynmap releases expect to add options for defining the colors used for cave shading.
+
+## Defining a custom TexturePackHDShader shader
+
+The TexturePackHDShader class is the most likely shader to be customized, as this is required in order to make use of an add-on Minecraft Texture pack.  The TexturePackHDShader class supports the standard texture pack features, as well as many of the add-on features provided through the MCPatcher client patcher, including hi-resolution textures, custom water and lava, and custom biome shading for grass and leaves.
+
+An example of a typical texture pack shader configuration is shown below:
+
+    shaders:
+      - class: org.dynmap.hdmap.TexturePackHDShader
+        name: mytexturepackshader
+        texturepack: my-favorite-texturepack-v2.1.zip
+        biomeshaded: true
+
+The settings for the TexturePackHDShader include:
+
+- _name_ : the unique name of the shader
+
+- _texturepack_ : The name of the texture pack file (if it is a ZIP file), or the directory containing the extracted texture pack (which must include the minimum texture pack files - **terrain.png**, **misc/grasscolor.png**, **misc/foliagecolor.png**, and **misc/water.png**).  Texture pack ZIP files or directories must be in the **texturepacks** directory under **plugins/dynmap**.
+
+- _biomeshaded_ : This setting controls whether grass and leaves are colored based on raw biome data (temperature and rainfall).  If set to **true** (the default), biome-shading is enabled.  If set to **false**, all grass and leaves are shaded consistently, based on the averaged colors from the **misc/grasscolor.png** and **misc/foliagecolor.png#**files, respectively.
+
+