path: root/renderscript/include/rs_matrix.rsh

/*
 * Copyright (C) 2015 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

// Don't edit this file!  It is auto-generated by frameworks/rs/api/gen_runtime.

/*
 * rs_matrix.rsh: Matrix functions
 *
 * These functions let you manipulate square matrices of rank 2x2, 3x3, and 4x4.
 * They are particularly useful for graphical transformations and are
 * compatible with OpenGL.
 *
 * We use a zero-based index for rows and columns.  E.g. the last element of
 * a rs_matrix4x4 is found at (3, 3).
 *
 * RenderScript uses column-major matrices and column-based vectors.
 * Transforming a vector is done by postmultiplying the vector,
 * e.g. (matrix * vector), as provided by rsMatrixMultiply().
 *
 * To create a transformation matrix that performs two transformations at
 * once, multiply the two source matrices, with the first transformation as the
 * right argument.  E.g. to create a transformation matrix that applies the
 * transformation s1 followed by s2, call rsMatrixLoadMultiply(&combined, &s2, &s1).
 * This derives from s2 * (s1 * v), which is (s2 * s1) * v.
 *
 * We have two style of functions to create transformation matrices:
 * rsMatrixLoadTransformation and rsMatrixTransformation.  The
 * former style simply stores the transformation matrix in the first argument.
 * The latter modifies a pre-existing transformation matrix so that the new
 * transformation happens first.  E.g. if you call rsMatrixTranslate()
 * on a matrix that already does a scaling, the resulting matrix when applied
 * to a vector will first do the translation then the scaling.
 */
#ifndef RENDERSCRIPT_RS_MATRIX_RSH
#define RENDERSCRIPT_RS_MATRIX_RSH

/*
 * rsMatrixGet: Get one element
 *
 * Returns one element of a matrix.
 *
 * Warning: The order of the column and row parameters may be unexpected.
 *
 * Parameters:
 *   m The matrix to extract the element from.
 *   col The zero-based column of the element to be extracted.
 *   row The zero-based row of the element to extracted.
 */
extern float __attribute__((overloadable))
    rsMatrixGet(const rs_matrix4x4* m, uint32_t col, uint32_t row);

extern float __attribute__((overloadable))
    rsMatrixGet(const rs_matrix3x3* m, uint32_t col, uint32_t row);

extern float __attribute__((overloadable))
    rsMatrixGet(const rs_matrix2x2* m, uint32_t col, uint32_t row);

/*
 * rsMatrixInverse: Inverts a matrix in place
 *
 * Returns true if the matrix was successfully inverted.
 *
 * Parameters:
 *   m The matrix to invert.
 */
extern bool __attribute__((overloadable))
    rsMatrixInverse(rs_matrix4x4* m);

/*
 * rsMatrixInverseTranspose: Inverts and transpose a matrix in place
 *
 * The matrix is first inverted then transposed.
 * Returns true if the matrix was successfully inverted.
 *
 * Parameters:
 *   m The matrix to modify.
 */
extern bool __attribute__((overloadable))
    rsMatrixInverseTranspose(rs_matrix4x4* m);

/*
 * rsMatrixLoad: Load or copy a matrix
 *
 * Set the elements of a matrix from an array of floats or from another matrix.
 *
 * If loading from an array, the floats should be in row-major order, i.e. the element a
 * row 0, column 0 should be first, followed by the element at
 * row 0, column 1, etc.
 *
 * If loading from a matrix and the source is smaller than the destination, the rest of the
 * destination is filled with elements of the identity matrix.  E.g.
 * loading a rs_matrix2x2 into a rs_matrix4x4 will give:
 *
 * m00 m01 0.0 0.0
 * m10 m11 0.0 0.0
 * 0.0 0.0 1.0 0.0
 * 0.0 0.0 0.0 1.0
 *
 *
 * Parameters:
 *   destination The matrix to set.
 *   array The array of values to set the matrix to. These arrays should be 4, 9, or 16 floats long, depending on the matrix size.
 *   source The source matrix.
 */
extern void __attribute__((overloadable))
    rsMatrixLoad(rs_matrix4x4* destination, const float* array);

extern void __attribute__((overloadable))
    rsMatrixLoad(rs_matrix3x3* destination, const float* array);

extern void __attribute__((overloadable))
    rsMatrixLoad(rs_matrix2x2* destination, const float* array);

extern void __attribute__((overloadable))
    rsMatrixLoad(rs_matrix4x4* destination, const rs_matrix4x4* source);

extern void __attribute__((overloadable))
    rsMatrixLoad(rs_matrix3x3* destination, const rs_matrix3x3* source);

extern void __attribute__((overloadable))
    rsMatrixLoad(rs_matrix2x2* destination, const rs_matrix2x2* source);

extern void __attribute__((overloadable))
    rsMatrixLoad(rs_matrix4x4* destination, const rs_matrix3x3* source);

extern void __attribute__((overloadable))
    rsMatrixLoad(rs_matrix4x4* destination, const rs_matrix2x2* source);

/*
 * rsMatrixLoadFrustum: Load a frustum projection matrix
 *
 * Constructs a frustum projection matrix, transforming the box
 * identified by the six clipping planes left, right, bottom, top,
 * near, far.
 *
 * To apply this projection to a vector, multiply the vector by the
 * created matrix using rsMatrixMultiply().
 *
 * Parameters:
 *   m The matrix to set.
 */
extern void __attribute__((overloadable))
    rsMatrixLoadFrustum(rs_matrix4x4* m, float left, float right, float bottom, float top,
                        float near, float far);

/*
 * rsMatrixLoadIdentity: Load identity matrix
 *
 * Set the elements of a matrix to the identity matrix.
 *
 * Parameters:
 *   m The matrix to set.
 */
extern void __attribute__((overloadable))
    rsMatrixLoadIdentity(rs_matrix4x4* m);

extern void __attribute__((overloadable))
    rsMatrixLoadIdentity(rs_matrix3x3* m);

extern void __attribute__((overloadable))
    rsMatrixLoadIdentity(rs_matrix2x2* m);

/*
 * rsMatrixLoadMultiply: Multiply two matrices
 *
 * Sets m to the matrix product of lhs * rhs.
 *
 * To combine two 4x4 transformaton matrices, multiply the second transformation matrix
 * by the first transformation matrix.  E.g. to create a transformation matrix that applies
 * the transformation s1 followed by s2, call
 * rsMatrixLoadMultiply(&combined, &s2, &s1).
 *
 * Warning: Prior to version 21, storing the result back into right matrix is not supported and
 * will result in undefined behavior.  Use rsMatrixMulitply instead.   E.g. instead of doing
 * rsMatrixLoadMultiply (&m2r, &m2r, &m2l), use rsMatrixMultiply (&m2r, &m2l).
 * rsMatrixLoadMultiply (&m2l, &m2r, &m2l) works as expected.
 *
 * Parameters:
 *   m The matrix to set.
 *   lhs The left matrix of the product.
 *   rhs The right matrix of the product.
 */
extern void __attribute__((overloadable))
    rsMatrixLoadMultiply(rs_matrix4x4* m, const rs_matrix4x4* lhs, const rs_matrix4x4* rhs);

extern void __attribute__((overloadable))
    rsMatrixLoadMultiply(rs_matrix3x3* m, const rs_matrix3x3* lhs, const rs_matrix3x3* rhs);

extern void __attribute__((overloadable))
    rsMatrixLoadMultiply(rs_matrix2x2* m, const rs_matrix2x2* lhs, const rs_matrix2x2* rhs);

/*
 * rsMatrixLoadOrtho: Load an orthographic projection matrix
 *
 * Constructs an orthographic projection matrix, transforming the box
 * identified by the six clipping planes left, right, bottom, top,
 * near, far into a unit cube with a corner at
 * (-1, -1, -1) and the opposite at (1, 1, 1).
 *
 * To apply this projection to a vector, multiply the vector by the
 * created matrix using rsMatrixMultiply().
 *
 * See https://en.wikipedia.org/wiki/Orthographic_projection .
 *
 * Parameters:
 *   m The matrix to set.
 */
extern void __attribute__((overloadable))
    rsMatrixLoadOrtho(rs_matrix4x4* m, float left, float right, float bottom, float top, float near,
                      float far);

/*
 * rsMatrixLoadPerspective: Load a perspective projection matrix
 *
 * Constructs a perspective projection matrix, assuming a symmetrical field of view.
 *
 * To apply this projection to a vector, multiply the vector by the
 * created matrix using rsMatrixMultiply().
 *
 * Parameters:
 *   m The matrix to set.
 *   fovy Field of view, in degrees along the Y axis.
 *   aspect Ratio of x / y.
 *   near The near clipping plane.
 *   far The far clipping plane.
 */
extern void __attribute__((overloadable))
    rsMatrixLoadPerspective(rs_matrix4x4* m, float fovy, float aspect, float near, float far);

/*
 * rsMatrixLoadRotate: Load a rotation matrix
 *
 * This function creates a rotation matrix.  The axis of rotation is the
 * (x, y, z) vector.
 *
 * To rotate a vector, multiply the vector by the created matrix
 * using rsMatrixMultiply().
 *
 * See http://en.wikipedia.org/wiki/Rotation_matrix .
 *
 * Parameters:
 *   m The matrix to set.
 *   rot How much rotation to do, in degrees.
 *   x The x component of the vector that is the axis of rotation.
 *   y The y component of the vector that is the axis of rotation.
 *   z The z component of the vector that is the axis of rotation.
 */
extern void __attribute__((overloadable))
    rsMatrixLoadRotate(rs_matrix4x4* m, float rot, float x, float y, float z);

/*
 * rsMatrixLoadScale: Load a scaling matrix
 *
 * This function creates a scaling matrix, where each component of a
 * vector is multiplied by a number.  This number can be negative.
 *
 * To scale a vector, multiply the vector by the created matrix
 * using rsMatrixMultiply().
 *
 * Parameters:
 *   m The matrix to set.
 *   x The multiple to scale the x components by.
 *   y The multiple to scale the y components by.
 *   z The multiple to scale the z components by.
 */
extern void __attribute__((overloadable))
    rsMatrixLoadScale(rs_matrix4x4* m, float x, float y, float z);

/*
 * rsMatrixLoadTranslate: Load a translation matrix
 *
 * This function creates a translation matrix, where a
 * number is added to each element of a vector.
 *
 * To translate a vector, multiply the vector by the created matrix
 * using rsMatrixMultiply().
 *
 * Parameters:
 *   m The matrix to set.
 *   x The number to add to each x component.
 *   y The number to add to each y component.
 *   z The number to add to each z component.
 */
extern void __attribute__((overloadable))
    rsMatrixLoadTranslate(rs_matrix4x4* m, float x, float y, float z);

/*
 * rsMatrixMultiply: Multiply a matrix by a vector or another matrix
 *
 * For the matrix by matrix variant, sets m to the matrix product m * rhs.
 *
 * When combining two 4x4 transformation matrices using this function, the resulting
 * matrix will correspond to performing the rhs transformation first followed by
 * the original m transformation.
 *
 * For the matrix by vector variant, returns the post-multiplication of the vector
 * by the matrix, ie. m * in.
 *
 * When multiplying a float3 to a rs_matrix4x4, the vector is expanded with (1).
 *
 * When multiplying a float2 to a rs_matrix4x4, the vector is expanded with (0, 1).
 *
 * When multiplying a float2 to a rs_matrix3x3, the vector is expanded with (0).
 *
 * Starting with API 14, this function takes a const matrix as the first argument.
 *
 * Parameters:
 *   m The left matrix of the product and the matrix to be set.
 *   rhs The right matrix of the product.
 */
extern void __attribute__((overloadable))
    rsMatrixMultiply(rs_matrix4x4* m, const rs_matrix4x4* rhs);

extern void __attribute__((overloadable))
    rsMatrixMultiply(rs_matrix3x3* m, const rs_matrix3x3* rhs);

extern void __attribute__((overloadable))
    rsMatrixMultiply(rs_matrix2x2* m, const rs_matrix2x2* rhs);

#if !defined(RS_VERSION) || (RS_VERSION <= 13)
extern float4 __attribute__((overloadable))
    rsMatrixMultiply(rs_matrix4x4* m, float4 in);
#endif

#if !defined(RS_VERSION) || (RS_VERSION <= 13)
extern float4 __attribute__((overloadable))
    rsMatrixMultiply(rs_matrix4x4* m, float3 in);
#endif

#if !defined(RS_VERSION) || (RS_VERSION <= 13)
extern float4 __attribute__((overloadable))
    rsMatrixMultiply(rs_matrix4x4* m, float2 in);
#endif

#if !defined(RS_VERSION) || (RS_VERSION <= 13)
extern float3 __attribute__((overloadable))
    rsMatrixMultiply(rs_matrix3x3* m, float3 in);
#endif

#if !defined(RS_VERSION) || (RS_VERSION <= 13)
extern float3 __attribute__((overloadable))
    rsMatrixMultiply(rs_matrix3x3* m, float2 in);
#endif

#if !defined(RS_VERSION) || (RS_VERSION <= 13)
extern float2 __attribute__((overloadable))
    rsMatrixMultiply(rs_matrix2x2* m, float2 in);
#endif

#if (defined(RS_VERSION) && (RS_VERSION >= 14))
extern float4 __attribute__((overloadable))
    rsMatrixMultiply(const rs_matrix4x4* m, float4 in);
#endif

#if (defined(RS_VERSION) && (RS_VERSION >= 14))
extern float4 __attribute__((overloadable))
    rsMatrixMultiply(const rs_matrix4x4* m, float3 in);
#endif

#if (defined(RS_VERSION) && (RS_VERSION >= 14))
extern float4 __attribute__((overloadable))
    rsMatrixMultiply(const rs_matrix4x4* m, float2 in);
#endif

#if (defined(RS_VERSION) && (RS_VERSION >= 14))
extern float3 __attribute__((overloadable))
    rsMatrixMultiply(const rs_matrix3x3* m, float3 in);
#endif

#if (defined(RS_VERSION) && (RS_VERSION >= 14))
extern float3 __attribute__((overloadable))
    rsMatrixMultiply(const rs_matrix3x3* m, float2 in);
#endif

#if (defined(RS_VERSION) && (RS_VERSION >= 14))
extern float2 __attribute__((overloadable))
    rsMatrixMultiply(const rs_matrix2x2* m, float2 in);
#endif

/*
 * rsMatrixRotate: Apply a rotation to a transformation matrix
 *
 * Multiply the matrix m with a rotation matrix.
 *
 * This function modifies a transformation matrix to first do a rotation.
 * The axis of rotation is the (x, y, z) vector.
 *
 * To apply this combined transformation to a vector, multiply
 * the vector by the created matrix using rsMatrixMultiply().
 *
 * Parameters:
 *   m The matrix to modify.
 *   rot How much rotation to do, in degrees.
 *   x The x component of the vector that is the axis of rotation.
 *   y The y component of the vector that is the axis of rotation.
 *   z The z component of the vector that is the axis of rotation.
 */
extern void __attribute__((overloadable))
    rsMatrixRotate(rs_matrix4x4* m, float rot, float x, float y, float z);

/*
 * rsMatrixScale: Apply a scaling to a transformation matrix
 *
 * Multiply the matrix m with a scaling matrix.
 *
 * This function modifies a transformation matrix to first do a scaling.
 * When scaling, each component of a vector is multiplied by a number.
 * This number can be negative.
 *
 * To apply this combined transformation to a vector, multiply
 * the vector by the created matrix using rsMatrixMultiply().
 *
 * Parameters:
 *   m The matrix to modify.
 *   x The multiple to scale the x components by.
 *   y The multiple to scale the y components by.
 *   z The multiple to scale the z components by.
 */
extern void __attribute__((overloadable))
    rsMatrixScale(rs_matrix4x4* m, float x, float y, float z);

/*
 * rsMatrixSet: Set one element
 *
 * Set an element of a matrix.
 *
 * Warning: The order of the column and row parameters may be unexpected.
 *
 * Parameters:
 *   m The matrix that will be modified.
 *   col The zero-based column of the element to be set.
 *   row The zero-based row of the element to be set.
 *   v The value to set.
 */
extern void __attribute__((overloadable))
    rsMatrixSet(rs_matrix4x4* m, uint32_t col, uint32_t row, float v);

extern void __attribute__((overloadable))
    rsMatrixSet(rs_matrix3x3* m, uint32_t col, uint32_t row, float v);

extern void __attribute__((overloadable))
    rsMatrixSet(rs_matrix2x2* m, uint32_t col, uint32_t row, float v);

/*
 * rsMatrixTranslate: Apply a translation to a transformation matrix
 *
 * Multiply the matrix m with a translation matrix.
 *
 * This function modifies a transformation matrix to first
 * do a translation.  When translating, a number is added
 * to each component of a vector.
 *
 * To apply this combined transformation to a vector, multiply
 * the vector by the created matrix using rsMatrixMultiply().
 *
 * Parameters:
 *   m The matrix to modify.
 *   x The number to add to each x component.
 *   y The number to add to each y component.
 *   z The number to add to each z component.
 */
extern void __attribute__((overloadable))
    rsMatrixTranslate(rs_matrix4x4* m, float x, float y, float z);

/*
 * rsMatrixTranspose: Transpose a matrix place
 *
 * Transpose the matrix m in place.
 *
 * Parameters:
 *   m The matrix to transpose.
 */
extern void __attribute__((overloadable))
    rsMatrixTranspose(rs_matrix4x4* m);

extern void __attribute__((overloadable))
    rsMatrixTranspose(rs_matrix3x3* m);

extern void __attribute__((overloadable))
    rsMatrixTranspose(rs_matrix2x2* m);

#endif // RENDERSCRIPT_RS_MATRIX_RSH