API inconsistency: Spatial.setLocalRotation, setLocalRotation

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

I actually agree.  I guess you could argue that it allows you to save some small amount of memory to reuse objects, but that's trivial.  You could also argue that it allows you to use a ref to the Vector3f/Quaternion you set to make changes, but this seems like poor programming to me.