wyvern.kernel.maps
Class AbstractCamera

java.lang.Object
  wyvern.kernel.maps.AbstractCamera

All Implemented Interfaces:

Camera, RPCDataSource

Direct Known Subclasses:

GroundCamera, MapCamera

public abstract class AbstractCamera

extends java.lang.Object

implements Camera

This class handles much of the overhead of creating a Camera. It registers with the map and collects any changes to the map that happen within its view. Subclasses are responsible for sizing and positioning the camera, and deciding how to pass the map changes to the client.

A Camera registers itself with a map by calling the CameraManager, passing itself and the map with which to register. The mapping of cameras to GameMaps is done externally in the CameraManager to keep the map code independent of the game display engine.

When a camera registers, the CameraManager makes the camera's entire view invalid, and adds the camera to its lists. Whenever a game map is changed, it notifies the CameraManager. The CameraManager remembers that the map is dirty, and the map remembers the change. Whenever a camera moves or resizes, it must inform the CameraManager, so the CameraManager knows what map changes are visible to the camera in its new location.

Periodically, the game Scheduler pauses in its event handling and tells the CameraManager to refresh all the cameras. The Scheduler pauses to make sure the map is in a consistent state when the cameras pull their data from the map.

At refresh-time, the CameraManager goes through its list of dirty maps and processes all the cameras in each map. It figures out which map changes were visible to each camera, and sends the visible changes to those cameras by calling validate().

The changes are sent to the Camera as a matrix the size of the map, where if a bit is set in the matrix, that square was dirty in the map. Each camera implementation will render this information differently: a MapCamera will generate a map-view of the changes, whereas a GroundCamera will check which objects changed, and update the client's ground display.

A camera uses a DisplayPolicy object to gather and filter the map information to be sent to the client. Each camera implementation uses its own DisplayPolicy implementation. The DisplayPolicy is reponsible for using the invalid-rectangles list to pull information from the map and render it suitably for the output display.

An AbstractCamera subclass must do the following:

• implement makeFrame() to create a DisplayPolicy implementation
• implement updateClient() to send the data to the RemoteClient

Version:

1.0, Mar 28, 1998

Author:

Steve Yegge

Field Summary

protected Rectangle	bounds_
protected RemoteClient	client_
protected boolean	completelyInvalid_
protected DisplayPolicy	frame_
protected boolean	hasMoved_
protected int	height_
protected int	left_
protected GameMap	map_
protected Player	player_
protected boolean	ready_
protected Dimension	size_
protected int	top_
protected int	width_
protected int	xoffset_
protected int	yoffset_

Constructor Summary

AbstractCamera(RemoteClient client, Player player)
Constructs a new AbstractCamera.

Method Summary

void	forceInvalidate() Forces the camera contents to refresh, even if it's already been marked as completely invalid.
Point	getCenter() Returns the center point of the camera view, in map coords.
DisplayPolicy	getFrame() Returns the object used for collecting and filtering the objects sent to the camera by the map.
GameMap	getMap() Returns the map this camera is viewing.
Player	getOwner() Returns the player associated with this camera.
Point	getPosition() Returns the upper-left corner of the camera, in map coords.
Rectangle	getViewRect() Gets the rectangle that this camera is viewing in the map.
Dimension	getViewSize() Returns the width and height of the camera.
boolean	hasBeenMoved() Returns whether the camera has been moved since the last client refresh.
void	invalidate() Markes the camera as dirty (i.e. needing a refresh).
void	invalidateNoRayCast() Forces the camera contents to refresh, but without redoing the visibility model raycasting.
boolean	isHandheld() Returns true if this camera is for a player using a handheld device.
boolean	isInvalid() Returns whether the entire camera is invalid.
boolean	isShutDown() Returns true if this camera has been shut down.
void	markReady() Called by the networking layer when the camera's last request has finished sending over the wire.
void	markValid() Sets the "completely-invalid" flag for the camera.
void	move(int xoffset, int yoffset) Moves the camera by a relative (x, y) amount without resizing it.
void	moveFrame()
void	setHandheld(boolean handheld)
void	setMap(GameMap map, int x, int y) Sets a new map and position for the camera simultaneously.
void	setMap(GameMap map, Point p) Sets a new map and position for the camera simultaneously.
void	setMoved(int xoffset, int yoffset) Remembers that the camera has been moved by a small amount, so the client can blit the old contents over.
void	setPosition(int x, int y) Tells the camera where in the map to view.
void	setViewRect(Rectangle r) Sets the view rectangle to a new position and size.
void	setViewSize(int width, int height) Resizes the camera view without moving the upper-left corner.
void	shutDown() Turns the camera off (permanently).
java.lang.String	toString()
protected void	tryUpdate() Calls updateClient, and if we succeed, clears the ready flag.
abstract boolean	updateClient(DisplayPolicy frame) This method is called from validate() if the camera has been marked ready via markReady().
void	validate(MapDirtyRegions updates) Tells the camera to check if it should update itself.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface wyvern.lib.Camera

makeFrame

Field Detail

client_

protected RemoteClient client_

player_

protected Player player_

map_

protected GameMap map_

width_

protected int width_

height_

protected int height_

left_

protected int left_

top_

protected int top_

bounds_

protected Rectangle bounds_

size_

protected Dimension size_

frame_

protected DisplayPolicy frame_

completelyInvalid_

protected volatile boolean completelyInvalid_

hasMoved_

protected boolean hasMoved_

xoffset_

protected int xoffset_

yoffset_

protected int yoffset_

ready_

protected volatile boolean ready_

Constructor Detail

AbstractCamera

public AbstractCamera(RemoteClient client,
                      Player player)
               throws java.rmi.RemoteException

Constructs a new AbstractCamera. Registers the the camera with the CameraManager.

Parameters:

client - the RemoteClient to send data to

player - the Player this camera is for

Method Detail

updateClient

public abstract boolean updateClient(DisplayPolicy frame)

This method is called from validate() if the camera has been marked ready via markReady().

Parameters:

frame - the frame to gather the data with

Returns:

true if any data was sent. It's essential that subclasses set this flag correctly for the camera to work properly. If the subclass determines that nothing has changed within the view of the camera, and doesn't make any calls to the RemoteClient as a result, then it should return false.

markReady

public void markReady()

Called by the networking layer when the camera's last request has finished sending over the wire. The camera should call the CameraManager indicating that it's ready to be serviced again. Note: this is called from the RemoteClientImpl writer thread.

Specified by:

markReady in interface Camera

validate

public void validate(MapDirtyRegions updates)

Description copied from interface: Camera

Tells the camera to check if it should update itself.

This method is called by the game scheduler thread, via the CameraManager. When this method is called, the CameraManager has determined that some changes have occurred in the map that we're viewing (or that we've marked ourselves dirty). This method is called even if none of those changes are visible (the 'updates' parameter will be null or empty). It's up to this method, or a subclass, to determine whether to do a client update.

The camera doesn't actually pull any data from the map unless it has been marked "ready" by the network output thread. If it's not ready, it just remembers the invalid regions and waits until it's ready again.

Specified by:

validate in interface Camera

Parameters:

updates - a MapDirtyRegions that contains a BitMatrix the size of the map we're viewing, with bits set everywhere there was a map cell invalidated. Can be null if camera is completely invalid, in which case it won't be used. Called by the CameraManager when refreshing the camera.

tryUpdate

protected void tryUpdate()

Calls updateClient, and if we succeed, clears the ready flag.

getViewRect

public Rectangle getViewRect()

Description copied from interface: Camera

Gets the rectangle that this camera is viewing in the map.

Specified by:

getViewRect in interface Camera

Returns:

the view Rectangle (upper-left corner is the position)

setViewRect

public void setViewRect(Rectangle r)

Description copied from interface: Camera

Sets the view rectangle to a new position and size.

Specified by:

setViewRect in interface Camera

Parameters:

r - the map rectangle to view

setViewSize

public void setViewSize(int width,
                        int height)

Description copied from interface: Camera

Resizes the camera view without moving the upper-left corner.

Specified by:

setViewSize in interface Camera

Parameters:

width - the new view width

height - the new view height

getViewSize

public Dimension getViewSize()

Description copied from interface: Camera

Returns the width and height of the camera.

Specified by:

getViewSize in interface Camera

Returns:

the camera view size

setPosition

public void setPosition(int x,
                        int y)

Description copied from interface: Camera

Tells the camera where in the map to view.

Specified by:

setPosition in interface Camera

Parameters:

x - the new map X position for the camera upper-left corner

y - the new map Y position for the camera upper-left corner

getPosition

public Point getPosition()

Description copied from interface: Camera

Returns the upper-left corner of the camera, in map coords.

Specified by:

getPosition in interface Camera

Returns:

the position of the camera

move

public void move(int xoffset,
                 int yoffset)

Description copied from interface: Camera

Moves the camera by a relative (x, y) amount without resizing it.

Specified by:

move in interface Camera

Parameters:

xoffset - the relative X offset to move the camera

yoffset - the relative Y offset to move the camera

setMap

public void setMap(GameMap map,
                   Point p)

Description copied from interface: Camera

Sets a new map and position for the camera simultaneously.

Specified by:

setMap in interface Camera

Parameters:

map - the GameMap to view

p - the map coordinates

setMap

public void setMap(GameMap map,
                   int x,
                   int y)

Description copied from interface: Camera

Sets a new map and position for the camera simultaneously.

Specified by:

setMap in interface Camera

Parameters:

map - the GameMap to view

x - the x position to view

y - the y position to view

getCenter

public Point getCenter()

Description copied from interface: Camera

Returns the center point of the camera view, in map coords.

Specified by:

getCenter in interface Camera

Returns:

the point that the camera view is centered on.

getMap

public GameMap getMap()

Description copied from interface: Camera

Returns the map this camera is viewing.

Specified by:

getMap in interface Camera

Returns:

the GameMap

getOwner

public Player getOwner()

Description copied from interface: Camera

Returns the player associated with this camera.

Specified by:

getOwner in interface Camera

Returns:

the player for this camera, or null if hasn't been set

invalidate

public void invalidate()

Description copied from interface: Camera

Markes the camera as dirty (i.e. needing a refresh). Used when the camera opens, changes maps, teleports, and so on. Does nothing if the camera is already marked invalid; use forceInvalidate() to force the contents to refresh, but only if invalidate() doesn't work - invalidate() should usually work, and requires less overhead.

Specified by:

invalidate in interface Camera

forceInvalidate

public void forceInvalidate()

Description copied from interface: Camera

Forces the camera contents to refresh, even if it's already been marked as completely invalid.

Specified by:

forceInvalidate in interface Camera

invalidateNoRayCast

public void invalidateNoRayCast()

Description copied from interface: Camera

Forces the camera contents to refresh, but without redoing the visibility model raycasting. Use whenever you need the camera data resent, but the player hasn't moved and the map hasn't changed (e.g. the "#refresh" command from the client).

Specified by:

invalidateNoRayCast in interface Camera

setMoved

public void setMoved(int xoffset,
                     int yoffset)

Description copied from interface: Camera

Remembers that the camera has been moved by a small amount, so the client can blit the old contents over.

Specified by:

setMoved in interface Camera

hasBeenMoved

public boolean hasBeenMoved()

Description copied from interface: Camera

Returns whether the camera has been moved since the last client refresh.

Specified by:

hasBeenMoved in interface Camera

isInvalid

public boolean isInvalid()

Description copied from interface: Camera

Returns whether the entire camera is invalid.

Specified by:

isInvalid in interface Camera

Returns:

true if the camera needs a complete refresh, e.g. after setting it to a new map.

markValid

public void markValid()

Description copied from interface: Camera

Sets the "completely-invalid" flag for the camera. Used for communication with the Frame.

Specified by:

markValid in interface Camera

getFrame

public DisplayPolicy getFrame()

Description copied from interface: Camera

Returns the object used for collecting and filtering the objects sent to the camera by the map. A MapCamera returns an object that sorts the objects into drawing layers, selecting one per layer. A GroundCamera gets all the objects with their titles. A camera is free to use any DisplayPolicy object it likes.

Specified by:

getFrame in interface Camera

moveFrame

public void moveFrame()

shutDown

public void shutDown()

Description copied from interface: Camera

Turns the camera off (permanently).

Specified by:

shutDown in interface Camera

isShutDown

public boolean isShutDown()

Description copied from interface: Camera

Returns true if this camera has been shut down.

Specified by:

isShutDown in interface Camera

isHandheld

public boolean isHandheld()

Description copied from interface: Camera

Returns true if this camera is for a player using a handheld device.

Specified by:

isHandheld in interface Camera

setHandheld

public void setHandheld(boolean handheld)

toString

public java.lang.String toString()