[Xmlgraphics-batik Wiki] Update of "PdfTranscoder" by JeremiasMaerki

[Apache Wiki <wi...@apache.org>]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Xmlgraphics-batik Wiki" for change notification.

The following page has been changed by JeremiasMaerki:
http://wiki.apache.org/xmlgraphics-batik/PdfTranscoder

The comment on the change is:
Documentation on PDF Transcoder

New page:
The PDF Transcoder was developed in the [http://xml.apache.org/fop Apache FOP] project and also uses several FOP classes and dependencies. The PDF Transcoder, along with the EPS Transcoder, is provided in the pdf-transcoder.jar found in the Batik distribution.

== Important Note ==

The PDF and EPS Transcoders will be moved from FOP to Batik in the next few weeks. Until then they are a little out of place not very well documented. The source code for these two Transcoders can be found in the Apache FOP project: http://xmlgraphics.apache.org/repo.html

== Basic usage ==

You can use the same pattern as document here: http://xml.apache.org/batik/rasterizerTutorial.html

The fully qualified class name for the PDF Transcoder is: '''org.apache.fop.svg.PDFTranscoder'''

=== Supported Transcoding Hints ===

 * ImageTranscoder.KEY_BACKGROUND_COLOR (Content: java.awt.Color)

    See Batik documentation.

 * ImageTranscoder.KEY_PIXEL_UNIT_TO_MILLIMETER (Content: java.lang.Float)

    Controls the resolution of the bitmaps that are used inside the PDF. The default is (25.4 / 96) = 0.26458333 (96dpi).

== Notes on text painting ==

There used to be an additional hint, AbstractFOPTranscoder.KEY_STROKE_TEXT (Content: java.lang.Boolean), but this hint has been disabled. It was used to force painting text as shapes.

The PDF Transcoder today uses PDF operations whenever possible to paint text. Only for cases like special effects or transformations Batik will convert the text into shapes. Text output as shapes will negatively affect performance and will result in a bigger PDF. There's currently no work-around other than investing some time in improving text output in the PDF Transcoder. Help is welcome.

== Notes on fonts ==

The PDF transcoder uses FOP's font subsystem to handle fonts. This is in contrast to the fonts which are normally used by Batik (they are provided by AWT). If you would like to use custom fonts the process is similar to the one used to add custom fonts to FOP. Please see FOP's documentation for details: http://xml.apache.org/fop/fonts.html

The PDF Transcoder differs from normal FOP in the way the custom fonts are configured. Instead of a userconfig.xml file, you will need to build an [http://excalibur.apache.org Avalon Framework] Configuration object. This is demonstrated on a separate page: http://wiki.apache.org/xmlgraphics-fop/SvgNotes/PdfTranscoderTrueTypeEmbedding

== Known issues ==

There are a number of smaller issues in the PDF Transcoder. Generally, it is not as far advanced as, for example, the ImageTranscoder (JPEG, PNG etc.) in Batik.

''TODO: List known issues''

== Notes on the EPS Transcoder ==

The EPS Transcoder came from the need to support SVG output for the PostScript Renderer in FOP. As the PDF Transcoder, the EPS Transcoder was developed inside the FOP project. This Transcoder is less advanced than the PDF Transcoder. Things like transparency and patterns are not implemented. The usage of the EPS Trancoder (including the Transcoding Hints) is the same as for the PDF Transcoder. The fully qualified class name is: '''org.apache.fop.render.ps.EPSTranscoder'''