Fever BitmapLib :: How to use BitmapData buffer

BitmapLib class allow user to load and cache image as BitmapData in application buffer.
But how it works exactly ?

BitmapLib class is a subclass of great Pixlib GraphicLib.
Thus, we keep all power features of GraphicLib ( anticache system, events support and more ).

Whereas GraphicLib loads an external image in a MovieClip target, BitmapLib tranform this loaded image into his BitmapData pixel representation.
No MovieClip is affected by this library.

The main goal ? store BitmapData data for multi-use.
You can load an image only one time and used it where you want, when you want and many time you want in your application.

BitmapLib has an internal system to store loaded image data named : BitmapLibLocator
BitmapLibLocator act like a repository for loaded image.
We can use the Fever default one, or create a specific one; it's your choice ;)

Memory leak with BitmapData ? sure... but you can organize your repository to allow a good and clean memory release.
How it works ? let's go !

First, we have to instanciate the BitmapLib class.

Constructor wait for only 1 parameter : the repository name !
If omitted, the BitmapData will be stored on the default BitmapLibLocator.
If BitmapLibLocator does not exist, it will be created.

As it is a GraphicLib subclass, we can use Pixlib methods to define event listeners and others lib properties, for example :

Now an important point on registration ( store ) process.
As we want to store loaded image in a repository, we have to define a registration ID before storing it.
This ID will allow us to retreive data in repository later.

There is 2 way to define this ID in BitmapLib.

• Using #setName( id : String ) method
• Using BitmapLib automatic naming process

As you see, we call #load( url : String ) method to start loading process.
Let's see how to retreive loaded image now.

BitmapData objects are stored in a BitmapLibLocator repository, so we have to :

• Retreives correct BitmapLibLocator ( default or your custom one ).
Retreives BitmapData using registration ID.

• BitmapLibLocator#getLocator( repositoryName : String ) : BitmapLibLocator
  • returns BitmapLibLocator defined by passed-in repositoryName name
  • returns the default BitmapLibLocator if omitted
  • creates new repository if not exist
• BitmapLibLocator#isRegistred( repositoryName : String ) : Boolean
  • returns true if a BitmapLibLocator is defined with repositoryName name
• BitmapLibLocator#getFullQualifiedData( id : String ) : BitmapData
  • shortcut method to retreive BitmapData without retreving BitmapLibLocator instance before
  • id must be a string identification formatted as : registration_id@locator_name
• BitmapLibLocator#unregister( repositoryName : String ) : Boolean
  • unregisters BitmapLibLocator registred with passed-in repositoryName
  • all BitmapData stored in it will be diposed

If you use the BitmapLibLocator#getLocator( ) method to retreives the BitmapLibLocator first, you can manage your BitmapData with ( instance methods ):

• #push( id : String, bmp : BitmapData ) : Boolean
  • stores a new bmp BitmapData object with id registration ID
  • if id already exist bmp is not stored
• #getData( id : String ) : BitmapData
  • returns BitmapData stored with passed-in id
• #exists( id : String ) : Boolean
  • returns true if a BitmapData is registred with the passed-in id
• #remove( id : String ) : Boolean
  • removes BitmapData stored with passed-in id
  • BitmapData is disposed
• #dispose() : Void
  • clears and dispose all BitmapData objects stored in current BitmapLibLocator

Some examples :

Of course, we can use direct #getContent() method of BitmapLib instance if we keep a reference to it; typically in an event handler after loading process.
Take an example with our previous event listener declaration :

Last note about BitmapLib and BitmapData managment, all retreives data are cloned to avoid BitmapData modification !

That's all, hope that I was clearly during this explanation.
You can contact me if some points still dark. ^_^

Romain Ecarnot