BMP Structure (1v0)

(Last Mod: 27 November 2010 21:37:52 )

NOTE: This page is presently just a copy of the IMAGE Structure page, which is being used as a template.

Overview
Macro Constants

IMAGE Version Parameters

IMAGE Color Parameters

IMAGE Composition Parameters

The Public Functions

Note on Data Types:

t_image_color => WORD => unsigned 16-bit integer

t_image_size => WORD => unsigned 16-bit integer

WORD IMAGE_version (int what)

void IMAGE_report (IMAGE *p)

IMAGE* IMAGE_new (IMAGE *p, t_image_size rows, t_image_size cols, WORD bits)

IMAGE* IMAGE_delete (IMAGE *p)

t_image_color IMAGE_get_color (IMAGE *p, t_image_size row, t_image_size col, WORD color)

t_image_color IMAGE_set_color (IMAGE *p, t_image_size row, t_image_size col, WORD color, t_image_color value)

t_image_color IMAGE_set_rgb (IMAGE *p, t_image_size row, t_image_size col,

t_image_color r, t_image_color g, t_image_color b)

WORD IMAGE_get_bits (IMAGE *p)

t_image_size IMAGE_get_rows (IMAGE *p)

t_image_size IMAGE_get_cols (IMAGE *p)

IMAGE* IMAGE_fill (IMAGE *p, t_image_color r, t_image_color g, t_image_color b)

The image.h Header File
The image.c Source Code File

Overview

The IMAGE structure is used to contain the data for a three-color 2-D picture. The size (number of rows and columns) of the image is maintained as part of the image structure. The data for each pixel may be accessed and modified individually. This data consists of three values, one each for the red, green, and blue color components.

The values for each component are WORDs (unsigned 16-bit integers) meaning that they can take on values from 0 through 65,535. However, most images are composed of one-byte color intensities (0 through 255), though some formats of interest use 10-bits (0 through 1023). The ideal way of dealing with these variations would be to store the data as floating point values between 0.0 and 1.0; however, not only would this require more space (not a large concern, here) and probably slow down the functions (again, not a large concern, here), but it would add potential uncertainly in the exact values for each pixel. Because of the nature of some of the applications this structure is intended for, such as steganography, this was considered unacceptable. The consequence is that the user is responsible for knowing what the acceptable range of values is for the image they are working with. To help out with this, the nominal bit depth of the image is maintained within the structure and several functions are provided to help the user translate between bit depths. But it is important to keep in mind that the basic functions do not verify that the data values stored are compatible with the nominal bit depth.

Macro Constants

The following sets of symbolic constants are defined in the image.h header file:

`IMAGE` Version Parameters

IMAGE_VERSION

IMAGE_MAJOR

IMAGE_MINOR

These are used as arguments to the IMAGE_version().

`IMAGE` Color Parameters

IMAGE_RED

IMAGE_GREEN

IMAGE_BLUE

IMAGE_GRAY

These are to be used as arguments to those functions calling for a "color" parameter. The purpose is to make indicating the intended color easier and the code more readable. The red, green, and blue constants are self-explanatory. Using a color of 'gray' will either set all three color components to the same value or return the 'gray' equivalent of the pixel color which, here, is taken to be the RMS (root-mean-square) value of the three color components.

`IMAGE` Composition Parameters

IMAGE_NEW

IMAGE_MIN

IMAGE_MAX

IMAGE_AVG

IMAGE_SUM

IMAGE_SUB

IMAGE_FUN

These are used as arguments to the IMAGE_compose() function to determine how pixels from two images are to be combined.

The Public Functions

IMAGE_version()

WORD IMAGE_report(int what)

Returns the version information for the STRUCT library as a 16-bit unsigned integer according to value passed as the what parameter:

what = IMAGE_VERSION: Upper byte is the major version number and the lower byte is the minor revision number.
what = IMAGE_MAJOR: The major version number
what = IMAGE_MINOR: The minor revision number.

IMAGE_report()

void IMAGE_report(IMAGE *p)

Generates an on screen report giving the address of the structure and the values of all of the members. This is primarily for debugging purposes.

IMAGE_new()

IMAGE* IMAGE_new(IMAGE *p, WORD rows, WORD cols, WORD bits)

If p is NULL (the usual case), allocates memory for a new IMAGE structure with sufficient memory to store a (rows)x(cols) image and returns a pointer to that structure if successful. If p is a pointer to an existing IMAGE structure, then that structure is reused. Returns NULL if unsuccessful. If either rows or cols is zero, then the structure is still allocated but no memory for the data is allocated.

The bits parameter is the nominal bit depth (per image component, not per pixel) of the image that is stored within the structure. It has no effect on the amount of memory allocated, but is used to ensure that data written to the structure is within the appropriate range. The maximum value of bits is sizeof(t_image_color).

IMAGE_delete()

IMAGE* IMAGE_delete(IMAGE *p)

Deallocates the memory used by the structure, including that allocated for the pixel data. Returns a NULL pointer if successful. If the memory could not be freed, then the original value of the pointer is returned.

IMAGE_get_color()

int IMAGE_get_color(IMAGE *p, WORD row, WORD col, WORD color)

Gets the value of the color component specified for the pixel in the specificed row and column. If the requested color is gray (IMAGE_GRAY), then the RMS value of the three color components is returned. Note: the data itself is not changed.

IMAGE_set_color()

WORD IMAGE_set_color(IMAGE *p, WORD row, WORD col, WORD color, WORD value)

Sets the specified color component of the pixel specified by row and col to value. If the specified component is gray (IMAGE_GRAY), then all three component are set to value. Returns the new value of the specified component (which should be value).