com.hdcookbook.grin.util
Class AssetFinder

java.lang.Object
  extended by com.hdcookbook.grin.util.AssetFinder

public class AssetFinder
extends java.lang.Object

This class serves two functions. First, it has a bunch of static methods that are used by GRIN and can be used by applications to find various resources. Secondly, an xlet (or other application) can create an instance of AssetFinder and bind it to us with the method setHelper. If this is done, AssetFinder will try to locate assets by first querying the helper. This way, an Xlet can make decisions about where to look for stuff. For example, a signed BD-Live xlet could set up a search path on the BUDA.

Author:
Bill Foote (http://jovial.com)

Constructor Summary
protected AssetFinder()
          See setHelper()
 
Method Summary
static void abort()
          Called when the disc playback should abort.
protected  void abortHelper()
          Called when the disc playback should abort.
static java.awt.Image createCompatibleImageBuffer(java.awt.Component c, int width, int height)
          Get an image buffer that's suitable for use double-buffering drawing to the componet c.
protected  java.awt.Image createCompatibleImageBufferHelper(java.awt.Component c, int width, int height)
          Subclasses can override this to return a different kind of buffered image, e.g.
static java.awt.Graphics2D createGraphicsFromImageBuffer(java.awt.Image buffer)
          Create a Graphic2D image for drawing into the given image buffer.
protected  java.awt.Graphics2D createGraphicsFromImageBufferHelper(java.awt.Image buffer)
          Subclasses can override this to work with a different kind of buffered image, e.g.
static void destroyImageBuffer(java.awt.Image buffer)
          Destroy an image buffer, freeing native resources that it uses (such as native memory used to hold a pixmap).
protected  void destroyImageBufferHelper(java.awt.Image buffer)
          Subclasses can override this to work with a different kind of buffered image, e.g.
static java.awt.Color getColor(int r, int g, int b, int a)
          Efficiently get a Color that's used within a Show.
static int getColorKeyCode(java.awt.Color c)
          Get the key code for the given color key.
protected  int getColorKeyCodeHelper(java.awt.Color c)
          Get the key code for the given color key.
static java.awt.Font getFont(java.lang.String fontName, int style, int size)
          Get a Font that's used within a Show.
protected  java.awt.Font getFontHelper(java.lang.String fontName, int style, int size)
          Helper subclass can override this in order to search for generic assets, like images.
static java.io.File[] getSearchPathFile()
          Get the appJarPathArg as set by setSearchPath()
static java.lang.String[] getSearchPathJar()
          Get the filePathArg as set by setSearchPath()
static java.net.URL getURL(java.lang.String path)
          Get a URL to an asset.
static java.awt.Image loadImage(java.lang.String path)
          Load an image from the given path.
protected  java.awt.Image loadImageHelper(java.lang.String path)
          Helper subclass can override this in order to search for images in some special way.
static void notifyLoaded(ManagedFullImage mi)
          Called by ManagedFullImage when an image finishes loading.
protected  void notifyLoadedHelper(ManagedFullImage mi)
          Called when a ManagedFullImage has finished loading.
static void notifyUnloaded(ManagedFullImage mi, int width, int height)
          Called by ManagedFullImage when a loaded image has been unloaded (flushed).
protected  void notifyUnloadedHelper(ManagedFullImage mi, int width, int height)
          Called when a ManagedFullImage has been unloaded (flushed).
static void setHelper(AssetFinder helperArg)
          An xlet can make an instance of a subclass of AssetFinder, and connect it to us by calling this method.
static void setImageMap(java.lang.String mapFile)
          Sets the image map.
static void setImageMap(java.lang.String[] mapFiles)
          Sets the image map to the concatination of the maps in the given files.
static void setSearchPath(java.lang.String[] appJarPathArg, java.io.File[] filePathArg)
           
static java.net.URL tryURL(java.lang.String path)
          Try to get an asset that might not be there.
protected  java.net.URL tryURLHelper(java.lang.String path)
          Helper subclass can override this in order to search for generic assets, like images.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

AssetFinder

protected AssetFinder()
See setHelper()

Method Detail

setHelper

public static void setHelper(AssetFinder helperArg)
An xlet can make an instance of a subclass of AssetFinder, and connect it to us by calling this method. Whenever the AssetFinder is looking for something, it will first check with the helper, by calling one of the helperXXX methods.


setSearchPath

public static void setSearchPath(java.lang.String[] appJarPathArg,
                                 java.io.File[] filePathArg)
Parameters:
appJarPathArg - A list of paths within the classpath of the app, for use by Class.getResource
filePathArg - A list of paths in the filesystem, e.g. from mounting a DSMCC carousel.

getSearchPathJar

public static java.lang.String[] getSearchPathJar()
Get the filePathArg as set by setSearchPath()


getSearchPathFile

public static java.io.File[] getSearchPathFile()
Get the appJarPathArg as set by setSearchPath()


setImageMap

public static void setImageMap(java.lang.String mapFile)
Sets the image map. This is used for mosaic images: The image map translates a logical image name into a tuple (mosaic image, rect within mosaic). This must be set after the search path, since the search path is used to load the image map.

If an image map was previously in place, it will be replaced with the new map as an atomic operation when the image map file has been completely read.

Parameters:
mapFile - The name of an image map file produced by MosaicMaker
See Also:
setImageMap(String[])

setImageMap

public static void setImageMap(java.lang.String[] mapFiles)
Sets the image map to the concatination of the maps in the given files. This is used for mosaic images: The image map translates a logical image name into a tuple (mosaic image, rect within mosaic). This must be set after the search path, since the search path is used to load the image map.

If an image map was previously in place, it will be replaced with the new map as an atomic operation when the image map file has been completely read.

It is up to the callee to make sure that there are no name collisions, either in the name of the source images, or in the names of the mosaics.

Parameters:
mapFiles - The name of image map files produced by MosaicMaker
See Also:
setImageMap(String)

getURL

public static java.net.URL getURL(java.lang.String path)
Get a URL to an asset. If the asset doesn't exist, emits debug messages and returns null.

Parameters:
path - A string, relative to the search path for assets TODO: Maybe need to search locators, too

tryURL

public static java.net.URL tryURL(java.lang.String path)
Try to get an asset that might not be there. If it's not, return null.


tryURLHelper

protected java.net.URL tryURLHelper(java.lang.String path)
Helper subclass can override this in order to search for generic assets, like images.


getColor

public static java.awt.Color getColor(int r,
                                      int g,
                                      int b,
                                      int a)
Efficiently get a Color that's used within a Show. This method might someday share one Color instance for multiple calls with the same rgba values.


getFont

public static java.awt.Font getFont(java.lang.String fontName,
                                    int style,
                                    int size)
Get a Font that's used within a Show. This method might someday share one Font instance and any needed font factories for multiple calls with the same specifications.


getFontHelper

protected java.awt.Font getFontHelper(java.lang.String fontName,
                                      int style,
                                      int size)
Helper subclass can override this in order to search for generic assets, like images.


createCompatibleImageBuffer

public static java.awt.Image createCompatibleImageBuffer(java.awt.Component c,
                                                         int width,
                                                         int height)
Get an image buffer that's suitable for use double-buffering drawing to the componet c. This is functionally equivalent to a java.awt.BufferedImage obtained from:

    c.getGraphicsConfiguration().createCompatibleImage(width, height)

 
In GEM-based systems, it is recommended that this be a DVBBufferedImage, for improved native memory management. See http://wiki.java.net/bin/view/Mobileandembedded/BDJImageMemoryManagement for a discussion of why.

Returns:
an off-screen image buffer
See Also:
createCompatibleImageBufferHelper(java.awt.Component, int, int), createGraphicsFromImageBuffer(java.awt.Image), destroyImageBuffer(java.awt.Image)

createCompatibleImageBufferHelper

protected java.awt.Image createCompatibleImageBufferHelper(java.awt.Component c,
                                                           int width,
                                                           int height)
Subclasses can override this to return a different kind of buffered image, e.g. DVBBufferedImage

See Also:
createCompatibleImageBufferHelper(java.awt.Component, int, int)

createGraphicsFromImageBuffer

public static java.awt.Graphics2D createGraphicsFromImageBuffer(java.awt.Image buffer)
Create a Graphic2D image for drawing into the given image buffer. This image buffer must have been obtained from createCompatibleImageBuffer().

See Also:
createCompatibleImageBuffer(java.awt.Component, int, int)

createGraphicsFromImageBufferHelper

protected java.awt.Graphics2D createGraphicsFromImageBufferHelper(java.awt.Image buffer)
Subclasses can override this to work with a different kind of buffered image, e.g. DVBBufferedImage

See Also:
createGraphicsFromImageBuffer(java.awt.Image)

destroyImageBuffer

public static void destroyImageBuffer(java.awt.Image buffer)
Destroy an image buffer, freeing native resources that it uses (such as native memory used to hold a pixmap). In Desktop java, this does nothing, because this is left to the garbage collector. In GEM-based systems, it should be equivalent to DVBBufferedImage.dispose(). See http://wiki.java.net/bin/view/Mobileandembedded/BDJImageMemoryManagement for a discussion of images and memory management.

See Also:
createCompatibleImageBuffer(java.awt.Component, int, int)

destroyImageBufferHelper

protected void destroyImageBufferHelper(java.awt.Image buffer)
Subclasses can override this to work with a different kind of buffered image, e.g. DVBBufferedImage

See Also:
destroyImageBuffer(java.awt.Image)

loadImage

public static java.awt.Image loadImage(java.lang.String path)
Load an image from the given path.

Parameters:
path - should be an absolute path within asset finder's path.

loadImageHelper

protected java.awt.Image loadImageHelper(java.lang.String path)
Helper subclass can override this in order to search for images in some special way. If the helper doesn't find one, the default AssetFinder implementation will call tryURL(), which the helper can also override. If you override tryURL() such that images can be located, there's no reason to override this method too.


getColorKeyCode

public static int getColorKeyCode(java.awt.Color c)
Get the key code for the given color key. The HD Cookbook has an algorithm that an xlet might choose to use, if it wants to assign the color keys in a way that works on most players. See the HD cookbook page 19-4, "Those Crazy Color Keys" for an algorithm.

Parameters:
c - A color that is == to one of the standard constants Color.red, Color.green, Color.yellow or Color.blue.
Returns:
A HAVi key code in the range 403..406 inclusive

getColorKeyCodeHelper

protected int getColorKeyCodeHelper(java.awt.Color c)
Get the key code for the given color key. Xlets may override this to do an intelligent assignment of the color keys. See the HD cookbook page 19-4, "Those Crazy Color Keys" for an algorithm.

An implementation of the cookbook's color key algorithm is also available, in the GrinXlet directory project. See, for example, xlets/GrinXlet/src/deploy/com/hdcookbook/grinxlet/GrinXlet.java

Parameters:
c - A color that is == to one of the standard constants Color.red, Color.green, Color.yellow or Color.blue.
Returns:
A HAVi key code in the range 403..406 inclusive

abort

public static void abort()
Called when the disc playback should abort. This should only be called when there's a fatal error, like an assertion failure. The expected behavior is immediate termination - like System.exit(1) on big JDK, or ejecting the disc on a player.


abortHelper

protected void abortHelper()
Called when the disc playback should abort. This should only be called when there's a fatal error, like an assertion failure. The expected behavior is immediate termination - like System.exit(1) on big JDK, or ejecting the disc on a player.


notifyLoaded

public static void notifyLoaded(ManagedFullImage mi)
Called by ManagedFullImage when an image finishes loading.

See Also:
notifyLoadedHelper(ManagedFullImage), notifyUnloaded(ManagedFullImage, int, int)

notifyLoadedHelper

protected void notifyLoadedHelper(ManagedFullImage mi)
Called when a ManagedFullImage has finished loading. By default this does nothing, but it can be overridden, e.g. for resource usage tracking. This will be called in one of the platform's image fetcher threads.

See Also:
notifyLoaded(ManagedFullImage), notifyUnloadedHelper(ManagedFullImage, int, int)

notifyUnloaded

public static void notifyUnloaded(ManagedFullImage mi,
                                  int width,
                                  int height)
Called by ManagedFullImage when a loaded image has been unloaded (flushed). This will be called from ManagedImage.unprepare(), which normally happens in the animation thread.

See Also:
notifyUnloadedHelper(ManagedFullImage, int, int), notifyLoaded(ManagedFullImage)

notifyUnloadedHelper

protected void notifyUnloadedHelper(ManagedFullImage mi,
                                    int width,
                                    int height)
Called when a ManagedFullImage has been unloaded (flushed). By default this does nothing, but it can be overridden, e.g. for resource usage tracking.

See Also:
notifyLoaded(ManagedFullImage), notifyLoadedHelper(ManagedFullImage)