cheng/libpng
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[libpng16] Fixed some editing cruft in libpng-manual.txt and libpng.3

Browse Source
This commit is contained in:
Glenn Randers-Pehrson 2012-02-03 21:14:33 -06:00
parent 3449169622
commit 612d52afce
2 changed files with 88 additions and 224 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

140
libpng-manual.txt
View File

@ -1,6 +1,6 @@
libpng-manual.txt - A description on how to use and modify libpng libpng-manual.txt - A description on how to use and modify libpng
libpng version 1.6.0beta11 - February 3, 2012 libpng version 1.6.0beta11 - February 4, 2012
Updated and distributed by Glenn Randers-Pehrson Updated and distributed by Glenn Randers-Pehrson
<glennrp at users.sourceforge.net> <glennrp at users.sourceforge.net>
Copyright (c) 1998-2011 Glenn Randers-Pehrson Copyright (c) 1998-2011 Glenn Randers-Pehrson
@ -11,7 +11,7 @@ libpng-manual.txt - A description on how to use and modify libpng
Based on: Based on:
libpng versions 0.97, January 1998, through 1.6.0beta11 - February 3, 2012 libpng versions 0.97, January 1998, through 1.6.0beta11 - February 4, 2012
Updated and distributed by Glenn Randers-Pehrson Updated and distributed by Glenn Randers-Pehrson
Copyright (c) 1998-2011 Glenn Randers-Pehrson Copyright (c) 1998-2011 Glenn Randers-Pehrson
@ -3662,119 +3662,52 @@ First the information about the samples.
Returns the size in bytes of a single component of a pixel or color-map Returns the size in bytes of a single component of a pixel or color-map
entry (as appropriate) in the image. entry (as appropriate) in the image.
PNG_IMAGE_SAMPLE_SIZE(fmt)
This is the size of the sample data for one sample. If the image is
color-mapped it is the size of one color-map entry (and image pixels are
one byte in size), otherwise it is the size of one image pixel.
+ PNG_IMAGE_COLORMAP_SIZE(fmt)
+#define PNG_IMAGE_SAMPLE_SIZE(fmt)\ The size of the color-map required by the format; this is the size of the
+ (PNG_IMAGE_SAMPLE_CHANNELS(fmt) * PNG_IMAGE_SAMPLE_COMPONENT_SIZE(fmt)) color-map buffer passed to the png_image_{read,write}_colormap APIs, it is
+ /* This is the size of the sample data for one sample. If the image is a fixed number determined by the format so can easily be allocated on the
+ * color-mapped it is the size of one color-map entry (and image pixels are stack if necessary.
+ * one byte in size), otherwise it is the size of one image pixel.
+ */
+
+#define PNG_IMAGE_COLORMAP_SIZE(fmt) (PNG_IMAGE_SAMPLE_SIZE(format) * 256)
+ /* The size of the color-map required by the format; this is the size of the
+ * color-map buffer passed to the png_image_{read,write}_colormap APIs, it is
+ * a fixed number determined by the format so can easily be allocated on the
+ * stack if necessary.
+ */
+
+/* Corresponding information about the pixels */
+#define PNG_IMAGE_PIXEL_(test,fmt)\
+ (((fmt)&PNG_FORMAT_FLAG_COLORMAP)?1:test(fmt))
+
+#define PNG_IMAGE_PIXEL_CHANNELS(fmt)\
+ PNG_IMAGE_PIXEL_(PNG_IMAGE_SAMPLE_CHANNELS,fmt)
+ /* The number of separate channels (components) in a pixel; 1 for a
+ * color-mapped image.
+ */
+
+#define PNG_IMAGE_PIXEL_COMPONENT_SIZE(fmt)\
+ PNG_IMAGE_PIXEL_(PNG_IMAGE_SAMPLE_COMPONENT_SIZE,fmt)
+ /* The size, in bytes, of each component in a pixel; 1 for a color-mapped
+ * image.
+ */
-#define PNG_IMAGE_PIXEL_SIZE(fmt)\
- (PNG_IMAGE_CHANNELS(fmt) * PNG_IMAGE_COMPONENT_SIZE(fmt))
- /* Return the size in bytes of a single pixel in the image. */
-
+#define PNG_IMAGE_PIXEL_SIZE(fmt) PNG_IMAGE_PIXEL_(PNG_IMAGE_SAMPLE_SIZE,fmt)
+ /* The size, in bytes, of a complete pixel; 1 for a color-mapped image. */
+
+/* Information about the whole row, or whole image */
#define PNG_IMAGE_ROW_STRIDE(image)\
- (PNG_IMAGE_CHANNELS((image).format) * (image).width)
+ (PNG_IMAGE_PIXEL_CHANNELS((image).format) * (image).width)
/* Return the total number of components in a single row of the image; this
* is the minimum 'row stride', the minimum count of components between each
+ * row. For a color-mapped image this is the minimum number of bytes in a
* row.
*/
#define PNG_IMAGE_BUFFER_SIZE(image, row_stride)\
- (PNG_IMAGE_COMPONENT_SIZE((image).format) * (image).height * (row_stride))
+ (PNG_IMAGE_PIXEL_COMPONENT_SIZE((image).format)*(image).height*(row_stride))
/* Return the size, in bytes, of an image buffer given a png_image and a row
* stride - the number of components to leave space for in each row.
*/
@@ -2815,17 +2903,24 @@ typedef struct
* Flags containing additional information about the image are held in the
* 'flags' field of png_image.
*/
-#define PNG_IMAGE_FLAG_COLORSPACE_NOT_sRGB 1
+#define PNG_IMAGE_FLAG_COLORSPACE_NOT_sRGB 0x01
/* This indicates the the RGB values of the in-memory bitmap do not
* correspond to the red, green and blue end-points defined by sRGB.
*/
+#define PNG_IMAGE_FLAG_COLORMAP 0x02
+ /* The PNG is color-mapped. If this flag is set png_image_read_colormap
+ * can be used without further loss of image information. If it is not set
+ * png_image_read_colormap will cause significant loss if the image has any
+ * colors (if PNG_FORMAT_FLAG_COLOR is set).
+ */
+
#ifdef PNG_SIMPLIFIED_READ_SUPPORTED
/* READ APIs
* ---------
*
* The png_image passed to the read APIs must have been initialized by setting
- * the png_controlp field 'opaque' to NULL (or, better, memset the whole thing.)
+ * the png_controlp field 'opaque' to NULL (or, safer, memset the whole thing.)
*/
Corresponding information about the pixels
PNG_IMAGE_PIXEL_(test,fmt)
PNG_IMAGE_PIXEL_CHANNELS(fmt)
The number of separate channels (components) in a pixel; 1 for a
color-mapped image.
PNG_IMAGE_PIXEL_COMPONENT_SIZE(fmt)\
The size, in bytes, of each component in a pixel; 1 for a color-mapped
image.
PNG_IMAGE_PIXEL_SIZE(fmt) PNG_IMAGE_PIXEL_SIZE(fmt)
Returns the size in bytes of a single pixel in the image. The size, in bytes, of a complete pixel; 1 for a color-mapped image.
Information about the whole row, or whole image
PNG_IMAGE_ROW_STRIDE(image) PNG_IMAGE_ROW_STRIDE(image)
Returns the total number of components in a single row Returns the total number of components in a single row of the image; this
of the image; this is the minimum 'row stride', the minimum is the minimum 'row stride', the minimum count of components between each
count of components between each row. row. For a color-mapped image this is the minimum number of bytes in a
row.
PNG_IMAGE_BUFFER_SIZE(image, row_stride) PNG_IMAGE_BUFFER_SIZE(image, row_stride)
Returns the size, in bytes, of an image buffer given Returns the size, in bytes, of an image buffer given a png_image and a row
a png_image and a row stride - the number of components to stride - the number of components to leave space for in each row.
leave space for in each row.
PNG_IMAGE_SIZE(image) PNG_IMAGE_FLAG_COLORSPACE_NOT_sRGB == 0x01
Returns the size, in bytes, of the image in memory given This indicates the the RGB values of the in-memory bitmap do not
just a png_image; the row stride is the minimum stride correspond to the red, green and blue end-points defined by sRGB.
required for the image.
PNG_IMAGE_FLAG_ PNG_IMAGE_FLAG_COLORMAP == 0x02
The PNG is color-mapped. If this flag is set png_image_read_colormap
Flags containing additional information about the image are held can be used without further loss of image information. If it is not set
in the 'flags' field of png_image. png_image_read_colormap will cause significant loss if the image has any
PNG_IMAGE_FLAG_COLORSPACE_NOT_sRGB
This indicates the the RGB values of the in-memory
bitmap do not correspond to the red, green and blue
end-points defined by sRGB.
READ APIs READ APIs
@ -3787,7 +3720,6 @@ READ APIs
The named file is opened for read and the image header The named file is opened for read and the image header
is filled in from the PNG header in the file. is filled in from the PNG header in the file.
int png_image_begin_read_from_stdio (png_imagep image, int png_image_begin_read_from_stdio (png_imagep image,
FILE* file) FILE* file)
@ -5043,7 +4975,7 @@ Other rules can be inferred by inspecting the libpng source.
XVI. Y2K Compliance in libpng XVI. Y2K Compliance in libpng
February 3, 2012 February 4, 2012
Since the PNG Development group is an ad-hoc body, we can't make Since the PNG Development group is an ad-hoc body, we can't make
an official declaration. an official declaration.

148
libpng.3
View File

@ -1,4 +1,4 @@
.TH LIBPNG 3 "February 3, 2012" .TH LIBPNG 3 "February 4, 2012"
.SH NAME .SH NAME
libpng \- Portable Network Graphics (PNG) Reference Library 1.6.0beta11 libpng \- Portable Network Graphics (PNG) Reference Library 1.6.0beta11
.SH SYNOPSIS .SH SYNOPSIS
@ -1003,7 +1003,7 @@ Following is a copy of the libpng-manual.txt file that accompanies libpng.
.SH LIBPNG.TXT .SH LIBPNG.TXT
libpng-manual.txt - A description on how to use and modify libpng libpng-manual.txt - A description on how to use and modify libpng
libpng version 1.6.0beta11 - February 3, 2012 libpng version 1.6.0beta11 - February 4, 2012
Updated and distributed by Glenn Randers-Pehrson Updated and distributed by Glenn Randers-Pehrson
<glennrp at users.sourceforge.net> <glennrp at users.sourceforge.net>
Copyright (c) 1998-2011 Glenn Randers-Pehrson Copyright (c) 1998-2011 Glenn Randers-Pehrson
@ -1014,7 +1014,7 @@ libpng-manual.txt - A description on how to use and modify libpng
Based on: Based on:
libpng versions 0.97, January 1998, through 1.6.0beta11 - February 3, 2012 libpng versions 0.97, January 1998, through 1.6.0beta11 - February 4, 2012
Updated and distributed by Glenn Randers-Pehrson Updated and distributed by Glenn Randers-Pehrson
Copyright (c) 1998-2011 Glenn Randers-Pehrson Copyright (c) 1998-2011 Glenn Randers-Pehrson
@ -4665,119 +4665,52 @@ First the information about the samples.
Returns the size in bytes of a single component of a pixel or color-map Returns the size in bytes of a single component of a pixel or color-map
entry (as appropriate) in the image. entry (as appropriate) in the image.
PNG_IMAGE_SAMPLE_SIZE(fmt)
This is the size of the sample data for one sample. If the image is
color-mapped it is the size of one color-map entry (and image pixels are
one byte in size), otherwise it is the size of one image pixel.
+ PNG_IMAGE_COLORMAP_SIZE(fmt)
+#define PNG_IMAGE_SAMPLE_SIZE(fmt)\ The size of the color-map required by the format; this is the size of the
+ (PNG_IMAGE_SAMPLE_CHANNELS(fmt) * PNG_IMAGE_SAMPLE_COMPONENT_SIZE(fmt)) color-map buffer passed to the png_image_{read,write}_colormap APIs, it is
+ /* This is the size of the sample data for one sample. If the image is a fixed number determined by the format so can easily be allocated on the
+ * color-mapped it is the size of one color-map entry (and image pixels are stack if necessary.
+ * one byte in size), otherwise it is the size of one image pixel.
+ */
+
+#define PNG_IMAGE_COLORMAP_SIZE(fmt) (PNG_IMAGE_SAMPLE_SIZE(format) * 256)
+ /* The size of the color-map required by the format; this is the size of the
+ * color-map buffer passed to the png_image_{read,write}_colormap APIs, it is
+ * a fixed number determined by the format so can easily be allocated on the
+ * stack if necessary.
+ */
+
+/* Corresponding information about the pixels */
+#define PNG_IMAGE_PIXEL_(test,fmt)\
+ (((fmt)&PNG_FORMAT_FLAG_COLORMAP)?1:test(fmt))
+
+#define PNG_IMAGE_PIXEL_CHANNELS(fmt)\
+ PNG_IMAGE_PIXEL_(PNG_IMAGE_SAMPLE_CHANNELS,fmt)
+ /* The number of separate channels (components) in a pixel; 1 for a
+ * color-mapped image.
+ */
+
+#define PNG_IMAGE_PIXEL_COMPONENT_SIZE(fmt)\
+ PNG_IMAGE_PIXEL_(PNG_IMAGE_SAMPLE_COMPONENT_SIZE,fmt)
+ /* The size, in bytes, of each component in a pixel; 1 for a color-mapped
+ * image.
+ */
-#define PNG_IMAGE_PIXEL_SIZE(fmt)\
- (PNG_IMAGE_CHANNELS(fmt) * PNG_IMAGE_COMPONENT_SIZE(fmt))
- /* Return the size in bytes of a single pixel in the image. */
-
+#define PNG_IMAGE_PIXEL_SIZE(fmt) PNG_IMAGE_PIXEL_(PNG_IMAGE_SAMPLE_SIZE,fmt)
+ /* The size, in bytes, of a complete pixel; 1 for a color-mapped image. */
+
+/* Information about the whole row, or whole image */
#define PNG_IMAGE_ROW_STRIDE(image)\
- (PNG_IMAGE_CHANNELS((image).format) * (image).width)
+ (PNG_IMAGE_PIXEL_CHANNELS((image).format) * (image).width)
/* Return the total number of components in a single row of the image; this
* is the minimum 'row stride', the minimum count of components between each
+ * row. For a color-mapped image this is the minimum number of bytes in a
* row.
*/
#define PNG_IMAGE_BUFFER_SIZE(image, row_stride)\
- (PNG_IMAGE_COMPONENT_SIZE((image).format) * (image).height * (row_stride))
+ (PNG_IMAGE_PIXEL_COMPONENT_SIZE((image).format)*(image).height*(row_stride))
/* Return the size, in bytes, of an image buffer given a png_image and a row
* stride - the number of components to leave space for in each row.
*/
@@ -2815,17 +2903,24 @@ typedef struct
* Flags containing additional information about the image are held in the
* 'flags' field of png_image.
*/
-#define PNG_IMAGE_FLAG_COLORSPACE_NOT_sRGB 1
+#define PNG_IMAGE_FLAG_COLORSPACE_NOT_sRGB 0x01
/* This indicates the the RGB values of the in-memory bitmap do not
* correspond to the red, green and blue end-points defined by sRGB.
*/
+#define PNG_IMAGE_FLAG_COLORMAP 0x02
+ /* The PNG is color-mapped. If this flag is set png_image_read_colormap
+ * can be used without further loss of image information. If it is not set
+ * png_image_read_colormap will cause significant loss if the image has any
+ * colors (if PNG_FORMAT_FLAG_COLOR is set).
+ */
+
#ifdef PNG_SIMPLIFIED_READ_SUPPORTED
/* READ APIs
* ---------
*
* The png_image passed to the read APIs must have been initialized by setting
- * the png_controlp field 'opaque' to NULL (or, better, memset the whole thing.)
+ * the png_controlp field 'opaque' to NULL (or, safer, memset the whole thing.)
*/
Corresponding information about the pixels
PNG_IMAGE_PIXEL_(test,fmt)
PNG_IMAGE_PIXEL_CHANNELS(fmt)
The number of separate channels (components) in a pixel; 1 for a
color-mapped image.
PNG_IMAGE_PIXEL_COMPONENT_SIZE(fmt)\
The size, in bytes, of each component in a pixel; 1 for a color-mapped
image.
PNG_IMAGE_PIXEL_SIZE(fmt) PNG_IMAGE_PIXEL_SIZE(fmt)
Returns the size in bytes of a single pixel in the image. The size, in bytes, of a complete pixel; 1 for a color-mapped image.
Information about the whole row, or whole image
PNG_IMAGE_ROW_STRIDE(image) PNG_IMAGE_ROW_STRIDE(image)
Returns the total number of components in a single row Returns the total number of components in a single row of the image; this
of the image; this is the minimum 'row stride', the minimum is the minimum 'row stride', the minimum count of components between each
count of components between each row. row. For a color-mapped image this is the minimum number of bytes in a
row.
PNG_IMAGE_BUFFER_SIZE(image, row_stride) PNG_IMAGE_BUFFER_SIZE(image, row_stride)
Returns the size, in bytes, of an image buffer given Returns the size, in bytes, of an image buffer given a png_image and a row
a png_image and a row stride - the number of components to stride - the number of components to leave space for in each row.
leave space for in each row.
PNG_IMAGE_SIZE(image) PNG_IMAGE_FLAG_COLORSPACE_NOT_sRGB == 0x01
Returns the size, in bytes, of the image in memory given This indicates the the RGB values of the in-memory bitmap do not
just a png_image; the row stride is the minimum stride correspond to the red, green and blue end-points defined by sRGB.
required for the image.
PNG_IMAGE_FLAG_ PNG_IMAGE_FLAG_COLORMAP == 0x02
The PNG is color-mapped. If this flag is set png_image_read_colormap
Flags containing additional information about the image are held can be used without further loss of image information. If it is not set
in the 'flags' field of png_image. png_image_read_colormap will cause significant loss if the image has any
PNG_IMAGE_FLAG_COLORSPACE_NOT_sRGB
This indicates the the RGB values of the in-memory
bitmap do not correspond to the red, green and blue
end-points defined by sRGB.
READ APIs READ APIs
@ -4790,7 +4723,6 @@ READ APIs
The named file is opened for read and the image header The named file is opened for read and the image header
is filled in from the PNG header in the file. is filled in from the PNG header in the file.
int png_image_begin_read_from_stdio (png_imagep image, int png_image_begin_read_from_stdio (png_imagep image,
FILE* file) FILE* file)
@ -6047,7 +5979,7 @@ Other rules can be inferred by inspecting the libpng source.
.SH XVI. Y2K Compliance in libpng .SH XVI. Y2K Compliance in libpng
February 3, 2012 February 4, 2012
Since the PNG Development group is an ad-hoc body, we can't make Since the PNG Development group is an ad-hoc body, we can't make
an official declaration. an official declaration.
@ -6315,7 +6247,7 @@ possible without all of you.
Thanks to Frank J. T. Wojcik for helping with the documentation. Thanks to Frank J. T. Wojcik for helping with the documentation.
Libpng version 1.6.0beta11 - February 3, 2012: Libpng version 1.6.0beta11 - February 4, 2012:
Initially created in 1995 by Guy Eric Schalnat, then of Group 42, Inc. Initially created in 1995 by Guy Eric Schalnat, then of Group 42, Inc.
Currently maintained by Glenn Randers-Pehrson (glennrp at users.sourceforge.net). Currently maintained by Glenn Randers-Pehrson (glennrp at users.sourceforge.net).
@ -6338,7 +6270,7 @@ this sentence.
This code is released under the libpng license. This code is released under the libpng license.
libpng versions 1.2.6, August 15, 2004, through 1.6.0beta11, February 3, 2012, are libpng versions 1.2.6, August 15, 2004, through 1.6.0beta11, February 4, 2012, are
Copyright (c) 2004,2006-2007 Glenn Randers-Pehrson, and are Copyright (c) 2004,2006-2007 Glenn Randers-Pehrson, and are
distributed according to the same disclaimer and license as libpng-1.2.5 distributed according to the same disclaimer and license as libpng-1.2.5
with the following individual added to the list of Contributing Authors with the following individual added to the list of Contributing Authors
@ -6437,7 +6369,7 @@ certification mark of the Open Source Initiative.
Glenn Randers-Pehrson Glenn Randers-Pehrson
glennrp at users.sourceforge.net glennrp at users.sourceforge.net
February 3, 2012 February 4, 2012
.\" end of man page .\" end of man page