Allocates a new image of the specified type, width, height and bit depth and optionally fills it with the specified color. See remarks for further details.

Namespace:  FreeImageAPI
Assembly:  FreeImageNET (in FreeImageNET.dll)


public static FIBITMAP AllocateExT<T>(
	int width,
	int height,
	int bpp,
	Nullable<T> color,
	RGBQUAD[] palette
where T : struct, new()
Visual Basic (Declaration)
Public Shared Function AllocateExT(Of T As {Structure, New}) ( _
	width As Integer, _
	height As Integer, _
	bpp As Integer, _
	color As Nullable(Of T), _
	palette As RGBQUAD() _
Visual C++
generic<typename T>
where T : value class, gcnew()
static FIBITMAP AllocateExT(
	int width, 
	int height, 
	int bpp, 
	Nullable<T> color, 
	array<RGBQUAD>^ palette


Type: FreeImageAPI..::.FREE_IMAGE_TYPE
Type of the image.
Type: System..::.Int32
Width of the new bitmap.
Type: System..::.Int32
Height of the new bitmap.
Type: System..::.Int32
Bit depth of the new bitmap. Supported pixel depth: 1-, 4-, 8-, 16-, 24-, 32-bit per pixel for standard bitmap
Type: System..::.Nullable<(Of <(T>)>)
The color to fill the bitmap with or null.
Options to enable or disable function-features.
Type: array< FreeImageAPI..::.RGBQUAD >[]()[]
The palette of the bitmap or null.

Type Parameters

The type of the specified color.

Return Value

Handle to a FreeImage bitmap.


This function is an extension to AllocateT(FREE_IMAGE_TYPE, Int32, Int32, Int32, UInt32, UInt32, UInt32), which additionally supports specifying a palette to be set for the newly create image, as well as specifying a background color, the newly created image should initially be filled with.

Basically, this function internally relies on function AllocateT(FREE_IMAGE_TYPE, Int32, Int32, Int32, UInt32, UInt32, UInt32), followed by a call to FillBackground<(Of <(T>)>)(FIBITMAP, T, FREE_IMAGE_COLOR_OPTIONS). This is why both parameters color and options behave the same as it is documented for function FillBackground<(Of <(T>)>)(FIBITMAP, T, FREE_IMAGE_COLOR_OPTIONS). So, please refer to the documentation of FillBackground<(Of <(T>)>)(FIBITMAP, T, FREE_IMAGE_COLOR_OPTIONS) to learn more about parameters color and options.

The palette specified through parameter palette is only copied to the newly created image, if its image type is FIT_BITMAP and the desired bit depth is smaller than or equal to 8 bits per pixel. In other words, the palette palette is only taken into account for palletized images. However, if the preceding conditions match and if palette is not null, the palette is assumed to be at least as large as the size of a fully populated palette for the desired bit depth. So, for an 8-bit image, this length is 256, for an 4-bit image it is 16 and it is 2 for a 1-bit image. In other words, this function does not support partial palettes.

However, specifying a palette is not necesarily needed, even for palletized images. This function is capable of implicitly creating a palette, if palette is null. If the specified background color is a greyscale value (red = green = blue) or if option FICO_ALPHA_IS_INDEX is specified, a greyscale palette is created. For a 1-bit image, only if the specified background color is either black or white, a monochrome palette, consisting of black and white only is created. In any case, the darker colors are stored at the smaller palette indices.

If the specified background color is not a greyscale value, or is neither black nor white for a 1-bit image, solely this specified color is injected into the otherwise black-initialized palette. For this operation, option FICO_ALPHA_IS_INDEX is implicit, so the specified color is applied to the palette entry, specified by the background color's rgbReserved field. The image is then filled with this palette index.

This function returns a newly created image as function AllocateT(FREE_IMAGE_TYPE, Int32, Int32, Int32, UInt32, UInt32, UInt32) does, if both parameters color and palette are null. If only color is null, the palette pointed to by parameter palette is initially set for the new image, if a palletized image of type FIT_BITMAP is created. However, in the latter case, this function returns an image, whose pixels are all initialized with zeros so, the image will be filled with the color of the first palette entry.

Version Information


Supported in: 3.13.0, 3.13.1

See Also