1/******************************************************************************
2* libbmpread - tiny, fast bitmap (.bmp) image file loader *
3* <https://github.com/chazomaticus/libbmpread> *
4* Copyright (C) 2005, 2012, 2016, 2018 Charles Lindsay <chaz@chazomatic.us> *
5* *
6* This software is provided 'as-is', without any express or implied *
7* warranty. In no event will the authors be held liable for any damages *
8* arising from the use of this software. *
9* *
10* Permission is granted to anyone to use this software for any purpose, *
11* including commercial applications, and to alter it and redistribute it *
12* freely, subject to the following restrictions: *
13* *
14* 1. The origin of this software must not be misrepresented; you must not *
15* claim that you wrote the original software. If you use this software *
16* in a product, an acknowledgment in the product documentation would be *
17* appreciated but is not required. *
18* 2. Altered source versions must be plainly marked as such, and must not be *
19* misrepresented as being the original software. *
20* 3. This notice may not be removed or altered from any source distribution. *
21******************************************************************************/
22
23
24/* bmpread.h
25 * version 3.0
26 * 2018-02-02
27 */
28
29
30#ifndef __bmpread_h__
31#define __bmpread_h__
32
33#ifdef __cplusplus
34extern "C"
35{
36#endif
37
38
39/* Flags for bmpread() and bmpread_t (see below). Combine with bitwise OR.
40 */
41
42/* Output data as top line first (default is bottom line first). */
43#define BMPREAD_TOP_DOWN 1u
44
45/* Don't pad lines to span a multiple of four bytes (default does pad). */
46#define BMPREAD_BYTE_ALIGN 2u
47
48/* Allow loading of any size bitmap (default is bitmaps must be 2^n x 2^m). */
49#define BMPREAD_ANY_SIZE 4u
50
51/* Load and output an alpha channel (default is just color channels). */
52#define BMPREAD_ALPHA 8u
53
54
55/* The struct filled by bmpread(). Holds information about the image's pixels.
56 */
57typedef struct bmpread_t
58{
59 int width; /* Width in pixels. */
60 int height; /* Height in pixels. */
61
62 /* BMPREAD_* flags, defined above, combined with bitwise OR, that affect
63 * the format of data. These are set to the flags passed to bmpread().
64 */
65 unsigned int flags;
66
67 /* A buffer holding the pixel data of the image.
68 *
69 * By default, each pixel spans three bytes: the red, green, and blue color
70 * components in that order. However, with BMPREAD_ALPHA set in flags,
71 * each pixel spans four bytes: the red, green, blue, and alpha components
72 * in that order.
73 *
74 * Pixels are ordered left to right sequentially. By default, the bottom
75 * line comes first, proceeding upward. However, with BMPREAD_TOP_DOWN set
76 * in flags, the top line comes first, proceeding downward instead.
77 *
78 * Lines by default must span a multiple of four bytes. If the image width
79 * and pixel span don't yield a multiple of four (a non-issue for
80 * BMPREAD_ALPHA with four bytes per pixel), the end of each line is padded
81 * with up to three unused bytes to meet the requirement. For example,
82 * each line of an image three pixels wide, loaded without BMPREAD_ALPHA,
83 * will span 12 bytes (3 pixels * 3 (RGB) channels per pixel = 9, padded
84 * with 3 bytes up to the next multiple of 4). However, this behavior is
85 * disabled with BMPREAD_BYTE_ALIGN set in flags, in which case all lines
86 * span exactly width * pixel_span bytes.
87 */
88 unsigned char * data;
89
90} bmpread_t;
91
92
93/* Loads the specified bitmap file from disk and fills out a bmpread_t struct
94 * with data about it.
95 *
96 * Inputs:
97 * bmp_file - The filename of the bitmap file to load.
98 * flags - Any BMPREAD_* flags, defined above, combined with bitwise OR.
99 * Specify 0 (or BMPREAD_ALPHA if you want an alpha channel) for
100 * standard, OpenGL compliant behavior.
101 * p_bmp_out - Pointer to a bmpread_t struct to fill with information. Its
102 * contents on input are ignored. Must be freed with
103 * bmpread_free() when no longer needed.
104 *
105 * Returns:
106 * 0 if there's an error (file doesn't exist or is invalid, i/o error, etc.),
107 * or nonzero if the file loaded ok.
108 *
109 * Notes:
110 * The file must be a Windows 3 (not NT) or higher format bitmap file with any
111 * valid bit depth (1, 4, 8, 16, 24, or 32), and must not be compressed (no
112 * RLE).
113 *
114 * Default behavior is for bmpread() to return data in a format directly usable
115 * by OpenGL texture functions, e.g. glTexImage2D, format GL_RGB (or GL_RGBA if
116 * BMPREAD_ALPHA is in flags), type GL_UNSIGNED_BYTE. This implies a few
117 * oddities:
118 * - Lines are ordered bottom-first. To return data starting with the top
119 * line like you might otherwise expect, pass BMPREAD_TOP_DOWN in flags.
120 * - Lines are padded to span a multiple of four bytes. To return data with
121 * no padding, pass BMPREAD_BYTE_ALIGN in flags.
122 * - Images with a width or height that isn't a power of 2 will fail to load.
123 * To allow loading images of any size, pass BMPREAD_ANY_SIZE in flags.
124 * Note that passing any of these flags may cause the output to be unusable as
125 * an OpenGL texture, which may or may not matter to you.
126 *
127 * Most bitmap files can't include an alpha channel, so the default behavior is
128 * to ignore any alpha values present in the file. Pass BMPREAD_ALPHA in flags
129 * to capture alpha values from the file; in case of an absent alpha channel,
130 * alpha values are output as 255 (this can be changed by redefining
131 * BMPREAD_DEFAULT_ALPHA in bmpread.c). This allows fully loading 16- and
132 * 32-bit bitmaps, which *can* include an alpha channel.
133 */
134int bmpread(const char * bmp_file, unsigned int flags, bmpread_t * p_bmp_out);
135
136
137/* Frees memory allocated during bmpread(). Call bmpread_free() when you are
138 * done using the bmpread_t struct (e.g. after you have passed the data on to
139 * OpenGL).
140 *
141 * Inputs:
142 * p_bmp - The pointer you previously passed to bmpread().
143 *
144 * Returns:
145 * void
146 */
147void bmpread_free(bmpread_t * p_bmp);
148
149
150#ifdef __cplusplus
151}
152#endif
153
154#endif
155