Form XObjects

From
Jump to: navigation, search

Form XObject is a special resource object in PDF that may contain any sequence of drawing commands and graphics objects (including path objects, text objects, and sampled images). A form XObject may be painted multiple times either on several pages or at several locations on the same page - and produces the same results each time, subject only to the graphics state at the time it is invoked(drawn). Other objects of similar nature are Image XObject and Transparency Group XObject.

Not only is this shared definition economical to represent in the PDF file, but under suitable circumstances the conforming reader can optimize execution by caching the results of rendering the form XObject for repeated reuse. See section 8.10 “Form XObjects” of the PDF specification for the detailed description.

So, basically form XObject is a group of drawing commands which can be repeatedly played at some place but unlike the tiling pattern for example, it requires to be called explicitly each time one needs to draw its content at some place. Apitron PDF Kit provides a FixedContent class that can be used to create form XObjects and insert drawing commands into them.

Consider the following code demonstrating how to create and use simple form XObject:

// create output PDF file
using (FileStream outputStream = new FileStream("xobjects.pdf", FileMode.Create, FileAccess.Write))
{
    // create new PDF document
    using(FixedDocument document = new FixedDocument())
    {
        document.Pages.Add(new Page());
                
        // create XObject
        FixedContent xObject = new FixedContent("myXObject", new Boundary(0, 0, 200, 100));

        // register XObject
        document.ResourceManager.RegisterResource(xObject);

        // select fill and stroke colors
        xObject.Content.SetDeviceNonStrokingColor(new double[]{1,0,0});
        xObject.Content.SetDeviceStrokingColor(new double[]{0});                
        // create path and fill it
        Path path = new Path();
        path.AppendRectangle(10,10,150,80);                
        xObject.Content.FillAndStrokePath(path);

        // set offset
        document.Pages[0].Content.Translate(20,730);
        // append xObject to page content
        document.Pages[0].Content.AppendXObject("myXObject");

        // set offset
        document.Pages[0].Content.Translate(240,0);
        // append xObject to page  content
        document.Pages[0].Content.AppendXObject("myXObject");

        // save document
        document.Save(outputStream);
    }
}
 

You see that we create new Form XObject, define its boundaries and register it into the document's ResourceManager. It’s important to not forget to register the XObject, otherwise you won’t appear on the page as the rendering software won't be able to resolve the reference to it, and more importantly there will be no data included into the document related to this XObject. After registering, we draw this XObject twice by calling AppendXObject() on the Page.Content instance.


Below is the resulting image demonstrating two identical rectangles drawn as XObjects:

Drawing a simple form XObject


Using this technique you may reduce the file size and optimize your PDF generation routines. Commands needed to paint an object can be created only once when you define it and this definition will be reused every time the object needs to be painted. It's extremely useful when you have to paint many objects having the same appearance, like images, watermarks, stamps, every possible type of repetitive content.