Prowl.Aperture 3.5.0

Prowl.Aperture

Image loading for the Prowl game engine. One dependency-free API that identifies and decodes fourteen formats.

using Prowl.Aperture;

// Header only. Reads a few kilobytes, never touches pixel data.
ImageInfo info = Image.Identify("photo.png");
Console.WriteLine($"{info.Width}x{info.Height} {info.PixelFormat} {info.Compression}");

// Full decode, with limits.
Image image = Image.Load("photo.png", new DecodeOptions
{
    TargetPixelFormat = PixelFormat.Rgba8,
    MaxPixels = 64_000_000,
});

// Nothing here throws, whatever the bytes are.
if (Image.TryLoad(untrusted, DecodeOptions.Default, out Image? loaded, out ApertureError error))
    Upload(loaded!.RootFrame.Pixels);

Formats

Pixel data

A decoded frame is a tightly packed buffer with a known stride, and the pixel memory is rented from a pool that Image.Dispose returns it to.

using Image image = Image.Load(bytes, new DecodeOptions
{
    TargetPixelFormat = PixelFormat.Rgba8,
    RowAlignment = 256,          // the row pitch a graphics API asked for
});

ImageFrame frame = image.RootFrame;
frame.Pixels;                    // Span<byte> over the whole frame
frame.PixelMemory;               // Memory<byte>, for the APIs that cannot take a span
frame.GetRow(y);                 // one row
frame.GetRowAs<Rgba32>(y);       // the same row as your own pixel struct
frame.CopyTo(mapped, pitch);     // straight into a mapped buffer, re-striding on the way

Set UsePooledMemory to false when the pixels have to outlive the Image they came from.

Uploading to a texture

The decode is asked for the exact layout and row order the graphics API wants, so the upload is a pointer and nothing else. No flip pass, no repack, no intermediate array.

public static Texture2D FromImage(ReadOnlySpan<byte> encoded, bool generateMipmaps = false)
{
    DecodeOptions options = new()
    {
        TargetPixelFormat = PixelFormat.Rgba8,  // tightly packed R,G,B,A
        FlipVertically = true,                  // OpenGL's origin is the lower left
        RowAlignment = 4,                       // matches the default GL_UNPACK_ALIGNMENT
    };

    using Image image = Image.Load(encoded, options);
    ImageFrame frame = image.RootFrame;

    Texture2D texture = new(image.Width, image.Height, false, TextureImageFormat.Color4b);
    try
    {
        unsafe
        {
            fixed (byte* pixels = frame.Pixels)
                Graphics.TexSubImage2D(texture.Handle, 0, 0, 0, image.Width, image.Height, pixels);
        }

        if (generateMipmaps)
            texture.GenerateMipmaps();

        texture.SetTextureFilters(
            generateMipmaps ? TextureMin.LinearMipmapLinear : TextureMin.Linear, TextureMag.Linear);

        return texture;
    }
    catch
    {
        texture.Dispose();
        throw;
    }
}

FlipVertically costs nothing: the decoder writes one row at a time and simply picks the destination row from the other end, where flipping afterwards is a second pass over the image.

RowAlignment is GL_UNPACK_ALIGNMENT. Four is the driver default and is what the code above assumes. An RGBA row is always a multiple of four anyway, so it only matters for three channel uploads of odd width. Going above eight means padding the driver will not infer, so set GL_UNPACK_ROW_LENGTH from frame.Stride if you ask for a wider alignment.

The pixel memory is pooled and owned by the Image, so the fixed block must sit inside the using. TexSubImage2D copies synchronously, which is why a pointer is enough here; anything that reads the buffer later needs frame.CopyTo into memory of its own.

Frames, levels and pages

A file that holds more than one picture hands them over as frames, and which of them come back is the caller's choice.

// Every frame of an animation, every page of a TIFF, every face of a cube map.
using Image animation = Image.Load(bytes, new DecodeOptions { DecodeAllFrames = true });

foreach (ImageFrame frame in animation.Frames)
    Console.WriteLine($"{frame.Width}x{frame.Height} for {frame.Delay}ms");

// The smaller copies a texture file carries, rather than only the largest.
using Image texture = Image.Load(bytes, new DecodeOptions { DecodeMipmaps = true });

foreach (ImageFrame level in texture.Frames)
    Console.WriteLine($"level {level.MipLevel}: {level.Width}x{level.Height}");

Block compressed data can also be taken as it lies, for a pipeline that would rather upload the blocks than a decoded picture:

using TextureData data = TextureData.Load("terrain.dds");
Graphics.CompressedTexImage2D(handle, data.Format, data.Width, data.Height, data.GetLevel(0));

Orientation

A camera records which way up it was holding the lens and writes the sensor's own rows. This library hands back those rows as stored and reports the tag, so the size of the buffer and the size of the picture are the same thing. Ask for the picture to be turned when that is what you want:

using Image upright = Image.Load(bytes, new DecodeOptions { ApplyExifOrientation = true });

It is off by default because a quarter turn trades the width for the height, and a caller who has already sized a buffer from Image.Identify should be the one to ask for that.

Performance

Measured against ImageSharp and against ImageMagick through Magick.NET, all three asked for the same eight bit RGBA picture from the same bytes. A ratio above one means Aperture is faster. These are one desktop, so treat them with a grain of salt

The harness decodes real corpus files rather than synthetic data, and checks that the three libraries produced identical pixels before timing them, so a timing is a timing of the same work. It lives outside this repository with the corpus it reads.

Testing

Roughly 47,000 test cases run against a 2,300 file corpus of real images. Well formed files must decode, deliberately broken ones must fail with an error rather than an exception, and the rest must reach either outcome without crashing or hanging.

Expected values do not come from Aperture. Pixels are compared against readings produced by Pillow, pypng, libjpeg, libwebp, OpenEXR and libraw, none of which share code with this library, and against reference renderings shipped with the upstream conformance suites.

The corpus runs to hundreds of megabytes of photos and may not be redistributed, so it lives outside this repository along with the test and benchmark projects that read it.