IG_image_create

Please use the new upgraded function IG_image_create_DIB_ex().

Declaration:

	Copy Code
AT_ERRCOUNT ACCUAPI IG_image_create_DIB( AT_DIMENSION nWidth, AT_DIMENSION nHeight, UINT nBitsPerPixel, 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 .
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
(See also the example for function IG_dspl_DDB_import). HIGEAR hIGearNew; /* Will be handle of new empty DIB / AT_DIMENSION nWid, nHi; / Dimensions for empty DIB / UINT Bpp; / Bits per pixel for empty DIB / AT_ERRCOUNT nErrCount; / Count of errors put on stack / HIGEAR hIGearCopy; / Will be handle of new copied DIB / char FAR lpExistingDIB; /* Holds address of an existing DIB / / Create an empty 500 x 300 x 16 bits per pixel DIB: / nWid = 500; nHi = 300; / Create a 500 pixel x 300 row DIB / nBpp = 16; / 16 Supported Raster Image Formats: / nErrCount = IG_image_create_DIB (nWid, nHi, nBpp, NULL, &hIGearNew); if ( nErrs ) { ...} / Process any errors / ... / Copy DIB at lpExistingDIB, creating HIGEAR image hIGearCopy: / nErrCount = IG_image_create_DIB (0, 0, 0, (LPAT_DIB) lpExistingDIB, &hIGearCopy); if ( nErrs ) { ...} /* Process any errors */

Copy Code

(See also the example for function IG_dspl_DDB_import). 
HIGEAR  hIGearNew;      /* Will be handle of new empty DIB */ 
AT_DIMENSION  nWid, nHi;      /* Dimensions for empty DIB  */ 
UINT    Bpp;             /* Bits per pixel for empty DIB */ 
AT_ERRCOUNT   nErrCount;      /* Count of errors put on stack */ 
HIGEAR  hIGearCopy;     /* Will be handle of new copied DIB */ 
char FAR  *lpExistingDIB; /* Holds address of an existing DIB */ 
/* Create an empty 500 x 300 x 16 bits per pixel DIB:   */ 
nWid  =  500;  nHi = 300;   /* Create a 500 pixel x 300 row DIB  
*/ 
nBpp  =  16;                /* 16 Supported Raster Image Formats:  */ 
nErrCount =  IG_image_create_DIB (nWid, nHi, nBpp, NULL, 
&hIGearNew); 
if ( nErrs ) { ...}        /* Process any errors */ 
 ... 
/* Copy DIB at *lpExistingDIB, creating HIGEAR image hIGearCopy: 
*/ 
nErrCount =  IG_image_create_DIB (0, 0, 0,  (LPAT_DIB) 
lpExistingDIB, &hIGearCopy); 
if ( nErrs ) { ...}        /* Process any errors */

Remarks:

The functionality of this API call has been upgraded and supported by the new function IG_image_create_DIB_ex(). The reason that this new function has been created is that the old function cannot support 16-bit DIBs. In the interest of backward compatibility, we have left the old function in its original form and have retained support for it. If you have already used the old function in your code, it is not mandatory that you modify your code, but it is recommended.

This function creates a new DIB and returns you its HIGEAR handle. 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 you have an existing DIB which you simply want to give a HIGEAR handle to, use function IG_image_DIB_import(), which does not make a copy of the DIB.

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