Update: Here’s my quick prototype (before skinning)

Interfaces are amazing things. When I was young and green, I didn’t understand their purpose, but after working with them for a while, I will defend their use to the end. I try to create lots of interfaces early on in my projects and I find that by keeping things flexible, it saves more time despite the extra typing, pardon the double entendre.

But this is not an article about why interfaces are so great. No, this is an article about the mysterious gap in the Flash Player API with regards to an interface for DisplayObjects. If you have a class typed as something like IView, there’s no way to enure that IView can be a parameter of display list functions like addChild().

Why can’t we guarantee that something is a DisplayObject through interfaces? There is a practical answer. The inner workings of the Flash Player are slowing unfolding to us with each version. We now have low level access to sound, byte streams, and text rendering. However, the display list still relies exclusively on one of the only truly abstract classes in ActionScript 3.0, the DisplayObject. Because a low-level drawing engine is not exposed to AS3 programmers, we don’t know how it works and we cannot guarantee through an interface that an arbitrary class can be drawn.

Fortunately, there are some workarounds that can help, each with their own strengths and weaknesses. Personally, I think #2 is the way to go. It’s practically dripping with polymorphic goodness.

1. Make your interface inherit from IBitmapDrawable and IEventDispatcher

   DisplayObject is the only class that uses both of these two interfaces so by combining them in your interface, you can sort of be sure you’re working with a DisplayObject. Still, this is my least favorite solution

   Pros:

   • Uses interfaces exclusively.
   • Only a DisplayObject would implement both of these.

   Cons:

   • There’s nothing to stop you from using this to create a class that isn’t a DisplayObject and that could cause problems.
   • You would still have to type cast to DisplayObject to use this as an argument for addChild().

2. Create an interface that exposes a method to return the object as a DisplayObject

   My personal favorite solution. It not only solves the problem of guaranteeing that a class can go in the display list, it doesn’t even require that the class be a DisplayObject.

   Here’s an example of what this would look like. IDisplayObject.as

   Pros:

   • Flexible solution that conforms to good OOD principles.
   • Uses interfaces exclusively.
   • Easy to apply. You can usually implement it with a single line of code: return this;

   Cons:

   • Requires you to use asDisplayObject() every time you want to use the object as a DisplayObject.
   • Calling foo.asDisplayObject() would throw an exception if foo was null so additional checks may be necessary.

3. Use an abstract class that inherits from DisplayObject

   Not an ideal solution primarily because Flash doesn’t have true abstract classes (although there are workarounds) but still totally valid.

   Pros:

   • Guarantees that the object is a DisplayObject. No type casting required.
   • Abstract classes can be treated virtually the same as an interface for practical use.

   Cons:

   • No true abstract classes in Flash.
   • Not as flexible as an interface-based solution since it forces you to inherit from DisplayObject.

I’m doing a little exercise in a book that makes a textfield in which each letter can only be entered once. Not very useful, more of a teaching thing really. However there’s a bit of code that says:

var tf:TextField = event.target as TextField;

I don’t understand this at all! What the hell is event.target as TextField? Anyway here’s the full code for context’s sake:

package com.FoundationAS3.ch6 {

	import flash.display.Sprite;
	import flash.text.TextField;
	import flash.text.TextFieldType;
	import flash.events.TextEvent;

	public class PreventDefaultTest extends Sprite {

		public function PreventDefaultTest() {
			var tf:TextField = new TextField();
			addChild(tf);

			tf.width = stage.stageWidth;
			tf.height = stage.stageHeight;
			tf.type = TextFieldType.INPUT;
			tf.wordWrap = true;

			tf.addEventListener(TextEvent.TEXT_INPUT, onTextFieldTextInput);
		}

		private function onTextFieldTextInput(event:TextEvent):void {
			var tf:TextField = event.target as TextField;
			if (tf.text.indexOf(event.text) > -1) {
				event.preventDefault();
			}
		}
	}
}

Thanks,
-Neal

My response after the jump.

Neal,

First of all, let me say that preventing the default event handler, e.g. for a TextField, is rarely used and isn’t worth spending a lot of time discussing.

On the other hand, the as operator (along with the is operator and the type cast) are totally useful and you should learn all about them. First, let me cover is:

is

is is an operator that evaluates whether some object is of a certain type. The syntax is [object] is [type]. The term ‘type’ is similar but not interchangeable with ‘class’. A type can refer to not only the class of an object, but also the super-classes it extends and interfaces it implements. An example:

var sprite:Sprite = new Sprite();
trace(sprite is Sprite); // true, because the sprite object is an instance of Sprite
trace(sprite is DisplayObject); // true, Sprite is a subclass of DisplayObject
trace(sprite is MovieClip); // false, MovieClip is a subclass of Sprite.
trace(sprite is IEventDispatcher); // true, DisplayObject extends EventDispatcher which implements IEventDispatcher.

Note that sprite is not a MovieClip but a MovieClip is a Sprite. Because MovieClip extends Sprite and contains all the same methods and properties as Sprite but not the other way around.

Note: the instanceof operator commonly used in AS1/2 still exists in AS3 but is for all practical purposes deprecated by is (although still useful if you’re manipulating prototypes). typeof is also related but shouldn’t be used in place of is because it only returns strings for primitive data types like Object and String. In order to get the actual name of the class that an object is an instance of, you can use the flash.utils.getQualifiedClassName() global function.

as

as functions similarly to is except that it actually will attempt to coerce the object into the data type that you ask for. Coercion, AKA type conversion or casting, is the act of changing the data type of an object.

With the case from your book, an Event object has a target property which refers back to the object that originally dispatched the event. Since the Event object is designed to be sent out from all different types of objects, the target’s data type is Object (the mother of all the other classes). So, if the variable you’re defining is a TextField, you’re expecting an object with a text property. Object, doesn’t have a text property so you have a dilemma. The solution is to cast the object into the type you want it to be, basically forcing it to be more specific.

var textField:TextField = event.target; // Throws compile error because target is an Object not a TextField

var textField:TextField = event.target as TextField; // OK! as long as the event target actually is a text field

Going from a more generic type to a more specific type is called a downcast. Going from a more specific type to a more generic type is called an upcast. Upcasting in ActionScript, as with most other languages, is done automatically and is always safe. e.g. a Sprite can be used as a parameter for a function that requires a DisplayObject. Downcasting on the other hand is unsafe meaning that you can’t always guarantee that it will work. A DisplayObject is not necessarily a Sprite.

When an attempt to downcast with as fails, the value returned will be null:

var string:String = new String();
var textField:TextField = string as TextField // string can't be converted. textField will be set to null

If you’re not sure whether your object is the right type (and you should never assume it is) check to see if the value is null before proceeding:

var typedObject:TypedObject = mysteryObject as TypedObject;
if (typedObject != null) {
	// conversion was successful! do something with typedObject
} else {
	// conversion failed
}

Type casts

Another way to do this with slightly different results is by type casting. Type casting works with the syntax Type(object) and is functionally similar to object as Type. The only difference is with a type cast, you get a runtime error if the coercion fails.

var textField:TextField = TextField(event.target); // if event.target is a TextField, you're good. If not, you get an error.


you can also shortcut like this:

TextField(event.target).text = "foo";

Conclusion

Why are objects like event.target given such generic data types? The idea is that you want to minimize the requirements of a property, parameter, or function to maximize the number of objects that will qualify thus making your program more flexible. In other words, strive to use the most broadly defined data types that you can get away with.

For example, say you’re creating a simulator program for getting a person from their home to their job. You may be tempted to define your modeOfTransportation variable with a type of Car. But down the road the company you’re working for wants to create a more green image for themselves and suggests using alternative modes of transportation. If you’re code is based on Car, it’s limited in what you can do with it. However, if you had used a Vehicle type (includes Car, Bike, Motorcycle, Donkey) instead, you may not have had a problem. Using interfaces like IConveyance makes your program even more flexible because you can include non-vehicluar objects like MolecularTransporter, Feet, and CrowdSurfing as long as they satisfy the interface. In fact, I would suggest as an experiment that the next time you start a project, try coding all the interfaces first before you move on to coding specific classes. You’ll be surprised at how flexible it is and how it forces you to consider the roles of your classes from a higher level.

Though you should strive for generic types, sometimes you will need to get specific. If your program has a gas station simulator in it, the fillTankOfVehicle() method might require a MotorVehicle class (includes Car, Motorcycle, Plane) instead of simply Vehicle. Still, you should only get very specific when your program requires it. If you are making a racing program, use F1RaceCar only when a simple Car won’t cut it.

I hope this helps! This is definitely a difficult topic even for experienced programmers to grasp!

This version check is very simple. It checks a version number in the client code against a version number of the library (or external classes) when the main class of the library is initialized. It is also completely optional (so average users don’t need to mark up their code with version numbers).

Here’s an example:

Say you normally initialize your library using:

MyLibrary.initialize();

Which calls the initialize method:

public static function initialize():void {
   // initialize library here
}

If the external code changes unexpectedly (say through an SVN update) this could cause problems that are difficult to trace. The solution is to modify the initializer to match the client code version with the initializer version.

public static const VERSION:String = "1.6";
public static function initialize(versionCheck:String = VERSION):void {
   if (versionCheck != VERSION) {
       throw new Error ("The version check failed! This library is version " + VERSION + ". Update your code or GTFO!");
   }
   // initialize library here
}

And when you run the initializer, use the version number you’re expecting.

MyLibrary.initialize("1.6");

Some things to notice with this approach:

• I used a string instead of a number for the version number so that it would allow for sub-sub version numbers and other markers, e.g. “1.6.24 beta r545″
• Because there is a default value for versionCheck in the initializer, providing a version number is optional. Using MyLibrary.initialize() will still work and throw no errors.
• Unfortunately, there is not much you can do if the version numbers don’t match except to warn the client that the external code has changed. Still, I’ve found this to be very useful.

The code for my initializer in its entirety after the jump…

From KitchenSync.as

/**
* The current version of the library. Use this to verify that the library is the
* version that your software expects.
*/
public static const VERSION:String = "1.6";

/**
* Flag noting whether the engine has been initialized.
*/
private static var _initialized:Boolean = false;

/**
* Initializes the timing core for KitchenSync. Must be called before using any actions.
*
* @param frameRateSeed must be a DisplayObject that is added to the display list.
* @param versionCheck a string for the version you think you're using. e.g. 1.2 This is recommended
*                                         but not required. It will throw an error if you're using the wrong version of KS.
*/
public static function initialize(frameRateSeed:DisplayObject, versionCheck:String = VERSION):void
{       

	if (_initialized) {
		throw new IllegalOperationError("KitchenSync has already been initialized.");
	}
	if (versionCheck != VERSION) {
		throw new Error ("Version check failed. Please update to the correct version or to continue using this version (at your own risk) put the initialize() method inside a try{} block.");
	}

	// Initialization code omitted

	_initialized = true;
}

Animation
Animation in Papervision3D can be performed the exact same way animation would be performed in 2D. Simply apply any tween or algorithm to an object property (like x, y, rotationX, scaleY, etc) and re-render the scene. But, for imported animations its not quite that simple. Lately Moses’s GoASAP package is being adopted in testing for the Papervision engine. It could soon become adopted by the system.

The Collada DAE Parser
Imported animations come in plenty of flavors but must conform to the same system. That’s the reason the animations package exists. Papervision has long supported externally created 3D assets. You’ll find those file parsers in pv3d.objects.parsers. Although, these importers are nice to have, a big part of Great White was the introduction of the open source project ASCollada. ASCollada is an amazing parser for the standard 3D asset interchange format known as Collada. Collada files are basically very dense XML files that use a .dae file extension. Collada files can be exported from Maya, 3D Studio Max, Blender, Google Sketchup, and XSI. However, level of support for those programs probably follows this order: 3D Studio Max, Maya, Blender, Google Sketchup, XSI. Also, if you’re importing MD2 models, the MD2 file parser will import most animations as well.

You can try it out using the DAE class like so:

import org.papervision3d.events.FileLoadEvent;
import org.papervision3d.objects.parsers.DAE;
daeScene = new DAE();
daeScene.addEventListener(FileLoadEvent.LOAD_COMPLETE, onSceneGeometryLoaded);
daeScene.addEventListener(FileLoadEvent.ANIMATIONS_COMPLETE, onSceneAnimationsLoaded);
daeScene.load("your_scene.dae");
var animChannel:AbstractChannel3D = daeScene.getAnimationChannels()[0];
var frame:uint = 20;
var animObject:DisplayObject3D = animChannel.defaultTarget;
animChannel.updateToFrame(frame, animObject);

Render Statistics
Papervision records all the primary rendering tasks. If you want to monitor rendering statistics, you can have them captured when you execute the BasicRenderEngine instance method “renderScene().” When traced, a typical render report will appear like this:

ProjectionTime:0 RenderTime:1 Particles:0 CulledParticles:0 Triangles:38 ShadedTriangles:0 CulledTriangles:82 FilteredObjects:0 CulledObjects:0

You can use this information to determine how well your scene is rendering. And it could give you ideas on how you can improve rendering by adjusting camera settings, culling plans, and clipping.

Optimization
Great White has gained many huge performance advantages over previous versions of Papervision. One important advantage is that nearly all materials will render a surface to BitmapData. This is great because, as of Flash Player Update 3 (9.0.115, mid-2007) Multicore CPU support has been added to much of the BitmapData operations.

Clipping is a flag added to the Viewport3D constructor in Great White that will force the engine to perform clipping of all objects outside the the viewing rectangle (the viewport). This feature may seem obvious, but a lot of public engines neglect this.

Culling Algorithms
Drawing is the most expensive process that Papervision performs. As such, there are a few different standard methods for removing items from the render queue in any 3D drawing API. This helps speed up render times by removing renderable triangles that would otherwise be drawn. Papervision3D performs backface culling, view frustum culling, and contribution culling but NOT occlusion culling. Occlusion culling is a huge process that is more built into accelerated APIs like OpenGL. Though it can be very difficult to perform well, it can also add extrordinary benefits to rendering performance.

MovieClip Materials
Papervision3D supports interactive, animated, and smoothed MovieClip materials. However, those features come at a cost. You may already be aware that BitmapData smoothing (anti-aliasing) is slower than normal BitmapData rendering. Anti-aliasing algorithms are simply expensive operations and thats the bottom line. The other two features are performance hogs because they require that the Flash player to update the surface BitmapData object on each frame update –instead of reusing the original object that was derived from the MovieClip.

Relative Performance
I’m currently coding lots of Flash player performance tests as they relate to Papervision. Right now I’m only using the following methods for testing: Math.sqrt(), Math.sin(), Matrix3D.multiply3x3(), and BitmapData.draw(). The test is simply a for loop that iterates 9999 times. It looks interesting and helps me make another point about PV3D performance. I’ll have to publish this application elsewhere, but for now here’s a sample of what I’m finding:

Figure A: Performance timetable for 4 operations in a for loop lasting 9999 iterations. BitmapDataObject1 is 40×40, transparent and BitmapDataObject2 is 600×600, transparent. They both draw a single purple circle.

As you can see bitmap drawing is the most expensive operation here. In almost every instance that I can think of, drawing will be the most performance intensive activity in any 3D rendering API. I could explain that here, but it would probably double the size of this post. ;)  In a nutshell, it always helps to render only when you actually need to feature interaction and/or animation. Additionally, actively perform any reasonable operation to limit the number of objects in the scene. Again, the library does a lot for you there, but gains can always be made. Also, a little experience will show you that keeping the renderable area small will help also.

The Papervision3d source SVN location includes the standard AS3 version of Papervision3D (version 1.7 as of this writing). If you look at the branches folder inside trunk you will find version 2.0 which is code-named “Great White”. This series is focused on that branch, and NOT version 1.7. Also, its important to know that Great White is probably the fastest and most frequently changing part of the Papervision source and thus details in this article will likely change over time.

Also, as a convention in these posts, I’ll be putting direct references to actual Google Code hosted repository files inside this page. If you don’t wish to open that repository each time you want to know the path of a class, then simply mouse over the link and look at the link address or the tool tip that shows up for the link. All references to Papervision3D classes assume that all uses of the term “pv3d” refer to the root Papervision3D package.

All Flash demonstrations are interactive. After focusing on the Flash applet, you can use the following key controls to control the camera.

Please note that nothing will promote your understanding of the code better than just reading it yourself. Although that may seem daunting, you’ll end up doing it anyway if you really get into the project. A good place to start might be reading the comments for classes in the folder pv3d.core.proto. If you’ve happened upon this page but are unfamiliar with computer graphics from a technical standpoint, please read Part 1

Geometry
In Papervision, all geometry is basically stored in the form of vertex data (Vertex3D). Collections of Vertices are stored in GeometryObject3D instances. Every DisplayObject3D class contains object information (such as location, transformation, orientation axis, etc) AND a reference to a GeometryObject3D instance. The DisplayObject3D class is the building block of all 3D data in Papervision –much like the flash.display.DisplayObject class is the building block of a 2D stage. However, one important difference is that a DisplayObject3D will not contain any rasterized visual data (as the DisplayObject does in its graphics object). It contains only data that is used by the rendering engine (BasicRenderEngine) and the object’s material (* MaterialObject3D) which is used to draw the object onto a Viewport3D object.

*Note: the actual method performing all drawing operations is NOT MaterialObject3D.drawTriangle but instead any of its subclassses that are overriding that method (for example ColorMaterial.drawTriangle).

Texture Mapping
Up until now, all discussion about 3D rendering has excluded the use of images used on geometric surfaces. This feature, called texture mapping, is very widely used. Unfortunately, it can also be quite an expensive process in terms of CPU cylces. Texture mapping has also evolved to allow for plenty of visual effects like bump mapping, normal mapping, displacement mapping, light mapping and more.

As you may recall from Part 1, all surface geometry in Papervision is divided into triangles. However, since images used in texture mapping are rectangular, something must be done to determine how the image can be mapped onto triangles in order to render the rectangular map as a single image. This is where the UV coordinates come in. A UV is simply a 2D coordinate that represents a location on the texture map that is associated with the 3D point on a triangle. Figure A1 shows this relationship.

Figure A1: Three example UVs for texture mapping a rectangular plane.

In Papervision, all the actual drawing commands exist in the material class being used for an object (as I mentioned above). Please note that two options for texture mapping exist. There’s ‘normal’ texture mapping which is also known as ‘affine‘ texture mapping. And then there’s ‘precise’ texture mapping which would be perspective correct. Normal texture mapping is a bit less accurate but far faster in rendering then precise textures. Exhibit A2 shows an example.

Exhibit A2: Normal (left) vs precise (right) texture mapping in Papervision3D 2.0

[kml_flashembed movie="http://www.calebjohnston.com/storage/posts/textureExample.swf" height="250" width="450" /]

Materials
A Material is a term borrowed from 3D development tools (like 3D Studio Max) that describes a collection of properties that will determine how a 3D surface will be rendered. Materials can become very complicated in production 3D rendering tools, but in Papervision a material has only a few properties. Those properties will determine whether lines, fills and/or a bitmap is drawn and how they’re drawn. The real key component of all materials is the drawTriangle method which is called by the engine during the render cycle.

Lighting and Shading
Light simulation is probably one of the most intricate and complicated aspects of 3D rasterisation. Other forms of computer rendering (like ray tracing) don’t treat lighting the way the rasterisation technique does. The reason is simple, performance. So in order to mimic light phenomena using rasterisation, shaders can be used. With the Great White branch of Papervision, lighting and shading have been added. Outside of Papervision, the term “shader” sort of has multiple definitions. Shaders are used in 3D development tools to determine how light will appear on a surface. But in real-time rendering APIs (like OpenGL and Direct3D) a shader is used to modify the graphics pipeline. There are actually several languages that govern shader authoring. Even Adobe has their own brand of shader language called Adobe Image Foundation. Although shading and lighting are rather complicated features in GPU accelerated APIs, in Great White they’re actually much simpler.

With Papervision, shaders are probably most useful for applying native flash effects (filters and blend modes) to any desired surface. Although, filters are not fully supported yet. Aside from that, applying a shader to a material is basically the same as applying a gradient-like light map to the BitmapData surface. So if you understand gradients and BitmapData objects in Flash, you basically understand Papervision shading as well. There are really 4 types of light maps you can use and those are Phong, Flat, Gouraud, and Cell. For each of those light maps there is a shader. There is also one other shader that can create an environment map. Its the EnvMapShader. It allows one to pass in bitmap objects that are used in combination with the surface texture map. Also you can use bump maps in Papervision3D shaders. See the BumpmapGenerator class. Exhibit B illustrates a simple example of various shaders. While this is not really the same ‘shading’ that happens in video games, with Flash 10, shading could definitely change radically in Papervision.

Exhibit B: Shading examples in Papervision3D 2.0

[kml_flashembed movie="http://www.calebjohnston.com/storage/posts/shadersExample.swf" height="250" width="450" /]

Its also important to note that shading requires a light source. Unlike other popular 3D APIs, there is no default ambient light. And any light sources that are used are not a part of the scene. Instead you must add a light source to the shader and its position is used in determining what the light map looks like. At the time of this writing there is only one light source supported per shader in Papervision3D. Also there is only one type of light to choose from -a point light.

Cameras
Cameras aren’t that complicated in Papervision3D. There are three types of Cameras: free, target, and debug. A free camera is totally unattached to anything that exists in the environment and can be moved ‘freely’. But a target camera will have a focus object within the scene. That object can be moved freely, but the camera will always come along. It works just like a focus camera object would work in a 3D development tool like 3D Studio Max or Maya. And thus a key aspect of that behavior is that if you want to translate a Camera3D object, it will actually rotate about its focus object. The last type of camera (debug) allows for key control, so that you can move the camera around as desired. This is highly useful when you’re building a complex scene or importing geometry from an external editor.

The only three camera-specific properties you can manipulate to control the view are zoom, focus and field of view (fov). The fov is in degrees. Normally 60 is representative of a normal 35mm camera lens. But the debug camera defaults to 90 degrees. Zoom and focus can be determined based on the fov and the camera’s distance to the near clipping plane. Exhibit C demonstrates the interaction of the fov and focus value. Also, here are some rather crude numbers for comparison:

Note: all camera focus values are used with a default debug zoom value of 24. Field of view values are in degrees.

Exhibit C: Demonstration of camera field of view and focus. Use keys r and f to increase and decrease the fov respectively.

[kml_flashembed movie="http://www.calebjohnston.com/storage/posts/cameraExample.swf" height="250" width="450" /]

Stay tuned for more feature dissection in Part 3. In the meantime, download examples source files here.

I have many friends asking me for more information on Papervision 3D. Usually, they’re just genuinely interested in learning about it and also how they can use it. These friends are bright people, but generally unfamiliar with the topic of computer graphics. I’ve consistently directed them to Wikipedia articles that I think will make everything clear to them (in this order):

1. Computer Rendering
2. Rasterisation
3. 3D Projection
4. Matrix Multiplication

Unfortunately, I think people are reluctant to read those articles because they’re half written in math formulas. Those formulas are critical for getting a real understanding of what’s going on “under the hood” but I admit they’re annoying to read if you don’t really want to learn the math. And also, those articles won’t mention a single Papervision class file anywhere (naturally). I’m sure this is a little less exciting for someone who’s into 3D in Flash. Therefore, I’m reviewing and dissecting Papervision3D 2.0 (Great White) in a multi-part series for those who are curious about 3D in Flash.

Part 1 will review those Wikipedia articles and relate them to Papervision along the way. If you’re already familiar with computer graphics as a topic of CS, you may wish to skip this post. Parts 2 & 3 will review the details of many features of Papervision3D. Part 4 will be a set of useful notes and tips for anyone who’s not already experienced with Papervision3D.

An Ultra-Brief Background of Computer Graphics
Drawing an image from a 3D scene using a computer can be done many different ways. However, if its going to be done very quickly in order to allow for animation and/or interactivity then typically a process called rasterisation is best. This term is used to describe the transformation of (vector) data into raster (or pixel) data, such as an image.

A few things should also be understood about the vector data used in rasterisation. It really can be almost anything that defines a 3D entity. However Papervision follows the popular convention of using 3D points oriented into triangles. So if a surface looks like a rectangle, its actually (at least) two triangles –each triangle having at least one face. It should also be noted that in 3D space two more important values are often used: normals and UVs. A normal is short for “surface normal vector” which is a vector value that is perpendicular to the triangle’s face. And a UV is a value that is used to determine how an image can be mapped to the triangle’s face. In Papervision, there can be one UV for every 3D point. And there can be one normal for every triangle.

Rasterisation is a term that is used for both 2D and 3D graphics. Without getting into the real nitty gritty behind what’s going on inside a computer to produce an image on a monitor, we can say that Flash has pretty much always performed 2D rasterisation. But with a 3D engine used, a lot of logic is plugged in to produce an illusion of 3D on a 2D screen.

So what is all that logic? In short, 3D projection, matrix math and display list management. Plus, a lot of performance enhancement, shading, parsers, presets, and the structure of a nice OOP API. Here are the basics.

3D Projection
Ultimately, the task of projection is mapping points which are represented in 3D space in a 2D coordinate system. There are different ways of doing this. Figure A1 shows 2 common examples: orthographic and perspective projections.

Figure A1: two common 3D projections of a cube

When using either projection technique and mapping everything within view to a 2D rectangular plane, a renderable volume is determined. This volume will be the space bound by a cube if projection is orthographic. Or it will be a frustum if the projection is perspective. This space is highly useful for making some key optimizations. Figure A2 helps explain the view volume.

Figure A2: Perspective projection view frustum with view frustum culling.

The process of projection is achieved through transforming matrices. In Papervision (as in most 3D APIs) a 4×4 matrix will represent translation, rotation, and scaling for all axes. If you want to understand the raw math behind the matrix convention in 3D graphics, you should actually be reading the links I posted above from Wikipedia. Otherwise the following section will very briefly review the topic.

3D Matrices
A Papervision 3D matrix is represented in 16 Number values. Figure B helps to illustrate how those numbers are used in a right-handed coordinate system.  With Papervision, a left-hand coordinate system is used. This means that the z axis points into the screen and away from the viewer. This will have some important implications if you decide to import models into Papervision from files generated using common 3D software.

Figure B: Three example matrix transformations

There are also 3 matrices that are used to represent a 3D scene in Papervision: the world matrix, the view matrix (or camera matrix), and the object transform matrix. So when an object is projected, it will go through all 3 matrix multiplications AND any animation matrix operations that are performed. More explicitly, each 3D vertex that exists in each 3D object will have to be transformed by all these matrices to end up as a 2D point in Flash.

Display List Management
When an object is added to a scene it is also added to a render list. That render list is sorted so that each object being rendered appears on the screen at the correct depth. Each renderable object is then drawn to the viewport using the viewport graphics object. NOTE: This means that the final render in Papervision is drawn in a single DisplayObject.

Display list management is also where a lot of performance gains can be made. Many times its not necessary to show all the triangle faces that are in a scene because they don’t exist inside the viewing volume (typically a frustum). Removing objects from the render list because they exist outside the viewing volume is called view frustum culling. There are plenty of other (more advanced) methods used in order to optimize the render cycle. Many of those will be explained in part 3.

Valuable Presets
Simple objects like cubes and spheres that come prefabricated in Papervision are called Primitives. They may not seem so sophisticated but consider how you would describe a sphere in terms of triangles using only 3D coordinates. Not to mention how you would determine all the triangle’s UV coordinates and normals! And if you don’t desire creating your 3D scene from primitives, you can generate your own objects algorithmically or even import them from an external source such as a collada file. That’s very valuable indeed!

Actionscript 3.0 and Performance Tuning

AVM2 Overview

There are definitely some big take-aways in these two documents. I would list them here, but then you might not read them for yourself! ;)

The first document is 74 powerpoint slides (prepared by Gary Grossman of Adobe) which is very useful for getting a quick understanding of AVM2 topics such as garbage collection, the benefits of strong typing, the Actionscript byte code (abc) format, the code interpreter and JIT compilation. For an AS3 developer this is a must-read.

The second document is a bit more dense. It contains 108 pages of more formally described underpinnings of the virtual machine. It focuses a lot on how your AS3 code will ultimately be run as processor instructions. Its a great follow-up to the first document. If you’re a geek, I would highly recommend reading this overview.

Download the Starbucks basic class UML (PDF).

I’ve also conducted a certain amount of performance profiling that I will write up in the near future.

Download Source!

StateDemo.mxml

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute" xmlns:local="*" currentState="{ENGLISH}">
	<mx:Script>
		<![CDATA[
			// define the state names as constants
			static public const ENGLISH:String = "English";
			static public const FRENCH:String = "French";

			/**
			 * When the "make breakfast" button is clicked, display the steps
			 * you'll need to follow to make breakfast.
			 * Imagine that you'd need to implement all of these steps as functions
			 * and that there are several more languages to support.
			 */
			protected function onBreakfastButton(event:Event):void {
				if (currentState == ENGLISH) {
					output.text = "Fry eggs" +
								  "\nFry tomatoes" +
								  "\nToast bread" +
								  "\nMake tea";
				}
				if (currentState == FRENCH) {
					output.text = "Tartiner du beurre sur baguette" +
								  "\nMettre le yaourt dans un bol" +
								  "\nTranche les fruits" +
								  "\nFaire cafe";
				}

			}
		]]>
	</mx:Script>

	<!-- Define the changes to the view in the <mx:states> tags -->
	<mx:states>
		<mx:State name="{ENGLISH}">
			<mx:SetProperty target="{breakfastButton}" name="label" value="Make Breakfast" />
		</mx:State>
		<mx:State name="{FRENCH}">
			<mx:SetProperty target="{breakfastButton}" name="label" value="	Préparer des petits-déjeuners" />
		</mx:State>
	</mx:states>

	<mx:VBox>
		<mx:Button id="breakfastButton" click="onBreakfastButton(event)" />
		<mx:TextArea id="output"  height="100" width="250"/>
		<mx:HBox>
			<!-- Swap states using these buttons -->
			<mx:Button label="English" click="{currentState = ENGLISH}" />
			<mx:Button label="French" click="{currentState = FRENCH}" />
		</mx:HBox>
	</mx:VBox>
</mx:Application>

Compiling this code gives you the following…
View SWF

The problem

While there’s nothing inherently wrong with this application, there could be complications when trying to make changes to the logic. First of all, the onButtonClick() handler has to provide different functionality based on the currentState. The states themselves need to add labels to the breakfastButton. Imagine what would happen if you expanded this application to support 15 languages or to create lunch, dinner, and teatime. Things could get out of control fast!

The Solution – applying the state design pattern

The state design pattern allows you to separate out state specific functionality and defer the execution of methods to those state objects.

I’ll combine the state pattern with the view states by making a currentLogicalState property of the application. This setter will also automatically set the currentState based on a name stored in the currentLogicalState. This is easier done than said…

1. Define a logical state interface

My logical state interface only needs to have one getter for name so that we can associate it with a view state.

ILogicalState.as

package
{
	public interface ILogicalState
	{
		function get name():String;
	}
}

package
{
	public interface IBreakfastMakerState extends ILogicalState
	{
		function get breakfastInstructions():String;
		function get breakfastLabel():String;
	}
}

package
{
	public class EnglishBreakfastState implements IBreakfastMakerState
	{
		public function get name():String
		{
			return "English";
		}

		public function get breakfastInstructions():String
		{
			return "Fry eggs" +
				   "\nToast bread" +
				   "\nFry tomatoes" +
				   "\nMake tea";
		}
		public function get breakfastLabel():String {
			return "Make Breakfast";
		}
	}
}

package
{
	public class FrenchBreakfastState implements IBreakfastMakerState
	{
		public function get name():String
		{
			return "French";
		}

		public function get breakfastInstructions():String
		{
			return "Tartiner du beurre sur baguette" +
				   "\nMettre le yaourt dans un bol" +
				   "\nTranche les fruits" +
				   "\nFaire cafe";
		}

		public function get breakfastLabel():String {
			return "Préparer des petits-déjeuners";
		}
	}
}

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute" xmlns:local="*"
	initialize="onInitialize(event)">
	<mx:Script>
		<![CDATA[

			// define the logical states as constants
			static public const ENGLISH:IBreakfastMakerState = new EnglishBreakfastState();
			static public const FRENCH:IBreakfastMakerState = new FrenchBreakfastState();

			/**
			 * keep track of the current logical state and when the currentLogicalState changes
			 * update the currentState using its name property.
			 */
			protected var _currentLogicalState:IBreakfastMakerState;
			public function set currentLogicalState(state:IBreakfastMakerState):void {
				_currentLogicalState = state;
				currentState = _currentLogicalState.name;
			}

			protected function onInitialize(event:Event):void {
				currentLogicalState = ENGLISH;
			}

			protected function onBreakfastButton(event:Event):void {
				// rely on the logical state to handle the logic of preparing the breakfast.
				output.text = _currentLogicalState.breakfastInstructions;
			}
		]]>
	</mx:Script>

	<!-- Define the changes to the view in the <mx:states> tags -->
	<mx:states>
		<!-- Name each view state using the name of the logical state -->
		<mx:State name="{ENGLISH.name}">
			<!-- Change the label using a value from the logical state -->
			<mx:SetProperty target="{breakfastButton}" name="label" value="{ENGLISH.breakfastLabel}" />
		</mx:State>
		<mx:State name="{FRENCH.name}">
			<mx:SetProperty target="{breakfastButton}" name="label" value="{FRENCH.breakfastLabel}" />
		</mx:State>
	</mx:states>

	<mx:VBox>
		<mx:Button id="breakfastButton" click="onBreakfastButton(event)" />
		<mx:TextArea id="output"  height="100" width="250"/>
		<mx:HBox>
			<!-- Swap logical states using these buttons -->
			<mx:Button label="English" click="{currentLogicalState = ENGLISH}" />
			<mx:Button label="French" click="{currentLogicalState = FRENCH}" />
		</mx:HBox>
	</mx:VBox>
</mx:Application>