wasm-vips 0.0.9 → 0.0.11

package/lib/vips.d.ts

@@ -41,7 +41,7 @@ declare module Vips {
 
     /**
      * Queue of handles to be deleted.
-     * This is filled when [[deleteLater]] is called on the handle.
+     * This is filled when {@link deleteLater} is called on the handle.
      */
     const deletionQueue: DeletionFuncs<Image | Connection | Interpolate>;
 
@@ -112,14 +112,6 @@ declare module Vips {
      */
     function shutdown(): void;
 
-    /**
-     * Convert a bigint value (usually coming from Wasm->JS call) into an int53 JS Number.
-     * This is used when we have an incoming i64 that we know is a pointer or size_t and
-     * is expected to be withing the int53 range.
-     * @return The converted bigint value or NaN if the incoming bigint is outside the range.
-     */
-    function bigintToI53Checked(num: bigint): number;
-
     //#endregion
 
     //#region APIs
@@ -129,8 +121,8 @@ declare module Vips {
      */
     abstract class EmbindClassHandle<T extends EmbindClassHandle<T>> {
         /**
-         * Returns a new handle. It must eventually also be disposed with [[delete]] or
-         * [[deleteLater]].
+         * Returns a new handle. It must eventually also be disposed with {@link delete} or
+         * {@link deleteLater}.
          * @return A new handle.
          */
         clone(): T;
@@ -142,8 +134,9 @@ declare module Vips {
 
         /**
          * Signal that a C++ object is no longer needed and can be deleted later.
+         * @return `this`.
          */
-        deleteLater(): void;
+        deleteLater(): T;
 
         /**
          * Check whether two Embind handles point to the same underlying object.
@@ -157,6 +150,12 @@ declare module Vips {
          * @return `true` if this handle is deleted.
          */
         isDeleted(): boolean;
+
+        /**
+         * Prevents the C++ object from being auto deleted.
+         * @return `this`.
+         */
+        preventAutoDelete(): T;
     }
 
     /**
@@ -310,7 +309,7 @@ declare module Vips {
          * ```js
          * const source = vips.Source.newFromFile('myfile.jpg');
          * ```
-         * You can pass this source to (for example) [[Image.newFromSource]].
+         * You can pass this source to (for example) {@link Image.newFromSource}.
          * @param filename The file.
          * @return A new source.
          */
@@ -324,7 +323,7 @@ declare module Vips {
          * const data = image.writeToBuffer('.jpg');
          * const source = vips.Source.newFromMemory(data);
          * ```
-         * You can pass this source to (for example) [[Image.newFromSource]].
+         * You can pass this source to (for example) {@link Image.newFromSource}.
          * @param memory The memory object.
          * @return A new source.
          */
@@ -337,11 +336,13 @@ declare module Vips {
     class SourceCustom extends Source {
         /**
          * Attach a read handler.
-         * @param ptr A pointer to an array of bytes where the read content is stored.
-         * @param size The maximum number of bytes to be read.
-         * @return The total number of bytes read into the buffer.
+         * The handler is given a number of bytes to fetch {@link length}, and should return a
+         * bytes-like object containing up to that number of bytes. If there's no more data
+         * available, it should return `undefined`.
+         * @param length The maximum number of bytes to be read.
+         * @return A blob up to {@link length} bytes or `undefined` if there's no more data available.
          */
-        onRead: (ptr: number, size: bigint) => bigint;
+        onRead: (length: number) => Blob | undefined;
 
         /**
          * Attach a seek handler.
@@ -351,7 +352,7 @@ declare module Vips {
          * @param size A value indicating the reference point used to obtain the new position.
          * @return The new position within the current source.
          */
-        onSeek: (offset: bigint, whence: number) => bigint;
+        onSeek: (offset: number, whence: number) => number;
     }
 
     /**
@@ -365,8 +366,8 @@ declare module Vips {
          * ```js
          * const target = vips.Target.newToFile('myfile.jpg');
          * ```
-         * You can pass this target to (for example) [[image.writeToTarget]].
-         * @param filename Write to this this file.
+         * You can pass this target to (for example) {@link image.writeToTarget}.
+         * @param filename Write to this file.
          * @return A new target.
          */
         static newToFile(filename: string): Target;
@@ -378,9 +379,9 @@ declare module Vips {
          * ```js
          * const target = vips.Target.newToMemory();
          * ```
-         * You can pass this target to (for example) [[image.writeToTarget]].
+         * You can pass this target to (for example) {@link image.writeToTarget}.
          *
-         * After writing to the target, fetch the bytes from the target object with [[getBlob]].
+         * After writing to the target, fetch the bytes from the target object with {@link getBlob}.
          * @return A new target.
          */
         static newToMemory(): Target;
@@ -400,22 +401,20 @@ declare module Vips {
     class TargetCustom extends Target {
         /**
          * Attach a write handler.
-         * @param ptr A pointer to an array of bytes which will be written to.
-         * @param length The number of bytes to write.
+         * @param data A typed array of 8-bit unsigned integer values.
          * @return The number of bytes that were written.
          */
-        onWrite: (ptr: number, size: bigint) => bigint;
+        onWrite: (data: Uint8Array) => number;
 
         /* libtiff needs to be able to seek and read on targets, unfortunately.
          */
 
         /**
          * Attach a read handler.
-         * @param ptr A pointer to an array of bytes where the read content is stored.
-         * @param size The maximum number of bytes to be read.
-         * @return The total number of bytes read from the target.
+         * @param length The maximum number of bytes to be read.
+         * @return A blob up to {@link length} bytes or `undefined` if there's no more data available.
          */
-        onRead: (ptr: number, size: bigint) => bigint;
+        onRead: (length: number) => Blob | undefined;
 
         /**
          * Attach a seek handler.
@@ -423,7 +422,7 @@ declare module Vips {
          * @param size A value indicating the reference point used to obtain the new position.
          * @return The new position within the current target.
          */
-        onSeek: (offset: bigint, whence: number) => bigint;
+        onSeek: (offset: number, whence: number) => number;
 
         /**
          * Attach an end handler.
@@ -543,7 +542,7 @@ declare module Vips {
          * Make a new temporary image.
          *
          * Returns an image backed by a temporary file. When written to with
-         * [[write]], a temporary file will be created on disc in the
+         * {@link write}, a temporary file will be created on disc in the
          * specified format. When the image is closed, the file will be deleted
          * automatically.
          *
@@ -598,7 +597,7 @@ declare module Vips {
             access?: Access | Enum
             /**
              * The type of error that will cause load to fail. By default,
-             * loaders are permissive, that is, [[FailOn.none]].
+             * loaders are permissive, that is, {@link FailOn.none}.
              */
             fail_on?: FailOn | Enum
             /**
@@ -623,8 +622,8 @@ declare module Vips {
          * This method is useful for efficiently transferring images from WebGL into
          * libvips.
          *
-         * See [[writeToMemory]] for the opposite operation.
-         * Use [[copy]] to set other image attributes.
+         * See {@link writeToMemory} for the opposite operation.
+         * Use {@link copy} to set other image attributes.
          * @param data A C-style JavaScript array.
          * @param width Image width in pixels.
          * @param height Image height in pixels.
@@ -637,7 +636,7 @@ declare module Vips {
         /**
          * Wrap an image around a pointer.
          *
-         * This behaves exactly as [[newFromMemory]], but the image is
+         * This behaves exactly as {@link newFromMemory}, but the image is
          * loaded from a pointer rather than from a JavaScript array.
          * @param ptr A memory address.
          * @param size Length of memory area.
@@ -652,7 +651,7 @@ declare module Vips {
         /**
          * Load a formatted image from memory.
          *
-         * This behaves exactly as [[newFromFile]], but the image is
+         * This behaves exactly as {@link newFromFile}, but the image is
          * loaded from the memory object rather than from a file. The
          * memory object can be a string or buffer.
          * @param data The memory object to load the image from.
@@ -667,7 +666,7 @@ declare module Vips {
             access?: Access | Enum
             /**
              * The type of error that will cause load to fail. By default,
-             * loaders are permissive, that is, [[FailOn.none]].
+             * loaders are permissive, that is, {@link FailOn.none}.
              */
             fail_on?: FailOn | Enum
             /**
@@ -679,7 +678,7 @@ declare module Vips {
         /**
          * Load a formatted image from a source.
          *
-         * This behaves exactly as [[newFromFile]], but the image is
+         * This behaves exactly as {@link newFromFile}, but the image is
          * loaded from a source rather than from a file.
          * @param source The source to load the image from.
          * @param strOptions Load options as a string.
@@ -693,7 +692,7 @@ declare module Vips {
             access?: Access | Enum
             /**
              * The type of error that will cause load to fail. By default,
-             * loaders are permissive, that is, [[FailOn.none]].
+             * loaders are permissive, that is, {@link FailOn.none}.
              */
             fail_on?: FailOn | Enum
             /**
@@ -705,9 +704,9 @@ declare module Vips {
         /**
          * Create an image from a 1D array.
          *
-         * A new one-band image with [[BandFormat.double]] pixels is
+         * A new one-band image with {@link BandFormat.double} pixels is
          * created from the array. These images are useful with the libvips
-         * convolution operator [[conv]].
+         * convolution operator {@link conv}.
          * @param width Image width.
          * @param height Image height.
          * @param array Create the image from these values.
@@ -718,9 +717,9 @@ declare module Vips {
         /**
          * Create an image from a 2D array.
          *
-         * A new one-band image with [[BandFormat.double]] pixels is
+         * A new one-band image with {@link BandFormat.double} pixels is
          * created from the array. These images are useful with the libvips
-         * convolution operator [[conv]].
+         * convolution operator {@link conv}.
          * @param array Create the image from these values.
          * @param scale Default to 1.0. What to divide each pixel by after
          * convolution. Useful for integer convolution masks.
@@ -759,7 +758,7 @@ declare module Vips {
          * Write an image to another image.
          *
          * This function writes itself to another image. Use something like
-         * [[newTempFile]] to make an image that can be written to.
+         * {@link newTempFile} to make an image that can be written to.
          * @param other The image to write to.
          * @return A new image.
          */
@@ -770,7 +769,7 @@ declare module Vips {
          *
          * This method can save images in any format supported by libvips. The format
          * is selected from the filename suffix. The filename can include embedded
-         * save options, see [[newFromFile]].
+         * save options, see {@link newFromFile}.
          *
          * For example:
          * ```js
@@ -799,7 +798,7 @@ declare module Vips {
          *
          * This method can save images in any format supported by libvips. The format
          * is selected from the suffix in the format string. This can include
-         * embedded save options, see [[newFromFile]].
+         * embedded save options, see {@link newFromFile}.
          *
          * For example:
          * ```js
@@ -827,7 +826,7 @@ declare module Vips {
         /**
          * Write an image to a target.
          *
-         * This behaves exactly as [[writeToFile]], but the image is
+         * This behaves exactly as {@link writeToFile}, but the image is
          * written to a target rather than a file.
          * @param target Write to this target.
          * @param formatString The suffix, plus any string-form arguments.
@@ -872,28 +871,28 @@ declare module Vips {
         setArrayInt(name: string, value: ArrayConstant): void;
 
         /**
-         * Set an double array on an image as metadata.
+         * Set a double array on an image as metadata.
          * @param name The name of the piece of metadata to set the value of.
          * @param value The metadata value.
          */
         setArrayDouble(name: string, value: ArrayConstant): void;
 
         /**
-         * Set an double on an image as metadata.
+         * Set a double on an image as metadata.
          * @param name The name of the piece of metadata to set the value of.
          * @param value The metadata value.
          */
         setDouble(name: string, value: number): void;
 
         /**
-         * Set an string on an image as metadata.
+         * Set a string on an image as metadata.
          * @param name The name of the piece of metadata to set the value of.
          * @param value The metadata value.
          */
         setString(name: string, value: string): void;
 
         /**
-         * Set an blob on an image as metadata.
+         * Set a blob on an image as metadata.
          * The value will internally be copied from JavaScript to WASM.
          * @param name The name of the piece of metadata to set the value of.
          * @param value The metadata value.
@@ -901,7 +900,7 @@ declare module Vips {
         setBlob(name: string, value: Blob): void;
 
         /**
-         * Set an blob pointer on an image as metadata.
+         * Set a blob pointer on an image as metadata.
          * @param name The name of the piece of metadata to set the value of.
          * @param ptr The metadata value as memory address.
          * @param size Length of blob.
@@ -931,30 +930,30 @@ declare module Vips {
         getArrayInt(name: string): number[];
 
         /**
-         * Get an double array from an image.
+         * Get a double array from an image.
          * @param name The name of the piece of metadata to get.
-         * @return The metadata item as an double array.
+         * @return The metadata item as a double array.
          */
         getArrayDouble(name: string): number[];
 
         /**
          * Get an double from an image.
          * @param name The name of the piece of metadata to get.
-         * @return The metadata item as an double.
+         * @return The metadata item as a double.
          */
         getDouble(name: string): number;
 
         /**
-         * Get an string from an image.
+         * Get a string from an image.
          * @param name The name of the piece of metadata to get.
-         * @return The metadata item as an string.
+         * @return The metadata item as a string.
          */
         getString(name: string): string;
 
         /**
-         * Get an blob from an image.
+         * Get a blob from an image.
          * @param name The name of the piece of metadata to get.
-         * @return The metadata item as an typed array of 8-bit unsigned integer values.
+         * @return The metadata item as a typed array of 8-bit unsigned integer values.
          */
         getBlob(name: string): Uint8Array;
 
@@ -969,7 +968,7 @@ declare module Vips {
          * @param name The name of the piece of metadata to remove.
          * @return `true` if successfully removed.
          */
-        remove(name: string): string;
+        remove(name: string): boolean;
 
         //#endregion
 
@@ -984,7 +983,7 @@ declare module Vips {
         /**
          * Sets the `delete_on_close` flag for the image.
          * If this flag is set, when image is finalized, the filename held in
-         * [[image.filename]] at the time of this call is deleted.
+         * {@link image.filename} at the time of this call is deleted.
          * This function is clearly extremely dangerous, use with great caution.
          */
         setDeleteOnClose(flag: boolean): void;
@@ -2339,6 +2338,30 @@ declare module Vips {
         none = 3 // 'none'
     }
 
+    /**
+     * The SDF to generate,
+     *
+     * See also: vips_sdf().
+     */
+    enum SdfShape {
+        /**
+         * A circle at @a, radius @r
+         */
+        circle = 0, // 'circle'
+        /**
+         * A box from @a to @b
+         */
+        box = 1, // 'box'
+        /**
+         * A box with rounded @corners from @a to @b
+         */
+        rounded_box = 2, // 'rounded-box'
+        /**
+         * A line from @a to @b
+         */
+        line = 3 // 'line'
+    }
+
     /**
      * How sensitive loaders are to errors, from never stop (very insensitive), to
      * stop on the smallest warning (very sensitive).
@@ -3703,6 +3726,14 @@ declare module Vips {
          * @return Output image.
          */
         static jxlload(filename: string, options?: {
+            /**
+             * First page to load.
+             */
+            page?: number
+            /**
+             * Number of pages to load, -1 for all.
+             */
+            n?: number
             /**
              * Force open via memory.
              */
@@ -3732,6 +3763,14 @@ declare module Vips {
          * @return Output image.
          */
         static jxlloadBuffer(buffer: Blob, options?: {
+            /**
+             * First page to load.
+             */
+            page?: number
+            /**
+             * Number of pages to load, -1 for all.
+             */
+            n?: number
             /**
              * Force open via memory.
              */
@@ -3761,6 +3800,14 @@ declare module Vips {
          * @return Output image.
          */
         static jxlloadSource(source: Source, options?: {
+            /**
+             * First page to load.
+             */
+            page?: number
+            /**
+             * Number of pages to load, -1 for all.
+             */
+            n?: number
             /**
              * Force open via memory.
              */
@@ -4919,6 +4966,33 @@ declare module Vips {
             flags?: number | undefined
         }): Image;
 
+        /**
+         * Create an sdf image.
+         * @param width Image width in pixels.
+         * @param height Image height in pixels.
+         * @param shape SDF shape to create.
+         * @param options Optional options.
+         * @return Output image.
+         */
+        static sdf(width: number, height: number, shape: SdfShape | Enum, options?: {
+            /**
+             * Radius.
+             */
+            r?: number
+            /**
+             * Point a.
+             */
+            a?: ArrayConstant
+            /**
+             * Point b.
+             */
+            b?: ArrayConstant
+            /**
+             * Corner radii.
+             */
+            corners?: ArrayConstant
+        }): Image;
+
         /**
          * Make a 2d sine wave.
          * @param width Image width in pixels.
@@ -5862,6 +5936,12 @@ declare module Vips {
          */
         add(right: Image | ArrayConstant): Image;
 
+        /**
+         * Append an alpha channel.
+         * @return Output image.
+         */
+        addalpha(): Image;
+
         /**
          * Affine transform of an image.
          * @param matrix Transformation matrix.
@@ -5986,26 +6066,6 @@ declare module Vips {
          */
         byteswap(): Image;
 
-        /**
-         * Cache an image.
-         * @param options Optional options.
-         * @return Output image.
-         */
-        cache(options?: {
-            /**
-             * Maximum number of tiles to cache.
-             */
-            max_tiles?: number
-            /**
-             * Tile height in pixels.
-             */
-            tile_height?: number
-            /**
-             * Tile width in pixels.
-             */
-            tile_width?: number
-        }): Image;
-
         /**
          * Canny edge detector.
          * @param options Optional options.
@@ -6042,6 +6102,22 @@ declare module Vips {
             shift?: boolean
         }): Image;
 
+        /**
+         * Clamp values of an image.
+         * @param options Optional options.
+         * @return Output image.
+         */
+        clamp(options?: {
+            /**
+             * Minimum value.
+             */
+            min?: number
+            /**
+             * Maximum value.
+             */
+            max?: number
+        }): Image;
+
         /**
          * Convert to a new colorspace.
          * @param space Destination color space.
@@ -6898,9 +6974,15 @@ declare module Vips {
          * Read a point from an image.
          * @param x Point to read.
          * @param y Point to read.
+         * @param options Optional options.
          * @return Array of output values.
          */
-        getpoint(x: number, y: number): number[];
+        getpoint(x: number, y: number, options?: {
+            /**
+             * Complex pixels should be unpacked.
+             */
+            unpack_complex?: boolean
+        }): number[];
 
         /**
          * Save as gif.
@@ -7574,7 +7656,7 @@ declare module Vips {
 
         /**
          * Save image in jpeg2000 format.
-         * @param filename Filename to load from.
+         * @param filename Filename to save to.
          * @param options Optional options.
          */
         jp2ksave(filename: string, options?: {
@@ -7945,7 +8027,7 @@ declare module Vips {
 
         /**
          * Save image in jpeg-xl format.
-         * @param filename Filename to load from.
+         * @param filename Filename to save to.
          * @param options Optional options.
          */
         jxlsave(filename: string, options?: {
@@ -8408,6 +8490,13 @@ declare module Vips {
             y_array?: number[] | undefined
         }): number;
 
+        /**
+         * Maximum of a pair of images.
+         * @param right Right-hand image argument.
+         * @return Output image.
+         */
+        maxpair(right: Image | ArrayConstant): Image;
+
         /**
          * Measure a set of patches on a color chart.
          * @param h Number of patches across chart.
@@ -8482,6 +8571,13 @@ declare module Vips {
             y_array?: number[] | undefined
         }): number;
 
+        /**
+         * Minimum of a pair of images.
+         * @param right Right-hand image argument.
+         * @return Output image.
+         */
+        minpair(right: Image | ArrayConstant): Image;
+
         /**
          * Morphology operation.
          * @param mask Input matrix image.
@@ -9022,11 +9118,35 @@ declare module Vips {
         }): void;
 
         /**
-         * Write raw image to file descriptor.
-         * @param fd File descriptor to write to.
+         * Write raw image to buffer.
          * @param options Optional options.
+         * @return Buffer to save to.
          */
-        rawsaveFd(fd: number, options?: {
+        rawsaveBuffer(options?: {
+            /**
+             * Which metadata to retain.
+             */
+            keep?: ForeignKeep | Flag
+            /**
+             * Background value.
+             */
+            background?: ArrayConstant
+            /**
+             * Set page height for multipage save.
+             */
+            page_height?: number
+            /**
+             * Filename of icc profile to embed.
+             */
+            profile?: string
+        }): Uint8Array;
+
+        /**
+         * Write raw image to target.
+         * @param target Target to save to.
+         * @param options Optional options.
+         */
+        rawsaveTarget(target: Target, options?: {
             /**
              * Which metadata to retain.
              */
@@ -9169,7 +9289,7 @@ declare module Vips {
 
         /**
          * Rotate an image by a number of degrees.
-         * @param angle Rotate anticlockwise by this many degrees.
+         * @param angle Rotate clockwise by this many degrees.
          * @param options Optional options.
          * @return Output image.
          */
@@ -9372,7 +9492,7 @@ declare module Vips {
              */
             scale?: number
             /**
-             * Rotate anticlockwise by this many degrees.
+             * Rotate clockwise by this many degrees.
              */
             angle?: number
             /**
@@ -9611,7 +9731,7 @@ declare module Vips {
              */
             region_shrink?: RegionShrink | Enum
             /**
-             * Zstd compression level.
+             * Deflate (1-9, default 6) or zstd (1-22, default 9) compression level.
              */
             level?: number
             /**
@@ -9715,7 +9835,7 @@ declare module Vips {
              */
             region_shrink?: RegionShrink | Enum
             /**
-             * Zstd compression level.
+             * Deflate (1-9, default 6) or zstd (1-22, default 9) compression level.
              */
             level?: number
             /**
@@ -9819,7 +9939,7 @@ declare module Vips {
              */
             region_shrink?: RegionShrink | Enum
             /**
-             * Zstd compression level.
+             * Deflate (1-9, default 6) or zstd (1-22, default 9) compression level.
              */
             level?: number
             /**
@@ -10010,10 +10130,22 @@ declare module Vips {
              * Level of cpu effort to reduce file size.
              */
             effort?: number
+            /**
+             * Desired target size in bytes.
+             */
+            target_size?: number
             /**
              * Allow mixed encoding (might reduce file size).
              */
             mixed?: boolean
+            /**
+             * Enable auto-adjusting of the deblocking filter.
+             */
+            smart_deblock?: boolean
+            /**
+             * Number of entropy-analysis passes (in [1..10]).
+             */
+            passes?: number
             /**
              * Which metadata to retain.
              */
@@ -10078,10 +10210,22 @@ declare module Vips {
              * Level of cpu effort to reduce file size.
              */
             effort?: number
+            /**
+             * Desired target size in bytes.
+             */
+            target_size?: number
             /**
              * Allow mixed encoding (might reduce file size).
              */
             mixed?: boolean
+            /**
+             * Enable auto-adjusting of the deblocking filter.
+             */
+            smart_deblock?: boolean
+            /**
+             * Number of entropy-analysis passes (in [1..10]).
+             */
+            passes?: number
             /**
              * Which metadata to retain.
              */
@@ -10145,10 +10289,22 @@ declare module Vips {
              * Level of cpu effort to reduce file size.
              */
             effort?: number
+            /**
+             * Desired target size in bytes.
+             */
+            target_size?: number
             /**
              * Allow mixed encoding (might reduce file size).
              */
             mixed?: boolean
+            /**
+             * Enable auto-adjusting of the deblocking filter.
+             */
+            smart_deblock?: boolean
+            /**
+             * Number of entropy-analysis passes (in [1..10]).
+             */
+            passes?: number
             /**
              * Which metadata to retain.
              */
@@ -10213,10 +10369,22 @@ declare module Vips {
              * Level of cpu effort to reduce file size.
              */
             effort?: number
+            /**
+             * Desired target size in bytes.
+             */
+            target_size?: number
             /**
              * Allow mixed encoding (might reduce file size).
              */
             mixed?: boolean
+            /**
+             * Enable auto-adjusting of the deblocking filter.
+             */
+            smart_deblock?: boolean
+            /**
+             * Number of entropy-analysis passes (in [1..10]).
+             */
+            passes?: number
             /**
              * Which metadata to retain.
              */