Graphics::MNG version 0.01
==========================



NAME

Graphics::MNG - Perl extension for the MNG library from Gerard Juyn (gerard@libmng.com)


SYNOPSIS

   # OO-interface
   use Graphics::MNG;
   my $it=['user data'];
   my $obj = new Graphics::MNG (                   ); # w/o user data
   my $obj = new Graphics::MNG ( undef             ); # w/o user data
   my $obj = new Graphics::MNG ( $it               ); # w/  user data
   my $obj = Graphics::MNG::new(                   ); # w/o name w/o data
   my $obj = Graphics::MNG::new('Graphics::MNG'    ); # w/  name w/o data
   my $obj = Graphics::MNG::new('Graphics::MNG',$it); # w/  name w/  data
   $obj->set_userdata(['user data']);
   my $data = $obj->get_userdata();
   print @$data[0],"\n";
   undef $obj;

   # functional interface
   use Graphics::MNG qw( :fns );
   my $handle = initialize( ['more user data'] );
   die "Can't get an MNG handle" if ( MNG_NULL == $handle );
   my $rv = reset( $handle );
   die "Can't reset the MNG handle" unless ( MNG_NOERROR == $rv );
   my $data = get_userdata( $handle );
   print @$data[0],"\n";
   $rv = cleanup( $handle );
   die "handle not NULL" unless ( MNG_NULL == $handle );


DESCRIPTION

   This software is pre-alpha.  Use at your own risk.

   Please visit http://www.libmng.com/ to learn all about the new 
   MNG format.

   MNG (which stands for Moving Network Graphics) is a spin-off of 
   the PNG format, which is already gaining popularity over the 
   GIF format. MNG adds the aspect of animation that PNG lacks.

   The Gd module (by Lincoln Stein) supports PNG formats, but MNG is 
   more complicated. It would be cumbersome to add support to the Gd 
   interface for MNG.

   Gerard Juyn as been kind enough to bring us a C-library that 
   supports MNG, so now I thought I'd do my part in bringing you a 
   Perl interface to that library.

   The Graphics::MNG module is an attempt to provide an "accurate"
   interface to the MNG graphics library.  This means that the Perl
   functions supported in this module should look very much like the
   functions in the MNG library interface.

   This module supports both a functional and an OO interface to the 
   MNG library.


EXPORT

   Everthing under the :constants tag is exported by default.

   Ideally, you'll use one of the incantations of new() to get 
   yourself an object reference, and you'll call methods on that.


EXPORTABLE CONSTANTS

   :all               -- everything
   :callback_types    -- enum list of callback types (MNG_TYPE_*)
   :canvas            -- constants for canvas ops (MNG_CANVAS_*)
   :canvas_fns        -- functions for canvas ops (MNG_CANVAS_*)
   :chunk_fns         -- functions for chunk ops (getchunk_*,putchunk_*)
   :chunk_names       -- constants for chunk ops (MNG_UINT_*)
   :chunk_properties  -- constants for chunk ops
   :compile_options   -- constants describing how this extension was built
   :constants         -- constants which are commonly used
                         (MNG_FALSE,   MNG_TRUE, 
                          MNG_NOERROR, MNG_NULL, MNG_INVALIDHANDLE)
   :errors            -- constants returned as error values
   :fns               -- functions for the MNG functional interface
   :misc              -- constants misc.  (MNG_SUSPEND*)
   :version           -- functions to return various version numbers
                         (MNG,PNG,draft,etc.)
   :IJG               -- constants IJG parameters for compression
   :ZLIB              -- constants zlib compression params for deflateinit2


INTERFACE FUNCTIONS/METHODS

   In some cases it is convenient to change the Perl interface to make 
   it more convenient to use from within Perl.  A good example of this 
   is any mng_get*() functions that returned values via pointers in the 
   parameter list.  Most or all of these will return an array of values, 
   and will only accept the input parameters.

   The OO-I/F is the same as the functional interface, except that you
   new() your handle into existence, and you undef() it out.  Oh, and 
   you don't pass it as the first parameter to any of the methods -- 
   that's done for you when you use the -> calling syntax to call a
   method.

   There are a *lot* of interface functions in the MNG library.  I'd 
   love to list them all here, but you're really better off opening up 
   the libmng.h file, related documentation, or the Graphics/MNG.pm file 
   and looking at the list of exported functions.  I'll try to make a 
   list here of the functions that deviate in interface characteristics 
   from those found in the MNG library itself.

   I doubt that I've implemented the Perl interface correctly for all 
   of them.  You will find bugs.  Sorry about that.


LIMITATIONS

   The MNG library is designed around the concept of callbacks.  I've 
   tried to make the Perl interface closely model the library interface.  
   That means that you'll be working with callback functions.  Depending 
   on your point of view, that's a limitation.

   This Perl module is in the pre-alpha stage.  That means that you'll 
   be lucky to compile it, let alone use it effectively without tripping 
   over bugs.

   The MNG library has limitations of its own, please visit the MNG 
   homepage to learn about them.


PREREQUISITES/DEPENDENCIES

   You'll need a compiled MNG library, complete with header files, in 
   order to build this Perl module.

   MNG requires some or all of the following support libraries:
   - lcms (little CMS)
   - libjpeg
   - libz

   Specifically, I compile the MNG library (static library, NOT a DLL)
   using MSVC++ with the following compilation flags:
      MNG_FULL_CMS, MNG_INTERNAL_MEMMNGMT, NON_WINDOWS, 
      MNG_BUILD_SO, MNG_SUPPORT_TRACE


INSTALLATION

   Since this is pre-alpha software...
   - compile the MNG as a static library (Win32) or as a shared library
   - edit Makefile.PL as appropriate for your header file and lib paths

   Then you can install this module by typing the following:
   perl Makefile.PL
   make
   make test
   make install


KNOWN BUGS

   I haven't successfully created a file with this interface (yet).

   You may have noticed that the "mng_" prefix has been removed from all of
   the functions.  This was done to make the OO-I/F look prettier.  However,
   if you import the functional interface, you'll get read() and write()
   in your namespace, thus clashing with Perl's built-in functions.  I need
   to provide an alternate name for these.  In the meantime, I suggest that
   you use sysread() and syswrite() in your callbacks.  Even better, use
   the OO-I/F and don't import qw(:fns).

   I'm developing exclusively on Win32 for right now, although everything
   *should* work well for any other platform that the MNG library
   supports.

   I'm pretty sure that I have *not* gotten all of the appropriate #ifdef
   protection around parts of the XS code that may be affected by MNG
   compilation flags.
   

CHANGES AND FUTURE DEVELOPMENT

   This is pre-alpha software.  Expect the worst.  Hope for the best.

   For any functions that return or accept an array of integers or 
   structs, I plan (eventually) to provide a Perl interface that accepts 
   an array of integers or structs (the structs themselves probably being 
   represented as arrays or hashes).  Right now, you'll need to pack() 
   and unpack() the string.


AUTHOR

   David P. Mott (dpmott@sep.com)


SUPPORT

   The '.com' at the end of my email address means that I work for a
   living.

   If you see a problem, try to fix it.  If you can fix it, write a 
   test  case for it.  If you get all of that done, send me the fix 
   and the test  case, and I'll include it in the next release.

   If you can't fix it, or don't know how to test it, go ahead and send 
   me some email.  I'll see what I can do.

   If you want to maintain this module, by all means mail me and I'll
   get you set up.

   Releases will happen approximately whenever I feel like I have 
   something worthwhile to release, or whenever I get a whole bunch of 
   email from people like you demanding a release.


COPYRIGHT AND LICENCE

   The Graphics::MNG module is Copyright (c) 2001 David P. Mott, USA
   (dpmott@sep.com)
   All rights reserved.

   This program is free software; you can redistribute it and/or
   modify it under the same terms as Perl itself (i.e. GPL or Artistic).

   See the the Perl README file for more details.
   (maybe here: http://www.perldoc.com/perl5.6.1/README.html)

   For more info on GNU software and the GPL see http://www.gnu.org/
   For more info on the Artistic license see
      http://www.perl.com/perl/misc/Artistic.html

   THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
   WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
   MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.


SEE ALSO

L<perl>.

