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