Merge pull request #58 from SixLabors/js/v3

Update to Version 3

Author: JimBobSquarePants

articles/imagesharp/gettingstarted.md

@@ -114,11 +114,10 @@ The easiest way to work with ImageSharp is to utilize our extension methods:
 ### Performance
 Achieving near-to-native performance is a major goal for the SixLabors team, and thanks to the improvements brought by the RyuJIT runtime, it's no longer mission impossible. We have made great progress and are constantly working on improvements.
 
-At the moment it's pretty hard to define fair benchmarks comparing GDI+ (aka. `System.Drawing` on Windows) and ImageSharp, because of the differences between the algorithms being used. Generally speaking, we are more feature rich, producing better quality. We hope we can match the corresponding algorithm parameters, and present some very specific benchmark results soon.
+At the moment it's pretty hard to define fair benchmarks comparing GDI+ (aka. `System.Drawing` on Windows) and ImageSharp, because of the differences between the algorithms being used. Generally speaking, we are faster and more feature rich, producing better quality output.
 
 If you are experiencing a significant performance gap between System.Drawing and ImageSharp for basic use-cases, there is a high chance that essential SIMD optimizations are not utilized. 
 
 A few troubleshooting steps to try:
 
 - Check the value of [Vector.IsHardwareAccelerated](https://docs.microsoft.com/en-us/dotnet/api/system.numerics.vector.ishardwareaccelerated?view=netcore-2.1&viewFallbackFrom=netstandard-2.0#System_Numerics_Vector_IsHardwareAccelerated). If the output is false, it means there is no SIMD support in your runtime!
-- Make sure your code runs on 64bit! Older .NET Framework versions are using the legacy runtime on 32 bits, having no built-in SIMD support.

articles/imagesharp/imageformats.md

@@ -17,15 +17,13 @@ ImageSharp's API however, is designed to support extension by the registration o
 
 [`Image<TPixel>`](xref:SixLabors.ImageSharp.Image`1) represents raw pixel data, stored in a contiguous memory block. It does not "remember" the original image format.
 
-ImageSharp identifies image formats (Jpeg, Png, Gif etc.) by [`IImageFormat`](xref:SixLabors.ImageSharp.Formats.IImageFormat) instances. There are several overloads of [`Image.Load`](xref:SixLabors.ImageSharp.Image) capable of returning the format as an `out` parameter. It's possible to pass that value to `image.Save` after performing the operation:
+ImageSharp identifies image formats (Jpeg, Png, Gif etc.) by [`IImageFormat`](xref:SixLabors.ImageSharp.Formats.IImageFormat) instances. Decoded images store the format in the [DecodedImageFormat](xref:SixLabors.ImageSharp.Metadata.ImageMetadata.DecodedImageFormat) within the image metadata. It is possible to pass that value to `image.Save` after performing the operation:
 
 ```C#
-IImageFormat format;
-
-using (var image = Image.Load(inputStream, out format))
+using (var image = Image.Load(inputStream))
 {
     image.Mutate(c => c.Resize(30, 30));
-    image.Save(outputStream, format);
+    image.Save(outputStream, image.Metadata.DecodedImageFormat);
 }
 ```
 
@@ -45,25 +43,33 @@ using (var image = Image.Load(inputStream, out format))
 
 Real life image streams are usually stored / transferred in standardized formats like Jpeg, Png, Bmp, Gif etc. An image format is represented by an [`IImageFormat`](xref:SixLabors.ImageSharp.Formats.IImageFormat) implementation.
 
-- [`IImageDecoder`](xref:SixLabors.ImageSharp.Formats.IImageDecoder) is responsible for decoding streams (and files) in into [`Image<TPixel>`](xref:SixLabors.ImageSharp.Image`1). ImageSharp can **auto-detect** the image formats of streams/files based on their headers, selecting the correct [`IImageFormat`](xref:SixLabors.ImageSharp.Formats.IImageFormat) (and thus [`IImageDecoder`](xref:SixLabors.ImageSharp.Formats.IImageDecoder)). This logic is implemented by [`IImageFormatDetector`](xref:SixLabors.ImageSharp.Formats.IImageFormatDetector)'s.
-- [`IImageEncoder`](xref:SixLabors.ImageSharp.Formats.IImageEncoder) is responsible for writing [`Image<TPixel>`](xref:SixLabors.ImageSharp.Image`1) into a stream using a given format.
+- [`ImageDecoder`](xref:SixLabors.ImageSharp.Formats.ImageDecoder) is responsible for decoding streams (and files) in into [`Image<TPixel>`](xref:SixLabors.ImageSharp.Image`1). ImageSharp can **auto-detect** the image formats of streams/files based on their headers, selecting the correct [`IImageFormat`](xref:SixLabors.ImageSharp.Formats.IImageFormat) (and thus [`ImageDecoder`](xref:SixLabors.ImageSharp.Formats.ImageDecoder)). This logic is implemented by [`IImageFormatDetector`](xref:SixLabors.ImageSharp.Formats.IImageFormatDetector)'s.
+- [`ImageEncoder`](xref:SixLabors.ImageSharp.Formats.ImageEncoder) is responsible for writing [`Image<TPixel>`](xref:SixLabors.ImageSharp.Image`1) into a stream using a given format.
 - Decoders/encoders and [`IImageFormatDetector`](xref:SixLabors.ImageSharp.Formats.IImageFormatDetector)'s are mapped to image formats in [`ImageFormatsManager`](xref:SixLabors.ImageSharp.Configuration.ImageFormatsManager). It's possible to register new formats, or drop existing ones. See [Configuration](configuration.md) for more details.
 
+### Working with Decoders
+
+The behavior of the various decoders during the decoding process can be controlled by passing [`DecoderOptions`](xref:SixLabors.ImageSharp.Formats.DecoderOptions) instances to our general `Load` APIs. These options contain means to control metadata handling, the decoded frame count, and properties to allow directly decoding the encoded image to a given target size.
+
+### Specialized Decoding
+
+In addition to the general decoding API we offer additional specialized decoding options [`ISpecializedDecoderOptions`](xref:SixLabors.ImageSharp.Formats.ISpecializedDecoderOptions) that can be accessed directly against [`ISpecializedDecoder<T>`](xref:SixLabors.ImageSharp.Formats.ISpecializedImageDecoder`1) instances which provide further options for decoding.
+
 ### Metadata-only Decoding
 
 Sometimes it's worth to efficiently decode image metadata ignoring the memory and CPU heavy pixel information inside the stream. ImageSharp allows this by using one of the several [Image.Identify](xref:SixLabors.ImageSharp.Image) overloads:
 
 ```C#
-IImageInfo imageInfo = Image.Identify(inputStream);
+ImageInfo imageInfo = Image.Identify(inputStream);
 Console.WriteLine($"{imageInfo.Width}x{imageInfo.Height} | BPP: {imageInfo.PixelType.BitsPerPixel}");
 ```
 
-See [`IImageInfo`](xref:SixLabors.ImageSharp.IImageInfo) for more details about the identification result. Note that [`Image<TPixel>`](xref:SixLabors.ImageSharp.Image`1) also implements `IImageInfo`.
+See [`ImageInfo`](xref:SixLabors.ImageSharp.ImageInfo) for more details about the identification result. Note that [`Image<TPixel>`](xref:SixLabors.ImageSharp.Image`1) also implements `ImageInfo`.
 
 ### Working with Encoders
 
 Image formats are usually defined by complex standards allowing multiple representations for the same image. ImageSharp allows parameterizing the encoding process:
-[`IImageEncoder`](xref:SixLabors.ImageSharp.Formats.IImageEncoder) implementations are stateless, lightweight **parametric** objects. This means that if you want to encode a Png in a specific way (eg. changing the compression level), you need to new-up a custom [`PngEncoder`](xref:SixLabors.ImageSharp.Formats.Png.PngEncoder) instance.
+[`ImageEncoder`](xref:SixLabors.ImageSharp.Formats.ImageEncoder) implementations are stateless, lightweight **parametric** objects. This means that if you want to encode a Png in a specific way (eg. changing the compression level), you need to new-up a custom [`PngEncoder`](xref:SixLabors.ImageSharp.Formats.Png.PngEncoder) instance.
 
 Choosing the right encoder parameters allows to balance between conflicting tradeoffs:
 

articles/imagesharp/index.md

@@ -1,15 +1,15 @@
 # Introduction
 
 ### What is ImageSharp?
-ImageSharp is a new, fully featured, fully managed, cross-platform, 2D graphics library.
+ImageSharp is a modern, fully featured, fully managed, cross-platform, 2D graphics library.
 Designed to simplify image processing, ImageSharp brings you an incredibly powerful yet beautifully simple API.
 
 ImageSharp is designed from the ground up to be flexible and extensible. The library provides API endpoints for common image processing operations and the building blocks to allow for the development of additional operations.  
 
-Built against [.NET Standard 2.0](https://docs.microsoft.com/en-us/dotnet/standard/net-standard), ImageSharp can be used in device, cloud, and embedded/IoT scenarios.  
+Built against [.NET 6](https://learn.microsoft.com/en-us/dotnet/core/whats-new/dotnet-6), ImageSharp can be used in device, cloud, and embedded/IoT scenarios.  
 
 ### License  
-ImageSharp is licensed under the terms of [Apache License, Version 2.0](https://opensource.org/licenses/Apache-2.0). Commercial support licensing options are available in addition to this license, see https://sixlabors.com/pricing for details.
+ImageSharp is licensed under the terms of the [Six Labors Split License, Version 1.0](https://github.com/SixLabors/ImageSharp/blob/main/LICENSE). See https://sixlabors.com/pricing for commercial licensing details.
 
 ### Installation
 

build-dev.ps1

@@ -1,9 +1,6 @@
 # Ensure all submodules are checked out with the latest main. (Useful for docs development.)
-git submodule update --init --recursive
-
-# Enable the following lines should there be any issues.
-# git submodule foreach git rm --cached -r .
-# git submodule foreach git reset --hard origin/main
+git submodule foreach git rm --cached -r .
+git submodule foreach git reset --hard origin/main
 
 git submodule foreach git pull -f origin main --recurse-submodules
 

ext/ImageSharp

@@ -5,7 +5,7 @@ We aim to provide modern, cross-platform, incredibly powerful yet beautifully si
 You can find tutorials, examples and API details covering all Six Labors projects.
 
 >[!NOTE]
->Documentation for previous releases can be found at <https://docs-v1.sixlabors.com/>.
+>Documentation for previous releases can be found at <https://docs-v2.sixlabors.com/>.
 
 ### [API documentation](api/index.md)