SunFlare (LensFlare) Tutorial

Download Code File

[Introduction]
This tutorial will guide you through modifying torque to display lens flares through flags set in the mission files. This tutorial will show you how to get a Sun Flare working with screen whiteout if camera is pointing towards the sun. You could also use the Lens Flare to make things like street lights and other uses of lens flares like bright glares off of metal from the sun. This tutorial contains all C++ changes and the only script changes would be modifying your current mission files to display flares.

[Modifying the Engine]

Adding supplied Code
Replace engine/dgl/lensFlare.cc and engine/dgl/lensFlare.h with the copies in the attached zip, and put the SunFlare.cc and SunFlare.h from the zip into engine/game/fx/ dir and add them to your project so they will get compiled.

Modify existing files
First open engine/game/game.h and add the following code to it.

#ifndef _SUNFLARE_H_
#include "game/fx/SunFlare.h"
#endif

static SunFlare *gSunFlare;

Next open engine/game/game.cc

At the end of GameInit() add:

gSunFlare = new SunFlare;

Close to the end of GameRenderWorld() after the line collisionTest.render(); add:

GameConnection* connection = GameConnection::getServerConnection();

   if (connection)  {
		//check to see if sunflare is turned on in mission file
		char* showflare = (char*)Con::evaluate("return Sun.showflare;",false);
		
		if (dStrcmp(showflare,"1") == 0)
			gSunFlare->Render();   
   }

Next open engine/game/main.cc

At the top of shutdownGame() after Con::executef(1, "onExit"); Add:

delete gSunFlare;
   gSunFlare = NULL;

Next open engine/terrain/sun.h

After LightInfo mLight; add:

Point3F        mPosition;
	bool           mShowFlare;

[**updated**]
Add this code as a public function in the Sun class:

Point3F getPosition() { return mPosition; }

Next open engine/terrain/sun.cc

In the Constructor add:

mPosition.set(0.0f,0.0f,0.0f);
   mShowFlare = false;

Then in Sun::unpackUpdate(...) Add with the other reads:

mathRead(*stream, &mPosition);
    stream->read(&mShowFlare);

Then in Sun::packUpdate(...) Add with the other writes:

mathWrite(*stream, mPosition);
    stream->write(&mShowFlare);

Then in Sun::initPersistFields() Add:

addField("position",    TypePoint3F,   Offset(mPosition, Sun));
   addField("showflare",    TypeBool,   Offset(mShowFlare, Sun));

[***updated***]
Then open engine/game/gameConnection.h

After F32 getWhiteOut() add:

void setWhiteOut(F32 amount) { mWhiteOut = amount; }

[Modifying the mission file]

Pick a mission file and open it. Go to the Sun entity (i.e. new Sun())

Change new Sun() { to new Sun(Sun) {

change position ="0 0 0"; to where you want the sun to be located..something like position = "-88.0618 -20.8792 510.364";

and then add a new variable showflare = "true"; to the sun entity.

[SunFlare Textures]
Now you need to have some flare images. I took the ones from this tutorial and added alpha channels to them and they are included in this zip. So they belong to the author of that tutorial. BTW, I used that tutorial's technique in writing the basis of the new flare code so you could also read it if you are looking into modifying this code. If someone would like to donate some new better looking images to this tutorial then feel free to send them to me.

The 4 images should be in the folder common/lensflare/

[Conclusion]
Now after you compile and start up the mission you edited you should have a sun with lensflare. There are a few quirks in the code (like all of my code :) ) you can see the sunflare through the main player...I had to do this or the flare wouldnt work in first person view...the ray is cast from the position of the camera so it really needs modifying better. If I get any optimizations I'll post them in the comments here.

[Beyond SunFlare]
The new lensflare code is heavily commented so you should be able to figure out how it works. For something like a corona on a street lamp you would need to pass it the location of the light and then only add one flare with a 0.0f offset, the light texture. Probably also want to integrate some kind of list if you did this too for processing and rendering. For something like a glare of metal you would need to know the position of the point at which the glare should be on the metal and add a flare with offset 0.0f. Youd probably want some kind of processing list for this too.