Half-baked API (Camera position)

[Stephen F Northover]

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
>>>>>>
>>>>>
>>>>
>>>