aboutsummaryrefslogtreecommitdiffstats
path: root/src/documentation/content/xdocs/trunk/graphics.xml
diff options
context:
space:
mode:
authorClay Leeds <clay@apache.org>2013-02-10 17:42:26 +0000
committerClay Leeds <clay@apache.org>2013-02-10 17:42:26 +0000
commita9ba0e20ba94e9580953e0527f4c1400b8191f5b (patch)
tree7e562761bf382466b963b6b27d649830e066b6f6 /src/documentation/content/xdocs/trunk/graphics.xml
parenta9531b0195bdc26185baddfba219a0987fe8c912 (diff)
downloadxmlgraphics-fop-a9ba0e20ba94e9580953e0527f4c1400b8191f5b.tar.gz
xmlgraphics-fop-a9ba0e20ba94e9580953e0527f4c1400b8191f5b.zip
Removing Forrest-based documentation files.
git-svn-id: https://svn.apache.org/repos/asf/xmlgraphics/fop/trunk@1444573 13f79535-47bb-0310-9956-ffa450edef68
Diffstat (limited to 'src/documentation/content/xdocs/trunk/graphics.xml')
-rw-r--r--src/documentation/content/xdocs/trunk/graphics.xml593
1 files changed, 0 insertions, 593 deletions
diff --git a/src/documentation/content/xdocs/trunk/graphics.xml b/src/documentation/content/xdocs/trunk/graphics.xml
deleted file mode 100644
index eb05013b7..000000000
--- a/src/documentation/content/xdocs/trunk/graphics.xml
+++ /dev/null
@@ -1,593 +0,0 @@
-<?xml version="1.0" encoding="UTF-8" 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>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/>
- </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/>
- </tr>
- <tr>
- <td>GIF (Graphics Interchange Format)</td>
- <td>bitmap</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>X</td>
- </tr>
- <tr>
- <td><a href="#png">PNG</a> (Portable Network Graphic)</td>
- <td>bitmap</td>
- <td>(X)</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>X</td>
- <td/>
- </tr>
- <tr>
- <td><a href="#tiff">TIFF</a> (Tag Image Format File)</td>
- <td>bitmap</td>
- <td>(X)</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>(X)</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&amp;nbsp;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>X [1]</td>
- </tr>
- <tr>
- <td><a href="#eps">EPS</a> (Encapsulated PostScript)</td>
- <td/>
- <td>X [1]</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 [2]</td>
- <td>X [2]</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&amp;nbsp;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&amp;nbsp;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>
- FOP native support of PNG only includes the variants with 8 bits per channel and without
- interlacing. Native support requires using the ImageLoaderRawPNG image loader.
- Support through a Image I/O codec can use either the internal XGC PNG codec or the JRE PNG
- codec. The associated image loaders are, respectively, ImageLoaderPNG and ImageLoaderImageIO.
- 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&amp;nbsp;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:
- &lt;uri&gt;#page=&lt;nr&gt;
- (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> \ No newline at end of file