/**
 * Helper functions for common GIF creation tasks
 *
 * This module provides convenient, high-level functions for creating GIFs
 * without needing to work with low-level GIF writing details.
 */
import { ImageData, ImageOptions, GlobalColorTableOptions, RGBColor } from './types.js';
import { GifResult } from './gif-result.js';
/**
 * Creates a static GIF from image data using automatic color quantization.
 *
 * This is the most flexible static GIF creation function, accepting raw RGBA
 * image data and automatically quantizing colors to fit GIF's palette limitations.
 *
 * @param imageData - The source image data in RGBA format
 * @param imageData.width - Image width in pixels
 * @param imageData.height - Image height in pixels
 * @param imageData.data - RGBA pixel data as Uint8Array or Uint8ClampedArray
 * @param options - Optional configuration
 * @param options.maxColors - Maximum colors in quantized palette (default: 256)
 * @param options.globalColorTable - Global color table options
 * @param options.imageOptions - Image-specific options (position, delay, etc.)
 * @returns A GifResult with convenient output methods
 * @throws {GifValidationError} When image data is invalid
 *
 * @example
 * ```typescript
 * // Create from canvas ImageData
 * const canvas = document.createElement('canvas');
 * const ctx = canvas.getContext('2d');
 * const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);
 * const gif = createStaticGif(imageData);
 *
 * // Save or use the result
 * const dataUrl = gif.toDataURL();
 * await gif.saveToFile('output.gif');
 * ```
 *
 * @example
 * ```typescript
 * // Create with custom options
 * const gif = createStaticGif(imageData, {
 *   maxColors: 128,
 *   imageOptions: { delay: 0 }
 * });
 * ```
 */
export declare function createStaticGif(imageData: ImageData, options?: {
    maxColors?: number;
    globalColorTable?: GlobalColorTableOptions;
    imageOptions?: ImageOptions;
}): GifResult;
/**
 * Creates an animated GIF from multiple image frames.
 *
 * Processes multiple frames into a single animated GIF with consistent color
 * quantization across all frames. All frames are quantized using a unified
 * palette for optimal color consistency.
 *
 * @param frames - Array of image frames in RGBA format
 * @param options - Optional configuration
 * @param options.maxColors - Maximum colors in shared palette (default: 256)
 * @param options.delay - Delay between frames in milliseconds (default: 100)
 * @param options.loops - Number of animation loops, 0 for infinite (default: 0)
 * @param options.globalColorTable - Global color table options
 * @param options.imageOptions - Per-frame image options array
 * @returns A GifResult with convenient output methods
 * @throws {GifValidationError} When no frames provided or frames are invalid
 *
 * @example
 * ```typescript
 * const frames = [frame1, frame2, frame3]; // ImageData objects
 * const animatedGif = createAnimatedGif(frames, {
 *   delay: 200,
 *   loops: 0 // infinite loop
 * });
 * animatedGif.download('animation.gif');
 * ```
 *
 * @example
 * ```typescript
 * // Different delay for each frame
 * const gif = createAnimatedGif(frames, {
 *   imageOptions: [
 *     { delay: 100 },
 *     { delay: 200 },
 *     { delay: 150 }
 *   ]
 * });
 * ```
 */
export declare function createAnimatedGif(frames: ImageData[], options?: {
    maxColors?: number;
    delay?: number;
    loops?: number;
    globalColorTable?: GlobalColorTableOptions;
    imageOptions?: ImageOptions[];
}): GifResult;
/**
 * Creates a solid color GIF of the specified dimensions.
 *
 * This is the simplest way to create a GIF filled with a single color.
 * Perfect for backgrounds, placeholders, or testing.
 *
 * @param width - Image width in pixels (1-65535)
 * @param height - Image height in pixels (1-65535)
 * @param color - RGB color values
 * @param color.red - Red component (0-255)
 * @param color.green - Green component (0-255)
 * @param color.blue - Blue component (0-255)
 * @returns A GifResult with convenient output methods
 * @throws {GifValidationError} When dimensions or color values are invalid
 *
 * @example
 * ```typescript
 * // Create a red 100x100 square
 * const redSquare = createSolidColorGif(100, 100, {
 *   red: 255,
 *   green: 0,
 *   blue: 0
 * });
 *
 * // Use the GIF
 * document.body.innerHTML = `<img src="${redSquare.toDataURL()}">`;
 * ```
 *
 * @example
 * ```typescript
 * // Create a blue background
 * const background = createSolidColorGif(800, 600, {
 *   red: 70,
 *   green: 130,
 *   blue: 180 // Steel blue
 * });
 * ```
 */
export declare function createSolidColorGif(width: number, height: number, color: RGBColor): GifResult;
/**
 * Creates a checkerboard pattern GIF with alternating colors.
 *
 * Generates a classic checkerboard pattern with customizable colors and
 * check size. Useful for backgrounds, patterns, or testing.
 *
 * @param width - Image width in pixels
 * @param height - Image height in pixels
 * @param color1 - First alternating color (RGB)
 * @param color2 - Second alternating color (RGB)
 * @param checkSize - Size of each check square in pixels (default: 10)
 * @returns A GifResult with convenient output methods
 * @throws {GifValidationError} When dimensions or colors are invalid
 *
 * @example
 * ```typescript
 * // Classic black and white checkerboard
 * const checkerboard = createCheckerboardGif(
 *   200, 200,
 *   { red: 0, green: 0, blue: 0 },     // Black
 *   { red: 255, green: 255, blue: 255 }, // White
 *   20 // 20px squares
 * );
 * ```
 *
 * @example
 * ```typescript
 * // Colorful small checkerboard
 * const colorCheck = createCheckerboardGif(
 *   300, 200,
 *   { red: 255, green: 100, blue: 100 }, // Light red
 *   { red: 100, green: 100, blue: 255 }, // Light blue
 *   5 // Small 5px checks
 * );
 * ```
 */
export declare function createCheckerboardGif(width: number, height: number, color1: RGBColor, color2: RGBColor, checkSize?: number): GifResult;
/**
 * Converts an HTML Canvas element to ImageData format.
 *
 * Extracts pixel data from a canvas element in the format needed for GIF creation.
 * This is a convenient bridge between Canvas API and GIF generation.
 *
 * @param canvas - HTML Canvas element to convert
 * @returns ImageData object with width, height, and RGBA pixel data
 * @throws {GifValidationError} When canvas context cannot be obtained
 *
 * @example
 * ```typescript
 * // Draw on canvas and convert to GIF
 * const canvas = document.createElement('canvas');
 * canvas.width = 200;
 * canvas.height = 100;
 * const ctx = canvas.getContext('2d');
 *
 * // Draw something
 * ctx.fillStyle = 'blue';
 * ctx.fillRect(0, 0, 200, 100);
 * ctx.fillStyle = 'red';
 * ctx.fillRect(50, 25, 100, 50);
 *
 * // Convert to GIF
 * const imageData = canvasToImageData(canvas);
 * const gif = createStaticGif(imageData);
 * ```
 */
export declare function canvasToImageData(canvas: HTMLCanvasElement): ImageData;
/**
 * Creates ImageData from raw RGBA pixel data.
 *
 * Constructs an ImageData object from raw pixel data, with validation
 * to ensure data length matches dimensions.
 *
 * @param width - Image width in pixels
 * @param height - Image height in pixels
 * @param data - RGBA pixel data (4 bytes per pixel)
 * @returns ImageData object ready for GIF creation
 * @throws {GifValidationError} When data length doesn't match dimensions
 *
 * @example
 * ```typescript
 * // Create a simple 2x2 image
 * const width = 2, height = 2;
 * const data = new Uint8Array([
 *   255, 0, 0, 255,   // Red pixel
 *   0, 255, 0, 255,   // Green pixel
 *   0, 0, 255, 255,   // Blue pixel
 *   255, 255, 0, 255  // Yellow pixel
 * ]);
 *
 * const imageData = createImageData(width, height, data);
 * const gif = createStaticGif(imageData);
 * ```
 */
export declare function createImageData(width: number, height: number, data: Uint8Array | Uint8ClampedArray): ImageData;
/**
 * Creates a gradient GIF with smooth color transition.
 *
 * Generates a linear gradient between two colors in the specified direction.
 * Perfect for backgrounds, UI elements, or artistic effects.
 *
 * @param width - Image width in pixels
 * @param height - Image height in pixels
 * @param startColor - Starting gradient color (RGB)
 * @param endColor - Ending gradient color (RGB)
 * @param direction - Gradient direction (default: 'horizontal')
 * @returns A GifResult with convenient output methods
 *
 * @example
 * ```typescript
 * // Horizontal red to blue gradient
 * const gradient = createGradientGif(
 *   300, 100,
 *   { red: 255, green: 0, blue: 0 },   // Red
 *   { red: 0, green: 0, blue: 255 },   // Blue
 *   'horizontal'
 * );
 * ```
 *
 * @example
 * ```typescript
 * // Vertical sunset gradient
 * const sunset = createGradientGif(
 *   200, 300,
 *   { red: 255, green: 94, blue: 77 },  // Coral
 *   { red: 255, green: 154, blue: 0 },  // Orange
 *   'vertical'
 * );
 * ```
 */
export declare function createGradientGif(width: number, height: number, startColor: RGBColor, endColor: RGBColor, direction?: 'horizontal' | 'vertical' | 'diagonal'): GifResult;
/**
 * Creates an animated gradient GIF with dynamic effects.
 *
 * Generates an animated gradient with various animation types including
 * shifting, rotating colors, pulsing, and wave effects. Perfect for
 * dynamic backgrounds and eye-catching animations.
 *
 * @param width - Image width in pixels
 * @param height - Image height in pixels
 * @param startColor - Starting gradient color (RGB)
 * @param endColor - Ending gradient color (RGB)
 * @param options - Animation configuration
 * @param options.direction - Gradient direction (default: 'horizontal')
 * @param options.animationType - Type of animation (default: 'shift')
 * @param options.frames - Number of animation frames (default: 20)
 * @param options.delay - Delay between frames in ms (default: 100)
 * @param options.loops - Animation loops, 0 for infinite (default: 0)
 * @param options.intensity - Animation strength 0-1 (default: 1.0)
 * @param options.maxColors - Maximum colors in palette (default: 256)
 * @returns A GifResult with convenient output methods
 *
 * @example
 * ```typescript
 * // Shifting gradient animation
 * const shiftingGradient = createAnimatedGradientGif(
 *   200, 100,
 *   { red: 255, green: 0, blue: 0 },
 *   { red: 0, green: 0, blue: 255 },
 *   {
 *     animationType: 'shift',
 *     frames: 30,
 *     delay: 80
 *   }
 * );
 * ```
 *
 * @example
 * ```typescript
 * // Pulsing gradient with custom intensity
 * const pulsingGradient = createAnimatedGradientGif(
 *   150, 150,
 *   { red: 0, green: 255, blue: 0 },
 *   { red: 255, green: 0, blue: 255 },
 *   {
 *     direction: 'diagonal',
 *     animationType: 'pulse',
 *     intensity: 0.7,
 *     frames: 25
 *   }
 * );
 * ```
 *
 * @example
 * ```typescript
 * // Wave effect gradient
 * const waveGradient = createAnimatedGradientGif(
 *   300, 200,
 *   { red: 255, green: 255, blue: 0 },
 *   { red: 0, green: 255, blue: 255 },
 *   {
 *     animationType: 'wave',
 *     direction: 'vertical',
 *     frames: 40,
 *     delay: 60
 *   }
 * );
 * ```
 */
export declare function createAnimatedGradientGif(width: number, height: number, startColor: RGBColor, endColor: RGBColor, options?: {
    direction?: 'horizontal' | 'vertical' | 'diagonal';
    animationType?: 'shift' | 'rotate' | 'pulse' | 'wave';
    frames?: number;
    delay?: number;
    loops?: number;
    intensity?: number;
    maxColors?: number;
}): GifResult;