Half-baked API (Camera position)

[Pavel Safrata]

Kevin, could you please share the reasons for changing your opinion?

For the pure 2D case the distance is now always 1. There are also the 
mixed cases - for instance parallel camera, 2D objects, Z translation - 
that we need to handle, and as it is, we sometimes need negative 
distances. Anyway, we know we want to re-think the numbers we're 
returning which makes them essentially a bug for now. We can just keep 
it in Jira which is what we usually do for bugs, but in this case 
backward compatibility comes to play, so trying to minimize the impact 
seems desirable. As Richard, I don't really see much harm in the 
exception, it would quite reliably drive people away from the unstable 
API (and whatever the method does, we are going to change it, so I don't 
see much difference between wrong value and temporary exception - except 
that the value might turn out to be what we want). But I'd be OK with a 
truthful documentation and a logged warning as well. Opinions?

Thanks,
Pavel

On 18.10.2013 20:56, Kevin Rushforth wrote:
> After chatting with Chien about this, and thinking about it a bit 
> more, I agree with Steve that we shouldn't throw an exception unless 
> we are certain that the concept of a distance just doesn't make sense 
> in parallel mode. If we were so convinced, then an exception (UOE or 
> ISE) would be fine. As it is, I think we can come up with something 
> sensible, if a bit arbitrary, for the pure 2D case -- parallel camera, 
> 2D objects, 2D transforms -- so I don't think we want to throw an 
> exception.
>
> -- Kevin
>
>
> Richard Bair wrote:
>> I don't see how returning something wrong is any different than 
>> throwing an exception from a compatibility perspective. Bugs are bugs.
>>
>> On Oct 16, 2013, at 3:46 PM, Kevin Rushforth 
>> <kevin.rushforth at oracle.com> wrote:
>>
>>> I can see your point. There are cases where it can make sense to 
>>> have a restriction now and relax it later, but this isn't exactly 
>>> that case. It's really more of a case of not being currently 
>>> implemented correctly in some modes.
>>>
>>> I guess the other option (which Pavel also mentioned) is to continue 
>>> to return something plausible, but not really correct, and file it 
>>> as a bug against FX 8.
>>>
>>> -- Kevin
>>>
>>>
>>> Stephen F Northover wrote:
>>>> Initial position:
>>>>
>>>> I don't really want to see any exception.  Throwing an exception is 
>>>> unexpected and should really be reserved for when something bad 
>>>> happens, not when we can't decide how an API works.  If the 
>>>> exception goes in, it's API and it stays forever.
>>>>
>>>> Steve
>>>>
>>>> On 2013-10-16 5:23 PM, Kevin Rushforth wrote:
>>>>> Steve: if Pavel throws IllegalStateException("not yet supported 
>>>>> for parallel camera") or similar, do you think that would be OK or 
>>>>> do you not want to see any exception?
>>>>>
>>>>> -- Kevin
>>>>>
>>>>>
>>>>> Kevin Rushforth wrote:
>>>>>> Would IllegalStateException be better here? Usually UOE is for 
>>>>>> operations that are simply not supported by the class in 
>>>>>> question. In this case, the operation is only unsupported if the 
>>>>>> camera on the scene (i.e., the state of an object) is of a 
>>>>>> certain type which can change at runtime.
>>>>>>
>>>>>> I'm OK either way, just want it to be a deliberate decision.
>>>>>>
>>>>>> -- Kevin
>>>>>>
>>>>>>
>>>>>> Pavel Safrata wrote:
>>>>>>> As I've said, we intend to fix it in the future, so the 
>>>>>>> situation should not be impossible. It is mostly used that way 
>>>>>>> in the existing code, but there definitely are precedents for 
>>>>>>> throwing it just temporarily. For instance:
>>>>>>>
>>>>>>> nodeOrientationProperty().getCssMetaData:
>>>>>>>        throw new UnsupportedOperationException("Not supported 
>>>>>>> yet.");
>>>>>>>
>>>>>>> or
>>>>>>>
>>>>>>> MeshView.impl_computeContains():
>>>>>>>        throw new UnsupportedOperationException("Not supported 
>>>>>>> yet.");
>>>>>>> (internal but directly accessible to users via contains())
>>>>>>>
>>>>>>> Pavel
>>>>>>>
>>>>>>> On 16.10.2013 20:10, Stephen F Northover wrote:
>>>>>>>> I took a quick look through JavaFX to find how this exception 
>>>>>>>> is used. It is mostly used to indicate impossible situation.  
>>>>>>>> Is that the situation we have here?
>>>>>>>>
>>>>>>>> Personally, for me, if we throw the exception, then we will 
>>>>>>>> generally just leave it that way forever.
>>>>>>>>
>>>>>>>> Steve
>>>>>>>>
>>>>>>>> On 2013-10-16 11:22 AM, Pavel Safrata wrote:
>>>>>>>>> On 16.10.2013 17:03, Stephen F Northover wrote:
>>>>>>>>>> Could do something useful with what was there now?  We can 
>>>>>>>>>> always fix this in future by adding another API to govern the 
>>>>>>>>>> interpretation of the value.
>>>>>>>>> Not much useful. Anyway, any such stuff can be quite easily 
>>>>>>>>> done by reading the intersectedPoint's Z coordinate.
>>>>>>>>>
>>>>>>>>>> Throwing the exception indicates that the call is 
>>>>>>>>>> unsupported, but application code can be written to catch the 
>>>>>>>>>> exception and when we implement the API, it can break (I 
>>>>>>>>>> realize that this is unlikely).
>>>>>>>>> The exception can tell by the message that the operation will 
>>>>>>>>> be supported in the future.
>>>>>>>>>
>>>>>>>>> Pavel
>>>>>>>>>
>>>>>>>>>> Steve
>>>>>>>>>>
>>>>>>>>>> On 2013-10-16 10:46 AM, Richard Bair wrote:
>>>>>>>>>>> My quick vote would be throwing the exception, but is like 
>>>>>>>>>>> to hear from Steve and Kevin.
>>>>>>>>>>>
>>>>>>>>>>>> On Oct 16, 2013, at 1:04 AM, Pavel Safrata 
>>>>>>>>>>>> <pavel.safrata at oracle.com> wrote:
>>>>>>>>>>>>
>>>>>>>>>>>> Hello,
>>>>>>>>>>>> it looks like we can't help releasing a not-fully-baked 
>>>>>>>>>>>> piece of API with FX8. We've added bunch of new APIs for 3D 
>>>>>>>>>>>> and did our best to make them work well. Unfortunately, 
>>>>>>>>>>>> there's been not enough time&priority to fine-tune their 
>>>>>>>>>>>> behavior in 2D world. Right now I'm concerned about camera 
>>>>>>>>>>>> position in scene. It is inherent in the 3D perspective 
>>>>>>>>>>>> camera that it has its specific position in world, but the 
>>>>>>>>>>>> 2D parallel camera as we have it projects everything to the 
>>>>>>>>>>>> XY plane basically by ignoring the Z coordinate, so the 
>>>>>>>>>>>> camera position doesn't matter all that much. However, some 
>>>>>>>>>>>> of the newly added APIs depend on it:
>>>>>>>>>>>>
>>>>>>>>>>>> 1. Near/far clip on camera. This obviously cannot work 
>>>>>>>>>>>> without knowing where the camera is. Right now the parallel 
>>>>>>>>>>>> camera does no clipping though, so I guess we are OK to go 
>>>>>>>>>>>> with it as a "known limitation".
>>>>>>>>>>>>
>>>>>>>>>>>> 2. PickResult on events which reports "intersectedDistance" 
>>>>>>>>>>>> between the camera and the picked point. This is worse 
>>>>>>>>>>>> because we can't just "not support" it - there will be some 
>>>>>>>>>>>> value and once somebody uses it we'll have a backward 
>>>>>>>>>>>> compatibility issue. The state right now is that the camera 
>>>>>>>>>>>> is (tentatively, by my arbitrary decision) at [0, 0, -1] 
>>>>>>>>>>>> and reports distances from there (note that as the camera 
>>>>>>>>>>>> renders everything, for nodes "in front of Z=-1" it reports 
>>>>>>>>>>>> negative distances). This may change when the camera 
>>>>>>>>>>>> position is properly discussed and specified.
>>>>>>>>>>>>
>>>>>>>>>>>> Note that this post is *not* meant to discuss the camera 
>>>>>>>>>>>> position. Even if we could find the answer quickly (which I 
>>>>>>>>>>>> doubt), it's most probably too late to apply the change for 
>>>>>>>>>>>> FX8.
>>>>>>>>>>>>
>>>>>>>>>>>> So finally here is my question: do you think it's OK to 
>>>>>>>>>>>> solve this by keeping the current behavior and documenting 
>>>>>>>>>>>> the "intersectedDistance" in a way that for parallel camera 
>>>>>>>>>>>> the numbers are unspecified and subject to change in future 
>>>>>>>>>>>> versions? Or would you prefer something more drastic like 
>>>>>>>>>>>> throwing an UnsupportedOperationException (losing the 
>>>>>>>>>>>> possibility to compare the distances)?
>>>>>>>>>>>>
>>>>>>>>>>>> Thanks,
>>>>>>>>>>>> Pavel
>>