Structs

The codestream animation header, optionally present in the beginning of the codestream, and if it is it applies to all animation frames, unlike JxlFrameHeader which applies to an individual frame.

Basic image information. This information is available from the file signature and first part of the codestream header.

The information about blending the color channels or a single extra channel. When decoding, if coalescing is enabled (default), this can be ignored and the blend mode is considered to be JXL_BLEND_REPLACE. When encoding, these settings apply to the pixel data given to the encoder.

Interface for performing colorspace transforms. The @c init function can be called several times to instantiate several transforms, including before other transforms have been destroyed.

Color encoding of the image as structured information.

Represents an input or output colorspace to a color transform, as a serialized ICC profile.

The serialized ICC profile. This is guaranteed to be present and valid.

Information for a single extra channel.

The header of one displayed frame or non-coalesced layer.

The information about layers. When decoding, if coalescing is enabled (default), this can be ignored. When encoding, these settings apply to the pixel data given to the encoder, the encoder could choose an internal representation that differs.

Memory Manager struct. These functions, when provided by the caller, will be used to handle memory allocations.

Data type for the sample values per channel per pixel for the output buffer for pixels. This is not necessarily the same as the data type encoded in the codestream. The channels are interleaved per pixel. The pixels are organized row by row, left to right, top to bottom. TODO(lode): implement padding / alignment (row stride) TODO(lode): support different channel orders if needed (RGB, BGR, …)

The codestream preview header

Constants

Force big endian

Get the color profile of the pixel data the decoder outputs.

Get the color profile of the original image from the metadata.

Luminance based, the primaries in JxlColorEncoding must be ignored. This value implies that num_color_channels in JxlBasicInfo is 1, any other value implies num_color_channels is 3.

Tristimulus RGB

None of the other table entries describe the color space appropriately

XYB (opsin) color space

Informative event by @ref JxlDecoderProcessInput “JxlDecoderProcessInput”: Basic information such as image dimensions and extra channels. This event occurs max once per image.

Informative event by @ref JxlDecoderProcessInput “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:

The box contents output buffer is too small. @ref JxlDecoderSetBoxBuffer must be called again to make room for remaining bytes. This event may occur multiple times after @ref JXL_DEC_BOX.

Informative event by @ref JxlDecoderProcessInput “JxlDecoderProcessInput”: Color encoding or ICC profile from the codestream header. This event occurs max once per image and always later than @ref JXL_DEC_BASIC_INFO and earlier than any pixel data.

Informative event by @ref JxlDecoderProcessInput “JxlDecoderProcessInput”: DC image, 8x8 sub-sampled frame, decoded. It is not guaranteed that the decoder will always return DC separately, but when it does it will do so before outputting the full frame. @ref JxlDecoderSetDCOutBuffer must be used after getting the basic image information to be able to get the DC pixels, if not this return status only indicates we’re past this point in the codestream. This event occurs max once per frame and always later than @ref JXL_DEC_FRAME and other header events and earlier than full resolution pixel data.

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

Informative event by @ref JxlDecoderProcessInput “JxlDecoderProcessInput”: User extensions of the codestream header. This event occurs max once per image and always later than @ref JXL_DEC_BASIC_INFO and earlier than any pixel data.

Informative event by @ref JxlDecoderProcessInput “JxlDecoderProcessInput”: Beginning of a frame. @ref 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 @ref 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 @ref 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.

Informative event by @ref JxlDecoderProcessInput “JxlDecoderProcessInput”: a progressive step in decoding the frame is reached. When calling @ref 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 @ref JxlDecoderSetProgressiveDetail to configure more fine-grainedness. The event is not guaranteed to trigger, not all images have progressive steps or DC encoded.

Informative event by @ref JxlDecoderProcessInput “JxlDecoderProcessInput”: full frame (or layer, in case coalescing is disabled) is decoded. @ref 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 and always later than @ref JXL_DEC_DC_IMAGE.

The JPEG reconstruction buffer is too small for reconstructed JPEG codestream to fit. @ref JxlDecoderSetJPEGBuffer must be called again to make room for remaining bytes. This event may occur multiple times after @ref JXL_DEC_JPEG_RECONSTRUCTION.

Informative event by @ref JxlDecoderProcessInput “JxlDecoderProcessInput”: JPEG reconstruction data decoded. @ref 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 @ref JXL_DEC_FULL_IMAGE.

The decoder is able to decode a DC image and requests setting a DC output buffer using @ref JxlDecoderSetDCOutBuffer. This occurs if @ref JXL_DEC_DC_IMAGE is requested and it is possible to decode a DC image from the codestream and the DC out buffer was not yet set. This event re-occurs for new frames if there are multiple animation frames. @deprecated The DC feature in this form will be removed. For progressive rendering, @ref JxlDecoderFlushImage should be used.

The decoder requests an output buffer to store the full resolution image, which can be set with @ref JxlDecoderSetImageOutBuffer or with @ref JxlDecoderSetImageOutCallback. This event re-occurs for new frames if there are multiple animation frames and requires setting an output again.

The decoder needs more input bytes to continue. Before the next @ref JxlDecoderProcessInput call, more input data must be set, by calling @ref JxlDecoderReleaseInput (if input was set previously) and then calling @ref JxlDecoderSetInput. @ref JxlDecoderReleaseInput returns how many bytes are not yet processed, before a next call to @ref 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.

The decoder is able to decode a preview image and requests setting a preview output buffer using @ref JxlDecoderSetPreviewOutBuffer. This occurs if @ref 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.

Informative event by @ref JxlDecoderProcessInput “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 @ref JXL_DEC_COLOR_ENCODING and before @ref JXL_DEC_FRAME.

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

An error occurred, for example out of memory.

The encoder API is used in an incorrect way. In this case, a debug build of libjxl should output a specific error message. (if not, please open an issue about it)

Input is invalid (e.g. corrupt JPEG file or ICC profile)

Generic encoder error due to unspecified cause

JPEG bitstream reconstruction data could not be represented (e.g. too much tail data)

The encoder doesn’t (yet) support this. Either no version of libjxl supports this, and the API is used incorrectly, or the libjxl version should have been checked before trying to do this.

Out of memory TODO(jon): actually catch this and return this error

Prepare the frame for indexing in the frame index box. 0 = ignore this frame (same as not setting a value), 1 = index this frame within the Frame Index Box. If any frames are indexed, the first frame needs to be indexed, too. If the first frame is not indexed, and a later frame is attempted to be indexed, JXL_ENC_ERROR will occur. If non-keyframes, i.e., frames with cropping, blending or patches are attempted to be indexed, JXL_ENC_ERROR will occur.

Indicates the frame added with @ref JxlEncoderAddImageFrame is already downsampled by the downsampling factor set with @ref JXL_ENC_FRAME_SETTING_RESAMPLING. The input frame must then be given in the downsampled resolution, not the full image resolution. The downsampled resolution is given by ceil(xsize / resampling), ceil(ysize / resampling) with xsize and ysize the dimensions given in the basic info, and resampling the factor set with @ref JXL_ENC_FRAME_SETTING_RESAMPLING. Use 0 to disable, 1 to enable. Default value is 0.

Sets brotli encode effort for use in JPEG recompression and compressed metadata boxes (brob). Can be -1 (default) or 0 (fastest) to 11 (slowest). Default is based on the general encode effort in case of JPEG recompression, and 4 for brob boxes.

Use Global channel palette if the amount of colors is smaller than this percentage of range. Use 0-100 to set an explicit percentage, -1 to use the encoder default. Used for modular encoding.

Use Local (per-group) channel palette if the amount of colors is smaller than this percentage of range. Use 0-100 to set an explicit percentage, -1 to use the encoder default. Used for modular encoding.

Color transform for internal encoding: -1 = default, 0=XYB, 1=none (RGB), 2=YCbCr. The XYB setting performs the forward XYB transform. None and YCbCr both perform no transform, but YCbCr is used to indicate that the encoded data losslessly represents YCbCr values.

Sets the decoding speed tier for the provided options. Minimum is 0 (slowest to decode, best quality/density), and maximum is 4 (fastest to decode, at the cost of some quality/density). Default is 0.

Enables or disables dots generation. Use -1 for the default (encoder chooses), 0 to disable, 1 to enable.

Sets encoder effort/speed level without affecting decoding speed. Valid values are, from faster to slower speed: 1:lightning 2:thunder 3:falcon 4:cheetah 5:hare 6:wombat 7:squirrel 8:kitten 9:tortoise. Default: squirrel (7).

Edge preserving filter level, -1 to 3. Use -1 for the default (encoder chooses), 0 to 3 to set a strength.

Similar to JXL_ENC_FRAME_SETTING_RESAMPLING, but for extra channels. Integer option, use -1 for the default behavior (depends on encoder implementation), 1 for no downsampling (1x1), 2 for 2x2 downsampling, 4 for 4x4 downsampling, 8 for 8x8 downsampling.

Enum value not to be used as an option. This value is added to force the C compiler to have the enum to take a known size.

Enables or disables the gaborish filter. Use -1 for the default (encoder chooses), 0 to disable, 1 to enable.

Determines the order in which 256x256 regions are stored in the codestream for progressive rendering. Use -1 for the encoder default, 0 for scanline order, 1 for center-first order.

Determines the horizontal position of center for the center-first group order. Use -1 to automatically use the middle of the image, 0..xsize to specifically set it.

Determines the center for the center-first group order. Use -1 to automatically use the middle of the image, 0..ysize to specifically set it.

Enable or disable CFL (chroma-from-luma) for lossless JPEG recompression. -1 = default, 0 = disable CFL, 1 = enable CFL.

Enables or disables preserving color of invisible pixels. Use -1 for the default (1 if lossless, 0 if lossy), 0 to disable, 1 to enable.

Enables or disables delta palette. Use -1 for the default (encoder chooses), 0 to disable, 1 to enable. Used in modular mode.

Enables modular encoding. Use -1 for default (encoder chooses), 0 to enforce VarDCT mode (e.g. for photographic images), 1 to enforce modular mode (e.g. for lossless images).

Reversible color transform for modular encoding: -1=default, 0-41=RCT index, e.g. index 0 = none, index 6 = YCoCg. If this option is set to a non-default value, the RCT will be globally applied to the whole frame. The default behavior is to try several RCTs locally per modular group, depending on the speed and distance setting.

Group size for modular encoding: -1=default, 0=128, 1=256, 2=512, 3=1024.

Fraction of pixels used to learn MA trees as a percentage. -1 = default, 0 = no MA and fast decode, 50 = default value, 100 = all, values above 100 are also permitted. Higher values use more encoder memory.

Number of extra (previous-channel) MA tree properties to use. -1 = default, 0-11 = valid values. Recommended values are in the range 0 to 3, or 0 to amount of channels minus 1 (including all extra channels, and excluding color channels when using VarDCT mode). Higher value gives slower encoding and slower decoding.

Predictor for modular encoding. -1 = default, 0=zero, 1=left, 2=top, 3=avg0, 4=select, 5=gradient, 6=weighted, 7=topright, 8=topleft, 9=leftleft, 10=avg1, 11=avg2, 12=avg3, 13=toptop predictive average 14=mix 5 and 6, 15=mix everything.

Enables adaptive noise generation. This setting is not recommended for use, please use JXL_ENC_FRAME_SETTING_PHOTON_NOISE instead. Use -1 for the default (encoder chooses), 0 to disable, 1 to enable.

Use color palette if amount of colors is smaller than or equal to this amount, or -1 to use the encoder default. Used for modular encoding.

Enables or disables patches generation. Use -1 for the default (encoder chooses), 0 to disable, 1 to enable.

Adds noise to the image emulating photographic film noise, the higher the given number, the grainier the image will be. As an example, a value of 100 gives low noise whereas a value of 3200 gives a lot of noise. The default value is 0.

Set the progressive mode for the AC coefficients of VarDCT, using spectral progression from the DCT coefficients. Use -1 for the encoder default, 0 to disable, 1 to enable.

Set the progressive mode using lower-resolution DC images for VarDCT. Use -1 for the encoder default, 0 to disable, 1 to have an extra 64x64 lower resolution pass, 2 to have a 512x512 and 64x64 lower resolution pass.

Set the progressive mode for the AC coefficients of VarDCT, using quantization of the least significant bits. Use -1 for the encoder default, 0 to disable, 1 to enable.

Sets resampling option. If enabled, the image is downsampled before compression, and upsampled to original size in the decoder. Integer option, use -1 for the default behavior (resampling only applied for low quality), 1 for no downsampling (1x1), 2 for 2x2 downsampling, 4 for 4x4 downsampling, 8 for 8x8 downsampling.

Enables or disables progressive encoding for modular mode. Use -1 for the encoder default, 0 to disable, 1 to enable.

The encoder needs more output buffer to continue encoding.

DEPRECATED: the encoder does not return this status and there is no need to handle or expect it. Instead, JXL_ENC_ERROR is returned with error condition JXL_ENC_ERR_NOT_SUPPORTED.

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

Force little endian

Use the endianness of the system, either little endian or big endian, without forcing either specific endianness. Do not use if pixel data should be exported to a well defined format.

As specified in Rec. ITU-R BT.2100-1

Primaries must be read from the JxlColorEncoding primaries_red_xy, primaries_green_xy and primaries_blue_xy fields, or as ICC profile. This enum value is not an exact match of the corresponding CICP value.

As specified in SMPTE RP 431-2

The CIE xy values of the red, green and blue primaries are: 0.639998686, 0.330010138; 0.300003784, 0.600003357; 0.150002046, 0.059997204

A valid JPEG XL codestream signature was found, that is a JPEG XL image without container.

A valid container signature was found, that is a JPEG XL image embedded in a box format container.

No valid JPEG XL header was found.

Not enough bytes were passed to determine if a valid signature was found.

As specified in SMPTE RP 431-2

As specified in SMPTE ST 428-1

Transfer function follows power law given by the gamma value in JxlColorEncoding. Not a CICP value.

As specified in Rec. ITU-R BT.2100-1 (HLG)

The gamma exponent is 1

As specified in SMPTE ST 2084

As specified in IEC 61966-2-1 sRGB

None of the other table entries describe the transfer function.

Use 32-bit single-precision floating point values, with range 0.0-1.0 (within gamut, may go outside this range for wide color gamut). Floating point output, either JXL_TYPE_FLOAT or JXL_TYPE_FLOAT16, is recommended for HDR and wide gamut images when color profile conversion is required.

Use 16-bit IEEE 754 half-precision floating point values

Use type uint8_t. May clip wide color gamut data.

Use type uint16_t. May clip wide color gamut data.

White point must be read from the JxlColorEncoding white_point field, or as ICC profile. This enum value is not an exact match of the corresponding CICP value.

CIE Standard Illuminant D65: 0.3127, 0.3290

DCI-P3 from SMPTE RP 431-2: 0.314, 0.351

CIE Standard Illuminant E (equal-energy): 1/3, 1/3

Functions

Creates an instance of JxlButteraugliApi and initializes it.

Deinitializes and frees JxlButteraugliApi instance.

Set the hf_asymmetry option for butteraugli.

Set the intensity_target option for butteraugli.

Set the parallel runner for multithreading.

Computes intermediary butteraugli result between an original image and a distortion.

Deinitializes and frees JxlButteraugliResult instance.

Computes a butteraugli distance based on an intermediary butteraugli result.

Get a pointer to the distmap in the result.

Computes butteraugli max distance based on an intermediary butteraugli result.

Sets a color encoding to be linear sRGB.

Sets a color encoding to be sRGB.

Marks the input as finished, indicates that no more @ref 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 @ref 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 @ref JXL_DEC_BOX for getting metadata box contents. This function does not replace @ref JxlDecoderReleaseInput, that function should still be called if its return value is needed.

Creates an instance of @ref JxlDecoder and initializes it.

Returns the minimum size in bytes of the DC image output buffer for the given format. This is the buffer for @ref JxlDecoderSetDCOutBuffer. Requires the basic image information is available in the decoder.

Get the default pixel format for this decoder.

Deinitializes and frees @ref JxlDecoder instance.

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

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

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

Returns the size of a box as it appears in the container file, after the @ref JXL_DEC_BOX event. For a non-compressed box, this is the size of the contents, excluding the 4 bytes indicating the box type. For a compressed “brob” box, this is the size of the compressed box contents plus the additional 4 byte indicating the underlying box type, but excluding the 4 bytes indicating “brob”. This function gives the size of the data that will be written in the output buffer when getting boxes in the default raw compressed mode. When @ref 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.

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.

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.

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

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

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

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.

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

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

Outputs the size in bytes of the ICC profile returned by @ref 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, @ref JxlDecoderGetColorAsEncodedProfile must be used instead.

Returns the minimum size in bytes of the image output pixel buffer for the given format. This is the buffer for @ref 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 @ref 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).

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

Decodes JPEG XL file using the available bytes. Requires input has been set with @ref JxlDecoderSetInput. After @ref JxlDecoderProcessInput, input can optionally be released with @ref JxlDecoderReleaseInput and then set again to next bytes in the stream. @ref JxlDecoderReleaseInput returns how many bytes are not yet processed, before a next call to @ref 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.

Releases buffer which was provided with @ref JxlDecoderSetBoxBuffer.

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

Releases buffer which was provided with @ref JxlDecoderSetJPEGBuffer.

Re-initializes a @ref 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 @ref JxlDecoderCreate, but the memory manager is kept.

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 @ref JxlDecoderReset), the decoder can keep state about the image, which it can use to skip to a requested frame more efficiently with @ref JxlDecoderSkipFrames. Settings such as parallel runner or subscribed events are kept. After rewind, @ref JxlDecoderSubscribeEvents can be used again, and it is feasible to leave out events that were already handled before, such as @ref JXL_DEC_BASIC_INFO and @ref JXL_DEC_COLOR_ENCODING, since they will provide the same information as before.

Sets output buffer for box output codestream.

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.

Sets the buffer to write the lower resolution (8x8 sub-sampled) DC image to. The size of the buffer must be at least as large as given by @ref JxlDecoderDCOutBufferSize. The buffer follows the format described by JxlPixelFormat. The DC image has dimensions ceil(xsize / 8) * ceil(ysize / 8). The buffer is owned by the caller.

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.

Sets the buffer to write an extra channel to. This can be set when the @ref JXL_DEC_FRAME or @ref 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 @ref 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 @ref 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 @ref JxlDecoderSetImageOutBuffer, but additionally also can be gotten separately as extra channel. The color channels themselves cannot be gotten this way.

Sets the buffer to write the full resolution image to. This can be set when the @ref JXL_DEC_FRAME event occurs, must be set when the @ref 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 @ref JxlDecoderImageOutBufferSize. The buffer follows the format described by JxlPixelFormat. The buffer is owned by the caller.

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

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

Sets output buffer for reconstructed JPEG codestream.

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.

Similar to @ref 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.

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

Sets the color profile to use for @ref JXL_COLOR_PROFILE_TARGET_DATA for the special case when the decoder has a choice. This only has effect for a JXL image where uses_original_profile is false, and the original color profile is encoded as an ICC color profile rather than a JxlColorEncoding with known enum values. In most other cases (uses uses_original_profile is true, or the color profile is already given as a JxlColorEncoding), this setting is ignored and the decoder uses a profile related to the image. No matter what, the @ref JXL_COLOR_PROFILE_TARGET_DATA must still be queried to know the actual data format of the decoded pixels after decoding.

Sets the buffer to write the small resolution preview image to. The size of the buffer must be at least as large as given by @ref 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.

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

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 @ref JxlDecoderSetExtraChannelBuffer. This is useful for e.g. printing applications.

Returns a hint indicating how many more bytes the decoder is expected to need to make @ref JxlDecoderGetBasicInfo available after the next @ref JxlDecoderProcessInput call. This is a suggested large enough value for the amount of bytes to provide in the next @ref 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 @ref JxlDecoderProcessInput call, and is correct the first time in most cases. If not, @ref JxlDecoderSizeHintBasicInfo can be called again to get an updated hint.

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 @ref JxlDecoderRewind. If the decoder is already processing a frame (could have emitted @ref JXL_DEC_FRAME but not yet @ref 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.

Select for which informative events, i.e. @ref 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 @ref JxlDecoderProcessInput.

Decoder library version.

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

Sets the buffer to read pixels from for the next image to encode. Must call JxlEncoderSetBasicInfo before JxlEncoderAddImageFrame.

Sets the buffer to read JPEG encoded bytes from for the next frame to encode.

Declares that no further boxes will be added with @ref JxlEncoderAddBox. This function must be called after the last box is added so the encoder knows the stream will be finished. It is not necessary to use this function if @ref JxlEncoderUseBoxes is not used. Further frames may still be added.

Declares that no frames will be added and @ref JxlEncoderAddImageFrame and @ref JxlEncoderAddJPEGFrame won’t be called anymore. Further metadata boxes may still be added. This function or @ref JxlEncoderCloseInput must be called after adding the last frame and the next call to @ref JxlEncoderProcessOutput, or the frame won’t be properly marked as last.

Closes any input to the encoder, equivalent to calling JxlEncoderCloseFrames as well as calling JxlEncoderCloseBoxes if needed. No further input of any kind may be given to the encoder, but further @ref JxlEncoderProcessOutput calls should be done to create the final output.

Creates an instance of JxlEncoder and initializes it.

Deinitializes and frees JxlEncoder instance.

Create a new set of encoder options, with all values initially copied from the @p source options, or set to default if @p source is NULL.

Sets a frame-specific option of integer type to the encoder options. The JxlEncoderFrameSettingId argument determines which option is set.

Get the (last) error code in case JXL_ENC_ERROR was returned.

Returns the codestream level required to support the currently configured settings and basic info. This function can only be used at the beginning, before encoding starts, but after setting basic info.

Initializes a JxlBasicInfo struct to default values. For forwards-compatibility, this function has to be called before values are assigned to the struct fields. The default values correspond to an 8-bit RGB image, no alpha or any other extra channels.

Initializes a JxlBlendInfo struct to default values. For forwards-compatibility, this function has to be called before values are assigned to the struct fields.

Initializes a JxlExtraChannelInfo struct to default values. For forwards-compatibility, this function has to be called before values are assigned to the struct fields. The default values correspond to an 8-bit channel of the provided type.

Initializes a JxlFrameHeader struct to default values. For forwards-compatibility, this function has to be called before values are assigned to the struct fields. The default values correspond to a frame with no animation duration and the ‘replace’ blend mode. After using this function, For animation duration must be set, for composite still blend settings must be set.

DEPRECATED: use JxlEncoderFrameSettingsCreate instead.

@param frame_settings set of options and metadata for this frame. Also includes reference to the encoder object. @param tier the decoding speed tier to set. @return JXL_ENC_SUCCESS if the operation was successful, JXL_ENC_ERROR otherwise.

DEPRECATED: use JxlEncoderSetFrameDistance instead.

@param frame_settings set of options and metadata for this frame. Also includes reference to the encoder object. @param effort the effort value to set. @return JXL_ENC_SUCCESS if the operation was successful, JXL_ENC_ERROR otherwise.

DEPRECATED: use JxlEncoderSetFrameLossless instead.

Encodes JPEG XL file using the available bytes. @p *avail_out indicates how many output bytes are available, and @p *next_out points to the input bytes. *avail_out will be decremented by the amount of bytes that have been processed by the encoder and *next_out will be incremented by the same amount, so *next_out will now point at the amount of *avail_out unprocessed bytes.

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

Sets the global metadata of the image encoded by this encoder.

Sets the color management system (CMS) that will be used for color conversion (if applicable) during encoding. May only be set before starting encoding. If left unset, the default CMS implementation will be used.

Sets the feature level of the JPEG XL codestream. Valid values are 5 and 10. Keeping the default value of 5 is recommended for compatibility with all decoders.

Sets the original color encoding of the image encoded by this encoder. This is an alternative to JxlEncoderSetICCProfile and only one of these two must be used. This one sets the color encoding as a @ref JxlColorEncoding, while the other sets it as ICC binary data. Must be called after JxlEncoderSetBasicInfo.

Sets blend info of an extra channel. The blend info of extra channels is set separately from that of the color channels, the color channels are set with @ref JxlEncoderSetFrameHeader.

Sets the buffer to read pixels from for an extra channel at a given index. The index must be smaller than the num_extra_channels in the associated JxlBasicInfo. Must call @ref JxlEncoderSetExtraChannelInfo before JxlEncoderSetExtraChannelBuffer.

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

Sets the name for the extra channel at the given index in UTF-8. The index must be smaller than the num_extra_channels in the associated JxlBasicInfo.

Sets the distance level for lossy compression: target max butteraugli distance, lower = higher quality. Range: 0 .. 15. 0.0 = mathematically lossless (however, use JxlEncoderSetFrameLossless instead to use true lossless, as setting distance to 0 alone is not the only requirement). 1.0 = visually lossless. Recommended range: 0.5 .. 3.0. Default value: 1.0.

Sets the frame information for this frame to the encoder. This includes animation information such as frame duration to store in the frame header. The frame header fields represent the frame as passed to the encoder, but not necessarily the exact values as they will be encoded file format: the encoder could change crop and blending options of a frame for more efficient encoding or introduce additional internal frames. Animation duration and time code information is not altered since those are immutable metadata of the frame.

Enables lossless encoding.

Sets the name of the animation frame. This function is optional, frames are not required to have a name. This setting is a part of the frame header, and the same principles as for @ref JxlEncoderSetFrameHeader apply. The name_length field of JxlFrameHeader is ignored by the encoder, this function determines the name length instead as the length in bytes of the C string.

Sets the original color encoding of the image encoded by this encoder as an ICC color profile. This is an alternative to JxlEncoderSetColorEncoding and only one of these two must be used. This one sets the color encoding as ICC binary data, while the other defines it as a @ref JxlColorEncoding. Must be called after JxlEncoderSetBasicInfo.

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

Configure the encoder to store JPEG reconstruction metadata in the JPEG XL container.

Indicates the intention to add metadata boxes. This allows @ref JxlEncoderAddBox to be used. When using this function, then it is required to use @ref JxlEncoderCloseBoxes at the end.

Forces the encoder to use the box-based container format (BMFF) even when not necessary.

Encoder library version.

JPEG XL signature identification.

Parallel runner internally using std::thread. Use as JxlParallelRunner.

Creates the runner for JxlThreadParallelRunner. Use as the opaque runner.

Returns a default num_worker_threads value for JxlThreadParallelRunnerCreate.

Destroys the runner created by JxlThreadParallelRunnerCreate.

Type Definitions

Frame blend modes. When decoding, if coalescing is enabled (default), this can be ignored.

Data type holding the 4-character type name of an ISOBMFF box.

Opaque structure that holds a butteraugli API.

Opaque structure that holds intermediary butteraugli results.

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 received by the decoder. Both are the same if the JxlBasicInfo has uses_original_profile set.

Color space of the image data.

Data type for the sample values per channel per pixel.

Opaque structure that holds the JPEG XL decoder.

Return value for @ref JxlDecoderProcessInput. The values from @ref 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 @ref JxlDecoderSubscribeEvents.

Opaque structure that holds the JPEG XL encoder.

Error conditions: API usage errors have the 0x80 bit set to 1 Other errors have the 0x80 bit set to 0

Id of encoder options for a frame. This includes options such as setting encoding effort/speed or overriding the use of certain coding tools, for this frame. This does not include non-frame related encoder options such as for boxes.

Settings and metadata for a single image frame. This includes encoder options for a frame such as compression quality and speed.

Return value for multiple encoder functions.

Ordering of multi-byte data.

Given type of an extra channel.

Function type for @ref JxlDecoderSetImageOutCallback.

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

Initialization callback for @ref JxlDecoderSetMultithreadedImageOutCallback.

Worker callback for @ref JxlDecoderSetMultithreadedImageOutCallback.

Memory Manager struct. These functions, when provided by the caller, will be used to handle memory allocations.

Image orientation metadata. Values 1..8 match the EXIF definitions. The name indicates the operation to perform to transform from the encoded image to the display image.

Return code used in the JxlParallel* functions as return value. A value of 0 means success and any other value means error. The special value JXL_PARALLEL_RET_RUNNER_ERROR can be used by the runner to indicate any other error.

Parallel run data processing callback. See JxlParallelRunner for details.

Parallel run initialization callback. See JxlParallelRunner for details.

JxlParallelRunner function type. A parallel runner implementation can be provided by a JPEG XL caller to allow running computations in multiple threads. This function must call the initialization function @p init in the same thread that called it and then call the passed @p func once for every number in the range [start_range, end_range) (including start_range but not including end_range) possibly from different multiple threads in parallel.

Built-in primaries for color encoding. When decoding, the primaries can be read from the JxlColorEncoding primaries_red_xy, primaries_green_xy and primaries_blue_xy fields regardless of the enum value. When encoding, the enum values except JXL_PRIMARIES_CUSTOM override the numerical fields. Some enum values match a subset of CICP (Rec. ITU-T H.273 | ISO/IEC 23091-2:2019(E)), however the white point and RGB primaries are separate enums here.

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:

Renderig intent for color encoding, as specified in ISO 15076-1:2010

The result of @ref JxlSignatureCheck.

Built-in transfer functions for color encoding. Enum values match a subset of CICP (Rec. ITU-T H.273 | ISO/IEC 23091-2:2019(E)) unless specified otherwise.

Built-in whitepoints for color encoding. When decoding, the numerical xy whitepoint value can be read from the JxlColorEncoding white_point field regardless of the enum value. When encoding, enum values except JXL_WHITE_POINT_CUSTOM override the numerical fields. Some enum values match a subset of CICP (Rec. ITU-T H.273 | ISO/IEC 23091-2:2019(E)), however the white point and RGB primaries are separate enums here.

Allocating function for a memory region of a given size.

Performs the necessary clean-up and frees the memory allocated for user data.

Returns a buffer that can be used by callers of the interface to store the input of the conversion or read its result, if they pass it as the input or output of the @c run function. @param user_data the data returned by @c init. @param thread the index of the thread for which to return a buffer. @return A buffer that can be used by the caller for passing to @c run.

Allocates and returns the data needed for @p num_threads parallel transforms from the @p input colorspace to @p output, with up to @p pixels_per_thread pixels to transform per call to JxlCmsInterface::run. @p init_data comes directly from the JxlCmsInterface instance. Since @c run only receives the data returned by @c init, a reference to @p init_data should be kept there if access to it is desired in @c run. Likewise for JxlCmsInterface::destroy.

Executes one transform and returns true on success or false on error. It must be possible to call this from different threads with different values for @p thread, all between 0 (inclusive) and the value of @p num_threads passed to @c init (exclusive). It is allowed to implement this by locking such that the transforms are essentially performed sequentially, if such a performance profile is acceptable. @p user_data is the data returned by @c init. The buffers each contain @p num_pixels × @c num_channels interleaved floating point (0..1) samples where @c num_channels is the number of color channels of their respective color profiles. It is guaranteed that the only case in which they might overlap is if the output has fewer channels than the input, in which case the pointers may be identical. For CMYK data, 0 represents the maximum amount of ink while 1 represents no ink. @param user_data the data returned by @c init. @param thread the index of the thread from which the function is being called. @param input_buffer the buffer containing the pixel data to be transformed. @param output_buffer the buffer receiving the transformed pixel data. @param num_pixels the number of pixels to transform from @p input to @p output. @return JXL_TRUE on success, JXL_FALSE on failure.

Deallocating function pointer type.