Hi developers,
A non-user friendly part of the jME API, IMHO:
These functions keep a reference to the passed object:
//com.jme.scene.Spatial
setLocalRotation(Quaternion quaternion)
setLocalScale(Vector3f localScale)
setLocalTranslation(Vector3f localTranslation)
This one does not:
setLocalRotation(Matrix3f rotation)
If you are not aware of which ones keep a reference to the passed object, subtle bugs might arise.
(A year ago, I lost some hour on this, and a while ago I lost ten minutes (I'd forgotten how those functions function).)
The only way to find out which of them keep a reference is by studying the source code.
Perhaps updating the docs would suffice (to clarify which functions keep references). Personally, however, I intuitively expected no single setXXX to keep references to Vector3f:s and Quaternions, but rather copy their XYZW components. I think this is the behavior most people expect?
Perhaps the keep-reference behavior might sometimes be useful (why? to share the same local translation between several Spatial:s?) but is it perhaps the case that those situations are fairly rare, motivating perhaps a rename of [the setXXX functions that keep a reference] to clarify that the reference is kept? (I suppose they cannot be removed?)
Perhaps they could be named takeLocalTranslation() etc. instead, since... they take and keep the reference. Non-standard names for... non-standard behavior? (I don't know.)
I did a forum search on setLocalRotation and I got the impression that there was a little bit confusion caused by these functions keeping a reference.
obidobi said:
Doing
planet.setLocalTranslation(planet.getWorldTranslation());
instead of
planet.getLocalTranslation().set(planet.getWorldTranslation());
is probalby one of the most common misstakes you can do when starting with jme.
I did it to in the first jme code I wrote and did my fair share of head banging :)
adamgp said:
I read on the below guide not to use setLocal... and rather getLocal....set(x, y, z).
[...]
What are the differences between the two [...]
Thanks, Magnus