94 lines
3.9 KiB
Markdown
94 lines
3.9 KiB
Markdown
# ReFuel.StbImage
|
|
StbImage is a very common library that has been developed by Sean Barett, et al.
|
|
It is one of the easiest to use image loading libraries on the planet
|
|
especially for C and C++ users. It is relatively simple to load up and use in
|
|
C#, however the C# build system makes it a bit difficult to manage native
|
|
dependencies. Therefore this package makes it easy for you and everyone else
|
|
who needs a cross platform way to load and write images.
|
|
|
|
Intended OS targets are:
|
|
* Windows (x86 and x64)
|
|
* Linux (arm32, arm64, x86 and x64)
|
|
* MacOS (arm64, x64)
|
|
|
|
## Reading Image Files
|
|
```cs
|
|
using ReFuel.Stb;
|
|
|
|
// Simply load an image from a Stream or Span<byte> source.
|
|
using StbImage image = StbImage.Load(source);
|
|
|
|
Console.WriteLine("{0}x{1}", image.Width, image.Height);
|
|
// StbImage.ImagePointer is a pointer to the image data.
|
|
// You can cast the image pointer to any type if you use the AsSpan<T>() method.
|
|
|
|
// OpenGL example
|
|
GL.TexImage2D(
|
|
TextureTarget.Texture2D, 0, PixelInternalFormat.Rgba,
|
|
image.Width, image.Height, 0,
|
|
StbiFormatToGLFormat(image.Format),
|
|
image.IsFloat ? PixelFormat.Float : PixelFormat.UnsignedByte,
|
|
image.ImagePointer);
|
|
|
|
// C# example
|
|
struct Pixel
|
|
{
|
|
byte R, G, B, A;
|
|
}
|
|
|
|
ReadOnlySpan<Pixel> pixels = image.AsSpan<Pixel>();
|
|
```
|
|
|
|
> [!CAUTION]
|
|
> Even though the data pointed to by ImagePointer is read and write, you should
|
|
> not attempt to write or modify in any way. Anything dangerous you do with the
|
|
> pointer and the data pointed to is your responsibility.
|
|
|
|
## Writing Image Files
|
|
You can write any image file using `StbImage.WritePng`/`WriteBmp`/`WriteTga`/`WriteHdr` and `WriteJpg` functions. These will take a span, a stream and information about the format of
|
|
the image.
|
|
|
|
If your wish is to write an `StbImage` instance back to disk, you can use the instance
|
|
functions of the same name.
|
|
|
|
```cs
|
|
using Stream stream;
|
|
|
|
StbImage.WritePng(pixels, width, height, format, stream, isFloat);
|
|
StbImage.WriteBmp(pixels, width, height, format, stream, isFloat);
|
|
StbImage.WriteTga(pixels, width, height, format, stream, isFloat);
|
|
StbImage.WriteHdr(pixels, width, height, format, stream, isFloat);
|
|
StbImage.WriteJpg(pixels, width, height, format, stream, quality, isFloat);
|
|
|
|
StbImage image;
|
|
image.WritePng(stream);
|
|
image.WriteBmp(stream);
|
|
image.WriteTga(stream);
|
|
image.WriteHdr(stream);
|
|
image.WriteJpg(stream, quality);
|
|
```
|
|
|
|
> [!WARNING]
|
|
> These funtions depend on non-thread safe global options. Even though the
|
|
> functions themselves are reentrant, it might require some synchronization.
|
|
> This is a limitation of `stb_image_write` rather than `ReFuel.StbImage`.
|
|
|
|
## Global Options
|
|
| Option | Description |
|
|
|--------|-------------|
|
|
| `bool StbImage.FlipVerticallyOnLoad { set; }` | Flips the image vertically after loading. Practical for uses where a right handed coordinate system is used (e.g. OpenGL) |
|
|
| `bool StbImage.FlipVerticallyOnSave { set; }` | Similar to FlipVerticallyOnLoad, it will flip
|
|
the image vertically when writing. |
|
|
| `bool StbImage.UnpremultiplyOnLoad { set; }` | Applies to Apple iPhone PNG images, where the image is sometimes encoded with premultiplied alpha. Reverses this premultiplication. |
|
|
| `int StbImage.WriteForcePngFilter { get; set; }` | Forces a filter when writing PNG images. Must be -1 for auto, or 0 through 5, higher is more. See STBI documentation. |
|
|
| `int WritePngCompressionLevel { get; set; }` | Changes the PNG deflate compression level. Higher is more. Higher values take longer. 8 by default. |
|
|
| `bool WriteTgaEnableRLE { get; set; }` | Enables run length encoding for TGA images when writing. |
|
|
|
|
## Calling Stbi directly.
|
|
If you wish to call the native Stbi library, call functions in the static class `ReFuel.Stb.Native.Stbi`. See `stb_image.h` and `stb_image_write.h` documentation [online](https://github.com/nothings/stb/blob/master/stb_image.h).
|
|
|
|
## See Also
|
|
* [API](/api/ReFuel.Stb.StbImage.html)
|
|
* [nothings/stb](https://github.com/nothings/stb)
|
|
|