libmng.txt

Linux下的基于X11的图形开发环境。

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