acm.util
Class MediaTools

java.lang.Object
  acm.util.MediaTools

public class MediaTools
extends Object

This class implements a standard mechanism for loading images, sounds, and data files from the resources associated with a jar file.

Field Summary

String	DEFAULT_AUDIO_PATH The list of directories scanned for audio clips, separated by colons.
String	DEFAULT_DATAFILE_PATH The list of directories scanned for data files, separated by colons.
String	DEFAULT_IMAGE_PATH The list of directories scanned for images, separated by colons.

Method Summary

void	beep() This method sounds the audible alert on the console, which is typically a beep sound.
AudioClip	createAudioClip(InputStream in) Generates an audio clip from an input stream containing the data bytes for the audio clip.
AudioClip	createAudioClip(String[] hexData) Generates an audio clip from a string array that provides the sound values.
BufferedImage	createBufferedImage(Image image, int type) Creates a BufferedImage from the specified image.
Image	createImage(InputStream in) Generates an image from an input stream containing the data bytes for the image formatted in image/gif format.
Image	createImage(int[][] array) Generates an image from a two-dimensional array of pixel values.
Image	createImage(int[] pixels, int width, int height) Generates an image from a single-dimensional array of pixel values.
Image	createImage(String[] hexData) Generates an image from a string array that provides the pixel values.
void	defineAudioClip(String name, AudioClip clip) Inserts the given clip into the audio clip table under the specified name.
void	defineImage(String name, Image image) Inserts the given image into the image table under the specified name.
void	flushAudioClip(String name) Removes the audio clip with the given name from the cache, allowing it to be freed by the garbage collector.
void	flushImage(String name) Removes the image with the given name from the cache, allowing it to be freed by the garbage collector.
InputStream	getHexInputStream(String[] hexData) Returns an input stream whose bytes come from the string array hex, in which the elements consist of continuous bytes of hex data.
Component	getImageObserver() This method returns a new lightweight component suitable as an imageObserver.
int[][]	getPixelArray(Image image) Returns a two-dimensional array of the pixels in the image.
boolean	isCachingEnabled() This method returns the status of the flag that determins whether images and audio clips are cached internally by name, as described in setCachingEnabled.
AudioClip	loadAudioClip(String name) Searches the default audio clip search path for an audio clip with the specified name and then loads it to create an AudioClip.
AudioClip	loadAudioClip(URL url) Loads an audio clip from the specified URL.
AudioClip	loadAudioClip(URL url, boolean topLevel) Loads an audio clip from the specified URL.
Image	loadImage(Image image) Makes sure that the image is fully loaded before returning.
Image	loadImage(String name) Searches the default image search path for an image with the specified name and then loads it to create an Image.
Image	loadImage(URL url) Loads an image from the specified URL.
Image	loadImage(URL url, boolean topLevel) Loads an image from the specified URL.
InputStream	openDataFile(String name) Searches the default datafile search path for a file with the specified name and then opens it to create an InputStream.
InputStream	openDataFile(String name, String path) Searches for a data file with the given name and opens it to create an InputStream.
InputStream	openDataFile(URL url) Opens the specified URL to create an InputStream.
InputStream	openDataFile(URL url, boolean topLevel) Opens a data file using the specified URL.
void	saveImage(Image image, File file) Saves an image to the specified file.
void	saveImage(Image image, String filename) Saves an image to a file with the specified filename.
void	setCachingEnabled(boolean flag) This method sets an internal flag in the MediaTools package to indicate whether images and audio clips are cached internally by name.

Field Detail

public static final String DEFAULT_AUDIO_PATH

The list of directories scanned for audio clips, separated by colons.

See Also:

Constant Field Values

public static final String DEFAULT_DATAFILE_PATH

The list of directories scanned for data files, separated by colons.

See Also:

Constant Field Values

public static final String DEFAULT_IMAGE_PATH

The list of directories scanned for images, separated by colons.

See Also:

Constant Field Values

Method Detail

public static void beep()

This method sounds the audible alert on the console, which is typically a beep sound.

Usage:

MediaTools.beep();

public static AudioClip createAudioClip(InputStream in)

Generates an audio clip from an input stream containing the data bytes for the audio clip. The implementation first tries to create a SoundClip object from the data. If that fails, it then backs up to the older strategy of using the SunAudioClip class.

Usage:

AudioClip clip = MediaTools.createAudioClip(in);

Parameter:

in	An input stream containing the data

Returns:

An AudioClip object

public static AudioClip createAudioClip(String[] hexData)

Generates an audio clip from a string array that provides the sound values.

Usage:

AudioClip audio clip = MediaTools.createAudioClip(hexData);

Parameter:

hexData

A hex string array representing an audio clip

Returns:

An AudioClip object

public static BufferedImage createBufferedImage(Image image, int type)

Creates a BufferedImage from the specified image. The type parameter is used to specify the image type, as described in the BufferedImage documentation.

Usage:

BufferedImage image = MediaTools.createBufferedImage(image, type);

Parameters:

image	The original image
type	The type code used to describe the image model
A	BufferedImage containing the image data

public static Image createImage(InputStream in)

Generates an image from an input stream containing the data bytes for the image formatted in image/gif format.

Usage:

Image image = MediaTools.createImage(in);

Parameter:

in	An input stream containing the data

Returns:

An Image object

public static Image createImage(int[][] array)

Generates an image from a two-dimensional array of pixel values. As in standard image processing applications, the array is indexed so that the first subscript determines the row and the second determines the column.

Usage:

Image image = MediaTools.createImage(array);

Parameter:

array

A two-dimensional array of ints representing the pixels

Returns:

An Image object

public static Image createImage(int[] pixels, int width, int height)

Generates an image from a single-dimensional array of pixel values. The pixel array is stored in row-major order, which means that the pixels for the entire first row come before the pixels in the second row, and so on.

Usage:

Image image = MediaTools.createImage(pixels, width, height);

Parameters:

pixels	An array of ints representing the pixels
width	The width of the image
height	The height of the image

Returns:

An Image object

public static Image createImage(String[] hexData)

Generates an image from a string array that provides the pixel values.

Usage:

Image image = MediaTools.createImage(hexData);

Parameter:

hexData

A hex string array representing a .gif value

Returns:

An Image object

public static void defineAudioClip(String name, AudioClip clip)

Inserts the given clip into the audio clip table under the specified name.

Usage:

MediaTools.defineAudioClip(name, clip);

Parameters:

name	The name for the audio clip
clip	The audio clip to be stored in the table

public static void defineImage(String name, Image image)

Inserts the given image into the image table under the specified name.

Usage:

MediaTools.defineImage(name, image);

Parameters:

name	The name for the image
image	The image to be stored in the table

public static void flushAudioClip(String name)

Removes the audio clip with the given name from the cache, allowing it to be freed by the garbage collector.

Usage:

MediaTools.flushAudioClip(name);

Parameter:

name	The name for the audio clip

public static void flushImage(String name)

Removes the image with the given name from the cache, allowing it to be freed by the garbage collector.

Usage:

MediaTools.flushImage(name);

Parameter:

name	The name for the image

public static InputStream getHexInputStream(String[] hexData)

Returns an input stream whose bytes come from the string array hex, in which the elements consist of continuous bytes of hex data.

Usage:

InputStream in = MediaTools.getHexInputStream(hexData);

Parameter:

hexData

An array of strings specifying a byte stream coded in hex

Returns:

An input stream for reading the bytes

public static Component getImageObserver()

This method returns a new lightweight component suitable as an imageObserver.

Usage:	Component imageObserver = MediaTools.getImageObserver();
Returns:	A new lightweight component suitable as an imageObserver.

public static int[][] getPixelArray(Image image)

Returns a two-dimensional array of the pixels in the image. As in standard image processing applications, the array is indexed so that the first subscript determines the row and the second determines the column.

Parameter:

image

The image

Returns:

A two-dimensional array of pixels

public static boolean isCachingEnabled()

This method returns the status of the flag that determins whether images and audio clips are cached internally by name, as described in setCachingEnabled.

Usage:	boolean flag = MediaTools.isCachingEnabled();
Returns:	true if caching by name is enabled, false otherwise.

public static AudioClip loadAudioClip(String name)

Searches the default audio clip search path for an audio clip with the specified name and then loads it to create an AudioClip. The search process consists of the following steps:

1. Check to see if an audio clip with that name has already been defined. If so, return that audio clip.

2. Check to see if there is a resource available with that name whose contents can be read as an AudioClip. If so, read the audio clip from the resource file.

3. Load the audio clip from a file with the specified name, relative to the application directory or the applet code base.

The second and third steps are repeated for each element of the audio clip search path, which consists of a list of directories separated by colons.

Usage:

AudioClip clip = MediaTools.loadAudioClip(name);

Parameter:

name	The name of the audio clip

Returns:

A new AudioClip object

public static AudioClip loadAudioClip(URL url)

Loads an audio clip from the specified URL.

Usage:

AudioClip clip = MediaTools.loadAudioClip(url);

Parameter:

url	The url containing the audio clip

Returns:

A new AudioClip object

public static AudioClip loadAudioClip(URL url, boolean topLevel)

Loads an audio clip from the specified URL. The topLevel flag is false if this is invoked internally.

public static Image loadImage(Image image)

Makes sure that the image is fully loaded before returning.

Usage:

image = MediaTools.loadImage(image);

Parameter:

image

The Image which may not yet be loaded

Returns:

The same Image after ensuring that it is fully loaded

public static Image loadImage(String name)

Searches the default image search path for an image with the specified name and then loads it to create an Image. The search process consists of the following steps:

1. Check to see if an image with that name has already been defined. If so, return that image.

2. Check to see if there is a resource available with that name whose contents can be read as an Image. If so, read the image from the resource file.

3. Load the image from a file with the specified name, relative to the application directory or the applet code base.

The second and third steps are repeated for each element of the image search path, which consists of a list of directories separated by colons.

Unlike the getImage method in the Applet class, loadImage waits for an image to be fully loaded before returning.

Usage:

Image image = MediaTools.loadImage(name);

Parameter:

name	The name of the image

Returns:

A fully loaded Image object

public static Image loadImage(URL url)

Loads an image from the specified URL.

Usage:

Image image = MediaTools.loadImage(url);

Parameter:

url	The url containing the image

Returns:

A fully loaded Image object

public static Image loadImage(URL url, boolean topLevel)

Loads an image from the specified URL. The topLevel flag is false if this is invoked internally.

public static InputStream openDataFile(String name)

Searches the default datafile search path for a file with the specified name and then opens it to create an InputStream. The search process consists of the following steps:

1. Check to see if there is a resource available with that name. If so, return an InputStream open on that resource.

2. Open the file with the specified name, relative to the application directory or the applet code base.

These steps are repeated for each element of the datafile search path, which consists of a list of directories separated by colons.

Usage:

InputStream in = MediaTools.openDataFile(name);

Parameter:

name	The name of the input file

Returns:

A new InputStream open on the specified file

public static InputStream openDataFile(String name, String path)

Searches for a data file with the given name and opens it to create an InputStream. Its operation is identical to the single-argument openDataFile call except in that this version allows the client to specify the search path explicitly.

Usage:

InputStream in = MediaTools.openDataFile(name, path);

Parameters:

name	The name of the audio clip
path	A string of directories names separated by colons

Returns:

A new InputStream open on the specified file

public static InputStream openDataFile(URL url)

Opens the specified URL to create an InputStream.

Usage:

InputStream in = MediaTools.openDataFile(url);

Parameter:

url	The URL of the data file

Returns:

A new InputStream open on the specified URL

public static InputStream openDataFile(URL url, boolean topLevel)

Opens a data file using the specified URL. The topLevel flag is false if this is invoked internally.

public static void saveImage(Image image, File file)

Saves an image to the specified file. The data format for the image file is determined by the suffix of the filename. If the suffix of the file is not recognized as a supported image type, calling this method generates an error.

Usage:

MediaTools.saveImage(image, file);

Parameters:

image	The image
file	The File to which the image is saved

public static void saveImage(Image image, String filename)

Saves an image to a file with the specified filename. The data format for the image file is determined by the suffix of the filename. If the suffix of the file is not recognized as a supported image type, calling this method generates an error.

Usage:

MediaTools.saveImage(image, filename);

Parameters:

image	The image
filename	The name of the file to which the image is saved

public static void setCachingEnabled(boolean flag)

This method sets an internal flag in the MediaTools package to indicate whether images and audio clips are cached internally by name. This flag is disabled by default.

Usage:

MediaTools.setCachingEnabled(flag);

Parameter:

flag	true to enable caching by name, false to disable it.