Function libjxl_sys::JxlDecoderGetBoxType

source · [−]
pub unsafe extern "C" fn JxlDecoderGetBoxType(
    dec: *mut JxlDecoder, 
    type_: *mut c_char, 
    decompressed: c_int
) -> JxlDecoderStatus
Expand description

Outputs the type of the current box, after a @ref JXL_DEC_BOX event occured, as 4 characters without null termination character. In case of a compressed “brob” box, this will return “brob” if the decompressed argument is JXL_FALSE, or the underlying box type if the decompressed argument is JXL_TRUE.

The following box types are currently described in ISO/IEC 18181-2:

  • “Exif”: a box with EXIF metadata. Starts with a 4-byte tiff header offset (big-endian uint32) that indicates the start of the actual EXIF data (which starts with a tiff header). Usually the offset will be zero and the EXIF data starts immediately after the offset field. The Exif orientation should be ignored by applications; the JPEG XL codestream orientation takes precedence and libjxl will by default apply the correct orientation automatically (see @ref JxlDecoderSetKeepOrientation).
  • “xml “: a box with XML data, in particular XMP metadata.
  • “jumb”: a JUMBF superbox (JPEG Universal Metadata Box Format, ISO/IEC 19566-5).
  • “JXL “: mandatory signature box, must come first, 12 bytes long including the box header
  • “ftyp”: a second mandatory signature box, must come second, 20 bytes long including the box header
  • “jxll”: a JXL level box. This indicates if the codestream is level 5 or level 10 compatible. If not present, it is level 5. Level 10 allows more features such as very high image resolution and bit-depths above 16 bits per channel. Added automatically by the encoder when JxlEncoderSetCodestreamLevel is used
  • “jxlc”: a box with the image codestream, in case the codestream is not split across multiple boxes. The codestream contains the JPEG XL image itself, including the basic info such as image dimensions, ICC color profile, and all the pixel data of all the image frames.
  • “jxlp”: a codestream box in case it is split across multiple boxes. The contents are the same as in case of a jxlc box, when concatenated.
  • “brob”: a Brotli-compressed box, which otherwise represents an existing type of box such as Exif or “xml “. When @ref JxlDecoderSetDecompressBoxes is set to JXL_TRUE, these boxes will be transparently decompressed by the decoder.
  • “jxli”: frame index box, can list the keyframes in case of a JPEG XL animation allowing the decoder to jump to individual frames more efficiently.
  • “jbrd”: JPEG reconstruction box, contains the information required to byte-for-byte losslessly recontruct a JPEG-1 image. The JPEG DCT coefficients (pixel content) themselves as well as the ICC profile are encoded in the JXL codestream (jxlc or jxlp) itself. EXIF, XMP and JUMBF metadata is encoded in the corresponding boxes. The jbrd box itself contains information such as the remaining app markers of the JPEG-1 file and everything else required to fit the information together into the exact original JPEG file.

Other application-specific boxes can exist. Their typename should not begin with “jxl” or “JXL” or conflict with other existing typenames.

The signature, jxl* and jbrd boxes are processed by the decoder and would typically be ignored by applications. The typical way to use this function is to check if an encountered box contains metadata that the application is interested in (e.g. EXIF or XMP metadata), in order to conditionally set a box buffer.

@param dec decoder object @param type buffer to copy the type into @param decompressed which box type to get: JXL_FALSE to get the raw box type, which can be “brob”, JXL_TRUE, get the underlying box type. @return @ref JXL_DEC_SUCCESS if the value is available, @ref JXL_DEC_ERROR if not, for example the JXL file does not use the container format.