Images

diff --git a/src/documentation/content/xdocs/design/images.xml b/src/documentation/content/xdocs/design/images.xml new file mode 100644 index 000000000..fc40a64d6 --- /dev/null +++ b/src/documentation/content/xdocs/design/images.xml @@ -0,0 +1,135 @@ + + + + +

+ Images +

+ + +

+ Images in FOP + +

Images may only be needed to be loaded when the image is rendered to the +output or to find the dimensions.
+An image url may be invalid, this can be costly to find out so we need to +keep a list of invalid image urls.

We have a number of different caching schemes that are possible.

All images are referred to using the url given in the XSL:FO after +removing "url('')" wrapping. This does +not include any sort of resolving such as relative -> absolute. The +external graphic in the FO Tree and the image area in the Area Tree only +have the url as a reference. +The images are handled through a static interface in ImageFactory.

+ +

+ Threading + +

In a single threaded case with one document the image should be released +as soon as the renderer caches it. If there are multiple documents then +the images could be held in a weak cache in case another document needs to +load the same image.

+ +

In a multi threaded case many threads could be attempting to get the same +image. We need to make sure an image will only be loaded once at a +particular time. Once a particular document is finished then we can move +all the images to a common weak cache.

+ +

+ Caches +

+ LRU +

All images are in a common cache regardless of context. To limit the size +of the cache the LRU image is removed to keep the amount of memory used +low. Each image can supply the amount of data held in memory.

+ +

+ Context +

Images are cached according to the context, using the FOUserAgent as a key. +Once the context is finished the images are added to a common weak hashmap +so that other contexts can load these images or the data will be garbage +collected if required.

If images are to be used commonly then we cannot dispose of data in the +FopImage when cached by the renderer. Also if different contexts have +different base directories for resolving relative url's then the loading +and caching must be separate. We can have a cache that shares images among +all contexts or only loads an image for a context.

+ +

The cache uses an image loader so that it can synchronize the image +loading on an image by image basis. Finding and adding an image loader to +the cache is also synchronized to prevent thread problems.

+ +

+ Invalid Images + +

+If an image cannot be loaded for some reason, for example the url is +invalid or the image data is corrupt or an unknown type. Then it should +only attempt to load the image once. All other attempts to get the image +should return null so that it can be easily handled.
+This will prevent any extra processing or waiting.

+ +

+ Reading +

Once a stream is opened for the image url then a set of image readers is +used to determine what type of image it is. The reader can peek at the +image header or if necessary load the image. The reader can also get the +image size at this stage. +The reader then can provide the mime type to create the image object to +load the rest of the information.

+ +

+ Data + +

The data usually need for an image is the size and either a bitmap or the +original data. Images such as jpeg and eps can be embedded into the +document with the original data. SVG images are converted into a DOM which +needs to be rendered to the PDF. Other images such as gif, tiff etc. are +converted into a bitmap. +Data is loaded by the FopImage by calling load(type) where type is the type of data to load.

+ + +

+ Rendering + +

Different renderers need to have the information in different forms.

+ + +

+ PDF +

original data: JPG, EPS
bitmap: gif, tiff, bmp, png
other: SVG

+ +

+ PS +

bitmap: JPG, gif, tiff, bmp, png
other: SVG

+ +

+ awt +

bitmap: JPG, gif, tiff, bmp, png
other: SVG

+ +

The renderer uses the url to retrieve the image from the ImageFactory and +then load the required data depending on the image mime type. If the +renderer can insert the image into the document and use that data for all +future references of the same image then it can cache the reference in the +renderer and the image can be released from the image cache.

+ + + + diff --git a/src/documentation/content/xdocs/design/parsing.xml b/src/documentation/content/xdocs/design/parsing.xml new file mode 100644 index 000000000..9dc2646c3 --- /dev/null +++ b/src/documentation/content/xdocs/design/parsing.xml @@ -0,0 +1,60 @@ + + + +

+ XML Parsing +

+ +

+ XML Input +

The xml document is always handled internally as SAX. The SAX events + are used to read the elements, attributes and text data of the FO document. + After the manipulation of the data the renderer writes out the pages in the + appropriate format. It may write as it goes, a page at a time or the whole + document at once. Once finished the document should contain all the data in the + chosen format ready for whatever use.

FOP can take the input XML in a number of ways:

SAX Events through SAX Handler: FOTreeBuilder is the SAX Handler which is obtained through getContentHandler on Driver.
DOM (which is converted into SAX Events): The conversion of a DOM tree is done via the render(Document) method on Driver.
Data Source (which is parsed and converted into SAX Events): The Driver can take an InputSource as input. +This can use a Stream, String etc.
XML+XSLT Transformation (which is transformed using an XSLT Processor and the result is fired as SAX Events: XSLTInputHandler is used as an InputSource in the render(XMLReader, InputSource) method on Driver

The SAX Events which are fired on the SAX Handler, class FOTreeBuilder, must represent an XSL:FO document. +If not there will be an error. +Any problems with the XML being well-formed are also handled here.

+ Element Mappings +

The element mapping is a hashmap of all the elements in a particular namespace. +This makes it easy to create a different object for each element. +Element mappings are static to save on memory.

To add an extension a developer can put in the classpath a jar that contains the file /META-INF/services/org.apache.fop.fo.ElementMapping. +This must contain a line with the fully qualified name of a class that implements the org.apache.fop.fo.ElementMapping interface. +This will then be loaded automatically at the start. +Internal mappings are: FO, SVG and Extension (pdf bookmarks).

+ Tree Building +

The SAX Events will fire all the information for the document with start element, end element, text data etc. +This information is used to build up a representation of the FO document. +To do this for a namespace there is a set of element mappings. +When an element + namepsace mapping is found then it can create an object for that element. +If the element is not found then it creates a dummy object or a generic DOM for unknown namespaces.

The object is then setup and then given attributes for the element. +For the FO Tree the attributes are converted into properties. +The FO objects use a property list mapping to convert the attributes into a list of properties for the element. +For other XML, for example SVG, a DOM of the XML is constructed. +This DOM can then be passed through to the renderer. +Other element mappings can be used in different ways, for example to create elements that create areas during the layout process or setup information for the renderer etc.

While the tree building is mainly about creating the FO Tree there are some stages that can propagate to the renderer. +At the end of a page sequence we know that all pages in the page sequence can be laid out without being effected by any further XML. +The significance of this is that the FO Tree for the page sequence may be able to be disposed of. +The end of the XML document also tells us that we can finalise the output document. +(The layout of individual pages is accomplished by the layout managers page at a time; i.e. they do not need to wait for the end of the page sequence. +The page may not yet be complete, however, containing forward page number references, for example.)

+ + diff --git a/src/documentation/content/xdocs/design/pdf-library.xml b/src/documentation/content/xdocs/design/pdf-library.xml new file mode 100644 index 000000000..e7301f6b1 --- /dev/null +++ b/src/documentation/content/xdocs/design/pdf-library.xml @@ -0,0 +1,76 @@ + + + + +

+ PDF Library +

+ + +

+ PDF Library + +

The PDF Library is an independant package of classes in FOP. These class +provide a simple way to construct documents and add the contents. The +classes are found in org.apache.fop.pdf.*.

+ +

+ PDF Document +

This is where most of the document is created and put together.

It sets up the header, trailer and resources. Each page is made and added to the document. +There are a number of methods that can be used to create/add certain PDF objects to the document.

+ +

+ Building PDF +

The PDF Document is built by creating a page for each page in the Area Tree.

This page then has all the contents added. + The page is then added to the document and available objects can be written to the output stream.

The contents of the page are things such as text, lines, images etc. +The PDFRenderer inserts the text directly into a pdf stream. +The text consists of markup to set fonts, set text position and add text.

Most of the simple pdf markup is inserted directly into a pdf stream. +Other more complex objects or commonly used objects are added through java classes. +Some pdf objects such as an image consists of two parts.

It has a separate object for the image data and another bit of markup to display the image in a certain position on the page. +

The java objects that represent a pdf object implement a method that returns the markup for inserting into a stream. +The method is: byte[] toPDF().

+ +

+ Features + +

+ Fonts +

Support for embedding fonts and using the default Acrobat fonts. +

+ +

+ Images +

Images can be inserted into a page. The image can either be inserted as a pixel map or directly insert a jpeg image. +

+ +

+ Stream Filters +

A number of filters are available to encode the pdf streams. These filters can compress the data or change it such as converting to hex. +

+ +

+ Links +

A pdf link can be added for an area on the page. This link can then point to an external destination or a position on any page in the document. +

+ +

+ Patterns +

The fill and stroke of graphical objects can be set with a colour, pattern or gradient. +

+ +

The are a number of other features for handling pdf markup relevent to creating PDF files for FOP.

+ +

+ + + + diff --git a/src/documentation/content/xdocs/design/svg.xml b/src/documentation/content/xdocs/design/svg.xml new file mode 100644 index 000000000..74730dcd4 --- /dev/null +++ b/src/documentation/content/xdocs/design/svg.xml @@ -0,0 +1,74 @@ + + + + +

+ SVG +

+ +

+ SVG +

SVG is rendered through Batik.

The XML from the XSL:FO document + is converted into an SVG DOM with batik. This DOM is then set as the Document + on the Foreign Object area in the Area Tree.

This DOM is then available to + be rendered by the renderer.

SVG is rendered in the renderers via an XMLHandler in the FOUserAgent. This XML handler is used to render the SVG. The + SVG is rendered by using batik. Batik converts the SVG DOM into an internal + structure that can be drawn into a Graphics2D. So for PDF we use a + PDFGraphics2D to draw into.

This creates the necessary PDF information to + create the SVG image in the PDF document.

Most of the work is done in the + PDFGraphics2D class. There are also a few bridges that are plugged into batik + to provide different behaviour for some SVG elements.

+ Text Drawing +

Normally batik converts text into a set of curved + shapes.

This is handled as any other shapes when rendering to the output. This + is not always desirable as the shapes have very fine curves. This can cause the + output to look a bit bad in PDF and PS (it can be drawn properly but is not by + default). These curves also require much more data than the original + text.

To handle this there is a PDFTextElementBridge that is set when + using the bridge in batik. If the text is simple enough for the text to be + drawn in the PDF as with all other text then this sets the TextPainter to use + the PDFTextPainter. This inserts the text directly into the PDF using the drawString method on the PDFGraphics2D.

Text is considered simple if the + font is available, the font size is useable and there are no tspans or other + complications. This can make the resulting PDF significantly + smaller.

+ PDF Links +

To support links in PDF another batik + element bridge is used. The PDFAElementBridge creates a PDFANode which inserts + a link into the PDF document via the PDFGraphics2D.

Since links are positioned on the page without any transforms then we need to transform the + coordinates of the link area so that they match the current position of the a + element area. This transform may also need to account for the svg being + positioned on the page.

+ Images +

Images are normally drawn + into the PDFGraphics2D. This then creates a bitmap of the image data that can + be inserted into the PDF document.

As PDF can support jpeg images then another + element bridge is used so that the jpeg can be directly inserted into the PDF.

+ PDF Transcoder +

Batik provides a mechanism to + convert SVG into various formats. Through FOP we can convert an SVG document + into a single paged PDF document. The page contains the SVG drawn as best as + possible on the page. There is a PDFDocumentGraphics2D that creates a + standalone PDF document with a single page. This is then drawn into by batik in + the same way as with the PDFGraphics2D.

+ Other Outputs +

When rendering to AWT the SVG is simply drawn onto the + awt canvas using batik.

The PS Renderer uses a similar technique as the + PDF Renderer.

The SVG Renderer simply embeds the SVG inside an svg + element.

+ +

+ + + + diff --git a/src/documentation/content/xdocs/design/understanding/book.xml b/src/documentation/content/xdocs/design/understanding/book.xml deleted file mode 100644 index 576d556f2..000000000 --- a/src/documentation/content/xdocs/design/understanding/book.xml +++ /dev/null @@ -1,43 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/src/documentation/content/xdocs/design/understanding/images.xml b/src/documentation/content/xdocs/design/understanding/images.xml deleted file mode 100644 index fc40a64d6..000000000 --- a/src/documentation/content/xdocs/design/understanding/images.xml +++ /dev/null @@ -1,135 +0,0 @@ - - - - -

- Images -

- - -

- Images in FOP - -

Images may only be needed to be loaded when the image is rendered to the -output or to find the dimensions.
-An image url may be invalid, this can be costly to find out so we need to -keep a list of invalid image urls.

We have a number of different caching schemes that are possible.

All images are referred to using the url given in the XSL:FO after -removing "url('')" wrapping. This does -not include any sort of resolving such as relative -> absolute. The -external graphic in the FO Tree and the image area in the Area Tree only -have the url as a reference. -The images are handled through a static interface in ImageFactory.

- -

- Threading - -

In a single threaded case with one document the image should be released -as soon as the renderer caches it. If there are multiple documents then -the images could be held in a weak cache in case another document needs to -load the same image.

- -

In a multi threaded case many threads could be attempting to get the same -image. We need to make sure an image will only be loaded once at a -particular time. Once a particular document is finished then we can move -all the images to a common weak cache.

- -

- Caches -

- LRU -

All images are in a common cache regardless of context. To limit the size -of the cache the LRU image is removed to keep the amount of memory used -low. Each image can supply the amount of data held in memory.

- -

- Context -

Images are cached according to the context, using the FOUserAgent as a key. -Once the context is finished the images are added to a common weak hashmap -so that other contexts can load these images or the data will be garbage -collected if required.

If images are to be used commonly then we cannot dispose of data in the -FopImage when cached by the renderer. Also if different contexts have -different base directories for resolving relative url's then the loading -and caching must be separate. We can have a cache that shares images among -all contexts or only loads an image for a context.

- -

The cache uses an image loader so that it can synchronize the image -loading on an image by image basis. Finding and adding an image loader to -the cache is also synchronized to prevent thread problems.

- -

- Invalid Images - -

-If an image cannot be loaded for some reason, for example the url is -invalid or the image data is corrupt or an unknown type. Then it should -only attempt to load the image once. All other attempts to get the image -should return null so that it can be easily handled.
-This will prevent any extra processing or waiting.

- -

- Reading -

Once a stream is opened for the image url then a set of image readers is -used to determine what type of image it is. The reader can peek at the -image header or if necessary load the image. The reader can also get the -image size at this stage. -The reader then can provide the mime type to create the image object to -load the rest of the information.

- -

- Data - -

The data usually need for an image is the size and either a bitmap or the -original data. Images such as jpeg and eps can be embedded into the -document with the original data. SVG images are converted into a DOM which -needs to be rendered to the PDF. Other images such as gif, tiff etc. are -converted into a bitmap. -Data is loaded by the FopImage by calling load(type) where type is the type of data to load.

- - -

- Rendering - -

Different renderers need to have the information in different forms.

- - -

- PDF -

original data: JPG, EPS
bitmap: gif, tiff, bmp, png
other: SVG

- -

- PS -

bitmap: JPG, gif, tiff, bmp, png
other: SVG

- -

- awt -

bitmap: JPG, gif, tiff, bmp, png
other: SVG

- -

The renderer uses the url to retrieve the image from the ImageFactory and -then load the required data depending on the image mime type. If the -renderer can insert the image into the document and use that data for all -future references of the same image then it can cache the reference in the -renderer and the image can be released from the image cache.

- - - - diff --git a/src/documentation/content/xdocs/design/understanding/pdf_library.xml b/src/documentation/content/xdocs/design/understanding/pdf_library.xml deleted file mode 100644 index e7301f6b1..000000000 --- a/src/documentation/content/xdocs/design/understanding/pdf_library.xml +++ /dev/null @@ -1,76 +0,0 @@ - - - - -

- PDF Library -

- - -

- PDF Library - -

The PDF Library is an independant package of classes in FOP. These class -provide a simple way to construct documents and add the contents. The -classes are found in org.apache.fop.pdf.*.

- -

- PDF Document -

This is where most of the document is created and put together.

It sets up the header, trailer and resources. Each page is made and added to the document. -There are a number of methods that can be used to create/add certain PDF objects to the document.

- -

- Building PDF -

The PDF Document is built by creating a page for each page in the Area Tree.

This page then has all the contents added. - The page is then added to the document and available objects can be written to the output stream.

The contents of the page are things such as text, lines, images etc. -The PDFRenderer inserts the text directly into a pdf stream. -The text consists of markup to set fonts, set text position and add text.

Most of the simple pdf markup is inserted directly into a pdf stream. -Other more complex objects or commonly used objects are added through java classes. -Some pdf objects such as an image consists of two parts.

It has a separate object for the image data and another bit of markup to display the image in a certain position on the page. -

The java objects that represent a pdf object implement a method that returns the markup for inserting into a stream. -The method is: byte[] toPDF().

- -

- Features - -

- Fonts -

Support for embedding fonts and using the default Acrobat fonts. -

- -

- Images -

Images can be inserted into a page. The image can either be inserted as a pixel map or directly insert a jpeg image. -

- -

- Stream Filters -

A number of filters are available to encode the pdf streams. These filters can compress the data or change it such as converting to hex. -

- -

- Links -

A pdf link can be added for an area on the page. This link can then point to an external destination or a position on any page in the document. -

- -

- Patterns -

The fill and stroke of graphical objects can be set with a colour, pattern or gradient. -

- -

The are a number of other features for handling pdf markup relevent to creating PDF files for FOP.

- -

- - - - diff --git a/src/documentation/content/xdocs/design/understanding/svg.xml b/src/documentation/content/xdocs/design/understanding/svg.xml deleted file mode 100644 index 74730dcd4..000000000 --- a/src/documentation/content/xdocs/design/understanding/svg.xml +++ /dev/null @@ -1,74 +0,0 @@ - - - - -

- SVG -

- -

- SVG -

SVG is rendered through Batik.

The XML from the XSL:FO document - is converted into an SVG DOM with batik. This DOM is then set as the Document - on the Foreign Object area in the Area Tree.

This DOM is then available to - be rendered by the renderer.

SVG is rendered in the renderers via an XMLHandler in the FOUserAgent. This XML handler is used to render the SVG. The - SVG is rendered by using batik. Batik converts the SVG DOM into an internal - structure that can be drawn into a Graphics2D. So for PDF we use a - PDFGraphics2D to draw into.

This creates the necessary PDF information to - create the SVG image in the PDF document.

Most of the work is done in the - PDFGraphics2D class. There are also a few bridges that are plugged into batik - to provide different behaviour for some SVG elements.

- Text Drawing -

Normally batik converts text into a set of curved - shapes.

This is handled as any other shapes when rendering to the output. This - is not always desirable as the shapes have very fine curves. This can cause the - output to look a bit bad in PDF and PS (it can be drawn properly but is not by - default). These curves also require much more data than the original - text.

To handle this there is a PDFTextElementBridge that is set when - using the bridge in batik. If the text is simple enough for the text to be - drawn in the PDF as with all other text then this sets the TextPainter to use - the PDFTextPainter. This inserts the text directly into the PDF using the drawString method on the PDFGraphics2D.

Text is considered simple if the - font is available, the font size is useable and there are no tspans or other - complications. This can make the resulting PDF significantly - smaller.

- PDF Links -

To support links in PDF another batik - element bridge is used. The PDFAElementBridge creates a PDFANode which inserts - a link into the PDF document via the PDFGraphics2D.

Since links are positioned on the page without any transforms then we need to transform the - coordinates of the link area so that they match the current position of the a - element area. This transform may also need to account for the svg being - positioned on the page.

- Images -

Images are normally drawn - into the PDFGraphics2D. This then creates a bitmap of the image data that can - be inserted into the PDF document.

As PDF can support jpeg images then another - element bridge is used so that the jpeg can be directly inserted into the PDF.

- PDF Transcoder -

Batik provides a mechanism to - convert SVG into various formats. Through FOP we can convert an SVG document - into a single paged PDF document. The page contains the SVG drawn as best as - possible on the page. There is a PDFDocumentGraphics2D that creates a - standalone PDF document with a single page. This is then drawn into by batik in - the same way as with the PDFGraphics2D.

- Other Outputs -

When rendering to AWT the SVG is simply drawn onto the - awt canvas using batik.

The PS Renderer uses a similar technique as the - PDF Renderer.

The SVG Renderer simply embeds the SVG inside an svg - element.

- -

- - - - diff --git a/src/documentation/content/xdocs/design/understanding/xml_parsing.xml b/src/documentation/content/xdocs/design/understanding/xml_parsing.xml deleted file mode 100644 index 9dc2646c3..000000000 --- a/src/documentation/content/xdocs/design/understanding/xml_parsing.xml +++ /dev/null @@ -1,60 +0,0 @@ - - - -

- XML Parsing -

- -

- XML Input -

The xml document is always handled internally as SAX. The SAX events - are used to read the elements, attributes and text data of the FO document. - After the manipulation of the data the renderer writes out the pages in the - appropriate format. It may write as it goes, a page at a time or the whole - document at once. Once finished the document should contain all the data in the - chosen format ready for whatever use.

FOP can take the input XML in a number of ways:

SAX Events through SAX Handler: FOTreeBuilder is the SAX Handler which is obtained through getContentHandler on Driver.
DOM (which is converted into SAX Events): The conversion of a DOM tree is done via the render(Document) method on Driver.
Data Source (which is parsed and converted into SAX Events): The Driver can take an InputSource as input. -This can use a Stream, String etc.
XML+XSLT Transformation (which is transformed using an XSLT Processor and the result is fired as SAX Events: XSLTInputHandler is used as an InputSource in the render(XMLReader, InputSource) method on Driver

The SAX Events which are fired on the SAX Handler, class FOTreeBuilder, must represent an XSL:FO document. -If not there will be an error. -Any problems with the XML being well-formed are also handled here.

- Element Mappings -

The element mapping is a hashmap of all the elements in a particular namespace. -This makes it easy to create a different object for each element. -Element mappings are static to save on memory.

To add an extension a developer can put in the classpath a jar that contains the file /META-INF/services/org.apache.fop.fo.ElementMapping. -This must contain a line with the fully qualified name of a class that implements the org.apache.fop.fo.ElementMapping interface. -This will then be loaded automatically at the start. -Internal mappings are: FO, SVG and Extension (pdf bookmarks).

- Tree Building -

The SAX Events will fire all the information for the document with start element, end element, text data etc. -This information is used to build up a representation of the FO document. -To do this for a namespace there is a set of element mappings. -When an element + namepsace mapping is found then it can create an object for that element. -If the element is not found then it creates a dummy object or a generic DOM for unknown namespaces.

The object is then setup and then given attributes for the element. -For the FO Tree the attributes are converted into properties. -The FO objects use a property list mapping to convert the attributes into a list of properties for the element. -For other XML, for example SVG, a DOM of the XML is constructed. -This DOM can then be passed through to the renderer. -Other element mappings can be used in different ways, for example to create elements that create areas during the layout process or setup information for the renderer etc.

While the tree building is mainly about creating the FO Tree there are some stages that can propagate to the renderer. -At the end of a page sequence we know that all pages in the page sequence can be laid out without being effected by any further XML. -The significance of this is that the FO Tree for the page sequence may be able to be disposed of. -The end of the XML document also tells us that we can finalise the output document. -(The layout of individual pages is accomplished by the layout managers page at a time; i.e. they do not need to wait for the end of the page sequence. -The page may not yet be complete, however, containing forward page number references, for example.)

- -