Loading...
Searching...
No Matches
JPEG XL Decoder API
JPEG XL library (libjxl)
Collaboration diagram for JPEG XL Decoder API:

## Files

file | decode.h
| Decoding API for JPEG XL.

## Typedefs

typedef struct JxlDecoderStruct | JxlDecoder
typedef void(* | JxlImageOutCallback) (void *opaque, size_t x, size_t y, size_t num_pixels, const void *pixels)
typedef void *(* | JxlImageOutInitCallback) (void *init_opaque, size_t num_threads, size_t num_pixels_per_thread)
typedef void(* | JxlImageOutRunCallback) (void *run_opaque, size_t thread_id, size_t x, size_t y, size_t num_pixels, const void *pixels)
typedef void(* | JxlImageOutDestroyCallback) (void *run_opaque)

## Enumerations

enum | JxlSignature { JXL_SIG_NOT_ENOUGH_BYTES = 0 , JXL_SIG_INVALID = 1 , JXL_SIG_CODESTREAM = 2 , JXL_SIG_CONTAINER = 3 }

enum

JxlDecoderStatus {
JXL_DEC_SUCCESS = 0 , JXL_DEC_ERROR = 1 , JXL_DEC_NEED_MORE_INPUT = 2 , JXL_DEC_NEED_PREVIEW_OUT_BUFFER = 3 ,
JXL_DEC_NEED_IMAGE_OUT_BUFFER = 5 , JXL_DEC_JPEG_NEED_MORE_OUTPUT = 6 , JXL_DEC_BOX_NEED_MORE_OUTPUT = 7 , JXL_DEC_BASIC_INFO = 0x40 ,
JXL_DEC_COLOR_ENCODING = 0x100 , JXL_DEC_PREVIEW_IMAGE = 0x200 , JXL_DEC_FRAME = 0x400 , JXL_DEC_FULL_IMAGE = 0x1000 ,
JXL_DEC_JPEG_RECONSTRUCTION = 0x2000 , JXL_DEC_BOX = 0x4000 , JXL_DEC_FRAME_PROGRESSION = 0x8000 , JXL_DEC_BOX_COMPLETE = 0x10000
}

enum | JxlProgressiveDetail { kFrames = 0 , kDC = 1 , kLastPasses = 2 , kPasses = 3 , kDCProgressive = 4 , kDCGroups = 5 , kGroups = 6 }
enum | JxlColorProfileTarget { JXL_COLOR_PROFILE_TARGET_ORIGINAL = 0 , JXL_COLOR_PROFILE_TARGET_DATA = 1 }

## Functions

JXL_EXPORT uint32_t | JxlDecoderVersion (void)
JXL_EXPORT JxlSignature | JxlSignatureCheck (const uint8_t *buf, size_t len)
JXL_EXPORT JxlDecoder * | JxlDecoderCreate (const JxlMemoryManager *memory_manager)
JXL_EXPORT void | JxlDecoderReset (JxlDecoder *dec)
JXL_EXPORT void | JxlDecoderDestroy (JxlDecoder *dec)
JXL_EXPORT void | JxlDecoderRewind (JxlDecoder *dec)
JXL_EXPORT void | JxlDecoderSkipFrames (JxlDecoder *dec, size_t amount)
JXL_EXPORT JxlDecoderStatus | JxlDecoderSkipCurrentFrame (JxlDecoder *dec)
JXL_EXPORT JxlDecoderStatus | JxlDecoderSetParallelRunner (JxlDecoder *dec, JxlParallelRunner parallel_runner, void *parallel_runner_opaque)
JXL_EXPORT size_t | JxlDecoderSizeHintBasicInfo (const JxlDecoder *dec)
JXL_EXPORT JxlDecoderStatus | JxlDecoderSubscribeEvents (JxlDecoder *dec, int events_wanted)
JXL_EXPORT JxlDecoderStatus | JxlDecoderSetKeepOrientation (JxlDecoder *dec, JXL_BOOL skip_reorientation)
JXL_EXPORT JxlDecoderStatus | JxlDecoderSetUnpremultiplyAlpha (JxlDecoder *dec, JXL_BOOL unpremul_alpha)
JXL_EXPORT JxlDecoderStatus | JxlDecoderSetRenderSpotcolors (JxlDecoder *dec, JXL_BOOL render_spotcolors)
JXL_EXPORT JxlDecoderStatus | JxlDecoderSetCoalescing (JxlDecoder *dec, JXL_BOOL coalescing)
JXL_EXPORT JxlDecoderStatus | JxlDecoderProcessInput (JxlDecoder *dec)
JXL_EXPORT JxlDecoderStatus | JxlDecoderSetInput (JxlDecoder *dec, const uint8_t *data, size_t size)
JXL_EXPORT size_t | JxlDecoderReleaseInput (JxlDecoder *dec)
JXL_EXPORT void | JxlDecoderCloseInput (JxlDecoder *dec)
JXL_EXPORT JxlDecoderStatus | JxlDecoderGetBasicInfo (const JxlDecoder *dec, JxlBasicInfo *info)
JXL_EXPORT JxlDecoderStatus | JxlDecoderGetExtraChannelInfo (const JxlDecoder *dec, size_t index, JxlExtraChannelInfo *info)
JXL_EXPORT JxlDecoderStatus | JxlDecoderGetExtraChannelName (const JxlDecoder *dec, size_t index, char *name, size_t size)
JXL_EXPORT JxlDecoderStatus | JxlDecoderGetColorAsEncodedProfile (const JxlDecoder *dec, JxlColorProfileTarget target, JxlColorEncoding *color_encoding)
JXL_EXPORT JxlDecoderStatus | JxlDecoderGetICCProfileSize (const JxlDecoder *dec, JxlColorProfileTarget target, size_t *size)
JXL_EXPORT JxlDecoderStatus | JxlDecoderGetColorAsICCProfile (const JxlDecoder *dec, JxlColorProfileTarget target, uint8_t *icc_profile, size_t size)
JXL_EXPORT JxlDecoderStatus | JxlDecoderSetPreferredColorProfile (JxlDecoder *dec, const JxlColorEncoding *color_encoding)
JXL_EXPORT JxlDecoderStatus | JxlDecoderSetDesiredIntensityTarget (JxlDecoder *dec, float desired_intensity_target)
JXL_EXPORT JxlDecoderStatus | JxlDecoderSetOutputColorProfile (JxlDecoder *dec, const JxlColorEncoding *color_encoding, const uint8_t *icc_data, size_t icc_size)
JXL_EXPORT JxlDecoderStatus | JxlDecoderSetCms (JxlDecoder *dec, JxlCmsInterface cms)
JXL_EXPORT JxlDecoderStatus | JxlDecoderPreviewOutBufferSize (const JxlDecoder *dec, const JxlPixelFormat *format, size_t *size)
JXL_EXPORT JxlDecoderStatus | JxlDecoderSetPreviewOutBuffer (JxlDecoder *dec, const JxlPixelFormat *format, void *buffer, size_t size)
JXL_EXPORT JxlDecoderStatus | JxlDecoderGetFrameHeader (const JxlDecoder *dec, JxlFrameHeader *header)
JXL_EXPORT JxlDecoderStatus | JxlDecoderGetFrameName (const JxlDecoder *dec, char *name, size_t size)
JXL_EXPORT JxlDecoderStatus | JxlDecoderGetExtraChannelBlendInfo (const JxlDecoder *dec, size_t index, JxlBlendInfo *blend_info)
JXL_EXPORT JxlDecoderStatus | JxlDecoderImageOutBufferSize (const JxlDecoder *dec, const JxlPixelFormat *format, size_t *size)
JXL_EXPORT JxlDecoderStatus | JxlDecoderSetImageOutBuffer (JxlDecoder *dec, const JxlPixelFormat *format, void *buffer, size_t size)
JXL_EXPORT JxlDecoderStatus | JxlDecoderSetImageOutCallback (JxlDecoder *dec, const JxlPixelFormat *format, JxlImageOutCallback callback, void *opaque)
JXL_EXPORT JxlDecoderStatus | JxlDecoderSetMultithreadedImageOutCallback (JxlDecoder *dec, const JxlPixelFormat *format, JxlImageOutInitCallback init_callback, JxlImageOutRunCallback run_callback, JxlImageOutDestroyCallback destroy_callback, void *init_opaque)
JXL_EXPORT JxlDecoderStatus | JxlDecoderExtraChannelBufferSize (const JxlDecoder *dec, const JxlPixelFormat *format, size_t *size, uint32_t index)
JXL_EXPORT JxlDecoderStatus | JxlDecoderSetExtraChannelBuffer (JxlDecoder *dec, const JxlPixelFormat *format, void *buffer, size_t size, uint32_t index)
JXL_EXPORT JxlDecoderStatus | JxlDecoderSetJPEGBuffer (JxlDecoder *dec, uint8_t *data, size_t size)
JXL_EXPORT size_t | JxlDecoderReleaseJPEGBuffer (JxlDecoder *dec)
JXL_EXPORT JxlDecoderStatus | JxlDecoderSetBoxBuffer (JxlDecoder *dec, uint8_t *data, size_t size)
JXL_EXPORT size_t | JxlDecoderReleaseBoxBuffer (JxlDecoder *dec)
JXL_EXPORT JxlDecoderStatus | JxlDecoderSetDecompressBoxes (JxlDecoder *dec, JXL_BOOL decompress)
JXL_EXPORT JxlDecoderStatus | JxlDecoderGetBoxType (JxlDecoder *dec, JxlBoxType type, JXL_BOOL decompressed)
JXL_EXPORT JxlDecoderStatus | JxlDecoderGetBoxSizeRaw (const JxlDecoder *dec, uint64_t *size)
JXL_EXPORT JxlDecoderStatus | JxlDecoderGetBoxSizeContents (const JxlDecoder *dec, uint64_t *size)
JXL_EXPORT JxlDecoderStatus | JxlDecoderSetProgressiveDetail (JxlDecoder *dec, JxlProgressiveDetail detail)
JXL_EXPORT size_t | JxlDecoderGetIntendedDownsamplingRatio (JxlDecoder *dec)
JXL_EXPORT JxlDecoderStatus | JxlDecoderFlushImage (JxlDecoder *dec)
JXL_EXPORT JxlDecoderStatus | JxlDecoderSetImageOutBitDepth (JxlDecoder *dec, const JxlBitDepth *bit_depth)

## Detailed Description

## Typedef Documentation

## JxlDecoder

typedef struct JxlDecoderStruct JxlDecoder

Opaque structure that holds the JPEG XL decoder.

Allocated and initialized with JxlDecoderCreate(). Cleaned up and deallocated with JxlDecoderDestroy().

## JxlImageOutCallback

typedef void(* JxlImageOutCallback) (void *opaque, size_t x, size_t y, size_t num_pixels, const void *pixels)

Function type for JxlDecoderSetImageOutCallback.

The callback may be called simultaneously by different threads when using a threaded parallel runner, on different pixels.

Parameters

  opaque | optional user data, as given to JxlDecoderSetImageOutCallback.
  x | horizontal position of leftmost pixel of the pixel data.
  y | vertical position of the pixel data.
  num_pixels | amount of pixels included in the pixel data, horizontally. This is not the same as xsize of the full image, it may be smaller.
  pixels | pixel data as a horizontal stripe, in the format passed to JxlDecoderSetImageOutCallback. The memory is not owned by the user, and is only valid during the time the callback is running.

## JxlImageOutDestroyCallback

typedef void(* JxlImageOutDestroyCallback) (void *run_opaque)

Destruction callback for JxlDecoderSetMultithreadedImageOutCallback, called after all invocations of the `run` callback to perform any appropriate clean-up of the `run_opaque` data returned by `init`.

Parameters

  run_opaque | user data returned by the `init` callback.

## JxlImageOutInitCallback

typedef void *(* JxlImageOutInitCallback) (void *init_opaque, size_t num_threads, size_t num_pixels_per_thread)

Initialization callback for JxlDecoderSetMultithreadedImageOutCallback.

Parameters

  init_opaque | optional user data, as given to JxlDecoderSetMultithreadedImageOutCallback.
  num_threads | maximum number of threads that will call the `run` callback concurrently.
  num_pixels_per_thread | maximum number of pixels that will be passed in one call to `run`.

Returns
  a pointer to data that will be passed to the `run` callback, or `NULL` if initialization failed.

## JxlImageOutRunCallback

typedef void(* JxlImageOutRunCallback) (void *run_opaque, size_t thread_id, size_t x, size_t y, size_t num_pixels, const void *pixels)

Worker callback for JxlDecoderSetMultithreadedImageOutCallback.

Parameters

  run_opaque | user data returned by the `init` callback.
  thread_id | number in [0, num_threads) identifying the thread of the current invocation of the callback.
  x | horizontal position of the first (leftmost) pixel of the pixel data.
  y | vertical position of the pixel data.
  num_pixels | number of pixels in the pixel data. May be less than the full `xsize` of the image, and will be at most equal to the `num_pixels_per_thread` that was passed to `init`.
  pixels | pixel data as a horizontal stripe, in the format passed to JxlDecoderSetMultithreadedImageOutCallback. The data pointed to remains owned by the caller and is only guaranteed to outlive the current callback invocation.

## Enumeration Type Documentation

## JxlColorProfileTarget

enum JxlColorProfileTarget

Defines which color profile to get: the profile from the codestream metadata header, which represents the color profile of the original image, or the color profile from the pixel data produced by the decoder. Both are the same if the JxlBasicInfo has uses_original_profile set.

Enumerator
JXL_COLOR_PROFILE_TARGET_ORIGINAL | Get the color profile of the original image from the metadata.
JXL_COLOR_PROFILE_TARGET_DATA | Get the color profile of the pixel data the decoder outputs.

## JxlDecoderStatus

enum JxlDecoderStatus

Return value for JxlDecoderProcessInput. The values from JXL_DEC_BASIC_INFO onwards are optional informative events that can be subscribed to, they are never returned if they have not been registered with JxlDecoderSubscribeEvents.

Enumerator

JXL_DEC_SUCCESS

Function call finished successfully, or decoding is finished and there is nothing more to be done.

Note that JxlDecoderProcessInput will return JXL_DEC_SUCCESS if all events that were registered with JxlDecoderSubscribeEvents were processed, even before the end of the JPEG XL codestream.

In this case, the return value JxlDecoderReleaseInput will be the same as it was at the last signaled event. E.g. if JXL_DEC_FULL_IMAGE 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.

JXL_DEC_ERROR | An error occurred, for example invalid input file or out of memory. TODO(lode): add function to get error information from decoder.

JXL_DEC_NEED_MORE_INPUT

The decoder needs more input bytes to continue. Before the next JxlDecoderProcessInput call, more input data must be set, by calling JxlDecoderReleaseInput (if input was set previously) and then calling JxlDecoderSetInput. 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 must be concatenated after the unprocessed bytes. In most cases, JxlDecoderReleaseInput 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.

JXL_DEC_NEED_PREVIEW_OUT_BUFFER

The decoder is able to decode a preview image and requests setting a preview output buffer using JxlDecoderSetPreviewOutBuffer. This occurs if JXL_DEC_PREVIEW_IMAGE 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. In this case, JxlDecoderReleaseInput will return all bytes from the end of the frame header (including ToC) of the preview frame as unprocessed.

JXL_DEC_NEED_IMAGE_OUT_BUFFER

The decoder requests an output buffer to store the full resolution image, which can be set with JxlDecoderSetImageOutBuffer or with JxlDecoderSetImageOutCallback. This event re-occurs for new frames if there are multiple animation frames and requires setting an output again. In this case, JxlDecoderReleaseInput will return all bytes from the end of the frame header (including ToC) as unprocessed.

JXL_DEC_JPEG_NEED_MORE_OUTPUT | The JPEG reconstruction buffer is too small for reconstructed JPEG codestream to fit. JxlDecoderSetJPEGBuffer must be called again to make room for remaining bytes. This event may occur multiple times after JXL_DEC_JPEG_RECONSTRUCTION.
JXL_DEC_BOX_NEED_MORE_OUTPUT | The box contents output buffer is too small. JxlDecoderSetBoxBuffer must be called again to make room for remaining bytes. This event may occur multiple times after JXL_DEC_BOX.
JXL_DEC_BASIC_INFO | Informative event by JxlDecoderProcessInput: Basic information such as image dimensions and extra channels. This event occurs max once per image. In this case, 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).
JXL_DEC_COLOR_ENCODING | Informative event by JxlDecoderProcessInput: Color encoding or ICC profile from the codestream header. This event occurs max once per image and always later than JXL_DEC_BASIC_INFO and earlier than any pixel data. In this case, JxlDecoderReleaseInput will return all bytes from the end of the image header (which is the start of the first frame) as unprocessed.

JXL_DEC_PREVIEW_IMAGE

Informative event by 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 JXL_DEC_COLOR_ENCODING and before JXL_DEC_FRAME. In this case, JxlDecoderReleaseInput will return all bytes from the end of the preview frame as unprocessed.

JXL_DEC_FRAME

Informative event by JxlDecoderProcessInput: Beginning of a frame. JxlDecoderGetFrameHeader can be used at this point. A note on frames: a JPEG XL image can have internal frames that are not intended to be displayed (e.g. used for compositing a final frame), but this only returns displayed frames, unless JxlDecoderSetCoalescing was set to JXL_FALSE: in that case, the individual layers are returned, without blending. Note that even when coalescing is disabled, only frames of type kRegularFrame are returned; frames of type kReferenceOnly and kLfFrame are always for internal purposes only and cannot be accessed. A displayed frame either has an animation duration or is the only or last frame in the image. This event occurs max once per displayed frame, always later than JXL_DEC_COLOR_ENCODING, and always earlier than any pixel data. While 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. In this case, JxlDecoderReleaseInput will return all bytes from the end of the frame header (including ToC) as unprocessed.

JXL_DEC_FULL_IMAGE

Informative event by JxlDecoderProcessInput: full frame (or layer, in case coalescing is disabled) is decoded. JxlDecoderSetImageOutBuffer must be used after 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. In this case, JxlDecoderReleaseInput will return all bytes from the end of the frame (or if JXL_DEC_JPEG_RECONSTRUCTION is subscribed to, from the end of the last box that is needed for jpeg reconstruction) as unprocessed.

JXL_DEC_JPEG_RECONSTRUCTION

Informative event by JxlDecoderProcessInput: JPEG reconstruction data decoded. JxlDecoderSetJPEGBuffer may be used to set a JPEG reconstruction buffer after getting the JPEG reconstruction data. If a JPEG reconstruction buffer is set a byte stream identical to the JPEG codestream used to encode the 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 JXL_DEC_FULL_IMAGE. In this case, JxlDecoderReleaseInput will return all bytes from the end of the jbrd box as unprocessed.

JXL_DEC_BOX

Informative event by JxlDecoderProcessInput: The header of a box of the container format (BMFF) is decoded. The following API functions related to boxes can be used after this event:

- JxlDecoderSetBoxBuffer and JxlDecoderReleaseBoxBuffer: set and release a buffer to get the box data.
- JxlDecoderGetBoxType get the 4-character box typename.
- JxlDecoderGetBoxSizeRaw get the size of the box as it appears in the container file, not decompressed.
- JxlDecoderSetDecompressBoxes to configure whether to get the box data decompressed, or possibly compressed.

Boxes can be compressed. This is so when their box type is "brob". In that case, they have an underlying decompressed box type and decompressed data. JxlDecoderSetDecompressBoxes allows configuring which data to get. Decompressing requires Brotli. JxlDecoderGetBoxType has a flag to get the compressed box type, which can be "brob", or the decompressed box type. If a box is not compressed (its compressed type is not "brob"), then the output decompressed box type and data is independent of what setting is configured.

The buffer set with JxlDecoderSetBoxBuffer must be set again for each next box to be obtained, or can be left unset to skip outputting this box. The output buffer contains the full box data when the JXL_DEC_BOX_COMPLETE (if subscribed to) or subsequent JXL_DEC_SUCCESS or JXL_DEC_BOX event occurs. JXL_DEC_BOX occurs for all boxes, including non-metadata boxes such as the signature box or codestream boxes. To check whether the box is a metadata type for respectively EXIF, XMP or JUMBF, use JxlDecoderGetBoxType and check for types "Exif", "xml " and "jumb" respectively.

In this case, JxlDecoderReleaseInput will return all bytes from the start of the box header as unprocessed.

JXL_DEC_FRAME_PROGRESSION

Informative event by JxlDecoderProcessInput: a progressive step in decoding the frame is reached. When calling JxlDecoderFlushImage at this point, the flushed image will correspond exactly to this point in decoding, and not yet contain partial results (such as partially more fine detail) of a next step. By default, this event will trigger maximum once per frame, when a 8x8th resolution (DC) image is ready (the image data is still returned at full resolution, giving upscaled DC). Use JxlDecoderSetProgressiveDetail to configure more fine-grainedness. The event is not guaranteed to trigger, not all images have progressive steps or DC encoded. In this case, JxlDecoderReleaseInput will return all bytes from the end of the section that was needed to produce this progressive event as unprocessed.

JXL_DEC_BOX_COMPLETE | The box being decoded is now complete. This is only emitted if a buffer was set for the box.

## JxlProgressiveDetail

enum JxlProgressiveDetail

Types of progressive detail. Setting a progressive detail with value N implies all progressive details with smaller or equal value. Currently only the following level of progressive detail is implemented:

- kDC (which implies kFrames)
- kLastPasses (which implies kDC and kFrames)
- kPasses (which implies kLastPasses, kDC and kFrames)

Enumerator
kFrames | after completed kRegularFrames
kDC | after completed DC (1:8)
kLastPasses | after completed AC passes that are the last pass for their resolution target.
kPasses | after completed AC passes that are not the last pass for their resolution target.
kDCProgressive | during DC frame when lower resolution are completed (1:32, 1:16)
kDCGroups | after completed groups
kGroups | after completed groups

## JxlSignature

enum JxlSignature

The result of JxlSignatureCheck.

Enumerator
JXL_SIG_NOT_ENOUGH_BYTES | Not enough bytes were passed to determine if a valid signature was found.
JXL_SIG_INVALID | No valid JPEG XL header was found.
JXL_SIG_CODESTREAM | A valid JPEG XL codestream signature was found, that is a JPEG XL image without container.
JXL_SIG_CONTAINER | A valid container signature was found, that is a JPEG XL image embedded in a box format container.

## Function Documentation

## JxlDecoderCloseInput()

JXL_EXPORT void JxlDecoderCloseInput | ( | JxlDecoder * | dec | ) |

Marks the input as finished, indicates that no more JxlDecoderSetInput will be called. This function allows the decoder to determine correctly if it should return success, need more input or error in certain cases. For backwards compatibility with a previous version of the API, using this function is optional when not using the JXL_DEC_BOX event (the decoder is able to determine the end of the image frames without marking the end), but using this function is required when using JXL_DEC_BOX for getting metadata box contents. This function does not replace JxlDecoderReleaseInput, that function should still be called if its return value is needed.

JxlDecoderCloseInput should be called as soon as all known input bytes are set (e.g. at the beginning when not streaming but setting all input at once), before the final JxlDecoderProcessInput calls.

Parameters

  dec | decoder object

## JxlDecoderCreate()

JXL_EXPORT JxlDecoder * JxlDecoderCreate | ( | const JxlMemoryManager * | memory_manager | ) |

Creates an instance of JxlDecoder and initializes it.

`memory_manager` will be used for all the library dynamic allocations made from this instance. The parameter may be NULL, in which case the default allocator will be used. See jxl/memory_manager.h for details.

Parameters

  memory_manager | custom allocator function. It may be NULL. The memory manager will be copied internally.

Returns
  `NULL` if the instance can not be allocated or initialized
  pointer to initialized JxlDecoder otherwise

## JxlDecoderDestroy()

JXL_EXPORT void JxlDecoderDestroy | ( | JxlDecoder * | dec | ) |

Deinitializes and frees JxlDecoder instance.

Parameters

  dec | instance to be cleaned up and deallocated.

## JxlDecoderExtraChannelBufferSize()

JXL_EXPORT JxlDecoderStatus JxlDecoderExtraChannelBufferSize | ( | const JxlDecoder * | dec,
|  | const JxlPixelFormat * | format,
|  | size_t * | size,
|  | uint32_t | index )

Returns the minimum size in bytes of an extra channel pixel buffer for the given format. This is the buffer for JxlDecoderSetExtraChannelBuffer. Requires the basic image information is available in the decoder.

Parameters

  dec | decoder object
  format | format of the pixels. The num_channels value is ignored and is always treated to be 1.
  size | output value, buffer size in bytes
  index | which extra channel to get, matching the index used in JxlDecoderGetExtraChannelInfo. Must be smaller than num_extra_channels in the associated JxlBasicInfo.

Returns
  JXL_DEC_SUCCESS on success, JXL_DEC_ERROR on error, such as information not available yet or invalid index.

## JxlDecoderFlushImage()

JXL_EXPORT JxlDecoderStatus JxlDecoderFlushImage | ( | JxlDecoder * | dec | ) |

Outputs progressive step towards the decoded image so far when only partial input was received. If the flush was successful, the buffer set with JxlDecoderSetImageOutBuffer will contain partial image data.

Can be called when JxlDecoderProcessInput returns JXL_DEC_NEED_MORE_INPUT, after the JXL_DEC_FRAME event already occurred and before the JXL_DEC_FULL_IMAGE event occurred for a frame.

Parameters

  dec | decoder object

Returns
  JXL_DEC_SUCCESS if image data was flushed to the output buffer, or JXL_DEC_ERROR when no flush was done, e.g. if not enough image data was available yet even for flush, or no output buffer was set yet. This error is not fatal, it only indicates no flushed image is available right now. Regular decoding can still be performed.

## JxlDecoderGetBasicInfo()

JXL_EXPORT JxlDecoderStatus JxlDecoderGetBasicInfo | ( | const JxlDecoder * | dec,
|  | JxlBasicInfo * | info )

Outputs the basic image information, such as image dimensions, bit depth and all other JxlBasicInfo fields, if available.

Parameters

  dec | decoder object
  info | struct to copy the information into, or NULL to only check whether the information is available through the return value.

Returns
  JXL_DEC_SUCCESS if the value is available, JXL_DEC_NEED_MORE_INPUT if not yet available, JXL_DEC_ERROR in case of other error conditions.

## JxlDecoderGetBoxSizeContents()

JXL_EXPORT JxlDecoderStatus JxlDecoderGetBoxSizeContents | ( | const JxlDecoder * | dec,
|  | uint64_t * | size )

Returns the size of the contents of a box, after the JXL_DEC_BOX event. This does not include any of the headers of the box. For compressed "brob" boxes, this is the size of the compressed content. Even when JxlDecoderSetDecompressBoxes is enabled, the return value of function does not change, and the decompressed size is not known before it has already been decompressed and output.

Parameters

  dec | decoder object
  size | size of the payload of the box in bytes

Returns
  JXL_DEC_ERROR if no box size is available, JXL_DEC_SUCCESS otherwise.

## JxlDecoderGetBoxSizeRaw()

JXL_EXPORT JxlDecoderStatus JxlDecoderGetBoxSizeRaw | ( | const JxlDecoder * | dec,
|  | uint64_t * | size )

Returns the size of a box as it appears in the container file, after the JXL_DEC_BOX event. This includes all the box headers.

Parameters

  dec | decoder object
  size | raw size of the box in bytes

Returns
  JXL_DEC_ERROR if no box size is available, JXL_DEC_SUCCESS otherwise.

## JxlDecoderGetBoxType()

JXL_EXPORT JxlDecoderStatus JxlDecoderGetBoxType | ( | JxlDecoder * | dec,
|  | JxlBoxType | type,
|  | JXL_BOOL | decompressed )

Outputs the type of the current box, after a JXL_DEC_BOX event occurred, 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 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 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 reconstruct 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.

Parameters

  dec | decoder object
  type | buffer to copy the type into
  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.

Returns
  JXL_DEC_SUCCESS if the value is available, JXL_DEC_ERROR if not, for example the JPEG XL file does not use the container format.

## JxlDecoderGetColorAsEncodedProfile()

JXL_EXPORT JxlDecoderStatus JxlDecoderGetColorAsEncodedProfile | ( | const JxlDecoder * | dec,
|  | JxlColorProfileTarget | target,
|  | JxlColorEncoding * | color_encoding )

Outputs the color profile as JPEG XL encoded structured data, if available. This is an alternative to an ICC Profile, which can represent a more limited amount of color spaces, but represents them exactly through enum values.

It is often possible to use JxlDecoderGetColorAsICCProfile as an alternative anyway. The following scenarios are possible:

- The JPEG XL image has an attached ICC Profile, in that case, the encoded structured data is not available and this function will return an error status. JxlDecoderGetColorAsICCProfile should be called instead.
- The JPEG XL image has an encoded structured color profile, and it represents an RGB or grayscale color space. This function will return it. You can still use JxlDecoderGetColorAsICCProfile as well as an alternative if desired, though depending on which RGB color space is represented, the ICC profile may be a close approximation. It is also not always feasible to deduce from an ICC profile which named color space it exactly represents, if any, as it can represent any arbitrary space. HDR color spaces such as those using PQ and HLG are also potentially problematic, in that: while ICC profiles can encode a transfer function that happens to approximate those of PQ and HLG (HLG for only one given system gamma at a time, and necessitating a 3D LUT if gamma is to be different from 1), they cannot (before ICCv4.4) semantically signal that this is the color space that they represent. Therefore, they will typically not actually be interpreted as representing an HDR color space. This is especially detrimental to PQ which will then be interpreted as if the maximum signal value represented SDR white instead of 10000 cd/m^2, meaning that the image will be displayed two orders of magnitude (5-7 EV) too dim.
- The JPEG XL image has an encoded structured color profile, and it indicates an unknown or xyb color space. In that case, JxlDecoderGetColorAsICCProfile is not available.

When rendering an image on a system where ICC-based color management is used, JxlDecoderGetColorAsICCProfile should generally be used first as it will return a ready-to-use profile (with the aforementioned caveat about HDR). When knowledge about the nominal color space is desired if available, JxlDecoderGetColorAsEncodedProfile should be used first.

Parameters

  dec | decoder object
  target | whether to get the original color profile from the metadata or the color profile of the decoded pixels.
  color_encoding | struct to copy the information into, or NULL to only check whether the information is available through the return value.

Returns
  JXL_DEC_SUCCESS if the data is available and returned, JXL_DEC_NEED_MORE_INPUT if not yet available, JXL_DEC_ERROR in case the encoded structured color profile does not exist in the codestream.

## JxlDecoderGetColorAsICCProfile()

JXL_EXPORT JxlDecoderStatus JxlDecoderGetColorAsICCProfile | ( | const JxlDecoder * | dec,
|  | JxlColorProfileTarget | target,
|  | uint8_t * | icc_profile,
|  | size_t | size )

Outputs ICC profile if available. The profile is only available if JxlDecoderGetICCProfileSize returns success. The output buffer must have at least as many bytes as given by JxlDecoderGetICCProfileSize.

Parameters

  dec | decoder object
  target | whether to get the original color profile from the metadata or the color profile of the decoded pixels.
  icc_profile | buffer to copy the ICC profile into
  size | size of the icc_profile buffer in bytes

Returns
  JXL_DEC_SUCCESS if the profile was successfully returned, JXL_DEC_NEED_MORE_INPUT if not yet available, JXL_DEC_ERROR if the profile doesn't exist or the output size is not large enough.

## JxlDecoderGetExtraChannelBlendInfo()

JXL_EXPORT JxlDecoderStatus JxlDecoderGetExtraChannelBlendInfo | ( | const JxlDecoder * | dec,
|  | size_t | index,
|  | JxlBlendInfo * | blend_info )

Outputs the blend information for the current frame for a specific extra channel. This function can be called once the JXL_DEC_FRAME event occurred for the current frame, even if the have_animation field in the JxlBasicInfo is JXL_FALSE. This information is only useful if coalescing is disabled; otherwise the decoder will have performed blending already.

Parameters

  dec | decoder object
  index | the index of the extra channel
  blend_info | struct to copy the information into

Returns
  JXL_DEC_SUCCESS on success, JXL_DEC_ERROR on error

## JxlDecoderGetExtraChannelInfo()

JXL_EXPORT JxlDecoderStatus JxlDecoderGetExtraChannelInfo | ( | const JxlDecoder * | dec,
|  | size_t | index,
|  | JxlExtraChannelInfo * | info )

Outputs information for extra channel at the given index. The index must be smaller than num_extra_channels in the associated JxlBasicInfo.

Parameters

  dec | decoder object
  index | index of the extra channel to query.
  info | struct to copy the information into, or NULL to only check whether the information is available through the return value.

Returns
  JXL_DEC_SUCCESS if the value is available, JXL_DEC_NEED_MORE_INPUT if not yet available, JXL_DEC_ERROR in case of other error conditions.

## JxlDecoderGetExtraChannelName()

JXL_EXPORT JxlDecoderStatus JxlDecoderGetExtraChannelName | ( | const JxlDecoder * | dec,
|  | size_t | index,
|  | char * | name,
|  | size_t | size )

Outputs name for extra channel at the given index in UTF-8. The index must be smaller than num_extra_channels in the associated JxlBasicInfo. The buffer for name must have at least name_length + 1 bytes allocated, gotten from the associated JxlExtraChannelInfo.

Parameters

  dec | decoder object
  index | index of the extra channel to query.
  name | buffer to copy the name into
  size | size of the name buffer in bytes

Returns
  JXL_DEC_SUCCESS if the value is available, JXL_DEC_NEED_MORE_INPUT if not yet available, JXL_DEC_ERROR in case of other error conditions.

## JxlDecoderGetFrameHeader()

JXL_EXPORT JxlDecoderStatus JxlDecoderGetFrameHeader | ( | const JxlDecoder * | dec,
|  | JxlFrameHeader * | header )

Outputs the information from the frame, such as duration when have_animation. This function can be called when JXL_DEC_FRAME occurred for the current frame, even when have_animation in the JxlBasicInfo is JXL_FALSE.

Parameters

  dec | decoder object
  header | struct to copy the information into, or NULL to only check whether the information is available through the return value.

Returns
  JXL_DEC_SUCCESS if the value is available, JXL_DEC_NEED_MORE_INPUT if not yet available, JXL_DEC_ERROR in case of other error conditions.

## JxlDecoderGetFrameName()

JXL_EXPORT JxlDecoderStatus JxlDecoderGetFrameName | ( | const JxlDecoder * | dec,
|  | char * | name,
|  | size_t | size )

Outputs name for the current frame. The buffer for name must have at least name_length + 1 bytes allocated, gotten from the associated JxlFrameHeader.

Parameters

  dec | decoder object
  name | buffer to copy the name into
  size | size of the name buffer in bytes, including zero termination character, so this must be at least JxlFrameHeader::name_length + 1.

Returns
  JXL_DEC_SUCCESS if the value is available, JXL_DEC_NEED_MORE_INPUT if not yet available, JXL_DEC_ERROR in case of other error conditions.

## JxlDecoderGetICCProfileSize()

JXL_EXPORT JxlDecoderStatus JxlDecoderGetICCProfileSize | ( | const JxlDecoder * | dec,
|  | JxlColorProfileTarget | target,
|  | size_t * | size )

Outputs the size in bytes of the ICC profile returned by JxlDecoderGetColorAsICCProfile, if available, or indicates there is none available. In most cases, the image will have an ICC profile available, but if it does not, JxlDecoderGetColorAsEncodedProfile must be used instead.

See also
  JxlDecoderGetColorAsEncodedProfile for more information. The ICC profile is either the exact ICC profile attached to the codestream metadata, or a close approximation generated from JPEG XL encoded structured data, depending of what is encoded in the codestream.

Parameters

  dec | decoder object
  target | whether to get the original color profile from the metadata or the color profile of the decoded pixels.
  size | variable to output the size into, or NULL to only check the return status.

Returns
  JXL_DEC_SUCCESS if the ICC profile is available, JXL_DEC_NEED_MORE_INPUT if the decoder has not yet received enough input data to determine whether an ICC profile is available or what its size is, JXL_DEC_ERROR in case the ICC profile is not available and cannot be generated.

## JxlDecoderGetIntendedDownsamplingRatio()

JXL_EXPORT size_t JxlDecoderGetIntendedDownsamplingRatio | ( | JxlDecoder * | dec | ) |

Returns the intended downsampling ratio for the progressive frame produced by JxlDecoderFlushImage after the latest JXL_DEC_FRAME_PROGRESSION event.

Parameters

  dec | decoder object

Returns
  The intended downsampling ratio, can be 1, 2, 4 or 8.

## JxlDecoderImageOutBufferSize()

JXL_EXPORT JxlDecoderStatus JxlDecoderImageOutBufferSize | ( | const JxlDecoder * | dec,
|  | const JxlPixelFormat * | format,
|  | size_t * | size )

Returns the minimum size in bytes of the image output pixel buffer for the given format. This is the buffer for JxlDecoderSetImageOutBuffer. Requires that the basic image information is available in the decoder in the case of coalescing enabled (default). In case coalescing is disabled, this can only be called after the JXL_DEC_FRAME event occurs. In that case, it will return the size required to store the possibly cropped frame (which can be larger or smaller than the image dimensions).

Parameters

  dec | decoder object
  format | format of the pixels.
  size | output value, buffer size in bytes

Returns
  JXL_DEC_SUCCESS on success, JXL_DEC_ERROR on error, such as information not available yet.

## JxlDecoderPreviewOutBufferSize()

JXL_EXPORT JxlDecoderStatus JxlDecoderPreviewOutBufferSize | ( | const JxlDecoder * | dec,
|  | const JxlPixelFormat * | format,
|  | size_t * | size )

Returns the minimum size in bytes of the preview image output pixel buffer for the given format. This is the buffer for JxlDecoderSetPreviewOutBuffer. Requires the preview header information is available in the decoder.

Parameters

  dec | decoder object
  format | format of pixels
  size | output value, buffer size in bytes

Returns
  JXL_DEC_SUCCESS on success, JXL_DEC_ERROR on error, such as information not available yet.

## JxlDecoderProcessInput()

JXL_EXPORT JxlDecoderStatus JxlDecoderProcessInput | ( | JxlDecoder * | dec | ) |

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 JXL_DEC_ERROR), new information, such as JxlDecoderGetBasicInfo, may have become available after this call. When the return value is not JXL_DEC_ERROR or JXL_DEC_SUCCESS, the decoding requires more JxlDecoderProcessInput calls to continue.

Parameters

  dec | decoder object

Returns
  JXL_DEC_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 JXL_DEC_NEED_MORE_INPUT. JXL_DEC_SUCCESS can occur instead of JXL_DEC_NEED_MORE_INPUT 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.
  JXL_DEC_ERROR when decoding failed, e.g. invalid codestream. TODO(lode): document the input data mechanism
  JXL_DEC_NEED_MORE_INPUT when more input data is necessary.
  JXL_DEC_BASIC_INFO when basic info such as image dimensions is available and this informative event is subscribed to.
  JXL_DEC_COLOR_ENCODING when color profile information is available and this informative event is subscribed to.
  JXL_DEC_PREVIEW_IMAGE when preview pixel information is available and output in the preview buffer.
  JXL_DEC_FULL_IMAGE when all pixel information at highest detail is available and has been output in the pixel buffer.

## JxlDecoderReleaseBoxBuffer()

JXL_EXPORT size_t JxlDecoderReleaseBoxBuffer | ( | JxlDecoder * | dec | ) |

Releases buffer which was provided with JxlDecoderSetBoxBuffer.

Calling JxlDecoderReleaseBoxBuffer is required whenever a buffer is already set and a new buffer needs to be added with JxlDecoderSetBoxBuffer, but is not required before JxlDecoderDestroy or JxlDecoderReset.

Calling JxlDecoderReleaseBoxBuffer when no buffer is set is not an error and returns 0.

Parameters

  dec | decoder object

Returns
  the amount of bytes the decoder has not yet written to of the data set by JxlDecoderSetBoxBuffer, or 0 if no buffer is set or JxlDecoderReleaseBoxBuffer was already called.

## JxlDecoderReleaseInput()

JXL_EXPORT size_t JxlDecoderReleaseInput | ( | JxlDecoder * | dec | ) |

Releases input which was provided with JxlDecoderSetInput. Between JxlDecoderProcessInput and JxlDecoderReleaseInput, the user may not alter the data in the buffer. Calling JxlDecoderReleaseInput is required whenever any input is already set and new input needs to be added with JxlDecoderSetInput, but is not required before JxlDecoderDestroy or JxlDecoderReset. Calling JxlDecoderReleaseInput when no input is set is not an error and returns 0.

Parameters

  dec | decoder object

Returns
  The amount of bytes the decoder has not yet processed that are still remaining in the data set by JxlDecoderSetInput, or 0 if no input is set or JxlDecoderReleaseInput was already called. For a next call to JxlDecoderProcessInput, the buffer must start with these 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 JxlDecoderStatus for more information.

## JxlDecoderReleaseJPEGBuffer()

JXL_EXPORT size_t JxlDecoderReleaseJPEGBuffer | ( | JxlDecoder * | dec | ) |

Releases buffer which was provided with JxlDecoderSetJPEGBuffer.

Calling JxlDecoderReleaseJPEGBuffer is required whenever a buffer is already set and a new buffer needs to be added with JxlDecoderSetJPEGBuffer, but is not required before JxlDecoderDestroy or JxlDecoderReset.

Calling JxlDecoderReleaseJPEGBuffer when no buffer is set is not an error and returns 0.

Parameters

  dec | decoder object

Returns
  the amount of bytes the decoder has not yet written to of the data set by JxlDecoderSetJPEGBuffer, or 0 if no buffer is set or JxlDecoderReleaseJPEGBuffer was already called.

## JxlDecoderReset()

JXL_EXPORT void JxlDecoderReset | ( | JxlDecoder * | dec | ) |

Re-initializes a JxlDecoder instance, so it can be re-used for decoding another image. All state and settings are reset as if the object was newly created with JxlDecoderCreate, but the memory manager is kept.

Parameters

  dec | instance to be re-initialized.

## JxlDecoderRewind()

JXL_EXPORT void JxlDecoderRewind | ( | JxlDecoder * | dec | ) |

Rewinds decoder to the beginning. The same input must be given again from the beginning of the file and the decoder will emit events from the beginning again. When rewinding (as opposed to JxlDecoderReset), the decoder can keep state about the image, which it can use to skip to a requested frame more efficiently with JxlDecoderSkipFrames. Settings such as parallel runner or subscribed events are kept. After rewind, JxlDecoderSubscribeEvents can be used again, and it is feasible to leave out events that were already handled before, such as JXL_DEC_BASIC_INFO and JXL_DEC_COLOR_ENCODING, since they will provide the same information as before. The difference to JxlDecoderReset is that some state is kept, namely settings set by a call to

- JxlDecoderSetCoalescing,
- JxlDecoderSetDesiredIntensityTarget,
- JxlDecoderSetDecompressBoxes,
- JxlDecoderSetKeepOrientation,
- JxlDecoderSetUnpremultiplyAlpha,
- JxlDecoderSetParallelRunner,
- JxlDecoderSetRenderSpotcolors, and
- JxlDecoderSubscribeEvents.

Parameters

  dec | decoder object

## JxlDecoderSetBoxBuffer()

JXL_EXPORT JxlDecoderStatus JxlDecoderSetBoxBuffer | ( | JxlDecoder * | dec,
|  | uint8_t * | data,
|  | size_t | size )

Sets output buffer for box output codestream.

The data is owned by the caller and may be used by the decoder until JxlDecoderReleaseBoxBuffer is called or the decoder is destroyed or reset so must be kept alive until then.

If for the current box a box buffer was set before and released with JxlDecoderReleaseBoxBuffer, bytes that the decoder has already output should not be included, only the remaining bytes output must be set.

The JxlDecoderReleaseBoxBuffer must be used at the next JXL_DEC_BOX event or final JXL_DEC_SUCCESS event to compute the size of the output box bytes.

Parameters

  dec | decoder object
  data | pointer to next bytes to write to
  size | amount of bytes available starting from data

Returns
  JXL_DEC_ERROR if output buffer was already set and JxlDecoderReleaseBoxBuffer was not called on it, JXL_DEC_SUCCESS otherwise

## JxlDecoderSetCms()

JXL_EXPORT JxlDecoderStatus JxlDecoderSetCms | ( | JxlDecoder * | dec,
|  | JxlCmsInterface | cms )

Sets the color management system (CMS) that will be used for color conversion (if applicable) during decoding. May only be set before starting decoding and must not be called after JxlDecoderSetOutputColorProfile.

See JxlDecoderSetOutputColorProfile for how color conversions are done depending on whether or not a CMS has been set with JxlDecoderSetCms.

Parameters

  dec | decoder object.
  cms | structure representing a CMS implementation. See JxlCmsInterface for more details.

## JxlDecoderSetCoalescing()

JXL_EXPORT JxlDecoderStatus JxlDecoderSetCoalescing | ( | JxlDecoder * | dec,
|  | JXL_BOOL | coalescing )

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 | JXL_TRUE to enable coalescing (default), JXL_FALSE to disable it.

Returns
  JXL_DEC_SUCCESS if no error, JXL_DEC_ERROR otherwise.

## JxlDecoderSetDecompressBoxes()

JXL_EXPORT JxlDecoderStatus JxlDecoderSetDecompressBoxes | ( | JxlDecoder * | dec,
|  | JXL_BOOL | decompress )

Configures whether to get boxes in raw mode or in decompressed mode. In raw mode, boxes are output as their bytes appear in the container file, which may be decompressed, or compressed if their type is "brob". In decompressed mode, "brob" boxes are decompressed with Brotli before outputting them. The size of the decompressed stream is not known before the decompression has already finished.

The default mode is raw. This setting can only be changed before decoding, or directly after a JXL_DEC_BOX event, and is remembered until the decoder is reset or destroyed.

Enabling decompressed mode requires Brotli support from the library.

Parameters

  dec | decoder object
  decompress | JXL_TRUE to transparently decompress, JXL_FALSE to get boxes in raw mode.

Returns
  JXL_DEC_ERROR if decompressed mode is set and Brotli is not available, JXL_DEC_SUCCESS otherwise.

## JxlDecoderSetDesiredIntensityTarget()

JXL_EXPORT JxlDecoderStatus JxlDecoderSetDesiredIntensityTarget | ( | JxlDecoder * | dec,
|  | float | desired_intensity_target )

Requests that the decoder perform tone mapping to the peak display luminance passed as `desired_intensity_target`, if appropriate.

Note
  This is provided for convenience and the exact tone mapping that is performed is not meant to be considered authoritative in any way. It may change from version to version.

Parameters

  dec | decoder object
  desired_intensity_target | the intended target peak luminance

Returns
  JXL_DEC_SUCCESS if the preference was set successfully, JXL_DEC_ERROR otherwise.

## JxlDecoderSetExtraChannelBuffer()

JXL_EXPORT JxlDecoderStatus JxlDecoderSetExtraChannelBuffer | ( | JxlDecoder * | dec,
|  | const JxlPixelFormat * | format,
|  | void * | buffer,
|  | size_t | size,
|  | uint32_t | index )

Sets the buffer to write an extra channel to. This can be set when the JXL_DEC_FRAME or JXL_DEC_NEED_IMAGE_OUT_BUFFER event occurs, and applies only for the current frame. The size of the buffer must be at least as large as given by JxlDecoderExtraChannelBufferSize. The buffer follows the format described by JxlPixelFormat, but where num_channels is 1. The buffer is owned by the caller. The amount of extra channels is given by the num_extra_channels field in the associated JxlBasicInfo, and the information of individual extra channels can be queried with JxlDecoderGetExtraChannelInfo. To get multiple extra channels, this function must be called multiple times, once for each wanted index. Not all images have extra channels. The alpha channel is an extra channel and can be gotten as part of the color channels when using an RGBA pixel buffer with JxlDecoderSetImageOutBuffer, but additionally also can be gotten separately as extra channel. The color channels themselves cannot be gotten this way.

Parameters

  dec | decoder object
  format | format of the pixels. Object owned by user and its contents are copied internally. The num_channels value is ignored and is always treated to be 1.
  buffer | buffer type to output the pixel data to
  size | size of buffer in bytes
  index | which extra channel to get, matching the index used in JxlDecoderGetExtraChannelInfo. Must be smaller than num_extra_channels in the associated JxlBasicInfo.

Returns
  JXL_DEC_SUCCESS on success, JXL_DEC_ERROR on error, such as size too small or invalid index.

## JxlDecoderSetImageOutBitDepth()

JXL_EXPORT JxlDecoderStatus JxlDecoderSetImageOutBitDepth | ( | JxlDecoder * | dec,
|  | const JxlBitDepth * | bit_depth )

Sets the bit depth of the output buffer or callback.

Can be called after JxlDecoderSetImageOutBuffer or JxlDecoderSetImageOutCallback. For float pixel data types, only the default JXL_BIT_DEPTH_FROM_PIXEL_FORMAT setting is supported.

Parameters

  dec | decoder object
  bit_depth | the bit depth setting of the pixel output

Returns
  JXL_DEC_SUCCESS on success, JXL_DEC_ERROR on error, such as incompatible custom bit depth and pixel data type.

## JxlDecoderSetImageOutBuffer()

JXL_EXPORT JxlDecoderStatus JxlDecoderSetImageOutBuffer | ( | JxlDecoder * | dec,
|  | const JxlPixelFormat * | format,
|  | void * | buffer,
|  | size_t | size )

Sets the buffer to write the full resolution image to. This can be set when the JXL_DEC_FRAME event occurs, must be set when the JXL_DEC_NEED_IMAGE_OUT_BUFFER event occurs, and applies only for the current frame. The size of the buffer must be at least as large as given by JxlDecoderImageOutBufferSize. The buffer follows the format described by JxlPixelFormat. The buffer is owned by the caller.

Parameters

  dec | decoder object
  format | format of the pixels. Object owned by user and its contents are copied internally.
  buffer | buffer type to output the pixel data to
  size | size of buffer in bytes

Returns
  JXL_DEC_SUCCESS on success, JXL_DEC_ERROR on error, such as size too small.

## JxlDecoderSetImageOutCallback()

JXL_EXPORT JxlDecoderStatus JxlDecoderSetImageOutCallback | ( | JxlDecoder * | dec,
|  | const JxlPixelFormat * | format,
|  | JxlImageOutCallback | callback,
|  | void * | opaque )

Sets pixel output callback. This is an alternative to JxlDecoderSetImageOutBuffer. This can be set when the JXL_DEC_FRAME event occurs, must be set when the JXL_DEC_NEED_IMAGE_OUT_BUFFER event occurs, and applies only for the current frame. Only one of JxlDecoderSetImageOutBuffer or JxlDecoderSetImageOutCallback may be used for the same frame, not both at the same time.

The callback will be called multiple times, to receive the image data in small chunks. The callback receives a horizontal stripe of pixel data, 1 pixel high, xsize pixels wide, called a scanline. The xsize here is not the same as the full image width, the scanline may be a partial section, and xsize may differ between calls. The user can then process and/or copy the partial scanline to an image buffer. The callback may be called simultaneously by different threads when using a threaded parallel runner, on different pixels.

If JxlDecoderFlushImage is not used, then each pixel will be visited exactly once by the different callback calls, during processing with one or more JxlDecoderProcessInput calls. These pixels are decoded to full detail, they are not part of a lower resolution or lower quality progressive pass, but the final pass.

If JxlDecoderFlushImage is used, then in addition each pixel will be visited zero or one times during the blocking JxlDecoderFlushImage call. Pixels visited as a result of JxlDecoderFlushImage may represent a lower resolution or lower quality intermediate progressive pass of the image. Any visited pixel will be of a quality at least as good or better than previous visits of this pixel. A pixel may be visited zero times if it cannot be decoded yet or if it was already decoded to full precision (this behavior is not guaranteed).

Parameters

  dec | decoder object
  format | format of the pixels. Object owned by user; its contents are copied internally.
  callback | the callback function receiving partial scanlines of pixel data.
  opaque | optional user data, which will be passed on to the callback, may be NULL.

Returns
  JXL_DEC_SUCCESS on success, JXL_DEC_ERROR on error, such as JxlDecoderSetImageOutBuffer already set.

## JxlDecoderSetInput()

JXL_EXPORT JxlDecoderStatus JxlDecoderSetInput | ( | JxlDecoder * | dec,
|  | const uint8_t * | data,
|  | size_t | size )

Sets input data for JxlDecoderProcessInput. The data is owned by the caller and may be used by the decoder until JxlDecoderReleaseInput is called or the decoder is destroyed or reset so must be kept alive until then. Cannot be called if JxlDecoderSetInput was already called and JxlDecoderReleaseInput was not yet called, and cannot be called after JxlDecoderCloseInput indicating the end of input was called.

Parameters

  dec | decoder object
  data | pointer to next bytes to read from
  size | amount of bytes available starting from data

Returns
  JXL_DEC_ERROR if input was already set without releasing or JxlDecoderCloseInput was already called, JXL_DEC_SUCCESS otherwise.

## JxlDecoderSetJPEGBuffer()

JXL_EXPORT JxlDecoderStatus JxlDecoderSetJPEGBuffer | ( | JxlDecoder * | dec,
|  | uint8_t * | data,
|  | size_t | size )

Sets output buffer for reconstructed JPEG codestream.

The data is owned by the caller and may be used by the decoder until JxlDecoderReleaseJPEGBuffer is called or the decoder is destroyed or reset so must be kept alive until then.

If a JPEG buffer was set before and released with JxlDecoderReleaseJPEGBuffer, bytes that the decoder has already output should not be included, only the remaining bytes output must be set.

Parameters

  dec | decoder object
  data | pointer to next bytes to write to
  size | amount of bytes available starting from data

Returns
  JXL_DEC_ERROR if output buffer was already set and JxlDecoderReleaseJPEGBuffer was not called on it, JXL_DEC_SUCCESS otherwise

## JxlDecoderSetKeepOrientation()

JXL_EXPORT JxlDecoderStatus JxlDecoderSetKeepOrientation | ( | JxlDecoder * | dec,
|  | JXL_BOOL | skip_reorientation )

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 JXL_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 JXL_ORIENT_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 JXL_TRUE "JXL_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.

See also
  JxlBasicInfo for the orientation field, and JxlOrientation for the possible values.

Parameters

  dec | decoder object
  skip_reorientation | JXL_TRUE to enable, JXL_FALSE to disable.

Returns
  JXL_DEC_SUCCESS if no error, JXL_DEC_ERROR otherwise.

## JxlDecoderSetMultithreadedImageOutCallback()

JXL_EXPORT JxlDecoderStatus JxlDecoderSetMultithreadedImageOutCallback | ( | JxlDecoder * | dec,
|  | const JxlPixelFormat * | format,
|  | JxlImageOutInitCallback | init_callback,
|  | JxlImageOutRunCallback | run_callback,
|  | JxlImageOutDestroyCallback | destroy_callback,
|  | void * | init_opaque )

Similar to JxlDecoderSetImageOutCallback except that the callback is allowed an initialization phase during which it is informed of how many threads will call it concurrently, and those calls are further informed of which thread they are occurring in.

Parameters

  dec | decoder object
  format | format of the pixels. Object owned by user; its contents are copied internally.
  init_callback | initialization callback.
  run_callback | the callback function receiving partial scanlines of pixel data.
  destroy_callback | clean-up callback invoked after all calls to `run_callback`. May be NULL if no clean-up is necessary.
  init_opaque | optional user data passed to `init_callback`, may be NULL (unlike the return value from `init_callback` which may only be NULL if initialization failed).

Returns
  JXL_DEC_SUCCESS on success, JXL_DEC_ERROR on error, such as JxlDecoderSetImageOutBuffer having already been called.

## JxlDecoderSetOutputColorProfile()

JXL_EXPORT JxlDecoderStatus JxlDecoderSetOutputColorProfile | ( | JxlDecoder * | dec,
|  | const JxlColorEncoding * | color_encoding,
|  | const uint8_t * | icc_data,
|  | size_t | icc_size )

Sets the desired output color profile of the decoded image either from a color encoding or an ICC profile. Valid calls of this function have either `color_encoding` or `icc_data` set to NULL and `icc_size` must be 0 if and only if `icc_data` is NULL.

Depending on whether a color management system (CMS) has been set the behavior is as follows:

If a color management system (CMS) has been set with JxlDecoderSetCms, and the CMS supports output to the desired color encoding or ICC profile, then it will provide the output in that color encoding or ICC profile. If the desired color encoding or the ICC is not supported, then an error will be returned.

If no CMS has been set with JxlDecoderSetCms, there are two cases:

(1) Calling this function with a color encoding will convert XYB images to the desired color encoding. In this case, if the requested color encoding has a narrower gamut, or the white points differ, then the resulting image can have significant color distortion. Non-XYB images will not be converted to the desired color space.

(2) Calling this function with an ICC profile will result in an error.

If called with an ICC profile (after a call to JxlDecoderSetCms), the ICC profile has to be a valid RGB or grayscale color profile.

Can only be set after the JXL_DEC_COLOR_ENCODING event occurred and before any other event occurred, and should be used before getting JXL_COLOR_PROFILE_TARGET_DATA.

This function must not be called before JxlDecoderSetCms.

Parameters

  dec | decoder object
  color_encoding | the output color encoding
  icc_data | bytes of the icc profile
  icc_size | size of the icc profile in bytes

Returns
  JXL_DEC_SUCCESS if the color profile was set successfully, JXL_DEC_ERROR otherwise.

## JxlDecoderSetParallelRunner()

JXL_EXPORT JxlDecoderStatus JxlDecoderSetParallelRunner | ( | JxlDecoder * | dec,
|  | JxlParallelRunner | parallel_runner,
|  | void * | parallel_runner_opaque )

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
  JXL_DEC_SUCCESS if the runner was set, JXL_DEC_ERROR otherwise (the previous runner remains set).

## JxlDecoderSetPreferredColorProfile()

JXL_EXPORT JxlDecoderStatus JxlDecoderSetPreferredColorProfile | ( | JxlDecoder * | dec,
|  | const JxlColorEncoding * | color_encoding )

Sets the desired output color profile of the decoded image by calling JxlDecoderSetOutputColorProfile, passing on `color_encoding` and setting `icc_data` to NULL. See JxlDecoderSetOutputColorProfile for details.

Parameters

  dec | decoder object
  color_encoding | the default color encoding to set

Returns
  JXL_DEC_SUCCESS if the preference was set successfully, JXL_DEC_ERROR otherwise.

## JxlDecoderSetPreviewOutBuffer()

JXL_EXPORT JxlDecoderStatus JxlDecoderSetPreviewOutBuffer | ( | JxlDecoder * | dec,
|  | const JxlPixelFormat * | format,
|  | void * | buffer,
|  | size_t | size )

Sets the buffer to write the low-resolution preview image to. The size of the buffer must be at least as large as given by JxlDecoderPreviewOutBufferSize. The buffer follows the format described by JxlPixelFormat. The preview image dimensions are given by the JxlPreviewHeader. The buffer is owned by the caller.

Parameters

  dec | decoder object
  format | format of pixels. Object owned by user and its contents are copied internally.
  buffer | buffer type to output the pixel data to
  size | size of buffer in bytes

Returns
  JXL_DEC_SUCCESS on success, JXL_DEC_ERROR on error, such as size too small.

## JxlDecoderSetProgressiveDetail()

JXL_EXPORT JxlDecoderStatus JxlDecoderSetProgressiveDetail | ( | JxlDecoder * | dec,
|  | JxlProgressiveDetail | detail )

Configures at which progressive steps in frame decoding these JXL_DEC_FRAME_PROGRESSION event occurs. The default value for the level of detail if this function is never called is kDC.

Parameters

  dec | decoder object
  detail | at which level of detail to trigger JXL_DEC_FRAME_PROGRESSION

Returns
  JXL_DEC_SUCCESS on success, JXL_DEC_ERROR on error, such as an invalid value for the progressive detail.

## JxlDecoderSetRenderSpotcolors()

JXL_EXPORT JxlDecoderStatus JxlDecoderSetRenderSpotcolors | ( | JxlDecoder * | dec,
|  | JXL_BOOL | render_spotcolors )

Enables or disables rendering spot colors. By default, spot colors are rendered, which is OK for viewing the decoded image. If render_spotcolors is JXL_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 | JXL_TRUE to enable (default), JXL_FALSE to disable.

Returns
  JXL_DEC_SUCCESS if no error, JXL_DEC_ERROR otherwise.

## JxlDecoderSetUnpremultiplyAlpha()

JXL_EXPORT JxlDecoderStatus JxlDecoderSetUnpremultiplyAlpha | ( | JxlDecoder * | dec,
|  | JXL_BOOL | unpremul_alpha )

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.

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 | JXL_TRUE to enable, JXL_FALSE to disable.

Returns
  JXL_DEC_SUCCESS if no error, JXL_DEC_ERROR otherwise.

## JxlDecoderSizeHintBasicInfo()

JXL_EXPORT size_t JxlDecoderSizeHintBasicInfo | ( | const JxlDecoder * | dec | ) |

Returns a hint indicating how many more bytes the decoder is expected to need to make JxlDecoderGetBasicInfo available after the next JxlDecoderProcessInput call. This is a suggested large enough value for the amount of bytes to provide in the next JxlDecoderSetInput call, but it is not guaranteed to be an upper bound nor a lower bound. This number does not include bytes that have already been released from the input. Can be used before the first JxlDecoderProcessInput call, and is correct the first time in most cases. If not, JxlDecoderSizeHintBasicInfo can be called again to get an updated hint.

Parameters

  dec | decoder object

Returns
  the size hint in bytes if the basic info is not yet fully decoded.
  0 when the basic info is already available.

## JxlDecoderSkipCurrentFrame()

JXL_EXPORT JxlDecoderStatus JxlDecoderSkipCurrentFrame | ( | JxlDecoder * | dec | ) |

Skips processing the current frame. Can be called after frame processing already started, signaled by a JXL_DEC_NEED_IMAGE_OUT_BUFFER event, but before the corresponding JXL_DEC_FULL_IMAGE event. The next signaled event will be another JXL_DEC_FRAME, or JXL_DEC_SUCCESS if there are no more frames. If pixel data is required from the already processed part of the frame, JxlDecoderFlushImage must be called before this.

Parameters

  dec | decoder object

Returns
  JXL_DEC_SUCCESS if there is a frame to skip, and JXL_DEC_ERROR if the function was not called during frame processing.

## JxlDecoderSkipFrames()

JXL_EXPORT void JxlDecoderSkipFrames | ( | JxlDecoder * | dec,
|  | size_t | amount )

Makes the decoder skip the next amount frames. It still needs to process the input, but will not output the frame events. It can be more efficient when skipping frames, and even more so when using this after JxlDecoderRewind. If the decoder is already processing a frame (could have emitted JXL_DEC_FRAME but not yet JXL_DEC_FULL_IMAGE), it starts skipping from the next frame. If the amount is larger than the amount of frames remaining in the image, all remaining frames are skipped. Calling this function multiple times adds the amount to skip to the already existing amount.

A frame here is defined as a frame that without skipping emits events such as JXL_DEC_FRAME and JXL_DEC_FULL_IMAGE, frames that are internal to the file format but are not rendered as part of an animation, or are not the final still frame of a still image, are not counted.

Parameters

  dec | decoder object
  amount | the amount of frames to skip

## JxlDecoderSubscribeEvents()

JXL_EXPORT JxlDecoderStatus JxlDecoderSubscribeEvents | ( | JxlDecoder * | dec,
|  | int | events_wanted )

Select for which informative events, i.e. JXL_DEC_BASIC_INFO, 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
  JXL_DEC_SUCCESS if no error, JXL_DEC_ERROR otherwise.

## JxlDecoderVersion()

JXL_EXPORT uint32_t JxlDecoderVersion | ( | void |  | ) |

Decoder library version.

Returns
  the decoder library version as an integer: MAJOR_VERSION * 1000000 + MINOR_VERSION * 1000 + PATCH_VERSION. For example, version 1.2.3 would return 1002003.

## JxlSignatureCheck()

JXL_EXPORT JxlSignature JxlSignatureCheck | ( | const uint8_t * | buf,
|  | size_t | len )

JPEG XL signature identification.

Checks if the passed buffer contains a valid JPEG XL signature. The passed `buf` of size `size` doesn't need to be a full image, only the beginning of the file.

Returns
  a flag indicating if a JPEG XL signature was found and what type.
  - JXL_SIG_NOT_ENOUGH_BYTES if not enough bytes were passed to determine if a valid signature is there.
  - JXL_SIG_INVALID if no valid signature found for JPEG XL decoding.
  - JXL_SIG_CODESTREAM if a valid JPEG XL codestream signature was found.
  - JXL_SIG_CONTAINER if a valid JPEG XL container signature was found.