1/* stbi-1.16 - public domain JPEG/PNG reader - http://nothings.org/stb_image.c
2 when you control the images you're loading
3
4 QUICK NOTES:
5 Primarily of interest to game developers and other people who can
6 avoid problematic images and only need the trivial interface
7
8 JPEG baseline (no JPEG progressive, no oddball channel decimations)
9 PNG non-interlaced
10 BMP non-1bpp, non-RLE
11 TGA (not sure what subset, if a subset)
12 PSD (composited view only, no extra channels)
13 HDR (radiance rgbE format)
14 writes BMP,TGA (define STBI_NO_WRITE to remove code)
15 decoded from memory or through stdio FILE (define STBI_NO_STDIO to remove code)
16 supports installable dequantizing-IDCT, YCbCr-to-RGB conversion (define STBI_SIMD)
17
18 TODO:
19 stbi_info_*
20
21 history:
22 1.16 major bugfix - convert_format converted one too many pixels
23 1.15 initialize some fields for thread safety
24 1.14 fix threadsafe conversion bug; header-file-only version (#define STBI_HEADER_FILE_ONLY before including)
25 1.13 threadsafe
26 1.12 const qualifiers in the API
27 1.11 Support installable IDCT, colorspace conversion routines
28 1.10 Fixes for 64-bit (don't use "unsigned long")
29 optimized upsampling by Fabian "ryg" Giesen
30 1.09 Fix format-conversion for PSD code (bad global variables!)
31 1.08 Thatcher Ulrich's PSD code integrated by Nicolas Schulz
32 1.07 attempt to fix C++ warning/errors again
33 1.06 attempt to fix C++ warning/errors again
34 1.05 fix TGA loading to return correct *comp and use good luminance calc
35 1.04 default float alpha is 1, not 255; use 'void *' for stbi_image_free
36 1.03 bugfixes to STBI_NO_STDIO, STBI_NO_HDR
37 1.02 support for (subset of) HDR files, float interface for preferred access to them
38 1.01 fix bug: possible bug in handling right-side up bmps... not sure
39 fix bug: the stbi_bmp_load() and stbi_tga_load() functions didn't work at all
40 1.00 interface to zlib that skips zlib header
41 0.99 correct handling of alpha in palette
42 0.98 TGA loader by lonesock; dynamically add loaders (untested)
43 0.97 jpeg errors on too large a file; also catch another malloc failure
44 0.96 fix detection of invalid v value - particleman@mollyrocket forum
45 0.95 during header scan, seek to markers in case of padding
46 0.94 STBI_NO_STDIO to disable stdio usage; rename all #defines the same
47 0.93 handle jpegtran output; verbose errors
48 0.92 read 4,8,16,24,32-bit BMP files of several formats
49 0.91 output 24-bit Windows 3.0 BMP files
50 0.90 fix a few more warnings; bump version number to approach 1.0
51 0.61 bugfixes due to Marc LeBlanc, Christopher Lloyd
52 0.60 fix compiling as c++
53 0.59 fix warnings: merge Dave Moore's -Wall fixes
54 0.58 fix bug: zlib uncompressed mode len/nlen was wrong endian
55 0.57 fix bug: jpg last huffman symbol before marker was >9 bits but less
56 than 16 available
57 0.56 fix bug: zlib uncompressed mode len vs. nlen
58 0.55 fix bug: restart_interval not initialized to 0
59 0.54 allow NULL for 'int *comp'
60 0.53 fix bug in png 3->4; speedup png decoding
61 0.52 png handles req_comp=3,4 directly; minor cleanup; jpeg comments
62 0.51 obey req_comp requests, 1-component jpegs return as 1-component,
63 on 'test' only check type, not whether we support this variant
64*/
65
66#ifndef HEADER_STB_IMAGE_AUGMENTED
67#define HEADER_STB_IMAGE_AUGMENTED
68
69//// begin header file ////////////////////////////////////////////////////
70//
71// Limitations:
72// - no progressive/interlaced support (jpeg, png)
73// - 8-bit samples only (jpeg, png)
74// - not threadsafe
75// - channel subsampling of at most 2 in each dimension (jpeg)
76// - no delayed line count (jpeg) -- IJG doesn't support either
77//
78// Basic usage (see HDR discussion below):
79// int x,y,n;
80// unsigned char *data = stbi_load(filename, &x, &y, &n, 0);
81// // ... process data if not NULL ...
82// // ... x = width, y = height, n = # 8-bit components per pixel ...
83// // ... replace '0' with '1'..'4' to force that many components per pixel
84// stbi_image_free(data)
85//
86// Standard parameters:
87// int *x -- outputs image width in pixels
88// int *y -- outputs image height in pixels
89// int *comp -- outputs # of image components in image file
90// int req_comp -- if non-zero, # of image components requested in result
91//
92// The return value from an image loader is an 'unsigned char *' which points
93// to the pixel data. The pixel data consists of *y scanlines of *x pixels,
94// with each pixel consisting of N interleaved 8-bit components; the first
95// pixel pointed to is top-left-most in the image. There is no padding between
96// image scanlines or between pixels, regardless of format. The number of
97// components N is 'req_comp' if req_comp is non-zero, or *comp otherwise.
98// If req_comp is non-zero, *comp has the number of components that _would_
99// have been output otherwise. E.g. if you set req_comp to 4, you will always
100// get RGBA output, but you can check *comp to easily see if it's opaque.
101//
102// An output image with N components has the following components interleaved
103// in this order in each pixel:
104//
105// N=#comp components
106// 1 grey
107// 2 grey, alpha
108// 3 red, green, blue
109// 4 red, green, blue, alpha
110//
111// If image loading fails for any reason, the return value will be NULL,
112// and *x, *y, *comp will be unchanged. The function stbi_failure_reason()
113// can be queried for an extremely brief, end-user unfriendly explanation
114// of why the load failed. Define STBI_NO_FAILURE_STRINGS to avoid
115// compiling these strings at all, and STBI_FAILURE_USERMSG to get slightly
116// more user-friendly ones.
117//
118// Paletted PNG and BMP images are automatically depalettized.
119//
120//
121// ===========================================================================
122//
123// HDR image support (disable by defining STBI_NO_HDR)
124//
125// stb_image now supports loading HDR images in general, and currently
126// the Radiance .HDR file format, although the support is provided
127// generically. You can still load any file through the existing interface;
128// if you attempt to load an HDR file, it will be automatically remapped to
129// LDR, assuming gamma 2.2 and an arbitrary scale factor defaulting to 1;
130// both of these constants can be reconfigured through this interface:
131//
132// stbi_hdr_to_ldr_gamma(2.2f);
133// stbi_hdr_to_ldr_scale(1.0f);
134//
135// (note, do not use _inverse_ constants; stbi_image will invert them
136// appropriately).
137//
138// Additionally, there is a new, parallel interface for loading files as
139// (linear) floats to preserve the full dynamic range:
140//
141// float *data = stbi_loadf(filename, &x, &y, &n, 0);
142//
143// If you load LDR images through this interface, those images will
144// be promoted to floating point values, run through the inverse of
145// constants corresponding to the above:
146//
147// stbi_ldr_to_hdr_scale(1.0f);
148// stbi_ldr_to_hdr_gamma(2.2f);
149//
150// Finally, given a filename (or an open file or memory block--see header
151// file for details) containing image data, you can query for the "most
152// appropriate" interface to use (that is, whether the image is HDR or
153// not), using:
154//
155// stbi_is_hdr(char *filename);
156
157#ifndef STBI_NO_STDIO
158#include <stdio.h>
159#endif
160
161#define STBI_VERSION 1
162
163enum
164{
165 STBI_default = 0, // only used for req_comp
166
167 STBI_grey = 1,
168 STBI_grey_alpha = 2,
169 STBI_rgb = 3,
170 STBI_rgb_alpha = 4,
171};
172
173typedef unsigned char stbi_uc;
174
175#ifdef __cplusplus
176extern "C" {
177#endif
178
179// WRITING API
180
181#if !defined(STBI_NO_WRITE) && !defined(STBI_NO_STDIO)
182// write a BMP/TGA file given tightly packed 'comp' channels (no padding, nor bmp-stride-padding)
183// (you must include the appropriate extension in the filename).
184// returns TRUE on success, FALSE if couldn't open file, error writing file
185extern int stbi_write_bmp (char const *filename, int x, int y, int comp, void *data);
186extern int stbi_write_tga (char const *filename, int x, int y, int comp, void *data);
187#endif
188
189// PRIMARY API - works on images of any type
190
191// load image by filename, open file, or memory buffer
192#ifndef STBI_NO_STDIO
193extern stbi_uc *stbi_load (char const *filename, int *x, int *y, int *comp, int req_comp);
194extern stbi_uc *stbi_load_from_file (FILE *f, int *x, int *y, int *comp, int req_comp);
195extern int stbi_info_from_file (FILE *f, int *x, int *y, int *comp);
196#endif
197extern stbi_uc *stbi_load_from_memory(stbi_uc const *buffer, int len, int *x, int *y, int *comp, int req_comp);
198// for stbi_load_from_file, file pointer is left pointing immediately after image
199
200#ifndef STBI_NO_HDR
201#ifndef STBI_NO_STDIO
202extern float *stbi_loadf (char const *filename, int *x, int *y, int *comp, int req_comp);
203extern float *stbi_loadf_from_file (FILE *f, int *x, int *y, int *comp, int req_comp);
204#endif
205extern float *stbi_loadf_from_memory(stbi_uc const *buffer, int len, int *x, int *y, int *comp, int req_comp);
206
207extern void stbi_hdr_to_ldr_gamma(float gamma);
208extern void stbi_hdr_to_ldr_scale(float scale);
209
210extern void stbi_ldr_to_hdr_gamma(float gamma);
211extern void stbi_ldr_to_hdr_scale(float scale);
212
213#endif // STBI_NO_HDR
214
215// get a VERY brief reason for failure
216// NOT THREADSAFE
217extern char *stbi_failure_reason (void);
218
219// free the loaded image -- this is just free()
220extern void stbi_image_free (void *retval_from_stbi_load);
221
222// get image dimensions & components without fully decoding
223extern int stbi_info_from_memory(stbi_uc const *buffer, int len, int *x, int *y, int *comp);
224extern int stbi_is_hdr_from_memory(stbi_uc const *buffer, int len);
225#ifndef STBI_NO_STDIO
226extern int stbi_info (char const *filename, int *x, int *y, int *comp);
227extern int stbi_is_hdr (char const *filename);
228extern int stbi_is_hdr_from_file(FILE *f);
229#endif
230
231// ZLIB client - used by PNG, available for other purposes
232
233extern char *stbi_zlib_decode_malloc_guesssize(const char *buffer, int len, int initial_size, int *outlen);
234extern char *stbi_zlib_decode_malloc(const char *buffer, int len, int *outlen);
235extern int stbi_zlib_decode_buffer(char *obuffer, int olen, const char *ibuffer, int ilen);
236
237extern char *stbi_zlib_decode_noheader_malloc(const char *buffer, int len, int *outlen);
238extern int stbi_zlib_decode_noheader_buffer(char *obuffer, int olen, const char *ibuffer, int ilen);
239
240// TYPE-SPECIFIC ACCESS
241
242// is it a jpeg?
243extern int stbi_jpeg_test_memory (stbi_uc const *buffer, int len);
244extern stbi_uc *stbi_jpeg_load_from_memory(stbi_uc const *buffer, int len, int *x, int *y, int *comp, int req_comp);
245extern int stbi_jpeg_info_from_memory(stbi_uc const *buffer, int len, int *x, int *y, int *comp);
246
247#ifndef STBI_NO_STDIO
248extern stbi_uc *stbi_jpeg_load (char const *filename, int *x, int *y, int *comp, int req_comp);
249extern int stbi_jpeg_test_file (FILE *f);
250extern stbi_uc *stbi_jpeg_load_from_file (FILE *f, int *x, int *y, int *comp, int req_comp);
251
252extern int stbi_jpeg_info (char const *filename, int *x, int *y, int *comp);
253extern int stbi_jpeg_info_from_file (FILE *f, int *x, int *y, int *comp);
254#endif
255
256// is it a png?
257extern int stbi_png_test_memory (stbi_uc const *buffer, int len);
258extern stbi_uc *stbi_png_load_from_memory (stbi_uc const *buffer, int len, int *x, int *y, int *comp, int req_comp);
259extern int stbi_png_info_from_memory (stbi_uc const *buffer, int len, int *x, int *y, int *comp);
260
261#ifndef STBI_NO_STDIO
262extern stbi_uc *stbi_png_load (char const *filename, int *x, int *y, int *comp, int req_comp);
263extern int stbi_png_info (char const *filename, int *x, int *y, int *comp);
264extern int stbi_png_test_file (FILE *f);
265extern stbi_uc *stbi_png_load_from_file (FILE *f, int *x, int *y, int *comp, int req_comp);
266extern int stbi_png_info_from_file (FILE *f, int *x, int *y, int *comp);
267#endif
268
269// is it a bmp?
270extern int stbi_bmp_test_memory (stbi_uc const *buffer, int len);
271
272extern stbi_uc *stbi_bmp_load (char const *filename, int *x, int *y, int *comp, int req_comp);
273extern stbi_uc *stbi_bmp_load_from_memory (stbi_uc const *buffer, int len, int *x, int *y, int *comp, int req_comp);
274#ifndef STBI_NO_STDIO
275extern int stbi_bmp_test_file (FILE *f);
276extern stbi_uc *stbi_bmp_load_from_file (FILE *f, int *x, int *y, int *comp, int req_comp);
277#endif
278
279// is it a tga?
280extern int stbi_tga_test_memory (stbi_uc const *buffer, int len);
281
282extern stbi_uc *stbi_tga_load (char const *filename, int *x, int *y, int *comp, int req_comp);
283extern stbi_uc *stbi_tga_load_from_memory (stbi_uc const *buffer, int len, int *x, int *y, int *comp, int req_comp);
284#ifndef STBI_NO_STDIO
285extern int stbi_tga_test_file (FILE *f);
286extern stbi_uc *stbi_tga_load_from_file (FILE *f, int *x, int *y, int *comp, int req_comp);
287#endif
288
289// is it a psd?
290extern int stbi_psd_test_memory (stbi_uc const *buffer, int len);
291
292extern stbi_uc *stbi_psd_load (char const *filename, int *x, int *y, int *comp, int req_comp);
293extern stbi_uc *stbi_psd_load_from_memory (stbi_uc const *buffer, int len, int *x, int *y, int *comp, int req_comp);
294#ifndef STBI_NO_STDIO
295extern int stbi_psd_test_file (FILE *f);
296extern stbi_uc *stbi_psd_load_from_file (FILE *f, int *x, int *y, int *comp, int req_comp);
297#endif
298
299// is it an hdr?
300extern int stbi_hdr_test_memory (stbi_uc const *buffer, int len);
301
302extern float * stbi_hdr_load (char const *filename, int *x, int *y, int *comp, int req_comp);
303extern float * stbi_hdr_load_from_memory (stbi_uc const *buffer, int len, int *x, int *y, int *comp, int req_comp);
304extern stbi_uc *stbi_hdr_load_rgbe (char const *filename, int *x, int *y, int *comp, int req_comp);
305extern float * stbi_hdr_load_from_memory (stbi_uc const *buffer, int len, int *x, int *y, int *comp, int req_comp);
306#ifndef STBI_NO_STDIO
307extern int stbi_hdr_test_file (FILE *f);
308extern float * stbi_hdr_load_from_file (FILE *f, int *x, int *y, int *comp, int req_comp);
309extern stbi_uc *stbi_hdr_load_rgbe_file (FILE *f, int *x, int *y, int *comp, int req_comp);
310#endif
311
312// define new loaders
313typedef struct
314{
315 int (*test_memory)(stbi_uc const *buffer, int len);
316 stbi_uc * (*load_from_memory)(stbi_uc const *buffer, int len, int *x, int *y, int *comp, int req_comp);
317 #ifndef STBI_NO_STDIO
318 int (*test_file)(FILE *f);
319 stbi_uc * (*load_from_file)(FILE *f, int *x, int *y, int *comp, int req_comp);
320 #endif
321} stbi_loader;
322
323// register a loader by filling out the above structure (you must defined ALL functions)
324// returns 1 if added or already added, 0 if not added (too many loaders)
325// NOT THREADSAFE
326extern int stbi_register_loader(stbi_loader *loader);
327
328// define faster low-level operations (typically SIMD support)
329#if STBI_SIMD
330typedef void (*stbi_idct_8x8)(uint8 *out, int out_stride, short data[64], unsigned short *dequantize);
331// compute an integer IDCT on "input"
332// input[x] = data[x] * dequantize[x]
333// write results to 'out': 64 samples, each run of 8 spaced by 'out_stride'
334// CLAMP results to 0..255
335typedef void (*stbi_YCbCr_to_RGB_run)(uint8 *output, uint8 const *y, uint8 const *cb, uint8 const *cr, int count, int step);
336// compute a conversion from YCbCr to RGB
337// 'count' pixels
338// write pixels to 'output'; each pixel is 'step' bytes (either 3 or 4; if 4, write '255' as 4th), order R,G,B
339// y: Y input channel
340// cb: Cb input channel; scale/biased to be 0..255
341// cr: Cr input channel; scale/biased to be 0..255
342
343extern void stbi_install_idct(stbi_idct_8x8 func);
344extern void stbi_install_YCbCr_to_RGB(stbi_YCbCr_to_RGB_run func);
345#endif // STBI_SIMD
346
347#ifdef __cplusplus
348}
349#endif
350
351//
352//
353//// end header file /////////////////////////////////////////////////////
354#endif // STBI_INCLUDE_STB_IMAGE_H
355