nankin.zheng.gatem.view
Interface DisplayCache

All Known Implementing Classes:

DisplayCacheImplSwing

public interface DisplayCache

DisplayCache instance does the actual work of drawing, that is, game frame updating.

A DisplayCache instance accepts DrawCommand objects and caches them in its buffer. While its flush() method is called, it will flush all the DrawCommand objects onto the screen. While drawing, the depth field of the DrawCommand objects will be considered as the priority of drawing. ( A less deep DrawCommand object will be drawn earlier. )

This class also deals with control of viewport.

NOTE that all the positions of DrawCommand objects are logical coordonates (which represents blocks). DisplayCache instance can calculate their physical coordonates (which represents pixels).

DisplayCache interface can be implemented differently to improve performance or to integrate with different java application platforms. For example, we can have a Swing implementation and a j2me one.

Version:

1.0, Date 2003-04-11

Author:

ZHENG Zhong

Method Summary

void	addToCache(DrawCommand cmd) Add a DrawCommand object into display buffer.
void	flush(java.lang.Object helper) Flush display buffer.
int	getDepth() Get depth of this display cache.
void	setDepth(int d) Set depth of this display cache.
void	setViewport(Position vp) Set the viewport of Background.

Method Detail

addToCache

public void addToCache(DrawCommand cmd)
                throws GameException

Add a DrawCommand object into display buffer.

All draw commands are ordered in the buffer by their depths.

Note that before this method is called, the viewport must be set, so we can decide whether the parameter cmd is out of the viewport scope by referring to its position field. If is out of scope, cmd will be ignored.

Parameters:

cmd - DrawCommand

Throws:

GameException - if any error occured.

flush

public void flush(java.lang.Object helper)
           throws GameException

Flush display buffer. Flush all DrawCommand objects in display buffer onto the screen.

While drawing, the priority(depth) will be considered. This method is called by game container at the end of a frame updating, when all the roles have finished their work. After flushing, the buffer should be cleaned.

NOTE that this method does the actual work of drawing, so its implementation depends heavily on different application platforms. On many platforms, drawing an image onto the screen needs the help of other objects (for example in Swing, a Graphics instance is necessary for drawing). So this method takes an Object as parameter, which is the helper instance, or is a wrapper which holds the helper instances if there are more than one.

Parameters:

helper - helper instance for drawing

Throws:

GameException - if any error occured.

setViewport

public void setViewport(Position vp)
                 throws GameException

Set the viewport of Background.

This method should be called before any DrawCommand is added into the buffer. That is to say, while setting viewport, the display buffer of this DisplayCache instance must be empty.

It sets the viewport of Background, so while adding DrawCommand, we can decide whether the DrawCommand object is out of the viewport. If is out, we needn't add it into the buffer (for better performance).

Parameters:

vp - position (logical coordonate) of the viewport.

Throws:

GameException - if display buffer is not empty.

getDepth

public int getDepth()

Get depth of this display cache. NOTE that a DisplayCache instance itself has depth. In a game, there can be several DisplayCache instances, each in charge of one aera of the whole game window. A CacheContainer instance holds all DisplayCache instances. While calling flush() method, the depth of the DisplayCache instance will be considered as the priority. DisplayCache with less depth will be flushed earlier.

Returns:

depth of the display cache

setDepth

public void setDepth(int d)

Set depth of this display cache.

Parameters:

d - depth of the display cache