Game resources can soon grow very large in size, so it would be great if we could somehow compress these files so that they take up less space in our installation package, particularly if there are any restrictions on the maximum size an install package can have.
Marmalade provides just such a feature in the form of Derbh archives, which is very similar to compression systems such as ZIP that you will no doubt be familiar with. Derbh supports multiple compression algorithms, including the standard LZMA and also its own proprietary algorithm, which can achieve improved compression by operating over multiple files simultaneously.
The Marmalade SDK provides an API which allows us to load compressed files as easily as if they were provided as individual uncompressed files. A command-line utility called DZip is also provided to generate the archives in the first place.
To create a Derbh archive, the first thing we have to do is create a DZip Configuration File (DCL). This file is passed to the DZip utility to specify the source files and how they should be compressed. Here is a simple example of a DCL file taken from the Skiing example project for this chapter:
archive data-ramdata-gles1skiing.dz basedir data basedir data-ramdata-gles1 file textEN.str 0 dz file models.group.bin 0 dz file flagflag.group.bin 0 dz file rock ock.group.bin 0 dz file skierskierskiing.group.bin 0 dz file soundsound.group.bin 0 dz file tree ree.group.bin 0 dz file uiui.group.bin 0 dz
The first line uses the archive keyword to specify the name of the Derbh archive to be created, which is normally given the extension .dz. It is possible to create several archives at once by simply adding further archive entries.
The basedir keyword allows us to specify a directory in which to search for the files that will make up the archive. In the previous example we specify the directories data and data-ramdata-gles1.
Next we list all the files that will be added to the archive using the file keyword. The first parameter is the name of the file to include, which should be relative to one of the directories specified by the basedir keyword. This is followed by a number and a compression type. The number refers to which archive the file should be added to, with zero being the first archive specified in the DCL file.
There are a number of compression types available, although note that not all of them actually compress the source file! We can use a different compression type for each file if we so wish. The following table shows the types available:
|
Type |
Description |
|---|---|
|
Uses lzma compression, which generally gives the best compression ratio and has a reasonable decompression speed. | |
|
Marmalade's own compression format, which gives a good compression ratio and decompression speed. | |
|
Uses zlib compression, which provides a less optimal compression ratio but has a very good decompression speed. | |
|
A block of zeros the same size as the file will be added to the archive. Can be used for debugging purposes, for example, if we need to detect corrupted files. | |
|
The file is included uncompressed in the archive. In the case of a file type that is already compressed, this can produce a smaller end file size for the archive than trying to compress the file. |
With the DCL file constructed, we can then build the archive file using the DZip utility. This utility can be found as the file toolsdzipdzip.exe in the Marmalade SDK install directory.
To create the archive, simply pass the name of the DCL file into the DZip utility, ensuring you run the command from within a directory where the archive and basedir entries can be located.
With a
Derbh archive created, it is then really easy to make use of it in our game. Firstly we need to add support for the Derbh API by adding derbh to the list of subprojects in the MKB file. We also need to include the derbh.h file to provide access to the API functions.
To make use of our archive file we just need to add a call to the function dzArchiveAttach, which takes a single parameter—the filename of the Derbh archive itself. From then on any call to open a file will first check to see if it exists in the Derbh archive, and if it does the data will automatically be decompressed and returned whenever we try to read from the file. It really is that simple!
We can attach more than one archive at a time as well by simply calling dzArchiveAttach for each archive we wish to use.
If a request is made for a file that doesn't appear in the archive, Marmalade will then look in the data and data-ram directories.
If we want to stop using a Derbh archive for any reason, we can either call dzArchiveDetach to remove the last archive that was attached or we can specify the archive to detach
using the dzArchiveDetachNamed function.
Note
It is important to note that only files loaded from within the application code will be accessible from an attached Derbh archive. If you are trying to start a music track with s3eAudio or a video clip with s3eVideo, these files must exist as separate files as they are loaded by the operating system native methods, which obviously will have no way of accessing a Derbh file's contents.
For most projects there is actually an even easier way of making use of Derbh archives, which doesn't require us to create a DCL file or build a Derbh file ourselves. We don't even have to attach the archive in our code! To make use of this feature, all we need to do is add the following to the deployments section of our MKB file (we'll be covering this section of the MKB file in greater detail in just a moment).
deployments
{
auto-derbh
}With this in place, the Marmalade Deployment Tool will automatically build us a Derbh archive from the relevant files in the assets section of the MKB file (again, the assets section will be discussed shortly) and will attach it before our application code starts executing.
Note
Be wary of using the automatic Derbh facility if you ever deploy files that need to be modified by your code after installation. You will not be able to modify a file once it is contained within an archive, so you would instead need to make a copy of any such files in a new location the first time your application runs.