@gtkx/ffi 0.1.45 → 0.1.47

package/dist/generated/gdk/texture-downloader.d.ts

@@ -3,20 +3,101 @@ import { MemoryFormat } from "./enums.js";
 import { ColorState } from "./color-state.js";
 import { Texture } from "./texture.js";
 import * as GLib from "../glib/index.js";
+/**
+ * Used to download the contents of a [class@Gdk.Texture].
+ *
+ * It is intended to be created as a short-term object for a single download,
+ * but can be used for multiple downloads of different textures or with different
+ * settings.
+ *
+ * `GdkTextureDownloader` can be used to convert data between different formats.
+ * Create a `GdkTexture` for the existing format and then download it in a
+ * different format.
+ */
 export declare class TextureDownloader {
     ptr: unknown;
+    /**
+     * Creates a new texture downloader for @texture.
+     *
+     * By default, the downloader will convert the data to
+     * the default memory format, and to the sRGB color state.
+     * @param texture - texture to download
+     */
     constructor(texture: Texture);
     constructor(_args: unknown[]);
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Creates a copy of the downloader.
+     *
+     * This function is meant for language bindings.
+     */
     copy(): TextureDownloader;
+    /**
+     * Downloads the given texture pixels into a `GBytes`. The rowstride will
+     * be stored in the stride value.
+     *
+     * This function will abort if it tries to download a large texture and
+     * fails to allocate memory. If you think that may happen, you should handle
+     * memory allocation yourself and use [method@Gdk.TextureDownloader.download_into]
+     * once allocation succeeded.
+     *
+     * This function cannot be used with a multiplanar format. Use
+     * [method@Gdk.TextureDownloader.download_bytes_with_planes] for that purpose.
+     * @param outStride - The stride of the resulting data in bytes
+     */
     downloadBytes(outStride: Ref<number>): GLib.Bytes;
+    /**
+     * Downloads the given texture pixels into a `GBytes`. The offsets and
+     * strides of the resulting buffer will be stored in the respective values.
+     *
+     * If the format does have less than 4 planes, the remaining offsets and strides will be
+     * set to `0`.
+     * @param outOffsets - The offsets of the resulting data planes in bytes
+     * @param outStrides - The stride of the resulting data planes in bytes
+     */
     downloadBytesWithPlanes(outOffsets: Ref<number[]>, outStrides: Ref<number[]>): GLib.Bytes;
+    /**
+     * Downloads the `texture` into local memory.
+     *
+     * This function cannot be used with a multiplanar format.
+     * @param data - pointer to enough memory to be filled with the
+     * @param stride - rowstride in bytes
+     */
     downloadInto(data: number[], stride: number): void;
+    /**
+     * Frees the given downloader and all its associated resources.
+     */
     free(): void;
+    /**
+     * Gets the color state that the data will be downloaded in.
+     */
     getColorState(): ColorState;
+    /**
+     * Gets the format that the data will be downloaded in.
+     */
     getFormat(): MemoryFormat;
+    /**
+     * Gets the texture that the downloader will download.
+     */
     getTexture(): Texture;
+    /**
+     * Sets the color state the downloader will convert the data to.
+     *
+     * By default, the sRGB colorstate returned by [func@ColorState.get_srgb]
+     * is used.
+     * @param colorState - the color state to use
+     */
     setColorState(colorState: ColorState): void;
+    /**
+     * Sets the format the downloader will download.
+     *
+     * By default, GDK_MEMORY_DEFAULT is set.
+     * @param format - the format to use
+     */
     setFormat(format: MemoryFormat): void;
+    /**
+     * Changes the texture the downloader will download.
+     * @param texture - the new texture to download
+     */
     setTexture(texture: Texture): void;
 }

package/dist/generated/gdk/texture-downloader.js

@@ -3,6 +3,17 @@ import { getObject } from "@gtkx/ffi";
 import { ColorState } from "./color-state.js";
 import { Texture } from "./texture.js";
 import * as GLib from "../glib/index.js";
+/**
+ * Used to download the contents of a [class@Gdk.Texture].
+ *
+ * It is intended to be created as a short-term object for a single download,
+ * but can be used for multiple downloads of different textures or with different
+ * settings.
+ *
+ * `GdkTextureDownloader` can be used to convert data between different formats.
+ * Create a `GdkTexture` for the existing format and then download it in a
+ * different format.
+ */
 export class TextureDownloader {
     ptr;
     constructor(...args) {
@@ -18,6 +29,11 @@ export class TextureDownloader {
             },
         ], { type: "boxed", borrowed: true, innerType: "GdkTextureDownloader" });
     }
+    /**
+     * Creates a copy of the downloader.
+     *
+     * This function is meant for language bindings.
+     */
     copy() {
         const ptr = call("libgtk-4.so.1", "gdk_texture_downloader_copy", [
             {
@@ -32,6 +48,19 @@ export class TextureDownloader {
         });
         return getObject(ptr, TextureDownloader);
     }
+    /**
+     * Downloads the given texture pixels into a `GBytes`. The rowstride will
+     * be stored in the stride value.
+     *
+     * This function will abort if it tries to download a large texture and
+     * fails to allocate memory. If you think that may happen, you should handle
+     * memory allocation yourself and use [method@Gdk.TextureDownloader.download_into]
+     * once allocation succeeded.
+     *
+     * This function cannot be used with a multiplanar format. Use
+     * [method@Gdk.TextureDownloader.download_bytes_with_planes] for that purpose.
+     * @param outStride - The stride of the resulting data in bytes
+     */
     downloadBytes(outStride) {
         const ptr = call("libgtk-4.so.1", "gdk_texture_downloader_download_bytes", [
             {
@@ -53,6 +82,15 @@ export class TextureDownloader {
         });
         return getObject(ptr, GLib.Bytes);
     }
+    /**
+     * Downloads the given texture pixels into a `GBytes`. The offsets and
+     * strides of the resulting buffer will be stored in the respective values.
+     *
+     * If the format does have less than 4 planes, the remaining offsets and strides will be
+     * set to `0`.
+     * @param outOffsets - The offsets of the resulting data planes in bytes
+     * @param outStrides - The stride of the resulting data planes in bytes
+     */
     downloadBytesWithPlanes(outOffsets, outStrides) {
         const ptr = call("libgtk-4.so.1", "gdk_texture_downloader_download_bytes_with_planes", [
             {
@@ -87,6 +125,13 @@ export class TextureDownloader {
         });
         return getObject(ptr, GLib.Bytes);
     }
+    /**
+     * Downloads the `texture` into local memory.
+     *
+     * This function cannot be used with a multiplanar format.
+     * @param data - pointer to enough memory to be filled with the
+     * @param stride - rowstride in bytes
+     */
     downloadInto(data, stride) {
         call("libgtk-4.so.1", "gdk_texture_downloader_download_into", [
             {
@@ -106,6 +151,9 @@ export class TextureDownloader {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Frees the given downloader and all its associated resources.
+     */
     free() {
         call("libgtk-4.so.1", "gdk_texture_downloader_free", [
             {
@@ -114,6 +162,9 @@ export class TextureDownloader {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Gets the color state that the data will be downloaded in.
+     */
     getColorState() {
         const ptr = call("libgtk-4.so.1", "gdk_texture_downloader_get_color_state", [
             {
@@ -128,6 +179,9 @@ export class TextureDownloader {
         });
         return getObject(ptr, ColorState);
     }
+    /**
+     * Gets the format that the data will be downloaded in.
+     */
     getFormat() {
         return call("libgtk-4.so.1", "gdk_texture_downloader_get_format", [
             {
@@ -136,6 +190,9 @@ export class TextureDownloader {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Gets the texture that the downloader will download.
+     */
     getTexture() {
         const ptr = call("libgtk-4.so.1", "gdk_texture_downloader_get_texture", [
             {
@@ -145,6 +202,13 @@ export class TextureDownloader {
         ], { type: "gobject", borrowed: true });
         return getObject(ptr, Texture);
     }
+    /**
+     * Sets the color state the downloader will convert the data to.
+     *
+     * By default, the sRGB colorstate returned by [func@ColorState.get_srgb]
+     * is used.
+     * @param colorState - the color state to use
+     */
     setColorState(colorState) {
         call("libgtk-4.so.1", "gdk_texture_downloader_set_color_state", [
             {
@@ -162,6 +226,12 @@ export class TextureDownloader {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets the format the downloader will download.
+     *
+     * By default, GDK_MEMORY_DEFAULT is set.
+     * @param format - the format to use
+     */
     setFormat(format) {
         call("libgtk-4.so.1", "gdk_texture_downloader_set_format", [
             {
@@ -174,6 +244,10 @@ export class TextureDownloader {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Changes the texture the downloader will download.
+     * @param texture - the new texture to download
+     */
     setTexture(texture) {
         call("libgtk-4.so.1", "gdk_texture_downloader_set_texture", [
             {

package/dist/generated/gdk/texture.d.ts

@@ -7,31 +7,338 @@ import * as GLib from "../glib/index.js";
 import * as GObject from "../gobject/index.js";
 import * as GdkPixbuf from "../gdkpixbuf/index.js";
 import * as Gio from "../gio/index.js";
+/**
+ * Refers to pixel data in various forms.
+ *
+ * It is primarily meant for pixel data that will not change over
+ * multiple frames, and will be used for a long time.
+ *
+ * There are various ways to create `GdkTexture` objects from a
+ * [class@GdkPixbuf.Pixbuf], or from bytes stored in memory, a file, or a
+ * [struct@Gio.Resource].
+ *
+ * The ownership of the pixel data is transferred to the `GdkTexture`
+ * instance; you can only make a copy of it, via [method@Gdk.Texture.download].
+ *
+ * `GdkTexture` is an immutable object: That means you cannot change
+ * anything about it other than increasing the reference count via
+ * [method@GObject.Object.ref], and consequently, it is a threadsafe object.
+ *
+ * GDK provides a number of threadsafe texture loading functions:
+ * [ctor@Gdk.Texture.new_from_resource],
+ * [ctor@Gdk.Texture.new_from_bytes],
+ * [ctor@Gdk.Texture.new_from_file],
+ * [ctor@Gdk.Texture.new_from_filename],
+ * [ctor@Gdk.Texture.new_for_pixbuf]. Note that these are meant for loading
+ * icons and resources that are shipped with the toolkit or application. It
+ * is recommended that you use a dedicated image loading framework such as
+ * [glycin](https://lib.rs/crates/glycin), if you need to load untrusted image
+ * data.
+ */
 export declare class Texture extends GObject.GObject {
+    /**
+     * Creates a new texture object representing the `GdkPixbuf`.
+     *
+     * This function is threadsafe, so that you can e.g. use GTask
+     * and [method@Gio.Task.run_in_thread] to avoid blocking the main
+     * thread while loading a big image.
+     * @param pixbuf - a `GdkPixbuf`
+     */
     constructor(pixbuf: GdkPixbuf.Pixbuf);
     constructor(...args: unknown[]);
+    /**
+     * Creates a new texture by loading an image from memory,
+     *
+     * The file format is detected automatically. The supported formats
+     * are PNG, JPEG and TIFF, though more formats might be available.
+     *
+     * If `NULL` is returned, then `error` will be set.
+     *
+     * This function is threadsafe, so that you can e.g. use GTask
+     * and [method@Gio.Task.run_in_thread] to avoid blocking the main thread
+     * while loading a big image.
+     *
+     * ::: warning
+     * Note that this function should not be used with untrusted data.
+     * Use a proper image loading framework such as libglycin, which can
+     * load many image formats into a `GdkTexture`.
+     * @param bytes - a `GBytes` containing the data to load
+     */
     static newFromBytes(bytes: GLib.Bytes): Texture;
+    /**
+     * Creates a new texture by loading an image from a file.
+     *
+     * The file format is detected automatically. The supported formats
+     * are PNG, JPEG and TIFF, though more formats might be available.
+     *
+     * If `NULL` is returned, then `error` will be set.
+     *
+     * This function is threadsafe, so that you can e.g. use GTask
+     * and [method@Gio.Task.run_in_thread] to avoid blocking the main thread
+     * while loading a big image.
+     *
+     * ::: warning
+     * Note that this function should not be used with untrusted data.
+     * Use a proper image loading framework such as libglycin, which can
+     * load many image formats into a `GdkTexture`.
+     * @param file - `GFile` to load
+     */
     static newFromFile(file: Gio.File): Texture;
+    /**
+     * Creates a new texture by loading an image from a file.
+     *
+     * The file format is detected automatically. The supported formats
+     * are PNG, JPEG and TIFF, though more formats might be available.
+     *
+     * If `NULL` is returned, then `error` will be set.
+     *
+     * This function is threadsafe, so that you can e.g. use GTask
+     * and [method@Gio.Task.run_in_thread] to avoid blocking the main thread
+     * while loading a big image.
+     *
+     * ::: warning
+     * Note that this function should not be used with untrusted data.
+     * Use a proper image loading framework such as libglycin, which can
+     * load many image formats into a `GdkTexture`.
+     * @param path - the filename to load
+     */
     static newFromFilename(path: string): Texture;
+    /**
+     * Creates a new texture by loading an image from a resource.
+     *
+     * The file format is detected automatically. The supported formats
+     * are PNG, JPEG and TIFF, though more formats might be available.
+     *
+     * It is a fatal error if `resource_path` does not specify a valid
+     * image resource and the program will abort if that happens.
+     * If you are unsure about the validity of a resource, use
+     * [ctor@Gdk.Texture.new_from_file] to load it.
+     *
+     * This function is threadsafe, so that you can e.g. use GTask
+     * and [method@Gio.Task.run_in_thread] to avoid blocking the main thread
+     * while loading a big image.
+     * @param resourcePath - the path of the resource file
+     */
     static newFromResource(resourcePath: string): Texture;
     protected createPtr(args: unknown[]): unknown;
+    /**
+     * Downloads the `texture` into local memory.
+     *
+     * This may be an expensive operation, as the actual texture data
+     * may reside on a GPU or on a remote display server.
+     *
+     * The data format of the downloaded data is equivalent to
+     * %CAIRO_FORMAT_ARGB32, so every downloaded pixel requires
+     * 4 bytes of memory.
+     *
+     * Downloading a texture into a Cairo image surface:
+     * ```c
+     * surface = cairo_image_surface_create (CAIRO_FORMAT_ARGB32,
+     * gdk_texture_get_width (texture),
+     * gdk_texture_get_height (texture));
+     * gdk_texture_download (texture,
+     * cairo_image_surface_get_data (surface),
+     * cairo_image_surface_get_stride (surface));
+     * cairo_surface_mark_dirty (surface);
+     * ```
+     *
+     * For more flexible download capabilities, see
+     * [struct@Gdk.TextureDownloader].
+     * @param data - pointer to enough memory to be filled with the
+     * @param stride - rowstride in bytes
+     */
     download(data: number[], stride: number): void;
+    /**
+     * Returns the color state associated with the texture.
+     */
     getColorState(): ColorState;
+    /**
+     * Gets the memory format most closely associated with the data of
+     * the texture.
+     *
+     * Note that it may not be an exact match for texture data
+     * stored on the GPU or with compression.
+     *
+     * The format can give an indication about the bit depth and opacity
+     * of the texture and is useful to determine the best format for
+     * downloading the texture.
+     */
     getFormat(): MemoryFormat;
+    /**
+     * Returns the height of the @texture, in pixels.
+     */
     getHeight(): number;
+    /**
+     * Returns the width of @texture, in pixels.
+     */
     getWidth(): number;
+    /**
+     * Store the given `texture` to the `filename` as a PNG file.
+     *
+     * This is a utility function intended for debugging and testing.
+     * If you want more control over formats, proper error handling or
+     * want to store to a [iface@Gio.File] or other location, you might
+     * want to use [method@Gdk.Texture.save_to_png_bytes] or look into
+     * the libglycin library.
+     * @param filename - the filename to store to
+     */
     saveToPng(filename: string): boolean;
+    /**
+     * Store the given `texture` in memory as a PNG file.
+     *
+     * Use [ctor@Gdk.Texture.new_from_bytes] to read it back.
+     *
+     * If you want to serialize a texture, this is a convenient and
+     * portable way to do that.
+     *
+     * If you need more control over the generated image, such as
+     * attaching metadata, you should look into an image handling
+     * library such as the libglycin library.
+     *
+     * If you are dealing with high dynamic range float data, you
+     * might also want to consider [method@Gdk.Texture.save_to_tiff_bytes]
+     * instead.
+     */
     saveToPngBytes(): GLib.Bytes;
+    /**
+     * Store the given `texture` to the `filename` as a TIFF file.
+     *
+     * GTK will attempt to store data without loss.
+     * @param filename - the filename to store to
+     */
     saveToTiff(filename: string): boolean;
+    /**
+     * Store the given `texture` in memory as a TIFF file.
+     *
+     * Use [ctor@Gdk.Texture.new_from_bytes] to read it back.
+     *
+     * This function is intended to store a representation of the
+     * texture's data that is as accurate as possible. This is
+     * particularly relevant when working with high dynamic range
+     * images and floating-point texture data.
+     *
+     * If that is not your concern and you are interested in a
+     * smaller size and a more portable format, you might want to
+     * use [method@Gdk.Texture.save_to_png_bytes].
+     */
     saveToTiffBytes(): GLib.Bytes;
+    /**
+     * Compute a concrete size for the `GdkPaintable`.
+     *
+     * Applies the sizing algorithm outlined in the
+     * [CSS Image spec](https://drafts.csswg.org/css-images-3/#default-sizing)
+     * to the given @paintable. See that link for more details.
+     *
+     * It is not necessary to call this function when both `specified_width` and `specified_height` are known, but it is useful to call this
+     * function in GtkWidget:measure implementations to compute the
+     * other dimension when only one dimension is given.
+     * @param specifiedWidth - the width `paintable` could be drawn into or
+     * @param specifiedHeight - the height `paintable` could be drawn into or
+     * @param defaultWidth - the width `paintable` would be drawn into if
+     * @param defaultHeight - the height `paintable` would be drawn into if
+     * @param concreteWidth - will be set to the concrete width computed
+     * @param concreteHeight - will be set to the concrete height computed
+     */
     computeConcreteSize(specifiedWidth: number, specifiedHeight: number, defaultWidth: number, defaultHeight: number, concreteWidth: Ref<number>, concreteHeight: Ref<number>): void;
+    /**
+     * Gets an immutable paintable for the current contents displayed by @paintable.
+     *
+     * This is useful when you want to retain the current state of an animation,
+     * for example to take a screenshot of a running animation.
+     *
+     * If the `paintable` is already immutable, it will return itself.
+     */
     getCurrentImage(): Paintable;
+    /**
+     * Get flags for the paintable.
+     *
+     * This is oftentimes useful for optimizations.
+     *
+     * See [flags@Gdk.PaintableFlags] for the flags and what they mean.
+     */
     getFlags(): PaintableFlags;
+    /**
+     * Gets the preferred aspect ratio the `paintable` would like to be displayed at.
+     *
+     * The aspect ratio is the width divided by the height, so a value of 0.5
+     * means that the `paintable` prefers to be displayed twice as high as it
+     * is wide. Consumers of this interface can use this to preserve aspect
+     * ratio when displaying the paintable.
+     *
+     * This is a purely informational value and does not in any way limit the
+     * values that may be passed to [method@Gdk.Paintable.snapshot].
+     *
+     * Usually when a `paintable` returns nonzero values from
+     * [method@Gdk.Paintable.get_intrinsic_width] and
+     * [method@Gdk.Paintable.get_intrinsic_height] the aspect ratio
+     * should conform to those values, though that is not required.
+     *
+     * If the `paintable` does not have a preferred aspect ratio,
+     * it returns 0. Negative values are never returned.
+     */
     getIntrinsicAspectRatio(): number;
+    /**
+     * Gets the preferred height the `paintable` would like to be displayed at.
+     *
+     * Consumers of this interface can use this to reserve enough space to draw
+     * the paintable.
+     *
+     * This is a purely informational value and does not in any way limit the
+     * values that may be passed to [method@Gdk.Paintable.snapshot].
+     *
+     * If the `paintable` does not have a preferred height, it returns 0.
+     * Negative values are never returned.
+     */
     getIntrinsicHeight(): number;
+    /**
+     * Gets the preferred width the `paintable` would like to be displayed at.
+     *
+     * Consumers of this interface can use this to reserve enough space to draw
+     * the paintable.
+     *
+     * This is a purely informational value and does not in any way limit the
+     * values that may be passed to [method@Gdk.Paintable.snapshot].
+     *
+     * If the `paintable` does not have a preferred width, it returns 0.
+     * Negative values are never returned.
+     */
     getIntrinsicWidth(): number;
+    /**
+     * Called by implementations of `GdkPaintable` to invalidate their contents.
+     *
+     * Unless the contents are invalidated, implementations must guarantee that
+     * multiple calls of [method@Gdk.Paintable.snapshot] produce the same output.
+     *
+     * This function will emit the [signal@Gdk.Paintable::invalidate-contents]
+     * signal.
+     *
+     * If a `paintable` reports the %GDK_PAINTABLE_STATIC_CONTENTS flag,
+     * it must not call this function.
+     */
     invalidateContents(): void;
+    /**
+     * Called by implementations of `GdkPaintable` to invalidate their size.
+     *
+     * As long as the size is not invalidated, `paintable` must return the same
+     * values for its intrinsic width, height and aspect ratio.
+     *
+     * This function will emit the [signal@Gdk.Paintable::invalidate-size]
+     * signal.
+     *
+     * If a `paintable` reports the %GDK_PAINTABLE_STATIC_SIZE flag,
+     * it must not call this function.
+     */
     invalidateSize(): void;
+    /**
+     * Snapshots the given paintable with the given `width` and @height.
+     *
+     * The paintable is drawn at the current (0,0) offset of the @snapshot.
+     * If `width` and `height` are not larger than zero, this function will
+     * do nothing.
+     * @param snapshot - a `GdkSnapshot` to snapshot to
+     * @param width - width to snapshot in
+     * @param height - height to snapshot in
+     */
     snapshot(snapshot: Snapshot, width: number, height: number): void;
     connect(signal: "notify", handler: (self: Texture, pspec: GObject.ParamSpec) => void, after?: boolean): number;
     connect(signal: string, handler: (...args: any[]) => any, after?: boolean): number;