public static FIBITMAP AllocateEx(
	int width,
	int height,
	int bpp,
	Nullable<RGBQUAD> color,
	FREE_IMAGE_COLOR_OPTIONS options,
	RGBQUAD[] palette
)

Public Shared Function AllocateEx ( _
	width As Integer, _
	height As Integer, _
	bpp As Integer, _
	color As Nullable(Of RGBQUAD), _
	options As FREE_IMAGE_COLOR_OPTIONS, _
	palette As RGBQUAD() _
) As FIBITMAP

public:
static FIBITMAP AllocateEx(
	int width, 
	int height, 
	int bpp, 
	Nullable<RGBQUAD> color, 
	FREE_IMAGE_COLOR_OPTIONS options, 
	array<RGBQUAD>^ palette
)

Return Value

Basically, this function internally relies on function Allocate(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 the desired bit depth is smaller than or equal to 8 bits per pixel. In other words, the palette parameter is only taken into account for palletized images. So, for an 8-bit image, the 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 Allocate(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.

FreeImage.NET