SPS UVs documentation looks wrong

Bugs
1 
particle.uvs.x = 0.2; // left lower corner : 20% image width
particle.uvs.y = 0.1; // left lower corner : 10% image height
particle.uvs.z = 0.6; // right upper corner : 60% image width
particle.uvs.w = 0.3; // right upper corner : 30% image width

There are three problems with this.

  1. image width is used 3 times and image height is used 1 time. That has to be wrong.
  2. a single value is described as “left lower corner”. It is either the left or the lower, not both
  3. the order (xyzw) is not explained anywhere that I can find. And because of problem (1) and problem (2), one cannot discern what the values represent.

It also does not help that the examples are complicated.

The first example:
https://playground.babylonjs.com/#GLZ1PX#12
uses a complex faceUV command with the undocumented faceUV[i].scaleInPlace(2); command.
and then modifies the faceUV (already complicated unnecessarily) with the completely unexplained:

        particle.uvs.z = 0.5;
        particle.uvs.w = 0.5;

Suggestion 1:
Fix the first callout to be something like (I don’t actually know what is correct, so I am just guessing)

particle.uvs.x = 0.2; //  left starting at  20% image width
particle.uvs.y = 0.1; //  lower starting at 10% image height
particle.uvs.z = 0.6; // right ending at 60% image width
particle.uvs.w = 0.3; // upper starting at  30% image height

Suggestion 2:
This follows from suggestion 1. Define explicitly what ‘xyzw’ means and maybe mention why it is not ‘wxyz’. Which has to do with width? Which has to do with height?

1 Like
2

Thank you for drawing attention to this. First of all you are correct the last width should be a height and that there are some assumptions made, such as the reader will know that a vector4 has the form (x, y, z, w). It is always a difficult balance when writing a more advanced topic to know how much of the basics to put in, given that a reader may be very interested in a particular topic and want to jump straight in.

Also there are a combination of two topics in the example, face materials and particle uvs. The docs before the PG states

Model is a box with per face material, particles are direct copies of the model

The following is also then worth a read

Note that the PG you give an example from should be #13 not #12

That being said the docs do need correcting: regarding width; a diagram could be added to explain x, y, w, z; and a simpler example given that just uses particle uvs without faceUVs

I will see to it over the next day or two.

1 Like
3

Thanks for the additional information.

Personally, I have found it confusing to understand the relation between faceUV and .uvs on Solid Particle System objects.

I confess that I use trial and error mostly to get the results I want. For particles you have to use the uvs.x,y,z,w and for meshes you use uOffset, vOffset, uScale, vScale, uAngle, vAngle and wAngle.

And it is not clear to me what the relationship is between the various faces (from faceUV array) and the .uvs and of the uOffset, vOffset, uScale, vScale, uAngle, vAngle and wAngle.

In the inspector it refers to “UV set” with a slider. I can’t find any information on what that is.

I understand these are complex systems with a lot if different cases and there are limits. I just thought I would tell you what I have not been able to gleam from the documentation.

Thanks for all your hard work.

2 Likes
4

@trueshot SPS particle uvs docs now updated. Hope it is at least a little clearer Managing Solid Particles | Babylon.js Documentation

3 Likes
5

The explanation helps a great deal.

Thanks for all your efforts.

2 Likes