v.0.13 Change Log / Roadmap

Changes in v0.13

Breaking Changes

In earlier MagicScaler versions, any codec registered with WIC was eligible to use for decode. This resulted in some compatibility issues when third party codecs overrode the built-in WIC decoders in the discovery order. Now by default, only WIC built-in codecs are registered for use with the MagicScaler pipeline. Available codecs can be configured explicitly with the new CodecManager.
```
// WIC codecs are automatically registered on Windows, using WicCodecPolicy.BuiltIn
// This removes the default codec set and registers all WIC codecs
CodecManager.Configure(codecs => {
    codecs.Clear();
    codecs.UseWicCodecs(WicCodecPolicy.All);
});
```
The new codec registration system may alter the order in which compatible decoders are invoked for a given file when compared to WIC's codec discovery. Codecs may be reordered in the CodecManager.Configure action if you need to adjust preference -- codecs are tried in the order they appear in the collection.
The FileFormat enum has been deprecated in favor of MIME types in all APIs where it was previously used. The new ImageMimeTypes class contains definitions for most well-known image formats.
- The ProcessImageSettings.SaveFormat property has been obsoleted in favor of the new TrySetEncoderFormat(string mimeType) method, which allows selection of any encoder registered with the pipeline. Alternatively, new ProcessImage overloads accepting an output path have been added. These overloads will automatically select the encoder based on the file extension given in the path.
- ImageFileInfo.ContainerType has been obsoleted in favor of the new MimeType property.
- IImageContainer.ContainerType was removed and replaced with a new MimeType property.
ProcessImageSettings.JpegQuality and ProcessImageSettings.JpegSubsampleMode have been obsoleted in favor of JpegEncoderOptions.
ProcessImageSettings.FrameIndex has been obsoleted in favor of DecoderOptions supporting IMultiFrameDecoderOptions, which allows selection of a range of frames to decode.
```
// Old and busted
// settings.FrameIndex = 10;

// New hotness -- decode only the last 5 frames of a GIF
settings.DecoderOptions = new GifDecoderOptions(^5..^1);
```
Note that the above example uses the C# 8 range syntax. In order to support System.Index and System.Range, .NET Framework builds of MagicScaler use bgrainger/IndexRange, which is currently the most popular polyfill package. See https://github.com/dotnet/runtime/issues/28285
MagicImageProcessor.EnablePlanarPipeline has been obsoleted in favor of a per-decoder setting, using IPlanarDecoderOptions. Decoder options can be configured per-operation or as part of default options for the decoder.
```
// Disable planar decoding of JPEG for one operation
settings.DecoderOptions = new JpegDecoderOptions(AllowPlanar: false);

// Or change the default JPEG decoder options to disable planar decode globally
CodecManager.Configure(codecs => {
    var jpeg = codecs.OfType<DecoderInfo>().First(c => c.MimeTypes.Any(m => m == ImageMimeTypes.Jpeg));
    codecs.Remove(jpeg);
    codecs.Add(jpeg with { DefaultOptions = new JpegDecoderOptions(AllowPlanar: false) });
});
```
Note that the new codec descriptors and options make heavy use of C# 9 record syntax in order save on boilerplate code. You may not be able to access properties on these types by their friendly names unless you are using C# version 9 or newer in your projects. MagicScaler will continue to be supported on .NET Framework for the foreseeable future, but it will be making use of modern language features in the public API going forward. Update your tooling for the best experience.

Some advanced global settings have been moved from static fields on MagicImageProcessor to AppContext values. These values must be set at app startup, as they are cached by the library on first read.

// The following are no longer functional
// MagicImageProcessor.EnablePixelSourceStats = true;
// MagicImageProcessor.EnableLargeBufferPool = false;

// Replacements for the above
AppContext.SetSwitch("PhotoSauce.MagicScaler.EnablePixelSourceStats", true);
AppDomain.CurrentDomain.SetData("PhotoSauce.MagicScaler.MaxPooledBufferSize", 1 << 20);

// Or, starting in .NET 7 (https://github.com/dotnet/runtime/issues/47922)
AppContext.SetSwitch("PhotoSauce.MagicScaler.EnablePixelSourceStats", true);
AppContext.SetData("PhotoSauce.MagicScaler.MaxPooledBufferSize", 1 << 20);

Alternatively, these values can be configured in runtimeconfig.json and changed without altering your app code.

MagicImageProcessor.EnableXmpOrientation has been obsoleted with no planned replacement. Images storing orientation in XMP metadata are vanishingly rare, and very little software supports orientation stored in XMP. If you are using this feature, feel free to open an issue and plead your case for keeping it.
The following properties were removed from IImageFrame, to be replaced by the new IMetadataSource interface on frames that support these metadata types.
- DpiX
- DpiY
- ExifOrientation
- IccProfile
IImageContainer now inherits from IDisposable.
Dropped support for netcoreapp2.1, which is now out of support by Microsoft, and net5.0 which goes out of support next month.

New APIs

CodecManager allows explicit configuration of encoders and decoders, along with their default codec-specific configurations.
Many new codec-specific option types have been added, based on the IDecoderOptions and IEncoderOptions interfaces. Examples:
- PngIndexedEncoderOptions allows configuration of the PNG encoder with indexed color, replacing the obsoleted FileFormat.Png8, and adding the ability to explicitly configure PNG prediction filters which were not previously available.
- GifEncoderOptions and PngIndexedEncoderOptions allow selection of palette size, which was previously hard-coded to 256, as well as dithering options and custom palettes.
- CameraRawDecoderOptions allows control over use of the preview image stored in most Camera RAW images, which can be used instead of developing the RAW image. Previously the preview was used automatically if its size matched the RAW image exactly, but some cameras include a smaller (but still high-resolution) preview image. RawPreviewMode.Always enables use of these smaller previews.
Multiple new interfaces have been added to allow codec authors to define image decoders, encoders, metadata sources, and metadata items. See the ManagedCodecs.ImageSharp project in this repo for an example of how to use these interfaces. #22 #19
Added a new zone plate test pattern generator -- ZonePlatePixelSource.

Native Codec Previews

Added a libheif wrapper capable of decoding Apple HEIC images.
Added a libjxl wrapper to preview JPEG XL support. The underlying native library is quite unstable in this release, so use with extreme care.

Performance Improvements

Added new internal buffered Stream implementation to replace the buffering in FileStream. If you are using FileStream as a source or destination, it is recommended you disable buffering on the FileStream instance by using a constructor that accepts the bufferSize parameter and setting bufferSize = 1. Alternatively, use a ProcessImage overload accepting file paths and let MagicScaler handle the FileStream(s) for you.
Improved speed of palette selection and mapping for indexed color formats.
Improved speed of conversion from YCbCr to BGR formats.
Improved hybrid scaling quality and speed on BGRA images.
Increased the maximum size of the large buffer pool to match the new default of 1GiB on .NET 6. Max buffer size is now configurable with the new PhotoSauce.MagicScaler.MaxPooledBufferSize AppContext value.

Image Quality Improvements

Improved palette selection when converting high-color images to indexed formats. The new algorithm performs better on gradients by weighting color population more heavily, while the old algorithm preferred greater distance between colors, with the expectation that dithering would benefit from wider color choice.

Non-behavioral Changes

IL Trimming for self-contained apps is now enabled for all libraries.

Future Roadmap

Linux Compatibility

The main focus of the 0.14 release will be general Linux compatibility. Major work items:

Replace WIC LUT-based ICC profile processing with internal implementation. Matrix-based profiles already have managed implementations.
Add more managed pixel format converters. There are still a few conversions for which WIC is used.
Move WIC codec and metadata components to a separate library so they may be used only in Windows-targeted builds.
Add native wrappers for common codecs (libjpeg[-turbo], libpng, libgif, libtiff).

Advanced Metadata Handling

The current handling of metadata based on Windows Photo Metadata Policies is inadequate for many uses, particularly when converting between formats (see #60). The new API will support plugin metadata policies that give more explicit control.

One key use case is maintaining IPTC copyright and artist values used by Google Images when converting between image formats.

saucecontrol / PhotoSauce