Documentation of graphene_simd4x4f_vec4_mul() has notation issues

[Pekka Paalanen]

https://ebassi.github.io/graphene/docs/graphene-SIMD-matrix.html#graphene-simd4x4f-vec4-mul says:

void
graphene_simd4x4f_vec4_mul (const graphene_simd4x4f_t *a,
                            const graphene_simd4f_t *b,
                            graphene_simd4f_t *res);

Left multiplies the given graphene_simd4x4f_t with the given graphene_simd4f_t row vector using a dot product:

res = b × A

    = ⎡x⎤ ⎛ x.x  x.y  x.z  x.w ⎞
      ⎜y⎟ ⎜ y.x  y.y  y.z  y.w ⎟
      ⎜z⎟ ⎜ z.x  z.y  z.z  z.w ⎟
      ⎣w⎦ ⎝ w.x  w.y  w.z  w.w ⎠

    = [ x.x × x   x.y × x   x.z × x   x.w × x ]
           +         +         +         +
      [ y.x × y   y.y × y   y.z × y   y.w × y ]
           +         +         +         +
      [ z.x × z   z.y × z   z.z × z   z.w × z ]
           +         +         +         +
      [ w.x × w   w.y × w   w.z × w   w.w × w ]

    = ⎡ x.x × x + y.x × y + z.x × z + w.x × w ⎤
      ⎜ x.y × x + y.y × y + z.y × z + w.y × w ⎟
      ⎜ x.z × x + y.z × y + z.z × z + w.z × w ⎟
      ⎣ x.w × x + y.w × y + z.w × z + w.w × w ⎦

This has a problem with the notation. The text says b is a row vector, but in the formula it is written as a column vector.

If fact, this expression

    = ⎡x⎤ ⎛ x.x  x.y  x.z  x.w ⎞
      ⎜y⎟ ⎜ y.x  y.y  y.z  y.w ⎟
      ⎜z⎟ ⎜ z.x  z.y  z.z  z.w ⎟
      ⎣w⎦ ⎝ w.x  w.y  w.z  w.w ⎠

cannot be calculated at all. It is a little like trying to calculate the result of a binary operation by giving just one and a half operands. See e.g. https://www.mathsisfun.com/algebra/matrix-multiplying.html for how vector/matrix multiplication normally works.

If we fix the vector layout:

             ⎛ x.x  x.y  x.z  x.w ⎞
             ⎜ y.x  y.y  y.z  y.w ⎟
[ x y z w ]  ⎜ z.x  z.y  z.z  z.w ⎟
             ⎝ w.x  w.y  w.z  w.w ⎠

This is something we can calculate, because now the "inner dimensions" of the multiplication match, that is, the number of columns on the left hand operand equals the number of rows on the right hand operand. When calculating this according to the normal matrix multiplications rules, the end result is the transpose of the final result in the documentation:

    = [ x.x × x + y.x × y + z.x × z + w.x × w,  x.y × x + y.y × y + z.y × z + w.y × w,  x.z × x + y.z × y + z.z × z + w.z × w, x.w × x + y.w × y + z.w × z + w.w × w ]

It is a row vector, not a column vector like typeset in the documentation. Yes, it's hard to read like this, maybe you can use transpose operator to type out the transpose of the vector instead of the vector itself.

The intermediate form

    = [ x.x × x   x.y × x   x.z × x   x.w × x ]
           +         +         +         +
      [ y.x × y   y.y × y   y.z × y   y.w × y ]
           +         +         +         +
      [ z.x × z   z.y × z   z.z × z   z.w × z ]
           +         +         +         +
      [ w.x × w   w.y × w   w.z × w   w.w × w ]

could be left out in my opinion, for me it was only confusing.

Summary:

• a row vector should be typeset as a row, not a column
• maybe drop the intermediate form
• mentioning dot product is unnecessary, because that's how matrix multiplication works anyway