diff options
Diffstat (limited to 'cogl/cogl/cogl-matrix.h')
-rw-r--r-- | cogl/cogl/cogl-matrix.h | 491 |
1 files changed, 0 insertions, 491 deletions
diff --git a/cogl/cogl/cogl-matrix.h b/cogl/cogl/cogl-matrix.h deleted file mode 100644 index 008e5b467..000000000 --- a/cogl/cogl/cogl-matrix.h +++ /dev/null @@ -1,491 +0,0 @@ -/* - * Cogl - * - * A Low Level GPU Graphics and Utilities API - * - * Copyright (C) 2008,2009 Intel Corporation. - * - * Permission is hereby granted, free of charge, to any person - * obtaining a copy of this software and associated documentation - * files (the "Software"), to deal in the Software without - * restriction, including without limitation the rights to use, copy, - * modify, merge, publish, distribute, sublicense, and/or sell copies - * of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: - * - * The above copyright notice and this permission notice shall be - * included in all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, - * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF - * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND - * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS - * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN - * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN - * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. - * - * - * - * Authors: - * Robert Bragg <robert@linux.intel.com> - */ - -#ifndef __COGL_MATRIX_H -#define __COGL_MATRIX_H - -#include <cogl/cogl-defines.h> - -#include <glib-object.h> - -#include <cogl/cogl-types.h> -#include <cogl/cogl-macros.h> - -#include <glib-object.h> - -#include <graphene.h> - -G_BEGIN_DECLS - -/** - * SECTION:cogl-matrix - * @short_description: Functions for initializing and manipulating 4x4 matrices - * - * Matrices are used in Cogl to describe affine model-view transforms, texture - * transforms, and projective transforms. This exposes a utility API that can - * be used for direct manipulation of these matrices. - */ - -/** - * cogl_matrix_init_identity: - * @matrix: A 4x4 transformation matrix - * - * Resets matrix to the identity matrix: - * - * |[ - * .xx=1; .xy=0; .xz=0; .xw=0; - * .yx=0; .yy=1; .yz=0; .yw=0; - * .zx=0; .zy=0; .zz=1; .zw=0; - * .wx=0; .wy=0; .wz=0; .ww=1; - * ]| - */ -COGL_EXPORT void -cogl_matrix_init_identity (graphene_matrix_t *matrix); - -/** - * cogl_matrix_init_translation: - * @matrix: A 4x4 transformation matrix - * @tx: x coordinate of the translation vector - * @ty: y coordinate of the translation vector - * @tz: z coordinate of the translation vector - * - * Resets matrix to the (tx, ty, tz) translation matrix: - * - * |[ - * .xx=1; .xy=0; .xz=0; .xw=tx; - * .yx=0; .yy=1; .yz=0; .yw=ty; - * .zx=0; .zy=0; .zz=1; .zw=tz; - * .wx=0; .wy=0; .wz=0; .ww=1; - * ]| - * - * Since: 2.0 - */ -COGL_EXPORT void -cogl_matrix_init_translation (graphene_matrix_t *matrix, - float tx, - float ty, - float tz); - -/** - * cogl_matrix_multiply: - * @result: The address of a 4x4 matrix to store the result in - * @a: A 4x4 transformation matrix - * @b: A 4x4 transformation matrix - * - * Multiplies the two supplied matrices together and stores - * the resulting matrix inside @result. - * - * <note>It is possible to multiply the @a matrix in-place, so - * @result can be equal to @a but can't be equal to @b.</note> - */ -COGL_EXPORT void -cogl_matrix_multiply (graphene_matrix_t *result, - const graphene_matrix_t *a, - const graphene_matrix_t *b); - -/** - * cogl_matrix_rotate: - * @matrix: A 4x4 transformation matrix - * @angle: The angle you want to rotate in degrees - * @x: X component of your rotation vector - * @y: Y component of your rotation vector - * @z: Z component of your rotation vector - * - * Multiplies @matrix with a rotation matrix that applies a rotation - * of @angle degrees around the specified 3D vector. - */ -COGL_EXPORT void -cogl_matrix_rotate (graphene_matrix_t *matrix, - float angle, - float x, - float y, - float z); - -/** - * cogl_matrix_rotate_euler: - * @matrix: A 4x4 transformation matrix - * @euler: A euler describing a rotation - * - * Multiplies @matrix with a rotation transformation described by the - * given #graphene_euler_t. - * - * Since: 2.0 - */ -COGL_EXPORT void -cogl_matrix_rotate_euler (graphene_matrix_t *matrix, - const graphene_euler_t *euler); - -/** - * cogl_matrix_translate: - * @matrix: A 4x4 transformation matrix - * @x: The X translation you want to apply - * @y: The Y translation you want to apply - * @z: The Z translation you want to apply - * - * Multiplies @matrix with a transform matrix that translates along - * the X, Y and Z axis. - */ -COGL_EXPORT void -cogl_matrix_translate (graphene_matrix_t *matrix, - float x, - float y, - float z); - -/** - * cogl_matrix_scale: - * @matrix: A 4x4 transformation matrix - * @sx: The X scale factor - * @sy: The Y scale factor - * @sz: The Z scale factor - * - * Multiplies @matrix with a transform matrix that scales along the X, - * Y and Z axis. - */ -COGL_EXPORT void -cogl_matrix_scale (graphene_matrix_t *matrix, - float sx, - float sy, - float sz); - -/** - * cogl_matrix_look_at: - * @matrix: A 4x4 transformation matrix - * @eye_position_x: The X coordinate to look from - * @eye_position_y: The Y coordinate to look from - * @eye_position_z: The Z coordinate to look from - * @object_x: The X coordinate of the object to look at - * @object_y: The Y coordinate of the object to look at - * @object_z: The Z coordinate of the object to look at - * @world_up_x: The X component of the world's up direction vector - * @world_up_y: The Y component of the world's up direction vector - * @world_up_z: The Z component of the world's up direction vector - * - * Applies a view transform @matrix that positions the camera at - * the coordinate (@eye_position_x, @eye_position_y, @eye_position_z) - * looking towards an object at the coordinate (@object_x, @object_y, - * @object_z). The top of the camera is aligned to the given world up - * vector, which is normally simply (0, 1, 0) to map up to the - * positive direction of the y axis. - * - * Because there is a lot of misleading documentation online for - * gluLookAt regarding the up vector we want to try and be a bit - * clearer here. - * - * The up vector should simply be relative to your world coordinates - * and does not need to change as you move the eye and object - * positions. Many online sources may claim that the up vector needs - * to be perpendicular to the vector between the eye and object - * position (partly because the man page is somewhat misleading) but - * that is not necessary for this function. - * - * <note>You should never look directly along the world-up - * vector.</note> - * - * <note>It is assumed you are using a typical projection matrix where - * your origin maps to the center of your viewport.</note> - * - * <note>Almost always when you use this function it should be the first - * transform applied to a new modelview transform</note> - * - * Since: 1.8 - * Stability: unstable - */ -COGL_EXPORT void -cogl_matrix_look_at (graphene_matrix_t *matrix, - float eye_position_x, - float eye_position_y, - float eye_position_z, - float object_x, - float object_y, - float object_z, - float world_up_x, - float world_up_y, - float world_up_z); - -/** - * cogl_matrix_frustum: - * @matrix: A 4x4 transformation matrix - * @left: X position of the left clipping plane where it - * intersects the near clipping plane - * @right: X position of the right clipping plane where it - * intersects the near clipping plane - * @bottom: Y position of the bottom clipping plane where it - * intersects the near clipping plane - * @top: Y position of the top clipping plane where it intersects - * the near clipping plane - * @z_near: The distance to the near clipping plane (Must be positive) - * @z_far: The distance to the far clipping plane (Must be positive) - * - * Multiplies @matrix by the given frustum perspective matrix. - */ -COGL_EXPORT void -cogl_matrix_frustum (graphene_matrix_t *matrix, - float left, - float right, - float bottom, - float top, - float z_near, - float z_far); - -/** - * cogl_matrix_perspective: - * @matrix: A 4x4 transformation matrix - * @fov_y: Vertical field of view angle in degrees. - * @aspect: The (width over height) aspect ratio for display - * @z_near: The distance to the near clipping plane (Must be positive, - * and must not be 0) - * @z_far: The distance to the far clipping plane (Must be positive) - * - * Multiplies @matrix by the described perspective matrix - * - * <note>You should be careful not to have to great a @z_far / @z_near - * ratio since that will reduce the effectiveness of depth testing - * since there won't be enough precision to identify the depth of - * objects near to each other.</note> - */ -COGL_EXPORT void -cogl_matrix_perspective (graphene_matrix_t *matrix, - float fov_y, - float aspect, - float z_near, - float z_far); - -/** - * cogl_matrix_orthographic: - * @matrix: A 4x4 transformation matrix - * @left: The x coordinate for the first vertical clipping plane - * @bottom: The y coordinate for the first horizontal clipping plane - * @right: The x coordinate for the second vertical clipping plane - * @top: The y coordinate for the second horizontal clipping plane - * @near: The <emphasis>distance</emphasis> to the near clipping - * plane (will be <emphasis>negative</emphasis> if the plane is - * behind the viewer) - * @far: The <emphasis>distance</emphasis> to the far clipping - * plane (will be <emphasis>negative</emphasis> if the plane is - * behind the viewer) - * - * Multiplies @matrix by a parallel projection matrix. - * - * Since: 1.10 - * Stability: unstable - */ -COGL_EXPORT void -cogl_matrix_orthographic (graphene_matrix_t *matrix, - float left, - float bottom, - float right, - float top, - float near, - float far); - -/** - * cogl_matrix_init_from_array: - * @matrix: A 4x4 transformation matrix - * @array: A linear array of 16 floats (column-major order) - * - * Initializes @matrix with the contents of @array - */ -COGL_EXPORT void -cogl_matrix_init_from_array (graphene_matrix_t *matrix, - const float *array); - -/** - * cogl_matrix_init_from_matrix: - * @matrix: A 4x4 transformation matrix - * @source: the #graphene_matrix_t to copy - * - * Initializes @matrix with the contents of @source - */ -COGL_EXPORT void -cogl_matrix_init_from_matrix (graphene_matrix_t *matrix, - const graphene_matrix_t *source); - -/** - * cogl_matrix_to_float: - * @matrix: A 4x4 transformation matrix - * @out_array: (array fixed-size=16) (out caller-allocates): return location - * for an array of floating point values. The array must be capable of - * holding at least 16 values. - * - * Casts @matrix to a float array which can be directly passed to OpenGL. - */ -COGL_EXPORT void -cogl_matrix_to_float (const graphene_matrix_t *matrix, - float *out_array); - -/** - * cogl_matrix_get_value: - * @matrix: A 4x4 transformation matrix - * - * - */ -COGL_EXPORT float -cogl_matrix_get_value (const graphene_matrix_t *matrix, - unsigned int row, - unsigned int column); - -/** - * cogl_matrix_init_from_euler: - * @matrix: A 4x4 transformation matrix - * @euler: A #graphene_euler_t - * - * Initializes @matrix from a #graphene_euler_t rotation. - */ -COGL_EXPORT void -cogl_matrix_init_from_euler (graphene_matrix_t *matrix, - const graphene_euler_t *euler); - -/** - * cogl_matrix_equal: - * @v1: A 4x4 transformation matrix - * @v2: A 4x4 transformation matrix - * - * Compares two matrices to see if they represent the same - * transformation. Although internally the matrices may have different - * annotations associated with them and may potentially have a cached - * inverse matrix these are not considered in the comparison. - * - * Since: 1.4 - */ -COGL_EXPORT gboolean -cogl_matrix_equal (const void *v1, const void *v2); - -/** - * cogl_matrix_copy: - * @matrix: A 4x4 transformation matrix you want to copy - * - * Allocates a new #graphene_matrix_t on the heap and initializes it with - * the same values as @matrix. - * - * Return value: (transfer full): A newly allocated #graphene_matrix_t which - * should be freed using cogl_matrix_free() - * - * Since: 1.6 - */ -COGL_EXPORT graphene_matrix_t * -cogl_matrix_copy (const graphene_matrix_t *matrix); - -/** - * cogl_matrix_free: - * @matrix: A 4x4 transformation matrix you want to free - * - * Frees a #graphene_matrix_t that was previously allocated via a call to - * cogl_matrix_copy(). - * - * Since: 1.6 - */ -COGL_EXPORT void -cogl_matrix_free (graphene_matrix_t *matrix); - -/** - * cogl_matrix_is_identity: - * @matrix: A #graphene_matrix_t - * - * Determines if the given matrix is an identity matrix. - * - * Returns: %TRUE if @matrix is an identity matrix else %FALSE - * Since: 1.8 - */ -COGL_EXPORT gboolean -cogl_matrix_is_identity (const graphene_matrix_t *matrix); - -/** - * cogl_matrix_transpose: - * @matrix: A #graphene_matrix_t - * - * Replaces @matrix with its transpose. Ie, every element (i,j) in the - * new matrix is taken from element (j,i) in the old matrix. - * - * Since: 1.10 - */ -COGL_EXPORT void -cogl_matrix_transpose (graphene_matrix_t *matrix); - -/** - * cogl_debug_matrix_print: - * @matrix: A #graphene_matrix_t - * - * Prints the contents of a #graphene_matrix_t to stdout. - * - * Since: 2.0 - */ -COGL_EXPORT void -cogl_debug_matrix_print (const graphene_matrix_t *matrix); - -/** - * cogl_matrix_determinant: - * @matrix: a #graphene_matrix_t - * - * Computes the determinant of the @matrix. - * - * Returns: the value of the determinant - */ -COGL_EXPORT float -cogl_matrix_determinant (const graphene_matrix_t *matrix); - -/** - * cogl_matrix_skew_xy: - * @matrix: a #graphene_matrix_t - * @factor: skew factor - * - * Adds a skew of factor on the X and Y axis to @matrix. - */ -COGL_EXPORT void -cogl_matrix_skew_xy (graphene_matrix_t *matrix, - float factor); - -/** - * cogl_matrix_skew_xz: - * @matrix: a #graphene_matrix_t - * @factor: skew factor - * - * Adds a skew of factor on the X and Z axis to @matrix. - */ -COGL_EXPORT void -cogl_matrix_skew_xz (graphene_matrix_t *matrix, - float factor); - -/** - * cogl_matrix_skew_yz: - * @matrix: a #graphene_matrix_t - * @factor: skew factor - * - * Adds a skew of factor on the Y and Z axis to @matrix. - */ -COGL_EXPORT void -cogl_matrix_skew_yz (graphene_matrix_t *matrix, - float factor); - -G_END_DECLS - -#endif /* __COGL_MATRIX_H */ |