CreateDIBSection

Crea un mapa de bits independiente del dispositivo (DIB) que las aplicaciones pueden escribir directamente. La función proporciona un puntero a la posición a los valores del mapa de bits. Se le puede suministrar un manipulador de fichero que la función usará para crear el mapa de bits, o se puede dejar al sistema operativo que reserve la memoria para el mapa de bits.

Sintaxis

HBITMAP CreateDIBSection(
    HDC hdc,                // manipulador del contexto de dispositivo
    CONST BITMAPINFO *pbmi, // dirección de la estructura que contiene el 
                            // tamaño, formato y datos de color del mapa de bits
    UINT iUsage,            // indicador de tipo de datos de color: valores RGB 
                            // o índices de paleta
    VOID **ppvBits,         // puntero a variable que recibirá un puntero a los
                            // valores de bits del mapa de bits
    HANDLE hSection,        // manipulador opcional al fichero de mapeo de objeto
    DWORD dwOffset          // desplazamiento de los valores de bits dentro del mapa
                            // de bits dentro del fichero de mapeo de objeto
   );

Parámetros

hdc: manipulador de contexto de dispositivo. Si el valor de iUsage es DIB_PAL_COLORS, la función usa la paleta lógica del contexto de dispositivo para inicializar los colores del mapa de bits independiente del dispositivo.

pbmi: puntero a estructura BITMAPINFO que especifica varios atributos del mapa de bits independiente del dispositivo, incluyendo las dimensiones del mapa de bits y colores.

iUsage: especifica el tipo de datos contenidos en miembro array bmiColors de la estructura BITMAPINFO apuntada por pbmi: índices de paleta lógica o valores RGB. Están definidos los siguientes valores:

ppvBits: apunta a una variable que recibe un puntero a la posición de los valores de los bits del mapa de bits independiente del dispositivo.

hSection: manipulador de un fichero de mapeo de objeto que la función puede usar para crear el bitmap independiente del dispositivo. Este parámetro puede ser NULL.

Si hSection no es NULL, debe ser un manipulador de un fichero de mapeo de objeto creado mediante una llamada a la función CreateFileMapping. Manipuladores creados por otros métodos pueden provocar que CreateDIBSection falle.

Si hSection no es NULL, la función CreateDIBSection busca los valores del mapa de bits con el desplazamiento dwOffset en el fichero de mapeo de objeto referenciado por hSection. Una aplicación puede recuperar más tarde el manipulador hSection mediante una llamada a GetObject con el manipulador HBITMAP devuelto por CreateDIBSection.

Si hSection es NULL, el sistema operativo reserva memoria para el mapa de bits independiente del dispositivo. En ese caso, la función CreateDIBSection ignora el parámetro dwOffset. Una aplicación no podrá obtener más adelante un manipulador a de memoria: el miembro dshSection de la estructura DIBSECTION rellenada por la llamada a GetObject será NULL.

dwOffset: especifica el desplazamiento a partir del principio dentro del fichero de mapeo de objeto referenciado por hSection a partir del comienzo de donde se almacenan los valores de los bits del mapa de bits. Este valor se ignora si hSection es NULL. Los valores de bit del mapa de bits se alinean por dobles palabras, así que dwOffset debe ser un múltiplo del tamaño de un DWORD.

Valor de retorno

Si la función tiene éxito, el valor de retorno es un manipulador del nuevo mapa de bits independiente del dispositivo, y *ppvBits apunta a los valores de bit del mapa de bits.

Si la función falla, el valor de retorno es NULL, y *ppvBits es NULL. Para obtener mayor información sobre el error, llamar a GetLastError.

Observaciones

Como se coménto más arriba, si hSection es NULL, el sistema operativo reserva memoria para el mapa de bits independiente del dispositivo. El sistema operativo cierra el manipulador a esa memoria cuando se borre el mapa de bits mediante una llamada a DeleteObject. Si hSection no es NULL, se debe cerrar el manipulador de memoria hSection explícitamente después de llamar a DeleteObject para borrar el mapa de bits.

Windows NT: es necesario garantizar que el subsistema GDI ha completado cualquier dibujado de un mapa de bits creado mediante CreateDIBSection antes de trazar el mapa de bits tu mismo. El acceso al mapa de bits debe ser sincronizado. Esto se hace mediante una llamada a la función GdiFlush. Esto se aplica a cualquier uso del puntero a los valores del mapa de bits, incluyendo pasadas del puntero en llamadas a funciones como SetDIBits.