ImageGear for C and C++ on Linux v18.8 - Updated
IG_image_create_DIB_ex
API Reference Guide > Core Component API Reference > Core Component Functions Reference > General Image Functions > IG_image_create_DIB_ex

This function creates a new DIB and returns you its HIGEAR handle.

Declaration:

 
Copy Code
AT_ERRCOUNT ACCUAPI IG_image_create_DIB_ex(
        AT_DIMENSION nWidth, 
        AT_DIMENSION nHeight, 
        UINT nBitsPerPixel, 
        AT_LMODE lCompression, 
        LPAT_DIB lpDIB, 
        LPHIGEAR lphIGear 
);

Arguments:

Name Type Description
nWidth AT_DIMENSION Set to the width that the image will be, in pixels. If the DIB already exists (lpDIB <> NULL), this value will be ignored.
nHeight AT_DIMENSION Set to the height that the image will be (number of rows). If the DIB already exists (lpDIB <> NULL), this value will be ignored.
nBitsPerPixel UINT Set to the bit depth of the new DIB. If the DIB already exists (lpDIB <> NULL), this value will be ignored.
lCompression AT_LMODE

Set to the type of pixel storage format you would like used in the new DIB. Currently, there are three options:

  • IG_BI_RGB - for standard Windows DIB pixel storage.
  • IG_BI_GRAYSCALE - for 16-bitgrayscale DIB pixel storage.
  • IG_BI_CMYK - for 32-bit CMYK DIB pixel storage.

**This variable is named lCompression because it is used to set up the biCompression field of the DIB header.

lpDIB LPAT_DIB Far pointer to a DIB to copy, or NULL if creating an empty DIB. See the tip below. If this parameter is not NULL, it must be a valid pointer to the uncompressed bitmap. For example, the biCompression field of lpDIB can be either: IG_BI_RGB = 0 or IG_BI_GRAYSCALE = 503.
LphIGear LPHIGEAR A far pointer that returns a HIGEAR handle for the DIB just created.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Supported Raster Image Formats:

Indexed RGB – 1, 4, 8 bpp;
Grayscale – 9…16 bpp;
RGB – 24 bpp;
CMYK – 32 bpp.

This function is only kept for backward compatibility reasons. Please use IG_image_DIB_import or IG_image_create instead.

Example:

 
Copy Code
HIGEAR hIGearNew = NULL; // Will be handle of new empty DIB 
AT_DIMENSION nWidth=0, nHight=0; // Dimensions for empty DIB 
UINT nBpp = 0; // Bits per pixel for empty DIB 
AT_LMODE nCompression = IG_COMPRESSION_NONE; 
AT_ERRCOUNT nErrCount = 0; // Count of errors put on stack 
HIGEAR hIGearCopy = NULL; // Will be handle of new copied DIB 
char FAR *lpExistingDIB = NULL; // Holds address of an existing DIB 
// Create an empty 500 x 300 x 16 bits per pixel DIB 
nWidth = 500; nHight = 300; nBpp = 16; 
nErrCount = IG_image_create_DIB_ex (nWidth, nHight, nBpp, nCompression, NULL, &hIGearNew); 
if( nErrCount ) //Process any errors 
// Copy DIB at *lpExistingDIB, creating HIGEAR image hIGearCopy 
nErrCount = IG_image_create_DIB_ex (0, 0, 0, 0, (LPAT_DIB) lpExistingDIB, &hIGearCopy); 
if( nErrCount ) //Process any errors 

Remarks:

If the FAR pointer lpDIB = NULL, an empty DIB is created using arguments nWidth, nHeight, and nBitsPerPixel. If lpDIB is not NULL, it should be a FAR pointer to an existing DIB which is to be copied. The DIB to be copied need not have a HIGEAR handle associated with it. The width, height, and Bits Per Pixel will be copied from the existing DIB; arguments nWidth, nHeight, and nBitsPerPixel will be ignored.

If the lpDIB parameter is not NULL, then it must be a valid pointer to the uncompressed bitmap, that is the biCompression field of the lpDIB structure can be either IG_BI_RGB= 0 or IG_BI_GRAYSCALE= 503.

If you set lpDIB to NULL in order to create an empty DIB, the DIB palette will not be initialized. You will have to initialize it yourself. If you do not, the image will be displayed as all black.
Each raster in the DIB data must be padded to 32 bits. ImageGear does not support a top-down DIB (where biHeight is negative).