FCL/sf/mw/qt: comparison src/3rdparty/libmng/doc/libmng.txt

equal deleted inserted replaced

--1:000000000000
+:1918ee327afb
+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
+act as if the above code was in its place.
+There is also the mng_readdisplay() function, but this is discussed
+in the displaying section. It functions pretty much as the mng_read()
+function, but also immediately starts displaying the image.
+mng_read_resume() should be replaced by mng_display_resume() in that
+case!
+> What happens inside
+What actually happens inside the library depends on the configuration
+options set during the compilation of the library.
+Basically the library will first read the 8-byte file header, to determine
+its validity and the type of image it is about to process. Then it will
+repeatedly read a 4-byte chunk-length and then the remainder of the chunk
+until it either reaches EOF (indicated by the mng_readdata() callback) or
+implicitly decides EOF as it processed the logically last chunk of the
+image.
+Applications that require strict conformity and do not allow superfluous
+data after the ending chunk, will need to perform this check in their
+mng_closestream() callback.
+Each chunk is then checked on CRC, after which it is handed over to the
+appropriate chunk processing routine. These routines will disect the
+chunk, check the validity of its contents, check its position with respect
+to other chunks, etc, etc.
+If everything checks out, the chunk is further processed as follows:
+If display support has been selected during compilation, certain pre-display
+initialization will take place.
+If chunk-storage support has been selected during compilation, the chunks
+data may be stored in a special internal structure and held for future
+reference.
+> Storing and accessing chunks
+One of the compilation options activates support for chunk storage.
+This option may be useful if you want to examine an image. The directive
+is MNG_STORE_CHUNKS. You must also turn on the MNG_ACCESS_CHUNKS
+directive.
+The actual storage facility can be turned on or off with the
+mng_set_storechunks() function. If set to MNG_TRUE, chunks will be
+stored as they are read.
+At any point you can then call the mng_iterate_chunks() function
+to iterate through the current list of chunks. This function requires
+a callback which is called for each chunk and receives a specific
+chunk-handle. This chunk-handle can be used to call the appropriate
+mng_getchunk_xxxx() function, to access the chunks properties.
+A typical implementation may look like this:
+mng_bool my_iteratechunk (mng_handle  hHandle,
+mng_handle  hChunk,
+mng_chunkid iChunkid,
+mng_uint32  iChunkseq) {
+switch (iChunkid) {
+case MNG_UINT_MHDR : { /* process MHDR */;
+break; }
+case MNG_UINT_FRAM : { /* process FRAM */;
+break; }
+...etc...
+case MNG_UINT_HUH  : { /* unknown chunk */;
+break; }
+default : { /* duh; forgot one */; }
+}
+return MNG_TRUE; /* keep'm coming */
+}
+To get to the actual chunk fields of lets say a SHOW chunk you would do:
+mng_bool isempty;
+mng_uint16 firstid, lastid;
+mng_uint8 showmode;
+myretcode mng_getchunk_show (hHandle, hChunk,
+isempty, firstid,
+lastid, showmode);
+if (myretcode != MNG_NOERROR)
+/* process error */;
+V. Displaying
+> Setup
+Assuming you have initialized the library and are the owner of
+a mng_handle. The following callbacks are essential:
+mng_getcanvasline, mng_refresh
+mng_gettickcount, mng_settimer
+If you wish to use an application supplied background you must supply:
+mng_getbkgdline
+If you wish to use the MNG_CANVAS_RGB8_A8 canvas style you must supply:
+mng_getalphaline
+You may optionally define:
+mng_errorproc, mng_traceproc
+mng_processheader, mng_processtext
+mng_processsave, mng_processseek
+Note that the mng_processheader() callback is optional but will
+be quite significant for proper operation!
+Displaying an image will fail if you are creating a file or already
+displaying one. Yes, you can't display it twice!
+> A word on canvas styles
+The canvas style describes how your drawing canvas is made up.
+You must set this before the library actually starts drawing, so
+the mng_processheader() callback is a pretty good place for it.
+Currently only 8-bit RGB canvas styles are supported, either with
+or without an alpha channel.
+If you like to do alpha composition yourself you can select one of
+the canvas styles that include an alpha channel. You can even have
+a separate alpha canvas by selecting the MNG_CANVAS_RGB8_A8 style.
+All styles require a compact model. Eg. MNG_CANVAS_BGR8 requires
+your canvas lines in bgrbgrbgr... storage, where each letter
+represents an 8-bit value of the corresponding color, and each
+threesome makes up the values of one(1) pixel.
+The library processes a line at a time, so the canvas lines do not
+actually need to be consecutive in memory.
+> Alpha composition and application backgrounds
+All Network Graphics can be partially transparent. This requires
+special processing if you need to display an image against some
+background. Note that the MNG header (MHDR chunk) contains a
+simplicity field indicating whether transparency information in
+the file is critical or not. This only applies to embedded images,
+which means the full image-frame of the MNG may still contain fully
+transparent pixels!
+Depending on your needs you can supply a single background color,
+a background canvas or tell the library to return the alpha-channel
+and do alpha composition yourself.
+This is different from the BACK chunk in a MNG, or the bKGD chunk
+in an (embedded) PNG or JNG. The BACK chunk indicates an optional or
+mandatory background color and/or image. The bKGD chunk only indicates
+an optional background color. These chunks indicate the Authors
+preferences. They may be absent in which case you need to supply
+some sort of background yourself.
+> Composing against a background color
+This is the easiest method. Call the mng_set_bgcolor() function to
+set the values of the red, green and blue component of your preferred
+background color.
+Use one of the canvas styles that do not have an alpha-channel, and
+which matches your output requirements.
+> Composing against a background canvas
+This is somewhat more complicated. You will need to set the
+mng_getbkgdline() callback. This will be called whenever the library
+needs to compose a partially transparent line.
+This canvas must hold the background against which the image should
+be composed. Its size must match exactly with the image dimensions
+and thus the drawing canvas!
+Use one of the canvas styles that do not have an alpha-channel, and
+which matches your output requirements. The canvas style of the
+background canvas may even differ from the drawing canvas. The library's
+composing will still function properly.
+> Composing within the application
+If you have the option in your application to draw a (partially)
+transparent canvas to the output device, this option is preferred.
+Select one of the canvas styles that do have an alpha-channel.
+The library will now supply the appropriate alpha information,
+allowing the application to compose the image as it sees fit.
+> Color information and CMS
+Network Graphics may, and usually will, contain color-correction
+information. This information is intended to compensate for the
+difference in recording and display devices used.
+This document does not address the specifics of color-management.
+See the PNG specification for a more detailed description.
+> Using little cms by Marti Maria Saguer
+This is the easiest method, providing you can compile the lcms package.
+Select the MNG_FULL_CMS directive during compilation, and sit back and
+relax. The library will take care of all color-correction for you.
+> Using an OS- or application-supplied CMS
+If you are so lucky to have access to CMS functionality from within
+your application, you may instruct the library to leave color-correction
+to you.
+Select the MNG_APP_CMS directive during compilation of the library.
+You MUST also set the following callbacks:
+mng_processgamma, mng_processchroma,
+mng_processsrgb, mng_processiccp and
+mng_processarow
+The last callback is called when the library needs you to correct
+an arbitrary line of pixels. The other callbacks are called when
+the corresponding color-information is encountered in the file.
+You must store this information somewhere for use in the
+mng_processarow() callback.
+> Using gamma-only correction
+This isn't a preferred method, but it's better than no correction
+at all. Gamma-only correction will at least compensate for
+gamma-differences between the original recorder and your output device.
+Select the MNG_GAMMA_ONLY directive during compilation
+of the library. Your compiler MUST support fp operations.
+> No color correction
+Ouch. This is really bad. This is the least preferred method,
+but may be necessary if your system cannot use lcms, doesn't
+have its own CMS, and does not allow fp operations, ruling out
+the gamma-only option.
+Select the MNG_NO_CMS directive during compilation.
+Images will definitely not be displayed as seen by the Author!!!
+> Animations and timing
+Animations require some form of timing support. The library relies
+on two callbacks for this purpose. The mng_gettickcount() and
+mng_settimer() callbacks. mng_gettickcount() is used to determine
+the passing of time in milliseconds since the beginning of the
+animation. This is also used to compensate during suspension-mode
+if you are using the mng_readdisplay() function to read & display
+the file simultaneously.
+The callback may return an arbitrary number of milliseconds, but
+this number must increase proportionaly between calls. Most modern
+systems will have some tickcount() function which derives its
+input from an internal clock. The value returned from this function
+is more than adequate for libmng.
+The mng_settimer() callback is called when the library determines
+a little "pause" is required before rendering another frame of the
+animation. The pause interval is also expressed in milliseconds.
+Your application should store this value and return immediately.
+The library will then make appropriate arrangements to store its
+internal state and returns to your application with the
+MNG_NEEDTIMERWAIT code.
+At that point you should suspend processing and wait the given
+interval. Please use your OS features for this. Do not engage some
+sort of loop. That is real bad programming practice. Most modern
+systems will have some timing functions. A simple wait() function
+may suffice, but this may prevent your applications main-task from
+running, and possibly prevent the actual update of your output device.
+> The mng_refresh() callback
+The mng_refresh() callback is called whenever the library has
+"finished" drawing a new frame onto your canvas, and just before it
+will call the mng_settimer() callback.
+This allows you to perform some actions necessary to "refresh" the
+canvas onto your output device. Please do NOT suspend processing
+inside this callback. This must be handled after the mng_settimer()
+callback!
+> Displaying while reading
+This method is preferred if you are reading from a slow input device
+(such as a dialup-line) and you wish to start displaying something
+as quickly as possible. This functionality is provided mainly for
+browser-type applications but may be appropriate for other
+applications as well.
+The method is usually used in unison with the suspension-mode of
+the read module. A typical implementation would look like this:
+/* initiale library and set required callbacks */
+/* activate suspension-mode */
+myretcode = mng_set_suspensionmode (myhandle,
+MNG_TRUE);
+if (myretcode != MNG_NOERROR)
+/* process error */;
+myretcode = mng_readdisplay (myhandle);
+while ((myretcode == MNG_NEEDMOREDATA) ||
+(myretcode == MNG_NEEDTIMERWAIT)) {
+if (myretcode == MNG_NEEDMOREDATA)
+/* wait for more input-data */;
+else
+/* wait for timer interval */;
+myretcode = mng_display_resume (myhandle);
+}
+if (myretcode != MNG_NOERROR)
+/* process error */;
+More advanced programming methods may require a different approach,
+but the final result should function as in the code above.
+> Displaying after reading
+This method is used to display a file that was previously read.
+It is primarily meant for viewers with direct file access, such as
+1a local harddisk.
+Once you have successfully read the file, all you need to do is:
+myretcode = mng_display (myhandle);
+while (myretcode == MNG_NEEDTIMERWAIT) {
+/* wait for timer interval */;
+myretcode = mng_display_resume (myhandle);
+}
+if (myretcode != MNG_NOERROR)
+/* process error */;
+Again, more advanced programming methods may require a different
+approach, but the final result should function as in the code above.
+> Display manipulation
+Several HLAPI functions are provided to allow a user to manipulate
+the normal flow of an animation.
+- mng_display_freeze (mng_handle hHandle)
+This will "freeze" the animation in place.
+- mng_display_resume (mng_handle hHandle)
+This function can be used to resume a frozen animation, or to force
+the library to advance the animation to the next frame.
+- mng_display_reset (mng_handle hHandle)
+This function will "reset" the animation into its pristine state.
+Calling mng_display() afterwards will re-display the animation
+from the first frame.
+- mng_display_golayer    (mng_handle hHandle,
+mng_uint32 iLayer)
+- mng_display_goframe    (mng_handle hHandle,
+mng_uint32 iFrame)
+- mng_display_goplaytime (mng_handle hHandle,
+mng_uint32 iPlaytime)
+These three functions can be used to "jump" to a specific layer, frame
+or timeslot in the animation. You must "freeze" the animation before
+using any of these functions.
+All above functions may only be called during a timer interval!
+It is the applications responsibility to cleanup any resources with
+respect to the timer wait.
+VI. Writing
+The main focus of the library lies in its displaying capabilites.
+But it does offer writing support as well.
+You can create and write a file, or you can write a file you
+have previously read, providing the storage of chunks was enabled
+and active.
+For this to work you must have compiled the library with the
+MNG_WRITE_SUPPO1RT and MNG_ACCESS_CHUNKS directives. The standard DLL and
+Shared Library have this on by default!
+> Setup
+As always you must have initialized the library and be the owner of
+a mng_handle. The following callbacks are essential:
+mng_openstream, mng_writedata, mng_closestream
+You can optionally define:
+mng_errorproc, mng_traceproc
+The creation and writing functions will fail if you are in the middle
+of reading, creating or writing a file.
+> Creating a new file
+To start a new file the library must be in its initial state.
+First you need to tell the library your intentions:
+myretcode = mng_create (myhandle);
+if (myretcode != MNG_NOERROR)
+/* process error */;
+After that you start adding the appropriate chunks:
+myretcode = mng_putchunk_mhdr (myhandle, ...);
+if (myretcode != MNG_NOERROR)
+/* process error */;
+And so on, and so forth. Note that the library will automatically signal
+the logical end of the file by the ending chunk. Also the first chunk
+will indicate the library the filetype (eg. PNG, JNG or MNG) and force
+the proper signature when writing the file.
+The code above can be simplified, as you can always get the last errorcode
+by using the mng_getlasterror() function:
+if ( (mng_putchunk_xxxx (myhandle, ...)) or
+(mng_putchunk_xxxx (myhandle, ...)) or
+...etc...                          )
+/* process error */;
+Please note that you must have a pretty good understanding of the chunk
+specification. Unlike the read functions, there are virtually no checks,
+so it is quite possible to write completely wrong files.
+It is a good practice to read back your file into the library to verify
+its integrity.
+Once you've got all the chunks added, all you do is:
+myretcode mng_write (myhandle);
+if (myretcode != MNG_NOERROR)
+/* process error */;
+And presto. You're done. The real work is of course carried out in
+your callbacks. Note that this is a single operation as opposed to
+the read & display functions that may return with MNG_NEEDMOREDATA
+and/or MNG_NEEDTIMERWAIT. The write function just does the job, and
+only returns after it's finished or if it encounters some
+unrecoverable error.
+> Writing a previously read file
+If you have already successfully read a file, you can use the library to
+write it out as a copy or something. You MUST have compiled the library
+with the MNG_STORE_CHUNKS directive, and you must have done
+mng_set_storechunks (myhandle, MNG_TRUE).
+This doesn't require the MNG_ACCESS_CHUNKS directive, unless you want
+to fiddle with the chunks as well.
+Again all you need to do is:
+myretcode mng_write (myhandle);
+if (myretcode != MNG_NOERROR)
+/* process error */;
+VII. Modifying/Customizing libmng:
+to do
+> Compilation directives
+to do
+> Platform dependant modification
+to do
+References :
+libmng :
+http://www.libmng.com/
+zlib :
+http://www.info-zip.org/pub/infozip/zlib/
+IJG JPEG library :
+http://www.ijg.org/
+lcms (little CMS) by Marti Maria Saguer :
+http://www.littlecms.com/
+MNG specification:
+http://www.libpng.org/pub/mng
+In the case of any inconsistency between the MNG specification
+and this library, the specification takes precedence.
+The contributing authors would like to thank all those who helped
+with testing, bug fixes, and patience.  This wouldn't have been
+possible without all of you!!!
+COPYRIGHT NOTICE:
+Copyright (c) 2000,2001 Gerard Juyn
+For the purposes of this copyright and license, "Contributing Authors"
+is defined as the following set of individuals:
+Gerard Juyn
+The MNG Library is supplied "AS IS".  The Contributing Authors
+disclaim all warranties, expressed or implied, including, without
+limitation, the warranties of merchantability and of fitness for any
+purpose.  The Contributing Authors assume no liability for direct,
+indirect, incidental, special, exemplary, or consequential damages,
+which may result from the use of the MNG Library, even if advised of
+the possibility of such damage.
+Permission is hereby granted to use, copy, modify, and distribute this
+source code, or portions hereof, for any purpose, without fee, subject
+to the following restrictions:
+1. The origin of this source code must not be misrepresented;
+you must not claim that you wrote the original software.
+2. Altered versions must be plainly marked as such and must not be
+misrepresented as being the original source.
+3. This Copyright notice may not be removed or altered from any source
+or altered source distribution.
+The Contributing Authors specifically permit, without fee, and
+encourage the use of this source code as a component to supporting
+the MNG and JNG file format in commercial products.  If you use this
+source code in a product, acknowledgment would be highly appreciated.
+Remarks :
+Parts of this software have been adapted from the libpng library.
+Although this library supports all features from the PNG specification
+(as MNG descends from it) it does not require the libpng library.
+It does require the zlib library and optionally the IJG JPEG library,
+and/or the "little-cms" library by Marti Maria Saguer (depending on the
+inclusion of support for JNG and Full-Color-Management respectively.
+This library's function is primarily to read and display MNG
+animations. It is not meant as a full-featured image-editing
+component! It does however offer creation and editing functionality
+at the chunk level. (future modifications may include some more
+support for creation and or editing)