CD_PDF - PDF Driver (cdpdf.h)

This drivers allows generating a PDF file. This format developed for representing documents in a manner that is independent of the original application software, hardware, and operating system used to create those documents. The format's copyrights are property of Adobe Systems.

This driver is very similar to the PS driver but it uses the PDFlib library to generate the PDF (http://www.pdflib.com/). There were two PDFlib licenses available, one commercial and one free with a flexible license, see PDFlib Lite License. The CD_PDF driver works with both versions of PDFlib version 7.

By default the pre-compiled library in the distribution uses the PDF Lite version code. The configuration of the PDF Lite code included does not supports image file formats. The current PDF Lite version is 7.0.5 from GitHub: https://github.com/Distrotech/PDFlib-Lite.

PDFlib Copyright (c) 1997-2010 Thomas Merz and PDFlib GmbH. All rights reserved. Applications that use this driver are subject to the PDFlib GmbH License Agreement.

But notice that "PDFlib GmbH no longer offers open-source versions of PDFlib. PDFlib Lite is no longer supported and neither source code nor precompiled binaries are available for download."

IMPORTANT: The PDFLib Lite is NOT free! PDFlib Lite can freely be used for non-profit personal use. Commercial applications can NOT use PDFLib Lite. Commercial applications can only use the regular PDFLib, and it is only available under the terms of a commercial license, and always require a license fee.

An alternative is to use the CD_CAIRO_PDF driver, which is free.

Use

The file is created and opened by calling function cdCreateCanvas(CD_PDF, Data), in which Data contains the filename and canvas dimensions. This function opens the file and writes its header. Then, other functions in the CD library can be called as usual. The Data parameter string has the following format:

"filename -p[paper] -w[width_mm] -h[height_mm] -s[resolution_dpi] [-o]"
or in C
"%s -p%d -w%g -h%g -s%d -o"

The filename must be inside double quotes (") if it has spaces. Any amount of such canvases may exist simultaneously. It is important to note that a call to function cdKillCanvas is required to close the file properly.

To use this driver, the application must be linked with the "cdpdf" and "pdflib" libraries.

In Lua, it is necessary to call function cdluapdf_open() after a call to function cdlua_open(), apart from linking with the "cdluapdf" library. This is not necessary if you do require"cdluapdf".

Paper Size - The default paper size is A4. It is possible to change it by using one of the predefined sizes - CD_A0, CD_A1, CD_A2, CD_A3, CD_A4, CD_A5, CD_LETTER and CD_LEGAL - with parameter "-p". It is also possible to define a paper in a particular size by using parameters "-w" e "-h". Values are provided in millimeters.

Resolution - Resolution is used to convert values from millimeters to pixels (the same as points, but the number of points is per inch - DPI). Use parameter "-s" to configure the resolution. The default value is 300 DPI.

Orientation - The page can be oriented as portrait or landscape. The default value is portrait, but when the parameter "-o" is used, the horizontal and vertical values are switched.

Behavior of Functions

Control

• Play: does nothing, returns CD_ERROR.
• Flush: changes to a new page, preserving the previous one.
• Clear: does nothing.

Coordinate System & Clipping

• UpdateYAxis: does nothing.
• Complex Regions: not supported.

Attributes

• WriteMode: does nothing, returns CD_REPLACE.
• Font: the old "System" font is mapped to the "Courier" font. For the PDF core fonts styles are added to the font name, for other fonts styles are simulated by PDFlib. Underline and Strikeout are supported. Following is the core fonts:

Courier, Courier-Bold, Courier-Oblique, Courier-BoldOblique,
Helvetica, Helvetica-Bold, Helvetica-Oblique, Helvetica-BoldOblique,
Times-Roman, Times-Bold, Times-Italic, Times-BoldItalic,
Symbol, 
ZapfDingbats

Colors

• GetColorPlanes: returns 24.
• Palette: does nothing.

Client Images

• GetImageRGB: does nothing.
• PutImageMap: stores an RGB image.

Primitives

• Pixel: does not exist in PDF, is simulated using a circle with radius=1.
• Floating point primitives are supported.
• Filled primitives do not include the line at the edges of the filled area.
• When constructing a PATH the CD_PATH_ARC can add only a circular arc. The largest dimension will be used.

Server Images

• All functions do nothing.

Exclusive Attributes

• "POLYHOLE": defines the index of the vertex where there is a hole in a closed polygon. It will affect the next cdEnd. Can be called several times between cdBegin and cdEnd to define holes. The value passed must be a string containing an integer ("%d"). If the value of the attribute passed is NULL, all holes will no longer be considered. When consulted returns the current number of holes ("%d"). It can have a maximum of 500 holes. Default: NULL.

• "HATCHBOXSIZE": defines the size of smallest hatch box pattern. This affects the spacing between the hatch lines. The value passed must be a string containing an integer ("%d"). If the value of the attribute passed is NULL, the value is rest to the default. When consulted returns the current value ("%d"). Default: "8".

• "ROTATE":  allows the usage of 1 angle and 1 coordinate (x, y), that define a global rotation transformation centered in the specified coordinate. Use 1 real and 2 integer values inside a string ("%g %d %d" = angle x y). Can not be set if a transformation is already set.

• "OPACITY":  allows the usage of a global opacity value. The value passed must be a string containing an integer ("%d") [0=full transparent, 255=full opaque]. Use NULL to reset to the default. Default: 255.

• "PATTERN":  creates a pattern with regular primitives (except images). The value passed must be a string containing two integeres with the pattern size ("%dx%d") [widthxheight]. Just call regular primitives. Use NULL to end the pattern creation and set the interior style.

• "PDF": Returns the "PDF*" handle of the PDFLib.

• "PDFLIBVERSION": Returns the full PDFlib version string in the format <major>.<minor>.<revision>.

• "SUBJECT","TITLE","CREATOR","AUTHOR","KEYWORDS": write only attributes that allows to set a description string for the respective document information field.

• "UTF8MODE": enables the usage of the UTF-8 encoding for strings. It can have the following values: "1" or "0". Default is "0". (since 5.10)