Vgr_pdf
Vg PDF renderer.
Renders a sequence of renderables as a multi-page PDF 1.7 document. Each renderable defines a page of the document.
Bug reports. PDF being an insane standard, rendering abilities of PDF readers vary wildly. No rendering bug report for this renderer will be considered if it cannot be reproduced in the latest Adobe Acrobat Reader.
v0.9.4 - homepage
Font resolution happens during the rendering of Vg.I.cut_glyphs
images through the font
callback given to the PDF rendering target
. See Text rendering for more details.
val otf_font : string -> ([> `Otf of otf_font ], Otfm.error) result
otf_font bytes
is an OpenType font from the OpenType byte serialization bytes
.
The type for font resolution results. Any case different from `Otf
ends up using the PDF standard fonts. See Text rendering for details.
font
is the default font resolver. Given a Vg.font
f
it performs the following resolutions according to value of f.Font.name
:
"Helvetica"
, returns `Sans
"Times"
, returns `Serif
"Courier"
, returns `Fixed
`Sans
See Text rendering for understanding what this entails.
val target : ?font:(Vg.font -> font) -> ?xmp:string -> unit -> Vg.Vgr.dst_stored Vg.Vgr.target
target font xmp ()
is a PDF render target for rendering to the stored destination given to Vg.Vgr.create
.
font
is the font resolver, defaults to font
, see Text rendering for details. Note that font
results are cached by the renderer.xmp
is an optional UTF-8 encoded XML XMP metadata packet describing the PDF document (see ISO 16684-1 or the equivalent Adobe spec.). The convenience function Vg.Vgr.xmp
can be used to generate a packet.Multiple image. Multiple image render is supported. Each image defines a page of the resulting PDF file.
Text rendering depends on the way fonts are resolved by the function specified in the rendering target
. Given a glyph cut:
Vg.I.cut_glyphs
~text ~blocks ~advances font glyphs
First, if the optional text
and blocks
arguments are specified, they are always used to map the rendered glyphs to text for PDF text extraction. Then the following happens according to the resolution of the font
argument by the render target:
`Otf otf
, the values in glyphs
are glyph indexes of the OpenType font otf
. If advances
is specified these vectors are used to position the glyphs (e.g. you need to use this to perform kerning), otherwise the font's glyph advances, as found in otf
, are used.`Helvetica
, uses one of the standard PDF font Helvetica, Helvetica-Bold, Helvetica, Helvetica-Bold, Helvetica-Oblique, Helvetica-BoldOblique according to font
's Vg.Font.slant
and Vg.Font.weight
. The values in glyphs
are glyph indexes representing the corresponding Unicode character (e.g. glyph index 0x20
is the glyph for character U+0020
). The font supports glyph indexes for all the characters listed in the in the second column of this document which is all the Basic Latin block, the Latin-1 Supplement block without its control characters and some additional characters (those at rows 0x80-0x9F in that document). If a glyph index is not supported it is replaced by 0
. If advances
is specified these vectors are used to position the glyphs, otherwise the internal font's glyphs advances are used.`Times
, same as `Helvetica
but uses one of the standard PDF font Times-Roman, Times-Bold, Times-Italic or Times-BoldItalic.`Courier
, same as `Helvetica
but uses one of the standard PDF font Courier, Courier-Bold, Courier-Oblique, Courier-BoldOblique.`Sans
is the same as `Helvetica
except advances
and glyphs
are ignored. Instead the UTF-8 string text
is used to generate a corresponding glyphs
list, mapping supported characters as mentioned above to their corresponding glyph. Unsupported characters are mapped to glyph 0.`Serif
same as `Sans
but uses the same fonts as `Times
.`Fixed
same as `Sans
but uses the same fonts as `Courier
.So what should be used ? In general clients should use a font resolution mechanism independent from Vg
in order to get an OpenType font otf
for font
. Using this otf
font is should compute, using again a mechanism independent from Vg
, a glyph layout resulting in advances
and glyphs
to use with Vg.I.cut_glyphs
and finally resolve font
in the target with `Otf otf
. This means that font resolution should:
`Otf otf
whenever it is guaranteed that the glyph indexes in glyphs
actually correspond to the glyph indexes of otf
.`Sans
, `Serif
or `Fixed
whenever its is unable to resolve font
to an appropriate otf
, this may not result in the expected rendering but still at least show (the latin) part of the text.`Helvetica
, `Times
or `Courier
to perform glyph layout using PDF's standard fonts without having to embed the fonts in the PDF (the font metrics can be downloaded here). PDFs without embedded fonts are however not recommended.The following render warnings are reported.
`Unsupported_cut (`O o, i)
, outline area cuts can be performed only on (possibly transformed) Vg.I.const
, Vg.I.axial
, Vg.I.radial
images.`Unsupported_glyph_cut (`O o, i)
, outline area glyph cuts can be performed only on (possibly transformed) Vg.I.const
, Vg.I.axial
, Vg.I.radial
images.The following limitations should be taken into account:
Streams in the PDF files are currently uncompressed and fonts are embedded without subsetting which may result in large file sizes. This will be lifted in future versions of the library. Meanwhile if you need to reduce the size of generated PDFs you can pass them through cpdf or ghostscript.
> cpdf -compress -o output.pdf input.pdf > gs -dNOPAUSE -dBATCH -sDEVICE=pdfwrite -sOutputFile=output.pdf input.pdf