123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229 |
- <?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>
|