Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation of graphene_simd4x4f_vec4_mul() has notation issues #207

Open
ppaalanen opened this issue Jan 16, 2021 · 0 comments
Open

Documentation of graphene_simd4x4f_vec4_mul() has notation issues #207

ppaalanen opened this issue Jan 16, 2021 · 0 comments

Comments

@ppaalanen
Copy link

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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

2 participants