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 # 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 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 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 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 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: Intended OS targets are:
* Windows (x86 and x64) * Windows (x86 and x64)
* Linux (arm32, arm64, x86 and x64) * Linux (arm32, arm64, x86 and x64)
* MacOS (arm64, x64) * MacOS (arm64, x64)
## Usage ## Reading Image Files
```cs ```cs
using ReFuel.Stb; 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); using StbImage image = StbImage.Load(source);
Console.WriteLine("{0}x{1}", image.Width, image.Height); Console.WriteLine("{0}x{1}", image.Width, image.Height);
// StbImage.ImagePointer is a pointer to the image data. // 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 // 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 // C# example
struct Pixel struct Pixel
{ {
int R, G, B, A; byte R, G, B, A;
} }
Span<Pixel> pixels; ReadOnlySpan<Pixel> pixels = image.AsSpan<Pixel>();
unsafe
{
pixels = new Span<Pixel>(image.ImagePointer, image.Width * image.Height);
}
``` ```
### 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 | | 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 StbImage.FlipVerticallyOnLoad { set; }` | 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.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. ## 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)