mrdoob/three.js — pull request #3153 by WestLangley (2013-03-03 05:08:56+00:00)
Title: Changed Object3D.translate() so it supports non-uniform scaling.

This change is part of ongoing improvements to support non-uniform scaling (e.g., when `object.scale.x != object.scale.y` ). Many of our routines assume that the upper 3x3 of the object matrix is a pure rotation matrix, and these routines do not work correctly under arbitrary scaling.

In addition, the following does not currently work:

object.rotation.x = Math.PI;
object.translateY( 10 );

The reason is because the translate function queries the _object matrix_ for the rotation information, rather than the `rotation` vector or `quaternion` itself.

To make the above work with the existing code, the following pattern has been required ( and it occurs frequently ):

object.rotation.x = Math.PI;
object.updateMatrix();
object.translateY( 10 );

or

object.rotation.x = Math.PI;
render();
object.translateY( 10 );

With the proposed change, the first pattern above works as expected.

Be warned that this changed breaks `RollControls` because `RollControls` sets `camera.matrixAuotUpdate = false`, and then manipulates the camera.matrix directly.

Here is why doing so is a problem:

The reason for setting the flag `Object3D.matrixAutoUpdate = false` is to prevent the renderer from recomputing the object matrix every frame when the object is known to be _static_ -- NOT to provide the user an alternative method of setting the object transform by manipulating the object matrix directly.

Consequently, if the object is not static, then the user must manipulate the object by changing its `position`, `rotation`, and `scale` vectors, and not by changing the object's matrix directly.

If we want to support changing the matrix directly, then every routine that relies on rotation information must have two logic paths -- one to get it from the matrix, and one to get it from the rotation vector or quaternion.

To the best of my knowledge, `RollControls` is the only class that is broken by this change.