1 .TH LIBMNG 3 "January 30th, 2005"

     2 .SH NAME

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

     4 .SH SYNOPSIS

     5 \fI\fB

     6 

     7 \fB#include <libmng.h>\fP

     8 

     9 

    10 .SH DESCRIPTION

    11 The

    12 .I libmng

    13 library supports decoding, displaying, encoding, and various other

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

    15 image files. It uses the

    16 .IR zlib(3)

    17 compression library, and optionally the JPEG library by the Independant

    18 JPEG Group (IJG) and/or lcms (little cms), a color-management library

    19 by Marti Maria Saguer.

    20 

    21 

    22 .SH I. Introduction

    23 

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

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

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

    27 writing, and modification and configuration notes for various special

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

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

    30 

    31 Libmng was written to support and promote the MNG specification.

    32 

    33 The MNG-1.0 specification is available at

    34 <http://www.libpng.org/pub/mng/spec/>.

    35 

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

    37 <http://www.libpng.org/pub/mng/>.

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

    39 <http://www.libmng.com/>.

    40 

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

    42 For standardization purposes the library contains both a Windows DLL

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

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

    45 

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

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

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

    49 to use.

    50 

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

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

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

    54 The zlib compression utility is a general purpose utility that is

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

    56 See the documentation delivered with zlib for more details.

    57 

    58 Libmng optionally uses the JPEG library by the Independant JPEG Group

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

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

    61 thus highly compressed (photographic) images.

    62 Further information about the IJG JPEG library and the latest sources

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

    64 

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

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

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

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

    69 Further information and the latest sources can be found at

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

    71 

    72 Libmng is thread safe, provided the threads are using different

    73 handles as returned by the initialization call.

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

    75 Libmng does not protect itself against two threads using the

    76 same instance of a handle.

    77 

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

    79 with libmng:

    80 

    81 #include <libmng.h>

    82 

    83 

    84 .SH II. Callbacks

    85 

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

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

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

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

    90 

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

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

    93 will immediately return from whatever it was doing back to the

    94 application. Returning MNG_TRUE indicates there were no problems and

    95 processing can continue.

    96 

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

    98 reading, displaying and writing will also explain which callbacks are

    99 needed when and where.

   100 

   101 \- mng_ptr mng_memalloc (mng_size_t iLen)

   102 

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

   104 with the given size. A typical implementation would be:

   105 

   106     mng_ptr my_alloc (mng_size_t iLen) {

   107       return calloc (1, iLen);

   108     }

   109 

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

   111 

   112 \- void mng_memfree (mng_ptr    pPtr,

   113                     mng_size_t iLen)

   114 

   115 Counterpart of the previous function. Typically:

   116 

   117     void my_free (mng_ptr pPtr, mng_size_t iLen) {

   118       free (pPtr);

   119     }

   120 

   121 \- mng_bool mng_openstream  (mng_handle hHandle)

   122 

   123 \- mng_bool mng_closestream (mng_handle hHandle)

   124 

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

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

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

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

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

   130 

   131 \- mng_bool mng_readdata (mng_handle  hHandle, 

   132                          mng_ptr     pBuf, 

   133                          mng_uint32  iBuflen, 

   134                          mng_uint32p pRead)

   135     

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

   137 reading an image. The reading process supports two modes:

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

   139 See mng_set_suspensionmode() for a more detailed description.

   140 

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

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

   143 is exhausted and the library will return a MNG_UNEXPECTEDEOF errorcode.

   144 

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

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

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

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

   149 more input-data has arrived.

   150 

   151 For NSMOD this function could be as simple as:

   152 

   153     mng_bool my_read (mng_handle  hHandle,

   154                       mng_ptr     pBuf, 

   155                       mng_uint32  iBuflen,

   156                       mng_uint32p pRead) {

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

   158       return MNG_TRUE;

   159     }

   160 

   161 \- mng_bool mng_writedata (mng_handle  hHandle,

   162                           mng_ptr     pBuf, 

   163                           mng_uint32  iBuflen, 

   164                           mng_uint32p pWritten)

   165 

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

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

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

   169 requests to be written.

   170 

   171 A typical implementation could be:

   172 

   173     mng_bool my_write (mng_handle  hHandle,

   174                        mng_ptr     pBuf, 

   175                        mng_uint32  iBuflen,

   176                        mng_uint32p pWritten) {

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

   178       return MNG_TRUE;

   179     }

   180 

   181 \- mng_bool mng_errorproc (mng_handle  hHandle,

   182                           mng_int32   iErrorcode,

   183                           mng_int8    iSeverity,

   184                           mng_chunkid iChunkname,

   185                           mng_uint32  iChunkseq,

   186                           mng_int32   iExtra1,

   187                           mng_int32   iExtra2,

   188                           mng_pchar   zErrortext)

   189 

   190 This function is called whenever an error is detected inside the

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

   192 failure, or wrongfully calling functions out of place.

   193 

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

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

   196 function can be used to retrieve the other parameters.

   197 

   198 This function is currently only provided for convenience, but may

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

   200 and processing should continue.

   201 

   202 \- mng_bool mng_traceproc (mng_handle hHandle,

   203                           mng_int32  iFuncnr,

   204                           mng_int32  iFuncseq,

   205                           mng_pchar  zFuncname)

   206 

   207 This function is provided to allow a functional analysis of the

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

   209 cannot determine what the problem is.

   210 

   211 Almost all functions inside the library will activate this

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

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

   214 enormous amount of calls.

   215 

   216 \- mng_bool mng_processheader (mng_handle hHandle,

   217                               mng_uint32 iWidth,

   218                               mng_uint32 iHeight)

   219 

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

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

   222 available and also some other properties depending on the type

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

   224 simplicity fields are known.

   225 

   226 The primary purpose of this callback is to inform the application

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

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

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

   230 

   231 \- mng_bool mng_processtext (mng_handle hHandle,

   232                             mng_uint8  iType,

   233                             mng_pchar  zKeyword,

   234                             mng_pchar  zText,

   235                             mng_pchar  zLanguage,

   236                             mng_pchar  zTranslation)

   237 

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

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

   240 specific comments for presentation to the user.

   241 

   242 \- mng_bool mng_processsave (mng_handle hHandle)

   243 

   244 \- mng_bool mng_processseek (mng_handle hHandle,

   245                             mng_pchar  zName)

   246 

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

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

   249 future to specify some special processing. At the moment these

   250 functions are only provided as a signal.

   251 

   252 \- mng_ptr mng_getcanvasline (mng_handle hHandle,

   253                              mng_uint32 iLinenr)

   254 

   255 \- mng_ptr mng_getbkgdline   (mng_handle hHandle,

   256                              mng_uint32 iLinenr)

   257 

   258 \- mng_ptr mng_getalphaline  (mng_handle hHandle,

   259                              mng_uint32 iLinenr)

   260 

   261 These callbacks are used to access the drawing canvas, background

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

   263 used only with the MNG_CANVAS_RGB8_A8 canvas-style.

   264 

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

   266 composite fully or partially transparent pixels in the image against

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

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

   269 is very likely not needed.

   270 

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

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

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

   274 the representation of each pixel, unless specified by the canvas-style.

   275 

   276 \- mng_bool mng_refresh (mng_handle hHandle,

   277                         mng_uint32 iX,

   278                         mng_uint32 iY,

   279                         mng_uint32 iWidth,

   280                         mng_uint32 iHeight)

   281 

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

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

   284 The application is responsible for transferring the drawing canvas

   285 from memory onto the actual output device.

   286 

   287 \- mng_uint32 mng_gettickcount (mng_handle hHandle)

   288 

   289 This function should return the number of milliseconds on some internal

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

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

   292 

   293 \- mng_bool mng_settimer (mng_handle hHandle,

   294                          mng_uint32 iMsecs)

   295 

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

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

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

   299 will return with the MNG_NEEDTIMERWAIT code, indicating the callback

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

   301 

   302 After the indicated number of milliseconds have elapsed, the application

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

   304 

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

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

   307 settimer() callbacks are crucial for proper animation timing.

   308 

   309 \- mng_bool mng_processgamma  (mng_handle hHandle,

   310                               mng_uint32 iGamma)

   311 

   312 \- mng_bool mng_processchroma (mng_handle hHandle,

   313                               mng_uint32 iWhitepointx,

   314                               mng_uint32 iWhitepointy,

   315                               mng_uint32 iRedx,

   316                               mng_uint32 iRedy,

   317                               mng_uint32 iGreenx,

   318                               mng_uint32 iGreeny,

   319                               mng_uint32 iBluex,

   320                               mng_uint32 iBluey)

   321 

   322 \- mng_bool mng_processsrgb   (mng_handle hHandle,

   323                               mng_uint8  iRenderingintent)

   324 

   325 \- mng_bool mng_processiccp   (mng_handle hHandle,

   326                               mng_uint32 iProfilesize,

   327                               mng_ptr    pProfile)

   328 

   329 \- mng_bool mng_processarow   (mng_handle hHandle,

   330                               mng_uint32 iRowsamples,

   331                               mng_bool   bIsRGBA16,

   332                               mng_ptr    pRow)

   333 

   334 These callbacks are only required when you selected the MNG_APP_CMS

   335 directive during compilation of the library. See the configuration

   336 section for more details.

   337 

   338 \- mng_bool mng_iteratechunk (mng_handle  hHandle,

   339                              mng_handle  hChunk,

   340                              mng_chunkid iChunkid,

   341                              mng_uint32  iChunkseq)

   342 

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

   344 It is called exactly once for each chunk stored.

   345 

   346 

   347 .SH III. Housekeeping

   348 

   349 

   350 .SS Memory management

   351 

   352 The library can use internal memory allocation/deallocation or use

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

   354 compilation time. See the section on customization for details.

   355 

   356 If internal management has been selected, the memory callback functions

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

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

   359 section:

   360 

   361       pPtr = calloc (1, iLen);

   362 

   363       free (pPtr);

   364 

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

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

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

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

   369 above code was used.

   370 

   371 

   372 .SS Initialization

   373 

   374 The basic initialization of the library is short and swift:

   375 

   376     myhandle = mng_initialize (myuserdata, my_alloc, 

   377                                my_free, MNG_NULL);

   378     if (myhandle == MNG_NULL)

   379       /* process error */;

   380 

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

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

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

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

   385 

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

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

   388 section and the previous paragraph.

   389 

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

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

   392 need this!

   393 

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

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

   396 reference-point between your application and the library.

   397 

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

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

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

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

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

   403 will be retained.

   404 

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

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

   407 callbacks are required and which are optional.

   408 To set the callbacks simply do:

   409 

   410     myretcode = mng_setcb_xxxxxx (myhandle, my_xxxxxx);

   411     if (myretcode != MNG_NOERROR)

   412       /* process error */;

   413 

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

   415 

   416 

   417 .SS Cleanup

   418 

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

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

   421 Just do:

   422 

   423     mng_cleanup (myhandle);

   424 

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

   426 that call.

   427 

   428 Note that if you would like to process multiple files consecutively

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

   430 but simply

   431 

   432     myretcode = mng_reset (myhandle);

   433     if (myretcode != MNG_NOERROR)

   434       /* process error */;

   435 

   436 will suffice. Saves some time and effort, that.

   437 

   438 

   439 .SS Error handling

   440 

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

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

   443 Practically each call simply returns an errorcode, indicating success,

   444 eg. MNG_NOERROR or failure, anything else but MNG_NEEDMOREDATA and

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

   446 their respective fields of interest: the reading section and displaying

   447 section respectively.

   448 

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

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

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

   452 if you enabled that option during compilation of the library.

   453 

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

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

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

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

   458 mng_cleanup().

   459 

   460 

   461 .SH IV. Reading

   462 

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

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

   465 are similar in all cases.

   466 

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

   468 the MNG_READ_SUPPRT directive. The standard DLL and Shared Library

   469 have this on by default!

   470 

   471 

   472 .SS Setup

   473 

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

   475 a mng_handle. The following callbacks are essential:

   476 

   477     mng_openstream, mng_readdata, mng_closestream

   478 

   479 You may optionally define:

   480 

   481     mng_errorproc, mng_traceproc

   482     mng_processheader, mng_processtext

   483     mng_processsave, mng_processseek

   484 

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

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

   487 just in case.

   488 

   489 

   490 .SS To suspend or not to suspend

   491 

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

   493 Are you in need of suspension-mode or not?

   494 

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

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

   497 enough for straight reading.

   498 

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

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

   501 by calling

   502 

   503     myretcode = mng_set_suspensionmode (myhandle,

   504                                         MNG_TRUE);

   505     if (myretcode != MNG_NOERROR)

   506       /* process error */;

   507 

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

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

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

   511 chunk processing routines of the library.

   512 

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

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

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

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

   517 and then resume processing by calling mng_read_resume().

   518 

   519 

   520 .SS The read HLAPI

   521 

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

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

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

   525 

   526 All you really need to do is this:

   527 

   528     myretcode = mng_read (myhandle);

   529     if (myretcode != MNG_NOERROR)

   530       /* process error */;

   531 

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

   533 complicated:

   534 

   535     myretcode = mng_read (myhandle);

   536 

   537     while (myretcode == MNG_NEEDMOREDATA) {

   538       /* wait for input-data to arrive */

   539       myretcode = mng_read_resume (myhandle);

   540     } 

   541    

   542     if (myretcode != MNG_NOERROR)

   543       /* process error */;

   544 

   545 This is rather crude and more sophisticated programming methods may

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

   547 act as if the above code was in its place.

   548 

   549 There is also the mng_readdisplay() function, but this is discussed

   550 in the displaying section. It functions pretty much as the mng_read()

   551 function, but also immediately starts displaying the image.

   552 mng_read_resume() should be replaced by mng_display_resume() in that

   553 case!

   554 

   555 

   556 .SS What happens inside

   557 

   558 What actually happens inside the library depends on the configuration

   559 options set during the compilation of the library.

   560 

   561 Basically the library will first read the 8-byte file header, to determine

   562 its validity and the type of image it is about to process. Then it will

   563 repeatedly read a 4-byte chunk-length and then the remainder of the chunk

   564 until it either reaches EOF (indicated by the mng_readdata() callback) or

   565 implicitly decides EOF as it processed the logically last chunk of the

   566 image.

   567 

   568 Applications that require strict conformity and do not allow superfluous

   569 data after the ending chunk, will need to perform this check in their

   570 mng_closestream() callback.

   571 

   572 Each chunk is then checked on CRC, after which it is handed over to the

   573 appropriate chunk processing routine. These routines will disect the

   574 chunk, check the validity of its contents, check its position with respect

   575 to other chunks, etc, etc.

   576 

   577 If everything checks out, the chunk is further processed as follows:

   578 

   579 If display support has been selected during compilation, certain pre-display

   580 initialization will take place.

   581 

   582 If chunk-storage support has been selected during compilation, the chunks

   583 data may be stored in a special internal structure and held for future

   584 reference.

   585 

   586 

   587 .SS Storing and accessing chunks

   588 

   589 One of the compilation options activates support for chunk storage.

   590 This option may be useful if you want to examine an image. The directive

   591 is MNG_STORE_CHUNKS. You must also turn on the MNG_ACCESS_CHUNKS

   592 directive.

   593 

   594 The actual storage facility can be turned on or off with the

   595 mng_set_storechunks() function. If set to MNG_TRUE, chunks will be

   596 stored as they are read.

   597 

   598 At any point you can then call the mng_iterate_chunks() function

   599 to iterate through the current list of chunks. This function requires

   600 a callback which is called for each chunk and receives a specific

   601 chunk-handle. This chunk-handle can be used to call the appropriate

   602 mng_getchunk_xxxx() function, to access the chunks properties.

   603 

   604 A typical implementation may look like this:

   605 

   606     mng_bool my_iteratechunk (mng_handle  hHandle,

   607                               mng_handle  hChunk,

   608                               mng_chunkid iChunkid,

   609                               mng_uint32  iChunkseq) {

   610       switch (iChunkid) {

   611         case MNG_UINT_MHDR : { /* process MHDR */;

   612                                break; }

   613         case MNG_UINT_FRAM : { /* process FRAM */;

   614                                break; }

   615 

   616             ...etc...

   617 

   618         case MNG_UINT_HUH  : { /* unknown chunk */; 

   619                                break; }

   620         default : { /* duh; forgot one */; }

   621       }

   622 

   623       return MNG_TRUE; /* keep'm coming */

   624     }

   625 

   626 To get to the actual chunk fields of lets say a SHOW chunk you would do:

   627 

   628     mng_bool isempty;

   629     mng_uint16 firstid, lastid;

   630     mng_uint8 showmode;

   631 

   632     myretcode mng_getchunk_show (hHandle, hChunk, 

   633                                  isempty, firstid,

   634                                  lastid, showmode);

   635     if (myretcode != MNG_NOERROR)

   636       /* process error */;

   637 

   638 

   639 .SH V. Displaying

   640 

   641 

   642 .SS Setup

   643 

   644 Assuming you have initialized the library and are the owner of

   645 a mng_handle. The following callbacks are essential:

   646 

   647     mng_getcanvasline, mng_refresh

   648     mng_gettickcount, mng_settimer

   649 

   650 If you wish to use an application supplied background you must supply:

   651 

   652     mng_getbkgdline

   653 

   654 If you wish to use the MNG_CANVAS_RGB8_A8 canvas style you must supply:

   655 

   656     mng_getalphaline

   657 

   658 You may optionally define:

   659 

   660     mng_errorproc, mng_traceproc

   661     mng_processheader, mng_processtext

   662     mng_processsave, mng_processseek

   663 

   664 Note that the mng_processheader() callback is optional but will

   665 be quite significant for proper operation!

   666 

   667 Displaying an image will fail if you are creating a file or already

   668 displaying one. Yes, you can't display it twice!

   669 

   670 

   671 .SS A word on canvas styles

   672 

   673 The canvas style describes how your drawing canvas is made up.

   674 You must set this before the library actually starts drawing, so

   675 the mng_processheader() callback is a pretty good place for it.

   676 

   677 Currently only 8-bit RGB canvas styles are supported, either with

   678 or without an alpha channel.

   679 

   680 If you like to do alpha composition yourself you can select one of

   681 the canvas styles that include an alpha channel. You can even have

   682 a separate alpha canvas by selecting the MNG_CANVAS_RGB8_A8 style.

   683 

   684 All styles require a compact model. Eg. MNG_CANVAS_BGR8 requires

   685 your canvas lines in bgrbgrbgr... storage, where each letter

   686 represents an 8-bit value of the corresponding color, and each

   687 threesome makes up the values of one(1) pixel.

   688 

   689 The library processes a line at a time, so the canvas lines do not

   690 actually need to be consecutive in memory.

   691 

   692 

   693 .SS Alpha composition and application backgrounds

   694 

   695 All Network Graphics can be partially transparent. This requires

   696 special processing if you need to display an image against some

   697 background. Note that the MNG header (MHDR chunk) contains a

   698 simplicity field indicating whether transparency information in

   699 the file is critical or not. This only applies to embedded images,

   700 which means the full image-frame of the MNG may still contain fully

   701 transparent pixels!

   702 

   703 Depending on your needs you can supply a single background color,

   704 a background canvas or tell the library to return the alpha-channel

   705 and do alpha composition yourself.

   706 

   707 This is different from the BACK chunk in a MNG, or the bKGD chunk

   708 in an (embedded) PNG or JNG. The BACK chunk indicates an optional or

   709 mandatory background color and/or image. The bKGD chunk only indicates

   710 an optional background color. These chunks indicate the Authors

   711 preferences. They may be absent in which case you need to supply

   712 some sort of background yourself.

   713 

   714 .SS Composing against a background color

   715 

   716 This is the easiest method. Call the mng_set_bgcolor() function to

   717 set the values of the red, green and blue component of your preferred

   718 background color.

   719 

   720 Use one of the canvas styles that do not have an alpha-channel, and

   721 which matches your output requirements.

   722 

   723 .SS Composing against a background canvas

   724 

   725 This is somewhat more complicated. You will need to set the

   726 mng_getbkgdline() callback. This will be called whenever the library

   727 needs to compose a partially transparent line.

   728 

   729 This canvas must hold the background against which the image should

   730 be composed. Its size must match exactly with the image dimensions

   731 and thus the drawing canvas!

   732 

   733 Use one of the canvas styles that do not have an alpha-channel, and

   734 which matches your output requirements. The canvas style of the

   735 background canvas may even differ from the drawing canvas. The library's

   736 composing will still function properly.

   737 

   738 .SS Composing within the application

   739 

   740 If you have the option in your application to draw a (partially)

   741 transparent canvas to the output device, this option is preferred.

   742 

   743 Select one of the canvas styles that do have an alpha-channel.

   744 The library will now supply the appropriate alpha information,

   745 allowing the application to compose the image as it sees fit.

   746 

   747 

   748 .SS Color information and CMS

   749 

   750 Network Graphics may, and usually will, contain color-correction

   751 information. This information is intended to compensate for the

   752 difference in recording and display devices used.

   753 

   754 This document does not address the specifics of color-management.

   755 See the PNG specification for a more detailed description.

   756 

   757 .SS Using little cms by Marti Maria Saguer

   758 

   759 This is the easiest method, providing you can compile the lcms package.

   760 Select the MNG_FULL_CMS directive during compilation, and sit back and

   761 relax. The library will take care of all color-correction for you.

   762 

   763 .SS Using an OS- or application-supplied CMS

   764 

   765 If you are so lucky to have access to CMS functionality from within

   766 your application, you may instruct the library to leave color-correction

   767 to you.

   768 

   769 Select the MNG_APP_CMS directive during compilation of the library.

   770 You MUST also set the following callbacks:

   771 

   772     mng_processgamma, mng_processchroma,

   773     mng_processsrgb, mng_processiccp and

   774     mng_processarow

   775 

   776 The last callback is called when the library needs you to correct

   777 an arbitrary line of pixels. The other callbacks are called when

   778 the corresponding color-information is encountered in the file.

   779 You must store this information somewhere for use in the

   780 mng_processarow() callback.

   781 

   782 .SS Using gamma-only correction

   783 

   784 This isn't a preferred method, but it's better than no correction

   785 at all. Gamma-only correction will at least compensate for

   786 gamma-differences between the original recorder and your output device.

   787 

   788 Select the MNG_GAMMA_ONLY directive during compilation

   789 of the library. Your compiler MUST support fp operations.

   790 

   791 .SS No color correction

   792 

   793 Ouch. This is really bad. This is the least preferred method,

   794 but may be necessary if your system cannot use lcms, doesn't

   795 have its own CMS, and does not allow fp operations, ruling out

   796 the gamma-only option.

   797 

   798 Select the MNG_NO_CMS directive during compilation.

   799 Images will definitely not be displayed as seen by the Author!!!

   800 

   801 

   802 .SS Animations and timing

   803 

   804 Animations require some form of timing support. The library relies

   805 on two callbacks for this purpose. The mng_gettickcount() and

   806 mng_settimer() callbacks. mng_gettickcount() is used to determine

   807 the passing of time in milliseconds since the beginning of the

   808 animation. This is also used to compensate during suspension-mode

   809 if you are using the mng_readdisplay() function to read & display

   810 the file simultaneously.

   811 

   812 The callback may return an arbitrary number of milliseconds, but

   813 this number must increase proportionaly between calls. Most modern

   814 systems will have some tickcount() function which derives its

   815 input from an internal clock. The value returned from this function

   816 is more than adequate for libmng.

   817 

   818 The mng_settimer() callback is called when the library determines

   819 a little "pause" is required before rendering another frame of the

   820 animation. The pause interval is also expressed in milliseconds.

   821 Your application should store this value and return immediately.

   822 The library will then make appropriate arrangements to store its

   823 internal state and returns to your application with the

   824 MNG_NEEDTIMERWAIT code.

   825 

   826 At that point you should suspend processing and wait the given

   827 interval. Please use your OS features for this. Do not engage some

   828 sort of loop. That is real bad programming practice. Most modern

   829 systems will have some timing functions. A simple wait() function

   830 may suffice, but this may prevent your applications main-task from

   831 running, and possibly prevent the actual update of your output device.

   832 

   833 

   834 .SS The mng_refresh() callback

   835 

   836 The mng_refresh() callback is called whenever the library has

   837 "finished" drawing a new frame onto your canvas, and just before it

   838 will call the mng_settimer() callback.

   839 

   840 This allows you to perform some actions necessary to "refresh" the

   841 canvas onto your output device. Please do NOT suspend processing

   842 inside this callback. This must be handled after the mng_settimer()

   843 callback!

   844 

   845 

   846 .SS Displaying while reading

   847 

   848 This method is preferred if you are reading from a slow input device

   849 (such as a dialup-line) and you wish to start displaying something

   850 as quickly as possible. This functionality is provided mainly for

   851 browser-type applications but may be appropriate for other

   852 applications as well.

   853 

   854 The method is usually used in unison with the suspension-mode of

   855 the read module. A typical implementation would look like this:

   856 

   857     /* initiale library and set required callbacks */

   858 

   859     /* activate suspension-mode */

   860     myretcode = mng_set_suspensionmode (myhandle, 

   861                                         MNG_TRUE);

   862     if (myretcode != MNG_NOERROR)

   863       /* process error */;

   864 

   865     myretcode = mng_readdisplay (myhandle);

   866 

   867     while ((myretcode == MNG_NEEDMOREDATA) ||

   868            (myretcode == MNG_NEEDTIMERWAIT)) {

   869       if (myretcode == MNG_NEEDMOREDATA)

   870         /* wait for more input-data */;

   871       else

   872         /* wait for timer interval */;

   873 

   874       myretcode = mng_display_resume (myhandle);

   875     }

   876 

   877     if (myretcode != MNG_NOERROR)

   878       /* process error */;

   879 

   880 More advanced programming methods may require a different approach,

   881 but the final result should function as in the code above.

   882 

   883 

   884 .SS Displaying after reading

   885 

   886 This method is used to display a file that was previously read.

   887 It is primarily meant for viewers with direct file access, such as

   888 1a local harddisk.

   889 

   890 Once you have successfully read the file, all you need to do is:

   891 

   892     myretcode = mng_display (myhandle);

   893 

   894     while (myretcode == MNG_NEEDTIMERWAIT) {

   895       /* wait for timer interval */;

   896       myretcode = mng_display_resume (myhandle);

   897     }

   898 

   899     if (myretcode != MNG_NOERROR)

   900       /* process error */;

   901 

   902 Again, more advanced programming methods may require a different

   903 approach, but the final result should function as in the code above.

   904 

   905 

   906 .SS Display manipulation

   907 

   908 Several HLAPI functions are provided to allow a user to manipulate

   909 the normal flow of an animation.

   910 

   911 \- mng_display_freeze (mng_handle hHandle)

   912 

   913 This will "freeze" the animation in place.

   914 

   915 \- mng_display_resume (mng_handle hHandle)

   916 

   917 This function can be used to resume a frozen animation, or to force

   918 the library to advance the animation to the next frame.

   919 

   920 \- mng_display_reset (mng_handle hHandle)

   921 

   922 This function will "reset" the animation into its pristine state.

   923 Calling mng_display() afterwards will re-display the animation

   924 from the first frame.

   925 

   926 \- mng_display_golayer (mng_handle hHandle,

   927                         mng_uint32 iLayer)

   928 

   929 \- mng_display_goframe (mng_handle hHandle,

   930                         mng_uint32 iFrame)

   931 

   932 \- mng_display_gotime (mng_handle hHandle,

   933                        mng_uint32 iPlaytime)

   934 

   935 These three functions can be used to "jump" to a specific layer, frame

   936 or timeslot in the animation. You must "freeze" the animation before

   937 using any of these functions.

   938 

   939 All above functions may only be called during a timer interval!

   940 It is the applications responsibility to cleanup any resources with

   941 respect to the timer wait.

   942 

   943 

   944 .SH VI. Writing

   945 

   946 The main focus of the library lies in its displaying capabilites.

   947 But it does offer writing support as well.

   948 You can create and write a file, or you can write a file you

   949 have previously read, providing the storage of chunks was enabled

   950 and active.

   951 

   952 For this to work you must have compiled the library with the

   953 MNG_WRITE_SUPPO1RT and MNG_ACCESS_CHUNKS directives. The standard DLL and

   954 Shared Library have this on by default!

   955 

   956 

   957 .SS Setup

   958 

   959 As always you must have initialized the library and be the owner of

   960 a mng_handle. The following callbacks are essential:

   961 

   962     mng_openstream, mng_writedata, mng_closestream

   963 

   964 You can optionally define:

   965 

   966     mng_errorproc, mng_traceproc

   967 

   968 The creation and writing functions will fail if you are in the middle

   969 of reading, creating or writing a file.

   970 

   971 

   972 .SS Creating a new file

   973 

   974 To start a new file the library must be in its initial state.

   975 First you need to tell the library your intentions:

   976 

   977     myretcode = mng_create (myhandle);

   978     if (myretcode != MNG_NOERROR)

   979       /* process error */;

   980 

   981 After that you start adding the appropriate chunks:

   982 

   983     myretcode = mng_put1chunk_mhdr (myhandle, ...);

   984     if (myretcode != MNG_NOERROR)

   985       /* process error */;

   986 

   987 And so on, and so forth. Note that the library will automatically signal

   988 the logical end of the file by the ending chunk. Also the first chunk

   989 will indicate the library the filetype (eg. PNG, JNG or MNG) and force

   990 the proper signature when writing the file.

   991 

   992 The code above can be simplified, as you can always get the last errorcode

   993 by using the mng_getlasterror() function:

   994 

   995     if ( (mng_putchunk_xxxx (myhandle, ...)) or

   996          (mng_putchunk_xxxx (myhandle, ...)) or

   997              ...etc...                          )

   998       /* process error */;

   999 

  1000 Please note that you must have a pretty good understanding of the chunk

  1001 specification. Unlike the read functions, there are virtually no checks,

  1002 so it is quite possible to write completely wrong files.

  1003 It is a good practice to read back your file into the library to verify

  1004 its integrity.

  1005 

  1006 Once you've got all the chunks added, all you do is:

  1007 

  1008     myretcode mng_write (myhandle);

  1009     if (myretcode != MNG_NOERROR)

  1010       /* process error */;

  1011 

  1012 And presto. You're done. The real work is of course carried out in

  1013 your callbacks. Note that this is a single operation as opposed to

  1014 the read & display functions that may return with MNG_NEEDMOREDATA

  1015 and/or MNG_NEEDTIMERWAIT. The write function just does the job, and

  1016 only returns after it's finished or if it encounters some

  1017 unrecoverable error.

  1018 

  1019 

  1020 .SS Writing a previously read file

  1021 

  1022 If you have already successfully read a file, you can use the library to

  1023 write it out as a copy or something. You MUST have compiled the library

  1024 with the MNG_STORE_CHUNKS directive, and you must have done

  1025 mng_set_storechunks (myhandle, MNG_TRUE).

  1026 

  1027 This doesn't require the MNG_ACCESS_CHUNKS directive, unless you want

  1028 to fiddle with the chunks as well.

  1029 

  1030 Again all you need to do is:

  1031 

  1032     myretcode mng_write (myhandle);

  1033     if (myretcode != MNG_NOERROR)

  1034       /* process error */;

  1035 

  1036 

  1037 .SH VII. Modifying/Customizing libmng:

  1038 

  1039 not finished yet

  1040 

  1041 .SS Compilation directives

  1042 

  1043 not finished yet

  1044 

  1045 .SS Platform dependant modification

  1046 

  1047 not finished yet

  1048 

  1049 .SH "SEE ALSO"

  1050 .IR mng(5), jng(5), png(5), libpng(3)

  1051 

  1052 .LP

  1053 libmng :

  1054 .IP

  1055 .br

  1056 http://www.libmng.com

  1057 

  1058 .LP

  1059 zlib :

  1060 .IP

  1061 .br

  1062 http://www.info-zip.org/pub/infozip/zlib/

  1063 

  1064 .LP

  1065 IJG JPEG library :

  1066 .IP

  1067 .br

  1068 http://www.ijg.org

  1069 

  1070 .LP

  1071 lcms (little CMS) by Marti Maria Saguer :

  1072 .IP

  1073 .br

  1074 http://www.littlecms.com/

  1075 

  1076 .LP

  1077 MNG specification:

  1078 .IP

  1079 .br

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

  1081 

  1082 .LP

  1083 In the case of any inconsistency between the MNG specification

  1084 and this library, the specification takes precedence.

  1085 

  1086 

  1087 .SH AUTHORS

  1088 This man page: Gerard Juyn

  1089 <gerard at libmng.com>

  1090 

  1091 The contributing authors would like to thank all those who helped

  1092 with testing, bug fixes, and patience.  This wouldn't have been

  1093 possible without all of you!!!

  1094 

  1095 

  1096 .SH COPYRIGHT NOTICE:

  1097 

  1098 Copyright (c) 2000-2002 Gerard Juyn

  1099 

  1100 For the purposes of this copyright and license, "Contributing Authors"

  1101 is defined as the following set of individuals:

  1102 

  1103    Gerard Juyn

  1104 

  1105 The MNG Library is supplied "AS IS".  The Contributing Authors

  1106 disclaim all warranties, expressed or implied, including, without

  1107 limitation, the warranties of merchantability and of fitness for any

  1108 purpose.  The Contributing Authors assume no liability for direct,

  1109 indirect, incidental, special, exemplary, or consequential damages,

  1110 which may result from the use of the MNG Library, even if advised of

  1111 the possibility of such damage.

  1112 

  1113 Permission is hereby granted to use, copy, modify, and distribute this

  1114 source code, or portions hereof, for any purpose, without fee, subject

  1115 to the following restrictions:

  1116 

  1117 1. The origin of this source code must not be misrepresented;

  1118 you must not claim that you wrote the original software.

  1119 

  1120 2. Altered versions must be plainly marked as such and must not be

  1121 misrepresented as being the original source.

  1122 

  1123 3. This Copyright notice may not be removed or altered from any source

  1124 or altered source distribution.

  1125 

  1126 The Contributing Authors specifically permit, without fee, and

  1127 encourage the use of this source code as a component to supporting

  1128 the MNG and JNG file format in commercial products.  If you use this

  1129 source code in a product, acknowledgment would be highly appreciated.

  1130 

  1131 .SH Remarks

  1132 

  1133 Parts of this software have been adapted from the libpng library.

  1134 Although this library supports all features from the PNG specification

  1135 (as MNG descends from it) it does not require the libpng library.