Mercurial > hgrepos > Python2 > PyMuPDF

comparison mupdf-source/thirdparty/leptonica/src/pix_internal.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 /*====================================================================*
2 - Copyright (C) 2001 Leptonica. All rights reserved.
3 -
4 - Redistribution and use in source and binary forms, with or without
5 - modification, are permitted provided that the following conditions
6 - are met:
7 - 1. Redistributions of source code must retain the above copyright
8 - notice, this list of conditions and the following disclaimer.
9 - 2. Redistributions in binary form must reproduce the above
10 - copyright notice, this list of conditions and the following
11 - disclaimer in the documentation and/or other materials
12 - provided with the distribution.
13 -
14 - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
15 - ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
16 - LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
17 - A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL ANY
18 - CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
19 - EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
20 - PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
21 - PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
22 - OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
23 - NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
24 - SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
25 *====================================================================*/
26
27 #ifndef LEPTONICA_PIX_INTERNAL_H
28 #define LEPTONICA_PIX_INTERNAL_H
29
30 /*!
31 * \file pix_internal.h
32 *
33 * <pre>
34 * Valid image types in leptonica:
35 * Pix: 1 bpp, with and without colormap
36 * Pix: 2 bpp, with and without colormap
37 * Pix: 4 bpp, with and without colormap
38 * Pix: 8 bpp, with and without colormap
39 * Pix: 16 bpp (1 spp)
40 * Pix: 32 bpp (rgb, 3 spp)
41 * Pix: 32 bpp (rgba, 4 spp)
42 * FPix: 32 bpp float
43 * DPix: 64 bpp double
44 * Notes:
45 * (1) The only valid Pix image type with alpha is rgba.
46 * In particular, the alpha component is not used in
47 * cmapped images.
48 * (2) PixComp can hold any Pix with IFF_PNG encoding.
49 *
50 * This file is internal: it is not part of the public interface.
51 * It contains the definitions of most of the image-related structs
52 * used in leptonica:
53 * struct Pix
54 * struct PixColormap
55 * struct RGBA_Quad
56 * struct Pixa
57 * struct Pixaa
58 * struct Box
59 * struct Boxa
60 * struct Boxaa
61 * struct Pta
62 * struct Ptaa
63 * struct Pixacc
64 * struct PixTiling
65 * struct FPix
66 * struct FPixa
67 * struct DPix
68 * struct PixComp
69 * struct PixaComp
70 *
71 * This file can be #included after allheaders.h in source files that
72 * require direct access to the internal data fields in these structs.
73 *
74 * Notes on the pixels in the raster image. Most of this information
75 * can also be found in pix.h.
76 *
77 * (1) The image data is stored in a single contiguous
78 * array of l_uint32, into which the pixels are packed.
79 * By "packed" we mean that there are no unused bits
80 * between pixels, except for end-of-line padding to
81 * satisfy item (2) below.
82 *
83 * (2) Every image raster line begins on a 32-bit word
84 * boundary within this array.
85 *
86 * (3) Pix image data is stored in 32-bit units, with the
87 * pixels ordered from left to right in the image being
88 * stored in order from the MSB to LSB within the word,
89 * for both big-endian and little-endian machines.
90 * This is the natural ordering for big-endian machines,
91 * as successive bytes are stored and fetched progressively
92 * to the right. However, for little-endians, when storing
93 * we re-order the bytes from this byte stream order, and
94 * reshuffle again for byte access on 32-bit entities.
95 * So if the bytes come in sequence from left to right, we
96 * store them on little-endians in byte order:
97 * 3 2 1 0 7 6 5 4 ...
98 * This MSB to LSB ordering allows left and right shift
99 * operations on 32 bit words to move the pixels properly.
100 *
101 * (4) We use 32 bit pixels for both RGB and RGBA color images.
102 * The A (alpha) byte is ignored in most leptonica functions
103 * operating on color images. Within each 4 byte pixel, the
104 * color samples are ordered from MSB to LSB, as follows:
105 *
106 * | MSB | 2nd MSB | 3rd MSB | LSB |
107 * red green blue alpha
108 * 0 1 2 3 (big-endian)
109 * 3 2 1 0 (little-endian)
110 *
111 * Because we use MSB to LSB ordering within the 32-bit word,
112 * the individual 8-bit samples can be accessed with
113 * GET_DATA_BYTE and SET_DATA_BYTE macros, using the
114 * (implicitly big-ending) ordering
115 * red: byte 0 (MSB)
116 * green: byte 1 (2nd MSB)
117 * blue: byte 2 (3rd MSB)
118 * alpha: byte 3 (LSB)
119 *
120 * The specific color assignment is made in this file,
121 * through the definitions of COLOR_RED, etc. Then the R, G
122 * B and A sample values can be retrieved using
123 * redval = GET_DATA_BYTE(&pixel, COLOR_RED);
124 * greenval = GET_DATA_BYTE(&pixel, COLOR_GREEN);
125 * blueval = GET_DATA_BYTE(&pixel, COLOR_BLUE);
126 * alphaval = GET_DATA_BYTE(&pixel, L_ALPHA_CHANNEL);
127 * and they can be set with
128 * SET_DATA_BYTE(&pixel, COLOR_RED, redval);
129 * SET_DATA_BYTE(&pixel, COLOR_GREEN, greenval);
130 * SET_DATA_BYTE(&pixel, COLOR_BLUE, blueval);
131 * SET_DATA_BYTE(&pixel, L_ALPHA_CHANNEL, alphaval);
132 *
133 * More efficiently, these components can be extracted directly
134 * by shifting and masking, explicitly using the values in
135 * L_RED_SHIFT, etc.:
136 * (pixel32 >> L_RED_SHIFT) & 0xff; (red)
137 * (pixel32 >> L_GREEN_SHIFT) & 0xff; (green)
138 * (pixel32 >> L_BLUE_SHIFT) & 0xff; (blue)
139 * (pixel32 >> L_ALPHA_SHIFT) & 0xff; (alpha)
140 * The functions extractRGBValues() and extractRGBAValues() are
141 * provided to do this. Likewise, the pixels can be set
142 * directly by shifting, using composeRGBPixel() and
143 * composeRGBAPixel().
144 *
145 * All these operations work properly on both big- and little-endians.
146 *
147 * (5) A reference count is held within each pix, giving the
148 * number of ptrs to the pix. When a pixClone() call
149 * is made, the ref count is increased by 1, and
150 * when a pixDestroy() call is made, the reference count
151 * of the pix is decremented. The pix is only destroyed
152 * when the reference count goes to zero.
153 *
154 * (6) The version numbers (below) are used in the serialization
155 * of these data structures. They are placed in the files,
156 * and rarely (if ever) change.
157 *
158 * (7) The serialization dependencies are as follows:
159 * pixaa : pixa : boxa
160 * boxaa : boxa
161 * So, for example, pixaa and boxaa can be changed without
162 * forcing a change in pixa or boxa. However, if pixa is
163 * changed, it forces a change in pixaa, and if boxa is
164 * changed, if forces a change in the other three.
165 * We define four version numbers:
166 * PIXAA_VERSION_NUMBER
167 * PIXA_VERSION_NUMBER
168 * BOXAA_VERSION_NUMBER
169 * BOXA_VERSION_NUMBER
170 * </pre>
171 *-------------------------------------------------------------------------*/
172
173 /*-------------------------------------------------------------------------*
174 * Basic Pix *
175 *-------------------------------------------------------------------------*/
176 /* The 'special' field is by default 0, but it can hold integers
177 * that direct non-default actions, e.g., in png and jpeg I/O. */
178
179 /*! Basic Pix */
180 struct Pix
181 {
182 l_uint32 w; /*!< width in pixels */
183 l_uint32 h; /*!< height in pixels */
184 l_uint32 d; /*!< depth in bits (bpp) */
185 l_uint32 spp; /*!< number of samples per pixel */
186 l_uint32 wpl; /*!< 32-bit words/line */
187 l_atomic refcount; /*!< reference count (1 if no clones) */
188 l_int32 xres; /*!< image res (ppi) in x direction */
189 /*!< (use 0 if unknown) */
190 l_int32 yres; /*!< image res (ppi) in y direction */
191 /*!< (use 0 if unknown) */
192 l_int32 informat; /*!< input file format, IFF_* */
193 l_int32 special; /*!< special instructions for I/O, etc */
194 char *text; /*!< text string associated with pix */
195 struct PixColormap *colormap; /*!< colormap (may be null) */
196 l_uint32 *data; /*!< the image data */
197 };
198
199 /*! Colormap of a Pix */
200 struct PixColormap
201 {
202 void *array; /*!< colormap table (array of RGBA_QUAD) */
203 l_int32 depth; /*!< of pix (1, 2, 4 or 8 bpp) */
204 l_int32 nalloc; /*!< number of color entries allocated */
205 l_int32 n; /*!< number of color entries used */
206 };
207
208
209 /*! Colormap table entry (after the BMP version).
210 * Note that the BMP format stores the colormap table exactly
211 * as it appears here, with color samples being stored sequentially,
212 * in the order (b,g,r,a). */
213 struct RGBA_Quad
214 {
215 l_uint8 blue; /*!< blue value */
216 l_uint8 green; /*!< green value */
217 l_uint8 red; /*!< red value */
218 l_uint8 alpha; /*!< alpha value */
219 };
220
221
222 /*-------------------------------------------------------------------------*
223 * Array of pix *
224 *-------------------------------------------------------------------------*/
225 /* Serialization for primary data structures */
226 #define PIXAA_VERSION_NUMBER 2 /*!< Version for Pixaa serialization */
227 #define PIXA_VERSION_NUMBER 2 /*!< Version for Pixa serialization */
228 #define BOXA_VERSION_NUMBER 2 /*!< Version for Boxa serialization */
229 #define BOXAA_VERSION_NUMBER 3 /*!< Version for Boxaa serialization */
230
231 /*! Array of pix */
232 struct Pixa
233 {
234 l_int32 n; /*!< number of Pix in ptr array */
235 l_int32 nalloc; /*!< number of Pix ptrs allocated */
236 l_atomic refcount; /*!< reference count (1 if no clones) */
237 struct Pix **pix; /*!< the array of ptrs to pix */
238 struct Boxa *boxa; /*!< array of boxes */
239 };
240
241 /*! Array of arrays of pix */
242 struct Pixaa
243 {
244 l_int32 n; /*!< number of Pixa in ptr array */
245 l_int32 nalloc; /*!< number of Pixa ptrs allocated */
246 struct Pixa **pixa; /*!< array of ptrs to pixa */
247 struct Boxa *boxa; /*!< array of boxes */
248 };
249
250
251 /*-------------------------------------------------------------------------*
252 * Basic rectangle and rectangle arrays *
253 *-------------------------------------------------------------------------*/
254 /*! Basic rectangle */
255 struct Box
256 {
257 l_int32 x; /*!< left coordinate */
258 l_int32 y; /*!< top coordinate */
259 l_int32 w; /*!< box width */
260 l_int32 h; /*!< box height */
261 l_atomic refcount; /*!< reference count (1 if no clones) */
262 };
263
264 /*! Array of Box */
265 struct Boxa
266 {
267 l_int32 n; /*!< number of box in ptr array */
268 l_int32 nalloc; /*!< number of box ptrs allocated */
269 l_atomic refcount; /*!< reference count (1 if no clones) */
270 struct Box **box; /*!< box ptr array */
271 };
272
273 /*! Array of Boxa */
274 struct Boxaa
275 {
276 l_int32 n; /*!< number of boxa in ptr array */
277 l_int32 nalloc; /*!< number of boxa ptrs allocated */
278 struct Boxa **boxa; /*!< boxa ptr array */
279 };
280
281
282 /*-------------------------------------------------------------------------*
283 * Array of points *
284 *-------------------------------------------------------------------------*/
285 #define PTA_VERSION_NUMBER 1 /*!< Version for Pta serialization */
286
287 /*! Array of points */
288 struct Pta
289 {
290 l_int32 n; /*!< actual number of pts */
291 l_int32 nalloc; /*!< size of allocated arrays */
292 l_atomic refcount; /*!< reference count (1 if no clones) */
293 l_float32 *x, *y; /*!< arrays of floats */
294 };
295
296
297 /*-------------------------------------------------------------------------*
298 * Array of Pta *
299 *-------------------------------------------------------------------------*/
300 /*! Array of Pta */
301 struct Ptaa
302 {
303 l_int32 n; /*!< number of pta in ptr array */
304 l_int32 nalloc; /*!< number of pta ptrs allocated */
305 struct Pta **pta; /*!< pta ptr array */
306 };
307
308
309 /*-------------------------------------------------------------------------*
310 * Pix accumulator container *
311 *-------------------------------------------------------------------------*/
312 /*! Pix accumulator container */
313 struct Pixacc
314 {
315 l_int32 w; /*!< array width */
316 l_int32 h; /*!< array height */
317 l_int32 offset; /*!< used to allow negative */
318 /*!< intermediate results */
319 struct Pix *pix; /*!< the 32 bit accumulator pix */
320 };
321
322
323 /*-------------------------------------------------------------------------*
324 * Pix tiling *
325 *-------------------------------------------------------------------------*/
326 /*! Pix tiling */
327 struct PixTiling
328 {
329 struct Pix *pix; /*!< input pix (a clone) */
330 l_int32 nx; /*!< number of tiles horizontally */
331 l_int32 ny; /*!< number of tiles vertically */
332 l_int32 w; /*!< tile width */
333 l_int32 h; /*!< tile height */
334 l_int32 xoverlap; /*!< overlap on left and right */
335 l_int32 yoverlap; /*!< overlap on top and bottom */
336 l_int32 strip; /*!< strip for paint; default is TRUE */
337 };
338
339
340 /*-------------------------------------------------------------------------*
341 * FPix: pix with float array *
342 *-------------------------------------------------------------------------*/
343 #define FPIX_VERSION_NUMBER 2 /*!< Version for FPix serialization */
344
345 /*! Pix with float array */
346 struct FPix
347 {
348 l_int32 w; /*!< width in pixels */
349 l_int32 h; /*!< height in pixels */
350 l_int32 wpl; /*!< 32-bit words/line */
351 l_atomic refcount; /*!< reference count (1 if no clones) */
352 l_int32 xres; /*!< image res (ppi) in x direction */
353 /*!< (use 0 if unknown) */
354 l_int32 yres; /*!< image res (ppi) in y direction */
355 /*!< (use 0 if unknown) */
356 l_float32 *data; /*!< the float image data */
357 };
358
359 /*! Array of FPix */
360 struct FPixa
361 {
362 l_int32 n; /*!< number of fpix in ptr array */
363 l_int32 nalloc; /*!< number of fpix ptrs allocated */
364 l_atomic refcount; /*!< reference count (1 if no clones) */
365 struct FPix **fpix; /*!< the array of ptrs to fpix */
366 };
367
368
369 /*-------------------------------------------------------------------------*
370 * DPix: pix with double array *
371 *-------------------------------------------------------------------------*/
372 #define DPIX_VERSION_NUMBER 2 /*!< Version for DPix serialization */
373
374 /*! Pix with double array */
375 struct DPix
376 {
377 l_int32 w; /*!< width in pixels */
378 l_int32 h; /*!< height in pixels */
379 l_int32 wpl; /*!< 32-bit words/line */
380 l_atomic refcount; /*!< reference count (1 if no clones) */
381 l_int32 xres; /*!< image res (ppi) in x direction */
382 /*!< (use 0 if unknown) */
383 l_int32 yres; /*!< image res (ppi) in y direction */
384 /*!< (use 0 if unknown) */
385 l_float64 *data; /*!< the double image data */
386 };
387
388
389 /*-------------------------------------------------------------------------*
390 * PixComp: compressed pix *
391 *-------------------------------------------------------------------------*/
392 /*! Compressed Pix */
393 struct PixComp
394 {
395 l_int32 w; /*!< width in pixels */
396 l_int32 h; /*!< height in pixels */
397 l_int32 d; /*!< depth in bits */
398 l_int32 xres; /*!< image res (ppi) in x direction */
399 /*!< (use 0 if unknown) */
400 l_int32 yres; /*!< image res (ppi) in y direction */
401 /*!< (use 0 if unknown) */
402 l_int32 comptype; /*!< compressed format (IFF_TIFF_G4, */
403 /*!< IFF_PNG, IFF_JFIF_JPEG) */
404 char *text; /*!< text string associated with pix */
405 l_int32 cmapflag; /*!< flag (1 for cmap, 0 otherwise) */
406 l_uint8 *data; /*!< the compressed image data */
407 size_t size; /*!< size of the data array */
408 };
409
410
411 /*-------------------------------------------------------------------------*
412 * PixaComp: array of compressed pix *
413 *-------------------------------------------------------------------------*/
414 #define PIXACOMP_VERSION_NUMBER 2 /*!< Version for PixaComp serialization */
415
416 /*! Array of compressed pix */
417 struct PixaComp
418 {
419 l_int32 n; /*!< number of PixComp in ptr array */
420 l_int32 nalloc; /*!< number of PixComp ptrs allocated */
421 l_int32 offset; /*!< indexing offset into ptr array */
422 struct PixComp **pixc; /*!< the array of ptrs to PixComp */
423 struct Boxa *boxa; /*!< array of boxes */
424 };
425
426 #endif /* LEPTONICA_PIX_INTERNAL_H */