diff options
Diffstat (limited to 'tqtinterface/qt4/src/3rdparty/libmng/doc/man/libmng.3')
| -rw-r--r-- | tqtinterface/qt4/src/3rdparty/libmng/doc/man/libmng.3 | 1147 |
1 files changed, 0 insertions, 1147 deletions
diff --git a/tqtinterface/qt4/src/3rdparty/libmng/doc/man/libmng.3 b/tqtinterface/qt4/src/3rdparty/libmng/doc/man/libmng.3 deleted file mode 100644 index 7a6f544..0000000 --- a/tqtinterface/qt4/src/3rdparty/libmng/doc/man/libmng.3 +++ /dev/null @@ -1,1147 +0,0 @@ -.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 tqdevice. - -\- 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 tqdevice, 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 tqdevice, 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 tqdevices 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 tqdevice. - -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 tqdevice. - - -.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 tqdevice. 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 tqdevice -(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 -<gerard@libmng.com> - -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 |