=head1	NAME

dkbif - bitmap image file library

=head1	SYNOPSIS

 #include <dkbif.h>

 dk_bif_ptr
 dkbif_open(void);
 void
 dkbif_close(dk_bif_ptr p);
 int
 dkbif_read_header(dk_bif_ptr p, FILE *f, char *fn, int tp, char *tmpfn);
 int
 dkbif_read_data(dk_bif_ptr p, FILE *f);
 unsigned long
 dkbif_number_of_frames(dk_bif_ptr p);
 int
 dkbif_set_frame(dk_bif_ptr p, unsigned long fno);
 int
 dkbif_get_channels(dk_bif_ptr p);
 unsigned short
 dkbif_get_bits_per_component(dk_bif_ptr_p);
 int
 dkbif_set_bits_per_component(dk_bif_ptr p, unsigned short bpc);
 int
 dkbif_set_mixing(dk_bif_ptr p, int fl, double r, double g, double b);
 int
 dkbif_set_mask_trigger_level(dk_bif_ptr p, double tl);
 unsigned long
 dkbif_get_width(dk_bif_ptr p);
 unsigned long
 dkbif_get_height(dk_bif_ptr p);
 double
 dkbif_get_real_width(dk_bif_ptr p);
 double
 dkbif_get_real_height(dk_bif_ptr p);
 unsigned short
 dkbif_get_red(dk_bif_ptr p, unsigned long x, unsigned long y);
 unsigned short
 dkbif_get_green(dk_bif_ptr p, unsigned long x, unsigned long y);
 unsigned short
 dkbif_get_blue(dk_bif_ptr p, unsigned long x, unsigned long y);
 unsigned short
 dkbif_get_gray(dk_bif_ptr p, unsigned long x, unsigned long y);
 unsigned short
 dkbif_get_alpha(dk_bif_ptr p, unsigned long x, unsigned long y);
 unsigned short
 dkbif_get_mask(dk_bif_ptr p, unsigned long x, unsigned long y);
 int
 dkbif_get_type(char *fn);
 void
 dkbif_allow_fast_ntsc(dk_bif_ptr p, int fl);
 int
 dkbif_get_must_scale(dk_bif_ptr p);
 double
 dkbif_get_sf_x(dk_bif_ptr p);
 double
 dkbif_get_sf_y(dk_bif_ptr p);
 void
 dkbif_set_width_height_sufficient(dk_bif_ptr p, int fl);
 int
 dk_bif_can_handle(int t);
 int
 dk_bif_can_handle_name(char *fn);

=head1	DESCRIPTION

The dkbif library reads bitmap image files (PNG, JPEG, NetPBM).
TIFF files can be read if the TIFFReadRGBAImage() function from the
libtiff library can open them.

Two steps are necessary to read a file. The first step is to read image
header information (width, height, number of channels, number of
bits per component...). The optional second step reads the image data.

An alpha channel in the image can be used to either mix against a background
color and/or to create an image mask. You can provide a default background
color. If the input image contains background color information you can choose
to either use background information from input file or to use the default
background color.

If you want to change the number of bits per component the dkbif library
can do this conversion for you.

The dkbif library uses other libraries (i.e. libpng, jpeglib, NetPBM
and libtiff) to do the work ``behind the scenes'', application programmers
only have to deal with the dklibs API.

The dkbif_open() function allocates and initializes data for one input file
and returns the pointer to the data. This pointer can be used for the
subsequent operations. Use dkbif_close() to close the image file,
deallocate memory and release the ressources.

The dkbif_set_width_height_sufficient() function can be used to tell the dkbif
library, whether or not it is sufficient to retrieve width and height
information when dkbif_read_header() is called. A value I<fl>!=0 indicates
that retrieving width and height information is sufficient when running
dkbif_read_header().

The dkbif_get_type() function returns a numeric representation of the
image type (DKBIF_TYPE_...) based on the filename provided in
I<fn>. On error the function returns DKBIF_TYPE_UNKNOWN.

The dkbif_read_header() function opens a bitmap image file and attempts
to read image header information.
The file I<f> must be opened to read the image file
in binary mode. I<tp> is the file type returned by dkbif_get_type().

Most libraries use a FILE pointer to read data but other libraries
-- i.e. libtiff -- need a filename. To use these libraries
dkbif_read_header() copies the contents of the input file to a temporary
file and provides the filename to the ``behind-the-scenes''-library.
A filename for the temporary file must be specified in parameter I<tmpfn>.

By default header information includes
image width, image height, number of color channels, number of
bits per component. If you need image width and height only, run
dkbif_set_width_height_sufficient() before running dkbif_read_header().

The dkbif_read_data() function reads the image data. This
function can be called only if dkbif_read_header() returned successfully.

The dkbif_number_of_frames() function returns the number of frames
in the image. Some image file types -- i.e. PNG -- contain one frame (picture)
per image, other image file types can contain multiple frames in one file.

The dkbif_set_frame() function sets the number of the current frame
(the frame to process). After dkbif_read_data() the current frame is
0 by default (the first frame in the file). The dkbif_set_frame() function
can be used to process the other frames in the file.

The dkbif_get_channels() function returns the number of color channels
for the current frame (1=gray, 2=gray+alpha, 3=rgb, 4=rgb+alpha).

The dkbif_get_bits_per_component() function returns the number of bits
per component in the current frame.

The dkbif_set_bits_per_component() function sets the number of bits
per component returned by the dkbif_get_...() functions.

Note: The dkbif_get_bits_per_component() function always returns the
number of bits per component as stored in the file. This result is
independent from the dkbif_set_bits_per_component() setting.
The dkbif_set_bits_per_component() setting affects the results returned
by dkbif_get_red(), dkbif_get_green(), dkbif_get_blue(), dkbif_get_gray(),
dkbif_get_alpha() and dkbif_get_mask() only.

The dkbif_allow_fast_ntsc() function allows or denies use of
a fast RGB to gray conversion using approximately the NTSC
color to gray formula. The ``fast'' conversion uses unsigned long
values, the ``normal'' conversion uses double values.
I did not do any measurement to compare ``fast'' against
``normal'' conversion, not even to verify the ``fast'' conversion
is faster than ``normal'' conversion. I only use the
normal conversion.

The dkbif_set_mixing() function sets up mixing against a background color.
The flag I<fl> decides whether or not to mix: 0 means no mixing at all,
1 means mixing against the background provided by the background color
chunk in the image file
(I<r>, I<g> and I<b> are used if there is no background color chunk in the file)
and 2 means always mixing against I<r>, I<g> and I<b>.

The dkbif_set_mask_trigger_level() function sets up the trigger level for
converting an alpha channel into an image mask. The parameter I<tl> must
be in the range 0.0<=I<tl><=1.0.

The dkbif_get_width() and dkbif_get_height() functions return the frame
size in pixels.

The dkbif_get_real_width() and dkbif_get_real_height() functions return
the frame size in PS points. If the image contains no resolution data
the functions return the image size in pixels (a resolution of
72 dpi is used as default resolution).

The dkbif_get_red(), dkbif_get_green(), dkbif_get_blue(), dkbif_get_gray(),
and dkbif_get_alpha() functions return information about a pixel.

The dkbif_get_must_scale() function checks whether or not there is
resolution data in the file or a papersize was specified.

The dkbif_get_sf_x() and dkbif_get_sf_y() functions return the scale
factors to be used for the current frame.


The dkbif_close() function releases all ressources assigned to the image
data pointer and releases the memory.

The dkbif_can_handle() function checks, whether or not an image type
(i.e. obtained from dkbif_get_type()) can be handled.

The dkbif_can_handle_name() function checks, whether or not an image
can be handled, checking is based on the filename suffix.

=head1	RETURN VALUE

All functions return valid pointers or positive
integers on success and NULL or 0 on errors.

=head1	AUTHOR

Dirk Krause.

=head1	COPYRIGHT AND LICENSE

Copyright (c) 2007-2008, Dirk Krause
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

 * Redistributions of source code must retain the above
   copyright notice, this list of conditions and the
   following disclaimer.

 * Redistributions in binary form must reproduce the above
   copyright notice, this list of conditions and the following
   disclaimer in the documentation and/or other materials
   provided with the distribution.

 * Neither the name of the Dirk Krause nor the names of
   contributors may be used to endorse or promote products
   derived from this software without specific prior written
   permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
