Mercurial > hgrepos > Python2 > PyMuPDF

comparison mupdf-source/include/mupdf/fitz/pixmap.h @ 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 // Copyright (C) 2004-2025 Artifex Software, Inc.
2 //
3 // This file is part of MuPDF.
4 //
5 // MuPDF is free software: you can redistribute it and/or modify it under the
6 // terms of the GNU Affero General Public License as published by the Free
7 // Software Foundation, either version 3 of the License, or (at your option)
8 // any later version.
9 //
10 // MuPDF is distributed in the hope that it will be useful, but WITHOUT ANY
11 // WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
12 // FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
13 // details.
14 //
15 // You should have received a copy of the GNU Affero General Public License
16 // along with MuPDF. If not, see <https://www.gnu.org/licenses/agpl-3.0.en.html>
17 //
18 // Alternative licensing terms are available from the licensor.
19 // For commercial licensing, see <https://www.artifex.com/> or contact
20 // Artifex Software, Inc., 39 Mesa Street, Suite 108A, San Francisco,
21 // CA 94129, USA, for further information.
22
23 #ifndef MUPDF_FITZ_PIXMAP_H
24 #define MUPDF_FITZ_PIXMAP_H
25
26 #include "mupdf/fitz/system.h"
27 #include "mupdf/fitz/context.h"
28 #include "mupdf/fitz/geometry.h"
29 #include "mupdf/fitz/store.h"
30 #include "mupdf/fitz/separation.h"
31
32 /**
33 Pixmaps represent a set of pixels for a 2 dimensional region of
34 a plane. Each pixel has n components per pixel. The components
35 are in the order process-components, spot-colors, alpha, where
36 there can be 0 of any of those types. The data is in
37 premultiplied alpha when rendering, but non-premultiplied for
38 colorspace conversions and rescaling.
39 */
40
41 typedef struct fz_overprint fz_overprint;
42
43 /**
44 Return the bounding box for a pixmap.
45 */
46 fz_irect fz_pixmap_bbox(fz_context *ctx, const fz_pixmap *pix);
47
48 /**
49 Return the width of the pixmap in pixels.
50 */
51 int fz_pixmap_width(fz_context *ctx, const fz_pixmap *pix);
52
53 /**
54 Return the height of the pixmap in pixels.
55 */
56 int fz_pixmap_height(fz_context *ctx, const fz_pixmap *pix);
57
58 /**
59 Return the x value of the pixmap in pixels.
60 */
61 int fz_pixmap_x(fz_context *ctx, const fz_pixmap *pix);
62
63 /**
64 Return the y value of the pixmap in pixels.
65 */
66 int fz_pixmap_y(fz_context *ctx, const fz_pixmap *pix);
67
68 /**
69 Return sizeof fz_pixmap plus size of data, in bytes.
70 */
71 size_t fz_pixmap_size(fz_context *ctx, fz_pixmap *pix);
72
73 /**
74 Create a new pixmap, with its origin at (0,0)
75
76 cs: The colorspace to use for the pixmap, or NULL for an alpha
77 plane/mask.
78
79 w: The width of the pixmap (in pixels)
80
81 h: The height of the pixmap (in pixels)
82
83 seps: Details of separations.
84
85 alpha: 0 for no alpha, 1 for alpha.
86
87 Returns a pointer to the new pixmap. Throws exception on failure
88 to allocate.
89 */
90 fz_pixmap *fz_new_pixmap(fz_context *ctx, fz_colorspace *cs, int w, int h, fz_separations *seps, int alpha);
91
92 /**
93 Create a pixmap of a given size, location and pixel format.
94
95 The bounding box specifies the size of the created pixmap and
96 where it will be located. The colorspace determines the number
97 of components per pixel. Alpha is always present. Pixmaps are
98 reference counted, so drop references using fz_drop_pixmap.
99
100 colorspace: Colorspace format used for the created pixmap. The
101 pixmap will keep a reference to the colorspace.
102
103 bbox: Bounding box specifying location/size of created pixmap.
104
105 seps: Details of separations.
106
107 alpha: 0 for no alpha, 1 for alpha.
108
109 Returns a pointer to the new pixmap. Throws exception on failure
110 to allocate.
111 */
112 fz_pixmap *fz_new_pixmap_with_bbox(fz_context *ctx, fz_colorspace *colorspace, fz_irect bbox, fz_separations *seps, int alpha);
113
114 /**
115 Create a new pixmap, with its origin at
116 (0,0) using the supplied data block.
117
118 cs: The colorspace to use for the pixmap, or NULL for an alpha
119 plane/mask.
120
121 w: The width of the pixmap (in pixels)
122
123 h: The height of the pixmap (in pixels)
124
125 seps: Details of separations.
126
127 alpha: 0 for no alpha, 1 for alpha.
128
129 stride: The byte offset from the pixel data in a row to the
130 pixel data in the next row.
131
132 samples: The data block to keep the samples in.
133
134 Returns a pointer to the new pixmap. Throws exception on failure to
135 allocate.
136 */
137 fz_pixmap *fz_new_pixmap_with_data(fz_context *ctx, fz_colorspace *colorspace, int w, int h, fz_separations *seps, int alpha, int stride, unsigned char *samples);
138
139 /**
140 Create a pixmap of a given size, location and pixel format,
141 using the supplied data block.
142
143 The bounding box specifies the size of the created pixmap and
144 where it will be located. The colorspace determines the number
145 of components per pixel. Alpha is always present. Pixmaps are
146 reference counted, so drop references using fz_drop_pixmap.
147
148 colorspace: Colorspace format used for the created pixmap. The
149 pixmap will keep a reference to the colorspace.
150
151 rect: Bounding box specifying location/size of created pixmap.
152
153 seps: Details of separations.
154
155 alpha: Number of alpha planes (0 or 1).
156
157 samples: The data block to keep the samples in.
158
159 Returns a pointer to the new pixmap. Throws exception on failure
160 to allocate.
161 */
162 fz_pixmap *fz_new_pixmap_with_bbox_and_data(fz_context *ctx, fz_colorspace *colorspace, fz_irect rect, fz_separations *seps, int alpha, unsigned char *samples);
163
164 /**
165 Create a new pixmap that represents a subarea of the specified
166 pixmap. A reference is taken to this pixmap that will be dropped
167 on destruction.
168
169 The supplied rectangle must be wholly contained within the
170 original pixmap.
171
172 Returns a pointer to the new pixmap. Throws exception on failure
173 to allocate.
174 */
175 fz_pixmap *fz_new_pixmap_from_pixmap(fz_context *ctx, fz_pixmap *pixmap, const fz_irect *rect);
176
177 /**
178 Clone a pixmap, copying the pixels and associated data to new
179 storage.
180
181 The reference count of 'old' is unchanged.
182 */
183 fz_pixmap *fz_clone_pixmap(fz_context *ctx, const fz_pixmap *old);
184
185 /**
186 Increment the reference count for the pixmap. The same pointer
187 is returned.
188
189 Never throws exceptions.
190 */
191 fz_pixmap *fz_keep_pixmap(fz_context *ctx, fz_pixmap *pix);
192
193 /**
194 Decrement the reference count for the pixmap. When the
195 reference count hits 0, the pixmap is freed.
196
197 Never throws exceptions.
198 */
199 void fz_drop_pixmap(fz_context *ctx, fz_pixmap *pix);
200
201 /**
202 Return the colorspace of a pixmap
203
204 Returns colorspace.
205 */
206 fz_colorspace *fz_pixmap_colorspace(fz_context *ctx, const fz_pixmap *pix);
207
208 /**
209 Return the number of components in a pixmap.
210
211 Returns the number of components (including spots and alpha).
212 */
213 int fz_pixmap_components(fz_context *ctx, const fz_pixmap *pix);
214
215 /**
216 Return the number of colorants in a pixmap.
217
218 Returns the number of colorants (components, less any spots and
219 alpha).
220 */
221 int fz_pixmap_colorants(fz_context *ctx, const fz_pixmap *pix);
222
223 /**
224 Return the number of spots in a pixmap.
225
226 Returns the number of spots (components, less colorants and
227 alpha). Does not throw exceptions.
228 */
229 int fz_pixmap_spots(fz_context *ctx, const fz_pixmap *pix);
230
231 /**
232 Return the number of alpha planes in a pixmap.
233
234 Returns the number of alphas. Does not throw exceptions.
235 */
236 int fz_pixmap_alpha(fz_context *ctx, const fz_pixmap *pix);
237
238 /**
239 Returns a pointer to the pixel data of a pixmap.
240
241 Returns the pointer.
242 */
243 unsigned char *fz_pixmap_samples(fz_context *ctx, const fz_pixmap *pix);
244
245 /**
246 Return the number of bytes in a row in the pixmap.
247 */
248 int fz_pixmap_stride(fz_context *ctx, const fz_pixmap *pix);
249
250 /**
251 Set the pixels per inch resolution of the pixmap.
252 */
253 void fz_set_pixmap_resolution(fz_context *ctx, fz_pixmap *pix, int xres, int yres);
254
255 /**
256 Clears a pixmap with the given value.
257
258 pix: The pixmap to clear.
259
260 value: Values in the range 0 to 255 are valid. Each component
261 sample for each pixel in the pixmap will be set to this value,
262 while alpha will always be set to 255 (non-transparent).
263
264 This function is horrible, and should be removed from the
265 API and replaced with a less magic one.
266 */
267 void fz_clear_pixmap_with_value(fz_context *ctx, fz_pixmap *pix, int value);
268
269 /**
270 Fill pixmap with solid color.
271 */
272 void fz_fill_pixmap_with_color(fz_context *ctx, fz_pixmap *pix, fz_colorspace *colorspace, float *color, fz_color_params color_params);
273
274 /**
275 Clears a subrect of a pixmap with the given value.
276
277 pix: The pixmap to clear.
278
279 value: Values in the range 0 to 255 are valid. Each component
280 sample for each pixel in the pixmap will be set to this value,
281 while alpha will always be set to 255 (non-transparent).
282
283 r: the rectangle.
284 */
285 void fz_clear_pixmap_rect_with_value(fz_context *ctx, fz_pixmap *pix, int value, fz_irect r);
286
287 /**
288 Sets all components (including alpha) of
289 all pixels in a pixmap to 0.
290
291 pix: The pixmap to clear.
292 */
293 void fz_clear_pixmap(fz_context *ctx, fz_pixmap *pix);
294
295 /**
296 Invert all the pixels in a pixmap. All components (process and
297 spots) of all pixels are inverted (except alpha, which is
298 unchanged).
299 */
300 void fz_invert_pixmap(fz_context *ctx, fz_pixmap *pix);
301
302 /**
303 Invert the alpha of all the pixels in a pixmap.
304 */
305 void fz_invert_pixmap_alpha(fz_context *ctx, fz_pixmap *pix);
306
307 /**
308 Transform the pixels in a pixmap so that luminance of each
309 pixel is inverted, and the chrominance remains unchanged (as
310 much as accuracy allows).
311
312 All components of all pixels are inverted (except alpha, which
313 is unchanged). Only supports Grey and RGB bitmaps.
314 */
315 void fz_invert_pixmap_luminance(fz_context *ctx, fz_pixmap *pix);
316
317 /**
318 Tint all the pixels in an RGB, BGR, or Gray pixmap.
319
320 black: Map black to this hexadecimal RGB color.
321
322 white: Map white to this hexadecimal RGB color.
323 */
324 void fz_tint_pixmap(fz_context *ctx, fz_pixmap *pix, int black, int white);
325
326 /**
327 Invert all the pixels in a given rectangle of a (premultiplied)
328 pixmap. All components of all pixels in the rectangle are
329 inverted (except alpha, which is unchanged).
330 */
331 void fz_invert_pixmap_rect(fz_context *ctx, fz_pixmap *image, fz_irect rect);
332
333 /**
334 Invert all the pixels in a non-premultiplied pixmap in a
335 very naive manner.
336 */
337 void fz_invert_pixmap_raw(fz_context *ctx, fz_pixmap *pix);
338
339 /**
340 Apply gamma correction to a pixmap. All components
341 of all pixels are modified (except alpha, which is unchanged).
342
343 gamma: The gamma value to apply; 1.0 for no change.
344 */
345 void fz_gamma_pixmap(fz_context *ctx, fz_pixmap *pix, float gamma);
346
347 /**
348 Convert an existing pixmap to a desired
349 colorspace. Other properties of the pixmap, such as resolution
350 and position are copied to the converted pixmap.
351
352 pix: The pixmap to convert.
353
354 default_cs: If NULL pix->colorspace is used. It is possible that
355 the data may need to be interpreted as one of the color spaces
356 in default_cs.
357
358 cs_des: Desired colorspace, may be NULL to denote alpha-only.
359
360 prf: Proofing color space through which we need to convert.
361
362 color_params: Parameters that may be used in conversion (e.g.
363 ri).
364
365 keep_alpha: If 0 any alpha component is removed, otherwise
366 alpha is kept if present in the pixmap.
367 */
368 fz_pixmap *fz_convert_pixmap(fz_context *ctx, const fz_pixmap *pix, fz_colorspace *cs_des, fz_colorspace *prf, fz_default_colorspaces *default_cs, fz_color_params color_params, int keep_alpha);
369
370 /**
371 Check if the pixmap is a 1-channel image containing samples with
372 only values 0 and 255
373 */
374 int fz_is_pixmap_monochrome(fz_context *ctx, fz_pixmap *pixmap);
375
376 /* Implementation details: subject to change.*/
377
378 fz_pixmap *fz_alpha_from_gray(fz_context *ctx, fz_pixmap *gray);
379 void fz_decode_tile(fz_context *ctx, fz_pixmap *pix, const float *decode);
380 void fz_md5_pixmap(fz_context *ctx, fz_pixmap *pixmap, unsigned char digest[16]);
381
382 fz_stream *
383 fz_unpack_stream(fz_context *ctx, fz_stream *src, int depth, int w, int h, int n, int indexed, int pad, int skip);
384
385 /**
386 Pixmaps represent a set of pixels for a 2 dimensional region of
387 a plane. Each pixel has n components per pixel. The components
388 are in the order process-components, spot-colors, alpha, where
389 there can be 0 of any of those types. The data is in
390 premultiplied alpha when rendering, but non-premultiplied for
391 colorspace conversions and rescaling.
392
393 x, y: The minimum x and y coord of the region in pixels.
394
395 w, h: The width and height of the region in pixels.
396
397 n: The number of color components in the image.
398 n = num composite colors + num spots + num alphas
399
400 s: The number of spot channels in the image.
401
402 alpha: 0 for no alpha, 1 for alpha present.
403
404 flags: flag bits.
405 Bit 0: If set, draw the image with linear interpolation.
406 Bit 1: If set, free the samples buffer when the pixmap
407 is destroyed.
408
409 stride: The byte offset from the data for any given pixel
410 to the data for the same pixel on the row below.
411
412 seps: NULL, or a pointer to a separations structure. If NULL,
413 s should be 0.
414
415 xres, yres: Image resolution in dpi. Default is 96 dpi.
416
417 colorspace: Pointer to a colorspace object describing the
418 colorspace the pixmap is in. If NULL, the image is a mask.
419
420 samples: Pointer to the first byte of the pixmap sample data.
421 This is typically a simple block of memory w * h * n bytes of
422 memory in which the components are stored linearly, but with the
423 use of appropriate stride values, scanlines can be stored in
424 different orders, and have different amounts of padding. The
425 first n bytes are components 0 to n-1 for the pixel at (x,y).
426 Each successive n bytes gives another pixel in scanline order
427 as we move across the line. The start of each scanline is offset
428 the start of the previous one by stride bytes.
429 */
430 struct fz_pixmap
431 {
432 fz_storable storable;
433 int x, y, w, h;
434 unsigned char n;
435 unsigned char s;
436 unsigned char alpha;
437 unsigned char flags;
438 ptrdiff_t stride;
439 fz_separations *seps;
440 int xres, yres;
441 fz_colorspace *colorspace;
442 unsigned char *samples;
443 fz_pixmap *underlying;
444 };
445
446 enum
447 {
448 FZ_PIXMAP_FLAG_INTERPOLATE = 1,
449 FZ_PIXMAP_FLAG_FREE_SAMPLES = 2
450 };
451
452 /* Create a new pixmap from a warped section of another.
453 *
454 * Colorspace, resolution etc are inherited from the original.
455 * points give the corner points within the original pixmap of a
456 * (convex) quadrilateral. These corner points will be 'warped' to be
457 * the corner points of the returned bitmap, which will have the given
458 * width/height.
459 */
460 fz_pixmap *
461 fz_warp_pixmap(fz_context *ctx, fz_pixmap *src, fz_quad points, int width, int height);
462
463 /* As for fz_warp_pixmap, where width/height are automatically 'guessed'. */
464 fz_pixmap *
465 fz_autowarp_pixmap(fz_context *ctx, fz_pixmap *src, fz_quad points);
466
467 /* Search for a "document" within a pixmap (greyscale or rgb, no alpha).
468 *
469 * points should point to an array of 4 fz_points.
470 *
471 * If the function return false, no document was found.
472 * If true, points has been updated to include the corner positions of
473 * the detected document within the src image.
474 */
475 int
476 fz_detect_document(fz_context *ctx, fz_quad *points, fz_pixmap *src);
477
478 /*
479 Convert between different separation results.
480 */
481 fz_pixmap *fz_clone_pixmap_area_with_different_seps(fz_context *ctx, fz_pixmap *src, const fz_irect *bbox, fz_colorspace *dcs, fz_separations *seps, fz_color_params color_params, fz_default_colorspaces *default_cs);
482
483 /*
484 * Extract alpha channel as a separate pixmap.
485 * Returns NULL if there is no alpha channel in the source.
486 */
487 fz_pixmap *fz_new_pixmap_from_alpha_channel(fz_context *ctx, fz_pixmap *src);
488
489 /*
490 * Combine a pixmap without an alpha channel with a soft mask.
491 */
492 fz_pixmap *fz_new_pixmap_from_color_and_mask(fz_context *ctx, fz_pixmap *color, fz_pixmap *mask);
493
494 /*
495 * Scale the pixmap up or down in size to fit the rectangle. Will return `NULL`
496 * if the scaling factors are out of range. This applies fancy filtering and
497 * will anti-alias the edges for subpixel positioning if using non-integer
498 * coordinates. If the clip rectangle is set, the returned pixmap may be subset
499 * to fit the clip rectangle. Pass `NULL` to the clip if you want the whole
500 * pixmap scaled.
501 */
502 fz_pixmap *fz_scale_pixmap(fz_context *ctx, fz_pixmap *src, float x, float y, float w, float h, const fz_irect *clip);
503
504 /*
505 * Reduces size to:
506 * tile->w => (tile->w + 2^factor-1) / 2^factor
507 * tile->h => (tile->h + 2^factor-1) / 2^factor
508 */
509 void fz_subsample_pixmap(fz_context *ctx, fz_pixmap *tile, int factor);
510
511 /*
512 * Copies r (clipped to both src and dest) in src to dest.
513 */
514 void fz_copy_pixmap_rect(fz_context *ctx, fz_pixmap *dest, fz_pixmap *src, fz_irect r, const fz_default_colorspaces *default_cs);
515
516 #endif