SetDIBitsToDevice

La función SetDIBitsToDevice asigna los pixels en el rectángulo especificado en el dispositivo que está asociado con el contexto de dispositivo de destino usando los datos de colores desde el mapa de bits independiente del dispositivo (DIB).

Sintaxis

int SetDIBitsToDevice(

    HDC hdc,                   // manipulador de contexto de dispositivo
    int XDest,                 // coordenada x de la esquina superior izquierda del rectángulo destino
    int YDest,                 // coordenada y de la esquina superior izquierda del rectángulo destino
    DWORD dwWidth,             // anchura del rectángulo origen
    DWORD dwHeight,            // altura del rectángulo origen
    int XSrc,                  // coordenada x de la esquina inferior izquierda del rectángulo origen
    int YSrc,                  // coordenada y de la esquina inferior izquierda del rectángulo origen
    UINT uStartScan,           // primera línea de rastreo en el array 
    UINT cScanLines,           // número de líneas de rastreo
    CONST VOID * lpvBits,      // dirección del array con los bits del DIB
    CONST BITMAPINFO * lpbmi,  // dirección de la estructura con la información del mapa de bits
    UINT fuColorUse            // índices de paleta o RGB
   );

Parámetros:

hdc: identifica el contexto de dispositivo.

XDest: especifica la coordenada x, en unidades lógicas, de la esquina superior izquierda del rectángulo destino.

YDest: especifica la coordenada y, en unidades lógicas, de la esquina superior izquierda del rectángulo destino.

dwWidth: especifica la anchura, en unidades lógicas, del DIB.

dwHeight: especifica la altura, en unidades lógicas, del DIB.

XSrc: especifica la coordenada x, en unidades lógicas, de la esquina inferior izquierda del DIB.

YSrc: especifica la coordenada y, en unidades lógicas, de la esquina inferior izquierda del DIB.

uStartScan: especifica la línea de rastreo de inicio del DIB.

cScanLines: especifica el número de líneas de rastreo del DIB contenidas en el array apuntado por el parámetro lpvBits.

lpvBits: puntero a los datos de colores del DIB almacenados como un array de bytes.

lpbmi: puntero a una estructura BITMAPINFO que contiene información sobre el DIB.

fuColorUse: especifica si el miembro bmiColors de la estructura BITMAPINFO contiene valores rojo, verde y azul (RGB) explícitos o índices de paleta. El parámetro fuColorUse debe tener uno de los siguientes valores:

Valor de retorno

Si la función tiene éxito, el valor de retorno es el número de líneas copiadas.

Si la función falla, el valor de retorno es cero. Para obtener información más detallada sobre el error, llamar a la función GetLastError.

Observaciones

Las velocidades de visualización del mapa de bits óptimas se obtienen cuando los bits del mapa de bits son índices dentro de la paleta del sistema.

Las aplicaciones pueden recuperar los colores de la paleta del sistema y los índices mediante una llamada a la función GetSystemPaletteEntries. Una vez que los colores y los índices has sido recuperados, la aplicación puede crear el DIB. Para más información, ver el tema de la paleta del sistema.

El origen para DIBs de abajo-arriba es la esquina inferior izquierda del mapa de bits; el origen para DIBs de arriba-abajo es la esquina superior izquierda del mapa de bits.

Para reducir la cantidad de memoria necesaria para asignar los bits en grandes mapas de bits independientes del dispositivo a una superficie, la aplicación puede dividir en bandas la salida mediante llamadas repetidas a la función SetDIBitsToDevice, situando una porción diferente del mapa de bits en el array lpvBits cada vez. Los valores de los parámetros uStartScan y cScanLines identificarán la porción del mapa de bits contenida en el array lpvBits.

Windows 95: la función SetDIBitsToDevice devuelve un error si es llamada por un proceso que esté ejecutándose en segundo plano mientras una ventana MS-DOS de pantalla completa se está ejecutando en primer plano.