Allocates a new image of the specified 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)

Syntax

C#
public static FIBITMAP AllocateEx(
	int width,
	int height,
	int bpp,
	Nullable<RGBQUAD> color,
	FREE_IMAGE_COLOR_OPTIONS options,
	RGBQUAD[] palette,
	uint red_mask,
	uint green_mask,
	uint blue_mask
)
Visual Basic (Declaration)
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(), _
	red_mask As UInteger, _
	green_mask As UInteger, _
	blue_mask As UInteger _
) As FIBITMAP
Visual C++
public:
static FIBITMAP AllocateEx(
	int width, 
	int height, 
	int bpp, 
	Nullable<RGBQUAD> color, 
	FREE_IMAGE_COLOR_OPTIONS options, 
	array<RGBQUAD>^ palette, 
	unsigned int red_mask, 
	unsigned int green_mask, 
	unsigned int blue_mask
)

Parameters

width
Type: System..::.Int32
Width of the new bitmap.
height
Type: System..::.Int32
Height of the new bitmap.
bpp
Type: System..::.Int32
Bit depth of the new bitmap. Supported pixel depth: 1-, 4-, 8-, 16-, 24-, 32-bit per pixel for standard bitmaps.
color
Type: System..::.Nullable<(Of <(RGBQUAD>)>)
The color to fill the bitmap with or null.
options
Type: FreeImageAPI..::.FREE_IMAGE_COLOR_OPTIONS
Options to enable or disable function-features.
palette
Type: array< FreeImageAPI..::.RGBQUAD >[]()[]
The palette of the bitmap or null.
red_mask
Type: System..::.UInt32
Red part of the color layout. eg: 0xFF0000
green_mask
Type: System..::.UInt32
Green part of the color layout. eg: 0x00FF00
blue_mask
Type: System..::.UInt32
Blue part of the color layout. eg: 0x0000FF

Return Value

Handle to a FreeImage bitmap.

Remarks

This function is an extension to Allocate(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 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.

Version Information

FreeImage.NET

Supported in: 3.13.0, 3.13.1

See Also