imagescript 3.2.0 → 3.3.0

package/dist/image.d.ts

@@ -26,6 +26,15 @@ export interface CompositeOptions {
 export interface ResizeOptions {
     /** The resizing mode. Default: {@link Image.RESIZE_BILINEAR} */
     mode?: ResizeMode;
+    /**
+     * Whether to round to 8 bits between the two passes, so two channels share the multiplications of both: about
+     * 15-25% faster for opaque images, with 10-25% of the channel values a step off the precise result (instead of
+     * about 1%, never more than 1). Transparent images are premultiplied to 8 bits like browsers do, which makes them
+     * about twice as fast: what shows once they're composited differs by up to about 2 steps, pixels that are almost
+     * transparent keep less of their color. Only affects {@link Image.RESIZE_BILINEAR} and {@link Image.RESIZE_AREA},
+     * down to about a third of the size. Default: `true`
+     */
+    fast?: boolean;
 }
 /**
  * Options of {@link Image.opacity}, {@link Image.red}, {@link Image.green}, {@link Image.blue}, {@link Image.lightness}
@@ -92,6 +101,12 @@ export interface TextOptions extends TextStyle {
 export interface DecodeOptions {
     /** Whether to rotate/mirror JPEGs, TIFFs, PNGs and WebPs as their orientation tag (Exif or XMP) says. Default: `true` */
     applyOrientation?: boolean;
+    /**
+     * The most pixels to decode: larger images throw a RangeError before anything that size is allocated, so small
+     * files declaring huge images (decompression bombs) can't exhaust the memory. Default: `268402689` (16383², like
+     * sharp), `Infinity` for no limit
+     */
+    maxPixels?: number;
 }
 /** Text style options of {@link Image.renderText} */
 export interface TextStyle {
@@ -126,6 +141,13 @@ export interface DominantColorOptions {
 export interface RotateOptions {
     /** Whether to resize the image so it fits all pixels or just ignore outlying pixels. Default: `true` */
     resize?: boolean;
+    /**
+     * Whether to sample with 8-bit weights on 8-bit premultiplied pixels (like {@link ResizeOptions.fast}), about twice
+     * as fast: opaque pixels stay within a step of the precise result, what shows of translucent ones (also the
+     * faded edges) within about 2.5 steps (pixels that are almost transparent keep less of their color). Only affects
+     * angles that aren't multiples of 90°. Default: `true`
+     */
+    fast?: boolean;
 }
 /** Options of {@link Image.trim} */
 export interface TrimOptions {
@@ -165,9 +187,7 @@ export declare class Image {
     get bitmap(): Uint8ClampedArray;
     /** Replaces the pixel data, the array has to hold width * height * 4 bytes */
     set bitmap(bitmap: Uint8ClampedArray | Uint8Array);
-    /**
-     * @private
-     */
+    /** A short description for debugging, e.g. `Image<64x64>` */
     toString(): string;
     /**
      * The images width
@@ -669,7 +689,16 @@ export declare class Image {
      * Encodes the image into a PNG, an alias of {@link Image.encode}
      */
     encodePNG(options?: PNGEncodeOptions): Promise<Uint8Array>;
+    /**
+     * Encodes the image into a PNG, an alias of {@link Image.encode}
+     * @param compression The compression level (0-9). Default: `1`
+     * @param metadata Metadata to include, see {@link Metadata}
+     */
     encodePNG(compression?: number, metadata?: Metadata): Promise<Uint8Array>;
+    /**
+     * Encodes the image into a PNG, an alias of {@link Image.encode}
+     * @param metadata Metadata to include, see {@link Metadata}
+     */
     encodePNG(metadata?: Metadata): Promise<Uint8Array>;
     /**
      * Encodes the image into a JPEG
@@ -731,17 +760,23 @@ export declare class Image {
     static renderSVG(svg: string | BinaryData, size?: number, mode?: SVGScaleMode): Promise<Image>;
     /**
      * Creates a new image containing the rendered text.
-     * @param font TrueType (ttf/ttc) or OpenType (otf) font buffer to use
+     * @param font TrueType (ttf/ttc) or OpenType (otf) font buffer to use, or several by priority: every character
+     *     comes from the first font that has it (e.g. `[text, emoji]`), the first one sets the line height. Color
+     *     glyphs (COLR layers and paints, CBDT and sbix bitmaps, as in emoji fonts) keep their colors. Text in any script
+     *     is shaped like browsers do (right to left and bidirectional text, Arabic joining, Indic conjuncts, marks)
      * @param size Font size in pixels (per em)
      * @param text Text to render
      * @param options Color, layout and style, see {@link TextOptions}; the image grows by the outline width on every
      *     side
      * @return The rendered text
      */
-    static renderText(font: BinaryData, size: number, text: string, options?: TextOptions): Promise<Image>;
+    static renderText(font: BinaryData | BinaryData[], size: number, text: string, options?: TextOptions): Promise<Image>;
     /**
      * Creates a new image containing the rendered text.
-     * @param font TrueType (ttf/ttc) or OpenType (otf) font buffer to use
+     * @param font TrueType (ttf/ttc) or OpenType (otf) font buffer to use, or several by priority: every character
+     *     comes from the first font that has it (e.g. `[text, emoji]`), the first one sets the line height. Color
+     *     glyphs (COLR layers and paints, CBDT and sbix bitmaps, as in emoji fonts) keep their colors. Text in any script
+     *     is shaped like browsers do (right to left and bidirectional text, Arabic joining, Indic conjuncts, marks)
      * @param size Font size in pixels (per em)
      * @param text Text to render
      * @param [color=0xffffffff] Text color to use
@@ -749,5 +784,5 @@ export declare class Image {
      * @param style Outline, see {@link TextStyle}; the image grows by the outline width on every side
      * @return The rendered text
      */
-    static renderText(font: BinaryData, size: number, text: string, color?: Color, layout?: TextLayout, style?: TextStyle): Promise<Image>;
+    static renderText(font: BinaryData | BinaryData[], size: number, text: string, color?: Color, layout?: TextLayout, style?: TextStyle): Promise<Image>;
 }