diff options
| author | Keiron Liddle <keiron@apache.org> | 2002-04-22 13:19:51 +0000 |
|---|---|---|
| committer | Keiron Liddle <keiron@apache.org> | 2002-04-22 13:19:51 +0000 |
| commit | 4bacd6f54620684d992cf7f9d6093dd089558814 (patch) | |
| tree | c460cafba01ab42c91a49eb911272b17401b0a89 /docs | |
| parent | 4d585be94025d510c1af7561aff9b8cef4072fdc (diff) | |
| download | xmlgraphics-fop-4bacd6f54620684d992cf7f9d6093dd089558814.tar.gz xmlgraphics-fop-4bacd6f54620684d992cf7f9d6093dd089558814.zip | |
more understanding docs
converted from mailing list to xml doc
Submitted by: Cyril Rognon <crognon@objectiva.fr>
git-svn-id: https://svn.apache.org/repos/asf/xmlgraphics/fop/trunk@194738 13f79535-47bb-0310-9956-ffa450edef68
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/design/understanding/area_tree.xml | 108 | ||||
| -rw-r--r-- | docs/design/understanding/renderers.xml | 106 |
2 files changed, 210 insertions, 4 deletions
diff --git a/docs/design/understanding/area_tree.xml b/docs/design/understanding/area_tree.xml index bf8c63794..9013f647a 100644 --- a/docs/design/understanding/area_tree.xml +++ b/docs/design/understanding/area_tree.xml @@ -8,6 +8,110 @@ </authors> </header> <body><s1 title="Area Tree"> - <p>Yet to come :))</p> - <note>The series of notes for developers has started but it has not yet gone so far ! Keep watching</note></s1> +<s2 title="Area Tree"> +<p>The Area Tree is an internal representation of the result document. This +is a set of java classes that can put together a set of objects that +represent the pages and their contents.</p> +<p>This information is created by the layout managers and is rendered to the +output using a renderer.</p> +<p>The Area Tree follows the description of the area tree in the XSL:FO +specification.</p> +<p>The Area Tree consists of a set of pages, the actual implemenation places +these in +a set of page sequences.</p></s2> + +<s2 title="Pages"> +<p>A page consists of a page+viewport pair.</p> +<p>The PageViewPort and Page with the regions is created by the +LayoutMasterSet. The contents are then placed by the layout managers. Once +the layout of a page is complete then it is added to the Area Tree.</p> +<p>Inside the page is a set of RegionViewport+Region pairs for each region on +the page.</p></s2> + + +<s2 title="Blocks"> +<p>Block level areas contain either other blocks or line areas (which is a +special block area).</p><p> +A block is either positoned or stacked with other block areas.</p> +</s2> + +<s2 title="Inline Areas"> +<p>Inline areas are stacked in a line area. Inline areas are objects such as +character, viewport, inline-container, leader and space. A special inline +area Word is also used for a group of consecutive characters.</p> +<p>The image and instream foreign object areas are placed inside a viewport. +The leader (with use content) and unresolved page number areas are +resolved to other inline areas.</p> +<p>Once a LineArea is filled with inline areas then the inline areas need to +be aligned and adjusted to fill the line properly.</p></s2> + + +<s2 title="Traits"> + +<p>A trait is information associated with an area. This could be information +such as text colour or is-first.</p> +<p>Traits provide information about an area. The traits are derived from +properties on the formatting object or are generated during the layout +process. Many of the layout traits do not have actual values but can be +derived from the Area Tree. Other traits that apply when rendering the +areas are set on the area. Since setting the same value on every area +would use a lot of memory then the traits are derived from default or +parent values.</p> +<p>A dominant trait on a block area is set, for example font colour, so that +every line area with the same dominant value can derive it. The text +inline areas then get the font colour set on the inline area or from the +line area or from the block area.</p></s2> + + +<s2 title="Forward References"> +<p>The Area Tree maintains a set of mappings from the reference to pages.</p> +<p>The PageViewPort holds the list of forward references that need resolving +so that if a references is resolved during layout the page can be easily +found and then fixed. Once all the forward references are resolved then +the page is ready to be rendered.</p> +<p>To layout a page any areas that cannot be resolved need to reserve space. +Once the inline area is resolved then the complete line should be adjusted +to accomodate any change in space used by the area.</p></s2> + + +<s2 title="Caching"> +<p>We may need to cache pages due to forward references or when keeping all +pages.</p> +<p>This is done by serializing the Page. The PageViewport is retained to be +used as a key for page references and backward references. +The Page is serialized to an object stream and then all of the page +contents are released. The Page is then recoved by reading from the object +stream.</p> +<p>The PageViewport retains information about id areas for easy access.</p> +</s2> + +<s2 title="Extensions"> +<p>The Area Tree holds the Output Document extensions. This is information +such as pdf bookmarks or other output document specific information that +is not handled by XSL:FO.</p> +<p>It is also possible to create custom areas that extend a normal area. The +actual data that is rendered could be set in a different way or depend on +resolving a forward reference.</p> +</s2> + +<s2 title="Area Tree Handlers"> +<p>To handle different situations the handler for the Area Tree handles each +page as it is added.</p><p> +The RenderPagesModel sends the page directly to the renderer if the page +is ready to be rendered. Once a page is rendered it is discarded. +The StorePagesModel stores all the pages so that any page can be later +accessed.</p> +<p>The Area Tree retains the concept of page sequences (this is not in the +area tree in the spec) so that this information can be passed to the +renderer. This is useful for setting the title and organising the groups +of page sequences.</p></s2> + + +<s2 title="Associated Tasks"> +<ul><li>Sort out extensions concept, access to AreaTree.</li> +<li>Sort out trait handling.</li> +<li>Caching implementation.</li></ul></s2> + + + </s1> </body></document>
\ No newline at end of file diff --git a/docs/design/understanding/renderers.xml b/docs/design/understanding/renderers.xml index cf66e2b8e..e597d118b 100644 --- a/docs/design/understanding/renderers.xml +++ b/docs/design/understanding/renderers.xml @@ -8,6 +8,108 @@ </authors> </header> <body><s1 title="Renderers"> - <p>Yet to come :))</p> - <note>The series of notes for developers has started but it has not yet gone so far ! Keep watching</note></s1> + +<s2 title="Renderers"> + + +<p>A renderer is used to convert the Area Tree into the output document. +The renderer is given the tree one page at a time. 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 reeady 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.</p> +<p>The AbstractRenderer does most of the work to iterate through the area +tree parts. This means that the most renderers simply need to implement +the specific parts with inserting text, images and lines. The methods can +easily be overridden to handle things in a different way or do some extra +processing.</p></s2> + + +<s2 title="Fonts"> +<p>The fonts are setup by the renderer being used. The font metrics are used +during the layout process to determine the size of characters.</p> +</s2> + +<s2 title="Render Context"> +<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></s2> + + +<s2 title="XML Handling"> + +<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></s2> + + +<s2 title="Extensions"> +<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></s2> + + +<s2 title="Types"> + + +<s3 title="PDF"> +<p>This uses the PDFDocument classes to create a PDF document. This supports +out of order rendering as it is possible to reserve a pdf page object that +can be later filled. 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.</p><p> +This also allows for font embedding.</p> +</s3> +<s3 title="SVG"> +<p>This creates a single svg document that contains all the pages rendered +with page sequences horizontally and pages vertically. This also adds +links between the pages so that it can be viewed by clicking on the page +to go to the next page.</p></s3> + +<s3 title="TXT"> +<p>This simply outputs to a text document.</p></s3> +<s3 title="AWT"> +<p>This draws the pages into an AWT graphic.</p></s3> + +<s3 title="PS and PCL"> +<p>Similar to PDF.</p></s3> + +<s3 title="XML"> +<p>Creates an XML file that represents the AreaTree.</p> +</s3> +<s3 title="Print"> +<p>This prints the document using the java printing facitlities. The AWT +rendering is used to draw the pages onto the printjob. +</p></s3> +<s3 title="RTF and MIF"> +<p>These formats do not use this rendering mechanism.</p></s3> +</s2> + +<s2 title="Adding a Renderer"> +<p>It is also possible to add other renderers. The renderer simply needs to +implement the Renderer interface. The AbstractRenderer does most of what +is needed so it is better to extend this. This means that you only need to +implement the basic functionality such as text and lines. +</p></s2> + +<s2 title="Multiple Renderers"> +<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 render +the Area Tree in each renderer. This can be handled by the AreaTree +Handler.</p></s2> + + +<s2 title="Associated Tasks"> + +<ul><li>Sort out multiple renderers concept.</li></ul> +</s2> + +</s1> + + </body></document>
\ No newline at end of file |