Pixmaps

A pixmap is an 8-bit per component raster image. Each pixel is packed with process colorants, spot colors, and alpha channel in that order. If an alpha channel is present, the process colorants are pre-multiplied with the alpha value.

typedef struct {
	int w, h; // Width and height
	int x, y; // X and Y offset
	int n; // Number of components in total (colors + spots + alpha)
	int s; // Number of components that are spot colors
	int alpha; // True if alpha channel is present
	int stride; // Number of bytes per row
	int xres, yres; // Resolution in dots per inch.
	fz_colorspace *colorspace; // Colorspace of samples, or NULL if alpha only pixmap.
	unsigned char *samples;
	private internal fields
} fz_pixmap;

fz_pixmap *fz_keep_pixmap(fz_context *ctx, fz_pixmap *pix);
void fz_drop_pixmap(fz_context *ctx, fz_pixmap *pix);

There are too many pixmap constructors. Here is the only one you should need.

fz_pixmap *fz_new_pixmap(fz_context *ctx, fz_colorspace *cs, int w, int h, fz_separations *seps, int alpha);

A newly created pixmap has uninitialized data. The samples must either be cleared or overwritten with existing data before the pixmap can be safely used.

void fz_clear_pixmap(fz_context *ctx, fz_pixmap *pix);

Clear the pixmap to black.

void fz_clear_pixmap_with_value(fz_context *ctx, fz_pixmap *pix, int value);

Clear the pixmap to a grayscale value 0..255, where 0 is black and 255 is white. The value is automatically inverted for subtractive colorspaces.

void fz_fill_pixmap_with_color(fz_context *ctx, fz_pixmap *pix, fz_colorspace *colorspace, float *color, fz_color_params color_params);

Fill the pixmap with a solid color.

void fz_unpack_tile(fz_context *ctx, fz_pixmap *dst, unsigned char *src, int n, int depth, size_t stride, int scale);

Unpack pixel values from source data to fill in the pixmap samples. n is the number of samples per pixel, depth is the bit depth (1, 2, 4, 8, 16, 24, or 32), stride is the number of bytes per row. If scale is non-zero, it is the scaling factor to apply to the input samples to map them to the 8-bpc pixmap range. Pass 1 to the scale for indexed images, and 0 for everything else. If there are more components in the source data than the destination, they will be dropped. If there are fewer components in the source data, the pixmap will be padded with 255.

Some functions can create a pixmap and initialize its samples in one go:

… code-block:: c

fz_pixmap *fz_new_pixmap_from_8bpp_data(fz_context *ctx, int x, int y, int w, int h, unsigned char *data, int stride);
fz_pixmap *fz_new_pixmap_from_1bpp_data(fz_context *ctx, int x, int y, int w, int h, unsigned char *data, int stride);

Pixmaps can be tinted, inverted, scaled, gamma corrected, and converted to other colorspaces.

void fz_invert_pixmap(fz_context *ctx, fz_pixmap *pix);

Invert the pixmap samples.

void fz_tint_pixmap(fz_context *ctx, fz_pixmap *pix, int black, int white);

Map black to black and white to white. The black and white colors are represented as a packed RGB integer. 0xFFFFFF is white, 0xFF0000 is red, and 0x000000 is black.

void fz_gamma_pixmap(fz_context *ctx, fz_pixmap *pix, float gamma);

Apply a gamma correction curve on the samples. A typical use is to adjust the gamma curve on an inverted image by applying a correction factor of 1/1.4.

fz_pixmap *fz_convert_pixmap(fz_context *ctx, fz_pixmap *source_pixmap, fz_colorspace *destination_colorspace, fz_colorspace *proof_colorspace, fz_default_colorspaces *default_cs, fz_color_params color_params, int keep_alpha);

Convert the source pixmap into the destination colorspace. Pass NULL for the default_cs parameter.

fz_pixmap *fz_scale_pixmap(fz_context *ctx, fz_pixmap *src, float x, float y, float w, float h, const fz_irect *clip);

Scale the pixmap up or down in size to fit the rectangle. Will return NULL if the scaling factors are out of range. This applies fancy filtering and will anti-alias the edges for subpixel positioning if using non-integer coordinates. If the clip rectangle is set, the returned pixmap may be subset to fit the clip rectangle. Pass NULL to the clip if you want the whole pixmap scaled.