Mercurial > hgrepos > Python2 > PyMuPDF

comparison mupdf-source/include/mupdf/fitz/image.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-2024 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_IMAGE_H
24 #define MUPDF_FITZ_IMAGE_H
25
26 #include "mupdf/fitz/system.h"
27 #include "mupdf/fitz/context.h"
28 #include "mupdf/fitz/store.h"
29 #include "mupdf/fitz/pixmap.h"
30
31 #include "mupdf/fitz/buffer.h"
32 #include "mupdf/fitz/stream.h"
33 #include "mupdf/fitz/compressed-buffer.h"
34
35 /**
36 Images are storable objects from which we can obtain fz_pixmaps.
37 These may be implemented as simple wrappers around a pixmap, or
38 as more complex things that decode at different subsample
39 settings on demand.
40 */
41 typedef struct fz_image fz_image;
42 typedef struct fz_compressed_image fz_compressed_image;
43 typedef struct fz_pixmap_image fz_pixmap_image;
44
45 /**
46 Called to get a handle to a pixmap from an image.
47
48 image: The image to retrieve a pixmap from.
49
50 subarea: The subarea of the image that we actually care about
51 (or NULL to indicate the whole image).
52
53 ctm: Optional, unless subarea is given. If given, then on
54 entry this is the transform that will be applied to the complete
55 image. It should be updated on exit to the transform to apply to
56 the given subarea of the image. This is used to calculate the
57 desired width/height for subsampling.
58
59 w: If non-NULL, a pointer to an int to be updated on exit to the
60 width (in pixels) that the scaled output will cover.
61
62 h: If non-NULL, a pointer to an int to be updated on exit to the
63 height (in pixels) that the scaled output will cover.
64
65 Returns a non NULL kept pixmap pointer. May throw exceptions.
66 */
67 fz_pixmap *fz_get_pixmap_from_image(fz_context *ctx, fz_image *image, const fz_irect *subarea, fz_matrix *ctm, int *w, int *h);
68
69 /**
70 Calls fz_get_pixmap_from_image() with ctm, subarea, w and h all set to NULL.
71 */
72 fz_pixmap *fz_get_unscaled_pixmap_from_image(fz_context *ctx, fz_image *image);
73
74 /**
75 Increment the (normal) reference count for an image. Returns the
76 same pointer.
77
78 Never throws exceptions.
79 */
80 fz_image *fz_keep_image(fz_context *ctx, fz_image *image);
81
82 /**
83 Decrement the (normal) reference count for an image. When the
84 total (normal + key) reference count reaches zero, the image and
85 its resources are freed.
86
87 Never throws exceptions.
88 */
89 void fz_drop_image(fz_context *ctx, fz_image *image);
90
91 /**
92 Increment the store key reference for an image. Returns the same
93 pointer. (This is the count of references for an image held by
94 keys in the image store).
95
96 Never throws exceptions.
97 */
98 fz_image *fz_keep_image_store_key(fz_context *ctx, fz_image *image);
99
100 /**
101 Decrement the store key reference count for an image. When the
102 total (normal + key) reference count reaches zero, the image and
103 its resources are freed.
104
105 Never throws exceptions.
106 */
107 void fz_drop_image_store_key(fz_context *ctx, fz_image *image);
108
109 /**
110 Function type to destroy an images data
111 when it's reference count reaches zero.
112 */
113 typedef void (fz_drop_image_fn)(fz_context *ctx, fz_image *image);
114
115 /**
116 Function type to get a decoded pixmap for an image.
117
118 im: The image to decode.
119
120 subarea: NULL, or the subarea of the image required. Expressed
121 in terms of a rectangle in the original width/height of the
122 image. If non NULL, this should be updated by the function to
123 the actual subarea decoded - which must include the requested
124 area!
125
126 w, h: The actual width and height that the whole image would
127 need to be decoded to.
128
129 l2factor: On entry, the log 2 subsample factor required. If
130 possible the decode process can take care of (all or some) of
131 this subsampling, and must then update the value so the caller
132 knows what remains to be done.
133
134 Returns a reference to a decoded pixmap that satisfies the
135 requirements of the request. The caller owns the returned
136 reference.
137 */
138 typedef fz_pixmap *(fz_image_get_pixmap_fn)(fz_context *ctx, fz_image *im, fz_irect *subarea, int w, int h, int *l2factor);
139
140 /**
141 Function type to get the given storage
142 size for an image.
143
144 Returns the size in bytes used for a given image.
145 */
146 typedef size_t (fz_image_get_size_fn)(fz_context *, fz_image *);
147
148 /**
149 Internal function to make a new fz_image structure
150 for a derived class.
151
152 w,h: Width and height of the created image.
153
154 bpc: Bits per component.
155
156 colorspace: The colorspace (determines the number of components,
157 and any color conversions required while decoding).
158
159 xres, yres: The X and Y resolutions respectively.
160
161 interpolate: 1 if interpolation should be used when decoding
162 this image, 0 otherwise.
163
164 imagemask: 1 if this is an imagemask (i.e. transparent), 0
165 otherwise.
166
167 decode: NULL, or a pointer to to a decode array. The default
168 decode array is [0 1] (repeated n times, for n color components).
169
170 colorkey: NULL, or a pointer to a colorkey array. The default
171 colorkey array is [0 255] (repeated n times, for n color
172 components).
173
174 mask: NULL, or another image to use as a mask for this one.
175 A new reference is taken to this image. Supplying a masked
176 image as a mask to another image is illegal!
177
178 size: The size of the required allocated structure (the size of
179 the derived structure).
180
181 get: The function to be called to obtain a decoded pixmap.
182
183 get_size: The function to be called to return the storage size
184 used by this image.
185
186 drop: The function to be called to dispose of this image once
187 the last reference is dropped.
188
189 Returns a pointer to an allocated structure of the required size,
190 with the first sizeof(fz_image) bytes initialised as appropriate
191 given the supplied parameters, and the other bytes set to zero.
192 */
193 fz_image *fz_new_image_of_size(fz_context *ctx,
194 int w,
195 int h,
196 int bpc,
197 fz_colorspace *colorspace,
198 int xres,
199 int yres,
200 int interpolate,
201 int imagemask,
202 const float *decode,
203 const int *colorkey,
204 fz_image *mask,
205 size_t size,
206 fz_image_get_pixmap_fn *get_pixmap,
207 fz_image_get_size_fn *get_size,
208 fz_drop_image_fn *drop);
209
210 #define fz_new_derived_image(CTX,W,H,B,CS,X,Y,I,IM,D,C,M,T,G,S,Z) \
211 ((T*)Memento_label(fz_new_image_of_size(CTX,W,H,B,CS,X,Y,I,IM,D,C,M,sizeof(T),G,S,Z),#T))
212
213 /**
214 Create an image based on
215 the data in the supplied compressed buffer.
216
217 w,h: Width and height of the created image.
218
219 bpc: Bits per component.
220
221 colorspace: The colorspace (determines the number of components,
222 and any color conversions required while decoding).
223
224 xres, yres: The X and Y resolutions respectively.
225
226 interpolate: 1 if interpolation should be used when decoding
227 this image, 0 otherwise.
228
229 imagemask: 1 if this is an imagemask (i.e. transparency bitmap
230 mask), 0 otherwise.
231
232 decode: NULL, or a pointer to to a decode array. The default
233 decode array is [0 1] (repeated n times, for n color components).
234
235 colorkey: NULL, or a pointer to a colorkey array. The default
236 colorkey array is [0 255] (repeated n times, for n color
237 components).
238
239 buffer: Buffer of compressed data and compression parameters.
240 Ownership of this reference is passed in.
241
242 mask: NULL, or another image to use as a mask for this one.
243 A new reference is taken to this image. Supplying a masked
244 image as a mask to another image is illegal!
245 */
246 fz_image *fz_new_image_from_compressed_buffer(fz_context *ctx, int w, int h, int bpc, fz_colorspace *colorspace, int xres, int yres, int interpolate, int imagemask, const float *decode, const int *colorkey, fz_compressed_buffer *buffer, fz_image *mask);
247
248 /**
249 Create an image from the given
250 pixmap.
251
252 pixmap: The pixmap to base the image upon. A new reference
253 to this is taken.
254
255 mask: NULL, or another image to use as a mask for this one.
256 A new reference is taken to this image. Supplying a masked
257 image as a mask to another image is illegal!
258 */
259 fz_image *fz_new_image_from_pixmap(fz_context *ctx, fz_pixmap *pixmap, fz_image *mask);
260
261 /**
262 Create a new image from a
263 buffer of data, inferring its type from the format
264 of the data.
265 */
266 fz_image *fz_new_image_from_buffer(fz_context *ctx, fz_buffer *buffer);
267
268 /**
269 Create a new image from the contents
270 of a file, inferring its type from the format of the
271 data.
272 */
273 fz_image *fz_new_image_from_file(fz_context *ctx, const char *path);
274
275 /**
276 Internal destructor exposed for fz_store integration.
277 */
278 void fz_drop_image_imp(fz_context *ctx, fz_storable *image);
279
280 /**
281 Internal destructor for the base image class members.
282
283 Exposed to allow derived image classes to be written.
284 */
285 void fz_drop_image_base(fz_context *ctx, fz_image *image);
286
287 /**
288 Decode a subarea of a compressed image. l2factor is the amount
289 of subsampling inbuilt to the stream (i.e. performed by the
290 decoder). If non NULL, l2extra is the extra amount of
291 subsampling that should be performed by this routine. This will
292 be updated on exit to the amount of subsampling that is still
293 required to be done.
294
295 Returns a kept reference.
296 */
297 fz_pixmap *fz_decomp_image_from_stream(fz_context *ctx, fz_stream *stm, fz_compressed_image *image, fz_irect *subarea, int indexed, int l2factor, int *l2extra);
298
299 /**
300 Convert pixmap from indexed to base colorspace.
301
302 This creates a new bitmap containing the converted pixmap data.
303 */
304 fz_pixmap *fz_convert_indexed_pixmap_to_base(fz_context *ctx, const fz_pixmap *src);
305
306 /**
307 Convert pixmap from DeviceN/Separation to base colorspace.
308
309 This creates a new bitmap containing the converted pixmap data.
310 */
311 fz_pixmap *fz_convert_separation_pixmap_to_base(fz_context *ctx, const fz_pixmap *src);
312
313 /**
314 Return the size of the storage used by an image.
315 */
316 size_t fz_image_size(fz_context *ctx, fz_image *im);
317
318 /**
319 Return the type of a compressed image.
320
321 Any non-compressed image will have the type returned as UNKNOWN.
322 */
323 int fz_compressed_image_type(fz_context *ctx, fz_image *image);
324
325
326 /**
327 Structure is public to allow other structures to
328 be derived from it. Do not access members directly.
329 */
330 struct fz_image
331 {
332 fz_key_storable key_storable;
333 int w, h;
334 uint8_t n;
335 uint8_t bpc;
336 unsigned int imagemask:1;
337 unsigned int interpolate:1;
338 unsigned int use_colorkey:1;
339 unsigned int use_decode:1;
340 unsigned int decoded:1;
341 unsigned int scalable:1;
342 unsigned int intent:2;
343 unsigned int has_intent:1;
344 uint8_t orientation;
345 fz_image *mask;
346 int xres; /* As given in the image, not necessarily as rendered */
347 int yres; /* As given in the image, not necessarily as rendered */
348 fz_colorspace *colorspace;
349 fz_drop_image_fn *drop_image;
350 fz_image_get_pixmap_fn *get_pixmap;
351 fz_image_get_size_fn *get_size;
352 int colorkey[FZ_MAX_COLORS * 2];
353 float decode[FZ_MAX_COLORS * 2];
354 };
355
356 /**
357 Request the natural resolution
358 of an image.
359
360 xres, yres: Pointers to ints to be updated with the
361 natural resolution of an image (or a sensible default
362 if not encoded).
363 */
364 void fz_image_resolution(fz_image *image, int *xres, int *yres);
365
366 /**
367 Request the natural orientation of an image.
368
369 This is for images (such as JPEG) that can contain internal
370 specifications of rotation/flips. This is ignored by all the
371 internal decode/rendering routines, but can be used by callers
372 (such as the image document handler) to respect such
373 specifications.
374
375 The values used by MuPDF are as follows, with the equivalent
376 Exif specifications given for information:
377
378 0: Undefined
379 1: 0 degree ccw rotation. (Exif = 1)
380 2: 90 degree ccw rotation. (Exif = 8)
381 3: 180 degree ccw rotation. (Exif = 3)
382 4: 270 degree ccw rotation. (Exif = 6)
383 5: flip on X. (Exif = 2)
384 6: flip on X, then rotate ccw by 90 degrees. (Exif = 5)
385 7: flip on X, then rotate ccw by 180 degrees. (Exif = 4)
386 8: flip on X, then rotate ccw by 270 degrees. (Exif = 7)
387 */
388 uint8_t fz_image_orientation(fz_context *ctx, fz_image *image);
389
390 /*
391 Return true if the image source is a lossy format such as JPEG,
392 JPEG2000, or JPEG-XR.
393 */
394 int fz_is_lossy_image(fz_context *ctx, fz_image *image);
395
396 fz_matrix
397 fz_image_orientation_matrix(fz_context *ctx, fz_image *image);
398
399 /**
400 Retrieve the underlying compressed data for an image.
401
402 Returns a pointer to the underlying data buffer for an image,
403 or NULL if this image is not based upon a compressed data
404 buffer.
405
406 This is not a reference counted structure, so no reference is
407 returned. Lifespan is limited to that of the image itself.
408 */
409 fz_compressed_buffer *fz_compressed_image_buffer(fz_context *ctx, fz_image *image);
410 void fz_set_compressed_image_buffer(fz_context *ctx, fz_compressed_image *cimg, fz_compressed_buffer *buf);
411
412 /**
413 Retrieve the underlying fz_pixmap for an image.
414
415 Returns a pointer to the underlying fz_pixmap for an image,
416 or NULL if this image is not based upon an fz_pixmap.
417
418 No reference is returned. Lifespan is limited to that of
419 the image itself. If required, use fz_keep_pixmap to take
420 a reference to keep it longer.
421 */
422 fz_pixmap *fz_pixmap_image_tile(fz_context *ctx, fz_pixmap_image *cimg);
423 void fz_set_pixmap_image_tile(fz_context *ctx, fz_pixmap_image *cimg, fz_pixmap *pix);
424
425 /* Implementation details: subject to change. */
426
427 /**
428 Exposed for PDF.
429 */
430 fz_pixmap *fz_load_jpx(fz_context *ctx, const unsigned char *data, size_t size, fz_colorspace *cs);
431
432 /**
433 Exposed because compression and decompression need to share this.
434 */
435 void opj_lock(fz_context *ctx);
436 void opj_unlock(fz_context *ctx);
437
438
439 /**
440 Exposed for CBZ.
441 */
442 int fz_load_tiff_subimage_count(fz_context *ctx, const unsigned char *buf, size_t len);
443 fz_pixmap *fz_load_tiff_subimage(fz_context *ctx, const unsigned char *buf, size_t len, int subimage);
444 int fz_load_pnm_subimage_count(fz_context *ctx, const unsigned char *buf, size_t len);
445 fz_pixmap *fz_load_pnm_subimage(fz_context *ctx, const unsigned char *buf, size_t len, int subimage);
446 int fz_load_jbig2_subimage_count(fz_context *ctx, const unsigned char *buf, size_t len);
447 fz_pixmap *fz_load_jbig2_subimage(fz_context *ctx, const unsigned char *buf, size_t len, int subimage);
448 int fz_load_bmp_subimage_count(fz_context *ctx, const unsigned char *buf, size_t len);
449 fz_pixmap *fz_load_bmp_subimage(fz_context *ctx, const unsigned char *buf, size_t len, int subimage);
450
451 #endif