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:
FreeImageAPIAssembly: 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.