Loads an image from the specified file.
The return value from an image loader is an
'unsigned char *' which points to the pixel data, or
NULL on an allocation failure or if the image
is corrupt or invalid. The pixel data consists of
*y scanlines of
*x pixels, with each pixel consisting of N interleaved 8-bit
components; the first pixel pointed to is top-left-most in the image. There is no padding between image scanlines or between pixels, regardless of
format. The number of components N is
'desired_channels' if
desired_channels is non-zero, or
*channels_in_file otherwise. If
desired_channels is non-zero,
*channels_in_file has the number of components that would have been output otherwise. E.g. if you
set
desired_channels to 4, you will always get RGBA output, but you can check
*channels_in_file to see if it's trivially opaque because
e.g. there were only 3 channels in the source image.
An output image with N components has the following components interleaved in this order in each pixel:
N=#channels_in_file components
1 grey
2 grey, alpha
3 red, green, blue
4 red, green, blue, alpha
If image loading fails for any reason, the return value will be
NULL, and
*x,
*y,
*channels_in_file will be unchanged. The
function
#stbi_failure_reason can be queried for an extremely brief, end-user unfriendly explanation of why the load failed.
Paletted PNG, BMP, GIF, and PIC images are automatically depalettized.