refuel.mixedup.dev/docs/ReFuel.StbImage.md

# 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)