Read and write Microsoft Windows bitmap images. More...

Collaboration diagram for BMP:

Data Structures
struct	gdBmpInfo

struct	gdBmpWriteOptions
	Structured BMP writer options. More...

Macros
#define	GD_BMP_COMPRESS_NONE 0
	Write uncompressed BMP pixel data.

#define	GD_BMP_COMPRESS_RLE8 1
	Write BI_RLE8 compressed pixel data; valid only for 8 bpp output.

#define	GD_BMP_COMPRESS_RLE4 2
	Write BI_RLE4 compressed pixel data; valid only for 4 bpp output.

#define	GD_BMP_FLAG_NONE 0
	Use default BMP writer behavior.

#define	GD_BMP_FLAG_FORCE_V4HDR (1 << 0)
	Force output to use a BITMAPV4HEADER.

#define	GD_BMP_FLAG_QUANTIZE (1 << 1)
	Allow lossy truecolor-to-indexed conversion for 1, 4, or 8 bpp output.

#define	GD_BMP_FLAG_RGB555 (1 << 2)
	Use RGB555 bit masks instead of RGB565 for 16 bpp output.

Functions
gdImagePtr	gdImageCreateFromBmp (FILE *inFile)
	Create an image from a BMP stdio file.

gdImagePtr	gdImageCreateFromBmpPtr (int size, void *data)
	Create an image from a BMP memory buffer.

gdImagePtr	gdImageCreateFromBmpCtx (gdIOCtxPtr infile)
	Create an image from BMP data read through a gdIOCtx.

void	gdBmpInfoInit (gdBmpInfo *info)
	Initialize a gdBmpInfo structure to default values.

int	gdBmpGetInfo (FILE infile, gdBmpInfo info)
	Read BMP file information from a stdio file.

int	gdBmpGetInfoCtx (gdIOCtxPtr infile, gdBmpInfo *info)
	Read BMP file information from a gdIOCtx.

int	gdBmpGetInfoPtr (int size, const void data, gdBmpInfo info)
	Read BMP file information from a memory buffer.

void *	gdImageBmpPtr (gdImagePtr im, int *size, int compression)
	Write an image as BMP data to a newly allocated memory buffer.

void	gdImageBmp (gdImagePtr im, FILE *outFile, int compression)
	Write an image as BMP data to a stdio file.

void	gdImageBmpCtx (gdImagePtr im, gdIOCtxPtr out, int compression)
	Write an image as BMP data to a gdIOCtx.

void	gdBmpWriteOptionsInit (gdBmpWriteOptions *options)
	Initialize a gdBmpWriteOptions structure to default values.

int	gdImageBmpWithOptions (gdImagePtr im, FILE outFile, const gdBmpWriteOptions options)
	Write an image as BMP data to a stdio file with explicit options.

int	gdImageBmpCtxWithOptions (gdImagePtr im, gdIOCtxPtr out, const gdBmpWriteOptions *options)
	Write an image as BMP data to a gdIOCtx with explicit options.

void *	gdImageBmpPtrWithOptions (gdImagePtr im, int size, const gdBmpWriteOptions options)
	Write an image as BMP data to a newly allocated memory buffer with explicit options.

void *	gdImageBmpPtrEx (gdImagePtr im, int *size, int bpp, int compression, int flags)
	Write an image as BMP data to a newly allocated memory buffer.

void	gdImageBmpEx (gdImagePtr im, FILE *outFile, int bpp, int compression, int flags)
	Write an image as BMP data to a stdio file.

void	gdImageBmpCtxEx (gdImagePtr im, gdIOCtxPtr out, int bpp, int compression, int flags)
	Write an image as BMP data to a gdIOCtx.

Detailed Description

Read and write Microsoft Windows bitmap images.

BMP support reads stdio files, gdIOCtx streams, or caller-provided memory buffers into gd images. Indexed BMP inputs are returned as palette images when possible, while direct-color BMP inputs are returned as truecolor images. The returned image is owned by the caller and must be destroyed with gdImageDestroy.

BMP output can use the legacy automatic-bit-depth APIs or the extended APIs that select a specific BMP bit depth, compression mode, and writer flags. The writer supports 1, 4, 8, 16, 24, and 32 bits per pixel. RLE4 is valid only for 4 bpp output, and RLE8 is valid only for 8 bpp output. BMP output handles and FILE streams are borrowed and are not closed by gd.

gdImagePtr im, roundtrip;
void *data;
int size;
 
im = gdImageCreateTrueColor(32, 32);
gdImageFilledRectangle(im, 0, 0, 31, 31, 0x336699);
 
data = gdImageBmpPtrEx(im, &size, 24, GD_BMP_COMPRESS_NONE,
                       GD_BMP_FLAG_NONE);
if (data != NULL) {
       roundtrip = gdImageCreateFromBmpPtr(size, data);
       gdFree(data);
       if (roundtrip != NULL) {
               gdImageDestroy(roundtrip);
       }
}
 
gdImageDestroy(im);

Function Documentation

◆ gdBmpGetInfo()

int gdBmpGetInfo	(	FILE *	infile,
		gdBmpInfo *	info
	)

Read BMP file information from a stdio file.

Parameters

infile	Pointer to the BMP FILE stream to read.
info	Pointer to a gdBmpInfo structure to receive the BMP information.

Returns: Returns 1 on success, or 0 on failure.

◆ gdBmpGetInfoCtx()

int gdBmpGetInfoCtx	(	gdIOCtxPtr	infile,
		gdBmpInfo *	info
	)

Read BMP file information from a gdIOCtx.

Parameters

infile	Pointer to the gdIOCtx input context.
info	Pointer to a gdBmpInfo structure to receive the BMP information.

Returns: Returns 1 on success, or 0 on failure.

◆ gdBmpGetInfoPtr()

int gdBmpGetInfoPtr	(	int	size,
		const void *	data,
		gdBmpInfo *	info
	)

Read BMP file information from a memory buffer.

Parameters

size	Size of the BMP memory buffer in bytes.
data	Pointer to the BMP memory buffer.
info	Pointer to a gdBmpInfo structure to receive the BMP information.

Returns: Returns 1 on success, or 0 on failure.

◆ gdBmpInfoInit()

void gdBmpInfoInit ( gdBmpInfo * info )

Initialize a gdBmpInfo structure to default values.

Parameters

info	Pointer to the gdBmpInfo structure to initialize.

◆ gdBmpWriteOptionsInit()

void gdBmpWriteOptionsInit ( gdBmpWriteOptions * options )

Initialize a gdBmpWriteOptions structure to default values.

Updates or changes to the default values are not guaranteed to be compatible with future versions of gd. Callers should not assume that the default values will remain the same across versions. This is not considered part of the API contract and may change without notice. Callers should always explicitly set the fields they care about after calling this function.

◆ gdImageBmp()

void gdImageBmp	(	gdImagePtr	im,
		FILE *	outFile,
		int	compression
	)

Write an image as BMP data to a stdio file.

gdImageBmp() uses automatic BMP bit-depth selection. A zero compression value writes uncompressed BMP data; a nonzero value requests legacy RLE output when the automatically selected BMP bit depth supports it. The image and outFile are borrowed for the duration of the call, and outFile is not closed by gd.

Parameters

im	The image to write.
outFile	Pointer to the output FILE stream.
compression	Legacy compression selector; zero disables RLE, nonzero requests RLE when supported by the selected output bit depth.

◆ gdImageBmpCtx()

void gdImageBmpCtx	(	gdImagePtr	im,
		gdIOCtxPtr	out,
		int	compression
	)

Write an image as BMP data to a gdIOCtx.

gdImageBmpCtx() uses automatic BMP bit-depth selection. A zero compression value writes uncompressed BMP data; a nonzero value requests legacy RLE output when the automatically selected BMP bit depth supports it. The image and out context are borrowed for the duration of the call, and out is not closed by gd.

Parameters

im	The image to write.
out	Pointer to the gdIOCtx output context.
compression	Legacy compression selector; zero disables RLE, nonzero requests RLE when supported by the selected output bit depth.

◆ gdImageBmpCtxEx()

void gdImageBmpCtxEx	(	gdImagePtr	im,
		gdIOCtxPtr	out,
		int	bpp,
		int	compression,
		int	flags
	)

Write an image as BMP data to a gdIOCtx.

gdImageBmpCtxEx() writes BMP output with explicit control over output bit depth, compression, and writer flags. Pass bpp as 0 for automatic selection, or as one of 1, 4, 8, 16, 24, or 32. For 16 bpp output, RGB565 masks are used by default and GD_BMP_FLAG_RGB555 selects RGB555 masks. The image and out context are borrowed for the duration of the call, and out is not closed by gd.

Parameters

im	The image to write.
out	Pointer to the gdIOCtx output context.
bpp	Requested output bit depth, or 0 for automatic selection.
compression	One of GD_BMP_COMPRESS_NONE, GD_BMP_COMPRESS_RLE8, or GD_BMP_COMPRESS_RLE4.
flags	Bitwise OR of GD_BMP_FLAG_* values.

◆ gdImageBmpCtxWithOptions()

int gdImageBmpCtxWithOptions	(	gdImagePtr	im,
		gdIOCtxPtr	out,
		const gdBmpWriteOptions *	options
	)

Write an image as BMP data to a gdIOCtx with explicit options.

Parameters

im	The image to write.
out	Pointer to the gdIOCtx output context.
options	Pointer to a gdBmpWriteOptions structure specifying output options.

Returns: 0 on success, or a nonzero error code on failure.

See also: gdBmpWriteOptionsInit gdBmpWriteOptions

◆ gdImageBmpEx()

void gdImageBmpEx	(	gdImagePtr	im,
		FILE *	outFile,
		int	bpp,
		int	compression,
		int	flags
	)

Write an image as BMP data to a stdio file.

gdImageBmpEx() writes BMP output with explicit control over output bit depth, compression, and writer flags. Pass bpp as 0 for automatic selection, or as one of 1, 4, 8, 16, 24, or 32. RLE4 is valid only for 4 bpp output and RLE8 is valid only for 8 bpp output. The image and outFile are borrowed for the duration of the call, and outFile is not closed by gd.

Parameters

im	The image to write.
outFile	Pointer to the output FILE stream.
bpp	Requested output bit depth, or 0 for automatic selection.
compression	One of GD_BMP_COMPRESS_NONE, GD_BMP_COMPRESS_RLE8, or GD_BMP_COMPRESS_RLE4.
flags	Bitwise OR of GD_BMP_FLAG_* values.

◆ gdImageBmpPtr()

void * gdImageBmpPtr	(	gdImagePtr	im,
		int *	size,
		int	compression
	)

Write an image as BMP data to a newly allocated memory buffer.

gdImageBmpPtr() uses automatic BMP bit-depth selection. A zero compression value writes uncompressed BMP data; a nonzero value requests legacy RLE output when the automatically selected BMP bit depth supports it. The image is borrowed for the duration of the call. On success, the returned buffer must be freed with gdFree().

Parameters

im	The image to write.
size	Output location for the returned buffer size in bytes.
compression	Legacy compression selector; zero disables RLE, nonzero requests RLE when supported by the selected output bit depth.

Returns: A newly allocated BMP buffer, or NULL on error.

◆ gdImageBmpPtrEx()

void * gdImageBmpPtrEx	(	gdImagePtr	im,
		int *	size,
		int	bpp,
		int	compression,
		int	flags
	)

Write an image as BMP data to a newly allocated memory buffer.

gdImageBmpPtrEx() writes BMP output with explicit control over output bit depth, compression, and writer flags. Pass bpp as 0 for automatic selection, or as one of 1, 4, 8, 16, 24, or 32. Explicit indexed output from a truecolor image is lossy and fails unless GD_BMP_FLAG_QUANTIZE is set. The image is borrowed for the duration of the call. On success, the returned buffer must be freed with gdFree().

Parameters

im	The image to write.
size	Output location for the returned buffer size in bytes.
bpp	Requested output bit depth, or 0 for automatic selection.
compression	One of GD_BMP_COMPRESS_NONE, GD_BMP_COMPRESS_RLE8, or GD_BMP_COMPRESS_RLE4.
flags	Bitwise OR of GD_BMP_FLAG_* values.

Returns: A newly allocated BMP buffer, or NULL on error.

◆ gdImageBmpPtrWithOptions()

void * gdImageBmpPtrWithOptions	(	gdImagePtr	im,
		int *	size,
		const gdBmpWriteOptions *	options
	)

Write an image as BMP data to a newly allocated memory buffer with explicit options.

Parameters

im	The image to write.
size	Output location for the returned buffer size in bytes.
options	Pointer to a gdBmpWriteOptions structure specifying output options.

Returns: A newly allocated BMP buffer, or NULL on error. The caller is responsible for freeing the buffer with gdFree().

See also: gdBmpWriteOptionsInit gdBmpWriteOptions

◆ gdImageBmpWithOptions()

int gdImageBmpWithOptions	(	gdImagePtr	im,
		FILE *	outFile,
		const gdBmpWriteOptions *	options
	)

Write an image as BMP data to a stdio file with explicit options.

Parameters

im	The image to write.
outFile	Pointer to the output FILE stream.
options	Pointer to a gdBmpWriteOptions structure specifying output options.

Returns: 0 on success, or a nonzero error code on failure.

See also: gdBmpWriteOptionsInit gdBmpWriteOptions

◆ gdImageCreateFromBmp()

gdImagePtr gdImageCreateFromBmp ( FILE * inFile )

Create an image from a BMP stdio file.

gdImageCreateFromBmp() reads from the current position of inFile and does not close it. On success, the returned image is owned by the caller and must be destroyed with gdImageDestroy.

Parameters

inFile Pointer to the BMP FILE stream to read.

Returns: A newly allocated image, or NULL on error.

◆ gdImageCreateFromBmpCtx()

gdImagePtr gdImageCreateFromBmpCtx ( gdIOCtxPtr infile )

Create an image from BMP data read through a gdIOCtx.

gdImageCreateFromBmpCtx() reads from infile and does not close it. On success, the returned image is owned by the caller and must be destroyed with gdImageDestroy.

Parameters

infile Pointer to the gdIOCtx input context.

Returns: A newly allocated image, or NULL on error.

◆ gdImageCreateFromBmpPtr()

gdImagePtr gdImageCreateFromBmpPtr	(	int	size,
		void *	data
	)

Create an image from a BMP memory buffer.

gdImageCreateFromBmpPtr() borrows data for the duration of the call. The caller retains ownership of the input buffer. On success, the returned image is owned by the caller and must be destroyed with gdImageDestroy.

Parameters

size	Size of the BMP memory buffer in bytes.
data	Pointer to the BMP memory buffer.

Returns: A newly allocated image, or NULL on error.

Data Structures

Macros

Functions

Detailed Description

Function Documentation

◆ gdBmpGetInfo()

◆ gdBmpGetInfoCtx()

◆ gdBmpGetInfoPtr()

◆ gdBmpInfoInit()

◆ gdBmpWriteOptionsInit()

◆ gdImageBmp()

◆ gdImageBmpCtx()

◆ gdImageBmpCtxEx()

◆ gdImageBmpCtxWithOptions()

◆ gdImageBmpEx()

◆ gdImageBmpPtr()

◆ gdImageBmpPtrEx()

◆ gdImageBmpPtrWithOptions()

◆ gdImageBmpWithOptions()

◆ gdImageCreateFromBmp()

◆ gdImageCreateFromBmpCtx()

◆ gdImageCreateFromBmpPtr()