described DynamicPngStack in readme.txt

readme.txt

@@ -6,10 +6,14 @@ His blog is at http://www.catonmat.net  --  good coders code, great reuse.
 
 ------------------------------------------------------------------------------
 
-The module exports two objects - `Png` and `FixedPngStack`. The `Png` object
-is for creating PNG images from an RGBA buffer, and `FixedPngStack` object is
-for joining a number of PNGs together (stacking them together) on a
-transparent blackground.
+The module exports three objects: `Png`, `FixedPngStack` and `DynamicPngStack`.
+
+The `Png` object is for creating PNG images from an RGBA buffer.
+The `FixedPngStack` is for joining a number of PNGs together (stacking them
+together) on a transparent blackground.
+The `DynamicPngStack` is for joining a number of PNGs together in the most
+space efficient way (so that the canvas border matches the leftmost upper corner
+of some PNG and the rightmost bottom corner of some PNG).
 
 
 The `Png` object takes 3 arguments in its constructor:
@@ -50,6 +54,50 @@ buffers together and return a single PNG.
 All the regions that did not get covered will be transparent.
 
 
+The `DynamicPngStack` object doesn't take any arguments because its width and
+height is dynamically computed. To create it, do:
+
+    var dynamic_png = new DynamicPngStack();
+
+It provides three methods - `push`, `encode` and `dimensions`. The `push`
+and `encode` methods are the same as in `FixedPngStack`. You `push` each of
+the RGBA buffers to the stack and after that you call `encode`.
+
+The `dimensions` method is more interesting. It must be called only after
+`encode` as its values are calculated upon encoding the image. It returns an
+object with `width`, `height`, `x` and `y` properties. The `width` and
+`height` properties show the width and the height of the final image. The `x`
+and `y` propreties show the position of the leftmost upper PNG.
+
+Here is an example that illustrates it. Suppose you wish to join two PNGs
+together. One with width 100x40 at position (5, 10) and the other with
+width 20x20 at position (2, 210). First you create the DynamicPngStack
+object:
+
+    var dynamic_png = new DynamicPngStack();
+
+Next you push the RGBA buffers of the two PNGs to it:
+
+    dynamic_png.push(png1_buf, 5, 10, 100, 40);
+    dynamic_png.push(png2_buf, 2, 210, 20, 20);
+
+Now you can call `encode` to produce the final PNG:
+
+    var png = dynamic_png.encode();
+
+Now let's see what the dimensions are,
+
+    var dims = dynamic_png.dimensions();
+
+The x position `dims.x` is 2 because the 2nd png is closer to the left.
+The y position `dims.y` is 10 because the 1st png is closer to the top.
+The width `dims.width` is 103 because the first png stretches from x=5 to
+x=105, but the 2nd png starts only at x=2, so the first two pixels are not
+necessary and the width is 105-2=103.
+The height `dims.height` is 220 because the 2nd png is located at 210 and
+its height is 20, so it stretches to position 230, but the first png starts
+at 10, so the upper 10 pixels are not necessary and height becomes 230-10= 220.
+
 To get the node-png module compiled, you need to have libpng and node.js
 installed. Then just run: