# Function Reference

# _WinAPI_CreateDIB

Creates an uncompressed device-independent bitmap (DIB) with the specified width, height, and color depth

#include <WinAPIGdi.au3>
_WinAPI_CreateDIB ( $iWidth, $iHeight [, $iBitsPerPel = 32 [, $tColorTable = 0 [, $iColorCount = 0]]] )

## Parameters

$iWidth | The width of the bitmap, in pixels.
$iHeight | The height of the bitmap, in pixels. If this value is positive, the bitmap is a bottom-up DIB and its origin is the lower-left corner, otherwise, the bitmap is a top-down DIB and its origin is the upper-left corner.
$iBitsPerPel | [optional] The number of bits that define each pixel and the maximum number of colors in the bitmap. Default is 32.
$tColorTable | [optional] "dword[n]" structure that represents a DIB color table. The number of colors in this table depends on the values of the $iBitsPerPel parameters.
$iColorCount | [optional] The number of color indexes in the DIB color table that are actually used by the bitmap. The value of this parameter should not exceed the number of colors in the color table pointed to by the $pColorTable parameter. Default is 0.

## Return Value

Success: | Handle to the DIB.
Failure: | 0 and sets the @error flag to non-zero.

## Remarks

If the bitmap is monochrome (1 bits-per-pixel), the color table should contain two entries.
If the color table is not specified, the function creates a monochrome bitmap with black and white colors. If the bitmap use 4 or 8 bits-per-pixel, the color table should contain up to 16 or 256 entries respectively.
In this case, if the color table is not specified, the function creates an empty color table (all colors is black) with the maximum possible number of entries for the specified color depth.
You can fill out this color table later by using the _WinAPI_SetDIBColorTable() function.
If the bitmap use 16, 24, or 32 bits-per-pixel, the color table is not used, and $tColorTable parameter is ignored.
This function does not create a compressed 16, 24, or 32 bits-per-pixel bitmaps, that is the "biCompression" member of $tagBITMAPINFO structure is always 0 ($BI_RGB).
When you are finished using the bitmap, destroy it using the _WinAPI_DeleteObject() function.
Call _WinAPI_GetExtended() to retrieve a pointer to the location of the DIB bit values.

## Related

_WinAPI_DeleteObject, _WinAPI_GetExtended

## Example

    #include <GUIConstantsEx.au3>
    #include <SendMessage.au3>
    #include <StaticConstants.au3>
    #include <WinAPIGdi.au3>
    #include <WinAPIGdiDC.au3>
    #include <WinAPIHObj.au3>
    #include <WinAPIMem.au3>
    #include <WinAPIMisc.au3>

    ; Create array of colors of 256 entries required for 8 bits-per-pixel bitmap
    Local $aColorTable[256]
    For $i = 0 To 255
        $aColorTable[$i] = _WinAPI_RGB(0, $i, 255 - $i)
    Next

    ; Create color table from an array of colors
    Local $tColorTable = _WinAPI_CreateDIBColorTable($aColorTable)

    ; Create 8 bits-per-pixel device-independent bitmap (DIB) and retrieve a pointer to the location of its bit values
    Local $hBitmap = _WinAPI_CreateDIB(256, 256, 8, $tColorTable, 256)
    Local $pBits = _WinAPI_GetExtended()

    ; Fill bitmap color indexes
    For $i = 0 To 255
        _WinAPI_FillMemory($pBits + 256 * $i, 256, $i)
    Next

    ; Create GUI
    Local $hForm = GUICreate('Test ' & StringReplace(@ScriptName, '.au3', '()'), 256, 256)
    Local $idPic = GUICtrlCreatePic('', 0, 0, 256, 256)
    Local $hPic = GUICtrlGetHandle($idPic)

    ; Create DDB from DIB to correct display in control
    Local $hDC = _WinAPI_GetDC($hPic)
    Local $hDev = _WinAPI_CreateCompatibleBitmap($hDC, 256, 256)
    Local $hMemDC = _WinAPI_CreateCompatibleDC($hDC)
    Local $hMemSv = _WinAPI_SelectObject($hMemDC, $hDev)
    _WinAPI_DrawBitmap($hMemDC, 0, 0, $hBitmap)
    _WinAPI_ReleaseDC($hPic, $hDC)
    _WinAPI_SelectObject($hMemDC, $hMemSv)
    _WinAPI_DeleteDC($hMemDC)

    ; Set bitmap to control
    _SendMessage($hPic, $STM_SETIMAGE, 0, $hDev)
    Local $hObj = _SendMessage($hPic, $STM_GETIMAGE)
    If $hObj <> $hDev Then
        _WinAPI_DeleteObject($hDev)
    EndIf

    ; Show GUI
    GUISetState(@SW_SHOW)

    ; Save 8 bits-per-pixel bitmap to .bmp file
    Local $sPath = FileSaveDialog('Save Image', @TempDir, 'Bitmap Image Files (*.bmp)', 2 + 16, 'MyImage.bmp', $hForm)
    If $sPath Then
        _WinAPI_SaveHBITMAPToFile($sPath, $hBitmap, 2834, 2834)
    EndIf

    Do
    Until GUIGetMsg() = $GUI_EVENT_CLOSE