Package com.nerius.game

Class AbstractCanvas

  • All Implemented Interfaces:
    Destroyable, RunnableDestroyable, VisiblyUpdatable, java.lang.Runnable
    public abstract class AbstractCanvas
extends java.lang.Object
implements VisiblyUpdatable, RunnableDestroyable
    Useful for de-coupling a game's logic from things such as applets and windows. This framework (this class and CanvasAWTStub) are here to define a contract, hopefully making things simpler for games and animations.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected java.awt.Dimension m_size  
      protected CanvasAWTStub m_stub  

    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      protected AbstractCanvas​(CanvasAWTStub stub, java.awt.Dimension size)
      The parameter size is the size of the viewport that this board will be allowed to render into; it gets saved as member variable m_size.

    • Method Summary

      All Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      abstract void destroy()
      destroy() is called externally, usually not by subclasses.
      java.awt.Dimension getSize()
      Required for implementation of VisiblyUpdatable.
      abstract void run()
      run() is usually called externally, not by subclasses.
      abstract java.awt.Rectangle update​(java.awt.Graphics g)
      This will automatically be called [usually by an asynchronous thread] whenever m_stub's requestUpdate() method is called.

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • m_size

        protected final java.awt.Dimension m_size

    • Constructor Detail

      • AbstractCanvas

        protected AbstractCanvas​(CanvasAWTStub stub,
                         java.awt.Dimension size)
        The parameter size is the size of the viewport that this board will be allowed to render into; it gets saved as member variable m_size. When update(Graphics) is called, this canvas should render into the Graphics from the origin to m_size.

        IMPORTANT NOTE: Don't call stub.requestUpdate() from this constructor!!!

    • Method Detail

      • run

        public abstract void run()
        run() is usually called externally, not by subclasses. Calls to m_stub.requestUpdate() shall be made only from the thread invoking run(). run() isn't necessarily expected to return until destroy() is invoked (obviously, destroy() will be called from a different thread). Furthermore, run() shall only be called once for a given instance.

        An AbstractCanvas may create threads and run them. It is a good practice to create all such threads in run(), and to not return from run() until all created threads have finished.

        Specified by:
        run in interface java.lang.Runnable

      • destroy

        public abstract void destroy()
        destroy() is called externally, usually not by subclasses. destroy() itself should not block; it should return quickly. destroy() should signal to the thread that called run() to exit from the run() method.

        Both run() and destroy() shall each be called at most once for any given instance. Defining the order in which run() and destroy() are called is impossible because these two methods are called from different threads. If destroy() is called "before" run(), then the run() method, when and if it is invoked, should terminate immediately.

        Specified by:
        destroy in interface Destroyable

      • update

        public abstract java.awt.Rectangle update​(java.awt.Graphics g)
        This will automatically be called [usually by an asynchronous thread] whenever m_stub's requestUpdate() method is called. The requestUpdate() method will block until this update() code completes. This method is not meant to be directly called by this class (except for maybe debugging by updating to an offscreen image); it is only meant to be implemented. This canvas should call m_stub.requestUpdate() to render itself.

        Returns a Rectangle representing the area which was updated; a null return value indicates that nothing was updated.

        Each update() will be called with a new Graphics object.

        Having just an update() and no paint() fits in nicely in this abstraction layer; many canvases will have multiple image buffers to draw; these buffers can be drawn individually by this method, and the invoker of this method can keep a single buffer to be blitzed onto the screen. It is intended that such buffering not take place within the context of this class implementation.

        Subclasses should do as little computation as possible in this method. The recommended approach is to figure out exactly what is to be drawn before m_stub.requestUpdate() is called. This method should ideally return quickly.

        Please note that during destruction time, a call to m_stub.requestUpdate() may not necessarily trigger a call to update(); it may just return immediately. However, implementations of CanvasAWTStub are required to not return prematurely during an invocation of requestUpdate() if such a call triggers update(), even in the end of life situation.

        Specified by:
        update in interface VisiblyUpdatable

      • getSize

        public final java.awt.Dimension getSize()
        Required for implementation of VisiblyUpdatable. Normally subclasses would use the protected data member m_size.
        Specified by:
        getSize in interface VisiblyUpdatable