According to the JavaDoc for com.jme3.light.DirectionalLight.setDirection(Vector3f), the direction of a DirectionalLight is the direction the light is coming FROM. In fact, it is the direction that the light is shining TOWARDS, as one may easily verify.
Would someone please correct the documentation?
WellâŚâshining towardâ is not exact neitherâŚbut I see your point.
The doc should be âsets the lightâs directionâ. Canât see anything that makes more senseâŚ
âLightâs directionâ is ambiguous because itâs not obvious whether it means the direction of travel of the light or the direction to the light source. But almost anything would be better than the current JavaDoc, which is IMHO 100% misleading. Because I was misled, I wasted about an hour of debugging time a few days ago.
@sgold said: "Light's direction" is ambiguous because it's not obvious whether it means the direction of travel of the light or the direction to the light source. But almost anything would be better than the current JavaDoc, which is IMHO 100% misleading. Because I was misled, I wasted about an hour of debugging time a few days ago.
I agree that the docs need to be changed⌠but next time you waste an hour debugging something so trivial, please remember that there are many tutorials that work fine and have proper lighting setup. I hope that an hour is an exaggeration because it seems like backwards lighting is something that would be obvious right away. I think I hit this the first time I used DirectionalLight almost three years ago⌠and saw the light was on the wrong side and flipped it.
Anyway, âlight directionâ is not ambiguous because there are infinite number of âdirections to the light sourceâ since for DirectionalLight it is an infinite plane infinitely far away. So âlight directionâ can only mean the direction that the light travels⌠just like camera direction is the direction the camera is looking, etcâŚ
And I suspect most people would get it had they not already been misled by the current docs.
Thanks for your response @pspeed.
I didnât track the time I spent debugging, so perhaps âan hourâ is inaccurate. And since Iâd already written several apps that used DirectionalLight correctly, perhaps itâs worth explaining why this bug caused me such angst.
My code was originally calculating the direction correctly, by negating the direction vector to the source. After I noticed that the shadows were in the wrong places, I read the JavaDoc and concluded that I didnât need to negate the vector. However the real bug was in another piece of code that used the source direction to control another visible aspect of the scene. (This is a moderately complex app, not 100-line test app.) There were several possible sign errors I had to investigate before I realized I now had two errors in my app which tended to cancel each other out in the case of shadows.
I rely on JavaDoc a lot â perhaps more than other developers do. That may explain why I consider these errors worth reporting.
I also beg to differ with your âAnywayâ paragraph. In Geometry, the direction from a point to an infinite plane is well-defined. With a distant light source, all the light energy propagates in a single (Cartesian) direction. The direction to the source is always the opposite of the direction of propagation, so the direction to the (infinite planar) source is the same from every point in space.
The most likely confusion is over the sign of the direction, so thatâs what most needs to be documented. It doesnât help that non-technical English uses the same word (âlightâ) for two distinct concepts: âlight energyâ and âlight sourceâ.
I apologize if this is getting TLDR. Can I rely on you to change the docs?
Being pedantic, âdirection to the light sourceâ requires WAY too much qualification to be usefully interpretted as âlight directionâ. Youâre already assuming it means âshortest direction to the light sourceâ⌠but thatâs perhaps erroneous.
Without extra qualification, âdirection to the light sourceâ encompasses all of the green arrows in this picture:
To interpret it as you suggest, you have to assume that the light is already only traveling in one direction and that âshortest direction to light sourceâ is intended, etc⌠Itâs not at all concise.
Whereas there is only one blue arrow which is âdirection of the light sourceâ. And it is the same no matter where you move it on the yellow light plane. Itâs the very definition of âdirectional lightâ since the whole premise is that all of the light beams are perfectly in parallel. Why would we specify any other direction other than that direction?
Any other interpretation is admitting that extra information is needed and that extra work has to be done every time the useful value is required (mult(-1))⌠since a directional light is only direction, it makes little sense that it would be anything other than that direction. Anything else is an arbitrarily contrived concept attempting to explain how this imaginary directional light might exist in the real world.
So the direction is either the direction of the DirectionalLight or at best âthe opposite directionâ of the DirectionalLight⌠and the latter seems silly. After all, there is no light source⌠the light just âisâ. It only possesses color and direction.
Can I rely on you to change the docs?
@sgold said: Can I rely on you to change the docs?
Heheh⌠I donât know if I will be in the source code soon. Someone else may get to it first.
It is in the direction the light is coming from. I point in the direction the monster is coming from. I think the javadoc is fine.
@normen said: It is in the direction the light is coming from. I point in the direction the monster is coming from. I think the javadoc is fine.
Except if you point it up then all of the stuff is lit from the bottom because the javadoc is currently backwards for DirectionalLight. The direction controls the direction the light is traveling⌠because to do otherwise is backwards.
@pspeed said: Except if you point it up then all of the stuff is lit from the bottom because the javadoc is currently backwards for DirectionalLight. The direction controls the direction the light is traveling... because to do otherwise is backwards.
Yeah, when I point at the monster my arm goes in the direction Iâm looking too and if its above me I point at its feet. The direction is the right one though.
@normen said: Yeah, when I point at the monster my arm goes in the direction I'm looking too and if its above me I point at its feet. The direction is the right one though.
Is the monster the light in this metaphor? Or are we the light? I may have misunderstood.
The javadoc is currently wrong. It says it points to the light source but it actually points the opposite.
@pspeed said: Is the monster the light in this metaphor? Or are we the light? I may have misunderstood.The javadoc is currently wrong. It says it points to the light source but it actually points the opposite.
This is what the javadoc says:
DirectionalLight (main description)
âDirectionalLight is a light coming from a certain direction in world space. E.g sun or moon light.
Directional lights have no specific position in the scene, they always come from their direction regardless of where an object is placed.â
then for setDirection:
âSets the direction of the light. Represents the vector direction the light is coming from. (1, 0, 0) would represent a directional light coming from the X axis.â
To me its pretty obvious the description is from the perspective of the object (which has the actual material that is doing stuff because of all this). Maybe we should keep it that way instead of implying the DirectionalLight has a source from where it could send something âtowardsâ something else.
@normen said: This is what the javadoc says: DirectionalLight (main description) "DirectionalLight is a light coming from a certain direction in world space. E.g sun or moon light. Directional lights have no specific position in the scene, they always come from their direction regardless of where an object is placed."then for setDirection:
âSets the direction of the light. Represents the vector direction the light is coming from. (1, 0, 0) would represent a directional light coming from the X axis.âTo me its pretty obvious the description is from the perspective of the object (which has the actual material that is doing stuff because of all this). Maybe we should keep it that way instead of implying the DirectionalLight has a source from where it could send something âtowardsâ something else.
And if you set direction to 1,0,0 which side of the object would you expect to be lit? Hint: itâs backwards from the above description.
The light has no source. It exists everywhere. It only is direction⌠the direction the beams are traveling. And thatâs how itâs actually implemented. A light with direction 0,-1,0 will light the top of your object⌠because the beams are traveling down, ie: y = -1
@pspeed said: And if you set direction to 1,0,0 which side of the object would you expect to be lit? Hint: it's backwards from the above description.The light has no source. It exists everywhere. It only is direction⌠the direction the beams are traveling. And thatâs how itâs actually implemented. A light with direction 0,-1,0 will light the top of your object⌠because the beams are traveling down, ie: y = -1
Exactly, thats why it canât travel âtowardsâ anything. But it can come from somewhere at the point of âimpactâ.
But I agree that if you stick slavishly to the grammar youâd expect it to come from the other side (but then the rest of the sentence makes no sense). I guess I implicitly âcorrectâ that by expecting that only one vector direction makes sense for light. Still, no âtowardsâ please.
@normen said: Exactly, thats why it can't travel "towards" anything. But it can come *from* somewhere at the point of "impact".But I agree that if you stick slavishly to the grammar youâd expect it to come from the other side. I guess I implicitly âcorrectâ that by expecting that only one vector direction makes sense for light. Still, no âtowardsâ please.
Yes, I think Iâve argued pretty vehemently so far that there is no âtowardsâ since there is nothing to be âtowardsâ.
There is only light⌠and it is traveling in a direction. Itâs not defined as surface-centric but âlightâ centric. So if you were to imagine a GUI widget of some kind representing the light in a 3D scene, the widget would point in the direction the light is traveling.
Given the confusion, I now think that the javadoc will need some visual aids. 
I suggest replacing âcoming fromâ with âshiningâ or âpropagatingâ. Something like:
* Represents the direction the light is shining.
* (1, 0, 0) would represent light shining in the +X direction.Iâve opened a new issue (#605).
@sgold said: I've opened a new issue (#605).
Thanks. Itâs the best way to keep this stuff from getting lost. Few people are ready to do the backflips necessary in the face of (probably multiple) existing work environments to make a single doc change⌠but often someone positioned properly will try to knock a bunch of these out at once. Itâs nice to have them indexed with the rest of the issues where they are easily found.