freeimage.h

FreeImage_EnlargeCanvas

DLL_API FIBITMAP *DLL_CALLCONV FreeImage_EnlargeCanvas(FIBITMAP *src, int left, int
top, int right, int bottom, const void *color, int options);

Amplía o encoge una imagen seleccionando cada lado y rellena las nuevas áreas añadidas con el color de fondo especificado.

Parámetros

  • dib: La imagen a ampliar o encoger.
  • left: El número de pixels que debe debe ampliarse la imagen por el lado izquierdo. Los valores negativos encogen la imagen por el lado izquierdo.
  • top: El número de pixels que debe debe ampliarse la imagen por el lado superior. Los valores negativos encogen la imagen por el lado superior.
  • right: El número de pixels que debe debe ampliarse la imagen por el lado derecho. Los valores negativos encogen la imagen por el lado derecho.
  • bottom: El número de pixels que debe debe ampliarse la imagen por el lado inferior. Los valores negativos encogen la imagen por el lado inferior.
  • color: El color del que los lados ampliados de la imagen deben rellenarse.
  • options: Opciones que afectan al proceso de búsqueda de color para imágenes con paleta.

La función retorna un puntero a la nueva imagen ampliada o encogida si tiene éxito, NULL en caso contrario. Esta función falla si la imagen de entrada es NULL o si el puntero a color es NULL, siempre que al menos uno de los parámetros left, top, right o bottom sea mayor que cero. Esta función también retorna NULL si el nuevo tamaño de la imagen será negativo en la dirección x o y.

Esta función amplia o encoge una imagen por cada lado seleccionado. El propósito principal de esto es añadir bordes a una imagen. Para añadir un borde a cualquiera de los lados de una imagen, se debe pasar un valor entero positivo a cualquiera de los parámetros left, top, right o bottom. Este valor representa la anchura del borde en pixels. Las nuevas partes de la imagen creadas (las áreas de borde) son rellenadas con el color especificado. Especificando un valor entero negativo para cierto lado encogera o cortará la imagen por ese lado. En consecuencia, especificar cero para un lado no modificará la extensión de la imgen en ese lado.

Así que, llamar a esta fumción con todos los parámetros left, top, right y bottom a cero, es lo mismo que llamar a la función FreeImage_Clone; usar valores menores o iguales a cer para todos los parámetros left, top, right y bottom, puede ser sustituido fácilmente por una llamada a la función FreeImage_Copy. Ambos casos producen una nueva imagen que está garantizado que no será más grande que la imagen de entrada. Además, dado que no es necesario especificar un color en esos casos, el puntero a color puede ser NULL.

Los parámetros color y options funcionan de forma similar a como lo hacen en la función FreeImage_FillBackground. Así que se puede consultar la documentación referente a FreeImage_FillBackground para aprender más sobre esos parámetros. Para imágenes con paleta,, la paleta de la imagen de entrada src es copiada de forma transparente a la nueva imagen ampliada o engogida creada, así que cualquier búsqueda de color se hace sobre esa paleta.

A continuación se muestran algunos ejemplos que muestran el uso de los parámetros left, top, right y 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);