libmng - Multiple-image Network Graphics (MNG) Reference Library 1.0.9

DESCRIPTION

The libmng library supports decoding, displaying, encoding, and various

other manipulations of the Multiple-image Network Graphics (MNG) format

image files. It uses the zlib compression library, and optionally the

JPEG library by the Independant JPEG Group (IJG) and/or

lcms (little cms), a color-management library by Marti Maria Saguer.

I. Introduction

This file describes how to use and modify the MNG reference library

(known as libmng) for your own use.  There are seven sections to this

file: introduction, callbacks, housekeeping, reading, displaying,

writing, and modification and configuration notes for various special

platforms. We assume that libmng is already installed; see the

INSTALL.README file for instructions on how to install libmng.

Libmng was written to support and promote the MNG specification.

The latest MNG specification (currently 1.0) is available at

  http://www.libpng.org/pub/mng/

Other information about MNG can be found at the MNG home page at

  http://www.libpng.org/pub/mng/

The latest version of libmng can be found at its own homepage at

  http://www.libmng.com/

In most cases the library will not need to be changed.

For standardization purposes the library contains both a Windows DLL

and a makefile for building a shared library (SO). The library is

written in C, but an interface for Borland Delphi is also available.

Libmng has been designed to handle multiple sessions at one time,

to be easily modifiable, to be portable to the vast majority of

machines (ANSI, K&R, 32-, and 64-bit) available, and to be easy

to use.

Libmng uses zlib for its compression and decompression of MNG files.

Further information about zlib, and the latest version of zlib, can be

found at the zlib home page, <http://www.zlib.org/>.

The zlib compression utility is a general purpose utility that is

useful for more than MNG/PNG files, and can be used without libmng.

See the documentation delivered with zlib for more details.

Libmng optionally uses the JPEG library by the Independant JPEG Group

(IJG). This library is used for the JNG sub-format, which is part of

the MNG specification, and allows for inclusion of JPEG decoded and

thus highly compressed (photographic) images.

Further information about the IJG JPEG library and the latest sources

can be found at <http://www.ijg.org/>.

Libmng can also optionally use the lcms (little CMS) library by

Marti Maria Saguer. This library provides an excellent color-management

system (CMS), which gives libmng the ability to provide full

color-correction for images with the proper color-information encoded.

Further information and the latest sources can be found at

<http://www.littlecms.com/>.

Libmng is thread safe, provided the threads are using different

handles as returned by the initialization call.

Each thread should have its own handle and thus its own image.

Libmng does not protect itself against two threads using the

same instance of a handle.

The libmng.h header file is the single reference needed for programming

with libmng:

#include <libmng.h>

II. Callbacks

Libmng makes extensive use of callback functions. This is meant to

keep the library as platform-independant and flexible as possible.

Actually, the first call you will make to the library, already contains

three parameters you can use to provide callback entry-points.

Most functions must return a mng_bool (boolean). Returning MNG_FALSE

indicates the library the callback failed in some way and the library

will immediately return from whatever it was doing back to the

application. Returning MNG_TRUE indicates there were no problems and

processing can continue.

Let's step through each of the possible callbacks. The sections on

reading, displaying and writing will also explain which callbacks are

needed when and where.

- mng_ptr mng_memalloc (mng_size_t iLen)

A very basic function which the library uses to allocate a memory-block

with the given size. A typical implementation would be:

    mng_ptr my_alloc (mng_size_t iLen) {

      return calloc (1, iSize);

    }

Note that the library requires you to zero-out the memory-block!!!

- void mng_memfree (mng_ptr    pPtr,

                    mng_size_t iLen)

Counterpart of the previous function. Typically:

    void my_free (mng_ptr pPtr, mng_size_t iLen) {

      free (pPtr);

    }

- mng_bool mng_openstream  (mng_handle hHandle)

- mng_bool mng_closestream (mng_handle hHandle)

These are called by the library just before it starts to process

(either read or write) a file and just after the processing stops.

This is the recommended place to do I/O initialization & finalization.

Whether you do or not, is up to you. The library does not put any

meaning into the calls. They are simply provided for your convenience.

- mng_bool mng_readdata (mng_handle  hHandle,

                         mng_ptr     pBuf,

                         mng_uint32  iBuflen,

                         mng_uint32p pRead)

This function is called when the library needs some more input while

reading an image. The reading process supports two modes:

Suspension-mode (SMOD) and non-suspension-mode (NSMOD).

See mng_set_suspensionmode() for a more detailed description.

In NSMOD, the library requires you to return exactly the amount of bytes

requested (= iBuflen). Any lesser amount indicates the input file

is exhausted and the library will return a MNG_UNEXPECTEDEOF errorcode.

In SMOD, you may return a smaller amount of bytes than requested.

This tells the library it should temporarily wait for more input to

arrive. The lib will return with MNG_NEEDMOREDATA, and will expect a

call to mng_read_resume() or mng_display_resume() next, as soon as

more input-data has arrived.

For NSMOD this function could be as simple as:

    mng_bool my_read (mng_handle  hHandle,

                      mng_ptr     pBuf,

                      mng_uint32  iBuflen,

                      mng_uint32p pRead) {

      *pRead = fread (pBuf, 1, iBuflen, myfile);

      return MNG_TRUE;

    }

- mng_bool mng_writedata (mng_handle  hHandle,

                          mng_ptr     pBuf,

                          mng_uint32  iBuflen,

                          mng_uint32p pWritten)

This function is called during the mng_write() function to actually

output data to the file. There is no suspension-mode during write,

so the application must return the exact number of bytes the library

requests to be written.

A typical implementation could be:

    mng_bool my_write (mng_handle  hHandle,

                       mng_ptr     pBuf, 

                       mng_uint32  iBuflen,

                       mng_uint32p pWritten) {

      *pWritten = fwrite (pBuf, 1, iBuflen, myfile);

      return MNG_TRUE;

    }

- mng_bool mng_errorproc (mng_handle  hHandle,

                          mng_int32   iErrorcode,

                          mng_int8    iSeverity,

                          mng_chunkid iChunkname,

                          mng_uint32  iChunkseq,

                          mng_int32   iExtra1,

                          mng_int32   iExtra2,

                          mng_pchar   zErrortext)

This function is called whenever an error is detected inside the

library. This may be caused by invalid input, callbacks indicating

failure, or wrongfully calling functions out of place.

If you do not provide this callback the library will still return

an errorcode from the called function, and the mng_getlasterror()

function can be used to retrieve the other parameters.

This function is currently only provided for convenience, but may

at some point be used to indicate certain errors may be acceptable,

and processing should continue.

- mng_bool mng_traceproc (mng_handle hHandle,

                          mng_int32  iFuncnr,

                          mng_int32  iFuncseq,

                          mng_pchar  zFuncname)

This function is provided to allow a functional analysis of the

library. This may be useful if you encounter certain errors and

cannot determine what the problem is.

Almost all functions inside the library will activate this

callback with an appropriate function-name at the start and end

of the function. Please note that large images may generate an

enormous amount of calls.

- mng_bool mng_processheader (mng_handle hHandle,

                              mng_uint32 iWidth,

                              mng_uint32 iHeight)

This function is called once the header information of an input-

image has been processed. At this point the image dimensions are

available and also some other properties depending on the type

of the image. Eg. for a MNG the frame-/layercount, playtime &

simplicity fields are known.

The primary purpose of this callback is to inform the application

of the size of the image, and for the application to initialize

the drawing canvas to be used by the library. This is also a good

point to set the canvas-style. Eg. mng_set_canvasstyle().

- mng_bool mng_processtext (mng_handle hHandle,

                            mng_uint8  iType,

                            mng_pchar  zKeyword,

                            mng_pchar  zText,

                            mng_pchar  zLanguage,

                            mng_pchar  zTranslation)

This callback is activated for each textual chunk in the input-

image. These are tEXt, zTXt & iTXt. It may be used to retain

specific comments for presentation to the user.

- mng_bool mng_processsave (mng_handle hHandle)

- mng_bool mng_processseek (mng_handle hHandle,

                            mng_pchar  zName)

The purpose of these callbacks is to signal the processing of the

SAVE & SEEK chunks in a MNG input-file. This may be used in the

future to specify some special processing. At the moment these

functions are only provided as a signal.

- mng_ptr mng_getcanvasline (mng_handle hHandle,

                             mng_uint32 iLinenr)

- mng_ptr mng_getbkgdline   (mng_handle hHandle,

                             mng_uint32 iLinenr)

- mng_ptr mng_getalphaline  (mng_handle hHandle,

                             mng_uint32 iLinenr)

These callbacks are used to access the drawing canvas, background

canvas and an optional separate alpha-channel canvas. The latter is

used only with the MNG_CANVAS_RGB8_A8 canvas-style.

If the getbkgdline() callback is not supplied the library will

composite full or partially transparent pixels in the image against

a specified background color. See mng_set_bgcolor() for more details.

If a chosen canvas-style includes an alpha-channel, this callback

is very likely not needed.

The application is responsible for returning a pointer to a line of

pixels, which should be in the exact format as defined by the call

to mng_set_canvasstyle() and mng_set_bkgdstyle(), without gaps between

the representation of each pixel.

- mng_bool mng_refresh (mng_handle hHandle,

                        mng_uint32 iX,

                        mng_uint32 iY,

                        mng_uint32 iWidth,

                        mng_uint32 iHeight)

This callback is called when the library has drawn a complete frame

onto the drawing canvas, and it is ready to be displayed.

The application is responsible for transferring the drawing canvas

from memory onto the actual output device.

- mng_uint32 mng_gettickcount (mng_handle hHandle)

This function should return the number of milliseconds on some internal

clock. The entire animation timing depends heavily on this function,

1and the number returned should be as accurate as possible.

- mng_bool mng_settimer (mng_handle hHandle,

                         mng_uint32 iMsecs)

This callback is activated every time the library requires a "pause".

Note that the function itself should NOT execute the wait. It should

simply store the time-field and allow the library to return. Libmng

will return with the MNG_NEEDTIMERWAIT code, indicating the callback

was called and it is now time to execute the pause.

After the indicated number of milliseconds have elapsed, the application

should call mng_display_resume(), to resume the animation as planned.

This method allows for both a real timer or a simple wait command in the

application. Whichever method you select, both the gettickcount() and

settimer() callbacks are crucial for proper animation timing.

- mng_bool mng_processgamma  (mng_handle hHandle,

                              mng_uint32 iGamma)

- mng_bool mng_processchroma (mng_handle hHandle,

                              mng_uint32 iWhitepointx,

                              mng_uint32 iWhitepointy,

                              mng_uint32 iRedx,

                              mng_uint32 iRedy,

                              mng_uint32 iGreenx,

                              mng_uint32 iGreeny,

                              mng_uint32 iBluex,

                              mng_uint32 iBluey)

- mng_bool mng_processsrgb   (mng_handle hHandle,

                              mng_uint8  iRenderingintent)

- mng_bool mng_processiccp   (mng_handle hHandle,

                              mng_uint32 iProfilesize,

                              mng_ptr    pProfile)

- mng_bool mng_processarow   (mng_handle hHandle,

                              mng_uint32 iRowsamples,

                              mng_bool   bIsRGBA16,

                              mng_ptr    pRow)

These callbacks are only required when you selected the MNG_APP_CMS

directive during compilation of the library. See the configuration

section for more details.

- mng_bool mng_iteratechunk (mng_handle  hHandle,

                             mng_handle  hChunk,

                             mng_chunkid iChunkid,

                             mng_uint32  iChunkseq)

This callback is only used for the mng_iterate_chunks() function.

It is called exactly once for each chunk stored.

III. Housekeeping

> Memory management

The library can use internal memory allocation/deallocation or use

provided callbacks for its memory management. The choice is made at

compilation time. See the section on customization for details.

If internal management has been selected, the memory callback functions

need not be supplied. Even if you do supply them they will not be used.

The actual code used is similar to the code discussed in the callback

section:

      pPtr = calloc (1, iSize);

      free (pPtr);

If your compiler does not support these functions, or you wish to monitor

the library's use of memory for certain reasons, you can choose to

compile the library with external memory management. In this case the

memory callback functions MUST be supplied, and should function as if the

above code was used.

> Initialization

The basic initialization of the library is short and swift:

    myhandle = mng_initialize (myuserdata, my_alloc, 

                               my_free, MNG_NULL);

    if (myhandle == MNG_NULL)

      /* process error */;

The first field is an application-only parameter. It is saved in

libmng's internal structures and available at all times through the

mng_get_userdata() function. This is especially handy in callback functions

if your program may be handling multiple files at the same time.

The second and third field supply the library with the memory callback

1function entry-points. These are described in more detail in the callback

section and the previous paragraph.

The fourth and last field may be used to supply the library with the

entry-point of a trace callback function. For regular use you will not

need this!

The function returns a handle which will be your ticket to MNG-heaven.

All other functions rely on this handle. It is the single fixed unique

reference-point between your application and the library.

You should call the initialization function for each image you wish to

process simultaneously. If you are processing images consecutively, you can

reset the internal status of the library with the mng_reset() function.

This function will clear all internal state variables, free any stored

chunks and/or objects, etc, etc. Your callbacks and other external parameters

will be retained.

After you successfully received the handle it is time to set the required

callbacks. The sections on reading, displaying & writing indicate which

callbacks are required and which are optional.

To set the callbacks simply do:

    myretcode = mng_setcb_xxxxxx (myhandle, my_xxxxxx);

    if (myretcode != MNG_NOERROR)

      /* process error */;

Naturally you'd replace the x's with the name of the callback.

> Cleanup

Once you've gotten hold of that precious mng_handle, you should always,

and I mean always, call the cleanup function when you're done.

Just do:

    mng_cleanup (myhandle);

And you're done. There shouldn't be an ounce of memory spilled after

that call.

Note that if you would like to process multiple files consecutively

you do not need to do mng_cleanup() / mng_initialize() between each file

but simply

    myretcode = mng_reset (myhandle);

    if (myretcode != MNG_NOERROR)

      /* process error */;

will suffice. Saves some time and effort, that.

> Error handling

From the examples in the previous paragraphs you may have noticed a

meticulous scheme for error handling. And yes, that's exactly what it is.

Practically each call simply returns an errorcode, indicating success,

eg. MNG_NOERROR or failure, anything else but MNG_NEEDMOREDATA and

MNG_NEEDTIMERWAIT. These latter two will be discussed in more detail in

their respective fields of interest: the reading section and displaying

section respectively.

It is the application's responsibility to check the returncode after

each call. You can call mng_getlasterror() to receive the details of

the last detected error. This even includes a discriptive error-message

if you enabled that option during compilation of the library.

Note that after receiving an error it is still possible to call the

library, but it's also very likely that any following call will fail.

The only functions deemed to work will be mng_reset() and mng_cleanup().

Yes, if you abort your program after an error, you should still call

mng_cleanup().

IV. Reading

Reading a MNG, JNG or PNG is fairly easy. It depends slightly on your

ultimate goal how certain specifics are to be handled, but the basics

are similar in all cases.

For the read functioins to work you must have compiled the library with

the MNG_READ_SUPPRT directive. The standard DLL and Shared Library

have this on by default!

> Setup

Naturally you must have initialized the library and be the owner of

a mng_handle. The following callbacks are essential:

    mng_openstream, mng_readdata, mng_closestream

You may optionally define:

    mng_errorproc, mng_traceproc

    mng_processheader, mng_processtext

    mng_processsave, mng_processseek

The reading bit will also fail if you are already creating or

displaying a file. Seems a bit obvious, but I thought I'd mention it,

just in case.

> To suspend or not to suspend

There is one choice you need to make before calling the read function.

Are you in need of suspension-mode or not?

If you're reading from a disk you most certainly do not need

suspension-mode. Even the oldest and slowest of disks will be fast

enough for straight reading.

However, if your input comes from a really slow device, such as a

dialup-line or the likes, you may opt for suspension-mode. This is done

by calling

    myretcode = mng_set_suspensionmode (myhandle,

                                        MNG_TRUE);

    if (myretcode != MNG_NOERROR)

      /* process error */;

Suspension-mode will force the library to use special buffering on the

input. This allows your application to receive data of arbitrarily length

and return this in the mng_readdata() callback, without disturbing the

chunk processing routines of the library.

Suspension-mode does require a little extra care in the main logic of the

1application. The read function may return with MNG_NEEDMOREDATA when the

mng_readdata() callback returns less data then it needs to process the

next chunk. This indicates the application to wait for more data to arrive

and then resume processing by calling mng_read_resume().

> The read HLAPI

The actual reading is just plain simple. Since all I/O is done

1outside the library through the callbacks, the library can focus on

its real task. Understanding, checking and labelling the input data!

All you really need to do is this:

    myretcode = mng_read (myhandle);

    if (myretcode != MNG_NOERROR)

      /* process error */;

Of course, if you're on suspension-mode the code is a little more

complicated:

    myretcode = mng_read (myhandle);

    while (myretcode == MNG_NEEDMOREDATA) {

      /* wait for input-data to arrive */

      myretcode = mng_read_resume (myhandle);

    } 

    if (myretcode != MNG_NOERROR)

      /* process error */;

This is rather crude and more sophisticated programming methods may

dictate another approach. Whatever method you decide on, it should