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

DynaPDF Manual - Page 572

Previous Page 571   Index   Next Page 573

Function Reference
Page 572 of 750
The structure size is used to identify different versions of the structure. The a and d members of the
transformation matrix represent the scaling factors. If these factors are set to zero, then nothing can
be rendered! The matrix should be set to the identity matrix, unless DefScale is set to psFitZoom.
The members Flags and DefScale should be set to appropriate values too. Note that the structure
contains also many output fields. Especially the member PageSpace is sometimes important since this
matrix represents the mapping from user space to device space.
Basics
The function requires three pointers: the instance pointer of the PDF instance, a pointer of a
rasterizer object (see CreateRasterizer()), and finally a pointer of the page object that should be
rendered (returned by GetPageObject()). All three pointers must be valid and and not NULL.
Before a page can be rendered the caller must create a rasterizer with CreateRasterizer(). The
rasterizer is normally created when the application is initialized and deleted when the application is
terminated.
The size of the image buffer can be changed at runtime, e.g. when the window size must be changed,
without creating a new rasterizer. Simply attach the new buffer with AttachImageBuffer().
The pixel format cannot be changed at runtime but it is possible to use multiple rasterizers if
necessary.
The rasterizer and the rendering functions use the error log of the PDF instance to output errors and
warnings. An error that occurs during rendering does normally not affect the PDF file in memory.
This is also the case for fatal errors. The rendering engine can be seen as a separate modul that is not
allowed to interact directly with the PDF instance from which pages were rendered.
However, it is not always possible to isolate errors during rendering from the PDF instance. For
example, when a font resource must be decompressed and if an out of memory exception occurs
during decompression, then this will also cause an out of memory exception when trying to finish
the file, e.g. with CloseFile() or similar functions.
Keep in mind that the rasterizer contains a reference of the error log of the PDF instance.
Therefore, it is not allowed to delete the PDF instance whithout deleting the rasterizer. The
rasterizer should also be deleted before the PDF instance.
It is allowed to use one rasterizer with different PDF instances but note that errors will be reported
into the error log of the PDF instance that is associated with the rasterizer. To avoid multi-threading
issues it is usually best to create a separate rasterizer for each PDF instance that is used to render
PDF pages.
Pixel Formats
PDF uses a transparent imaging model, that means many objects depend on the availability of an
alpha channel. To achieve optimal results the image buffer should contain an alpha channel. If the
pixel format contains an alpha channel then DynaPDF produces an image with pre-multiplied alpha
since this is what most operating systems expect.
 

Previous topic: Minimal initialization

Next topic: Rendering PDF Pages