Three.js: customDepthMaterial and customDistanceMaterial are documented in the wrong place

[looeee]

https://threejs.org/docs/#api/en/materials/Material.customDepthMaterial

https://threejs.org/docs/#api/en/materials/Material.customDistanceMaterial

These are not properties of materials. As far as I can see from the couple of examples where they are used, they should be properties of Mesh, or perhaps Object3D.

By default, these properties are not initialised at all, even to undefined, and the only reference to them in the source is a couple of lines in WebGLShadowMap here:

https://github.com/mrdoob/three.js/blob/074290d3823ada31cade0c70c976be09213c99f9/src/renderers/webgl/WebGLShadowMap.js#L263-L278

Perhaps we could initialise them in Object3D as

function Object3D() {

    ... 

    this.customDepthMaterial = undefined;
    this.customDistanceMaterial= undefined;
    ...
}

and then document them correctly?

[pailhead]

That one was my bad. I wouldn't put them on Object3D though as many things extend from it that have no relationship to materials whatsoever (light, camera).

[looeee]

There's other cases in the library where things defined on the base class only work for some of the extended classes, so I'm not sure that's a problem.

For example on material we have material.dithering that only works for Lambert, Phong and Standard materials.

[Mugen87]

I would document customDepthMaterial and customDistanceMaterial in Mesh.html for now since casting shadows with points and lines is problematic, see https://github.com/mrdoob/three.js/issues/7738.

[pailhead]

Actually, would you consider the thought of keeping the doc on the material, and moving the prop to the material?

The base concept is that some of the stuff is shared, while the mesh has no idea about it.

class SomeMaterial {
   fragmentMain: 'glslThatDrawsColorLight',
   fragmentDepth: 'somePackingGLSL'
   vertexShaderBase: 'someVertTransformation',
   vertexShaderLights: 'glslForNormalsAndSuch'
}

Ie.

myMesh.material = myColorMaterial
myMesh.customDepthMaterial = myCustomDepthMaterial

vs

myColorMaterial.depth = myCustomDepth
myMesh.material = myColorMaterial

If you're applying the same material to N meshes, you don't have to set this twice.

As far as I can see from the couple of examples where they are used,

It's possible to use it in other examples, like displacement. If for some reason all the three.js examples had DOF, or shadows, this would have to be present in all of them.

[looeee]

Actually, would you consider the thought of keeping the doc on the material

The current API seems simpler, but I don't have any kind of strong opinion on this.

However, the documentation is currently incorrect and confusing so if this is going to take some time to work out, we should remove the current documentation in the meantime.

[Mugen87]

I vote to change the documentation like suggested here: https://github.com/mrdoob/three.js/issues/15449#issuecomment-448552384

This will reflect the current usage of both properties. I don't think the documentation should account for scenarios which are currently not supported by the renderer. Like I said before both properties make only sense for meshes. And customDistanceMaterial is only evaluated in context of PointLights.

[mrdoob]

I think it's okay to put it on Object3D and mention that only affects Mesh.