THREE.Instances

[mrdoob]

I've been toying with this API recently.

var mesh = new THREE.Mesh( geometry, material );

var instances = new THREE.Instances( mesh );
instances.objects.push(
    new THREE.Object3D().setPosition( 1, 1, 1 ).setRotation( 0, 1, 0 ),
    new THREE.Object3D().setPosition( 2, 2, 2 ),
    new THREE.Object3D().setPosition( 3, 3, 3 ).setScale( 2, 1, 1 )
);
scene.add( instances );

Based on ANGLE_instanced_arrays. (~50%)

Thoughts?

[zz85]

👍 for instanced arrays.

However, I'm not sure about the instances.objects part though. Since instanced arrays are use to create eg 100k objects, don't think its a good idea to create 100k Object3D()s (the same reason behind BufferGeometry.

Rather,

var mesh = new THREE.Mesh( geometry, material );

var instances = new THREE.Instances( mesh );
instances.position = new Float32Array();
instances.rotation = new Float32Array();
instances.scale = new Float32Array();

scene.add( instances );

[zz85]

Also, I'm not sure how well is THREE.Instances( mesh ); going to play round with other types, eg.

new THREE.Instances( pointCloud );
new THREE.Instances( line );

Or whether it'd be better to do

var mesh = new THREE.InstancedMesh( geometry, material );
var pointCloud = new THREE.InstancedPointCloud( geometry, material );
var line = new THREE.InstancedLine( geometry, material );

scene.add( mesh );
scene.add( pointCloud );
scene.add( line );

...

[mrdoob]

However, I'm not sure about the instances.objects part though. Since instanced arrays are use to create eg 100k objects, don't think its a good idea to create 100k Object3D()s (the same reason behind BufferGeometry.

What about...

var instances = new THREE.Instances( mesh );
instances.matrices.push(
    new THREE.Matrix4().makeTranslation( 1, 1, 1 ),
    new THREE.Matrix4().makeTranslation( 2, 2, 2 ),
    new THREE.Matrix4().makeTranslation( 3, 3, 3 )
);
scene.add( instances );

[zz85]

hmm... i'm not sure if this make sense to me right now...

in @toji instanced monkey example, there are 3 elements - the positions for mesh instances, the individual positions, and individual colors.

so mesh position offsets maps to a geometry, and both positions and colors could be individual FloatArrays.

perhaps

monkey = new Geometry(); // usual geometry
material = new Material(); // could be the usual material or custom shader material
instances = new THREE.InstancedMesh( monkey, material, 10000 );

instances.addAttribute('color', 3);
instances.addAttribute('position', 3);

scene.add( instances )

?

[TheJim01]

What about...

var instances = new THREE.Instances( mesh );
instances.matrices.push(
    new THREE.Matrix4().makeTranslation( 1, 1, 1 ),
    new THREE.Matrix4().makeTranslation( 2, 2, 2 ),
    new THREE.Matrix4().makeTranslation( 3, 3, 3 )
);
scene.add( instances );

This would require instances.matricies and instances.materials to be the same length, which--if left to the user--might not always be the case. It might be more convenient to:

instances.addInstance( { matrix: new THREE.Matrix4().makeTranslation(1,1,1), material: new THREE.MeshBasicMaterial( { color: 'red' } ) } );

The API handles metadata allocation, and becomes a little more dynamic, allowing it to accept other fields.

[mrdoob]

Hmmm... I was thinking that THREE.Instances would have just one material for all the instances though.

[TheJim01]

I get what you're saying, and it makes sense. It avoids a bunch of headaches surrounding material sharing/instancing inside the instance array. If you have an instance array of green cubes, and want some of them to be red, it's easier to make another instance array of red cubes, and nothing is stopping me from re-using the geometry over again.

    var cube = new THREE.BoxGeometry( 5, 5 );
    var mesh1 = new THREE.Mesh( cube, new THREE.MeshBasicMaterial( { color: 'green' } ) );
    var instances1 = new THREE.Instances( mesh1 );
    instances1.matrices.push(
        new THREE.Matrix4().makeTranslation( 1, 1, 1 ),
        new THREE.Matrix4().makeTranslation( 2, 2, 2 ),
        new THREE.Matrix4().makeTranslation( 3, 3, 3 )
    );
    scene.add( instances1 );
    var mesh2 = new THREE.Mesh( cube, new THREE.MeshBasicMaterial( { color: 'red' } ) );
    var instances2 = new THREE.Instances( mesh2 );
    instances2.matrices.push(
        new THREE.Matrix4().makeTranslation( 4, 4, 4 ),
        new THREE.Matrix4().makeTranslation( 5, 5, 5 ),
        new THREE.Matrix4().makeTranslation( 6, 6, 6 )
    );
    scene.add( instances2 );

👍

[Baccanno]

Looking at the proposal I'm very more keen on something keeping same logic and syntax than the other mesh stuff.

Here I need to calculate manually my transform matrix but everything is ready in the Object3D class for manipulation object transformation ( and everyone knows how to ),
Would it be possible to perhaps do something like

    var cube = new THREE.BoxGeometry( 5, 5 );
    var mesh = new THREE.Mesh( cube , new THREE.MeshBasicMaterial( { color: 'green' } );
    var instance1 = new THREE.InstancedMesh( mesh );
    var instance2 = new THREE.InstancedMesh( mesh );

   myParentOnACliff.add( instance1 );
   instance1.rotation.x = Math.PI;

  myParentUnderTheSea.add( instance2 );
  instance2.position.setX( 50 );


   var mesh2 = new THREE.Mesh( cube , new THREE.MeshBasicMaterial( { color: 'red' } );
   for (var i = 0; i < 1000; ++i){
      myOtherParent.add( new THREE.InstancedMesh( mesh2 );
   }

Then when the instance is added under the hood we calculate the correct transform matrix.

This would add much more control over instances, so they can be moved, removed, switched from one parent to an other, well any scene graph use case without having to redo everything that's already done.

If I'm not wrong I understand that the proposal wants to keep objects in memory low, but It would be great to find a compromise between memory performances and usability.

[mrdoob]

You could do something like this:

var object1 = new THREE.Object3D();
object1.position.x = 10;

var object2 = new THREE.Object3D();
object2.rotation.x = 1.57;

var object3 = new THREE.Object3D();
object3.scale.x = 2;

var instances = new THREE.Instances( mesh );
instances.matrices.push(
    object1.matrix,
    object2.matrix,
    object3.matrix
);
scene.add( instances );

[Baccanno]

And updating the object3D matrices would work ?

[mrdoob]

Not initially... I'm looking at Object.observe() though.

[Baccanno]

Is this solution well suited for independently moving objects then ?

[mrdoob]

It kind of allows what you want to do and, at the same time, it can be memory efficient.

[Baccanno]

In order to get the parent transform of objects shouldn't we use .matrixWorld after calling updateMatrixWorld() ?

Then couldn't we have a instances.updateMatrices() ?

So the objects would use normal API and scene graph placement, and at each frame we would update the instanced matrices