This tutorial illustrates how to encode a DjVu file.

Step 1: Initialization

To use DjVu SDK, you firstly include several headers.

#include "cel_storage.h" // for DiskStorageWithRollback
#include "djv_djvuencoder.h" // for DjVu::DjVuEncoder
using namespace Celartem;
using namespace Celartem::DjVu;

Since the base library is shared with PixelLive SDK, they're in Celartem namespace while DjVu related classes are in Celartem::DjVu namespace.

Step 2: Preparing encode parameters

Now, let's prepare the encode parameters. All the encode parameters are in DjVu::DjVuEncoder::Params structure and the most easiest declaration can be like the following:

DjVuEncoder::Params params;

You can optionally initialize parameters by loading one of the existing profiles using DjVu::DjVuEncoder::Params::loadFromProfile function:

params.loadFromProfile("scan300");

A profile is a set of parameters, which can be identified by a name. The profiles can be shared between applications such as Document Express Enterprise and you can use the same encode parameters to these applications if you specify the predefined profile names. For more information of the profiles, see Profile.

Anyway, after loading the profile, you can still change each parameter if you want.

Step 3: Creating encoder instance

DjVu::DjVuEncoder is the main object to encode DjVu pages and it can be initialized like the following:

AutoPtr<DjVuEncoder> encoder = DjVuEncoder::create(params);

The code configures the encoder according to the specified parameter and modifications to param after this does not change the encoder configuration. If you want to encode DjVu files with other parameters, you should create another DjVu::DjVuEncoder instance.

Step 4: Adding pages

Now you can add the pages to that DjVu::DjVuEncoder instance.

// assuming 3000x4000 RGB (300 dpi) image input
size_t dpi = 300;
size_t width = 3000;
size_t height = 4000;
long stride = (long)width * 3; // bytes-per-line; a R-G-B pixel consumes 3 bytes
unsigned char* buf = new unsigned char[stride * height];
//
// TODO: Insert your code to create a page image here
//
// add the page to the encoder
encoder->addPage(
    buf, stride, pmRGB8, width, height, dpi,
// release the allocated buffer
delete[] buf;

DjVu::DjVuEncoder::addPage function encode the input page image into DjVu but it does not return any data directly. If you have more than one page, call DjVu::DjVuEncoder::addPage function for every page.

Step 5: Finalizing pages

It's a little difficult to understand what "finalize" actually means but it's the most important part for encoding DjVu files. The following code finalizes the DjVu encode:

AutoPtr<Chunk> djvm = encoder->finalizeSession();

The function returns the encoded result in DjVu::Chunk, which is called DJVM. DJVM contains all the information for a DjVu document (a document consists of pages) and normally this is the data to be saved to a file.
For more Chunk operations, see Step 6: Accessing to the actual chunks.

Warning: Without setting appropriate license script, encoding function (DjVuEncode feature) will stop working after 2 weeks from the its built time. See License System for more information.

Step 6: Writing to a file

In this step, you should create a DiskStorageWithRollback instance for writting out DjVu file.

AutoPtr<DiskStorageWithRollback> storage = DiskStorageWithRollback::create("myfirst.djvu", accessWrite);
// write the djvu chunks
IFF::serialize(storage, djvm);
// commit the changes to the storage.
storage->commit();

DiskStorageWithRollback class rollbacks the write operations on the output file unless you explicitly call DiskStorageWithRollback::commit function. This ensures that the file is not in half-done status. If the writing operation overwrites the existing file, the rollback (revert) process will recover the original file. if the file by the specified name does not exist, the rollback process will remove the garbage file.
There're also other Storage classes. For more information about them, see Storage Class Factory Functions.

In the case above, IFF::serialize function may fail if there're some issues on the chunk (but it's unlike to occur in the case anyway) and on the failure case, the function throws an exception and then DiskStorageWithRollback::commit is not called and the data written to the storage is rollbacked correctly.