This is the readme for my mod (daaa's mod) of 
Grimfate126's "animlib" in lua, currently version 0.1,
first release.

If you need help, look for the release thread in the
QJ forums, or drop me a PM, I'm daaa57150 there. But
before, look at this tutorial and at the index.lua
it should be easy.
You can also send me a mail at daaa57150@gmail.com but
I'll answer really slowly there.

Please if you use it, give me and Grimfate126 credit
somewhere.

daaa.



1) WHAT DOES THIS LIBRARY DO:
This allows you to create animation objects based on
spritesheets or multiple images, for your lua scripts.
It buffers the pictures if you have many copy of the same
animation, and can keep them (the pictures) in memory even if
they are  destroyed in the case you want to create a copy of 
the animation later.
The animations are customizable in speed and loop numbers,
independently from each other. Playback can be started, paused,
resumed, resetted. Many utility functions are also available to
get or set some properties (isRunning, nbImages etc...).

2) WHAT DOESN'T THIS LIBRARY DO:
- It's not precise on the time, you can have 2 same animations
and start them at the exact same time, and still see one go 
faster. If you want sync'ed animations, you'll need to find a
way yourself.
- Does not permit to have the same image multiple times in the
same animation, for the moment at least.
- Does not permit to have delay variations in the animation, 
each frame is separated from the previous one by the same 
amount of time.
- Contrary to what Grimfate said, there seem to be a limitation
with the spritesheets, sizewise.


3) WHAT'S DIFFERENT FROM ANIMLIB V4:
- No more distinction between spritesheets and multiple images
animations, exept during creation of course. This allows you
to have tables with a mix of the 2 kinds, and calling the exact
same function on all items without caring anymore.
- Loops limitation and speed are set during construction, and
not parameterized during blitting. This can be altered with 
setter methods on the object. So there is no more advancedBlit().
- Blit functions require a target, usually you'll do it on the
'screen' var but you may want to blit it on an image, so it's
possible now.
- I removed garbage collection from the library, you'll have to 
call it when appropriate. This is so it's not called multiple
times in a freeing loop for example.
- Images used in animations are buffered, so if you have many
animations based on the same images, they won't be loaded as 
many times as you have animations, but will be shared amongst
them. There are also some memory functions to allow you to
prebuffer the images you'll need, and ask them to stay in 
memory even if no more animation uses them. This will allow you
to create an animation based on them later, without loading. By
default, they are shared but will be unloaded once no animation
need them anymore.
- Animations don't start automatically, you'll have to call the
start method.
- Certainly other things I don't remember, I changed so many...


3) HOW TO INCLUDE THIS IN YOUR CODE:
Simply add this line at the beginning of your code:

dofile("animLibDaaa.lua")

and you'll be able to use my functions.

4) MEMORY MANAGEMENT
Images that the animations need are shared between all the
animations that need them. A reference based on the image
url is kept in memory to achieve this.
There are 2 modes available to manage this:

- By default, the first time an image is needed it is loaded
and your animation will use it. Further animations you create
that need that image will simply use the one already loaded.
If all your animations are freed, so none needs the image
anymore, the library will unload the image automatically. So
you'll always have the max memory possible available. The 
counterpart for this is that if you need that image again,
the library will need to reload it.

- In the second mode, the first time an image is needed it is
loaded and your animation will use it. Further animations you 
create that need that image will simply use the one already 
loaded. If all your animations are freed, so none needs the 
image anymore, it is kept in memory. So next time you create
an animation that needs it, you'll experience no loading. The
counterpart of this is that you'll have to manage the images
you keep in memory and force unloading yourself when appropriate.
There are many functions that help you doing this easily.
Look in the index.lua file for an example.

This behaviour is set per image, so you can have some that
behave in a way and some the other way.
To change from one mode to the other use those 2 functions:
ANIM.setDefaultMemoryModeToAlwaysFree(): free as soon as possible
ANIM.setDefaultMemoryModeToBuffer(): keep in memory
This will affect further image loadings (ie: new animation creations).
You can preload images before image creation by using this
function:
ANIM.bufferImage(file)
this will put this specific image in the second mode and load it.

WARNING:
For this to work, ie the images references counters to be
always correct, you have to call the free method on your
animations! This is important! If you don't you'll end up
with all the images staying in memory (one copy), and maybe
animations with references on images that are non-existent.

To "unbuffer" an image, call the function
ANIM.freeImage(file)
This will mark it to be at mode 1 (default), ie the image will
be unloded from memory as soon as it is not referenced anymore.
When calling this function, if there are already no reference
to this image, it is unloaded directly.

Note that in my code there are no calls to collectgarbage().
You'll have to call it when you see fit.

I'm using mode 2 in my index.lua file, read it to understand
this. Comment the line that says:
ANIM.setDefaultMemoryModeToBuffer()
to let it be at mode 1, and start the program to see the
difference. You should see the psp load images on the MS on 
the first creation of an animation.





5) MEMORY FUNCTIONS:
-------------------------------------------------------------
ANIM.setDefaultMemoryModeToAlwaysFree()
-------------------------------------------------------------
Sets the default memory mode to favor memory, ie the images
will be unloaded from memory as soon as no animation needs
them anymore. This applies to subsequent images loading, ie
during the construction of a new animation that needs an
image not already loaded.
Images already in memory are not affected.

-------------------------------------------------------------
ANIM.setDefaultMemoryModeToBuffer()
-------------------------------------------------------------
Sets the default memory mode to favor speed, ie the images
will stay in memory even if no animation needs them. You will
have to unload them with the freeImage function. his applies 
to subsequent images loading, ie during the construction of 
a new animation that needs an image not already loaded.
Images already in memory are not affected.

-------------------------------------------------------------
ANIM.bufferImage(file)
-------------------------------------------------------------
Pre-buffers an image, so it is already in memory when you'll
create animations. The memory mode is set to buffer mode for
this image.
"file" is the path to the image to buffer.

-------------------------------------------------------------
ANIM.freeImage(file)
-------------------------------------------------------------
Unloads an image from memory if no animation references it,
or marks it to be in mode 1 so that it is unloaded as soon as
no animation references it anymore.
"file" is the path to the image to delete.

-------------------------------------------------------------
ANIM.freeAllImages()
-------------------------------------------------------------
Same as the function above, but for all the images that the
library has loaded.



6) CREATOR FUNCTIONS
-------------------------------------------------------------
ANIM.newMultImgAnim(nbImages, header, extension, where, delay, maxLoops)
-------------------------------------------------------------
Creates a new animation, based on multiple images. Those 
images need to be at the same place on the filesystem and be
named the same way with a number at the end, like this:
"<header><number>.<extension>"
for example "my_image_4.png".

nbImages: number of images your animation is composed of.
header: beginning of the name of your images.
extension: the extension of your images ("png" or "jpg").
where: folder where they are. Must end with a "/", or can be 
equal to "" or be nil (which will make it equal to "").
delay: time separating 2 frames, in ms.
maxLoops: tells how many loops the animation does before
stopping on the last frame. Leave it nil for endless looping.


-------------------------------------------------------------
ANIM.newSpriteSheetAnim(file, nWidth, nHeight, delay, maxLoops)
-------------------------------------------------------------
Creates a new animation, based on a spritesheet.
file: path to your spritesheet image
nWidth: width in pixels of one frame in this image.
nHeight: height in pixels of one frame in this image.
delay: time separating 2 frames, in ms.
maxLoops: tells how many loops the animation does before
stopping on the last frame. Leave it nil for endless looping.


7) METHODS
Call them like this:
myAnimation:theMethod(params)

-------------------------------------------------------------
blit(target, x, y)
-------------------------------------------------------------
Blits the animation on the target.
target: the image on which to blit the animation, "screen" for
example.
x, y: coordinates where to blit it.


-------------------------------------------------------------
width()
-------------------------------------------------------------
Returns the width of the currently displayed image.



-------------------------------------------------------------
height()
-------------------------------------------------------------
Returns the height of the currently displayed image.


-------------------------------------------------------------
getImage(num)
-------------------------------------------------------------
Returns the nth image in the animation, an Image object. This
object is either the image in memory for multImg animations,
or a newly created image cut in the spritesheet for 
spritesheet animations. Thus the uneffectiveness of this 
method with spritesheets.
When no parameter is given, the 1st image is returned for
multiple images animations, and the whole spritesheet image
for the spritesheets.
It is certainly a bad idea to use this method anyway, but 
it's here in case you need it.
Note that you may loose transparency in the process for
spritesheet animations (only semi transparent pixels), this
is a bug of luaplayer.


-------------------------------------------------------------
reset(num)
-------------------------------------------------------------
Resets the animation to the frame number "num", or the first
if no arg is supplied.
The animation will continue running if it was or stay paused
if it was.
num: the frame num where the animation should go. Only 
positive numbers allowed, and not 0. It starts at 1. It can 
be greater to the total frame number of the animation, this
will simply get to the asked frame as if loops have been made
but the loop counter won't change.
By default it goes to the first frame.


-------------------------------------------------------------
pause()
-------------------------------------------------------------
Pauses the animation. If it is already paused, it has no 
effect.


-------------------------------------------------------------
resume()
-------------------------------------------------------------
Resumes the animation, ie makes it run from where it is. If
the animation is already running it has no effect.


-------------------------------------------------------------
start()
-------------------------------------------------------------
Starts the animation from the beginning, the loop counter
is also resetted.


-------------------------------------------------------------
free()
-------------------------------------------------------------
Frees the animation, ie the object, and also the images if 
they are not referenced from another animation and the memory
management for them favors memory over speed.
If speed is favored, even when there are no more references 
on them they stay in memory, and you have to free them with 
ANIM.freeImage(file)


-------------------------------------------------------------
isRunning()
-------------------------------------------------------------
Returns true if the animation is running, false otherwise.


-------------------------------------------------------------
isPaused()
-------------------------------------------------------------
Returns true if the animation is paused, false otherwise.


-------------------------------------------------------------
finishedLooping(n)
-------------------------------------------------------------
Returns true if it has made n loops already, this is true if 
it has made more, or if it has reached the last frame of the 
nth loop.
n: the number of loops the animation must have finished.


-------------------------------------------------------------
setDelay(delay)
-------------------------------------------------------------
Changes the interval time between frames for this animation.
delay: the delay between 2 frames, in ms.


-------------------------------------------------------------
resetLoop()
-------------------------------------------------------------
Puts the loop counter at the beginning, ie 1.


-------------------------------------------------------------
getTime()
-------------------------------------------------------------
Returns the timer's time. This is the time from the last frame
change (or the beginning if no frame change occured). This is
NOT the time the animation is running, or from it's creation.


-------------------------------------------------------------
getFrame()
-------------------------------------------------------------
Returns the current frame number.


-------------------------------------------------------------
getLoops()
-------------------------------------------------------------
Returns the current loop number.


-------------------------------------------------------------
getRow()
-------------------------------------------------------------
Returns the current row, might be useful for spritesheet 
animations, always returns 1 for multiple images animations.
Row count starts at 1.


-------------------------------------------------------------
getColumn()
-------------------------------------------------------------
Returns the current column, might be useful for spritesheet 
animations, always returns 1 for multiple images animations.
Column count starts at 1.


-------------------------------------------------------------
setProp(prop)
-------------------------------------------------------------
This is a utility function, here as a way for you to attach
a property (can be a table of properties) to the animation,
like a name or id for example.
Get it again with getProp().


-------------------------------------------------------------
getProp()
-------------------------------------------------------------
This is a utility function, here as a way for you to get 
a property (can be a table of properties) you attached to 
the animation, like a name or id for example.
Set it with setProp().


-------------------------------------------------------------
getType()
-------------------------------------------------------------
Returns the type of animation it is, spritesheet or multiple
images. So it either returns: 
ANIM.TYPE_MULTIMG if it's a multiple images animation
or
ANIM.TYPE_SS if it's a spritesheet animation


-------------------------------------------------------------
getMaxLoops()
-------------------------------------------------------------
Returns the max loop number the animation was told to do when
created or when changed with setMaxLoops.


-------------------------------------------------------------
setMaxLoops(maxLoops)
-------------------------------------------------------------
Sets the maximum number of loops the animation must do before
stopping on the last frame. This won't make it run again if
it was stopped because it reached the max loop already.


-------------------------------------------------------------
getNbPictures()
-------------------------------------------------------------
Returns the number of images the animation is composed of. It
always returns 1 for spritesheet animations. This is not the
same as getNbFrames().


-------------------------------------------------------------
getNbFrames()
-------------------------------------------------------------
Returns the number of frames in the animation. This is 
different from getNbPictures for spritesheets.


-------------------------------------------------------------
getImageName(num)
-------------------------------------------------------------
Returns the name of the image number num in the animation.
If no arg is submitted, this returns the name of the first
image. For spritesheet animations it always returns the name
of the spritesheet image, as it's the only one.


-------------------------------------------------------------
unbufferImages()
-------------------------------------------------------------
Calls ANIM.freeImage() on each image the animation is
composed of.
Call this if you want to unbuffer the ressources attached to
this animation, so that when no copy exists anymore, the
images are freed from memory.
If you used the default mode for the memory ie you called 
	ANIM.setDefaultMemoryModeToAlwaysFree()
or didn't call 
	ANIM.setDefaultMemoryModeToBuffer()
and
	ANIM.bufferImage(file)
for an image in this animation, this won't have any effect as
everything is cleaned automatically when you'll call the 
free() method on the animation.



7) PAY ATTENTION TO THIS
- always call the free method on your animations
- be coherent in the file names you pass as params to the
functions.
"images/myimage.png", "./images/myimage.png" may describe the 
same image, but the library will consider them beeing 2 
different images! so choose which you prefer and stick to it.



8)INDEX.LUA:
This file creates, destroys, blits animations of the 2 types
(spritesheets: Alucard and multiple images animations: Richter).
It uses mode 2 for memory management, ie if no images are
in memory and no animation uses it, it stays here.
You can change this behaviour by commenting the line
ANIM.setDefaultMemoryModeToBuffer()
If you do so, you may see that when you delete all Alucards or
all Richters, and create on again, it will need a loading again.
Press cross to create a new Richter, circle to create a new
Alucard. Square erases the last created, without explicitely
unbuffering the images. You can add up to 56 animations, for
a total of 61 animations (4 buttons and the cursor). This will
make the PSP lag a bit around 20 animations I think.
Triangle pauses all the Alucards and Richters animations.
There is a cursor available, move it on the animations with
the DPad, and see the details at the bottom of the screen,
I tried to call as many functions as possible.



9) CONTACT
If you have some questions, think I should add or modify
something or simply want to tell me something, feel free to contact me.
The best way is on the QJ forums, in the release thread, or
by PM (I'm daaa57150). You can also reach me at this mail address:
daaa57150@gmail.com but I don't go there often.

Oh and if you use this for a game, tell me!

daaa.












