libmng.txt

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

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_resume() afterwards will restart 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)