view release on metacpan or  search on metacpan

src/Source/FreeImageToolkit/Background.cpp  view on Meta::CPAN

}

/** @brief Allocates a new image of the specified width, height and bit depth and optionally
 fills it with the specified color.

 This function is an extension to FreeImage_Allocate, 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 FreeImage_Allocate, followed by a
 call to FreeImage_FillBackground. This is why both parameters color and options behave the
 same as it is documented for function FreeImage_FillBackground. So, please refer to the
 documentation of FreeImage_FillBackground 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. However, if the
 image to be created is a palletized image and if palette is not NULL, the memory pointed to
 by the palette pointer is assumed to be at least as large as size of a fully populated
 palette for the desired bit depth. So, for an 8-bit image, this size is 256 x sizeof(RGBQUAD),
 for an 4-bit image it is 16 x sizeof(RGBQUAD) and it is 2 x sizeof(RGBQUAD) for a 1-bit
 image. In other words, this function does not support partial palettes.

 However, specifying a palette is not necessarily needed, even for palletized images. This
 function is capable of implicitly creating a palette, if parameter palette is NULL. If the
 specified background color is a greyscale value (red = green = blue) or if option
 FI_COLOR_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 single color is injected into the otherwise black-initialized
 palette. For this operation, option FI_COLOR_ALPHA_IS_INDEX is implicit, so the specified
 color is applied to the palette entry, specified by the background color's rgbReserved
 member. The image is then filled with this palette index.

 This function returns a newly created image as function FreeImage_Allocate 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.

 @param width The desired width in pixels of the new image.
 @param height The desired height in pixels of the new image.
 @param bpp The desired bit depth of the new image.
 @param color A pointer to an RGBQUAD structure, that provides the color to be used for
 filling the image.
 @param options Options that affect the color search process for palletized images.
 @param red_mask Specifies the bits used to store the red components of a pixel.
 @param green_mask Specifies the bits used to store the green components of a pixel.
 @param blue_mask Specifies the bits used to store the blue components of a pixel.
 @return Returns a pointer to a newly allocated image on success, NULL otherwise.
 */
FIBITMAP * DLL_CALLCONV
FreeImage_AllocateEx(int width, int height, int bpp, const RGBQUAD *color, int options, const RGBQUAD *palette, unsigned red_mask, unsigned green_mask, unsigned blue_mask) {
	return FreeImage_AllocateExT(FIT_BITMAP, width, height, bpp, ((void *)color), options, palette, red_mask, green_mask, blue_mask);
}

/** @brief Enlarges or shrinks an image selectively per side and fills newly added areas
 with the specified background color.

 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 FreeImage_Clone; 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 FreeImage_Copy. 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,
 the pointer color may be NULL.

 Both parameters color and options work according to function FreeImage_FillBackground. So,
 please refer to the documentation of FreeImage_FillBackground to learn more about parameters
 color and options. For palletized images, the palette of the input image src is
 transparently copied to the newly created enlarged or shrunken image, so any color
 look-ups are performed on this palette.

 Here are some examples, that illustrate, how to use the parameters left, top, right and
 bottom:

 // 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, FI_COLOR_IS_RGB_COLOR);

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

 // 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, FI_COLOR_IS_RGB_COLOR);

 This function fails if either the input image is NULL or the pointer to the color is
 NULL, while at least on of left, top, right and bottom is greater than zero. This
 function also returns NULL, if the new image's size will be negative in either x- or
 y-direction.

 @param dib The image to be enlarged or shrunken.
 @param left The number of pixels, the image should be enlarged on its left side. Negative
 values shrink the image on its left side.
 @param top The number of pixels, the image should be enlarged on its top side. Negative
 values shrink the image on its top side.
 @param right The number of pixels, the image should be enlarged on its right side. Negative
 values shrink the image on its right side.
 @param bottom The number of pixels, the image should be enlarged on its bottom side. Negative
 values shrink the image on its bottom side.
 @param color The color, the enlarged sides of the image should be filled with.
 @param options Options that affect the color search process for palletized images.
 @return Returns a pointer to a newly allocated enlarged or shrunken image on success,
 NULL otherwise. This function fails if either the input image is NULL or the pointer to the
 color is NULL, while at least on of left, top, right and bottom is greater than zero. This
 function also returns NULL, if the new image's size will be negative in either x- or