Documentation for which materials can be applied to which objects

The documentation for Line, LineSegments, Mesh, and Points don’t specify which materials those objects are allowed to be created with. It seems from the names of materials that materials beginning with Mesh (e.g. MeshBasicMaterial, MeshDepthMaterial, MeshLambertMaterial, MeshNormalMaterial, MeshPhongMaterial, MeshPhysicalMaterial, MeshStandardMaterial, and MeshToonMaterial) should only be applied to Meshs, materials beginning with Line (e.g. LineBasicMaterial and LineDashedMaterial) should only be applied to Line and LineSegments, and PointsMaterial should only be applied to Points. Is it correct that only a certain subset of materials should be applied to certain objects? If this is the case, can that be documented in the documentation or code? I’m fine with making the PR to update the documentation if that’s the case, but I thought I should ask if this is the case first. (The reason for this issue is because of the discussion started here: DefinitelyTyped/DefinitelyTyped#27413).

Author: Fantashit

2 thoughts on “Documentation for which materials can be applied to which objects

  1. Is there ever a case where any of the materials could be used with objects of a type that’s not in their name? I.e. is there ever a time when you might want to use a PointsMaterial with a line or something similar?

    If not then I think that the material’s names are sufficient documentation.

  2. It might be stating the obvious, but we have to decide in the TypeScript definitions whether or not the object constructors should accept any type of Material or whether it should restrict them to accepting only the materials it is “obvious” for them to accept. Obviously for someone using this library in JavaScript it doesn’t matter one way or the other. However, the point of the TypeScript definitions is to define which types should be allowed and which types should not as to avoid any misuse of the library. That way if someone passes a MeshBasicMaterial into a Sprite, the compiler can warn the user that they’re probably doing something they weren’t intending to do. So three.js might not throw an error when a mesh material is passed into Points, but if it doesn’t render the Points (doesn’t work as intended), then TypeScript should restrict the user from making that mistake if possible.

    All that to say, we have to make a decision in the TypeScript definitions whether or not to restrict the types of materials in object constructors. And the lack of documentation and self-evident code makes it hard to prove that the types of these materials should be restricted. Some people do not find the current naming convention to be sufficient documentation and sometimes stating what may seem obvious is necessary especially when writing code. Unless you’re opposed to the idea, I plan on making a PR to add it to the documentation to clarify the situation.

Comments are closed.