Module decode 

Decoding API for JPEG XL.

Structs

JxlDecoder

Opaque structure that holds the JPEG XL decoder.

Enums

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.

JxlDecoderStatus

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

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:

JxlSignature

The result of JxlSignatureCheck.

Functions

JxlDecoderCloseInput^⚠

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 JxlDecoderStatus::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 JxlDecoderStatus::Box for getting metadata box contents. This function does not replace JxlDecoderReleaseInput, that function should still be called if its return value is needed.

JxlDecoderCreate^⚠

Creates an instance of JxlDecoder and initializes it.

JxlDecoderDestroy^⚠

Deinitializes and frees JxlDecoder instance.

JxlDecoderExtraChannelBufferSize^⚠

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.

JxlDecoderFlushImage^⚠

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.

JxlDecoderGetBasicInfo^⚠

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

JxlDecoderGetBoxSizeContents^⚠

Returns the size of the contents of a box, after the JxlDecoderStatus::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.

JxlDecoderGetBoxSizeRaw^⚠

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

JxlDecoderGetBoxType^⚠

Outputs the type of the current box, after a JxlDecoderStatus::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 JxlBool::False, or the underlying box type if the decompressed argument is JxlBool::True.

JxlDecoderGetColorAsEncodedProfile^⚠

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.

JxlDecoderGetColorAsICCProfile^⚠

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.

JxlDecoderGetExtraChannelBlendInfo^⚠

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

JxlDecoderGetExtraChannelInfo^⚠

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

JxlDecoderGetExtraChannelName^⚠

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.

JxlDecoderGetFrameHeader^⚠

Outputs the information from the frame, such as duration when have_animation. This function can be called when JxlDecoderStatus::Frame occurred for the current frame, even when have_animation in the JxlBasicInfo is JxlBool::False.

JxlDecoderGetFrameName^⚠

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

JxlDecoderGetICCProfileSize^⚠

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.

JxlDecoderGetIntendedDownsamplingRatio^⚠

Returns the intended downsampling ratio for the progressive frame produced by JxlDecoderFlushImage after the latest JxlDecoderStatus::FrameProgression event.

JxlDecoderImageOutBufferSize^⚠

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 JxlDecoderStatus::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).

JxlDecoderPreviewOutBufferSize^⚠

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.

JxlDecoderProcessInput^⚠

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.

JxlDecoderReleaseBoxBuffer^⚠

Releases buffer which was provided with JxlDecoderSetBoxBuffer.

JxlDecoderReleaseInput^⚠

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.

JxlDecoderReleaseJPEGBuffer^⚠

Releases buffer which was provided with JxlDecoderSetJPEGBuffer.

JxlDecoderReset^⚠

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.

JxlDecoderRewind^⚠

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 JxlDecoderStatus::BasicInfo and JxlDecoderStatus::ColorEncoding, 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

JxlDecoderSetBoxBuffer^⚠

Sets output buffer for box output codestream.

JxlDecoderSetCms^⚠

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.

JxlDecoderSetCoalescing^⚠

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.

JxlDecoderSetDecompressBoxes^⚠

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.

JxlDecoderSetDesiredIntensityTarget^⚠

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

JxlDecoderSetExtraChannelBuffer^⚠

Sets the buffer to write an extra channel to. This can be set when the JxlDecoderStatus::Frame or JxlDecoderStatus::NeedImageOutBuffer 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.

JxlDecoderSetImageOutBitDepth^⚠

Sets the bit depth of the output buffer or callback.

JxlDecoderSetImageOutBuffer^⚠

Sets the buffer to write the full resolution image to. This can be set when the JxlDecoderStatus::Frame event occurs, must be set when the JxlDecoderStatus::NeedImageOutBuffer 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.

JxlDecoderSetImageOutCallback^⚠

Sets pixel output callback. This is an alternative to JxlDecoderSetImageOutBuffer. This can be set when the JxlDecoderStatus::Frame event occurs, must be set when the JxlDecoderStatus::NeedImageOutBuffer 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.

JxlDecoderSetInput^⚠

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 it 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.

JxlDecoderSetJPEGBuffer^⚠

Sets output buffer for reconstructed JPEG codestream.

JxlDecoderSetKeepOrientation^⚠

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.

JxlDecoderSetMultithreadedImageOutCallback^⚠

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.

JxlDecoderSetOutputColorProfile^⚠

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.

JxlDecoderSetParallelRunner^⚠

Set the parallel runner for multithreading. May only be set before starting decoding.

JxlDecoderSetPreferredColorProfile^⚠

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.

JxlDecoderSetPreviewOutBuffer^⚠

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.

JxlDecoderSetProgressiveDetail^⚠

Configures at which progressive steps in frame decoding the JxlDecoderStatus::FrameProgression event occurs. The default value for the level of detail if this function is never called is JxlProgressiveDetail::DC.

JxlDecoderSetRenderSpotcolors^⚠

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.

JxlDecoderSetUnpremultiplyAlpha^⚠

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.

JxlDecoderSizeHintBasicInfo^⚠

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.

JxlDecoderSkipCurrentFrame^⚠

Skips processing the current frame. Can be called after frame processing already started, signaled by a JxlDecoderStatus::NeedImageOutBuffer event, but before the corresponding JxlDecoderStatus::FullImage event. The next signaled event will be another JxlDecoderStatus::Frame, or JxlDecoderStatus::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.

JxlDecoderSkipFrames^⚠

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 JxlDecoderStatus::Frame but not yet JxlDecoderStatus::FullImage), 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.

JxlDecoderSubscribeEvents^⚠

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 is 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 called before using JxlDecoderProcessInput.

JxlDecoderVersion^⚠

Decoder library version.

JxlSignatureCheck^⚠

JPEG XL signature identification.

Type Aliases

JxlImageOutCallback

Function type for JxlDecoderSetImageOutCallback.

JxlImageOutDestroyCallback

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.

JxlImageOutInitCallback

Initialization callback for JxlDecoderSetMultithreadedImageOutCallback.

JxlImageOutRunCallback

Worker callback for JxlDecoderSetMultithreadedImageOutCallback