readme.md

1 files changed, 54 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..f173772
--- /dev/null
+++ b/README.md
@@ -0,0 +1,54 @@
+# imbricate
+
+Make tilesheets from directories of png files.
+
+## Use as a library
+
+    ;; clone the repo into ~/quicklisp/local-projects
+    (ql:quickload :imbricate) 
+    
+    (multiple-value-bind (sheet meta bad-paths) (imbricate:imbricate #P"/path/to/images/")
+       ;; save the sheet image to disk as a png file
+       (opticl:write-png-file "tilesheet.png" sheet)
+   
+       ;; print the first tile metainfo 
+       (print (car meta)) (terpri))
+       
+    ; prints, e.g. (:PATH "/path/to/images/an-image.png :X 0 :Y 0 :WIDTH 200 :HEIGHT 100)
+    ; or whatever your actual images are like. 
+    
+    
+The function `imbricate` will recurse down through a directory
+collecting PNG files as it goes. It will arrange those the images
+contained in those PNG files into a single large sheet that contains
+all of them, and return that as its first return value.  The files do
+not need to be the same size. 
+
+The second return value of `imbricate` is a list of PLISTs that look like:
+
+
+    (:PATH "/path/to/images/an-image.png :X 0 :Y 0 :WIDTH 200 :HEIGHT 100)
+    
+This way you can use the `:PATH` value to pick out a desired image
+from within a tilesheet, using the coordinates and dimensions to
+isolate that image's data within the sheet's texture.
+
+## Build as a command line tool
+
+The repo contains a `build.lisp` script that will build an executable
+SBCL Lisp image. 
+
+    sbcl --load build.lisp
+    
+From there you can use the imbricate command like so
+
+    #             SOURCE            TARGET           TITLE
+    ./imbricate /path/to/images/ /target/directory/ mysheet
+
+Which will put two files into `/target/directory/`, one pngfile
+containing the tilesheet, and another file containg the s-expressions
+represneting the tilesheet's meta data. 
+
+If any of the PNG files in the source directory could not be loaded,
+then a third file `mysheet.errors.txt` will appear containing the
+paths of the offending files.