add optionalTarget parameter to Raycaster.intersectObject(s) to allow array reuse

[ngokevin]

Description of the Problem

Allow optionalTarget for raycaster.intersectObject and raycaster.intersectObjects. This lets developers reuse array and reduce array instantiations.

For A-Frame/WebVR, an application often has two raycasters, one for each hand, updating up to 90 times a second. Two hands would have 180 raycaster intersects per second. So this could save 180 array instantiations per second for us.

[WestLangley]

This PR has implications for #12231.

[ngokevin]

Cool, that looks agreeable, I always try to pass in a target. Does this look good in the mean time so it can get picked up as part of that overhaul?

[WestLangley]

Can you please explain your use case? What is the compelling reason for this change?

[ngokevin]

We have raycasters that raycast frequently for a VR app (10 to potentially 90 times a second each). Saving unnecessary arrays will reduce GC and memory usage to increase performance. Not much different from wanting to save memory in the other optionalTarget-type patterns.

[WestLangley]

How are you clearing out the array between raycast calls so previous intersections are not sorted?

[ngokevin]

I'm using array.length = 0;

[ngokevin]

I can change the PR to automatically clear the optional target with array.length = 0.

[WestLangley]

Ugh... I was confused because Raycaster.intersectObject() calls intersectObject()-- a different function with the same name that, itself, is recursive.

I do not have a problem with this PR as written, but I'll defer to others. Thank you for the suggestion.

If this is merged, please update the docs.

[ngokevin]

I've updated the docs and made it clear the array/optional target if specified (since there's no reason not to clear the array).

r? @Mugen87

[mrdoob]

I think I would prefer if the clearing logic was in the application (ie. aframe) layer instead.

[ngokevin]

Updated to not clear the array automatically.

[ngokevin]

Merge conflicts fixed.

[WestLangley]

Instead of

Application is responsible for clearing this array on each call (e.g., array.length = 0;).

It may be more clear like so:

If set, you must clear this array prior to each call (e.g., array.length = 0;).

[ngokevin]

Updated the docs comment.

[WestLangley]

I think this is fine.

[mrdoob]

Thanks!