Standard Image Types

The most common type of fz_image is fz_compressed_image - that is, an image based upon a fz_buffer of data in a standard compressed format, such as JPEG, PNG, TIFF, and others.

typedef struct fz_compressed_buffer_s
{
fz_compression_params params;
fz_buffer *buffer;
} fz_compressed_buffer;

The data is held in the buffer field, and the details of the compression used are given in the params field, of type fz_compression_params:

struct fz_compression_params_s
{
   int type;
   union {
      struct {
         int color_transform; /* Use -1 for unset */
      } jpeg;
      struct {
         int smask_in_data;
      } jpx;
      struct {
         int columns;
         int rows;
         int k;
         int end_of_line;
         int encoded_byte_align;
         int end_of_block;
         int black_is_1;
         int damaged_rows_before_error;
      } fax;
      struct
      {
         int columns;
         int colors;
         int predictor;
         int bpc;
      }
      flate;
      struct
      {
         int columns;
         int colors;
         int predictor;
         int bpc;
         int early_change;
      } lzw;
   } u;
};

enum
{
   FZ_IMAGE_UNKNOWN = 0,

   /* Uncompressed samples */
   FZ_IMAGE_RAW,

   /* Compressed samples */
   FZ_IMAGE_FAX,
   FZ_IMAGE_FLATE,
   FZ_IMAGE_LZW,
   FZ_IMAGE_RLD,

   /* Full image formats */
   FZ_IMAGE_BMP,
   FZ_IMAGE_GIF,
   FZ_IMAGE_JPEG,
   FZ_IMAGE_JPX,
   FZ_IMAGE_JXR,
   FZ_IMAGE_PNG,
   FZ_IMAGE_PNM,
   FZ_IMAGE_TIFF,
};

/*
   fz_compressed_image_buffer: Retrieve the underlying compressed
   data for an image.

   Returns a pointer to the underlying data buffer for an image,
   or NULL if this image is not based upon a compressed data
   buffer.

   This is not a reference counted structure, so no reference is
   returned. Lifespan is limited to that of the image itself.
*/
fz_compressed_buffer *fz_compressed_image_buffer(fz_context *ctx, fz_image *image);

The easiest way to tell if an image is a compressed image is to request its underlying buffer. If it returns NULL, you know it is not this sort of image.

19.2.2 Decoded

The next most common type of image is based upon a decoded fz_pixmap. These are generally only used if the pixmap takes less storage than the compressed data would.

/*
   fz_pixmap_image_tile: Retried the underlying fz_pixmap
   for an image.

   Returns a pointer to the underlying fz_pixmap for an image,
   or NULL if this image is not based upon an fz_pixmap.

   No reference is returned. Lifespan is limited to that of
   the image itself. If required, use fz_keep_pixmap to take
   a reference to keep it longer.
*/
fz_pixmap *fz_pixmap_image_tile(fz_context *ctx, fz_pixmap_image *cimg);

The easiest way to tell if an image is a decoded image is to request its underlying tile. If it returns NULL, you know it is not this sort of image.

19.2.3 Display List

The final standard sort of image in MuPDF (though more types may of course be added in future) is that based upon a display list.

We use this to easily embed one file format within another. For example, EPUB files frequently contain SVG images for title pages. We open the SVG image as a separate document, run it to a display list, and close the document. We can then create an image from the display list, and use this in the HTML flow of the EPUB document.

These images maintain the properties of the original (vector-based) document in that they remain scalable even after conversion to an image.

19.2 Standard Image Types

19.2.1 Compressed

19.2.2 Decoded

19.2.3 Display List