Name
  doc:LoadPNGImage -- load external PNG image
Synopsis

      img = doc:LoadPNGImage(filename[, cache])

Function
  `doc:LoadPNGImage()` loads an external PNG image file. The optional `cache` argument allows you to set whether this method should cache the whole PNG image in memory or not. If you need to embed a PNG image several times, it is faster to set this argument to `True`.

  Note that when embedding PNG images in a PDF, they are not embedded in PNG format but as raw, uncompressed pixels (although you can activate compression for the pixel data by calling doc:SetCompressionMode()). The only image format which can be embedded directly inside PDF documents is JPEG. Use doc:LoadJPEGImage() to load a JPEG image for embedding in a PDF.

  When `doc:LoadPNGImage()` succeeds, it returns the handle of an image object. Otherwise, it returns `Nil` and the error handler is called.

Inputs
  filename
    path to a PNG image file
  cache
    optional: whether caching should be enabled (defaults to `False`)
Results
  img
    handle to an image
Errors
  `#HPDF_INVALID_DOCUMENT` - An invalid document handle was set.

  `#HPDF_FAILED_TO_ALLOC_MEM` - Memory allocation failed.

  `#HPDF_UNSUPPORTED_FUNC` - The library is not configured to use PNGLIB.

  `#HPDF_LIBPNG_ERROR` - Failed when invoking PNGLIB's function.

  `#HPDF_INVALID_PNG_IMAGE` - Invalid PNG format.

Show TOC