NAME
    Image::XBin - Load, create, manipulate and save XBin image files

SYNOPSIS
            use Image::XBin;

            # Read in a file...
            my $img = Image::XBin->new( file => 'myxbin.xb' );

            # Image width and height
            my $w = $img->width;
            my $h = $img->height;

            # get and put "pixels"
            my $pixel = $img->getpixel( $x, $y );
            $img->putpixel( $x, $y, $pixel );

            # font (XBin::Font)
            my $font = $img->font;

            # palette (XBin::Palette)
            my $palette = $img->palette;

            # save the data to a file
            $img->write( file => 'x.xb' );

DESCRIPTION
    XBin stands for "eXtended BIN" -- an extention to the normal raw-image
    BIN files.

    XBin features:

    * allows for binary images up to 65536 columns wide, and 65536 lines
    high
    * can have an alternate set of palette colors either in blink or in
    non-blink mode
    * can have different textmode fonts from 1 to 32 scanlines high,
    consisting of either 256 or 512 different characters
    * can be compressed

    XBin file stucture:

            +------------+
            | Header     |
            +------------+
            | Palette    |
            +------------+
            | Font       |
            +------------+
            | Image Data |
            +------------+

    Note, the only required element is a header. See the XBin specs for for
    information. http://www.acid.org/info/xbin/xbin.htm

INSTALLATION
    To install this module via Module::Build:

            perl Build.PL
            ./Build         # or `perl Build`
            ./Build test    # or `perl Build test`
            ./Build install # or `perl Build install`

    To install this module via ExtUtils::MakeMaker:

            perl Makefile.PL
            make
            make test
            make install

METHODS
  new( %options )
    Creates a new XBin image. Currently only reads in data.

            # filename
            $xbin = Image::XBin->new( file => 'file.xb' );
        
            # file handle
            $xbin = Image::XBin->new( handle => $handle );

            # string
            $xbin = Image::XBin->new( string => $string );

  clear(  )
    Clears any in-memory data.

  read( %options )
    Explicitly reads in an XBin.

  write( %options )
    Write the XBin data to a file, handle of string.

  as_string( )
    Returns the XBin data as a string - suitable for saving.

  as_png( [%options] )
    Returns a binary PNG version of the image.

            # Thumbnail -- Default
            $xbin->as_png( mode => 'thumbnail' );

            # Full size
            $xbin->as_png( mode => 'full' );

    This function is just a wrapper around as_png_thumbnail() and
    as_png_full().

  as_png_thumbnail( [%options] )
    Creates a thumbnail version of the XBin.

  as_png_full( [%options] )
    Creates a full-size replica of the image. You can pass a "crop" option
    to crop the image at certain height.

            # Crop it after 25 (text-mode) rows
            $xbin->as_png_full( crop => 25 );

  has_palette( )
    Returns true if the file has a palette defined.

  has_font( )
    Returns true if the file has a font defined.

  is_compressed( )
    Returns true if the data was (or is to be) compressed

  is_nonblink( )
    Returns true if the file is in non-blink mode.

  has_512chars( )
    Returns true if the font associated with the XBin has 512 characters

  sauce( [File::SAUCE] )
    Gets / sets the SAUCE object associated with the XBin.

  putpixel( $x, $y, $pixel )
    Sets the pixel at $x, $y with $pixel (which should be an
    Image::XBin::Pixel).

  getpixel( $x, $y )
    Returns the Image::XBin::Pixel object at $x, $y (or undef).

  pixel( [$x, $y, $pixel] )
    Generic get / set method used by both getpixel and putpixel.

  font( [Image::XBin::Font] )
    Gets or sets the font. Must be of type Image::XBin::Font. Passing
    anything but that type will remove the font and change related header
    data.

  palette( [Image::XBin::Palette] )
    Gets or sets the palette. Must be of type Image::XBin::Palette. Passing
    anything but that type will remove the font and related header data.

  compress( [true or false] )
    Get / sets the compression header value to true or false. Affect the
    output from as_string() and write().

  width( )
    Returns the image width.

  height( )
    Returns the image height.

TODO
    * fix write() method to include compression
    * use new()'s options to create a new file from scratch

AUTHOR
    * Brian Cassidy <bricas@cpan.org>

COPYRIGHT AND LICENSE
    Copyright 2005 by Brian Cassidy

    This library is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.