This tutorial illustrates how to encode a DjVu file.
To use DjVu SDK, you firstly include several headers.
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:
You can optionally initialize parameters by loading one of the existing profiles using DjVu::DjVuEncoder::Params::loadFromProfile function:
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.
DjVu::DjVuEncoder is the main object to encode DjVu pages and it can be initialized like the following:
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.
Now you can add the pages to that DjVu::DjVuEncoder instance.
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.
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:
The function returns the encoded result in DjVu::Chunk, which is called
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.
In this step, you should create a DiskStorageWithRollback instance for writting out DjVu file.
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.