png++ Documentation

0.2.1

Introduction

This is the documentation for png++ the C++ wrapper for libpng. This page documents png++ version 0.2.1.

Png++ aims to provide simple yet powerful C++ interface to libpng, the PNG reference implementation library. Png++ is free software distributed under a modified variant of BSD license.

News

• Added support for tRNS chunk.
• Added non-std IO streams support.
• Fixed 16-bit endianness problems.
• Improved test script.

Getting started

The following code demonstrates how to read and write PNG images using png++:

 png::image< png::rgb_pixel > image("input.png");
 image.write("output.png");

The code reads an image from the file named input.png, then writes the image to a file named output.png. The image class template allows you to specify the desired pixel type for the image data. The available pixel types include: RGB, Grayscale and Indexed pixels. Some of the pixel types can have an alpha channel.

The png++ naturally supports reading PNG images of any color type into RGB or Grayscale pixel buffers (with optional alpha channel). This is particularly useful for an image viewer if it needs to display the PNG image on, for example, RGB device regardless of the image color type.

On the other hand one might want to read only images of particular type. With png++ you can specify it this way:

 png::image< png::rgb_pixel > image("rgb.png", png::require_color_space< png::rgb_pixel >());

Installing

Png++ comes as a set of header files and does not require compilation to be installed. For the same reason there are no binary packages for png++.

Prerequisites

• png++ works with libpng-1.2.x.
• png++ compiles with g++-4.1 and g++-4.2. Other version should work well too.
• png++ relies on GNU make for compiling tests and examples; in particular it uses "remaking makefiles" feature
• Documentation is produced using doxygen. See the bottom of this page for doxygen version used to compile these docs.

Installing png++

Follow these instructions in order to install png++:

1. Unpack source package:

   $ tar -zxf png++-0.2.x.tar.gz -C ~/src 

2. Go to your brand new png++ sources directory:

   $ cd ~/src/png++-0.2.x 

3. Issue make to test how it's doing:

   $ make 

   This will compile examples in the example directory. If everything goes well, try

   $ make test 

   (or make check which is the same as above) to run the test suite. If tests do not produce error messages then probably all is OK.
4. Now you can create documentation (optional). Use

   $ make docs 

   to run doxygen in the sources directory.
5. Now it is time to become root and install png++ into your system. It's OK to issue make install under ordinary user permissions if you want to install png++ into your home directory. Run the following command:

   $ make install PREFIX=$HOME 

   to copy png++ header files to ~/include/png++ and documentation files to ~/share/doc/png++-0.2.x. Without a PREFIX png++ installs to /usr/local.

Working with images

In png++ you can create new images like this:

 #include <png++/png.hpp>
 //...
 png::image< png::rgb_pixel > image(128, 128);
 for (size_t y = 0; y < image.get_height(); ++y)
 {
     for (size_t x = 0; x < image.get_width(); ++x)
     {
         image[y][x] = png::rgb_pixel(x, y, x + y);
         // non-checking equivalent of image.set_pixel(x, y, ...);
     }
 }
 image.write("rgb.png");

Optionally, you may specify

 image.set_interlace_type(png::interlace_adam7)

to produce an interlaced image.

If you are writing an indexed colors image, you should provide a palette (colormap). One of the ways to do this is the following:

 #include <png++/png.hpp>
 //...
 png::image< png::index_pixel > image;
 png::palette pal(256);
 for (size_t i = 0; i < pal.size(); ++i)
 {
     pal[i] = png::color(i, 255 - i, i);
 }
 image.set_palette(pal);
 ...
 image.write("palette.png");

It is not absolutely necessary to have the whole image data in memory in order to write a PNG file. You can use generator class template to write the image row-by-row. An example of this is provided in example/pixel_generator.cpp bundled with the sources package.

The same holds for reading images too. You can use consumer class template in order to read the image data row-by-row. This might help in applications which have to deal with large PNG images but do not want to read the entire image into memory.

You can read or write images from/to generic IO stream, not only file on disk. Check out image::read(std::istream&), image::write(std::ostream&) overloads in the reference manual.

Compiling your programs

Use the following command to compile your program:

$ g++ -c example.cpp `libpng-config --cflags` 

and the following to link it:

$ g++ -o example example.o `libpng-config --ldflags` 

When compiling you should add -I $PREFIX/include if you have installed png++ to non-standard location, like your home directory.

In your program, the line

 #include <png++/png.hpp>

brings in all the header files in png++ which should be suitable for the most of the applications. You may include only the headers you really use, for example:

 #include <png++/image.hpp>
 #include <png++/rgb_pixel.hpp>

If do not want to install png++ headers you still can compile your programs. Just create a subdirectory named png++ somewhere in your project tree and copy all of the .hpp files in png++ distribution there. Then use appropriate compiler options to add this directory into the header search path.

Further reading

• To get information about specific features, use reference (can be reached from the top of this page).
• If you are looking for more example code, please go to the example/ directory of the source distribution. You may also find sources in the test/ directory insightful (well, somewhat).
• Have a question? Check out Getting help section below.
• Of course, your ultimate source for learning is the source code. :-)

Download

The project is hosted at Savannah: http://savannah.nongnu.org/projects/pngpp/

Released source packages can be found here: http://download.savannah.nongnu.org/releases/pngpp/

Also, you can check out sources directly from SVN repository: svn://svn.sv.nongnu.org/pngpp/trunk/ or http://svn.sv.nongnu.org/pngpp/trunk/ (for people w/o outgoing svn).

Online version of this documentation can be found here: http://www.nongnu.org/pngpp/doc/0.2.1/index.html

Bugs

The following is a list of known bugs and limitations:

• Lacks support for output transformations
• Lacks support for optional/unknown chunks in PNG data stream
• Documentation sucks ;-)

To report bugs, please use Savannah bug tracker: http://savannah.nongnu.org/bugs/?group=pngpp&func=additem

Do not forget to check if the bug was already filed. :-)

Getting help

There is a mailing list for developers: http://lists.nongnu.org/mailman/listinfo/pngpp-devel

You can also contact me by dropping a mail to <alex.shulgin@gmail.com>.

Happy hacking!

Alex Shulgin

---