Assets¶
PursuedPyBear features a background, eager-loading asset system. The first time an asset is referenced, PPB starts reading and parsing it in a background thread.
The data is kept in memory for the lifetime of the Asset
. When
nothing is referencing it any more, the Python garbage collector will clean up
the object and its data.
Asset
instances are consolidated or “interned”: if you ask for the
same asset twice, you’ll get the same instance back. Note that this is a
performance optimization and should not be relied upon (do not do things like
asset1 is asset2
).
General Asset Interface¶
All assets inherit from Asset
. It handles the background loading
system and the data logistics.
-
class
ppb.assetlib.
Asset
(name)[source]¶ A resource to be loaded from the filesystem and used.
Meant to be subclassed, but in specific ways.
-
file_missing
()¶ Called if the file could not be found, to produce a default value.
Subclasses may want to define this.
Called in the background thread.
-
load
(timeout: float = None)¶ Gets the parsed data.
Will block until the data is loaded.
-
is_loaded
()¶ Returns if the data has been loaded and parsed.
-
Subclassing¶
Asset
makes specific assumptions and is only suitable for loading
file-based assets. These make the consolidation, background-loading, and other
aspects of Asset
possible.
You should really only implement three methods:
background_parse()
: This is called with the loaded data and returns an object constructed from that data. This is called from a background thread and its return value is accessible fromload()
This is an excellent place for decompression, data parsing, and other tasks needed to turn a pile of bytes into a useful data structure.
file_missing()
: This is called if the asset is not found. Defining this method surpressesload()
from raising aFileNotFoundError
and will instead call this, andload()
will return what this returns.For example,
ppb.Image
uses this to produce the default square.free()
: This is to clean up any resources that would not normally be cleaned up by Python’s garbage collector. If you are integrating external libraries, you may need this.
Concrete Assets¶
While Asset
can load anything, it only produces bytes, limiting its
usefulness. Most likely, you want a concrete subclass that does something more
useful.
-
class
ppb.
Image
(name)[source]¶ Loads an image file and parses it into a form usable by the renderer.
-
class
ppb.
Sound
(name)[source] Loads and decodes an image file. A variety of formats are supported.
Asset Proxies and Virtual Assets¶
Asset Proxies and Virtual Assets are assets that implement the interface but either delegate to other Assets or are completely synthesized.
For example, ppb.features.animation.Animation
is an asset proxy that
delegates to actual ppb.Image
instances.