Función StretchDIBits (wingdi.h)

Artículo
03/08/2023

La función StretchDIBits copia los datos de color de un rectángulo de píxeles en una imagen DIB, JPEG o PNG en el rectángulo de destino especificado. Si el rectángulo de destino es mayor que el rectángulo de origen, esta función amplía las filas y columnas de datos de color para ajustarse al rectángulo de destino. Si el rectángulo de destino es menor que el rectángulo de origen, esta función comprime las filas y columnas mediante la operación de trama especificada.

Sintaxis

int StretchDIBits(
  [in] HDC              hdc,
  [in] int              xDest,
  [in] int              yDest,
  [in] int              DestWidth,
  [in] int              DestHeight,
  [in] int              xSrc,
  [in] int              ySrc,
  [in] int              SrcWidth,
  [in] int              SrcHeight,
  [in] const VOID       *lpBits,
  [in] const BITMAPINFO *lpbmi,
  [in] UINT             iUsage,
  [in] DWORD            rop
);

Parámetros

[in] hdc

Controlar el contexto del dispositivo de destino.

[in] xDest

Coordenada x, en unidades lógicas, de la esquina superior izquierda del rectángulo de destino.

[in] yDest

Coordenada y, en unidades lógicas, de la esquina superior izquierda del rectángulo de destino.

[in] DestWidth

Ancho, en unidades lógicas, del rectángulo de destino.

[in] DestHeight

Alto, en unidades lógicas, del rectángulo de destino.

[in] xSrc

Coordenada x, en píxeles, del rectángulo de origen de la imagen.

[in] ySrc

Coordenada y, en píxeles, del rectángulo de origen de la imagen.

[in] SrcWidth

Ancho, en píxeles, del rectángulo de origen de la imagen.

[in] SrcHeight

Alto, en píxeles, del rectángulo de origen de la imagen.

[in] lpBits

Puntero a los bits de imagen, que se almacenan como una matriz de bytes. Para obtener más información, vea la sección Comentarios.

[in] lpbmi

Puntero a una estructura BITMAPINFO que contiene información sobre la DIB.

[in] iUsage

Especifica si se proporcionó el miembro indexColors de la estructura BITMAPINFO y, si es así, si los valores o índices de los valores o índices explícitos son rojo, verde, azul (RGB). El parámetro iUsage debe ser uno de los valores siguientes.

Valor	Significado
DIB_PAL_COLORS	La matriz contiene índices de 16 bits en la paleta lógica del contexto del dispositivo de origen.
DIB_RGB_COLORS	La tabla de colores contiene valores RGB literales.

Para obtener más información, vea la sección Comentarios.

[in] rop

Código de operación ráster que especifica cómo se combinarán los píxeles de origen, el pincel actual del contexto del dispositivo de destino y los píxeles de destino para formar la nueva imagen. Para obtener una lista de algunos códigos de operación ráster comunes, consulte BitBlt.

Valor devuelto

Si la función se realiza correctamente, el valor devuelto es el número de líneas de examen copiadas. Tenga en cuenta que este valor puede ser negativo para el contenido reflejado.

Si se produce un error en la función o no se copian líneas de examen, el valor devuelto es 0.

Si el controlador no puede admitir la imagen de archivo JPEG o PNG pasada a StretchDIBits, se producirá un error en la función y se devolverá GDI_ERROR. Si se produce un error, la aplicación debe revertirse a su propia compatibilidad con JPEG o PNG para descomprimir la imagen en un mapa de bits y, a continuación, pasar el mapa de bits a StretchDIBits.

Comentarios

El origen de una DIB de abajo arriba es la esquina inferior izquierda; el origen de una DIB de arriba abajo es la esquina superior izquierda.

StretchDIBits crea una imagen reflejada de un mapa de bits si los signos de los parámetros nSrcWidth y nDestWidth , o si los parámetros nSrcHeight y nDestHeight difieren. Si nSrcWidth y nDestWidth tienen signos diferentes, la función crea una imagen reflejada del mapa de bits a lo largo del eje X. Si nSrcHeight y nDestHeight tienen signos diferentes, la función crea una imagen reflejada del mapa de bits a lo largo del eje y.

StretchDIBits crea una imagen de arriba abajo si el signo del miembro biHeight de la estructura BITMAPINFOHEADER para la DIB es negativo. Para obtener un ejemplo de código, vea Cambiar el tamaño de una imagen JPEG o PNG.

Esta función permite pasar una imagen JPEG o PNG como imagen de origen. El modo en que se usa cada parámetro sigue siendo el mismo, excepto:

Si el miembro biCompression de BITMAPINFOHEADER es BI_JPEG o BI_PNG, lpBits apunta a un búfer que contiene una imagen JPEG o PNG, respectivamente. El miembro biSizeImage de la estructura BITMAPINFOHEADER especifica el tamaño del búfer. El parámetro iUsage debe establecerse en DIB_RGB_COLORS. El parámetro dwRop debe establecerse en SRCCOPY.
Para garantizar una cola de metarchivo adecuada durante la impresión, las aplicaciones deben llamar al escape CHECKJPEGFORMAT o CHECKPNGFORMAT para comprobar que la impresora reconoce la imagen JPEG o PNG, respectivamente, antes de llamar a StretchDIBits.

ICM: La administración de colores se realiza si se ha habilitado la administración de colores con una llamada a SetICMMode con el parámetro iEnableICM establecido en ICM_ON. Si el mapa de bits especificado por lpBitsInfo tiene un BITMAPV4HEADER que especifica los miembros gamma y endpoints, o un BITMAPV5HEADER que especifica los miembros gamma y endpoints o los miembros profileData y profileSize, la llamada trata los píxeles del mapa de bits como se expresa en el espacio de colores descrito por esos miembros, en lugar de en el espacio de color de origen del contexto del dispositivo.

Ejemplos

Para obtener un ejemplo, vea Cambiar el tamaño de una imagen JPEG o PNG.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 2000 Professional [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows 2000 Server [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	wingdi.h (incluye Windows.h)
Library	Gdi32.lib
Archivo DLL	Gdi32.dll