sixDofDragBehavior section in meshBehaviors.md is off

[sevaseva]

I tried to use https://doc.babylonjs.com/features/featuresDeepDive/behaviors/meshBehaviors to learn to use SixDofDragBehavior and briefly familiarize myself with some other mesh behaviors. Once I looked closely at https://doc.babylonjs.com/features/featuresDeepDive/behaviors/meshBehaviors#sixdofdragbehavior section, I found it all over the place.

I am returning to reading code to learn what I need to learn, but it seems harmful to have https://doc.babylonjs.com/features/featuresDeepDive/behaviors/meshBehaviors#sixdofdragbehavior section that pretends to be comprehensive but in fact is far from that. (i.e. some users won't look at the code and will miss out on the majority of the functionality)

Some specific issues:

• [ ] comment for sixDofDragBehavior.zDragFactor is copied from a wrong place
• [ ] various other public properties/settings of sixDofDragBehavior aren't documented
  • [ ] It seems that a better idea is to document those things in a lot more detail (than is typically done today) in jsdoc instead of writing dedicated explanations in featuresDeepDive pages. Then as long as a featuresDeepDive page has a link to class jsdoc page it will always keep itself reasonably up-to-date.
• [ ] playground example for SixDofDragBehavior paints stuff outside of the viewport and doesn't seem to demonstrate anything clearly
• [ ] playground example for MultiPointerScaleBehavior is the same as the one above; so it doesn't really demonstrate anything, certainly nothing about MultiPointerScaleBehavior
• [ ] after reading Note - To avoid large performance hits when using with models that have complex geometries, the object should be wrapped in a bounding box mesh. See [BoundingBoxGizmo.MakeNotPickableAndWrapInBoundingBox](https://doc.babylonjs.com/features/featuresDeepDive/mesh/gizmo) and then searching for MakeNotPickableAndWrapInBoundingBox on https://doc.babylonjs.com/features/featuresDeepDive/mesh/gizmo and reading all around there, I still don't understand how and why one would use BoundingBoxGizmo to improve performance when complex meshes and SixDofDragBehavior are involved.
  • [ ] https://doc.babylonjs.com/features/featuresDeepDive/mesh/gizmo#bounding-box-gizmo mentions gizmo.ignoreChildren = true and some performance gains, but never explains what it means to ignore children in that context

[CedricGuillemet]

@sevaseva

paints stuff outside of the viewport and doesn't seem to demonstrate anything clearly

by stuff, you mean the white ground? I'll just add #5G9MC5 with a comment saying it works for single or multipoint

I still don't understand how and why one would use BoundingBoxGizmo to improve performance when complex meshes and SixDofDragBehavior are involved.

I'll add a line for explanation on ray cast with triangles and ray/box intersection performance difference.

some performance gains, but never explains what it means to ignore children in that context

It sound obvious to me that ignoring children means less iteration and so performance gains. Maybe it justg need that phrase to make it clearer?

Then as long as a featuresDeepDive page has a link to class jsdoc page it will always keep itself reasonably up-to-date.

Is this what you expect @PatrickRyanMS ? Do you have a good example for that?

[sevaseva]

by stuff, you mean the white ground?

It looks like this.

That is literally all I see after reloading the page or pressing the "play" button to rerun the code. And that white thing moves slowly (without me touching keyboard or mouse). This reproduces intermittently, and seems to only (or more likely) reproduce once the meta immersive emulator extension (you can see its icon near the top right corner of my browser on the screenshot) is installed and activated in the session on that playground URL. What you see on the screenshot is not any immersive mode (you can tell because you see the "enter VR" button), but the meta's immersive emulator extension is active. This could be because of createDefaultVRExperience (VR, not XR, the old one) I suspect.

[sevaseva]

I'll add a line for explanation on ray cast with triangles and ray/box intersection performance difference.

That may be helpful but does not help one understand why and how: how and why one would use BoundingBoxGizmo.

In other words, what performance bottlenecks/issues may arise in what kinds of situations when the developer tries to do what in in what kind of scene, etc. (this helps answer the "why" question").

And then the how question. perhaps some example?...

[sevaseva]

That above may sound like a lot of text to write, but I'm just saying: when I read the current version of that docs article, I didn't get the point, didn't get the why. it may or may not be just me

[sevaseva]

It sound obvious to me that ignoring children means less iteration and so performance gains. Maybe it justg need that phrase to make it clearer?

i believe to me it wasn't clear exactly what isn't done to the children when gizmo.ignoreChildren = true is set. once that's not clear, why that unknown thing helps with (an unknown aspect of) performance is also not clear, and at that point I missed most of what author wanted to communicate in there. it may or may not be just me (c)

[PatrickRyanMS]

hen as long as a featuresDeepDive page has a link to class jsdoc page it will always keep itself reasonably up-to-date.

Is this what you expect @PatrickRyanMS ? Do you have a good example for that?

We don't really have a standard for how to reference the class docs, but what I typically do is to reference a specific class when it helps clarify something I am talking about. In the solid particles section on the second bullet, you can see I reference a class for more information, but we don't have a real pattern for how or when we reference it.

[CedricGuillemet]

by stuff, you mean the white ground?

It looks like this.

That is literally all I see after reloading the page or pressing the "play" button to rerun the code. And that white thing moves slowly (without me touching keyboard or mouse). This reproduces intermittently, and seems to only (or more likely) reproduce once the meta immersive emulator extension (you can see its icon near the top right corner of my browser on the screenshot) is installed and activated in the session on that playground URL. What you see on the screenshot is not any immersive mode (you can tell because you see the "enter VR" button), but the meta's immersive emulator extension is active. This could be because of createDefaultVRExperience (VR, not XR, the old one) I suspect.

This is weird. If you have a replay video, I suggest you to open an issue on the forum. I don't repro.

[sevaseva]

I might. (didn't do that right away simply because i don't have a working screen recorder installed on my machine; the Wayland support is still weak in the linuxland and I happen to be running that on most computers I have handy)

Regardless of the weird behavior some users might observe though, i thought the documentation needs to be updated anyway so it doesn't reference deeply deprecated VR (not XR) stack, or so I thought. Doing that should fix this issue I am observing as a side effect of the natural improvement of the documentation. Just a thought :shrug: