Mercurial > hgrepos > Python2 > PyMuPDF

comparison mupdf-source/docs/reference/c/fitz/pixmap.md @ 2:b50eed0cc0ef upstream

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. The directory name has changed: no version number in the expanded directory now.
author Franz Glasner <fzglas.hg@dom66.de>
date Mon, 15 Sep 2025 11:43:07 +0200
parents
children
comparison
equal deleted inserted replaced
1:1d09e1dec1d9 2:b50eed0cc0ef
1 # Pixmaps
2
3 A pixmap is an 8-bit per component raster image. Each pixel is packed with
4 process colorants, spot colors, and alpha channel in that order. If an alpha
5 channel is present, the process colorants are pre-multiplied with the alpha
6 value.
7
8 typedef struct {
9 int w, h; // Width and height
10 int x, y; // X and Y offset
11 int n; // Number of components in total (colors + spots + alpha)
12 int s; // Number of components that are spot colors
13 int alpha; // True if alpha channel is present
14 int stride; // Number of bytes per row
15 int xres, yres; // Resolution in dots per inch.
16 fz_colorspace *colorspace; // Colorspace of samples, or NULL if alpha only pixmap.
17 unsigned char *samples;
18 private internal fields
19 } fz_pixmap;
20
21 fz_pixmap *fz_keep_pixmap(fz_context *ctx, fz_pixmap *pix);
22 void fz_drop_pixmap(fz_context *ctx, fz_pixmap *pix);
23
24 There are too many pixmap constructors. Here is the only one you should need.
25
26 fz_pixmap *fz_new_pixmap(fz_context *ctx, fz_colorspace *cs, int w, int h, fz_separations *seps, int alpha);
27
28
29 A newly created pixmap has uninitialized data. The samples must either be
30 cleared or overwritten with existing data before the pixmap can be safely used.
31
32 `void fz_clear_pixmap(fz_context *ctx, fz_pixmap *pix);`
33 : Clear the pixmap to black.
34
35 `void fz_clear_pixmap_with_value(fz_context *ctx, fz_pixmap *pix, int value);`
36 : Clear the pixmap to a grayscale value `0..255`, where `0` is black and
37 `255` is white. The value is automatically inverted for subtractive
38 colorspaces.
39
40 `void fz_fill_pixmap_with_color(fz_context *ctx, fz_pixmap *pix, fz_colorspace *colorspace, float *color, fz_color_params color_params);`
41 : Fill the pixmap with a solid color.
42
43 `void fz_unpack_tile(fz_context *ctx, fz_pixmap *dst, unsigned char *src, int n, int depth, size_t stride, int scale);`
44 : Unpack pixel values from source data to fill in the pixmap samples. `n`
45 is the number of samples per pixel, `depth` is the bit depth (`1`, `2`,
46 `4`, `8`, `16`, `24`, or `32`), `stride` is the number of bytes per
47 row. If `scale` is non-zero, it is the scaling factor to apply to the
48 input samples to map them to the 8-bpc pixmap range. Pass `1` to the
49 scale for indexed images, and `0` for everything else. If there are
50 more components in the source data than the destination, they will be
51 dropped. If there are fewer components in the source data, the pixmap
52 will be padded with `255`.
53
54
55
56 Some functions can create a pixmap and initialize its samples in one go:
57
58 .. code-block:: c
59
60 fz_pixmap *fz_new_pixmap_from_8bpp_data(fz_context *ctx, int x, int y, int w, int h, unsigned char *data, int stride);
61 fz_pixmap *fz_new_pixmap_from_1bpp_data(fz_context *ctx, int x, int y, int w, int h, unsigned char *data, int stride);
62
63
64 Pixmaps can be tinted, inverted, scaled, gamma corrected, and converted to other colorspaces.
65
66
67
68 `void fz_invert_pixmap(fz_context *ctx, fz_pixmap *pix);`
69 : Invert the pixmap samples.
70
71 `void fz_tint_pixmap(fz_context *ctx, fz_pixmap *pix, int black, int white);`
72 : Map black to black and white to white. The black and white colors are
73 represented as a packed RGB integer. `0xFFFFFF` is white, `0xFF0000` is
74 red, and `0x000000` is black.
75
76 `void fz_gamma_pixmap(fz_context *ctx, fz_pixmap *pix, float gamma);`
77 : Apply a gamma correction curve on the samples. A typical use is to
78 adjust the gamma curve on an inverted image by applying a correction
79 factor of 1/1.4.
80
81 `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);`
82 : Convert the source pixmap into the destination colorspace. Pass `NULL`
83 for the `default_cs` parameter.
84
85 `fz_pixmap *fz_scale_pixmap(fz_context *ctx, fz_pixmap *src, float x, float y, float w, float h, const fz_irect *clip);`
86 : Scale the pixmap up or down in size to fit the rectangle. Will return
87 `NULL` if the scaling factors are out of range. This applies fancy
88 filtering and will anti-alias the edges for subpixel positioning if
89 using non-integer coordinates. If the clip rectangle is set, the
90 returned pixmap may be subset to fit the clip rectangle. Pass `NULL` to
91 the clip if you want the whole pixmap scaled.