Documentation update for bitmap output. git-svn-id: https://svn.apache.org/repos/asf/xmlgraphics/fop/trunk@820939 13f79535-47bb-0310-9956-ffa450edef68tags/fop-1_0
@@ -1033,8 +1033,13 @@ out = proc.getOutputStream();]]></source> | |||
<p> | |||
Currently, two output formats are supported: PNG and TIFF. TIFF produces | |||
one file with multiple pages, while PNG output produces one file per | |||
page. The quality of the bitmap depends on the target resolution setting | |||
on the FOUserAgent. | |||
page. Note: FOP can only produce multiple files (with PNG output) if | |||
you can set a <code>java.io.File</code> indicating the primary PNG file | |||
using the <code>FOUserAgent.setOutputFile(File)</code> method. | |||
</p> | |||
<p> | |||
The quality of the bitmap depends on the target resolution setting | |||
on the FOUserAgent and on further settings described below. | |||
</p> | |||
<section id="bitmap-configuration"> | |||
<title>Configuration</title> | |||
@@ -1042,15 +1047,52 @@ out = proc.getOutputStream();]]></source> | |||
The TIFF and PNG renderer configuration currently allows the following settings: | |||
</p> | |||
<source><![CDATA[<renderer mime="image/png"> | |||
<color-mode>rgba</color-mode> | |||
<transparent-page-background>true</transparent-page-background> | |||
<background-color>white</background-color> | |||
<anti-aliasing>true</anti-aliasing> | |||
<rendering>quality</rendering> | |||
<fonts><!-- described elsewhere --></fonts> | |||
</renderer>]]></source> | |||
<p> | |||
The default value for the "transparent-page-background" setting is "false" which | |||
paints an opaque, white background for the whole image. If you set this to true, | |||
The default value for the <code>"color-mode"</code> setting is <code>"rgba"</code> which | |||
is equivalent to a 24bit RGB image with an 8bit alpha channel for transparency. | |||
Valid values are: | |||
</p> | |||
<ul> | |||
<li><code>rgba</code>: RGB with alpha channel (24bit + 8bit = 32bit)</li> | |||
<li><code>rgb</code>: RGB (24bit)</li> | |||
<li><code>gray</code>: gray (8bit)</li> | |||
<li><code>bi-level</code> (or <code>binary</code>): bi-level (1bit)</li> | |||
</ul> | |||
<p> | |||
Please note that there is currently no dithering or error diffusion available for bi-level | |||
bitmap output. | |||
</p> | |||
<p> | |||
The default value for the <code>"transparent-page-background"</code> setting is | |||
<code>"false"</code> which paints an opaque, white background for the whole image. | |||
If you set this to <code>"true"</code>, | |||
no such background will be painted and you will get a transparent image if | |||
an alpha channel is available in the output format. | |||
</p> | |||
<p> | |||
The default value for the <code>"background-color"</code> setting is <code>"white"</code>. | |||
The color specifies in which color the page background is painted. It will only be | |||
painted if <code>"transparent-page-background"</code> is not set to <code>"true"</code>. | |||
All XSL-FO colors (including color functions) can be used. | |||
</p> | |||
<p> | |||
The default value for the <code>"anti-aliasing"</code> setting is <code>"true"</code>. | |||
You can set this value to <code>"false"</code> to disable anti-aliasing and | |||
thus improve rendering speeds a bit at the loss of some image quality. | |||
</p> | |||
<p> | |||
The default value for the <code>"rendering"</code> setting is <code>"true"</code>. | |||
You can set this value to <code>"false"</code> to improve rendering speeds a bit | |||
at the loss of some image quality. If this setting has an actual effect depends | |||
on the JVM's Java2D backend. | |||
</p> | |||
</section> | |||
<section id="tiff-configuration"> | |||
<title>TIFF-specific Configuration</title> | |||
@@ -1071,17 +1113,22 @@ out = proc.getOutputStream();]]></source> | |||
actual codecs being available. Here is a list of possible values: | |||
</p> | |||
<ul> | |||
<li>NONE (no compression)</li> | |||
<li>PackBits (RLE, run-length encoding)</li> | |||
<li>JPEG</li> | |||
<li>Deflate</li> | |||
<li>LZW</li> | |||
<li>ZLib</li> | |||
<li>CCITT T.4 (Fax Group 3)</li> | |||
<li>CCITT T.6 (Fax Group 4)</li> | |||
<li><code>NONE</code> (no compression)</li> | |||
<li><code>PackBits</code> (RLE, run-length encoding)</li> | |||
<li><code>JPEG</code></li> | |||
<li><code>Deflate</code></li> | |||
<li><code>LZW</code></li> | |||
<li><code>ZLib</code></li> | |||
<li><code>CCITT T.4</code> (Fax Group 3)</li> | |||
<li><code>CCITT T.6</code> (Fax Group 4)</li> | |||
</ul> | |||
<p> | |||
This setting may override any setting made using the <code>"color-mode"</code>. For example, if | |||
<code>"CCITT T.6"</code> is selected, the color mode is automatically forced to <code>"bi-level"</code> because | |||
this compression format only supports bi-level images. | |||
</p> | |||
<note> | |||
If you want to use CCITT compression, please make sure you've got a J2SE 1.4 or later and | |||
If you want to use CCITT compression, please make sure you've got | |||
<a href="http://java.sun.com/products/java-media/jai/current.html"> | |||
Java Advanced Imaging Image I/O Tools | |||
</a> | |||
@@ -1090,6 +1137,17 @@ out = proc.getOutputStream();]]></source> | |||
Deflate and JPEG compression for writing. | |||
</note> | |||
</section> | |||
<section id="bitmap-rendering-options"> | |||
<title>Runtime Rendering Options</title> | |||
<p> | |||
The IF-based bitmap output implementations support a rendering option with the key | |||
"target-bitmap-size" (value: java.awt.Dimension) that allows to force the pages to | |||
be proportionally fit into a bitmap of a given size. This can be used to produce | |||
thumbnails or little preview images of the individual pages. An example: | |||
</p> | |||
<source><![CDATA[userAgent.getRenderingOptions().put( | |||
"target-bitmap-size", new Dimension(320, 200));]]></source> | |||
</section> | |||
</section> | |||
<section id="txt"> | |||
<title>TXT</title> |
@@ -22,9 +22,11 @@ package org.apache.fop.render.bitmap; | |||
import java.awt.Dimension; | |||
import java.awt.Graphics2D; | |||
import java.awt.RenderingHints; | |||
import java.awt.geom.Point2D; | |||
import java.awt.image.BufferedImage; | |||
import java.io.IOException; | |||
import java.io.OutputStream; | |||
import java.util.Map; | |||
import org.apache.commons.io.IOUtils; | |||
import org.apache.commons.logging.Log; | |||
@@ -53,6 +55,13 @@ public abstract class AbstractBitmapDocumentHandler extends AbstractBinaryWritin | |||
/** logging instance */ | |||
private static Log log = LogFactory.getLog(AbstractBitmapDocumentHandler.class); | |||
/** | |||
* Rendering Options key for the controlling the required bitmap size to create. | |||
* This is used to create thumbnails, for example. If used, the target resolution is ignored. | |||
* Value type: java.awt.Dimension (size in pixels) | |||
*/ | |||
public static final String TARGET_BITMAP_SIZE = "target-bitmap-size"; | |||
private ImageWriter imageWriter; | |||
private MultiImageWriter multiImageWriter; | |||
@@ -66,6 +75,7 @@ public abstract class AbstractBitmapDocumentHandler extends AbstractBinaryWritin | |||
private BitmapRenderingSettings bitmapSettings = new BitmapRenderingSettings(); | |||
private double scaleFactor = 1.0; | |||
private Dimension targetBitmapSize; | |||
/** | |||
* Default constructor. | |||
@@ -94,6 +104,9 @@ public abstract class AbstractBitmapDocumentHandler extends AbstractBinaryWritin | |||
//Set target resolution | |||
int dpi = Math.round(context.getUserAgent().getTargetResolution()); | |||
getSettings().getWriterParams().setResolution(dpi); | |||
Map renderingOptions = getUserAgent().getRendererOptions(); | |||
setTargetBitmapSize((Dimension)renderingOptions.get(TARGET_BITMAP_SIZE)); | |||
} | |||
/** {@inheritDoc} */ | |||
@@ -113,6 +126,17 @@ public abstract class AbstractBitmapDocumentHandler extends AbstractBinaryWritin | |||
setFontInfo(fi); | |||
} | |||
/** | |||
* Sets the target bitmap size (in pixels) of the bitmap that should be produced. Normally, | |||
* the bitmap size is calculated automatically based on the page size and the target | |||
* resolution. But for example, if you want to create thumbnails or small preview bitmaps | |||
* from pages it is more practical (and efficient) to set the required bitmap size. | |||
* @param size the target bitmap size (in pixels) | |||
*/ | |||
public void setTargetBitmapSize(Dimension size) { | |||
this.targetBitmapSize = size; | |||
} | |||
//---------------------------------------------------------------------------------------------- | |||
/** {@inheritDoc} */ | |||
@@ -176,13 +200,43 @@ public abstract class AbstractBitmapDocumentHandler extends AbstractBinaryWritin | |||
/** {@inheritDoc} */ | |||
public IFPainter startPageContent() throws IFException { | |||
double scale = scaleFactor | |||
* (25.4f / FopFactoryConfigurator.DEFAULT_TARGET_RESOLUTION) | |||
/ getUserAgent().getTargetPixelUnitToMillimeter(); | |||
int bitmapWidth = (int) ((this.currentPageDimensions.width * scale / 1000f) + 0.5f); | |||
int bitmapHeight = (int) ((this.currentPageDimensions.height * scale / 1000f) + 0.5f); | |||
int bitmapWidth; | |||
int bitmapHeight; | |||
double scale; | |||
Point2D offset = null; | |||
if (targetBitmapSize != null) { | |||
//Fit the generated page proportionally into the given rectangle (in pixels) | |||
double scale2w = 1000 * targetBitmapSize.width | |||
/ this.currentPageDimensions.getWidth(); | |||
double scale2h = 1000 * targetBitmapSize.height | |||
/ this.currentPageDimensions.getHeight(); | |||
bitmapWidth = targetBitmapSize.width; | |||
bitmapHeight = targetBitmapSize.height; | |||
//Centering the page in the given bitmap | |||
offset = new Point2D.Double(); | |||
if (scale2w < scale2h) { | |||
scale = scale2w; | |||
double h = this.currentPageDimensions.height * scale / 1000; | |||
offset.setLocation(0, (bitmapHeight - h) / 2.0); | |||
} else { | |||
scale = scale2h; | |||
double w = this.currentPageDimensions.width * scale / 1000; | |||
offset.setLocation((bitmapWidth - w) / 2.0, 0); | |||
} | |||
} else { | |||
//Normal case: just scale according to the target resolution | |||
scale = scaleFactor | |||
* getUserAgent().getTargetResolution() | |||
/ FopFactoryConfigurator.DEFAULT_TARGET_RESOLUTION; | |||
bitmapWidth = (int) ((this.currentPageDimensions.width * scale / 1000f) + 0.5f); | |||
bitmapHeight = (int) ((this.currentPageDimensions.height * scale / 1000f) + 0.5f); | |||
} | |||
//Set up bitmap to paint on | |||
this.currentImage = createBufferedImage(bitmapWidth, bitmapHeight); | |||
Graphics2D graphics2D = this.currentImage.createGraphics(); | |||
// draw page background | |||
if (!getSettings().hasTransparentPageBackground()) { | |||
graphics2D.setBackground(getSettings().getPageBackgroundColor()); | |||
@@ -190,6 +244,7 @@ public abstract class AbstractBitmapDocumentHandler extends AbstractBinaryWritin | |||
graphics2D.fillRect(0, 0, bitmapWidth, bitmapHeight); | |||
} | |||
//Set rendering hints | |||
graphics2D.setRenderingHint(RenderingHints.KEY_FRACTIONALMETRICS, | |||
RenderingHints.VALUE_FRACTIONALMETRICS_ON); | |||
if (getSettings().isAntiAliasingEnabled() | |||
@@ -213,6 +268,11 @@ public abstract class AbstractBitmapDocumentHandler extends AbstractBinaryWritin | |||
} | |||
graphics2D.setRenderingHint(RenderingHints.KEY_STROKE_CONTROL, | |||
RenderingHints.VALUE_STROKE_PURE); | |||
//Set up initial coordinate system for the page | |||
if (offset != null) { | |||
graphics2D.translate(offset.getX(), offset.getY()); | |||
} | |||
graphics2D.scale(scale / 1000f, scale / 1000f); | |||
return new Java2DPainter(graphics2D, getContext(), getFontInfo()); |
@@ -19,7 +19,6 @@ | |||
package org.apache.fop.render.bitmap; | |||
import java.awt.Color; | |||
import java.awt.Graphics2D; | |||
import java.awt.image.BufferedImage; | |||
import java.util.List; | |||
@@ -80,8 +79,6 @@ public class BitmapRendererConfigurator extends Java2DRendererConfigurator | |||
if (background != null) { | |||
settings.setPageBackgroundColor( | |||
ColorUtil.parseColorString(this.userAgent, background)); | |||
} else { | |||
settings.setPageBackgroundColor(Color.WHITE); | |||
} | |||
} | |||
@@ -106,6 +103,8 @@ public class BitmapRendererConfigurator extends Java2DRendererConfigurator | |||
settings.setBufferedImageType(BufferedImage.TYPE_BYTE_GRAY); | |||
} else if ("binary".equalsIgnoreCase(color)) { | |||
settings.setBufferedImageType(BufferedImage.TYPE_BYTE_BINARY); | |||
} else if ("bi-level".equalsIgnoreCase(color)) { | |||
settings.setBufferedImageType(BufferedImage.TYPE_BYTE_BINARY); | |||
} else { | |||
throw new FOPException("Invalid value for color-mode: " + color); | |||
} |
@@ -58,6 +58,10 @@ | |||
documents. Example: the fix of marks layering will be such a case when it's done. | |||
--> | |||
<release version="FOP Trunk" date="TBD"> | |||
<action context="Renderers" dev="JM" type="add"> | |||
Added support for creating thumbnails or preview bitmaps of fixed size for PNG and TIFF | |||
output. | |||
</action> | |||
<action context="Extensions" dev="JM" type="add"> | |||
Added support for the #CMYK pseudo-profile supported by some commercial XSL implementations | |||
on the rgb-icc() function. |