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