In the first post I introduced Coral, explaining what it is and why I’m releasing it as an open source project. The next post looked at the key architectural differences between Coral and the native Vector3D and Matrix3D classes. The third post compared the performance of Coral and the native 3D math classes. This last post is about bugs.

The classes in Coral are covered by unit tests. I don’t write unit tests for every bit of code I write, but for classes like these 3D Math classes, which will be used in many different projects, in many different circumstances, where bugs could be hard to track down, I consider unit tests essential.

I adapted the unit tests from Coral to test Flash’s native Vector3D and Matrix3D classes. In so doing, I discovered a number of bugs in the native classes. All the test code is in the Coral project on Github. This is what I found.

Bugs in Vector3D

Vector3D passed most of the tests. These are the tests it failed.

X_AXIS, Y_AXIS & Z_ AXIS are mutable.

Consider this code

var v : Vector3D = Vector3D.X_AXIS;
v.scaleBy( 2 );
var u : Vector3D = Vector3D.X_AXIS;
trace( u );

It would be natural to expect u to be the vector ( 1 0 0 ), but it isn’t. It’s ( 2 0 0 ). Because X_AXIS, Y_AXIS & Z_AXIS return a reference to the same vector every time. They should return a new vector each time, so the value of the X_AXIS, Y_AXIS & Z_AXIS properties can’t be changed.

Vote for this bug on Adobe’s bug tracker

CrossProduct sets the w coordinate to 1

The default value for the w coordinate is supposed to be zero. So the w coordinate of the result of the crossProduct of two vectors should be zero. It isn’t – it’s one.

var u : Vector3D = new Vector3D( 1, 0, 0 );
var v : Vector3D = new Vector3D( 0, 1, 0 );
var r : Vector3D = u.crossProduct( v );
trace( u.w ); // 0
trace( v.w ); // 0
trace( r.w ); // 1

Vote for this bug on Adobe’s bug tracker

Bugs in Matrix3D

Matrix3D contains more serious bugs than Vector3D. Here they are.

The determinant is incorrect

When the Matrix3D class calculates the determinant, it gets it wrong. Every time. Consider this matrix, for example.

[ 1 2 3 4 ]
[ 2 3 4 5 ]
[ 3 4 5 6 ]
[ 4 5 6 7 ]

The determinant of this matrix is zero. But the Matrix3D class thinks it is -36. Stranger, but reassuring, if you ask Matrix3D to calculate the inverse, it recognizes that the inverse can’t be calculated because the determinant is zero!!

var m : Matrix3D = new Matrix3D(Vector.([1,2,3,4,2,3,4,5,3,4,5,6,4,5,6,7]));
trace( m.determinant ); // -36
var b : Boolean = m.invert();
trace( b ); // false

Matrix3D even gets the determinant of the identity matrix wrong.

var m : Matrix3D = new Matrix3D();
trace( m.determinant ); // -1

The correct value is 1.

Vote for this bug on Adobe’s bug tracker

Floating point inaccuracies

The Matrix3D class introduces inaccuracies in floating point numbers that far exceed the normal floating point inaccuracies. You can see this without even touching the matrix after creating it…

var m : Matrix3D = new Matrix3D(Vector.([1.1,0,0,0,0,1.1,0,0,0,0,1.1,0,0,0,0,1]));
trace( m.rawData );

The output from this is

1.100000023841858,0,0,0,0,1.100000023841858,0,0,0,0,1.100000023841858,0,0,0,0,1

The Matrix3D class intermittently fails some of Coral’s unit tests because the results are not within 0.0001 of what they should be. To me, that’s a big error.

Vote for this bug on Adobe’s bug tracker

appendRotation() and prependRotation() assume the axis is of unit length

The appendRotation() and prependRotation() methods only produce the correct matrix if the axis property passed to the method is of unit length.

This code specifies a 90° rotation about the x-axis.

var m : Matrix3D = new Matrix3D();
m.appendRotation( 90, new Vector3D( 1, 0, 0 ) );
trace( m.rawData );

The result is the matrix

[ 1 0 0 0 ]
[ 0 0-1 0 ]
[ 0 1 0 0 ]
[ 0 0 0 1 ]

This code also specifies a 90° rotation about the x-axis.

var m : Matrix3D = new Matrix3D();
m.appendRotation( 90, new Vector3D( 2, 0, 0 ) );
trace( m.rawData );

But the result is the matrix

[ 4 0 0 0 ]
[ 0 0-2 0 ]
[ 0 2 0 0 ]
[ 0 0 0 1 ]

Which is a rotation and scale.

That the axis should be a unit vector isn’t specified as a requirement in the documentation and it isn’t enforced in the code. These methods should calculate a unit vector from the axis and use that to calculate the rotation.

Vote for this bug on Adobe’s bug tracker

appendTranslation() ignores the bottom row of the matrix

The appendTranslation() method simply adds the new translation coordinates to the translation coordinates in the last column of the matrix. This is only correct if the first three numbers in the bottom row of the matrix are zero.

[ 1 0 0 2 ]   [ 2 1 0 0 ]   [ 2 1 0 2 ]
[ 0 1 0 3 ] . [ 3 1 2 0 ] = [ 3 1 2 3 ]
[ 0 0 1 4 ]   [ 1 0 1 0 ]   [ 1 0 1 4 ]
[ 0 0 0 1 ]   [ 0 0 0 1 ]   [ 0 0 0 1 ]

[ 1 0 0 2 ]   [ 2 1 0 0 ]   [ 4 3 2 2 ]
[ 0 1 0 3 ] . [ 3 1 2 0 ] = [ 6 4 5 3 ]
[ 0 0 1 4 ]   [ 1 0 1 0 ]   [ 5 4 5 4 ]
[ 0 0 0 1 ]   [ 1 1 1 1 ]   [ 1 1 1 1 ]

The Matrix3D class gets the first calculation correct and gets the second one wrong.

var m1 : Matrix3D = new Matrix3D(Vector.([2,3,1,0,1,1,0,0,0,2,1,0,0,0,0,1]));
m1.appendTranslation( 2, 3, 4 );
trace( m1.rawData ); // 2,3,1,0,1,1,0,0,0,2,1,0,2,3,4,1 
var m2 : Matrix3D = new Matrix3D(Vector.([2,3,1,1,1,1,0,1,0,2,1,1,0,0,0,1]));
m2.appendTranslation( 2, 3, 4 );
trace( m2.rawData ); // 2,3,1,1,1,1,0,1,0,2,1,1,2,3,4,1

Vote for this bug on Adobe’s bug tracker

transformVector() ignores the w coordinate

The transformVector() method ignores the value of the w property of the input vector. The transformVector() method will set the w property if you define a matrix that affects the fourth coordinate of the vector, for example a perspective projection matrix. However, it assumes the w coordinate of the input vector is 1, even though the default value for the w coordinate is 0.

Vote for this bug on Adobe’s bug tracker

The end

That’s all the bugs I found. Please vote for them in the Adobe bug tracking site.

That’s also the end of this series of posts about Coral and Flash’s native 3D Math classes. Please feel free to use, fork and improve Coral. And let me know what you think, in the comments or via Twitter.

Footnote

The new Flash Player 11 Incubator pre-release became available on 28 February. I ran the test suite using this new player and all the bugs appear to still be present. That’s not surprising since I only notified Adobe of the bugs a few days before the pre-release.

In the first post I introduced Coral, explaining what it is and why I’m releasing it as an open source project. The next post looked at the key architectural differences between Coral and the native Vector3D and Matrix3D classes. In a later post I will show you the bugs I discovered in the native 3D math classes. This post is about performance.

Coral is covered by a set of performance tests for measuring and optimizing it’s performance. These tests are run using Grant Skinner’s performance test suite. I adapted these tests to also apply to the native 3D geometry classes, for comparison. All the test code is in the Coral project on Github.

I ran these tests on my laptop, a MacBook with a 2.4GHz Core2Duo cpu, with the release version of Flash Player 10.2.152.26. All tests were over 1,000,000 iterations and each test is run four times and an average taken.

Vector3d performance tests

Comparing Coral’s Vector3d class to the native Vector3D class, the first thing I notice is that the majority of methods show insignificant differences. Those methods where significant differences occur are situations where Coral avoids creation of a temporary object. Thus, Coral is marginally faster when adding two vectors to produce a third new vector, but is very much quicker when it’s allowed to use an existing vector to hold the result – something which the native vector class can’t do.

Point3d performance tests

As with Coral’s Vector3d class, the Point3d class has comparable (usually marginally faster) performance where functionality is identical, but is very much faster where it is able to avoid creating a temporary object.

Matrix3d performance tests

* collection being transformed contained 30 vectors/points

The results of the matrix tests are more diverse than the vector and point tests. Creating transformation matrices using ‘new’ plus the various append/prepend transformation methods will usually be quicker with Coral than with the native classes. In some cases (e.g. prependScale) the difference is very large.

However, it could be argued that this is rarely important. The area where real speed is needed is when performing transformations on vectors and points. Here the performance profiles differ. Coral is very much faster when performing transformations on individual vectors and points, where it can produce a 25x speed improvement by avoiding creating temporary objects.

However, if you bundle all your points into a Vector.<Number> collection, the native Matrix3D class outperforms everything else.

Next

That’s all for performance. Overall I have found Coral to be a lot more performant than the native 3D math classes. In the final post in this series I will look at the bugs in Flash’s native 3D classes that were revealed by applying Coral’s unit tests to the native 3D classes.

Footnote

The new Flash Player 11 Incubator pre-release became available on 28 February. This pre-release is only available as a debug version, so results from it are not comparable to the release players. Even so, I ran the tests out of interest and it looks like Matrix3D.transformVectors() has got a lot faster. There is nothing else of significance to draw from the debug version – we’ll have to wait for a release version to land to find out more.

In the first post I introduced Coral, explaining what it is and why I’m releasing it as an open source project. In later posts I will compare the performance of Coral with the native Vector3D & Matrix3D classes and will discuss the bugs I discovered in the native 3D math classes.

In this post I will look at the key architectural differences between Coral and the native Vector3D and Matrix3D classes. Code architecture is an important area to me. I find well architected code is much easier to use, leading to more rapid development and fewer bugs. So good architecture in core classes like Vector3D and Matrix3D can make a lot of difference to developers.

I happen to think that Coral has a much better architecture than the native classes, but then I would – I wrote it. I’d like to know what you think, in the comments below or on Twitter.

How many core classes do we need?

The first thing you’ll notice when comparing the two projects is the number of core classes they have. The core 3D geometry classes in Flash are

• Vector3D
• Matrix3D

In Coral, the core classes are

• Vector3d
• Point3d
• Quaternion
• Matrix3d

This is because the native Vector3D class is used to represent vectors, points and quaternions. I think this is a big architectural mistake and so Coral has separate classes for each type. Here’s why…

Vectors and Points

A point is a location in space, like the centre of Trafalgar Square in London, or the centre of Times Square in New York. You can’t do much to a point – you can’t add points together (Times Square + Trafalgar Square = ?), you can’t multiply them by a scalar (what’s 2 x the centre of Times Square?). You can’t find the dot product of two points. Points have zero dimensions and there’s not a lot you can do with points alone, except change the coordinate system you use to represent them.

A vector on the other hand represents a direction and distance in space. Like 5 miles north, or 3 miles west. 5 miles north is a vector – it’s a distance and a direction. We can do lots more with vectors. For example, we can add them together: 5 miles north + 5 miles west = 7 and a bit miles north west (thanks to Pythagoras for that one). We can subtract them: 5 miles north – 5 miles west = 7 and a bit miles north east. We can multiply them by a scalar: 2 * 5 miles north = 10 miles north, and we can do a whole lot more besides, like dot product, cross product, normalize, etc.

We can also add a vector to a point, to get a new point – Times square + 5 miles north = somewhere in New Jersey.

The whole point of this is, points and vectors are different. Yes, they can both be represented in cartesian coordinate space by three coordinates, but that doesn’t make them the same.

Yet Actionscript uses a single class (Vector3D) to represent them both. So, in the Vector3D class we have methods like crossProduct() and properties like length that only apply to vectors, and we have methods like project() that only apply to points. It’s the developer’s responsibility to know whether the Vector3D object they’re using actually represents a point or a vector, and hence which methods are valid.

Coral has no such issues because in Coral points and vectors are represented by different classes.

Matrix Transformations

Transformations in 3D space are commonly represented by a 4×4 matrix. A transformation that doesn’t move the origin can be, and often is, represented with a 3×3 matrix.

[ a b c ]
[ d e f ]
[ g h i ]

We can multiply our vector or point by this matrix to get the transformed vector or point.

[ a b c ]   [ x ]   [ new_x ]
[ d e f ] x [ y ] = [ new_y ]
[ g h i ]   [ z ]   [ new_z ]

If we want to include translations in the transformation we use a 4×4 matrix.

[ a b c tx ]
[ d e f ty ]
[ g h i tz ]
[ 0 0 0 1  ]

Where tx, ty and tz represent the translation in the x, y and z directions. We also add a fourth value to the point or vector, often called the w coordinate, to bring the translation in to play. For a point we would use 1 for the w value.

[ a b c tx ]   [ x ]   [ new_x + tx ]
[ d e f ty ] x [ y ] = [ new_y + ty ]
[ g h i tz ]   [ z ]   [ new_z + tz ]
[ 0 0 0 1  ]   [ 1 ]   [     1      ]

By using a 1 for the y coordinate, we ensure the translation elements are added in to the transformation of the point.

However, when transforming a vector, the translation part of the transformation should not be applied. This is because, unlike a point, a vector is not located in the three-d space. The vector “5 miles north” is the same whether you are in London or New York.

To avoid applying the translation part of the 4×4 matrix when transforming a vector, we set the w coordinate of the vector to 0.

[ a b c tx ]   [ x ]   [ new_x ]
[ d e f ty ] x [ y ] = [ new_y ]
[ g h i tz ]   [ z ]   [ new_z ]
[ 0 0 0 1  ]   [ 0 ]   [   0   ]

This is another area where vectors and points differ, and Coral takes care of the difference for you. Coral’s Vector3d and Point3d classes both have a w coordinate, which defaults to 0 in the Vector3d class and 1 in the Point3d class. You don’t usually have to change these values, but if you do that’s fine. The Matrix3d class will use whatever value of w the point or vector has when transforming it.

Actionscript’s Vector3D class also has a w coordinate property. the value of this property defaults to 0. Don’t bother changing it because the value of this property is ignored when applying a Matrix3D transformation to a Vector3D object. Instead, to transform your point or vector you have to choose between the radically misnamed transformVector() method, which assumes a w coordinate of 1, for transforming a point and the almost as badly named deltaTransformVector() method, which assumes a w coordinate of 0, for transforming a vector.

Quaternions

Quaternions are another object type used in 3D geometry. A quaternion represents a rotation in 3D space. Rotations can be represented using a Matrix, but sometimes it’s much easier to use a quaternion.

A quaternion has nothing in common with a vector or a point, although a quaternion is represented using four numbers, commonly called w, x, y & z. These are not like the coordinates of a vector or point and the common methods of vectors and points don’t apply to quaternions. Despite this, in the native 3D classes quaternions are represented using the Vector3D class. This overloads the Vector3D class with yet another object to represent – an object to which methods like crossProduct() and project() are meaningless, and which can’t be transformed by a matrix.

This is so confusing that most 3D Actionscript libraries give up at this point and create their own class to represent a quaternion. Flint is no exception to this rule – it uses the quaternion class from Coral.

More methods

Coral contains many methods that are not in the native Vector3D and Matrix3D classes, ranging from simple methods like Vector3d.multiply() to more complex methods like Matrix3d.appendBasisTransform(). These are all useful additions to the classes and make 3D development simpler because it frees developers from having to implement these behaviours in their own code.

Method chaining

Often the code that uses classes like Vector3D is performing simple mathematical methods on vector or point objects. For example, if you have an initial position point p, an initial velocity vector u and final velocity vector v and a time number t, and you want to calculate the new position after time t. In mathematics, this would be expressed as

newP = p + ( u + v ) * t / 2

In the absence of operator overloading, we can’t make the same calculation in Acrionscript look as concise as the mathematics, but we can do better than Flash’s native Vector3D class.

Using Flash’s native Vector3D class the calculation above is expressed as

var temp:Vector3D = u.add( v );
temp.scaleBy( t / 2 );
p.incrementBy( temp );

(252 ms for 1,000,000 iterations)

Using Coral’s classes, the same calculation is expressed as

p.incrementBy( u.add( v ).scaleBy( t / 2 ) );

(194 ms for 1,000,000 iterations)

In Coral, all methods that manipulate the object the method belongs to return a reference to that object (i.e. a reference to ‘this’). So in the example above, the scaleBy method of the Vector3d class returns a reference to the vector that has been scaled. This enables chaining of methods to produce more compact, cleaner code.

Optional result objects

It is common knowledge that object creation in Actionscript is slow. That’s why many speed-critical projects use object pools to reuse objects rather than create new ones. Unfortunately, it’s very difficult to use Flash’s native geometry classes without creating lots of temporary Vector3D and Matrix3D objects.

The previous example is a case in point. The temporary vector object is explicitly required in the native example. In the Coral example, a similar temporary object is created from the addition. But with Coral this can be avoided. In Coral, all methods that would create an object to hold the result of the method, have an optional parameter allowing you to pass in an object to hold the result and thus avoid the object creation.

So, if I have a temporary Vector3d available, from an object pool or elsewhere, I can rewrite the calculation above as

p.incrementBy( ( u.add( v, temp ).scaleBy( t / 2 ) );

(35 ms for 1,000,000 iterations)

and get a fivefold speed increase by avoiding the object creation.

Conclusion

It’s my opinion that the overloading of a single Vector3D class to represent vectors, points and quaternions is the worst architectural mistake in Actionscript’s native 3D math classes. That the matrix transformations also ignore the w coordinate, forcing one to choose between two badly named methods instead, compounds the problem.

The other architectural improvements in Coral that I mention above improve readability and performance of the code, and hence are very useful.

Next

That’s all for architecture. Next time I’ll compare the performance of Flash’s native 3D math classes and the classes in Coral. Then I’ll finish up by describing the bugs I found in the native Vector3D and Matrix3D classes.

I started work on Flint Particles before Flash 10 was launched, so back then I created my own 3D mathematics classes for Flint. At the time this was not unusual – Away3D and Papervision3D had their own Number3D and Matrix3D classes, for example.

Since the release of Flash 10, open-source projects have gradually switched to use the native Vector3D and Matrix3D classes found in the flash.geom package and recently I decided it was time for Flint to also make this change, hence the release of Flint 3.0 a few weeks ago which uses those native 3D math classes.

Converting Flint to use the native classes was an interesting experience. For one thing, I think the architecture of Flint’s classes was better than the native classes. That wasn’t sufficient reason to stick with Flint’s own classes; using it’s own 3D math classes was a barrier to entry for users who were familiar with the native classes and resulted in many questions from confused new users. (For much the same reason, I don’t use the excellent As3-Signals library by Robert Penner in Flint, even though I use it in all my other work.)

So I set about converting Flint to use the native 3D classes. The initial conversion was mostly straightforward, only complicated by a lack of functionality in the native classes that sometimes meant one line of code using Flint’s classes had to be replaced with 3 or 4 lines of code using the native classes.

Having made the change, however, I was surprised to find two significant issues with the new code. The first was a couple of bugs in the native classes, which were not too serious since I could find a way to work around them. The second, and far more troubling issue, was a very large drop in performance – the code using the native 3D classes ran at about one quarter of the rate of the code using Flint’s own 3D classes.

I was eventually able to fix the performance loss, mostly by inlining some critical and slow methods including, for example, the code to transform every particle’s position from global coordinate space to camera coordinate space, where instead of a simple

pp = camera.transform.transformVector( p );

Flint now does

var raw:Vector. = camera.transform.rawData;
pp.x = raw[0] * p.x + raw[4] * p.y + raw[8] * p.z + raw[12] * p.w;
pp.y = raw[1] * p.x + raw[5] * p.y + raw[9] * p.z + raw[13] * p.w;
pp.z = raw[2] * p.x + raw[6] * p.y + raw[10] * p.z + raw[14] * p.w;
pp.w = raw[3] * p.x + raw[7] * p.y + raw[11] * p.z + raw[15] * p.w;

for a massive performance improvement.

Coral

In light of the issues I encountered I have decided to release the 3D math classes that were formerly part of Flint as a separate open source project. I continue to use these classes in my own work (with the exception of Flint) and others may want to do so too.

I am calling the project “Coral” – apparently small pieces of coral are sometimes found inside larger pieces of flint. Coral is available on Github, including unit tests and performance tests. Please feel free to use it, fork it and improve it.

Since releasing Flint 3.0, I modified the unit tests and performance tests in Coral to also apply to the native 3D math classes, Vector3D and Matrix3D. This was out of curiosity mainly, but it revealed a number of bugs in the native classes and where the major performance weaknesses in these classes are.

In the following posts I’ll look at the results of these tests, with posts about the bugs I found and a performance comparison of Coral and the native classes. But first, if you’ll indulge me, here’s a post comparing the architecture of Coral and the architecture of Flash’s native 3D classes.

For Away3D Flint has one renderer, the Away3D renderer, that uses any Away3D Object3D type for displaying each particle inside an ObjectContainer3D. This lets you use 2D sprites or 3D objects for the particles.

For Papervision3D, Flint has three renderers -

• A pixel renderer that displays each particle as a pixel in a Papervision Pixels object.
• A particle renderer that displays each particle in a Papervision Particles object using a Papervision particle.
• A basic renderer that displays each particle in a DisplayObject3DContainer using a Papervision DisplayObject3D object.

In all cases, the renderer sets the appropriate properties of the particle’s display object based on the state of the particle system and leaves the 3D engine to do the drawing.

Flint can be downloaded from the Google Code repository. Along with the source download, you’ll find documentation and examples using the new features.

Have fun with this, and if you find any bugs or spot a better way to do something please let me know via the Flint forum.

The 2D effects have some enhancements over previous versions. The 3D effects are all new, and include most of the features from 2D, along with some new stuff. At the moment, rendering is done via Flint’s own new 3D renderers, but I’m developing renderers for Papervision3d, Away3d and Sandy3d so that Flint can be used as a particle system with any of these 3d libraries too.

Here’s an example.

Use W,A,S,D keys to track in/out and left/right. Use cursor keys to pan and tilt. Use page-up/page-down to raise and lower the camera.

As always, find out more about Flint from the project website.

Flash Player 10 beta

Lots of cool new stuff in the Flash Player 10 beta, if only I had time to try it out.

• The player
• The Flex compiler
• The docs

3D engines

I still haven’t had time to do much with 3D in Flash (although I need to know to get Flint working in the 3D engines). I want time to experiment with the 3D engines and discover their strengths and weaknesses.

• Papervision3D
• Sandy3D
• Away3D
• Alternative3D
• Five3D

Physics engines

I also want time to try out the 2D and 3D physics engines.

• Box2DFlashAS3
• Motor 2
• APE
• FOAM
• Fisix
• Wow-engine

Flex tools

There’s a number of Flex tools/libraries that I want to investigate. Top of the list are

• Mate
• OpenFlux

What I’m doing now

Meanwhile, I only have a little spare time, which I’m using to develop the next version of Flint. I have some other personal projects I want to work on but they are all on hold for now.