libmng.h

奇趣公司比较新的qt/emd版本

/* *                                                                        * */
/* *  note that version_so & version_dll will always remain equal so it     * */
/* *  doesn't matter which one is called to do version-checking; they are   * */
/* *  just provided for their target platform                               * */
/* *                                                                        * */
/* ************************************************************************** */

#define MNG_VERSION_TEXT    "1.0.9"
#define MNG_VERSION_SO      1          /* eg. libmng.so.1  */
#define MNG_VERSION_DLL     1          /* but: libmng.dll (!) */
#define MNG_VERSION_MAJOR   1
#define MNG_VERSION_MINOR   0
#define MNG_VERSION_RELEASE 9
#define MNG_VERSION_BETA    MNG_FALSE

MNG_EXT mng_pchar MNG_DECL mng_version_text      (void);
MNG_EXT mng_uint8 MNG_DECL mng_version_so        (void);
MNG_EXT mng_uint8 MNG_DECL mng_version_dll       (void);
MNG_EXT mng_uint8 MNG_DECL mng_version_major     (void);
MNG_EXT mng_uint8 MNG_DECL mng_version_minor     (void);
MNG_EXT mng_uint8 MNG_DECL mng_version_release   (void);
MNG_EXT mng_bool  MNG_DECL mng_version_beta      (void);

/* use the following call to check wether the version of libmng your app
   is using supports the given function; this is useful in apps that dynamically
   load the library to make sure a certain function will work; the result will
   be MNG_TRUE if the given function is implemented in this version of the library;
   Major/Minor/Version indicate the version the function became available;
   (if these fields are zero the function is not yet implemented!) */
#ifdef MNG_SUPPORT_FUNCQUERY
MNG_EXT mng_bool  MNG_DECL mng_supports_func     (mng_pchar  zFunction,
                                                  mng_uint8* iMajor,
                                                  mng_uint8* iMinor,
                                                  mng_uint8* iRelease);
#endif

/* ************************************************************************** */
/* *                                                                        * */
/* *  MNG/PNG specification level conformance                               * */
/* *                                                                        * */
/* ************************************************************************** */

#define MNG_PNG_VERSION     "1.2"
#define MNG_PNG_VERSION_MAJ 1
#define MNG_PNG_VERSION_MIN 2

#define MNG_MNG_VERSION     "1.1"
#define MNG_MNG_VERSION_MAJ 1
#define MNG_MNG_VERSION_MIN 1
#define MNG_MNG_DRAFT       99         /* deprecated;
                                          only used for nEED "MNG DRAFT nn" */

/* ************************************************************************** */
/* *                                                                        * */
/* *  High-level application functions                                      * */
/* *                                                                        * */
/* ************************************************************************** */

/* library initialization function */
/* must be the first called before anything can be done at all */
/* initializes internal datastructure(s) */
MNG_EXT mng_handle  MNG_DECL mng_initialize      (mng_ptr       pUserdata,
                                                  mng_memalloc  fMemalloc,
                                                  mng_memfree   fMemfree,
                                                  mng_traceproc fTraceproc);

/* library reset function */
/* can be used to re-initialize the library, so another image can be
   processed. there's absolutely no harm in calling it, even when it's not
   really necessary */
MNG_EXT mng_retcode MNG_DECL mng_reset           (mng_handle    hHandle);

/* library cleanup function */
/* must be the last called to clean up internal datastructure(s) */
MNG_EXT mng_retcode MNG_DECL mng_cleanup         (mng_handle*   hHandle);

/* high-level read functions */
/* use mng_read if you simply want to read a Network Graphic */
/* mng_read_resume is used in I/O-read-suspension scenarios, where the
   "readdata" callback may return FALSE & length=0 indicating it's buffer is
   depleted or too short to supply the required bytes, and the buffer needs
   to be refilled; libmng will return the errorcode MNG_NEEDMOREDATA telling
   the app to refill it's read-buffer after which it must call mng_read_resume
   (or mng_display_resume if it also displaying the image simultaneously) */
#ifdef MNG_SUPPORT_READ
MNG_EXT mng_retcode MNG_DECL mng_read            (mng_handle    hHandle);
MNG_EXT mng_retcode MNG_DECL mng_read_resume     (mng_handle    hHandle);
#endif

/* high-level "data push" functions */
/* these functions can be used in situations where data is streaming into the
   application and needs to be buffered by libmng before it is actually
   requested by libmng itself. the pushing complements the normal reading
   mechanism, but applications can decide to always return "0 bytes read" to
   make libmng go into suspension mode with the returncode MNG_NEEDMOREDATA */
/* mng_read_pushdata can be used to push blobs of data of arbitrary size;
   mng_read_pushsig and mng_read_pushchunk can be used if the application
   has already done some low-level decoding (eg. at the chunk level) */
/* the data being pushed into libmng with mng_read_pushdata *must* contain
   the regular 4-byte chunklength, but *must not* contain it with
   mng_read_pushchunk!!! */
/* mng_read_pushsig is used to prevent libmng from trying to parse the regular
   PNG/JNG/MNG signature bytes; the application must have done this itself
   and *must* indicate the proper type in the function call or things will
   go amiss!!
   also you *must* call this first, so pretty much right after mng_initialize
   and certainly before any call to mng_read or mng_readdisplay !!!! */
/* IMPORTANT!!! data can only be safely pushed when libmng is in a
   "wait" state; eg. during MNG_NEEDTIMERWAIT, MNG_NEEDSECTIONWAIT or
   MNG_NEEDMOREDATA !!! this just means you can't have one thread displaying
   and another thread pushing data !!! */
/* if bOwnership = MNG_TRUE, libmng will retain the supplied pointer and
   *will* expect the buffer to remain available until libmng is finished
   with it; what happens then depends on whether or not you have set the
   releasedata() callback; if this is set than the supplied buffer will
   be returned through this callback and your application can take care of
   cleaning it up, otherwise libmng will use its internal freeing mechanism
   (which, depending on compile-options, will be the standard C free() call,
   or the memfree() callback */
/* if bOwnership = MNG_FALSE, libmng will just copy the data into its own
   buffers and dispose of it in the normal way */
#ifdef MNG_SUPPORT_READ
MNG_EXT mng_retcode MNG_DECL mng_read_pushdata   (mng_handle    hHandle,
                                                  mng_ptr       pData,
                                                  mng_size_t    iLength,
                                                  mng_bool      bTakeownership);
MNG_EXT mng_retcode MNG_DECL mng_read_pushsig    (mng_handle    hHandle,
                                                  mng_imgtype   eSigtype);
MNG_EXT mng_retcode MNG_DECL mng_read_pushchunk  (mng_handle    hHandle,
                                                  mng_ptr       pChunk,
                                                  mng_size_t    iLength,
                                                  mng_bool      bTakeownership);
#endif

/* high-level write & create functions */
/* use this if you want to write a previously read Network Graphic or
   if you want to create a new graphic and write it */
/* to write a previously read graphic you must have defined MNG_STORE_CHUNKS */
/* to create a new graphic you'll also need access to the chunks
   (eg. #define MNG_ACCESS_CHUNKS !) */
#ifdef MNG_SUPPORT_WRITE
MNG_EXT mng_retcode MNG_DECL mng_write           (mng_handle    hHandle);
MNG_EXT mng_retcode MNG_DECL mng_create          (mng_handle    hHandle);
#endif

/* high-level display functions */
/* use these to display a previously read or created graphic or
   to read & display a graphic simultaneously */
/* mng_display_resume should be called after a timer-interval
   expires that was set through the settimer-callback, after a
   read suspension-break, or, to resume an animation after a call
   to mng_display_freeze/mng_display_reset */
/* mng_display_freeze thru mng_display_gotime can be used to influence
   the display of an image, BUT ONLY if it has been completely read! */
#ifdef MNG_SUPPORT_DISPLAY
#ifdef MNG_SUPPORT_READ
MNG_EXT mng_retcode MNG_DECL mng_readdisplay     (mng_handle    hHandle);
#endif
MNG_EXT mng_retcode MNG_DECL mng_display         (mng_handle    hHandle);
MNG_EXT mng_retcode MNG_DECL mng_display_resume  (mng_handle    hHandle);
MNG_EXT mng_retcode MNG_DECL mng_display_freeze  (mng_handle    hHandle);
MNG_EXT mng_retcode MNG_DECL mng_display_reset   (mng_handle    hHandle);
#ifndef MNG_NO_DISPLAY_GO_SUPPORTED
MNG_EXT mng_retcode MNG_DECL mng_display_goframe (mng_handle    hHandle,
                                                  mng_uint32    iFramenr);
MNG_EXT mng_retcode MNG_DECL mng_display_golayer (mng_handle    hHandle,
                                                  mng_uint32    iLayernr);
MNG_EXT mng_retcode MNG_DECL mng_display_gotime  (mng_handle    hHandle,
                                                  mng_uint32    iPlaytime);
#endif
#endif /* MNG_SUPPORT_DISPLAY */

/* event processing function */
/* this needs to be called by the app when dynamic MNG is enabled and
   a specific event occurs in the user-interface */
#if defined(MNG_SUPPORT_DISPLAY) && defined(MNG_SUPPORT_DYNAMICMNG)
MNG_EXT mng_retcode MNG_DECL mng_trapevent       (mng_handle    hHandle,
                                                  mng_uint8     iEventtype,
                                                  mng_int32     iX,
                                                  mng_int32     iY);
#endif

/* error reporting function */
/* use this if you need more detailed info on the last error */
/* iExtra1 & iExtra2 may contain errorcodes from zlib, jpeg, etc... */
/* zErrortext will only be filled if you #define MNG_ERROR_TELLTALE */
MNG_EXT mng_retcode MNG_DECL mng_getlasterror    (mng_handle    hHandle,
                                                  mng_int8*     iSeverity,
                                                  mng_chunkid*  iChunkname,
                                                  mng_uint32*   iChunkseq,
                                                  mng_int32*    iExtra1,
                                                  mng_int32*    iExtra2,
                                                  mng_pchar*    zErrortext);

/* ************************************************************************** */
/* *                                                                        * */
/* *  Callback set functions                                                * */
/* *                                                                        * */
/* ************************************************************************** */

/* memory callbacks */
/* called to allocate and release internal datastructures */
#ifndef MNG_INTERNAL_MEMMNGMT
MNG_EXT mng_retcode MNG_DECL mng_setcb_memalloc      (mng_handle        hHandle,
                                                      mng_memalloc      fProc);
MNG_EXT mng_retcode MNG_DECL mng_setcb_memfree       (mng_handle        hHandle,
                                                      mng_memfree       fProc);
#endif /* MNG_INTERNAL_MEMMNGMT */

/* open- & close-stream callbacks */
/* called to open & close streams for input or output */
#if defined(MNG_SUPPORT_READ) || defined(MNG_SUPPORT_WRITE)
#ifndef MNG_NO_OPEN_CLOSE_STREAM
MNG_EXT mng_retcode MNG_DECL mng_setcb_openstream    (mng_handle        hHandle,
                                                      mng_openstream    fProc);
MNG_EXT mng_retcode MNG_DECL mng_setcb_closestream   (mng_handle        hHandle,
                                                      mng_closestream   fProc);