OLD | NEW |
| (Empty) |
1 | |
2 /* pnginfo.h - header file for PNG reference library | |
3 * | |
4 * Last changed in libpng 1.6.1 [March 28, 2013] | |
5 * Copyright (c) 1998-2013 Glenn Randers-Pehrson | |
6 * (Version 0.96 Copyright (c) 1996, 1997 Andreas Dilger) | |
7 * (Version 0.88 Copyright (c) 1995, 1996 Guy Eric Schalnat, Group 42, Inc.) | |
8 * | |
9 * This code is released under the libpng license. | |
10 * For conditions of distribution and use, see the disclaimer | |
11 * and license in png.h | |
12 */ | |
13 | |
14 /* png_info is a structure that holds the information in a PNG file so | |
15 * that the application can find out the characteristics of the image. | |
16 * If you are reading the file, this structure will tell you what is | |
17 * in the PNG file. If you are writing the file, fill in the information | |
18 * you want to put into the PNG file, using png_set_*() functions, then | |
19 * call png_write_info(). | |
20 * | |
21 * The names chosen should be very close to the PNG specification, so | |
22 * consult that document for information about the meaning of each field. | |
23 * | |
24 * With libpng < 0.95, it was only possible to directly set and read the | |
25 * the values in the png_info_struct, which meant that the contents and | |
26 * order of the values had to remain fixed. With libpng 0.95 and later, | |
27 * however, there are now functions that abstract the contents of | |
28 * png_info_struct from the application, so this makes it easier to use | |
29 * libpng with dynamic libraries, and even makes it possible to use | |
30 * libraries that don't have all of the libpng ancillary chunk-handing | |
31 * functionality. In libpng-1.5.0 this was moved into a separate private | |
32 * file that is not visible to applications. | |
33 * | |
34 * The following members may have allocated storage attached that should be | |
35 * cleaned up before the structure is discarded: palette, trans, text, | |
36 * pcal_purpose, pcal_units, pcal_params, hist, iccp_name, iccp_profile, | |
37 * splt_palettes, scal_unit, row_pointers, and unknowns. By default, these | |
38 * are automatically freed when the info structure is deallocated, if they were | |
39 * allocated internally by libpng. This behavior can be changed by means | |
40 * of the png_data_freer() function. | |
41 * | |
42 * More allocation details: all the chunk-reading functions that | |
43 * change these members go through the corresponding png_set_* | |
44 * functions. A function to clear these members is available: see | |
45 * png_free_data(). The png_set_* functions do not depend on being | |
46 * able to point info structure members to any of the storage they are | |
47 * passed (they make their own copies), EXCEPT that the png_set_text | |
48 * functions use the same storage passed to them in the text_ptr or | |
49 * itxt_ptr structure argument, and the png_set_rows and png_set_unknowns | |
50 * functions do not make their own copies. | |
51 */ | |
52 #ifndef PNGINFO_H | |
53 #define PNGINFO_H | |
54 | |
55 struct png_info_def | |
56 { | |
57 /* The following are necessary for every PNG file */ | |
58 png_uint_32 width; /* width of image in pixels (from IHDR) */ | |
59 png_uint_32 height; /* height of image in pixels (from IHDR) */ | |
60 png_uint_32 valid; /* valid chunk data (see PNG_INFO_ below) */ | |
61 png_size_t rowbytes; /* bytes needed to hold an untransformed row */ | |
62 png_colorp palette; /* array of color values (valid & PNG_INFO_PLTE) */ | |
63 png_uint_16 num_palette; /* number of color entries in "palette" (PLTE) */ | |
64 png_uint_16 num_trans; /* number of transparent palette color (tRNS) */ | |
65 png_byte bit_depth; /* 1, 2, 4, 8, or 16 bits/channel (from IHDR) */ | |
66 png_byte color_type; /* see PNG_COLOR_TYPE_ below (from IHDR) */ | |
67 /* The following three should have been named *_method not *_type */ | |
68 png_byte compression_type; /* must be PNG_COMPRESSION_TYPE_BASE (IHDR) */ | |
69 png_byte filter_type; /* must be PNG_FILTER_TYPE_BASE (from IHDR) */ | |
70 png_byte interlace_type; /* One of PNG_INTERLACE_NONE, PNG_INTERLACE_ADAM7 */ | |
71 | |
72 /* The following are set by png_set_IHDR, called from the application on | |
73 * write, but the are never actually used by the write code. | |
74 */ | |
75 png_byte channels; /* number of data channels per pixel (1, 2, 3, 4) */ | |
76 png_byte pixel_depth; /* number of bits per pixel */ | |
77 png_byte spare_byte; /* to align the data, and for future use */ | |
78 | |
79 #ifdef PNG_READ_SUPPORTED | |
80 /* This is never set during write */ | |
81 png_byte signature[8]; /* magic bytes read by libpng from start of file */ | |
82 #endif | |
83 | |
84 /* The rest of the data is optional. If you are reading, check the | |
85 * valid field to see if the information in these are valid. If you | |
86 * are writing, set the valid field to those chunks you want written, | |
87 * and initialize the appropriate fields below. | |
88 */ | |
89 | |
90 #if defined(PNG_COLORSPACE_SUPPORTED) || defined(PNG_GAMMA_SUPPORTED) | |
91 /* png_colorspace only contains 'flags' if neither GAMMA or COLORSPACE are | |
92 * defined. When COLORSPACE is switched on all the colorspace-defining | |
93 * chunks should be enabled, when GAMMA is switched on all the gamma-defining | |
94 * chunks should be enabled. If this is not done it becomes possible to read | |
95 * inconsistent PNG files and assign a probably incorrect interpretation to | |
96 * the information. (In other words, by carefully choosing which chunks to | |
97 * recognize the system configuration can select an interpretation for PNG | |
98 * files containing ambiguous data and this will result in inconsistent | |
99 * behavior between different libpng builds!) | |
100 */ | |
101 png_colorspace colorspace; | |
102 #endif | |
103 | |
104 #ifdef PNG_iCCP_SUPPORTED | |
105 /* iCCP chunk data. */ | |
106 png_charp iccp_name; /* profile name */ | |
107 png_bytep iccp_profile; /* International Color Consortium profile data */ | |
108 png_uint_32 iccp_proflen; /* ICC profile data length */ | |
109 #endif | |
110 | |
111 #ifdef PNG_TEXT_SUPPORTED | |
112 /* The tEXt, and zTXt chunks contain human-readable textual data in | |
113 * uncompressed, compressed, and optionally compressed forms, respectively. | |
114 * The data in "text" is an array of pointers to uncompressed, | |
115 * null-terminated C strings. Each chunk has a keyword that describes the | |
116 * textual data contained in that chunk. Keywords are not required to be | |
117 * unique, and the text string may be empty. Any number of text chunks may | |
118 * be in an image. | |
119 */ | |
120 int num_text; /* number of comments read or comments to write */ | |
121 int max_text; /* current size of text array */ | |
122 png_textp text; /* array of comments read or comments to write */ | |
123 #endif /* TEXT */ | |
124 | |
125 #ifdef PNG_tIME_SUPPORTED | |
126 /* The tIME chunk holds the last time the displayed image data was | |
127 * modified. See the png_time struct for the contents of this struct. | |
128 */ | |
129 png_time mod_time; | |
130 #endif | |
131 | |
132 #ifdef PNG_sBIT_SUPPORTED | |
133 /* The sBIT chunk specifies the number of significant high-order bits | |
134 * in the pixel data. Values are in the range [1, bit_depth], and are | |
135 * only specified for the channels in the pixel data. The contents of | |
136 * the low-order bits is not specified. Data is valid if | |
137 * (valid & PNG_INFO_sBIT) is non-zero. | |
138 */ | |
139 png_color_8 sig_bit; /* significant bits in color channels */ | |
140 #endif | |
141 | |
142 #if defined(PNG_tRNS_SUPPORTED) || defined(PNG_READ_EXPAND_SUPPORTED) || \ | |
143 defined(PNG_READ_BACKGROUND_SUPPORTED) | |
144 /* The tRNS chunk supplies transparency data for paletted images and | |
145 * other image types that don't need a full alpha channel. There are | |
146 * "num_trans" transparency values for a paletted image, stored in the | |
147 * same order as the palette colors, starting from index 0. Values | |
148 * for the data are in the range [0, 255], ranging from fully transparent | |
149 * to fully opaque, respectively. For non-paletted images, there is a | |
150 * single color specified that should be treated as fully transparent. | |
151 * Data is valid if (valid & PNG_INFO_tRNS) is non-zero. | |
152 */ | |
153 png_bytep trans_alpha; /* alpha values for paletted image */ | |
154 png_color_16 trans_color; /* transparent color for non-palette image */ | |
155 #endif | |
156 | |
157 #if defined(PNG_bKGD_SUPPORTED) || defined(PNG_READ_BACKGROUND_SUPPORTED) | |
158 /* The bKGD chunk gives the suggested image background color if the | |
159 * display program does not have its own background color and the image | |
160 * is needs to composited onto a background before display. The colors | |
161 * in "background" are normally in the same color space/depth as the | |
162 * pixel data. Data is valid if (valid & PNG_INFO_bKGD) is non-zero. | |
163 */ | |
164 png_color_16 background; | |
165 #endif | |
166 | |
167 #ifdef PNG_oFFs_SUPPORTED | |
168 /* The oFFs chunk gives the offset in "offset_unit_type" units rightwards | |
169 * and downwards from the top-left corner of the display, page, or other | |
170 * application-specific co-ordinate space. See the PNG_OFFSET_ defines | |
171 * below for the unit types. Valid if (valid & PNG_INFO_oFFs) non-zero. | |
172 */ | |
173 png_int_32 x_offset; /* x offset on page */ | |
174 png_int_32 y_offset; /* y offset on page */ | |
175 png_byte offset_unit_type; /* offset units type */ | |
176 #endif | |
177 | |
178 #ifdef PNG_pHYs_SUPPORTED | |
179 /* The pHYs chunk gives the physical pixel density of the image for | |
180 * display or printing in "phys_unit_type" units (see PNG_RESOLUTION_ | |
181 * defines below). Data is valid if (valid & PNG_INFO_pHYs) is non-zero. | |
182 */ | |
183 png_uint_32 x_pixels_per_unit; /* horizontal pixel density */ | |
184 png_uint_32 y_pixels_per_unit; /* vertical pixel density */ | |
185 png_byte phys_unit_type; /* resolution type (see PNG_RESOLUTION_ below) */ | |
186 #endif | |
187 | |
188 #ifdef PNG_hIST_SUPPORTED | |
189 /* The hIST chunk contains the relative frequency or importance of the | |
190 * various palette entries, so that a viewer can intelligently select a | |
191 * reduced-color palette, if required. Data is an array of "num_palette" | |
192 * values in the range [0,65535]. Data valid if (valid & PNG_INFO_hIST) | |
193 * is non-zero. | |
194 */ | |
195 png_uint_16p hist; | |
196 #endif | |
197 | |
198 #ifdef PNG_pCAL_SUPPORTED | |
199 /* The pCAL chunk describes a transformation between the stored pixel | |
200 * values and original physical data values used to create the image. | |
201 * The integer range [0, 2^bit_depth - 1] maps to the floating-point | |
202 * range given by [pcal_X0, pcal_X1], and are further transformed by a | |
203 * (possibly non-linear) transformation function given by "pcal_type" | |
204 * and "pcal_params" into "pcal_units". Please see the PNG_EQUATION_ | |
205 * defines below, and the PNG-Group's PNG extensions document for a | |
206 * complete description of the transformations and how they should be | |
207 * implemented, and for a description of the ASCII parameter strings. | |
208 * Data values are valid if (valid & PNG_INFO_pCAL) non-zero. | |
209 */ | |
210 png_charp pcal_purpose; /* pCAL chunk description string */ | |
211 png_int_32 pcal_X0; /* minimum value */ | |
212 png_int_32 pcal_X1; /* maximum value */ | |
213 png_charp pcal_units; /* Latin-1 string giving physical units */ | |
214 png_charpp pcal_params; /* ASCII strings containing parameter values */ | |
215 png_byte pcal_type; /* equation type (see PNG_EQUATION_ below) */ | |
216 png_byte pcal_nparams; /* number of parameters given in pcal_params */ | |
217 #endif | |
218 | |
219 /* New members added in libpng-1.0.6 */ | |
220 png_uint_32 free_me; /* flags items libpng is responsible for freeing */ | |
221 | |
222 #ifdef PNG_STORE_UNKNOWN_CHUNKS_SUPPORTED | |
223 /* Storage for unknown chunks that the library doesn't recognize. */ | |
224 png_unknown_chunkp unknown_chunks; | |
225 | |
226 /* The type of this field is limited by the type of | |
227 * png_struct::user_chunk_cache_max, else overflow can occur. | |
228 */ | |
229 int unknown_chunks_num; | |
230 #endif | |
231 | |
232 #ifdef PNG_sPLT_SUPPORTED | |
233 /* Data on sPLT chunks (there may be more than one). */ | |
234 png_sPLT_tp splt_palettes; | |
235 int splt_palettes_num; /* Match type returned by png_get API */ | |
236 #endif | |
237 | |
238 #ifdef PNG_sCAL_SUPPORTED | |
239 /* The sCAL chunk describes the actual physical dimensions of the | |
240 * subject matter of the graphic. The chunk contains a unit specification | |
241 * a byte value, and two ASCII strings representing floating-point | |
242 * values. The values are width and height corresponsing to one pixel | |
243 * in the image. Data values are valid if (valid & PNG_INFO_sCAL) is | |
244 * non-zero. | |
245 */ | |
246 png_byte scal_unit; /* unit of physical scale */ | |
247 png_charp scal_s_width; /* string containing height */ | |
248 png_charp scal_s_height; /* string containing width */ | |
249 #endif | |
250 | |
251 #ifdef PNG_INFO_IMAGE_SUPPORTED | |
252 /* Memory has been allocated if (valid & PNG_ALLOCATED_INFO_ROWS) | |
253 non-zero */ | |
254 /* Data valid if (valid & PNG_INFO_IDAT) non-zero */ | |
255 png_bytepp row_pointers; /* the image bits */ | |
256 #endif | |
257 | |
258 }; | |
259 #endif /* PNGINFO_H */ | |
OLD | NEW |