/**	@file	dk3bif.h	Bitmap image file routines.
We can open an image file by either specifying the name or a file
opened for binary reading.

A temporary copy of the initial file is used if at least one of the following
conditions is true:

-   The bitmap image file is opened using a file name which indicates
    a TIFF file.

  - The bitmap image file is opened using a FILE pointer.

The libtiff library uses an 8-bit character file name to open the file.

Opening a bitmap image file using a FILE pointer typically occures when
processing standard input. We must create a copy on disk so we can do
seek/rewind operations.

The file name is ``dk3bif-PID-INDEX.tmp''. PID is replaced by the process
ID expressed as 8 hex digits, INDEX is a unique number within a process,
also expressed as 8 hex digits.

A typical example how to use the library looks like this:
@code
#include <dk3bif.h>

dkChar const filename[] = { dkT("test.png") };

dk3_app_t	*app = NULL;	/* Application structure. */
dk3_bif_t	*bp = NULL;	/* Bitmap image file structure. */
dk3_bif_coord_t	w;		/* Width of current frame. */
dk3_bif_coord_t h;		/* Height of current frame. */
size_t		bits;		/* Bits per pixel. */
size_t		nrb;		/* Non-redundant bits per pixel. */
int		cs;		/* Color space. */
int		ic;		/* Flag: Is colored. */
dk3_bif_pixel_t	r;
dk3_bif_pixel_t	g;
dk3_bif_pixel_t	b;
dk3_bif_pixel_t	gr;

/* Code to initialize app */

if(app) {
  /*
  	Check whether file name suffix indicates one of the
	supported files.
  */
  if(dk3bif_check_file_name(filename)) {
    /*
    	Attempt to open the image.
    */
    bp = dk3bif_open_filename_app(filename, DK3_BIF_IMAGE_TYPE_UNKNOWN, app);
    if(bp) {
      /*
      	Set default background color white for mixing if there
	is an alpha channel in the file.
	The final parameter 0 indicates to use this color only
	if there is no background color chunk in the file.
	A value 0 would override the background color chunk
	information.
	This function must be called before dk3bif_read_data().
      */
      dk3bif_set_background(255, 255, 255, 0);
      /*
      	When opening the image file we only read the header
	information for PNG and JPEG.
	To access image data we have to call dk3bif_read_data().
      */
      if(dk3bif_read_data(bp)) {
        /*
		Use reset/next combination to access all
		frames in the image.
		Alternatively use dk3bif_number_of_frames()
		and dk3bif_set_frame() to obtain the number
		of available frames and to access a specific
		frame by number.
	*/
        dk3bif_reset_frames(bp);
	while(dk3bif_next_frame(bp)) {
	  /*
	  	Find number of bits per pixel.
	  */
	  bits = dk3bif_get_bits_per_pixel(bp);
	  /*
	  	Find color space.
	  */
	  cs   = dk3bif_get_color_space(bp);
	  /*
	  	Optionally analyze the current frame and find the
		number of non-redundant bits per pixel and check
		whether or not the image is really colored.
	  */
	  dk3bif_analyze(bp);
	  nrb = dk3bif_real_bits_per_pixel(bp);
	  ic = dk3bif_is_colored(bp);
	  /*
	  	Process pixel values.
		(0,0) is the upper left corner.
	  */
	  for(y = 0; y < h; y++) {
	    for(x = 0; x < w; x++) {
	      r = dk3bif_get_red(bp, x, y);
	      g = dk3bif_get_green(bp, x, y);
	      b = dk3bif_get_blue(bp, x, y);
	      gr = dk3bif_get_gray(bp, x, y);
	      /*
	      	Do something using the value...
	      */
	    }
	  }
	}
      } else {
        /* ERROR: Failed to read image data! */
      }
      /*
      	Close the image, release memory and resources.
      */
      dk3bif_close(bp);
    } else {
      /* ERROR: Failed to open graphics. */
    }
  } else {
    /* ERROR: File name suffix indicates a non-supported file type! */
  }
} else {
  /* ERROR: Application structure not initialized! */
}
@endcode
*/