dklibs(3)

NAME
dkbif - bitmap image file library

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);

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 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 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 f must be opened to read the image file in binary mode. 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 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 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 (r, g and b are used if there is no background color chunk in the file) and 2 means always mixing against r, g and b.

The dkbif_set_mask_trigger_level() function sets up the trigger level for converting an alpha channel into an image mask. The parameter tl must be in the range 0.0<=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.

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

AUTHOR
Dirk Krause.

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.