| <?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 V1.3//EN" "http://forrest.apache.org/dtd/document-v13.dtd"> |
| <document> |
| <header> |
| <title>Apache™ FOP Design: Renderers</title> |
| <version>$Revision$</version> |
| <authors> |
| <person name="Keiron Liddle" email="keiron@aftexsw.com"/> |
| </authors> |
| </header> |
| <body> |
| <section id="intro"> |
| <title>Introduction</title> |
| <p>A renderer is primarily designed to convert a given area tree into the output |
| document format. It should be able to produce pages and fill the pages |
| with the text and graphical content. Usually the output is sent to |
| an output stream.</p> |
| <p>Some output formats may support extra information that is not available |
| from the area tree or depends on the destination of the document.</p> |
| <p>Each renderer is given an area tree to render to its output format. |
| The area tree is simply a representation of the pages and the placement |
| of text and graphical objects on those pages.</p> |
| <p>The renderer will be given each page as it is ready and an output stream |
| to write the data out. |
| All pages are supplied in the order they appear in the document. |
| In order to save memory it is |
| possble to render the pages out of order. Any page that is not ready to |
| be rendered is setup by the renderer first so that it can reserve a space |
| or reference for when the page is ready to be rendered.The renderer is responsible for managing the |
| output format and associated data and flow.</p> |
| </section> |
| <section id="issues"> |
| <title>Design Issues</title> |
| <section id="issue-renderers-responsible"> |
| <title>Renderers are Responsible</title> |
| <p>Each renderer is totally responsible for its output format.</p> |
| </section> |
| <section id="issue-output-stream"> |
| <title>Send Output to a Stream</title> |
| </section> |
| </section> |
| <section id="fonts"> |
| <title>Fonts</title> |
| <p>Because font metrics (and therefore layout) are obtained in two different ways depending on the renderer, the renderer actually sets up the fonts being used. The font metrics are used |
| during the layout process to determine the size of characters.</p> |
| </section> |
| <section id="context"> |
| <title>Render Context</title> |
| <p>The render context is used by handlers. |
| It contains information about the current state of the renderer, such as the page, the position, and any other miscellanous objects that are required to draw into the page.</p> |
| </section> |
| <section> |
| <title>XML Handling</title> |
| <p>A document may contain information in the form of XML for an image or instream foreign object. |
| This XML is handled through the user agent. |
| A standard extension for PDF is the SVG handler.</p> |
| <p>If there is XML in the SVG namespace it is given to the handler which renders the SVG into the pdf document at the given location. |
| This separation means that other XML handlers can easily be added.</p> |
| </section> |
| <section> |
| <title>Extensions</title> |
| <p>Document level extensions are handled with an extension handler. |
| This handles the information from the AreaTree and adds renders it to the document. |
| An example is the pdf bookmarks. This information first needs to have all references resolved. |
| Then the extension handler is ready to put the information into the pdf document.</p> |
| </section> |
| <section id="implement"> |
| <title>Renderer Implementations</title> |
| <table> |
| <tr> |
| <th>Name</th> |
| <th>Type</th> |
| <th>Font Source</th> |
| <th>Font Embedding?</th> |
| <th>Out of Order Rendering?</th> |
| <th>Notes</th> |
| </tr> |
| <tr> |
| <td>PDF</td> |
| <td>Paginated</td> |
| <td>FOP</td> |
| <td>Yes</td> |
| <td>Yes</td> |
| <td>Uses the PDFDocument classes to create a PDF document. Most of the work is to insert text or create lines. SVG is handled by the XML handler that uses the PDFGraphics2D and batik to |
| draw the svg into the pdf page.</td> |
| </tr> |
| <tr> |
| <td>PostScript</td> |
| <td>Paginated</td> |
| <td>FOP</td> |
| <td>Not implemented</td> |
| <td>?</td> |
| <td>Similar to PDF.</td> |
| </tr> |
| <tr> |
| <td>PCL</td> |
| <td>Paginated</td> |
| <td>FOP</td> |
| <td>?</td> |
| <td>?</td> |
| <td>Similar to PDF.</td> |
| </tr> |
| <tr> |
| <td>SVG</td> |
| <td>Paginated</td> |
| <td>?</td> |
| <td>?</td> |
| <td>?</td> |
| <td>Creates a single svg document that contains all the pages rendered |
| with page sequences horizontally and pages vertically. Adds |
| links between the pages so that it can be viewed by clicking on the page |
| to go to the next page.</td> |
| </tr> |
| <tr> |
| <td>TXT</td> |
| <td>Paginated</td> |
| <td>N/A</td> |
| <td>N/A</td> |
| <td>No</td> |
| <td>Outputs to a text document.</td> |
| </tr> |
| <tr> |
| <td>AWT</td> |
| <td>Paginated</td> |
| <td>AWT</td> |
| <td>N/A</td> |
| <td>?</td> |
| <td>This draws the pages into an AWT graphic.</td> |
| </tr> |
| <tr> |
| <td>XML</td> |
| <td>Paginated</td> |
| <td>FOP</td> |
| <td>No</td> |
| <td>No</td> |
| <td>Creates an XML file that represents the AreaTree.</td> |
| </tr> |
| <tr> |
| <td>Print</td> |
| <td>Paginated</td> |
| <td>AWT</td> |
| <td>?</td> |
| <td>No</td> |
| <td>Prints the document using the java printing facitlities. The AWT |
| rendering is used to draw the pages onto the printjob.</td> |
| </tr> |
| <tr> |
| <td>RTF</td> |
| <td>Structural</td> |
| <td>N/A</td> |
| <td>N/A</td> |
| <td>No</td> |
| <td>Structural format uses a different rendering mechanism.</td> |
| </tr> |
| <tr> |
| <td>MIF</td> |
| <td>Structural</td> |
| <td>N/A</td> |
| <td>N/A</td> |
| <td>No</td> |
| <td>Structural format uses a different rendering mechanism.</td> |
| </tr> |
| </table> |
| </section> |
| <section id="add"> |
| <title>Adding a Renderer</title> |
| <p>You can add other renderers by implementing the Renderer interface. |
| However, the AbstractRenderer does most of what is needed, including iterating through the tree parts, so it is probably better to extend this. |
| This means that you only need to implement the basic functionality such as text, images, and lines. |
| AbstractRenderer's methods can easily be overridden to handle things in a different way or do some extra processing.</p> |
| <p>The relevent AreaTree structures that will need to be rendered are:</p> |
| <ul> |
| <li>Page</li> |
| <li>Viewport</li> |
| <li>Region</li> |
| <li>Span</li> |
| <li>Block</li> |
| <li>Line</li> |
| <li>Inline</li> |
| </ul> |
| <p>A renderer implementation does the following:</p> |
| <ul> |
| <li>render each individual page</li> |
| <li>clip and align child areas to a viewport</li> |
| <li>handle all types of inline area, text, image etc.</li> |
| <li>draw various lines and rectangles</li> |
| </ul> |
| </section> |
| <section id="multiple"> |
| <title>Multiple Renderers</title> |
| <p>The layout of the document depends mainly on the font being used. |
| If two renderers have the same font metrics then it is possible to use the same Area Tree to render both. This can be handled by the AreaTree Handler.</p> |
| </section> |
| <section id="status"> |
| <title>Status</title> |
| <section id="status-todo"> |
| <title>To Do</title> |
| </section> |
| <section id="status-wip"> |
| <title>Work In Progress</title> |
| </section> |
| <section id="status-complete"> |
| <title>Completed</title> |
| <ul> |
| <li>new renderer model</li> |
| <li>new interface for structured documents, rtf and mif</li> |
| <li>added handlers for xml in renderer</li> |
| </ul> |
| </section> |
| </section> |
| </body> |
| </document> |
