Change API to v0.7rc, update some code comments

Update library files to Git 2022-08-24 build.

JxlExample/EncoderOptionsForm2.cs

@@ -58,7 +58,7 @@ private void SetOptions()
 
 		private void ReadOptions()
 		{
-			int effort = 7;
+			long effort = 7;
 			if (this.EncoderOptions.Settings.TryGetValue(JxlEncoderFrameSettingId.Effort, out effort) && effort != -1)
 			{
 
@@ -68,7 +68,7 @@ private void ReadOptions()
 				effort = 7;
 			}
 
-			int decodingSpeed = 0;
+			long decodingSpeed = 0;
 			if (this.EncoderOptions.Settings.TryGetValue(JxlEncoderFrameSettingId.DecodingSpeed, out decodingSpeed) && decodingSpeed != -1)
 			{
 
@@ -78,7 +78,7 @@ private void ReadOptions()
 				decodingSpeed = 0;
 			}
 
-			int keepInvisible = 0;
+			long keepInvisible = 0;
 			if (this.EncoderOptions.Settings.TryGetValue(JxlEncoderFrameSettingId.KeepInvisible, out keepInvisible) && keepInvisible != -1)
 			{
 
@@ -96,15 +96,15 @@ private void ReadOptions()
 
 			if (effort >= 1 && effort <= 9)
 			{
-				cboEncodingSpeed.SelectedIndex = effort - 1;
+				cboEncodingSpeed.SelectedIndex = (int)(effort - 1);
 			}
 			else
 			{
 				cboEncodingSpeed.SelectedIndex = 7 - 1;
 			}
 			if (decodingSpeed >= 0 && decodingSpeed <= 4)
 			{
-				cboDecodingSpeed.SelectedIndex = decodingSpeed;
+				cboDecodingSpeed.SelectedIndex = (int)decodingSpeed;
 			}
 			optLossless.Checked = false;
 			optAuto.Checked = false;
@@ -134,7 +134,7 @@ private void ReadOptions()
 
 	public class EncoderOptions
 	{
-		public Dictionary<JxlSharp.JxlEncoderFrameSettingId, int> Settings = new Dictionary<JxlSharp.JxlEncoderFrameSettingId, int>();
+		public Dictionary<JxlSharp.JxlEncoderFrameSettingId, long> Settings = new Dictionary<JxlSharp.JxlEncoderFrameSettingId, long>();
 		public JxlLossyMode LossyMode;
 		public float Quality;
 		public EncoderOptions()

JxlExample/Form1.cs

@@ -16,7 +16,7 @@ public partial class Form1 : Form
 	{
 		string loadedFileName = "";
 		EncoderOptions encoderOptions = new EncoderOptions();
-		Dictionary<JxlEncoderFrameSettingId, int> jxlSettings = new Dictionary<JxlEncoderFrameSettingId, int>();
+		Dictionary<JxlEncoderFrameSettingId, long> jxlSettings = new Dictionary<JxlEncoderFrameSettingId, long>();
 
 		public Form1()
 		{

JxlSharp/JXL.cs

@@ -653,7 +653,7 @@ private static byte[] CopyBitmapAndBgrSwap(Bitmap bitmap, bool hasAlpha)
 		/// Default value: 1.0.</param>
 		/// <param name="settings">The settings to save the image with</param>
 		/// <returns>The JXL file, or null on failure</returns>
-		public static byte[] EncodeJxl(Bitmap bitmap, JxlLossyMode lossyMode, float frameDistance, IDictionary<JxlEncoderFrameSettingId, int> settings)
+		public static byte[] EncodeJxl(Bitmap bitmap, JxlLossyMode lossyMode, float frameDistance, IDictionary<JxlEncoderFrameSettingId, long> settings)
 		{
 			JxlEncoderStatus status;
 			MemoryStream ms = new MemoryStream();

JxlSharp/JxlDecoder.cs

@@ -165,6 +165,7 @@ public JxlDecoderStatus SkipCurrentFrame()
 		/// <returns>
 		///     <see cref="JxlDecoderStatus.Success" /> if no error, <see cref="JxlDecoderStatus.NeedMoreInput" /> if the
 		/// basic info isn't yet available, and <see cref="JxlDecoderStatus.Error" /> otherwise.</returns>
+		[Obsolete]
 		public JxlDecoderStatus GetDefaultPixelFormat(out JxlPixelFormat format)
 		{
 			format = new JxlPixelFormat();
@@ -241,6 +242,25 @@ public JxlDecoderStatus SetKeepOrientation(bool keepOrientation)
 			return (JxlDecoderStatus)decoderWrapper.SetKeepOrientation(keepOrientation);
 		}
 
+		/// <summary>
+		/// Enables or disables preserving of associated alpha channels. If
+		/// unpremul_alpha is set to JXL_FALSE then for associated alpha channel, the
+		/// pixel data is returned with premultiplied colors. If it is set to JXL_TRUE,
+		/// The colors will be unpremultiplied based on the alpha channel. This function
+		/// has no effect if the image does not have an associated alpha channel.
+		/// <br /><br />
+		/// By default, this option is disabled, and the returned pixel data "as is".
+		/// <br /><br />
+		/// This function must be called at the beginning, before decoding is performed.
+		/// </summary>
+		/// <param name="unpremulAlpha"> JXL_TRUE to enable, JXL_FALSE to disable.</param>
+		/// <returns>
+		///     <see cref="JxlDecoderStatus.Success" /> if no error, <see cref="JxlDecoderStatus.Error" /> otherwise.</returns>
+		public JxlDecoderStatus SetUnpremultiplyAlpha(bool unpremulAlpha)
+		{
+			return (JxlDecoderStatus)decoderWrapper.SetUnpremultiplyAlpha(unpremulAlpha);
+		}
+
 		/// <summary>
 		/// Enables or disables rendering spot colors. By default, spot colors
 		/// are rendered, which is OK for viewing the decoded image. If render_spotcolors
@@ -379,9 +399,10 @@ public JxlDecoderStatus SetInput(byte[] data)
 		/// remaining in the data set by <see cref="SetInput(byte[])" />, or 0 if no input is
 		/// set or <see cref="ReleaseInput" /> was already called. For a next call
 		/// to <see cref="ProcessInput" />, the buffer must start with these
-		/// unprocessed bytes. This value doesn't provide information about how many
-		/// bytes the decoder truly processed internally or how large the original
-		/// JPEG XL codestream or file are.</returns>
+		/// unprocessed bytes. From this value it is possible to infer the position
+		/// of certain JPEG XL codestream elements (e.g. end of headers, frame
+		/// start/end). See the documentation of individual values of 
+		/// <see cref="JxlDecoderStatus" /> for more information.</returns>
 		public int ReleaseInput()
 		{
 			return decoderWrapper.ReleaseInput();
@@ -485,8 +506,7 @@ public JxlDecoderStatus GetExtraChannelName(int index, out string name)
 		/// for a specific color space, possibly indicated in the JPEG XL
 		/// image, <see cref="GetColorAsEncodedProfile" /> should be used first.
 		/// </summary>
-		/// <param name="format"> pixel format to output the data to. Only used for 
-		/// <see cref="JxlColorProfileTarget.Data" />, may be nullptr otherwise.</param>
+		/// <param name="unusedFormat"> deprecated, can be NULL</param>
 		/// <param name="target"> whether to get the original color profile from the metadata
 		/// or the color profile of the decoded pixels.</param>
 		/// <param name="colorEncoding"> struct to copy the information into, or NULL to only
@@ -496,14 +516,14 @@ public JxlDecoderStatus GetExtraChannelName(int index, out string name)
 		/// <see cref="JxlDecoderStatus.NeedMoreInput" /> if not yet available, <see cref="JxlDecoderStatus.Error" /> in
 		/// case the encoded structured color profile does not exist in the
 		/// codestream.</returns>
-		public JxlDecoderStatus GetColorAsEncodedProfile(JxlPixelFormat format, JxlColorProfileTarget target, out JxlColorEncoding colorEncoding)
+		public JxlDecoderStatus GetColorAsEncodedProfile(JxlPixelFormat unusedFormat, JxlColorProfileTarget target, out JxlColorEncoding colorEncoding)
 		{
 			colorEncoding = new JxlColorEncoding();
 			unsafe
 			{
-				if (format != null)
+				if (unusedFormat != null)
 				{
-					fixed (UnsafeNativeJxl.JxlPixelFormat* pFormat = &format.pixelFormat)
+					fixed (UnsafeNativeJxl.JxlPixelFormat* pFormat = &unusedFormat.pixelFormat)
 					{
 						var status = (JxlDecoderStatus)decoderWrapper.GetColorAsEncodedProfile(pFormat, (UnsafeNativeJxl.JxlColorProfileTarget)target, out colorEncoding.colorEncoding);
 						return status;
@@ -527,8 +547,7 @@ public JxlDecoderStatus GetColorAsEncodedProfile(JxlPixelFormat format, JxlColor
 		/// or a close approximation generated from JPEG XL encoded structured data,
 		/// depending of what is encoded in the codestream.
 		/// </summary>
-		/// <param name="format"> pixel format to output the data to. Only used for 
-		/// <see cref="JxlColorProfileTarget.Data" />, may be NULL otherwise.</param>
+		/// <param name="unusedFormat"> deprecated, can be NULL</param>
 		/// <param name="target"> whether to get the original color profile from the metadata
 		/// or the color profile of the decoded pixels.</param>
 		/// <param name="size"> variable to output the size into, or NULL to only check the
@@ -539,14 +558,14 @@ public JxlDecoderStatus GetColorAsEncodedProfile(JxlPixelFormat format, JxlColor
 		/// input data to determine whether an ICC profile is available or what its
 		/// size is, <see cref="JxlDecoderStatus.Error" /> in case the ICC profile is not available and
 		/// cannot be generated.</returns>
-		public JxlDecoderStatus GetICCProfileSize(JxlPixelFormat format, JxlColorProfileTarget target, out int size)
+		public JxlDecoderStatus GetICCProfileSize(JxlPixelFormat unusedFormat, JxlColorProfileTarget target, out int size)
 		{
 			JxlDecoderStatus status;
 			unsafe
 			{
-				if (format != null)
+				if (unusedFormat != null)
 				{
-					fixed (UnsafeNativeJxl.JxlPixelFormat* pFormat = &format.pixelFormat)
+					fixed (UnsafeNativeJxl.JxlPixelFormat* pFormat = &unusedFormat.pixelFormat)
 					{
 						status = (JxlDecoderStatus)decoderWrapper.GetICCProfileSize(pFormat, (UnsafeNativeJxl.JxlColorProfileTarget)target, out size);
 						return status;
@@ -565,8 +584,7 @@ public JxlDecoderStatus GetICCProfileSize(JxlPixelFormat format, JxlColorProfile
 		/// <see cref="GetICCProfileSize" /> returns success. The output buffer must have
 		/// at least as many bytes as given by <see cref="GetICCProfileSize" />.
 		/// </summary>
-		/// <param name="format"> pixel format to output the data to. Only used for 
-		/// <see cref="JxlColorProfileTarget.Data" />, may be NULL otherwise.</param>
+		/// <param name="unusedFormat"> deprecated, can be NULL</param>
 		/// <param name="target"> whether to get the original color profile from the metadata
 		/// or the color profile of the decoded pixels.</param>
 		/// <param name="iccProfile"> buffer to copy the ICC profile into</param>
@@ -575,13 +593,13 @@ public JxlDecoderStatus GetICCProfileSize(JxlPixelFormat format, JxlColorProfile
 		/// available, <see cref="JxlDecoderStatus.NeedMoreInput" /> if not yet available, 
 		/// <see cref="JxlDecoderStatus.Error" /> if the profile doesn't exist or the output size is not
 		/// large enough.</returns>
-		public JxlDecoderStatus GetColorAsICCProfile(JxlPixelFormat format, JxlColorProfileTarget target, out byte[] iccProfile)
+		public JxlDecoderStatus GetColorAsICCProfile(JxlPixelFormat unusedFormat, JxlColorProfileTarget target, out byte[] iccProfile)
 		{
 			unsafe
 			{
-				if (format != null)
+				if (unusedFormat != null)
 				{
-					fixed (UnsafeNativeJxl.JxlPixelFormat* pFormat = &format.pixelFormat)
+					fixed (UnsafeNativeJxl.JxlPixelFormat* pFormat = &unusedFormat.pixelFormat)
 					{
 						var status = (JxlDecoderStatus)decoderWrapper.GetColorAsICCProfile(pFormat, (UnsafeNativeJxl.JxlColorProfileTarget)target, out iccProfile);
 						return status;

JxlSharp/JxlEncoder.cs

@@ -863,11 +863,27 @@ public JxlEncoderStatus SetFrameName(string frameName)
 		/// value for the given option. If an error is returned, the state of the
 		/// JxlEncoderFrameSettings object is still valid and is the same as before this
 		/// function was called.</returns>
-		public JxlEncoderStatus SetOption(JxlEncoderFrameSettingId option, int value)
+		public JxlEncoderStatus SetOption(JxlEncoderFrameSettingId option, long value)
 		{
 			return (JxlEncoderStatus)frameSettings.SetOption((UnsafeNativeJxl.JxlEncoderFrameSettingId)option, value);
 		}
 
+		/// <summary>
+		/// Sets a frame-specific option of float type to the encoder options.
+		/// The JxlEncoderFrameSettingId argument determines which option is set.
+		/// </summary>
+		/// <param name="option"> ID of the option to set.</param>
+		/// <param name="value"> Float value to set for this option.</param>
+		/// <returns> <see cref="JxlEncoderStatus.Success"/> if the operation was successful, <see cref="JxlEncoderStatus.Error"/> in
+		/// case of an error, such as invalid or unknown option id, or invalid integer
+		/// value for the given option. If an error is returned, the state of the
+		/// JxlEncoderFrameSettings object is still valid and is the same as before this
+		/// function was called.</returns>
+		public JxlEncoderStatus SetFloatOption(JxlEncoderFrameSettingId option, float value)
+		{
+			return (JxlEncoderStatus)frameSettings.SetFloatOption((UnsafeNativeJxl.JxlEncoderFrameSettingId)option, value);
+		}
+
 		/// <summary>
 		/// Enables lossless encoding.
 		/// <br /><br />

JxlSharp/JxlTypes.cs

@@ -130,6 +130,16 @@ public enum JxlDecoderStatus
 		/// <summary>
 		/// Function call finished successfully, or decoding is finished and there is
 		/// nothing more to be done.
+		/// <br /><br />
+		/// Note that <see cref="JxlDecoder.ProcessInput" /> will return <see cref="JxlDecoderStatus.Success"/> if all
+		/// events that were registered with <see cref="JxlDecoder.SubscribeEvents" /> were
+		/// processed, even before the end of the JPEG XL codestream.
+		/// <br /><br />
+		/// In this case, the return value <see cref="JxlDecoder.ReleaseInput" /> will be the same
+		/// as it was at the last signaled event. E.g. if <see cref="JxlDecoderStatus.FullImage"/> was
+		/// subscribed to, then all bytes from the end of the JPEG XL codestream
+		/// (including possible boxes needed for jpeg reconstruction) will be returned
+		/// as unprocessed.
 		/// </summary>
 		Success = 0,
 
@@ -148,6 +158,11 @@ public enum JxlDecoderStatus
 		/// all unprocessed bytes must be provided again (the address need not match,
 		/// but the contents must), and more bytes must be concatenated after the
 		/// unprocessed bytes.
+		/// <br/>In most cases, <see cref="JxlDecoder.ReleaseInput" /> will return no unprocessed bytes
+		/// at this event, the only exceptions are if the previously set input ended
+		/// within (a) the raw codestream signature, (b) the signature box, (c) a box
+		/// header, or (d) the first 4 bytes of a brob, ftyp, or jxlp box. In any of
+		/// these cases the number of unprocessed bytes is less than 20.
 		/// </summary>
 		NeedMoreInput = 2,
 
@@ -157,6 +172,9 @@ public enum JxlDecoderStatus
 		/// if <see cref="PreviewImage"/> is requested and it is possible to decode a
 		/// preview image from the codestream and the preview out buffer was not yet
 		/// set. There is maximum one preview image in a codestream.
+		/// <br/>In this case, <see cref="JxlDecoder.ReleaseInput" /> will return all bytes from the
+		/// end of the frame header (including ToC) of the preview frame as
+		/// unprocessed.
 		/// </summary>
 		NeedPreviewOutBuffer = 3,
 
@@ -174,6 +192,8 @@ public enum JxlDecoderStatus
 		/// The decoder requests an output buffer to store the full resolution image,
 		/// which can be set with <see cref="JxlDecoder.SetImageOutBuffer"/> or with <see cref="JxlDecoder.SetImageOutCallback"/>. This event re-occurs for new frames if
 		/// there are multiple animation frames and requires setting an output again.
+		/// <br/>In this case, <see cref="JxlDecoder.ReleaseInput" /> will return all bytes from the
+		/// end of the frame header (including ToC) as unprocessed.
 		/// </summary>
 		NeedImageOutBuffer = 5,
 
@@ -196,6 +216,9 @@ public enum JxlDecoderStatus
 		/// Informative event by <see cref="JxlDecoder.ProcessInput"/>
 		/// "JxlDecoderProcessInput": Basic information such as image dimensions and
 		/// extra channels. This event occurs max once per image.
+		/// <br/>In this case, <see cref="JxlDecoder.ReleaseInput" /> will return all bytes from the
+		/// end of the basic info as unprocessed (including the last byte of basic info
+		/// if it did not end on a byte boundary).
 		/// </summary>
 		BasicInfo = 0x40,
 
@@ -214,6 +237,9 @@ public enum JxlDecoderStatus
 		/// "JxlDecoderProcessInput": Color encoding or ICC profile from the
 		/// codestream header. This event occurs max once per image and always later
 		/// than <see cref="BasicInfo"/> and earlier than any pixel data.
+		/// <br/>In this case, <see cref="JxlDecoder.ReleaseInput" /> will return all bytes from the
+		/// end of the image header (which is the start of the first frame) as
+		/// unprocessed.
 		/// </summary>
 		ColorEncoding = 0x100,
 
@@ -222,6 +248,8 @@ public enum JxlDecoderStatus
 		/// "JxlDecoderProcessInput": Preview image, a small frame, decoded. This
 		/// event can only happen if the image has a preview frame encoded. This event
 		/// occurs max once for the codestream and always later than <see cref="ColorEncoding"/> and before <see cref="Frame"/>.
+		/// <br/>In this case, <see cref="JxlDecoder.ReleaseInput" /> will return all bytes from the
+		/// end of the preview frame as unprocessed.
 		/// </summary>
 		PreviewImage = 0x200,
 
@@ -240,6 +268,8 @@ public enum JxlDecoderStatus
 		/// JPEG XL supports encoding a single frame as the composition of multiple
 		/// internal sub-frames also called frames, this event is not indicated for the
 		/// internal frames.
+		/// <br/>In this case, <see cref="JxlDecoder.ReleaseInput" /> will return all bytes from the
+		/// end of the frame header (including ToC) as unprocessed.
 		/// </summary>
 		Frame = 0x400,
 
@@ -265,6 +295,10 @@ public enum JxlDecoderStatus
 		/// getting the basic image information to be able to get the image pixels, if
 		/// not this return status only indicates we're past this point in the
 		/// codestream. This event occurs max once per frame and always later than <see cref="DcImage"/>.
+		/// <br/>In this case, <see cref="JxlDecoder.ReleaseInput" /> will return all bytes from the
+		/// end of the frame (or if <see cref="JpegReconstruction" /> is subscribed to,
+		/// from the end of the last box that is needed for jpeg reconstruction) as
+		/// unprocessed.
 		/// </summary>
 		FullImage = 0x1000,
 
@@ -276,6 +310,8 @@ public enum JxlDecoderStatus
 		/// image will be written to the JPEG reconstruction buffer instead of pixels
 		/// to the image out buffer. This event occurs max once per image and always
 		/// before <see cref="FullImage"/>.
+		/// <br/>In this case, <see cref="JxlDecoder.ReleaseInput" /> will return all bytes from the
+		/// end of the 'jbrd' box as unprocessed.
 		/// </summary>
 		JpegReconstruction = 0x2000,
 
@@ -311,6 +347,9 @@ public enum JxlDecoderStatus
 		/// boxes. To check whether the box is a metadata type for respectively EXIF,
 		/// XMP or JUMBF, use <see cref="JxlDecoder.GetBoxType"/> and check for types "Exif",
 		/// "xml " and "jumb" respectively.
+		/// <br /><br />
+		/// In this case, <see cref="JxlDecoder.ReleaseInput" /> will return all bytes from the
+		/// start of the box header as unprocessed.
 		/// </summary>
 		Box = 0x4000,
 
@@ -325,6 +364,9 @@ public enum JxlDecoderStatus
 		/// full resolution, giving upscaled DC). Use <see cref="JxlDecoder.SetProgressiveDetail"/> to configure more fine-grainedness. The
 		/// event is not guaranteed to trigger, not all images have progressive steps
 		/// or DC encoded.
+		/// <br/>In this case, <see cref="JxlDecoder.ReleaseInput" /> will return all bytes from the
+		/// end of the section that was needed to produce this progressive event as
+		/// unprocessed.
 		/// </summary>
 		FrameProgression = 0x8000,
 	}