[api-minor] Replace the useOnlyCssZoom option with maxCanvasPixels = 0 instead (PR 16729 follow-up)

Given that the `useOnlyCssZoom` option is essentially just a special-case of the `maxCanvasPixels` functionality, we can combine the two options in order to simplify the overall implementation.
Note that the `useOnlyCssZoom` functionality was only ever used, by default, in the PDF Viewer for the B2G/FirefoxOS project (which was abandoned years ago).

examples/mobile-viewer/viewer.js

@@ -20,7 +20,7 @@ if (!pdfjsLib.getDocument || !pdfjsViewer.PDFViewer) {
   alert("Please build the pdfjs-dist library using\n `gulp dist-install`");
 }
 
-const USE_ONLY_CSS_ZOOM = true;
+const MAX_CANVAS_PIXELS = 0; // CSS-only zooming.
 const TEXT_LAYER_MODE = 0; // DISABLE
 const MAX_IMAGE_SIZE = 1024 * 1024;
 const CMAP_URL = "../../node_modules/pdfjs-dist/cmaps/";
@@ -363,7 +363,7 @@ const PDFViewerApplication = {
       eventBus,
       linkService,
       l10n: this.l10n,
-      useOnlyCssZoom: USE_ONLY_CSS_ZOOM,
+      maxCanvasPixels: MAX_CANVAS_PIXELS,
       textLayerMode: TEXT_LAYER_MODE,
     });
     this.pdfViewer = pdfViewer;

web/app.js

@@ -522,7 +522,6 @@ const PDFViewerApplication = {
       annotationEditorMode,
       imageResourcesPath: AppOptions.get("imageResourcesPath"),
       enablePrintAutoRotate: AppOptions.get("enablePrintAutoRotate"),
-      useOnlyCssZoom: AppOptions.get("useOnlyCssZoom"),
       isOffscreenCanvasSupported,
       maxCanvasPixels: AppOptions.get("maxCanvasPixels"),
       enablePermissions: AppOptions.get("enablePermissions"),

web/app_options.js

@@ -189,11 +189,6 @@ const defaultOptions = {
     value: 1,
     kind: OptionKind.VIEWER + OptionKind.PREFERENCE,
   },
-  useOnlyCssZoom: {
-    /** @type {boolean} */
-    value: false,
-    kind: OptionKind.VIEWER,
-  },
   viewerCssTheme: {
     /** @type {number} */
     value: typeof PDFJSDev !== "undefined" && PDFJSDev.test("CHROME") ? 2 : 0,

web/pdf_page_view.js

@@ -71,13 +71,11 @@ import { XfaLayerBuilder } from "./xfa_layer_builder.js";
  *   The default value is `AnnotationMode.ENABLE_FORMS`.
  * @property {string} [imageResourcesPath] - Path for image resources, mainly
  *   for annotation icons. Include trailing slash.
- * @property {boolean} [useOnlyCssZoom] - Enables CSS only zooming. The default
- *   value is `false`.
  * @property {boolean} [isOffscreenCanvasSupported] - Allows to use an
  *   OffscreenCanvas if needed.
  * @property {number} [maxCanvasPixels] - The maximum supported canvas size in
- *   total pixels, i.e. width * height. Use -1 for no limit. The default value
+ *   total pixels, i.e. width * height. Use `-1` for no limit, or `0` for
- *   is 4096 * 4096 (16 mega-pixels).
+ *   CSS-only zooming. The default value is 4096 * 4096 (16 mega-pixels).
  * @property {Object} [pageColors] - Overwrites background and foreground colors
  *   with user defined ones in order to improve readability in high contrast
  *   mode.
@@ -112,6 +110,8 @@ const DEFAULT_LAYER_PROPERTIES = () => {
 class PDFPageView {
   #annotationMode = AnnotationMode.ENABLE_FORMS;
 
+  #hasRestrictedScaling = false;
+
   #layerProperties = null;
 
   #loadingId = null;
@@ -151,15 +151,13 @@ class PDFPageView {
     this.pdfPageRotate = defaultViewport.rotation;
     this._optionalContentConfigPromise =
       options.optionalContentConfigPromise || null;
-    this.hasRestrictedScaling = false;
     this.#textLayerMode = options.textLayerMode ?? TextLayerMode.ENABLE;
     this.#annotationMode =
       options.annotationMode ?? AnnotationMode.ENABLE_FORMS;
     this.imageResourcesPath = options.imageResourcesPath || "";
-    this.useOnlyCssZoom = options.useOnlyCssZoom || false;
     this.isOffscreenCanvasSupported =
       options.isOffscreenCanvasSupported ?? true;
-    this.maxCanvasPixels = options.maxCanvasPixels || MAX_CANVAS_PIXELS;
+    this.maxCanvasPixels = options.maxCanvasPixels ?? MAX_CANVAS_PIXELS;
     this.pageColors = options.pageColors || null;
 
     this.eventBus = options.eventBus;
@@ -171,6 +169,13 @@ class PDFPageView {
     if (typeof PDFJSDev === "undefined" || PDFJSDev.test("GENERIC")) {
       this._isStandalone = !this.renderingQueue?.hasViewer();
       this._container = container;
+
+      if (options.useOnlyCssZoom) {
+        console.error(
+          "useOnlyCssZoom was removed, please use `maxCanvasPixels = 0` instead."
+        );
+        this.maxCanvasPixels = 0;
+      }
     }
 
     this._annotationCanvasMap = null;
@@ -586,23 +591,25 @@ class PDFPageView {
       this._container?.style.setProperty("--scale-factor", this.viewport.scale);
     }
 
-    let isScalingRestricted = false;
+    if (this.canvas) {
-    if (this.canvas && this.maxCanvasPixels > 0) {
+      let onlyCssZoom = false;
+      if (this.#hasRestrictedScaling) {
+        if (
+          (typeof PDFJSDev === "undefined" || PDFJSDev.test("GENERIC")) &&
+          this.maxCanvasPixels === 0
+        ) {
+          onlyCssZoom = true;
+        } else if (this.maxCanvasPixels > 0) {
           const { width, height } = this.viewport;
           const { sx, sy } = this.outputScale;
-      if (
+          onlyCssZoom =
             ((Math.floor(width) * sx) | 0) * ((Math.floor(height) * sy) | 0) >
-        this.maxCanvasPixels
+            this.maxCanvasPixels;
-      ) {
-        isScalingRestricted = true;
         }
       }
-    const onlyCssZoom =
-      this.useOnlyCssZoom || (this.hasRestrictedScaling && isScalingRestricted);
       const postponeDrawing =
         !onlyCssZoom && drawingDelay >= 0 && drawingDelay < 1000;
 
-    if (this.canvas) {
       if (postponeDrawing || onlyCssZoom) {
         if (
           postponeDrawing &&
@@ -921,25 +928,25 @@ class PDFPageView {
     const ctx = canvas.getContext("2d", { alpha: false });
     const outputScale = (this.outputScale = new OutputScale());
 
-    if (this.useOnlyCssZoom) {
+    if (
-      const actualSizeViewport = viewport.clone({
+      (typeof PDFJSDev === "undefined" || PDFJSDev.test("GENERIC")) &&
-        scale: PixelsPerInch.PDF_TO_CSS_UNITS,
+      this.maxCanvasPixels === 0
-      });
+    ) {
+      const invScale = 1 / this.scale;
       // Use a scale that makes the canvas have the originally intended size
       // of the page.
-      outputScale.sx *= actualSizeViewport.width / width;
+      outputScale.sx *= invScale;
-      outputScale.sy *= actualSizeViewport.height / height;
+      outputScale.sy *= invScale;
-    }
+      this.#hasRestrictedScaling = true;
-
+    } else if (this.maxCanvasPixels > 0) {
-    if (this.maxCanvasPixels > 0) {
       const pixelsInViewport = width * height;
       const maxScale = Math.sqrt(this.maxCanvasPixels / pixelsInViewport);
       if (outputScale.sx > maxScale || outputScale.sy > maxScale) {
         outputScale.sx = maxScale;
         outputScale.sy = maxScale;
-        this.hasRestrictedScaling = true;
+        this.#hasRestrictedScaling = true;
       } else {
-        this.hasRestrictedScaling = false;
+        this.#hasRestrictedScaling = false;
       }
     }
     const sfx = approximateFraction(outputScale.sx);

web/pdf_viewer.js

@@ -108,13 +108,11 @@ function isValidAnnotationEditorMode(mode) {
  *   mainly for annotation icons. Include trailing slash.
  * @property {boolean} [enablePrintAutoRotate] - Enables automatic rotation of
  *   landscape pages upon printing. The default is `false`.
- * @property {boolean} [useOnlyCssZoom] - Enables CSS only zooming. The default
- *   value is `false`.
  * @property {boolean} [isOffscreenCanvasSupported] - Allows to use an
  *   OffscreenCanvas if needed.
  * @property {number} [maxCanvasPixels] - The maximum supported canvas size in
- *   total pixels, i.e. width * height. Use -1 for no limit. The default value
+ *   total pixels, i.e. width * height. Use `-1` for no limit, or `0` for
- *   is 4096 * 4096 (16 mega-pixels).
+ *   CSS-only zooming. The default value is 4096 * 4096 (16 mega-pixels).
  * @property {IL10n} [l10n] - Localization service.
  * @property {boolean} [enablePermissions] - Enables PDF document permissions,
  *   when they exist. The default value is `false`.
@@ -274,8 +272,14 @@ class PDFViewer {
     this.enablePrintAutoRotate = options.enablePrintAutoRotate || false;
     if (typeof PDFJSDev === "undefined" || PDFJSDev.test("GENERIC")) {
       this.removePageBorders = options.removePageBorders || false;
+
+      if (options.useOnlyCssZoom) {
+        console.error(
+          "useOnlyCssZoom was removed, please use `maxCanvasPixels = 0` instead."
+        );
+        options.maxCanvasPixels = 0;
+      }
     }
-    this.useOnlyCssZoom = options.useOnlyCssZoom || false;
     this.isOffscreenCanvasSupported =
       options.isOffscreenCanvasSupported ?? true;
     this.maxCanvasPixels = options.maxCanvasPixels;
@@ -894,7 +898,6 @@ class PDFViewer {
             textLayerMode,
             annotationMode,
             imageResourcesPath: this.imageResourcesPath,
-            useOnlyCssZoom: this.useOnlyCssZoom,
             isOffscreenCanvasSupported: this.isOffscreenCanvasSupported,
             maxCanvasPixels: this.maxCanvasPixels,
             pageColors: this.pageColors,