Rework texture generating code, add texture grouping via ( ... )

1 files changed, 72 insertions, 0 deletions

diff --git a/doc/lua_api.txt b/doc/lua_api.txt
index 28509a267..3d8038f87 100644
--- a/doc/lua_api.txt
+++ b/doc/lua_api.txt
@@ -186,6 +186,78 @@ stripping out the file extension:
   e.g. foomod_foothing.png
   e.g. foomod_foothing
 
+Texture modifiers
+-----------------
+There are various texture modifiers that can be used
+to generate textures on-the-fly.
+
+Texture overlaying:
+  Textures can be overlaid by putting a ^ between them.
+  Example: default_dirt.png^default_grass_side.png
+    default_grass_side.png is overlayed over default_dirt.png
+
+Texture grouping:
+  Textures can be grouped together by enclosing them in ( and ).
+  Example: cobble.png^(thing1.png^thing2.png)
+    A texture for 'thing1.png^thing2.png' is created and the resulting
+    texture is overlaid over cobble.png.
+
+Advanced texture modifiers:
+  [crack:<n>:<p>
+    n = animation frame count, p = current animation frame
+    Draw a step of the crack animation on the texture.
+    Example: default_cobble.png^[crack:10:1
+
+  [combine:<w>x<h>:<x1>,<y1>=<file1>:<x2>,<y2>=<file2>
+    w = width, h = height, x1/x2 = x position, y1/y1 = y position,
+    file1/file2 = texture to combine
+    Create a textue of size <w> x <h> and blit <file1> to (<x1>,<y1>)
+    and blit <file2> to (<x2>,<y2>).
+    Example: [combine:16x32:0,0=default_cobble.png:0,16=default_wood.png
+
+  [brighten
+    Brightens the texture.
+    Example: tnt_tnt_side.png^[brighten
+
+  [noalpha
+    Makes the texture completly opaque.
+    Example: default_leaves.png^[noalpha
+
+  [makealpha:<r>,<g>,<b>
+    Convert one color to transparency.
+    Example: default_cobble.png^[makealpha:128,128,128
+
+  [transform<t>
+    t = transformation(s) to apply
+    Rotates and/or flips the image.
+    <t> can be a number (between 0 and 7) or a transform name.
+	Rotations are counter-clockwise.
+     0  I      identity
+     1  R90    rotate by 90 degrees
+     2  R180   rotate by 180 degrees
+     3  R270   rotate by 270 degrees
+     4  FX     flip X
+     5  FXR90  flip X then rotate by 90 degrees
+     6  FY     flip Y
+     7  FYR90  flip Y then rotate by 90 degrees
+    Example: default_stone.png^[transformFXR90
+
+  [inventorycube{<top>{<left>{<right>
+     '^' is replaced by '&' in texture names
+    Create an inventory cube texture using the side textures.
+    Example: [inventorycube{grass.png{dirt.png&grass_side.png{dirt.png&grass_side.png
+     Creates an inventorycube with 'grass.png', 'dirt.png^grass_side.png' and
+     'dirt.png^grass_side.png' textures
+
+  [lowpart:<percent>:<file>
+    Blit the lower <percent>% part of <file> on the texture:
+    Example: base.png^[lowpart:25:overlay.png
+
+  [verticalframe:<t>:<n>
+    t = animation frame count, n = current animation frame
+    Crops the texture to a frame of a vertical animation.
+    Example: default_torch_animated.png^[verticalframe:16:8
+
 Sounds
 -------
 Only OGG Vorbis files are supported.