Three.js: Notes on Legacy Geometry

[WestLangley]

r100 has been mentioned as the target release for removing support for rendering THREE.Geometry.

That means you can instantiate an instance of THREE.Geometry, but you will have to convert it to THREE.BufferGeometry prior to adding it to the scene.

By my notes, the remaining examples where Geometry is rendered are webgl_materials.html and svg_sandbox.html. I believe in all other examples where Geometry is used, Geometry is instantiated, but not rendered.

Also, to do is #14608 -- an important one.

I would also suggest renaming THREE.Geometry to THREE.LegacyGeometry.

At some point, THREE.BufferGeometry can become THREE.Geometry, but that would be in the distant future.

[Mugen87]

THREE.Geometry is an integral part of THREE.Octree. After analyzing the code today, I think it's better to remove THREE.Octree and both related examples for now and refer instead to the originial repository right here: https://github.com/collinhover/threeoctree

In general, I don't like the fact that code like THREE.Octree or THREE.OBJLoader2 resides in two repositories. IMHO, I think it's better to have a single repo and avoid to mirror the code into three.js. Especially if the code is non-trivial and the original developers do not provide support anymore. The current recommended release for THREE.Octree is R60 :expressionless:.

[WestLangley]

I think it's better to remove THREE.Octree and both related examples for now

/ping @mrdoob Is that OK with you?

[Mugen87]

side note^^: webgl_materials.html and svg_sandbox.html use BufferGeoemtry now.

[aardgoose]

Presumably DirectGeometry is also being deprecated.
Will all the fromGeometry() and fromDirectGeometry() code be removed from BufferGeometry

[Mugen87]

The conversion between both geometry types should still be possible. So we still need BufferGeometry.fromGeometry(), Geometry.fromBufferGeometry() and thus DirectGeometry.

The next step is to stop rendering Geometry. At some point, it's not valid to have Geometry entities in the scene graph anymore.

[aardgoose]

I understand the direction of these changes, it just leaves a lot of code in BufferGeometry that maybe could be moved elsewhere to avoid bloating builds that don't use Geometry.

[mrdoob]

I think it's better to remove THREE.Octree

/ping @mrdoob Is that OK with you?

Yep! We should remove Octree 👌

[Mugen87]

By my notes, the remaining examples where Geometry is rendered are webgl_materials.html and svg_sandbox.html.

webgl_modifier_subdivision is another one^^. Fixing...

[WestLangley]

r100 has been mentioned as the target release for removing support for rendering THREE.Geometry.

@mrdoob Do you want to remove the ability of the renderers to render Geometry in r100 or r101?

I would also suggest renaming THREE.Geometry to THREE.LegacyGeometry.

@mrdoob How do you feel about that? I would be inclined to do that now, in r100.

[mrdoob]

Lets leave it for r101 as it'll require a fair amount of testing.
Renaming to THREE.LegacyGeometry sounds good.

[Mugen87]

What about the geometry generators? Should we also rename them like so:

BoxGeometry → BoxLegacyGeometry

[looeee]

We now have examples divided into two sections with different naming schemes. These don't really make sense any more.
Actually they haven't for a while since we've been updating lots of the geometry / xyz examples to use BufferGeometry, but now is a good opportunity to unify these as well.

My vote would be to call them all geometry / xyz

webgl

geometry / colors
geometry / colors / lookuptable
geometry / convex
.etc

webgl / advanced

buffergeometry
buffergeometry / constructed / from / geometry
buffergeometry / custom / attributes / particles
buffergeometry / drawcalls

If breaking the links is something that people want to avoid, we should at least update the names.

[Mugen87]

Still trying to figure out how to proceed with the geometry generators. If we actually rename BoxGeometry to BoxLegacyGeometry, then BoxBufferGeometry could be renamed to BoxGeometry. In this case, we can finally have a single documentation page per generator. And all definitions of legacy classes would go to Three.Legacy.js.

The usage of BoxBufferGeometry could still be valid as an alias (without printing a warning). But code that relies on BoxGeometry would break of course. At least the migration effort is manageable (renaming to BoxLegacyGeometry).

[WestLangley]

As I suggested,

At some point, THREE.BufferGeometry can become THREE.Geometry, but that would be in the distant future.

[Mugen87]

I'm just not sure if renaming to Geometry to LegacyGeometry now makes sense. I think I would do this when BufferGeometry is renamed to Geometry.

The next step from my point of view is to stop rendering Geometry.

[mrdoob]

What do you guys think about creating these 3 new classes extending BufferGeometry?

THREE.MeshGeometry
THREE.LineGeometry
THREE.PointsGeometry

Benefits:

1. We can "hide" the BufferGeometry naming a little bit. Users will likely create a MeshGeometry directly.
2. We can warn the user when they're not using the right geometry/material pairs (ie. LineGeometry/LineMaterial).
3. We can convert from one to the other. We can use our current wireframe code to convert from MeshGeometry to LineGeometry.

In such case, we should probably rename the generators too:

THREE.BoxBufferGeometry > THREE.BoxMeshGeometry

[makc]

I bet MeshGeometry would grow to be equivalent of detested Geometry

[mrdoob]

@makc why?

[donmccurdy]

@mrdoob The node-based materials currently don't require mesh/line/point prefixes, e.g. StandardNodeMaterial. We could keep the prefixed material names for backward compatibility of course, but if materials didn't need the prefixes, would you still like the idea of adding matching prefixes to geometry? I don't think I have a preference.

^Disclaimer: I haven't tested points/lines with NodeMaterial yet. It's possible that's not implemented yet...

The conversion between both geometry types should still be possible. So we still need BufferGeometry.fromGeometry(), Geometry.fromBufferGeometry() and thus DirectGeometry.

Maybe Geometry.toBufferGeometry(), instead of BufferGeometry.fromGeometry() so that BufferGeometry will not depend on Geometry or DirectGeometry?

[looeee]

What do you guys think about creating these 3 new classes extending BufferGeometry?

At first glance, I like this idea. One thing I'm finding difficult to explain in a simple way while writing my book is the whole Geometry/BufferGeometry/Meshes/Lines/Points area and the way materials work or don't work in different cases.

It's definitely one of the main points of complexity for users at the moment, and moving some of that complexity under the hood to make the API easier to understand is something that I would like to see happen.

@donmccurdy I would personally support the idea of moving the prefixes from the materials to the geometry, especially since in my recent tests most of the MeshXXXMaterial seems to work fine with lines and points anyway.

Maybe Geometry.toBufferGeometry(), instead of BufferGeometry.fromGeometry() so that BufferGeometry will not depend on Geometry or DirectGeometry?

+1 for this.

[WestLangley]

in my recent tests most of the MeshXXXMaterial seems to work fine with lines and points anyway.

Really? Lines and points do not have normals.

[Mugen87]

Correct. In general, the usage of (mesh specific) lit materials in context of lines or points is invalid. Even unlit materials often have properties that make no sense for points/lines.

In any event, having MeshGeometry, LineGeometry and PointsGeometry seems a nice approach to me. I've seen this in other 3D libraries (like OpenSG) and it makes the handling of geometries more clear. But TBH, I have no feeling how much effort it takes to implement these classes. This might need some research.

@mrdoob How to do feel about renaming BufferGeometry to Geometry in one of the upcoming releases? (And Geometry to LegacyGeometry).

[makc]

@mrdoob in my eyes, Geometry was sort of intermediate representation between various format parsers and gpu - as opposed to 3js now, where you have every parser repeat the work and build those buffers themselves. if there will be MeshGeometry, it will be easier for people to make a case for de-duplicating parsers code again

[takahirox]

Maybe Geometry.toBufferGeometry(), instead of BufferGeometry.fromGeometry() so that BufferGeometry will not depend on Geometry or DirectGeometry?

+1. I prefer removing dependency on legacy stuffs.

[takahirox]

How will extended geometries exactly be? Currently users freely add/remove attributes to/from it. Will the extended geometries have some limitations, for example they must have position attributes, and [Line|Points]Geometry refuse to add normal attribute?

[aardgoose]

Geometry does not have any explicit type, and the current renderer relies on the type of the containing Obect3D to determine how to map to a Geometry to a BufferGeometry in BufferGeometry.fromObject().

Users won't be able to map from Geometry using BufferGeometry.fromGeometry() in the general case (it expects a mesh geometry) with the current API except for mesh geometries, so are left to their own devices for Lines and Points unless temporarily attaching the Geometry to a Points or Line etc which seems very ugly.

This suggests the something like Geometry.toPointsGeometry() .toLineGeometry() and .toMeshGeometry() are required which would align with the proposal for PointGeometry types etc, which would work alongside removing .fromObject() and fromGeometry().

Thoughts?

Is it worth coding these for the current release in advance of the rendering changes.