dkbif.h File Reference

API to access bitmap images. More...

#include <stdio.h>
#include "dk.h"
#include "dkstream.h"
#include "dkapp.h"

Go to the source code of this file.

Data Structures

struct  dk_bif_jfif_analyze_t
 Structure for direct analysis of JPEG files. More...

Defines

#define DKBIF_TYPE_UNKNOWN   0
 Unknown file type.
#define DKBIF_TYPE_PNG   1
 File type PNG.
#define DKBIF_TYPE_JPG   2
 File type JPEG.
#define DKBIF_TYPE_NETPBM   3
 File type NetPBM.
#define DKBIF_TYPE_TIFF   4
 File type TIFF.
#define DKBIF_JFIF_SOF0   0x0001
 Flag for SOF_0 in dk_bif_sof_t.
#define DKBIF_JFIF_SOF1   0x0002
 Flag for SOF_1 in dk_bif_sof_t.
#define DKBIF_JFIF_SOF2   0x0004
 Flag for SOF_2 in dk_bif_sof_t.
#define DKBIF_JFIF_SOF3   0x0008
 Flag for SOF_3 in dk_bif_sof_t.
#define DKBIF_JFIF_SOF5   0x0010
 Flag for SOF_5 in dk_bif_sof_t.
#define DKBIF_JFIF_SOF6   0x0020
 Flag for SOF_6 in dk_bif_sof_t.
#define DKBIF_JFIF_SOF7   0x0040
 Flag for SOF_7 in dk_bif_sof_t.
#define DKBIF_JFIF_SOF8   0x0080
 Flag for SOF_8 in dk_bif_sof_t.
#define DKBIF_JFIF_SOF9   0x0100
 Flag for SOF_9 in dk_bif_sof_t.
#define DKBIF_JFIF_SOF10   0x0200
 Flag for SOF_10 in dk_bif_sof_t.
#define DKBIF_JFIF_SOF11   0x0400
 Flag for SOF_11 in dk_bif_sof_t.
#define DKBIF_JFIF_SOF13   0x0800
 Flag for SOF_13 in dk_bif_sof_t.
#define DKBIF_JFIF_SOF14   0x1000
 Flag for SOF_14 in dk_bif_sof_t.
#define DKBIF_JFIF_SOF15   0x2000
 Flag for SOF_15 in dk_bif_sof_t.
#define DKBIF_I_SOF0   0x00C0
 Marker for SOF_0 in JPEG/JFIF file.
#define DKBIF_I_SOF1   0x00C1
 Marker for SOF_1 in JPEG/JFIF file.
#define DKBIF_I_SOF2   0x00C2
 Marker for SOF_2 in JPEG/JFIF file.
#define DKBIF_I_SOF3   0x00C3
 Marker for SOF_3 in JPEG/JFIF file.
#define DKBIF_I_SOF5   0x00C5
 Marker for SOF_5 in JPEG/JFIF file.
#define DKBIF_I_SOF6   0x00C6
 Marker for SOF_6 in JPEG/JFIF file.
#define DKBIF_I_SOF7   0x00C7
 Marker for SOF_7 in JPEG/JFIF file.
#define DKBIF_I_SOF8   0x00C8
 Marker for SOF_8 in JPEG/JFIF file.
#define DKBIF_I_SOF9   0x00C9
 Marker for SOF_9 in JPEG/JFIF file.
#define DKBIF_I_SOF10   0x00CA
 Marker for SOF_10 in JPEG/JFIF file.
#define DKBIF_I_SOF11   0x00CB
 Marker for SOF_11 in JPEG/JFIF file.
#define DKBIF_I_SOF13   0x00CD
 Marker for SOF_13 in JPEG/JFIF file.
#define DKBIF_I_SOF14   0x00CE
 Marker for SOF_14 in JPEG/JFIF file.
#define DKBIF_I_SOF15   0x00CF
 Marker for SOF_15 in JPEG/JFIF file.

Typedefs

typedef void * dk_bif_ptr
 Pointer to structure representing an image file.
typedef void * dk_bif_frame_ptr
 Pointer to structure representing an image frame.
typedef unsigned dk_bif_sof_t
 JPEG/JFIF SOF type.

Functions

int dkbif_can_handle_name (char *n)
 Check whether the dkbif library can handle a file.
dk_bif_ptr dkbif_open (void)
 Create new image structure.
void dkbif_close (dk_bif_ptr i)
 Destroy image structure and release memory.
int dkbif_get_type (char *n)
 Get numeric key to represent the image type based on the file name suffix.
int dkbif_can_handle (int s)
 Check whether an image file type can be handled.
void dkbif_set_width_height_sufficient (dk_bif_ptr i, int f)
 Set "width and height sufficient" flag for image structure.
int dkbif_read_header (\dk_bif_ptr i, FILE *f, char *n, int s, char *t)
 Read image file header into image structure.
int dkbif_read_data (dk_bif_ptr i, FILE *f)
 Read image data.
unsigned long dkbif_number_of_frames (dk_bif_ptr i)
 Get number of frames in image.
int dkbif_set_frame (dk_bif_ptr i, unsigned long f)
 Set current frame.
int dkbif_get_channels (dk_bif_ptr i)
 Get number of color channels in the current frame.
unsigned long dkbif_get_width (dk_bif_ptr i)
 Get width of current frame in pixels.
unsigned long dkbif_get_height (dk_bif_ptr i)
 Get height of current frame in pixels.
int dkbif_get_must_scale (dk_bif_ptr i)
 Check whether the image contains resolution information.
double dkbif_get_real_width (dk_bif_ptr i)
 Get width of current frame.
double dkbif_get_real_height (dk_bif_ptr i)
 Get height of current frame.
unsigned short dkbif_get_bits_per_component (dk_bif_ptr i)
 Get number of bits per component for current frame.
int dkbif_set_bits_per_component (dk_bif_ptr i, unsigned short b)
 Set number of bits per component.
int dkbif_set_mixing (dk_bif_ptr i, int f, double r, double g, double b)
 Set background color for mixing.
int dkbif_set_mask_trigger_level (dk_bif_ptr i, double l)
 Set trigger level to create an image mask.
unsigned short dkbif_get_red (dk_bif_ptr i, unsigned long x, unsigned long y)
 Get red value for pixel.
unsigned short dkbif_get_green (dk_bif_ptr i, unsigned long x, unsigned long y)
 Get green value for pixel.
unsigned short dkbif_get_blue (dk_bif_ptr i, unsigned long x, unsigned long y)
 Get blue value for pixel.
unsigned short dkbif_get_gray (dk_bif_ptr i, unsigned long x, unsigned long y)
 Get gray value for pixel.
unsigned short dkbif_get_alpha (dk_bif_ptr i, unsigned long x, unsigned long y)
 Get alpha value for pixel.
unsigned short dkbif_get_mask (dk_bif_ptr i, unsigned long x, unsigned long y)
 Get mask value for pixel.
void dkbif_allow_fast_ntsc (dk_bif_ptr i, int f)
 Allow/deny the use of fast NTSC color to grayscale conversion.
double dkbif_get_sf_x (dk_bif_ptr i)
 Get horizontal scale factor.
double dkbif_get_sf_y (dk_bif_ptr i)
 Get vertical scale factor.
char ** dkbif_lic_get (void)
 Get license information and information about used libraries.
void dkbif_jfif_analyze (dk_bif_jfif_analyze_t *a)
 Attempt to analyze JPEG/JFIF file.
int dkbif_jfif_get_sof (dk_bif_sof_t f, int s)
 Test bit for a SOF marker in a SOF marker flag set.
dk_bif_sof_t dkbif_jfif_set_sof (dk_bif_sof_t f, int s)
 Set bit for a SOF marker in a SOF marker flag set.
void dkbif_jfif_transfer (dk_stream_t *o, FILE *i)
 Transfer contents of JFIF file to stream.


Detailed Description

API to access bitmap images.

This module provides a simple unique API to access bitmap image files. This module does not open the files directly, it uses other libraries (libpng, jpeglib, tifflib and NetPBM).

Two steps are necessary to read a file:

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 eigher use background information from input file or to use a default color you have specified.

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


Function Documentation

void dkbif_allow_fast_ntsc ( dk_bif_ptr  i,
int  f 
)

Allow/deny the use of fast NTSC color to grayscale conversion.

By default the formula
g = 0.3 * r + 0.59 * g + 0.11 b
in floating point arithmetics is used to convert colors to grayscale. The formula
g = (54 * r + 183 * g + 19 * b) >> 8
in integer arithmetics is probably faster but results may differ from the floating point result.

Parameters:
i Pointer to image structure.
f Flag to enable fast integer calculation.

int dkbif_can_handle ( int  s  ) 

Check whether an image file type can be handled.

Parameters:
s Image file type as obtained from dkbif_get_type().
Returns:
Flag to indicate whether the file type can be handled.

int dkbif_can_handle_name ( char *  n  ) 

Check whether the dkbif library can handle a file.

The test is only based on a file name suffix inspection.

Parameters:
n File name.
Returns:
Flag to indicate whether the file can be handled.

void dkbif_close ( dk_bif_ptr  i  ) 

Destroy image structure and release memory.

Parameters:
i Pointer to image structure.

unsigned short dkbif_get_alpha ( dk_bif_ptr  i,
unsigned long  x,
unsigned long  y 
)

Get alpha value for pixel.

Parameters:
i Pointer to image structure.
x X position of the pixel.
y Y position of the pixel.
Returns:
Alpha component of the pixel.

unsigned short dkbif_get_bits_per_component ( dk_bif_ptr  i  ) 

Get number of bits per component for current frame.

Parameters:
i Pointer to image structure.
Returns:
Number of bits per component.

unsigned short dkbif_get_blue ( dk_bif_ptr  i,
unsigned long  x,
unsigned long  y 
)

Get blue value for pixel.

Parameters:
i Pointer to image structure.
x X position of the pixel.
y Y position of the pixel.
Returns:
Blue component of the pixel.

int dkbif_get_channels ( dk_bif_ptr  i  ) 

Get number of color channels in the current frame.

  • 1 = gray
  • 2 = gray + alpha
  • 3 = rgb
  • 4 = rgb + alpha
    Parameters:
    i Pointer to image structure.
    Returns:
    The number of color channels in the current frame of the image.

unsigned short dkbif_get_gray ( dk_bif_ptr  i,
unsigned long  x,
unsigned long  y 
)

Get gray value for pixel.

Parameters:
i Pointer to image structure.
x X position of the pixel.
y Y position of the pixel.
Returns:
Gray component of the pixel.

unsigned short dkbif_get_green ( dk_bif_ptr  i,
unsigned long  x,
unsigned long  y 
)

Get green value for pixel.

Parameters:
i Pointer to image structure.
x X position of the pixel.
y Y position of the pixel.
Returns:
Green component of the pixel.

unsigned long dkbif_get_height ( dk_bif_ptr  i  ) 

Get height of current frame in pixels.

Parameters:
i Pointer to image structure.
Returns:
The image height in pixels.

unsigned short dkbif_get_mask ( dk_bif_ptr  i,
unsigned long  x,
unsigned long  y 
)

Get mask value for pixel.

Parameters:
i Pointer to image structure.
x X position of the pixel.
y Y position of the pixel.
Returns:
Mask value of the pixel.

int dkbif_get_must_scale ( dk_bif_ptr  i  ) 

Check whether the image contains resolution information.

Parameters:
i Pointer to image structure.
Returns:
Flag to indicate the presence of resolution information.

double dkbif_get_real_height ( dk_bif_ptr  i  ) 

Get height of current frame.

Parameters:
i Pointer to image structure.
Returns:
The width of the current frame, either in:
  • PS points
    if the image contains resolution informaton or
  • pixels.

double dkbif_get_real_width ( dk_bif_ptr  i  ) 

Get width of current frame.

Parameters:
i Pointer to image structure.
Returns:
The width of the current frame, either in:
  • PS points
    if the image contains resolution information or
  • pixels.

unsigned short dkbif_get_red ( dk_bif_ptr  i,
unsigned long  x,
unsigned long  y 
)

Get red value for pixel.

Parameters:
i Pointer to image structure.
x X position of the pixel.
y Y position of the pixel.
Returns:
Red component of the pixel.

double dkbif_get_sf_x ( dk_bif_ptr  i  ) 

Get horizontal scale factor.

Parameters:
i Pointer to image structure.
Returns:
The horizontal scale factor needed to fit PS output into an area specified by the resolution information in the image file.

double dkbif_get_sf_y ( dk_bif_ptr  i  ) 

Get vertical scale factor.

Parameters:
i Pointer to image structure.
Returns:
The vertical scale factor needed to fit PS output into an area specified by the resolution information in the image file.

int dkbif_get_type ( char *  n  ) 

Get numeric key to represent the image type based on the file name suffix.

Parameters:
n Image file name.
Returns:
Image type (DKBIF_TYPE_PNG, DKBIF_TYPE_JPG, DKBIF_TYPE_NETPBM or DKBIF_TYPE_TIFF) on success, DKBIF_TYPE_UNKNOWN on error (Failed to find image type).

unsigned long dkbif_get_width ( dk_bif_ptr  i  ) 

Get width of current frame in pixels.

Parameters:
i Pointer to image structure.
Returns:
The width of the current frame in pixels.

void dkbif_jfif_analyze ( dk_bif_jfif_analyze_t a  ) 

Attempt to analyze JPEG/JFIF file.

Parameters:
a Pointer to JFIF analysis structure. Before starting an analysis the inputfile component of the structure must be set.
After a successful analysis the is_jfif component is set to JFIF_RESULT_OK (or JFIF_RESULT_PROBLEMATIC if SOF markers other than SOF_0 or SOF_1 were found), the other components are set as follows:
  • vers_major
    Major version number, (must be 0x01).
  • vers_minor
    Minor version number, (must be 0x01 or 0x02).
  • width
    Image width in pixels.
  • height
    Image height in pixels.
  • dpi_setting
    Flag to indicate whether resolution information was found.
  • xres
    X resolution in dpi (only if dpi_setting is set).
  • yres Y resolution in dpi (only if dpi_setting is set).
  • bpc
    Number of bits per component.
  • components
    Number of components (color channels), must be
    • 1 for grayscaled images,
    • 3 for RGB images or
    • 4 for CMYK images.
  • adobe_marker_found
    Flag to indicate the string ``Adobe'' was found in an application tag 14.
  • used_sofs
    Flag set to indicate which SOF(s) type(s) are used in the image.
  • n_sofs
    Number of SOF markers found (must be 1, otherwise the analysis fails).
  • n_images
    Number of frames (must be 1, otherwise the analysis fails).

int dkbif_jfif_get_sof ( dk_bif_sof_t  f,
int  s 
)

Test bit for a SOF marker in a SOF marker flag set.

Parameters:
f SOF marker flag set.
s SOF type to test (0-15).
Returns:
Flag to indicate the bit was set.

dk_bif_sof_t dkbif_jfif_set_sof ( dk_bif_sof_t  f,
int  s 
)

Set bit for a SOF marker in a SOF marker flag set.

Parameters:
f SOF marker flag set.
s SOF type to add.
Returns:
New SOF marker flag set.

void dkbif_jfif_transfer ( dk_stream_t o,
FILE *  i 
)

Transfer contents of JFIF file to stream.

Parameters:
o Destination stream.
i Source file.

char** dkbif_lic_get ( void   ) 

Get license information and information about used libraries.

Returns:
Pointer to array of pointers to strings. The last pointer in the array is a NULL pointer.

unsigned long dkbif_number_of_frames ( dk_bif_ptr  i  ) 

Get number of frames in image.

Parameters:
i Pointer to image structure.
Returns:
The number of frames (pictures) in the image file.

dk_bif_ptr dkbif_open ( void   ) 

Create new image structure.

The image structure is created in dynamically allocated memory. Call dkbif_close() to destroy the structure and release memory after usage.

Returns:
Pointer to new image structure.

int dkbif_read_data ( dk_bif_ptr  i,
FILE *  f 
)

Read image data.

Call this function after dkbif_read_header() and only if dkbif_read_header() returned successfully.

Parameters:
i Pointer to image structure.
f Pointer to input file.
Returns:
Flag to indicate success.

int dkbif_read_header ( \dk_bif_ptr  i,
FILE *  f,
char *  n,
int  s,
char *  t 
)

Read image file header into image structure.

Some image libraries provide functions to read an image from using a FILE * pointer, other image libraries have functions taking a file name as argument. If necessary the contents of f is transferred into a new file t, and the file name t is passed to functions requiring a file name.

Parameters:
i Pointer to image structure.
f Input file, must be opened in binary mode.
n Input file name.
s Suffix type as returned from dkbif_get_type().
t File name for a temporary file.
Returns:
Flag to indicate success.

int dkbif_set_bits_per_component ( dk_bif_ptr  i,
unsigned short  b 
)

Set number of bits per component.

If your application requires another number of bits per component than available in the image file, use this function to require a conversion.

Parameters:
i Pointer to image structure.
b Number of bits per component required.
Returns:
Flag to indicate success.

int dkbif_set_frame ( dk_bif_ptr  i,
unsigned long  f 
)

Set current frame.

All subsequent functions to get pixel information or width/height will access the frame. The first frames index is 0.

Parameters:
i Pointer to image structure.
f Frame index.
Returns:
Flag to indicate success.

int dkbif_set_mask_trigger_level ( dk_bif_ptr  i,
double  l 
)

Set trigger level to create an image mask.

Parameters:
i Pointer to image structure.
l Trigger level (0.0-1.0).
Returns:
Flag to indicate success.

int dkbif_set_mixing ( dk_bif_ptr  i,
int  f,
double  r,
double  g,
double  b 
)

Set background color for mixing.

Parameters:
i Pointer to image structure.
f Mix decision:
  • 0
    no mixing,
  • 1
    mixing, prefer image background information over the colors specified here or
  • 2
    mixing, always use the background color specified here.
r Red component of background color.
g Green component of background color.
b Blue component of background color.
Returns:
Flag to indicate success.

void dkbif_set_width_height_sufficient ( dk_bif_ptr  i,
int  f 
)

Set "width and height sufficient" flag for image structure.

If this flag is set, in the following call(s) to dkbif_read_header() it is sufficient to find width and height of the image, no other information is needed. This might be useful for applications showing bounding box information only or printing placeholders in document drafts.

Parameters:
i Pointer to image structure.
f New flag value.


Generated on Mon Feb 16 17:12:04 2009 for dklibs by  doxygen 1.5.6