libgamegraphics

libgamegraphics provides a standard interface to access images in different file formats, many of which are unique to a single game only.

Graphics are split into two categories - images and tilesets. An image is a single picture, while a tileset is a collection of many images. While images have width and height, a tileset often (but not always) requires all its images to be the same size.

When reading images and tilesets, there are capability flags that need to be checked to discover whether an image can be resized, whether all the images in a tileset can be resized together, or whether a tileset can have a new image inserted, and so on.

Structure

The main interface to the library is the getManager() function, which returns an instance of the Manager class. The Manager is used to query supported graphics formats, and for each supported file format it returns an instance of the ImageType or TilesetType class.

The Type class can be used to examine files and check what file format they are in, and if they are in the correct format, to open them. Successfully opening an image file produces an instance of the Image class, and opening a tileset file produces an instance of the Tileset class. The Type classes can also be used to create new files from scratch, which will again return an Image or Tileset instance.

The Image and Tileset classes are used to directly manipulate the graphics files, such as by importing/exporting image data or inserting and removing tiles.

Examples

The libgamegraphics distribution comes with example code in the form of the gamearch utility, which provides a simple command-line interface to the full functionality of the library.

For a small "hello world" example, try this:

#include <iostream>
#include <camoto/stream_file.hpp>
#include <camoto/gamegraphics.hpp>

using namespace camoto;
using namespace camoto::gamegraphics;

int main(void)
{
  // Get hold of the Manager class
  ManagerPtr manager = getManager();

  // Use the manager to look up a particular image format, in this case a
  // 256-colour PCX image.  This will fail if the image is not 256 colours,
  // but you can use img-pcx-1b4p for a 16-colour image too.
  ImageTypePtr imageType = manager->getImageTypeByCode("img-pcx-8b1p");

  // Open an image file on disk
  stream::file_sptr file(new stream::file());
  file->open("apogee.pcx");

  // We cheat here - we should check and load any supplementary files, but
  // for the sake of keeping this example simple we know this format doesn't
  // need any supps.
  camoto::SuppData supps;

  // Use the format handler to read in the file we opened.
  ImagePtr img = imageType->open(file, supps);

  // Find out the dimensions of the image.
  unsigned int width, height;
  img->getDimensions(&width, &height);
  std::cout << "This image is " << width << "x" << height << " pixels in size.\n";

  // No cleanup required because all the Ptr variables are shared pointers,
  // which get destroyed automatically when they go out of scope (and nobody
  // else is using them!)

  return 0;
}

When run, this program produces output similar to the following:

This image is 320x200 pixels in size.

More information

Additional information is available from the Camoto homepage http://www.shikadi.net/camoto.