summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--README.md54
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.