Proposal: Deprecate `sizeAttenuation` in favor of `sizeUnits`

[WestLangley]

Description

Objects in three.js are sized in world units, with the exception of Points and Sprites (and, in the examples, Fat Lines).

Points are sized in logical pixel units by default, and when rendered with a perspective camera only, they are sized in arbitrary units when sizeAttenuation is true.

Sprites are sized in world units by default, and when rendered with a perspective camera only, they are sized in arbitrary units when sizeAttenuation is false.

The above two statements are true for WebGLRenderer, and with #31627, likewise for WebGPURenderer.

Solution

I suggest a new API that is both less confusing and more flexible.

I propose we deprecate .sizeAttenuation in favor of a new property for Points or Sprites that specifies the size units as "world units" or "pixel units". This API has already been implemented for Fat Lines.

These units would be honored by both perspective and orthographic cameras.

This means that when Points or Sprites are rendered in a fixed size, the units are alway CSS (logical) pixels. Otherwise, the units are world units.

I think it is natural for Points to default to pixel units, and Sprites to default to world units -- the current standard. But it does not have to be that way. The default could be the same for both. In WebGPURenderer, Points and Sprites are becoming one and the same.

If the default is world units for both, an API like the following makes sense:

points.pixelUnits = true; // default is false

sprite.pixelUnits = true; // default is false

Another API, which may be better if they have different defaults, and may be better anyway:

points.sizeUnits = THREE.PixelUnits; // default

sprite.sizeUnits = THREE.WorldUnits; // default

Alternatives

Leave the API as-is to avoid a breaking change.

Additional context

No response

[sunag]

I liked it, it looks much clearer.