diff options
Diffstat (limited to 'src/3rdparty/libmng/doc/man/libmng.3')
| -rw-r--r-- | src/3rdparty/libmng/doc/man/libmng.3 | 1147 |
1 files changed, 1147 insertions, 0 deletions
diff --git a/src/3rdparty/libmng/doc/man/libmng.3 b/src/3rdparty/libmng/doc/man/libmng.3 new file mode 100644 index 0000000..54d6ad3 --- /dev/null +++ b/src/3rdparty/libmng/doc/man/libmng.3 @@ -0,0 +1,1147 @@ +.TH LIBMNG 3 "June 23rd, 2002" +.SH NAME +libmng \- Multiple-image Network Graphics (MNG) Reference Library 1.0.4 +.SH SYNOPSIS +\fI\fB + +\fB#include <libmng.h>\fP + + +.SH DESCRIPTION +The +.I libmng +library supports decoding, displaying, encoding, and various other +manipulations of the Multiple-image Network Graphics (MNG) format +image files. It uses the +.IR zlib(3) +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. + + +.SH 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 MNG-1.0 specification should be shortly available at +<http://www.libpng.org/pub/mng>. + +Other information about MNG can be found at the MNG home page, +<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.info-zip.org/pub/infozip/zlib/>. +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> + + +.SH 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. + + +.SH III. Housekeeping + + +.SS 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. + + +.SS 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. + + +.SS 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. + + +.SS 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(). + + +.SH 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! + + +.SS 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. + + +.SS 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(). + + +.SS 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! + + +.SS 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. + + +.SS 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 */; + + +.SH V. Displaying + + +.SS 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! + + +.SS 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. + + +.SS 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. + +.SS 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. + +.SS 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. + +.SS 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. + + +.SS 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. + +.SS 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. + +.SS 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. + +.SS 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. + +.SS 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!!! + + +.SS 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. + + +.SS 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! + + +.SS 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. + + +.SS 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. + + +.SS 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. + + +.SH 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! + + +.SS 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. + + +.SS 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_put1chunk_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. + + +.SS 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 */; + + +.SH VII. Modifying/Customizing libmng: + +not finished yet + +.SS Compilation directives + +not finished yet + +.SS Platform dependant modification + +not finished yet + +.SH "SEE ALSO" +.IR mng(5), jng(5), png(5), libpng(3) + +.LP +libmng : +.IP +.br +http://www.libmng.com + +.LP +zlib : +.IP +.br +http://www.info-zip.org/pub/infozip/zlib/ + +.LP +IJG JPEG library : +.IP +.br +http://www.ijg.org + +.LP +lcms (little CMS) by Marti Maria Saguer : +.IP +.br +http://www.littlecms.com/ + +.LP +MNG specification: +.IP +.br +http://www.libpng.org/pub/mng + +.LP +In the case of any inconsistency between the MNG specification +and this library, the specification takes precedence. + + +.SH AUTHORS +This man page: Gerard Juyn + +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!!! + + +.SH COPYRIGHT NOTICE: + +Copyright (c) 2000 Gerard Juyn + +For the purposes of this copyright and license, "Contributing Authors" +is defined as the following set of individuals: + + Gerard Juyn + Tim Rowley + +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. + +.SH 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) + +.\" end of man page |