org.razvan.jzx
Class BaseScreen

java.lang.Object
  extended by java.awt.Component
      extended by java.awt.Canvas
          extended by org.razvan.jzx.BaseScreen
All Implemented Interfaces:
java.awt.image.ImageObserver, java.awt.MenuContainer, java.io.Serializable, javax.accessibility.Accessible
Direct Known Subclasses:
ScreenBoth, ScreenJava1, ScreenJava2

public abstract class BaseScreen
extends java.awt.Canvas

Base class extended by all screen components that comprise the emulator.

Note: BaseScreen must extend Canvas, so it does not extend BaseComponent, although it (correctly) should. Instead, it implements all the BaseComponent methods explicitly.

This class provides basic, common screen functionality for the screen subsystem of the emulator. Specific methods are overriden or implemented so as to comply with the idiosyncracies of various JVM versions. There are no differences between the Spectrum 48k and the Spectrum 128k models.

Author:
Razvan Surdulescu (c) 2001 - 2006, Erik Kunze (c) 1995, 1996, 1997, Des Herriott (c) 1993, 1994
You may use and distribute this software for free provided you include this copyright notice. You may not sell this software, use my name for publicity reasons or modify the code without permission from me.
See Also:
Serialized Form

Nested Class Summary
 
Nested classes/interfaces inherited from class java.awt.Canvas
java.awt.Canvas.AccessibleAWTCanvas
 
Nested classes/interfaces inherited from class java.awt.Component
java.awt.Component.AccessibleAWTComponent, java.awt.Component.BltBufferStrategy, java.awt.Component.FlipBufferStrategy
 
Field Summary
static int ATTR_LENGTH
          Length of attribute memory area.
static int ATTR_START
          Memory address where the attribute area starts.
static int BLACK
          The Spectrum index of the color "black"
static int BLUE
          The Spectrum index of the color "blue"
static int BORDER_PIXELS
          Width of border area, in pixels.
static int BRIGHT
          Bright attribute mask.
static int BRIGHT_BLACK
          The Spectrum index of the color "bright black"
static int BRIGHT_BLUE
          The Spectrum index of the color "bright blue"
static int BRIGHT_CYAN
          The Spectrum index of the color "bright cyan"
static int BRIGHT_GREEN
          The Spectrum index of the color "bright green"
static int BRIGHT_MAGENTA
          The Spectrum index of the color "bright magenta"
static int BRIGHT_RED
          The Spectrum index of the color "bright red"
static int BRIGHT_WHITE
          The Spectrum index of the color "bright white"
static int BRIGHT_YELLOW
          The Spectrum index of the color "bright yellow"
static int COLS
          Number of character columns on the screen.
static int CYAN
          The Spectrum index of the color "cyan"
static int FLASH
          Flash attribute mask.
static int GREEN
          The Spectrum index of the color "green"
static int INK
          Ink attribute mask.
protected  int m_borderColor
          The current border color.
protected  boolean m_borderDirty
          If true, the border needs repainting.
protected  boolean m_flashPhase
          Is the flash phase normal or inverted?
protected  int[] m_inkTable
          Maps a given attribute value to its corresponding ink value, to avoid having to decode it explicitly.
protected  ILogger m_logger
          The ILogger object used to logStream information and exceptions.
protected  java.awt.Image m_offscreenBorder
          The image that renders the border and the screen.
protected  java.awt.Graphics m_offscreenBorderGraphics
          The Graphics object corresponding to the border image.
protected  java.awt.Image m_offscreenImage
          The image that renders the screen.
protected  java.awt.Graphics m_offscreenImageGraphics
          The Graphics object corresponding to the screen image.
protected  int[] m_paperTable
          Maps a given attribute value to its corresponding paper value, to avoid having to decode it explicitly.
protected  int m_scale
          The screen scaling factor.
protected  boolean[] m_screenChanged
          Bit vector that indicates whether a particular memory byte has been changed.
protected  boolean m_screenDirty
          If true, the screen needs repainting.
protected  int m_screenHeight
          The screen height, in pixels (uses m_scale.)
protected  int m_screenWidth
          The screen width, in pixels (uses m_scale.)
protected  BaseSpectrum m_spectrum
          Cached reference to the BaseSpectrum object.
static int MAGENTA
          The Spectrum index of the color "magenta"
static int PAPER
          Paper attribute mask.
static int PIXEL_LENGTH
          Length of pixel memory area.
static int PIXEL_START
          Memory address where the screen area starts.
static int RED
          The Spectrum index of the color "red"
static int ROWS
          Number of character rows on the screen.
protected static java.awt.Color[] s_colorPalette
          An array of Color objects corresponding to the color indices above.
protected static int[] s_rgbPalette
          An array of RGB integral values corresponding to the color indices above.
static int WHITE
          The Spectrum index of the color "white"
static int X_PIXELS
          Number of X pixels on the screen.
static int Y_PIXELS
          Number of Y pixels on the screen.
static int YELLOW
          The Spectrum index of the color "yellow"
 
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
 
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
 
Constructor Summary
BaseScreen()
           
 
Method Summary
 void attrTouch(int addr16)
          Touch a particular attribute value, marking it for update next time the screen is rendered.
 void clear(int attr)
          Clear the screen with the given attribute color.
 void clear(int width, int height, int attr)
          Clear a box on the screen, with upper-left corner at the current cursor position, with given height and width using the given attribute color.
protected  java.awt.Image createCompatibleImage(int width, int height)
          Create and return an Image object that isa appropriate for this Screen object.
protected abstract  void draw8(int x, int y, int pix8, int attr8)
          Draws the given 8 bits (pix8), with the given attribute values (attr8) at coordinates x, y on the Canvas.
 void dumpScreenshot()
           
protected  void endRender()
          Trigger method that is called right afterthe screen is rendered.
 void flash()
          When the flash phase changes, update all attribute values that have the flash bit set.
 int getCursorX()
          Retrieve current cursor X position.
 int getCursorY()
          Retrieve current cursor Y position.
static BaseScreen getInstance()
          Construct the appropriate (derived class) instance for the current environment (JVM version.)
 java.awt.Dimension getMinimumSize()
          Set the minimum size to (full width, full height).
 int getPage()
          Trivial accessor to the physical memory page for the screen data.
 java.awt.Dimension getPreferredSize()
          Set the preferred size to (full width, full height).
 void init(BaseSpectrum spectrum, ILogger logger)
           Set cached pointers to the BaseSpectrum and BaseMemory objects. Allocate pixel modification bit vector. Allocate ink and paper tables. Set the size of the Canvas object, and add it to the Container. Add the keyboard object as the KeyListener. Set the scale.
 void load(BaseLoader loader)
          Load the screen contents from the given BaseLoader object.
 void paint(java.awt.Graphics g)
          If the screen is dirty, update it by walking the memory page and re-drawing the data that has changed.
 void print(char letter, int attr)
          Print a given character at the current cursor position and advance the cursor X position by 1.
 void print(java.lang.String string, int attr)
          Call print(char, int) for every character in the given string.
 void println(char letter, int attr)
          Call print(char, int) and advance the cursor Y position by 1.
 void println(java.lang.String string, int attr)
          Call print(String, int) with the given string, then set the cursor to be on the line immediately underneath the original cursor position.
 void reset()
          Touch all the screen bits in order to force the initial refresh.
 void screenTouch(int addr16)
          Touch a particular byte value in screen memory, marking it for update next time the screen is rendered.
 void setBorderColor(int val8)
          Change the current border color, and mark the border as dirty for update at the next screen refresh.
 void setCursor(int x, int y)
          Set the current cursor position used by print methods below.
 void setPage(int page)
          Trivial mutator for the physical memory page for the screen data.
protected  void setScale(int scale)
          Non-trivial mutator for the screen scale value.
protected  void startRender()
          Trigger method that is called right before the screen is rendered.
 void terminate()
          Release all cached pointers, set all the tables to null.
 void update(java.awt.Graphics g)
          Redraw the screen, but do not erase it first in order to avoid flicker.
 
Methods inherited from class java.awt.Canvas
addNotify, createBufferStrategy, createBufferStrategy, getAccessibleContext, getBufferStrategy
 
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, bounds, checkImage, checkImage, coalesceEvents, contains, contains, createImage, createImage, createVolatileImage, createVolatileImage, deliverEvent, disable, disableEvents, dispatchEvent, doLayout, enable, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getAlignmentX, getAlignmentY, getBackground, getBounds, getBounds, getColorModel, getComponentAt, getComponentAt, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeys, getFocusTraversalKeysEnabled, getFont, getFontMetrics, getForeground, getGraphics, getGraphicsConfiguration, getHeight, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getListeners, getLocale, getLocation, getLocation, getLocationOnScreen, getMaximumSize, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getSize, getToolkit, getTreeLock, getWidth, getX, getY, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, invalidate, isBackgroundSet, isCursorSet, isDisplayable, isDoubleBuffered, isEnabled, isFocusable, isFocusCycleRoot, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isOpaque, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, layout, list, list, list, list, list, locate, location, lostFocus, minimumSize, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, paramString, postEvent, preferredSize, prepareImage, prepareImage, print, printAll, processComponentEvent, processEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processKeyEvent, processMouseEvent, processMouseMotionEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removeNotify, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, repaint, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, reshape, resize, resize, setBackground, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setEnabled, setFocusable, setFocusTraversalKeys, setFocusTraversalKeysEnabled, setFont, setForeground, setIgnoreRepaint, setLocale, setLocation, setLocation, setMaximumSize, setMinimumSize, setName, setPreferredSize, setSize, setSize, setVisible, show, show, size, toString, transferFocus, transferFocusBackward, transferFocusUpCycle, validate
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

PIXEL_START

public static final int PIXEL_START
Memory address where the screen area starts.

See Also:
Constant Field Values

ROWS

public static final int ROWS
Number of character rows on the screen.

See Also:
Constant Field Values

COLS

public static final int COLS
Number of character columns on the screen.

See Also:
Constant Field Values

X_PIXELS

public static final int X_PIXELS
Number of X pixels on the screen.

See Also:
Constant Field Values

Y_PIXELS

public static final int Y_PIXELS
Number of Y pixels on the screen.

See Also:
Constant Field Values

PIXEL_LENGTH

public static final int PIXEL_LENGTH
Length of pixel memory area.

See Also:
Constant Field Values

ATTR_START

public static final int ATTR_START
Memory address where the attribute area starts.

See Also:
Constant Field Values

ATTR_LENGTH

public static final int ATTR_LENGTH
Length of attribute memory area.

See Also:
Constant Field Values

BORDER_PIXELS

public static final int BORDER_PIXELS
Width of border area, in pixels.

See Also:
Constant Field Values

BLACK

public static final int BLACK
The Spectrum index of the color "black"

See Also:
Constant Field Values

BLUE

public static final int BLUE
The Spectrum index of the color "blue"

See Also:
Constant Field Values

RED

public static final int RED
The Spectrum index of the color "red"

See Also:
Constant Field Values

MAGENTA

public static final int MAGENTA
The Spectrum index of the color "magenta"

See Also:
Constant Field Values

GREEN

public static final int GREEN
The Spectrum index of the color "green"

See Also:
Constant Field Values

CYAN

public static final int CYAN
The Spectrum index of the color "cyan"

See Also:
Constant Field Values

YELLOW

public static final int YELLOW
The Spectrum index of the color "yellow"

See Also:
Constant Field Values

WHITE

public static final int WHITE
The Spectrum index of the color "white"

See Also:
Constant Field Values

BRIGHT_BLACK

public static final int BRIGHT_BLACK
The Spectrum index of the color "bright black"

See Also:
Constant Field Values

BRIGHT_BLUE

public static final int BRIGHT_BLUE
The Spectrum index of the color "bright blue"

See Also:
Constant Field Values

BRIGHT_RED

public static final int BRIGHT_RED
The Spectrum index of the color "bright red"

See Also:
Constant Field Values

BRIGHT_MAGENTA

public static final int BRIGHT_MAGENTA
The Spectrum index of the color "bright magenta"

See Also:
Constant Field Values

BRIGHT_GREEN

public static final int BRIGHT_GREEN
The Spectrum index of the color "bright green"

See Also:
Constant Field Values

BRIGHT_CYAN

public static final int BRIGHT_CYAN
The Spectrum index of the color "bright cyan"

See Also:
Constant Field Values

BRIGHT_YELLOW

public static final int BRIGHT_YELLOW
The Spectrum index of the color "bright yellow"

See Also:
Constant Field Values

BRIGHT_WHITE

public static final int BRIGHT_WHITE
The Spectrum index of the color "bright white"

See Also:
Constant Field Values

FLASH

public static final int FLASH
Flash attribute mask.

See Also:
Constant Field Values

BRIGHT

public static final int BRIGHT
Bright attribute mask.

See Also:
Constant Field Values

PAPER

public static final int PAPER
Paper attribute mask.

See Also:
Constant Field Values

INK

public static final int INK
Ink attribute mask.

See Also:
Constant Field Values

m_scale

protected int m_scale
The screen scaling factor.


m_screenWidth

protected int m_screenWidth
The screen width, in pixels (uses m_scale.)


m_screenHeight

protected int m_screenHeight
The screen height, in pixels (uses m_scale.)


s_colorPalette

protected static final java.awt.Color[] s_colorPalette
An array of Color objects corresponding to the color indices above.


s_rgbPalette

protected static final int[] s_rgbPalette
An array of RGB integral values corresponding to the color indices above.


m_flashPhase

protected boolean m_flashPhase
Is the flash phase normal or inverted?


m_borderColor

protected int m_borderColor
The current border color.


m_inkTable

protected int[] m_inkTable
Maps a given attribute value to its corresponding ink value, to avoid having to decode it explicitly.


m_paperTable

protected int[] m_paperTable
Maps a given attribute value to its corresponding paper value, to avoid having to decode it explicitly.


m_screenChanged

protected boolean[] m_screenChanged
Bit vector that indicates whether a particular memory byte has been changed.


m_screenDirty

protected boolean m_screenDirty
If true, the screen needs repainting.


m_borderDirty

protected boolean m_borderDirty
If true, the border needs repainting.


m_offscreenBorder

protected java.awt.Image m_offscreenBorder
The image that renders the border and the screen.


m_offscreenBorderGraphics

protected java.awt.Graphics m_offscreenBorderGraphics
The Graphics object corresponding to the border image.


m_offscreenImage

protected java.awt.Image m_offscreenImage
The image that renders the screen.


m_offscreenImageGraphics

protected java.awt.Graphics m_offscreenImageGraphics
The Graphics object corresponding to the screen image.


m_spectrum

protected BaseSpectrum m_spectrum
Cached reference to the BaseSpectrum object.


m_logger

protected ILogger m_logger
The ILogger object used to logStream information and exceptions.

Constructor Detail

BaseScreen

public BaseScreen()
Method Detail

init

public void init(BaseSpectrum spectrum,
                 ILogger logger)


reset

public void reset()
Touch all the screen bits in order to force the initial refresh.


terminate

public void terminate()
Release all cached pointers, set all the tables to null.


getPage

public int getPage()
Trivial accessor to the physical memory page for the screen data.


setPage

public void setPage(int page)
Trivial mutator for the physical memory page for the screen data.


setScale

protected void setScale(int scale)
Non-trivial mutator for the screen scale value.

This method updates all the screen size parameters in accordance to the new scale value. This method should be appropriately overriden by child classes in order to to modify their inner structures if the scale is changed.


getMinimumSize

public java.awt.Dimension getMinimumSize()
Set the minimum size to (full width, full height).

Overrides:
getMinimumSize in class java.awt.Component

getPreferredSize

public java.awt.Dimension getPreferredSize()
Set the preferred size to (full width, full height).

Overrides:
getPreferredSize in class java.awt.Component

update

public void update(java.awt.Graphics g)
Redraw the screen, but do not erase it first in order to avoid flicker. This method just calls paint(java.awt.Graphics) with the specified Graphics context.

Overrides:
update in class java.awt.Canvas

paint

public void paint(java.awt.Graphics g)
If the screen is dirty, update it by walking the memory page and re-drawing the data that has changed.

Call the abstract draw8() method below to do the actual work for every pixel.

Note that there exists a benign race condition in this code: a PAINT event may be issued as the CPU is decoding instructions and updating the screen from the main thread. The reason this race condition is benign is because in the worst case it can cause aliasing: the screen contents are changed half way through a frame. Fixing this race condition would involve making a copy of the screen memory page, which hurts performance.

Overrides:
paint in class java.awt.Canvas
See Also:
draw8(int, int, int, int)

createCompatibleImage

protected java.awt.Image createCompatibleImage(int width,
                                               int height)
Create and return an Image object that isa appropriate for this Screen object.

Override this method to return image types that are optimized for the particular JVM and/or platform.


startRender

protected void startRender()
Trigger method that is called right before the screen is rendered.

Override this method to receive a notification.


endRender

protected void endRender()
Trigger method that is called right afterthe screen is rendered.

Override this method to receive a notification.


draw8

protected abstract void draw8(int x,
                              int y,
                              int pix8,
                              int attr8)
Draws the given 8 bits (pix8), with the given attribute values (attr8) at coordinates x, y on the Canvas.

This method is implemented as appropriate for performance reasons in the various child classes.

Parameters:
x - The X coordinate where the pixels should be drawn onto the Canvas object.
y - The Y coordinat where the pixels should be drawn onto the Canvas object.
pix8 - The 8 bits to draw starting at (X,Y) ending at (X+8,Y).
attr8 - The attributes used to draw the 8 bits.

flash

public void flash()
When the flash phase changes, update all attribute values that have the flash bit set.

The next time the screen is rendered, all flash attributes will appear correctly.


attrTouch

public void attrTouch(int addr16)
Touch a particular attribute value, marking it for update next time the screen is rendered.

The touching of an attribute entails touching the 8 byte values whose screen representation is altered by this attribute value.

Parameters:
addr16 - The 16-bit absolute memory address (in the attribute memory area) which should be touched.

screenTouch

public void screenTouch(int addr16)
Touch a particular byte value in screen memory, marking it for update next time the screen is rendered.

Parameters:
addr16 - The 16-bit absolute memory address (in the screen memory area) which should be touched.

setBorderColor

public void setBorderColor(int val8)
Change the current border color, and mark the border as dirty for update at the next screen refresh.


setCursor

public void setCursor(int x,
                      int y)
Set the current cursor position used by print methods below.

Parameters:
x - New cursor X position
y - New cursor Y position
See Also:
print(char, int), println(char, int), print(String, int), println(String, int)

getCursorX

public int getCursorX()
Retrieve current cursor X position.

Returns:
Current cursor X position

getCursorY

public int getCursorY()
Retrieve current cursor Y position.

Returns:
Current cursor Y position

clear

public void clear(int attr)
Clear the screen with the given attribute color.

Parameters:
attr - Attribute color used to clear the screen

clear

public void clear(int width,
                  int height,
                  int attr)
Clear a box on the screen, with upper-left corner at the current cursor position, with given height and width using the given attribute color.

Parameters:
width - Width of box to clear
height - Height of box to clear
attr - Attribute color used to clear

print

public void print(char letter,
                  int attr)
Print a given character at the current cursor position and advance the cursor X position by 1. If the cursor falls outside the bounds of the screen, do not display anything. If the letter is invalid (not in the interval [32, 127]) display '?'. You must manually call Component.repaint()

Parameters:
letter - The letter to print on the screen
attr - The attribute used to print the letter on the screen

println

public void println(char letter,
                    int attr)
Call print(char, int) and advance the cursor Y position by 1.

Parameters:
letter - The letter to print on the screen
attr - The attribute used to print the letter on the screen
See Also:
print(char, int)

print

public void print(java.lang.String string,
                  int attr)
Call print(char, int) for every character in the given string.

Parameters:
string - The string to print on the screen
attr - The attribute used to print the letter on the screen
See Also:
print(char, int)

println

public void println(java.lang.String string,
                    int attr)
Call print(String, int) with the given string, then set the cursor to be on the line immediately underneath the original cursor position.

Parameters:
string - The string to print on the screen
attr - The attribute used to print the letter on the screen
See Also:
print(String, int)

load

public void load(BaseLoader loader)
Load the screen contents from the given BaseLoader object.

Since the screen data is not saved, this method does nothing.


getInstance

public static BaseScreen getInstance()
Construct the appropriate (derived class) instance for the current environment (JVM version.)

The method constructs an instance of ScreenJava1 if the JVM is version 1.1.x, and an instance of ScreenJava2 if the JVM is version of 1.2.x.

See Also:
ScreenJava1, ScreenJava2, ScreenBoth

dumpScreenshot

public void dumpScreenshot()