Skip to content

Latest commit

 

History

History
180 lines (131 loc) · 6.4 KB

README.md

File metadata and controls

180 lines (131 loc) · 6.4 KB
Raw


Pfim

CI NuGet

Pfim is a .NET Standard 2.0 compatible Targa (tga) and Direct Draw Surface (dds) decoding library

Pfim can interoperate with a multitude of environments and libraries.

So no matter if you're targeting Windows, Linux, or Mac -- .NET Core or .NET Framework -- desktop, server, or mobile -- Pfim can fit.

Since Pfim emphasizes on being frontend and backend agnostic some work is entailed to coax it into a displayable form. Check out the listed samples for how to use Pfim in each scenario.

Installation

Install from NuGet

Usage

Below is a snippet that will convert a 32bit rgba targa or direct draw surface image into a png using the .NET framework.

using (var image = Pfimage.FromFile(path))
{
    PixelFormat format;

    // Convert from Pfim's backend agnostic image format into GDI+'s image format
    switch (image.Format)
    {
        case ImageFormat.Rgba32:
            format = PixelFormat.Format32bppArgb;
            break;
        default:
            // see the sample for more details
            throw new NotImplementedException(); 
    }

    // Pin pfim's data array so that it doesn't get reaped by GC, unnecessary
    // in this snippet but useful technique if the data was going to be used in
    // control like a picture box
    var handle = GCHandle.Alloc(image.Data, GCHandleType.Pinned);
    try
    {
        var data = Marshal.UnsafeAddrOfPinnedArrayElement(image.Data, 0);
        var bitmap = new Bitmap(image.Width, image.Height, image.Stride, format, data);
        bitmap.Save(Path.ChangeExtension(path, ".png"), System.Drawing.Imaging.ImageFormat.Png);
    }
    finally
    {
        handle.Free();
    }
}

Benchmarks

Pfim is fast. Faster than anything benchmarked in C#.

The contestants:

The task: a 120x120 image was encoded into 7 different images: 3 different types of targa and 4 different direct draw surface images. The benchmark was how how many times a library could decode the image.

Takeaways:

  • Pfim is hands down the fastest targa decoder. More than 10x faster than the closest competitor
  • For DDS it's a little less clear except for 32bit (uncompressed) images.

Rest assured, Pfim is one of the fastest if not the fastest when it comes to DDS decoding, but to get a clear view, let's look at the raw data.

Same story, but it's now apparent that the only time Pfim doesn't come in first is when it was 1% slower for decoding dxt5 DDS images.

Configuration

The decoding process can be customized via the PfimConfig parameter.

Buffer Size

When reading from a file or stream, this is the buffer size that Pfim will read in chunks of. The default value is 32KiB (kibibytes).

Decompress

Dictate if block encoded direct draw surface areas should be decompressed. Default is true. The only time this should be false is if only the dds metadata is desired or decoding will happen on the GPU.

Allocator

Unless this option is specified, all image allocations are performed via new byte[]. This can have less than desired effects on memory usage and GC especially when many images are being decoded. To fix this issue, Pfim introduced an IImageAllocator to allow a custom allocation. Below is a naive example for buffer pooling backed by ArrayPool

class PooledAllocator : IImageAllocator
{
    private readonly ArrayPool<byte> _shared = ArrayPool<byte>.Shared;

    public byte[] Rent(int size)
    {
        return _shared.Rent(size);
    }

    public void Return(byte[] data)
    {
        _shared.Return(data);
    }
}

Apply Color Map

Some targa images are mapped such that 24bit pixel data is encoded as 8 bits. Applying a color map will make the conversion from 8bit to 24bit. The default is true.

Target Format

Reserved for future usage to dictate decode process. For instance instead of having a post process stage of flipping the red and blue channels, to flip them during the decoding process so only a single pass is needed.

Contributing

All contributions are welcome. Here is a quick guideline:

  • Does your image fail to parse or look incorrect? File an issue with the image attached.
  • Want Pfim to support more image codecs? Raise an issue to let everyone know you're working on it and then get to work!
  • Have a performance improvement for Pfim? Excellent, run the before and after benchmarks!
dotnet run -c Release --project .\src\Pfim.Benchmarks -- --filter '*.Pfim'
  • Know a library to include in the benchmarks? If it is NuGet installable / easily integratable, please raise an issue or pull request!

Developer Resources

Building the library is as easy as

dotnet test -f net6.0

Or hit "Build" in Visual Studio 😄

Some references: