Cogl 2.0 Reference Manual  

Top  Description 
void cogl_vector3_init (float *vector
,float x
,float y
,float z
); void cogl_vector3_init_zero (float *vector
); CoglBool cogl_vector3_equal (const void *v1
,const void *v2
); CoglBool cogl_vector3_equal_with_epsilon (const float *vector0
,const float *vector1
,float epsilon
); float * cogl_vector3_copy (const float *vector
); void cogl_vector3_free (float *vector
); void cogl_vector3_invert (float *vector
); void cogl_vector3_add (float *result
,const float *a
,const float *b
); void cogl_vector3_subtract (float *result
,const float *a
,const float *b
); void cogl_vector3_multiply_scalar (float *vector
,float scalar
); void cogl_vector3_divide_scalar (float *vector
,float scalar
); void cogl_vector3_normalize (float *vector
); float cogl_vector3_magnitude (const float *vector
); void cogl_vector3_cross_product (float *result
,const float *u
,const float *v
); float cogl_vector3_dot_product (const float *a
,const float *b
); float cogl_vector3_distance (const float *a
,const float *b
);
This exposes a utility API that can be used for basic manipulation of 3 component float vectors.
void cogl_vector3_init (float *vector
,float x
,float y
,float z
);
Initializes a 3 component, single precision float vector which can then be manipulated with the cogl_vector convenience APIs. Vectors can also be used in places where a "point" is often desired.

The 3 component vector you want to initialize 

The x component 

The y component 

The z component 
Since 1.4
Stability Level: Unstable
void cogl_vector3_init_zero (float *vector
);
Initializes a 3 component, single precision float vector with zero for each component.

The 3 component vector you want to initialize 
Since 1.4
Stability Level: Unstable
CoglBool cogl_vector3_equal (const void *v1
,const void *v2
);
Compares the components of two vectors and returns TRUE if they are the same.
The comparison of the components is done with the '==' operator such that 0 is considered equal to 0, but otherwise there is no fuzziness such as an epsilon to consider vectors that are essentially identical except for some minor precision error differences due to the way they have been manipulated.

The first 3 component vector you want to compare 

The second 3 component vector you want to compare 
Returns : 
TRUE if the vectors are equal else FALSE. 
Since 1.4
Stability Level: Unstable
CoglBool cogl_vector3_equal_with_epsilon (const float *vector0
,const float *vector1
,float epsilon
);
Compares the components of two vectors using the given epsilon and returns TRUE if they are the same, using an internal epsilon for comparing the floats.
Each component is compared against the epsilon value in this way:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 


The first 3 component vector you want to compare 

The second 3 component vector you want to compare 

The allowable difference between components to still be considered equal 
Returns : 
TRUE if the vectors are equal else FALSE. 
Since 1.4
Stability Level: Unstable
float * cogl_vector3_copy (const float *vector
);
Allocates a new 3 component float vector on the heap initializing
the components from the given vector
and returns a pointer to the
newly allocated vector. You should free the memory using
cogl_vector3_free()

The 3 component vector you want to copy 
Returns : 
A newly allocated 3 component float vector 
Since 1.4
Stability Level: Unstable
void cogl_vector3_free (float *vector
);
Frees a 3 component vector that was previously allocated with
cogl_vector3_copy()

The 3 component you want to free 
Since 1.4
Stability Level: Unstable
void cogl_vector3_invert (float *vector
);
Inverts/negates all the components of the given vector
.

The 3 component vector you want to manipulate 
Since 1.4
Stability Level: Unstable
void cogl_vector3_add (float *result
,const float *a
,const float *b
);
Adds each of the corresponding components in vectors a
and b
storing the results in result
.

Where you want the result written 

The first vector operand 

The second vector operand 
Since 1.4
Stability Level: Unstable
void cogl_vector3_subtract (float *result
,const float *a
,const float *b
);
Subtracts each of the corresponding components in vector b
from
a
storing the results in result
.

Where you want the result written 

The first vector operand 

The second vector operand 
Since 1.4
Stability Level: Unstable
void cogl_vector3_multiply_scalar (float *vector
,float scalar
);
Multiplies each of the vector
components by the given scalar.

The 3 component vector you want to manipulate 

The scalar you want to multiply the vector components by 
Since 1.4
Stability Level: Unstable
void cogl_vector3_divide_scalar (float *vector
,float scalar
);
Divides each of the vector
components by the given scalar.

The 3 component vector you want to manipulate 

The scalar you want to divide the vector components by 
Since 1.4
Stability Level: Unstable
void cogl_vector3_normalize (float *vector
);
Updates the vector so it is a "unit vector" such that the
vector
s magnitude or length is equal to 1.

The 3 component vector you want to manipulate 
Since 1.4
Stability Level: Unstable
float cogl_vector3_magnitude (const float *vector
);
Calculates the scalar magnitude or length of vector
.

The 3 component vector you want the magnitude for 
Returns : 
The magnitude of vector . 
Since 1.4
Stability Level: Unstable
void cogl_vector3_cross_product (float *result
,const float *u
,const float *v
);
Calculates the cross product between the two vectors u
and v
.
The cross product is a vector perpendicular to both u
and v
. This
can be useful for calculating the normal of a polygon by creating
two vectors in its plane using the polygons vertices and taking
their cross product.
If the two vectors are parallel then the cross product is 0.
You can use a right hand rule to determine which direction the
perpendicular vector will point: If you place the two vectors tail,
to tail and imagine grabbing the perpendicular line that extends
through the common tail with your right hand such that you fingers
rotate in the direction from u
to v
then the resulting vector
points along your extended thumb.

Where you want the result written 

Your first 3 component vector 

Your second 3 component vector 
Returns : 
The cross product between two vectors u and v . 
Since 1.4
Stability Level: Unstable
float cogl_vector3_dot_product (const float *a
,const float *b
);
Calculates the dot product of the two 3 component vectors. This can be used to determine the magnitude of one vector projected onto another. (for example a surface normal)
For example if you have a polygon with a given normal vector and some other point for which you want to calculate its distance from the polygon, you can create a vector between one of the polygon vertices and that point and use the dot product to calculate the magnitude for that vector but projected onto the normal of the polygon. This way you don't just get the distance from the point to the edge of the polygon you get the distance from the point to the nearest part of the polygon.
The dot product is calculated as:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 
(a>x * b>x + a>y * b>y + a>z * b>z) 
For reference, the dot product can also be calculated from the angle between two vectors as:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 
abcos𝜃 

Your first 3 component vector 

Your second 3 component vector 
Returns : 
The dot product of two vectors. 
Since 1.4
Stability Level: Unstable
float cogl_vector3_distance (const float *a
,const float *b
);
If you consider the two given vectors as (x,y,z) points instead then this will compute the distance between those two points.

The first point 

The second point 
Returns : 
The distance between two points given as 3 component vectors. 
Since 1.4
Stability Level: Unstable