freeimage.h

FreeImage_AllocateExT

DLL_API FIBITMAP *DLL_CALLCONV FreeImage_AllocateExT(FREE_IMAGE_TYPE type, int width,
int height, int bpp, const void *color, int options, const RGBQUAD *palette, unsigned 
red_mask FI_DEFAULT(0), unsigned green_mask FI_DEFAULT(0), unsigned blue_mask
FI_DEFAULT(0));

Crea una nueva imagen del tipo, anchura, altura y profundidad de bits especificados y opcionalmente la rellena con el color indicado.

Parámetros

  • type: Especifica el tipo de la nueva imagen.
  • width: Anchura deseada en pixels de la nueva imagen.
  • height: Altura deseada en pixels de la nueva imagen.
  • bpp: Profundidad de bits deseada de la nueva imagen.
  • color: Un puntero al valor de color a usar para rellenar la imagen. La memoria apuntada por este puntero se asime que tiene al menos el tamaño de valor de color de la imagen, pero nunca menos que el tamaño de una estructura RGBQUAD.
  • options: Opciones que afectatan al proceso de búsqueda del color para imágenes con paleta.
  • red_mask: Especifica los bits usados para almacenar el componente rojo de un pixel.
  • green_mask: Especifica los bits usados para almacenar el componente verde de un pixel.
  • blue_mask: Especifica los bits usados para almacenar el componente azul de un pixel.

La función retorna un puntero a la nueva imagen creada si tiene éxito, o NULL en caso contrario.

Esta función es una extensión de FreeImage_AllocateT, que adicionalmente soporta la especificación de una paleta para ser asignada a la nueva imagen creada, así como un color de fondo, que se usará para rellenar la nueva imagen.

Básicamente, esta función internamente llamaa a la función FreeImage_AllocateT, y después a FreeImage_FillBackground. Es por eso que los parámetros color y options se comportan del mismo modo que se documenta 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.

La paleta especificada mediante el parámetro palette sólo se copia a la nueva imagen creada, si es una imagen de tipo FIT_BITMAP y la profundidad de bits deseada es menor o igual a 8-bit por pixel. En otras palabras, el parámetro palette sólo se toma en cuenta para imágenes con paleta. Sin embargo, si se cumplen las condiciones anteriores y palette no es NULL, se asume que la memoria apuntada por el puntero palette es al menos tan grande como el tamaño de una paleta completamente asignada para la profundidad de bits deseada. Así, para una imagen de 8-bit, este tamaño es 256 x sizeof(RGBQUAD), para una imagen de 4-bit es 16 x sizeof(RGBQUAD) y para una imagen de 1-bit es 2 x sizeof(RGBQUAD). En otras palabras, esta función no soporta paletas parciales.

Sin embargo, especificar una paleta no es necesario, incluso para imágenes con paleta. Esta función es capaz de crear una paleta implícitamente, ei el parámetro palette es NULL. Si el color de fonde especificado es un valor de gris, (red = green = blue) o si se especifica la opción FI_COLOR_ALPHA_IS_INDEX, se creará una paleta de escala de grises. Para imágenes de 1-bit se creará una paleta monocromo, consistente sólo de negro y blanco, sólo si el color de fondo especifiado es blanco o negro. En cualquier caso, los colores más oscuros se almacenarás en los índices de paleta más pequeños.

Si el color de fondo especificado no es un valor de gris, o no es blanco ni negro para una imagen de 1-bit, únicamente ese color será inyectado en, de otro modo, una paleta iniciada en negro. Para esta operación, la opción FI_COLOR_ALPHA_IS_INDEX queda implícita, asi que el color especificado es aplicado a la entrada de la paleta especificada por el miembro rgbReserved del color de fondo. La imagen es entonces rellenada con ese índice de la paleta.

Esta función retorna una nueva imagen creada, igual que hace la función FreeImage_AllocateT, si tanto el parámetro color como palette son NULL. Si sólo color es NULL, la paleta apuntada por el parámetro palette es asignada inicialmente para la nueva imagen, si la imagen con paleta creada es de tipo FIT_BITMAP. Sin embargo, en el último caso, esta función retorna una imagen cuyos pixels serán inicializados con cero, asi que la imagen será rellenada con el color de la primera entrada en la paleta.