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:
FreeImageAPIAssembly: FreeImageNET (in FreeImageNET.dll)
Syntax
C# |
---|
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() |
Visual Basic (Declaration) |
---|
Public Shared Function EnlargeCanvas(Of T As {Structure, New}) ( _ dib As FIBITMAP, _ left As Integer, _ top As Integer, _ right As Integer, _ bottom As Integer, _ color As Nullable(Of T), _ options As FREE_IMAGE_COLOR_OPTIONS _ ) As FIBITMAP |
Visual C++ |
---|
public: generic<typename T> where T : value class, gcnew() static FIBITMAP EnlargeCanvas( FIBITMAP dib, int left, int top, int right, int bottom, Nullable<T> color, FREE_IMAGE_COLOR_OPTIONS options ) |
Parameters
- dib
- Type: FreeImageAPI..::.FIBITMAP
Handle to a FreeImage bitmap.
- left
- Type: System..::.Int32
The number of pixels, the image should be enlarged on its left side. Negative values shrink the image on its left side.
- top
- Type: System..::.Int32
The number of pixels, the image should be enlarged on its top side. Negative values shrink the image on its top side.
- right
- Type: System..::.Int32
The number of pixels, the image should be enlarged on its right side. Negative values shrink the image on its right side.
- bottom
- Type: System..::.Int32
The number of pixels, the image should be enlarged on its bottom side. Negative values shrink the image on its bottom side.
- color
- Type: System..::.Nullable<(Of <(T>)>)
The color, the enlarged sides of the image should be filled with.
- options
- Type: FreeImageAPI..::.FREE_IMAGE_COLOR_OPTIONS
Options that affect the color search process for palletized images.
Type Parameters
- T
- The type of the specified color.
Return Value
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 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. 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);
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);