Docs: Clarify .lights property

[Mugen87]

Documents Material.lights just once in Material and not in other documentation pages. Also added a note so users consider this property as read-only except for ShaderMaterial and RawShaderMaterial.

Fixed #13896

[donmccurdy]

I didn't realize it was readonly for default materials. That's good to know. 😅

[WestLangley]

Documents Material.lights just once in Material and not in other documentation pages.

Why? The defaults are different.

[WestLangley]

I do not think you should be updating Chinese docs. We need to be consistent. Always update them -- or never update them, and let someone else do that.

[donmccurdy]

FWIW my preference would be to update the structure of the Chinese docs when we can (e.g. adding empty headers or removing sections), but leave others to fill in the translations. This way at least it is easy to see where translations are missing. But probably best to get their preference on how they'd prefer to track changes, they have a hard enough task as-is..

[Mugen87]

FWIW my preference would be to update the structure of the Chinese docs when we can (e.g. adding empty headers or removing sections), but leave others to fill in the translations.

Sounds good 👍 . Let me do it like this in future PRs.

Why? The defaults are different.

It's a bit unusual to document properties in derived classes again just because they have a different value. I've never seen this in a software project. And I think in this particular case, this information is not valuable for the user.

[WestLangley]

FWIW my preference would be to update the structure of the Chinese docs when we can (e.g. adding empty headers or removing sections), but leave others to fill in the translations.

I very much disagree with that. When we ask another contributor to update the docs for their PR, are we going to make sure to ask them to update the structure of the Chinese docs, too? I hope not.

[donmccurdy]

I agree that’s not necessary, but wouldn’t say it’s an argument do discourage others from updating the Chinese docs if they choose to.

[mrdoob]

Updating the chinese docs whenever possible sounds good to me. But it definitely won't scale if we start getting more languages.

As per the actual issue... I can't think of any reason why lights need to be in Material and not in ShaderMaterial...?

[Mugen87]

I can't think of any reason why lights need to be in Material and not in ShaderMaterial...?

WebGLRenderer uses material.lights at several places in order to distinct between lit and unlit materials e.g.:

three.js/src/renderers/WebGLRenderer.js

Lines 1521 to 1540 in 8b137e5

	if ( material.lights ) {
	// wire up the material to this renderer's lighting state
	uniforms.ambientLightColor.value = lights.state.ambient;
	uniforms.directionalLights.value = lights.state.directional;
	uniforms.spotLights.value = lights.state.spot;
	uniforms.rectAreaLights.value = lights.state.rectArea;
	uniforms.pointLights.value = lights.state.point;
	uniforms.hemisphereLights.value = lights.state.hemi;
	uniforms.directionalShadowMap.value = lights.state.directionalShadowMap;
	uniforms.directionalShadowMatrix.value = lights.state.directionalShadowMatrix;
	uniforms.spotShadowMap.value = lights.state.spotShadowMap;
	uniforms.spotShadowMatrix.value = lights.state.spotShadowMatrix;
	uniforms.pointShadowMap.value = lights.state.pointShadowMap;
	uniforms.pointShadowMatrix.value = lights.state.pointShadowMatrix;
	// TODO (abelnation): add area lights shadow info to uniforms
	}

[Mugen87]

@mrdoob Is it okay to merge this PR? I think the new description in docs/api/en/materials/Material.html is definitely an improvement.

[Mugen87]

Closing due to merge conflicts. If there is any interest in changing the description of Material.lights like suggested in this PR, I'll reopen and update it.

[looeee]

I think it's good practice to document when a property on the base class is overwritten by a derived class, so I don't support this change.