chore: Update copyright years in licenses and README.md.

inflation · Aug 24, 2024 · 7a1248f · 7a1248f
1 parent 20d747a
commit 7a1248f
Show file tree

Hide file tree

Showing 5 changed files with 206 additions and 9 deletions.
diff --git a/README.md b/README.md
@@ -5,7 +5,7 @@
 [![dependency status](https://deps.rs/repo/github/inflation/jpegxl-rs/status.svg)](https://deps.rs/repo/github/inflation/jpegxl-rs)
 [![CI](https://github.com/inflation/jpegxl-rs/workflows/CI/badge.svg)](https://github.com/inflation/jpegxl-rs/actions?query=workflow%3ACI)
 [![codecov](https://codecov.io/gh/inflation/jpegxl-rs/branch/master/graph/badge.svg?token=3WMRUQ816H)](https://codecov.io/gh/inflation/jpegxl-rs)
-[![License: GPL-3.0-or-later](https://img.shields.io/crates/l/jpegxl-rs)](https://github.com/inflation/jpegxl-rs/blob/master/LICENSE)
+[![License: GPL-3.0-or-later](https://img.shields.io/crates/l/jpegxl-rs)](https://github.com/inflation/jpegxl-rs/blob/master/jpegxl-rs/LICENSE)
 
 A safe JPEGXL wrapper over `libjxl` library. Check out the original [library](https://github.com/libjxl/libjxl)
 and the [bindings](https://github.com/inflation/jpegxl-rs/tree/master/jpegxl-sys).
@@ -110,4 +110,7 @@ let img = decoder.decode_to_image(&sample).unwrap();
 let img = decoder.decode_to_image_with::<f32>(&sample).unwrap();
 ```
 
-License: GPL-3.0-or-later
+## License
+
+* `jpegxl-rs` and `jpegxl-sys`: GPL-3.0-or-later
+* `jpegxl-src`: BSD 3-Clause
diff --git a/jpegxl-rs/LICENSE b/jpegxl-rs/LICENSE
@@ -1,5 +1,5 @@
 jpegxl-rs is a safe wrapper around jpeg-xl decoder
-Copyright (C) 2020-2022 Inflation
+Copyright (C) 2020-2024 Inflation
 
 This program is free software: you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by
@@ -12,4 +12,4 @@ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 GNU General Public License for more details.
 
 You should have received a copy of the GNU General Public License
-along with this program.  If not, see <https://www.gnu.org/licenses/>.
+along with this program.  If not, see <https://www.gnu.org/licenses/>.
diff --git a/jpegxl-src/LICENSE b/jpegxl-src/LICENSE
@@ -1,6 +1,6 @@
 BSD 3-Clause License
 
-Copyright (c) 2022, Inflation
+Copyright (c) 2022-2024, Inflation
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions are met:
@@ -25,4 +25,4 @@ DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
 SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
 CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
diff --git a/jpegxl-sys/LICENSE b/jpegxl-sys/LICENSE
@@ -1,5 +1,5 @@
 jpegxl-sys is a wrapper around jpeg-xl decoder's C API
-Copyright (C) 2020 Inflation
+Copyright (C) 2020-2024 Inflation
 
 This program is free software: you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by
@@ -12,4 +12,4 @@ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 GNU General Public License for more details.
 
 You should have received a copy of the GNU General Public License
-along with this program.  If not, see <https://www.gnu.org/licenses/>.
+along with this program.  If not, see <https://www.gnu.org/licenses/>.
diff --git a/jpegxl-sys/src/decode.rs b/jpegxl-sys/src/decode.rs
@@ -22,7 +22,9 @@ use std::{
 
 use crate::{
     cms::JxlCmsInterface,
-    codestream_header::{JxlBasicInfo, JxlBlendInfo, JxlExtraChannelInfo, JxlFrameHeader},
+    codestream_header::{
+        JxlBasicInfo, JxlBlendInfo, JxlExtraChannelInfo, JxlFrameHeader, JxlOrientation,
+    },
     color_encoding::JxlColorEncoding,
     memory_manager::JxlMemoryManager,
     parallel_runner::JxlParallelRunner,
@@ -47,20 +49,42 @@ pub struct JxlDecoder {
 #[repr(C)]
 #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
 pub enum JxlDecoderStatus {
+    #[doc(alias = "JXL_DEC_SUCCESS")]
     Success = 0,
+    #[doc(alias = "JXL_DEC_ERROR")]
     Error = 1,
+    #[doc(alias = "JXL_DEC_NEED_MORE_INPUT")]
     NeedMoreInput = 2,
+    #[doc(alias = "JXL_DEC_JPEG_RESTART")]
     NeedPreviewOutBuffer = 3,
+    #[doc(alias = "JXL_DEC_NEED_IMAGE_OUT_BUFFER")]
     NeedImageOutBuffer = 5,
+    #[doc(alias = "JXL_DEC_JPEG_NEED_MORE_OUTPUT")]
     JpegNeedMoreOutput = 6,
+    #[doc(alias = "JXL_DEC_BOX_NEED_MORE_OUTPUT")]
     BoxNeedMoreOutput = 7,
+    /** Informative event by [`JxlDecoderProcessInput`]
+     * "JxlDecoderProcessInput": Basic information such as image dimensions and
+     * extra channels. This event occurs max once per image.
+     * In this case, @ref [`JxlDecoderReleaseInput`] 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).
+     */
+    #[doc(alias = "JXL_DEC_BASIC_INFO")]
     BasicInfo = 0x40,
+    #[doc(alias = "JXL_DEC_COLOR_ENCODING")]
     ColorEncoding = 0x100,
+    #[doc(alias = "JXL_DEC_PREVIEW_IMAGE")]
     PreviewImage = 0x200,
+    #[doc(alias = "JXL_DEC_FRAME")]
     Frame = 0x400,
+    #[doc(alias = "JXL_DEC_FULL_IMAGE")]
     FullImage = 0x1000,
+    #[doc(alias = "JXL_DEC_JPEG_RECONSTRUCTION")]
     JpegReconstruction = 0x2000,
+    #[doc(alias = "JXL_DEC_BOX")]
     Box = 0x4000,
+    #[doc(alias = "JXL_DEC_FRAME_PROGRESSION")]
     FrameProgression = 0x8000,
 }
 
@@ -119,6 +143,21 @@ extern "C" {
 
     pub fn JxlDecoderSkipCurrentFrame(dec: *mut JxlDecoder) -> JxlDecoderStatus;
 
+    /**
+     * Set the parallel runner for multithreading. May only be set before starting
+     * decoding.
+     *
+     * # Parameters
+     * - `dec`: decoder object
+     * - `parallel_runner`: function pointer to runner for multithreading. It may
+     *     be NULL to use the default, single-threaded, runner. A multithreaded
+     *     runner should be set to reach fast performance.
+     * - `parallel_runner_opaque`: opaque pointer for `parallel_runner`.
+     *
+     * # Returns
+     * [`JxlDecoderStatus::Success`]: if the runner was set,
+     * [`JxlDecoderStatus::Error`]otherwise (the previous runner remains set).
+     */
     pub fn JxlDecoderSetParallelRunner(
         dec: *mut JxlDecoder,
         parallel_runner: JxlParallelRunner,
@@ -127,28 +166,183 @@ extern "C" {
 
     pub fn JxlDecoderSizeHintBasicInfo(dec: *const JxlDecoder) -> usize;
 
+    /** Select for which informative events, i.e. [`JxlDecoderStatus::BasicInfo`], etc., the
+     * decoder should return with a status.
+     *
+     * It is not required to subscribe to any
+     * events, data can still be requested from the decoder as soon as it available.
+     * By default, the decoder is subscribed to no events (`events_wanted` == 0), and
+     * the decoder will then only return when it cannot continue because it needs
+     * more input data or more output buffer. This function may only be be called
+     * before using [`JxlDecoderProcessInput`].
+     *
+     * # Parameters
+     * - `dec`:  decoder object
+     * - `events_wanted`: bitfield of desired events.
+     *
+     * # Returns
+     * [`JxlDecoderStatus::Success`] if no error, [`JxlDecoderStatus::Error`] otherwise.
+     */
     pub fn JxlDecoderSubscribeEvents(
         dec: *mut JxlDecoder,
         events_wanted: c_int,
     ) -> JxlDecoderStatus;
 
+    /** Enables or disables preserving of as-in-bitstream pixeldata
+     * orientation.
+     *
+     * Some images are encoded with an Orientation tag
+     * indicating that the decoder must perform a rotation and/or
+     * mirroring to the encoded image data.
+     *
+     *  - If `skip_reorientation` is [`JxlBool::False`] (the default): the decoder
+     *    will apply the transformation from the orientation setting, hence
+     *    rendering the image according to its specified intent. When
+     *    producing a [`JxlBasicInfo`], the decoder will always set the
+     *    orientation field to [`JxlOrientation::Identity`] (matching the returned
+     *    pixel data) and also align xsize and ysize so that they correspond
+     *    to the width and the height of the returned pixel data.
+     *  - If `skip_reorientation` is [`JxlBool::True`]: the decoder will skip
+     *    applying the transformation from the orientation setting, returning
+     *    the image in the as-in-bitstream pixeldata orientation.
+     *    This may be faster to decode since the decoder doesn't have to apply the
+     *    transformation, but can cause wrong display of the image if the
+     *    orientation tag is not correctly taken into account by the user.
+     *
+     * By default, this option is disabled, and the returned pixel data is
+     * re-oriented according to the image's Orientation setting.
+     *
+     * This function must be called at the beginning, before decoding is performed.
+     *
+     * ## Note
+     * See [`JxlBasicInfo::orientation`] for the orientation field, and [`JxlOrientation`] for the
+     * possible values.
+     *
+     * # Parameters
+     * - `dec`: decoder object
+     * - `skip_reorientation`: [`JxlBool::True`] to enable, [`JxlBool::False`] to disable.
+     *
+     * # Returns
+     * [`JxlDecoderStatus::Success`] if no error, [`JxlDecoderStatus::Error`] otherwise.
+     */
     pub fn JxlDecoderSetKeepOrientation(
         dec: *mut JxlDecoder,
         keep_orientation: JxlBool,
     ) -> JxlDecoderStatus;
 
+    /**
+     * Enables or disables preserving of associated alpha channels.
+     *
+     * If `unpremul_alpha` is set to [`JxlBool::False`] then for associated alpha channel,
+     * the pixel data is returned with premultiplied colors. If it is set to [`JxlBool::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.
+     *
+     * By default, this option is disabled, and the returned pixel data "as is".
+     *
+     * This function must be called at the beginning, before decoding is performed.
+     *
+     * # Parameters
+     * - `dec`: decoder object
+     * - `unpremul_alpha`: [`JxlBool::True`] to enable, [`JxlBool::False`] to disable.
+     *
+     * # Returns
+     * [`JxlDecoderStatus::Success`] if no error, [`JxlDecoderStatus::Error`] otherwise.
+     */
     pub fn JxlDecoderSetUnpremultiplyAlpha(
         dec: *mut JxlDecoder,
         unpremul_alpha: JxlBool,
     ) -> JxlDecoderStatus;
 
+    /** Enables or disables rendering spot colors.
+     *
+     * By default, spot colors are rendered, which is OK for viewing the decoded image.
+     * If `render_spotcolors` is [`JxlBool::False`], then spot colors are not rendered,
+     * and have to be retrieved separately using [`JxlDecoderSetExtraChannelBuffer`]. This is
+     * useful for e.g. printing applications.
+     *
+     * # Parameters
+     * - `dec`: decoder object
+     * - `render_spotcolors`: [`JxlBool::True`] to enable (default), [`JxlBool::False`] to disable.
+     *
+     * # Returns
+     * [`JxlDecoderStatus::Success`] if no error, [`JxlDecoderStatus::Error`] otherwise.
+     */
     pub fn JxlDecoderSetRenderSpotcolors(
         dec: *mut JxlDecoder,
         render_spotcolors: JxlBool,
     ) -> JxlDecoderStatus;
 
+    /** Enables or disables coalescing of zero-duration frames.
+     *
+     * By default, frames are returned with coalescing enabled, i.e. all frames have the image
+     * dimensions, and are blended if needed. When coalescing is disabled, frames
+     * can have arbitrary dimensions, a non-zero crop offset, and blending is not
+     * performed. For display, coalescing is recommended. For loading a multi-layer
+     * still image as separate layers (as opposed to the merged image), coalescing
+     * has to be disabled.
+     *
+     * # Parameters
+     * - `dec`: decoder object
+     * - `coalescing`: [`JxlBool::True`] to enable coalescing (default), [`JxlBool::False`] to disable.
+     *
+     * # Returns
+     * [`JxlDecoderStatus::Success`] if no error, [`JxlDecoderStatus::Error`] otherwise.
+     */
     pub fn JxlDecoderSetCoalescing(dec: *mut JxlDecoder, coalescing: JxlBool) -> JxlDecoderStatus;
 
+    /**
+     * Decodes JPEG XL file using the available bytes.
+     *
+     * Requires input has been set with [`JxlDecoderSetInput`]. After [`JxlDecoderProcessInput`],
+     * input can optionally be released with [`JxlDecoderReleaseInput`] and then set
+     * again to next bytes in the stream. [`JxlDecoderReleaseInput`] returns how
+     * many bytes are not yet processed, before a next call to [`JxlDecoderProcessInput`]
+     * all unprocessed bytes must be provided again (the
+     * address need not match, but the contents must), and more bytes may be
+     * concatenated after the unprocessed bytes.
+     *
+     * The returned status indicates whether the decoder needs more input bytes, or
+     * more output buffer for a certain type of output data. No matter what the
+     * returned status is (other than [`JxlDecoderStatus::Error`]), new information, such
+     * as [`JxlDecoderGetBasicInfo`], may have become available after this call.
+     * When the return value is not [`JxlDecoderStatus::Error`] or [`JxlDecoderStatus::Success`], the
+     * decoding requires more [`JxlDecoderProcessInput`] calls to continue.
+     *
+     * # Parameters
+     * `dec`: decoder object
+     *
+     * # Returns
+     * * [`JxlDecoderStatus::Success`]: when decoding finished and all events handled.
+     *
+     *   If you still have more unprocessed input data anyway, then you can still
+     *   continue by using [`JxlDecoderSetInput`] and calling [`JxlDecoderProcessInput`] again,
+     *   similar to handling [`JxlDecoderStatus::NeedMoreInput`]. [`JxlDecoderStatus::Success`]
+     *   can occur instead of [`JxlDecoderStatus::NeedMoreInput`] when, for example, the input data ended right at
+     *   the boundary of a box of the container format, all essential codestream
+     *   boxes were already decoded, but extra metadata boxes are still present in
+     *   the next data. [`JxlDecoderProcessInput`] cannot return success if all
+     *   codestream boxes have not been seen yet.
+     *
+     * * [`JxlDecoderStatus::Error`]: when decoding failed, e.g. invalid codestream.
+     *
+     *   TODO(lode): document the input data mechanism
+     *
+     * * [`JxlDecoderStatus::NeedMoreInput`]: when more input data is necessary.
+     *
+     * * [`JxlDecoderStatus::BasicInfo`]: when basic info such as image dimensions is
+     *     available and this informative event is subscribed to.
+     *
+     * * [`JxlDecoderStatus::ColorEncoding`]: when color profile information is
+     *     available and this informative event is subscribed to.
+     *
+     * * [`JxlDecoderStatus::PreviewImage`]: when preview pixel information is
+     *     available and output in the preview buffer.
+     *
+     * * [`JxlDecoderStatus::FullImage`]: when all pixel information at highest detail
+     *     is available and has been output in the pixel buffer.
+     */
     pub fn JxlDecoderProcessInput(dec: *mut JxlDecoder) -> JxlDecoderStatus;
 
     pub fn JxlDecoderSetInput(