Función CreateDIBSection (wingdi.h)

Artículo
03/08/2023

La función CreateDIBSection crea una DIB en la que las aplicaciones pueden escribir directamente. La función proporciona un puntero a la ubicación de los valores de bits del mapa de bits. Puede proporcionar un identificador a un objeto de asignación de archivos que la función usará para crear el mapa de bits, o bien puede permitir que el sistema asigne la memoria para el mapa de bits.

Sintaxis

HBITMAP CreateDIBSection(
  [in]  HDC              hdc,
  [in]  const BITMAPINFO *pbmi,
  [in]  UINT             usage,
  [out] VOID             **ppvBits,
  [in]  HANDLE           hSection,
  [in]  DWORD            offset
);

Parámetros

[in] hdc

Identificador de un contexto de dispositivo. Si el valor de iUsage es DIB_PAL_COLORS, la función usa la paleta lógica de este contexto del dispositivo para inicializar los colores dib.

[in] pbmi

Puntero a una estructura BITMAPINFO que especifica varios atributos de la DIB, incluidas las dimensiones y los colores del mapa de bits.

[in] usage

El tipo de datos contenidos en el miembro de la matriz imcColors de la estructura BITMAPINFO a la que apunta pbmi (índices de paleta lógica o valores RGB literales). Se definen los valores siguientes.

Valor	Significado
DIB_PAL_COLORS	El miembro imcColors es una matriz de índices de 16 bits en la paleta lógica del contexto del dispositivo especificado por hdc.
DIB_RGB_COLORS	La estructura BITMAPINFO contiene una matriz de valores RGB literales.

[out] ppvBits

Puntero a una variable que recibe un puntero a la ubicación de los valores de bits DIB.

[in] hSection

Identificador de un objeto de asignación de archivos que la función usará para crear la DIB. Este parámetro puede ser NULL.

Si hSection no es NULL, debe ser un identificador para un objeto de asignación de archivos creado llamando a la función CreateFileMapping con la marca PAGE_READWRITE o PAGE_WRITECOPY. No se admiten secciones dib de solo lectura. Los identificadores creados por otros medios provocarán un error en CreateDIBSection .

Si hSection no es NULL, la función CreateDIBSection busca los valores de bits de mapa de bits en dwOffset de desplazamiento en el objeto de asignación de archivos al que hace referencia hSection. Una aplicación puede recuperar posteriormente el identificador hSection llamando a la función GetObject con el HBITMAP devuelto por CreateDIBSection.

Si hSection es NULL, el sistema asigna memoria para la DIB. En este caso, la función CreateDIBSection omite el parámetro dwOffset . Una aplicación no puede obtener más adelante un identificador para esta memoria. El miembro dshSection de la estructura DIBSECTION rellenada llamando a la función GetObject será NULL.

[in] offset

Desplazamiento desde el principio del objeto de asignación de archivos al que hace referencia hSection donde se va a comenzar el almacenamiento de los valores de bits del mapa de bits. Este valor se omite si hSection es NULL. Los valores de bits del mapa de bits se alinean en límites de doble palabra, por lo que dwOffset debe ser un múltiplo del tamaño de un DWORD.

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto es un identificador de la DIB recién creada y *ppvBits apunta a los valores de bits del mapa de bits.

Si se produce un error en la función, el valor devuelto es NULL y *ppvBits es NULL. Para obtener información de error extendida, llame a GetLastError.

GetLastError puede devolver el siguiente valor:

Código de error	Descripción
ERROR_INVALID_PARAMETER	Uno o varios de los parámetros de entrada no son válidos.

Comentarios

Como se indicó anteriormente, si hSection es NULL, el sistema asigna memoria para la DIB. El sistema cierra el identificador de esa memoria cuando se elimina posteriormente la DIB mediante una llamada a la función DeleteObject . Si hSection no es NULL, debe cerrar el identificador de memoria de hSection después de llamar a DeleteObject para eliminar el mapa de bits.

No se puede pegar una sección DIB de una aplicación en otra.

CreateDIBSection no usa los parámetros BITMAPINFOHEADERbiXPelsPerMeter o biYPelsPerMeter y no proporcionará información de resolución en la estructura BITMAPINFO .

Debe garantizar que el subsistema GDI haya completado cualquier dibujo en un mapa de bits creado por CreateDIBSection antes de dibujar el mapa de bits usted mismo. El acceso al mapa de bits debe estar sincronizado. Para ello, llame a la función GdiFlush . Esto se aplica a cualquier uso del puntero a los valores de bits del mapa de bits, incluido pasar el puntero en llamadas a funciones como SetDIBits.

ICM: No se realiza ninguna administración de colores.

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