@vue-pdf-viewer/viewer/dist/types/utils/scaleUtils.d.ts

A vue-pdf-viewer component for Vue and Nuxt. Suitable for vue-pdf document.

/**
 * Scale utilities for CSS round() based dimension calculations
 * Based on pdf.js implementation for pixel-perfect layer alignment
 */
/**
 * Detect iOS devices (following pdf.js pattern)
 * Used for platform-specific canvas memory limits and optimizations
 */
export declare const isIOS: boolean;
/**
 * Detect Safari browser (following pdf.js pattern from app_options.js)
 * Safari has stricter canvas memory limits than other browsers
 */
export declare const isSafari: boolean;
/**
 * Maximum canvas pixels for different browsers (following pdf.js pattern)
 * Safari: 16,777,216 pixels (~16 megapixels) - to stay within ~128MB per-canvas limit
 * Others: 33,554,432 pixels (2^25, ~32 megapixels)
 *
 * Note: iOS Safari uses even lower limits (5.2M) via platform-specific checks
 */
export declare const maxCanvasPixels: number;
/**
 * Maximum canvas dimension (width or height) - following pdf.js app_options.js default
 * This is the browser canvas size limit (32767 on most browsers)
 * Corresponds to pdf.js maxCanvasDim option
 */
export declare const MAX_CANVAS_DIM = 32767;
/**
 * Maximum canvas area (4096×4096) - used for initial scale calculation
 * This is a conservative limit to prevent memory issues during setup
 */
export declare const MAX_CANVAS_SIZE: number;
/**
 * Approximate a float scale value as a fraction using Farey sequence.
 * This ensures CSS and canvas dimensions round to the same pixel boundaries.
 *
 * @param x - The scale value to approximate
 * @returns [numerator, denominator] array
 */
export declare function approximateFraction(x: number): [number, number];
/**
 * Canvas area factor for viewport-based capping (following pdf.js default)
 * Limits canvas to viewportArea × factor pixels
 * Default: 200 (allows ~14x zoom on small viewports, since √200 ≈ 14.14)
 */
export declare const DEFAULT_CAP_CANVAS_AREA_FACTOR = 200;
/**
 * Calculate effective max pixels based on viewport size and area factor.
 * Following pdf.js OutputScale.capPixels() pattern.
 *
 * This function prevents over-allocation of canvas memory for small viewports
 * by capping maxCanvasPixels based on the viewport area. For example, a tiny
 * 400×300 viewport would be capped at 24M pixels instead of the default 33.5M.
 *
 * @param viewportWidth - Viewport width in CSS pixels
 * @param viewportHeight - Viewport height in CSS pixels
 * @param maxPixels - Static maximum canvas pixels limit
 * @param capAreaFactor - Multiplier for viewport area (default: 200, ≤0 = disabled)
 * @returns Effective maximum canvas pixels (minimum of static limit and capped limit)
 *
 * @example
 * // Small viewport: 400×300 = 120,000 px²
 * capPixels(400, 300, 33554432, 200)
 * // Returns: min(33554432, 120000 × 200) = 24,000,000 pixels
 *
 * @example
 * // Large viewport: 1920×1080 = 2,073,600 px²
 * capPixels(1920, 1080, 33554432, 200)
 * // Returns: min(33554432, 414720000) = 33,554,432 pixels (static limit wins)
 */
export declare function capPixels(viewportWidth: number, viewportHeight: number, maxPixels: number, capAreaFactor?: number): number;
/**
 * Browser-specific precision rounding.
 * Firefox uses f32 precision for CSS calc, so we need to match it.
 */
export declare const calcRound: (x: number) => number;
/**
 * Floor a value to the nearest multiple of divisor.
 * Used for canvas dimension calculations.
 *
 * @param value - The value to floor
 * @param divisor - The divisor to floor to
 * @returns Floored value
 */
export declare function floorToDivide(value: number, divisor: number): number;
/**
 * Check if the browser supports CSS round() function.
 * Falls back to calc() if not supported.
 */
export declare function isCSSRoundSupported(): boolean;
/**
 * Generate CSS dimension string using round() or calc() based on browser support.
 *
 * @param baseVar - The base CSS variable name (e.g., '--page-width')
 * @param scaleVar - The scale CSS variable name (e.g., '--scale-factor')
 * @param roundVar - The rounding CSS variable name (e.g., '--scale-round-x')
 * @returns CSS calc/round string
 */
export declare function generateDimensionCSS(baseVar: string, scaleVar?: string, roundVar?: string | null): string;
/**
 * Calculate scale rounding values for CSS variables.
 *
 * @param scale - The current scale value
 * @returns Object with scaleRoundX and scaleRoundY in pixels
 */
export declare function calculateScaleRound(scale: number): {
    scaleRoundX: string;
    scaleRoundY: string;
};
/**
 * Calculate safe output scale considering all canvas constraints.
 * Following pdf.js OutputScale.limitCanvas() pattern from display_utils.js
 *
 * This function applies four types of constraints:
 * 1. Viewport-based area capping (viewportArea × capAreaFactor, pdf.js pattern)
 * 2. Total pixel area (width × height ≤ effectiveMaxPixels)
 * 3. Maximum width dimension (width ≤ maxDim)
 * 4. Maximum height dimension (height ≤ maxDim)
 *
 * Takes the most restrictive constraint and scales down if needed.
 *
 * @param width - Canvas width at scale 1
 * @param height - Canvas height at scale 1
 * @param requestedScale - Desired output scale (typically devicePixelRatio)
 * @param viewportWidth - Viewport width for area capping (default: width)
 * @param viewportHeight - Viewport height for area capping (default: height)
 * @param maxPixels - Maximum total canvas pixels (platform-specific, default from maxCanvasPixels)
 * @param maxDim - Maximum canvas dimension for width or height (default 32767)
 * @param capAreaFactor - Viewport area multiplier for capping (default: 200, ≤0 = disabled)
 * @returns Object with scale, needsRestriction flag, and reason for restriction
 *
 * @example
 * // Normal case: 800×600 page at 2x scale
 * limitCanvasScale(800, 600, 2.0)
 * // Returns: { scale: 2.0, needsRestriction: false }
 *
 * @example
 * // Wide page: 40000×1000 page at 1x scale
 * limitCanvasScale(40000, 1000, 1.0)
 * // Returns: { scale: 0.819, needsRestriction: true, reason: 'width' }
 * // Actual canvas: 32767×819 pixels
 *
 * @example
 * // Small viewport: 400×300 viewport with area capping
 * limitCanvasScale(800, 600, 2.0, 400, 300)
 * // Viewport area: 120,000 → capped limit: 24M pixels
 * // Returns: { scale: 1.414, needsRestriction: true, reason: 'area-capped' }
 */
export declare function limitCanvasScale(width: number, height: number, requestedScale: number, viewportWidth?: number, viewportHeight?: number, maxPixels?: number, maxDim?: number, capAreaFactor?: number): {
    scale: number;
    needsRestriction: boolean;
    reason?: 'area' | 'area-capped' | 'width' | 'height';
};