abe.blog() - Tag - flash

Ludum Dare 20 - Rainbow Riding HoodZ

Cédric — Tue, 03 May 2011 12:37:00 +0200

Pfiouu, weekend de fou furieux, 72 heures pour concevoir et réaliser un jeu avec mes compère Mr_Hk_ et Aries, on peut parler d'un sacré challenge.

Un grand merci à Motion Twin pour nous avoir hébergé le temps de la manifestation, ainsi qu'a Valandre et Deepnight qui nous ont accompagné pendant ce week end.

PLAY THE GAME

Voila :).

À bientôt.

GPP : Preprocessing and FDT

Cédric — Fri, 22 May 2009 22:15:00 +0200

A quick note about some research I've done on preprocessing and its usage in combination with FDT. It'll demonstrate how to configure GPP to make it compliant with FDT.

I'm not going to detail why using preprocessor or what you can do with it, but how to work with it in an environment which doesn't recognize it.

First problem

Using a preprocessor assume that you insert specific instructions in your files. If you use a cpp style preprocessor the syntax of the macro definition are well known by FDT so writing :

#define FOO this is foo

will not be considered as an error. But referring to FOO in your code wil result in FDT showing an error because FOO haven't be declared (in fact it was declared, but FDT don't know that it was, it's not actionscript).

It's really an important point, because when you have dozens of errors due to the preprocessing stuff you greatly reduce the relevancy of the FDT's live error highlighting feature. And it also could sometimes break autocompletion.

To solve that issue, you need a way to insert preprocessing instructions without breaking the parser. The solution have to work in any context we should use preprocessors such as :

FOO
var foo : Number = FOO;
trace( FOO );

It's at that time I came to look at GPP which allow to create your own preprocessing instructions syntax and provide default modes compliant with cpp syntax (which I'll use as base for my experiment).

To install GPP on Debian based linux distro open a shell and execute :

sudo apt-get install gpp

I've first tryed to work with syntax such as "FOO", /FOO/ or <FOO/> to trick the parser, but it should remain the type problem and I couldn't use it in all context.

I finally came to the following syntax :

[].FOO

FDT will interpret this as an access to a dynamic property of an anonymous array. As FDT can't know the type of the property it will consider it as of type *, and don't show any error when used in a typed context.

The GPP's option to setup the user-defined macro call syntax is -U, in that case the command line look like :

gpp   -U "[]." "\W" "(" "," ")" "(" ")" "#" "\" \ 
  	-O "GPPTest.as" \
  	"GPPTest.as"

Second problem

You probably want, at some point, create macro with arguments. Take a look at the example below :

// define a macro with arguments
#define CONCAT|#1#2

// call that macro, FDT will show error cause hello
//and world are not declared 
[].CONCAT(hello, world)
// produce : hello world

That macro will take the two arguments and will concatenate them. But neither hello nor world are declared members, and you probably don't want to define them as string such as the example below :

[].CONCAT("hello", "world")
// produce : "hello" "world"

So, to workaround this issue I simply wrap all the macro arguments into a single quote string such as below :

[].CONCAT('hello, world')
// produce : hello world

In fact, the macro arguments start sequence is defined with (' and the macro arguments end sequence is defined with '), in that way FDT will not complain any more about undeclared member's call. It also prevent from misinterpretation when you're passing invalid actionscript construct into a macro (example below).

#define VERSION #1 "Version : 1.0" #2

[].VERSION('trace( , )');
// produce : trace( "Version : 1.0" )

The new command line, at this step, look like :

gpp   -U "[]." "\W" "('" "," "')" "(" ")" "#" "\" \ 
  	-O "GPPTest.as" \
  	"GPPTest.as"

However there's some limitations with this workaround :

1 - If you want to pass a string as argument (with the quotes) you can only use the double quotes, and as the GPP's cpp mode define strings with both " and ' you'll need to remove the second string definition using the -s option, or you can redefine all the comments and strings option like that (I've encountered some issues using the -s options because of the default mode, so I prefer redefine all that stuff by myself) :

gpp   -U "[]." "\W" "('" "," "')" "(" ")" "#" "\" \ 
  	+c "/*" "*/" \ 
 	+c "//" "\n" \
  	+s "\"" "\"" "\\" \
  	-O "GPPTest.as" \
  	"GPPTest.as"

2 - GPP offer to create macro with named arguments. In order to create such macro you need to use user defined macro call as the name of the new macro, such as

#define FOO(x,y) this is x, and the this is y.

But it seems that GPP doesn't like quotes in that context. In that case, there's a little trick to do before defining these kind of macros. Just use the #mode macro to change locally the way the macro are called, like that :

// push a new mode in the modes' stack
#mode push
// change the macro call syntax for the pushed mode
#mode user "" "" "(" "\W,\W" ")" "(" ")" "#" "\\";
// define the macro using the new mode syntax
#define FOO(x,y) this is x, and the this is y.
// remove the mode
#mode pop

Third problem

Another case which may cause trouble to FDT is the case of multi-line macro definition such as :

#define FOO I want to insert a new line \
in the macro

GPP's cpp mode define a macro definition as starting with # and finishing with \n. So you have to escape the new line character to create a multi-line declaration. When FDT find a # character it simply ignore the rest of the line, but it don't understand that escaping the new line char means that the macro definition continue on the next line, so, if the next line don't start with a # char it'll parse it as normal code, which probably result in errors.

For that issue I found that XML can be used outside of the class definition, I modified the built-in macro syntax to match that syntax :

<#define:FOO I want to insert a new line 
in the macro/>

The GPP's option to setup meta-macro definition syntax is -M. To produce that syntax, the option will look like that :

-M "<#" "/>" ":" "\B" "/>" "<" "/>"

However it'll produce many parsing error while starting to nest macros definition. Take the following example :

#define ASIS(x) x
#define SILENT(x) ASIS()
#define ASSERTS(msg) SILENT(
	#ifndef DEBUG
	#define TEMP(x) trace( x + ' at #file
:#line
' )
	#else
	#define TEMP(x)
	#endif
) TEMP(msg)

It create a simple macro called ASSERTS witch render a trace call with the file and line appended to the macro argument. The issue here is that we cannot use the XML like syntax because it suppose to nest macros. But as the macro definition is supposed to be ended with a \n char, it produces many errors in FDT because some lines starts with invalid chars. You can workaround this by using another termination char for the macro definition, such as ; for example.

With these settings, the previous example look like :

#define ASIS(x) x;
#define SILENT(x) ASIS();
#define ASSERTS(msg) SILENT(
	#ifndef DEBUG;
	#define TEMP(x) trace( x + ' at #file;:#line;' ); 
	#else;
	#define TEMP(x); 
	#endif; ) TEMP(msg);

The fact that the single quote string is not defined allow GPP to parse macro in the string, without having to escape the quote (which result in big mess in the FDT parsing). And as you can see, you can now inline the part that may produce errors in FDT. And the command line now look like :

gpp +n \
-U "[]." "\W" "('" "," "')" "(" ")" "#" "\\" \
	-M "#" "\n" "\B" "\B" ";" "(" ")" \
  	+c "/*" "*/" \
 	+c "//" "\n" \
  	+s "\"" "\"" "\\" \
  	-O "GPPTest.as" \
  	"../src/GPPTest.as"

Conclusion

All these tricks works well for the common usage of a preprocessor, but for some advanced GPP's features such as defeval macro there's still a lot of issues coming from the syntax changes. I'll continue to search how I can fix the issues with defeval, but I'm not sure there's a way to fix it. So stay tuned :).

Using PixelBender on Linux with Wine and PBDT

Cédric — Sat, 25 Apr 2009 19:52:00 +0200

Joa Erbert just release the PDBT plugin for Eclipse, and as I was waiting for it since its first announcement I'm happy to propose you a little step by step on how to setup Wine properly and use the PDBT plugin with the Pixel Bender Toolkit.

Wine and Winetricks

Download and install Wine with apt :

sudo apt-get install wine

Get the winetricks command file :

wget http://www.kegel.com/wine/winetricks

Then execute these commands, it will greatly simplify the use of winetricks :

chmod +x winetricks
sudo mv winetricks /usr/bin

Installing Pixel Bender

In my humble opinion, trying to install Pixel Bender directly in wine is way too hard and long (as for all the CS3|CS4 stuff), many error occurs and trying to fix all issues is probably not possible. The simpler is to install it on Windows, and then copying the whole Pixel Bender Toolkit folder into wine (~/.wine/dosdevices/c:/Program\ Files).

Once the copy done, you can try to run the pbutil.exe with :

wine ~/.wine/dosdevices/c:/Program\ Files/Pixel\ Bender\ Toolkit/pbutil.exe

If you have any errors such :

fixme:actctx:parse_depend_manifests Could not find dependent assembly L"Microsoft.VC80.CRT"
fixme:actctx:parse_depend_manifests Could not find dependent assembly L"Microsoft.VC80.CRT"
err:module:import_dll Library MSVCP80.dll (which is needed by L"Z:\\media\\disk\\Dev\\tools\\archives\\Pixel Bender Toolkit\\aif_core.dll") not found
err:module:import_dll Library MSVCR80.dll (which is needed by L"Z:\\media\\disk\\Dev\\tools\\archives\\Pixel Bender Toolkit\\aif_core.dll") not found
err:module:import_dll Library aif_core.dll (which is needed by L"Z:\\media\\disk\\Dev\\tools\\archives\\Pixel Bender Toolkit\\pbutil.exe") not found
fixme:actctx:parse_depend_manifests Could not find dependent assembly L"Microsoft.VC80.CRT"
...

That there is some missing dlls, that's where we need to use winetricks. Report to the Winetricks page to find which lib to load to get all the missing dlls.

In my case (the log above), I needed to execute :

winetricks vcrun2005sp1 vcrun2005

Which installs the MS Visual C++ 2005 libraries (mfc80,msvcp80,msvcr80) into wine.

When you get :

APPLICATION ERROR: not enough command line arguments! Program usage: pbutil inputFileName outputFileName

It works !!

PDBT

Once You've install the PDBT plugin into the proper Eclipse install, you need to make sure that PDBT will call pbutil.exe with Wine. The operation is really simple, create a file named pbutil in the Pixel Bender Util directory in Wine, make it executable, and write :

#!/bin/sh
wine "$0.exe $@"

That's all, now PDBT will compile .pbj file each time you save your .pbk files :).

La bonne blague de Flash

Cédric — Thu, 16 Apr 2009 12:44:00 +0200

La bonne blague, c'est que si vous importez une image dans la bibliothèque de Flash, que vous placez ce bitmap au sein d'un clip, que vous cochez la case Exporter pour ActionScript, alors l'image n'est plus une image mais un objet Shape une fois le fichier compilé. Impossible donc d'accéder aux propriétés du bitmap. Si vous souhaitez par exemple activer ou désactiver le lissage, ou le pixel snapping à l'exécution, et ben vous pouvez pas !

L'explication ? J'en ai trouvé une ici, par le toujours très pertinent Senocular :

Flash consolidates child objects on the timeline by merging all vector shapes and bitmaps in a timeline (that occupy the same frame span). To make this work for bitmaps, they are converted to vector shapes with bitmap fills. But in doing this, many vectors and bitmaps can go from dozens of different objects and children and become just one. Since none of these objects can be dynamically manipulated at runtime (i.e. you cannot associate instance names with them) this consolidation is suitable and efficient.

If you want the bitmapData, you'll have to draw the screen with whats there now, or better yet, get the bitmap from the library.

En résumé, pour éviter que chaque image d'une animation soit encombré de dizaines d'objets, Flash converti tout les bitmaps en formes vectorielles, et utilise un remplissage bitmap pour afficher l'image. L'idée peut paraître séduisante, si ce n'est qu'elle limite grandement l'usage d'images à partir de bibliothèques créées dans Flash.

On a alors deux solutions possible.
Soit on n'a pas besoin d'accéder aux propriétés du bitmap à l'exécution (aussi bien au niveau du BitmapData que de l'objet Bitmap devant le contenir) et auquel cas on peut laisser Flash faire ses optimisations, mais si un lissage est nécessaire sur les images c'est à la personne constituant la bibliothèque de cocher l'option adéquate pour chaque image.
L'autre solution, c'est d'exporter pour ActionScript l'image et non pas le clip la contenant, le résultat, c'est que l'image est instanciable en tant que BitmapData. Le seul souci pour moi, c'est que le constructeur de la classe BitmapData impose de définir les dimensions de l'image, ce qui me pose quelques problèmes car je préfère pouvoir instancier les ressources graphiques à la volée et sans avoir à préciser des arguments (ainsi je peux plus ou moins tout inter-changé à l'exécution).
On en reviens donc à la première solution, c'est-à-dire que le graphiste en charge de la bibliothèque dans Flash doit régler correctement les options de chaque image. Hors, l'option "Autoriser le lissage" est toujours décoché par défaut. Du coup, j'ai développé un petit script JSFL pour autoriser le lissage sur tout les bitmaps d'une bibliothèque. Script que voici :

var lib = fl.getDocumentDOM().library;
// on force la sélection de tout les éléments afin de pouvoir
// traiter la totalité de la bibliothèque d'un coup
lib.selectAll();

var a = lib.items;
for( var i in a )
{
	var asset = a[i];

	if( asset.itemType == "bitmap" )
		asset.allowSmoothing = true;
}

Voila, en espérant que ça soit utile à d'autres.

PS : C'est typiquement le genre de détails qui ne me fait pas du tout regretter mon passage sous Linux et mon abandon de Flash dans mon travail quotidien. Je trouve l'usage des metatag [Embed] beaucoup plus souple que de passer par Flash pour la constitution de bibliothèque.

Teasing

Cédric — Fri, 20 Feb 2009 12:06:00 +0100

A bit of teasing about some works I've done the past months for Aesia. For the moment the code is far to be clean enough for a public release.
You can see in the Log windows the string used to fill the custom text field.

It seems that you haven't a Flash Player installed, go [here|http://get.adobe.com/fr/flashplayer/|fr] to get the latest version.

Camera & Layers - Part 3 - Rotation

Cédric — Thu, 12 Feb 2009 20:16:00 +0100

The third part of the camera & layers series. Now we are going to make the world rotating according to the camera.

Rotation

That's the most difficult part of the creation of the Camera, and to achieve that we must use some matrix computations. By the way, the camera rotation can't be used directly with bitmap based renderer (because of the BitmapData.copyPixel limitations).

The change in the Camera class are really small. The only significant changes are the add of getters to access the original (unmodified) width and height and a protected property which will store the camera rotation. Rotation is an angle in radians, in that way there's no need to convert the rotation value each time we will need to operate a transformation onto an object.

protected var _rotation : Number;

public function get originalWidth () : Number { return _originalWidth; }
public function get originalHeight () : Number { return _originalHeight; }

I also modify the Camera constructor like this :

public function Camera ( screen : Rectangle = null, zoom : Number = 1, rotation : Number = 0, silent : Boolean = false )
{
	_rotation = rotation;
	this.screen = screen ? screen : new Rectangle ( 0, 0, 550, 400 );
	this.zoom = zoom;
	silentMode = silent;
}

I affect the rotation before setting screen and zoom for the reason that rotation don't affect directly the other camera properties. It's a bit weird, because if the rotation is different than 0, the x and y properties of the screen will not be accurate. But as the Rectangle class don't handle rotation, we should use a Polygon instead, but it should be a heavy change and it doesn't fit well with the performance purpose that games requires.

I also add accesors for the rotation :

public function get rotation () : Number { return _rotation; }
public function set rotation ( n : Number ) : void
{
	_rotation = n;
	fireSilentCameraChange();
}

In the same way, I modify the CameraEvent to add an accessor to the camera rotation :

public function get rotation () : Number { return camera.rotation; }

Ok, now the big part. To handle the rotation in the layer, we have to change the whole transformation routine. Instead of affecting each value independently we will use a Matrix object.

public function cameraChanged ( e : CameraEvent ) : void
{   	
	// first we store some usefull data for computation
	var m : Matrix = transform.matrix;
	var sc : Point = e.camera.center;
	var csx : Number = e.camera.screen.x;
	var csy : Number = e.camera.screen.y;

	// reset the matrix
	m.identity();

	// translate the matrix corresponding to the scroll and parallax part
	m.translate( -csx * parallax, -csy * parallax );
	
	//  we scale and rotate the matrix according to the center of the camera
	scaleAndRotateAroundExternalPoint( m, 
							sc.x - csx, 
							sc.y - csy,
							-e.rotation, 
							e.zoom,
						  	e.zoom );
	
	// then we translate the camera to return back the transformation center to the stage center
	// it's because of that translation that we need to access the camera's original width and height
	m.translate( csx - sc.x + ( e.camera.originalWidth / 2 ),
			 csy - sc.y + ( e.camera.originalHeight / 2 ) );

	// affect the matrix to this layer
	transform.matrix = m;
}
// that implementation is based on the work of Robert Penner for the fl.motion package in Flash.
public function scaleAndRotateAroundExternalPoint(m:Matrix, x:Number, y:Number, angleRadians:Number, scalex : Number, scaley : Number ):void
{
	m.tx -= x;
	m.ty -= y;
	m.rotate( angleRadians );
	m.scale( scalex, scaley );
	m.tx += x;
	m.ty += y;
}

The last change is operated in the demo class to animate the camera rotation

camera.rotation = n / 8;

It seems that you haven't a Flash Player installed, go [here|http://get.adobe.com/fr/flashplayer/|fr] to get the latest version.

Last words

As you have probably notice, with the rotation the Rectangle figuring the screen is no longer a reliable source to know the real screen part. That's due to the fact that the Rectangle class don't handle rotation natively. As a consequence, the getLocalCameraScreen is somewhat useless for all case where rotation != 0. One way to solve these cases is to use a Polygon object instead of Rectangle but that require much more matrix computation, each vertex of the polygon have to be rotated each time the camera rotation change. It's will be a bit heavier than without rotation, and if you don't need rotation you should prefer the lighter implementation presented before. In most games there's no need for rotation, that's why I always have an implementation that fit with the context.

I hope that these posts have been useful for you. And if I get some time in the next months, I'll try to complete them with some funny usages of cameras.

Complete code

package
{
	import flash.display.DisplayObject;
	import flash.events.Event;
	import flash.events.EventDispatcher;
	import flash.geom.Point;
	import flash.geom.Rectangle;

	[Event ( name="cameraChange", type="CameraEvent" )]
	public class Camera extends EventDispatcher
	{
		public var silentMode : Boolean;
		
		protected var _screen : Rectangle;
		protected var _zoom : Number;
		protected var _rotation : Number;
		
		protected var _originalWidth : Number;
		protected var _originalHeight : Number;
		
		public function Camera ( screen : Rectangle = null, zoom : Number = 1, rotation : Number = 0, silent : Boolean = false )
		{
			_rotation = rotation;
			this.screen = screen ? screen : new Rectangle ( 0, 0, 550, 400 );
			this.zoom = zoom;
			silentMode = silent;
		}
		
		/*---------------------------------------------------------------------
		 * ACCESSORS
		 *--------------------------------------------------------------------*/
		
		public function get x () : Number { return _screen.x; }  
		public function set x ( n : Number ) : void
		{ 
			_screen.x = n;
			fireSilentCameraChange ();
		}
		public function get y () : Number { return _screen.y; }  
		public function set y ( n : Number ) : void
		{ 
			_screen.y = n;
			fireSilentCameraChange ();
		}      
		public function get width () : Number { return _screen.width; }  
		public function set width ( n : Number ) : void
		{ 
			_screen.width = n;
			fireSilentCameraChange ();
		}
		public function get height () : Number { return _screen.height; }  
		public function set height ( n : Number ) : void
		{ 
			_screen.height = n;
			fireSilentCameraChange ();
		} 
		
		public function get originalWidth () : Number { return _originalWidth; }
		public function get originalHeight () : Number { return _originalHeight; }
		
		public function get rotation () : Number { return _rotation; }
		public function set rotation ( n : Number ) : void
		{
			_rotation = n;
			fireSilentCameraChange();
		}
		   
		public function get center () : Point	
		{ 
			return new Point( _screen.x + _screen.width / 2, 
							  _screen.y + _screen.height / 2 ); 
		}
		public function set center ( p : Point ) : void
		{
			_screen.x = p.x - ( _screen.width / 2 );
			_screen.y = p.y - ( _screen.height / 2 );
			fireSilentCameraChange ();
		}
		public function get centerX () : Number { return center.x; }  
		public function set centerX ( n : Number ) : void
		{ 
			center = new Point( n, center.y );
			fireSilentCameraChange ();
		}
		public function get centerY () : Number { return center.y; }  
		public function set centerY ( n : Number ) : void
		{ 
			center = new Point( center.x, n );
			fireSilentCameraChange ();
		}    
		public function get screen () : Rectangle { return _screen.clone(); }
		public function set screen ( screen : Rectangle ) : void
		{
			_screen = screen;
			_originalWidth = screen.width;
			_originalHeight = screen.height;
			fireSilentCameraChange ();
		}
		public function get zoom () : Number { return _zoom; }
		public function set zoom ( n : Number ) : void
		{
		    _zoom = n;
		
		    // save the actual screen center
		    var c : Point = center;
		        
		    _screen.width = _originalWidth / _zoom;
		    _screen.height = _originalHeight / _zoom;
		
		    center = c;
		}
		
		/*---------------------------------------------------------------------
		 * PUBLIC MISC
		 *--------------------------------------------------------------------*/
		public function centerDisplayObject ( display : DisplayObject ) : void
		{
			var r : Rectangle = display.getBounds( display.parent );
			var x : Number = r.x + r.width / 2;
			var y : Number = r.y + r.height / 2;
			
			center = new Point( x, y );
		}	
		public function addCameraChangeListener ( closure : Function ) : void
		{
			addEventListener( CameraEvent.CAMERA_CHANGE, closure );
		}
		public function removeCameraChangeListener ( closure : Function ) : void
		{
			removeEventListener( CameraEvent.CAMERA_CHANGE, closure );
		} 
		public function fireCameraChange () : void
		{
			if( hasEventListener( CameraEvent.CAMERA_CHANGE ) )
		    	dispatchEvent( new CameraEvent( CameraEvent.CAMERA_CHANGE, this ) ); 
		}
		
		/*---------------------------------------------------------------------
		 * PROTECTED MEMBERS
		 *--------------------------------------------------------------------*/
		
		protected function fireSilentCameraChange () : void
		{
			if( !silentMode )
				fireCameraChange();
		}
	}
}

package 
{
	import flash.display.Sprite;
	import flash.geom.Matrix;
	import flash.geom.Point;
	import flash.geom.Rectangle;

	public class CameraLayer extends Sprite
	{
	    public var parallax : Number;
	  
	    public function CameraLayer ( parallax : Number = 1 )
	    {
	         this.parallax = parallax;
	    }
	     
		public function cameraChanged ( e : CameraEvent ) : void
		{
			// first we store some usefull data for computation
			var m : Matrix = transform.matrix;
			var sc : Point = e.camera.center;
			var csx : Number = e.camera.screen.x;
			var csy : Number = e.camera.screen.y;
			
			// reset the matrix
			m.identity();
			
			// translate the matrix corresponding to the scroll and parallax part
			m.translate( -csx * parallax, -csy * parallax );
			
			//  we scale and rotate the matrix according to the center of the camera
			scaleAndRotateAroundExternalPoint( m, 
											 sc.x - csx, 
											 sc.y - csy,
											  -e.rotation, 
											   e.zoom,
									  		   e.zoom );
			
			// then we translate the camera to return back the transformation center to the stage center
			// it's because of that translation that we need to access the camera's original width and height
			m.translate( csx - sc.x + ( e.camera.originalWidth / 2 ),
						 csy - sc.y + ( e.camera.originalHeight / 2 ) );
			
			// affect the matrix to this layer
			transform.matrix = m;
		}
		// that implementation is based on the work of Robert Penner for the fl.motion package in Flash.
		public function scaleAndRotateAroundExternalPoint(m:Matrix, x:Number, y:Number, angleRadians:Number, scalex : Number, scaley : Number ):void
		{
			m.tx -= x;
			m.ty -= y;
			m.rotate( angleRadians );
			m.scale( scalex, scaley );
			m.tx += x;
			m.ty += y;
		}
	    
		public function getLocalCameraScreen ( c : Camera ) : Rectangle
		{
			return new Rectangle( c.x * parallax,
								  c.y * parallax, 
								  c.width, 
								  c.height);
		}
	}
}

package
{
	public class CameraEvent extends Event
	{
		static public const CAMERA_CHANGE : String = "cameraChange";
		
		public var camera : Camera;
	
		public function CameraEvent ( type : String, 
								camera : Camera, 
								bubbles : Boolean = false, 
								cancelable : Boolean = false )
		{
			super( type, bubbles, cancelable );
			this.camera = camera;
		}
		public function get screen () : Rectangle { return camera.screen; }
		public function get zoom () : Number { return camera.zoom; }
		public function get rotation () : Number { return camera.rotation; }
	}
}

Camera & Layers - Part 2 - Zoom

Cédric — Mon, 02 Feb 2009 20:45:00 +0100

The second post in the camera & layers series. In this post we will look at implementing the zoom in the previously created Camera and CameraLayer classes.

Zoom

As I previously say, the screen rectangle in Camera represent the part of the stage that should be on the screen. So, to implements zoom in our camera, we should consider these two assumptions :

The size of the rectangle must grow or reduce according to the zoom factor.
The zoom will be performed on the middle of the screen. So the screen rectangle position will change according.

First of all, we need to change our Camera class to implements zoom. As the Rectangle instance, figuring the screen, have to be resized we have to store the original width and height of the camera each time a new screen rectangle is defined for the camera. So we add some protected properties in the class body.

protected var _zoom : Number;
protected var _minZoom : Number;
protected var _maxZoom : Number;

protected var _originalWidth : Number;
protected var _originalHeight : Number;

Then, in the screen setter, the width and height of the rectangle are stored.

public function set screen ( r : Rectangle ) : void
{
    _screen = r;
    _originalWidth = r.width;
    _originalHeight = r.height;
    fireSilentCameraChange ();
}

We need accessors for the zoom stuff :

public function get zoom () : Number { return _zoom; }
public function set zoom ( n : Number ) : void
{
    // restrict the zoom value into the boundary
    _zoom = Math.max( _minZoom, Math.min( _maxZoom, n ) );

    // save the actual screen center
    var c : Point = center;
        
    _screen.width = _originalWidth / _zoom;
    _screen.height = _originalHeight / _zoom;
    
    // relocate and fire event
    center = c;
}
public function get minZoom () : Number { return _minZoom; }
public function set minZoom ( n : Number ) : void
{
    _minZoom = n;
    // force to check boundary and update
    zoom = zoom;
}
public function get maxZoom () : Number { return _maxZoom; }
public function set maxZoom ( n : Number ) : void
{
    _maxZoom = n;
    // force to check boundary and update
    zoom = zoom;
}

And to initialize the new stuff, I add some arguments to the Camera constructor, call the screen and zoom setters (by calling this.screen we also initialize the original dimension for the screen).

public function Camera ( screen : Rectangle = null, 
								zoom : Number = 1, 
								minZoom : Number = 0.1, 
								maxZoom : Number = 2, 
								silent : Boolean = false )
{
	this._minZoom = minZoom;
	this._maxZoom = maxZoom;
	this.screen = screen ? screen : new Rectangle ( 0, 0, 550, 400 );
	this.zoom = zoom;
	silentMode = silent;
}

In the CameraEvent class we add a getter for the zoom :

public function get zoom () : Number { return camera.zoom; }

In the CameraLayer class we modify the cameraChange function :

public function cameraChange ( e : CameraEvent ) : void
{
     // use the parallax and camera zoom to multiply the screen coords
    x = -e.screen.x * e.zoom * parallax;
    y = -e.screen.y * e.zoom * parallax;
    // scale is equal to zoom
    scaleY = scaleX = e.zoom;
}

And last but not least, in the enterFrame function of our sample demo, add :

// make the zoom vary between 0.5 and 1.5
camera.zoom = 1 + Math.sin( n/4 )*.5;

As the on screen size of the layers will change due to the zoom change, I adapt th fillLayer function to always dots all over the screen :

s.x = Math.random() * 2200;
s.y = -100 + Math.random() * 400;

Instead of :

s.x = Math.random() * 1100;
s.y = Math.random() * 200;

Run the demo and look :

It seems that you haven't a Flash Player installed, go [here|http://get.adobe.com/fr/flashplayer/|fr] to get the latest version.

Special cases

Zoom & Parallax at the same time

Combining zoom and parallax together don't produce a perspective effect, there's no focal or no depth value at all. Of course, you can obtain it by implementing these features in your camera.

Zoom & BitBlit-based renderer

As BitmapData.copyPixel don't support scale or rotation, You can't use zoom directly. There's, as far as I know, two solutions to this issue :

You use the BitmapData.draw method instead, and create a Matrix instance to provide to the function. It's important to notice that using the draw method don't offer as much performance as using copyPixel.
You create the Bitmap, onto which your renderer will draw, bigger than the screen size. Then you can use the zoom factor to resize that bitmap, and at the same time, you change the size of the redrawn part of that bitmap in your renderer. The size of the BitmapData, in that case, should be width / minZoom and height / minZoom (according to BitmapData size limitations).

Complete `Camera` class

package
{
	import flash.display.DisplayObject;
	import flash.events.Event;
	import flash.events.EventDispatcher;
	import flash.geom.Point;
	import flash.geom.Rectangle;
	
	[Event ( name="cameraChange", type="flash.events.Event" )]
	public class Camera extends EventDispatcher
	{
	    public var silentMode : Boolean;
		
		protected var _screen : Rectangle;
		protected var _zoom : Number;
		protected var _minZoom : Number;
		protected var _maxZoom : Number;
		
		protected var _originalWidth : Number;
		protected var _originalHeight : Number;
		
		public function Camera ( screen : Rectangle = null,
										zoom : Number = 1, 
										minZoom : Number = 0.1, 
										maxZoom : Number = 2, 
										silent : Boolean = false )
		{
			this._minZoom = minZoom;
			this._maxZoom = maxZoom;
			this.screen = screen ? screen : new Rectangle ( 0, 0, 550, 400 );
			this.zoom = zoom;
			silentMode = silent;
		}
		
		/*---------------------------------------------------------------------
		 * ACCESSORS
		 *--------------------------------------------------------------------*/
		
		public function get x () : Number { return _screen.x; }  
		public function set x ( n : Number ) : void
		{ 
			_screen.x = n;
			fireSilentCameraChange ();
		}
		public function get y () : Number { return _screen.y; }  
		public function set y ( n : Number ) : void
		{ 
			_screen.y = n;
			fireSilentCameraChange ();
		}      
		public function get width () : Number { return _screen.width; }  
		public function set width ( n : Number ) : void
		{ 
			_screen.width = n;
			fireSilentCameraChange ();
		}
		public function get height () : Number { return _screen.height; }  
		public function set height ( n : Number ) : void
		{ 
			_screen.height = n;
			fireSilentCameraChange ();
		}    
		public function get center () : Point	
		{ 
			return new Point( _screen.x + _screen.width / 2, 
							  _screen.y + _screen.height / 2 ); 
		}
		public function set center ( p : Point ) : void
		{
			_screen.x = p.x - ( _screen.width / 2 );
			_screen.y = p.y - ( _screen.height / 2 );
			fireSilentCameraChange ();
		}
		public function get centerX () : Number { return center.x; }  
		public function set centerX ( n : Number ) : void
		{ 
			center = new Point( n, center.y );
			fireSilentCameraChange ();
		}
		public function get centerY () : Number { return center.y; }  
		public function set centerY ( n : Number ) : void
		{ 
			center = new Point( center.x, n );
			fireSilentCameraChange ();
		}    
		public function get screen () : Rectangle { return _screen.clone(); }
		public function set screen ( screen : Rectangle ) : void
		{
			_screen = screen;
			_originalWidth = screen.width;
			_originalHeight = screen.height;
			fireSilentCameraChange ();
		}
		public function get zoom () : Number { return _zoom; }
		public function set zoom ( n : Number ) : void
		{
			// restrict the zoom value into the boundary
			_zoom = Math.max( _minZoom, Math.min( _maxZoom, n ) );
		
			// save the actual screen center
			var c : Point = center;
		        
			_screen.width = _originalWidth / _zoom;
			_screen.height = _originalHeight / _zoom;
		
			// relocate and fire event
			center = c;
		}
		public function get minZoom () : Number { return _minZoom; }
		public function set minZoom ( n : Number ) : void
		{
			_minZoom = n;
			// force to check boundary and update
			zoom = zoom;
		}
		public function get maxZoom () : Number { return _maxZoom; }
		public function set maxZoom ( n : Number ) : void
		{
			_maxZoom = n;
			// force to check boundary and update
			zoom = zoom;
		}
		
		/*---------------------------------------------------------------------
		 * PUBLIC MISC
		 *--------------------------------------------------------------------*/
		public function centerDisplayObject ( display : DisplayObject ) : void
		{
			var r : Rectangle = display.getBounds( display.parent );
			var x : Number = r.x + r.width / 2;
			var y : Number = r.y + r.height / 2;
			
			center = new Point( x, y );
		}	
		public function addCameraChangeListener ( closure : Function ) : void
		{
			addEventListener( CameraEvent.CAMERA_CHANGE, closure );
		}
		public function removeCameraChangeListener ( closure : Function ) : void
		{
			removeEventListener( CameraEvent.CAMERA_CHANGE, closure );
		} 
		public function fireCameraChange () : void
		{
			if( hasEventListener( CameraEvent.CAMERA_CHANGE ) )
				dispatchEvent( new CameraEvent( CameraEvent.CAMERA_CHANGE, this ) ); 
		}
		
		/*---------------------------------------------------------------------
		 * PROTECTED MEMBERS
		 *--------------------------------------------------------------------*/
		
		protected function fireSilentCameraChange () : void
		{
			if( !silentMode )
				fireCameraChange();
		}
	}

}

Complete `CameraEvent` class

package
{
	import flash.events.Event;
	import flash.geom.Rectangle;

	public class CameraEvent extends Event
	{
		static public const CAMERA_CHANGE : String = "cameraChange";
		
		public var camera : Camera;
	
		public function CameraEvent ( type : String, 
									  camera : Camera, 
									  bubbles : Boolean = false, 
									  cancelable : Boolean = false )
		{
			super( type, bubbles, cancelable );
			this.camera = camera;
		}
		public function get screen () : Rectangle { return camera.screen; }
		public function get zoom () : Number { return camera.zoom; }
	}
}

Complete `CameraLayer` class

package
{
	import flash.display.Sprite;
	import flash.geom.Rectangle;

	public class CameraLayer extends Sprite
	{
		public var parallax : Number;
	  
		public function CameraLayer ( parallax : Number = 1 )
		{
			this.parallax = parallax;
		}
	     
		public function cameraChange ( e : CameraEvent ) : void
		{
			// use the parallax to multiply the screen coords
			x = -e.screen.x * e.zoom * parallax;
			y = -e.screen.y * e.zoom * parallax;
			// scale is equal to zoom
			scaleY = scaleX = e.zoom;
		}
	    
		public function getLocalCameraScreen ( c : Camera ) : Rectangle
		{
			return new Rectangle( c.x * parallax,
								  c.y * parallax, 
								  c.width, 
								  c.height);
		}
	}
}

Camera & Layers - Part 1 - Scrolling and Parallax

Cédric — Fri, 30 Jan 2009 19:51:00 +0100

There's the first post of a series about some concepts I learn during the last six years, since I started to learn programming.

As I don't really know how to introduce it, I will do it briefly. The first topic of that series will be about camera and layers. These objects are one of those I use everyday, in almost every game project.

Many game types require, in their engine, features such scrolling, parallax and objects buffering. These features are, in many games, an important part of the engine, such as in tile based game, shoot them up, platform games, etc...

In the first engine I wrote, I built these features independently, without thinking about how I can manage all that stuff in a simple and unique way, stupid isn't it ? Resulting that these engines was really hard to maintain (that's rather obvious...). Scrolling was achieved by moving the main stage MovieClip accordingly to the moves of the first player character. Then, when it comes to add some parallax layer in the background I have to keep a reference to the first player character in each of these layers. And concerning objects buffering, pfff... It was really a mess... I prefer not to talk about it ^^'. Of course all the code I wrote for a game was too dependent of the game elements, so I rewrote that part in each new game.

It's at that time I started to think about a way to handle all that stuff with a single object : a Camera. Those who are familiar with 3D world always manipulate cameras, but in the 2D world that's not a widely adopted practice. And it's not a game specific tool, a camera is really usefull when creating application. For exemple, with that camera, creating an application with a main canvas, with common controls like pan, zoom or canvas rotation (such as those we can see in software such Painter or ArtRage), is pretty fast. So I think everybody should benefit of using that kind of stuff.

Camera Basis

Basically, a camera can be represented as a Rectangle object. That rectangle figure the screen, or, more precisely, the part of the stage that should be on the screen. Of course, our camera must notify all layers (or any other kind of camera listeners) attached to it to change their state when camera state have changed. So the Camera class will extends EventDispatcher. I don't want to have an object with too much dependencies with the render, that's why the camera system will be event-based.

I will not talk at this time of all the methods the Camera class should implements, so I start with a really poor implementation of the Camera class. You can find a more usable version at the end of this page.

package 
{
    import flash.events.Event;
    import flash.events.EventDispatcher;
    import flash.geom.Rectangle;

    [Event ( name="cameraChange", type="flash.events.Event" )]
    public class Camera extends EventDispatcher
    {
        // screen is public for the moment, faster to write and to test
        public var screen : Rectangle;

        public function Camera ( screen : Rectangle = null )
        {
            this.screen = screen ? screen : new Rectangle ( 0, 0, 550, 400 );
        }
        public function fireCameraChange () : void
        {
            dispatchEvent( new Event ( "cameraChange" ) ); 
        }
    }
}

Ok, now we have the base for our Camera class, I'll return on that later in order to make it more user-friendly. For the moment, let's talk about layers.

A layer, in this context, is just a DisplayObject which move according to the camera it listen to. A layer always move in the inverse direction of the camera, so, when camera screen is at coordinates x=500 and y=500, the layer coordinates will be x=-500 and y=-500.

package 
{
    import flash.events.Event;
    
    public class CameraLayer extends Sprite
    {
        public function CameraLayer ()
        {}
         
        public function cameraChanged ( e : Event ) : void
        {
             var camera : Camera = e.target as Camera;

             x = -camera.screen.x;
             y = -camera.screen.y;
        }
    }
}

It's as simple as that :). Now you can fill the layer with whatever object you want, and after having register the layer to the cameraChange event of the camera, the layer will move accordingly to the camera moves.

Below a sample code of demo :

package  
{
	import flash.display.Shape;
	import flash.display.Sprite;
	import flash.events.Event;
	import flash.geom.Rectangle;		

	[SWF(width="550", height="200")]
	public class CameraTut1 extends Sprite 
	{
		private var camera : Camera;
		private var layer : CameraLayer;	

		public function CameraTut1 ()
		{
			camera = new Camera( new Rectangle( 0, 0, 550, 200 ) );
			layer = new CameraLayer();
			
			camera.addEventListener( "cameraChange" , layer.cameraChanged );
			
			fillLayer();
			addChild( layer );
			
			addEventListener( Event.ENTER_FRAME, enterFrame );
		}
		// used to move the cam
		private var n:Number = 0;
		private function enterFrame ( e : Event ) : void
		{
			// move the camera and make it loop back to origin
			camera.screen.x = 225 + Math.sin( n ) * 225;
			camera.fireCameraChange();
			
			n += 0.05;
		}
		private function fillLayer () : void
		{
			var l : Number = 100;
			
			while (l--)
			{
				var s : Shape = new Shape();
				s.graphics.beginFill(0);
				s.graphics.drawCircle(0, 0, 5 + Math.random() * 5);
				s.graphics.endFill();
				
				s.x = Math.random() * 1100;
				s.y = Math.random() * 200;
				
				layer.addChild( s );
			}
		}
	}
}

And the result (the swf was compiled with the latest Flex SDK, and targeted to Flash Player 10) :

It seems that you haven't a Flash Player installed, go [here|http://get.adobe.com/fr/flashplayer/|fr] to get the latest version.

As you can see, the scroll works :).

Parallax

Parallax^[1] is pretty simple to implements. We just need to add a property to the CameraLayer class and use it as a factor on camera screen coordinates.

package 
{
    import flash.events.Event;
    
    public class CameraLayer extends Sprite
    {
        public var parallax : Number;
      
        public function CameraLayer ( parallax : Number = 1 )
        {
             this.parallax = parallax
        }
         
        public function cameraChanged ( e : Event ) : void
        {
             var camera : Camera = e.target as Camera;

             // use the parallax to multiply the screen coords
             x = -camera.screen.x * parallax;
             y = -camera.screen.y * parallax;
        }
    }
}

And now, let's create a new layer in our demo :

package  
{
	import flash.display.Shape;
	import flash.display.Sprite;
	import flash.events.Event;
	import flash.geom.Rectangle;	

	[SWF(width="550", height="200")]
	public class CameraTut2 extends Sprite 
	{
		private var camera : Camera;
		private var layer1 : CameraLayer;	
		private var layer2 : CameraLayer;	

		public function CameraTut2 ()
		{
			camera = new Camera( new Rectangle( 0, 0, 550, 200 ) );
			layer1 = new CameraLayer(.5);
			layer2 = new CameraLayer();
			
			camera.addEventListener( "cameraChange" , layer1.cameraChanged );
			camera.addEventListener( "cameraChange" , layer2.cameraChanged );
			
			fillLayer( layer1 );
			fillLayer( layer2 );
			
			layer1.alpha = .3;
						
			addChild( layer1 );
			addChild( layer2 );
			
			addEventListener( Event.ENTER_FRAME, enterFrame );
		}
		// used to move the cam
		private var n:Number = 0;
		private function enterFrame ( e : Event ) : void
		{
			// move the camera and make it loop back to origin
			camera.screen.x = 225 + Math.sin( n ) * 225;
			camera.fireCameraChange();
			
			n += 0.05;
		}
		private function fillLayer ( layer : CameraLayer ) : void
		{
			var l : Number = 100;
			
			while (l--)
			{
				var s : Shape = new Shape();
				s.graphics.beginFill(0);
				s.graphics.drawCircle(0, 0, 5 + Math.random() * 5);
				s.graphics.endFill();
				
				s.x = Math.random() * 1100;
				s.y = Math.random() * 200;
				
				layer.addChild( s );
			}
		}
	}
}

As you can see, the layer1 object is moving two times slower than the layer2 :

It seems that you haven't a Flash Player installed, go [here|http://get.adobe.com/fr/flashplayer/|fr] to get the latest version.

A bit of refactoring

It's to clean up things and improve the usability of the Camera class.

The first things I'll do is to create a custom event class, named CameraEvent, which store the camera's events names and provide some shortcuts to camera's properties. I create the event first in that way I can made all the Camera and CameraLayer refactoring in a single step.

package
{
	public class CameraEvent extends Event
	{
		static public const CAMERA_CHANGE : String = "cameraChange";
		
		public var camera : Camera;
	
		public function CameraEvent ( type : String, 
									  camera : Camera, 
									  bubbles : Boolean = false, 
									  cancelable : Boolean = false )
		{
			super( type, bubbles, cancelable );
			this.camera = camera;
		}
		public function get screen () : Rectangle { return camera.screen; }
	}
}

Now let's start Camera refactoring. Below the list of changes operated :

Dispatch a CameraEvent instead.
Created some accessors on the Camera class to access screen's properties.
Added a addCameraChangeListener andremoveCameraChangeListener functions which register or unregister the passed-in closure for listening to the CameraEvent.CAMERA_CHANGE event.
Added a centerDisplayObject method which center the camera on the passed-in DisplayObject.

I also created an handy silentMode for the camera. The silent mode disable the dispatch of the cameraChange event when modifying a property. Then, in a game routine, you can perform a lot of camera operations before dispatching a unique event to update the whole scene. The check for the silent mode is done in the fireSilentCameraChange method. All setters use that method instead of fireCameraChange.

package
{
	import flash.display.DisplayObject;
	import flash.display.Sprite;
	import flash.events.Event;
	import flash.events.EventDispatcher;
	import flash.geom.Point;
	import flash.geom.Rectangle;
	
	[Event ( name="cameraChange", type="CameraEvent" )]
	public class Camera extends EventDispatcher
	{
		public var silentMode : Boolean;
		
		protected var _screen : Rectangle;
		
		public function Camera ( screen : Rectangle = null, silent : Boolean = false )
		{
			this._screen = screen ? screen : new Rectangle ( 0, 0, 550, 400 );
			silentMode = silent;
		}
		
		/*---------------------------------------------------------------------
		 * ACCESSORS
		 *--------------------------------------------------------------------*/
		
		public function get x () : Number { return _screen.x; }  
		public function set x ( n : Number ) : void
		{ 
			_screen.x = n;
			fireSilentCameraChange ();
		}
		public function get y () : Number { return _screen.y; }  
		public function set y ( n : Number ) : void
		{ 
			_screen.y = n;
			fireSilentCameraChange ();
		}      
		public function get width () : Number { return _screen.width; }  
		public function set width ( n : Number ) : void
		{ 
			_screen.width = n;
			fireSilentCameraChange ();
		}
		public function get height () : Number { return _screen.height; }  
		public function set height ( n : Number ) : void
		{ 
			_screen.height = n;
			fireSilentCameraChange ();
		}    
		public function get center () : Point	
		{ 
			return new Point( _screen.x + _screen.width / 2, 
						  _screen.y + _screen.height / 2 ); 
		}
		public function set center ( p : Point ) : void
		{
			_screen.x = p.x - ( _screen.width / 2 );
			_screen.y = p.y - ( _screen.height / 2 );
			fireSilentCameraChange ();
		}
		public function get centerX () : Number { return center.x; }  
		public function set centerX ( n : Number ) : void
		{ 
			center = new Point( n, center.y );
			fireSilentCameraChange ();
		}
		public function get centerY () : Number { return center.y; }  
		public function set centerY ( n : Number ) : void
		{ 
			center = new Point( center.x, n );
			fireSilentCameraChange ();
		}
		public function get screen () : Rectangle { return _screen.clone(); }
		public function set screen ( screen : Rectangle ) : void
		{
			_screen = screen;
			fireSilentCameraChange ();
		}
		
		/*---------------------------------------------------------------------
		 * PUBLIC MISC
		 *--------------------------------------------------------------------*/
		
		public function centerDisplayObject ( display : DisplayObject ) : void
		{
			var r : Rectangle = display.getBounds( display.parent );
			var x : Number = r.x + r.width / 2;
			var y : Number = r.y + r.height / 2;
			
			center = new Point( x, y );
		}
		public function addCameraChangeListener ( closure : Function ) : void
		{
			addEventListener( CameraEvent.CAMERA_CHANGE, closure );
		} 
		public function removeCameraChangeListener ( closure : Function ) : void
		{
			removeEventListener( CameraEvent.CAMERA_CHANGE, closure );
		}
		public function fireCameraChange () : void
		{
			if( hasEventListener( CameraEvent.CAMERA_CHANGE ) )
				dispatchEvent( new CameraEvent( CameraEvent.CAMERA_CHANGE, this ) ); 
		}
		
		/*---------------------------------------------------------------------
		 * PROTECTED MEMBERS
		 *--------------------------------------------------------------------*/
		
		protected function fireSilentCameraChange () : void
		{
			if( !silentMode )
				fireCameraChange();
		}
	}
}

And now, it's the CameraLayer turn. There's just two changes :

The cameraChange method take a CameraEvent instance as argument. The layer placement is done using the event shortcuts.
I added a getLocalCameraScreen method which return a Rectangle instance corresponding to the camera screen in the layer coordinates system.

package
{
	import flash.geom.Rectangle;

	public class CameraLayer extends Sprite
	{
		public var parallax : Number;
		  
		public function CameraLayer ( parallax : Number = 1 )
		{
			this.parallax = parallax;
		}
		     
		public function cameraChanged ( e : CameraEvent ) : void
		{
			// use the parallax to multiply the screen coords
			x = -e.screen.x * parallax;
			y = -e.screen.y * parallax;
		}
		
		public function getLocalCameraScreen ( c : Camera ) : Rectangle
		{
			return new Rectangle( c.x * parallax,
							 c.y * parallax, 
							 c.width, 
							 c.height);
		}
	}
}

As conclusion, below the last version of the demo code.

Drag the stage to move the camera.

It seems that you haven't a Flash Player installed, go [here|http://get.adobe.com/fr/flashplayer/|fr] to get the latest version.

And the code of the demo :

package  
{
	import flash.display.Shape;
	import flash.display.Sprite;
	import flash.events.Event;
	import flash.events.MouseEvent;
	import flash.geom.Rectangle;	

	[SWF(width="550", height="200")]
	public class CameraTut2 extends Sprite 
	{
		private var camera : Camera;
		private var layer1 : CameraLayer;

		private var layer2 : CameraLayer;	

		public function CameraTut2 ()
		{
			camera = new Camera( new Rectangle( 0, 0, 550, 200 ) );
			layer1 = new CameraLayer(.5);

			layer2 = new CameraLayer();
			
			camera.addEventListener( "cameraChange" , layer1.cameraChanged );

			camera.addEventListener( "cameraChange" , layer2.cameraChanged );
			layer1.alpha = .3;
			
			fillLayer( layer1 );
			fillLayer( layer2 );
						
			addChild( layer1 );

			addChild( layer2 );
			
			addEventListener( Event.ENTER_FRAME, enterFrame );

			stage.addEventListener( MouseEvent.MOUSE_DOWN, mouseDown );

			stage.addEventListener( MouseEvent.MOUSE_UP, mouseUp );

		}

		// used to move the cam
		private var lastXMouse : Number;

		private var lastYMouse : Number;
		private var down : Boolean;

		public function mouseDown ( e : MouseEvent ) : void
		{
			lastXMouse = mouseX;

			lastYMouse = mouseY;
			down = true;

		}

		public function mouseUp ( e : MouseEvent ) : void
		{
			down = false;
		}
		private function enterFrame ( e : Event ) : void
		{
			if( down )
			{
				// move the camera and make it loop back to origin
				camera.centerX -= mouseX - lastXMouse;

				camera.centerY -= mouseY - lastYMouse;
				camera.fireCameraChange();
				
				lastXMouse = mouseX;
				lastYMouse = mouseY;
			}
		}
		private function fillLayer ( layer : CameraLayer ) : void
		{
			var l : Number = 100;
			
			while (l--)
			{
				var s : Shape = new Shape();
				s.graphics.beginFill(0);
				s.graphics.drawCircle(0, 0, 5 + Math.random() * 5);
				s.graphics.endFill();
				
				s.x = Math.random() * 1100;
				s.y = Math.random() * 200;
				
				layer.addChild( s );
			}
		}
	}
}

That's all for today, the next parts will talk about adding zoom and then rotation to the camera. Next parts will come soon :).

Notes

[1] If you don't know what parallax is, just take a look here

Templates FDT3 pour LowRA

Cédric — Mon, 11 Feb 2008 14:05:00 +0100

Pour ceux qui utilise FDT3 voici un petit fichier avec des templates pour Lowra.

Le fichier est donc disponible dans les pièces jointes du billet.

Au programme :

Commande
Commande Asynchrone
Classe de debug
Model
Vue
Vue avec DisplayObjectContainer
Plugin
Liste d'évènements

La face cachée d'ASDoc

Cédric — Sat, 09 Feb 2008 20:26:00 +0100

Encore un billet très technique, en attendant de nouvelles images prochainement.

Suite à de nombreuses questions concernant ASDoc, et sur comment résoudre les nombreux problèmes qui se pose lors de son utilisation, je vais tenter de débroussailler un peu la bête.

Pour rappel, ASDoc est un outil fournit par Adobe, et qui permet de générer la documentation d'une API à partir de son code source.

Sommaire

Introduction

L'arrivée d'un outil comme ASDoc dans le Flex SDK est une bonne nouvelle. ASDoc est un bon outil, il fournit la plupart des fonctionnalités que l'on attend de ce genre d'outil. Cependant, il n'est pas réellement soutenu par Adobe, ou plutôt Adobe n'a pas prévu de le faire évoluer ni de résoudre les problèmes déjà rapporté par les utilisateurs. En conséquence, en attendant une hypothétique ouverture des sources, il faut faire avec et trouver les moyens de contourner les problèmes rencontrés.

Exclure les dépendances de la documentation

Le premier problème rencontré par la plupart des gens concerne la possibilité d'exclure les dépendances de la compilation. Plus concrètement, si je décide de générer la documentation de Kairos, étant donné que de nombreux objets utilisent des classes ou des interfaces provenant de LowRA, toutes ces dépendances seront elles aussi documentées par ASDoc si je les défini avec l'argument -source-path. Pour pouvoir exclure ces classes de la documentation, il faut utiliser la version pré-compilée de LowRA, et donc le fichier *.swc et l'argument -library-path.

Bien écrire la documentation dans son code

Pour moi, la référence la plus importante pour bien rédiger de la documentation est l'article de Sun How to Write Doc Comments for the Javadoc Tool. Il contient à peu près tout ce qu'il faut pour écrire de la bonne documentation, il suffit de voir le résultat dans la documentation de l'API Java pour s'en rendre compte.

Différences avec l'outil JavaDoc

Même si ASDoc, comme de nombreux autres outils, s'inspire des spécifications de Javadoc, il y a des différences entre les 2 outils assez importantes à connaître (outre celles liées aux fonctionnalités du langage) :

Les balises <p> doivent être systématiquement fermées dans ASDoc, alors que Javadoc se chargera de les fermer pour vous. Si vous ne respectez pas cette règle vous risquez d'avoir des surprises dans la mise en page de la documentation.
Les balises {@code ...} et {@link ...} ne sont pas supporté par ASDoc, vous devrez donc utiliser respectivement les balises <code> et <a> en remplacement.
Les paramètres d'une fonction sont optionnels dans une balise @see pointant vers une fonction.
ASDoc ne supporte pas les fichiers de description de package, ni l'inclusion automatique d'exemples compilés dans la documentation.

La balise @param

La balise @param à un comportement un peu particulier dans sa gestion des espaces, il considère que la séquence entre le 1er espace et le 2ème espace est le nom de l'argument. Donc si l'on souhaite respecter les directives de Sun pour rendre les commentaires contenant la documentation plus lisibles, comme indenter tout les contenus de balises, il faut bien prendre garde aux espaces supplémentaires.

/**
 * Un exemple de documentation
 *
 * @param 	param1	description param1
 * @param 	param2	description param2
 * @return	description du retour
 * @example	un exemple d'utilisation
 */
function foo ( param1 : String, param2 : Number = 0 ) ; Boolean;

L'exemple précédent ne donnera pas une documentation propre, puisque les balises @param sont suivi d'un espace puis d'une tabulation (sélectionnez le texte pour vous en rendre compte), le nom du paramètre sera donc ajouter au début de la description de celui-ci. Pour que le paramètre n'apparaisse pas dans la description il faut supprimer le 1er espace. Comme dans l'exemple ci-dessous :

/**
 * Un exemple de documentation
 *
 * @param	param1	description param1
 * @param	param2	description param2
 * @return	description du retour
 * @example	un exemple d'utilisation
 */
function foo ( param1 : String, param2 : Number = 0 ) ; Boolean;

Pour s'assurer qu'aucune balise @param ne contient d'espaces inutiles, vous pouvez utiliser l'expression rationnelle suivante pour effectuer un remplacement (si votre IDE supporte les recherches avec des expressions rationelles)

Rechercher :

@param[\s]+([^\s]+)

Remplacer :

@param	$1

Cette expression recherche toute les balises @param suivi d'au minium un espace et les remplace par des balises @param suivi d'une tabulation (ou d'un espace si vous préférez)

La balise @throws

La balise @throws est vraiment la plus capricieuse de toutes. Elle se présente sous cette forme :

@throws claspath.Error Description de l'erreur

Seulement il y a un petit hic, si la classe de l'erreur n'est pas directement déclarée dans le répertoire qui est documentée, par exemple si c'est une classe d'erreur fournit dans le core du SDK, ou dans une autre librarie dont votre code est dépendant. Non seulement il n'y aura pas de lien vers la classe de l'erreur, mais le nom de l'erreur sera complètement occulté. Comme pour la balise @param ce sont les espaces qui conditionnent le traitement par ASDoc. Pour faire donc systématiquement apparaître le nom de l'erreur dans la documentation finale, il ne faudra pas compter avec la syntaxe normale de la balise. Comme dans l'exemple suivant :

/**
 * Un exemple de documentation
 *
 * @param	param1	description param1
 * @param	param2	description param2
 * @return	description du retour
 * @throws	TypeError Le type de l'erreur ne sera pas visible
 * 		dans la documentation finale puisque TypeError existe
 * 		seulement dans les *.swc de Flex
 */
function foo ( param1 : String, param2 : Number = 0 ) ; Boolean;

J'ai donc pris l'habitude de rédiger la documentation d'une exception ainsi (là encore sélectionnez le texte pour voir l'espace supplémentaire après la balise @throws), et donc de ne plus utiliser la syntaxe normale de cette balise :

/**
 * Un exemple de documentation
 *
 * @param	param1	description param1
 * @param	param2	description param2
 * @return	description du retour
 * @throws 	TypeError - Le type de l'erreur sera visible
 * 		dans la documentation finale mais au sein
 * 		de la description de l'erreur
 */
function foo ( param1 : String, param2 : Number = 0 ) ; Boolean;

Là encore une petite expression rationnelle permet de s'assurer que toutes les balises @throws sont correctement formées pour faire apparaître le type de l'erreur dans la documentation finale.

Rechercher :

@throws[\s]+([^\s]+)

Remplacer :

@throws 	<code>$1</code> —

Problèmes connus

Une petite liste de problèmes rencontrés avec l'outil ASDoc

Il ne faut pas utiliser les balises <code></code> dans une balise @see, sinon cela provoquera un crash de ASDoc.
Il ne faut pas utiliser de doubles quotes (") dans une balise @see, sinon cela provoquera un crash de ASDoc.
Les caractères spéciaux dans les options -footer, -title, -window-title, -main-title et -package (en gros toutes les options permettant de rajouter du texte quelque part) doivent être écris sous leur forme HTML.

Expressions Rationelles utiles

Une petites série d'expressions rationnelles bien utile pour convertir de la documentation d'un système vers un autre :

Remplacement des balises <code></code> en AS2, qui définissent les exemples, par des balises <listing></listing> qui sont les blocs d'exemples en AS3.

Rechercher :

<code>([^<]*)</code>

Remplacer :

<listing>$1</listing>

Remplacement des balises {@code ...} qui ne sont pas supporté par ASDoc, remplacé par des balises <code></code>.

Rechercher :

\{@code ([a-zA-Z0-9.,:#()\s]*)\}

Remplacer :

<code>$1</code>

Remplacement des balises <tt></tt> par des balises <code></code>.

Rechercher :

<tt>([^<]*)</tt>

Remplacer :

<code>$1</code>

Remplacement des balises {@link ...} qui ne sont pas supporté par ASDoc, remplacé par des balises <code></code>.

Rechercher :

\{@link ([a-zA-Z0-9.,:#()\s]*)\}

Remplacer :

<code>$1</code>

Remplacement des balises <code></code> par des tags {@code ...}.

Rechercher :

<code>([^<]*)</code>

Remplacer :

\{@code $1\}

Remplacement des balises <listing></listing> par des balises <code></code>.

Rechercher :

<listing>([^<]*)</listing>

Remplacer :

<code>$1</code>

abe.blog() - Tag - flash

Ludum Dare 20 - Rainbow Riding HoodZ

PLAY THE GAME

GPP : Preprocessing and FDT

First problem

Second problem

Third problem

Conclusion

Using PixelBender on Linux with Wine and PBDT

Wine and Winetricks

Installing Pixel Bender

PDBT

La bonne blague de Flash

Teasing

Camera & Layers - Part 3 - Rotation

Rotation

Last words

Complete code

Camera & Layers - Part 2 - Zoom

Zoom

Special cases

Zoom & Parallax at the same time

Zoom & BitBlit-based renderer

Complete Camera class

Complete CameraEvent class

Complete CameraLayer class

Camera & Layers - Part 1 - Scrolling and Parallax

Camera Basis

Parallax

A bit of refactoring

Notes

Templates FDT3 pour LowRA

La face cachée d'ASDoc

Sommaire

Introduction

Exclure les dépendances de la documentation

Bien écrire la documentation dans son code

Différences avec l'outil JavaDoc

La balise @param

La balise @throws

Problèmes connus

Expressions Rationelles utiles

Complete `Camera` class

Complete `CameraEvent` class

Complete `CameraLayer` class