A PixelLive SDK Simple Tutorial

This tutorial illustrates how to load/export a image file.

Step 1: Initialization

To initialize PixelLive system, you should create a PixelLiveSystem instance. For this operation, you should include pxl_pixellive.h and specify Celartem namespace.

#include "pxl_pixellive.h"
using namespace Celartem;

...

AutoPtr<PixelLiveSystem> system = PixelLiveSystem::create();

Step 2: Creating a Storage Instance

In this step, you should create a Storage instance from an image file.

AutoPtr<DiskStorage> storage = Storage::create("myimage.tif");

The Storage class is the most easiest one to load files from local disk or a http based web servers. The following code is trying to load image from a web server:

AutoPtr<Storage> storage = Storage::create("http://sample.celartem.com/images/mrsaito.jpg");

There're also other Storage classes. For more information about them, see Storage Class Factory Functions.

Step 3: Creating a Doc Instance

You should create a Doc instance from the Storage instance. Usually, you can use PixelLiveSystem instance to load a new Doc instance from the Storage instance.

AutoPtr<Doc> doc = system->load(storage);

Step 4: Creating an Image Instance

The Doc instance manages information about the image file but not the image data. For image data, you should create an Image instance from the Doc instance.

AutoPtr<Image> image = doc->createImage();

Step 5: Manipulating the Image

Now, it is the time to manipulate the image data. If you want to enlarge the image twice, the code below does it for you:

AutoPtr<Image> imageOut = Scale(image, 2.0);

For use of Scale function, you should include pxl_imageutils.h and specify the ImageUtils namespace explicitly or implicitly. For other utility functions, see Factory Functions for Image Classes.

Step 6: Accessing to Raw Image Data

If you want to display and/or print the image, you should access to the raw image data. In such case, you should create an ImageLock instance from the Image instance to load the raw image data.

AutoPtr<ImageLock> imLock = imageOut->lock();

Now you can load the raw data by ImageLock::read function. The code below loads the raw data corresponding to the area of 300x200 started from (100,100).

ssize_t rowStride;
const u8 *raw = imLock->read(&rowStride, Rect(100,100,300,200));

The rowStride variable in this code stores the relative position of the next line and usually called "Row Stride". Although it is usually the multiple of the width and bytes-per-pixel, it may contain some padding bytes (due to the some internal consistency). And it may be a negative value if the image is stored as bottom to top order. See Accessing to Raster Image Data for more information.
Anyway, the returned value, raw is a pointer to the memory block that stores the raw image. You can only read the memory block; you should not write on it. In PixelLive SDK, you could not modify the raw image from Image instances.

Step 7: Exporting the Image

You can export the Image instance to a file using the functions defined in pxl_imageexport.h. The export functions are in ExportUtils namespace and you should specify it. The following code illustrates how to export the Image instance as MrSID file using ExportUtils::exportAsMrSID function.

AutoPtr<DiskStorageWithRollback> storageOut
    = DiskStorageWithRollback::create("output.sid", accessWrite);

MrSIDExportParam param;
exportAsMrSID(storageOut, imageOut);

storageOut->commit();

We recommend you should use DiskStorageWithRollback instead of DiskStorage since it has rollback feature and suitable for exporting the image.
For the formats which are natively supported by PixelLive SDK, see Image Export Functions.

Advanced: Replacing the input file with DiskStorageWithRollback

Usually, the input file is locked by the instances you've created and you cannot overwrite it with DiskStorageWithRollback class.
But it is possible to overwrite the file on the fly; all you have to do is to release any instances that locks the file before calling DiskStorageWithRollback::commit method.

AutoPtr<DiskStorageWithRollback> storageOut
    = DiskStorageWithRollback::create("myimage.tif" /* same to input file name*/, accessWrite);

MrSIDExportParam param;
exportAsTIFF(storageOut, imageOut);

// release all the instances that locks the input file.
storage = NULL;
doc = NULL;
image = NULL;
imageOut = NULL;

storageOut->commit();

See also:

Image Export Functions, DiskStorageWithRollback

---

This document is automatically generated using doxygen 1.5.4 at Fri Jun 27 18:22:54 2008.