[devel] Updated manual synopses, fixed several typos,
put paramter descriptions in proper order, applied libpng indentation
style in code snippets.
diff --git a/libpng-manual.txt b/libpng-manual.txt
index 2403083..62809ca 100644
--- a/libpng-manual.txt
+++ b/libpng-manual.txt
@@ -1,6 +1,6 @@
libpng-manual.txt - A description on how to use and modify libpng
- libpng version 1.5.1rc01 - January 21, 2011
+ libpng version 1.5.1beta07 - January 22, 2011
Updated and distributed by Glenn Randers-Pehrson
<glennrp at users.sourceforge.net>
Copyright (c) 1998-2011 Glenn Randers-Pehrson
@@ -11,7 +11,7 @@
Based on:
- libpng versions 0.97, January 1998, through 1.5.1rc01 - January 21, 2011
+ libpng versions 0.97, January 1998, through 1.5.1beta07 - January 22, 2011
Updated and distributed by Glenn Randers-Pehrson
Copyright (c) 1998-2011 Glenn Randers-Pehrson
@@ -309,13 +309,15 @@
FILE *fp = fopen(file_name, "rb");
if (!fp)
{
- return (ERROR);
+ return (ERROR);
}
+
fread(header, 1, number, fp);
is_png = !png_sig_cmp(header, 0, number);
+
if (!is_png)
{
- return (NOT_PNG);
+ return (NOT_PNG);
}
@@ -331,29 +333,32 @@
create the structure, so your application should check for that.
png_structp png_ptr = png_create_read_struct
- (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
+ (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
user_error_fn, user_warning_fn);
+
if (!png_ptr)
- return (ERROR);
+ return (ERROR);
png_infop info_ptr = png_create_info_struct(png_ptr);
+
if (!info_ptr)
{
- png_destroy_read_struct(&png_ptr,
+ png_destroy_read_struct(&png_ptr,
(png_infopp)NULL, (png_infopp)NULL);
- return (ERROR);
+ return (ERROR);
}
png_infop end_info = png_create_info_struct(png_ptr);
+
if (!end_info)
{
- png_destroy_read_struct(&png_ptr, &info_ptr,
+ png_destroy_read_struct(&png_ptr, &info_ptr,
(png_infopp)NULL);
- return (ERROR);
+ return (ERROR);
}
If you want to use your own memory allocation routines,
-define PNG_USER_MEM_SUPPORTED and use
+use a libpng that was built with PNG_USER_MEM_SUPPORTED defined, and use
png_create_read_struct_2() instead of png_create_read_struct():
png_structp png_ptr = png_create_read_struct_2
@@ -381,10 +386,10 @@
if (setjmp(png_jmpbuf(png_ptr)))
{
- png_destroy_read_struct(&png_ptr, &info_ptr,
+ png_destroy_read_struct(&png_ptr, &info_ptr,
&end_info);
- fclose(fp);
- return (ERROR);
+ fclose(fp);
+ return (ERROR);
}
If you would rather avoid the complexity of setjmp/longjmp issues,
@@ -523,14 +528,17 @@
1: ignore; do not keep
2: keep only if safe-to-copy
3: keep even if unsafe-to-copy
+
You can use these definitions:
PNG_HANDLE_CHUNK_AS_DEFAULT 0
PNG_HANDLE_CHUNK_NEVER 1
PNG_HANDLE_CHUNK_IF_SAFE 2
PNG_HANDLE_CHUNK_ALWAYS 3
+
chunk_list - list of chunks affected (a byte string,
five bytes per chunk, NULL or '\0' if
num_chunks is 0)
+
num_chunks - number of chunks affected; if 0, all
unknown chunks are affected. If nonzero,
only the chunks in the list are affected
@@ -566,8 +574,10 @@
#if defined(PNG_UNKNOWN_CHUNKS_SUPPORTED)
/* ignore all unknown chunks: */
png_set_keep_unknown_chunks(read_ptr, 1, NULL, 0);
+
/* except for vpAg: */
png_set_keep_unknown_chunks(read_ptr, 2, vpAg, 1);
+
/* also ignore unused known chunks: */
png_set_keep_unknown_chunks(read_ptr, 1, unused_chunks,
(int)sizeof(unused_chunks)/5);
@@ -680,17 +690,22 @@
if (height > PNG_UINT_32_MAX/png_sizeof(png_byte))
png_error (png_ptr,
- "Image is too tall to process in memory");
+ "Image is too tall to process in memory");
+
if (width > PNG_UINT_32_MAX/pixel_size)
png_error (png_ptr,
- "Image is too wide to process in memory");
+ "Image is too wide to process in memory");
+
row_pointers = png_malloc(png_ptr,
- height*png_sizeof(png_bytep));
+ height*png_sizeof(png_bytep));
+
for (int i=0; i<height, i++)
row_pointers[i]=NULL; /* security precaution */
+
for (int i=0; i<height, i++)
row_pointers[i]=png_malloc(png_ptr,
- width*pixel_size);
+ width*pixel_size);
+
png_set_rows(png_ptr, info_ptr, &row_pointers);
Alternatively you could allocate your image in one big block and define
@@ -700,7 +715,7 @@
row_pointers (and row_pointers[i], if they were separately allocated).
If you don't allocate row_pointers ahead of time, png_read_png() will
-do it, and it'll be free'ed when you call png_destroy_*().
+do it, and it'll be free'ed by libpng when you call png_destroy_*().
The low-level read interface
@@ -724,13 +739,16 @@
width - holds the width of the image
in pixels (up to 2^31).
+
height - holds the height of the image
in pixels (up to 2^31).
+
bit_depth - holds the bit depth of one of the
image channels. (valid values are
1, 2, 4, 8, 16 and depend also on
the color_type. See also
significant bits (sBIT) below).
+
color_type - describes which color/alpha channels
are present.
PNG_COLOR_TYPE_GRAY
@@ -773,28 +791,38 @@
width = png_get_image_width(png_ptr,
info_ptr);
+
height = png_get_image_height(png_ptr,
info_ptr);
+
bit_depth = png_get_bit_depth(png_ptr,
info_ptr);
+
color_type = png_get_color_type(png_ptr,
info_ptr);
+
interlace_type = png_get_interlace_type(png_ptr,
info_ptr);
+
compression_type = png_get_compression_type(png_ptr,
info_ptr);
+
filter_method = png_get_filter_type(png_ptr,
info_ptr);
channels = png_get_channels(png_ptr, info_ptr);
+
channels - number of channels of info for the
color type (valid values are 1 (GRAY,
PALETTE), 2 (GRAY_ALPHA), 3 (RGB),
4 (RGB_ALPHA or RGB + filler byte))
+
rowbytes = png_get_rowbytes(png_ptr, info_ptr);
+
rowbytes - number of bytes needed to hold a row
signature = png_get_signature(png_ptr, info_ptr);
+
signature - holds the signature read from the
file (if any). The data is kept in
the same offset it would be if the
@@ -814,15 +842,19 @@
png_get_PLTE(png_ptr, info_ptr, &palette,
&num_palette);
+
palette - the palette for the file
(array of png_color)
+
num_palette - number of entries in the palette
png_get_gAMA(png_ptr, info_ptr, &gamma);
+
gamma - the gamma the file is written
at (PNG_INFO_gAMA)
png_get_sRGB(png_ptr, info_ptr, &srgb_intent);
+
srgb_intent - the rendering intent (PNG_INFO_sRGB)
The presence of the sRGB chunk
means that the pixel data is in the
@@ -832,16 +864,21 @@
png_get_iCCP(png_ptr, info_ptr, &name,
&compression_type, &profile, &proflen);
+
name - The profile name.
+
compression_type - The compression type; always
PNG_COMPRESSION_TYPE_BASE for PNG 1.0.
You may give NULL to this argument to
ignore it.
+
profile - International Color Consortium color
profile data. May contain NULs.
+
proflen - length of profile data in bytes.
png_get_sBIT(png_ptr, info_ptr, &sig_bit);
+
sig_bit - the number of significant bits for
(PNG_INFO_sBIT) each of the gray,
red, green, and blue channels,
@@ -850,50 +887,66 @@
png_get_tRNS(png_ptr, info_ptr, &trans_alpha,
&num_trans, &trans_color);
+
trans_alpha - array of alpha (transparency)
entries for palette (PNG_INFO_tRNS)
+
num_trans - number of transparent entries
(PNG_INFO_tRNS)
+
trans_color - graylevel or color sample values of
the single transparent color for
non-paletted images (PNG_INFO_tRNS)
png_get_hIST(png_ptr, info_ptr, &hist);
(PNG_INFO_hIST)
+
hist - histogram of palette (array of
png_uint_16)
png_get_tIME(png_ptr, info_ptr, &mod_time);
+
mod_time - time image was last modified
(PNG_VALID_tIME)
png_get_bKGD(png_ptr, info_ptr, &background);
+
background - background color (PNG_VALID_bKGD)
valid 16-bit red, green and blue
values, regardless of color_type
num_comments = png_get_text(png_ptr, info_ptr,
&text_ptr, &num_text);
+
num_comments - number of comments
+
text_ptr - array of png_text holding image
comments
+
text_ptr[i].compression - type of compression used
on "text" PNG_TEXT_COMPRESSION_NONE
PNG_TEXT_COMPRESSION_zTXt
PNG_ITXT_COMPRESSION_NONE
PNG_ITXT_COMPRESSION_zTXt
+
text_ptr[i].key - keyword for comment. Must contain
1-79 characters.
+
text_ptr[i].text - text comments for current
keyword. Can be empty.
+
text_ptr[i].text_length - length of text string,
after decompression, 0 for iTXt
+
text_ptr[i].itxt_length - length of itxt string,
after decompression, 0 for tEXt/zTXt
+
text_ptr[i].lang - language of comment (empty
string for unknown).
+
text_ptr[i].lang_key - keyword in UTF-8
(empty string for unknown).
+
Note that the itxt_length, lang, and lang_key
members of the text_ptr structure only exist
when the library is built with iTXt chunk support.
@@ -901,6 +954,7 @@
num_text - number of comments (same as
num_comments; you can put NULL here
to avoid the duplication)
+
Note while png_set_text() will accept text, language,
and translated keywords that can be NULL pointers, the
structure returned by png_get_text will always contain
@@ -909,49 +963,68 @@
num_spalettes = png_get_sPLT(png_ptr, info_ptr,
&palette_ptr);
+
+ num_spalettes - number of sPLT chunks read.
+
palette_ptr - array of palette structures holding
contents of one or more sPLT chunks
read.
- num_spalettes - number of sPLT chunks read.
png_get_oFFs(png_ptr, info_ptr, &offset_x, &offset_y,
&unit_type);
+
offset_x - positive offset from the left edge
of the screen
+
offset_y - positive offset from the top edge
of the screen
+
unit_type - PNG_OFFSET_PIXEL, PNG_OFFSET_MICROMETER
png_get_pHYs(png_ptr, info_ptr, &res_x, &res_y,
&unit_type);
+
res_x - pixels/unit physical resolution in
x direction
+
res_y - pixels/unit physical resolution in
x direction
+
unit_type - PNG_RESOLUTION_UNKNOWN,
PNG_RESOLUTION_METER
png_get_sCAL(png_ptr, info_ptr, &unit, &width,
&height)
+
unit - physical scale units (an integer)
+
width - width of a pixel in physical scale units
+
height - height of a pixel in physical scale units
(width and height are doubles)
png_get_sCAL_s(png_ptr, info_ptr, &unit, &width,
&height)
+
unit - physical scale units (an integer)
+
width - width of a pixel in physical scale units
+
height - height of a pixel in physical scale units
(width and height are strings like "2.54")
num_unknown_chunks = png_get_unknown_chunks(png_ptr,
info_ptr, &unknowns)
+
unknowns - array of png_unknown_chunk
structures holding unknown chunks
+
unknowns[i].name - name of unknown chunk
+
unknowns[i].data - data of unknown chunk
+
unknowns[i].size - size of unknown chunk's data
+
unknowns[i].location - position of chunk in file
The value of "i" corresponds to the order in which the
@@ -963,34 +1036,55 @@
res_x = png_get_x_pixels_per_meter(png_ptr,
info_ptr)
+
res_y = png_get_y_pixels_per_meter(png_ptr,
info_ptr)
+
res_x_and_y = png_get_pixels_per_meter(png_ptr,
info_ptr)
+
res_x = png_get_x_pixels_per_inch(png_ptr,
info_ptr)
+
res_y = png_get_y_pixels_per_inch(png_ptr,
info_ptr)
+
res_x_and_y = png_get_pixels_per_inch(png_ptr,
info_ptr)
+
aspect_ratio = png_get_pixel_aspect_ratio(png_ptr,
info_ptr)
- (Each of these returns 0 [signifying "unknown"] if
+ Each of these returns 0 [signifying "unknown"] if
the data is not present or if res_x is 0;
- res_x_and_y is 0 if res_x != res_y)
+ res_x_and_y is 0 if res_x != res_y
+
+ Note that because of the way the resolutions are
+ stored internally, the inch conversions won't
+ come out to exactly even number. For example,
+ 72 dpi is stored as 0.28346 pixels/meter, and
+ when this is retrieved it is 71.9988 dpi, so
+ be sure to round the returned value appropriately
+ if you want to display a reasonable-looking result.
The data from the oFFs chunk can be retrieved in several convenient
forms:
x_offset = png_get_x_offset_microns(png_ptr, info_ptr);
+
y_offset = png_get_y_offset_microns(png_ptr, info_ptr);
+
x_offset = png_get_x_offset_inches(png_ptr, info_ptr);
+
y_offset = png_get_y_offset_inches(png_ptr, info_ptr);
- (Each of these returns 0 [signifying "unknown" if both
+ Each of these returns 0 [signifying "unknown" if both
x and y are 0] if the data is not present or if the
- chunk is present but the unit is the pixel)
+ chunk is present but the unit is the pixel. The
+ remark about inexact inch conversions applies here
+ as well, because a value in inches can't always be
+ converted to microns and back without some loss
+ of precision.
For more information, see the png_info definition in png.h and the
PNG specification for chunk contents. Be careful with trusting
@@ -1077,7 +1171,7 @@
As of libpng version 1.2.9, png_set_expand_gray_1_2_4_to_8() was
added. It expands the sample depth without changing tRNS to alpha.
-As of libpng version 1.5.1rc01, not all possible expansions are supported.
+As of libpng version 1.5.1beta07, not all possible expansions are supported.
In the following table, the 01 means grayscale with depth<8, 31 means
indexed with depth<8, other numerals represent the color type, "T" means
@@ -1118,7 +1212,7 @@
8 bits per channel, this will strip the pixels down to 8 bit.
if (bit_depth == 16)
- png_set_strip_16(png_ptr);
+ png_set_strip_16(png_ptr);
If, for some reason, you don't need the alpha channel on an image,
and you want to remove it rather than combining it with the background
@@ -1126,7 +1220,7 @@
it with the background, so that's what you should probably do):
if (color_type & PNG_COLOR_MASK_ALPHA)
- png_set_strip_alpha(png_ptr);
+ png_set_strip_alpha(png_ptr);
In PNG files, the alpha channel in an image
is the level of opacity. If you need the alpha channel in an image to
@@ -1143,7 +1237,7 @@
values of the pixels:
if (bit_depth < 8)
- png_set_packing(png_ptr);
+ png_set_packing(png_ptr);
PNG files have possible bit depths of 1, 2, 4, 8, and 16. All pixels
stored in a PNG image have been "scaled" or "shifted" up to the next
@@ -1155,20 +1249,20 @@
png_color_8p sig_bit;
if (png_get_sBIT(png_ptr, info_ptr, &sig_bit))
- png_set_shift(png_ptr, sig_bit);
+ png_set_shift(png_ptr, sig_bit);
PNG files store 3-color pixels in red, green, blue order. This code
changes the storage of the pixels to blue, green, red:
if (color_type == PNG_COLOR_TYPE_RGB ||
color_type == PNG_COLOR_TYPE_RGB_ALPHA)
- png_set_bgr(png_ptr);
+ png_set_bgr(png_ptr);
PNG files store RGB pixels packed into 3 or 6 bytes. This code expands them
into 4 or 8 bytes for windowing systems that need them in this format:
if (color_type == PNG_COLOR_TYPE_RGB)
- png_set_filler(png_ptr, filler, PNG_FILLER_BEFORE);
+ png_set_filler(png_ptr, filler, PNG_FILLER_BEFORE);
where "filler" is the 8 or 16-bit number to fill with, and the location is
either PNG_FILLER_BEFORE or PNG_FILLER_AFTER, depending upon whether
@@ -1181,8 +1275,8 @@
to do that, you can add a true alpha channel with
if (color_type == PNG_COLOR_TYPE_RGB ||
- color_type == PNG_COLOR_TYPE_GRAY)
- png_set_add_alpha(png_ptr, filler, PNG_FILLER_AFTER);
+ color_type == PNG_COLOR_TYPE_GRAY)
+ png_set_add_alpha(png_ptr, filler, PNG_FILLER_AFTER);
where "filler" contains the alpha value to assign to each pixel.
This function was added in libpng-1.2.7.
@@ -1191,33 +1285,36 @@
data as ARGB instead of the normal PNG format RGBA:
if (color_type == PNG_COLOR_TYPE_RGB_ALPHA)
- png_set_swap_alpha(png_ptr);
+ png_set_swap_alpha(png_ptr);
For some uses, you may want a grayscale image to be represented as
RGB. This code will do that conversion:
if (color_type == PNG_COLOR_TYPE_GRAY ||
color_type == PNG_COLOR_TYPE_GRAY_ALPHA)
- png_set_gray_to_rgb(png_ptr);
+ png_set_gray_to_rgb(png_ptr);
Conversely, you can convert an RGB or RGBA image to grayscale or grayscale
with alpha.
if (color_type == PNG_COLOR_TYPE_RGB ||
color_type == PNG_COLOR_TYPE_RGB_ALPHA)
- png_set_rgb_to_gray_fixed(png_ptr, error_action,
- int red_weight, int green_weight);
+ png_set_rgb_to_gray_fixed(png_ptr, error_action,
+ int red_weight, int green_weight);
error_action = 1: silently do the conversion
+
error_action = 2: issue a warning if the original
image has any pixel where
red != green or red != blue
+
error_action = 3: issue an error and abort the
conversion if the original
image has any pixel where
red != green or red != blue
red_weight: weight of red component times 100000
+
green_weight: weight of green component times 100000
If either weight is negative, default
weights (21268, 71514) are used.
@@ -1268,11 +1365,11 @@
png_color_16p image_background;
if (png_get_bKGD(png_ptr, info_ptr, &image_background))
- png_set_background(png_ptr, image_background,
- PNG_BACKGROUND_GAMMA_FILE, 1, 1.0);
+ png_set_background(png_ptr, image_background,
+ PNG_BACKGROUND_GAMMA_FILE, 1, 1.0);
else
- png_set_background(png_ptr, &my_background,
- PNG_BACKGROUND_GAMMA_SCREEN, 0, 1.0);
+ png_set_background(png_ptr, &my_background,
+ PNG_BACKGROUND_GAMMA_SCREEN, 0, 1.0);
The png_set_background() function tells libpng to composite images
with alpha or simple transparency against the supplied background
@@ -1305,6 +1402,7 @@
{
screen_gamma = user_defined_screen_gamma;
}
+
/* One way that applications can share the same
screen gamma value */
else if ((gamma_str = getenv("SCREEN_GAMMA"))
@@ -1312,13 +1410,16 @@
{
screen_gamma = (double)atof(gamma_str);
}
+
/* If we don't have another value */
else
{
screen_gamma = 2.2; /* A good guess for a
PC monitor in a bright office or a dim room */
+
screen_gamma = 2.0; /* A good guess for a
PC monitor in a dark room */
+
screen_gamma = 1.7 or 1.0; /* A good
guess for Mac systems */
}
@@ -1335,6 +1436,7 @@
if (png_get_gAMA(png_ptr, info_ptr, &gamma))
png_set_gamma(png_ptr, screen_gamma, gamma);
+
else
png_set_gamma(png_ptr, screen_gamma, 0.45455);
@@ -1342,7 +1444,7 @@
file has more entries then will fit on your screen, png_set_quantize()
will do that. Note that this is a simple match quantization that merely
finds the closest color available. This should work fairly well with
-optimized palettes, and fairly badly with linear color cubes. If you
+optimized palettes, but fairly badly with linear color cubes. If you
pass a palette that is larger then maximum_colors, the file will
reduce the number of colors in the palette so it will fit into
maximum_colors. If there is a histogram, it will use it to make
@@ -1352,15 +1454,16 @@
if (color_type & PNG_COLOR_MASK_COLOR)
{
if (png_get_valid(png_ptr, info_ptr,
- PNG_INFO_PLTE))
+ PNG_INFO_PLTE))
{
png_uint_16p histogram = NULL;
png_get_hIST(png_ptr, info_ptr,
- &histogram);
+ &histogram);
png_set_quantize(png_ptr, palette, num_palette,
max_screen_colors, histogram, 1);
}
+
else
{
png_color std_color_cube[MAX_SCREEN_COLORS] =
@@ -1382,7 +1485,7 @@
This function can also be used to invert grayscale and gray-alpha images:
if (color_type == PNG_COLOR_TYPE_GRAY ||
- color_type == PNG_COLOR_TYPE_GRAY_ALPHA)
+ color_type == PNG_COLOR_TYPE_GRAY_ALPHA)
png_set_invert_mono(png_ptr);
PNG files store 16 bit pixels in network byte order (big-endian,
@@ -1391,7 +1494,7 @@
way PCs store them):
if (bit_depth == 16)
- png_set_swap(png_ptr);
+ png_set_swap(png_ptr);
If you are using packed-pixel images (1, 2, or 4 bits/pixel), and you
need to change the order the pixels are packed into bytes, you can use:
@@ -1404,12 +1507,12 @@
with
png_set_read_user_transform_fn(png_ptr,
- read_transform_fn);
+ read_transform_fn);
You must supply the function
void read_transform_fn(png_ptr ptr, row_info_ptr
- row_info, png_bytep data)
+ row_info, png_bytep data)
See pngtest.c for a working example. Your function will be called
after all of the other transformations have been processed.
@@ -1420,7 +1523,7 @@
function
png_set_user_transform_info(png_ptr, user_ptr,
- user_depth, user_channels);
+ user_depth, user_channels);
The user's application, not libpng, is responsible for allocating and
freeing any memory required for the user structure.
@@ -1429,7 +1532,7 @@
png_get_user_transform_ptr(). For example:
voidp read_user_transform_ptr =
- png_get_user_transform_ptr(png_ptr);
+ png_get_user_transform_ptr(png_ptr);
The last thing to handle is interlacing; this is covered in detail below,
but you must call the function here if you want libpng to handle expansion
@@ -1454,13 +1557,13 @@
array of pointers to each row, as it will be needed for some
of the functions below.
-Remember: Before you call png_read_update_info the png_get_
+Remember: Before you call png_read_update_info(), the png_get_
functions return the values corresponding to the original PNG image.
After you call png_read_update_info the values refer to the image
that libpng will output. Consequently you must call all the png_set_
-functions before you call png_read_update_info. This is particularly
-important for png_set_interlace_handling - if you are going to call
-png_read_update_info you must call png_set_interlace_handling before
+functions before you call png_read_update_info(). This is particularly
+important for png_set_interlace_handling() - if you are going to call
+png_read_update_info() you must call png_set_interlace_handling() before
it unless you want to receive interlaced output.
Reading image data
@@ -1490,7 +1593,7 @@
interlace_type == PNG_INTERLACE_NONE), this is simple:
png_read_rows(png_ptr, row_pointers, NULL,
- number_of_rows);
+ number_of_rows);
where row_pointers is the same as in the png_read_image() call.
@@ -1524,7 +1627,7 @@
calling png_start_read_image() or png_read_update_info():
if (interlace_type == PNG_INTERLACE_ADAM7)
- number_of_passes
+ number_of_passes
= png_set_interlace_handling(png_ptr);
This will return the number of passes needed. Currently, this is seven,
@@ -1550,14 +1653,14 @@
pass, and assumes the data from previous passes is still valid.
png_read_rows(png_ptr, row_pointers, NULL,
- number_of_rows);
+ number_of_rows);
If you only want the first effect (the rectangles), do the same as
before except pass the row buffer in the third parameter, and leave
the second parameter NULL.
png_read_rows(png_ptr, NULL, row_pointers,
- number_of_rows);
+ number_of_rows);
If you don't want libpng to handle the interlacing details, just call
png_read_rows() PNG_INTERLACE_ADAM7_PASSES times to read in all the images.
@@ -1610,12 +1713,14 @@
while (output_x < output_image_width)
{
- image[output_y][output_x] = subimage[pass][input_y][input_x++];
+ image[output_y][output_x] =
+ subimage[pass][input_y][input_x++];
+
output_x += xStep;
}
++input_y;
- ouput_y += yStep;
+ output_y += yStep;
}
Notice that the steps between successive output rows and columns are
@@ -1667,6 +1772,7 @@
point to libpng-allocated storage with the following function:
png_free_data(png_ptr, info_ptr, mask, seq)
+
mask - identifies data to be freed, a mask
containing the bitwise OR of one or
more of
@@ -1676,6 +1782,7 @@
PNG_FREE_SCAL, PNG_FREE_SPLT,
PNG_FREE_TEXT, PNG_FREE_UNKN,
or simply PNG_FREE_ALL
+
seq - sequence number of item to be freed
(-1 for all items)
@@ -1693,13 +1800,15 @@
or png_zalloc() and passed in via a png_set_*() function, with
png_data_freer(png_ptr, info_ptr, freer, mask)
- mask - which data elements are affected
- same choices as in png_free_data()
+
freer - one of
PNG_DESTROY_WILL_FREE_DATA
PNG_SET_WILL_FREE_DATA
PNG_USER_WILL_FREE_DATA
+ mask - which data elements are affected
+ same choices as in png_free_data()
+
This function only affects data that has already been allocated.
You can call this function after reading the PNG data but before calling
any png_set_*() functions, to control whether the user or the png_set_*()
@@ -1728,6 +1837,7 @@
your application instead of by libpng, you can use
png_set_invalid(png_ptr, info_ptr, mask);
+
mask - identifies the chunks to be made invalid,
containing the bitwise OR of one or
more of
@@ -1767,21 +1877,24 @@
png_ptr = png_create_read_struct
(PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
user_error_fn, user_warning_fn);
+
if (!png_ptr)
return (ERROR);
+
info_ptr = png_create_info_struct(png_ptr);
+
if (!info_ptr)
{
- png_destroy_read_struct(&png_ptr, (png_infopp)NULL,
- (png_infopp)NULL);
- return (ERROR);
+ png_destroy_read_struct(&png_ptr,
+ (png_infopp)NULL, (png_infopp)NULL);
+ return (ERROR);
}
if (setjmp(png_jmpbuf(png_ptr)))
{
- png_destroy_read_struct(&png_ptr, &info_ptr,
- (png_infopp)NULL);
- return (ERROR);
+ png_destroy_read_struct(&png_ptr, &info_ptr,
+ (png_infopp)NULL);
+ return (ERROR);
}
/* This one's new. You can provide functions
@@ -1813,9 +1926,9 @@
{
if (setjmp(png_jmpbuf(png_ptr)))
{
- png_destroy_read_struct(&png_ptr, &info_ptr,
+ png_destroy_read_struct(&png_ptr, &info_ptr,
(png_infopp)NULL);
- return (ERROR);
+ return (ERROR);
}
/* This one's new also. Simply give it a chunk
@@ -1938,10 +2051,9 @@
custom writing functions. See the discussion under Customizing libpng.
FILE *fp = fopen(file_name, "wb");
+
if (!fp)
- {
return (ERROR);
- }
Next, png_struct and png_info need to be allocated and initialized.
As these can be both relatively large, you may not want to store these
@@ -1954,6 +2066,7 @@
png_structp png_ptr = png_create_write_struct
(PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
user_error_fn, user_warning_fn);
+
if (!png_ptr)
return (ERROR);
@@ -1961,7 +2074,7 @@
if (!info_ptr)
{
png_destroy_write_struct(&png_ptr,
- (png_infopp)NULL);
+ (png_infopp)NULL);
return (ERROR);
}
@@ -1987,7 +2100,7 @@
if (setjmp(png_jmpbuf(png_ptr)))
{
- png_destroy_write_struct(&png_ptr, &info_ptr);
+ png_destroy_write_struct(&png_ptr, &info_ptr);
fclose(fp);
return (ERROR);
}
@@ -2057,7 +2170,8 @@
/* turn on or off filtering, and/or choose
specific filters. You can use either a single
PNG_FILTER_VALUE_NAME or the bitwise OR of one
- or more PNG_FILTER_NAME masks. */
+ or more PNG_FILTER_NAME masks.
+ */
png_set_filter(png_ptr, 0,
PNG_FILTER_NONE | PNG_FILTER_VALUE_NONE |
PNG_FILTER_SUB | PNG_FILTER_VALUE_SUB |
@@ -2113,16 +2227,20 @@
png_set_IHDR(png_ptr, info_ptr, width, height,
bit_depth, color_type, interlace_type,
compression_type, filter_method)
+
width - holds the width of the image
in pixels (up to 2^31).
+
height - holds the height of the image
in pixels (up to 2^31).
+
bit_depth - holds the bit depth of one of the
image channels.
(valid values are 1, 2, 4, 8, 16
and depend also on the
color_type. See also significant
bits (sBIT) below).
+
color_type - describes which color/alpha
channels are present.
PNG_COLOR_TYPE_GRAY
@@ -2142,8 +2260,10 @@
interlace_type - PNG_INTERLACE_NONE or
PNG_INTERLACE_ADAM7
+
compression_type - (must be
PNG_COMPRESSION_TYPE_DEFAULT)
+
filter_method - (must be PNG_FILTER_TYPE_DEFAULT
or, if you are writing a PNG to
be embedded in a MNG datastream,
@@ -2161,15 +2281,18 @@
png_set_PLTE(png_ptr, info_ptr, palette,
num_palette);
+
palette - the palette for the file
(array of png_color)
num_palette - number of entries in the palette
png_set_gAMA(png_ptr, info_ptr, gamma);
+
gamma - the gamma the image was created
at (PNG_INFO_gAMA)
png_set_sRGB(png_ptr, info_ptr, srgb_intent);
+
srgb_intent - the rendering intent
(PNG_INFO_sRGB) The presence of
the sRGB chunk means that the pixel
@@ -2189,6 +2312,7 @@
png_set_sRGB_gAMA_and_cHRM(png_ptr, info_ptr,
srgb_intent);
+
srgb_intent - the rendering intent
(PNG_INFO_sRGB) The presence of the
sRGB chunk means that the pixel
@@ -2200,16 +2324,21 @@
png_set_iCCP(png_ptr, info_ptr, name, compression_type,
profile, proflen);
+
name - The profile name.
+
compression_type - The compression type; always
PNG_COMPRESSION_TYPE_BASE for PNG 1.0.
You may give NULL to this argument to
ignore it.
+
profile - International Color Consortium color
profile data. May contain NULs.
+
proflen - length of profile data in bytes.
png_set_sBIT(png_ptr, info_ptr, sig_bit);
+
sig_bit - the number of significant bits for
(PNG_INFO_sBIT) each of the gray, red,
green, and blue channels, whichever are
@@ -2218,30 +2347,38 @@
png_set_tRNS(png_ptr, info_ptr, trans_alpha,
num_trans, trans_color);
+
trans_alpha - array of alpha (transparency)
entries for palette (PNG_INFO_tRNS)
+
trans_color - graylevel or color sample values
(in order red, green, blue) of the
single transparent color for
non-paletted images (PNG_INFO_tRNS)
+
num_trans - number of transparent entries
(PNG_INFO_tRNS)
png_set_hIST(png_ptr, info_ptr, hist);
(PNG_INFO_hIST)
+
hist - histogram of palette (array of
png_uint_16)
png_set_tIME(png_ptr, info_ptr, mod_time);
+
mod_time - time image was last modified
(PNG_VALID_tIME)
png_set_bKGD(png_ptr, info_ptr, background);
+
background - background color (PNG_VALID_bKGD)
png_set_text(png_ptr, info_ptr, text_ptr, num_text);
+
text_ptr - array of png_text holding image
comments
+
text_ptr[i].compression - type of compression used
on "text" PNG_TEXT_COMPRESSION_NONE
PNG_TEXT_COMPRESSION_zTXt
@@ -2267,6 +2404,7 @@
png_set_sPLT(png_ptr, info_ptr, &palette_ptr,
num_spalettes);
+
palette_ptr - array of png_sPLT_struct structures
to be added to the list of palettes
in the info structure.
@@ -2275,35 +2413,48 @@
png_set_oFFs(png_ptr, info_ptr, offset_x, offset_y,
unit_type);
+
offset_x - positive offset from the left
edge of the screen
+
offset_y - positive offset from the top
edge of the screen
+
unit_type - PNG_OFFSET_PIXEL, PNG_OFFSET_MICROMETER
png_set_pHYs(png_ptr, info_ptr, res_x, res_y,
unit_type);
+
res_x - pixels/unit physical resolution
in x direction
+
res_y - pixels/unit physical resolution
in y direction
+
unit_type - PNG_RESOLUTION_UNKNOWN,
PNG_RESOLUTION_METER
png_set_sCAL(png_ptr, info_ptr, unit, width, height)
+
unit - physical scale units (an integer)
+
width - width of a pixel in physical scale units
+
height - height of a pixel in physical scale units
(width and height are doubles)
png_set_sCAL_s(png_ptr, info_ptr, unit, width, height)
+
unit - physical scale units (an integer)
+
width - width of a pixel in physical scale units
+
height - height of a pixel in physical scale units
(width and height are strings like "2.54")
png_set_unknown_chunks(png_ptr, info_ptr, &unknowns,
num_unknowns)
+
unknowns - array of png_unknown_chunk
structures holding unknown chunks
unknowns[i].name - name of unknown chunk
@@ -2342,21 +2493,30 @@
After the text has been written out to the file, the compression type
is set to PNG_TEXT_COMPRESSION_NONE_WR or PNG_TEXT_COMPRESSION_zTXt_WR,
so that it isn't written out again at the end (in case you are calling
-png_write_end() with the same struct.
+png_write_end() with the same struct).
The keywords that are given in the PNG Specification are:
Title Short (one line) title or
caption for image
+
Author Name of image's creator
+
Description Description of image (possibly long)
+
Copyright Copyright notice
+
Creation Time Time of original image creation
(usually RFC 1123 format, see below)
+
Software Software used to create the image
+
Disclaimer Legal disclaimer
+
Warning Warning of nature of content
+
Source Device used to create the image
+
Comment Miscellaneous comment; conversion
from other image format
@@ -2526,17 +2686,19 @@
/* Set the true bit depth of the image data */
if (color_type & PNG_COLOR_MASK_COLOR)
{
- sig_bit.red = true_bit_depth;
- sig_bit.green = true_bit_depth;
- sig_bit.blue = true_bit_depth;
+ sig_bit.red = true_bit_depth;
+ sig_bit.green = true_bit_depth;
+ sig_bit.blue = true_bit_depth;
}
+
else
{
- sig_bit.gray = true_bit_depth;
+ sig_bit.gray = true_bit_depth;
}
+
if (color_type & PNG_COLOR_MASK_ALPHA)
{
- sig_bit.alpha = true_bit_depth;
+ sig_bit.alpha = true_bit_depth;
}
png_set_sBIT(png_ptr, info_ptr, &sig_bit);
@@ -2719,6 +2881,7 @@
point to libpng-allocated storage with the following function:
png_free_data(png_ptr, info_ptr, mask, seq)
+
mask - identifies data to be freed, a mask
containing the bitwise OR of one or
more of
@@ -2728,6 +2891,7 @@
PNG_FREE_SCAL, PNG_FREE_SPLT,
PNG_FREE_TEXT, PNG_FREE_UNKN,
or simply PNG_FREE_ALL
+
seq - sequence number of item to be freed
(-1 for all items)
@@ -2749,19 +2913,22 @@
or png_zalloc() and passed in via a png_set_*() function, with
png_data_freer(png_ptr, info_ptr, freer, mask)
- mask - which data elements are affected
- same choices as in png_free_data()
+
freer - one of
PNG_DESTROY_WILL_FREE_DATA
PNG_SET_WILL_FREE_DATA
PNG_USER_WILL_FREE_DATA
+ mask - which data elements are affected
+ same choices as in png_free_data()
+
For example, to transfer responsibility for some data from a read structure
to a write structure, you could use
png_data_freer(read_ptr, read_info_ptr,
PNG_USER_WILL_FREE_DATA,
PNG_FREE_PLTE|PNG_FREE_tRNS|PNG_FREE_hIST)
+
png_data_freer(write_ptr, write_info_ptr,
PNG_DESTROY_WILL_FREE_DATA,
PNG_FREE_PLTE|PNG_FREE_tRNS|PNG_FREE_hIST)
@@ -2827,6 +2994,7 @@
png_voidp malloc_fn(png_structp png_ptr,
png_alloc_size_t size);
+
void free_fn(png_structp png_ptr, png_voidp ptr);
Your malloc_fn() must return NULL in case of failure. The png_malloc()
@@ -2859,8 +3027,10 @@
void user_read_data(png_structp png_ptr,
png_bytep data, png_size_t length);
+
void user_write_data(png_structp png_ptr,
png_bytep data, png_size_t length);
+
void user_flush_data(png_structp png_ptr);
The user_read_data() function is responsible for detecting and
@@ -2905,6 +3075,7 @@
void user_error_fn(png_structp png_ptr,
png_const_charp error_msg);
+
void user_warning_fn(png_structp png_ptr,
png_const_charp warning_msg);
@@ -3015,8 +3186,10 @@
png_set_compression_strategy(png_ptr,
strategy);
+
png_set_compression_window_bits(png_ptr,
window_bits);
+
png_set_compression_method(png_ptr, method);
png_set_compression_buffer_size(png_ptr, size);
@@ -3106,6 +3279,8 @@
you can turn off individual capabilities with defines that begin with
PNG_NO_.
+In libpng-1.5.0 and later, the #define's are in pnglibconf.h instead.
+
You can also turn all of the transforms and ancillary chunk capabilities
off en masse with compiler directives that define
PNG_NO_READ[or WRITE]_TRANSFORMS, or PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS,
@@ -3158,8 +3333,8 @@
is expanded to
- if(PNG_DEBUG > 2)
- fprintf(PNG_DEBUG_FILE, "foo=%d\n", foo);
+ if (PNG_DEBUG > 2)
+ fprintf(PNG_DEBUG_FILE, "foo=%d\n", foo);
When PNG_DEBUG is defined but is zero, the macros aren't defined, but you
can still use PNG_DEBUG to control your own debugging:
@@ -3180,11 +3355,13 @@
png_permit_mng_features() function:
feature_set = png_permit_mng_features(png_ptr, mask)
+
mask is a png_uint_32 containing the bitwise OR of the
features you want to enable. These include
PNG_FLAG_MNG_EMPTY_PLTE
PNG_FLAG_MNG_FILTER_64
PNG_ALL_MNG_FEATURES
+
feature_set is a png_uint_32 that is the bitwise AND of
your mask with the set of MNG features that is
supported by the version of libpng that you are using.
@@ -3209,7 +3386,7 @@
The old libpng functions png_read_init(), png_write_init(),
png_info_init(), png_read_destroy(), and png_write_destroy() have been
moved to PNG_INTERNAL in version 0.95 to discourage their use. These
-functions will be removed from libpng version 2.0.0.
+functions will be removed from libpng version 1.4.0.
The preferred method of creating and initializing the libpng structures is
via the png_create_read_struct(), png_create_write_struct(), and
@@ -3445,7 +3622,8 @@
was reenabled, but the function was renamed png_set_quantize() to
reflect more accurately what it actually does. At the same time,
the PNG_DITHER_[RED,GREEN_BLUE]_BITS macros were also renamed to
-PNG_QUANTIZE_[RED,GREEN,BLUE]_BITS.
+PNG_QUANTIZE_[RED,GREEN,BLUE]_BITS, and PNG_READ_DITHER_SUPPORTED
+was renamed to PNG_READ_QUANTIZE_SUPPORTED.
We removed the trailing '.' from the warning and error messages.
@@ -3472,7 +3650,7 @@
header file (pngpriv.h) that is not accessible to applications.
In png_get_iCCP, the type of "profile" was changed from png_charpp
-to png_bytepp, and in png_set_iCCP, from png_charp to png_const_bytepp.
+to png_bytepp, and in png_set_iCCP, from png_charp to png_const_bytep.
There are changes of form in png.h, including new and changed macros to
declare
@@ -3587,8 +3765,8 @@
is used and operating system specific directives are defined in
pnglibconf.h
-As part of this the mechanism used to chose procedure call standards on those
-systems that allow a choice has been changed. At present this only
+As part of this the mechanism used to choose procedure call standards on
+those systems that allow a choice has been changed. At present this only
affects certain Microsoft (DOS, Windows) and IBM (OS/2) operating systems
running on Intel processors. As before PNGAPI is defined where required
to control the exported API functions; however, two new macros, PNGCBAPI
@@ -3606,7 +3784,7 @@
therefore set PNG_API_RULE to 2 should also contact the mailing list.
A new test program, pngvalid, is provided in addition to pngtest.
- pngvalid validates the arithmetic accuracy of the gamma correction
+pngvalid validates the arithmetic accuracy of the gamma correction
calculations and includes a number of validations of the file format.
A subset of the full range of tests is run when "make check" is done
(in the 'configure' build.) pngvalid also allows total allocated memory
@@ -3689,8 +3867,8 @@
These mechanisms still work in the configure build and in any makefile
build that builds pnglibconf.h although the feature selection macros
-have changed somewhat as described above. In 1.5.0, however, pngusr.h
-is processed once when the exported header file pnglibconf.h is built.
+have changed somewhat as described above. In 1.5.0, however, pngusr.h is
+processed only once, when the exported header file pnglibconf.h is built.
pngconf.h no longer includes pngusr.h, therefore it is ignored after the
build of pnglibconf.h and it is never included in an application build.
@@ -3745,6 +3923,11 @@
http://libpng.sourceforge.net
+We also accept patches built from the tar or zip distributions, and
+simple verbal discriptions of bug fixes, reported either to the
+SourceForge bug tracker or to the png-mng-implement at lists.sf.net
+mailing list.
+
XIII. Coding style
Our coding style is similar to the "Allman" style, with curly
@@ -3855,13 +4038,13 @@
XIV. Y2K Compliance in libpng
-January 21, 2011
+January 22, 2011
Since the PNG Development group is an ad-hoc body, we can't make
an official declaration.
This is your unofficial assurance that libpng from version 0.71 and
-upward through 1.5.1rc01 are Y2K compliant. It is my belief that earlier
+upward through 1.5.1beta07 are Y2K compliant. It is my belief that earlier
versions were also Y2K compliant.
Libpng only has three year fields. One is a 2-byte unsigned integer that
diff --git a/libpng.3 b/libpng.3
index 77aba88..0cca06a 100644
--- a/libpng.3
+++ b/libpng.3
@@ -1,6 +1,6 @@
-.TH LIBPNG 3 "January 21, 2011"
+.TH LIBPNG 3 "January 22, 2011"
.SH NAME
-libpng \- Portable Network Graphics (PNG) Reference Library 1.5.1rc01
+libpng \- Portable Network Graphics (PNG) Reference Library 1.5.1beta07
.SH SYNOPSIS
\fI\fB
@@ -92,75 +92,75 @@
\fI\fB
-\fBpng_byte png_get_bit_depth (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
+\fBpng_byte png_get_bit_depth (const_png_structp \fP\fIpng_ptr\fP\fB, const_png_infop \fIinfo_ptr\fP\fB);\fP
\fI\fB
-\fBpng_uint_32 png_get_bKGD (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_color_16p \fI*background\fP\fB);\fP
+\fBpng_uint_32 png_get_bKGD (const_png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_color_16p \fI*background\fP\fB);\fP
\fI\fB
-\fBpng_byte png_get_channels (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
+\fBpng_byte png_get_channels (const_png_structp \fP\fIpng_ptr\fP\fB, const_png_infop \fIinfo_ptr\fP\fB);\fP
\fI\fB
-\fBpng_uint_32 png_get_cHRM (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, double \fP\fI*white_x\fP\fB, double \fP\fI*white_y\fP\fB, double \fP\fI*red_x\fP\fB, double \fP\fI*red_y\fP\fB, double \fP\fI*green_x\fP\fB, double \fP\fI*green_y\fP\fB, double \fP\fI*blue_x\fP\fB, double \fI*blue_y\fP\fB);\fP
+\fBpng_uint_32 png_get_cHRM (const_png_structp \fP\fIpng_ptr\fP\fB, const_png_infop \fP\fIinfo_ptr\fP\fB, double \fP\fI*white_x\fP\fB, double \fP\fI*white_y\fP\fB, double \fP\fI*red_x\fP\fB, double \fP\fI*red_y\fP\fB, double \fP\fI*green_x\fP\fB, double \fP\fI*green_y\fP\fB, double \fP\fI*blue_x\fP\fB, double \fI*blue_y\fP\fB);\fP
\fI\fB
-\fBpng_uint_32 png_get_cHRM_fixed (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fI*white_x\fP\fB, png_uint_32 \fP\fI*white_y\fP\fB, png_uint_32 \fP\fI*red_x\fP\fB, png_uint_32 \fP\fI*red_y\fP\fB, png_uint_32 \fP\fI*green_x\fP\fB, png_uint_32 \fP\fI*green_y\fP\fB, png_uint_32 \fP\fI*blue_x\fP\fB, png_uint_32 \fI*blue_y\fP\fB);\fP
+\fBpng_uint_32 png_get_cHRM_fixed (const_png_structp \fP\fIpng_ptr\fP\fB, const_png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fI*white_x\fP\fB, png_uint_32 \fP\fI*white_y\fP\fB, png_uint_32 \fP\fI*red_x\fP\fB, png_uint_32 \fP\fI*red_y\fP\fB, png_uint_32 \fP\fI*green_x\fP\fB, png_uint_32 \fP\fI*green_y\fP\fB, png_uint_32 \fP\fI*blue_x\fP\fB, png_uint_32 \fI*blue_y\fP\fB);\fP
\fI\fB
-\fBpng_uint_32 png_get_chunk_cache_max (png_structp \fIpng_ptr\fP\fB);\fP
+\fBpng_uint_32 png_get_chunk_cache_max (const_png_structp \fIpng_ptr\fP\fB);\fP
\fI\fB
-\fBpng_byte png_get_color_type (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
+\fBpng_byte png_get_color_type (const_png_structp \fP\fIpng_ptr\fP\fB, const_png_infop \fIinfo_ptr\fP\fB);\fP
\fI\fB
-\fBpng_uint_32 png_get_compression_buffer_size (png_structp \fIpng_ptr\fP\fB);\fP
+\fBpng_uint_32 png_get_compression_buffer_size (const_png_structp \fIpng_ptr\fP\fB);\fP
\fI\fB
-\fBpng_byte png_get_compression_type (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
+\fBpng_byte png_get_compression_type (const_png_structp \fP\fIpng_ptr\fP\fB, const_png_infop \fIinfo_ptr\fP\fB);\fP
\fI\fB
-\fBpng_byte png_get_copyright (png_structp \fIpng_ptr\fP\fB);\fP
+\fBpng_byte png_get_copyright (const_png_structp \fIpng_ptr\fP\fB);\fP
\fI\fB
-\fBpng_voidp png_get_error_ptr (png_structp \fIpng_ptr\fP\fB);\fP
+\fBpng_voidp png_get_error_ptr (const_png_structp \fIpng_ptr\fP\fB);\fP
\fI\fB
-\fBpng_byte png_get_filter_type (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
+\fBpng_byte png_get_filter_type (const_png_structp \fP\fIpng_ptr\fP\fB, const_png_infop \fIinfo_ptr\fP\fB);\fP
\fI\fB
-\fBpng_uint_32 png_get_gAMA (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, double \fI*file_gamma\fP\fB);\fP
+\fBpng_uint_32 png_get_gAMA (const_png_structp \fP\fIpng_ptr\fP\fB, const_png_infop \fP\fIinfo_ptr\fP\fB, double \fI*file_gamma\fP\fB);\fP
\fI\fB
-\fBpng_uint_32 png_get_gAMA_fixed (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fI*int_file_gamma\fP\fB);\fP
+\fBpng_uint_32 png_get_gAMA_fixed (const_png_structp \fP\fIpng_ptr\fP\fB, const_png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fI*int_file_gamma\fP\fB);\fP
\fI\fB
-\fBpng_byte png_get_header_ver (png_structp \fIpng_ptr\fP\fB);\fP
+\fBpng_byte png_get_header_ver (const_png_structp \fIpng_ptr\fP\fB);\fP
\fI\fB
-\fBpng_byte png_get_header_version (png_structp \fIpng_ptr\fP\fB);\fP
+\fBpng_byte png_get_header_version (const_png_structp \fIpng_ptr\fP\fB);\fP
\fI\fB
-\fBpng_uint_32 png_get_hIST (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_16p \fI*hist\fP\fB);\fP
+\fBpng_uint_32 png_get_hIST (const_png_structp \fP\fIpng_ptr\fP\fB, const_png_infop \fP\fIinfo_ptr\fP\fB, png_uint_16p \fI*hist\fP\fB);\fP
\fI\fB
-\fBpng_uint_32 png_get_iCCP (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_charpp \fP\fIname\fP\fB, int \fP\fI*compression_type\fP\fB, png_bytepp \fP\fIprofile\fP\fB, png_uint_32 \fI*proflen\fP\fB);\fP
+\fBpng_uint_32 png_get_iCCP (const_png_structp \fP\fIpng_ptr\fP\fB, const_png_infop \fP\fIinfo_ptr\fP\fB, png_charpp \fP\fIname\fP\fB, int \fP\fI*compression_type\fP\fB, png_bytepp \fP\fIprofile\fP\fB, png_uint_32 \fI*proflen\fP\fB);\fP
\fI\fB
@@ -168,11 +168,11 @@
\fI\fB
-\fBpng_uint_32 png_get_image_height (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
+\fBpng_uint_32 png_get_image_height (const_png_structp \fP\fIpng_ptr\fP\fB, const_png_infop \fIinfo_ptr\fP\fB);\fP
\fI\fB
-\fBpng_uint_32 png_get_image_width (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
+\fBpng_uint_32 png_get_image_width (const_png_structp \fP\fIpng_ptr\fP\fB, const_png_infop \fIinfo_ptr\fP\fB);\fP
\fI\fB
@@ -180,7 +180,7 @@
\fI\fB
-\fBpng_byte png_get_interlace_type (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
+\fBpng_byte png_get_interlace_type (const_png_structp \fP\fIpng_ptr\fP\fB, const_png_infop \fIinfo_ptr\fP\fB);\fP
\fI\fB
@@ -188,109 +188,109 @@
\fI\fB
-\fBpng_byte png_get_libpng_ver (png_structp \fIpng_ptr\fP\fB);\fP
+\fBpng_byte png_get_libpng_ver (const_png_structp \fIpng_ptr\fP\fB);\fP
\fI\fB
-\fBpng_alloc_size_t png_get_chunk_malloc_max (png_structp \fIpng_ptr\fP\fB);\fP
+\fBpng_alloc_size_t png_get_chunk_malloc_max (const_png_structp \fIpng_ptr\fP\fB);\fP
\fI\fB
-\fBpng_voidp png_get_mem_ptr(png_structp \fIpng_ptr\fP\fB);\fP
+\fBpng_voidp png_get_mem_ptr(const_png_structp \fIpng_ptr\fP\fB);\fP
\fI\fB
-\fBint png_get_num_cols (png_structp \fIpng_ptr\fP\fB);\fP
+\fBint png_get_num_cols (const_png_structp \fIpng_ptr\fP\fB);\fP
\fI\fB
-\fBint png_get_num_passes (png_structp \fIpng_ptr\fP\fB);\fP
+\fBint png_get_num_passes (const_png_structp \fIpng_ptr\fP\fB);\fP
\fI\fB
-\fBint png_get_num_rows (png_structp \fIpng_ptr\fP\fB);\fP
+\fBint png_get_num_rows (const_png_structp \fIpng_ptr\fP\fB);\fP
\fI\fB
-\fBpng_uint_32 png_get_oFFs (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fI*offset_x\fP\fB, png_uint_32 \fP\fI*offset_y\fP\fB, int \fI*unit_type\fP\fB);\fP
+\fBpng_uint_32 png_get_oFFs (const_png_structp \fP\fIpng_ptr\fP\fB, const_png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fI*offset_x\fP\fB, png_uint_32 \fP\fI*offset_y\fP\fB, int \fI*unit_type\fP\fB);\fP
\fI\fB
-\fBpng_uint_32 png_get_pCAL (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_charp \fP\fI*purpose\fP\fB, png_int_32 \fP\fI*X0\fP\fB, png_int_32 \fP\fI*X1\fP\fB, int \fP\fI*type\fP\fB, int \fP\fI*nparams\fP\fB, png_charp \fP\fI*units\fP\fB, png_charpp \fI*params\fP\fB);\fP
+\fBpng_uint_32 png_get_pCAL (const_png_structp \fP\fIpng_ptr\fP\fB, const_png_infop \fP\fIinfo_ptr\fP\fB, png_charp \fP\fI*purpose\fP\fB, png_int_32 \fP\fI*X0\fP\fB, png_int_32 \fP\fI*X1\fP\fB, int \fP\fI*type\fP\fB, int \fP\fI*nparams\fP\fB, png_charp \fP\fI*units\fP\fB, png_charpp \fI*params\fP\fB);\fP
\fI\fB
-\fBpng_uint_32 png_get_pHYs (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fI*res_x\fP\fB, png_uint_32 \fP\fI*res_y\fP\fB, int \fI*unit_type\fP\fB);\fP
+\fBpng_uint_32 png_get_pHYs (const_png_structp \fP\fIpng_ptr\fP\fB, const_png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fI*res_x\fP\fB, png_uint_32 \fP\fI*res_y\fP\fB, int \fI*unit_type\fP\fB);\fP
\fI\fB
-\fBfloat png_get_pixel_aspect_ratio (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
+\fBfloat png_get_pixel_aspect_ratio (const_png_structp \fP\fIpng_ptr\fP\fB, const_png_infop \fIinfo_ptr\fP\fB);\fP
\fI\fB
-\fBpng_fixed_point png_get_pixel_aspect_ratio_fixed (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
+\fBpng_fixed_point png_get_pixel_aspect_ratio_fixed (const_png_structp \fP\fIpng_ptr\fP\fB, const_png_infop \fIinfo_ptr\fP\fB);\fP
\fI\fB
-\fBpng_uint_32 png_get_pixels_per_meter (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
+\fBpng_uint_32 png_get_pixels_per_meter (const_png_structp \fP\fIpng_ptr\fP\fB, const_png_infop \fIinfo_ptr\fP\fB);\fP
\fI\fB
-\fBpng_voidp png_get_progressive_ptr (png_structp \fIpng_ptr\fP\fB);\fP
+\fBpng_voidp png_get_progressive_ptr (const_png_structp \fIpng_ptr\fP\fB);\fP
\fI\fB
-\fBpng_uint_32 png_get_PLTE (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_colorp \fP\fI*palette\fP\fB, int \fI*num_palette\fP\fB);\fP
+\fBpng_uint_32 png_get_PLTE (const_png_structp \fP\fIpng_ptr\fP\fB, const_png_infop \fP\fIinfo_ptr\fP\fB, png_colorp \fP\fI*palette\fP\fB, int \fI*num_palette\fP\fB);\fP
\fI\fB
-\fBpng_byte png_get_rgb_to_gray_status (png_structp \fIpng_ptr)
+\fBpng_byte png_get_rgb_to_gray_status (const_png_structp \fIpng_ptr)
-\fBpng_uint_32 png_get_rowbytes (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
+\fBpng_uint_32 png_get_rowbytes (const_png_structp \fP\fIpng_ptr\fP\fB, const_png_infop \fIinfo_ptr\fP\fB);\fP
\fI\fB
-\fBpng_bytepp png_get_rows (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
+\fBpng_bytepp png_get_rows (const_png_structp \fP\fIpng_ptr\fP\fB, const_png_infop \fIinfo_ptr\fP\fB);\fP
\fI\fB
-\fBpng_uint_32 png_get_sBIT (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_color_8p \fI*sig_bit\fP\fB);\fP
+\fBpng_uint_32 png_get_sBIT (const_png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_color_8p \fI*sig_bit\fP\fB);\fP
\fI\fB
-\fBvoid png_get_sCAL (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int* \fP\fIunit\fP\fB, double* \fP\fIwidth\fP\fB, double* \fIheight\fP\fB);\fP
+\fBvoid png_get_sCAL (const_png_structp \fP\fIpng_ptr\fP\fB, const_png_infop \fP\fIinfo_ptr\fP\fB, int* \fP\fIunit\fP\fB, double* \fP\fIwidth\fP\fB, double* \fIheight\fP\fB);\fP
\fI\fB
-\fBvoid png_get_sCAL_fixed (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int* \fP\fIunit\fP\fB, png_fixed_pointp \fP\fIwidth\fP\fB, png_fixed_pointp \fIheight\fP\fB);\fP
+\fBvoid png_get_sCAL_fixed (const_png_structp \fP\fIpng_ptr\fP\fB, const_png_infop \fP\fIinfo_ptr\fP\fB, int* \fP\fIunit\fP\fB, png_fixed_pointp \fP\fIwidth\fP\fB, png_fixed_pointp \fIheight\fP\fB);\fP
\fI\fB
-\fBvoid png_get_sCAL_s (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int* \fP\fIunit\fP\fB, png_charpp \fP\fIwidth\fP\fB, \fIpng_charppheight\fP\fB);\fP
+\fBvoid png_get_sCAL_s (const_png_structp \fP\fIpng_ptr\fP\fB, const_png_infop \fP\fIinfo_ptr\fP\fB, int* \fP\fIunit\fP\fB, png_charpp \fP\fIwidth\fP\fB, png_charpp \fIheight\fP\fB);\fP
\fI\fB
-\fBpng_bytep png_get_signature (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
+\fBpng_bytep png_get_signature (const_png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
\fI\fB
-\fBpng_uint_32 png_get_sPLT (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_spalette_p \fI*splt_ptr\fP\fB);\fP
+\fBpng_uint_32 png_get_sPLT (const_png_structp \fP\fIpng_ptr\fP\fB, const_png_infop \fP\fIinfo_ptr\fP\fB, png_spalette_p \fI*splt_ptr\fP\fB);\fP
\fI\fB
-\fBpng_uint_32 png_get_sRGB (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fI*intent\fP\fB);\fP
+\fBpng_uint_32 png_get_sRGB (const_png_structp \fP\fIpng_ptr\fP\fB, const_png_infop \fP\fIinfo_ptr\fP\fB, int \fI*intent\fP\fB);\fP
\fI\fB
-\fBpng_uint_32 png_get_text (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_textp \fP\fI*text_ptr\fP\fB, int \fI*num_text\fP\fB);\fP
+\fBpng_uint_32 png_get_text (const_png_structp \fP\fIpng_ptr\fP\fB, const_png_infop \fP\fIinfo_ptr\fP\fB, png_textp \fP\fI*text_ptr\fP\fB, int \fI*num_text\fP\fB);\fP
\fI\fB
-\fBpng_uint_32 png_get_tIME (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_timep \fI*mod_time\fP\fB);\fP
+\fBpng_uint_32 png_get_tIME (const_png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_timep \fI*mod_time\fP\fB);\fP
\fI\fB
-\fBpng_uint_32 png_get_tRNS (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_bytep \fP\fI*trans_alpha\fP\fB, int \fP\fI*num_trans\fP\fB, png_color_16p \fI*trans_color\fP\fB);\fP
+\fBpng_uint_32 png_get_tRNS (const_png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_bytep \fP\fI*trans_alpha\fP\fB, int \fP\fI*num_trans\fP\fB, png_color_16p \fI*trans_color\fP\fB);\fP
\fI\fB
@@ -300,7 +300,7 @@
\fI\fB
-\fBpng_uint_32 png_get_uint_31 (png_bytep \fIbuf\fP\fB);\fP
+\fBpng_uint_32 png_get_uint_31 (png_structp \fP\fIpng_ptr\fP\fB, png_bytep \fIbuf\fP\fB);\fP
\fI\fB
@@ -310,67 +310,67 @@
\fI\fB
-\fBpng_uint_32 png_get_unknown_chunks (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_unknown_chunkpp \fIunknowns\fP\fB);\fP
+\fBpng_uint_32 png_get_unknown_chunks (const_png_structp \fP\fIpng_ptr\fP\fB, const_png_infop \fP\fIinfo_ptr\fP\fB, png_unknown_chunkpp \fIunknowns\fP\fB);\fP
\fI\fB
-\fBpng_voidp png_get_user_chunk_ptr (png_structp \fIpng_ptr\fP\fB);\fP
+\fBpng_voidp png_get_user_chunk_ptr (const_png_structp \fIpng_ptr\fP\fB);\fP
\fI\fB
-\fBpng_uint_32 png_get_user_height_max( png_structp \fIpng_ptr\fP\fB);\fP
+\fBpng_uint_32 png_get_user_height_max(const_png_structp \fIpng_ptr\fP\fB);\fP
\fI\fB
-\fBpng_voidp png_get_user_transform_ptr (png_structp \fIpng_ptr\fP\fB);\fP
+\fBpng_voidp png_get_user_transform_ptr (const_png_structp \fIpng_ptr\fP\fB);\fP
\fI\fB
-\fBpng_uint_32 png_get_user_width_max (png_structp \fIpng_ptr\fP\fB);\fP
+\fBpng_uint_32 png_get_user_width_max (const_png_structp \fIpng_ptr\fP\fB);\fP
\fI\fB
-\fBpng_uint_32 png_get_valid (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fIflag\fP\fB);\fP
+\fBpng_uint_32 png_get_valid (const_png_structp \fP\fIpng_ptr\fP\fB, const_png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fIflag\fP\fB);\fP
\fI\fB
-\fBfloat png_get_x_offset_inches (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
+\fBfloat png_get_x_offset_inches (const_png_structp \fP\fIpng_ptr\fP\fB, const_png_infop \fIinfo_ptr\fP\fB);\fP
\fI\fB
-\fBpng_fixed_point png_get_x_offset_inches_fixed (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
+\fBpng_fixed_point png_get_x_offset_inches_fixed (png_structp \fP\fIpng_ptr\fP\fB, const_png_infop \fIinfo_ptr\fP\fB);\fP
\fI\fB
-\fBpng_int_32 png_get_x_offset_microns (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
+\fBpng_int_32 png_get_x_offset_microns (const_png_structp \fP\fIpng_ptr\fP\fB, const_png_infop \fIinfo_ptr\fP\fB);\fP
\fI\fB
-\fBpng_int_32 png_get_x_offset_pixels (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
+\fBpng_int_32 png_get_x_offset_pixels (const_png_structp \fP\fIpng_ptr\fP\fB, const_png_infop \fIinfo_ptr\fP\fB);\fP
\fI\fB
-\fBpng_uint_32 png_get_x_pixels_per_meter (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
+\fBpng_uint_32 png_get_x_pixels_per_meter (const_png_structp \fP\fIpng_ptr\fP\fB, const_png_infop \fIinfo_ptr\fP\fB);\fP
\fI\fB
-\fBfloat png_get_y_offset_inches (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
+\fBfloat png_get_y_offset_inches (const_png_structp \fP\fIpng_ptr\fP\fB, const_png_infop \fIinfo_ptr\fP\fB);\fP
\fI\fB
-\fBpng_fixed_point png_get_y_offset_inches_fixed (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
+\fBpng_fixed_point png_get_y_offset_inches_fixed (png_structp \fP\fIpng_ptr\fP\fB, const_png_infop \fIinfo_ptr\fP\fB);\fP
\fI\fB
-\fBpng_int_32 png_get_y_offset_microns (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
+\fBpng_int_32 png_get_y_offset_microns (const_png_structp \fP\fIpng_ptr\fP\fB, const_png_infop \fIinfo_ptr\fP\fB);\fP
\fI\fB
-\fBpng_int_32 png_get_y_offset_pixels (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
+\fBpng_int_32 png_get_y_offset_pixels (const_png_structp \fP\fIpng_ptr\fP\fB, const_png_infop \fIinfo_ptr\fP\fB);\fP
\fI\fB
-\fBpng_uint_32 png_get_y_pixels_per_meter (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
+\fBpng_uint_32 png_get_y_pixels_per_meter (const_png_structp \fP\fIpng_ptr\fP\fB, const_png_infop \fIinfo_ptr\fP\fB);\fP
\fI\fB
@@ -851,7 +851,7 @@
.SH LIBPNG.TXT
libpng-manual.txt - A description on how to use and modify libpng
- libpng version 1.5.1rc01 - January 21, 2011
+ libpng version 1.5.1beta07 - January 22, 2011
Updated and distributed by Glenn Randers-Pehrson
<glennrp at users.sourceforge.net>
Copyright (c) 1998-2011 Glenn Randers-Pehrson
@@ -862,7 +862,7 @@
Based on:
- libpng versions 0.97, January 1998, through 1.5.1rc01 - January 21, 2011
+ libpng versions 0.97, January 1998, through 1.5.1beta07 - January 22, 2011
Updated and distributed by Glenn Randers-Pehrson
Copyright (c) 1998-2011 Glenn Randers-Pehrson
@@ -1160,13 +1160,15 @@
FILE *fp = fopen(file_name, "rb");
if (!fp)
{
- return (ERROR);
+ return (ERROR);
}
+
fread(header, 1, number, fp);
is_png = !png_sig_cmp(header, 0, number);
+
if (!is_png)
{
- return (NOT_PNG);
+ return (NOT_PNG);
}
@@ -1182,29 +1184,32 @@
create the structure, so your application should check for that.
png_structp png_ptr = png_create_read_struct
- (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
+ (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
user_error_fn, user_warning_fn);
+
if (!png_ptr)
- return (ERROR);
+ return (ERROR);
png_infop info_ptr = png_create_info_struct(png_ptr);
+
if (!info_ptr)
{
- png_destroy_read_struct(&png_ptr,
+ png_destroy_read_struct(&png_ptr,
(png_infopp)NULL, (png_infopp)NULL);
- return (ERROR);
+ return (ERROR);
}
png_infop end_info = png_create_info_struct(png_ptr);
+
if (!end_info)
{
- png_destroy_read_struct(&png_ptr, &info_ptr,
+ png_destroy_read_struct(&png_ptr, &info_ptr,
(png_infopp)NULL);
- return (ERROR);
+ return (ERROR);
}
If you want to use your own memory allocation routines,
-define PNG_USER_MEM_SUPPORTED and use
+use a libpng that was built with PNG_USER_MEM_SUPPORTED defined, and use
png_create_read_struct_2() instead of png_create_read_struct():
png_structp png_ptr = png_create_read_struct_2
@@ -1232,10 +1237,10 @@
if (setjmp(png_jmpbuf(png_ptr)))
{
- png_destroy_read_struct(&png_ptr, &info_ptr,
+ png_destroy_read_struct(&png_ptr, &info_ptr,
&end_info);
- fclose(fp);
- return (ERROR);
+ fclose(fp);
+ return (ERROR);
}
If you would rather avoid the complexity of setjmp/longjmp issues,
@@ -1374,14 +1379,17 @@
1: ignore; do not keep
2: keep only if safe-to-copy
3: keep even if unsafe-to-copy
+
You can use these definitions:
PNG_HANDLE_CHUNK_AS_DEFAULT 0
PNG_HANDLE_CHUNK_NEVER 1
PNG_HANDLE_CHUNK_IF_SAFE 2
PNG_HANDLE_CHUNK_ALWAYS 3
+
chunk_list - list of chunks affected (a byte string,
five bytes per chunk, NULL or '\0' if
num_chunks is 0)
+
num_chunks - number of chunks affected; if 0, all
unknown chunks are affected. If nonzero,
only the chunks in the list are affected
@@ -1417,8 +1425,10 @@
#if defined(PNG_UNKNOWN_CHUNKS_SUPPORTED)
/* ignore all unknown chunks: */
png_set_keep_unknown_chunks(read_ptr, 1, NULL, 0);
+
/* except for vpAg: */
png_set_keep_unknown_chunks(read_ptr, 2, vpAg, 1);
+
/* also ignore unused known chunks: */
png_set_keep_unknown_chunks(read_ptr, 1, unused_chunks,
(int)sizeof(unused_chunks)/5);
@@ -1531,17 +1541,22 @@
if (height > PNG_UINT_32_MAX/png_sizeof(png_byte))
png_error (png_ptr,
- "Image is too tall to process in memory");
+ "Image is too tall to process in memory");
+
if (width > PNG_UINT_32_MAX/pixel_size)
png_error (png_ptr,
- "Image is too wide to process in memory");
+ "Image is too wide to process in memory");
+
row_pointers = png_malloc(png_ptr,
- height*png_sizeof(png_bytep));
+ height*png_sizeof(png_bytep));
+
for (int i=0; i<height, i++)
row_pointers[i]=NULL; /* security precaution */
+
for (int i=0; i<height, i++)
row_pointers[i]=png_malloc(png_ptr,
- width*pixel_size);
+ width*pixel_size);
+
png_set_rows(png_ptr, info_ptr, &row_pointers);
Alternatively you could allocate your image in one big block and define
@@ -1551,7 +1566,7 @@
row_pointers (and row_pointers[i], if they were separately allocated).
If you don't allocate row_pointers ahead of time, png_read_png() will
-do it, and it'll be free'ed when you call png_destroy_*().
+do it, and it'll be free'ed by libpng when you call png_destroy_*().
.SS The low-level read interface
@@ -1575,13 +1590,16 @@
width - holds the width of the image
in pixels (up to 2^31).
+
height - holds the height of the image
in pixels (up to 2^31).
+
bit_depth - holds the bit depth of one of the
image channels. (valid values are
1, 2, 4, 8, 16 and depend also on
the color_type. See also
significant bits (sBIT) below).
+
color_type - describes which color/alpha channels
are present.
PNG_COLOR_TYPE_GRAY
@@ -1624,28 +1642,38 @@
width = png_get_image_width(png_ptr,
info_ptr);
+
height = png_get_image_height(png_ptr,
info_ptr);
+
bit_depth = png_get_bit_depth(png_ptr,
info_ptr);
+
color_type = png_get_color_type(png_ptr,
info_ptr);
+
interlace_type = png_get_interlace_type(png_ptr,
info_ptr);
+
compression_type = png_get_compression_type(png_ptr,
info_ptr);
+
filter_method = png_get_filter_type(png_ptr,
info_ptr);
channels = png_get_channels(png_ptr, info_ptr);
+
channels - number of channels of info for the
color type (valid values are 1 (GRAY,
PALETTE), 2 (GRAY_ALPHA), 3 (RGB),
4 (RGB_ALPHA or RGB + filler byte))
+
rowbytes = png_get_rowbytes(png_ptr, info_ptr);
+
rowbytes - number of bytes needed to hold a row
signature = png_get_signature(png_ptr, info_ptr);
+
signature - holds the signature read from the
file (if any). The data is kept in
the same offset it would be if the
@@ -1665,15 +1693,19 @@
png_get_PLTE(png_ptr, info_ptr, &palette,
&num_palette);
+
palette - the palette for the file
(array of png_color)
+
num_palette - number of entries in the palette
png_get_gAMA(png_ptr, info_ptr, &gamma);
+
gamma - the gamma the file is written
at (PNG_INFO_gAMA)
png_get_sRGB(png_ptr, info_ptr, &srgb_intent);
+
srgb_intent - the rendering intent (PNG_INFO_sRGB)
The presence of the sRGB chunk
means that the pixel data is in the
@@ -1683,16 +1715,21 @@
png_get_iCCP(png_ptr, info_ptr, &name,
&compression_type, &profile, &proflen);
+
name - The profile name.
+
compression_type - The compression type; always
PNG_COMPRESSION_TYPE_BASE for PNG 1.0.
You may give NULL to this argument to
ignore it.
+
profile - International Color Consortium color
profile data. May contain NULs.
+
proflen - length of profile data in bytes.
png_get_sBIT(png_ptr, info_ptr, &sig_bit);
+
sig_bit - the number of significant bits for
(PNG_INFO_sBIT) each of the gray,
red, green, and blue channels,
@@ -1701,50 +1738,66 @@
png_get_tRNS(png_ptr, info_ptr, &trans_alpha,
&num_trans, &trans_color);
+
trans_alpha - array of alpha (transparency)
entries for palette (PNG_INFO_tRNS)
+
num_trans - number of transparent entries
(PNG_INFO_tRNS)
+
trans_color - graylevel or color sample values of
the single transparent color for
non-paletted images (PNG_INFO_tRNS)
png_get_hIST(png_ptr, info_ptr, &hist);
(PNG_INFO_hIST)
+
hist - histogram of palette (array of
png_uint_16)
png_get_tIME(png_ptr, info_ptr, &mod_time);
+
mod_time - time image was last modified
(PNG_VALID_tIME)
png_get_bKGD(png_ptr, info_ptr, &background);
+
background - background color (PNG_VALID_bKGD)
valid 16-bit red, green and blue
values, regardless of color_type
num_comments = png_get_text(png_ptr, info_ptr,
&text_ptr, &num_text);
+
num_comments - number of comments
+
text_ptr - array of png_text holding image
comments
+
text_ptr[i].compression - type of compression used
on "text" PNG_TEXT_COMPRESSION_NONE
PNG_TEXT_COMPRESSION_zTXt
PNG_ITXT_COMPRESSION_NONE
PNG_ITXT_COMPRESSION_zTXt
+
text_ptr[i].key - keyword for comment. Must contain
1-79 characters.
+
text_ptr[i].text - text comments for current
keyword. Can be empty.
+
text_ptr[i].text_length - length of text string,
after decompression, 0 for iTXt
+
text_ptr[i].itxt_length - length of itxt string,
after decompression, 0 for tEXt/zTXt
+
text_ptr[i].lang - language of comment (empty
string for unknown).
+
text_ptr[i].lang_key - keyword in UTF-8
(empty string for unknown).
+
Note that the itxt_length, lang, and lang_key
members of the text_ptr structure only exist
when the library is built with iTXt chunk support.
@@ -1752,6 +1805,7 @@
num_text - number of comments (same as
num_comments; you can put NULL here
to avoid the duplication)
+
Note while png_set_text() will accept text, language,
and translated keywords that can be NULL pointers, the
structure returned by png_get_text will always contain
@@ -1760,49 +1814,68 @@
num_spalettes = png_get_sPLT(png_ptr, info_ptr,
&palette_ptr);
+
+ num_spalettes - number of sPLT chunks read.
+
palette_ptr - array of palette structures holding
contents of one or more sPLT chunks
read.
- num_spalettes - number of sPLT chunks read.
png_get_oFFs(png_ptr, info_ptr, &offset_x, &offset_y,
&unit_type);
+
offset_x - positive offset from the left edge
of the screen
+
offset_y - positive offset from the top edge
of the screen
+
unit_type - PNG_OFFSET_PIXEL, PNG_OFFSET_MICROMETER
png_get_pHYs(png_ptr, info_ptr, &res_x, &res_y,
&unit_type);
+
res_x - pixels/unit physical resolution in
x direction
+
res_y - pixels/unit physical resolution in
x direction
+
unit_type - PNG_RESOLUTION_UNKNOWN,
PNG_RESOLUTION_METER
png_get_sCAL(png_ptr, info_ptr, &unit, &width,
&height)
+
unit - physical scale units (an integer)
+
width - width of a pixel in physical scale units
+
height - height of a pixel in physical scale units
(width and height are doubles)
png_get_sCAL_s(png_ptr, info_ptr, &unit, &width,
&height)
+
unit - physical scale units (an integer)
+
width - width of a pixel in physical scale units
+
height - height of a pixel in physical scale units
(width and height are strings like "2.54")
num_unknown_chunks = png_get_unknown_chunks(png_ptr,
info_ptr, &unknowns)
+
unknowns - array of png_unknown_chunk
structures holding unknown chunks
+
unknowns[i].name - name of unknown chunk
+
unknowns[i].data - data of unknown chunk
+
unknowns[i].size - size of unknown chunk's data
+
unknowns[i].location - position of chunk in file
The value of "i" corresponds to the order in which the
@@ -1814,34 +1887,55 @@
res_x = png_get_x_pixels_per_meter(png_ptr,
info_ptr)
+
res_y = png_get_y_pixels_per_meter(png_ptr,
info_ptr)
+
res_x_and_y = png_get_pixels_per_meter(png_ptr,
info_ptr)
+
res_x = png_get_x_pixels_per_inch(png_ptr,
info_ptr)
+
res_y = png_get_y_pixels_per_inch(png_ptr,
info_ptr)
+
res_x_and_y = png_get_pixels_per_inch(png_ptr,
info_ptr)
+
aspect_ratio = png_get_pixel_aspect_ratio(png_ptr,
info_ptr)
- (Each of these returns 0 [signifying "unknown"] if
+ Each of these returns 0 [signifying "unknown"] if
the data is not present or if res_x is 0;
- res_x_and_y is 0 if res_x != res_y)
+ res_x_and_y is 0 if res_x != res_y
+
+ Note that because of the way the resolutions are
+ stored internally, the inch conversions won't
+ come out to exactly even number. For example,
+ 72 dpi is stored as 0.28346 pixels/meter, and
+ when this is retrieved it is 71.9988 dpi, so
+ be sure to round the returned value appropriately
+ if you want to display a reasonable-looking result.
The data from the oFFs chunk can be retrieved in several convenient
forms:
x_offset = png_get_x_offset_microns(png_ptr, info_ptr);
+
y_offset = png_get_y_offset_microns(png_ptr, info_ptr);
+
x_offset = png_get_x_offset_inches(png_ptr, info_ptr);
+
y_offset = png_get_y_offset_inches(png_ptr, info_ptr);
- (Each of these returns 0 [signifying "unknown" if both
+ Each of these returns 0 [signifying "unknown" if both
x and y are 0] if the data is not present or if the
- chunk is present but the unit is the pixel)
+ chunk is present but the unit is the pixel. The
+ remark about inexact inch conversions applies here
+ as well, because a value in inches can't always be
+ converted to microns and back without some loss
+ of precision.
For more information, see the png_info definition in png.h and the
PNG specification for chunk contents. Be careful with trusting
@@ -1928,7 +2022,7 @@
As of libpng version 1.2.9, png_set_expand_gray_1_2_4_to_8() was
added. It expands the sample depth without changing tRNS to alpha.
-As of libpng version 1.5.1rc01, not all possible expansions are supported.
+As of libpng version 1.5.1beta07, not all possible expansions are supported.
In the following table, the 01 means grayscale with depth<8, 31 means
indexed with depth<8, other numerals represent the color type, "T" means
@@ -1969,7 +2063,7 @@
8 bits per channel, this will strip the pixels down to 8 bit.
if (bit_depth == 16)
- png_set_strip_16(png_ptr);
+ png_set_strip_16(png_ptr);
If, for some reason, you don't need the alpha channel on an image,
and you want to remove it rather than combining it with the background
@@ -1977,7 +2071,7 @@
it with the background, so that's what you should probably do):
if (color_type & PNG_COLOR_MASK_ALPHA)
- png_set_strip_alpha(png_ptr);
+ png_set_strip_alpha(png_ptr);
In PNG files, the alpha channel in an image
is the level of opacity. If you need the alpha channel in an image to
@@ -1994,7 +2088,7 @@
values of the pixels:
if (bit_depth < 8)
- png_set_packing(png_ptr);
+ png_set_packing(png_ptr);
PNG files have possible bit depths of 1, 2, 4, 8, and 16. All pixels
stored in a PNG image have been "scaled" or "shifted" up to the next
@@ -2006,20 +2100,20 @@
png_color_8p sig_bit;
if (png_get_sBIT(png_ptr, info_ptr, &sig_bit))
- png_set_shift(png_ptr, sig_bit);
+ png_set_shift(png_ptr, sig_bit);
PNG files store 3-color pixels in red, green, blue order. This code
changes the storage of the pixels to blue, green, red:
if (color_type == PNG_COLOR_TYPE_RGB ||
color_type == PNG_COLOR_TYPE_RGB_ALPHA)
- png_set_bgr(png_ptr);
+ png_set_bgr(png_ptr);
PNG files store RGB pixels packed into 3 or 6 bytes. This code expands them
into 4 or 8 bytes for windowing systems that need them in this format:
if (color_type == PNG_COLOR_TYPE_RGB)
- png_set_filler(png_ptr, filler, PNG_FILLER_BEFORE);
+ png_set_filler(png_ptr, filler, PNG_FILLER_BEFORE);
where "filler" is the 8 or 16-bit number to fill with, and the location is
either PNG_FILLER_BEFORE or PNG_FILLER_AFTER, depending upon whether
@@ -2032,8 +2126,8 @@
to do that, you can add a true alpha channel with
if (color_type == PNG_COLOR_TYPE_RGB ||
- color_type == PNG_COLOR_TYPE_GRAY)
- png_set_add_alpha(png_ptr, filler, PNG_FILLER_AFTER);
+ color_type == PNG_COLOR_TYPE_GRAY)
+ png_set_add_alpha(png_ptr, filler, PNG_FILLER_AFTER);
where "filler" contains the alpha value to assign to each pixel.
This function was added in libpng-1.2.7.
@@ -2042,33 +2136,36 @@
data as ARGB instead of the normal PNG format RGBA:
if (color_type == PNG_COLOR_TYPE_RGB_ALPHA)
- png_set_swap_alpha(png_ptr);
+ png_set_swap_alpha(png_ptr);
For some uses, you may want a grayscale image to be represented as
RGB. This code will do that conversion:
if (color_type == PNG_COLOR_TYPE_GRAY ||
color_type == PNG_COLOR_TYPE_GRAY_ALPHA)
- png_set_gray_to_rgb(png_ptr);
+ png_set_gray_to_rgb(png_ptr);
Conversely, you can convert an RGB or RGBA image to grayscale or grayscale
with alpha.
if (color_type == PNG_COLOR_TYPE_RGB ||
color_type == PNG_COLOR_TYPE_RGB_ALPHA)
- png_set_rgb_to_gray_fixed(png_ptr, error_action,
- int red_weight, int green_weight);
+ png_set_rgb_to_gray_fixed(png_ptr, error_action,
+ int red_weight, int green_weight);
error_action = 1: silently do the conversion
+
error_action = 2: issue a warning if the original
image has any pixel where
red != green or red != blue
+
error_action = 3: issue an error and abort the
conversion if the original
image has any pixel where
red != green or red != blue
red_weight: weight of red component times 100000
+
green_weight: weight of green component times 100000
If either weight is negative, default
weights (21268, 71514) are used.
@@ -2119,11 +2216,11 @@
png_color_16p image_background;
if (png_get_bKGD(png_ptr, info_ptr, &image_background))
- png_set_background(png_ptr, image_background,
- PNG_BACKGROUND_GAMMA_FILE, 1, 1.0);
+ png_set_background(png_ptr, image_background,
+ PNG_BACKGROUND_GAMMA_FILE, 1, 1.0);
else
- png_set_background(png_ptr, &my_background,
- PNG_BACKGROUND_GAMMA_SCREEN, 0, 1.0);
+ png_set_background(png_ptr, &my_background,
+ PNG_BACKGROUND_GAMMA_SCREEN, 0, 1.0);
The png_set_background() function tells libpng to composite images
with alpha or simple transparency against the supplied background
@@ -2156,6 +2253,7 @@
{
screen_gamma = user_defined_screen_gamma;
}
+
/* One way that applications can share the same
screen gamma value */
else if ((gamma_str = getenv("SCREEN_GAMMA"))
@@ -2163,13 +2261,16 @@
{
screen_gamma = (double)atof(gamma_str);
}
+
/* If we don't have another value */
else
{
screen_gamma = 2.2; /* A good guess for a
PC monitor in a bright office or a dim room */
+
screen_gamma = 2.0; /* A good guess for a
PC monitor in a dark room */
+
screen_gamma = 1.7 or 1.0; /* A good
guess for Mac systems */
}
@@ -2186,6 +2287,7 @@
if (png_get_gAMA(png_ptr, info_ptr, &gamma))
png_set_gamma(png_ptr, screen_gamma, gamma);
+
else
png_set_gamma(png_ptr, screen_gamma, 0.45455);
@@ -2193,7 +2295,7 @@
file has more entries then will fit on your screen, png_set_quantize()
will do that. Note that this is a simple match quantization that merely
finds the closest color available. This should work fairly well with
-optimized palettes, and fairly badly with linear color cubes. If you
+optimized palettes, but fairly badly with linear color cubes. If you
pass a palette that is larger then maximum_colors, the file will
reduce the number of colors in the palette so it will fit into
maximum_colors. If there is a histogram, it will use it to make
@@ -2203,15 +2305,16 @@
if (color_type & PNG_COLOR_MASK_COLOR)
{
if (png_get_valid(png_ptr, info_ptr,
- PNG_INFO_PLTE))
+ PNG_INFO_PLTE))
{
png_uint_16p histogram = NULL;
png_get_hIST(png_ptr, info_ptr,
- &histogram);
+ &histogram);
png_set_quantize(png_ptr, palette, num_palette,
max_screen_colors, histogram, 1);
}
+
else
{
png_color std_color_cube[MAX_SCREEN_COLORS] =
@@ -2233,7 +2336,7 @@
This function can also be used to invert grayscale and gray-alpha images:
if (color_type == PNG_COLOR_TYPE_GRAY ||
- color_type == PNG_COLOR_TYPE_GRAY_ALPHA)
+ color_type == PNG_COLOR_TYPE_GRAY_ALPHA)
png_set_invert_mono(png_ptr);
PNG files store 16 bit pixels in network byte order (big-endian,
@@ -2242,7 +2345,7 @@
way PCs store them):
if (bit_depth == 16)
- png_set_swap(png_ptr);
+ png_set_swap(png_ptr);
If you are using packed-pixel images (1, 2, or 4 bits/pixel), and you
need to change the order the pixels are packed into bytes, you can use:
@@ -2255,12 +2358,12 @@
with
png_set_read_user_transform_fn(png_ptr,
- read_transform_fn);
+ read_transform_fn);
You must supply the function
void read_transform_fn(png_ptr ptr, row_info_ptr
- row_info, png_bytep data)
+ row_info, png_bytep data)
See pngtest.c for a working example. Your function will be called
after all of the other transformations have been processed.
@@ -2271,7 +2374,7 @@
function
png_set_user_transform_info(png_ptr, user_ptr,
- user_depth, user_channels);
+ user_depth, user_channels);
The user's application, not libpng, is responsible for allocating and
freeing any memory required for the user structure.
@@ -2280,7 +2383,7 @@
png_get_user_transform_ptr(). For example:
voidp read_user_transform_ptr =
- png_get_user_transform_ptr(png_ptr);
+ png_get_user_transform_ptr(png_ptr);
The last thing to handle is interlacing; this is covered in detail below,
but you must call the function here if you want libpng to handle expansion
@@ -2305,13 +2408,13 @@
array of pointers to each row, as it will be needed for some
of the functions below.
-Remember: Before you call png_read_update_info the png_get_
+Remember: Before you call png_read_update_info(), the png_get_
functions return the values corresponding to the original PNG image.
After you call png_read_update_info the values refer to the image
that libpng will output. Consequently you must call all the png_set_
-functions before you call png_read_update_info. This is particularly
-important for png_set_interlace_handling - if you are going to call
-png_read_update_info you must call png_set_interlace_handling before
+functions before you call png_read_update_info(). This is particularly
+important for png_set_interlace_handling() - if you are going to call
+png_read_update_info() you must call png_set_interlace_handling() before
it unless you want to receive interlaced output.
.SS Reading image data
@@ -2341,7 +2444,7 @@
interlace_type == PNG_INTERLACE_NONE), this is simple:
png_read_rows(png_ptr, row_pointers, NULL,
- number_of_rows);
+ number_of_rows);
where row_pointers is the same as in the png_read_image() call.
@@ -2375,7 +2478,7 @@
calling png_start_read_image() or png_read_update_info():
if (interlace_type == PNG_INTERLACE_ADAM7)
- number_of_passes
+ number_of_passes
= png_set_interlace_handling(png_ptr);
This will return the number of passes needed. Currently, this is seven,
@@ -2401,14 +2504,14 @@
pass, and assumes the data from previous passes is still valid.
png_read_rows(png_ptr, row_pointers, NULL,
- number_of_rows);
+ number_of_rows);
If you only want the first effect (the rectangles), do the same as
before except pass the row buffer in the third parameter, and leave
the second parameter NULL.
png_read_rows(png_ptr, NULL, row_pointers,
- number_of_rows);
+ number_of_rows);
If you don't want libpng to handle the interlacing details, just call
png_read_rows() PNG_INTERLACE_ADAM7_PASSES times to read in all the images.
@@ -2461,12 +2564,14 @@
while (output_x < output_image_width)
{
- image[output_y][output_x] = subimage[pass][input_y][input_x++];
+ image[output_y][output_x] =
+ subimage[pass][input_y][input_x++];
+
output_x += xStep;
}
++input_y;
- ouput_y += yStep;
+ output_y += yStep;
}
Notice that the steps between successive output rows and columns are
@@ -2518,6 +2623,7 @@
point to libpng-allocated storage with the following function:
png_free_data(png_ptr, info_ptr, mask, seq)
+
mask - identifies data to be freed, a mask
containing the bitwise OR of one or
more of
@@ -2527,6 +2633,7 @@
PNG_FREE_SCAL, PNG_FREE_SPLT,
PNG_FREE_TEXT, PNG_FREE_UNKN,
or simply PNG_FREE_ALL
+
seq - sequence number of item to be freed
(-1 for all items)
@@ -2544,13 +2651,15 @@
or png_zalloc() and passed in via a png_set_*() function, with
png_data_freer(png_ptr, info_ptr, freer, mask)
- mask - which data elements are affected
- same choices as in png_free_data()
+
freer - one of
PNG_DESTROY_WILL_FREE_DATA
PNG_SET_WILL_FREE_DATA
PNG_USER_WILL_FREE_DATA
+ mask - which data elements are affected
+ same choices as in png_free_data()
+
This function only affects data that has already been allocated.
You can call this function after reading the PNG data but before calling
any png_set_*() functions, to control whether the user or the png_set_*()
@@ -2579,6 +2688,7 @@
your application instead of by libpng, you can use
png_set_invalid(png_ptr, info_ptr, mask);
+
mask - identifies the chunks to be made invalid,
containing the bitwise OR of one or
more of
@@ -2618,21 +2728,24 @@
png_ptr = png_create_read_struct
(PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
user_error_fn, user_warning_fn);
+
if (!png_ptr)
return (ERROR);
+
info_ptr = png_create_info_struct(png_ptr);
+
if (!info_ptr)
{
- png_destroy_read_struct(&png_ptr, (png_infopp)NULL,
- (png_infopp)NULL);
- return (ERROR);
+ png_destroy_read_struct(&png_ptr,
+ (png_infopp)NULL, (png_infopp)NULL);
+ return (ERROR);
}
if (setjmp(png_jmpbuf(png_ptr)))
{
- png_destroy_read_struct(&png_ptr, &info_ptr,
- (png_infopp)NULL);
- return (ERROR);
+ png_destroy_read_struct(&png_ptr, &info_ptr,
+ (png_infopp)NULL);
+ return (ERROR);
}
/* This one's new. You can provide functions
@@ -2664,9 +2777,9 @@
{
if (setjmp(png_jmpbuf(png_ptr)))
{
- png_destroy_read_struct(&png_ptr, &info_ptr,
+ png_destroy_read_struct(&png_ptr, &info_ptr,
(png_infopp)NULL);
- return (ERROR);
+ return (ERROR);
}
/* This one's new also. Simply give it a chunk
@@ -2789,10 +2902,9 @@
custom writing functions. See the discussion under Customizing libpng.
FILE *fp = fopen(file_name, "wb");
+
if (!fp)
- {
return (ERROR);
- }
Next, png_struct and png_info need to be allocated and initialized.
As these can be both relatively large, you may not want to store these
@@ -2805,6 +2917,7 @@
png_structp png_ptr = png_create_write_struct
(PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
user_error_fn, user_warning_fn);
+
if (!png_ptr)
return (ERROR);
@@ -2812,7 +2925,7 @@
if (!info_ptr)
{
png_destroy_write_struct(&png_ptr,
- (png_infopp)NULL);
+ (png_infopp)NULL);
return (ERROR);
}
@@ -2838,7 +2951,7 @@
if (setjmp(png_jmpbuf(png_ptr)))
{
- png_destroy_write_struct(&png_ptr, &info_ptr);
+ png_destroy_write_struct(&png_ptr, &info_ptr);
fclose(fp);
return (ERROR);
}
@@ -2908,7 +3021,8 @@
/* turn on or off filtering, and/or choose
specific filters. You can use either a single
PNG_FILTER_VALUE_NAME or the bitwise OR of one
- or more PNG_FILTER_NAME masks. */
+ or more PNG_FILTER_NAME masks.
+ */
png_set_filter(png_ptr, 0,
PNG_FILTER_NONE | PNG_FILTER_VALUE_NONE |
PNG_FILTER_SUB | PNG_FILTER_VALUE_SUB |
@@ -2964,16 +3078,20 @@
png_set_IHDR(png_ptr, info_ptr, width, height,
bit_depth, color_type, interlace_type,
compression_type, filter_method)
+
width - holds the width of the image
in pixels (up to 2^31).
+
height - holds the height of the image
in pixels (up to 2^31).
+
bit_depth - holds the bit depth of one of the
image channels.
(valid values are 1, 2, 4, 8, 16
and depend also on the
color_type. See also significant
bits (sBIT) below).
+
color_type - describes which color/alpha
channels are present.
PNG_COLOR_TYPE_GRAY
@@ -2993,8 +3111,10 @@
interlace_type - PNG_INTERLACE_NONE or
PNG_INTERLACE_ADAM7
+
compression_type - (must be
PNG_COMPRESSION_TYPE_DEFAULT)
+
filter_method - (must be PNG_FILTER_TYPE_DEFAULT
or, if you are writing a PNG to
be embedded in a MNG datastream,
@@ -3012,15 +3132,18 @@
png_set_PLTE(png_ptr, info_ptr, palette,
num_palette);
+
palette - the palette for the file
(array of png_color)
num_palette - number of entries in the palette
png_set_gAMA(png_ptr, info_ptr, gamma);
+
gamma - the gamma the image was created
at (PNG_INFO_gAMA)
png_set_sRGB(png_ptr, info_ptr, srgb_intent);
+
srgb_intent - the rendering intent
(PNG_INFO_sRGB) The presence of
the sRGB chunk means that the pixel
@@ -3040,6 +3163,7 @@
png_set_sRGB_gAMA_and_cHRM(png_ptr, info_ptr,
srgb_intent);
+
srgb_intent - the rendering intent
(PNG_INFO_sRGB) The presence of the
sRGB chunk means that the pixel
@@ -3051,16 +3175,21 @@
png_set_iCCP(png_ptr, info_ptr, name, compression_type,
profile, proflen);
+
name - The profile name.
+
compression_type - The compression type; always
PNG_COMPRESSION_TYPE_BASE for PNG 1.0.
You may give NULL to this argument to
ignore it.
+
profile - International Color Consortium color
profile data. May contain NULs.
+
proflen - length of profile data in bytes.
png_set_sBIT(png_ptr, info_ptr, sig_bit);
+
sig_bit - the number of significant bits for
(PNG_INFO_sBIT) each of the gray, red,
green, and blue channels, whichever are
@@ -3069,30 +3198,38 @@
png_set_tRNS(png_ptr, info_ptr, trans_alpha,
num_trans, trans_color);
+
trans_alpha - array of alpha (transparency)
entries for palette (PNG_INFO_tRNS)
+
trans_color - graylevel or color sample values
(in order red, green, blue) of the
single transparent color for
non-paletted images (PNG_INFO_tRNS)
+
num_trans - number of transparent entries
(PNG_INFO_tRNS)
png_set_hIST(png_ptr, info_ptr, hist);
(PNG_INFO_hIST)
+
hist - histogram of palette (array of
png_uint_16)
png_set_tIME(png_ptr, info_ptr, mod_time);
+
mod_time - time image was last modified
(PNG_VALID_tIME)
png_set_bKGD(png_ptr, info_ptr, background);
+
background - background color (PNG_VALID_bKGD)
png_set_text(png_ptr, info_ptr, text_ptr, num_text);
+
text_ptr - array of png_text holding image
comments
+
text_ptr[i].compression - type of compression used
on "text" PNG_TEXT_COMPRESSION_NONE
PNG_TEXT_COMPRESSION_zTXt
@@ -3118,6 +3255,7 @@
png_set_sPLT(png_ptr, info_ptr, &palette_ptr,
num_spalettes);
+
palette_ptr - array of png_sPLT_struct structures
to be added to the list of palettes
in the info structure.
@@ -3126,35 +3264,48 @@
png_set_oFFs(png_ptr, info_ptr, offset_x, offset_y,
unit_type);
+
offset_x - positive offset from the left
edge of the screen
+
offset_y - positive offset from the top
edge of the screen
+
unit_type - PNG_OFFSET_PIXEL, PNG_OFFSET_MICROMETER
png_set_pHYs(png_ptr, info_ptr, res_x, res_y,
unit_type);
+
res_x - pixels/unit physical resolution
in x direction
+
res_y - pixels/unit physical resolution
in y direction
+
unit_type - PNG_RESOLUTION_UNKNOWN,
PNG_RESOLUTION_METER
png_set_sCAL(png_ptr, info_ptr, unit, width, height)
+
unit - physical scale units (an integer)
+
width - width of a pixel in physical scale units
+
height - height of a pixel in physical scale units
(width and height are doubles)
png_set_sCAL_s(png_ptr, info_ptr, unit, width, height)
+
unit - physical scale units (an integer)
+
width - width of a pixel in physical scale units
+
height - height of a pixel in physical scale units
(width and height are strings like "2.54")
png_set_unknown_chunks(png_ptr, info_ptr, &unknowns,
num_unknowns)
+
unknowns - array of png_unknown_chunk
structures holding unknown chunks
unknowns[i].name - name of unknown chunk
@@ -3193,21 +3344,30 @@
After the text has been written out to the file, the compression type
is set to PNG_TEXT_COMPRESSION_NONE_WR or PNG_TEXT_COMPRESSION_zTXt_WR,
so that it isn't written out again at the end (in case you are calling
-png_write_end() with the same struct.
+png_write_end() with the same struct).
The keywords that are given in the PNG Specification are:
Title Short (one line) title or
caption for image
+
Author Name of image's creator
+
Description Description of image (possibly long)
+
Copyright Copyright notice
+
Creation Time Time of original image creation
(usually RFC 1123 format, see below)
+
Software Software used to create the image
+
Disclaimer Legal disclaimer
+
Warning Warning of nature of content
+
Source Device used to create the image
+
Comment Miscellaneous comment; conversion
from other image format
@@ -3377,17 +3537,19 @@
/* Set the true bit depth of the image data */
if (color_type & PNG_COLOR_MASK_COLOR)
{
- sig_bit.red = true_bit_depth;
- sig_bit.green = true_bit_depth;
- sig_bit.blue = true_bit_depth;
+ sig_bit.red = true_bit_depth;
+ sig_bit.green = true_bit_depth;
+ sig_bit.blue = true_bit_depth;
}
+
else
{
- sig_bit.gray = true_bit_depth;
+ sig_bit.gray = true_bit_depth;
}
+
if (color_type & PNG_COLOR_MASK_ALPHA)
{
- sig_bit.alpha = true_bit_depth;
+ sig_bit.alpha = true_bit_depth;
}
png_set_sBIT(png_ptr, info_ptr, &sig_bit);
@@ -3570,6 +3732,7 @@
point to libpng-allocated storage with the following function:
png_free_data(png_ptr, info_ptr, mask, seq)
+
mask - identifies data to be freed, a mask
containing the bitwise OR of one or
more of
@@ -3579,6 +3742,7 @@
PNG_FREE_SCAL, PNG_FREE_SPLT,
PNG_FREE_TEXT, PNG_FREE_UNKN,
or simply PNG_FREE_ALL
+
seq - sequence number of item to be freed
(-1 for all items)
@@ -3600,19 +3764,22 @@
or png_zalloc() and passed in via a png_set_*() function, with
png_data_freer(png_ptr, info_ptr, freer, mask)
- mask - which data elements are affected
- same choices as in png_free_data()
+
freer - one of
PNG_DESTROY_WILL_FREE_DATA
PNG_SET_WILL_FREE_DATA
PNG_USER_WILL_FREE_DATA
+ mask - which data elements are affected
+ same choices as in png_free_data()
+
For example, to transfer responsibility for some data from a read structure
to a write structure, you could use
png_data_freer(read_ptr, read_info_ptr,
PNG_USER_WILL_FREE_DATA,
PNG_FREE_PLTE|PNG_FREE_tRNS|PNG_FREE_hIST)
+
png_data_freer(write_ptr, write_info_ptr,
PNG_DESTROY_WILL_FREE_DATA,
PNG_FREE_PLTE|PNG_FREE_tRNS|PNG_FREE_hIST)
@@ -3678,6 +3845,7 @@
png_voidp malloc_fn(png_structp png_ptr,
png_alloc_size_t size);
+
void free_fn(png_structp png_ptr, png_voidp ptr);
Your malloc_fn() must return NULL in case of failure. The png_malloc()
@@ -3710,8 +3878,10 @@
void user_read_data(png_structp png_ptr,
png_bytep data, png_size_t length);
+
void user_write_data(png_structp png_ptr,
png_bytep data, png_size_t length);
+
void user_flush_data(png_structp png_ptr);
The user_read_data() function is responsible for detecting and
@@ -3756,6 +3926,7 @@
void user_error_fn(png_structp png_ptr,
png_const_charp error_msg);
+
void user_warning_fn(png_structp png_ptr,
png_const_charp warning_msg);
@@ -3866,8 +4037,10 @@
png_set_compression_strategy(png_ptr,
strategy);
+
png_set_compression_window_bits(png_ptr,
window_bits);
+
png_set_compression_method(png_ptr, method);
png_set_compression_buffer_size(png_ptr, size);
@@ -3957,6 +4130,8 @@
you can turn off individual capabilities with defines that begin with
PNG_NO_.
+In libpng-1.5.0 and later, the #define's are in pnglibconf.h instead.
+
You can also turn all of the transforms and ancillary chunk capabilities
off en masse with compiler directives that define
PNG_NO_READ[or WRITE]_TRANSFORMS, or PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS,
@@ -4009,8 +4184,8 @@
is expanded to
- if(PNG_DEBUG > 2)
- fprintf(PNG_DEBUG_FILE, "foo=%d\n", foo);
+ if (PNG_DEBUG > 2)
+ fprintf(PNG_DEBUG_FILE, "foo=%d\n", foo);
When PNG_DEBUG is defined but is zero, the macros aren't defined, but you
can still use PNG_DEBUG to control your own debugging:
@@ -4031,11 +4206,13 @@
png_permit_mng_features() function:
feature_set = png_permit_mng_features(png_ptr, mask)
+
mask is a png_uint_32 containing the bitwise OR of the
features you want to enable. These include
PNG_FLAG_MNG_EMPTY_PLTE
PNG_FLAG_MNG_FILTER_64
PNG_ALL_MNG_FEATURES
+
feature_set is a png_uint_32 that is the bitwise AND of
your mask with the set of MNG features that is
supported by the version of libpng that you are using.
@@ -4060,7 +4237,7 @@
The old libpng functions png_read_init(), png_write_init(),
png_info_init(), png_read_destroy(), and png_write_destroy() have been
moved to PNG_INTERNAL in version 0.95 to discourage their use. These
-functions will be removed from libpng version 2.0.0.
+functions will be removed from libpng version 1.4.0.
The preferred method of creating and initializing the libpng structures is
via the png_create_read_struct(), png_create_write_struct(), and
@@ -4296,7 +4473,8 @@
was reenabled, but the function was renamed png_set_quantize() to
reflect more accurately what it actually does. At the same time,
the PNG_DITHER_[RED,GREEN_BLUE]_BITS macros were also renamed to
-PNG_QUANTIZE_[RED,GREEN,BLUE]_BITS.
+PNG_QUANTIZE_[RED,GREEN,BLUE]_BITS, and PNG_READ_DITHER_SUPPORTED
+was renamed to PNG_READ_QUANTIZE_SUPPORTED.
We removed the trailing '.' from the warning and error messages.
@@ -4323,7 +4501,7 @@
header file (pngpriv.h) that is not accessible to applications.
In png_get_iCCP, the type of "profile" was changed from png_charpp
-to png_bytepp, and in png_set_iCCP, from png_charp to png_const_bytepp.
+to png_bytepp, and in png_set_iCCP, from png_charp to png_const_bytep.
There are changes of form in png.h, including new and changed macros to
declare
@@ -4438,8 +4616,8 @@
is used and operating system specific directives are defined in
pnglibconf.h
-As part of this the mechanism used to chose procedure call standards on those
-systems that allow a choice has been changed. At present this only
+As part of this the mechanism used to choose procedure call standards on
+those systems that allow a choice has been changed. At present this only
affects certain Microsoft (DOS, Windows) and IBM (OS/2) operating systems
running on Intel processors. As before PNGAPI is defined where required
to control the exported API functions; however, two new macros, PNGCBAPI
@@ -4457,7 +4635,7 @@
therefore set PNG_API_RULE to 2 should also contact the mailing list.
A new test program, pngvalid, is provided in addition to pngtest.
- pngvalid validates the arithmetic accuracy of the gamma correction
+pngvalid validates the arithmetic accuracy of the gamma correction
calculations and includes a number of validations of the file format.
A subset of the full range of tests is run when "make check" is done
(in the 'configure' build.) pngvalid also allows total allocated memory
@@ -4540,8 +4718,8 @@
These mechanisms still work in the configure build and in any makefile
build that builds pnglibconf.h although the feature selection macros
-have changed somewhat as described above. In 1.5.0, however, pngusr.h
-is processed once when the exported header file pnglibconf.h is built.
+have changed somewhat as described above. In 1.5.0, however, pngusr.h is
+processed only once, when the exported header file pnglibconf.h is built.
pngconf.h no longer includes pngusr.h, therefore it is ignored after the
build of pnglibconf.h and it is never included in an application build.
@@ -4596,6 +4774,11 @@
http://libpng.sourceforge.net
+We also accept patches built from the tar or zip distributions, and
+simple verbal discriptions of bug fixes, reported either to the
+SourceForge bug tracker or to the png-mng-implement at lists.sf.net
+mailing list.
+
.SH XIII. Coding style
Our coding style is similar to the "Allman" style, with curly
@@ -4706,13 +4889,13 @@
.SH XIV. Y2K Compliance in libpng
-January 21, 2011
+January 22, 2011
Since the PNG Development group is an ad-hoc body, we can't make
an official declaration.
This is your unofficial assurance that libpng from version 0.71 and
-upward through 1.5.1rc01 are Y2K compliant. It is my belief that earlier
+upward through 1.5.1beta07 are Y2K compliant. It is my belief that earlier
versions were also Y2K compliant.
Libpng only has three year fields. One is a 2-byte unsigned integer that
@@ -4952,7 +5135,7 @@
Thanks to Frank J. T. Wojcik for helping with the documentation.
-Libpng version 1.5.1rc01 - January 21, 2011:
+Libpng version 1.5.1beta07 - January 22, 2011:
Initially created in 1995 by Guy Eric Schalnat, then of Group 42, Inc.
Currently maintained by Glenn Randers-Pehrson (glennrp at users.sourceforge.net).
@@ -4975,7 +5158,7 @@
This code is released under the libpng license.
-libpng versions 1.2.6, August 15, 2004, through 1.5.1rc01, January 21, 2011, are
+libpng versions 1.2.6, August 15, 2004, through 1.5.1beta07, January 22, 2011, are
Copyright (c) 2004,2006-2007 Glenn Randers-Pehrson, and are
distributed according to the same disclaimer and license as libpng-1.2.5
with the following individual added to the list of Contributing Authors
@@ -5074,7 +5257,7 @@
Glenn Randers-Pehrson
glennrp at users.sourceforge.net
-January 21, 2011
+January 22, 2011
.\" end of man page
