[Bug]: gradients are not rendered correctly with OffscreenCanvas

[nikitar]

Attach (recommended) or Link to PDF file

gradient repo.pdf

Web browser and its version

Chrome 134.0.6998.166

Operating system and its version

Macos 15.3.2

PDF.js version

5.1.91

Is the bug present in the latest PDF.js version?

Yes

Is a browser extension

No

Steps to reproduce the problem

1. Use OffscreenCanvas for rendering, for example through the CanvasFactory option on getDocument.

class OffscreenCanvasFactory {
    create(width: number, height: number): CanvasAndContext {
        const canvas = new OffscreenCanvas(width, height);
        const context = canvas.getContext('2d');
        assertNotNullish(context, 'Unable to create 2d canvas context');
        return { canvas, context };
    }

    reset(canvasAndContext: CanvasAndContext, width: number, height: number) {
        assertNotNullish(canvasAndContext.canvas, 'Canvas is not specified');
        canvasAndContext.canvas.width = width;
        canvasAndContext.canvas.height = height;
    }

    destroy(canvasAndContext: CanvasAndContext) {
        assertNotNullish(canvasAndContext.canvas, 'Canvas is not specified');
        canvasAndContext.canvas.width = 0;
        canvasAndContext.canvas.height = 0;
        canvasAndContext.canvas = null;
        canvasAndContext.context = null;
    }
}


    const loadingTask = getDocument({
        url: url,
        worker: pdfWorker,
        withCredentials: true,
        cMapUrl: `/pdfjs/cmaps/`,
        cMapPacked: true,
        isEvalSupported: false,
        CanvasFactory: OffscreenCanvasFactory,
    })

2. Either create a PDFViewer instance that uses this loading task, or use page.render api:

        const viewport = page.getViewport({ scale: PDF_TO_CSS_UNITS, offsetX: -left, offsetY: -top });
        // @ts-expect-error pdf.canvasFactory is an Object
        const canvasAndContext = this.pdf.canvasFactory.create(width, height);
        const renderTask = page.render({
            canvasContext: canvasAndContext.context,
            viewport,
            annotationMode: AnnotationMode.ENABLE,
        });
        await renderTask.promise;

        const blob = await canvasAndContext.canvas.convertToBlob({ type: 'image/png' });
        console.log(URL.createObjectURL(blob));

What is the expected behavior?

Pdf is displayed correctly:

What went wrong?

Gradients seem to either be discarded, or go from 0 to 100 in an instant:

Applies equally to PDFViewer and page.render output.

Link to a viewer

No response

Additional context

Aware that OffscreenCanvas is not the main focus for pdfjs, but there are several tickets that indicate it is supported, including for use entirely in a web worker (e.g. #10319).

Open to contributing a fix, if the issue is fixable, though would appreciate some pointers.

[nikitar]

I tried using Proxy on canvas & context, to see what's going on, but proxies seem to break them.

[Snuffleupagus]

Aware that OffscreenCanvas is not the main focus for pdfjs, but there are several tickets that indicate it is supported, including for use entirely in a web worker (e.g. #10319).

Sorry, but we currently do not officially support using OffscreenCanvas for general rendering.

Steps to reproduce the problem

1. Use OffscreenCanvas for rendering, for example through the `CanvasFactory` option on `getDocument`.

The code looks like TypeScript, rather than JavaScript, and it also cannot be run directly.
Please see https://github.com/mozilla/pdf.js/blob/master/.github/CONTRIBUTING.md (emphasis mine):

If you are developing a custom solution, first check the examples at https://github.com/mozilla/pdf.js#learning and search existing issues. If this does not help, please prepare a short well-documented example that demonstrates the problem and make it accessible online on your website, JS Bin, GitHub, etc. before opening a new issue or contacting us in the Matrix room -- keep in mind that just code snippets won't help us troubleshoot the problem.

[nikitar]

Combined everything into a single test module, which can be run as window.open(await runImageTest(documentUrl, 1, 800, 500));. Or as console.log(await runImageTest(pdfUrl, 1, 800, 500));, if your popup blocker is unhappy.

I think everything is the standard usage, except for the OffscreenCanvasFactory.

import {
    AnnotationMode,
    PDFWorker,
    getDocument,
} from 'pdfjs-dist/legacy/build/pdf.mjs';

class OffscreenCanvasFactory {
    create(width, height) {
        const canvas = new OffscreenCanvas(width, height);
        const context = canvas.getContext('2d');
        return { canvas, context };
    }

    reset(canvasAndContext, width, height) {
        canvasAndContext.canvas.width = width;
        canvasAndContext.canvas.height = height;
    }

    destroy(canvasAndContext) {
        canvasAndContext.canvas.width = 0;
        canvasAndContext.canvas.height = 0;
        canvasAndContext.canvas = null;
        canvasAndContext.context = null;
    }
}

// For vite, may work differently in another bundler
const worker = new Worker(new URL('pdfjs-dist/legacy/build/pdf.worker.mjs', import.meta.url), {
    type: 'module',
});

const pdfWorker = PDFWorker.fromPort({ name: 'testWorker', port: worker });

export const runImageTest = async (url, pageNumber, width, height) => {
    const loadingTask = getDocument({
        url: url,
        worker: pdfWorker,
        withCredentials: true,
        cMapUrl: `/pdfjs/cmaps/`,
        cMapPacked: true,
        isEvalSupported: false,
        CanvasFactory: OffscreenCanvasFactory,                          // <------ the important part
    });
    const pdf = await loadingTask.promise;

    const page = await pdf.getPage(pageNumber);
    const viewport = page.getViewport({ scale: 1 });
    const canvasAndContext = pdf.canvasFactory.create(width, height);
    const renderTask = page.render({
        canvasContext: canvasAndContext.context,
        viewport,
        annotationMode: AnnotationMode.ENABLE,
    });
    await renderTask.promise;

    const blob = await canvasAndContext.canvas.convertToBlob({ type: 'image/png' });
    return URL.createObjectURL(blob);
}

[nikitar]

Is OffscreenCanvas support anticipated and/or desirable? It already mostly works and I'm open to contributing bug fixes for whatever remains. Though I don't know a ton about pdf.js internals & structure.

[nikitar]

I'm also curious if the issue also affects the "image conversion/rendering" part below. It may refer to images embedded in the document, not page-rendering.

pdf.js/src/display/api.js

Lines 163 to 165 in 220a289

	* @property {boolean} [isOffscreenCanvasSupported] - Determines if we can use
	* `OffscreenCanvas` in the worker. Primarily used to improve performance of
	* image conversion/rendering.