This is a little algorithm I sketched in my moleskin on the train and for once had the free time to build. The idea is to split a convex polygon between two line segments, creating two new polygons. Each shape is pushed into a queue ready to be subdivided itself. Despite the simplicity of the algorithm, the results are quite nice and with certain configurations often far removed from what I would have expected – surprise is always good.

The Subdivide Algorithm

Here are the basic steps used to create the sketch above:

• Create the first polygon
• Pick two adjacent vertices at random
• Use linear interpolation to find a point between them (P1)
• You now have a point on one line segment connecting the two vertices
• Choose another line segment from the polygon
• Find a point along this line segment (P2)
• Build a new polygon by moving clockwise from P1 to P2
• Build a second polygon by moving clockwise from P2 back to P1
• Splice the original polygon from the list and insert the two new ones
• Choose a polygon from the list and (↑repeat)

Very simple, but you can start to have fun with each of these steps to produce different results. Here are some of the variations which can be created with the demo.

• Choose line segments to cut at random
• Always subdivide between the two longest line segments
• Always interpolate (choose points) half way along segments
• Choose points at random positions along line segments
• Only mark some polygons eligible for subdivision
• Vary the minimum area of divisible polygons

Source Code

The Polygon class is a DisplayObject (it extends Sprite) and implements it’s own draw method. I’ve had a lot of fun filling the shapes with textures, but kept it minimal for the example. One technique which I found worked well was to choose two vertices and compute the angle between them. From this I created a transformation matrix to use with Graphics.beginBitmapFill, giving the sketch a more 3 dimensional feel as if the collection of polygons was a 3D mesh with textures mapped to it. I’ll put these examples on Flickr soon.

If you’re interested in the source code, it’s available in my code repository or you can download the archive below (for the demo GUI, I am using minimal comps courtesy of Keith Peters and for image encoding, Ian McLean’s asynchronous JPEG encoder – thanks guys :).

Related posts:

1. 2D Cellular Automata
2. AS3 Webcam Motion Tracking
3. AS3 Shuffle Grid Class

If you are building a multilingual application (or any application that requires dynamic, runtime loaded assets), swapping and managing assets can easily become tedious and messy.

Recently, for projects requiring special characters (such as Chinese, Arabic, Japanese and Hindi) and where dynamic or input text is not required, we have been creating library SWFs for each language and using static textfields to populate content. This saves file size, as unnecessary characters are not embedded, and it eases the process of including different character sets (and even fonts) for each language. It also means that we can include text in the same runtime loaded library as general display assets.

Introducing DynamicSprite

Using this process, a language specific library SWF is loaded at startup, or at runtime when the users selects a language, and once complete all dynamic assets are updated accordingly. This can get very messy for two reasons. Firstly, it means that each individual asset has to be destroyed and tidied up to release memory before it is replaced. Secondly, if you have a complex application architecture, you will end up dispatching a ton of events and implementing countless methods within every view or component, in order to rollout the update to each desired DisplayObject.

This is where DynamicSprite comes in handy. Using DynamicSprite you can effortlessly update any amount of DisplayObjects from any amount of library SWFs at runtime, whilst keeping the SWF loading logic centralised in your proxy or loader class. No events, no asset update APIs in your views and no cleaning up after yourself.

Bored? Skip straight to the examples and download

How It Works

The concept is very simple. Each instance of DynamicSprite is registered globally at a class level, you need only call a static update method once and all DynamicSprite instances will update themselves automatically. Each instance of DynamicSprite is given a class definition, which can be set or changed at runtime if desired. When a new library is loaded, it will look inside the SWFs applicationDomain and if it finds a matching asset, update itself and destroy any existing instances of that asset it might own. You can also create DynamicSprite instances at runtime anytime after an asset library has been loaded – they will check previously loaded libraries for their class definition when created. This works with any display asset, Sprites, MovieClips, Bitmaps (etc) – BitmapDatas are also detected and destroyed during the cleanup process.

Furthermore, you can load any amount of libraries per language, at different times if necessary – DynamicSprites will only update themselves when applicable, making it easy to manage your language specific libraries and even individual libraries per language if you choose to (each type of library has it’s own ID).

A DynamicSprite instance will also dispatch an event (named DynamicSprite.INSTANCE_UPDATED) when it has changed it’s asset. You can listen for this event if you need to respond to new asset dimensions. You can also listen for two events on the class itself (through a static, encapsulated EventDispatcher) which are dispatched when a library is added or updated but before all instances have changed (DynamicSprite.LIBRARY_UPDATE_START) and when all instances have finished updating themselves (if necessary) from the added / updated library SWF (DynamicSprite.LIBRARY_UPDATE_COMPLETE).

Example Implementation 

Here is a simple example of how to use DynamicSprite. Although this example only loads one SWF (the code for the multi SWF example is included in the download), it demonstrates how DynamicSprite can also be useful for single language applications where you still choose to load your assets at runtime.

public function SimpleExample()
{
	// Create a DynamicSprite instance and provide a class definition for it's asset
	var example : DynamicSprite = new DynamicSprite("assets.example.HelloWorld");
	addChild(example);

	// Load a library SWF
	var loader : Loader = new Loader();
	loader.contentLoaderInfo.addEventListener(Event.COMPLETE, onLoadComplete);
	loader.load(new URLRequest("assets_en.swf"));
}

private function onLoadComplete(event : Event) : void
{
	// Call the static update method once to update all DynamicSprites
	DynamicSprite.update("example", LoaderInfo(event.target).content);
}

Another advantage of DynamicSprite is that you need not worry about synchronising loading with the update process. Any existing DynamicSprite instance will be updated if required when a library is loaded, however you can also create new instances after a required library has been loaded (useful for highly dynamic content) and any loaded libraries will be searched for matching assets upon creation. This snippet demonstrates this feature.

public function SimpleExample()
{
	// Load a library SWF
	var loader : Loader = new Loader();
	loader.contentLoaderInfo.addEventListener(Event.COMPLETE, onLoadComplete);
	loader.load(new URLRequest("assets_en.swf"));
}

private function onLoadComplete(event : Event) : void
{
	// Register this library
	DynamicSprite.update("example", LoaderInfo(event.target).content);

	// Creating a DynamicSprite after a library is loaded still works fine
	var example : DynamicSprite = new DynamicSprite("assets.example.HelloWorld");
	addChild(example);
}

Download DynamicSprite

You can download the DynamicSprite class and the demo below. Also check my code repository for updates. If you find any bugs or have any suggestions please leave them in the comments.

Related posts:

1. Double Sided 3D Plane in FP10
2. Flipping you the Boid
3. AS3 Webcam Motion Tracking

The Adobe Swatch Exchange (ASE) is a useful file format for importing colour schemes into applications in the Creative Suite (Photoshop, Illustrator etc).

I’ve been optimising the BitmapData colour palette algorithm (coming shortly in another post) and for the demo thought that it would be nice to give you the option to save the extracted color palette (a feature that people have been requesting in the comments). I added an option for saving a TXT file containing the hexadecimal and RGB colour values, but thought it would be nice to offer the choice of downloading the palette in ASE format so you can quickly incorporate the colour scheme in your artwork or designs, one of the nice features of Kuler.

So the first step was to open up and existing ASE file (created by Photoshop) in a hex editor (I use 0xED which is an excellent and free editor for OS X). Looking at the bytes of the file showed that it was evidently a quite simple format and wouldn’t be difficult to reverse engineer. I also found the ASE file format specification and a PHP implementation over at Colour Lovers, both of which were quite helpful.

This AS3 code will take an Array of colours (adding Vectors to the <pre> tag seems to cause problems, though my local source code does use a Vector of uints) and encode the ByteArray of an ASE file, ready to save using FileReference of FileStream in AIR…

const FILE_SIGNATURE : String = "ASEF";

function encode ( pixels : Array ):ByteArray
{
	var swatch : ByteArray = new ByteArray();
	var ase : ByteArray = new ByteArray();
	var hex:String;
	var pix:uint;

	ase.writeUTFBytes (FILE_SIGNATURE);// header
	ase.writeInt (0x10000);// version
	ase.writeInt (pixels.length * 2);// blocks

	for (var i : int = 0; i < pixels.length; ++i)
	{
		pix = pixels[i];
		swatch.length = 0;

		// start of group

		ase.writeShort (0xC001);
		ase.writeInt (0);
		ase.writeShort (1);

		// swatch name

		hex = pix.toString(16);
		while (hex.length < 6) hex = "0" + hex;

		swatch.writeShort ((hex = "#" + hex).length + 1);
		for (var n : int = 0; n < hex.length; ++n) swatch.writeShort (hex.charCodeAt(n));
		swatch.writeShort (0);

		// colours

		swatch.writeUTFBytes ("RGB ");
		swatch.writeFloat ((pix >> 16 & 0xFF) / 255);
		swatch.writeFloat ((pix >> 8 & 0xFF) / 255);
		swatch.writeFloat ((pix & 0xFF) / 255);
		swatch.writeShort (2);

		// write swatch

		ase.writeInt (swatch.length);
		ase.writeBytes (swatch);
	}

	return ase;
}

I’ll put the full code in my repository along with the improved ColourUtils Class which prompted the ASEEncoder, though for now you can just copy and paste this snippet and play with the demo above to save the top colour schemes from Colour Lovers as ASE files, which you can then import into Adobe Creative Suite applications.

Here is an example of how to encode a palette and then save it to the file system:

var colours : Array = [0xFF0000, 0x00FF00, 0x0000FF];
var aseFile : ByteArray = encode( colours );
var fileRef : FileReference = new FileReference();
fileRef.save( aseFile, "swatch.ase" );

The AS3 ASEEncoder currently only encodes swatches as RGB, though saving CMYK should only be a matter of converting the colour space and then changing the swatch declaration.

Going in the other direction, it would be nice to provide a method to decode existing ASE files into a Vector of uints, something which I’ll look at once the new ColourUtils is online.

Related posts:

1. BitmapData Average Colours
2. BitmapData Colour Palette
3. Smack My Glitch Up

Sometimes it’s good to break things…

During a recent project I needed to find a way of simulating digital interference on an image / video stream. At first, it seemed the best approach might be to use the graphics API or Bitmap effects, but why imitate when you can have the real thing.

The principle is incredibly simple. Corrupt / alter a byte (or several bytes) in the ByteArray of a JPEG and then load this back into a DisplayObject using Loader.loadBytes(). Because of the way in which JPEGs work, the image will still display but the corrupt bytes will mangle the output to varying degrees, depending on how many bytes have been corrupted. The result is an interesting glitch pattern, a bit like those which were accidentally created when my webcam drivers lost the plot.

It is also possible to corrupt other image formats (png, gif etc) in the same way, by first passing the image ByteArray through a JPEGEncoder.

I’ve implemented this technique in the Glitchmap class, which you can download and play with at the bottom of this post. I hope that it will provide a few moments of fun, if not a practical use (I’m thinking image gallery transitions or music visualisations).

The small gottcha is that it isn’t desirable to mess with the JPEG headers, so when the clean ByteArray is passed to the Glitchmap class, it will determine the length of the header by reading through the bytes until it finds the SOS (start of scan) declaration (0xFFDA). The next two bytes represent the length of the SOS, so it skips forward by this amount – the resulting position in the ByteArray should be the end of the header, and so between this point and the EOI (end of image) the data corruption takes place. I’m not sure whether this is the best way of determining the JPEG header size; perhaps any CS graduates / students out there can help me out?

After I posted the webcam glitch images, Jon used them in his title sequences for the 48 hour film gala. If you find a similar creative use for this script or the glitch generator then please let us all know.

I think the next step is to experiment with merging the bytes of multiple glitched images in order to create transition effects. I may also build an AIR app and see what the best way of outputting video might be (using NativeProcess for screen capture perhaps?).

You can also download the Glitchmap Class and the Glitch Generator source code from the soulwire code repository.

Related posts:

1. Webcam Glitch Art
2. ASE (Adobe Swatch Exchange) Encoder
3. Recursive Polygon Subdivision

I’ve been revisiting one of my favourite topics lately – recursion – and have been getting together a bunch of sketches for a big personal project I’m working on (more on that another time). Anyway, I inadvertently stumbled across quite a nice way of making things grow in a convincing manner, and whilst this script doesn’t actually use recursion ‘per se’, I thought it was kind of cool so I ran with it.

It also presented a good opportunity to try out another Flash Player 10 feature that I’ve been eager to try, which is using Pixel Bender and ShaderJob. Although I’ve used Pixel Bender before, I’ve never used it in this way.

Basically, the idea is to exploit Pixel Bender’s performance and ask it to do some of the heavier number crunching for you – a concept that is currently being used by the Papervision3D team to give some juice to the next release. The other great thing about this approach is that these computations can run in another thread, leaving you more resources for other tasks (like rendering a fishing boat load of tentacles)

So, although this isn’t the best example of using Pixel Bender’s capabilities, it was a nice opportunity to exercise the idea. Each Tentacle starts a new ShaderJob and Pixel Bender whips up some tasty trigonometry for me, before passing it back inside a Vector object (typed Array). From there it’s just a question of making those numbers look nice… Kind of reminds me of the illustrative style used for the O’Reilly book covers…

Related posts:

1. Recursive Polygon Subdivision
2. Perlin Noise Flow Field
3. Double Sided 3D Plane in FP10

We’ve all been there. You’re building an image gallery and you need to create consistently sized thumbnails from a set of images, of various sizes and orientations and with differing aspect ratios – or you need a fullscreen background which always fills the stage, regardless of a user’s screen resolution and browser window size – or maybe you just need to fit a DisplayObject into a rectangular area whilst maintaining the correct proportions of the original image.

Introducing DisplayUtils

Since this is a common task, one that I find myself coding over and over, I’ve whipped up a little class called DisplayUtils which will help with the scenarios mentioned above and more.

The main method in DisplayUtils is FitIntoRect. FitIntoRect can work in several ways. You can use it to resize a DisplayObject to fit inside a rectangle, or you can use it to generate a transformation matrix, which can be applied to an object or used with the BitmapData.draw method to create thumbnail previews, or both. There is also another method called createThumb, which uses fitIntoRect to quickly and easily create nicely cropped and scaled thumbnails from a source image with any aspect ratio.

Have a play with the demo above to see what you can do with these methods.

Using DisplayUtils and fitIntoRect

There are several parameters to control how fitIntoRect works. Here’s what you can pass to the method:

• displayObject : The DisplayObject to resize
• rectangle : A Rectangle object representing the space the DisplayObject should fit into.
• fillRect : Whether the DisplayObject should be transformed to fill the entire rectangle, or whether it should fit completely within it.
• align : The alignment of the DisplayObject within the rectangle, for example Top Left or Middle.
• applyTransform : Whether the calculated transformation matrix should be applied to the DisplayObject within the fitIntoRect method. If false, the DisplayObject will not be modified, but the Matrix returned by the fitIntoRect method can be used to transform objects or modify the draw command on a BitmapData object.

The download includes all necessary classes as well as several examples of how to use the fitIntoRect method. Here are some code snippets for getting started with…

Example Usage

Fit a DisplayObject into a Rectangle

var area:Rectangle = new Rectangle( 0, 0, 200, 100 );
DisplayUtils.fitIntoRect( myDisplayObject, area, true, Alignment.MIDDLE );

Create a fullscreen background image

stage.align = StageAlign.TOP_LEFT;
stage.scaleMode = StageScaleMode.NO_SCALE;

function onStageResized( event:Event = null ):void
{
	var area:Rectangle = new Rectangle( 0, 0, stage.stageWidth, stage.stageHeight );
	DisplayUtils.fitIntoRect( myDisplayObject, area, true, Alignment.MIDDLE );
}

stage.addEventListener( Event.RESIZE, onStageResized );
onStageResized();

Create a thumbnail

var thumb:Bitmap = DisplayUtils.createThumb( myBitmap.bitmapData, 100, 100, Alignment.MIDDLE, true );
addChild( thumb );

Download

You can download the DisplayUtils class, as well as the Alignment class, which simply contains enumeration for the various alignment options when using fitIntoRect and createThumb.

A example of some of the uses discussed above is also available in the zip.

Related posts:

1. AS3 Webcam Motion Tracking
2. Double Sided 3D Plane in FP10
3. Flipping you the Boid

I’ve uploaded the Boid source code. Sorry for the delay. I’ve also included some basic examples of how you can create nice behaviors using the Boid class. If you set Main.as as your document class then you’ll see that within that you can specify the demo to run when you compile.

The basic demos included are:

• Chase – Boids chase each other
• Flock – Boids flock together with some wander
• Graphics – How to use custom graphics with a Boid instance
• Seek – Boids seek the mouse position
• Wander – You guessed it, they wander

I’ve commented all of the methods and properties and there is also documentation (open index.html in the docs folder) to get you started. Before you mention it, yes, there is some redundant code ;) (such as the constrainToRect method which doesn’t really work) but I need to do some optimisations anyway so I just left it as is for now, rough and ready.

Download: AS3 Boid Class & Demos

It’s been a little while since I posted! I’m in the process of moving house and office, plus I’ve been repeatedly slammed at work. Apologies to those of you who’ve left comments and haven’t got much by way of reply. I’ll hopefully be visible again over the next few weeks.

I actually coded this experiment back in November, but only recently decided that enough was enough and hijacked an evening so I could tidy up the code and build a UI for the demo.

Since coming across Craig Reynold’s paper; “Steering Behaviors for Autonomous Characters” whilst I was researching complexity theory for a university project (it wasn’t as academic as it sounds!), I’ve found myself becoming fascinated by flocking and swarm beahviors and the notion that you can create complex systems from relatively simple components. Much like the Cellular Automata, you can program an agent to have only a limited set of abilities and awareness, define a set rules for it to follow, and then create a multitude of instances of the agent to see what patterns begin to emerge through their interactions.

Flocking is a great example of this, as Reynolds demonstrated. His agents, or “Boids”, could perform certain maneuvers, such as seeking a target, fleeing from a predator, avoiding obstacles or wandering randomly. Combine these behaviors though, and allow each Boid to consider it’s neighbors when deciding on its locomotion, and complex behaviors begin to emerge.

The most infamous of these combinations is that of separation, cohesion and alignment, as it can produce a swarm behavior reminiscent of flocking birds or shoals of fish.

Separation means that each Boid attempts to maintain a certain distance from its immediate neighbors, Cohesion ensures that each Boid attempts to stay close to the centre of the immediate flock and Alignment will calculate the average heading of the flock and steer towards this vector.

Each of these behaviors is fairly simple in isolation, but the results can give the impression that some significant AI is at work, when all that’s really going on is some simple vector math.

Robert Hodgin has done some amazing work with flocking behaviors, so too has Psyop, and of course Reynolds is the daddy of all this stuff. There are some good libraries out there too, such as OpenSteer, and Keith Peters talks about this too in Advanced Actionscript Animation.

I’ve been trying to sharpen up my mathematical skills lately though, and was eager to play around with the new (new when I created this experiment anyway!) Flash Player 10 API – the 3D aspects in particular. So at the core of the Boid class are the native Vector3D, Matrix3D and PerspectiveProjection classes. Ok, so we’ve all got our own Vector3D and Matrix3D class in our library, but I thought it’d be good to use Adobe’s, especially seeing you can then apply the Matrix3D directly to a DisplayObject’s transform property.

Another cool feature I came across was the Matrix3D.pointAt() method, which will rotate a Matrix around a given axis and in this case can be used to orientate the Boid to it’s heading vector… Nice!

I’ve had a lot of fun putting together the Boid demo anyway – tweaking various settings on the individual Boids as well as the group behaviors (my personal favorite is ‘Chase’ mode with ‘Number of Boids’ cranked right up!).

If you have a play with the settings though, you’ll quickly see what I mean about the plethora of different effects that can be accomplished, even by simply adjusting the locomotive abilities of the Boids.

Due to said lack of free time as of late, I haven’t documented the code fully, though I have started and so if anyone is interested in the source code then please say so in the comments and I’ll try and finish the job (after a mere 6 months!) and put it up for download.

Related posts:

1. Perlin Noise Flow Field
2. AS3 Shuffle Grid Class
3. Double Sided 3D Plane in FP10

Just a quick (and slightly belated) announcement.

The distinguished Bandcamp has recently been regaled with another round of audio-visual snacks. I’ve had a lot of fun working on them, and there will be even more in the not too distant future.

The whole Bandcamp site in fact is bursting with more and more tasty new features which you should check out. In terms of my little contribution on the music visualistions front, there are currently four new full fat flavors to feast on…

Ribbons » which uses my Papervision3D Ribbons Class and is designed for crunching riffs and hard beats.

Strata » which was inspired by stream-graphs and rock formations, and flows like a charred pizza in a log-flume along an imaginary Teflon oven dish.

Plughole » which comprises of disembodied appendages and iconography encapsulating the zeitgeist of generation stupid – mashes the aforementioned archetypes up into crumbs before offering them to the esophagus of oblivion.

Hypno » which was designed to bring about universal harmony and spiritual equilibrium but accidentally caused the credit crunch.

You can see them in action by visiting an artist’s page (such as Hot Bitch Arsenal or Pattern), hitting play and selecting a visualisation from the pop-out menu underneath the cover art.

Related posts:

1. Bandcamp Music Visualisations
2. AS3 Music Visualisation
3. Disabed Algebra

Drag & Drop the images to shuffle them around…

A friend of mine, Dale Sattler over at No Ponies recently posted a grid sorting class. He said it was based on my old dynamic stacking menu; but that was pure modesty as his script is based on a 2D grid and much more sophisticated.

Anyway – it inspired me to create a grid sorting / shuffling algorithm of my own. It behaves differently to Dales but I think it works pretty well.

The basic logic of the algorithm works by determining how far a dragged item travels along the grid (rows and columns) and then shuffling the surrounding items in the opposite direction by these values, therefore creating space for the dragged item to slot into when released.

It currently only works for grids which are fully populated, but adding more flexibility for incomplete grids will only be a matter of adding a few conditions – functionality which I’ll add when I get a moment.

You can extend the ShuffleGridItem class to add the functionality you need. In the demo I’ve made a simple image class which grabs a photo from Flickr.

Creating a ShuffleGrid is very simple, and can be done like so:

var grid:ShuffleGrid = new ShuffleGrid(4,7,40,40,1);

for (var i : int = 0; i < grid.numCells; i++)
{
	grid.addItem (new ShuffleGridItem());
}

addChild (grid);

The constructor takes the following arguments:

new ShuffleGrid(rows, cols, cellWidth, cellHeight, spacing);

Feel free to download the class and a simple demo and have a play around. I can imagine many uses for it, so hopefully it will come in handy.

Related posts:

1. AS3 Webcam Motion Tracking
2. 2D Cellular Automata
3. Double Sided 3D Plane in FP10

I’ve made a couple of small improvements to the PaperSprite class:

1. The visible face of the plane is updated automatically only when required. This saves on processing load and also means you can just set up the PaperSprite and not have to worry about anything else, just tween the crap out of all its properties and it won’t mind one bit. (Thanks to Jesse for the pointers re. using stage.invalidate for this process)
2. The back face is now automatically flipped horizontally, so text and graphics are no longer mirrored and will display correctly
3. I’ve changed the logic which sets the dynamic registration point for the pivot. This should now correctly line up the front and back faces of the 3D plane, regardless of where their individual registration points are.

Also, some people have asked how to use it, so here is a really quick example to get you up and running with PaperSprite if you are not familiar with using classes and are using the Flash IDE to compile your movie:

1. First, download the PaperSprite class and put the soulwire folder in the same directory as your FLA or source code.
2. Then paste this code into the main timeline of your FLA:

// Import the PaperSprite class

import soulwire.display.PaperSprite;

/*
Create a new PaperSprite:

If your front and back faces already exist, you can pass them straight
into the constructor, like so:

myPaperSprite = new PaperSprite( myFrontMc, myBackMc );
*/

var myPaperSprite:PaperSprite = new PaperSprite();

/*
Optionally specify a pivot point, in this example the centre is used
(this is also the default so there is no need to set this normally).

To pivot around the top left use:
myPaperSprite.pivot = new Point(0,0);

or for bottom right:
myPaperSprite.pivot = new Point(1,1);

and so on...
*/

myPaperSprite.pivot = new Point(0.5,0.5);

// Centre it on the stage

myPaperSprite.x = stage.stageWidth / 2;
myPaperSprite.y = stage.stageHeight / 2;

/*
Set the front and back faces:

These can be any type of DisplayObject, for example, to use a MovieClip
from your library use:

myPaperSprite.front = new MyLibraryClip();
*/

myPaperSprite.front = createSprite(0x66FF00);
myPaperSprite.back = createSprite(0xFF3399);

// Add the PaperSprite to the display list

addChild ( myPaperSprite );

// This method just creates coloured boxes for the demo

function createSprite (colour:uint):Sprite
{
	var mySprite:Sprite = new Sprite();
	mySprite.graphics.beginFill ( colour );
	mySprite.graphics.drawRect (0,0,100,100);
	mySprite.graphics.endFill ();
	return mySprite;
}

// Listen for the enterFrame event

addEventListener ( Event.ENTER_FRAME, spin );

/*
Move and rotate your PaperSprite in any way you want - it will
update it's visible face automatically!
*/

function spin ( event:Event ):void
{
	var mX:Number = ((mouseX / stage.stageWidth) - 0.5) * 360;
	var mY:Number = ((mouseY / stage.stageHeight) - 0.5) * 360;

	myPaperSprite.rotationY += (mX - myPaperSprite.rotationY) / 40;
	myPaperSprite.rotationX += (mY - myPaperSprite.rotationX) / 40;
}

Publish the movie and you’re all done!

Background

Flash Player 10’s new 3D capabilities are a much welcomed and exiting addition, and although their implementation at first seemed a little obtuse after using libraries such as Papervision3D, Adobe’s implementation is beginning to make a lot more sense to me. Rather than being handed a complete 3D library, developer’s have been given the necessary building blocks to use 3D, or 2.5D with less ‘hacks’ and arguably better performance where it matters.

Time will tell, but I personally think this will be a positive development for existing frameworks like Papervision and Sandy, because whilst Flash can now natively handle certain tasks like triangle drawing, 3D matrices etc – implementing cameras and shaders, loading and building meshes and so on is something which developers will still require. If this can plug neatly into Flash Player’s capabilities and possibly yield increased performance then all the better.

In more basic situations though, the ability to rotate a DisplayObject around its X, Y and Z axis, as well as finally having a Z property, is useful for adding basic 3D effects, even if your project doesn’t require anything more sophisticated than that.

But this is where some gaps begin to arise. Z sorting, for example, will be required, and Ralph Hauwert (a member of the Papervision3D team) has already written a useful script for this.

Two Sided DisplayObjects

Another common use for Flash Player 10’s 3D capabilities is to create double sided sprites or planes, than can be rotated to reveal alternate content on either side. Again, I would have expected this to be a new property of DisplayObjectContainer, so that front and back could be passed to it as DisplayObjects. This isn’t the case though, so it requires some minimal work around.

Lee Brimelow demonstrated one approach to this, which was to monitor the rotation of a DisplayObject, and swap the visible faces accordingly (Jesse Freeman also used this technique). This works great in many cases, however it doesn’t give the desired results when the parent DisplayObject is off centre and therefore subject to the perspective of the 3D environment. It also means that if you are rotating the DisplayObject around multiple axis then the calculations required get slightly more complex.

The Solution

As ever, the wise and prolific Senocular came to the rescue. He described a technique whereby 3 points are placed on the surface of the DisplayObject, and by determining the winding direction of these points when translated from 3D to 2D space; one is able to determine which way the DisplayObject is facing. Because this is relative to the perspective used to produce this transformation, the result is true to the point of view of the user.

Senocular published his helper class which will return a Boolean value indicating whether a given DisplayObject is front facing or not, and so I wish to stress that all credit is his for his solution and wonderfully clear explanation of the process.

I did feel that it might be beneficial though to wrap this up, along with other functionality, into a class which solved the double sided DisplayObject issue, and so I introduce the PaperSprite class (I chose to call it PaperSprite so that it isn’t confused with Sprite3D if you use another 3D library).

How to use PaperSprite

Creating a two sided Plane using PaperSprite is simple:

import soulwire.display.PaperSprite;

var mySprite:PaperSprite = new PaperSprite();

// Any type of DisplayObject can be used for each face
mySprite.front = new Sprite();
mySprite.back = new Bitmap( myImage );

So you can use any DisplayObject for the front and reverse sides; MovieClips, Sprites, Bitmaps, Shapes, Loaders etc. These can also be set via the constructor…

Another property of PaperSprite is whether is updates it’s display automatically. If true, once the PaperSprite is added to the stage it will update its visible face autonomously, however if you have a more general render loop where you’re controlling your 3D scene from, you can set this to false and then call the update method when calculating the visible face is required:

Thanks to Jesse Freeman for suggesting a method to limit unnecessary calls to the update method. By overriding the setters for the position and rotation properties and using stage.invalidate(), then listening for the render event (Event.RENDER), the calculations needed to determine the visible face of the PaperSprite need only be made if one or more properties have been changed and if the PaperSprite needs to be rendered. Therefore there is no longer a need for autoUpdate, everything is handled internally by the PaperSprite class. Cheers Jesse! :)

…The other useful feature is the pivot property. By default, a PaperSprite will pivot (rotate around) its centre point, which will be automatically calculated for each face depending on its respective dimensions. Alternatively, if you want the PaperSprite to rotate around the top left corner, bottom right, or indeed any point on its surface, you can set the pivot property, which is a Point object and requires 2 normalised values, representing the fraction of the width and height of the PaperSprite at which you want to place the pivot.

So to set the PaperSprite to rotate around its centre (this is set by default) you can use:

mySprite.pivot = new Point( 0.5, 0.5 );

And its Top Left corner:

mySprite.pivot = new Point( 0.0, 0.0 );

And its top centre:

mySprite.pivot = new Point( 0.5, 0.0 );

And so on!

You can also access its isFrontFacing property at any time:

if ( mySprite.isFrontFacing )
{
	doSomethingGood();
}

An finally, removing the front or back face from its display list (or indeed not defining one at all) will cause the PaperSprite to display the available face at all times, essentially giving it the default behaviour of a one sided Sprite.

Download the PaperSprite class

Again, this is really just a glorified augmentation of Senocular’s solution to finding the front facing side of a DisplayObject in 3D. All credit should go to him for creating such an elegant solution. I built this class in order to simplify its use and provide the extra functionality needed to quickly start working with a two-sided DisplayObject.

Related posts:

1. Fit DisplayObject into Rectangle
2. Flipping you the Boid
3. Hello Dynamic Sprite