---

Images

libpdf++ supports adding images to the document. In libpdf++, an image is specified by the following parameters:

• Image width (in pixels)
• Image height (in pixels)
• Image resolution (in dot-per-inch, optional)
• Channel per pixel (e.g. 3 for RGB colour space)
• Number of bits per channel
• Colour space
• Pixel array

All these parameters are stored in the image::CHeader class, except the pixel array. The image::CImage class contain an image header and the pixel array. Read its documentation for details.

libpdf++ will not support reading an image from a file (except JPEG, see below). As a result, you will have to read the image yourself and provide libpdf++ with the above parameters.

To add an image to the document, you have to make an image::CImage object with the above parameters. the image::CImage class is a container of the above parameters. You may have to write code like:

    image::CImage image( image::CHeader( width, height, channel_per_pixel,
                                         bit_per_pixel, colour_space,
                                         x_resolution, y_resolution ),
                         pixels ) ;
    graph::CImage *pdf_image = new graph::CImage( image, graph::CImage::DCT ) ;
    doc.AddXObj( pdf_image ) ;

Please refer to the documentation of the image::CImage and image::CHeader classes for the meaning of the parameters.

Once you have an image, you can add it by calling CDoc::AddXObj(). Adding the image to the document doesn't mean that it will appear in the document. It just put it in the document's resources.

After adding it to the document, you have to draw it on a page to make it appear. The function to do it is CPage::DrawXObj().

    // suppose we have a graph::CImage object called pdf_image
    // just from the above
    page.DrawXObj( pdf_image, 100, 100, image.Header( ).Width( ),
                                        image.Header( ).Height( ) ) ;

This way, the image will appear on the page in the coordinate (100,100) with its original width and height. You can draw the image multiple times in any pages, but the actual pixels will just appear in the PDF file once. Both position and width and height are in user space units (1/72 inches by default).

libpdf++ supports three kinds of compression of image data: uncompressed, deflate and DCT. I am not sure if "uncompressed" can be treated as one kind of "compression", but deflate and DCT surely can. The deflate aglorithm is a patent free, fast and most importantly lossless compression. It is used by the zip family of compressors and the mightly PNG image format. On the other hand, DCT is a lossy compression aglorithm. It is being widely used by JPEG images. There are others compression "filters" supported by the PDF specification, but personally I think these two are enough.

Application that use libpdf++ should use the DCT (i.e. JPEG) for realistic photographs, such as scanned images or digital camera outputs; while use deflate (i.e. PNG) for line art, hard edge images. This can ensure you will get a good compression ratio and won't affect much of the image quality.

libpdf++ supports adding a JPEG image directly, without decompressing the image pixels. This is done by the CJpegImage class. This is because the format of the JPEG file is the same as the image stream in the PDF file, so libpdf++ can just copy the bytes of JPEG file to the PDF file. In this case, we can save a lot of time and code to do the decompression and compression.

The usage of the CJpegImage is as follows:

    graph::CJpegImage *pdf_image = new graph::CJpegImage( "main.jpg" ) ;
    page.DrawXObj( pdf_image, 100, 100, image.Header( ).Width( ),
                                        image.Header( ).Height( ) ) ;

You just give the filename of JPEG image file. It is much more simple than the previous one. You should use this method whenever possible. Although the pixel data in the JPEG file will not be decoded, its header will be read to get the image pararmeters like width and height.

---