TransformControls: Derive from Controls.

[Mugen87]

Related issue: #29085

Description

Same as #29085.

This is a breaking change though. TransformControls was derived from Object3D so far which had pros and cons. You could add the controls directly to the scene to render the gizmo (the visual helpers) but the Object3D methods attach() and detach() were overwritten with control specific methods.

The new approach is conceptually cleaner and more consistent compared to all other controls. But since TransformControls is no 3D object anymore, developers must add the gizmo differently now. So instead of:

scene.add( controls );

It is now:

scene.add( controls.getGizmo() );

[Mugen87]

@mrdoob Are you okay with getGizmo()?

[Mugen87]

@arodic How does this change look to you?

[mrdoob]

getGizmo() is okay 👌

[mrdoob]

Actually, getHelper() would follow the current naming:
https://github.com/mrdoob/three.js/tree/dev/examples/jsm/helpers

[puxiao]

TransformControls.html

You forgot to delete these:

- <h3>[property:Object3D object]</h3>
- <p>
-	The 3D object being controlled.
- </p>

[Mugen87]

@puxiao Actually I had to restore some deleted docs. The camera property actually represents the camera whereas the object reference represents the object that is controlled by TransformControls.

The thing is TransformControls does not transform the camera so it makes sense when object points to the controlled 3D object and the scene's camera is saved in a separate reference.

[puxiao]

Rome wasn't built in a day.

By the way, you forgot to delete these:

docs/examples/en/controls/DragControls.html

    <h2>Methods</h2>

    <p>See the base [page:Controls] class for common methods.</p>

-    <h3>[method:undefined connect] ()</h3>
-    <p>
-        Adds the event listeners of the controls.
-    </p>

-    <h3>[method:undefined disconnect] ()</h3>
-    <p>
-        Removes the event listeners of the controls.
-    </p>

-    <h3>[method:undefined dispose] ()</h3>
-    <p>
-        Should be called if the controls is no longer required.
-    </p>

    <h2>Source</h2>

[puxiao]

@Mugen87 Will these PRs be released in r168?
I have prepared some Chinese translations, but have not submitted PR yet, waiting for your this PR.

[Mugen87]

I'd like to wait for at least one feedback (see #29146 (comment)) so the API change is approved. Hence, the change might not be included in r168.

[Mugen87]

It has been a month since the PR was filed so I'm going ahead and merge it so we can finish the migration to THREE.Controls.

Of course we can update the API at any point if things like getGizmo() or the connect/disconnect routines require changes.

[VegarRingdalAibel]

Updated from 167 to 169.
Got error when calling dispose(), error looks to be this:
https://github.com/mrdoob/three.js/blob/dev/examples/jsm/controls/TransformControls.js#L539-L544

Traverse was part of Object3D so dispose might need some changes. Unless Ive manged to overlook/mess something up.

[jacksontan]

Hi, how do you get the function getGizmo from controls? I cannot seem to see it in
https://threejs.org/docs/#examples/en/controls/TransformControls or https://threejs.org/docs/#api/en/extras/Controls

As the suggested comment, this code scene.add(controls) will break on r169 and suggestion is to use scene.add( controls.getGizmo() ); but cannot get the gizmo.

[VegarRingdalAibel]

[jacksontan]

ah right, thanks.