ReFuel/refuel.mixedup.dev
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Make documentation better for StbImage.

Browse Source
This commit is contained in:
H. Utku Maden 2024-06-19 14:04:29 +03:00
parent 9e83c5dd83
commit 0272531025
1 changed files with 61 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

77
docs/ReFuel.StbImage.md
View File

@ -1,48 +1,93 @@
# ReFuel.StbImage
StbImage is a very common library that has been developed mainly by Sean Barett.
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 images.
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)
## Usage
## Reading Image Files
```cs
using ReFuel.Stb;
// Simply load an image from a Stream or Span<T> (T: unmanaged) source.
// 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.
// Pass the image to an unsafe library as is (e.g. OpenGL), or cast it to a span. Currently there is no "safe" way to do this.
// 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);
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
{
int R, G, B, A;
byte R, G, B, A;
}
Span<Pixel> pixels;
unsafe
{
pixels = new Span<Pixel>(image.ImagePointer, image.Width * image.Height);
}
ReadOnlySpan<Pixel> pixels = image.AsSpan<Pixel>();
```
### Global Options
> [!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` | Flips the image vertically after loading. Practical for uses where a right handed coordinate system is used (e.g. OpenGL) |
| `bool UnpremultiplyOnLoad` | Applies to Apple iPhone PNG images, where the image is sometimes encoded with premultiplied alpha. Reverses this premultiplication. |
| `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 `Stbi`. See `stb_image.h` documentation [online](https://github.com/nothings/stb/blob/master/stb_image.h).
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)