@gtkx/ffi 0.1.45 → 0.1.46

package/dist/generated/gsk/functions.js

@@ -2,6 +2,11 @@ import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
 import { Path } from "./path.js";
 import { RenderNode } from "./render-node.js";
+/**
+ * Compares two component transfers for equality.
+ * @param self - a component transfer
+ * @param other - another component transfer
+ */
 export const componentTransferEqual = (self, other) => {
     return call("libgtk-4.so.1", "gsk_component_transfer_equal", [
         {
@@ -14,6 +19,33 @@ export const componentTransferEqual = (self, other) => {
         },
     ], { type: "boolean" });
 };
+/**
+ * Constructs a path from a serialized form.
+ *
+ * The string is expected to be in (a superset of)
+ * SVG path syntax,
+ * as e.g. produced by [method@Gsk.Path.to_string].
+ *
+ * A high-level summary of the syntax:
+ *
+ * - `M x y` Move to `(x, y)`
+ * - `L x y` Add a line from the current point to `(x, y)`
+ * - `Q x1 y1 x2 y2` Add a quadratic Bézier from the current point to `(x2, y2)`, with control point `(x1, y1)`
+ * - `C x1 y1 x2 y2 x3 y3` Add a cubic Bézier from the current point to `(x3, y3)`, with control points `(x1, y1)` and `(x2, y2)`
+ * - `Z` Close the contour by drawing a line back to the start point
+ * - `H x` Add a horizontal line from the current point to the given x value
+ * - `V y` Add a vertical line from the current point to the given y value
+ * - `T x2 y2` Add a quadratic Bézier, using the reflection of the previous segments' control point as control point
+ * - `S x2 y2 x3 y3` Add a cubic Bézier, using the reflection of the previous segments' second control point as first control point
+ * - `A rx ry r l s x y` Add an elliptical arc from the current point to `(x, y)` with radii rx and ry. See the SVG documentation for how the other parameters influence the arc.
+ * - `O x1 y1 x2 y2 w` Add a rational quadratic Bézier from the current point to `(x2, y2)` with control point `(x1, y1)` and weight `w`.
+ *
+ * All the commands have lowercase variants that interpret coordinates
+ * relative to the current point.
+ *
+ * The `O` command is an extension that is not supported in SVG.
+ * @param string - a string
+ */
 export const pathParse = (string) => {
     const ptr = call("libgtk-4.so.1", "gsk_path_parse", [
         {
@@ -30,6 +62,9 @@ export const pathParse = (string) => {
         return null;
     return getObject(ptr, Path);
 };
+/**
+ * Registers an error quark for [class@Gsk.RenderNode] errors.
+ */
 export const serializationErrorQuark = () => {
     return call("libgtk-4.so.1", "gsk_serialization_error_quark", [], {
         type: "int",
@@ -37,6 +72,11 @@ export const serializationErrorQuark = () => {
         unsigned: true,
     });
 };
+/**
+ * Checks if two strokes are identical.
+ * @param stroke1 - the first stroke
+ * @param stroke2 - the second stroke
+ */
 export const strokeEqual = (stroke1, stroke2) => {
     return call("libgtk-4.so.1", "gsk_stroke_equal", [
         {
@@ -51,6 +91,17 @@ export const strokeEqual = (stroke1, stroke2) => {
         },
     ], { type: "boolean" });
 };
+/**
+ * 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
+ */
 export const transformParse = (string, outTransform) => {
     return call("libgtk-4.so.1", "gsk_transform_parse", [
         {
@@ -70,6 +121,11 @@ export const transformParse = (string, outTransform) => {
         },
     ], { type: "boolean" });
 };
+/**
+ * Retrieves the render node stored inside a `GValue`,
+ * and acquires a reference to it.
+ * @param value - a [struct@GObject.Value] initialized with type `GSK_TYPE_RENDER_NODE`
+ */
 export const valueDupRenderNode = (value) => {
     const ptr = call("libgtk-4.so.1", "gsk_value_dup_render_node", [
         {
@@ -86,6 +142,10 @@ export const valueDupRenderNode = (value) => {
         return null;
     return getObject(ptr, RenderNode);
 };
+/**
+ * Retrieves the render node stored inside a `GValue`.
+ * @param value - a `GValue` initialized with type `GSK_TYPE_RENDER_NODE`
+ */
 export const valueGetRenderNode = (value) => {
     const ptr = call("libgtk-4.so.1", "gsk_value_get_render_node", [
         {
@@ -102,6 +162,14 @@ export const valueGetRenderNode = (value) => {
         return null;
     return getObject(ptr, RenderNode);
 };
+/**
+ * Stores the given render node inside a `GValue`.
+ *
+ * The [struct@GObject.Value] will acquire a reference
+ * to the render node.
+ * @param value - a [struct@GObject.Value] initialized with type `GSK_TYPE_RENDER_NODE`
+ * @param node - a render node
+ */
 export const valueSetRenderNode = (value, node) => {
     call("libgtk-4.so.1", "gsk_value_set_render_node", [
         {
@@ -119,6 +187,14 @@ export const valueSetRenderNode = (value, node) => {
         },
     ], { type: "undefined" });
 };
+/**
+ * Stores the given render node inside a `GValue`.
+ *
+ * This function transfers the ownership of the
+ * render node to the `GValue`.
+ * @param value - a [struct@GObject.Value] initialized with type `GSK_TYPE_RENDER_NODE`
+ * @param node - a render node
+ */
 export const valueTakeRenderNode = (value, node) => {
     call("libgtk-4.so.1", "gsk_value_take_render_node", [
         {

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

@@ -1,5 +1,13 @@
 import { Renderer } from "./renderer.js";
+/**
+ * Renders a GSK rendernode tree with OpenGL.
+ *
+ * See [class@Gsk.Renderer].
+ */
 export declare class GLRenderer extends Renderer {
+    /**
+     * Creates an instance of the GL renderer.
+     */
     constructor(...args: unknown[]);
     protected createPtr(_args: unknown[]): unknown;
 }

package/dist/generated/gsk/glrenderer.js

@@ -1,6 +1,14 @@
 import { call } from "@gtkx/native";
 import { Renderer } from "./renderer.js";
+/**
+ * Renders a GSK rendernode tree with OpenGL.
+ *
+ * See [class@Gsk.Renderer].
+ */
 export class GLRenderer extends Renderer {
+    /**
+     * Creates an instance of the GL renderer.
+     */
     constructor(...args) {
         super(...args);
     }

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

@@ -2,12 +2,50 @@ import { GLShader } from "./glshader.js";
 import * as GLib from "../glib/index.js";
 import * as Graphene from "../graphene/index.js";
 import { RenderNode } from "./render-node.js";
+/** A render node using a GL shader when drawing its children nodes. */
 export declare class GLShaderNode extends RenderNode {
+    /**
+     * Creates a `GskRenderNode` that will render the given `shader` into the
+     * area given by @bounds.
+     *
+     * The `args` is a block of data to use for uniform input, as per types and
+     * offsets defined by the @shader. Normally this is generated by
+     * [method@Gsk.GLShader.format_args] or [struct@Gsk.ShaderArgsBuilder].
+     *
+     * See [class@Gsk.GLShader] for details about how the shader should be written.
+     *
+     * All the children will be rendered into textures (if they aren't already
+     * `GskTextureNodes`, which will be used directly). These textures will be
+     * sent as input to the shader.
+     *
+     * If the renderer doesn't support GL shaders, or if there is any problem
+     * when compiling the shader, then the node will draw pink. You should use
+     * [method@Gsk.GLShader.compile] to ensure the `shader` will work for the
+     * renderer before using it.
+     * @param shader - the `GskGLShader`
+     * @param bounds - the rectangle to render the shader into
+     * @param args - Arguments for the uniforms
+     * @param children - array of child nodes,
+     * @param nChildren - Length of `children` (currently the GL backend supports
+     */
     constructor(shader: GLShader, bounds: Graphene.Rect, args: GLib.Bytes, nChildren: number, children?: RenderNode[] | null);
     constructor(...args: unknown[]);
     protected createPtr(ctorArgs: unknown[]): unknown;
+    /**
+     * Gets args for the node.
+     */
     getArgs(): GLib.Bytes;
+    /**
+     * Gets one of the children.
+     * @param idx - the position of the child to get
+     */
     getChild(idx: number): RenderNode;
+    /**
+     * Returns the number of children
+     */
     getNChildren(): number;
+    /**
+     * Gets shader code for the node.
+     */
     getShader(): GLShader;
 }

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

@@ -3,6 +3,7 @@ import { getObject } from "@gtkx/ffi";
 import { GLShader } from "./glshader.js";
 import * as GLib from "../glib/index.js";
 import { RenderNode } from "./render-node.js";
+/** A render node using a GL shader when drawing its children nodes. */
 export class GLShaderNode extends RenderNode {
     constructor(...args) {
         super(...args);
@@ -43,6 +44,9 @@ export class GLShaderNode extends RenderNode {
             },
         ], { type: "gobject", borrowed: false });
     }
+    /**
+     * Gets args for the node.
+     */
     getArgs() {
         const ptr = call("libgtk-4.so.1", "gsk_gl_shader_node_get_args", [
             {
@@ -57,6 +61,10 @@ export class GLShaderNode extends RenderNode {
         });
         return getObject(ptr, GLib.Bytes);
     }
+    /**
+     * Gets one of the children.
+     * @param idx - the position of the child to get
+     */
     getChild(idx) {
         const ptr = call("libgtk-4.so.1", "gsk_gl_shader_node_get_child", [
             {
@@ -70,6 +78,9 @@ export class GLShaderNode extends RenderNode {
         ], { type: "gobject", borrowed: true });
         return getObject(ptr, RenderNode);
     }
+    /**
+     * Returns the number of children
+     */
     getNChildren() {
         return call("libgtk-4.so.1", "gsk_gl_shader_node_get_n_children", [
             {
@@ -78,6 +89,9 @@ export class GLShaderNode extends RenderNode {
             },
         ], { type: "int", size: 32, unsigned: true });
     }
+    /**
+     * Gets shader code for the node.
+     */
     getShader() {
         const ptr = call("libgtk-4.so.1", "gsk_gl_shader_node_get_shader", [
             {

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

@@ -3,27 +3,253 @@ import { Renderer } from "./renderer.js";
 import * as GLib from "../glib/index.js";
 import * as GObject from "../gobject/index.js";
 import * as Graphene from "../graphene/index.js";
+/**
+ * Implements a fragment shader using GLSL.
+ *
+ * A fragment shader gets the coordinates being rendered as input and
+ * produces the pixel values for that particular pixel. Additionally,
+ * the shader can declare a set of other input arguments, called
+ * uniforms (as they are uniform over all the calls to your shader in
+ * each instance of use). A shader can also receive up to 4
+ * textures that it can use as input when producing the pixel data.
+ *
+ * `GskGLShader` is usually used with gtk_snapshot_push_gl_shader()
+ * to produce a [class@Gsk.GLShaderNode] in the rendering hierarchy,
+ * and then its input textures are constructed by rendering the child
+ * nodes to textures before rendering the shader node itself. (You can
+ * pass texture nodes as children if you want to directly use a texture
+ * as input).
+ *
+ * The actual shader code is GLSL code that gets combined with
+ * some other code into the fragment shader. Since the exact
+ * capabilities of the GPU driver differs between different OpenGL
+ * drivers and hardware, GTK adds some defines that you can use
+ * to ensure your GLSL code runs on as many drivers as it can.
+ *
+ * If the OpenGL driver is GLES, then the shader language version
+ * is set to 100, and GSK_GLES will be defined in the shader.
+ *
+ * Otherwise, if the OpenGL driver does not support the 3.2 core profile,
+ * then the shader will run with language version 110 for GL2 and 130 for GL3,
+ * and GSK_LEGACY will be defined in the shader.
+ *
+ * If the OpenGL driver supports the 3.2 code profile, it will be used,
+ * the shader language version is set to 150, and GSK_GL3 will be defined
+ * in the shader.
+ *
+ * The main function the shader must implement is:
+ *
+ * ```glsl
+ * void mainImage(out vec4 fragColor,
+ * in vec2 fragCoord,
+ * in vec2 resolution,
+ * in vec2 uv)
+ * ```
+ *
+ * Where the input `fragCoord` is the coordinate of the pixel we're
+ * currently rendering, relative to the boundary rectangle that was
+ * specified in the `GskGLShaderNode`, and `resolution` is the width and
+ * height of that rectangle. This is in the typical GTK coordinate
+ * system with the origin in the top left. `uv` contains the u and v
+ * coordinates that can be used to index a texture at the
+ * corresponding point. These coordinates are in the [0..1]x[0..1]
+ * region, with 0, 0 being in the lower left corder (which is typical
+ * for OpenGL).
+ *
+ * The output `fragColor` should be a RGBA color (with
+ * premultiplied alpha) that will be used as the output for the
+ * specified pixel location. Note that this output will be
+ * automatically clipped to the clip region of the glshader node.
+ *
+ * In addition to the function arguments the shader can define
+ * up to 4 uniforms for textures which must be called u_textureN
+ * (i.e. u_texture1 to u_texture4) as well as any custom uniforms
+ * you want of types int, uint, bool, float, vec2, vec3 or vec4.
+ *
+ * All textures sources contain premultiplied alpha colors, but if some
+ * there are outer sources of colors there is a gsk_premultiply() helper
+ * to compute premultiplication when needed.
+ *
+ * Note that GTK parses the uniform declarations, so each uniform has to
+ * be on a line by itself with no other code, like so:
+ *
+ * ```glsl
+ * uniform float u_time;
+ * uniform vec3 u_color;
+ * uniform sampler2D u_texture1;
+ * uniform sampler2D u_texture2;
+ * ```
+ *
+ * GTK uses the "gsk" namespace in the symbols it uses in the
+ * shader, so your code should not use any symbols with the prefix gsk
+ * or GSK. There are some helper functions declared that you can use:
+ *
+ * ```glsl
+ * vec4 GskTexture(sampler2D sampler, vec2 texCoords);
+ * ```
+ *
+ * This samples a texture (e.g. u_texture1) at the specified
+ * coordinates, and contains some helper ifdefs to ensure that
+ * it works on all OpenGL versions.
+ *
+ * You can compile the shader yourself using [method@Gsk.GLShader.compile],
+ * otherwise the GSK renderer will do it when it handling the glshader
+ * node. If errors occurs, the returned `error` will include the glsl
+ * sources, so you can see what GSK was passing to the compiler. You
+ * can also set GSK_DEBUG=shaders in the environment to see the sources
+ * and other relevant information about all shaders that GSK is handling.
+ *
+ * # An example shader
+ *
+ * ```glsl
+ * uniform float position;
+ * uniform sampler2D u_texture1;
+ * uniform sampler2D u_texture2;
+ *
+ * void mainImage(out vec4 fragColor,
+ * in vec2 fragCoord,
+ * in vec2 resolution,
+ * in vec2 uv) {
+ * vec4 source1 = GskTexture(u_texture1, uv);
+ * vec4 source2 = GskTexture(u_texture2, uv);
+ *
+ * fragColor = position * source1 + (1.0 - position) * source2;
+ * }
+ * ```
+ */
 export declare class GLShader extends GObject.GObject {
+    /**
+     * Creates a `GskGLShader` that will render pixels using the specified code.
+     * @param sourcecode - GLSL sourcecode for the shader, as a `GBytes`
+     */
     constructor(sourcecode: GLib.Bytes);
     constructor(...args: unknown[]);
+    /**
+     * Creates a `GskGLShader` that will render pixels using the specified code.
+     * @param resourcePath - path to a resource that contains the GLSL sourcecode for
+     */
     static shaderNewFromResource(resourcePath: string): GLShader;
     protected createPtr(args: unknown[]): unknown;
+    /**
+     * Tries to compile the `shader` for the given @renderer.
+     *
+     * If there is a problem, this function returns %FALSE and reports
+     * an error. You should use this function before relying on the shader
+     * for rendering and use a fallback with a simpler shader or without
+     * shaders if it fails.
+     *
+     * Note that this will modify the rendering state (for example
+     * change the current GL context) and requires the renderer to be
+     * set up. This means that the widget has to be realized. Commonly you
+     * want to call this from the realize signal of a widget, or during
+     * widget snapshot.
+     * @param renderer - a `GskRenderer`
+     */
     compile(renderer: Renderer): boolean;
+    /**
+     * Looks for a uniform by the name @name, and returns the index
+     * of the uniform, or -1 if it was not found.
+     * @param name - uniform name
+     */
     findUniformByName(name: string): number;
+    /**
+     * Gets the value of the uniform `idx` in the `args` block.
+     *
+     * The uniform must be of bool type.
+     * @param args - uniform arguments
+     * @param idx - index of the uniform
+     */
     getArgBool(args: GLib.Bytes, idx: number): boolean;
+    /**
+     * Gets the value of the uniform `idx` in the `args` block.
+     *
+     * The uniform must be of float type.
+     * @param args - uniform arguments
+     * @param idx - index of the uniform
+     */
     getArgFloat(args: GLib.Bytes, idx: number): number;
+    /**
+     * Gets the value of the uniform `idx` in the `args` block.
+     *
+     * The uniform must be of int type.
+     * @param args - uniform arguments
+     * @param idx - index of the uniform
+     */
     getArgInt(args: GLib.Bytes, idx: number): number;
+    /**
+     * Gets the value of the uniform `idx` in the `args` block.
+     *
+     * The uniform must be of uint type.
+     * @param args - uniform arguments
+     * @param idx - index of the uniform
+     */
     getArgUint(args: GLib.Bytes, idx: number): number;
+    /**
+     * Gets the value of the uniform `idx` in the `args` block.
+     *
+     * The uniform must be of vec2 type.
+     * @param args - uniform arguments
+     * @param idx - index of the uniform
+     * @param outValue - location to store the uniform value in
+     */
     getArgVec2(args: GLib.Bytes, idx: number, outValue: Graphene.Vec2): void;
+    /**
+     * Gets the value of the uniform `idx` in the `args` block.
+     *
+     * The uniform must be of vec3 type.
+     * @param args - uniform arguments
+     * @param idx - index of the uniform
+     * @param outValue - location to store the uniform value in
+     */
     getArgVec3(args: GLib.Bytes, idx: number, outValue: Graphene.Vec3): void;
+    /**
+     * Gets the value of the uniform `idx` in the `args` block.
+     *
+     * The uniform must be of vec4 type.
+     * @param args - uniform arguments
+     * @param idx - index of the uniform
+     * @param outValue - location to store set the uniform value in
+     */
     getArgVec4(args: GLib.Bytes, idx: number, outValue: Graphene.Vec4): void;
+    /**
+     * Get the size of the data block used to specify arguments for this shader.
+     */
     getArgsSize(): number;
+    /**
+     * Returns the number of textures that the shader requires.
+     *
+     * This can be used to check that the a passed shader works
+     * in your usecase. It is determined by looking at the highest
+     * u_textureN value that the shader defines.
+     */
     getNTextures(): number;
+    /**
+     * Get the number of declared uniforms for this shader.
+     */
     getNUniforms(): number;
+    /**
+     * Gets the resource path for the GLSL sourcecode being used
+     * to render this shader.
+     */
     getResource(): string | null;
+    /**
+     * Gets the GLSL sourcecode being used to render this shader.
+     */
     getSource(): GLib.Bytes;
+    /**
+     * Get the name of the declared uniform for this shader at index @idx.
+     * @param idx - index of the uniform
+     */
     getUniformName(idx: number): string;
+    /**
+     * Get the offset into the data block where data for this uniforms is stored.
+     * @param idx - index of the uniform
+     */
     getUniformOffset(idx: number): number;
+    /**
+     * Get the type of the declared uniform for this shader at index @idx.
+     * @param idx - index of the uniform
+     */
     getUniformType(idx: number): GLUniformType;
     connect(signal: "notify", handler: (self: GLShader, pspec: GObject.ParamSpec) => void, after?: boolean): number;
     connect(signal: string, handler: (...args: any[]) => any, after?: boolean): number;