Three.js: LinearMipMapNearestFilter naming confusion

[makc]

So, the code in webgl renderer says this:

if ( p === THREE.LinearMipMapNearestFilter ) return _gl.LINEAR_MIPMAP_NEAREST;

and here we have this:

GL_LINEAR_MIPMAP_NEAREST
Chooses the mipmap that most closely matches the size of the pixel
being textured and uses the GL_LINEAR criterion
(a weighted average of the four texture elements that are closest
to the center of the pixel)
to produce a texture value.

sounds like what I would expect from THREE.NearestMipMapLinearFilter ?

[makc]

So maybe to both address this and maintain compatibility, make another names LinearFilterNearestMipMap = current LinearMipMapNearestFilter and deprecate current names?

[mrdoob]

Hmmm, I'm a bit confused. What would be the resulting list of options?

[WestLangley]

What would be the resulting list of options?

THREE.NearestFilter              => _gl.NEAREST;
THREE.NearestFilterNearestMipMap => _gl.NEAREST_MIPMAP_NEAREST;
THREE.NearestFilterLinearMipMap  => _gl.NEAREST_MIPMAP_LINEAR;

THREE.LinearFilter               => _gl.LINEAR;
THREE.LinearFilterNearestMipMap  => _gl.LINEAR_MIPMAP_NEAREST;
THREE.LinearFilterLinearMipMap   => _gl.LINEAR_MIPMAP_LINEAR;

I am on the fence regarding this one. I think these proposed names are better, but the nomenclature of the webGL spec is well-documented.

[benaadams]

I think the confusion arises because of the addition of Filter on the end of them all currently designating a filter:

THREE.NearestFilter              => THREE.NearestFilter              => _gl.NEAREST;
THREE.NearestMipMapNearestFilter => THREE.NearestFilterNearestMipMap => _gl.NEAREST_MIPMAP_NEAREST;
THREE.NearestMipMapLinearFilter  => THREE.NearestFilterLinearMipMap  => _gl.NEAREST_MIPMAP_LINEAR;
THREE.LinearFilter               => THREE.LinearFilter               => _gl.LINEAR;
THREE.LinearMipMapNearestFilter  => THREE.LinearFilterNearestMipMap  => _gl.LINEAR_MIPMAP_NEAREST;
THREE.LinearMipMapLinearFilter   => THREE.LinearFilterLinearMipMap   => _gl.LINEAR_MIPMAP_LINEAR;

[WestLangley]

Thinking outside the box...

THREE.NearestPixel               => _gl.NEAREST;
THREE.NearestPixelNearestMipMap  => _gl.NEAREST_MIPMAP_NEAREST;
THREE.NearestPixelLinearMipMap   => _gl.NEAREST_MIPMAP_LINEAR;

THREE.LinearPixel                => _gl.LINEAR;
THREE.LinearPixelNearestMipMap   => _gl.LINEAR_MIPMAP_NEAREST;
THREE.LinearPixelLinearMipMap    => _gl.LINEAR_MIPMAP_LINEAR;

[makc]

I don't care much about naming style as long as it is clear what it implicates. The 2nd part was just to preserve existing names for backwards compatibility (but remove them from examples/docs)

[makc]

I think the confusion arises because of the addition of Filter on the end of them all currently designating a filter

yes, I was mentally decomposing LinearMipMapNearestFilter into "Linear MipMap, Nearest Filter", not in "LINEAR_MIPMAP_NEAREST Filter". if it was THREE.LINEAR_MIPMAP_NEAREST, I would just look up what it does straight away, without guessing from the name.

[crobi]

A filter is a very generic concept. Both wikipedia and the opengl wiki describe mipmapping as part of the texture filtering process. "Filtering" is therefore not limited to the interpolation of texels within one texture level.

So "Linear MipMap, Nearest Filter" is probably not a very good name. I'd either keep the current names or use what @WestLangley proposed (maybe replace Pixel with Texel?)

[WestLangley]

If there is motivation to change it, I would vote for this pattern:

THREE.NearestPixelNearestMipMap

[mrdoob]

I don't care much about naming style as long as it is clear what it implicates.

That means that you care about the naming ;)

Hmmm, as I can see in the gl spec, those are "minifying functions" and not "filters".

[crobi]

Hmmm, as I can see in the gl spec, those are "minifying functions" and not "filters".

The spec seems to use both. The names of the respective glTexParameter parameters are GL_TEXTURE_MIN_FILTER and GL_TEXTURE_MAG_FILTER, using the term "filter". The description on the other hand uses the expression "texture minifying/magnifying function". The way I see it, "filter" usually refers to the whole texture minifying/magnifying function, and not to the part that interpolates between texels. That's why I wouldn't use what @makc was proposing.

[benaadams]

Naming things is NP-hard :)

How about Interpolation and always referencing the MipMap?

THREE.NearestInterpolationMipMapNone     => _gl.NEAREST;
THREE.NearestInterpolationMipMapNearest  => _gl.NEAREST_MIPMAP_NEAREST;
THREE.NearestInterpolationMipMapLinear   => _gl.NEAREST_MIPMAP_LINEAR;

THREE.LinearInterpolationMipMapNone      => _gl.LINEAR;
THREE.LinearInterpolationMipMapNearest   => _gl.LINEAR_MIPMAP_NEAREST;
THREE.LinearInterpolationMipMapLinear    => _gl.LINEAR_MIPMAP_LINEAR;

[WestLangley]

@benaadams The problem with using MipMapNone is that _gl.NEARESTand _gl.LINEAR are used for magnification, too, in which case having MipMap in the name does not make any sense.

[makc]

@WestLangley remember you can have 2 constant names with same values.

[WestLangley]

@makc In that case, we could do this

THREE.NearestPixel               => _gl.NEAREST;
THREE.NearestPixelNoMipMap       => _gl.NEAREST;
THREE.NearestPixelNearestMipMap  => _gl.NEAREST_MIPMAP_NEAREST;
THREE.NearestPixelLinearMipMap   => _gl.NEAREST_MIPMAP_LINEAR;

THREE.LinearPixel                => _gl.LINEAR;
THREE.LinearPixelNoMipMap        => _gl.LINEAR;
THREE.LinearPixelNearestMipMap   => _gl.LINEAR_MIPMAP_NEAREST;
THREE.LinearPixelLinearMipMap    => _gl.LINEAR_MIPMAP_LINEAR;

As I said, I am on the fence on this one.

[EliasHasle]

I agree that the current names (and those in GL) are confusing. I do not have a strong opinion on which alternative naming is better. I would, however, like to add that if these constants are to be renamed soon, that will be an opportunity to correct the inconsistency of capital 'M' in "Map" in "MipMap". In Texture, there is an option generateMipmaps with lower-case 'm'. Of course, that may be up for correction instead. Anyway, since that case mistake is so easy to make (and not always as easy to debug), maybe one should have aliases, at least on the constants.

[mrdoob]

@WestLangley should this one be closed now?

[EliasHasle]

The lower case confusion was a separate matter (not intending to answer for West).

Quoting West (still not intending to answer Ricardo's question):

I am on the fence regarding this one. I think these proposed names are better, but the nomenclature of the webGL spec is well-documented.

It may be well-documented, but I have to check the docs every time I use the constants, and I doubt I am alone. Three.js is really good at protecting users from the difficulties of WebGL, and this renaming/aliasing would improve user experience by being more intuitive (and optionally more flexible). So I guess I am off the fence, supporting West's latest suggestion (from my own user perspective).

[WestLangley]

Hmm... since there has been no groundswell of requests for a nomenclature change, I think I would leave things as-is and improve the docs if needed. Just my opinion.

[Mugen87]

Hmm... since there has been no groundswell of requests for a nomenclature change, I think I would leave things as-is and improve the docs if needed. Just my opinion.

Sounds good! Closing for now.