wyvern.lib
Interface Camera

All Superinterfaces:

RPCDataSource

All Known Implementing Classes:

AbstractCamera

public interface Camera

extends RPCDataSource

Cameras provide different views of game maps to the client.

Different implementations will display the information differently: the client map-display and ground-display are both Camera implementations.

All existing game cameras inherit from wyvern.kernel.maps.AbstractCamera, which provides a framework that makes it easier to create new camera types.

Version:

1.0, Dec 31, 1997

Author:

Steve Yegge

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.
DisplayPolicy	makeFrame() A factory method that instantiates a DisplayPolicy subclass appropriate for this camera.
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	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).
void	validate(MapDirtyRegions updates) Tells the camera to check if it should update itself.

Method Detail

setViewRect

public void setViewRect(Rectangle r)

Sets the view rectangle to a new position and size.

Parameters:

r - the map rectangle to view

setViewSize

public void setViewSize(int width,
                        int height)

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

Parameters:

width - the new view width

height - the new view height

setPosition

public void setPosition(int x,
                        int y)

Tells the camera where in the map to view.

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

move

public void move(int xoffset,
                 int yoffset)

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

Parameters:

xoffset - the relative X offset to move the camera

yoffset - the relative Y offset to move the camera

getViewRect

public Rectangle getViewRect()

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

Returns:

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

getPosition

public Point getPosition()

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

Returns:

the position of the camera

getCenter

public Point getCenter()

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

Returns:

the point that the camera view is centered on.

getViewSize

public Dimension getViewSize()

Returns the width and height of the camera.

Returns:

the camera view size

setMap

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

Sets a new map and position for the camera simultaneously.

Parameters:

map - the GameMap to view

x - the x position to view

y - the y position to view

setMap

public void setMap(GameMap map,
                   Point p)

Sets a new map and position for the camera simultaneously.

Parameters:

map - the GameMap to view

p - the map coordinates

getOwner

public Player getOwner()

Returns the player associated with this camera.

Returns:

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

getMap

public GameMap getMap()

Returns the map this camera is viewing.

Returns:

the GameMap

getFrame

public DisplayPolicy getFrame()

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.

makeFrame

public DisplayPolicy makeFrame()

A factory method that instantiates a DisplayPolicy subclass appropriate for this camera. The object is obtained later by calls to getFrame().

validate

public void validate(MapDirtyRegions updates)

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.

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.

invalidate

public void invalidate()

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.

forceInvalidate

public void forceInvalidate()

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

invalidateNoRayCast

public void invalidateNoRayCast()

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).

isInvalid

public boolean isInvalid()

Returns whether the entire camera is invalid.

Returns:

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

setMoved

public 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.

hasBeenMoved

public boolean hasBeenMoved()

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

shutDown

public void shutDown()

Turns the camera off (permanently).

isShutDown

public boolean isShutDown()

Returns true if this camera has been shut down.

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.

Specified by:

markReady in interface RPCDataSource

isHandheld

public boolean isHandheld()

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

markValid

public void markValid()

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