FreeImage.EnlargeCanvas(T) Method

FreeImage.NET

previous page next page
FreeImageEnlargeCanvasT Method
Enlarges or shrinks the FreeImage bitmap selectively per side and fills newly added areas with the specified background color. See remarks for further details.

Namespace: FreeImageAPI
Assembly: FreeImageNET (in FreeImageNET.dll) Version: 3.17.0.4 (3.17.0)
Syntax
C#
Copy
public static FIBITMAP EnlargeCanvas<T>(
	FIBITMAP dib,
	int left,
	int top,
	int right,
	int bottom,
	Nullable<T> color,
	FREE_IMAGE_COLOR_OPTIONS options
)
where T : struct, new()

Parameters

dib
Type: FreeImageAPIFIBITMAP
Handle to a FreeImage bitmap.
left
Type: SystemInt32
The number of pixels, the image should be enlarged on its left side. Negative values shrink the image on its left side.
top
Type: SystemInt32
The number of pixels, the image should be enlarged on its top side. Negative values shrink the image on its top side.
right
Type: SystemInt32
The number of pixels, the image should be enlarged on its right side. Negative values shrink the image on its right side.
bottom
Type: SystemInt32
The number of pixels, the image should be enlarged on its bottom side. Negative values shrink the image on its bottom side.
color
Type: SystemNullableT
The color, the enlarged sides of the image should be filled with.
options
Type: FreeImageAPIFREE_IMAGE_COLOR_OPTIONS
Options that affect the color search process for palletized images.

Type Parameters

T
The type of the specified color.

Return Value

Type: FIBITMAP
Handle to a FreeImage bitmap.
Remarks
This function enlarges or shrinks an image selectively per side. The main purpose of this function is to add borders to an image. To add a border to any of the image's sides, a positive integer value must be passed in any of the parameters left, top, right or bottom. This value represents the border's width in pixels. Newly created parts of the image (the border areas) are filled with the specified color. Specifying a negative integer value for a certain side, will shrink or crop the image on this side. Consequently, specifying zero for a certain side will not change the image's extension on that side.

So, calling this function with all parameters left, top, right and bottom set to zero, is effectively the same as calling function Clone(FIBITMAP); setting all parameters left, top, right and bottom to value equal to or smaller than zero, my easily be substituted by a call to function Copy(FIBITMAP, Int32, Int32, Int32, Int32). Both these cases produce a new image, which is guaranteed not to be larger than the input image. Thus, since the specified color is not needed in these cases, color may be null.

Both parameters color and options work according to 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. For palletized images, the palette of the input image is transparently copied to the newly created enlarged or shrunken image, so any color look-ups are performed on this palette.

Examples
// create a white color
RGBQUAD c;
c.rgbRed = 0xFF;
c.rgbGreen = 0xFF;
c.rgbBlue = 0xFF;
c.rgbReserved = 0x00;

// add a white, symmetric 10 pixel wide border to the image
dib2 = FreeImage_EnlargeCanvas(dib, 10, 10, 10, 10, c, FREE_IMAGE_COLOR_OPTIONS.FICO_RGB);

// add white, 20 pixel wide stripes to the top and bottom side of the image
dib3 = FreeImage_EnlargeCanvas(dib, 0, 20, 0, 20, c, FREE_IMAGE_COLOR_OPTIONS.FICO_RGB);

// add white, 30 pixel wide stripes to the right side of the image and
// cut off the 40 leftmost pixel columns
dib3 = FreeImage_EnlargeCanvas(dib, -40, 0, 30, 0, c, FREE_IMAGE_COLOR_OPTIONS.FICO_RGB);
See Also
previous page start next page