Why is `customDepthMaterial` documented to exist on Object3D?

The code isn’t quite clear: Object3D implementation has no occurrence of customDepthMaterial, but the documentation and the type declaration file both mention customDepthMaterial, yet these docs mention that the property is only for meshes.

So I have a couple questions:

  1. Why isn’t this property detailed as existing on Mesh, instead of Object3D?
  2. Why isn’t there a placeholder in the implementation, like with other properties?

My guesses:

  1. Because there are different types of meshes, like Mesh, Line, Points? So why not make a base class for all of those, so things are clear when looking at the implementation.
  2. Because by not explicitly placing the value it is already undefined by default? Why not just place it, even if explicitly set to undefined, so the code is clear?

Because it wasn’t documented at all for probably years and people must have been tired when it was approved. I made this doc edit, others approved it.

But you’re right about 1 i think this may have been in my head, but then it breaks others that dont cast shadows (like cameras, lights, helpers etc).

2 is just a pattern thats been present for years - there’s some magic property that no one knows about but thats super powerful and/or intrusive.

See https://github.com/mrdoob/three.js/pull/15490 for a similar approach. Because things are so locked and innacessible in renderers, you can do stuff like this.

Yeah, it’s like completely invisible until you scour through the renderer, but most people using Three at a high level are not likely to look in the renderer, but rather in the object implementations. At least it is documented now. :slight_smile:

And then there is customDistanceMaterial for PointLights which I just heard about for the first time yesterday trying to help some dude’s shadows with instanced geometry.

1 Like

Yes but i thought that too was documented (in the wrong place).

Maybe it could be a mixin, so that it can be applied to different classes (even if only props)? Such code would add some self-documentation, showing which classes need it.

Well… this is the one material that i totally wouldn’t object being created by the WebGLRenderer, unlike all the other materials. With replaceble chunks, or (sigh) nodes, the overlapping chunks (like vertex positioning) could just sample the chunks you provide.