Clarify attribute indexing documentation

The current documentation around the indicesPerMaterial attribute is very confusing as many different terms are used interchangeably.

The Readme states that the indices can be used to index into the attribute component arrays such like

submeshIndices = indicesPerMaterial[0];
attributeIndex = submeshIndices[0];
vertices[attributeIndex];
normals[attributeIndex];
textures[attributeIndex];

However the attribute arrays themselves are flattened so that each element stores an attribute component rather than a vertex full attribute. Therefore to store information for a full vertex one must index the attribute arrays once for each component of the vertex attribute (so 3 times for a position and 2 times for a texture coordinate). But it isn’t clear which is the correct method of doing this either:

attributeIndex0 = submeshIndices[0];
attributeIndex1 = submeshIndices[1];
attributeIndex2 = submeshIndices[2];
Vector3 actualVertexPosition;
actualVertexPosition.x = vertices[attributeIndex0];
actualVertexPosition.y = vertices[attributeIndex1];
actualVertexPosition.z = vertices[attributeIndex2];

or

attributeIndex = submeshIndices[0];
Vector3 actualVertexPosition;
actualVertexPosition.x = vertices[attributeIndex];
actualVertexPosition.y = vertices[attributeIndex + 1];
actualVertexPosition.z = vertices[attributeIndex + 2];

I’m guessing the latter otherwise it wouldn’t work with attributes of different sizes, but that’s just my guess. The documentation should be clearer to specify which is correct.

What also doesn’t help is the naming of the vertices attribute which is in fact vertex positions and so should be named positions, but maybe I should make a separate issue for that?

[frenchtoast747]

Will do for adding a note on vertices being position.

I will also add the following snippet for correctly indexing the individual components on the JS side:

// there are 3 components for a geometric vertex: X, Y, and Z
const NUM_COMPONENTS_FOR_VERTS = 3;
elementIdx = mesh.indices[SOME_IDX]; // e.g. 38
// in order to get the X component of the vertex component of element "38"
elementVertX = mesh.vertices[(elementIdx * NUM_COMPONENTS_FOR_VERTS) + 0]
// in order to get the Y component of the vertex component of element "38"
elementVertY = mesh.vertices[(elementIdx * NUM_COMPONENTS_FOR_VERTS) + 1]
// in order to get the Z component of the vertex component of element "38"
elementVertZ = mesh.vertices[(elementIdx * NUM_COMPONENTS_FOR_VERTS) + 2]

which is doing roughly what the shader compiler does for you when you say vert.x, vert.y, vert.z.

And likewise, to iterate over the each vertex

for (let i = 0; i < mesh.vertices.length; i += 3) {
    const x = mesh.vertices[i];
    const y = mesh.vertices[i+ 1];
    const z = mesh.vertices[i + 2];
}

[frenchtoast747]

Hi @abcthomas, I have updated the README based on the points from the discussion here. Could you have a quick look at it and let me know what you think?

I used the same diagram but included an additional description underneath it that should hopefully describe the boxes and why X, Y, and Z are labeled with the 38th index.