Fabrizio Hernández avatar Fabrizio Hernández committed 2793d21

Added the README file.

Comments (0)

Files changed (1)

+# 8bitAnimator.js
+
+`8bitAnimator.js` is an ultra-small ultra-hackish javascript library with the solely porpouse of creating and displaying
+8bit-like animations inside any div. Such animation is displayed using divs as "pixels" inside the
+div that will serve as screen.
+
+It has _several_ interesting features:
+
+* An animation can have **unlimited** number of color palettes.
+* Each animation frame can specify it`s own display time and color palette.
+* The animation can be showed in **any** div.
+
+Creating and showing an animation is pretty simple; let`s see
+how 8bitAnimator.js represents animations.
+
+## Animations
+
+Animations are defined as `json` objects. Each `animation` object is must contain:
+
+* `dimention`: A two dimentional array containing two integers, each one corresponding to the number of
+pixels in the screen (width and height).
+        [size_x, siez_y]
+
+* `pixSize`: An integer that specifies how many real pixels each div-pixel is going to use in the browser.
+
+* `repeat`: A boolean value that specifies if the animation must loop or stop after being shown once.
+
+* `palettes`: An array of the palettes to be used within the animation. Each palette is nothing but an array of
+(a maximun of ten) css valid color codes or names.
+
+* `frames`: An array of `frame` objects. Each frame object must contain:
+    + `duration`: An integer that specifies how much time (in millisecons) should the frame be displayed.
+    + `palette`: An integer that represents the color palette`s index to use while drawing the frame.
+    + `frame`: An array of integer arrays. Each array represents a pixel row in the frame. Each integer is the
+    color index to use for the corresponding pixel according to the used palette.
+
+### You talk too much, gimme examples
+
+Ok I know, this is an example of a very simple (it has just one single frame for the sake of simplicity) animation
+object defined in json:
+
+    {
+        "frames": [
+            {
+                "frame":
+                [
+                    [1,0,0,0,0,0,0,0,0,0],
+                    [1,1,0,0,0,0,0,0,0,0],
+                    [1,1,1,0,0,0,0,0,0,0],
+                    [1,1,1,1,0,0,0,0,0,0],
+                    [1,1,1,1,1,0,0,0,0,0],
+                    [1,1,1,1,1,1,0,0,0,0],
+                    [1,1,1,1,1,0,0,0,0,0],
+                    [1,1,1,1,0,0,0,0,0,0],
+                    [1,1,1,0,0,0,0,0,0,0],
+                    [1,1,0,0,0,0,0,0,0,0]
+                ],
+                "duration": 5000, 
+                "palette": 0
+            }
+        ],
+        "dimention": [10, 10], 
+        "pixSize": 20;
+        "repeat": true,
+        "palettes": [
+            [
+                "white", "black"
+            ]
+        ]
+    }
+
+Simple, isn't it?
+
+## Glorious API
+
+Super easy! You can define your animation object inside a remote json file, a json string inside your code, or directly
+coding the object in your js code. `8bitAnimator.js` has a simple function call for each case.
+
+Using as example the next page:
+
+    <!DOCTYPE html>
+    <html>
+    <head>
+        <script src="8bitanimator.js"></script>
+    </head>
+    <body>
+        <div id="container">
+        </div>
+    </body>
+    </html>
+
+You may call:
+
+* `animator8.animateUrl(containerId, animationURL)`: In the case you've got a remote json animation saved file (why wouldn't
+you? :) you would call something like `animator8.animateUrl("container", "url/To/Remote/Json/Object.json")`.
+* `animator8.animateObject(containerId, animationObject)`: Use this is you defined you builded your animation as a
+javascript object instead of a json string.
+* `animator8.animateObject(containerId, animateString)`: I'm not sure if anyone would use this, but in this case
+you need to pass an actual json string defining the animation.
+
+Wanna see a live example? [C'mere!][1] (it's also included in the source)
+
+## Graphical editor
+
+Along with the source (which is super small and ugly) there's a dead simple graphical editor. Performance 
+is more than poor, and it lacks so many feature. But hey, it's graphical! Also, it supports saving and loading
+animations. Use it with chrome. [Click here to see it live][2].
+
+***
+
+Use `8bitAnimator.js` for your pleasure and profit.
+Feel free to cooperate in the development, too. I'm pretty open-minded.
+
+[1]: http://fabzter.com/tests/8bit_animator/test/
+[2]: http://fabzter.com/tests/8bit_animator/editor/
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.