My Project: openb3dlib.mod/openb3d/src/stb_image.h Source File

My Project

stb_image.h
Go to the documentation of this file.
1 #ifndef STBI_INCLUDE_STB_IMAGE_H
2 #define STBI_INCLUDE_STB_IMAGE_H
3
4 // To get a header file for this, either cut and paste the header,
5 // or create stb_image.h, #define STBI_HEADER_FILE_ONLY, and
6 // then include stb_image.c from it.
7
9 //
10 // Limitations:
11 // - no jpeg progressive support
12 // - non-HDR formats support 8-bit samples only (jpeg, png)
13 // - no delayed line count (jpeg) -- IJG doesn't support either
14 // - no 1-bit BMP
15 // - GIF always returns *comp=4
16 //
17 // Basic usage (see HDR discussion below):
18 // int x,y,n;
19 // unsigned char *data = stbi_load(filename, &x, &y, &n, 0);
20 // // ... process data if not NULL ...
21 // // ... x = width, y = height, n = # 8-bit components per pixel ...
22 // // ... replace '0' with '1'..'4' to force that many components per pixel
23 // // ... but 'n' will always be the number that it would have been if you said 0
24 // stbi_image_free(data)
25 //
26 // Standard parameters:
27 // int *x -- outputs image width in pixels
28 // int *y -- outputs image height in pixels
29 // int *comp -- outputs # of image components in image file
30 // int req_comp -- if non-zero, # of image components requested in result
31 //
32 // The return value from an image loader is an 'unsigned char *' which points
33 // to the pixel data. The pixel data consists of *y scanlines of *x pixels,
34 // with each pixel consisting of N interleaved 8-bit components; the first
35 // pixel pointed to is top-left-most in the image. There is no padding between
36 // image scanlines or between pixels, regardless of format. The number of
37 // components N is 'req_comp' if req_comp is non-zero, or *comp otherwise.
38 // If req_comp is non-zero, *comp has the number of components that _would_
39 // have been output otherwise. E.g. if you set req_comp to 4, you will always
40 // get RGBA output, but you can check *comp to easily see if it's opaque.
41 //
42 // An output image with N components has the following components interleaved
43 // in this order in each pixel:
44 //
45 // N=#comp components
46 // 1 grey
47 // 2 grey, alpha
48 // 3 red, green, blue
49 // 4 red, green, blue, alpha
50 //
51 // If image loading fails for any reason, the return value will be NULL,
52 // and *x, *y, *comp will be unchanged. The function stbi_failure_reason()
53 // can be queried for an extremely brief, end-user unfriendly explanation
54 // of why the load failed. Define STBI_NO_FAILURE_STRINGS to avoid
55 // compiling these strings at all, and STBI_FAILURE_USERMSG to get slightly
56 // more user-friendly ones.
57 //
58 // Paletted PNG, BMP, GIF, and PIC images are automatically depalettized.
59 //
60 // ===========================================================================
61 //
62 // iPhone PNG support:
63 //
64 // By default we convert iphone-formatted PNGs back to RGB; nominally they
65 // would silently load as BGR, except the existing code should have just
66 // failed on such iPhone PNGs. But you can disable this conversion by
67 // by calling stbi_convert_iphone_png_to_rgb(0), in which case
68 // you will always just get the native iphone "format" through.
69 //
70 // Call stbi_set_unpremultiply_on_load(1) as well to force a divide per
71 // pixel to remove any premultiplied alpha *only* if the image file explicitly
72 // says there's premultiplied data (currently only happens in iPhone images,
73 // and only if iPhone convert-to-rgb processing is on).
74 //
75 // ===========================================================================
76 //
77 // HDR image support (disable by defining STBI_NO_HDR)
78 //
79 // stb_image now supports loading HDR images in general, and currently
80 // the Radiance .HDR file format, although the support is provided
81 // generically. You can still load any file through the existing interface;
82 // if you attempt to load an HDR file, it will be automatically remapped to
83 // LDR, assuming gamma 2.2 and an arbitrary scale factor defaulting to 1;
84 // both of these constants can be reconfigured through this interface:
85 //
86 // stbi_hdr_to_ldr_gamma(2.2f);
87 // stbi_hdr_to_ldr_scale(1.0f);
88 //
89 // (note, do not use _inverse_ constants; stbi_image will invert them
90 // appropriately).
91 //
92 // Additionally, there is a new, parallel interface for loading files as
93 // (linear) floats to preserve the full dynamic range:
94 //
95 // float *data = stbi_loadf(filename, &x, &y, &n, 0);
96 //
97 // If you load LDR images through this interface, those images will
98 // be promoted to floating point values, run through the inverse of
99 // constants corresponding to the above:
100 //
101 // stbi_ldr_to_hdr_scale(1.0f);
102 // stbi_ldr_to_hdr_gamma(2.2f);
103 //
104 // Finally, given a filename (or an open file or memory block--see header
105 // file for details) containing image data, you can query for the "most
106 // appropriate" interface to use (that is, whether the image is HDR or
107 // not), using:
108 //
109 // stbi_is_hdr(char *filename);
110 //
111 // ===========================================================================
112 //
113 // I/O callbacks
114 //
115 // I/O callbacks allow you to read from arbitrary sources, like packaged
116 // files or some other source. Data read from callbacks are processed
117 // through a small internal buffer (currently 128 bytes) to try to reduce
118 // overhead.
119 //
120 // The three functions you must define are "read" (reads some bytes of data),
121 // "skip" (skips some bytes of data), "eof" (reports if the stream is at the end).
122
123
124 #ifndef STBI_NO_STDIO
125
126 #if defined(_MSC_VER) && _MSC_VER >= 0x1400
127 #define _CRT_SECURE_NO_WARNINGS // suppress bogus warnings about fopen()
128 #endif
129
130 #include <stdio.h>
131 #endif
132
133 #define STBI_VERSION 1
134
135 enum
136 {
137 STBI_default = 0, // only used for req_comp
138
139 STBI_grey = 1,
140 STBI_grey_alpha = 2,
141 STBI_rgb = 3,
142 STBI_rgb_alpha = 4
143 };
144
145 typedef unsigned char stbi_uc;
146
147 #ifdef __cplusplus
148 extern "C" {
149 #endif
150
152 //
153 // PRIMARY API - works on images of any type
154 //
155
156 //
157 // load image by filename, open file, or memory buffer
158 //
159
160 extern stbi_uc *stbi_load_from_memory(stbi_uc const *buffer, int len, int *x, int *y, int *comp, int req_comp);
161
162 #ifndef STBI_NO_STDIO
163 extern stbi_uc *stbi_load (char const *filename, int *x, int *y, int *comp, int req_comp);
164 extern stbi_uc *stbi_load_from_file (FILE *f, int *x, int *y, int *comp, int req_comp);
165 // for stbi_load_from_file, file pointer is left pointing immediately after image
166 #endif
167
168 typedef struct
169 {
170 int (*read) (void *user,char *data,int size); // fill 'data' with 'size' bytes. return number of bytes actually read
171 void (*skip) (void *user,unsigned n); // skip the next 'n' bytes
172 int (*eof) (void *user); // returns nonzero if we are at end of file/data
173 } stbi_io_callbacks;
174
175 extern stbi_uc *stbi_load_from_callbacks (stbi_io_callbacks const *clbk, void *user, int *x, int *y, int *comp, int req_comp);
176
177 #ifndef STBI_NO_HDR
178 extern float *stbi_loadf_from_memory(stbi_uc const *buffer, int len, int *x, int *y, int *comp, int req_comp);
179
180 #ifndef STBI_NO_STDIO
181 extern float *stbi_loadf (char const *filename, int *x, int *y, int *comp, int req_comp);
182 extern float *stbi_loadf_from_file (FILE *f, int *x, int *y, int *comp, int req_comp);
183 #endif
184
185 extern float *stbi_loadf_from_callbacks (stbi_io_callbacks const *clbk, void *user, int *x, int *y, int *comp, int req_comp);
186
187 extern void stbi_hdr_to_ldr_gamma(float gamma);
188 extern void stbi_hdr_to_ldr_scale(float scale);
189
190 extern void stbi_ldr_to_hdr_gamma(float gamma);
191 extern void stbi_ldr_to_hdr_scale(float scale);
192
193 #ifndef STBI_NO_STDIO
194 extern int stbi_is_hdr (char const *filename);
195 extern int stbi_is_hdr_from_file(FILE *f);
196 #endif // STBI_NO_STDIO
197
198 extern int stbi_is_hdr_from_callbacks(stbi_io_callbacks const *clbk, void *user);
199 extern int stbi_is_hdr_from_memory(stbi_uc const *buffer, int len);
200 #endif // STBI_NO_HDR
201
202 // get a VERY brief reason for failure
203 // NOT THREADSAFE
204 extern const char *stbi_failure_reason (void);
205
206 // free the loaded image -- this is just free()
207 extern void stbi_image_free (void *retval_from_stbi_load);
208
209 // get image dimensions & components without fully decoding
210 extern int stbi_info_from_memory(stbi_uc const *buffer, int len, int *x, int *y, int *comp);
211 extern int stbi_info_from_callbacks(stbi_io_callbacks const *clbk, void *user, int *x, int *y, int *comp);
212
213 #ifndef STBI_NO_STDIO
214 extern int stbi_info (char const *filename, int *x, int *y, int *comp);
215 extern int stbi_info_from_file (FILE *f, int *x, int *y, int *comp);
216
217 #endif
218
219
220
221 // for image formats that explicitly notate that they have premultiplied alpha,
222 // we just return the colors as stored in the file. set this flag to force
223 // unpremultiplication. results are undefined if the unpremultiply overflow.
224 extern void stbi_set_unpremultiply_on_load(int flag_true_if_should_unpremultiply);
225
226 // indicate whether we should process iphone images back to canonical format,
227 // or just pass them through "as-is"
228 extern void stbi_convert_iphone_png_to_rgb(int flag_true_if_should_convert);
229
230
231 // ZLIB client - used by PNG, available for other purposes
232
233 extern char *stbi_zlib_decode_malloc_guesssize(const char *buffer, int len, int initial_size, int *outlen);
234 extern char *stbi_zlib_decode_malloc(const char *buffer, int len, int *outlen);
235 extern int stbi_zlib_decode_buffer(char *obuffer, int olen, const char *ibuffer, int ilen);
236
237 extern char *stbi_zlib_decode_noheader_malloc(const char *buffer, int len, int *outlen);
238 extern int stbi_zlib_decode_noheader_buffer(char *obuffer, int olen, const char *ibuffer, int ilen);
239
240
241 // define faster low-level operations (typically SIMD support)
242 #ifdef STBI_SIMD
243 typedef void (*stbi_idct_8x8)(stbi_uc *out, int out_stride, short data[64], unsigned short *dequantize);
244 // compute an integer IDCT on "input"
245 // input[x] = data[x] * dequantize[x]
246 // write results to 'out': 64 samples, each run of 8 spaced by 'out_stride'
247 // CLAMP results to 0..255
248 typedef void (*stbi_YCbCr_to_RGB_run)(stbi_uc *output, stbi_uc const *y, stbi_uc const *cb, stbi_uc const *cr, int count, int step);
249 // compute a conversion from YCbCr to RGB
250 // 'count' pixels
251 // write pixels to 'output'; each pixel is 'step' bytes (either 3 or 4; if 4, write '255' as 4th), order R,G,B
252 // y: Y input channel
253 // cb: Cb input channel; scale/biased to be 0..255
254 // cr: Cr input channel; scale/biased to be 0..255
255
256 extern void stbi_install_idct(stbi_idct_8x8 func);
257 extern void stbi_install_YCbCr_to_RGB(stbi_YCbCr_to_RGB_run func);
258 #endif // STBI_SIMD
259
260
261 #ifdef __cplusplus
262 }
263 #endif
264
265 //
266 //
268 #endif // STBI_INCLUDE_STB_IMAGE_H
stbi_zlib_decode_malloc
char * stbi_zlib_decode_malloc(const char *buffer, int len, int *outlen)
Definition: stb_image.c:2342
STBI_grey_alpha
Definition: stb_image.h:140
stbi_is_hdr_from_callbacks
int stbi_is_hdr_from_callbacks(stbi_io_callbacks const *clbk, void *user)
Definition: stb_image.c:701
stbi_info_from_file
int stbi_info_from_file(FILE *f, int *x, int *y, int *comp)
Definition: stb_image.c:4552
stbi_is_hdr
int stbi_is_hdr(char const *filename)
Definition: stb_image.c:678
STBI_grey
Definition: stb_image.h:139
stbi_ldr_to_hdr_scale
void stbi_ldr_to_hdr_scale(float scale)
Definition: stb_image.c:720
stbi_info_from_memory
int stbi_info_from_memory(stbi_uc const *buffer, int len, int *x, int *y, int *comp)
Definition: stb_image.c:4564
stbi_load
stbi_uc * stbi_load(char const *filename, int *x, int *y, int *comp, int req_comp)
Definition: stb_image.c:572
STBI_rgb_alpha
Definition: stb_image.h:142
stbi_zlib_decode_noheader_malloc
char * stbi_zlib_decode_noheader_malloc(const char *buffer, int len, int *outlen)
Definition: stb_image.c:2374
stbi_hdr_to_ldr_scale
void stbi_hdr_to_ldr_scale(float scale)
Definition: stb_image.c:717
stbi_loadf
float * stbi_loadf(char const *filename, int *x, int *y, int *comp, int req_comp)
Definition: stb_image.c:640
stbi_io_callbacks
Definition: stb_image.c:235
stbi_image_free
void stbi_image_free(void *retval_from_stbi_load)
Definition: stb_image.c:539
stbi_loadf_from_memory
float * stbi_loadf_from_memory(stbi_uc const *buffer, int len, int *x, int *y, int *comp, int req_comp)
Definition: stb_image.c:625
stbi_ldr_to_hdr_gamma
void stbi_ldr_to_hdr_gamma(float gamma)
Definition: stb_image.c:719
stbi_failure_reason
const char * stbi_failure_reason(void)
Definition: stb_image.c:513
stbi_load_from_file
stbi_uc * stbi_load_from_file(FILE *f, int *x, int *y, int *comp, int req_comp)
Definition: stb_image.c:582
stbi_is_hdr_from_file
int stbi_is_hdr_from_file(FILE *f)
Definition: stb_image.c:689
stbi_info
int stbi_info(char const *filename, int *x, int *y, int *comp)
Definition: stb_image.c:4542
stbi_zlib_decode_noheader_buffer
int stbi_zlib_decode_noheader_buffer(char *obuffer, int olen, const char *ibuffer, int ilen)
Definition: stb_image.c:2390
stbi_load_from_callbacks
stbi_uc * stbi_load_from_callbacks(stbi_io_callbacks const *clbk, void *user, int *x, int *y, int *comp, int req_comp)
Definition: stb_image.c:603
stbi_zlib_decode_malloc_guesssize
char * stbi_zlib_decode_malloc_guesssize(const char *buffer, int len, int initial_size, int *outlen)
Definition: stb_image.c:2326
stbi_zlib_decode_buffer
int stbi_zlib_decode_buffer(char *obuffer, int olen, const char *ibuffer, int ilen)
Definition: stb_image.c:2363
stbi_load_from_memory
stbi_uc * stbi_load_from_memory(stbi_uc const *buffer, int len, int *x, int *y, int *comp, int req_comp)
STBI_NO_STDIO.
Definition: stb_image.c:596
stbi_uc
unsigned char stbi_uc
Definition: stb_image.h:145
STBI_rgb
Definition: stb_image.h:141
stbi_is_hdr_from_memory
int stbi_is_hdr_from_memory(stbi_uc const *buffer, int len)
Definition: stb_image.c:664
stbi_hdr_to_ldr_gamma
void stbi_hdr_to_ldr_gamma(float gamma)
Definition: stb_image.c:716
stbi_info_from_callbacks
int stbi_info_from_callbacks(stbi_io_callbacks const *clbk, void *user, int *x, int *y, int *comp)
Definition: stb_image.c:4571
stbi_uc
unsigned char stbi_uc
Definition: stb_image.c:212
stbi_set_unpremultiply_on_load
void stbi_set_unpremultiply_on_load(int flag_true_if_should_unpremultiply)
Definition: stb_image.c:2649
STBI_default
Definition: stb_image.h:137
stbi_loadf_from_callbacks
float * stbi_loadf_from_callbacks(stbi_io_callbacks const *clbk, void *user, int *x, int *y, int *comp, int req_comp)
Definition: stb_image.c:632
stbi_loadf_from_file
float * stbi_loadf_from_file(FILE *f, int *x, int *y, int *comp, int req_comp)
Definition: stb_image.c:650
stbi_convert_iphone_png_to_rgb
void stbi_convert_iphone_png_to_rgb(int flag_true_if_should_convert)
Definition: stb_image.c:2653