Improvement: Three parameters management

This suggest/request/need is about the parameters management in three library. This “Issue” is composed by three parts ( ah ah ah ), which are different but with the same underlying topic, that’s why i make a unique issue instead of three.

1. Lacking documentation

The last day i was searching some help in the threejs doc… and what was my surprise ! I was unable to known which value i could use for some parameters….

Me the last day, reading the doc:

Ok… this is a string… That look like an ugly enum, but i don’t known what are the enum values, damned ! Will i need to find it in the code ? Really ? 😭

Things like that are really common with the current documentation. For a lot of params, class members etc… it is impossible to known which values can be used, even if the type can be deduce ( note the deduced here ! ) by default parameters.

Some example here:

.blendDstAlpha

The tranparency of the .blendDst. Default is null.

Ok transparency is an floating point number between 0.0 and 1.0…

.customDistanceMaterial

Same as customDepthMaterial, but used with PointLight. Default is undefined.

Right, so… should i use a MeshDepthMaterial ?

.getPointsHoles ( divisions )

divisions -- The fineness of the result.

Get an array of Vector2s that represent the holes in the shape.

Should i send 1/3 ?
Etc…

Note that this is not a criticism of the big documentation about threejs ! This is more a question if is it possible to have somethings like below, and if not why is this wanted by documentation design ?

.getPointsHoles ( divisions )

divisions - [Floating point number] - The fineness of the result. Default is 0.0

Get an array of Vector2s that represent the holes in the shape.

2. Enums or not Enums

Sometimes, during development i need a threejs constante. I have some memory trouble so i can’t remember all of them, or other possibility in a range of values. And i won’t have an open windows over the documentation, i prefer use the smart auto-completion of my IDE which is designed for that !

But with threejs constant i can’t ! Is it possible to use some “real” enum like for a value in a set of values ?

Example:

In constant.js

export var UVMapping = 300;
export var CubeReflectionMapping = 301;
export var CubeRefractionMapping = 302;
export var EquirectangularReflectionMapping = 303;
export var EquirectangularRefractionMapping = 304;
export var SphericalReflectionMapping = 305;
export var CubeUVReflectionMapping = 306;
export var CubeUVRefractionMapping = 307;

usage:

if ( this.mapping !== CubeRefractionMapping ) return;

could become:

var Mapping = Object.freeze( {
    UV: 0, 
    CubeReflection: 1, 
    CubeRefraction: 2,
    EquirectangularReflection: 3,
    EquirectangularRefraction: 4,
    SphericalReflection: 5,
    CubeUVReflection: 6,
    CubeUVRefraction: 7
} );

usage:

if ( this.mapping !== Mapping.CubeRefraction ) return;

Notice here the numbering that start to 0 instead of use tricky(?) numbering. Because when we need to extend enum it will be easier for cases like this:

export var RepeatWrapping = 1000;
export var ClampToEdgeWrapping = 1001;
export var MirroredRepeatWrapping = 1002;  <= dude ! I need a new wrapping type
export var NearestFilter = 1003;
export var NearestMipMapNearestFilter = 1004;
export var NearestMipMapLinearFilter = 1005;
export var LinearFilter = 1006;
export var LinearMipMapNearestFilter = 1007;
export var LinearMipMapLinearFilter = 1008;  <= Or damned, i need a new filter type, i will need to increase all type bellow...
export var UnsignedByteType = 1009;
export var ByteType = 1010;
export var ShortType = 1011;
export var UnsignedShortType = 1012;

3. Please throw me away

This is my bigger problem with threejs library ! The inconsistency of error return.
Sometimes, i make mistakes 🙈 … But when i got the error this is absolutely not related to the root problem. And this is due to a real lack in parameters check !

One of the best error in my opinion is the NaN value get in spherical bounding box computation.
Ok i have NaN values that break the bounding box computation… But WHY have i NaN values ??? I will need to pass 2 hours ( ok maybe 10min but… ) to find the real cause.

This type of headache could be easily resolve, with a very big gain for the library and ( especially ) for users ! We just need to check params in ctor and setters ( in fact all methods where monkeys could send a banana, and yes i’m a monkey too ! ). This will have a little performance impact, but a huge impact in terme of stability and safety of the library. The only part where this should be avoid are core types, and methods in render pipeline.

Earlier an error is raise better is !

A good things could be to have a Validator class for commun error case like in LoaderSupport.

I hope I am clear in my comments, and that we can find a satisfactory outcome.

Author: Fantashit

1 thought on “Improvement: Three parameters management

  1. 1. Documentation

    One feature that is easy to miss, you can mouse over most parameters to learn their type:

    parameter tooltip screencap

    I agree it would be great to provide something more obvious and easier to read. Maybe that can be done just using some tweaks to the website rendering? There are also options like documentation.js, but I don’t know that it would be necessary here.

    2. Typings and constants

    There are some projects that provide three.js autocomplete for popular editors, like https://github.com/blackjk3/threejs-sublime. Do you know why this doesn’t work in your editor? I’m not sure I understand how your suggestions would make autocomplete start working in editors where it currently doesn’t?

    3. Performance, return types, validation, etc.

    Always good to hear specific ideas for making three.js easy to use, thanks.

    Checking for NaN and returning an error unfortunately can and will have high performance costs on some critical methods.. maybe there are some specific methods where it’s OK, but it can’t be done everywhere — especially in the Math code.

    Would be curious what features you would like for a Validator class?

Comments are closed.