You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@xmlgraphics.apache.org by je...@apache.org on 2008/01/22 08:44:12 UTC
svn commit: r614134 - in /xmlgraphics/site/deploy/commons: changes.html
changes.pdf download.html image-loader.html image-loader.pdf
images/update.jpg index.html linkmap.html linkmap.pdf postscript.html
Author: jeremias
Date: Mon Jan 21 23:44:11 2008
New Revision: 614134
URL: http://svn.apache.org/viewvc?rev=614134&view=rev
Log:
Automatic publish from forrestbot
Added:
xmlgraphics/site/deploy/commons/image-loader.html (with props)
xmlgraphics/site/deploy/commons/image-loader.pdf (with props)
xmlgraphics/site/deploy/commons/images/update.jpg (with props)
Modified:
xmlgraphics/site/deploy/commons/changes.html
xmlgraphics/site/deploy/commons/changes.pdf
xmlgraphics/site/deploy/commons/download.html
xmlgraphics/site/deploy/commons/index.html
xmlgraphics/site/deploy/commons/linkmap.html
xmlgraphics/site/deploy/commons/linkmap.pdf
xmlgraphics/site/deploy/commons/postscript.html
Modified: xmlgraphics/site/deploy/commons/changes.html
URL: http://svn.apache.org/viewvc/xmlgraphics/site/deploy/commons/changes.html?rev=614134&r1=614133&r2=614134&view=diff
==============================================================================
--- xmlgraphics/site/deploy/commons/changes.html (original)
+++ xmlgraphics/site/deploy/commons/changes.html Mon Jan 21 23:44:11 2008
@@ -108,6 +108,9 @@
<div class="menuitem">
<a href="postscript.html" title="Tools for Adobe PostScript">Tools for Adobe PostScript</a>
</div>
+<div class="menuitem">
+<a href="image-loader.html" title="Image Loader Framework">Image Loader Framework</a>
+</div>
</div>
<div onclick="SwitchMenu('menu_selected_1.1.6', 'skin/')" id="menu_selected_1.1.6Title" class="menutitle" style="background-image: url('skin/images/chapter_open.gif');">Information</div>
<div id="menu_selected_1.1.6" class="selectedmenuitemgroup" style="display: block;">
@@ -175,6 +178,15 @@
<ul>
<li>
<img class="icon" alt="add" src="images/add.jpg">
+ The package org.apache.xmlgraphics.image.loader was added. It contains a general
+ image loading framework for various image formats (bitmap & vector).
+ (JM)</li>
+<li>
+<img class="icon" alt="add" src="images/add.jpg">
+ XMP: Added support for structured properties.
+ (JM)</li>
+<li>
+<img class="icon" alt="add" src="images/add.jpg">
PostScript: Added classes for "BoundingBox" DSC comments.
(JM)</li>
<li>
@@ -191,15 +203,35 @@
(CB) Thanks to Adrian Cumiskey. Fixes <a href="http://issues.apache.org/bugzilla/show_bug.cgi?id=43069">43069</a>.</li>
<li>
<img class="icon" alt="fix" src="images/fix.jpg">
+ Bugfix for XMP serialization: arrays with only one entry were serialized as
+ simple property which could lead to information loss for merge operations.
+ (JM)</li>
+<li>
+<img class="icon" alt="fix" src="images/fix.jpg">
+ PostScript: Fixed %%EOF checking for nested documents.
+ (JM)</li>
+<li>
+<img class="icon" alt="fix" src="images/fix.jpg">
+ PostScript: Improved robustness of DSC parsing (multi-line comments with no value
+ on the first line don't cause crashes anymore, fallback for unparsable DSC comments).
+ (JM)</li>
+<li>
+<img class="icon" alt="fix" src="images/fix.jpg">
Fixed a possible NPE in the TIFF codec (in the TIFFImage constructor).
(JM) Thanks to Sergey Orlov. Fixes <a href="http://issues.apache.org/bugzilla/show_bug.cgi?id=43120">43120</a>.</li>
+<li>
+<img class="icon" alt="update" src="images/update.jpg">
+ PostScript: Improved PSImageUtils by introducing the ImageEncoder interface and
+ allowing for streams instead of byte arrays for data transfer which can lower
+ memory consumption.
+ (JM)</li>
</ul>
</div>
-<a name="N10032"></a><a name="version_1.2"></a>
+<a name="N10050"></a><a name="version_1.2"></a>
<h2 class="underlined_10">Version 1.2 (21 July 2007)</h2>
<div class="section">
-<a name="N10036"></a><a name="Code-N10036"></a>
+<a name="N10054"></a><a name="Code-N10054"></a>
<h3 class="underlined_5">Code</h3>
<ul>
<li>
@@ -220,10 +252,10 @@
</ul>
</div>
-<a name="N1004F"></a><a name="version_1.1"></a>
+<a name="N1006D"></a><a name="version_1.1"></a>
<h2 class="underlined_10">Version 1.1 (22 Dec 2006)</h2>
<div class="section">
-<a name="N10053"></a><a name="Code-N10053"></a>
+<a name="N10071"></a><a name="Code-N10071"></a>
<h3 class="underlined_5">Code</h3>
<ul>
<li>
@@ -255,10 +287,10 @@
</ul>
</div>
-<a name="N10077"></a><a name="version_1.0"></a>
+<a name="N10095"></a><a name="version_1.0"></a>
<h2 class="underlined_10">Version 1.0 (17 Apr 2006)</h2>
<div class="section">
-<a name="N1007B"></a><a name="Code-N1007B"></a>
+<a name="N10099"></a><a name="Code-N10099"></a>
<h3 class="underlined_5">Code</h3>
<ul>
<li>
Modified: xmlgraphics/site/deploy/commons/changes.pdf
URL: http://svn.apache.org/viewvc/xmlgraphics/site/deploy/commons/changes.pdf?rev=614134&r1=614133&r2=614134&view=diff
==============================================================================
Binary files - no diff available.
Modified: xmlgraphics/site/deploy/commons/download.html
URL: http://svn.apache.org/viewvc/xmlgraphics/site/deploy/commons/download.html?rev=614134&r1=614133&r2=614134&view=diff
==============================================================================
--- xmlgraphics/site/deploy/commons/download.html (original)
+++ xmlgraphics/site/deploy/commons/download.html Mon Jan 21 23:44:11 2008
@@ -108,6 +108,9 @@
<div class="menuitem">
<a href="postscript.html" title="Tools for Adobe PostScript">Tools for Adobe PostScript</a>
</div>
+<div class="menuitem">
+<a href="image-loader.html" title="Image Loader Framework">Image Loader Framework</a>
+</div>
</div>
<div onclick="SwitchMenu('menu_1.1.6', 'skin/')" id="menu_1.1.6Title" class="menutitle">Information</div>
<div id="menu_1.1.6" class="menuitemgroup">
Added: xmlgraphics/site/deploy/commons/image-loader.html
URL: http://svn.apache.org/viewvc/xmlgraphics/site/deploy/commons/image-loader.html?rev=614134&view=auto
==============================================================================
--- xmlgraphics/site/deploy/commons/image-loader.html (added)
+++ xmlgraphics/site/deploy/commons/image-loader.html Mon Jan 21 23:44:11 2008
@@ -0,0 +1,549 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
+<meta content="Apache Forrest" name="Generator">
+<meta name="Forrest-version" content="0.7">
+<meta name="Forrest-skin-name" content="pelt">
+<title>Image Loader Framework</title>
+<link type="text/css" href="skin/basic.css" rel="stylesheet">
+<link media="screen" type="text/css" href="skin/screen.css" rel="stylesheet">
+<link media="print" type="text/css" href="skin/print.css" rel="stylesheet">
+<link type="text/css" href="skin/profile.css" rel="stylesheet">
+<script src="skin/getBlank.js" language="javascript" type="text/javascript"></script><script src="skin/getMenu.js" language="javascript" type="text/javascript"></script><script src="skin/fontsize.js" language="javascript" type="text/javascript"></script>
+<link rel="shortcut icon" href="favicon.ico">
+</head>
+<body onload="init()">
+<script type="text/javascript">ndeSetTextSize();</script>
+<div id="top">
+<!--+
+ |header
+ +-->
+<div class="header">
+<!--+
+ |start group logo
+ +-->
+<div class="grouplogo">
+<a href="http://xmlgraphics.apache.org/"><img class="logoImage" alt="xmlgraphics.apache.org" src="images/apache-xml-graphics.gif" title="Apache XML Graphics is responsible for the creation and maintenance of software for managing the conversion of XML formats to graphical output, and the creation and maintenance of related software components, based on software licensed to the Foundation"></a>
+</div>
+<!--+
+ |end group logo
+ +-->
+<!--+
+ |start Project Logo
+ +-->
+<div class="projectlogo">
+<a href="http://xmlgraphics.apache.org/commons/">Apache XML Graphics Commons</a>
+</div>
+<!--+
+ |end Project Logo
+ +-->
+<!--+
+ |start Search
+ +-->
+<div class="searchbox">
+<form action="http://www.google.com/search" method="get" class="roundtopsmall">
+<input value="xmlgraphics.apache.org" name="sitesearch" type="hidden"><input onFocus="getBlank (this, 'Search the site with google');" size="25" name="q" id="query" type="text" value="Search the site with google">
+ <input attr="value" name="Search" value="Search" type="submit">
+</form>
+</div>
+<!--+
+ |end search
+ +-->
+<!--+
+ |start Tabs
+ +-->
+<ul id="tabs">
+<li class="current">
+<a class="base-selected" href="index.html">Home</a>
+</li>
+</ul>
+<!--+
+ |end Tabs
+ +-->
+</div>
+</div>
+<div id="main">
+<div id="publishedStrip">
+<!--+
+ |start Subtabs
+ +-->
+<div id="level2tabs"></div>
+<!--+
+ |end Endtabs
+ +-->
+<script type="text/javascript"><!--
+document.write("<text>Last Published:</text> " + document.lastModified);
+// --></script>
+</div>
+<!--+
+ |breadtrail
+ +-->
+<div class="breadtrail">
+<a href="http://www.apache.org/">apache.org</a> > <a href="http://xml.apache.org/">XML Federation</a> > <a href="http://xmlgraphics.apache.org/">xmlgraphics.apache.org</a><script src="skin/breadcrumbs.js" language="JavaScript" type="text/javascript"></script>
+</div>
+<!--+
+ |start Menu, mainarea
+ +-->
+<!--+
+ |start Menu
+ +-->
+<div id="menu">
+<div onclick="SwitchMenu('menu_selected_1.1', 'skin/')" id="menu_selected_1.1Title" class="menutitle" style="background-image: url('skin/images/chapter_open.gif');">XML Graphics Commons</div>
+<div id="menu_selected_1.1" class="selectedmenuitemgroup" style="display: block;">
+<div class="menuitem">
+<a href="index.html" title="Overview">Overview</a>
+</div>
+<div class="menuitem">
+<a href="download.html" title="Download">Download</a>
+</div>
+<div class="menuitem">
+<a href="http://www.apache.org/foundation/sponsorship.html">ASF Sponsorship Program</a>
+</div>
+<div class="menuitem">
+<a href="http://www.apache.org/foundation/thanks.html">ASF Thanks</a>
+</div>
+<div onclick="SwitchMenu('menu_selected_1.1.5', 'skin/')" id="menu_selected_1.1.5Title" class="menutitle" style="background-image: url('skin/images/chapter_open.gif');">Documentation</div>
+<div id="menu_selected_1.1.5" class="selectedmenuitemgroup" style="display: block;">
+<div class="menuitem">
+<a href="postscript.html" title="Tools for Adobe PostScript">Tools for Adobe PostScript</a>
+</div>
+<div class="menupage">
+<div class="menupagetitle">Image Loader Framework</div>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.1.6', 'skin/')" id="menu_1.1.6Title" class="menutitle">Information</div>
+<div id="menu_1.1.6" class="menuitemgroup">
+<div class="menuitem">
+<a href="http://xmlgraphics.apache.org/mail.html" title="Information on Mailing Lists">Mailing Lists</a>
+</div>
+<div class="menuitem">
+<a href="http://xmlgraphics.apache.org/repo.html" title="Information on Code Repositories">Code Repositories</a>
+</div>
+<div class="menuitem">
+<a href="changes.html">Changes</a>
+</div>
+</div>
+</div>
+<div id="credit"></div>
+<div id="roundbottom">
+<img style="display: none" class="corner" height="15" width="15" alt="" src="skin/images/rc-b-l-15-1body-2menu-3menu.png"></div>
+<!--+
+ |alternative credits
+ +-->
+<div id="credit2">
+<a href="http://eu.apachecon.com/"><img border="0" title="ApacheCon Europe 2008" alt="ApacheCon Europe 2008 - logo" src="http://apache.org/ads/ApacheCon/2008-europe-125x125.png" style="width: 125px;height: 125px;"></a>
+</div>
+</div>
+<!--+
+ |end Menu
+ +-->
+<!--+
+ |start content
+ +-->
+<div id="content">
+<div title="Portable Document Format" class="pdflink">
+<a class="dida" href="image-loader.pdf"><img alt="PDF -icon" src="skin/images/pdfdoc.gif" class="skin"><br>
+ PDF</a>
+</div>
+<div class="trail">
+<text>Font size:</text>
+ <input value="Reset" class="resetfont" title="Reset text" onclick="ndeSetTextSize('reset'); return false;" type="button">
+ <input value="-a" class="smallerfont" title="Shrink text" onclick="ndeSetTextSize('decr'); return false;" type="button">
+ <input value="+a" class="biggerfont" title="Enlarge text" onclick="ndeSetTextSize('incr'); return false;" type="button">
+</div>
+<h1>Image Loader Framework</h1>
+<div id="minitoc-area">
+<ul class="minitoc">
+<li>
+<a href="#overview">Overview</a>
+</li>
+<li>
+<a href="#tutorial">Tutorial</a>
+<ul class="minitoc">
+<li>
+<a href="#manager-setup">Setting up the manager</a>
+</li>
+<li>
+<a href="#preloading">Preloading an image</a>
+</li>
+<li>
+<a href="#loading">Loading an image</a>
+</li>
+</ul>
+</li>
+<li>
+<a href="#tipsntricks">Tips & Tricks</a>
+</li>
+<li>
+<a href="#spi">Service Provider Interface (SPI, Plug-ins)</a>
+<ul class="minitoc">
+<li>
+<a href="#ImagePreloader">ImagePreloader</a>
+</li>
+<li>
+<a href="#ImageLoader">ImageLoader and ImageLoaderFactory</a>
+</li>
+<li>
+<a href="#ImageConverter">ImageConverter</a>
+</li>
+</ul>
+</li>
+</ul>
+</div>
+
+<a name="N1000D"></a><a name="overview"></a>
+<h2 class="underlined_10">Overview</h2>
+<div class="section">
+<p>
+ Apache XML Graphics Commons contains a unified framework for loading and
+ processing images (bitmap and vector). The package name is
+ <span class="codefrag">org.apache.xmlgraphics.image.loader</span>. Key features:
+ </p>
+<ul>
+
+<li>
+ Unified basic API for all supported image types.
+ </li>
+
+<li>
+ Image "Preloading": It allows automatic detection on the image
+ content type and can extract the intrinsic size (in pixels and length
+ units) of the image without loading the whole image into memory in
+ most cases. <a href="http://xmlgraphics.apache.org/fop/">Apache FOP</a>
+ uses this as it only needs the size of the image to do the layout.
+ The image is only fully read at the rendering stage.
+ </li>
+
+<li>
+ Image conversion facility: Images can be converted into different
+ representations depending on the needs of the consumer.
+ </li>
+
+<li>
+ Supported formats: All bitmap formats for which there are codecs
+ for the ImageIO API (like JPEG, PNG, GIF etc.), EPS, EMF. These
+ formats are bundled. Other formats such as SVG and WMF are available
+ through plug-ins hosted elsewhere.
+ </li>
+
+<li>
+ Supported in-memory representations:
+ <ul>
+
+<li>RenderedImage/BufferedImage</li>
+
+<li>raw/undecoded (JPEG, EPS, CCITT group 3/4)</li>
+
+<li>Java2D (Images painted through Graphics2D)</li>
+
+<li>XML DOM (for SVG, MathML etc.)</li>
+
+<li>Additional representations can be added as necessary.</li>
+
+</ul>
+
+</li>
+
+<li>
+ Custom image loaders and converters can be dynamically plugged in.
+ Automatic plug-in detection through the application classpath.
+ </li>
+
+<li>
+ An image cache speeds up the processing for images that are requested
+ multiple times.
+ </li>
+
+</ul>
+</div>
+
+<a name="N10048"></a><a name="tutorial"></a>
+<h2 class="underlined_10">Tutorial</h2>
+<div class="section">
+<a name="N1004E"></a><a name="manager-setup"></a>
+<h3 class="underlined_5">Setting up the manager</h3>
+<p>
+ Before we can start to work with the package we need to set up the
+ <span class="codefrag">ImageManager</span>. It provides convenience methods to load
+ and convert images and holds the image cache.
+ </p>
+<p>
+ The <span class="codefrag">ImageManager</span> needs an <span class="codefrag">ImageContext</span>.
+ This interface provides the <span class="codefrag">ImageManager</span> with important
+ context and configuration data. Currently this is only the source
+ resolution. The <span class="codefrag">ImageManager</span> and
+ <span class="codefrag">ImageContext</span> are intended to be shared within an
+ application.
+ </p>
+<pre class="code">
+import org.apache.xmlgraphics.image.loader.ImageContext;
+import org.apache.xmlgraphics.image.loader.ImageManager;
+import org.apache.xmlgraphics.image.loader.impl.DefaultImageContext;
+
+[..]
+
+ ImageManager imageManager = new ImageManager(new DefaultImageContext());
+ </pre>
+<div class="note">
+<div class="label">Note</div>
+<div class="content">
+ In this example, <span class="codefrag">DefaultImageContext</span> is used. You may
+ need to write your own implementation of <span class="codefrag">ImageContext</span> for
+ your use case.
+ </div>
+</div>
+<a name="N1007A"></a><a name="preloading"></a>
+<h3 class="underlined_5">Preloading an image</h3>
+<p>
+ In order to load an image, it needs to be "preloaded" first, i.e. the image content
+ type is detected and the intrinsic size of the image is determined. The result of this
+ process is an <span class="codefrag">ImageInfo</span> instance which contains the URI, MIME type and
+ intrinsic size. In most cases, this is done without loading the whole image (see
+ SPI section below for information on exceptions to this rule).
+ </p>
+<p>
+ Preloading is normally done through the <span class="codefrag">ImageManager</span>'s
+ <span class="codefrag">getImageInfo()</span> method. For this operation
+ an <span class="codefrag">ImageSessionContext</span> needs to be provided. It is responsible for
+ supplying JAXP <span class="codefrag">Source</span> objects, URI resolution and providing other
+ information needed for the image operations. In simple cases you can simply use
+ <span class="codefrag">DefaultImageSessionContext</span>, but often you will want to write your own
+ implementation of <span class="codefrag">ImageSessionContext</span>. In that case, it's recommended to
+ subclass <span class="codefrag">AbstractImageSessionContext</span> which lets you avoid rewriting a
+ lot of code for providing <span class="codefrag">Source</span> objects.
+ </p>
+<p>
+
+</p>
+<pre class="code">
+import org.apache.xmlgraphics.image.loader.ImageInfo;
+import org.apache.xmlgraphics.image.loader.ImageSessionContext;
+import org.apache.xmlgraphics.image.loader.impl.DefaultImageSessionContext;
+
+[..]
+ ImageSessionContext sessionContext = new DefaultImageSessionContext(
+ imageManager.getImageContext(), null);
+
+ ImageInfo info = imageManager.getImageInfo(uri, sessionContext);
+ </pre>
+<a name="N100A9"></a><a name="loading"></a>
+<h3 class="underlined_5">Loading an image</h3>
+<p>
+ Once the image is "preloaded", it can be fully loaded in the form/flavor that is
+ needed by the consuming application. The required flavor is indicated through the
+ <span class="codefrag">ImageFlavor</span> class. If you want the image as a bitmap image in memory,
+ you could request an <span class="codefrag">ImageFlavor.RENDERED_IMAGE</span>. Again, the
+ <span class="codefrag">ImageSessionContext</span> will be needed.
+ </p>
+<pre class="code">
+import org.apache.xmlgraphics.image.loader.Image;
+import org.apache.xmlgraphics.image.loader.ImageFlavor;
+
+[..]
+ Image img = this.imageManager.getImage(
+ info, ImageFlavor.RENDERED_IMAGE, sessionContext);
+
+ ImageRendered imageRend = (ImageRendered)img;
+ RenderedImage ri = imageRend.getRenderedImage();
+ //...and do anything with the RenderedImage
+ </pre>
+<p>
+ In this example above, we simply acquire the image as a RenderedImage instance.
+ If the original image was a vector graphic image (SVG, WMF etc.), it's automatically
+ converted to a bitmap image. Note: The resolution of the created image is controlled
+ by the target resolution returned by the <span class="codefrag">ImageSessionContext</span>.
+ </p>
+<p>
+ Of course, the framework can only provide images in the formats, it has image loaders
+ or image converters for. An example: It is possible to load EPS images, but they
+ can only be provided in raw form. In order to provide it as a bitmap image, a PostScript
+ interpreter would be needed to interpret the PostScript code. This interpreter would
+ be integrated using an <span class="codefrag">ImageConverter</span> implementation (see SPI section below).
+ If the requested form of the image cannot be provided you will get an
+ <span class="codefrag">ImageException</span> on which you'll have to react as needed.
+ </p>
+<p>
+ In <a href="http://xmlgraphics.apache.org/fop/">Apache FOP</a>, each renderer supports
+ a different set of image flavors that can be embedded in the target format. For example:
+ The PDF renderer can deal with Java2D image, bitmaps, XML, native JPEG and CCITT images.
+ The PCL renderer, however, can only consume bitmap images. So, if you can accept
+ more than one flavor, the package allows you to specify all of them in an ordered list
+ (the first in the list is the preferred format). The package will then try to return
+ the best representation possible. Here's a code example:
+ </p>
+<pre class="code">
+import org.apache.xmlgraphics.image.loader.Image;
+import org.apache.xmlgraphics.image.loader.ImageFlavor;
+
+[..]
+ final ImageFlavor[] flavors = new ImageFlavor[]
+ {ImageFlavor.GRAPHICS2D,
+ ImageFlavor.BUFFERED_IMAGE,
+ ImageFlavor.RENDERED_IMAGE};
+
+ Image img = manager.getImage(
+ info, flavors, sessionContext);
+
+ if (img instanceof ImageGraphics2D) {
+ //handle Java2D/Graphics2D image
+ } else if (img instanceof ImageRendered) {
+ //handle BufferedImage and RenderedImage
+ //(BufferedImage is a subclass of RenderedImage)
+ } else {
+ throw new IllegalStateException("Unexpected flavor");
+ }
+ </pre>
+<div class="note">
+<div class="label">Note</div>
+<div class="content">
+ While each <span class="codefrag">BufferedImage</span> is also a <span class="codefrag">RenderedImage</span>,
+ it can be more efficient to also specify <span class="codefrag">ImageFlavor.BUFFERED_IMAGE</span> in
+ the flavor array.
+ </div>
+</div>
+</div>
+
+<a name="N100E7"></a><a name="tipsntricks"></a>
+<h2 class="underlined_10">Tips & Tricks</h2>
+<div class="section">
+<p>
+ If you are loading bitmap images and you get an error like
+ <span class="codefrag">"Cannot load image (no suitable loader/converter combination available) for
+ myimage.tif (image/tiff)</span>,
+ you maybe be missing the necessary ImageIO codec to decode the image. A number of
+ well-written codecs can be found in
+ <a href="https://jai-imageio.dev.java.net/">JAI Image I/O Tools Project</a>. Just download
+ the distribution and add the JAR to the classpath. ImageIO will automatically pick up
+ the new codecs and they will subsequently be available to the image framework.
+ </p>
+</div>
+
+<a name="N100F8"></a><a name="spi"></a>
+<h2 class="underlined_10">Service Provider Interface (SPI, Plug-ins)</h2>
+<div class="section">
+<p>
+ The whole image framework is designed to be highly extensible. There are various
+ extension points where new functionality can be added. The three main SPI interfaces are:
+ </p>
+<ul>
+
+<li>
+<span class="codefrag">ImagePreloader</span>: detects the content type and preloads an image</li>
+
+<li>
+<span class="codefrag">ImageLoader</span> and <span class="codefrag">ImageLoaderFactory</span>: loads images</li>
+
+<li>
+<span class="codefrag">ImageConverter</span>: converts images from one representation into another</li>
+
+</ul>
+<p>
+ If you plan to write an implementation of one of the above interfaces, please also take
+ a look at the existing implementations for reference.
+ </p>
+<p>
+ Throughout the SPI, you'll find a <span class="codefrag">Map</span> parameter (hints) in the most important
+ methods. That's a way to supply additional information to the implementation by the
+ caller. For example, the source and target resolutions from the image (session) context
+ is stored in the hints. The implementation should not rely on the presence of specialized
+ information and should always have sensible defaults to rely on in this case.
+ </p>
+<a name="N1011F"></a><a name="ImagePreloader"></a>
+<h3 class="underlined_5">ImagePreloader</h3>
+<p>
+ The first task is identifying whether the implementation supports the given image.
+ If the image is loaded using an ImageInputStream it is important to always reset the
+ stream position to the beginning of the file at the end of the
+ <span class="codefrag">preloadImage()</span> method, because all registered preloaders are check in turn
+ until one implementation signals that it supports the format. In that case, it has to
+ extract only the minimal information from the image necessary to identify the image's
+ intrinsic size. For most formats, this is doable without loading the whole image into
+ memory.
+ </p>
+<p>
+ However, for some formats (like MathML or WMF), loading the whole image at preloading
+ time is hard to avoid since the image's size can only be determined that way. In such
+ a case, the <span class="codefrag">ImagePreloader</span> implementations shall pass the loaded
+ document to the respective <span class="codefrag">ImageLoader</span> through the custom objects that
+ can be attached to the <span class="codefrag">ImageInfo</span> object. If the preloader loads the whole
+ document, it shall close the given <span class="codefrag">Source</span> object (calling
+ <span class="codefrag">ImageUtil.closeQuietly(Source)</span>).
+ </p>
+<p>
+ The priority the implementation reports is used to sort all registered implementations.
+ This is to fine-tune the inner workings and to optimize performance since some formats
+ are usually used more frequently than others.
+ </p>
+<div class="note">
+<div class="label">Note</div>
+<div class="content">
+ Normally, if you implement an <span class="codefrag">ImagePreloader</span> you will also need to implement
+ the respective <span class="codefrag">ImageLoader/ImageLoaderFactory</span>, or vice versa.
+ </div>
+</div>
+<a name="N1014A"></a><a name="ImageLoader"></a>
+<h3 class="underlined_5">ImageLoader and ImageLoaderFactory</h3>
+<p>
+ The factory interface has been created to allow checking if some library that an
+ implementation depends on is really in the classpath so it can report back that the
+ <span class="codefrag">ImageLoader</span> is not funtional. The factory also reports what kind of
+ image formats it supports and which image flavors it can return. There can be a
+ complex relationship between the two. It is recommmended, however, to write smaller
+ implementations rather than big, almighty ones.
+ </p>
+<p>
+ The usage penalty is used when constructing image conversion pipelines. There can be
+ multiple ways to provide an image in one of the supported flavors and this value helps
+ to make the best decision.
+ </p>
+<p>
+ While the factory basically just provides information and creates new
+ <span class="codefrag">ImageLoader</span> instances, the image loaders are doing the actual leg work
+ of decoding the images. The image flavor returned by the loader must match the
+ flavor that is returned by <span class="codefrag">getTargetFlavor()</span>.
+ </p>
+<a name="N10163"></a><a name="ImageConverter"></a>
+<h3 class="underlined_5">ImageConverter</h3>
+<p>
+ The image converter is responsible to transform one image representation into another.
+ Bundled implementations support these conversions: Java2D to bitmap, bitmap to Java2D
+ and RenderedImage to "raw" PNG. Ideas for additional image converters could be:
+ PDF to Java2D, EPS to Java2D or MathML to SVG or Java2D.
+ </p>
+<p>
+ Each ImageConverter comes with a usage penalty which is used when constructing
+ conversion pipelines so the pipeline with the least penalty value can be chosen. This
+ is necessary as the consuming application my support multiple image flavors and there
+ can be multiple ways to convert an image in one of the requested image flavors.
+ Internally, <a href="http://en.wikipedia.org/wiki/Dijkstra%27s_algorithm">Dijkstra's
+ shortest path algorithm</a> is used to find the best path using the penalties as "way
+ lengths".
+ </p>
+</div>
+
+</div>
+<!--+
+ |end content
+ +-->
+<div class="clearboth"> </div>
+</div>
+<div id="footer">
+<!--+
+ |start bottomstrip
+ +-->
+<div class="lastmodified">
+<script type="text/javascript"><!--
+document.write("<text>Last Published:</text> " + document.lastModified);
+// --></script>
+</div>
+<div class="copyright">
+ Copyright ©
+ 2006-2007 <a href="http://www.apache.org/licenses/">The Apache Software Foundation.</a>
+</div>
+<!--+
+ |end bottomstrip
+ +-->
+</div>
+</body>
+</html>
Propchange: xmlgraphics/site/deploy/commons/image-loader.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: xmlgraphics/site/deploy/commons/image-loader.pdf
URL: http://svn.apache.org/viewvc/xmlgraphics/site/deploy/commons/image-loader.pdf?rev=614134&view=auto
==============================================================================
Binary file - no diff available.
Propchange: xmlgraphics/site/deploy/commons/image-loader.pdf
------------------------------------------------------------------------------
svn:mime-type = application/pdf
Added: xmlgraphics/site/deploy/commons/images/update.jpg
URL: http://svn.apache.org/viewvc/xmlgraphics/site/deploy/commons/images/update.jpg?rev=614134&view=auto
==============================================================================
Binary file - no diff available.
Propchange: xmlgraphics/site/deploy/commons/images/update.jpg
------------------------------------------------------------------------------
svn:mime-type = image/jpeg
Modified: xmlgraphics/site/deploy/commons/index.html
URL: http://svn.apache.org/viewvc/xmlgraphics/site/deploy/commons/index.html?rev=614134&r1=614133&r2=614134&view=diff
==============================================================================
--- xmlgraphics/site/deploy/commons/index.html (original)
+++ xmlgraphics/site/deploy/commons/index.html Mon Jan 21 23:44:11 2008
@@ -108,6 +108,9 @@
<div class="menuitem">
<a href="postscript.html" title="Tools for Adobe PostScript">Tools for Adobe PostScript</a>
</div>
+<div class="menuitem">
+<a href="image-loader.html" title="Image Loader Framework">Image Loader Framework</a>
+</div>
</div>
<div onclick="SwitchMenu('menu_1.1.6', 'skin/')" id="menu_1.1.6Title" class="menutitle">Information</div>
<div id="menu_1.1.6" class="menuitemgroup">
Modified: xmlgraphics/site/deploy/commons/linkmap.html
URL: http://svn.apache.org/viewvc/xmlgraphics/site/deploy/commons/linkmap.html?rev=614134&r1=614133&r2=614134&view=diff
==============================================================================
--- xmlgraphics/site/deploy/commons/linkmap.html (original)
+++ xmlgraphics/site/deploy/commons/linkmap.html Mon Jan 21 23:44:11 2008
@@ -108,6 +108,9 @@
<div class="menuitem">
<a href="postscript.html" title="Tools for Adobe PostScript">Tools for Adobe PostScript</a>
</div>
+<div class="menuitem">
+<a href="image-loader.html" title="Image Loader Framework">Image Loader Framework</a>
+</div>
</div>
<div onclick="SwitchMenu('menu_1.1.6', 'skin/')" id="menu_1.1.6Title" class="menutitle">Information</div>
<div id="menu_1.1.6" class="menuitemgroup">
@@ -197,6 +200,12 @@
<ul>
<li>
<a href="postscript.html">Tools for Adobe PostScript</a> _________________________ <em>postscript</em>
+</li>
+</ul>
+
+<ul>
+<li>
+<a href="image-loader.html">Image Loader Framework</a> _________________________ <em>image-loader</em>
</li>
</ul>
Modified: xmlgraphics/site/deploy/commons/linkmap.pdf
URL: http://svn.apache.org/viewvc/xmlgraphics/site/deploy/commons/linkmap.pdf?rev=614134&r1=614133&r2=614134&view=diff
==============================================================================
Binary files - no diff available.
Modified: xmlgraphics/site/deploy/commons/postscript.html
URL: http://svn.apache.org/viewvc/xmlgraphics/site/deploy/commons/postscript.html?rev=614134&r1=614133&r2=614134&view=diff
==============================================================================
--- xmlgraphics/site/deploy/commons/postscript.html (original)
+++ xmlgraphics/site/deploy/commons/postscript.html Mon Jan 21 23:44:11 2008
@@ -108,6 +108,9 @@
<div class="menupage">
<div class="menupagetitle">Tools for Adobe PostScript</div>
</div>
+<div class="menuitem">
+<a href="image-loader.html" title="Image Loader Framework">Image Loader Framework</a>
+</div>
</div>
<div onclick="SwitchMenu('menu_1.1.6', 'skin/')" id="menu_1.1.6Title" class="menutitle">Information</div>
<div id="menu_1.1.6" class="menuitemgroup">
---------------------------------------------------------------------
Apache XML Graphics Project URL: http://xmlgraphics.apache.org/
To unsubscribe, e-mail: commits-unsubscribe@xmlgraphics.apache.org
For additional commands, e-mail: commits-help@xmlgraphics.apache.org