@gtkx/ffi 0.1.45 → 0.1.46

package/dist/generated/gtk/glarea.js

@@ -3,6 +3,121 @@ import { getObject } from "@gtkx/ffi";
 import * as GLib from "../glib/index.js";
 import * as Gdk from "../gdk/index.js";
 import { Widget } from "./widget.js";
+/**
+ * Allows drawing with OpenGL.
+ *
+ *
+ *
+ * `GtkGLArea` sets up its own [class@Gdk.GLContext], and creates a custom
+ * GL framebuffer that the widget will do GL rendering onto. It also ensures
+ * that this framebuffer is the default GL rendering target when rendering.
+ * The completed rendering is integrated into the larger GTK scene graph as
+ * a texture.
+ *
+ * In order to draw, you have to connect to the [signal@Gtk.GLArea::render]
+ * signal, or subclass `GtkGLArea` and override the GtkGLAreaClass.render
+ * virtual function.
+ *
+ * The `GtkGLArea` widget ensures that the `GdkGLContext` is associated with
+ * the widget's drawing area, and it is kept updated when the size and
+ * position of the drawing area changes.
+ *
+ * ## Drawing with GtkGLArea
+ *
+ * The simplest way to draw using OpenGL commands in a `GtkGLArea` is to
+ * create a widget instance and connect to the [signal@Gtk.GLArea::render] signal:
+ *
+ * The `render()` function will be called when the `GtkGLArea` is ready
+ * for you to draw its content:
+ *
+ * The initial contents of the framebuffer are transparent.
+ *
+ * ```c
+ * static gboolean
+ * render (GtkGLArea *area, GdkGLContext *context)
+ * {
+ * // inside this function it's safe to use GL; the given
+ * // GdkGLContext has been made current to the drawable
+ * // surface used by the `GtkGLArea` and the viewport has
+ * // already been set to be the size of the allocation
+ *
+ * // we can start by clearing the buffer
+ * glClearColor (0, 0, 0, 0);
+ * glClear (GL_COLOR_BUFFER_BIT);
+ *
+ * // record the active framebuffer ID, so we can return to it
+ * // with `glBindFramebuffer (GL_FRAMEBUFFER, screen_fb)` should
+ * // we, for instance, intend on utilizing the results of an
+ * // intermediate render texture pass
+ * GLuint screen_fb = 0;
+ * glGetIntegerv (GL_FRAMEBUFFER_BINDING, &screen_fb);
+ *
+ * // draw your object
+ * // draw_an_object ();
+ *
+ * // we completed our drawing; the draw commands will be
+ * // flushed at the end of the signal emission chain, and
+ * // the buffers will be drawn on the window
+ * return TRUE;
+ * }
+ *
+ * void setup_glarea (void)
+ * {
+ * // create a GtkGLArea instance
+ * GtkWidget *gl_area = gtk_gl_area_new ();
+ *
+ * // connect to the "render" signal
+ * g_signal_connect (gl_area, "render", G_CALLBACK (render), NULL);
+ * }
+ * ```
+ *
+ * If you need to initialize OpenGL state, e.g. buffer objects or
+ * shaders, you should use the [signal@Gtk.Widget::realize] signal;
+ * you can use the [signal@Gtk.Widget::unrealize] signal to clean up.
+ * Since the `GdkGLContext` creation and initialization may fail, you
+ * will need to check for errors, using [method@Gtk.GLArea.get_error].
+ *
+ * An example of how to safely initialize the GL state is:
+ *
+ * ```c
+ * static void
+ * on_realize (GtkGLArea *area)
+ * {
+ * // We need to make the context current if we want to
+ * // call GL API
+ * gtk_gl_area_make_current (area);
+ *
+ * // If there were errors during the initialization or
+ * // when trying to make the context current, this
+ * // function will return a GError for you to catch
+ * if (gtk_gl_area_get_error (area) != NULL)
+ * return;
+ *
+ * // You can also use gtk_gl_area_set_error() in order
+ * // to show eventual initialization errors on the
+ * // GtkGLArea widget itself
+ * GError *internal_error = NULL;
+ * init_buffer_objects (&error);
+ * if (error != NULL)
+ * {
+ * gtk_gl_area_set_error (area, error);
+ * g_error_free (error);
+ * return;
+ * }
+ *
+ * init_shaders (&error);
+ * if (error != NULL)
+ * {
+ * gtk_gl_area_set_error (area, error);
+ * g_error_free (error);
+ * return;
+ * }
+ * }
+ * ```
+ *
+ * If you need to change the options for creating the `GdkGLContext`
+ * you should use the [signal@Gtk.GLArea::create-context] signal.
+ */
 const SIGNAL_META = {
     "create-context": {
         params: [],
@@ -26,6 +141,9 @@ const SIGNAL_META = {
     },
 };
 export class GLArea extends Widget {
+    /**
+     * Creates a new `GtkGLArea` widget.
+     */
     constructor(...args) {
         super(...args);
     }
@@ -35,6 +153,16 @@ export class GLArea extends Widget {
             borrowed: true,
         });
     }
+    /**
+     * Binds buffers to the framebuffer.
+     *
+     * Ensures that the `area` framebuffer object is made the current draw
+     * and read target, and that all the required buffers for the `area` are created and bound to the framebuffer.
+     *
+     * This function is automatically called before emitting the
+     * [signal@Gtk.GLArea::render] signal, and doesn't normally need to be
+     * called by application code.
+     */
     attachBuffers() {
         call("libgtk-4.so.1", "gtk_gl_area_attach_buffers", [
             {
@@ -43,6 +171,11 @@ export class GLArea extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Gets the allowed APIs.
+     *
+     * See [method@Gtk.GLArea.set_allowed_apis].
+     */
     getAllowedApis() {
         return call("libgtk-4.so.1", "gtk_gl_area_get_allowed_apis", [
             {
@@ -51,6 +184,11 @@ export class GLArea extends Widget {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Gets the API that is currently in use.
+     *
+     * If the GL area has not been realized yet, 0 is returned.
+     */
     getApi() {
         return call("libgtk-4.so.1", "gtk_gl_area_get_api", [
             {
@@ -59,6 +197,9 @@ export class GLArea extends Widget {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Returns whether the area is in auto render mode or not.
+     */
     getAutoRender() {
         return call("libgtk-4.so.1", "gtk_gl_area_get_auto_render", [
             {
@@ -67,6 +208,9 @@ export class GLArea extends Widget {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Retrieves the `GdkGLContext` used by @area.
+     */
     getContext() {
         const ptr = call("libgtk-4.so.1", "gtk_gl_area_get_context", [
             {
@@ -78,6 +222,9 @@ export class GLArea extends Widget {
             return null;
         return getObject(ptr, Gdk.GLContext);
     }
+    /**
+     * Gets the current error set on the @area.
+     */
     getError() {
         const ptr = call("libgtk-4.so.1", "gtk_gl_area_get_error", [
             {
@@ -94,6 +241,9 @@ export class GLArea extends Widget {
             return null;
         return getObject(ptr, GLib.GError);
     }
+    /**
+     * Returns whether the area has a depth buffer.
+     */
     getHasDepthBuffer() {
         return call("libgtk-4.so.1", "gtk_gl_area_get_has_depth_buffer", [
             {
@@ -102,6 +252,9 @@ export class GLArea extends Widget {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Returns whether the area has a stencil buffer.
+     */
     getHasStencilBuffer() {
         return call("libgtk-4.so.1", "gtk_gl_area_get_has_stencil_buffer", [
             {
@@ -110,6 +263,13 @@ export class GLArea extends Widget {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Retrieves the required version of OpenGL.
+     *
+     * See [method@Gtk.GLArea.set_required_version].
+     * @param major - return location for the required major version
+     * @param minor - return location for the required minor version
+     */
     getRequiredVersion(major, minor) {
         call("libgtk-4.so.1", "gtk_gl_area_get_required_version", [
             {
@@ -132,6 +292,11 @@ export class GLArea extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Returns whether the `GtkGLArea` should use OpenGL ES.
+     *
+     * See [method@Gtk.GLArea.set_use_es].
+     */
     getUseEs() {
         return call("libgtk-4.so.1", "gtk_gl_area_get_use_es", [
             {
@@ -140,6 +305,14 @@ export class GLArea extends Widget {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Ensures that the `GdkGLContext` used by `area` is associated with
+     * the `GtkGLArea`.
+     *
+     * This function is automatically called before emitting the
+     * [signal@Gtk.GLArea::render] signal, and doesn't normally need
+     * to be called by application code.
+     */
     makeCurrent() {
         call("libgtk-4.so.1", "gtk_gl_area_make_current", [
             {
@@ -148,6 +321,17 @@ export class GLArea extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Marks the currently rendered data (if any) as invalid, and queues
+     * a redraw of the widget.
+     *
+     * This ensures that the [signal@Gtk.GLArea::render] signal
+     * is emitted during the draw.
+     *
+     * This is only needed when [method@Gtk.GLArea.set_auto_render] has
+     * been called with a %FALSE value. The default behaviour is to
+     * emit [signal@Gtk.GLArea::render] on each draw.
+     */
     queueRender() {
         call("libgtk-4.so.1", "gtk_gl_area_queue_render", [
             {
@@ -156,6 +340,15 @@ export class GLArea extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the allowed APIs to create a context with.
+     *
+     * You should check [property@Gtk.GLArea:api] before drawing
+     * with either API.
+     *
+     * By default, all APIs are allowed.
+     * @param apis - the allowed APIs
+     */
     setAllowedApis(apis) {
         call("libgtk-4.so.1", "gtk_gl_area_set_allowed_apis", [
             {
@@ -168,6 +361,20 @@ export class GLArea extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets whether the `GtkGLArea` is in auto render mode.
+     *
+     * If `auto_render` is %TRUE the [signal@Gtk.GLArea::render] signal will
+     * be emitted every time the widget draws. This is the default and is
+     * useful if drawing the widget is faster.
+     *
+     * If `auto_render` is %FALSE the data from previous rendering is kept
+     * around and will be used for drawing the widget the next time,
+     * unless the window is resized. In order to force a rendering
+     * [method@Gtk.GLArea.queue_render] must be called. This mode is
+     * useful when the scene changes seldom, but takes a long time to redraw.
+     * @param autoRender - a boolean
+     */
     setAutoRender(autoRender) {
         call("libgtk-4.so.1", "gtk_gl_area_set_auto_render", [
             {
@@ -180,6 +387,14 @@ export class GLArea extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets an error on the area which will be shown instead of the
+     * GL rendering.
+     *
+     * This is useful in the [signal@Gtk.GLArea::create-context]
+     * signal if GL context creation fails.
+     * @param error - a new `GError`, or %NULL to unset the error
+     */
     setError(error) {
         call("libgtk-4.so.1", "gtk_gl_area_set_error", [
             {
@@ -198,6 +413,14 @@ export class GLArea extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets whether the `GtkGLArea` should use a depth buffer.
+     *
+     * If `has_depth_buffer` is %TRUE the widget will allocate and
+     * enable a depth buffer for the target framebuffer. Otherwise
+     * there will be none.
+     * @param hasDepthBuffer - %TRUE to add a depth buffer
+     */
     setHasDepthBuffer(hasDepthBuffer) {
         call("libgtk-4.so.1", "gtk_gl_area_set_has_depth_buffer", [
             {
@@ -210,6 +433,14 @@ export class GLArea extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets whether the `GtkGLArea` should use a stencil buffer.
+     *
+     * If `has_stencil_buffer` is %TRUE the widget will allocate and
+     * enable a stencil buffer for the target framebuffer. Otherwise
+     * there will be none.
+     * @param hasStencilBuffer - %TRUE to add a stencil buffer
+     */
     setHasStencilBuffer(hasStencilBuffer) {
         call("libgtk-4.so.1", "gtk_gl_area_set_has_stencil_buffer", [
             {
@@ -222,6 +453,14 @@ export class GLArea extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the required version of OpenGL to be used when creating
+     * the context for the widget.
+     *
+     * This function must be called before the area has been realized.
+     * @param major - the major version
+     * @param minor - the minor version
+     */
     setRequiredVersion(major, minor) {
         call("libgtk-4.so.1", "gtk_gl_area_set_required_version", [
             {
@@ -238,6 +477,13 @@ export class GLArea extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets whether the `area` should create an OpenGL or an OpenGL ES context.
+     *
+     * You should check the capabilities of the `GdkGLContext` before drawing
+     * with either API.
+     * @param useEs - whether to use OpenGL or OpenGL ES
+     */
     setUseEs(useEs) {
         call("libgtk-4.so.1", "gtk_gl_area_set_use_es", [
             {

package/dist/generated/gtk/graphics-offload.d.ts

@@ -1,15 +1,93 @@
 import { GraphicsOffloadEnabled } from "./enums.js";
 import * as GObject from "../gobject/index.js";
 import { Widget } from "./widget.js";
+/**
+ * Bypasses gsk rendering by passing the content of its child directly to the compositor.
+ *
+ * Graphics offload is an optimization to reduce overhead and battery use that is
+ * most useful for video content. It only works on some platforms and in certain
+ * situations. GTK will automatically fall back to normal rendering if it doesn't.
+ *
+ * Graphics offload is most efficient if there are no controls drawn on top of the
+ * video content.
+ *
+ * You should consider using graphics offload for your main widget if it shows
+ * frequently changing content (such as a video, or a VM display) and you provide
+ * the content in the form of dmabuf textures (see [class@Gdk.DmabufTextureBuilder]),
+ * in particular if it may be fullscreen.
+ *
+ * Numerous factors can prohibit graphics offload:
+ *
+ * - Unsupported platforms. Currently, graphics offload only works on Linux with Wayland.
+ *
+ * - Clipping, such as rounded corners that cause the video content to not be rectangular
+ *
+ * - Unsupported dmabuf formats (see [method@Gdk.Display.get_dmabuf_formats])
+ *
+ * - Translucent video content (content with an alpha channel, even if it isn't used)
+ *
+ * - Transforms that are more complex than translations and scales
+ *
+ * - Filters such as opacity, grayscale or similar
+ *
+ * To investigate problems related graphics offload, GTK offers debug flags to print
+ * out information about graphics offload and dmabuf use:
+ *
+ * GDK_DEBUG=offload
+ * GDK_DEBUG=dmabuf
+ *
+ * The GTK inspector provides a visual debugging tool for graphics offload.
+ */
 export declare class GraphicsOffload extends Widget {
+    /**
+     * Creates a new GtkGraphicsOffload widget.
+     * @param child - the child widget
+     */
     constructor(child?: Widget | null);
     constructor(...args: unknown[]);
     protected createPtr(args: unknown[]): unknown;
+    /**
+     * Returns whether the widget draws a black background.
+     *
+     * See [method@Gtk.GraphicsOffload.set_black_background].
+     */
     getBlackBackground(): boolean;
+    /**
+     * Gets the child of @self.
+     */
     getChild(): Widget | null;
+    /**
+     * Returns whether offload is enabled for @self.
+     */
     getEnabled(): GraphicsOffloadEnabled;
+    /**
+     * Sets whether this GtkGraphicsOffload widget will draw a black
+     * background.
+     *
+     * A main use case for this is **_letterboxing_** where black bars are
+     * visible next to the content if the aspect ratio of the content does
+     * not match the dimensions of the monitor.
+     *
+     * Using this property for letterboxing instead of CSS allows compositors
+     * to show content with maximum efficiency, using direct scanout to avoid
+     * extra copies in the compositor.
+     *
+     * On Wayland, this is implemented using the
+     * [single-pixel buffer](https://wayland.app/protocols/single-pixel-buffer-v1)
+     * protocol.
+     * @param value - whether to draw a black background behind the content
+     */
     setBlackBackground(value: boolean): void;
+    /**
+     * Sets the child of @self.
+     * @param child - the child widget
+     */
     setChild(child?: Widget | null): void;
+    /**
+     * Sets whether this GtkGraphicsOffload widget will attempt
+     * to offload the content of its child widget.
+     * @param enabled - whether to enable offload
+     */
     setEnabled(enabled: GraphicsOffloadEnabled): void;
     connect(signal: "notify", handler: (self: GraphicsOffload, pspec: GObject.ParamSpec) => void, after?: boolean): number;
     connect(signal: string, handler: (...args: any[]) => any, after?: boolean): number;

package/dist/generated/gtk/graphics-offload.js

@@ -1,6 +1,43 @@
 import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
 import { Widget } from "./widget.js";
+/**
+ * Bypasses gsk rendering by passing the content of its child directly to the compositor.
+ *
+ * Graphics offload is an optimization to reduce overhead and battery use that is
+ * most useful for video content. It only works on some platforms and in certain
+ * situations. GTK will automatically fall back to normal rendering if it doesn't.
+ *
+ * Graphics offload is most efficient if there are no controls drawn on top of the
+ * video content.
+ *
+ * You should consider using graphics offload for your main widget if it shows
+ * frequently changing content (such as a video, or a VM display) and you provide
+ * the content in the form of dmabuf textures (see [class@Gdk.DmabufTextureBuilder]),
+ * in particular if it may be fullscreen.
+ *
+ * Numerous factors can prohibit graphics offload:
+ *
+ * - Unsupported platforms. Currently, graphics offload only works on Linux with Wayland.
+ *
+ * - Clipping, such as rounded corners that cause the video content to not be rectangular
+ *
+ * - Unsupported dmabuf formats (see [method@Gdk.Display.get_dmabuf_formats])
+ *
+ * - Translucent video content (content with an alpha channel, even if it isn't used)
+ *
+ * - Transforms that are more complex than translations and scales
+ *
+ * - Filters such as opacity, grayscale or similar
+ *
+ * To investigate problems related graphics offload, GTK offers debug flags to print
+ * out information about graphics offload and dmabuf use:
+ *
+ * GDK_DEBUG=offload
+ * GDK_DEBUG=dmabuf
+ *
+ * The GTK inspector provides a visual debugging tool for graphics offload.
+ */
 export class GraphicsOffload extends Widget {
     constructor(...args) {
         super(...args);
@@ -15,6 +52,11 @@ export class GraphicsOffload extends Widget {
             },
         ], { type: "gobject", borrowed: true });
     }
+    /**
+     * Returns whether the widget draws a black background.
+     *
+     * See [method@Gtk.GraphicsOffload.set_black_background].
+     */
     getBlackBackground() {
         return call("libgtk-4.so.1", "gtk_graphics_offload_get_black_background", [
             {
@@ -23,6 +65,9 @@ export class GraphicsOffload extends Widget {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Gets the child of @self.
+     */
     getChild() {
         const ptr = call("libgtk-4.so.1", "gtk_graphics_offload_get_child", [
             {
@@ -34,6 +79,9 @@ export class GraphicsOffload extends Widget {
             return null;
         return getObject(ptr, Widget);
     }
+    /**
+     * Returns whether offload is enabled for @self.
+     */
     getEnabled() {
         return call("libgtk-4.so.1", "gtk_graphics_offload_get_enabled", [
             {
@@ -42,6 +90,23 @@ export class GraphicsOffload extends Widget {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Sets whether this GtkGraphicsOffload widget will draw a black
+     * background.
+     *
+     * A main use case for this is **_letterboxing_** where black bars are
+     * visible next to the content if the aspect ratio of the content does
+     * not match the dimensions of the monitor.
+     *
+     * Using this property for letterboxing instead of CSS allows compositors
+     * to show content with maximum efficiency, using direct scanout to avoid
+     * extra copies in the compositor.
+     *
+     * On Wayland, this is implemented using the
+     * [single-pixel buffer](https://wayland.app/protocols/single-pixel-buffer-v1)
+     * protocol.
+     * @param value - whether to draw a black background behind the content
+     */
     setBlackBackground(value) {
         call("libgtk-4.so.1", "gtk_graphics_offload_set_black_background", [
             {
@@ -54,6 +119,10 @@ export class GraphicsOffload extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the child of @self.
+     * @param child - the child widget
+     */
     setChild(child) {
         call("libgtk-4.so.1", "gtk_graphics_offload_set_child", [
             {
@@ -67,6 +136,11 @@ export class GraphicsOffload extends Widget {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets whether this GtkGraphicsOffload widget will attempt
+     * to offload the content of its child widget.
+     * @param enabled - whether to enable offload
+     */
     setEnabled(enabled) {
         call("libgtk-4.so.1", "gtk_graphics_offload_set_enabled", [
             {

package/dist/generated/gtk/grid-layout-child.d.ts

@@ -1,13 +1,42 @@
 import { LayoutChild } from "./layout-child.js";
+/** `GtkLayoutChild` subclass for children in a `GtkGridLayout`. */
 export declare class GridLayoutChild extends LayoutChild {
     constructor(...args: unknown[]);
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Retrieves the column number to which `child` attaches its left side.
+     */
     getColumn(): number;
+    /**
+     * Retrieves the number of columns that `child` spans to.
+     */
     getColumnSpan(): number;
+    /**
+     * Retrieves the row number to which `child` attaches its top side.
+     */
     getRow(): number;
+    /**
+     * Retrieves the number of rows that `child` spans to.
+     */
     getRowSpan(): number;
+    /**
+     * Sets the column number to attach the left side of @child.
+     * @param column - the attach point for @child
+     */
     setColumn(column: number): void;
+    /**
+     * Sets the number of columns `child` spans to.
+     * @param span - the span of @child
+     */
     setColumnSpan(span: number): void;
+    /**
+     * Sets the row to place `child` in.
+     * @param row - the row for @child
+     */
     setRow(row: number): void;
+    /**
+     * Sets the number of rows `child` spans to.
+     * @param span - the span of @child
+     */
     setRowSpan(span: number): void;
 }