Xojo Developer Conference
25/27th April 2018 in Denver.
MBS Xojo Conference
6/7th September 2018 in Munich, Germany.

DynaPDF Manual - Page 577

Previous Page 576   Index   Next Page 578

Function Reference
Page 577 of 750
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
versions will also support specific flags to further improve the access time to external pages. So,
don't load PDF pages in a separate thread!

Previous topic: UpdateOnPathCount limit

Next topic: How to save the image on disk?