update docs

Author: saucecontrol

building.md

@@ -21,5 +21,5 @@ git submodule update --remote
 The projects can then be built as normal with Visual Studio or dotnet CLI.  The NuGet packages are built only under the `Dist` build configuration.
 
 ```
-dotnet build -c Dist
+dotnet build src\MagicScaler -c Dist
 ```

license

@@ -1,6 +1,6 @@
 The MIT License
 
-Copyright (c) 2015-2019 Clinton Ingram and Contributors
+Copyright (c) 2015-2020 Clinton Ingram and Contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

src/MagicScaler/Core/Enums.cs

@@ -50,9 +50,9 @@ public enum HybridScaleMode
 	/// <summary>Defines the modes that control <a href="http://blog.johnnovak.net/2016/09/21/what-every-coder-should-know-about-gamma/">gamma correction</a> in pixel blending.</summary>
 	public enum GammaMode
 	{
-		/// <summary>Convert values to linear RGB before blending.</summary>
+		/// <summary>Convert values to linear RGB before blending.  This is more mathematically correct and more visually pleasing in most cases.</summary>
 		Linear,
-		/// <summary>Blend gamma-companded R'G'B' values directly.</summary>
+		/// <summary>Blend gamma-companded R'G'B' values directly.  This is usually a poor choice but may be used for compatibility with other software or where speed is more important than image quality.</summary>
 		Companded,
 		/// <summary>Same as <see cref="Companded" />.</summary>
 		[Obsolete("Replaced by " + nameof(GammaMode) + "." + nameof(Companded), true), EditorBrowsable(EditorBrowsableState.Never)]
@@ -86,6 +86,7 @@ public enum ColorProfileMode
 		/// <summary>Convert the input image to the <a href="https://en.wikipedia.org/wiki/SRGB">sRGB color space</a> during processing.  Output an untagged sRGB image.</summary>
 		Normalize,
 		/// <summary>Convert the input image to the <a href="https://en.wikipedia.org/wiki/SRGB">sRGB color space</a> during processing.  Embed a compact sRGB profile in the output.</summary>
+		/// <remarks>This option ensures maximum compatibility with web browsers and other software but results in slightly larger (+456 bytes) output files.</remarks>
 		NormalizeAndEmbed,
 		/// <summary>Preserve the input image color space during processing.  Embed the ICC profile in the output image.  If the output format does not support embedded profiles, it will be discarded.</summary>
 		Preserve,
@@ -117,11 +118,11 @@ public enum Orientation
 	/// <summary>Defines the modes that control <a href="https://magnushoff.com/jpeg-orientation.html">Exif Orientation</a> correction.</summary>
 	public enum OrientationMode
 	{
-		/// <summary>Correct the image orientation according to the Exif tag on load.  Save the output in normal orientation.</summary>
+		/// <summary>Correct the image orientation according to the Exif tag on load.  Save the output in normal orientation.  This option ensures maximum compatibility with viewer software.</summary>
 		Normalize,
 		/// <summary>Preserve the orientation of the input image and tag the output image to reflect the orientation.  If the output format does not support orientation tagging, it will be discarded.</summary>
 		Preserve,
-		/// <summary>Ignore any orientation tag and treat the image as if its stored orientation is normal.  Do not tag the output image.</summary>
+		/// <summary>Ignore any orientation tag and treat the image as if its stored orientation is normal.  Do not tag the output image.  This option should only be used if the Exif orientation of the input image is known to be incorrect.</summary>
 		Ignore = 0xff
 	}
 

src/MagicScaler/Core/Interfaces.cs

@@ -26,29 +26,35 @@ public interface IPixelSource
 	/// <summary>A single image frame within an <see cref="IImageContainer" /></summary>
 	public interface IImageFrame : IDisposable
 	{
-		/// <summary>The horizontal resolution of the image frame, in dots/pixels per inch.  If the frame source has no resolution information, a default value of 72 or 96 is suitable.</summary>
+		/// <summary>The horizontal resolution of the image frame, in dots/pixels per inch.</summary>
+		/// <remarks>Implementation note: If the frame source has no resolution information, a default value of 72 or 96 is suitable.</remarks>
 		double DpiX { get; }
 
-		/// <summary>The vertical resolution of the image frame, in dots/pixels per inch.  If the frame source has no resolution information, a default value of 72 or 96 is suitable.</summary>
+		/// <summary>The vertical resolution of the image frame, in dots/pixels per inch.</summary>
+		/// <remarks>Implementation note: If the frame source has no resolution information, a default value of 72 or 96 is suitable.</remarks>
 		double DpiY { get; }
 
-		/// <summary>The <see cref="Orientation"/> of the image frame.  If the frame source has no orientation information, a default value of <see cref="Orientation.Normal"/> is suitable.</summary>
+		/// <summary>The <see cref="Orientation"/> of the image frame.</summary>
+		/// <remarks>Implementation note: If the frame source has no orientation information, a default value of <see cref="Orientation.Normal"/> is suitable.</remarks>
 		Orientation ExifOrientation { get; }
 
-		/// <summary>The <a href="https://en.wikipedia.org/wiki/ICC_profile">ICC color profile</a> that describes the color space of the image frame.  If this value is <see cref="ReadOnlySpan{T}.Empty" />, colors will be interpreted as <a href="https://en.wikipedia.org/wiki/SRGB">sRGB or sYCC</a>.</summary>
+		/// <summary>The <a href="https://en.wikipedia.org/wiki/ICC_profile">ICC color profile</a> that describes the color space of the image frame.</summary>
+		/// <remarks>If this value is <see cref="ReadOnlySpan{T}.Empty" />, colors will be interpreted as <a href="https://en.wikipedia.org/wiki/SRGB">sRGB or sYCC</a>.</remarks>
 		ReadOnlySpan<byte> IccProfile { get; }
 
 		/// <summary>The <see cref="IPixelSource" /> to retrieve pixels from this image frame.</summary>
 		IPixelSource PixelSource { get; }
 	}
 
 	/// <summary>An image frame within an <see cref="IImageContainer" />.  The frame exposes 3 <see cref="IPixelSource" /> values, representing the Y', Cb, and Cr planes.</summary>
+	/// <remarks>Implementation note: The <see cref="PixelSource" /> property should return the Y (luma) plane.</remarks>
 	public interface IYccImageFrame : IImageFrame
 	{
 		/// <summary>The position of subsampled chroma components relative to their associated luma components.</summary>
 		ChromaPosition ChromaPosition { get; }
 
-		/// <summary>A 3x3 matrix containing the coefficients for converting from R'G'B' to the Y'CbCr format of this image frame.  The fourth row and column will be ignored.  See <see cref="YccMatrix" /> for standard values.</summary>
+		/// <summary>A 3x3 matrix containing the coefficients for converting from R'G'B' to the Y'CbCr format of this image frame.</summary>
+		/// <remarks>The fourth row and column will be ignored.  See <see cref="YccMatrix" /> for standard values.</remarks>
 		Matrix4x4 RgbYccMatrix { get; }
 
 		/// <summary>True if the encoding uses the full 0-255 range for pixel values, false if it uses video range (16-235 luma and 16-240 chroma).</summary>

src/MagicScaler/Core/PixelFormats.cs

@@ -348,20 +348,26 @@ private static ReadOnlyDictionary<Guid, PixelFormat> getFormatCache()
 	public static class PixelFormats
 	{
 		/// <summary>Greyscale data with 1 byte per pixel.</summary>
+		/// <value>6FDDC324-4E03-4BFE-B185-3D77768DC908</value>
 		public static readonly Guid Grey8bpp = Consts.GUID_WICPixelFormat8bppGray;
 		/// <summary>RGB data with 1 byte per channel in BGR byte order.</summary>
+		/// <value>6FDDC324-4E03-4BFE-B185-3D77768DC90C</value>
 		public static readonly Guid Bgr24bpp = Consts.GUID_WICPixelFormat24bppBGR;
 		/// <summary>RGBA data with 1 byte per channel in BGRA byte order.</summary>
+		/// <value>6FDDC324-4E03-4BFE-B185-3D77768DC90F</value>
 		public static readonly Guid Bgra32bpp = Consts.GUID_WICPixelFormat32bppBGRA;
 
 		/// <summary>Contains standard pixel formats for <see cref="IYccImageFrame"/> implementations.</summary>
 		public static class Planar
 		{
 			/// <summary>Planar luma data with 1 byte per pixel.</summary>
+			/// <value>91B4DB54-2DF9-42F0-B449-2909BB3DF88E</value>
 			public static readonly Guid Y8bpp = Consts.GUID_WICPixelFormat8bppY;
 			/// <summary>Planar blue-yellow chroma data with 1 byte per pixel.</summary>
+			/// <value>1339F224-6BFE-4C3E-9302E4F3A6D0CA2A</value>
 			public static readonly Guid Cb8bpp = Consts.GUID_WICPixelFormat8bppCb;
 			/// <summary>Planar red-green chroma data with 1 byte per pixel.</summary>
+			/// <value>B8145053-2116-49F0-8835ED844B205C51</value>
 			public static readonly Guid Cr8bpp = Consts.GUID_WICPixelFormat8bppCr;
 		}
 	}

src/MagicScaler/Core/ProcessImageResult.cs

@@ -139,7 +139,7 @@ public ProcessingPipeline AddTransform(IPixelTransform transform)
 		}
 
 		/// <summary>Completes processing of the pipeline, writing the output image to <paramref name="outStream" />.</summary>
-		/// <param name="outStream">The stream to which the output image will be written.</param>
+		/// <param name="outStream">The stream to which the output image will be written. The stream must allow Seek and Write.</param>
 		/// <returns>A <see cref="ProcessImageResult" /> containing the settings used and basic instrumentation for the pipeline.</returns>
 		public ProcessImageResult WriteOutput(Stream outStream) => MagicImageProcessor.WriteOutput(Context, outStream);