## GimpVector

GimpVector — Utilities to set up and manipulate vectors.

## Synopsis

    struct      GimpVector2;
    struct      GimpVector3;
    struct      GimpVector4;
    GimpVector2 gimp_vector2_new                (gdouble x,
                                                 gdouble y);
    gdouble     gimp_vector2_inner_product      (const GimpVector2 *vector1,
                                                 const GimpVector2 *vector2);
    gdouble     gimp_vector2_inner_product_val  (GimpVector2 vector1,
                                                 GimpVector2 vector2);
    GimpVector2 gimp_vector2_cross_product      (const GimpVector2 *vector1,
                                                 const GimpVector2 *vector2);
    GimpVector2 gimp_vector2_cross_product_val  (GimpVector2 vector1,
                                                 GimpVector2 vector2);
    gdouble     gimp_vector2_length             (const GimpVector2 *vector);
    gdouble     gimp_vector2_length_val         (GimpVector2 vector);
    void        gimp_vector2_normalize          (GimpVector2 *vector);
    GimpVector2 gimp_vector2_normalize_val      (GimpVector2 vector);
    void        gimp_vector2_mul                (GimpVector2 *vector,
                                                 gdouble factor);
    GimpVector2 gimp_vector2_mul_val            (GimpVector2 vector,
                                                 gdouble factor);
    void        gimp_vector2_sub                (GimpVector2 *result,
                                                 const GimpVector2 *vector1,
                                                 const GimpVector2 *vector2);
    GimpVector2 gimp_vector2_sub_val            (GimpVector2 vector1,
                                                 GimpVector2 vector2);
    void        gimp_vector2_set                (GimpVector2 *vector,
                                                 gdouble x,
                                                 gdouble y);
    void        gimp_vector2_add                (GimpVector2 *result,
                                                 const GimpVector2 *vector1,
                                                 const GimpVector2 *vector2);
    GimpVector2 gimp_vector2_add_val            (GimpVector2 vector1,
                                                 GimpVector2 vector2);
    void        gimp_vector2_neg                (GimpVector2 *vector);
    GimpVector2 gimp_vector2_neg_val            (GimpVector2 vector);
    void        gimp_vector2_rotate             (GimpVector2 *vector,
                                                 gdouble alpha);
    GimpVector2 gimp_vector2_rotate_val         (GimpVector2 vector,
                                                 gdouble alpha);
    gdouble     gimp_vector3_inner_product      (const GimpVector3 *vector1,
                                                 const GimpVector3 *vector2);
    gdouble     gimp_vector3_inner_product_val  (GimpVector3 vector1,
                                                 GimpVector3 vector2);
    GimpVector3 gimp_vector3_cross_product      (const GimpVector3 *vector1,
                                                 const GimpVector3 *vector2);
    GimpVector3 gimp_vector3_cross_product_val  (GimpVector3 vector1,
                                                 GimpVector3 vector2);
    gdouble     gimp_vector3_length             (const GimpVector3 *vector);
    gdouble     gimp_vector3_length_val         (GimpVector3 vector);
    void        gimp_vector3_normalize          (GimpVector3 *vector);
    GimpVector3 gimp_vector3_normalize_val      (GimpVector3 vector);
    void        gimp_vector3_mul                (GimpVector3 *vector,
                                                 gdouble factor);
    GimpVector3 gimp_vector3_mul_val            (GimpVector3 vector,
                                                 gdouble factor);
    void        gimp_vector3_sub                (GimpVector3 *result,
                                                 const GimpVector3 *vector1,
                                                 const GimpVector3 *vector2);
    GimpVector3 gimp_vector3_sub_val            (GimpVector3 vector1,
                                                 GimpVector3 vector2);
    void        gimp_vector3_set                (GimpVector3 *vector,
                                                 gdouble x,
                                                 gdouble y,
                                                 gdouble z);
    GimpVector3 gimp_vector3_new                (gdouble x,
                                                 gdouble y,
                                                 gdouble z);
    void        gimp_vector3_add                (GimpVector3 *result,
                                                 const GimpVector3 *vector1,
                                                 const GimpVector3 *vector2);
    GimpVector3 gimp_vector3_add_val            (GimpVector3 vector1,
                                                 GimpVector3 vector2);
    void        gimp_vector3_neg                (GimpVector3 *vector);
    GimpVector3 gimp_vector3_neg_val            (GimpVector3 vector);
    void        gimp_vector3_rotate             (GimpVector3 *vector,
                                                 gdouble alpha,
                                                 gdouble beta,
                                                 gdouble gamma);
    GimpVector3 gimp_vector3_rotate_val         (GimpVector3 vector,
                                                 gdouble alpha,
                                                 gdouble beta,
                                                 gdouble gamma);
    void        gimp_vector_2d_to_3d            (gint sx,
                                                 gint sy,
                                                 gint w,
                                                 gint h,
                                                 gint x,
                                                 gint y,
                                                 const GimpVector3 *vp,
                                                 GimpVector3 *p);
    GimpVector3 gimp_vector_2d_to_3d_val        (gint sx,
                                                 gint sy,
                                                 gint w,
                                                 gint h,
                                                 gint x,
                                                 gint y,
                                                 GimpVector3 vp,
                                                 GimpVector3 p);
    void        gimp_vector_3d_to_2d            (gint sx,
                                                 gint sy,
                                                 gint w,
                                                 gint h,
                                                 gdouble *x,
                                                 gdouble *y,
                                                 const GimpVector3 *vp,
                                                 const GimpVector3 *p);

## Description

Utilities to set up and manipulate vectors.

## Details

### struct GimpVector2

    struct GimpVector2 {

      gdouble x, y;
    };

### struct GimpVector3

    struct GimpVector3 {

      gdouble x, y, z;
    };

### struct GimpVector4

    struct GimpVector4 {

      gdouble x, y, z, w;
    };

### gimp_vector2_new ()

    GimpVector2 gimp_vector2_new                (gdouble x,
                                                 gdouble y);

Creates a GimpVector2 of coordinate `x` and `y`.

`x` : | a gdouble used as first coordinate
`y` : | a gdouble used as second coordinate
Returns : | the resulting GimpVector2.

### gimp_vector2_inner_product ()

    gdouble     gimp_vector2_inner_product      (const GimpVector2 *vector1,
                                                 const GimpVector2 *vector2);

Computes the inner (dot) product of two 2D vectors. This product is nul iff the two vectors are orthognal.

`vector1` : | the first vector (by address),
`vector2` : | the second vector (by address).
Returns : | The inner product.

### gimp_vector2_inner_product_val ()

    gdouble     gimp_vector2_inner_product_val  (GimpVector2 vector1,
                                                 GimpVector2 vector2);

Computes the inner (dot) product of two 2D vectors. This product is nul iff the two vectors are orthognal.

`vector1` : | the first vector (by value),
`vector2` : | the second vector (by value).
Returns : | The inner product.

### gimp_vector2_cross_product ()

    GimpVector2 gimp_vector2_cross_product      (const GimpVector2 *vector1,
                                                 const GimpVector2 *vector2);

Compute the cross product of two vectors. The result is a vector (a GimpVector2) which is orthognal to both of vector1 and vector2. If vector1 and vector2 and parallel, the result will be the nul vector.

Note that in 2D, this function is mostly useful to test if two vectors are parallel or not, or to compute the area spawned by two vectors.

`vector1` : | the first vector (by address)
`vector2` : | the second vector (by address)
Returns : | The cross product.

### gimp_vector2_cross_product_val ()

    GimpVector2 gimp_vector2_cross_product_val  (GimpVector2 vector1,
                                                 GimpVector2 vector2);

This function is mainly another implementation of gimp_vector2_cross_product where the arguments are passed by value rather than by address.

`vector1` : | the first vector (by value)
`vector2` : | the second vector (by value)
Returns : | The cross product.

### gimp_vector2_length ()

    gdouble     gimp_vector2_length             (const GimpVector2 *vector);

Computes the length of a 2D vector.

`vector` : | a GimpVector2 (by address)
Returns : | the length of the given vector (a positive gdouble)

### gimp_vector2_length_val ()

    gdouble     gimp_vector2_length_val         (GimpVector2 vector);

Computes the length of a 2D vector.

`vector` : | a GimpVector2 (by value)
Returns : | the length of the given vector (a positive gdouble)

### gimp_vector2_normalize ()

    void        gimp_vector2_normalize          (GimpVector2 *vector);

Normalizes the vector pointed by the argument, so the length of the pointed vector will be 1.0 after this. The nul vector will not be changed, though.

`vector` : | a GimpVector2 (by address)

### gimp_vector2_normalize_val ()

    GimpVector2 gimp_vector2_normalize_val      (GimpVector2 vector);

Computes and returns the normalized vector corresponding with the one passed in argument.

`vector` : | a GimpVector2 (by value)
Returns : | a GimpVector2 parallel to `vector`, pointing in the same direction but with a length of 1.0.

### gimp_vector2_mul ()

    void        gimp_vector2_mul                (GimpVector2 *vector,
                                                 gdouble factor);

Multiplies each component of the `vector` by `factor`. Note that the vector's length will be multiplied by `factor`.

`vector` : | a GimpVector2 (by address)
`factor` : | a scalar

### gimp_vector2_mul_val ()

    GimpVector2 gimp_vector2_mul_val            (GimpVector2 vector,
                                                 gdouble factor);

Computes and returns a GimpVector2 pointing in the same direction than `vector`, but with a length multiplied by `factor`.

`vector` : | a GimpVector2 (by value)
`factor` : | a scalar.
Returns : | the resulting GimpVector2.

### gimp_vector2_sub ()

    void        gimp_vector2_sub                (GimpVector2 *result,
                                                 const GimpVector2 *vector1,
                                                 const GimpVector2 *vector2);

Computes the difference of two 2D vectors (`vector1` minus `vector2`). The result is stored in the GimpVector2 pointed by `result`.

`result` : | a placeholder for the resulting GimpVector2
`vector1` : | a GimpVector2 (by address)
`vector2` : | a GimpVector2 (by address)

### gimp_vector2_sub_val ()

    GimpVector2 gimp_vector2_sub_val            (GimpVector2 vector1,
                                                 GimpVector2 vector2);

Computes and returns the difference of two 2D vectors (`vector1` minus `vector2`).

`vector1` : | a GimpVector2 (by value)
`vector2` : | a GimpVector2 (by value)
Returns : | the resulting GimpVector2.

### gimp_vector2_set ()

    void        gimp_vector2_set                (GimpVector2 *vector,
                                                 gdouble x,
                                                 gdouble y);

Sets the first and second coordinates of `vector` to `x` and `y`.

`vector` : | a GimpVector2 (by address)
`x` : | a gdouble used as first coordinate
`y` : | a gdouble used as second coordinate

### gimp_vector2_add ()

    void        gimp_vector2_add                (GimpVector2 *result,
                                                 const GimpVector2 *vector1,
                                                 const GimpVector2 *vector2);

Computes the sum of two 2D vectors. The result is stored in the GimpVector2 pointed by `result`.

`result` : | a placeholder for the resulting GimpVector2
`vector1` : | a GimpVector2 (by address)
`vector2` : | a GimpVector2 (by address)

### gimp_vector2_add_val ()

    GimpVector2 gimp_vector2_add_val            (GimpVector2 vector1,
                                                 GimpVector2 vector2);

Computes and returns the sum of two 2D vectors.

`vector1` : | a GimpVector2 (by value)
`vector2` : | a GimpVector2 (by value)
Returns : | the resulting GimpVector2.

### gimp_vector2_neg ()

    void        gimp_vector2_neg                (GimpVector2 *vector);

Negates the `vector` (i.e. negate all its coordinates).

`vector` : | a GimpVector2 (by address)

### gimp_vector2_neg_val ()

    GimpVector2 gimp_vector2_neg_val            (GimpVector2 vector);

Computes and returns the negation of the `vector`.

`vector` : | a GimpVector2 (by value)
Returns : | the negated vector.

### gimp_vector2_rotate ()

    void        gimp_vector2_rotate             (GimpVector2 *vector,
                                                 gdouble alpha);

Rotates the `vector` by `alpha` radians, counterclockwize.

`vector` : | a GimpVector2 (by address)
`alpha` : | an angle (in radians)

### gimp_vector2_rotate_val ()

    GimpVector2 gimp_vector2_rotate_val         (GimpVector2 vector,
                                                 gdouble alpha);

Computes and returns the rotation of the `vector` by `alpha` radians, counterclockwize.

`vector` : | a GimpVector2 (by value)
`alpha` : | an angle (in radians)
Returns : | the `vector` rotated by `alpha` radians.

### gimp_vector3_inner_product ()

    gdouble     gimp_vector3_inner_product      (const GimpVector3 *vector1,
                                                 const GimpVector3 *vector2);

Computes the inner (dot) product of two 23 vectors. This product is nul iff the two vectors are orthognal.

`vector1` : | the first GimpVector3 (by address),
`vector2` : | the second GimpVector3 (by address).
Returns : | The inner product.

### gimp_vector3_inner_product_val ()

    gdouble     gimp_vector3_inner_product_val  (GimpVector3 vector1,
                                                 GimpVector3 vector2);

Computes the inner (dot) product of two 3D vectors. This product is nul iff the two vectors are orthognal.

`vector1` : | the first GimpVector3 (by value),
`vector2` : | the second GimpVector3 (by value).
Returns : | The inner product.

### gimp_vector3_cross_product ()

    GimpVector3 gimp_vector3_cross_product      (const GimpVector3 *vector1,
                                                 const GimpVector3 *vector2);

Compute the cross product of two vectors. The result is a GimpVector3 which is orthognal to both of vector1 and vector2. If vector1 and vector2 and parallel, the result will be the nul vector.

This function can be used to compute the normal of the plan defined by `vector1` and `vector2`.

`vector1` : | the first GimpVector3 (by address)
`vector2` : | the second GimpVector3 (by address)
Returns : | The cross product.

### gimp_vector3_cross_product_val ()

    GimpVector3 gimp_vector3_cross_product_val  (GimpVector3 vector1,
                                                 GimpVector3 vector2);

This function is mainly another implementation of gimp_vector3_cross_product where the arguments are passed by value rather than by address.

`vector1` : | the first GimpVector3 (by value)
`vector2` : | the second GimpVector3 (by value)
Returns : | The cross product.

### gimp_vector3_length ()

    gdouble     gimp_vector3_length             (const GimpVector3 *vector);

Computes and returns the length of a 3D vector.

`vector` : | a GimpVector3 (by address)
Returns : | the length of `vector`.

### gimp_vector3_length_val ()

    gdouble     gimp_vector3_length_val         (GimpVector3 vector);

Computes and returns the length of a 3D vector.

`vector` : | a GimpVector3 (by value)
Returns : | the length of `vector`.

### gimp_vector3_normalize ()

    void        gimp_vector3_normalize          (GimpVector3 *vector);

Normalizes the vector pointed by `vector`, so its length will be 1.0. The nul vector will not be changed though.

`vector` : | a GimpVector3 (by address)

### gimp_vector3_normalize_val ()

    GimpVector3 gimp_vector3_normalize_val      (GimpVector3 vector);

Computes and returns the normalized vector corresponding with the one passed in argument.

`vector` : | a GimpVector3 (by value)
Returns : | a GimpVector2 parallel to `vector`, pointing in the same direction but with a length of 1.0.

### gimp_vector3_mul ()

    void        gimp_vector3_mul                (GimpVector3 *vector,
                                                 gdouble factor);

Multiplies each component of the `vector` by `factor`. Note that this is equivalent to multiplied the length of `vector` by `factor`.

`vector` : | a GimpVector3 (by address)
`factor` : | a scalar

### gimp_vector3_mul_val ()

    GimpVector3 gimp_vector3_mul_val            (GimpVector3 vector,
                                                 gdouble factor);

Computes and returns a GimpVector3 pointing in the same direction than `vector`, but with a length multiplied by `factor`.

`vector` : | a GimpVector3 (by value)
`factor` : | a scalar.
Returns : | the resulting GimpVector3.

### gimp_vector3_sub ()

    void        gimp_vector3_sub                (GimpVector3 *result,
                                                 const GimpVector3 *vector1,
                                                 const GimpVector3 *vector2);

Computes the difference of two 3D vectors (`vector1` minus `vector2`). The result is stored in the GimpVector3 pointed by `result`.

`result` : | a placeholder for the resulting GimpVector3
`vector1` : | a GimpVector3 (by address)
`vector2` : | a GimpVector3 (by address)

### gimp_vector3_sub_val ()

    GimpVector3 gimp_vector3_sub_val            (GimpVector3 vector1,
                                                 GimpVector3 vector2);

Computes and returns the difference of two 3D vectors (`vector1` minus `vector2`).

`vector1` : | a GimpVector3 (by value)
`vector2` : | a GimpVector3 (by value)
Returns : | the resulting GimpVector3.

### gimp_vector3_set ()

    void        gimp_vector3_set                (GimpVector3 *vector,
                                                 gdouble x,
                                                 gdouble y,
                                                 gdouble z);

Sets the three coordinates of `vector` to `x`, `y` and `z`.

`vector` : | a GimpVector3 (by address)
`x` : | a gdouble used as first coordinate
`y` : | a gdouble used as second coordinate
`z` : | a gdouble used as third coordinate

### gimp_vector3_new ()

    GimpVector3 gimp_vector3_new                (gdouble x,
                                                 gdouble y,
                                                 gdouble z);

Creates a GimpVector3 of coordinate `x`, `y` and `z`.

`x` : | a gdouble used as first coordinate
`y` : | a gdouble used as second coordinate
`z` : | a gdouble used as third coordinate
Returns : | the resulting GimpVector3.

### gimp_vector3_add ()

    void        gimp_vector3_add                (GimpVector3 *result,
                                                 const GimpVector3 *vector1,
                                                 const GimpVector3 *vector2);

Computes the sum of two 3D vectors. The result is stored in the GimpVector3 pointed by `result`.

`result` : | a placeholder for the resulting GimpVector3
`vector1` : | a GimpVector3 (by address)
`vector2` : | a GimpVector3 (by address)

### gimp_vector3_add_val ()

    GimpVector3 gimp_vector3_add_val            (GimpVector3 vector1,
                                                 GimpVector3 vector2);

Computes and returns the sum of two 3D vectors (`vector1` minus `vector2`).

`vector1` : | a GimpVector3 (by value)
`vector2` : | a GimpVector3 (by value)
Returns : | the resulting GimpVector3.

### gimp_vector3_neg ()

    void        gimp_vector3_neg                (GimpVector3 *vector);

Negates the `vector` (i.e. negate all its coordinates).

`vector` : | a GimpVector3 (by address)

### gimp_vector3_neg_val ()

    GimpVector3 gimp_vector3_neg_val            (GimpVector3 vector);

Computes and returns the negation of the `vector`.

`vector` : | a GimpVector3 (by value)
Returns : | the negated vector.

### gimp_vector3_rotate ()

    void        gimp_vector3_rotate             (GimpVector3 *vector,
                                                 gdouble alpha,
                                                 gdouble beta,
                                                 gdouble gamma);

Rotates the `vector` around the three axis (Z, Y, and X) by `alpha`, `beta` and `gamma`, respectively.

Note that the order of the rotation is very important. If you expect a vector to be rotated around X, and then around Y, you will have to call this function twice. Also, it is often wise to call this function with only one of `alpha`, `beta` and `gamma` non-nul.

`vector` : | a GimpVector3 (by address)
`alpha` : | the angle (in radian) of rotation around the Z axis.
`beta` : | the angle (in radian) of rotation around the Y axis.
`gamma` : | the angle (in radian) of rotation around the X axis.

### gimp_vector3_rotate_val ()

    GimpVector3 gimp_vector3_rotate_val         (GimpVector3 vector,
                                                 gdouble alpha,
                                                 gdouble beta,
                                                 gdouble gamma);

Rotates the `vector` around the three axis (Z, Y, and X) by `alpha`, `beta` and `gamma`, respectively, and return the resulting vector.

Note that the order of the rotation is very important. If you expect a vector to be rotated around X, and then around Y, you will have to call this function twice. Also, it is often wise to call this function with only one of `alpha`, `beta` and `gamma` non-nul.

`vector` : | a GimpVector3 (by value)
`alpha` : | the angle (in radian) of rotation around the Z axis.
`beta` : | the angle (in radian) of rotation around the Y axis.
`gamma` : | the angle (in radian) of rotation around the X axis.
Returns : | the rotated vector.

### gimp_vector_2d_to_3d ()

    void        gimp_vector_2d_to_3d            (gint sx,
                                                 gint sy,
                                                 gint w,
                                                 gint h,
                                                 gint x,
                                                 gint y,
                                                 const GimpVector3 *vp,
                                                 GimpVector3 *p);

\"Compute screen (sx,sy)-(sx+w,sy+h) to 3D unit square mapping. The plane to map to is given in the z field of p. The observer is located at position vp (vp->z!=0.0).\"

In other words, this computes the projection of the point (`x` ,`y`) to the plane z = `p`->z (parallel to XY), from the `vp` point of view through the screen (`sx`, `sy`)->(`sx`+`w`, `sy`+`h`)

`sx` : | the abscisse of the upper-left screen rectangle.
`sy` : | the ordinate of the upper-left screen rectangle.
`w` : | the width of the screen rectangle.
`h` : | the height of the screen rectangle.
`x` : | the abscisse of the point in the screen rectangle to map.
`y` : | the ordinate of the point in the screen rectangle to map.
`vp` : | position of the observer (by address).
`p` : | the resulting point (by address).

### gimp_vector_2d_to_3d_val ()

    GimpVector3 gimp_vector_2d_to_3d_val        (gint sx,
                                                 gint sy,
                                                 gint w,
                                                 gint h,
                                                 gint x,
                                                 gint y,
                                                 GimpVector3 vp,
                                                 GimpVector3 p);

This is mostly the same function as gimp_vector_2d_to_3d, with the position of the observer and the projecting plane given by value rather than by address. Also, the resulting point is returned.

`sx` : | the abscisse of the upper-left screen rectangle.
`sy` : | the ordinate of the upper-left screen rectangle.
`w` : | the width of the screen rectangle.
`h` : | the height of the screen rectangle.
`x` : | the abscisse of the point in the screen rectangle to map.
`y` : | the ordinate of the point in the screen rectangle to map.
`vp` : | position of the observer (by value).
`p` : | the resulting point (by value).
Returns : | the computed GimpVector3 point.

### gimp_vector_3d_to_2d ()

    void        gimp_vector_3d_to_2d            (gint sx,
                                                 gint sy,
                                                 gint w,
                                                 gint h,
                                                 gdouble *x,
                                                 gdouble *y,
                                                 const GimpVector3 *vp,
                                                 const GimpVector3 *p);

Convert the given 3D point to 2D (project it onto the viewing plane, (sx,sy,0)-(sx+w,sy+h,0). The input is assumed to be in the unit square (0,0,z)-(1,1,z). The viewpoint of the observer is passed in vp.

This is basically the opposite of the gimp_vector_2d_to_3d function.

`sx` : | the abscisse of the upper-left screen rectangle.
`sy` : | the ordinate of the upper-left screen rectangle.
`w` : | the width of the screen rectangle.
`h` : | the height of the screen rectangle.
`x` : | the abscisse of the point in the screen rectangle to map (return value).
`y` : | the ordinate of the point in the screen rectangle to map (return value).
`vp` : | position of the observer (by address).
`p` : | the 3D point to project to the plane. (by address).

## See Also

GimpMatrix3

GimpMatrix4