@gtkx/ffi 0.1.45 → 0.1.46

package/dist/generated/graphene/matrix.d.ts

@@ -10,74 +10,551 @@ import { Rect } from "./rect.js";
 import { Sphere } from "./sphere.js";
 import { Vec3 } from "./vec3.js";
 import { Vec4 } from "./vec4.js";
+/**
+ * A structure capable of holding a 4x4 matrix.
+ *
+ * The contents of the #graphene_matrix_t structure are private and
+ * should never be accessed directly.
+ */
 export declare class Matrix {
     ptr: unknown;
+    /**
+     * Allocates a new #graphene_matrix_t.
+     */
     constructor();
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Decomposes a transformation matrix into its component transformations.
+     *
+     * The algorithm for decomposing a matrix is taken from the
+     * [CSS3 Transforms specification](http://dev.w3.org/csswg/css-transforms/);
+     * specifically, the decomposition code is based on the equivalent code
+     * published in "Graphics Gems II", edited by Jim Arvo, and
+     * [available online](http://web.archive.org/web/20150512160205/http://tog.acm.org/resources/GraphicsGems/gemsii/unmatrix.c).
+     * @param translate - the translation vector
+     * @param scale - the scale vector
+     * @param rotate - the rotation quaternion
+     * @param shear - the shear vector
+     * @param perspective - the perspective vector
+     */
     decompose(translate: Ref<Vec3>, scale: Ref<Vec3>, rotate: Ref<Quaternion>, shear: Ref<Vec3>, perspective: Ref<Vec4>): boolean;
+    /**
+     * Computes the determinant of the given matrix.
+     */
     determinant(): number;
+    /**
+     * Checks whether the two given #graphene_matrix_t matrices are equal.
+     * @param b - a #graphene_matrix_t
+     */
     equal(b: Matrix): boolean;
+    /**
+     * Checks whether the two given #graphene_matrix_t matrices are
+     * byte-by-byte equal.
+     *
+     * While this function is faster than graphene_matrix_equal(), it
+     * can also return false negatives, so it should be used in
+     * conjuction with either graphene_matrix_equal() or
+     * graphene_matrix_near(). For instance:
+     *
+     * |[<!-- language="C" -->
+     * if (graphene_matrix_equal_fast (a, b))
+     * {
+     * // matrices are definitely the same
+     * }
+     * else
+     * {
+     * if (graphene_matrix_equal (a, b))
+     * // matrices contain the same values within an epsilon of FLT_EPSILON
+     * else if (graphene_matrix_near (a, b, 0.0001))
+     * // matrices contain the same values within an epsilon of 0.0001
+     * else
+     * // matrices are not equal
+     * }
+     * ]|
+     * @param b - a #graphene_matrix_t
+     */
     equalFast(b: Matrix): boolean;
+    /**
+     * Frees the resources allocated by graphene_matrix_alloc().
+     */
     free(): void;
+    /**
+     * Retrieves the given row vector at `index_` inside a matrix.
+     * @param index_ - the index of the row vector, between 0 and 3
+     * @param res - return location for the #graphene_vec4_t
+     */
     getRow(index_: number, res: Ref<Vec4>): void;
+    /**
+     * Retrieves the value at the given `row` and `col` index.
+     * @param row - the row index
+     * @param col - the column index
+     */
     getValue(row: number, col: number): number;
+    /**
+     * Retrieves the scaling factor on the X axis in @m.
+     */
     getXScale(): number;
+    /**
+     * Retrieves the translation component on the X axis from @m.
+     */
     getXTranslation(): number;
+    /**
+     * Retrieves the scaling factor on the Y axis in @m.
+     */
     getYScale(): number;
+    /**
+     * Retrieves the translation component on the Y axis from @m.
+     */
     getYTranslation(): number;
+    /**
+     * Retrieves the scaling factor on the Z axis in @m.
+     */
     getZScale(): number;
+    /**
+     * Retrieves the translation component on the Z axis from @m.
+     */
     getZTranslation(): number;
+    /**
+     * Initializes a #graphene_matrix_t from the values of an affine
+     * transformation matrix.
+     *
+     * The arguments map to the following matrix layout:
+     *
+     * |[<!-- language="plain" -->
+     * ⎛ xx  yx ⎞   ⎛  a   b  0 ⎞
+     * ⎜ xy  yy ⎟ = ⎜  c   d  0 ⎟
+     * ⎝ x0  y0 ⎠   ⎝ tx  ty  1 ⎠
+     * ]|
+     *
+     * This function can be used to convert between an affine matrix type
+     * from other libraries and a #graphene_matrix_t.
+     * @param xx - the xx member
+     * @param yx - the yx member
+     * @param xy - the xy member
+     * @param yy - the yy member
+     * @param x_0 - the x0 member
+     * @param y_0 - the y0 member
+     */
     initFrom_2d(xx: number, yx: number, xy: number, yy: number, x_0: number, y_0: number): Matrix;
+    /**
+     * Initializes a #graphene_matrix_t with the given array of floating
+     * point values.
+     * @param v - an array of at least 16 floating
+     */
     initFromFloat(v: number[]): Matrix;
+    /**
+     * Initializes a #graphene_matrix_t using the values of the
+     * given matrix.
+     * @param src - a #graphene_matrix_t
+     */
     initFromMatrix(src: Matrix): Matrix;
+    /**
+     * Initializes a #graphene_matrix_t with the given four row
+     * vectors.
+     * @param v0 - the first row vector
+     * @param v1 - the second row vector
+     * @param v2 - the third row vector
+     * @param v3 - the fourth row vector
+     */
     initFromVec4(v0: Vec4, v1: Vec4, v2: Vec4, v3: Vec4): Matrix;
+    /**
+     * Initializes a #graphene_matrix_t compatible with #graphene_frustum_t.
+     *
+     * See also: graphene_frustum_init_from_matrix()
+     * @param left - distance of the left clipping plane
+     * @param right - distance of the right clipping plane
+     * @param bottom - distance of the bottom clipping plane
+     * @param top - distance of the top clipping plane
+     * @param zNear - distance of the near clipping plane
+     * @param zFar - distance of the far clipping plane
+     */
     initFrustum(left: number, right: number, bottom: number, top: number, zNear: number, zFar: number): Matrix;
+    /**
+     * Initializes a #graphene_matrix_t with the identity matrix.
+     */
     initIdentity(): Matrix;
+    /**
+     * Initializes a #graphene_matrix_t so that it positions the "camera"
+     * at the given `eye` coordinates towards an object at the `center` coordinates. The top of the camera is aligned to the direction
+     * of the `up` vector.
+     *
+     * Before the transform, the camera is assumed to be placed at the
+     * origin, looking towards the negative Z axis, with the top side of
+     * the camera facing in the direction of the Y axis and the right
+     * side in the direction of the X axis.
+     *
+     * In theory, one could use `m` to transform a model of such a camera
+     * into world-space. However, it is more common to use the inverse of
+     * `m` to transform another object from world coordinates to the view
+     * coordinates of the camera. Typically you would then apply the
+     * camera projection transform to get from view to screen
+     * coordinates.
+     * @param eye - the vector describing the position to look from
+     * @param center - the vector describing the position to look at
+     * @param up - the vector describing the world's upward direction; usually,
+     */
     initLookAt(eye: Vec3, center: Vec3, up: Vec3): Matrix;
+    /**
+     * Initializes a #graphene_matrix_t with an orthographic projection.
+     * @param left - the left edge of the clipping plane
+     * @param right - the right edge of the clipping plane
+     * @param top - the top edge of the clipping plane
+     * @param bottom - the bottom edge of the clipping plane
+     * @param zNear - the distance of the near clipping plane
+     * @param zFar - the distance of the far clipping plane
+     */
     initOrtho(left: number, right: number, top: number, bottom: number, zNear: number, zFar: number): Matrix;
+    /**
+     * Initializes a #graphene_matrix_t with a perspective projection.
+     * @param fovy - the field of view angle, in degrees
+     * @param aspect - the aspect value
+     * @param zNear - the near Z plane
+     * @param zFar - the far Z plane
+     */
     initPerspective(fovy: number, aspect: number, zNear: number, zFar: number): Matrix;
+    /**
+     * Initializes `m` to represent a rotation of `angle` degrees on
+     * the axis represented by the `axis` vector.
+     * @param angle - the rotation angle, in degrees
+     * @param axis - the axis vector as a #graphene_vec3_t
+     */
     initRotate(angle: number, axis: Vec3): Matrix;
+    /**
+     * Initializes a #graphene_matrix_t with the given scaling factors.
+     * @param x - the scale factor on the X axis
+     * @param y - the scale factor on the Y axis
+     * @param z - the scale factor on the Z axis
+     */
     initScale(x: number, y: number, z: number): Matrix;
+    /**
+     * Initializes a #graphene_matrix_t with a skew transformation
+     * with the given factors.
+     * @param xSkew - skew factor, in radians, on the X axis
+     * @param ySkew - skew factor, in radians, on the Y axis
+     */
     initSkew(xSkew: number, ySkew: number): Matrix;
+    /**
+     * Initializes a #graphene_matrix_t with a translation to the
+     * given coordinates.
+     * @param p - the translation coordinates
+     */
     initTranslate(p: Point3D): Matrix;
+    /**
+     * Linearly interpolates the two given #graphene_matrix_t by
+     * interpolating the decomposed transformations separately.
+     *
+     * If either matrix cannot be reduced to their transformations
+     * then the interpolation cannot be performed, and this function
+     * will return an identity matrix.
+     * @param b - a #graphene_matrix_t
+     * @param factor - the linear interpolation factor
+     * @param res - return location for the
+     */
     interpolate(b: Matrix, factor: number, res: Ref<Matrix>): void;
+    /**
+     * Inverts the given matrix.
+     * @param res - return location for the
+     */
     inverse(res: Ref<Matrix>): boolean;
+    /**
+     * Checks whether the given #graphene_matrix_t is compatible with an
+     * a 2D affine transformation matrix.
+     */
     is_2d(): boolean;
+    /**
+     * Checks whether a #graphene_matrix_t has a visible back face.
+     */
     isBackfaceVisible(): boolean;
+    /**
+     * Checks whether the given #graphene_matrix_t is the identity matrix.
+     */
     isIdentity(): boolean;
+    /**
+     * Checks whether a matrix is singular.
+     */
     isSingular(): boolean;
+    /**
+     * Multiplies two #graphene_matrix_t.
+     *
+     * Matrix multiplication is not commutative in general; the order of the factors matters.
+     * The product of this multiplication is (`a` × @b)
+     * @param b - a #graphene_matrix_t
+     * @param res - return location for the matrix
+     */
     multiply(b: Matrix, res: Ref<Matrix>): void;
+    /**
+     * Compares the two given #graphene_matrix_t matrices and checks
+     * whether their values are within the given `epsilon` of each
+     * other.
+     * @param b - a #graphene_matrix_t
+     * @param epsilon - the threshold between the two matrices
+     */
     near(b: Matrix, epsilon: number): boolean;
+    /**
+     * Normalizes the given #graphene_matrix_t.
+     * @param res - return location for the normalized matrix
+     */
     normalize(res: Ref<Matrix>): void;
+    /**
+     * Applies a perspective of `depth` to the matrix.
+     * @param depth - the depth of the perspective
+     * @param res - return location for the
+     */
     perspective(depth: number, res: Ref<Matrix>): void;
+    /**
+     * Prints the contents of a matrix to the standard error stream.
+     *
+     * This function is only useful for debugging; there are no guarantees
+     * made on the format of the output.
+     */
     print(): void;
+    /**
+     * Projects a #graphene_point_t using the matrix @m.
+     * @param p - a #graphene_point_t
+     * @param res - return location for the projected
+     */
     projectPoint(p: Point, res: Ref<Point>): void;
+    /**
+     * Projects all corners of a #graphene_rect_t using the given matrix.
+     *
+     * See also: graphene_matrix_project_point()
+     * @param r - a #graphene_rect_t
+     * @param res - return location for the projected
+     */
     projectRect(r: Rect, res: Ref<Quad>): void;
+    /**
+     * Projects a #graphene_rect_t using the given matrix.
+     *
+     * The resulting rectangle is the axis aligned bounding rectangle capable
+     * of fully containing the projected rectangle.
+     * @param r - a #graphene_rect_t
+     * @param res - return location for the projected
+     */
     projectRectBounds(r: Rect, res: Ref<Rect>): void;
+    /**
+     * Adds a rotation transformation to @m, using the given `angle` and `axis` vector.
+     *
+     * This is the equivalent of calling graphene_matrix_init_rotate() and
+     * then multiplying the matrix `m` with the rotation matrix.
+     * @param angle - the rotation angle, in degrees
+     * @param axis - the rotation axis, as a #graphene_vec3_t
+     */
     rotate(angle: number, axis: Vec3): void;
+    /**
+     * Adds a rotation transformation to @m, using the given
+     * #graphene_euler_t.
+     * @param e - a rotation described by a #graphene_euler_t
+     */
     rotateEuler(e: Euler): void;
+    /**
+     * Adds a rotation transformation to @m, using the given
+     * #graphene_quaternion_t.
+     *
+     * This is the equivalent of calling graphene_quaternion_to_matrix() and
+     * then multiplying `m` with the rotation matrix.
+     * @param q - a rotation described by a #graphene_quaternion_t
+     */
     rotateQuaternion(q: Quaternion): void;
+    /**
+     * Adds a rotation transformation around the X axis to @m, using
+     * the given @angle.
+     *
+     * See also: graphene_matrix_rotate()
+     * @param angle - the rotation angle, in degrees
+     */
     rotateX(angle: number): void;
+    /**
+     * Adds a rotation transformation around the Y axis to @m, using
+     * the given @angle.
+     *
+     * See also: graphene_matrix_rotate()
+     * @param angle - the rotation angle, in degrees
+     */
     rotateY(angle: number): void;
+    /**
+     * Adds a rotation transformation around the Z axis to @m, using
+     * the given @angle.
+     *
+     * See also: graphene_matrix_rotate()
+     * @param angle - the rotation angle, in degrees
+     */
     rotateZ(angle: number): void;
+    /**
+     * Adds a scaling transformation to @m, using the three
+     * given factors.
+     *
+     * This is the equivalent of calling graphene_matrix_init_scale() and then
+     * multiplying the matrix `m` with the scale matrix.
+     * @param factorX - scaling factor on the X axis
+     * @param factorY - scaling factor on the Y axis
+     * @param factorZ - scaling factor on the Z axis
+     */
     scale(factorX: number, factorY: number, factorZ: number): void;
+    /**
+     * Adds a skew of `factor` on the X and Y axis to the given matrix.
+     * @param factor - skew factor
+     */
     skewXy(factor: number): void;
+    /**
+     * Adds a skew of `factor` on the X and Z axis to the given matrix.
+     * @param factor - skew factor
+     */
     skewXz(factor: number): void;
+    /**
+     * Adds a skew of `factor` on the Y and Z axis to the given matrix.
+     * @param factor - skew factor
+     */
     skewYz(factor: number): void;
+    /**
+     * Converts a #graphene_matrix_t to an affine transformation
+     * matrix, if the given matrix is compatible.
+     *
+     * The returned values have the following layout:
+     *
+     * |[<!-- language="plain" -->
+     * ⎛ xx  yx ⎞   ⎛  a   b  0 ⎞
+     * ⎜ xy  yy ⎟ = ⎜  c   d  0 ⎟
+     * ⎝ x0  y0 ⎠   ⎝ tx  ty  1 ⎠
+     * ]|
+     *
+     * This function can be used to convert between a #graphene_matrix_t
+     * and an affine matrix type from other libraries.
+     * @param xx - return location for the xx member
+     * @param yx - return location for the yx member
+     * @param xy - return location for the xy member
+     * @param yy - return location for the yy member
+     * @param x_0 - return location for the x0 member
+     * @param y_0 - return location for the y0 member
+     */
     to_2d(xx: Ref<number>, yx: Ref<number>, xy: Ref<number>, yy: Ref<number>, x_0: Ref<number>, y_0: Ref<number>): boolean;
+    /**
+     * Converts a #graphene_matrix_t to an array of floating point
+     * values.
+     * @param v - return location
+     */
     toFloat(v: Ref<number[]>): void;
+    /**
+     * Transforms each corner of a #graphene_rect_t using the given matrix @m.
+     *
+     * The result is the axis aligned bounding rectangle containing the coplanar
+     * quadrilateral.
+     *
+     * See also: graphene_matrix_transform_point()
+     * @param r - a #graphene_rect_t
+     * @param res - return location for the bounds
+     */
     transformBounds(r: Rect, res: Ref<Rect>): void;
+    /**
+     * Transforms the vertices of a #graphene_box_t using the given matrix @m.
+     *
+     * The result is the axis aligned bounding box containing the transformed
+     * vertices.
+     * @param b - a #graphene_box_t
+     * @param res - return location for the bounds
+     */
     transformBox(b: Box, res: Ref<Box>): void;
+    /**
+     * Transforms the given #graphene_point_t using the matrix @m.
+     *
+     * Unlike graphene_matrix_transform_vec3(), this function will take into
+     * account the fourth row vector of the #graphene_matrix_t when computing
+     * the dot product of each row vector of the matrix.
+     *
+     * See also: graphene_simd4x4f_point3_mul()
+     * @param p - a #graphene_point_t
+     * @param res - return location for the
+     */
     transformPoint(p: Point, res: Ref<Point>): void;
+    /**
+     * Transforms the given #graphene_point3d_t using the matrix @m.
+     *
+     * Unlike graphene_matrix_transform_vec3(), this function will take into
+     * account the fourth row vector of the #graphene_matrix_t when computing
+     * the dot product of each row vector of the matrix.
+     *
+     * See also: graphene_simd4x4f_point3_mul()
+     * @param p - a #graphene_point3d_t
+     * @param res - return location for the result
+     */
     transformPoint3d(p: Point3D, res: Ref<Point3D>): void;
+    /**
+     * Transform a #graphene_ray_t using the given matrix @m.
+     * @param r - a #graphene_ray_t
+     * @param res - return location for the
+     */
     transformRay(r: Ray, res: Ref<Ray>): void;
+    /**
+     * Transforms each corner of a #graphene_rect_t using the given matrix @m.
+     *
+     * The result is a coplanar quadrilateral.
+     *
+     * See also: graphene_matrix_transform_point()
+     * @param r - a #graphene_rect_t
+     * @param res - return location for the
+     */
     transformRect(r: Rect, res: Ref<Quad>): void;
+    /**
+     * Transforms a #graphene_sphere_t using the given matrix @m. The
+     * result is the bounding sphere containing the transformed sphere.
+     * @param s - a #graphene_sphere_t
+     * @param res - return location for the bounds
+     */
     transformSphere(s: Sphere, res: Ref<Sphere>): void;
+    /**
+     * Transforms the given #graphene_vec3_t using the matrix @m.
+     *
+     * This function will multiply the X, Y, and Z row vectors of the matrix `m` with the corresponding components of the vector @v. The W row vector will
+     * be ignored.
+     *
+     * See also: graphene_simd4x4f_vec3_mul()
+     * @param v - a #graphene_vec3_t
+     * @param res - return location for a #graphene_vec3_t
+     */
     transformVec3(v: Vec3, res: Ref<Vec3>): void;
+    /**
+     * Transforms the given #graphene_vec4_t using the matrix @m.
+     *
+     * See also: graphene_simd4x4f_vec4_mul()
+     * @param v - a #graphene_vec4_t
+     * @param res - return location for a #graphene_vec4_t
+     */
     transformVec4(v: Vec4, res: Ref<Vec4>): void;
+    /**
+     * Adds a translation transformation to `m` using the coordinates
+     * of the given #graphene_point3d_t.
+     *
+     * This is the equivalent of calling graphene_matrix_init_translate() and
+     * then multiplying `m` with the translation matrix.
+     * @param pos - a #graphene_point3d_t
+     */
     translate(pos: Point3D): void;
+    /**
+     * Transposes the given matrix.
+     * @param res - return location for the
+     */
     transpose(res: Ref<Matrix>): void;
+    /**
+     * Unprojects the given `point` using the `projection` matrix and
+     * a `modelview` matrix.
+     * @param modelview - a #graphene_matrix_t for the modelview matrix; this is
+     * @param point - a #graphene_point3d_t with the coordinates of the point
+     * @param res - return location for the unprojected
+     */
     unprojectPoint3d(modelview: Matrix, point: Point3D, res: Ref<Point3D>): void;
+    /**
+     * Undoes the transformation on the corners of a #graphene_rect_t using the
+     * given matrix, within the given axis aligned rectangular @bounds.
+     * @param r - a #graphene_rect_t
+     * @param bounds - the bounds of the transformation
+     * @param res - return location for the
+     */
     untransformBounds(r: Rect, bounds: Rect, res: Ref<Rect>): void;
+    /**
+     * Undoes the transformation of a #graphene_point_t using the
+     * given matrix, within the given axis aligned rectangular @bounds.
+     * @param p - a #graphene_point_t
+     * @param bounds - the bounds of the transformation
+     * @param res - return location for the
+     */
     untransformPoint(p: Point, bounds: Rect, res: Ref<Point>): boolean;
 }