| 1 |
/* |
| 2 |
LodePNG version 20180819 |
| 3 |
|
| 4 |
Copyright (c) 2005-2018 Lode Vandevenne |
| 5 |
|
| 6 |
This software is provided 'as-is', without any express or implied |
| 7 |
warranty. In no event will the authors be held liable for any damages |
| 8 |
arising from the use of this software. |
| 9 |
|
| 10 |
Permission is granted to anyone to use this software for any purpose, |
| 11 |
including commercial applications, and to alter it and redistribute it |
| 12 |
freely, subject to the following restrictions: |
| 13 |
|
| 14 |
1. The origin of this software must not be misrepresented; you must not |
| 15 |
claim that you wrote the original software. If you use this software |
| 16 |
in a product, an acknowledgment in the product documentation would be |
| 17 |
appreciated but is not required. |
| 18 |
|
| 19 |
2. Altered source versions must be plainly marked as such, and must not be |
| 20 |
misrepresented as being the original software. |
| 21 |
|
| 22 |
3. This notice may not be removed or altered from any source |
| 23 |
distribution. |
| 24 |
*/ |
| 25 |
|
| 26 |
#ifndef LODEPNG_H |
| 27 |
#define LODEPNG_H |
| 28 |
|
| 29 |
#include <string.h> /*for size_t*/ |
| 30 |
|
| 31 |
extern const char* LODEPNG_VERSION_STRING; |
| 32 |
|
| 33 |
/* |
| 34 |
The following #defines are used to create code sections. They can be disabled |
| 35 |
to disable code sections, which can give faster compile time and smaller binary. |
| 36 |
The "NO_COMPILE" defines are designed to be used to pass as defines to the |
| 37 |
compiler command to disable them without modifying this header, e.g. |
| 38 |
-DLODEPNG_NO_COMPILE_ZLIB for gcc. |
| 39 |
In addition to those below, you can also define LODEPNG_NO_COMPILE_CRC to |
| 40 |
allow implementing a custom lodepng_crc32. |
| 41 |
*/ |
| 42 |
/*deflate & zlib. If disabled, you must specify alternative zlib functions in |
| 43 |
the custom_zlib field of the compress and decompress settings*/ |
| 44 |
#ifndef LODEPNG_NO_COMPILE_ZLIB |
| 45 |
#define LODEPNG_COMPILE_ZLIB |
| 46 |
#endif |
| 47 |
/*png encoder and png decoder*/ |
| 48 |
#ifndef LODEPNG_NO_COMPILE_PNG |
| 49 |
#define LODEPNG_COMPILE_PNG |
| 50 |
#endif |
| 51 |
/*deflate&zlib decoder and png decoder*/ |
| 52 |
#ifndef LODEPNG_NO_COMPILE_DECODER |
| 53 |
#define LODEPNG_COMPILE_DECODER |
| 54 |
#endif |
| 55 |
/*deflate&zlib encoder and png encoder*/ |
| 56 |
#ifndef LODEPNG_NO_COMPILE_ENCODER |
| 57 |
#define LODEPNG_COMPILE_ENCODER |
| 58 |
#endif |
| 59 |
/*the optional built in harddisk file loading and saving functions*/ |
| 60 |
#ifndef LODEPNG_NO_COMPILE_DISK |
| 61 |
#define LODEPNG_COMPILE_DISK |
| 62 |
#endif |
| 63 |
/*support for chunks other than IHDR, IDAT, PLTE, tRNS, IEND: ancillary and unknown chunks*/ |
| 64 |
#ifndef LODEPNG_NO_COMPILE_ANCILLARY_CHUNKS |
| 65 |
#define LODEPNG_COMPILE_ANCILLARY_CHUNKS |
| 66 |
#endif |
| 67 |
/*ability to convert error numerical codes to English text string*/ |
| 68 |
#ifndef LODEPNG_NO_COMPILE_ERROR_TEXT |
| 69 |
#define LODEPNG_COMPILE_ERROR_TEXT |
| 70 |
#endif |
| 71 |
/*Compile the default allocators (C's free, malloc and realloc). If you disable this, |
| 72 |
you can define the functions lodepng_free, lodepng_malloc and lodepng_realloc in your |
| 73 |
source files with custom allocators.*/ |
| 74 |
#ifndef LODEPNG_NO_COMPILE_ALLOCATORS |
| 75 |
#define LODEPNG_COMPILE_ALLOCATORS |
| 76 |
#endif |
| 77 |
/*compile the C++ version (you can disable the C++ wrapper here even when compiling for C++)*/ |
| 78 |
#ifdef __cplusplus |
| 79 |
#ifndef LODEPNG_NO_COMPILE_CPP |
| 80 |
#define LODEPNG_COMPILE_CPP |
| 81 |
#endif |
| 82 |
#endif |
| 83 |
|
| 84 |
#ifdef LODEPNG_COMPILE_CPP |
| 85 |
#include <vector> |
| 86 |
#include <string> |
| 87 |
#endif /*LODEPNG_COMPILE_CPP*/ |
| 88 |
|
| 89 |
#ifdef LODEPNG_COMPILE_PNG |
| 90 |
/*The PNG color types (also used for raw).*/ |
| 91 |
typedef enum LodePNGColorType |
| 92 |
{ |
| 93 |
LCT_GREY = 0, /*greyscale: 1,2,4,8,16 bit*/ |
| 94 |
LCT_RGB = 2, /*RGB: 8,16 bit*/ |
| 95 |
LCT_PALETTE = 3, /*palette: 1,2,4,8 bit*/ |
| 96 |
LCT_GREY_ALPHA = 4, /*greyscale with alpha: 8,16 bit*/ |
| 97 |
LCT_RGBA = 6 /*RGB with alpha: 8,16 bit*/ |
| 98 |
} LodePNGColorType; |
| 99 |
|
| 100 |
#ifdef LODEPNG_COMPILE_DECODER |
| 101 |
/* |
| 102 |
Converts PNG data in memory to raw pixel data. |
| 103 |
out: Output parameter. Pointer to buffer that will contain the raw pixel data. |
| 104 |
After decoding, its size is w * h * (bytes per pixel) bytes larger than |
| 105 |
initially. Bytes per pixel depends on colortype and bitdepth. |
| 106 |
Must be freed after usage with free(*out). |
| 107 |
Note: for 16-bit per channel colors, uses big endian format like PNG does. |
| 108 |
w: Output parameter. Pointer to width of pixel data. |
| 109 |
h: Output parameter. Pointer to height of pixel data. |
| 110 |
in: Memory buffer with the PNG file. |
| 111 |
insize: size of the in buffer. |
| 112 |
colortype: the desired color type for the raw output image. See explanation on PNG color types. |
| 113 |
bitdepth: the desired bit depth for the raw output image. See explanation on PNG color types. |
| 114 |
Return value: LodePNG error code (0 means no error). |
| 115 |
*/ |
| 116 |
unsigned lodepng_decode_memory(unsigned char** out, unsigned* w, unsigned* h, |
| 117 |
const unsigned char* in, size_t insize, |
| 118 |
LodePNGColorType colortype, unsigned bitdepth); |
| 119 |
|
| 120 |
/*Same as lodepng_decode_memory, but always decodes to 32-bit RGBA raw image*/ |
| 121 |
unsigned lodepng_decode32(unsigned char** out, unsigned* w, unsigned* h, |
| 122 |
const unsigned char* in, size_t insize); |
| 123 |
|
| 124 |
/*Same as lodepng_decode_memory, but always decodes to 24-bit RGB raw image*/ |
| 125 |
unsigned lodepng_decode24(unsigned char** out, unsigned* w, unsigned* h, |
| 126 |
const unsigned char* in, size_t insize); |
| 127 |
|
| 128 |
#ifdef LODEPNG_COMPILE_DISK |
| 129 |
/* |
| 130 |
Load PNG from disk, from file with given name. |
| 131 |
Same as the other decode functions, but instead takes a filename as input. |
| 132 |
*/ |
| 133 |
unsigned lodepng_decode_file(unsigned char** out, unsigned* w, unsigned* h, |
| 134 |
const char* filename, |
| 135 |
LodePNGColorType colortype, unsigned bitdepth); |
| 136 |
|
| 137 |
/*Same as lodepng_decode_file, but always decodes to 32-bit RGBA raw image.*/ |
| 138 |
unsigned lodepng_decode32_file(unsigned char** out, unsigned* w, unsigned* h, |
| 139 |
const char* filename); |
| 140 |
|
| 141 |
/*Same as lodepng_decode_file, but always decodes to 24-bit RGB raw image.*/ |
| 142 |
unsigned lodepng_decode24_file(unsigned char** out, unsigned* w, unsigned* h, |
| 143 |
const char* filename); |
| 144 |
#endif /*LODEPNG_COMPILE_DISK*/ |
| 145 |
#endif /*LODEPNG_COMPILE_DECODER*/ |
| 146 |
|
| 147 |
|
| 148 |
#ifdef LODEPNG_COMPILE_ENCODER |
| 149 |
/* |
| 150 |
Converts raw pixel data into a PNG image in memory. The colortype and bitdepth |
| 151 |
of the output PNG image cannot be chosen, they are automatically determined |
| 152 |
by the colortype, bitdepth and content of the input pixel data. |
| 153 |
Note: for 16-bit per channel colors, needs big endian format like PNG does. |
| 154 |
out: Output parameter. Pointer to buffer that will contain the PNG image data. |
| 155 |
Must be freed after usage with free(*out). |
| 156 |
outsize: Output parameter. Pointer to the size in bytes of the out buffer. |
| 157 |
image: The raw pixel data to encode. The size of this buffer should be |
| 158 |
w * h * (bytes per pixel), bytes per pixel depends on colortype and bitdepth. |
| 159 |
w: width of the raw pixel data in pixels. |
| 160 |
h: height of the raw pixel data in pixels. |
| 161 |
colortype: the color type of the raw input image. See explanation on PNG color types. |
| 162 |
bitdepth: the bit depth of the raw input image. See explanation on PNG color types. |
| 163 |
Return value: LodePNG error code (0 means no error). |
| 164 |
*/ |
| 165 |
unsigned lodepng_encode_memory(unsigned char** out, size_t* outsize, |
| 166 |
const unsigned char* image, unsigned w, unsigned h, |
| 167 |
LodePNGColorType colortype, unsigned bitdepth); |
| 168 |
|
| 169 |
/*Same as lodepng_encode_memory, but always encodes from 32-bit RGBA raw image.*/ |
| 170 |
unsigned lodepng_encode32(unsigned char** out, size_t* outsize, |
| 171 |
const unsigned char* image, unsigned w, unsigned h); |
| 172 |
|
| 173 |
/*Same as lodepng_encode_memory, but always encodes from 24-bit RGB raw image.*/ |
| 174 |
unsigned lodepng_encode24(unsigned char** out, size_t* outsize, |
| 175 |
const unsigned char* image, unsigned w, unsigned h); |
| 176 |
|
| 177 |
#ifdef LODEPNG_COMPILE_DISK |
| 178 |
/* |
| 179 |
Converts raw pixel data into a PNG file on disk. |
| 180 |
Same as the other encode functions, but instead takes a filename as output. |
| 181 |
NOTE: This overwrites existing files without warning! |
| 182 |
*/ |
| 183 |
unsigned lodepng_encode_file(const char* filename, |
| 184 |
const unsigned char* image, unsigned w, unsigned h, |
| 185 |
LodePNGColorType colortype, unsigned bitdepth); |
| 186 |
|
| 187 |
/*Same as lodepng_encode_file, but always encodes from 32-bit RGBA raw image.*/ |
| 188 |
unsigned lodepng_encode32_file(const char* filename, |
| 189 |
const unsigned char* image, unsigned w, unsigned h); |
| 190 |
|
| 191 |
/*Same as lodepng_encode_file, but always encodes from 24-bit RGB raw image.*/ |
| 192 |
unsigned lodepng_encode24_file(const char* filename, |
| 193 |
const unsigned char* image, unsigned w, unsigned h); |
| 194 |
#endif /*LODEPNG_COMPILE_DISK*/ |
| 195 |
#endif /*LODEPNG_COMPILE_ENCODER*/ |
| 196 |
|
| 197 |
|
| 198 |
#ifdef LODEPNG_COMPILE_CPP |
| 199 |
namespace lodepng |
| 200 |
{ |
| 201 |
#ifdef LODEPNG_COMPILE_DECODER |
| 202 |
/*Same as lodepng_decode_memory, but decodes to an std::vector. The colortype |
| 203 |
is the format to output the pixels to. Default is RGBA 8-bit per channel.*/ |
| 204 |
unsigned decode(std::vector<unsigned char>& out, unsigned& w, unsigned& h, |
| 205 |
const unsigned char* in, size_t insize, |
| 206 |
LodePNGColorType colortype = LCT_RGBA, unsigned bitdepth = 8); |
| 207 |
unsigned decode(std::vector<unsigned char>& out, unsigned& w, unsigned& h, |
| 208 |
const std::vector<unsigned char>& in, |
| 209 |
LodePNGColorType colortype = LCT_RGBA, unsigned bitdepth = 8); |
| 210 |
#ifdef LODEPNG_COMPILE_DISK |
| 211 |
/* |
| 212 |
Converts PNG file from disk to raw pixel data in memory. |
| 213 |
Same as the other decode functions, but instead takes a filename as input. |
| 214 |
*/ |
| 215 |
unsigned decode(std::vector<unsigned char>& out, unsigned& w, unsigned& h, |
| 216 |
const std::string& filename, |
| 217 |
LodePNGColorType colortype = LCT_RGBA, unsigned bitdepth = 8); |
| 218 |
#endif /* LODEPNG_COMPILE_DISK */ |
| 219 |
#endif /* LODEPNG_COMPILE_DECODER */ |
| 220 |
|
| 221 |
#ifdef LODEPNG_COMPILE_ENCODER |
| 222 |
/*Same as lodepng_encode_memory, but encodes to an std::vector. colortype |
| 223 |
is that of the raw input data. The output PNG color type will be auto chosen.*/ |
| 224 |
unsigned encode(std::vector<unsigned char>& out, |
| 225 |
const unsigned char* in, unsigned w, unsigned h, |
| 226 |
LodePNGColorType colortype = LCT_RGBA, unsigned bitdepth = 8); |
| 227 |
unsigned encode(std::vector<unsigned char>& out, |
| 228 |
const std::vector<unsigned char>& in, unsigned w, unsigned h, |
| 229 |
LodePNGColorType colortype = LCT_RGBA, unsigned bitdepth = 8); |
| 230 |
#ifdef LODEPNG_COMPILE_DISK |
| 231 |
/* |
| 232 |
Converts 32-bit RGBA raw pixel data into a PNG file on disk. |
| 233 |
Same as the other encode functions, but instead takes a filename as output. |
| 234 |
NOTE: This overwrites existing files without warning! |
| 235 |
*/ |
| 236 |
unsigned encode(const std::string& filename, |
| 237 |
const unsigned char* in, unsigned w, unsigned h, |
| 238 |
LodePNGColorType colortype = LCT_RGBA, unsigned bitdepth = 8); |
| 239 |
unsigned encode(const std::string& filename, |
| 240 |
const std::vector<unsigned char>& in, unsigned w, unsigned h, |
| 241 |
LodePNGColorType colortype = LCT_RGBA, unsigned bitdepth = 8); |
| 242 |
#endif /* LODEPNG_COMPILE_DISK */ |
| 243 |
#endif /* LODEPNG_COMPILE_ENCODER */ |
| 244 |
} /* namespace lodepng */ |
| 245 |
#endif /*LODEPNG_COMPILE_CPP*/ |
| 246 |
#endif /*LODEPNG_COMPILE_PNG*/ |
| 247 |
|
| 248 |
#ifdef LODEPNG_COMPILE_ERROR_TEXT |
| 249 |
/*Returns an English description of the numerical error code.*/ |
| 250 |
const char* lodepng_error_text(unsigned code); |
| 251 |
#endif /*LODEPNG_COMPILE_ERROR_TEXT*/ |
| 252 |
|
| 253 |
#ifdef LODEPNG_COMPILE_DECODER |
| 254 |
/*Settings for zlib decompression*/ |
| 255 |
typedef struct LodePNGDecompressSettings LodePNGDecompressSettings; |
| 256 |
struct LodePNGDecompressSettings |
| 257 |
{ |
| 258 |
/* Check LodePNGDecoderSettings for more ignorable errors such as ignore_crc */ |
| 259 |
unsigned ignore_adler32; /*if 1, continue and don't give an error message if the Adler32 checksum is corrupted*/ |
| 260 |
|
| 261 |
/*use custom zlib decoder instead of built in one (default: null)*/ |
| 262 |
unsigned (*custom_zlib)(unsigned char**, size_t*, |
| 263 |
const unsigned char*, size_t, |
| 264 |
const LodePNGDecompressSettings*); |
| 265 |
/*use custom deflate decoder instead of built in one (default: null) |
| 266 |
if custom_zlib is used, custom_deflate is ignored since only the built in |
| 267 |
zlib function will call custom_deflate*/ |
| 268 |
unsigned (*custom_inflate)(unsigned char**, size_t*, |
| 269 |
const unsigned char*, size_t, |
| 270 |
const LodePNGDecompressSettings*); |
| 271 |
|
| 272 |
const void* custom_context; /*optional custom settings for custom functions*/ |
| 273 |
}; |
| 274 |
|
| 275 |
extern const LodePNGDecompressSettings lodepng_default_decompress_settings; |
| 276 |
void lodepng_decompress_settings_init(LodePNGDecompressSettings* settings); |
| 277 |
#endif /*LODEPNG_COMPILE_DECODER*/ |
| 278 |
|
| 279 |
#ifdef LODEPNG_COMPILE_ENCODER |
| 280 |
/* |
| 281 |
Settings for zlib compression. Tweaking these settings tweaks the balance |
| 282 |
between speed and compression ratio. |
| 283 |
*/ |
| 284 |
typedef struct LodePNGCompressSettings LodePNGCompressSettings; |
| 285 |
struct LodePNGCompressSettings /*deflate = compress*/ |
| 286 |
{ |
| 287 |
/*LZ77 related settings*/ |
| 288 |
unsigned btype; /*the block type for LZ (0, 1, 2 or 3, see zlib standard). Should be 2 for proper compression.*/ |
| 289 |
unsigned use_lz77; /*whether or not to use LZ77. Should be 1 for proper compression.*/ |
| 290 |
unsigned windowsize; /*must be a power of two <= 32768. higher compresses more but is slower. Default value: 2048.*/ |
| 291 |
unsigned minmatch; /*mininum lz77 length. 3 is normally best, 6 can be better for some PNGs. Default: 0*/ |
| 292 |
unsigned nicematch; /*stop searching if >= this length found. Set to 258 for best compression. Default: 128*/ |
| 293 |
unsigned lazymatching; /*use lazy matching: better compression but a bit slower. Default: true*/ |
| 294 |
|
| 295 |
/*use custom zlib encoder instead of built in one (default: null)*/ |
| 296 |
unsigned (*custom_zlib)(unsigned char**, size_t*, |
| 297 |
const unsigned char*, size_t, |
| 298 |
const LodePNGCompressSettings*); |
| 299 |
/*use custom deflate encoder instead of built in one (default: null) |
| 300 |
if custom_zlib is used, custom_deflate is ignored since only the built in |
| 301 |
zlib function will call custom_deflate*/ |
| 302 |
unsigned (*custom_deflate)(unsigned char**, size_t*, |
| 303 |
const unsigned char*, size_t, |
| 304 |
const LodePNGCompressSettings*); |
| 305 |
|
| 306 |
const void* custom_context; /*optional custom settings for custom functions*/ |
| 307 |
}; |
| 308 |
|
| 309 |
extern const LodePNGCompressSettings lodepng_default_compress_settings; |
| 310 |
void lodepng_compress_settings_init(LodePNGCompressSettings* settings); |
| 311 |
#endif /*LODEPNG_COMPILE_ENCODER*/ |
| 312 |
|
| 313 |
#ifdef LODEPNG_COMPILE_PNG |
| 314 |
/* |
| 315 |
Color mode of an image. Contains all information required to decode the pixel |
| 316 |
bits to RGBA colors. This information is the same as used in the PNG file |
| 317 |
format, and is used both for PNG and raw image data in LodePNG. |
| 318 |
*/ |
| 319 |
typedef struct LodePNGColorMode |
| 320 |
{ |
| 321 |
/*header (IHDR)*/ |
| 322 |
LodePNGColorType colortype; /*color type, see PNG standard or documentation further in this header file*/ |
| 323 |
unsigned bitdepth; /*bits per sample, see PNG standard or documentation further in this header file*/ |
| 324 |
|
| 325 |
/* |
| 326 |
palette (PLTE and tRNS) |
| 327 |
|
| 328 |
Dynamically allocated with the colors of the palette, including alpha. |
| 329 |
When encoding a PNG, to store your colors in the palette of the LodePNGColorMode, first use |
| 330 |
lodepng_palette_clear, then for each color use lodepng_palette_add. |
| 331 |
If you encode an image without alpha with palette, don't forget to put value 255 in each A byte of the palette. |
| 332 |
|
| 333 |
When decoding, by default you can ignore this palette, since LodePNG already |
| 334 |
fills the palette colors in the pixels of the raw RGBA output. |
| 335 |
|
| 336 |
The palette is only supported for color type 3. |
| 337 |
*/ |
| 338 |
unsigned char* palette; /*palette in RGBARGBA... order. When allocated, must be either 0, or have size 1024*/ |
| 339 |
size_t palettesize; /*palette size in number of colors (amount of bytes is 4 * palettesize)*/ |
| 340 |
|
| 341 |
/* |
| 342 |
transparent color key (tRNS) |
| 343 |
|
| 344 |
This color uses the same bit depth as the bitdepth value in this struct, which can be 1-bit to 16-bit. |
| 345 |
For greyscale PNGs, r, g and b will all 3 be set to the same. |
| 346 |
|
| 347 |
When decoding, by default you can ignore this information, since LodePNG sets |
| 348 |
pixels with this key to transparent already in the raw RGBA output. |
| 349 |
|
| 350 |
The color key is only supported for color types 0 and 2. |
| 351 |
*/ |
| 352 |
unsigned key_defined; /*is a transparent color key given? 0 = false, 1 = true*/ |
| 353 |
unsigned key_r; /*red/greyscale component of color key*/ |
| 354 |
unsigned key_g; /*green component of color key*/ |
| 355 |
unsigned key_b; /*blue component of color key*/ |
| 356 |
} LodePNGColorMode; |
| 357 |
|
| 358 |
/*init, cleanup and copy functions to use with this struct*/ |
| 359 |
void lodepng_color_mode_init(LodePNGColorMode* info); |
| 360 |
void lodepng_color_mode_cleanup(LodePNGColorMode* info); |
| 361 |
/*return value is error code (0 means no error)*/ |
| 362 |
unsigned lodepng_color_mode_copy(LodePNGColorMode* dest, const LodePNGColorMode* source); |
| 363 |
|
| 364 |
void lodepng_palette_clear(LodePNGColorMode* info); |
| 365 |
/*add 1 color to the palette*/ |
| 366 |
unsigned lodepng_palette_add(LodePNGColorMode* info, |
| 367 |
unsigned char r, unsigned char g, unsigned char b, unsigned char a); |
| 368 |
|
| 369 |
/*get the total amount of bits per pixel, based on colortype and bitdepth in the struct*/ |
| 370 |
unsigned lodepng_get_bpp(const LodePNGColorMode* info); |
| 371 |
/*get the amount of color channels used, based on colortype in the struct. |
| 372 |
If a palette is used, it counts as 1 channel.*/ |
| 373 |
unsigned lodepng_get_channels(const LodePNGColorMode* info); |
| 374 |
/*is it a greyscale type? (only colortype 0 or 4)*/ |
| 375 |
unsigned lodepng_is_greyscale_type(const LodePNGColorMode* info); |
| 376 |
/*has it got an alpha channel? (only colortype 2 or 6)*/ |
| 377 |
unsigned lodepng_is_alpha_type(const LodePNGColorMode* info); |
| 378 |
/*has it got a palette? (only colortype 3)*/ |
| 379 |
unsigned lodepng_is_palette_type(const LodePNGColorMode* info); |
| 380 |
/*only returns true if there is a palette and there is a value in the palette with alpha < 255. |
| 381 |
Loops through the palette to check this.*/ |
| 382 |
unsigned lodepng_has_palette_alpha(const LodePNGColorMode* info); |
| 383 |
/* |
| 384 |
Check if the given color info indicates the possibility of having non-opaque pixels in the PNG image. |
| 385 |
Returns true if the image can have translucent or invisible pixels (it still be opaque if it doesn't use such pixels). |
| 386 |
Returns false if the image can only have opaque pixels. |
| 387 |
In detail, it returns true only if it's a color type with alpha, or has a palette with non-opaque values, |
| 388 |
or if "key_defined" is true. |
| 389 |
*/ |
| 390 |
unsigned lodepng_can_have_alpha(const LodePNGColorMode* info); |
| 391 |
/*Returns the byte size of a raw image buffer with given width, height and color mode*/ |
| 392 |
size_t lodepng_get_raw_size(unsigned w, unsigned h, const LodePNGColorMode* color); |
| 393 |
|
| 394 |
#ifdef LODEPNG_COMPILE_ANCILLARY_CHUNKS |
| 395 |
/*The information of a Time chunk in PNG.*/ |
| 396 |
typedef struct LodePNGTime |
| 397 |
{ |
| 398 |
unsigned year; /*2 bytes used (0-65535)*/ |
| 399 |
unsigned month; /*1-12*/ |
| 400 |
unsigned day; /*1-31*/ |
| 401 |
unsigned hour; /*0-23*/ |
| 402 |
unsigned minute; /*0-59*/ |
| 403 |
unsigned second; /*0-60 (to allow for leap seconds)*/ |
| 404 |
} LodePNGTime; |
| 405 |
#endif /*LODEPNG_COMPILE_ANCILLARY_CHUNKS*/ |
| 406 |
|
| 407 |
/*Information about the PNG image, except pixels, width and height.*/ |
| 408 |
typedef struct LodePNGInfo |
| 409 |
{ |
| 410 |
/*header (IHDR), palette (PLTE) and transparency (tRNS) chunks*/ |
| 411 |
unsigned compression_method;/*compression method of the original file. Always 0.*/ |
| 412 |
unsigned filter_method; /*filter method of the original file*/ |
| 413 |
unsigned interlace_method; /*interlace method of the original file: 0=none, 1=Adam7*/ |
| 414 |
LodePNGColorMode color; /*color type and bits, palette and transparency of the PNG file*/ |
| 415 |
|
| 416 |
#ifdef LODEPNG_COMPILE_ANCILLARY_CHUNKS |
| 417 |
/* |
| 418 |
Suggested background color chunk (bKGD) |
| 419 |
|
| 420 |
This uses the same color mode and bit depth as the PNG (except no alpha channel), |
| 421 |
with values truncated to the bit depth in the unsigned integer. |
| 422 |
|
| 423 |
For greyscale and palette PNGs, the value is stored in background_r. The values |
| 424 |
in background_g and background_b are then unused. |
| 425 |
|
| 426 |
So when decoding, you may get these in a different color mode than the one you requested |
| 427 |
for the raw pixels. |
| 428 |
|
| 429 |
When encoding with auto_convert, you must use the color model defined in info_png.color for |
| 430 |
these values. The encoder normally ignores info_png.color when auto_convert is on, but will |
| 431 |
use it to interpret these values (and convert copies of them to its chosen color model). |
| 432 |
|
| 433 |
When encoding, avoid setting this to an expensive color, such as a non-grey value |
| 434 |
when the image is grey, or the compression will be worse since it will be forced to |
| 435 |
write the PNG with a more expensive color mode (when auto_convert is on). |
| 436 |
|
| 437 |
The decoder does not use this background color to edit the color of pixels. This is a |
| 438 |
completely optional metadata feature. |
| 439 |
*/ |
| 440 |
unsigned background_defined; /*is a suggested background color given?*/ |
| 441 |
unsigned background_r; /*red/grey/palette component of suggested background color*/ |
| 442 |
unsigned background_g; /*green component of suggested background color*/ |
| 443 |
unsigned background_b; /*blue component of suggested background color*/ |
| 444 |
|
| 445 |
/* |
| 446 |
non-international text chunks (tEXt and zTXt) |
| 447 |
|
| 448 |
The char** arrays each contain num strings. The actual messages are in |
| 449 |
text_strings, while text_keys are keywords that give a short description what |
| 450 |
the actual text represents, e.g. Title, Author, Description, or anything else. |
| 451 |
|
| 452 |
All the string fields below including keys, names and language tags are null terminated. |
| 453 |
The PNG specification uses null characters for the keys, names and tags, and forbids null |
| 454 |
characters to appear in the main text which is why we can use null termination everywhere here. |
| 455 |
|
| 456 |
A keyword is minimum 1 character and maximum 79 characters long. It's |
| 457 |
discouraged to use a single line length longer than 79 characters for texts. |
| 458 |
|
| 459 |
Don't allocate these text buffers yourself. Use the init/cleanup functions |
| 460 |
correctly and use lodepng_add_text and lodepng_clear_text. |
| 461 |
*/ |
| 462 |
size_t text_num; /*the amount of texts in these char** buffers (there may be more texts in itext)*/ |
| 463 |
char** text_keys; /*the keyword of a text chunk (e.g. "Comment")*/ |
| 464 |
char** text_strings; /*the actual text*/ |
| 465 |
|
| 466 |
/* |
| 467 |
international text chunks (iTXt) |
| 468 |
Similar to the non-international text chunks, but with additional strings |
| 469 |
"langtags" and "transkeys". |
| 470 |
*/ |
| 471 |
size_t itext_num; /*the amount of international texts in this PNG*/ |
| 472 |
char** itext_keys; /*the English keyword of the text chunk (e.g. "Comment")*/ |
| 473 |
char** itext_langtags; /*language tag for this text's language, ISO/IEC 646 string, e.g. ISO 639 language tag*/ |
| 474 |
char** itext_transkeys; /*keyword translated to the international language - UTF-8 string*/ |
| 475 |
char** itext_strings; /*the actual international text - UTF-8 string*/ |
| 476 |
|
| 477 |
/*time chunk (tIME)*/ |
| 478 |
unsigned time_defined; /*set to 1 to make the encoder generate a tIME chunk*/ |
| 479 |
LodePNGTime time; |
| 480 |
|
| 481 |
/*phys chunk (pHYs)*/ |
| 482 |
unsigned phys_defined; /*if 0, there is no pHYs chunk and the values below are undefined, if 1 else there is one*/ |
| 483 |
unsigned phys_x; /*pixels per unit in x direction*/ |
| 484 |
unsigned phys_y; /*pixels per unit in y direction*/ |
| 485 |
unsigned phys_unit; /*may be 0 (unknown unit) or 1 (metre)*/ |
| 486 |
|
| 487 |
/* |
| 488 |
Color profile related chunks: gAMA, cHRM, sRGB, iCPP |
| 489 |
|
| 490 |
LodePNG does not apply any color conversions on pixels in the encoder or decoder and does not interpret these color |
| 491 |
profile values. It merely passes on the information. If you wish to use color profiles and convert colors, please |
| 492 |
use these values with a color management library. |
| 493 |
|
| 494 |
See the PNG, ICC and sRGB specifications for more information about the meaning of these values. |
| 495 |
*/ |
| 496 |
|
| 497 |
/* gAMA chunk: optional, overridden by sRGB or iCCP if those are present. */ |
| 498 |
unsigned gama_defined; /* Whether a gAMA chunk is present (0 = not present, 1 = present). */ |
| 499 |
unsigned gama_gamma; /* Gamma exponent times 100000 */ |
| 500 |
|
| 501 |
/* cHRM chunk: optional, overridden by sRGB or iCCP if those are present. */ |
| 502 |
unsigned chrm_defined; /* Whether a cHRM chunk is present (0 = not present, 1 = present). */ |
| 503 |
unsigned chrm_white_x; /* White Point x times 100000 */ |
| 504 |
unsigned chrm_white_y; /* White Point y times 100000 */ |
| 505 |
unsigned chrm_red_x; /* Red x times 100000 */ |
| 506 |
unsigned chrm_red_y; /* Red y times 100000 */ |
| 507 |
unsigned chrm_green_x; /* Green x times 100000 */ |
| 508 |
unsigned chrm_green_y; /* Green y times 100000 */ |
| 509 |
unsigned chrm_blue_x; /* Blue x times 100000 */ |
| 510 |
unsigned chrm_blue_y; /* Blue y times 100000 */ |
| 511 |
|
| 512 |
/* |
| 513 |
sRGB chunk: optional. May not appear at the same time as iCCP. |
| 514 |
If gAMA is also present gAMA must contain value 45455. |
| 515 |
If cHRM is also present cHRM must contain respectively 31270,32900,64000,33000,30000,60000,15000,6000. |
| 516 |
*/ |
| 517 |
unsigned srgb_defined; /* Whether an sRGB chunk is present (0 = not present, 1 = present). */ |
| 518 |
unsigned srgb_intent; /* Rendering intent: 0=perceptual, 1=rel. colorimetric, 2=saturation, 3=abs. colorimetric */ |
| 519 |
|
| 520 |
/* |
| 521 |
iCCP chunk: optional. May not appear at the same time as sRGB. |
| 522 |
|
| 523 |
LodePNG does not parse or use the ICC profile (except its color space header field for an edge case), a |
| 524 |
separate library to handle the ICC data (not included in LodePNG) format is needed to use it for color |
| 525 |
management and conversions. |
| 526 |
|
| 527 |
For encoding, if iCCP is present, gAMA and cHRM are recommended to be added as well with values that match the ICC |
| 528 |
profile as closely as possible, if you wish to do this you should provide the correct values for gAMA and cHRM and |
| 529 |
enable their '_defined' flags since LodePNG will not automatically compute them from the ICC profile. |
| 530 |
|
| 531 |
For encoding, the ICC profile is required by the PNG specification to be an "RGB" profile for non-grey |
| 532 |
PNG color types and a "GRAY" profile for grey PNG color types. If you disable auto_convert, you must ensure |
| 533 |
the ICC profile type matches your requested color type, else the encoder gives an error. If auto_convert is |
| 534 |
enabled (the default), and the ICC profile is not a good match for the pixel data, this will result in an encoder |
| 535 |
error if the pixel data has non-grey pixels for a GRAY profile, or a silent less-optimal compression of the pixel |
| 536 |
data if the pixels could be encoded as greyscale but the ICC profile is RGB. |
| 537 |
|
| 538 |
To avoid this do not set an ICC profile in the image unless there is a good reason for it, and when doing so |
| 539 |
make sure you compute it carefully to avoid the above problems. |
| 540 |
*/ |
| 541 |
unsigned iccp_defined; /* Whether an iCCP chunk is present (0 = not present, 1 = present). */ |
| 542 |
char* iccp_name; /* Null terminated string with profile name, 1-79 bytes */ |
| 543 |
/* |
| 544 |
The ICC profile in iccp_profile_size bytes. |
| 545 |
Don't allocate this buffer yourself. Use the init/cleanup functions |
| 546 |
correctly and use lodepng_set_icc and lodepng_clear_icc. |
| 547 |
*/ |
| 548 |
unsigned char* iccp_profile; |
| 549 |
unsigned iccp_profile_size; /* The size of iccp_profile in bytes */ |
| 550 |
|
| 551 |
/* End of color profile related chunks */ |
| 552 |
|
| 553 |
|
| 554 |
/* |
| 555 |
unknown chunks: chunks not known by LodePNG, passed on byte for byte. |
| 556 |
|
| 557 |
There are 3 buffers, one for each position in the PNG where unknown chunks can appear. |
| 558 |
Each buffer contains all unknown chunks for that position consecutively. |
| 559 |
The 3 positions are: |
| 560 |
0: between IHDR and PLTE, 1: between PLTE and IDAT, 2: between IDAT and IEND. |
| 561 |
|
| 562 |
For encoding, do not store critical chunks or known chunks that are enabled with a "_defined" flag |
| 563 |
above in here, since the encoder will blindly follow this and could then encode an invalid PNG file |
| 564 |
(such as one with two IHDR chunks or the disallowed combination of sRGB with iCCP). But do use |
| 565 |
this if you wish to store an ancillary chunk that is not supported by LodePNG (such as sPLT or hIST), |
| 566 |
or any non-standard PNG chunk. |
| 567 |
|
| 568 |
Do not allocate or traverse this data yourself. Use the chunk traversing functions declared |
| 569 |
later, such as lodepng_chunk_next and lodepng_chunk_append, to read/write this struct. |
| 570 |
*/ |
| 571 |
unsigned char* unknown_chunks_data[3]; |
| 572 |
size_t unknown_chunks_size[3]; /*size in bytes of the unknown chunks, given for protection*/ |
| 573 |
#endif /*LODEPNG_COMPILE_ANCILLARY_CHUNKS*/ |
| 574 |
} LodePNGInfo; |
| 575 |
|
| 576 |
/*init, cleanup and copy functions to use with this struct*/ |
| 577 |
void lodepng_info_init(LodePNGInfo* info); |
| 578 |
void lodepng_info_cleanup(LodePNGInfo* info); |
| 579 |
/*return value is error code (0 means no error)*/ |
| 580 |
unsigned lodepng_info_copy(LodePNGInfo* dest, const LodePNGInfo* source); |
| 581 |
|
| 582 |
#ifdef LODEPNG_COMPILE_ANCILLARY_CHUNKS |
| 583 |
unsigned lodepng_add_text(LodePNGInfo* info, const char* key, const char* str); /*push back both texts at once*/ |
| 584 |
void lodepng_clear_text(LodePNGInfo* info); /*use this to clear the texts again after you filled them in*/ |
| 585 |
|
| 586 |
unsigned lodepng_add_itext(LodePNGInfo* info, const char* key, const char* langtag, |
| 587 |
const char* transkey, const char* str); /*push back the 4 texts of 1 chunk at once*/ |
| 588 |
void lodepng_clear_itext(LodePNGInfo* info); /*use this to clear the itexts again after you filled them in*/ |
| 589 |
|
| 590 |
/*replaces if exists*/ |
| 591 |
unsigned lodepng_set_icc(LodePNGInfo* info, const char* name, const unsigned char* profile, unsigned profile_size); |
| 592 |
void lodepng_clear_icc(LodePNGInfo* info); /*use this to clear the texts again after you filled them in*/ |
| 593 |
#endif /*LODEPNG_COMPILE_ANCILLARY_CHUNKS*/ |
| 594 |
|
| 595 |
/* |
| 596 |
Converts raw buffer from one color type to another color type, based on |
| 597 |
LodePNGColorMode structs to describe the input and output color type. |
| 598 |
See the reference manual at the end of this header file to see which color conversions are supported. |
| 599 |
return value = LodePNG error code (0 if all went ok, an error if the conversion isn't supported) |
| 600 |
The out buffer must have size (w * h * bpp + 7) / 8, where bpp is the bits per pixel |
| 601 |
of the output color type (lodepng_get_bpp). |
| 602 |
For < 8 bpp images, there should not be padding bits at the end of scanlines. |
| 603 |
For 16-bit per channel colors, uses big endian format like PNG does. |
| 604 |
Return value is LodePNG error code |
| 605 |
*/ |
| 606 |
unsigned lodepng_convert(unsigned char* out, const unsigned char* in, |
| 607 |
const LodePNGColorMode* mode_out, const LodePNGColorMode* mode_in, |
| 608 |
unsigned w, unsigned h); |
| 609 |
|
| 610 |
#ifdef LODEPNG_COMPILE_DECODER |
| 611 |
/* |
| 612 |
Settings for the decoder. This contains settings for the PNG and the Zlib |
| 613 |
decoder, but not the Info settings from the Info structs. |
| 614 |
*/ |
| 615 |
typedef struct LodePNGDecoderSettings |
| 616 |
{ |
| 617 |
LodePNGDecompressSettings zlibsettings; /*in here is the setting to ignore Adler32 checksums*/ |
| 618 |
|
| 619 |
/* Check LodePNGDecompressSettings for more ignorable errors such as ignore_adler32 */ |
| 620 |
unsigned ignore_crc; /*ignore CRC checksums*/ |
| 621 |
unsigned ignore_critical; /*ignore unknown critical chunks*/ |
| 622 |
unsigned ignore_end; /*ignore issues at end of file if possible (missing IEND chunk, too large chunk, ...)*/ |
| 623 |
/* TODO: make a system involving warnings with levels and a strict mode instead. Other potentially recoverable |
| 624 |
errors: srgb rendering intent value, size of content of ancillary chunks, more than 79 characters for some |
| 625 |
strings, placement/combination rules for ancillary chunks, crc of unknown chunks, allowed characters |
| 626 |
in string keys, etc... */ |
| 627 |
|
| 628 |
unsigned color_convert; /*whether to convert the PNG to the color type you want. Default: yes*/ |
| 629 |
|
| 630 |
#ifdef LODEPNG_COMPILE_ANCILLARY_CHUNKS |
| 631 |
unsigned read_text_chunks; /*if false but remember_unknown_chunks is true, they're stored in the unknown chunks*/ |
| 632 |
/*store all bytes from unknown chunks in the LodePNGInfo (off by default, useful for a png editor)*/ |
| 633 |
unsigned remember_unknown_chunks; |
| 634 |
#endif /*LODEPNG_COMPILE_ANCILLARY_CHUNKS*/ |
| 635 |
} LodePNGDecoderSettings; |
| 636 |
|
| 637 |
void lodepng_decoder_settings_init(LodePNGDecoderSettings* settings); |
| 638 |
#endif /*LODEPNG_COMPILE_DECODER*/ |
| 639 |
|
| 640 |
#ifdef LODEPNG_COMPILE_ENCODER |
| 641 |
/*automatically use color type with less bits per pixel if losslessly possible. Default: AUTO*/ |
| 642 |
typedef enum LodePNGFilterStrategy |
| 643 |
{ |
| 644 |
/*every filter at zero*/ |
| 645 |
LFS_ZERO, |
| 646 |
/*Use filter that gives minimum sum, as described in the official PNG filter heuristic.*/ |
| 647 |
LFS_MINSUM, |
| 648 |
/*Use the filter type that gives smallest Shannon entropy for this scanline. Depending |
| 649 |
on the image, this is better or worse than minsum.*/ |
| 650 |
LFS_ENTROPY, |
| 651 |
/* |
| 652 |
Brute-force-search PNG filters by compressing each filter for each scanline. |
| 653 |
Experimental, very slow, and only rarely gives better compression than MINSUM. |
| 654 |
*/ |
| 655 |
LFS_BRUTE_FORCE, |
| 656 |
/*use predefined_filters buffer: you specify the filter type for each scanline*/ |
| 657 |
LFS_PREDEFINED |
| 658 |
} LodePNGFilterStrategy; |
| 659 |
|
| 660 |
/*Gives characteristics about the integer RGBA colors of the image (count, alpha channel usage, bit depth, ...), |
| 661 |
which helps decide which color model to use for encoding. |
| 662 |
Used internally by default if "auto_convert" is enabled. Public because it's useful for custom algorithms. |
| 663 |
NOTE: This is not related to the ICC color profile, search "iccp_profile" instead to find the ICC/chromacity/... |
| 664 |
fields in this header file.*/ |
| 665 |
typedef struct LodePNGColorProfile |
| 666 |
{ |
| 667 |
unsigned colored; /*not greyscale*/ |
| 668 |
unsigned key; /*image is not opaque and color key is possible instead of full alpha*/ |
| 669 |
unsigned short key_r; /*key values, always as 16-bit, in 8-bit case the byte is duplicated, e.g. 65535 means 255*/ |
| 670 |
unsigned short key_g; |
| 671 |
unsigned short key_b; |
| 672 |
unsigned alpha; /*image is not opaque and alpha channel or alpha palette required*/ |
| 673 |
unsigned numcolors; /*amount of colors, up to 257. Not valid if bits == 16.*/ |
| 674 |
unsigned char palette[1024]; /*Remembers up to the first 256 RGBA colors, in no particular order*/ |
| 675 |
unsigned bits; /*bits per channel (not for palette). 1,2 or 4 for greyscale only. 16 if 16-bit per channel required.*/ |
| 676 |
size_t numpixels; |
| 677 |
} LodePNGColorProfile; |
| 678 |
|
| 679 |
void lodepng_color_profile_init(LodePNGColorProfile* profile); |
| 680 |
|
| 681 |
/*Get a LodePNGColorProfile of the image. The profile must already have been inited. |
| 682 |
NOTE: This is not related to the ICC color profile, search "iccp_profile" instead to find the ICC/chromacity/... |
| 683 |
fields in this header file.*/ |
| 684 |
unsigned lodepng_get_color_profile(LodePNGColorProfile* profile, |
| 685 |
const unsigned char* image, unsigned w, unsigned h, |
| 686 |
const LodePNGColorMode* mode_in); |
| 687 |
/*The function LodePNG uses internally to decide the PNG color with auto_convert. |
| 688 |
Chooses an optimal color model, e.g. grey if only grey pixels, palette if < 256 colors, ...*/ |
| 689 |
unsigned lodepng_auto_choose_color(LodePNGColorMode* mode_out, |
| 690 |
const unsigned char* image, unsigned w, unsigned h, |
| 691 |
const LodePNGColorMode* mode_in); |
| 692 |
|
| 693 |
/*Settings for the encoder.*/ |
| 694 |
typedef struct LodePNGEncoderSettings |
| 695 |
{ |
| 696 |
LodePNGCompressSettings zlibsettings; /*settings for the zlib encoder, such as window size, ...*/ |
| 697 |
|
| 698 |
unsigned auto_convert; /*automatically choose output PNG color type. Default: true*/ |
| 699 |
|
| 700 |
/*If true, follows the official PNG heuristic: if the PNG uses a palette or lower than |
| 701 |
8 bit depth, set all filters to zero. Otherwise use the filter_strategy. Note that to |
| 702 |
completely follow the official PNG heuristic, filter_palette_zero must be true and |
| 703 |
filter_strategy must be LFS_MINSUM*/ |
| 704 |
unsigned filter_palette_zero; |
| 705 |
/*Which filter strategy to use when not using zeroes due to filter_palette_zero. |
| 706 |
Set filter_palette_zero to 0 to ensure always using your chosen strategy. Default: LFS_MINSUM*/ |
| 707 |
LodePNGFilterStrategy filter_strategy; |
| 708 |
/*used if filter_strategy is LFS_PREDEFINED. In that case, this must point to a buffer with |
| 709 |
the same length as the amount of scanlines in the image, and each value must <= 5. You |
| 710 |
have to cleanup this buffer, LodePNG will never free it. Don't forget that filter_palette_zero |
| 711 |
must be set to 0 to ensure this is also used on palette or low bitdepth images.*/ |
| 712 |
const unsigned char* predefined_filters; |
| 713 |
|
| 714 |
/*force creating a PLTE chunk if colortype is 2 or 6 (= a suggested palette). |
| 715 |
If colortype is 3, PLTE is _always_ created.*/ |
| 716 |
unsigned force_palette; |
| 717 |
#ifdef LODEPNG_COMPILE_ANCILLARY_CHUNKS |
| 718 |
/*add LodePNG identifier and version as a text chunk, for debugging*/ |
| 719 |
unsigned add_id; |
| 720 |
/*encode text chunks as zTXt chunks instead of tEXt chunks, and use compression in iTXt chunks*/ |
| 721 |
unsigned text_compression; |
| 722 |
#endif /*LODEPNG_COMPILE_ANCILLARY_CHUNKS*/ |
| 723 |
} LodePNGEncoderSettings; |
| 724 |
|
| 725 |
void lodepng_encoder_settings_init(LodePNGEncoderSettings* settings); |
| 726 |
#endif /*LODEPNG_COMPILE_ENCODER*/ |
| 727 |
|
| 728 |
|
| 729 |
#if defined(LODEPNG_COMPILE_DECODER) || defined(LODEPNG_COMPILE_ENCODER) |
| 730 |
/*The settings, state and information for extended encoding and decoding.*/ |
| 731 |
typedef struct LodePNGState |
| 732 |
{ |
| 733 |
#ifdef LODEPNG_COMPILE_DECODER |
| 734 |
LodePNGDecoderSettings decoder; /*the decoding settings*/ |
| 735 |
#endif /*LODEPNG_COMPILE_DECODER*/ |
| 736 |
#ifdef LODEPNG_COMPILE_ENCODER |
| 737 |
LodePNGEncoderSettings encoder; /*the encoding settings*/ |
| 738 |
#endif /*LODEPNG_COMPILE_ENCODER*/ |
| 739 |
LodePNGColorMode info_raw; /*specifies the format in which you would like to get the raw pixel buffer*/ |
| 740 |
LodePNGInfo info_png; /*info of the PNG image obtained after decoding*/ |
| 741 |
unsigned error; |
| 742 |
#ifdef LODEPNG_COMPILE_CPP |
| 743 |
/* For the lodepng::State subclass. */ |
| 744 |
virtual ~LodePNGState(){} |
| 745 |
#endif |
| 746 |
} LodePNGState; |
| 747 |
|
| 748 |
/*init, cleanup and copy functions to use with this struct*/ |
| 749 |
void lodepng_state_init(LodePNGState* state); |
| 750 |
void lodepng_state_cleanup(LodePNGState* state); |
| 751 |
void lodepng_state_copy(LodePNGState* dest, const LodePNGState* source); |
| 752 |
#endif /* defined(LODEPNG_COMPILE_DECODER) || defined(LODEPNG_COMPILE_ENCODER) */ |
| 753 |
|
| 754 |
#ifdef LODEPNG_COMPILE_DECODER |
| 755 |
/* |
| 756 |
Same as lodepng_decode_memory, but uses a LodePNGState to allow custom settings and |
| 757 |
getting much more information about the PNG image and color mode. |
| 758 |
*/ |
| 759 |
unsigned lodepng_decode(unsigned char** out, unsigned* w, unsigned* h, |
| 760 |
LodePNGState* state, |
| 761 |
const unsigned char* in, size_t insize); |
| 762 |
|
| 763 |
/* |
| 764 |
Read the PNG header, but not the actual data. This returns only the information |
| 765 |
that is in the IHDR chunk of the PNG, such as width, height and color type. The |
| 766 |
information is placed in the info_png field of the LodePNGState. |
| 767 |
*/ |
| 768 |
unsigned lodepng_inspect(unsigned* w, unsigned* h, |
| 769 |
LodePNGState* state, |
| 770 |
const unsigned char* in, size_t insize); |
| 771 |
#endif /*LODEPNG_COMPILE_DECODER*/ |
| 772 |
|
| 773 |
|
| 774 |
#ifdef LODEPNG_COMPILE_ENCODER |
| 775 |
/*This function allocates the out buffer with standard malloc and stores the size in *outsize.*/ |
| 776 |
unsigned lodepng_encode(unsigned char** out, size_t* outsize, |
| 777 |
const unsigned char* image, unsigned w, unsigned h, |
| 778 |
LodePNGState* state); |
| 779 |
#endif /*LODEPNG_COMPILE_ENCODER*/ |
| 780 |
|
| 781 |
/* |
| 782 |
The lodepng_chunk functions are normally not needed, except to traverse the |
| 783 |
unknown chunks stored in the LodePNGInfo struct, or add new ones to it. |
| 784 |
It also allows traversing the chunks of an encoded PNG file yourself. |
| 785 |
|
| 786 |
The chunk pointer always points to the beginning of the chunk itself, that is |
| 787 |
the first byte of the 4 length bytes. |
| 788 |
|
| 789 |
In the PNG file format, chunks have the following format: |
| 790 |
-4 bytes length: length of the data of the chunk in bytes (chunk itself is 12 bytes longer) |
| 791 |
-4 bytes chunk name (ASCII a-z,A-Z only, see below) |
| 792 |
-length bytes of data (may be 0 bytes if length was 0) |
| 793 |
-4 bytes of CRC, computed on chunk name + data |
| 794 |
|
| 795 |
The first chunk starts at the 8th byte of the PNG file, the entire rest of the file |
| 796 |
exists out of concatenated chunks with the above format. |
| 797 |
|
| 798 |
PNG standard chunk ASCII naming conventions: |
| 799 |
-First byte: uppercase = critical, lowercase = ancillary |
| 800 |
-Second byte: uppercase = public, lowercase = private |
| 801 |
-Third byte: must be uppercase |
| 802 |
-Fourth byte: uppercase = unsafe to copy, lowercase = safe to copy |
| 803 |
*/ |
| 804 |
|
| 805 |
/* |
| 806 |
Gets the length of the data of the chunk. Total chunk length has 12 bytes more. |
| 807 |
There must be at least 4 bytes to read from. If the result value is too large, |
| 808 |
it may be corrupt data. |
| 809 |
*/ |
| 810 |
unsigned lodepng_chunk_length(const unsigned char* chunk); |
| 811 |
|
| 812 |
/*puts the 4-byte type in null terminated string*/ |
| 813 |
void lodepng_chunk_type(char type[5], const unsigned char* chunk); |
| 814 |
|
| 815 |
/*check if the type is the given type*/ |
| 816 |
unsigned char lodepng_chunk_type_equals(const unsigned char* chunk, const char* type); |
| 817 |
|
| 818 |
/*0: it's one of the critical chunk types, 1: it's an ancillary chunk (see PNG standard)*/ |
| 819 |
unsigned char lodepng_chunk_ancillary(const unsigned char* chunk); |
| 820 |
|
| 821 |
/*0: public, 1: private (see PNG standard)*/ |
| 822 |
unsigned char lodepng_chunk_private(const unsigned char* chunk); |
| 823 |
|
| 824 |
/*0: the chunk is unsafe to copy, 1: the chunk is safe to copy (see PNG standard)*/ |
| 825 |
unsigned char lodepng_chunk_safetocopy(const unsigned char* chunk); |
| 826 |
|
| 827 |
/*get pointer to the data of the chunk, where the input points to the header of the chunk*/ |
| 828 |
unsigned char* lodepng_chunk_data(unsigned char* chunk); |
| 829 |
const unsigned char* lodepng_chunk_data_const(const unsigned char* chunk); |
| 830 |
|
| 831 |
/*returns 0 if the crc is correct, 1 if it's incorrect (0 for OK as usual!)*/ |
| 832 |
unsigned lodepng_chunk_check_crc(const unsigned char* chunk); |
| 833 |
|
| 834 |
/*generates the correct CRC from the data and puts it in the last 4 bytes of the chunk*/ |
| 835 |
void lodepng_chunk_generate_crc(unsigned char* chunk); |
| 836 |
|
| 837 |
/* |
| 838 |
Iterate to next chunks, allows iterating through all chunks of the PNG file. Expects at least 4 readable |
| 839 |
bytes of memory in the input pointer. Will output pointer to the start of the next chunk or the end of the |
| 840 |
file if there is no more chunk after this. Start this process at the 8th byte of the PNG file. In a non-corrupt |
| 841 |
PNG file, the last chunk should have name "IEND". |
| 842 |
*/ |
| 843 |
unsigned char* lodepng_chunk_next(unsigned char* chunk); |
| 844 |
const unsigned char* lodepng_chunk_next_const(const unsigned char* chunk); |
| 845 |
|
| 846 |
/* |
| 847 |
Appends chunk to the data in out. The given chunk should already have its chunk header. |
| 848 |
The out variable and outlength are updated to reflect the new reallocated buffer. |
| 849 |
Returns error code (0 if it went ok) |
| 850 |
*/ |
| 851 |
unsigned lodepng_chunk_append(unsigned char** out, size_t* outlength, const unsigned char* chunk); |
| 852 |
|
| 853 |
/* |
| 854 |
Appends new chunk to out. The chunk to append is given by giving its length, type |
| 855 |
and data separately. The type is a 4-letter string. |
| 856 |
The out variable and outlength are updated to reflect the new reallocated buffer. |
| 857 |
Returne error code (0 if it went ok) |
| 858 |
*/ |
| 859 |
unsigned lodepng_chunk_create(unsigned char** out, size_t* outlength, unsigned length, |
| 860 |
const char* type, const unsigned char* data); |
| 861 |
|
| 862 |
|
| 863 |
/*Calculate CRC32 of buffer*/ |
| 864 |
unsigned lodepng_crc32(const unsigned char* buf, size_t len); |
| 865 |
#endif /*LODEPNG_COMPILE_PNG*/ |
| 866 |
|
| 867 |
|
| 868 |
#ifdef LODEPNG_COMPILE_ZLIB |
| 869 |
/* |
| 870 |
This zlib part can be used independently to zlib compress and decompress a |
| 871 |
buffer. It cannot be used to create gzip files however, and it only supports the |
| 872 |
part of zlib that is required for PNG, it does not support dictionaries. |
| 873 |
*/ |
| 874 |
|
| 875 |
#ifdef LODEPNG_COMPILE_DECODER |
| 876 |
/*Inflate a buffer. Inflate is the decompression step of deflate. Out buffer must be freed after use.*/ |
| 877 |
unsigned lodepng_inflate(unsigned char** out, size_t* outsize, |
| 878 |
const unsigned char* in, size_t insize, |
| 879 |
const LodePNGDecompressSettings* settings); |
| 880 |
|
| 881 |
/* |
| 882 |
Decompresses Zlib data. Reallocates the out buffer and appends the data. The |
| 883 |
data must be according to the zlib specification. |
| 884 |
Either, *out must be NULL and *outsize must be 0, or, *out must be a valid |
| 885 |
buffer and *outsize its size in bytes. out must be freed by user after usage. |
| 886 |
*/ |
| 887 |
unsigned lodepng_zlib_decompress(unsigned char** out, size_t* outsize, |
| 888 |
const unsigned char* in, size_t insize, |
| 889 |
const LodePNGDecompressSettings* settings); |
| 890 |
#endif /*LODEPNG_COMPILE_DECODER*/ |
| 891 |
|
| 892 |
#ifdef LODEPNG_COMPILE_ENCODER |
| 893 |
/* |
| 894 |
Compresses data with Zlib. Reallocates the out buffer and appends the data. |
| 895 |
Zlib adds a small header and trailer around the deflate data. |
| 896 |
The data is output in the format of the zlib specification. |
| 897 |
Either, *out must be NULL and *outsize must be 0, or, *out must be a valid |
| 898 |
buffer and *outsize its size in bytes. out must be freed by user after usage. |
| 899 |
*/ |
| 900 |
unsigned lodepng_zlib_compress(unsigned char** out, size_t* outsize, |
| 901 |
const unsigned char* in, size_t insize, |
| 902 |
const LodePNGCompressSettings* settings); |
| 903 |
|
| 904 |
/* |
| 905 |
Find length-limited Huffman code for given frequencies. This function is in the |
| 906 |
public interface only for tests, it's used internally by lodepng_deflate. |
| 907 |
*/ |
| 908 |
unsigned lodepng_huffman_code_lengths(unsigned* lengths, const unsigned* frequencies, |
| 909 |
size_t numcodes, unsigned maxbitlen); |
| 910 |
|
| 911 |
/*Compress a buffer with deflate. See RFC 1951. Out buffer must be freed after use.*/ |
| 912 |
unsigned lodepng_deflate(unsigned char** out, size_t* outsize, |
| 913 |
const unsigned char* in, size_t insize, |
| 914 |
const LodePNGCompressSettings* settings); |
| 915 |
|
| 916 |
#endif /*LODEPNG_COMPILE_ENCODER*/ |
| 917 |
#endif /*LODEPNG_COMPILE_ZLIB*/ |
| 918 |
|
| 919 |
#ifdef LODEPNG_COMPILE_DISK |
| 920 |
/* |
| 921 |
Load a file from disk into buffer. The function allocates the out buffer, and |
| 922 |
after usage you should free it. |
| 923 |
out: output parameter, contains pointer to loaded buffer. |
| 924 |
outsize: output parameter, size of the allocated out buffer |
| 925 |
filename: the path to the file to load |
| 926 |
return value: error code (0 means ok) |
| 927 |
*/ |
| 928 |
unsigned lodepng_load_file(unsigned char** out, size_t* outsize, const char* filename); |
| 929 |
|
| 930 |
/* |
| 931 |
Save a file from buffer to disk. Warning, if it exists, this function overwrites |
| 932 |
the file without warning! |
| 933 |
buffer: the buffer to write |
| 934 |
buffersize: size of the buffer to write |
| 935 |
filename: the path to the file to save to |
| 936 |
return value: error code (0 means ok) |
| 937 |
*/ |
| 938 |
unsigned lodepng_save_file(const unsigned char* buffer, size_t buffersize, const char* filename); |
| 939 |
#endif /*LODEPNG_COMPILE_DISK*/ |
| 940 |
|
| 941 |
#ifdef LODEPNG_COMPILE_CPP |
| 942 |
/* The LodePNG C++ wrapper uses std::vectors instead of manually allocated memory buffers. */ |
| 943 |
namespace lodepng |
| 944 |
{ |
| 945 |
#ifdef LODEPNG_COMPILE_PNG |
| 946 |
class State : public LodePNGState |
| 947 |
{ |
| 948 |
public: |
| 949 |
State(); |
| 950 |
State(const State& other); |
| 951 |
virtual ~State(); |
| 952 |
State& operator=(const State& other); |
| 953 |
}; |
| 954 |
|
| 955 |
#ifdef LODEPNG_COMPILE_DECODER |
| 956 |
/* Same as other lodepng::decode, but using a State for more settings and information. */ |
| 957 |
unsigned decode(std::vector<unsigned char>& out, unsigned& w, unsigned& h, |
| 958 |
State& state, |
| 959 |
const unsigned char* in, size_t insize); |
| 960 |
unsigned decode(std::vector<unsigned char>& out, unsigned& w, unsigned& h, |
| 961 |
State& state, |
| 962 |
const std::vector<unsigned char>& in); |
| 963 |
#endif /*LODEPNG_COMPILE_DECODER*/ |
| 964 |
|
| 965 |
#ifdef LODEPNG_COMPILE_ENCODER |
| 966 |
/* Same as other lodepng::encode, but using a State for more settings and information. */ |
| 967 |
unsigned encode(std::vector<unsigned char>& out, |
| 968 |
const unsigned char* in, unsigned w, unsigned h, |
| 969 |
State& state); |
| 970 |
unsigned encode(std::vector<unsigned char>& out, |
| 971 |
const std::vector<unsigned char>& in, unsigned w, unsigned h, |
| 972 |
State& state); |
| 973 |
#endif /*LODEPNG_COMPILE_ENCODER*/ |
| 974 |
|
| 975 |
#ifdef LODEPNG_COMPILE_DISK |
| 976 |
/* |
| 977 |
Load a file from disk into an std::vector. |
| 978 |
return value: error code (0 means ok) |
| 979 |
*/ |
| 980 |
unsigned load_file(std::vector<unsigned char>& buffer, const std::string& filename); |
| 981 |
|
| 982 |
/* |
| 983 |
Save the binary data in an std::vector to a file on disk. The file is overwritten |
| 984 |
without warning. |
| 985 |
*/ |
| 986 |
unsigned save_file(const std::vector<unsigned char>& buffer, const std::string& filename); |
| 987 |
#endif /* LODEPNG_COMPILE_DISK */ |
| 988 |
#endif /* LODEPNG_COMPILE_PNG */ |
| 989 |
|
| 990 |
#ifdef LODEPNG_COMPILE_ZLIB |
| 991 |
#ifdef LODEPNG_COMPILE_DECODER |
| 992 |
/* Zlib-decompress an unsigned char buffer */ |
| 993 |
unsigned decompress(std::vector<unsigned char>& out, const unsigned char* in, size_t insize, |
| 994 |
const LodePNGDecompressSettings& settings = lodepng_default_decompress_settings); |
| 995 |
|
| 996 |
/* Zlib-decompress an std::vector */ |
| 997 |
unsigned decompress(std::vector<unsigned char>& out, const std::vector<unsigned char>& in, |
| 998 |
const LodePNGDecompressSettings& settings = lodepng_default_decompress_settings); |
| 999 |
#endif /* LODEPNG_COMPILE_DECODER */ |
| 1000 |
|
| 1001 |
#ifdef LODEPNG_COMPILE_ENCODER |
| 1002 |
/* Zlib-compress an unsigned char buffer */ |
| 1003 |
unsigned compress(std::vector<unsigned char>& out, const unsigned char* in, size_t insize, |
| 1004 |
const LodePNGCompressSettings& settings = lodepng_default_compress_settings); |
| 1005 |
|
| 1006 |
/* Zlib-compress an std::vector */ |
| 1007 |
unsigned compress(std::vector<unsigned char>& out, const std::vector<unsigned char>& in, |
| 1008 |
const LodePNGCompressSettings& settings = lodepng_default_compress_settings); |
| 1009 |
#endif /* LODEPNG_COMPILE_ENCODER */ |
| 1010 |
#endif /* LODEPNG_COMPILE_ZLIB */ |
| 1011 |
} /* namespace lodepng */ |
| 1012 |
#endif /*LODEPNG_COMPILE_CPP*/ |
| 1013 |
|
| 1014 |
/* |
| 1015 |
TODO: |
| 1016 |
[.] test if there are no memory leaks or security exploits - done a lot but needs to be checked often |
| 1017 |
[.] check compatibility with various compilers - done but needs to be redone for every newer version |
| 1018 |
[X] converting color to 16-bit per channel types |
| 1019 |
[X] support color profile chunk types (but never let them touch RGB values by default) |
| 1020 |
[ ] support all public PNG chunk types |
| 1021 |
[ ] make sure encoder generates no chunks with size > (2^31)-1 |
| 1022 |
[ ] partial decoding (stream processing) |
| 1023 |
[X] let the "isFullyOpaque" function check color keys and transparent palettes too |
| 1024 |
[X] better name for the variables "codes", "codesD", "codelengthcodes", "clcl" and "lldl" |
| 1025 |
[ ] don't stop decoding on errors like 69, 57, 58 (make warnings) |
| 1026 |
[ ] make warnings like: oob palette, checksum fail, data after iend, wrong/unknown crit chunk, no null terminator in text, ... |
| 1027 |
[ ] errors with line numbers (and version) |
| 1028 |
[ ] let the C++ wrapper catch exceptions coming from the standard library and return LodePNG error codes |
| 1029 |
[ ] allow user to provide custom color conversion functions, e.g. for premultiplied alpha, padding bits or not, ... |
| 1030 |
[ ] allow user to give data (void*) to custom allocator |
| 1031 |
*/ |
| 1032 |
|
| 1033 |
#endif /*LODEPNG_H inclusion guard*/ |
| 1034 |
|
| 1035 |
/* |
| 1036 |
LodePNG Documentation |
| 1037 |
--------------------- |
| 1038 |
|
| 1039 |
0. table of contents |
| 1040 |
-------------------- |
| 1041 |
|
| 1042 |
1. about |
| 1043 |
1.1. supported features |
| 1044 |
1.2. features not supported |
| 1045 |
2. C and C++ version |
| 1046 |
3. security |
| 1047 |
4. decoding |
| 1048 |
5. encoding |
| 1049 |
6. color conversions |
| 1050 |
6.1. PNG color types |
| 1051 |
6.2. color conversions |
| 1052 |
6.3. padding bits |
| 1053 |
6.4. A note about 16-bits per channel and endianness |
| 1054 |
7. error values |
| 1055 |
8. chunks and PNG editing |
| 1056 |
9. compiler support |
| 1057 |
10. examples |
| 1058 |
10.1. decoder C++ example |
| 1059 |
10.2. decoder C example |
| 1060 |
11. state settings reference |
| 1061 |
12. changes |
| 1062 |
13. contact information |
| 1063 |
|
| 1064 |
|
| 1065 |
1. about |
| 1066 |
-------- |
| 1067 |
|
| 1068 |
PNG is a file format to store raster images losslessly with good compression, |
| 1069 |
supporting different color types and alpha channel. |
| 1070 |
|
| 1071 |
LodePNG is a PNG codec according to the Portable Network Graphics (PNG) |
| 1072 |
Specification (Second Edition) - W3C Recommendation 10 November 2003. |
| 1073 |
|
| 1074 |
The specifications used are: |
| 1075 |
|
| 1076 |
*) Portable Network Graphics (PNG) Specification (Second Edition): |
| 1077 |
http://www.w3.org/TR/2003/REC-PNG-20031110 |
| 1078 |
*) RFC 1950 ZLIB Compressed Data Format version 3.3: |
| 1079 |
http://www.gzip.org/zlib/rfc-zlib.html |
| 1080 |
*) RFC 1951 DEFLATE Compressed Data Format Specification ver 1.3: |
| 1081 |
http://www.gzip.org/zlib/rfc-deflate.html |
| 1082 |
|
| 1083 |
The most recent version of LodePNG can currently be found at |
| 1084 |
http://lodev.org/lodepng/ |
| 1085 |
|
| 1086 |
LodePNG works both in C (ISO C90) and C++, with a C++ wrapper that adds |
| 1087 |
extra functionality. |
| 1088 |
|
| 1089 |
LodePNG exists out of two files: |
| 1090 |
-lodepng.h: the header file for both C and C++ |
| 1091 |
-lodepng.c(pp): give it the name lodepng.c or lodepng.cpp (or .cc) depending on your usage |
| 1092 |
|
| 1093 |
If you want to start using LodePNG right away without reading this doc, get the |
| 1094 |
examples from the LodePNG website to see how to use it in code, or check the |
| 1095 |
smaller examples in chapter 13 here. |
| 1096 |
|
| 1097 |
LodePNG is simple but only supports the basic requirements. To achieve |
| 1098 |
simplicity, the following design choices were made: There are no dependencies |
| 1099 |
on any external library. There are functions to decode and encode a PNG with |
| 1100 |
a single function call, and extended versions of these functions taking a |
| 1101 |
LodePNGState struct allowing to specify or get more information. By default |
| 1102 |
the colors of the raw image are always RGB or RGBA, no matter what color type |
| 1103 |
the PNG file uses. To read and write files, there are simple functions to |
| 1104 |
convert the files to/from buffers in memory. |
| 1105 |
|
| 1106 |
This all makes LodePNG suitable for loading textures in games, demos and small |
| 1107 |
programs, ... It's less suitable for full fledged image editors, loading PNGs |
| 1108 |
over network (it requires all the image data to be available before decoding can |
| 1109 |
begin), life-critical systems, ... |
| 1110 |
|
| 1111 |
1.1. supported features |
| 1112 |
----------------------- |
| 1113 |
|
| 1114 |
The following features are supported by the decoder: |
| 1115 |
|
| 1116 |
*) decoding of PNGs with any color type, bit depth and interlace mode, to a 24- or 32-bit color raw image, |
| 1117 |
or the same color type as the PNG |
| 1118 |
*) encoding of PNGs, from any raw image to 24- or 32-bit color, or the same color type as the raw image |
| 1119 |
*) Adam7 interlace and deinterlace for any color type |
| 1120 |
*) loading the image from harddisk or decoding it from a buffer from other sources than harddisk |
| 1121 |
*) support for alpha channels, including RGBA color model, translucent palettes and color keying |
| 1122 |
*) zlib decompression (inflate) |
| 1123 |
*) zlib compression (deflate) |
| 1124 |
*) CRC32 and ADLER32 checksums |
| 1125 |
*) handling of unknown chunks, allowing making a PNG editor that stores custom and unknown chunks. |
| 1126 |
*) the following chunks are supported (generated/interpreted) by both encoder and decoder: |
| 1127 |
IHDR: header information |
| 1128 |
PLTE: color palette |
| 1129 |
IDAT: pixel data |
| 1130 |
IEND: the final chunk |
| 1131 |
tRNS: transparency for palettized images |
| 1132 |
tEXt: textual information |
| 1133 |
zTXt: compressed textual information |
| 1134 |
iTXt: international textual information |
| 1135 |
bKGD: suggested background color |
| 1136 |
pHYs: physical dimensions |
| 1137 |
tIME: modification time |
| 1138 |
|
| 1139 |
1.2. features not supported |
| 1140 |
--------------------------- |
| 1141 |
|
| 1142 |
The following features are _not_ supported: |
| 1143 |
|
| 1144 |
*) some features needed to make a conformant PNG-Editor might be still missing. |
| 1145 |
*) partial loading/stream processing. All data must be available and is processed in one call. |
| 1146 |
*) The following public chunks are not supported but treated as unknown chunks by LodePNG |
| 1147 |
cHRM, gAMA, iCCP, sRGB, sBIT, hIST, sPLT |
| 1148 |
Some of these are not supported on purpose: LodePNG wants to provide the RGB values |
| 1149 |
stored in the pixels, not values modified by system dependent gamma or color models. |
| 1150 |
|
| 1151 |
|
| 1152 |
2. C and C++ version |
| 1153 |
-------------------- |
| 1154 |
|
| 1155 |
The C version uses buffers allocated with alloc that you need to free() |
| 1156 |
yourself. You need to use init and cleanup functions for each struct whenever |
| 1157 |
using a struct from the C version to avoid exploits and memory leaks. |
| 1158 |
|
| 1159 |
The C++ version has extra functions with std::vectors in the interface and the |
| 1160 |
lodepng::State class which is a LodePNGState with constructor and destructor. |
| 1161 |
|
| 1162 |
These files work without modification for both C and C++ compilers because all |
| 1163 |
the additional C++ code is in "#ifdef __cplusplus" blocks that make C-compilers |
| 1164 |
ignore it, and the C code is made to compile both with strict ISO C90 and C++. |
| 1165 |
|
| 1166 |
To use the C++ version, you need to rename the source file to lodepng.cpp |
| 1167 |
(instead of lodepng.c), and compile it with a C++ compiler. |
| 1168 |
|
| 1169 |
To use the C version, you need to rename the source file to lodepng.c (instead |
| 1170 |
of lodepng.cpp), and compile it with a C compiler. |
| 1171 |
|
| 1172 |
|
| 1173 |
3. Security |
| 1174 |
----------- |
| 1175 |
|
| 1176 |
Even if carefully designed, it's always possible that LodePNG contains possible |
| 1177 |
exploits. If you discover one, please let me know, and it will be fixed. |
| 1178 |
|
| 1179 |
When using LodePNG, care has to be taken with the C version of LodePNG, as well |
| 1180 |
as the C-style structs when working with C++. The following conventions are used |
| 1181 |
for all C-style structs: |
| 1182 |
|
| 1183 |
-if a struct has a corresponding init function, always call the init function when making a new one |
| 1184 |
-if a struct has a corresponding cleanup function, call it before the struct disappears to avoid memory leaks |
| 1185 |
-if a struct has a corresponding copy function, use the copy function instead of "=". |
| 1186 |
The destination must also be inited already. |
| 1187 |
|
| 1188 |
|
| 1189 |
4. Decoding |
| 1190 |
----------- |
| 1191 |
|
| 1192 |
Decoding converts a PNG compressed image to a raw pixel buffer. |
| 1193 |
|
| 1194 |
Most documentation on using the decoder is at its declarations in the header |
| 1195 |
above. For C, simple decoding can be done with functions such as |
| 1196 |
lodepng_decode32, and more advanced decoding can be done with the struct |
| 1197 |
LodePNGState and lodepng_decode. For C++, all decoding can be done with the |
| 1198 |
various lodepng::decode functions, and lodepng::State can be used for advanced |
| 1199 |
features. |
| 1200 |
|
| 1201 |
When using the LodePNGState, it uses the following fields for decoding: |
| 1202 |
*) LodePNGInfo info_png: it stores extra information about the PNG (the input) in here |
| 1203 |
*) LodePNGColorMode info_raw: here you can say what color mode of the raw image (the output) you want to get |
| 1204 |
*) LodePNGDecoderSettings decoder: you can specify a few extra settings for the decoder to use |
| 1205 |
|
| 1206 |
LodePNGInfo info_png |
| 1207 |
-------------------- |
| 1208 |
|
| 1209 |
After decoding, this contains extra information of the PNG image, except the actual |
| 1210 |
pixels, width and height because these are already gotten directly from the decoder |
| 1211 |
functions. |
| 1212 |
|
| 1213 |
It contains for example the original color type of the PNG image, text comments, |
| 1214 |
suggested background color, etc... More details about the LodePNGInfo struct are |
| 1215 |
at its declaration documentation. |
| 1216 |
|
| 1217 |
LodePNGColorMode info_raw |
| 1218 |
------------------------- |
| 1219 |
|
| 1220 |
When decoding, here you can specify which color type you want |
| 1221 |
the resulting raw image to be. If this is different from the colortype of the |
| 1222 |
PNG, then the decoder will automatically convert the result. This conversion |
| 1223 |
always works, except if you want it to convert a color PNG to greyscale or to |
| 1224 |
a palette with missing colors. |
| 1225 |
|
| 1226 |
By default, 32-bit color is used for the result. |
| 1227 |
|
| 1228 |
LodePNGDecoderSettings decoder |
| 1229 |
------------------------------ |
| 1230 |
|
| 1231 |
The settings can be used to ignore the errors created by invalid CRC and Adler32 |
| 1232 |
chunks, and to disable the decoding of tEXt chunks. |
| 1233 |
|
| 1234 |
There's also a setting color_convert, true by default. If false, no conversion |
| 1235 |
is done, the resulting data will be as it was in the PNG (after decompression) |
| 1236 |
and you'll have to puzzle the colors of the pixels together yourself using the |
| 1237 |
color type information in the LodePNGInfo. |
| 1238 |
|
| 1239 |
|
| 1240 |
5. Encoding |
| 1241 |
----------- |
| 1242 |
|
| 1243 |
Encoding converts a raw pixel buffer to a PNG compressed image. |
| 1244 |
|
| 1245 |
Most documentation on using the encoder is at its declarations in the header |
| 1246 |
above. For C, simple encoding can be done with functions such as |
| 1247 |
lodepng_encode32, and more advanced decoding can be done with the struct |
| 1248 |
LodePNGState and lodepng_encode. For C++, all encoding can be done with the |
| 1249 |
various lodepng::encode functions, and lodepng::State can be used for advanced |
| 1250 |
features. |
| 1251 |
|
| 1252 |
Like the decoder, the encoder can also give errors. However it gives less errors |
| 1253 |
since the encoder input is trusted, the decoder input (a PNG image that could |
| 1254 |
be forged by anyone) is not trusted. |
| 1255 |
|
| 1256 |
When using the LodePNGState, it uses the following fields for encoding: |
| 1257 |
*) LodePNGInfo info_png: here you specify how you want the PNG (the output) to be. |
| 1258 |
*) LodePNGColorMode info_raw: here you say what color type of the raw image (the input) has |
| 1259 |
*) LodePNGEncoderSettings encoder: you can specify a few settings for the encoder to use |
| 1260 |
|
| 1261 |
LodePNGInfo info_png |
| 1262 |
-------------------- |
| 1263 |
|
| 1264 |
When encoding, you use this the opposite way as when decoding: for encoding, |
| 1265 |
you fill in the values you want the PNG to have before encoding. By default it's |
| 1266 |
not needed to specify a color type for the PNG since it's automatically chosen, |
| 1267 |
but it's possible to choose it yourself given the right settings. |
| 1268 |
|
| 1269 |
The encoder will not always exactly match the LodePNGInfo struct you give, |
| 1270 |
it tries as close as possible. Some things are ignored by the encoder. The |
| 1271 |
encoder uses, for example, the following settings from it when applicable: |
| 1272 |
colortype and bitdepth, text chunks, time chunk, the color key, the palette, the |
| 1273 |
background color, the interlace method, unknown chunks, ... |
| 1274 |
|
| 1275 |
When encoding to a PNG with colortype 3, the encoder will generate a PLTE chunk. |
| 1276 |
If the palette contains any colors for which the alpha channel is not 255 (so |
| 1277 |
there are translucent colors in the palette), it'll add a tRNS chunk. |
| 1278 |
|
| 1279 |
LodePNGColorMode info_raw |
| 1280 |
------------------------- |
| 1281 |
|
| 1282 |
You specify the color type of the raw image that you give to the input here, |
| 1283 |
including a possible transparent color key and palette you happen to be using in |
| 1284 |
your raw image data. |
| 1285 |
|
| 1286 |
By default, 32-bit color is assumed, meaning your input has to be in RGBA |
| 1287 |
format with 4 bytes (unsigned chars) per pixel. |
| 1288 |
|
| 1289 |
LodePNGEncoderSettings encoder |
| 1290 |
------------------------------ |
| 1291 |
|
| 1292 |
The following settings are supported (some are in sub-structs): |
| 1293 |
*) auto_convert: when this option is enabled, the encoder will |
| 1294 |
automatically choose the smallest possible color mode (including color key) that |
| 1295 |
can encode the colors of all pixels without information loss. |
| 1296 |
*) btype: the block type for LZ77. 0 = uncompressed, 1 = fixed huffman tree, |
| 1297 |
2 = dynamic huffman tree (best compression). Should be 2 for proper |
| 1298 |
compression. |
| 1299 |
*) use_lz77: whether or not to use LZ77 for compressed block types. Should be |
| 1300 |
true for proper compression. |
| 1301 |
*) windowsize: the window size used by the LZ77 encoder (1 - 32768). Has value |
| 1302 |
2048 by default, but can be set to 32768 for better, but slow, compression. |
| 1303 |
*) force_palette: if colortype is 2 or 6, you can make the encoder write a PLTE |
| 1304 |
chunk if force_palette is true. This can used as suggested palette to convert |
| 1305 |
to by viewers that don't support more than 256 colors (if those still exist) |
| 1306 |
*) add_id: add text chunk "Encoder: LodePNG <version>" to the image. |
| 1307 |
*) text_compression: default 1. If 1, it'll store texts as zTXt instead of tEXt chunks. |
| 1308 |
zTXt chunks use zlib compression on the text. This gives a smaller result on |
| 1309 |
large texts but a larger result on small texts (such as a single program name). |
| 1310 |
It's all tEXt or all zTXt though, there's no separate setting per text yet. |
| 1311 |
|
| 1312 |
|
| 1313 |
6. color conversions |
| 1314 |
-------------------- |
| 1315 |
|
| 1316 |
An important thing to note about LodePNG, is that the color type of the PNG, and |
| 1317 |
the color type of the raw image, are completely independent. By default, when |
| 1318 |
you decode a PNG, you get the result as a raw image in the color type you want, |
| 1319 |
no matter whether the PNG was encoded with a palette, greyscale or RGBA color. |
| 1320 |
And if you encode an image, by default LodePNG will automatically choose the PNG |
| 1321 |
color type that gives good compression based on the values of colors and amount |
| 1322 |
of colors in the image. It can be configured to let you control it instead as |
| 1323 |
well, though. |
| 1324 |
|
| 1325 |
To be able to do this, LodePNG does conversions from one color mode to another. |
| 1326 |
It can convert from almost any color type to any other color type, except the |
| 1327 |
following conversions: RGB to greyscale is not supported, and converting to a |
| 1328 |
palette when the palette doesn't have a required color is not supported. This is |
| 1329 |
not supported on purpose: this is information loss which requires a color |
| 1330 |
reduction algorithm that is beyong the scope of a PNG encoder (yes, RGB to grey |
| 1331 |
is easy, but there are multiple ways if you want to give some channels more |
| 1332 |
weight). |
| 1333 |
|
| 1334 |
By default, when decoding, you get the raw image in 32-bit RGBA or 24-bit RGB |
| 1335 |
color, no matter what color type the PNG has. And by default when encoding, |
| 1336 |
LodePNG automatically picks the best color model for the output PNG, and expects |
| 1337 |
the input image to be 32-bit RGBA or 24-bit RGB. So, unless you want to control |
| 1338 |
the color format of the images yourself, you can skip this chapter. |
| 1339 |
|
| 1340 |
6.1. PNG color types |
| 1341 |
-------------------- |
| 1342 |
|
| 1343 |
A PNG image can have many color types, ranging from 1-bit color to 64-bit color, |
| 1344 |
as well as palettized color modes. After the zlib decompression and unfiltering |
| 1345 |
in the PNG image is done, the raw pixel data will have that color type and thus |
| 1346 |
a certain amount of bits per pixel. If you want the output raw image after |
| 1347 |
decoding to have another color type, a conversion is done by LodePNG. |
| 1348 |
|
| 1349 |
The PNG specification gives the following color types: |
| 1350 |
|
| 1351 |
0: greyscale, bit depths 1, 2, 4, 8, 16 |
| 1352 |
2: RGB, bit depths 8 and 16 |
| 1353 |
3: palette, bit depths 1, 2, 4 and 8 |
| 1354 |
4: greyscale with alpha, bit depths 8 and 16 |
| 1355 |
6: RGBA, bit depths 8 and 16 |
| 1356 |
|
| 1357 |
Bit depth is the amount of bits per pixel per color channel. So the total amount |
| 1358 |
of bits per pixel is: amount of channels * bitdepth. |
| 1359 |
|
| 1360 |
6.2. color conversions |
| 1361 |
---------------------- |
| 1362 |
|
| 1363 |
As explained in the sections about the encoder and decoder, you can specify |
| 1364 |
color types and bit depths in info_png and info_raw to change the default |
| 1365 |
behaviour. |
| 1366 |
|
| 1367 |
If, when decoding, you want the raw image to be something else than the default, |
| 1368 |
you need to set the color type and bit depth you want in the LodePNGColorMode, |
| 1369 |
or the parameters colortype and bitdepth of the simple decoding function. |
| 1370 |
|
| 1371 |
If, when encoding, you use another color type than the default in the raw input |
| 1372 |
image, you need to specify its color type and bit depth in the LodePNGColorMode |
| 1373 |
of the raw image, or use the parameters colortype and bitdepth of the simple |
| 1374 |
encoding function. |
| 1375 |
|
| 1376 |
If, when encoding, you don't want LodePNG to choose the output PNG color type |
| 1377 |
but control it yourself, you need to set auto_convert in the encoder settings |
| 1378 |
to false, and specify the color type you want in the LodePNGInfo of the |
| 1379 |
encoder (including palette: it can generate a palette if auto_convert is true, |
| 1380 |
otherwise not). |
| 1381 |
|
| 1382 |
If the input and output color type differ (whether user chosen or auto chosen), |
| 1383 |
LodePNG will do a color conversion, which follows the rules below, and may |
| 1384 |
sometimes result in an error. |
| 1385 |
|
| 1386 |
To avoid some confusion: |
| 1387 |
-the decoder converts from PNG to raw image |
| 1388 |
-the encoder converts from raw image to PNG |
| 1389 |
-the colortype and bitdepth in LodePNGColorMode info_raw, are those of the raw image |
| 1390 |
-the colortype and bitdepth in the color field of LodePNGInfo info_png, are those of the PNG |
| 1391 |
-when encoding, the color type in LodePNGInfo is ignored if auto_convert |
| 1392 |
is enabled, it is automatically generated instead |
| 1393 |
-when decoding, the color type in LodePNGInfo is set by the decoder to that of the original |
| 1394 |
PNG image, but it can be ignored since the raw image has the color type you requested instead |
| 1395 |
-if the color type of the LodePNGColorMode and PNG image aren't the same, a conversion |
| 1396 |
between the color types is done if the color types are supported. If it is not |
| 1397 |
supported, an error is returned. If the types are the same, no conversion is done. |
| 1398 |
-even though some conversions aren't supported, LodePNG supports loading PNGs from any |
| 1399 |
colortype and saving PNGs to any colortype, sometimes it just requires preparing |
| 1400 |
the raw image correctly before encoding. |
| 1401 |
-both encoder and decoder use the same color converter. |
| 1402 |
|
| 1403 |
Non supported color conversions: |
| 1404 |
-color to greyscale: no error is thrown, but the result will look ugly because |
| 1405 |
only the red channel is taken |
| 1406 |
-anything to palette when that palette does not have that color in it: in this |
| 1407 |
case an error is thrown |
| 1408 |
|
| 1409 |
Supported color conversions: |
| 1410 |
-anything to 8-bit RGB, 8-bit RGBA, 16-bit RGB, 16-bit RGBA |
| 1411 |
-any grey or grey+alpha, to grey or grey+alpha |
| 1412 |
-anything to a palette, as long as the palette has the requested colors in it |
| 1413 |
-removing alpha channel |
| 1414 |
-higher to smaller bitdepth, and vice versa |
| 1415 |
|
| 1416 |
If you want no color conversion to be done (e.g. for speed or control): |
| 1417 |
-In the encoder, you can make it save a PNG with any color type by giving the |
| 1418 |
raw color mode and LodePNGInfo the same color mode, and setting auto_convert to |
| 1419 |
false. |
| 1420 |
-In the decoder, you can make it store the pixel data in the same color type |
| 1421 |
as the PNG has, by setting the color_convert setting to false. Settings in |
| 1422 |
info_raw are then ignored. |
| 1423 |
|
| 1424 |
The function lodepng_convert does the color conversion. It is available in the |
| 1425 |
interface but normally isn't needed since the encoder and decoder already call |
| 1426 |
it. |
| 1427 |
|
| 1428 |
6.3. padding bits |
| 1429 |
----------------- |
| 1430 |
|
| 1431 |
In the PNG file format, if a less than 8-bit per pixel color type is used and the scanlines |
| 1432 |
have a bit amount that isn't a multiple of 8, then padding bits are used so that each |
| 1433 |
scanline starts at a fresh byte. But that is NOT true for the LodePNG raw input and output. |
| 1434 |
The raw input image you give to the encoder, and the raw output image you get from the decoder |
| 1435 |
will NOT have these padding bits, e.g. in the case of a 1-bit image with a width |
| 1436 |
of 7 pixels, the first pixel of the second scanline will the the 8th bit of the first byte, |
| 1437 |
not the first bit of a new byte. |
| 1438 |
|
| 1439 |
6.4. A note about 16-bits per channel and endianness |
| 1440 |
---------------------------------------------------- |
| 1441 |
|
| 1442 |
LodePNG uses unsigned char arrays for 16-bit per channel colors too, just like |
| 1443 |
for any other color format. The 16-bit values are stored in big endian (most |
| 1444 |
significant byte first) in these arrays. This is the opposite order of the |
| 1445 |
little endian used by x86 CPU's. |
| 1446 |
|
| 1447 |
LodePNG always uses big endian because the PNG file format does so internally. |
| 1448 |
Conversions to other formats than PNG uses internally are not supported by |
| 1449 |
LodePNG on purpose, there are myriads of formats, including endianness of 16-bit |
| 1450 |
colors, the order in which you store R, G, B and A, and so on. Supporting and |
| 1451 |
converting to/from all that is outside the scope of LodePNG. |
| 1452 |
|
| 1453 |
This may mean that, depending on your use case, you may want to convert the big |
| 1454 |
endian output of LodePNG to little endian with a for loop. This is certainly not |
| 1455 |
always needed, many applications and libraries support big endian 16-bit colors |
| 1456 |
anyway, but it means you cannot simply cast the unsigned char* buffer to an |
| 1457 |
unsigned short* buffer on x86 CPUs. |
| 1458 |
|
| 1459 |
|
| 1460 |
7. error values |
| 1461 |
--------------- |
| 1462 |
|
| 1463 |
All functions in LodePNG that return an error code, return 0 if everything went |
| 1464 |
OK, or a non-zero code if there was an error. |
| 1465 |
|
| 1466 |
The meaning of the LodePNG error values can be retrieved with the function |
| 1467 |
lodepng_error_text: given the numerical error code, it returns a description |
| 1468 |
of the error in English as a string. |
| 1469 |
|
| 1470 |
Check the implementation of lodepng_error_text to see the meaning of each code. |
| 1471 |
|
| 1472 |
|
| 1473 |
8. chunks and PNG editing |
| 1474 |
------------------------- |
| 1475 |
|
| 1476 |
If you want to add extra chunks to a PNG you encode, or use LodePNG for a PNG |
| 1477 |
editor that should follow the rules about handling of unknown chunks, or if your |
| 1478 |
program is able to read other types of chunks than the ones handled by LodePNG, |
| 1479 |
then that's possible with the chunk functions of LodePNG. |
| 1480 |
|
| 1481 |
A PNG chunk has the following layout: |
| 1482 |
|
| 1483 |
4 bytes length |
| 1484 |
4 bytes type name |
| 1485 |
length bytes data |
| 1486 |
4 bytes CRC |
| 1487 |
|
| 1488 |
8.1. iterating through chunks |
| 1489 |
----------------------------- |
| 1490 |
|
| 1491 |
If you have a buffer containing the PNG image data, then the first chunk (the |
| 1492 |
IHDR chunk) starts at byte number 8 of that buffer. The first 8 bytes are the |
| 1493 |
signature of the PNG and are not part of a chunk. But if you start at byte 8 |
| 1494 |
then you have a chunk, and can check the following things of it. |
| 1495 |
|
| 1496 |
NOTE: none of these functions check for memory buffer boundaries. To avoid |
| 1497 |
exploits, always make sure the buffer contains all the data of the chunks. |
| 1498 |
When using lodepng_chunk_next, make sure the returned value is within the |
| 1499 |
allocated memory. |
| 1500 |
|
| 1501 |
unsigned lodepng_chunk_length(const unsigned char* chunk): |
| 1502 |
|
| 1503 |
Get the length of the chunk's data. The total chunk length is this length + 12. |
| 1504 |
|
| 1505 |
void lodepng_chunk_type(char type[5], const unsigned char* chunk): |
| 1506 |
unsigned char lodepng_chunk_type_equals(const unsigned char* chunk, const char* type): |
| 1507 |
|
| 1508 |
Get the type of the chunk or compare if it's a certain type |
| 1509 |
|
| 1510 |
unsigned char lodepng_chunk_critical(const unsigned char* chunk): |
| 1511 |
unsigned char lodepng_chunk_private(const unsigned char* chunk): |
| 1512 |
unsigned char lodepng_chunk_safetocopy(const unsigned char* chunk): |
| 1513 |
|
| 1514 |
Check if the chunk is critical in the PNG standard (only IHDR, PLTE, IDAT and IEND are). |
| 1515 |
Check if the chunk is private (public chunks are part of the standard, private ones not). |
| 1516 |
Check if the chunk is safe to copy. If it's not, then, when modifying data in a critical |
| 1517 |
chunk, unsafe to copy chunks of the old image may NOT be saved in the new one if your |
| 1518 |
program doesn't handle that type of unknown chunk. |
| 1519 |
|
| 1520 |
unsigned char* lodepng_chunk_data(unsigned char* chunk): |
| 1521 |
const unsigned char* lodepng_chunk_data_const(const unsigned char* chunk): |
| 1522 |
|
| 1523 |
Get a pointer to the start of the data of the chunk. |
| 1524 |
|
| 1525 |
unsigned lodepng_chunk_check_crc(const unsigned char* chunk): |
| 1526 |
void lodepng_chunk_generate_crc(unsigned char* chunk): |
| 1527 |
|
| 1528 |
Check if the crc is correct or generate a correct one. |
| 1529 |
|
| 1530 |
unsigned char* lodepng_chunk_next(unsigned char* chunk): |
| 1531 |
const unsigned char* lodepng_chunk_next_const(const unsigned char* chunk): |
| 1532 |
|
| 1533 |
Iterate to the next chunk. This works if you have a buffer with consecutive chunks. Note that these |
| 1534 |
functions do no boundary checking of the allocated data whatsoever, so make sure there is enough |
| 1535 |
data available in the buffer to be able to go to the next chunk. |
| 1536 |
|
| 1537 |
unsigned lodepng_chunk_append(unsigned char** out, size_t* outlength, const unsigned char* chunk): |
| 1538 |
unsigned lodepng_chunk_create(unsigned char** out, size_t* outlength, unsigned length, |
| 1539 |
const char* type, const unsigned char* data): |
| 1540 |
|
| 1541 |
These functions are used to create new chunks that are appended to the data in *out that has |
| 1542 |
length *outlength. The append function appends an existing chunk to the new data. The create |
| 1543 |
function creates a new chunk with the given parameters and appends it. Type is the 4-letter |
| 1544 |
name of the chunk. |
| 1545 |
|
| 1546 |
8.2. chunks in info_png |
| 1547 |
----------------------- |
| 1548 |
|
| 1549 |
The LodePNGInfo struct contains fields with the unknown chunk in it. It has 3 |
| 1550 |
buffers (each with size) to contain 3 types of unknown chunks: |
| 1551 |
the ones that come before the PLTE chunk, the ones that come between the PLTE |
| 1552 |
and the IDAT chunks, and the ones that come after the IDAT chunks. |
| 1553 |
It's necessary to make the distionction between these 3 cases because the PNG |
| 1554 |
standard forces to keep the ordering of unknown chunks compared to the critical |
| 1555 |
chunks, but does not force any other ordering rules. |
| 1556 |
|
| 1557 |
info_png.unknown_chunks_data[0] is the chunks before PLTE |
| 1558 |
info_png.unknown_chunks_data[1] is the chunks after PLTE, before IDAT |
| 1559 |
info_png.unknown_chunks_data[2] is the chunks after IDAT |
| 1560 |
|
| 1561 |
The chunks in these 3 buffers can be iterated through and read by using the same |
| 1562 |
way described in the previous subchapter. |
| 1563 |
|
| 1564 |
When using the decoder to decode a PNG, you can make it store all unknown chunks |
| 1565 |
if you set the option settings.remember_unknown_chunks to 1. By default, this |
| 1566 |
option is off (0). |
| 1567 |
|
| 1568 |
The encoder will always encode unknown chunks that are stored in the info_png. |
| 1569 |
If you need it to add a particular chunk that isn't known by LodePNG, you can |
| 1570 |
use lodepng_chunk_append or lodepng_chunk_create to the chunk data in |
| 1571 |
info_png.unknown_chunks_data[x]. |
| 1572 |
|
| 1573 |
Chunks that are known by LodePNG should not be added in that way. E.g. to make |
| 1574 |
LodePNG add a bKGD chunk, set background_defined to true and add the correct |
| 1575 |
parameters there instead. |
| 1576 |
|
| 1577 |
|
| 1578 |
9. compiler support |
| 1579 |
------------------- |
| 1580 |
|
| 1581 |
No libraries other than the current standard C library are needed to compile |
| 1582 |
LodePNG. For the C++ version, only the standard C++ library is needed on top. |
| 1583 |
Add the files lodepng.c(pp) and lodepng.h to your project, include |
| 1584 |
lodepng.h where needed, and your program can read/write PNG files. |
| 1585 |
|
| 1586 |
It is compatible with C90 and up, and C++03 and up. |
| 1587 |
|
| 1588 |
If performance is important, use optimization when compiling! For both the |
| 1589 |
encoder and decoder, this makes a large difference. |
| 1590 |
|
| 1591 |
Make sure that LodePNG is compiled with the same compiler of the same version |
| 1592 |
and with the same settings as the rest of the program, or the interfaces with |
| 1593 |
std::vectors and std::strings in C++ can be incompatible. |
| 1594 |
|
| 1595 |
CHAR_BITS must be 8 or higher, because LodePNG uses unsigned chars for octets. |
| 1596 |
|
| 1597 |
*) gcc and g++ |
| 1598 |
|
| 1599 |
LodePNG is developed in gcc so this compiler is natively supported. It gives no |
| 1600 |
warnings with compiler options "-Wall -Wextra -pedantic -ansi", with gcc and g++ |
| 1601 |
version 4.7.1 on Linux, 32-bit and 64-bit. |
| 1602 |
|
| 1603 |
*) Clang |
| 1604 |
|
| 1605 |
Fully supported and warning-free. |
| 1606 |
|
| 1607 |
*) Mingw |
| 1608 |
|
| 1609 |
The Mingw compiler (a port of gcc for Windows) should be fully supported by |
| 1610 |
LodePNG. |
| 1611 |
|
| 1612 |
*) Visual Studio and Visual C++ Express Edition |
| 1613 |
|
| 1614 |
LodePNG should be warning-free with warning level W4. Two warnings were disabled |
| 1615 |
with pragmas though: warning 4244 about implicit conversions, and warning 4996 |
| 1616 |
where it wants to use a non-standard function fopen_s instead of the standard C |
| 1617 |
fopen. |
| 1618 |
|
| 1619 |
Visual Studio may want "stdafx.h" files to be included in each source file and |
| 1620 |
give an error "unexpected end of file while looking for precompiled header". |
| 1621 |
This is not standard C++ and will not be added to the stock LodePNG. You can |
| 1622 |
disable it for lodepng.cpp only by right clicking it, Properties, C/C++, |
| 1623 |
Precompiled Headers, and set it to Not Using Precompiled Headers there. |
| 1624 |
|
| 1625 |
NOTE: Modern versions of VS should be fully supported, but old versions, e.g. |
| 1626 |
VS6, are not guaranteed to work. |
| 1627 |
|
| 1628 |
*) Compilers on Macintosh |
| 1629 |
|
| 1630 |
LodePNG has been reported to work both with gcc and LLVM for Macintosh, both for |
| 1631 |
C and C++. |
| 1632 |
|
| 1633 |
*) Other Compilers |
| 1634 |
|
| 1635 |
If you encounter problems on any compilers, feel free to let me know and I may |
| 1636 |
try to fix it if the compiler is modern and standards complient. |
| 1637 |
|
| 1638 |
|
| 1639 |
10. examples |
| 1640 |
------------ |
| 1641 |
|
| 1642 |
This decoder example shows the most basic usage of LodePNG. More complex |
| 1643 |
examples can be found on the LodePNG website. |
| 1644 |
|
| 1645 |
10.1. decoder C++ example |
| 1646 |
------------------------- |
| 1647 |
|
| 1648 |
#include "lodepng.h" |
| 1649 |
#include <iostream> |
| 1650 |
|
| 1651 |
int main(int argc, char *argv[]) |
| 1652 |
{ |
| 1653 |
const char* filename = argc > 1 ? argv[1] : "test.png"; |
| 1654 |
|
| 1655 |
//load and decode |
| 1656 |
std::vector<unsigned char> image; |
| 1657 |
unsigned width, height; |
| 1658 |
unsigned error = lodepng::decode(image, width, height, filename); |
| 1659 |
|
| 1660 |
//if there's an error, display it |
| 1661 |
if(error) std::cout << "decoder error " << error << ": " << lodepng_error_text(error) << std::endl; |
| 1662 |
|
| 1663 |
//the pixels are now in the vector "image", 4 bytes per pixel, ordered RGBARGBA..., use it as texture, draw it, ... |
| 1664 |
} |
| 1665 |
|
| 1666 |
10.2. decoder C example |
| 1667 |
----------------------- |
| 1668 |
|
| 1669 |
#include "lodepng.h" |
| 1670 |
|
| 1671 |
int main(int argc, char *argv[]) |
| 1672 |
{ |
| 1673 |
unsigned error; |
| 1674 |
unsigned char* image; |
| 1675 |
size_t width, height; |
| 1676 |
const char* filename = argc > 1 ? argv[1] : "test.png"; |
| 1677 |
|
| 1678 |
error = lodepng_decode32_file(&image, &width, &height, filename); |
| 1679 |
|
| 1680 |
if(error) printf("decoder error %u: %s\n", error, lodepng_error_text(error)); |
| 1681 |
|
| 1682 |
/ * use image here * / |
| 1683 |
|
| 1684 |
free(image); |
| 1685 |
return 0; |
| 1686 |
} |
| 1687 |
|
| 1688 |
11. state settings reference |
| 1689 |
---------------------------- |
| 1690 |
|
| 1691 |
A quick reference of some settings to set on the LodePNGState |
| 1692 |
|
| 1693 |
For decoding: |
| 1694 |
|
| 1695 |
state.decoder.zlibsettings.ignore_adler32: ignore ADLER32 checksums |
| 1696 |
state.decoder.zlibsettings.custom_...: use custom inflate function |
| 1697 |
state.decoder.ignore_crc: ignore CRC checksums |
| 1698 |
state.decoder.ignore_critical: ignore unknown critical chunks |
| 1699 |
state.decoder.ignore_end: ignore missing IEND chunk. May fail if this corruption causes other errors |
| 1700 |
state.decoder.color_convert: convert internal PNG color to chosen one |
| 1701 |
state.decoder.read_text_chunks: whether to read in text metadata chunks |
| 1702 |
state.decoder.remember_unknown_chunks: whether to read in unknown chunks |
| 1703 |
state.info_raw.colortype: desired color type for decoded image |
| 1704 |
state.info_raw.bitdepth: desired bit depth for decoded image |
| 1705 |
state.info_raw....: more color settings, see struct LodePNGColorMode |
| 1706 |
state.info_png....: no settings for decoder but ouput, see struct LodePNGInfo |
| 1707 |
|
| 1708 |
For encoding: |
| 1709 |
|
| 1710 |
state.encoder.zlibsettings.btype: disable compression by setting it to 0 |
| 1711 |
state.encoder.zlibsettings.use_lz77: use LZ77 in compression |
| 1712 |
state.encoder.zlibsettings.windowsize: tweak LZ77 windowsize |
| 1713 |
state.encoder.zlibsettings.minmatch: tweak min LZ77 length to match |
| 1714 |
state.encoder.zlibsettings.nicematch: tweak LZ77 match where to stop searching |
| 1715 |
state.encoder.zlibsettings.lazymatching: try one more LZ77 matching |
| 1716 |
state.encoder.zlibsettings.custom_...: use custom deflate function |
| 1717 |
state.encoder.auto_convert: choose optimal PNG color type, if 0 uses info_png |
| 1718 |
state.encoder.filter_palette_zero: PNG filter strategy for palette |
| 1719 |
state.encoder.filter_strategy: PNG filter strategy to encode with |
| 1720 |
state.encoder.force_palette: add palette even if not encoding to one |
| 1721 |
state.encoder.add_id: add LodePNG identifier and version as a text chunk |
| 1722 |
state.encoder.text_compression: use compressed text chunks for metadata |
| 1723 |
state.info_raw.colortype: color type of raw input image you provide |
| 1724 |
state.info_raw.bitdepth: bit depth of raw input image you provide |
| 1725 |
state.info_raw: more color settings, see struct LodePNGColorMode |
| 1726 |
state.info_png.color.colortype: desired color type if auto_convert is false |
| 1727 |
state.info_png.color.bitdepth: desired bit depth if auto_convert is false |
| 1728 |
state.info_png.color....: more color settings, see struct LodePNGColorMode |
| 1729 |
state.info_png....: more PNG related settings, see struct LodePNGInfo |
| 1730 |
|
| 1731 |
|
| 1732 |
12. changes |
| 1733 |
----------- |
| 1734 |
|
| 1735 |
The version number of LodePNG is the date of the change given in the format |
| 1736 |
yyyymmdd. |
| 1737 |
|
| 1738 |
Some changes aren't backwards compatible. Those are indicated with a (!) |
| 1739 |
symbol. |
| 1740 |
|
| 1741 |
*) 19 aug 2018 (!): fixed color mode bKGD is encoded with and made it use palette |
| 1742 |
index in case of palette. |
| 1743 |
*) 10 aug 2018 (!): added support for gAMA, cHRM, sRGB and iCCP chunks. This |
| 1744 |
change is backwards compatible unless you relied on unknown_chunks for those. |
| 1745 |
*) 11 jun 2018: less restrictive check for pixel size integer overflow |
| 1746 |
*) 14 jan 2018: allow optionally ignoring a few more recoverable errors |
| 1747 |
*) 17 sep 2017: fix memory leak for some encoder input error cases |
| 1748 |
*) 27 nov 2016: grey+alpha auto color model detection bugfix |
| 1749 |
*) 18 apr 2016: Changed qsort to custom stable sort (for platforms w/o qsort). |
| 1750 |
*) 09 apr 2016: Fixed colorkey usage detection, and better file loading (within |
| 1751 |
the limits of pure C90). |
| 1752 |
*) 08 dec 2015: Made load_file function return error if file can't be opened. |
| 1753 |
*) 24 okt 2015: Bugfix with decoding to palette output. |
| 1754 |
*) 18 apr 2015: Boundary PM instead of just package-merge for faster encoding. |
| 1755 |
*) 23 aug 2014: Reduced needless memory usage of decoder. |
| 1756 |
*) 28 jun 2014: Removed fix_png setting, always support palette OOB for |
| 1757 |
simplicity. Made ColorProfile public. |
| 1758 |
*) 09 jun 2014: Faster encoder by fixing hash bug and more zeros optimization. |
| 1759 |
*) 22 dec 2013: Power of two windowsize required for optimization. |
| 1760 |
*) 15 apr 2013: Fixed bug with LAC_ALPHA and color key. |
| 1761 |
*) 25 mar 2013: Added an optional feature to ignore some PNG errors (fix_png). |
| 1762 |
*) 11 mar 2013 (!): Bugfix with custom free. Changed from "my" to "lodepng_" |
| 1763 |
prefix for the custom allocators and made it possible with a new #define to |
| 1764 |
use custom ones in your project without needing to change lodepng's code. |
| 1765 |
*) 28 jan 2013: Bugfix with color key. |
| 1766 |
*) 27 okt 2012: Tweaks in text chunk keyword length error handling. |
| 1767 |
*) 8 okt 2012 (!): Added new filter strategy (entropy) and new auto color mode. |
| 1768 |
(no palette). Better deflate tree encoding. New compression tweak settings. |
| 1769 |
Faster color conversions while decoding. Some internal cleanups. |
| 1770 |
*) 23 sep 2012: Reduced warnings in Visual Studio a little bit. |
| 1771 |
*) 1 sep 2012 (!): Removed #define's for giving custom (de)compression functions |
| 1772 |
and made it work with function pointers instead. |
| 1773 |
*) 23 jun 2012: Added more filter strategies. Made it easier to use custom alloc |
| 1774 |
and free functions and toggle #defines from compiler flags. Small fixes. |
| 1775 |
*) 6 may 2012 (!): Made plugging in custom zlib/deflate functions more flexible. |
| 1776 |
*) 22 apr 2012 (!): Made interface more consistent, renaming a lot. Removed |
| 1777 |
redundant C++ codec classes. Reduced amount of structs. Everything changed, |
| 1778 |
but it is cleaner now imho and functionality remains the same. Also fixed |
| 1779 |
several bugs and shrunk the implementation code. Made new samples. |
| 1780 |
*) 6 nov 2011 (!): By default, the encoder now automatically chooses the best |
| 1781 |
PNG color model and bit depth, based on the amount and type of colors of the |
| 1782 |
raw image. For this, autoLeaveOutAlphaChannel replaced by auto_choose_color. |
| 1783 |
*) 9 okt 2011: simpler hash chain implementation for the encoder. |
| 1784 |
*) 8 sep 2011: lz77 encoder lazy matching instead of greedy matching. |
| 1785 |
*) 23 aug 2011: tweaked the zlib compression parameters after benchmarking. |
| 1786 |
A bug with the PNG filtertype heuristic was fixed, so that it chooses much |
| 1787 |
better ones (it's quite significant). A setting to do an experimental, slow, |
| 1788 |
brute force search for PNG filter types is added. |
| 1789 |
*) 17 aug 2011 (!): changed some C zlib related function names. |
| 1790 |
*) 16 aug 2011: made the code less wide (max 120 characters per line). |
| 1791 |
*) 17 apr 2011: code cleanup. Bugfixes. Convert low to 16-bit per sample colors. |
| 1792 |
*) 21 feb 2011: fixed compiling for C90. Fixed compiling with sections disabled. |
| 1793 |
*) 11 dec 2010: encoding is made faster, based on suggestion by Peter Eastman |
| 1794 |
to optimize long sequences of zeros. |
| 1795 |
*) 13 nov 2010: added LodePNG_InfoColor_hasPaletteAlpha and |
| 1796 |
LodePNG_InfoColor_canHaveAlpha functions for convenience. |
| 1797 |
*) 7 nov 2010: added LodePNG_error_text function to get error code description. |
| 1798 |
*) 30 okt 2010: made decoding slightly faster |
| 1799 |
*) 26 okt 2010: (!) changed some C function and struct names (more consistent). |
| 1800 |
Reorganized the documentation and the declaration order in the header. |
| 1801 |
*) 08 aug 2010: only changed some comments and external samples. |
| 1802 |
*) 05 jul 2010: fixed bug thanks to warnings in the new gcc version. |
| 1803 |
*) 14 mar 2010: fixed bug where too much memory was allocated for char buffers. |
| 1804 |
*) 02 sep 2008: fixed bug where it could create empty tree that linux apps could |
| 1805 |
read by ignoring the problem but windows apps couldn't. |
| 1806 |
*) 06 jun 2008: added more error checks for out of memory cases. |
| 1807 |
*) 26 apr 2008: added a few more checks here and there to ensure more safety. |
| 1808 |
*) 06 mar 2008: crash with encoding of strings fixed |
| 1809 |
*) 02 feb 2008: support for international text chunks added (iTXt) |
| 1810 |
*) 23 jan 2008: small cleanups, and #defines to divide code in sections |
| 1811 |
*) 20 jan 2008: support for unknown chunks allowing using LodePNG for an editor. |
| 1812 |
*) 18 jan 2008: support for tIME and pHYs chunks added to encoder and decoder. |
| 1813 |
*) 17 jan 2008: ability to encode and decode compressed zTXt chunks added |
| 1814 |
Also various fixes, such as in the deflate and the padding bits code. |
| 1815 |
*) 13 jan 2008: Added ability to encode Adam7-interlaced images. Improved |
| 1816 |
filtering code of encoder. |
| 1817 |
*) 07 jan 2008: (!) changed LodePNG to use ISO C90 instead of C++. A |
| 1818 |
C++ wrapper around this provides an interface almost identical to before. |
| 1819 |
Having LodePNG be pure ISO C90 makes it more portable. The C and C++ code |
| 1820 |
are together in these files but it works both for C and C++ compilers. |
| 1821 |
*) 29 dec 2007: (!) changed most integer types to unsigned int + other tweaks |
| 1822 |
*) 30 aug 2007: bug fixed which makes this Borland C++ compatible |
| 1823 |
*) 09 aug 2007: some VS2005 warnings removed again |
| 1824 |
*) 21 jul 2007: deflate code placed in new namespace separate from zlib code |
| 1825 |
*) 08 jun 2007: fixed bug with 2- and 4-bit color, and small interlaced images |
| 1826 |
*) 04 jun 2007: improved support for Visual Studio 2005: crash with accessing |
| 1827 |
invalid std::vector element [0] fixed, and level 3 and 4 warnings removed |
| 1828 |
*) 02 jun 2007: made the encoder add a tag with version by default |
| 1829 |
*) 27 may 2007: zlib and png code separated (but still in the same file), |
| 1830 |
simple encoder/decoder functions added for more simple usage cases |
| 1831 |
*) 19 may 2007: minor fixes, some code cleaning, new error added (error 69), |
| 1832 |
moved some examples from here to lodepng_examples.cpp |
| 1833 |
*) 12 may 2007: palette decoding bug fixed |
| 1834 |
*) 24 apr 2007: changed the license from BSD to the zlib license |
| 1835 |
*) 11 mar 2007: very simple addition: ability to encode bKGD chunks. |
| 1836 |
*) 04 mar 2007: (!) tEXt chunk related fixes, and support for encoding |
| 1837 |
palettized PNG images. Plus little interface change with palette and texts. |
| 1838 |
*) 03 mar 2007: Made it encode dynamic Huffman shorter with repeat codes. |
| 1839 |
Fixed a bug where the end code of a block had length 0 in the Huffman tree. |
| 1840 |
*) 26 feb 2007: Huffman compression with dynamic trees (BTYPE 2) now implemented |
| 1841 |
and supported by the encoder, resulting in smaller PNGs at the output. |
| 1842 |
*) 27 jan 2007: Made the Adler-32 test faster so that a timewaste is gone. |
| 1843 |
*) 24 jan 2007: gave encoder an error interface. Added color conversion from any |
| 1844 |
greyscale type to 8-bit greyscale with or without alpha. |
| 1845 |
*) 21 jan 2007: (!) Totally changed the interface. It allows more color types |
| 1846 |
to convert to and is more uniform. See the manual for how it works now. |
| 1847 |
*) 07 jan 2007: Some cleanup & fixes, and a few changes over the last days: |
| 1848 |
encode/decode custom tEXt chunks, separate classes for zlib & deflate, and |
| 1849 |
at last made the decoder give errors for incorrect Adler32 or Crc. |
| 1850 |
*) 01 jan 2007: Fixed bug with encoding PNGs with less than 8 bits per channel. |
| 1851 |
*) 29 dec 2006: Added support for encoding images without alpha channel, and |
| 1852 |
cleaned out code as well as making certain parts faster. |
| 1853 |
*) 28 dec 2006: Added "Settings" to the encoder. |
| 1854 |
*) 26 dec 2006: The encoder now does LZ77 encoding and produces much smaller files now. |
| 1855 |
Removed some code duplication in the decoder. Fixed little bug in an example. |
| 1856 |
*) 09 dec 2006: (!) Placed output parameters of public functions as first parameter. |
| 1857 |
Fixed a bug of the decoder with 16-bit per color. |
| 1858 |
*) 15 okt 2006: Changed documentation structure |
| 1859 |
*) 09 okt 2006: Encoder class added. It encodes a valid PNG image from the |
| 1860 |
given image buffer, however for now it's not compressed. |
| 1861 |
*) 08 sep 2006: (!) Changed to interface with a Decoder class |
| 1862 |
*) 30 jul 2006: (!) LodePNG_InfoPng , width and height are now retrieved in different |
| 1863 |
way. Renamed decodePNG to decodePNGGeneric. |
| 1864 |
*) 29 jul 2006: (!) Changed the interface: image info is now returned as a |
| 1865 |
struct of type LodePNG::LodePNG_Info, instead of a vector, which was a bit clumsy. |
| 1866 |
*) 28 jul 2006: Cleaned the code and added new error checks. |
| 1867 |
Corrected terminology "deflate" into "inflate". |
| 1868 |
*) 23 jun 2006: Added SDL example in the documentation in the header, this |
| 1869 |
example allows easy debugging by displaying the PNG and its transparency. |
| 1870 |
*) 22 jun 2006: (!) Changed way to obtain error value. Added |
| 1871 |
loadFile function for convenience. Made decodePNG32 faster. |
| 1872 |
*) 21 jun 2006: (!) Changed type of info vector to unsigned. |
| 1873 |
Changed position of palette in info vector. Fixed an important bug that |
| 1874 |
happened on PNGs with an uncompressed block. |
| 1875 |
*) 16 jun 2006: Internally changed unsigned into unsigned where |
| 1876 |
needed, and performed some optimizations. |
| 1877 |
*) 07 jun 2006: (!) Renamed functions to decodePNG and placed them |
| 1878 |
in LodePNG namespace. Changed the order of the parameters. Rewrote the |
| 1879 |
documentation in the header. Renamed files to lodepng.cpp and lodepng.h |
| 1880 |
*) 22 apr 2006: Optimized and improved some code |
| 1881 |
*) 07 sep 2005: (!) Changed to std::vector interface |
| 1882 |
*) 12 aug 2005: Initial release (C++, decoder only) |
| 1883 |
|
| 1884 |
|
| 1885 |
13. contact information |
| 1886 |
----------------------- |
| 1887 |
|
| 1888 |
Feel free to contact me with suggestions, problems, comments, ... concerning |
| 1889 |
LodePNG. If you encounter a PNG image that doesn't work properly with this |
| 1890 |
decoder, feel free to send it and I'll use it to find and fix the problem. |
| 1891 |
|
| 1892 |
My email address is (puzzle the account and domain together with an @ symbol): |
| 1893 |
Domain: gmail dot com. |
| 1894 |
Account: lode dot vandevenne. |
| 1895 |
|
| 1896 |
|
| 1897 |
Copyright (c) 2005-2018 Lode Vandevenne |
| 1898 |
*/ |