applicationbase.h

RGA: Biowaste Game Example This C++ application demonstrates how to create a 2D mobile game for S60

/*
* ==============================================================================
*  Name        : ApplicationBase.h
*  Part of     : RGA Game Example
*  Interface   :
*  Description : Base application class handles RGA initialisation
* 				 and application main loop.	
*  Version     : 1.0
*
*  Copyright (c) 2007-2008 Nokia Corporation.
*  This material, including documentation and any related
*  computer programs, is protected by copyright controlled by
*  Nokia Corporation.
* ==============================================================================
*/

#ifndef __APPLICATIONBASE_H__
#define __APPLICATIONBASE_H__


// from Symbian
#include <e32base.h>
#include <bitstd.h>
#include <bitdev.h>
#include <w32std.h>
#include <e32math.h>


// from RGA
#include <runtime.h>
#include <displaymanager.h>
#include <display.h>
#include <graphics.h>
#include <backbuffer.h>
#include <errorcodes.h>
#include <idle.h>
#include <graphicscontext.h>
#include <applicationstate.h>
#include <ngibitmap.h>
#include <imageconverter.h>
#include <timing.h>
#include <input.h>
#include <devicestatus.h>

using namespace ngi;

#include "TickTimer.h"


class CApplicationBase :	public CBase,
							public IApplicationStateObserver,
							public IDisplayObserver,
							public IInputDeviceObserver,
							public ITimerObserver,
							public IAlarmObserver,
							public ITelephonyObserver
	{
	public:
		CApplicationBase();
		virtual ~CApplicationBase();
		
		/**
		 * Init
		 * initialise the application.
		 * function creates window, and RGA graphics
		 * initialises timers and basic keyboard input
		 * @param aColorFormat 	format of the application back buffer
		 * 						see 'rga\graphics.h'
		 * @return KErrNone if successfull
		 */
		TInt Init(TUint32 aColorFormat);
		
		/**
		 * Run
		 * starts application main loop.
		 * function returns when application is closed
		 * @return KErrNone
		 */
		TInt Run();
		
		/**
		 * Close
		 * stops the application main loop and
		 * exits from 'Run' function.
		 * @param aError	error code that is passed as a return value
		 *					from 'Run' function.
		 * @param aDescription	message to display after exit
		 * 						if aError is not KErrNone
		 */
		void Close(TInt aError, const TDesC& aDescription = _L(""));
		
		/**
		 * IsFocused
		 * @return ETrue if application has focus and
		 * it is running
		 */
		TBool IsFocused() const;
		
		/**
		 * FrameTimer
		 * @return reference to application frame timer
		 */
		CTickTimer& FrameTimer() const;
		
		/**
		 * LoadImage
		 * load image into the bitmap object
		 * @param aBitmap bitmap to load image into
		 * @param aFilename file to load
		 * @param aBitmapFormat use bitmaps current format
		 * @return KErrNone if successfull
		 */
		TInt LoadImage(IBitmap& aBitmap, const TDesC& aFilename, TBool aBitmapFormat = EFalse);
		
		/**
		 * CreateBitmapAndContext
		 * helper function to create RGA bitmap and context
		 * bitmap is created into the same format as current
		 * back buffer
		 * @param aSize size of created bitmap in pixels
		 * @param aBitmap bitmap object to initialise
		 * @param aContext context object to initialise, context is set to aBitmap
		 * @return KErrNone, or error code
		 */
		TInt CreateBitmapAndContext(	const TSize& aSize,
										IBitmap*& aBitmap,
										IGraphicsContext*& aContext);

		/**
		 * ReleaseBitmapAndContext
		 * helper function to release bitmap and context pair
		 * @param aBitmap bitmap object to release
		 * @param aContext context object to release
		 */
		void ReleaseBitmapAndContext(	IBitmap*& aBitmap,
										IGraphicsContext*& aContext);
		
		/**
		 * RGAErrorToSymbianError
		 * static helper converts given RGA error code to
		 * nearest Symbian OS error code
		 * @param aError RGA error code
		 * @return Symbian error code
		 */
		static TInt RGAErrorToSymbianError(ReturnCode aError);
		
		/**
		 * RGAFormatToDisplayMode
		 * static helper converts given RGA color format to
		 * Symbian TDisplayMode
		 * @param aFormat RGA color format
		 * @return Symbian display mode, ENone if not compatible
		 */
		static TDisplayMode RGAFormatToDisplayMode(TUint32 aFormat);
		
		/**
		 * BitmapStride
		 * computes stride of the Symbian bitmap
		 * @param aBitmap bitmap to compute stride from
		 * @return number of bytes in one horline of the bitmap
		 */
		static TInt BitmapStride(CFbsBitmap& aBitmap);
		
		/**
		 * IsKeyDown
		 * @param aKeyCode RGA key code
		 * @return ETrue if specified key is down
		 */
		TBool IsKeyDown(TUint32 aKeyCode) const;
		
		/**
		 * SystemGc
		 * Allows access to RGA bitmaps thru Symbian graphics context
		 * Symbian gc can then be used to draw into
		 * the RGA bitmaps. Drawing with Symbian gc is applied in
		 * call to 'ApplySystemGc'. Only one 'SystemGc' call can
		 * be active at one time. The given graphics device is
		 * locked in between calls to 'SystemGc' and 'ApplySystemGc'
		 * functions. No other RGA drawing functions should be used
		 * While accessing the RGA bitmap with Symbian gc.
		 * @param aDevice RGA graphics device to draw to
		 * @return	Symbian graphics context which can be used to
		 * 			draw into the RGA graphics device
		 */
		CGraphicsContext* SystemGc(IGraphicsDevice& aDevice);
		
		/**
		 * ApplySystemGc
		 * Applies the Symbian gc drawings into the RGA graphics
		 * device.
		 */
		void ApplySystemGc();
		
		/**
		 * Fps
		 * Application frames per second value is updated once a
		 * second
		 * @return application frames per second value.
		 */
		TUint32 Fps() const;
		
		/**
		 * BackBuffer
		 * @return RGA back buffer object
		 */
		IBackBuffer& BackBuffer() const;
		
		/**
		 * BackBufferSize
		 * @return size of the application back buffer
		 */
		TSize BackBufferSize() const;
		
		/**
		 * Keyboard
		 * @return RGA keyboard input device
		 */
		IInputDevice* Keyboard();
		
		/**
		 * Window
		 * @return RGA window object
		 */
		IWindow* Window();
		
		/**
		 * RandInt
		 * @param aLow Low value in range
		 * @param aHigh High value in range
		 * @return Random integer in range
		 */
		TInt RandInt(const TInt aLow, const TInt aHigh);

		/**
		 * RandFloat
		 * @param aLow Low value in range
		 * @param aHigh High value in range
		 * @return Random float in range
		 */
		TReal RandFloat(const TReal aLow, const TReal aHigh);
		
		/**
		 * BuildFilepath
		 * builds full path of the given filename
		 * full path is constructed by getting the session
		 * drive letter, private path and appending given
		 * filename
		 * @param aFilename filename to append to full path
		 * @param aFullPath on return contains full path to file
		 * 					including the drive letter
		 */
		void BuildFilepath(const TDesC& aFilename, TDes& aFullPath);
		
		/**
		 * EnableScreenUpdate
		 * enable or disable screen update
		 * @param aEnable ETrue to enable screen update, EFalse to disable
		 */
		void EnableScreenUpdate(const TBool aEnable);
		
		/**
		 * ExitMessage
		 * @return pointer to exit message text, or NULL if not set
		 */
		HBufC* ExitMessage();
		
	protected:	// CApplicationBase pure virtuals
	
		/**
		 * OnInitialize
		 * called by the CApplicationBase right after
		 * initialisation of the application is complete
		 * this is a correct place to initialise any
		 * application specific resources
		 * @return	error code. If application returs error
		 * 			application initialisation is canceled
		 * 			and error code is passed as a return code
		 * 			from CApplicationBase::Init function
		 */
		virtual TInt OnInitialize() = 0;
		
		/**
		 * OnClose
		 * called by the CApplicationBase right before
		 * it releases its resources. This is a right place
		 * to release all application specific resources
		 */
		virtual void OnClose() = 0;
		
		/**
		 * OnDraw
		 * called by the CApplicationBase right before
		 * updating the back buffer to the screen
		 * effectively, this is a applications main loop
		 * where it renders graphics into the back buffer
		 * @param aContext back buffer context, already locked
		 */
		virtual void OnDraw(IGraphicsContext& aContext) = 0;
		
		
	private:
		
		/**
		 * InitDisplay
		 * initialise RGA display objects
		 * @return RGA error code or OK
		 */
		ReturnCode InitDisplay();
		
		/**
		 * InitGraphics
		 * initialise RGA graphics objects
		 * @param aColorFormat format of the back buffer
		 * @return RGA error code or OK
		 */
		ReturnCode InitGraphics(TUint32 aColorFormat);
		
		/**
		 * InitInput
		 * initialise RGA input objects
		 * @return RGA error code or OK
		 */
		ReturnCode InitInput();
		
		/**
		 * InitDeviceStatusObservers
		 * initialise RGA observers for messages
		 * @return RGA error code or OK
		 */
		ReturnCode InitDeviceStatusObservers();
		
		/**
		 * SolveResolution
		 * @return resolution mask values for RGA based on current display size
		 */
		uint32 SolveResolution();
		
		/**
		 * Release
		 * Release all application resources
		 */
		void Release();

	protected:	// from IInputDeviceObserver
		virtual void InputKeyPressed(	IInputDevice& aDevice,
										uint64 aTimeStamp,
										uint32 aKeyCode ) NO_THROW;
		virtual void InputKeyReleased( IInputDevice& aDevice,
	                               uint64 aTimeStamp,
	                               uint32 aKeyCode ) NO_THROW;
		virtual void InputAxisMoved( IInputDevice& aDevice,
	                             uint64 aTimeStamp,
	                             uint32 aAxisNumber,
	                             int32 aNewAxisValue ) NO_THROW;
		virtual void DeviceDisconnected( IInputDevice& aDevice ) NO_THROW;
		virtual void DeviceConnected( IInputDevice& aDevice ) NO_THROW;
		
	
	protected:	// from IApplicationStateObserver 
		virtual void FocusGained() NO_THROW;
		virtual void FocusLost() NO_THROW;
		virtual void ExitRequested() NO_THROW;
		
	protected:	// from IDisplayObserver
        virtual void DisplayOrientationChanged(
                                        uint32 aDisplayIndex,
                                        GraphicsOrientationType aType,
                                        GraphicsOrientationAngle aAngle ) NO_THROW;
        virtual void RedrawWindow( const IWindow& aWindow ) NO_THROW;
        
	private:	// from ITimerObserver
		virtual void HandleTimer( uint32 aTimerID ) NO_THROW;


	private:	// from IAlarmObserver
        virtual void AlarmOccurence( AlarmType aType ) NO_THROW;

	private:	// from ITelephonyObserver
        virtual void IncomingCall() NO_THROW;
        virtual void FinishedCall() NO_THROW;
        virtual void IncomingMessage( MessageType aMessage ) NO_THROW;
        


	protected:
		CWsScreenDevice*			iWsScreen;
	
	
	private:
		// RGA graphics members
		IIdle*						iIdle;
		IDisplay*					iDisplay;
		IWindow*					iWindow;
		IBackBuffer*				iBackBuffer;
		IGraphicsContext*			iBackBufferContext;
		IApplicationState*			iApplicationState;
		IImageConverter*			iConverter;
		IPeriodicTimer*				iFPSTimer;
		
		// RGA input members
        IInputDevice*				iKeyboard;
        TUint32						iKeyboardMask;
        
        // Symbian members
		RWsSession					iWs;
        
		
        // frame timer
        CTickTimer*					iFrameTimer;
        TUint32						iFPS;
        TUint32						iFrameCounter;

		CGraphicsContext*			iSymbianGc;
		CFbsBitmapDevice*			iSymbianBitmapDevice;
        CFbsBitmap*					iSymbianBitmap;
        IGraphicsDevice*			iRGADevice;
        
		TBool						iFocused;
		TBool						iRunning;
		TBool						iUpdateScreen;
		
		TInt64						iRandomSeed;
		
		TInt						iExitValue;
		HBufC*						iExitMessage;
		
		// device status observing
		IDeviceStatusAlarm*			iAlarmStatus;
		IDeviceStatusTelephony*		iTelephonyStatus;
	};


#endif	// __APPLICATIONBASE_H__