ImmediateRenderObject: Clarify implementation.

[Mugen87]

This PR slightly clarifies the implementation of ImmediateRenderObject by:

• Improving the docs.
• Add all properties to ImmediateRenderObject which are expected by WebGLRenderer.

[gkjohnson]

Awesome to see the docs get updated for this! I still don't understand at all how to use this class, though. When should I consider using it? Is it only for per frame generated geometry? Is it always faster than the built in Mesh? If so then why would I not always use it? Is the vertex information reuploaded every frame?

An inline example or some pseudocode would really help here, too.

Just a few things that come to mind for future improvements!

[Mugen87]

I think the marching cubes example nicely demonstrate its purpose. It's a low level interface for generating geometry data per frame.

Is it always faster than the built in Mesh?

Yes, assuming you are updating the geometry data per frame. Let me clarify this point in the docs.

If so then why would I not always use it?

I think the docs should now answer this question: Because many built-in features like view frustum culling are not supported.

Is the vertex information reuploaded every frame?

Yes.

[sciecode]

This is very useful, thank you Mugen87.

I have considered using this for a number of GPGPU experiments, but I've struggled to understand the actual workflow for using it, so ended up giving up on the idea. What happens to light uniforms, do they still need to be calculated and sent to the shader? If so, is there a workflow that avoids it?

[Mugen87]

What happens to light uniforms, do they still need to be calculated and sent to the shader? If so, is there a workflow that avoids it?

Material related stuff is unrelated to ImmediateRenderObject. So it's not possible to bypass any shader/uniform logic when using this class.

[gkjohnson]

@Mugen87

I think the docs should now answer this question: Because many built-in features like view frustum culling are not supported.

I think after the update it's a bit more clear -- it would only be faster for frequently updated / dynamically generated meshes. I shouldn't use it otherwise.

I think the marching cubes example nicely demonstrate its purpose. It's a low level interface for generating geometry data per frame.

I've looked through that example before and did see that it uses ImmediateRenderObject -- it's a bit of a heavy example to dig through to understand but it does make a little more sense with these updates. It's still not really enough to confidently get started implementing something with the class, though. The renderCallback behavior is still unclear to me. It's not documented why a callback is passed in rather than the renderer just rendering the object after it's ready. A callback makes me think this function can be called later / in an async fashion but certainly that's not the case? It also looks like it takes no arguments and should only get called once at the end of the render function but skimming over the MarchingCubes example it looks like it can get called multiple times and should be called with this as an argument. Does calling renderCallback render the current state of the object so multiple draw calls can be issued per render? I appreciate you putting in the time to make this more understandable!

I do feel it would be helpful to have a code snippet to demonstrate how set the object up like almost every other docs page has but I'm not sure what a simple function body might look like to demonstrate its use:

var material = new THREE.MeshStandardMaterial( { color: 0xffff00 } );
var renderObject = new THREE.ImmediateRenderObject( material );
renderObject.render = function( renderCallback ) {

  // ... create / update hasPositions, positionArray, count, etc
  renderCallback( this ); 

}
scene.add( mesh );

@sciecode

I have considered using this for a number of GPGPU experiments

How might you use this for GPGPU work? It seems like this is specifically for data being generated in javascript?

[Mugen87]

Let's enhance the doc page with a subsequent PR. TBH, I wanna get this quickly merged in order to have one progress save.

[sciecode]

How might you use this for GPGPU work? It seems like this is specifically for data being generated in javascript?

Truth be told, I didn't know exactly how it worked.

But I was hopeful it would avoid plenty of unnecessary stuff that is, more or less, required in the regular workflow. Namely, I don't really need frustum culling, wireframe, morthtargets, normals, backgrounds, instancing, dynamic draw range. Since CPU bottleneck is very apparent for GPGPU workflow in three.js, I thought that it could help.

However, I do use vertex data for texture look-up coordinates. Which is used in the vertex-shader for getting vertex positions, velocity, etc.. from textures. Although I don't usually change this dynamically too often.

[mrdoob]

Thanks!