DragonWins Home Page

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.

IMAGE Version Parameters

IMAGE Color Parameters

IMAGE Composition Parameters

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




These are used as arguments to the IMAGE_version().

IMAGE Color Parameters





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








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

The Public Functions


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:


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* 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).



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.


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.


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


WORD IMAGE_set_rgb(IMAGE *p, WORD row, WORD col, WORD r, WORD g, WORD b)

Sets the color of the pixel specified by row and col to that indicated by the r, g, and b parameters. Returns the new grayscale value of the pixel.


WORD IMAGE_get_bits(IMAGE *p)

Returns the nominal bit depth of the image.


WORD IMAGE_get_rows(IMAGE *p)

Returns the number of rows in the image.


WORD IMAGE_get_cols(IMAGE *p)

Returns the number of columns in the image.



Fills the entire image with the color indicated by the r, g, and b parameters. Returns p.