[prev in list] [next in list] [prev in thread] [next in thread]
List: fop-cvs
Subject: svn commit: r508559 -
From: jeremias () apache ! org
Date: 2007-02-16 20:22:08
Message-ID: 20070216202208.247361A981A () eris ! apache ! org
[Download RAW message or body]
Author: jeremias
Date: Fri Feb 16 12:22:07 2007
New Revision: 508559
URL: http://svn.apache.org/viewvc?view=rev&rev=508559
Log:
Attempted to improve/fix documentation on images. There was some out-dated and wrong \
information on the page.
Modified:
xmlgraphics/fop/trunk/src/documentation/content/xdocs/trunk/graphics.xml
Modified: xmlgraphics/fop/trunk/src/documentation/content/xdocs/trunk/graphics.xml
URL: http://svn.apache.org/viewvc/xmlgraphics/fop/trunk/src/documentation/content/xdocs/trunk/graphics.xml?view=diff&rev=508559&r1=508558&r2=508559
==============================================================================
--- xmlgraphics/fop/trunk/src/documentation/content/xdocs/trunk/graphics.xml \
(original)
+++ xmlgraphics/fop/trunk/src/documentation/content/xdocs/trunk/graphics.xml Fri Feb \
16 12:22:07 2007 @@ -75,7 +75,7 @@
<td>(X)</td>
<td></td>
<td></td>
- <td></td>
+ <td>X</td>
<td></td>
<td></td>
</tr>
@@ -85,7 +85,7 @@
<td></td>
<td></td>
<td>X</td>
- <td></td>
+ <td>X</td>
<td></td>
<td></td>
</tr>
@@ -105,11 +105,21 @@
<td>(X)</td>
<td></td>
<td>X</td>
- <td></td>
+ <td>X</td>
<td>X</td>
<td></td>
<!--td><a href="#native">FOP native</a> or <a href="#jai">JAI</a>, \
depending on the subformat. See <a href="#tiff">TIFF</a> for more details.(JIMI also \
supports TIFF, but this has not been implemented within FOP).</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>
+ <td></td>
+ <td></td>
+ <td></td>
+ </tr>
</table>
<note>"(X)" means restricted support. Please see the details below.</note>
</section>
@@ -122,9 +132,9 @@
</p>
</section>
<section id="batik-codecs">
- <title>Batik codecs</title>
+ <title>"Internal" codecs</title>
<p>
- Apache Batik contains codecs for PNG and TIFF access. FOP can use these.
+ Apache XML Graphics Commons contains codecs for PNG and TIFF access. FOP \
can use these. </p>
</section>
<section id="imageio">
@@ -153,7 +163,7 @@
</p>
</section>
<section id="batik">
- <title>Batik</title>
+ <title>Apache Batik</title>
<p>Current FOP distributions include a distribution of the Apache <a \
class="fork" href="ext:batik">Batik</a> version 1.6. It is automatically installed \
with FOP. 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> @@ -186,6 +196,11 \
@@ (including GhostScript) will render the EPS correctly.
</li>
</ul>
+ <warning>
+ Please note that the EPS embedding feature has been \
<strong>deprecated</strong> in the + PDF specification version 1.4. You should \
not use this feature anymore, especially + since newer PDF tools don't \
support embedded EPS files anymore. + </warning>
<p>
Other output targets can't be supported at the moment because
FOP lacks a PostScript interpreter. Furthermore, FOP is not able
@@ -194,28 +209,37 @@
</section>
<section id="jpeg">
<title>JPEG</title>
- <p>FOP native support 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. + <p>
+ FOP native support 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. </p>
</section>
<section id="png">
<title>PNG</title>
- <p>If using JAI for PNG support, only RGB and RGBA color-spaces are supported \
for FOP rendering.</p> + <p>
+ If using JAI for PNG support, only RGB and RGBA color-spaces are supported \
for + FOP rendering.
+ </p>
+ <p>
+ 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">Batik</a> for SVG support.
+ <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://xml.apache.org/batik/svgrasterizer.html">SVG Rasterizer \
documentation</a> +<a \
href="http://xmlgraphics.apache.org/batik/svgrasterizer.html">SVG Rasterizer \
documentation</a> on the Batik site.
</note>
</section>
@@ -224,74 +248,89 @@
<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.
+this remain as vector graphics. The same applies to PostScript output.
+For other output formats the SVG graphic will 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 this graphic may not
-be ideal depending on the FOP dpi (72dpi) and the scaling for that graphic.
-We hope to improve this in the future.</p>
+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 not supported in PDF so many svg images that
-contain effects or graphics with transparent areas will not be displayed
+Currently transparency is limited in PDF so many 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</title>
- <p>If possible, Batik will use normal PDF text when inserting text. It does
+ <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> /
<!--link href="../dev/svg/text.pdf"-->text.pdf<!--/link-->
shows how various types and effects with text are handled.
Note that tspan and outlined text are not yet implemented.</p>
<p>
-Otherwise, text is converted and drawn as a set of shapes by batik, using the \
stroking text painter. +Otherwise, 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 pdf files large and when the pdf is viewed the
-viewer does not normally draw those fine curves very well (turning on
-Smooth Line Art in the Acrobat preferences will fix this).
-If the text is inserted into the PDF using the inbuilt text commands
-for PDF it will use a single character.
+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).
+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> + <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-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.
-FOP will probably implement a scaling mechanism in the future.</p>
+ <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. FOP will probably implement a scaling + mechanism in the future.
+ </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
+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
+or darker on pdf 1.4 viewers.
</li>
<li>
-there is some problem with a gradient inside a pattern causing a pdf
-error when viewed in acrobat 5
+There is some problem with a gradient inside a pattern causing 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
+Text is not always handled correctly, it may select the wrong font
+especially if characters have multiple fonts in the font list.
</li>
<li>
-more pdf text handling could be implemented
+More PDF text handling could be implemented.
It could draw the string using the attributed character iterator
to handle tspans and other simple changes of text.
</li>
<li>
-JPEG images are not inserted directly into the pdf document
+JPEG images are not inserted directly into the pdf document.
This area has not been implemented yet since the appropriate
-method in batik is static
+method in batik is static.
</li>
<li>
Uniform transparency for images and other svg elements that are converted
@@ -302,36 +341,61 @@
</section>
<section id="tiff">
<title>TIFF</title>
- <p>FOP-native TIFF support is limited to PDF and PostScript output only. Also, \
according to user reports, FOP's native support for TIFF is limited to images with \
the following characteristics (all must be true for successful rendering):</p> + \
<p> + FOP-native TIFF support is limited to PDF and PostScript output only. \
Also, + according to user reports, FOP's native support for TIFF is limited \
to images with the + following characteristics (all must be true for \
successful rendering): + </p>
<ul>
<li>single channel images (i.e., bi-level and grayscale only)</li>
<li>uncompressed images, or images using CCITT T.4, CCITT T.6, or JPEG \
compression</li>
<li>images using white-is-zero encoding in the TIFF \
PhotometricInterpretation tag</li> </ul>
+ <note>
+ Native support in this case means that the images can be embedded into the \
output format + without decoding it.
+ </note>
<p><em>JAI:</em> Supports RGB and RGBA only for FOP rendering.</p>
</section>
+ <section id="emf">
+ <title>EMF</title>
+ <p>Windows Enhanced Metafiles (EMF) are only supported in RTF output.</p>
+ </section>
<section id="resolution">
<title>Graphics Resolution</title>
- <p>Some bitmapped image file formats store a dots-per-inch (dpi) or other \
resolution value. Since PDF and most output formats do not have a concept of \
resolution, but only of absolute image units (i.e. pixels) FOP ignores the resolution \
values as well. Instead, FOP uses the dimensions of the image as specified in the \
fo:external-graphic element to render the image:</p>
- <ul>
- <li>If no dimensions are given, FOP uses a default value of 72 dpi to \
compute the graphic's dimensions. For example, suppose a graphic 300 pixels wide and \
400 pixels high. FOP will render the graphic at 4.167 inches wide, 5.555 inches high, \
with an apparent resolution of 72 dpi.</li>
- <li>If only one dimension is given, FOP by default uses the same aspect \
ratio to compute the other dimension (to avoid the appearance of stretching). For \
example, suppose a graphic 300 pixels wide and 400 pixels high, for which \
content-width = ".5in". FOP will compute the content-height = .667 inches, and will \
render the graphic at that size, with an apparent resolution of 600 \
dpi.</li>
- <li>If both dimensions are given, FOP simply renders the image in that \
space. For example, suppose a graphic 300 pixels wide and 400 pixels high, for which \
content-width = "3in" and content-height = "4in". FOP will render the graphic at that \
size, with an apparent resolution of 100 dpi.</li>
- </ul>
- <p>If you need a higher apparent output resolution for bitmapped images, first \
make sure that at least one dimension of the image is defined in your XSL-FO input. \
Apart from that, resolution problems are in the image file itself, and must be \
corrected there: use or create a higher-resolution image file.</p>
- <note>The explanation above describes only the basic default behavior. There \
are other attributes of the fo:external-graphic element that can affect the behavior \
described above.</note> + <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 + superceeded 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 + 72 dpi is assumed (the default resolution of PDF and PostScript).
+ </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="caching">
<title>Image caching</title>
<p>
- FOP caches images between runs. The URL is used as a key to identify images \
which means that when
- a particular URL 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 URL you \
need to use a constantly + 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 URL you need to use a constantly changing dummy parameter \
on the URL to avoid caching. </p>
<p>
- The image cache has been improved considerably in the redesigned code. \
Therefore, a resetCache() method
- has become unnecessary. If you still experience OutOfMemoryErrors, please \
notify us. + The image cache has been improved considerably in the redesigned \
code. Therefore, a + resetCache() method like in earlier versions of FOP has \
become unnecessary. If you + still experience OutOfMemoryErrors, please \
notify us. </p>
</section>
</body>
---------------------------------------------------------------------
To unsubscribe, e-mail: fop-commits-unsubscribe@xmlgraphics.apache.org
For additional commands, e-mail: fop-commits-help@xmlgraphics.apache.org
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic