Monkeybread Software - DynaPDF Manual

DynaPDF Manual - Page 671

Function Reference

Page 671 of 860

already rendered. The update event is fired when either the UpdateOnPathCount limit was reached

or when more than 100.000 vertices were rendered, whatever occurs first. This makes sure that the

window becomes updated from time to time when very large but few paths were rendered.

UpdateOnImageCoverage limit

The member UpdateOnImageCoverage specifies a factor that is multiplied with a master area of

1,000,000 pixels. So, when the factor is set to 1.0 then the update event is fired when 1,000,000

unscaled source pixels were processed. This calculation makes sure that small images cause not too

many update events and the coverage area doesn't depend on the size of the destination image that

is rendered. The bit depth of images is also taken into account since rendering 1 bit or gray scale

images is much faster than rendering RGB or CMYK images.

In addition to the coverage limit DynaPDF counts also the number of images which were already

rendered. The update event is fired when either the coverage limit was reached or when more than

3000 images were rendered, whatever occurs first. This makes sure that the window becomes

updated from time to time when many small images were rendered.

The image scaler cannot produce an update event during scaling at this time. The event occurs

always after an image was fully scaled. This behaviour will be changed as soon as possible…

The return value

The TOnUpdateWindow callback function can break processing if necessary. The return value must

be zero to continue processing. Negative values break processing. However, the return value must

be either 0 or -1. Other return values are not permitted and can cause unwanted side effects. The

TOnUpdateWindow callback function is not the only way to break processing. When the page is

rendered in a separate thread then use the function Abort() to break processing. See next section.

Multi-Threading strategies

PDF pages can be very large and complex; hence, it is not always possible to render pages in just a

few milliseconds. When the rendering engine is used in a viewer application then it is usually best

to render pages in a separate thread so that the main thread becomes not blocked. A good viewer

implementation must also be able to stop rendering as fast as possible whenever necessary, e.g.

when the user requests to change the view area, zoom factor, page position or other things.

To achieve this, the rendering engine provides the function Abort() (rasAbort() in C/C++). This

function works of course only if RenderPage() is executed asynchronously. The one and only stable

and reasonable way to do this is to execute the function RenderPage() in a separate thread.

The development of a stable multi-threaded viewer requires a few design considerations to avoid

unnecessary multi-threading issues. Before we can render a PDF page we must usually import a

page or create it with DynaPDF functions.

One thing that you must consider is that it is generally not allowed to import a page in a separate

thread. However, importing a PDF page is very fast and there is generally no need to do so. Future