Function JxlEncoderAddBox 

pub unsafe extern "C-unwind" fn JxlEncoderAddBox(
    enc: *mut JxlEncoder,
    box_type: *const JxlBoxType,
    contents: *const u8,
    size: usize,
    compress_box: JxlBool,
) -> JxlEncoderStatus

Adds a metadata box to the file format. JxlEncoderProcessOutput must be used to effectively write the box to the output. JxlEncoderUseBoxes must be enabled before using this function.

Boxes allow inserting application-specific data and metadata (Exif, XML/XMP, JUMBF and user defined boxes).

The box format follows ISO BMFF and shares features and box types with other image and video formats, including the Exif, XML and JUMBF boxes. The box format for JPEG XL is specified in ISO/IEC 18181-2.

Boxes in general don’t contain other boxes inside, except a JUMBF superbox. Boxes follow each other sequentially and are byte-aligned. If the container format is used, the JXL stream consists of concatenated boxes. It is also possible to use a direct codestream without boxes, but in that case metadata cannot be added.

Each box generally has the following byte structure in the file:

• 4 bytes: box size including box header (Big endian. If set to 0, an 8-byte 64-bit size follows instead).
• 4 bytes: type, e.g. “JXL “ for the signature box, “jxlc” for a codestream box.
• N bytes: box contents.

Only the box contents are provided to the contents argument of this function, the encoder encodes the size header itself. Most boxes are written automatically by the encoder as needed (“JXL “, “ftyp”, “jxll”, “jxlc”, “jxlp”, “jxli”, “jbrd”), and this function only needs to be called to add optional metadata when encoding from pixels (using JxlEncoderAddImageFrame). When recompressing JPEG files (using JxlEncoderAddJPEGFrame), if the input JPEG contains EXIF, XMP or JUMBF metadata, the corresponding boxes are already added automatically.

Box types are given by 4 characters. The following boxes can be added with this function:

• “Exif”: a box with EXIF metadata, can be added by libjxl users, or is automatically added when needed for JPEG reconstruction. The contents of this box must be prepended by a 4-byte tiff header offset, which may be 4 zero bytes in case the tiff header follows immediately. The EXIF metadata must be in sync with what is encoded in the JPEG XL codestream, specifically the image orientation. While this is not recommended in practice, in case of conflicting metadata, the JPEG XL codestream takes precedence.
• “xml “: a box with XML data, in particular XMP metadata, can be added by libjxl users, or is automatically added when needed for JPEG reconstruction
• “jumb”: a JUMBF superbox, which can contain boxes with different types of metadata inside. This box type can be added by the encoder transparently, and other libraries to create and handle JUMBF content exist.
• Application-specific boxes. Their typename should not begin with “jxl” or “JXL” or conflict with other existing typenames, and they should be registered with MP4RA (mp4ra.org).

These boxes can be stored uncompressed or Brotli-compressed (using a “brob” box), depending on the compress_box parameter.

Parameters

• enc: encoder object.
• box_type: the box type, e.g. “Exif” for EXIF metadata, “xml “ for XMP or IPTC metadata, “jumb” for JUMBF metadata.
• contents: the full contents of the box, for example EXIF data. ISO BMFF box header must not be included, only the contents. Owned by the caller and its contents are copied internally.
• size: size of the box contents.
• compress_box: Whether to compress this box as a “brob” box. Requires Brotli support.

Returns

• JxlEncoderStatus::Success on success.
• JxlEncoderStatus::Error on error, such as when using this function without JxlEncoderUseContainer, or adding a box type that would result in an invalid file format.