mirror of
https://github.com/brl/mutter.git
synced 2024-11-26 18:11:05 -05:00
54735dec84
The coding style has for a long time said to avoid using redundant glib
data types such as gint or gchar etc because we feel that they make the
code look unnecessarily foreign to developers coming from outside of the
Gnome developer community.
Note: When we tried to find the historical rationale for the types we
just found that they were apparently only added for consistent syntax
highlighting which didn't seem that compelling.
Up until now we have been continuing to use some of the platform
specific type such as gint{8,16,32,64} and gsize but this patch switches
us over to using the standard c99 equivalents instead so we can further
ensure that our code looks familiar to the widest range of C developers
who might potentially contribute to Cogl.
So instead of using the gint{8,16,32,64} and guint{8,16,32,64} types this
switches all Cogl code to instead use the int{8,16,32,64}_t and
uint{8,16,32,64}_t c99 types instead.
Instead of gsize we now use size_t
For now we are not going to use the c99 _Bool type and instead we have
introduced a new CoglBool type to use instead of gboolean.
Reviewed-by: Neil Roberts <neil@linux.intel.com>
(cherry picked from commit 5967dad2400d32ca6319cef6cb572e81bf2c15f0)
350 lines
9.5 KiB
C
350 lines
9.5 KiB
C
/*
|
|
* Cogl
|
|
*
|
|
* An object oriented GL/GLES Abstraction/Utility Layer
|
|
*
|
|
* Copyright (C) 2008,2009,2010 Intel Corporation.
|
|
*
|
|
* This library is free software; you can redistribute it and/or
|
|
* modify it under the terms of the GNU Lesser General Public
|
|
* License as published by the Free Software Foundation; either
|
|
* version 2 of the License, or (at your option) any later version.
|
|
*
|
|
* This library is distributed in the hope that it will be useful,
|
|
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|
* Lesser General Public License for more details.
|
|
*
|
|
* You should have received a copy of the GNU Lesser General Public
|
|
* License along with this library; if not, write to the
|
|
* Free Software Foundation, Inc., 59 Temple Place - Suite 330,
|
|
* Boston, MA 02111-1307, USA.
|
|
*
|
|
* Authors:
|
|
* Robert Bragg <robert@linux.intel.com>
|
|
*/
|
|
|
|
#if !defined(__COGL_H_INSIDE__) && !defined(CLUTTER_COMPILATION)
|
|
#error "Only <cogl/cogl.h> can be included directly."
|
|
#endif
|
|
|
|
#ifndef __COGL_VECTOR_H
|
|
#define __COGL_VECTOR_H
|
|
|
|
#include <glib.h>
|
|
|
|
G_BEGIN_DECLS
|
|
|
|
/**
|
|
* SECTION:cogl-vector
|
|
* @short_description: Functions for handling single precision float
|
|
* vectors.
|
|
*
|
|
* This exposes a utility API that can be used for basic manipulation of 3
|
|
* component float vectors.
|
|
*/
|
|
|
|
/**
|
|
* cogl_vector3_init:
|
|
* @vector: The 3 component vector you want to initialize
|
|
* @x: The x component
|
|
* @y: The y component
|
|
* @z: The z component
|
|
*
|
|
* 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.
|
|
*
|
|
* Since: 1.4
|
|
* Stability: Unstable
|
|
*/
|
|
void
|
|
cogl_vector3_init (float *vector, float x, float y, float z);
|
|
|
|
/**
|
|
* cogl_vector3_init_zero:
|
|
* @vector: The 3 component vector you want to initialize
|
|
*
|
|
* Initializes a 3 component, single precision float vector with zero
|
|
* for each component.
|
|
*
|
|
* Since: 1.4
|
|
* Stability: Unstable
|
|
*/
|
|
void
|
|
cogl_vector3_init_zero (float *vector);
|
|
|
|
/**
|
|
* cogl_vector3_equal:
|
|
* @v1: The first 3 component vector you want to compare
|
|
* @v2: The second 3 component vector you want to compare
|
|
*
|
|
* 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.
|
|
*
|
|
* Returns: TRUE if the vectors are equal else FALSE.
|
|
*
|
|
* Since: 1.4
|
|
* Stability: Unstable
|
|
*/
|
|
CoglBool
|
|
cogl_vector3_equal (const void *v1, const void *v2);
|
|
|
|
/**
|
|
* cogl_vector3_equal_with_epsilon:
|
|
* @vector0: The first 3 component vector you want to compare
|
|
* @vector1: The second 3 component vector you want to compare
|
|
* @epsilon: The allowable difference between components to still be
|
|
* considered equal
|
|
*
|
|
* 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:
|
|
* |[
|
|
* if (fabsf (vector0->x - vector1->x) < epsilon)
|
|
* ]|
|
|
*
|
|
* Returns: TRUE if the vectors are equal else FALSE.
|
|
*
|
|
* Since: 1.4
|
|
* Stability: Unstable
|
|
*/
|
|
CoglBool
|
|
cogl_vector3_equal_with_epsilon (const float *vector0,
|
|
const float *vector1,
|
|
float epsilon);
|
|
|
|
/**
|
|
* cogl_vector3_copy:
|
|
* @vector: The 3 component vector you want to copy
|
|
*
|
|
* 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()
|
|
*
|
|
* Returns: A newly allocated 3 component float vector
|
|
*
|
|
* Since: 1.4
|
|
* Stability: Unstable
|
|
*/
|
|
float *
|
|
cogl_vector3_copy (const float *vector);
|
|
|
|
/**
|
|
* cogl_vector3_free:
|
|
* @vector: The 3 component you want to free
|
|
*
|
|
* Frees a 3 component vector that was previously allocated with
|
|
* cogl_vector_copy()
|
|
*
|
|
* Since: 1.4
|
|
* Stability: Unstable
|
|
*/
|
|
void
|
|
cogl_vector3_free (float *vector);
|
|
|
|
/**
|
|
* cogl_vector3_invert:
|
|
* @vector: The 3 component vector you want to manipulate
|
|
*
|
|
* Inverts/negates all the components of the given @vector.
|
|
*
|
|
* Since: 1.4
|
|
* Stability: Unstable
|
|
*/
|
|
void
|
|
cogl_vector3_invert (float *vector);
|
|
|
|
/**
|
|
* cogl_vector3_add:
|
|
* @result: Where you want the result written
|
|
* @a: The first vector operand
|
|
* @b: The second vector operand
|
|
*
|
|
* Adds each of the corresponding components in vectors @a and @b
|
|
* storing the results in @result.
|
|
*
|
|
* Since: 1.4
|
|
* Stability: Unstable
|
|
*/
|
|
void
|
|
cogl_vector3_add (float *result,
|
|
const float *a,
|
|
const float *b);
|
|
|
|
/**
|
|
* cogl_vector3_subtract:
|
|
* @result: Where you want the result written
|
|
* @a: The first vector operand
|
|
* @b: The second vector operand
|
|
*
|
|
* Subtracts each of the corresponding components in vector @b from
|
|
* @a storing the results in @result.
|
|
*
|
|
* Since: 1.4
|
|
* Stability: Unstable
|
|
*/
|
|
void
|
|
cogl_vector3_subtract (float *result,
|
|
const float *a,
|
|
const float *b);
|
|
|
|
/**
|
|
* cogl_vector3_multiply_scalar:
|
|
* @vector: The 3 component vector you want to manipulate
|
|
* @scalar: The scalar you want to multiply the vector components by
|
|
*
|
|
* Multiplies each of the @vector components by the given scalar.
|
|
*
|
|
* Since: 1.4
|
|
* Stability: Unstable
|
|
*/
|
|
void
|
|
cogl_vector3_multiply_scalar (float *vector,
|
|
float scalar);
|
|
|
|
/**
|
|
* cogl_vector3_divide_scalar:
|
|
* @vector: The 3 component vector you want to manipulate
|
|
* @scalar: The scalar you want to divide the vector components by
|
|
*
|
|
* Divides each of the @vector components by the given scalar.
|
|
*
|
|
* Since: 1.4
|
|
* Stability: Unstable
|
|
*/
|
|
void
|
|
cogl_vector3_divide_scalar (float *vector,
|
|
float scalar);
|
|
|
|
/**
|
|
* cogl_vector3_normalize:
|
|
* @vector: The 3 component vector you want to manipulate
|
|
*
|
|
* Updates the vector so it is a "unit vector" such that the
|
|
* @vector<!-- -->s magnitude or length is equal to 1.
|
|
*
|
|
* Since: 1.4
|
|
* Stability: Unstable
|
|
*/
|
|
void
|
|
cogl_vector3_normalize (float *vector);
|
|
|
|
/**
|
|
* cogl_vector3_magnitude:
|
|
* @vector: The 3 component vector you want the magnitude for
|
|
*
|
|
* Calculates the scalar magnitude or length of @vector.
|
|
*
|
|
* Returns: The magnitude of @vector.
|
|
*
|
|
* Since: 1.4
|
|
* Stability: Unstable
|
|
*/
|
|
float
|
|
cogl_vector3_magnitude (const float *vector);
|
|
|
|
/**
|
|
* cogl_vector3_cross_product:
|
|
* @result: Where you want the result written
|
|
* @u: Your first 3 component vector
|
|
* @v: Your second 3 component vector
|
|
*
|
|
* 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.
|
|
*
|
|
* Returns: The cross product between two vectors @u and @v.
|
|
*
|
|
* Since: 1.4
|
|
* Stability: Unstable
|
|
*/
|
|
void
|
|
cogl_vector3_cross_product (float *result,
|
|
const float *u,
|
|
const float *v);
|
|
|
|
/**
|
|
* cogl_vector3_dot_product:
|
|
* @a: Your first 3 component vector
|
|
* @b: Your second 3 component vector
|
|
*
|
|
* 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.
|
|
*
|
|
* <note>If you don't use a unit length normal in the above example
|
|
* then you would then also have to divide the result by the magnitude
|
|
* of the normal</note>
|
|
*
|
|
* The dot product is calculated as:
|
|
* |[
|
|
* (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:
|
|
* |[
|
|
* |a||b|cos𝜃
|
|
* ]|
|
|
*
|
|
* Returns: The dot product of two vectors.
|
|
*
|
|
* Since: 1.4
|
|
* Stability: Unstable
|
|
*/
|
|
float
|
|
cogl_vector3_dot_product (const float *a, const float *b);
|
|
|
|
/**
|
|
* cogl_vector3_distance:
|
|
* @a: The first point
|
|
* @b: The second point
|
|
*
|
|
* If you consider the two given vectors as (x,y,z) points instead
|
|
* then this will compute the distance between those two points.
|
|
*
|
|
* Returns: The distance between two points given as 3 component
|
|
* vectors.
|
|
*
|
|
* Since: 1.4
|
|
* Stability: Unstable
|
|
*/
|
|
float
|
|
cogl_vector3_distance (const float *a, const float *b);
|
|
|
|
G_END_DECLS
|
|
|
|
#endif /* __COGL_VECTOR_H */
|
|
|