diff options
Diffstat (limited to 'src/documentation/content/xdocs/1.0/graphics.xml')
| -rw-r--r-- | src/documentation/content/xdocs/1.0/graphics.xml | 590 |
1 files changed, 590 insertions, 0 deletions
diff --git a/src/documentation/content/xdocs/1.0/graphics.xml b/src/documentation/content/xdocs/1.0/graphics.xml new file mode 100644 index 000000000..270d6b49b --- /dev/null +++ b/src/documentation/content/xdocs/1.0/graphics.xml @@ -0,0 +1,590 @@ +<?xml version="1.0" standalone="no"?> +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<!-- $Id$ --> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd"> +<document> + <header> + <title>Apache FOP: Graphics Formats</title> + <version>$Revision$</version> + </header> + <body> + <section id="introduction"> + <title>Introduction</title> + <p> + Some noteworthy features of the image handling subsystem are: + </p> + <ul> + <li> + The image libraries Jimi and JAI are not supported. Instead, Apache FOP uses the + Image I/O API that was introduced with Java 1.4 for all bitmap codecs. + </li> + <li> + Some bitmap images are not converted to a standardized 24 bit RGB image but are + instead handled in their native format. + </li> + <li> + A plug-in mechanism offers a possibility to add support for new formats without changing + the FOP's source code. + </li> + </ul> + <p> + The actual <a href="http://xmlgraphics.apache.org/commons/image-loader.html">image loading framework</a> + does not reside in Apache FOP, but in + <a href="ext:xmlgraphics.apache.org/commons/">XML Graphics Commons</a>. + </p> + </section> + <section id="support-overview"> + <title>Overview of Graphics Support</title> + <p> + The table below summarizes the <em>theoretical</em> support for graphical formats + within FOP. In other words, within the constraints of the limitations listed here, + these formats <em>should</em> work. However, many of them have not been tested, + and there may be limitations that have not yet been discovered or documented. + The packages needed to support some formats are not included in the FOP distribution + and must be installed separately. Follow the links in the "Support Through" columns + for more details. + </p> + <table> + <tr> + <th rowspan="2">Format</th> + <th rowspan="2">Type</th> + <th colspan="3">Support Through</th> + </tr> + <tr> + <th><a href="#native">Apache FOP (native)</a></th> + <th><a href="#batik">Apache Batik</a></th> + <th><a href="#imageio">Image I/O</a></th> + </tr> + <tr> + <td><a href="#bmp">BMP</a> (Microsoft Windows Bitmap)</td> + <td>bitmap</td> + <td></td> + <td></td> + <td>X [1]</td> + </tr> + <tr> + <td><a href="#emf">EMF</a> (Windows Enhanced Metafile)</td> + <td>vector (with embedded bitmaps)</td> + <td>(X)</td> + <td></td> + <td></td> + </tr> + <tr> + <td><a href="#eps">EPS</a> (Encapsulated PostScript)</td> + <td>metafile (both bitmap and vector), most frequently used for vector drawings</td> + <td>(X)</td> + <td></td> + <td></td> + </tr> + <tr> + <td>GIF (Graphics Interchange Format)</td> + <td>bitmap</td> + <td></td> + <td></td> + <td>X</td> + </tr> + <tr> + <td><a href="#jpeg">JPEG</a> (Joint Photographic Experts Group)</td> + <td>bitmap</td> + <td>(X)</td> + <td></td> + <td>X</td> + </tr> + <tr> + <td><a href="#png">PNG</a> (Portable Network Graphic)</td> + <td>bitmap</td> + <td></td> + <td></td> + <td>X</td> + </tr> + <tr> + <td><a href="#svg">SVG</a> (Scalable Vector Graphics)</td> + <td>vector (with embedded bitmaps)</td> + <td></td> + <td>X</td> + <td></td> + </tr> + <tr> + <td><a href="#tiff">TIFF</a> (Tag Image Format File)</td> + <td>bitmap</td> + <td>(X)</td> + <td></td> + <td>X [1]</td> + </tr> + <tr> + <td><a href="#wmf">WMF</a> (Windows Metafile)</td> + <td>vector (with embedded bitmaps)</td> + <td></td> + <td>(X)</td> + <td></td> + </tr> + </table> + <p> + Legend: + </p> + <ul> + <li>"(X)" means restricted support. Please see the details below.</li> + <li> + [1]: Requires the presence of <a href="http://jai-imageio.dev.java.net/">JAI Image I/O Tools</a> + (or an equivalent Image I/O compatible codec) in the classpath. JAI Image I/O Tools also + adds support for JPEG 2000, WBMP, RAW and PNM. Other Image I/O codecs may provide + support for additional formats. + </li> + </ul> + <note> + <a href="http://jai-imageio.dev.java.net/">JAI Image I/O Tools</a> is not the same as the + <a href="http://java.sun.com/javase/technologies/desktop/media/jai/">JAI library</a>! The + former simply exposes JAI's codecs using the Image I/O API but does not include all + the image manipulation functionality. + </note> + <section id="format-map"> + <title>Map of supported image formats by output format</title> + <p> + Not all image formats are supported for all output formats! For example, while you can + use EPS (Encapsulated PostScript) files when you generate PostScript output, this format + will not be supported by any other output format. Here's an overview of which image + formats are supported by which output format: + </p> + <table> + <tr> + <th>Image Format</th> + <th>PDF</th> + <th>PostScript</th> + <th>Java2D, PNG, TIFF, AWT</th> + <th>PCL</th> + <th>AFP</th> + <th>RTF</th> + </tr> + <tr> + <td><a href="#bmp">BMP</a> (Microsoft Windows Bitmap)</td> + <td>X</td> + <td>X</td> + <td>X</td> + <td>X</td> + <td>X</td> + <td>X</td> + </tr> + <tr> + <td><a href="#emf">EMF</a> (Windows Enhanced Metafile)</td> + <td></td> + <td></td> + <td></td> + <td></td> + <td></td> + <td>X [1]</td> + </tr> + <tr> + <td><a href="#eps">EPS</a> (Encapsulated PostScript)</td> + <td></td> + <td>X [1]</td> + <td></td> + <td></td> + <td></td> + <td></td> + </tr> + <tr> + <td>GIF (Graphics Interchange Format)</td> + <td>X</td> + <td>X</td> + <td>X</td> + <td>X</td> + <td>X</td> + <td>X</td> + </tr> + <tr> + <td><a href="#jpeg">JPEG</a> (Joint Photographic Experts Group)</td> + <td>X [1]</td> + <td>X [1]</td> + <td>X</td> + <td>X</td> + <td>X [1]</td> + <td>X</td> + </tr> + <tr> + <td><a href="#png">PNG</a> (Portable Network Graphic)</td> + <td>X</td> + <td>X</td> + <td>X</td> + <td>X</td> + <td>X</td> + <td>X</td> + </tr> + <tr> + <td><a href="#svg">SVG</a> (Scalable Vector Graphics)</td> + <td>X</td> + <td>X</td> + <td>X</td> + <td>X</td> + <td>X</td> + <td>X</td> + </tr> + <tr> + <td><a href="#tiff">TIFF</a> (Tag Image Format File)</td> + <td>X [2]</td> + <td>X [2]</td> + <td>X</td> + <td>X</td> + <td>X [2]</td> + <td>X</td> + </tr> + <tr> + <td><a href="#wmf">WMF</a> (Windows Metafile)</td> + <td>X</td> + <td>X</td> + <td>X</td> + <td>X</td> + <td>X</td> + <td>X</td> + </tr> + </table> + <p> + Legend: + </p> + <ul> + <li> + [1]: Supported without the need to decode the image. + </li> + <li> + [2]: Supported without the need to decode the image, but only for certain subtypes. + </li> + </ul> + </section> + </section> + <section id="packages"> + <title>Graphics Packages</title> + <section id="native"> + <title>XML Graphics Commons Native</title> + <p> + <a href="ext:xmlgraphics.apache.org/commons">XML Graphics Commons</a> supports a number + of graphic file formats natively as basic functionality: all bitmap formats for which + there are Image I/O codecs available (JPEG, PNG, GIF, TIFF, etc.), EPS and EMF. + </p> + </section> + <section id="fop-native"> + <title>FOP Native</title> + <p> + FOP has no native image plug-ins for the image loading framework of its own but currently + hosts the Batik-dependent SVG and WMF plug-ins until they can be moved to + <a href="ext:xmlgraphics.apache.org/batik">Apache Batik</a>. + </p> + </section> + <section id="batik"> + <title>Apache Batik</title> + <p> + <a href="ext:xmlgraphics.apache.org/batik">Apache Batik</a> will later receive the + SVG and WMF plug-ins for the image loading framework that are currently hosted inside + FOP. + </p> + <p> + Current FOP distributions include a distribution of the + <a class="fork" href="ext:xmlgraphics.apache.org/batik">Apache Batik</a>. + Because Batik's API changes frequently, it is highly recommended that you use the + version that ships with FOP, at least when running FOP. + </p> + <warning>Batik must be run in a graphical environment.</warning> + <p> + Batik must be run in a graphical environment. + It uses AWT classes for rendering SVG, which in turn require an X server on Unixish + systems. If you run a server without X, or if you can't connect to the X server due to + security restrictions or policies (a so-called "headless" environment), SVG rendering + will fail. + </p> + <p>Here are some workarounds:</p> + <ul> + <li> + Start Java with the <code>-Djava.awt.headless=true</code> command line option. + </li> + <li> + Install an X server which provides an in-memory framebuffer without actually using a + screen device or any display hardware. One example is Xvfb. + </li> + <li> + Install a toolkit which emulates AWT without the need for an underlying X server. One + example is the <a href="http://www.eteks.com/pja/en">PJA toolkit</a>, which is free + and comes with detailed installation instructions. + </li> + </ul> + </section> + <section id="imageio"> + <title>Image I/O</title> + <p> + The image loading framework in <a href="ext:xmlgraphics.apache.org/commons">XML Graphics Commons</a> + provides a wrapper to load images through the + <a class="fork" href="http://java.sun.com/j2se/1.4.2/docs/guide/imageio/index.html">JDK's Image I/O API</a> (JSR 015). + Image I/O allows to dynamically add additional image codecs. An example of such an + add-on library are the + <a class="fork" href="http://java.sun.com/products/java-media/jai/">JAI Image I/O Tools</a> + available from Sun. + </p> + </section> + </section> + <section id="image-formats"> + <title>Details on image formats</title> + <section id="bmp"> + <title>BMP</title> + <p> + BMP images are supported through an Image I/O codec. There may be limitations of the + codec which are outside the control of Apache FOP. + </p> + </section> + <section id="emf"> + <title>EMF</title> + <p> + Windows Enhanced Metafiles (EMF) are only supported in RTF output where they are + embedded without decoding. + </p> + </section> + <section id="eps"> + <title>EPS</title> + <p>Apache FOP allows to use EPS files when generating PostScript output only.</p> + <p> + Other output targets can't be supported at the moment because + FOP lacks a PostScript interpreter. Furthermore, FOP is currently not able + to parse the preview bitmaps sometimes contained in EPS files. + </p> + </section> + <section id="gif"> + <title>GIF</title> + <p> + GIF images are supported through an Image I/O codec. Transparency is supported but + not guaranteed to work with every output format. + </p> + </section> + <section id="jpeg"> + <title>JPEG</title> + <p> + FOP native support (i.e. the handling of undecoded images) of JPEG does not include all + variants, especially those containing unusual color lookup tables and color profiles. + If you have trouble with a JPEG image in FOP, try opening it with an image processing + program (such as Photoshop or Gimp) and then saving it. Specifying 24-bit color output + may also help. For the PDF and PostScript renderers most JPEG images can be passed + through without decompression. User reports indicate that grayscale, RGB, and + CMYK color spaces are all rendered properly. However, for other output formats, the + JPEG images have to be decompressed. Tests have shown that there are some limitation + in some Image I/O codecs concerning images in the CMYK color space. Work-arounds are + in place but may not always work as expected. + </p> + </section> + <section id="png"> + <title>PNG</title> + <p> + PNG images are supported through an Image I/O codec. Transparency is supported but + not guaranteed to work with every output format. + </p> + </section> + <section id="svg"> + <title>SVG</title> + <section id="svg-intro"> + <title>Introduction</title> + <p>FOP uses <a href="#batik"> Apache Batik</a> for SVG support. + This format can be handled as an <code>fo:instream-foreign-object</code> or in a separate + file referenced with <code>fo:external-graphic</code>.</p> + <note> + Batik's SVG Rasterizer utility may also be used to convert standalone SVG + documents into PDF. For more information please see the + <a href="http://xmlgraphics.apache.org/batik/svgrasterizer.html">SVG Rasterizer documentation</a> + on the Batik site. + </note> + </section> + <section id="svg-pdf-graphics"> + <title>Placing SVG Graphics into PDF</title> + <p> + The SVG is rendered into PDF by using PDF commands to draw and fill + lines and curves. This means that the graphical objects created with + this remain as vector graphics. The same applies to PostScript output. + For other output formats the SVG graphic may be converted to a bitmap + image. + </p> + <p> + There are a number of SVG things that cannot be converted directly into + PDF. Parts of the graphic such as effects, patterns and images are inserted + into the PDF as a raster graphic. The resolution of these raster images can + be controlled through the "target resolution" setting in the + <a href="configuration.html">configuration</a>.</p> + <p> + Currently transparency is limited in PDF so some SVG images that + contain effects or graphics with transparent areas may not be displayed + correctly. + </p> + </section> + <section id="svg-pdf-text"> + <title>Placing SVG Text into PDF and PostScript</title> + <p>If possible, Batik will use normal PDF or PostScript text when inserting text. It does + this by checking if the text can be drawn normally and the font is + supported. This example svg <a href="../dev/svg/text.svg">text.svg</a> / + <a href="../dev/svg/text.pdf">text.pdf</a> / <a href="../dev/svg/text.png">text.png</a> + shows how various types and effects with text are handled. + Note that SVG font support is not yet implemented. Furthermore, text handling in + PostScript output is inferior to PDF output - more text will be painted as shapes in + PS than in PDF. + </p> + <p> + When there's no support to paint text using native text operations, + text is converted and drawn as a set of shapes by Batik, using the + stroking text painter. This means that a typical character will + have about 10 curves (each curve consists of at least 20 characters). + This can make the output files large and when it is viewed the + viewer may not normally draw those fine curves very well (In Adobe Acrobat, turning on + "Smooth Line Art" in the preferences will fix this). Copy/paste functionality + will not be supported in this case. + If the text is inserted into the output file using the inbuilt text commands + it will use a single character. + </p> + <p> + Note that because SVG text can be rendered as either text or a vector graphic, you + may need to consider settings in your viewer for both. The Acrobat viewer has both + "smooth line art" and "smooth text" settings that may need to be set for SVG images + to be displayed nicely on your screen (see Edit / Preferences / Display). + This setting will not affect the printing of your document, which should be OK in + any case, but will only affect the quality of the screen display. + </p> + </section> + <section id="svg-font-selection"> + <title>Font selection notes</title> + <p> + Apache Batik uses the AWT/Java2D subsystem as font source while FOP has its own font + subsystem. Great care has been taken that font selection does the best possible choices. + But it must be noted when creating PDF or PostScript that a font used in SVG graphics + needs to be registered with the operating system as well as in FOP's configuration. + By using FOP's font auto-detection, you simply have to install the font in the operating + system and not care about anything else. This is less of an issue if you create + formats like TIFFs, PNGs or PCL because in these cases SVG graphics are usually rendered + to bitmaps which means that on both sides (Batik and FOP), AWT/Java2D is used as the + single font source. + </p> + <p> + Whenever an SVG is converted into a PDF or PostScript file, the font that has been used + inside Batik has to be mapped to a font used by the actual output format. Features like + font substitution in FOP may need to be taken into account but can also be an advantage + when working around font mapping issues. Like for XSL-FO content, you'll get a warning + if a particular font could not be found and had to be substituted, or if a particular + glyph is missing in a font. + </p> + </section> + <section id="svg-scaling"> + <title>Scaling</title> + <p> + Currently, SVG images are rendered with the dimensions specified <em>in the SVG + file</em>, within the viewport specified in the fo:external-graphic element. + For everything to work properly, the two should be equal. The SVG standard leaves + this issue as an implementation detail. Additional scaling options are available + through XSL-FO means. + </p> + <p> + If you use pixels to specify the size of an SVG graphic the "source resolution" setting + in the <a href="configuration.html">configuration</a> will be used to determine the + size of a pixel. The use of pixels to specify sizes is discouraged as they may + be interpreted differently in different environments. + </p> + </section> + <section id="svg-problems"> + <title>Known Problems</title> + <ul> + <li> + Soft mask transparency is combined with white so that it looks better + on PDF 1.3 viewers but this causes the soft mask to be slightly lighter + or darker on PDF 1.4 viewers. + </li> + <li> + There is some problem with a gradient inside a pattern which may cause a PDF + error when viewed in Acrobat 5. + </li> + <li> + Text is not always handled correctly, it may select the wrong font + especially if characters have multiple fonts in the font list. + </li> + <li> + Uniform transparency for images and other SVG elements that are converted + into a raster graphic are not drawn properly in PDF. The image is opaque. + </li> + </ul> + </section> + </section> + <section id="tiff"> + <title>TIFF</title> + <p> + FOP can embed TIFF images without decompression into PDF, PostScript and AFP if they + have either CCITT T.4, CCITT T.6, or JPEG compression. Otherwise, a TIFF-capable + Image I/O codec is necessary for decoding the image. + </p> + <p> + There may be some limitation concerning images in the CMYK color space. + </p> + </section> + <section id="wmf"> + <title>WMF</title> + <p> + Windows Metafiles (WMF) are supported through classes in + <a href="ext:xmlgraphics.apache.org/batik">Apache Batik</a>. At the moment, support + for this format is experimental and may not always work as expected. + </p> + </section> + </section> + <section id="resolution"> + <title>Graphics Resolution</title> + <p> + Some bitmapped image file formats store a dots-per-inch (dpi) or other resolution + values. FOP tries to use this resolution information whenever possible to determine + the image's intrinsic size. This size is used during the layout process when it is not + superseded by an explicit size on fo:external-graphic (content-width and content-height + properties). + </p> + <p> + Please note that not all images contain resolution information. If it's not available + the source resolution set on the FopFactory (or through the user configuration XML) is used. + The default here is 72 dpi. + </p> + <p> + Bitmap images are generally embedded into the output format at their original resolution + (as is). No resampling of the image is performed. Explicit resampling is on our wishlist, + but hasn't been implemented, yet. Bitmaps included in SVG graphics may be resampled to + the resolution specified in the "target resolution" setting in the + <a href="configuration.html">configuration</a> if SVG filters are applied. This can be + used as a work-around to resample images in FO documents. + </p> + </section> + <section id="page-selection"> + <title>Page selection for multi-page formats</title> + <p> + Some image formats such as TIFF support multiple pages/sub-images per file. You can + select a particular page using a special URI fragment in the form: + <uri>#page=<nr> + (for example: <code>http://localhost/images/myimage.tiff#page=3</code>) + </p> + </section> + <section id="caching"> + <title>Image caching</title> + <p> + FOP caches images between runs. There is one cache per FopFactory instance. The URI is + used as a key to identify images which means that when a particular URI appears again, + the image is taken from the cache. If you have a servlet that generates a different + image each time it is called with the same URI you need to use a constantly + changing dummy parameter on the URI to avoid caching. + </p> + <p> + The image cache has been improved considerably in the redesigned code. Therefore, + resetting the image cache should be a thing of the past. If you + still experience OutOfMemoryErrors, please notify us. + </p> + <p> + If all else fails, the image cache can be cleared like this: + <code>fopFactory.getImageManager().getCache().clearCache();</code> + </p> + </section> + </body> +</document> |