FreeImage.AllocateExT(T) Method (FREE_IMAGE_TYPE, Int32, Int32, Int32, Nullable(T), FREE_IMAGE_COLOR_OPTIONS, RGBQUAD[], UInt32, UInt32, UInt32)

public static FIBITMAP AllocateExT<T>(
	FREE_IMAGE_TYPE type,
	int width,
	int height,
	int bpp,
	Nullable<T> color,
	FREE_IMAGE_COLOR_OPTIONS options,
	RGBQUAD[] palette,
	uint red_mask,
	uint green_mask,
	uint blue_mask
)
where T : struct, new()

Parameters

type

Type: FreeImageAPIFREE_IMAGE_TYPE
Type of the image.

width

Type: SystemInt32
Width of the new bitmap.

height

Type: SystemInt32
Height of the new bitmap.

bpp

Type: SystemInt32
Bit depth of the new bitmap. Supported pixel depth: 1-, 4-, 8-, 16-, 24-, 32-bit per pixel for standard bitmap

color

Type: SystemNullableT
The color to fill the bitmap with or null.

options

Type: FreeImageAPIFREE_IMAGE_COLOR_OPTIONS
Options to enable or disable function-features.

palette

Type: FreeImageAPIRGBQUAD
The palette of the bitmap or null.

red_mask

Type: SystemUInt32
Red part of the color layout. eg: 0xFF0000

green_mask

Type: SystemUInt32
Green part of the color layout. eg: 0x00FF00

blue_mask

Type: SystemUInt32
Blue part of the color layout. eg: 0x0000FF

Type Parameters

T

The type of the specified color.

Return Value

Basically, this function internally relies on function AllocateT(FREE_IMAGE_TYPE, Int32, Int32, Int32, UInt32, UInt32, UInt32), followed by a call to FillBackgroundT(FIBITMAP, T, FREE_IMAGE_COLOR_OPTIONS). This is why both parameters color and options behave the same as it is documented for function FillBackgroundT(FIBITMAP, T, FREE_IMAGE_COLOR_OPTIONS). So, please refer to the documentation of FillBackgroundT(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 [!:FREE_IMAGE_COLOR_OPTIONS.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 [!:FREE_IMAGE_COLOR_OPTIONS.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.

Reference