yaarq.sys
Interface yrqApplication

All Known Implementing Classes:
yrqDemoApplication

public interface yrqApplication

This interface defines callback functions which are used by the engine to communicate with the application. Any application using the engine has to implement this interface.

TODO: Nothing


Method Summary
 java.awt.Component engineComponentRequest()
          This function is called by the engine to request the component it is running in.
 void engineInitCallback(yrqEngine a_engine)
          This callback is used by the engine to notify applications that loading of low-level ressources has been done and all internal initalisation has finished.
 void engineInputCallback(yrqEngine a_engine, java.awt.AWTEvent a_evt)
          This callback is used by the engine to inform the application that a mouse or keyboard event has occurred.
 void engineLoadCallback(yrqEngine a_engine)
          This callback is used by the engine to notify applications that low-level ressources like textures, sounds etc. should be loaded into the repository.
 void engineRenderCallback(yrqEngine a_engine, java.awt.Graphics2D a_gfx)
          This callback is used by the engine after every 3D frame rendering to allow for the application to do 2D overlay drawing.
 void engineUpdateCallback(yrqEngine a_engine)
          This callback is used by the engine to request updates from the application.
 

Method Detail

engineComponentRequest

public java.awt.Component engineComponentRequest()
This function is called by the engine to request the component it is running in. The callback is issued by the engine on load to determine a listener for image loading operations, and during initialisation of the rendering canvas to adjust the canvas to the component size and to attach it to the component.

Applications should pass back a container component into which the engine should render, e.g. java.awt.frame for an engine instance running in its own window or java.awt.panel if the engine shares the screen with other components in a user interface. Note: The use of swing components like jpanel is not recommended.

Returns:
The component within which the engine should render

engineInitCallback

public void engineInitCallback(yrqEngine a_engine)
This callback is used by the engine to notify applications that loading of low-level ressources has been done and all internal initalisation has finished. From the moment this function is called, applications can use the setActive method of the engine to start and stop rendering, and they can add objects to the various collections kept by the engine.

Applications working with one scene, which do not have the need for recreation of objects at runtime, could create all scene-relevant objects here and implement interactivity in the update callback.

Parameters:
a_engine - Instance of yrqEngine responsible for the callback

engineInputCallback

public void engineInputCallback(yrqEngine a_engine,
                                java.awt.AWTEvent a_evt)
This callback is used by the engine to inform the application that a mouse or keyboard event has occurred. The according event is passed back and the application has to check, using instanceof, which type of event has caused the callback.

Parameters:
a_engine - Instance of yrqEngine responsible for the callback
a_evt - The event that ocurred

engineLoadCallback

public void engineLoadCallback(yrqEngine a_engine)
This callback is used by the engine to notify applications that low-level ressources like textures, sounds etc. should be loaded into the repository. Though ressources could be loaded at runtime, after the engine has been started, it is recommended to add all needed ressources within this callback function and display a loading dialog.

Parameters:
a_engine - Instance of yrqEngine responsible for the callback

engineRenderCallback

public void engineRenderCallback(yrqEngine a_engine,
                                 java.awt.Graphics2D a_gfx)
This callback is used by the engine after every 3D frame rendering to allow for the application to do 2D overlay drawing. Note: The Java3D implementation is very slow here, so don't draw anything fancy.

Parameters:
a_engine - Instance of yrqEngine responsible for the callback
a_gfx - The graphics context onto which to render

engineUpdateCallback

public void engineUpdateCallback(yrqEngine a_engine)
This callback is used by the engine to request updates from the application. Within this function, the application is free to change the states (e.g. position, alpha, existance) of all objects kept in the various collections by the engine.

Applications can clear all objects and add a totally new set of objects here if a complete scene change is necessary.

Calls to update occur exactly every 1/50 second by default, or in the intervals specified by a call to the setUpdateInterval method of the engine, so animation sequences updated by this call can use simple counters for updating and still be synchronous.

Parameters:
a_engine - Instance of yrqEngine responsible for the callback