GimpVector: GIMP Math Library Reference Manual

## GimpVector GimpVector — Utilities to set up and manipulate vectors. |

## Functions

GimpVector2 | gimp_vector2_new ()
void | gimp_vector2_set ()
gdouble | gimp_vector2_length ()
gdouble | gimp_vector2_length_val ()
void | gimp_vector2_mul ()
GimpVector2 | gimp_vector2_mul_val ()
GimpVector2 | gimp_vector2_normal ()
GimpVector2 | gimp_vector2_normal_val ()
void | gimp_vector2_normalize ()
GimpVector2 | gimp_vector2_normalize_val ()
void | gimp_vector2_neg ()
GimpVector2 | gimp_vector2_neg_val ()
void | gimp_vector2_add ()
GimpVector2 | gimp_vector2_add_val ()
void | gimp_vector2_sub ()
GimpVector2 | gimp_vector2_sub_val ()
gdouble | gimp_vector2_inner_product ()
gdouble | gimp_vector2_inner_product_val ()
GimpVector2 | gimp_vector2_cross_product ()
GimpVector2 | gimp_vector2_cross_product_val ()
void | gimp_vector2_rotate ()
GimpVector2 | gimp_vector2_rotate_val ()
GimpVector3 | gimp_vector3_new ()
void | gimp_vector3_set ()
gdouble | gimp_vector3_length ()
gdouble | gimp_vector3_length_val ()
void | gimp_vector3_mul ()
GimpVector3 | gimp_vector3_mul_val ()
void | gimp_vector3_normalize ()
GimpVector3 | gimp_vector3_normalize_val ()
void | gimp_vector3_neg ()
GimpVector3 | gimp_vector3_neg_val ()
void | gimp_vector3_add ()
GimpVector3 | gimp_vector3_add_val ()
void | gimp_vector3_sub ()
GimpVector3 | gimp_vector3_sub_val ()
gdouble | gimp_vector3_inner_product ()
gdouble | gimp_vector3_inner_product_val ()
GimpVector3 | gimp_vector3_cross_product ()
GimpVector3 | gimp_vector3_cross_product_val ()
void | gimp_vector3_rotate ()
GimpVector3 | gimp_vector3_rotate_val ()
void | gimp_vector_2d_to_3d ()
GimpVector3 | gimp_vector_2d_to_3d_val ()
void | gimp_vector_3d_to_2d ()

## Types and Values

struct | GimpVector2
struct | GimpVector3
struct | GimpVector4

## Description

Utilities to set up and manipulate vectors.

## Functions

### gimp_vector2_new ()

    GimpVector2
    gimp_vector2_new (gdouble x,
                      gdouble y);

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

#### Parameters

x | the X coordinate. |
y | the Y coordinate. |

#### Returns

the resulting GimpVector2.

### gimp_vector2_set ()

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

Sets the X and Y coordinates of `vector` to `x` and `y` .

#### Parameters

vector | a pointer to a GimpVector2. |
x | the X coordinate. |
y | the Y coordinate. |

### gimp_vector2_length ()

    gdouble
    gimp_vector2_length (const GimpVector2 *vector);

Computes the length of a 2D vector.

#### Parameters

vector | a pointer to a GimpVector2. |

#### Returns

the length of `vector` (a positive gdouble).

### gimp_vector2_length_val ()

    gdouble
    gimp_vector2_length_val (GimpVector2 vector);

This function is identical to `gimp_vector2_length()` but the vector is passed by value rather than by reference.

#### Parameters

vector | a GimpVector2. |

#### Returns

the length of `vector` (a positive gdouble).

### gimp_vector2_mul ()

    void
    gimp_vector2_mul (GimpVector2 *vector,
                      gdouble factor);

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

#### Parameters

vector | a pointer to a GimpVector2. |
factor | a scalar. |

### gimp_vector2_mul_val ()

    GimpVector2
    gimp_vector2_mul_val (GimpVector2 vector,
                          gdouble factor);

This function is identical to `gimp_vector2_mul()` but the vector is passed by value rather than by reference.

#### Parameters

vector | a GimpVector2. |
factor | a scalar. |

#### Returns

the resulting GimpVector2.

### gimp_vector2_normal ()

    GimpVector2
    gimp_vector2_normal (GimpVector2 *vector);

Compute a normalized perpendicular vector to `vector`

#### Parameters

vector | a pointer to a GimpVector2. |

#### Returns

a GimpVector2 perpendicular to `vector` , with a length of 1.0.

Since: 2.8

### gimp_vector2_normal_val ()

    GimpVector2
    gimp_vector2_normal_val (GimpVector2 vector);

This function is identical to `gimp_vector2_normal()` but the vector is passed by value rather than by reference.

#### Parameters

vector | a GimpVector2. |

#### Returns

a GimpVector2 perpendicular to `vector` , with a length of 1.0.

Since: 2.8

### gimp_vector2_normalize ()

    void
    gimp_vector2_normalize (GimpVector2 *vector);

Normalizes the `vector` so the length of the `vector` is 1.0. The nul vector will not be changed.

#### Parameters

vector | a pointer to a GimpVector2. |

### gimp_vector2_normalize_val ()

    GimpVector2
    gimp_vector2_normalize_val (GimpVector2 vector);

This function is identical to `gimp_vector2_normalize()` but the vector is passed by value rather than by reference.

#### Parameters

vector | a GimpVector2. |

#### Returns

a GimpVector2 parallel to `vector` , pointing in the same direction but with a length of 1.0.

### gimp_vector2_neg ()

    void
    gimp_vector2_neg (GimpVector2 *vector);

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

#### Parameters

vector | a pointer to a GimpVector2. |

### gimp_vector2_neg_val ()

    GimpVector2
    gimp_vector2_neg_val (GimpVector2 vector);

This function is identical to `gimp_vector2_neg()` but the vector is passed by value rather than by reference.

#### Parameters

vector | a GimpVector2. |

#### Returns

the negated GimpVector2.

### gimp_vector2_add ()

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

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

#### Parameters

result | destination for the resulting GimpVector2. |
vector1 | a pointer to the first GimpVector2. |
vector2 | a pointer to the second GimpVector2. |

### gimp_vector2_add_val ()

    GimpVector2
    gimp_vector2_add_val (GimpVector2 vector1,
                          GimpVector2 vector2);

This function is identical to `gimp_vector2_add()` but the vectors are passed by value rather than by reference.

#### Parameters

vector1 | the first GimpVector2. |
vector2 | the second GimpVector2. |

#### 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 resulting GimpVector2 is stored in `result` .

#### Parameters

result | the destination for the resulting GimpVector2. |
vector1 | a pointer to the first GimpVector2. |
vector2 | a pointer to the second GimpVector2. |

### gimp_vector2_sub_val ()

    GimpVector2
    gimp_vector2_sub_val (GimpVector2 vector1,
                          GimpVector2 vector2);

This function is identical to `gimp_vector2_sub()` but the vectors are passed by value rather than by reference.

#### Parameters

vector1 | the first GimpVector2. |
vector2 | the second GimpVector2. |

#### 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 zero if and only if the two vectors are orthogonal.

#### Parameters

vector1 | a pointer to the first GimpVector2. |
vector2 | a pointer to the second GimpVector2. |

#### Returns

The inner product.

### gimp_vector2_inner_product_val ()

    gdouble
    gimp_vector2_inner_product_val (GimpVector2 vector1,
                                    GimpVector2 vector2);

This function is identical to `gimp_vector2_inner_product()` but the vectors are passed by value rather than by reference.

#### Parameters

vector1 | the first GimpVector2. |
vector2 | the second GimpVector2. |

#### 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 GimpVector2 which is orthogonal to both `vector1` and `vector2` . If `vector1` and `vector2` are parallel, the result will be the nul vector.

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

#### Parameters

vector1 | a pointer to the first GimpVector2. |
vector2 | a pointer to the second GimpVector2. |

#### Returns

The cross product.

### gimp_vector2_cross_product_val ()

    GimpVector2
    gimp_vector2_cross_product_val (GimpVector2 vector1,
                                    GimpVector2 vector2);

This function is identical to `gimp_vector2_cross_product()` but the vectors are passed by value rather than by reference.

#### Parameters

vector1 | the first GimpVector2. |
vector2 | the second GimpVector2. |

#### Returns

The cross product.

### gimp_vector2_rotate ()

    void
    gimp_vector2_rotate (GimpVector2 *vector,
                         gdouble alpha);

Rotates the `vector` counterclockwise by `alpha` radians.

#### Parameters

vector | a pointer to a GimpVector2. |
alpha | an angle (in radians). |

### gimp_vector2_rotate_val ()

    GimpVector2
    gimp_vector2_rotate_val (GimpVector2 vector,
                             gdouble alpha);

This function is identical to `gimp_vector2_rotate()` but the vector is passed by value rather than by reference.

#### Parameters

vector | a GimpVector2. |
alpha | an angle (in radians). |

#### Returns

a GimpVector2 representing `vector` rotated by `alpha` radians.

### gimp_vector3_new ()

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

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

#### Parameters

x | the X coordinate. |
y | the Y coordinate. |
z | the Z coordinate. |

#### Returns

the resulting GimpVector3.

### gimp_vector3_set ()

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

Sets the X, Y and Z coordinates of `vector` to `x` , `y` and `z` .

#### Parameters

vector | a pointer to a GimpVector3. |
x | the X coordinate. |
y | the Y coordinate. |
z | the Z coordinate. |

### gimp_vector3_length ()

    gdouble
    gimp_vector3_length (const GimpVector3 *vector);

Computes the length of a 3D vector.

#### Parameters

vector | a pointer to a GimpVector3. |

#### Returns

the length of `vector` (a positive gdouble).

### gimp_vector3_length_val ()

    gdouble
    gimp_vector3_length_val (GimpVector3 vector);

This function is identical to `gimp_vector3_length()` but the vector is passed by value rather than by reference.

#### Parameters

vector | a GimpVector3. |

#### Returns

the length of `vector` (a positive gdouble).

### 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 multiplying the vectors length by `factor` .

#### Parameters

vector | a pointer to a GimpVector3. |
factor | a scalar. |

### gimp_vector3_mul_val ()

    GimpVector3
    gimp_vector3_mul_val (GimpVector3 vector,
                          gdouble factor);

This function is identical to `gimp_vector3_mul()` but the vector is passed by value rather than by reference.

#### Parameters

vector | a GimpVector3. |
factor | a scalar. |

#### Returns

the resulting GimpVector3.

### gimp_vector3_normalize ()

    void
    gimp_vector3_normalize (GimpVector3 *vector);

Normalizes the `vector` so the length of the `vector` is 1.0. The nul vector will not be changed.

#### Parameters

vector | a pointer to a GimpVector3. |

### gimp_vector3_normalize_val ()

    GimpVector3
    gimp_vector3_normalize_val (GimpVector3 vector);

This function is identical to `gimp_vector3_normalize()` but the vector is passed by value rather than by reference.

#### Parameters

vector | a GimpVector3. |

#### Returns

a GimpVector3 parallel to `vector` , pointing in the same direction but with a length of 1.0.

### gimp_vector3_neg ()

    void
    gimp_vector3_neg (GimpVector3 *vector);

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

#### Parameters

vector | a pointer to a GimpVector3. |

### gimp_vector3_neg_val ()

    GimpVector3
    gimp_vector3_neg_val (GimpVector3 vector);

This function is identical to `gimp_vector3_neg()` but the vector is passed by value rather than by reference.

#### Parameters

vector | a GimpVector3. |

#### Returns

the negated GimpVector3.

### gimp_vector3_add ()

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

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

#### Parameters

result | destination for the resulting GimpVector3. |
vector1 | a pointer to the first GimpVector3. |
vector2 | a pointer to the second GimpVector3. |

### gimp_vector3_add_val ()

    GimpVector3
    gimp_vector3_add_val (GimpVector3 vector1,
                          GimpVector3 vector2);

This function is identical to `gimp_vector3_add()` but the vectors are passed by value rather than by reference.

#### Parameters

vector1 | a GimpVector3. |
vector2 | a GimpVector3. |

#### 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 resulting GimpVector3 is stored in `result` .

#### Parameters

result | the destination for the resulting GimpVector3. |
vector1 | a pointer to the first GimpVector3. |
vector2 | a pointer to the second GimpVector3. |

### gimp_vector3_sub_val ()

    GimpVector3
    gimp_vector3_sub_val (GimpVector3 vector1,
                          GimpVector3 vector2);

This function is identical to `gimp_vector3_sub()` but the vectors are passed by value rather than by reference.

#### Parameters

vector1 | a GimpVector3. |
vector2 | a GimpVector3. |

#### Returns

the resulting GimpVector3.

### gimp_vector3_inner_product ()

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

Computes the inner (dot) product of two 3D vectors. This product is zero if and only if the two vectors are orthogonal.

#### Parameters

vector1 | a pointer to the first GimpVector3. |
vector2 | a pointer to the second GimpVector3. |

#### Returns

The inner product.

### gimp_vector3_inner_product_val ()

    gdouble
    gimp_vector3_inner_product_val (GimpVector3 vector1,
                                    GimpVector3 vector2);

This function is identical to `gimp_vector3_inner_product()` but the vectors are passed by value rather than by reference.

#### Parameters

vector1 | the first GimpVector3. |
vector2 | the second GimpVector3. |

#### 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 orthogonal to both `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 plane defined by `vector1` and `vector2` .

#### Parameters

vector1 | a pointer to the first GimpVector3. |
vector2 | a pointer to the second GimpVector3. |

#### Returns

The cross product.

### gimp_vector3_cross_product_val ()

    GimpVector3
    gimp_vector3_cross_product_val (GimpVector3 vector1,
                                    GimpVector3 vector2);

This function is identical to `gimp_vector3_cross_product()` but the vectors are passed by value rather than by reference.

#### Parameters

vector1 | the first GimpVector3. |
vector2 | the second GimpVector3. |

#### Returns

The cross product.

### 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-zero.

#### Parameters

vector | a pointer to a GimpVector3. |
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);

This function is identical to `gimp_vector3_rotate()` but the vectors are passed by value rather than by reference.

#### Parameters

vector | a GimpVector3. |
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` )

#### Parameters

sx | the abscissa 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 abscissa of the point in the screen rectangle to map. |
y | the ordinate of the point in the screen rectangle to map. |
vp | the position of the observer. |
p | the resulting point. |

### 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 function is identical to `gimp_vector_2d_to_3d()` but the position of the `observer` and the resulting point `p` are passed by value rather than by reference.

#### Parameters

sx | the abscissa 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 abscissa 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. |
p | the resulting point. |

#### 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 `gimp_vector_2d_to_3d()`.

#### Parameters

sx | the abscissa 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 abscissa 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. |
p | the 3D point to project to the plane. |

## Types and Values

### struct GimpVector2

    struct GimpVector2 {
      gdouble x, y;
    };

A two dimensional vector.

#### Members

gdouble `x`; | the x axis |
gdouble `y`; | the y axis |

### struct GimpVector3

    struct GimpVector3 {
      gdouble x, y, z;
    };

A three dimensional vector.

#### Members

gdouble `x`; | the x axis |
gdouble `y`; | the y axis |
gdouble `z`; | the z axis |

### struct GimpVector4

    struct GimpVector4 {
      gdouble x, y, z, w;
    };

A four dimensional vector.

#### Members

gdouble `x`; | the x axis |
gdouble `y`; | the y axis |
gdouble `z`; | the z axis |
gdouble `w`; | the w axis |

## See Also

GimpMatrix2, GimpMatrix3, GimpMatrix4