The fz_pixmap structure is used to represent a 2 dimensional array of contone pixels. This is used throughout MuPDF, as the target of rendering from the draw device, as internal buffers during processing, and during image decoding.
A pixmap can have an arbitrary number of colour components, together with an optional alpha plane. Every component sample is represented by an unsigned char.
Pixmaps contain a set of n values per pixel, where n = c + s + a. c is the number of color components in the colorspace of a pixmap (or 0, if the colorspace is NULL). s is the number of spot colors in a pixmap (frequently 0). a is 0 if there is no alpha plane, and 1 otherwise.
The initial c entries are referred to as the ‘process’ color components. These can be either additive or subtractive dependent on the colorspace of the pixmap. Additive spaces (such as Gray, or RGB) have value 0 as dark, 255 as light. Subtractive spaces (such as CMYK) have value 0 as light (no ink), 255 as dark (full ink).
The next s entries are the spot colors represented by a pixmap. These are always in subtractive form.
The final entry (if a = 1) is the alpha value. This is 0 for completely transparent, 255 for completely opaque.
The data within a pixmap is always stored packed in ‘chunky’ format. For instance, an RGB pixmap would have data in the form: RGBRGBRGBRGB...
Alpha data is always sent as the last byte in the set corresponding to a pixel. An RGB pixmap with an alpha plane would be therefore have data of the form: RGBARGBARGBA...
A CMYK pixmap with spots for Orange and Green would have data of the form: CMYKOGCMYKOGCMYKOG...
To allow greater flexibility in the layout of the underlying memory blocks used by pixmaps, they have a ‘stride’ field. This gives the number of bytes difference from the address of the start of the representation of a pixel to the address of the start of the representation of the same pixel on the scanline below.
Normally you’d expect stride to be the same as width multiplied by the number of components in the image (including alpha), but for some cases (notably when we have pixmaps that represent a sub-rectangle of larger pixmaps) these can be much larger.
Pixmaps can frequently map onto operating system specific bitmap representations, but these sometimes require each scanline to be word aligned - again the provision of stride allows for this. Bottom up bitmaps can be implemented using a negative stride.
By convention MuPDF holds pixmaps in ‘premultipled alpha’ form. This means that when an alpha plane is present, the values for the process and spot colors are stored scaled by the alpha value.
So for a pixel with R=G=B=1, with solid alpha, we’d have values of 255, but with an alpha value of 0.5 we’d have values of 127 stored.
This format is used because it simplifies many of the plotting and compositing operations used within MuPDF.
For information on saving pixmaps, see chapter 14 Rendered Output Formats.