GF4J 0.9.4 Beta

gameframe.engines
Interface EngineFactory

All Known Implementing Classes:
CEngineFactory, CEngineFactory, CEngineFactory

public interface EngineFactory

Defines an interface to an engine factory. An engine factory is used to create all the needed engines (graphics, sound, input etc.) that then take care of one part of the game frame functionality. When an engine factory is finalized, it will finalize all the engines that were created by it. This interface is used internally by the library to wrap access to engine factories in MainFactory class.

To engine implementors:
To make your own engine factory work with GameFrame for Java you must do these things:

Since:
GameFrame for Java 0.9
Version:
GameFrame for Java 0.9.4

Field Summary
static int SUITABILITY_GOOD
          Enumerated value for the suitability of the engine factory for the platform.
static int SUITABILITY_NOT_SUITED
          Enumerated value for the suitability of the engine factory for the platform.
static int SUITABILITY_POOR
          Enumerated value for the suitability of the engine factory for the platform.
static int SUITABILITY_ULTIMATE
          Enumerated value for the suitability of the engine factory for the platform.
 
Method Summary
 Timer createTimer()
          Returns a new timer instance.
 void finalizationNotify(Timer timer)
          Notifies that the given timer has been finalized.
 void finalize()
          Invoked before application exits.
 java.lang.String getDescription()
          Returns the (possibly multiline) description of the engine factory implementation.
 GraphicsEngine getGraphicsEngine()
          Returns the graphics engine implementation for the current platform.
 InputEngine getInputEngine()
          Returns the input engine implementation for the current platform.
 java.lang.String getName()
          Returns the short name (max 8 characters) of the engine factory implementation (e.g.
 SoundEngine getSoundEngine()
          Returns the sound engine implementation for the current platform.
 int getSuitabilityForPlatform()
          Returns the suitability of this engine implementation for the current platform as one of the enumerated SUITABILITY_xxx values.
 java.lang.String[] getSupportedResolutions()
          Returns all the fullscreen graphics modes supported by graphics engines that are created by this factory.
 

Field Detail

SUITABILITY_NOT_SUITED

public static final int SUITABILITY_NOT_SUITED
Enumerated value for the suitability of the engine factory for the platform. This value means that the engine factory can't run on this platform (e.g. Microsoft Java VM specific DirectX implementation on JavaSoft Java VM).
Since:
GameFrame for Java 0.9

SUITABILITY_POOR

public static final int SUITABILITY_POOR
Enumerated value for the suitability of the engine factory for the platform. This value means that the engine factory can run on this platform, but likely is not the best option available (e.g. Java 1.1 based implementation on Microsoft Java VM).
Since:
GameFrame for Java 0.9

SUITABILITY_GOOD

public static final int SUITABILITY_GOOD
Enumerated value for the suitability of the engine factory for the platform. This value means that the engine factory can run on this platform and is most likely a good (even the best) option available for this platform (e.g. JNI DirectX implementation on JavaSoft Java VM).
Since:
GameFrame for Java 0.9

SUITABILITY_ULTIMATE

public static final int SUITABILITY_ULTIMATE
Enumerated value for the suitability of the engine factory for the platform. This value means that the engine factory is the ultimate version available for this platform (e.g. Direct/J DirectX implementation on Microsoft Java VM). This value should only be used in EXTREME cases. Even the examplary case might not be a good place to use this value, for example a JNI DirectX implementation might be faster on the Microsoft Java VM.
Since:
GameFrame for Java 0.9
Method Detail

getName

public java.lang.String getName()
Returns the short name (max 8 characters) of the engine factory implementation (e.g. "Java 1.1" or "MSDX").
Returns:
The short name of the engine factory.
Since:
GameFrame for Java 0.9

getDescription

public java.lang.String getDescription()
Returns the (possibly multiline) description of the engine factory implementation.
Returns:
A description of the engine factory.
Since:
GameFrame for Java 0.9

getSuitabilityForPlatform

public int getSuitabilityForPlatform()
Returns the suitability of this engine implementation for the current platform as one of the enumerated SUITABILITY_xxx values.
Returns:
Suitability of the engine factory for this platform.
Since:
GameFrame for Java 0.9

getSupportedResolutions

public java.lang.String[] getSupportedResolutions()

Returns all the fullscreen graphics modes supported by graphics engines that are created by this factory. If the factory created graphics engines support only windowed modes, this method returns null.

Note to engine developers: This method should always do a full cleanup after it has been run. This means releasing all of the memory and resources that were used.

Returns:
Supported fullscreen modes or null.
Since:
GameFrame for Java 0.9

getSoundEngine

public SoundEngine getSoundEngine()
                           throws GameFrameException
Returns the sound engine implementation for the current platform. When this method returns the sound engine is in fully usable state (fully initialized). If not successfull returns the do-nothing implementation of a sound engine (CNullSoundEngine in package gameframe) or throws GameFrameException exception.
Returns:
The single sound engine for this platform.
Throws:
GameFrameException - Thrown if sound engine creation fails.
Since:
GameFrame for Java 0.9

getGraphicsEngine

public GraphicsEngine getGraphicsEngine()
                                 throws GameFrameException
Returns the graphics engine implementation for the current platform. When this method returns the graphics engine is in fully usable state (fully initialized). If not successfull throws GameFrameException exception. The requirements for the created graphics engine are taken from the user specified MainFactory settings in the MainFactory class.
Returns:
The single graphics engine for this platform.
Throws:
GameFrameException - Thrown if graphics engine creation fails.
Since:
GameFrame for Java 0.9

getInputEngine

public InputEngine getInputEngine()
                           throws GameFrameException
Returns the input engine implementation for the current platform. When this method returns the input engine is in fully usable state (fully initialized). If not successfull throws GameFrameException exception.
Returns:
The single input engine for this platform.
Throws:
GameFrameException - Thrown if input engine creation fails.
Since:
GameFrame for Java 0.9

createTimer

public Timer createTimer()
                  throws GameFrameException
Returns a new timer instance. Several timers can be created with this method. If a native timer can't be for some reason created, this method returns the basic implementation CTimer from the GameFrame.Java11 package. If even this doesn't succeed throws GameFrameException exception.
Returns:
A new timer instance.
Throws:
GameFrameException - Thrown if timer creation fails.
Since:
GameFrame for Java 0.9

finalizationNotify

public void finalizationNotify(Timer timer)
Notifies that the given timer has been finalized.

finalize

public void finalize()
Invoked before application exits. Does all the cleanup that is necessary to exit cleanly (closes windows, stops playing sounds, releases any objects referenced etc.). Also finalizes all the engines and timers that were created with this engine factory.
Overrides:
finalize in class java.lang.Object
Since:
GameFrame for Java 0.9

GF4J 0.9.4 Beta