[libpng15] Simplified read/write API initial version; basic read/write tested

on a variety of images, limited documentation (in the header file.)

1 files changed, 277 insertions, 6 deletions

diff --git a/png.h b/png.h
index 9852f7224..922fe16b3 100644
--- a/png.h
+++ b/png.h
@@ -1,7 +1,7 @@
 
 /* png.h - header file for PNG reference library
  *
- * libpng version 1.5.7beta02 - November 5, 2011
+ * libpng version 1.5.7beta02 - November 8, 2011
  * Copyright (c) 1998-2011 Glenn Randers-Pehrson
  * (Version 0.96 Copyright (c) 1996, 1997 Andreas Dilger)
  * (Version 0.88 Copyright (c) 1995, 1996 Guy Eric Schalnat, Group 42, Inc.)
@@ -11,7 +11,7 @@
  * Authors and maintainers:
  *   libpng versions 0.71, May 1995, through 0.88, January 1996: Guy Schalnat
  *   libpng versions 0.89c, June 1996, through 0.96, May 1997: Andreas Dilger
- *   libpng versions 0.97, January 1998, through 1.5.7beta02 - November 5, 2011: Glenn
+ *   libpng versions 0.97, January 1998, through 1.5.7beta02 - November 8, 2011: Glenn
  *   See also "Contributing Authors", below.
  *
  * Note about libpng version numbers:
@@ -195,7 +195,7 @@
  *
  * This code is released under the libpng license.
  *
- * libpng versions 1.2.6, August 15, 2004, through 1.5.7beta02, November 5, 2011, are
+ * libpng versions 1.2.6, August 15, 2004, through 1.5.7beta02, November 8, 2011, are
  * Copyright (c) 2004, 2006-2011 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:
@@ -307,7 +307,7 @@
  * Y2K compliance in libpng:
  * =========================
  *
- *    November 5, 2011
+ *    November 8, 2011
  *
  *    Since the PNG Development group is an ad-hoc body, we can't make
  *    an official declaration.
@@ -365,12 +365,15 @@
  * describes how to use libpng, and the file example.c summarizes it
  * with some code on which to build.  This file is useful for looking
  * at the actual function definitions and structure components.
+ *
+ * If you just need to read a PNG file and don't want to read the documentation
+ * skip to the end of this file and read the section entitled 'simplified API'.
  */
 
 /* Version information for png.h - this should match the version in png.c */
 #define PNG_LIBPNG_VER_STRING "1.5.7beta02"
 #define PNG_HEADER_VERSION_STRING \
-     " libpng version 1.5.7beta02 - November 5, 2011\n"
+     " libpng version 1.5.7beta02 - November 8, 2011\n"
 
 #define PNG_LIBPNG_VER_SONUM   15
 #define PNG_LIBPNG_VER_DLLNUM  15
@@ -488,6 +491,7 @@ extern "C" {
  * 2. Type definitions (base types are defined in pngconf.h), structure
  *    definitions.
  * 3. Exported library functions.
+ * 4. Simplified API.
  *
  * The library source code has additional files (principally pngpriv.h) that
  * allow configuration of the library.
@@ -1124,6 +1128,11 @@ PNG_EXPORT(31, void, png_set_gray_to_rgb, (png_structp png_ptr));
 
 #ifdef PNG_READ_RGB_TO_GRAY_SUPPORTED
 /* Reduce RGB to grayscale. */
+#define PNG_ERROR_ACTION_NONE  1
+#define PNG_ERROR_ACTION_WARN  2
+#define PNG_ERROR_ACTION_ERROR 3
+#define PNG_RGB_TO_GRAY_DEFAULT (-1)/*for red/green coefficients*/
+
 PNG_FP_EXPORT(32, void, png_set_rgb_to_gray, (png_structp png_ptr,
     int error_action, double red, double green));
 PNG_FIXED_EXPORT(33, void, png_set_rgb_to_gray_fixed, (png_structp png_ptr,
@@ -2611,6 +2620,268 @@ PNG_EXPORT(207, void, png_save_uint_16, (png_bytep buf, unsigned int i));
       : (png_int_32)png_get_uint_32(buf)))
 #endif
 
+/*******************************************************************************
+ *  SIMPLIFIED API
+ ******************************************************************************/
+/*
+ * Please read the documentation in libpng-manual.txt if you don't understand
+ * what follows.
+ *
+ * The simplified API hides the details of both libpng and the PNG file format
+ * itself.  It allows PNG files to be read into a very limited number of
+ * in-memory bitmap formats or to be written from the same formats.  If these
+ * formats do not accomodate your needs then you can, and should, use the more
+ * sophisticated APIs above - these support a wide variety of in-memory formats
+ * and a wide variety of sophisticated transformations to those formats as well
+ * as a wide variety of APIs to manipulate ancilliary information.
+ *
+ * To read a PNG file using the simplified API:
+ *
+ * 1) Declare a 'png_image' structure (see below) on the stack and memset() it
+ * to all zero.
+ * 2) Call the appropriate png_image_begin_read... function.
+ * 3) Set the png_image 'format' member to the required format and allocate a
+ * buffer for the image.
+ * 4) Call png_image_finish_read to read the image into your buffer.
+ *
+ * To write a PNG file using the simplified API:
+ *
+ * 1) Declare a 'png_image' structure on the stack and memset() it to all zero.
+ * 2) Initialize the members of the structure that describe the image, setting
+ * the 'format' member to the format of the image in memory.
+ * 3) Call the appropriate png_image_write... function with a pointer to the
+ * image to write the PNG data.
+ *
+ * png_image is a structure that describes the in-memory formant of an image
+ * when it is being read or define the in-memory format of an image that you
+ * need to write:
+ */
+typedef struct png_control *png_controlp;
+typedef struct
+{
+   png_uint_32  width;  /* Image width in pixels (columns) */
+   png_uint_32  height; /* Image height in pixels (rows) */
+   png_uint_32  format; /* Image format as defined below */
+   png_uint_32  flags;  /* A bit mask containing informational flags */
+   png_controlp opaque; /* Initialize to NULL, free with png_image_free */
+
+   /* In the event of an error or warning the following field will be set to a
+    * non-zero value and the 'message' field will contain a '\0' terminated
+    * string with the libpng error message.
+    */
+   png_uint_32  warning_or_error;
+   char         message[64];
+} png_image, *png_imagep;
+
+/* The pixels (samples) of the image have one to four channels in the range 0 to
+ * 1.0:
+ *
+ * 1: A single gray or luminance channel (G).
+ * 2: A gray/luminance channel and an alpha channel (GA).
+ * 3: Three red, green, blue color channels (RGB).
+ * 4: Three color channels and an alpha channel (RGBA).
+ *
+ * The channels are encoded in one of two ways:
+ *
+ * a) As a small integer, value 0..255, contained in a (png_byte).  For the
+ * alpha channel the original value is simple value/255.  For the color or
+ * luminance channels the value is encoded according to the sRGB specification
+ * and matches the 8-bit format expected by typical display devices.
+ *
+ *    The color/gray channels are not scaled (pre-multiplied) by the alpha
+ * channel and are suitable for passing to color management software.
+ *
+ * b) As a value in the range 0..65535, contained in a (png_uint_16).  All
+ * channels can be converted to the original value by dividing by 65535; all
+ * channels are linear.  Color channels use the RGB encoding (RGB end-points) of
+ * the sRGB specification.  This encoding is identified by the
+ * PNG_FORMAT_FLAG_LINEAR flag below.
+ *
+ *    When an alpha channel is present it is expected to denote pixel coverage
+ * of the color or luminance channels and is returned as an associated alpha
+ * channel: the color/gray channels are scaled (pre-multiplied) the alpha value.
+ */
+
+/* PNG_FORMAT_*
+ *
+ * #defines to be used in png_image::format.  Each #define identifies a
+ * particular layout of channel data and, if present, alpha values.  There are
+ * separate defines for each of the two channel encodings.
+ *
+ * A format is built up using single bit flag values.  Not all combinations are
+ * valid: use the bit flag values below for testing a format returned by the
+ * read APIs, but set formats from the derived values.
+ *
+ * NOTE: libpng can be built with particular features disabled, if you see
+ * compiler errors because the definition of one of the following flags has been
+ * compiled out it is because libpng does not have the required support.  It is
+ * possible, however, for the libpng configuration to enable the format on just
+ * read or just write, in that case you will may see an error at run time.  You
+ * can guard against this by checking for the definition of:
+ *
+ *    PNG_SIMPLIFIED_{READ,WRITE}_{BGR,AFIRST}_SUPPORTED
+ */
+#define PNG_FORMAT_FLAG_ALPHA    0x01 /* format with an alpha channel */
+#define PNG_FORMAT_FLAG_COLOR    0x02 /* color format: otherwise grayscale */
+#define PNG_FORMAT_FLAG_LINEAR   0x04 /* png_uint_16 channels else png_byte */
+
+#ifdef PNG_FORMAT_BGR_SUPPORTED
+#  define PNG_FORMAT_FLAG_BGR    0x08 /* BGR colors, else order is RGB */
+#endif
+
+#ifdef PNG_FORMAT_AFIRST_SUPPORTED
+#  define PNG_FORMAT_FLAG_AFIRST 0x10 /* alpha channel comes first */
+#endif
+
+/* Supported formats are as follows.  Future versions of libpng may support more
+ * formats, for compatibility with older versions simply check if the format
+ * macro is defined using #ifdef.  These defines describe the in-memory layout
+ * of the components of the pixels of the image.
+ *
+ * First the single byte formats:
+ */
+#define PNG_FORMAT_GRAY 0
+#define PNG_FORMAT_GA   PNG_FORMAT_FLAG_ALPHA
+#define PNG_FORMAT_AG   (PNG_FORMAT_GA|PNG_FORMAT_AFIRST)
+#define PNG_FORMAT_RGB  PNG_FORMAT_FLAG_COLOR
+#define PNG_FORMAT_BGR  (PNG_FORMAT_FLAG_COLOR|PNG_FORMAT_FLAG_BGR)
+#define PNG_FORMAT_RGBA (PNG_FORMAT_RGB|PNG_FORMAT_FLAG_ALPHA)
+#define PNG_FORMAT_ARGB (PNG_FORMAT_RGBA|PNG_FORMAT_FLAG_AFIRST)
+#define PNG_FORMAT_BGRA (PNG_FORMAT_BGR|PNG_FORMAT_FLAG_ALPHA)
+#define PNG_FORMAT_ABGR (PNG_FORMAT_BGRA|PNG_FORMAT_FLAG_AFIRST)
+
+/* Then the linear (png_uint_16) formats.  When naming these "Y" is used to
+ * indicate a luminance channel.  The component order within the pixel is
+ * always the same - there is no provision for swapping the order of the
+ * components in the linear format.
+ */
+#define PNG_FORMAT_FP_Y PNG_FORMAT_FLAG_FP
+#define PNG_FORMAT_FP_Y_ALPHA (PNG_FORMAT_FLAG_FP|PNG_FORMAT_FLAG_ALPHA)
+#define PNG_FORMAT_FP_RGB (PNG_FORMAT_FLAG_FP|PNG_FORMAT_FLAG_COLOR)
+#define PNG_FORMAT_FP_RGB_ALPHA \
+   (PNG_FORMAT_FLAG_FP|PNG_FORMAT_FLAG_COLOR|PNG_FORMAT_FLAG_ALPHA)
+
+/* PNG_IMAGE macros
+ *
+ * These are convenience macros to derive information from a png_image structure
+ */
+#define PNG_IMAGE_CHANNELS(fmt)\
+   (1+((fmt)&(PNG_FORMAT_FLAG_COLOR|PNG_FORMAT_FLAG_ALPHA)))
+   /* Return the total number of channels in a given format: 1..4 */
+
+#define PNG_IMAGE_COMPONENT_SIZE(fmt)\
+   (((fmt) & PNG_FORMAT_FLAG_LINEAR) ? sizeof (png_uint_16) : sizeof (png_byte))
+   /* Return the size in bytes of a single component of a pixel in the 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_ROW_STRIDE(image)\
+   (PNG_IMAGE_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.  */
+
+#define PNG_IMAGE_BUFFER_SIZE(image, row_stride)\
+   (PNG_IMAGE_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. */
+
+/* PNG_IMAGE_FLAG_*
+ *
+ * Flags containing additional information about the image are held in the
+ * 'flags' field of png_image.
+ */
+#define PNG_IMAGE_FLAG_COLORSPACE_NOT_sRGB 1
+   /* 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.
+    */
+
+#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.)
+ */
+#ifdef PNG_STDIO_SUPPORTED
+PNG_EXPORT(234, int, png_image_begin_read_from_file, (png_imagep image,
+   const char *file_name));
+   /* The named file is opened for read and the image filled in from the PNG
+    * header in the file. */
+
+PNG_EXPORT(235, int, png_image_begin_read_from_stdio, (png_imagep image,
+   FILE* file));
+   /* The PNG header is read from the stdio FILE object. */
+#endif /* PNG_STDIO_SUPPORTED */
+
+PNG_EXPORT(236, int, png_image_begin_read_from_memory, (png_imagep image,
+   png_const_voidp memory, png_size_t size));
+   /* The PNG header is read from the given memory buffer. */
+
+PNG_EXPORT(237, int, png_image_finish_read, (png_imagep image,
+   png_colorp background, void *buffer, png_int_32 row_stride));
+   /* Finish reading the image into the supplied buffer and clean up the
+    * png_image structure.
+    *
+    * row_stride is the step, in png_byte or float units as appropriate,
+    * between adjacent rows.  A positive stride indicates that the top-most row
+    * is first in the buffer - the normal top-down arrangement.  A negative
+    * stride indicates that the bottom-most row is first in the buffer.
+    *
+    * background need only be supplied if an alpha channel must be removed from
+    * a png_byte format and the removal is to be done by compositing on a solid
+    * color; otherwise it may be NULL and any composition will be done directly
+    * onto the buffer.  The value is an sRGB color to use for the background,
+    * for grayscale output the green channel is used.
+    *
+    * For linear output removing an alpha channel is always done by compositing
+    * on black.
+    */
+
+PNG_EXPORT(238, void, png_image_free, (png_imagep image));
+   /* Free any data allocated by libpng in image->opaque, setting the pointer to
+    * NULL.  May be called at any time after the structure is initialized. */
+#endif /* PNG_SIMPLIFIED_READ_SUPPORTED */
+
+#ifdef PNG_SIMPLIFIED_WRITE_SUPPORTED
+/* WRITE APIS
+ * ----------
+ * For write you must initialize a png_image structure to describe the image to
+ * be written:
+ *
+ * opaque: must be initialized to NULL
+ * width: image width in pixels
+ * height: image height in rows
+ * format: the format of the data you wish to write
+ * flags: set to 0 unless one of the defined flags applies; set
+ *    PNG_IMAGE_FLAG_COLORSPACE_NOT_sRGB for color format images where the RGB
+ *    values do not correspond to the colors in sRGB.
+ */
+PNG_EXPORT(239, int, png_image_write_to_file, (png_imagep image,
+   const char *file, int convert_to_8bit, const void *buffer,
+   png_int_32 row_stride));
+   /* Write the image to the named file. */
+
+PNG_EXPORT(240, int, png_image_write_to_stdio, (png_imagep image, FILE *file,
+   int convert_to_8_bit, const void *buffer, png_int_32 row_stride));
+   /* Write the image to the given (FILE*). */
+
+/* With all write APIs if image is in one of the linear formats with
+ * (png_uint_16) data then setting convert_to_8_bit will cause the output to be
+ * a (png_byte) PNG gamma encoded according to the sRGB specification, otherwise
+ * a 16-bit linear encoded PNG file is written.
+ *
+ * With all APIs row_stride is handled as in the read APIs - it is the spacing
+ * from one row to the next in component sized units (float) and if negative
+ * indicates a bottom-up row layout in the buffer.
+ */
+#endif /* PNG_SIMPLIFIED_WRITE_SUPPORTED */
+/*******************************************************************************
+ *  END OF SIMPLIFIED API
+ ******************************************************************************/
+
 /* Maintainer: Put new public prototypes here ^, in libpng.3, and project
  * defs
  */
@@ -2620,7 +2891,7 @@ PNG_EXPORT(207, void, png_save_uint_16, (png_bytep buf, unsigned int i));
  * scripts/symbols.def as well.
  */
 #ifdef PNG_EXPORT_LAST_ORDINAL
-  PNG_EXPORT_LAST_ORDINAL(233);
+  PNG_EXPORT_LAST_ORDINAL(240);
 #endif
 
 #ifdef __cplusplus