dkbif(3) - Linux man page

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 © 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.