Godot-docs: Misleading and incomplete OpenSimplexNoise reference

[hazarek]

Your Godot version:
3.2.3rc3official

Issue description:
_Misleading information:_ Doc says the all ranges are in [-1,1], this is not true, I'll prove it.
_Missing information:_ There is no information about the min and max values ​​of the properties, only the following was written for octave;

Note: The maximum allowed value is 9.

URL to the documentation page:
https://docs.godotengine.org/en/latest/classes/class_opensimplexnoise.html

Values do not exceed the range [-0,8,0,8] (approximately) at normal settings. it becomes infinitive when the critical threshold is exceeded.(negative persistence)

If it exceeds the range [-1,1], the documentation is lying. Here I proved it, and More useful information about parameters should be given.

that is, you can never dynamically get the value -1 and 1 at runtime (not valid for textures, values stored in arrays can be normalized)

[Calinou]

Does negative persistence even make sense? If not, we should prevent setting a negative persistence at the engine level.

If it exceeds the range [-1,1], the documentation is lying

Documentation can be incorrect, but it doesn't intentionally lie. Please be mindful of your language and assume positive intent.

[hazarek]

Does negative persistence even make sense? If not, we should prevent setting a negative persistence at the engine level.

If it exceeds the range [-1,1], the documentation is lying

Documentation can be incorrect, but it doesn't intentionally _lie_. Please be mindful of your language and assume positive intent.

Sorry my English is not good. I am getting help from google translate. the solution is very simple;

1. It will be limited by the clamp () function at engine level.
2. the range of properties will be in reference description
3. and range limit is approximately [-0.8 0.8].

[NathanLovato]

I can confirm the noise generators seem to never produce values in [-1, 1] range. The actual range depends on the parameters, but it's smaller. We have had to write code to normalize the noise values in our Godot PCG demos.

[Omicron666]

Original author of Open Simplex has released new versions : https://github.com/KdotJPG/OpenSimplex2
From comparison image, we can see in original original implementation is far from using full range of intensity on rendered 2D noise picture. Thus probably not generating and using full range of [-1,1] values. (and apparently, neither uniformly distributed)

Also, from https://www.reddit.com/r/VoxelGameDev/comments/ee94wg/supersimplex_the_better_opensimplex_new_gradient/, there were actually already reports about [-1,1] range not fully used :

Range of output values
Finally, some users commented that the output values of OpenSimplex were further inside [-1, 1] than they would have preferred. So I used a gradient ascent solver to solve for the true maximum values of the noise functions, and normalized them accordingly. The area generators will deviate from this slightly, but I suspect that you will find the output of the evaluators to be very close to [-1, 1].

So it makes sense to detail documentation about that currently (un)expected behavior.
And maybe consider new implementations (for 4.0? ^^)

[Zylann]

I can confirm from a brute force test I did earlier that values never exceed -0.87 to 0.87.
As for the range of values, period is in ]0, +inf[, persistence is in [0, 1], octave is in [0, 8], seed is whatever int you want, and lacunarity is theoretically any float you want, but realistically keep it around [1, 5] to preserve precision (there is no point beyond that).
I'm surprised arguments were left unchecked.