Creating Images

ImageIcon vs Image

Just to confuse matters, there is also the Icon interface that ImageIcon implements. Whenever you see a method taking a Icon, you can feed it an ImageIcon.

ImageIcon.getImage will convert an ImageIcon to an Image. The constructor new ImageIcon( Image image ) will convert an Image to an ImageIcon.

The ImageIcon class and the Icon interface have nothing whatsover to do with Windows *.ico icon format that supports multiple resolutions in one file. Java ImageIcons don’t have to be magic sizes. They don’t have to be square. They can be *.png, *.gif or *.jpg just like Images.

Image Stages

1. Images are often downloaded over the Internet or read from disk. Sometimes they are created out of raw bytes in some well known format in RAM.
2. Then the image has to be converted from gif or compressed jpg to standard internal linear bit map format.
3. The image may have to be scaled. Programmers using drawImage often inadvertently scale when they meant to clip or resize.
4. Then the image has to be converted to native video card bit map format.
5. Finally the image has to be copied into the REGEN buffer of the video card.

You can think of the scheme as like an assembly line. At each stage, the image consumer asks the previous stage image producer for a chunk of the partly processed image to work on. The producer gives it as much as it can, and the consumer then asks again later for the remaining bits. With this scheme, you do not have to wait until all the image has completely arrived before getting on with the later stages of processing, e.g. getting at least part of the image up there on the screen. The details of how it all works are mind boggling, but surprisingly, you can write code even if you have only the vaguest understanding of how they work.

You can just close you eyes to those complexities at first, but you will have to understand them once you start fine tuning your apps when you want to get rid of strange behaviours and flicker.

The Image class is abstract. You can’t instantiate an Image with a constructor. Part of the problem is Image is associated with some very platform dependent code. Besides the terrifying ways of dealing with ImageProducers, ImageConsumers and ImageObservers, there are some simple techniques to create an Image.

Saving an image in gif or jpg format is referred to as encoding.

Getting Images From A File

Getting Images From a Server

Getting Images From The Archive Jar

Class.getResource makes these changes to the resource name: if the resource name starts with "/", it is unchanged; otherwise, the package name is prepended to the resource name after converting "." to "/". This allows you to use either dots or slashes to separate the components of the name. The name is case sensitive. Double check the case by studying your jar files with Winzip.

Unfortunately class.getResource, upon which that preceding technique depends, is broken, in that Netscape version 4.x does not support it. Now that Netscape 8.0 is available, perhaps we can ignore that restriction.

Getting Images From Other Jars

Getting Images from raw bytes

Toolkit.getDefaultToolkit().createImage( rawByteArray , start, length );

MediaTracker: Ensuring Images Are Fully Loaded Before Use

MediaTracker t = new MediaTracker( this );
t.addImage( orangeball, 0 );
t.addImage( pinkball, 1 );
try
   {
   t.waitForAll();
   }
catch ( InterruptedException e )
   {
   Thread.currentThread().interrupt();
   }

AWT ImageViewer

There is no Component in JDK 1.1 that simply displays an Image. I have written one here called ImageViewer which is a greatly simplified version of the one that ships with Café. The component automatically sizes itself to fit the size of the Image you feed it. You can attach a standard MouseListener to it to trigger some action when somebody clicks it. Here is the source for it:

You can download the latest source, and a fancier one called ResizingImageViewer as part of the Canadian Mind Products Business package

Swing ImageViewer

Double Buffering

Without Swing, you have to handle double buffering yourself. With Swing, all you need is Component.setDoubleBuffered( true ). If you don’t use double buffering you paint directly to the screen. Double buffering is not always faster. In JDK 1.2+ Swing components, double buffering is applied by default. Sometimes you have to turn double buffering off to avoid strange ghosting effects. A simple offscreen drawing technique works like this:

// Use Component.createImage to get you a blank image to draw on.
// Do this in your init method, not static init, or you will just get null.
Image img = createImage( width, height );
Graphics gi = img.getGraphics();

// Now use gi.drawString, gi.clearRect etc. to draw,
// just as you would on-screen graphics.
// That gives you an off-screen bit map of your image.
// To blast the image onto the screen in your paint routine use:
g.drawImage( img, x, y, /* image observer */ this );
// And override update to call paint without clearing first.

I have experimented with Component.createImage( width, height). It is a tricky mechanism. It behaves differently in different JVMs and different browsers. The problem is it uses the current Component’s (e.g. the Applet’s) peer object to create the offscreen Image object. createImage is an instance method of the current Component, not an independent static method as you might expect. That is how it finds the Component’s peer object in the native GUI that knows the details of the image format used by the particular video card we are using.

That peer does not get created until the last minute when Component.setVisible ( true ). Since you are presumably using createImage to eventually create that screen image, you have a minor catch-22. You can’t create the Image well ahead of time. You somehow must postpone any use of createImage until the Component’s addNotify method has been called assigning it a peer object in the native GUI that knows the native format for images on that particular video card. Hooking your code into the addNotify is an essay in itself.

In Java 1.2 Component.isDisplayAble was introduced that lets you know if the peer object is ready yet for createImage to work. It definitely won’t work in static init. It sometimes works in init. Best to put it in an overriding addNotify method which is used to create the peer object. When it returns from super.addNotify is the earliest possible time you can use the peer.

public void addNotify()
   {
   super.addNotify();
   offScreenImage = createImage ( width, height );
   }

Encoding: Saving Images to Disk

png format bypasses the patent problem, but it is not as widely supported. Java did not support it until version 1.4. The easiest way is to use an external screen capture utility such as Paint Shop Pro. if you want to do it under java program control, you have to look for third party image-savers. See Peter van der Linden’s FAQ for some options. You can of course serialise the Image, but you can’t reconstitute it on a different platform because the format of the pickled (serialized) Image is platform-dependent. For speed, Images are stored in a ColorModel (internal format) matching or closely matching the local video card.

Don’t try to send serialised Images over RMI either for the same reason. One way to do it is to use uk.co.demon.windsong.image.ZipImage in to convert the Image to a device Independent GZIPOutputStream, and the companion uk.co.demon.windsong.image.ImageProducer to reconstitute it.

Transparency

Getting Fancy

When you want animation speed/smoothness, look into VolatileImage available since Java 1.4 which is implemented where possible inside the video hardware. BitBlts on such images would be done with the 128-bit GPU (graphics processing unit) which is much better designed than the CPU for shovelling misaligned bits around. You build your images in the offscreen part of the hardware video REGEN buffer. Then when you blast them to the screen, they go instantaneously, since the BitBlt video hardware moves it without having to cross the blood-brain boundary to the video hardware memory buffer. It is a high speed double buffering technique.

Manipulating Image Files Without a GUI

• Use Marco Schmidt’s ImageInfo.
• Use my ImageInfo part of the CMP business classes. It is simpler than Marco’s. It will sniff a *.gif, *.jpg or *.png file on disk, and tell you if it is truly what it claims to be, and what its width and height is, all by reading only a few bytes of the file.
• Use the javax.imageio package, in particular IIOImage. That is not a typo.
  ImageIO

Under The Hood

In your AWT paint method or equivalent Swing paintComponent method you use you use the drawImage method typically with code like this:

What is all this?

g is the Graphics object. It represents the place where we are painting to, usually the screen, but it could be printer or offscreen image. It knows what sort of image format the video card likes. It is passed as a parameter to your paint or paintComponent method.

image is the usually-MediaTracked image more or less ready to draw. It may be part way through the conversion process to internal format.

x,y is where on screen you want to paint the Image.

width, height is how much of the Image you want to copy, usually the whole thing.

this is the Canvas or other Component we are painting on. It is used to reschedule work that cannot be completed now.

done is true if drawImage was able to complete the work.

If done is false then things get interesting. The work is left unfinished and your paint method completes.

When more of the Image is ready, the ImageProducer will use the Component’s ImageObserver interface to call its default Component.updateImage method. That method then calls repaint with a clipregion describing the uncompleted part of the work.

repaint schedules a repaint event, which eventually ends up calling your paint or paintComponent again, but this time with Graphics object with a reduced clipregion so you don’t have to bother redoing the completed work if you are clever.

This process repeats until eventually drawImage returns true.

The key point to understand is that your paint or paintComponent method may be called several times to complete the drawing from an initial repaint request. You can write your paint method oblivious to this madness. The Graphics object automatically clips everything you draw to the uncompleted region. However, ideally you should avoid excessive painting outside the clip region.

The Cast

Debugging

• Did you remember to call super.addNotify() first thing in your addNotify method?
• Did you remember to add the Component to the Container?
• Did you remember to setVisible( true )?
• Did you remember to validate? Double check by dumping the size and location of the invisible Component.
• Have you tied up the Swing thread so it can’t find any time to paint?
• Did you do your getImages in addNotify rather than the constructor?
• With absolute positioning and the null LayoutMananger, did you remember to do a setSize and setLocation on every component?
• Have you positioned the missing Component way off screen?
• Is the window you are looking for buried underneath other ones?

Dealing with Old Versions Of Netscape

Learning More