@gtkx/ffi 0.1.45 → 0.1.46

package/dist/generated/gsk/transform-node.d.ts

@@ -1,9 +1,21 @@
 import { Transform } from "./transform.js";
 import { RenderNode } from "./render-node.js";
+/** A render node applying a `GskTransform` to its single child node. */
 export declare class TransformNode extends RenderNode {
+    /**
+     * Creates a `GskRenderNode` that will transform the given `child` with the given @transform.
+     * @param child - The node to transform
+     * @param transform - The transform to apply
+     */
     constructor(child: RenderNode, transform: Transform);
     constructor(...args: unknown[]);
     protected createPtr(args: unknown[]): unknown;
+    /**
+     * Gets the child node that is getting transformed by the given @node.
+     */
     getChild(): RenderNode;
+    /**
+     * Retrieves the `GskTransform` used by the @node.
+     */
     getTransform(): Transform;
 }

package/dist/generated/gsk/transform-node.js

@@ -2,6 +2,7 @@ import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
 import { Transform } from "./transform.js";
 import { RenderNode } from "./render-node.js";
+/** A render node applying a `GskTransform` to its single child node. */
 export class TransformNode extends RenderNode {
     constructor(...args) {
         super(...args);
@@ -24,6 +25,9 @@ export class TransformNode extends RenderNode {
             },
         ], { type: "gobject", borrowed: false });
     }
+    /**
+     * Gets the child node that is getting transformed by the given @node.
+     */
     getChild() {
         const ptr = call("libgtk-4.so.1", "gsk_transform_node_get_child", [
             {
@@ -33,6 +37,9 @@ export class TransformNode extends RenderNode {
         ], { type: "gobject", borrowed: true });
         return getObject(ptr, RenderNode);
     }
+    /**
+     * Retrieves the `GskTransform` used by the @node.
+     */
     getTransform() {
         const ptr = call("libgtk-4.so.1", "gsk_transform_node_get_transform", [
             {

package/dist/generated/gsk/transform.d.ts

@@ -2,34 +2,316 @@ import { Ref } from "@gtkx/native";
 import { TransformCategory } from "./enums.js";
 import * as GLib from "../glib/index.js";
 import * as Graphene from "../graphene/index.js";
+/**
+ * Describes a 3D transform.
+ *
+ * Unlike `graphene_matrix_t`, `GskTransform` retains the steps in how
+ * a transform was constructed, and allows inspecting them. It is modeled
+ * after the way CSS describes transforms.
+ *
+ * `GskTransform` objects are immutable and cannot be changed after creation.
+ * This means code can safely expose them as properties of objects without
+ * having to worry about others changing them.
+ */
 export declare class Transform {
     ptr: unknown;
+    /**
+     * Creates a new identity transform.
+     *
+     * This function is meant to be used by language
+     * bindings. For C code, this is equivalent to using `NULL`.
+     */
     constructor();
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Parses a given into a transform.
+     *
+     * Strings printed via [method@Gsk.Transform.to_string]
+     * can be read in again successfully using this function.
+     *
+     * If `string` does not describe a valid transform, false
+     * is returned and `NULL` is put in @out_transform.
+     * @param string - the string to parse
+     * @param outTransform - return location for the transform
+     */
     static parse(string: string, outTransform: Ref<Transform>): boolean;
+    /**
+     * Checks two transforms for equality.
+     * @param second - the second transform
+     */
     equal(second?: Transform | null): boolean;
+    /**
+     * Returns the category this transform belongs to.
+     */
     getCategory(): TransformCategory;
+    /**
+     * Inverts the given transform.
+     *
+     * If `self` is not invertible, `NULL` is returned.
+     * Note that inverting `NULL` also returns `NULL`, which is
+     * the correct inverse of `NULL`. If you need to differentiate
+     * between those cases, you should check `self` is not `NULL`
+     * before calling this function.
+     *
+     * This function consumes @self. Use [method@Gsk.Transform.ref] first
+     * if you want to keep it around.
+     */
     invert(): Transform | null;
+    /**
+     * Multiplies `next` with the given @matrix.
+     *
+     * This function consumes @next. Use [method@Gsk.Transform.ref] first
+     * if you want to keep it around.
+     * @param matrix - the matrix to multiply `next` with
+     */
     matrix(matrix: Graphene.Matrix): Transform;
+    /**
+     * Multiplies `next` with the matrix [ xx yx x0; xy yy y0; 0 0 1 ].
+     *
+     * The result of calling [method@Gsk.Transform.to_2d] on the returned
+     * [struct@Gsk.Transform] should match the input passed to this
+     * function.
+     *
+     * This function consumes @next. Use [method@Gsk.Transform.ref] first
+     * if you want to keep it around.
+     * @param xx - the xx member
+     * @param yx - the yx member
+     * @param xy - the xy member
+     * @param yy - the yy member
+     * @param dx - the x0 member
+     * @param dy - the y0 member
+     */
     matrix_2d(xx: number, yx: number, xy: number, yy: number, dx: number, dy: number): Transform | null;
+    /**
+     * Applies a perspective projection transform.
+     *
+     * This transform scales points in X and Y based on their Z value,
+     * scaling points with positive Z values away from the origin, and
+     * those with negative Z values towards the origin. Points
+     * on the z=0 plane are unchanged.
+     *
+     * This function consumes @next. Use [method@Gsk.Transform.ref] first
+     * if you want to keep it around.
+     * @param depth - distance of the z=0 plane. Lower values give a more
+     */
     perspective(depth: number): Transform;
+    /**
+     * Converts the transform into a human-readable representation.
+     *
+     * The result of this function can later be parsed with
+     * [func@Gsk.Transform.parse].
+     * @param string - The string to print into
+     */
     print(string: GLib.String): void;
+    /**
+     * Acquires a reference on the given transform.
+     */
     ref(): Transform | null;
+    /**
+     * Rotates `next` by an angle around the Z axis.
+     *
+     * The rotation happens around the origin point of (0, 0).
+     *
+     * This function consumes @next. Use [method@Gsk.Transform.ref] first
+     * if you want to keep it around.
+     * @param angle - the rotation angle, in degrees (clockwise)
+     */
     rotate(angle: number): Transform | null;
+    /**
+     * Rotates `next` `angle` degrees around @axis.
+     *
+     * For a rotation in 2D space, use [method@Gsk.Transform.rotate]
+     *
+     * This function consumes @next. Use [method@Gsk.Transform.ref] first
+     * if you want to keep it around.
+     * @param angle - the rotation angle, in degrees (clockwise)
+     * @param axis - The rotation axis
+     */
     rotate_3d(angle: number, axis: Graphene.Vec3): Transform | null;
+    /**
+     * Scales `next` in 2-dimensional space by the given factors.
+     *
+     * Use [method@Gsk.Transform.scale_3d] to scale in all 3 dimensions.
+     *
+     * This function consumes @next. Use [method@Gsk.Transform.ref] first
+     * if you want to keep it around.
+     * @param factorX - scaling factor on the X axis
+     * @param factorY - scaling factor on the Y axis
+     */
     scale(factorX: number, factorY: number): Transform | null;
+    /**
+     * Scales `next` by the given factors.
+     *
+     * This function consumes @next. Use [method@Gsk.Transform.ref] first
+     * if you want to keep it around.
+     * @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_3d(factorX: number, factorY: number, factorZ: number): Transform | null;
+    /**
+     * Applies a skew transform.
+     *
+     * This function consumes @next. Use [method@Gsk.Transform.ref] first
+     * if you want to keep it around.
+     * @param skewX - skew factor, in degrees, on the X axis
+     * @param skewY - skew factor, in degrees, on the Y axis
+     */
     skew(skewX: number, skewY: number): Transform | null;
+    /**
+     * Converts a transform to a 2D transformation matrix.
+     *
+     * `self` must be a 2D transformation. If you are not
+     * sure, use
+     *
+     * gsk_transform_get_category() >= GSK_TRANSFORM_CATEGORY_2D
+     *
+     * to check.
+     *
+     * The returned values are a subset of the full 4x4 matrix that
+     * is computed by [method@Gsk.Transform.to_matrix] and have the
+     * following layout:
+     *
+     * ```
+     * | xx yx |   |  a  b  0 |
+     * | xy yy | = |  c  d  0 |
+     * | dx dy |   | tx ty  1 |
+     * ```
+     *
+     * This function can be used to convert between a `GskTransform`
+     * and a matrix type from other 2D drawing libraries, in particular
+     * Cairo.
+     * @param outXx - return location for the xx member
+     * @param outYx - return location for the yx member
+     * @param outXy - return location for the xy member
+     * @param outYy - return location for the yy member
+     * @param outDx - return location for the x0 member
+     * @param outDy - return location for the y0 member
+     */
     to_2d(outXx: Ref<number>, outYx: Ref<number>, outXy: Ref<number>, outYy: Ref<number>, outDx: Ref<number>, outDy: Ref<number>): void;
+    /**
+     * Converts a transform to 2D transformation factors.
+     *
+     * To recreate an equivalent transform from the factors returned
+     * by this function, use
+     *
+     * gsk_transform_skew (
+     * gsk_transform_scale (
+     * gsk_transform_rotate (
+     * gsk_transform_translate (NULL, &GRAPHENE_POINT_T (dx, dy)),
+     * angle),
+     * scale_x, scale_y),
+     * skew_x, skew_y)
+     *
+     * `self` must be a 2D transformation. If you are not sure, use
+     *
+     * gsk_transform_get_category() >= GSK_TRANSFORM_CATEGORY_2D
+     *
+     * to check.
+     * @param outSkewX - return location for the skew factor
+     * @param outSkewY - return location for the skew factor
+     * @param outScaleX - return location for the scale
+     * @param outScaleY - return location for the scale
+     * @param outAngle - return location for the rotation angle
+     * @param outDx - return location for the translation
+     * @param outDy - return location for the translation
+     */
     to_2dComponents(outSkewX: Ref<number>, outSkewY: Ref<number>, outScaleX: Ref<number>, outScaleY: Ref<number>, outAngle: Ref<number>, outDx: Ref<number>, outDy: Ref<number>): void;
+    /**
+     * Converts a transform to 2D affine transformation factors.
+     *
+     * To recreate an equivalent transform from the factors returned
+     * by this function, use
+     *
+     * gsk_transform_scale (
+     * gsk_transform_translate (
+     * NULL,
+     * &GRAPHENE_POINT_T (dx, dy)),
+     * sx, sy)
+     *
+     * `self` must be a 2D affine transformation. If you are not
+     * sure, use
+     *
+     * gsk_transform_get_category() >= GSK_TRANSFORM_CATEGORY_2D_AFFINE
+     *
+     * to check.
+     * @param outScaleX - return location for the scale
+     * @param outScaleY - return location for the scale
+     * @param outDx - return location for the translation
+     * @param outDy - return location for the translation
+     */
     toAffine(outScaleX: Ref<number>, outScaleY: Ref<number>, outDx: Ref<number>, outDy: Ref<number>): void;
+    /**
+     * Computes the 4x4 matrix for the transform.
+     *
+     * The previous value of `out_matrix` will be ignored.
+     * @param outMatrix - return location for the matrix
+     */
     toMatrix(outMatrix: Ref<Graphene.Matrix>): void;
+    /**
+     * Converts the transform into a human-readable string.
+     *
+     * The resulting string can be parsed with [func@Gsk.Transform.parse].
+     *
+     * This is a wrapper around [method@Gsk.Transform.print].
+     */
     toString(): string;
+    /**
+     * Converts a transform to a translation operation.
+     *
+     * `self` must be a 2D transformation. If you are not
+     * sure, use
+     *
+     * gsk_transform_get_category() >= GSK_TRANSFORM_CATEGORY_2D_TRANSLATE
+     *
+     * to check.
+     * @param outDx - return location for the translation
+     * @param outDy - return location for the translation
+     */
     toTranslate(outDx: Ref<number>, outDy: Ref<number>): void;
+    /**
+     * Applies all the operations from `other` to @next.
+     *
+     * This function consumes @next. Use [method@Gsk.Transform.ref] first
+     * if you want to keep it around.
+     * @param other - transform to apply
+     */
     transform(other?: Transform | null): Transform | null;
+    /**
+     * Transforms a rectangle using the given transform.
+     *
+     * The result is the bounding box containing the coplanar quad.
+     * @param rect - the rectangle to transform
+     * @param outRect - return location for the bounds
+     */
     transformBounds(rect: Graphene.Rect, outRect: Ref<Graphene.Rect>): void;
+    /**
+     * Transforms a point using the given transform.
+     * @param point - the point to transform
+     * @param outPoint - return location for
+     */
     transformPoint(point: Graphene.Point, outPoint: Ref<Graphene.Point>): void;
+    /**
+     * Translates `next` in 2-dimensional space by @point.
+     *
+     * This function consumes @next. Use [method@Gsk.Transform.ref] first
+     * if you want to keep it around.
+     * @param point - the point to translate the transform by
+     */
     translate(point: Graphene.Point): Transform | null;
+    /**
+     * Translates `next` by @point.
+     *
+     * This function consumes @next. Use [method@Gsk.Transform.ref] first
+     * if you want to keep it around.
+     * @param point - the point to translate the transform by
+     */
     translate_3d(point: Graphene.Point3D): Transform | null;
+    /**
+     * Releases a reference on the given transform.
+     *
+     * If the reference was the last, the resources associated to the `self` are
+     * freed.
+     */
     unref(): void;
 }