[whatwg] Proposal: HTMLCanvasElement.printCallback API

[Elliott Sprehn]

1) I feel like this should probably be an event. I don't know why we're
inventing new callback facilities everywhere.

canvas.onprintcanvas = function(e) { e.printState ... }

2) What does "send the canvas' content without rasterization to the
printer" mean? How are blending and overlapping images handled? Your
current description makes it sound like if I did two drawImage() calls it
would make my printer print the images on top of each other.

3) If we're advocating that developers "put a canvas on every page that
covers the whole page" as the standard way to handle large document
printing why not have a handler that gets given a canvas for every page
automatically instead of requiring the developer to insert it themselves.
This seems much easier, and handles the memory management for since we can
drop the backing buffer between events for each page.

document.onprintpage = function(e) {
  e.index // number of the page
  e.range // range that encompasses all the nodes to print
  e.canvas // canvas to send drawing commands to for printing
};

4) SVG is for vector graphics, not canvas. Why can't I replace an entire
page with an <svg> instead of drawing to a canvas? :)

- E


On Wed, Jan 23, 2013 at 3:11 PM, Julian Viereck <
julian.viereck at googlemail.com> wrote:

> Discussing the proposal with Robert "roc" O'Callahan, we came up with the
> following adjustments. They are targeting the "Some more details on the
> behavior of the API" from before:
>
> (1) With the previous proposal, printCallbacks are executed even after the
> window is unloaded. We think this is not a good idea. There shouldn't be
> any JavaScript execution after a window is unloaded. Therefore let's add
> the following:
>
>     Encourage the UA to prevent closing the window while print callbacks
> are pending. If the window is nevertheless closed and while some
> printCallbacks have not completed yet, all printCallbacks are canceled, the
> JavaScript execution is stopped and the print job is aborted. Canceling the
> printCallbacks is done to prevent any JavaScript execution after the window
> is unloaded.
>
>
> (2) Given the change in (1), we can now change the following point:
>
>  * the "canvas" property on the printContext points to the canvas on the
>> page and not the canvas element that is printed. Otherwise it's possible to
>> change the layout of the printing while printing. As the canvas on the page
>> might not be available anymore (e.g. the canvas was removed and garbage
>> collected from the document before the printCallback gets invoked), the
>> "canvas" property might be "undefined" or "null".
>>
>
> to:
>
> * the "canvas" property on the printContext points to the canvas on the
> page and not the canvas element that is printed. Otherwise it's possible to
> change the layout of the printing while printing.
>
> Simply saying, if the window object is always alive while the
> printCallbacks are happening (thanks to (1)), the "canvas" property on the
> printContext can always point to the canvas on the page.
>
> Best regards,
>
> Julian
>
> On 9/26/12 2:46 PM, Julian Viereck wrote:
>
>> Hello WHATWG members,
>>
>> This email is about proposing a new attribute "printCallback" on the
>> HTMLCanvasElement (in the following called "Canvas"). This new API allows
>> to:
>>
>> * define the content of a canvas element during the printing progress
>> * send the canvas' content without rasterization to the printer
>>
>> The basic API was implemented in [1] and is available in Firefox Nightly
>> 18.
>>
>> ## Motivation And Use-Case
>>
>> The motivation for designing and implementing the API was to add proper
>> printing support for the PDF.JS project. The PDF.JS project is an
>> implementation of aPDF viewer using only web technologies. Without this API
>> it is not possible to:
>>
>> * render only the pages needed for printing. A webpage is printed with
>> the content visible at the moment the print action is started. For PDF.JS
>> this means that all pages are required to be rendered before printing.
>> Rendering all the pages takes quite some time for complex and huge
>> documents (> 100 pages). But the user might only want to print the first
>> page. That means, the user waits for unnecessary computation to finish.
>> * print the content of a canvas element without rasterization artifacts
>> on the printout. One could increase the size of the canvas such that the
>> rasterization doesn't becomes visible, but this is not possible due to the
>> large usage of memory going with this. Using a different way to render the
>> pages than using canvas (e.g. SVG) is not possible, due to memory and
>> performance issues.
>>
>> Although not directly relevant to PDF.JS - it's also not possible to
>>
>> * define the content of a printed page that looks exactly the same cross
>> all user agents. There are small variations, that cause breaks and styles
>> to look slightly different between user agents. Using CSS it's possible to
>> make one canvas element take up one physical page and then precisely layout
>> contenton the canvas.
>>
>> (I will later describe briefly how the API was used to solve these
>> issues.)
>>
>> ## Actual API
>>
>> The actual API looks like this:
>>
>> The "printCallback" attribute on a Canvas takes a callback. This callback
>> is invoked when the canvas with a printCallback is printed. A "printState"
>> object is passed as argument to the callback. The printState object has a
>> "context" property, which points to a CanvasRenderingContext2D object.
>> Against this context all known operations of the CanvasRenderingContext2D
>> are executable. However, the CanvasRenderingContext2D doesn't rasterize the
>> operations but instead forward them directly to the printer - instead of
>> drawing to a pixel surface it's more like drawing to a vector surface. The
>> result of the operations show up on the canvas when printed, but are not
>> visible on the screen. The "printState.done()" function  must be called
>> once all drawing operations for the canvas are done andthe printing should
>> progress.This was added to allow the printCallback to perform asynchronous
>> tasks.
>>
>> A simple example of the API looks like this:
>>
>> ```
>> var canvas = document.getElementById('**canvas');
>> var ctx = canvas.getContext('2d');
>> ctx.fillText('Hi there.', 50, 50);
>>
>> canvas.printCallback = function(printState) {
>>   var printCtx = printState.context;
>>   printCtx.fillText('I\'m only visible when printed.', 50, 50);
>>   printState.done();
>> };
>> ```
>>
>> You can try this example out in [2] using Firefox Nighlty and see the
>> results as a PDF in [3]. Notice that you can select the text in the PDF
>> linked in [3]. (Note: in the linked example [2], the callback is called
>> "mozPrintCallback" as the API is currently prefixed in Gecko. The canvas
>> output is rasterized on Windows and Linux due to a bug in Gecko at the
>> moment.)
>>
>> Some more details on the behavior of the API:
>>
>> * the printCallback function is only invoked on the canvases that will be
>> visible in the print output.
>> * there is only one printCallback called at the time. After the
>> "printState.done()" function is called, the next printCallback function
>> gets invoked assuming there is another canvas that gets printed and has a
>> printCallback specified.
>> * the order the printCallbacks of the canvases are called follows the
>> output order of the canvases in the printout.
>> * the resolution on the printContext is the same as when drawing to the
>> canvas on the page. E.g. if a canvas has the attribute "width" set to "100"
>> and by using CSS the canvas takes 10 cm in width on the printout, then 1
>> unit on the context corresponds to 0.1 cm.
>> * the putImageData and getImageData functions on the
>> CanvasRenderingContext2D use the same pixel resolution (width/height) as
>> the canvas on the page (this results in the data of the getImageData
>> function to be rasterized).
>> * the "canvas" property on the printContext points to the canvas on the
>> page and not the canvas element that is printed. Otherwise it's possible to
>> change the layout of the printing while printing. As the canvas on the page
>> might not be available anymore (e.g. the canvas was removed and garbage
>> collected from the document before the printCallback gets invoked), the
>> "canvas" property might be "undefined" or "null".
>> * the window.onafterprint event is called either
>>   1. after all printCallbacks are done and the page is ready for printing
>>   2. the printing got aborted using the print dialog.
>> * the printContext holds no content when passed to the callback and takes
>> the default values (for transformation matrix, styles etc.) of a
>> CanvasRenderingContext2D
>> * the printContext is a CanvasRenderingContext2D but instead of using a
>> pixel map to store the drawing operations result, the operations are
>> forwarded to the printer without rasterization.
>> * the API does not change the layout of the canvas element on the page.
>>
>> ## Open Discussion:
>>
>> * There is no way to abort in case something goes wrong. E.g. printing to
>> the canvas might require a successful network request, but the request
>> failed.
>> * The printState.done() function gets eventually never called and
>> therefore printing the document might never finish.
>>
>> ## How The PrintCallback-API Solved The Problems For PDF.JS
>>
>> * using CSS all content except a single div is hidden during printing
>> * when the beforePrint event is fired it is checked if the webpage is
>> setup for printing or not. If it is not, the webpage is setup and the print
>> action is canceled. Otherwise, the printing is not prevented and happens as
>> regular
>> * the "setup webpage for printing" consists of the following steps
>> 1. for each page of the PDF document, a canvas element is created and
>> insert to the div that is visible during printing
>> 2. using CSS, the canvas inside the print-visible div take up an entire
>> page in the later printout
>> 3. for each canvas the `mozPrintCallback` is set. If the callback
>> function is called, the pdf page corresponding to the canvas is loaded and
>> drawn on the canvas. Once finished, the `printState.done()` function is
>> called
>> * after the user set the print settings in the print dialog, the webpage
>> is printed
>> * for the pages that are required for the printout, the mozPrintCallback
>> is called on the canvas for these pages
>> * after the printing finished (detected by listening to the afterPrint
>> event), the created canvases are removed again to save memory.
>>
>> Best regards and looking for feedback on this,
>>
>> Julian
>>
>> ---
>>
>> [1]: Mozilla Bug 745025 - Implement CanvasElement.**mozPrintCallback:
>> https://bugzilla.mozilla.org/**show_bug.cgi?id=745025<https://bugzilla.mozilla.org/show_bug.cgi?id=745025>
>> [2]: http://jsfiddle.net/FPNMM/2/**embedded/js%2Cresult/<http://jsfiddle.net/FPNMM/2/embedded/js%2Cresult/>
>> [3]: http://n.ethz.ch/~jviereck/**drop/mozPrintCallback_output.**pdf<http://n.ethz.ch/~jviereck/drop/mozPrintCallback_output.pdf><
>> http://n.ethz.ch/%7Ejviereck/**drop/mozPrintCallback_output.**pdf<http://n.ethz.ch/%7Ejviereck/drop/mozPrintCallback_output.pdf>
>> >
>>
>>
>