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

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.

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.

See Also

• API
• nothings/stb