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.
Color encoding of the image as structured information.
Information for a single extra channel.
The header of one displayed frame.
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
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.
None of the other table entries describe the color space appropriately
XYB (opsin) color space
Informative event by JxlDecoderProcessInput: basic information such as image dimensions and extra channels. This event occurs max once per image.
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.
Informative event by 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. 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 JXL_DEC_FRAME_HEADER and other header events and earlier than full resolution pixel data.
An error occured, for example invalid input file or out of memory. TODO(lode): add function to get error information from decoder.
Informative event by JxlDecoderProcessInput: user extensions of the codestream header. This event occurs max once per image and always later than JXL_DEC_BASIC_INFO and earlier than any pixel data.
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. 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.
Informative event by JxlDecoderProcessInput: full frame 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 and always later than JXL_DEC_DC_IMAGE.
Informative event by JxlDecoderProcessInput: 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
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.
The decoder is able to decode a DC image and requests setting a DC output buffer using JxlDecoderSetDCOutBuffer. This occurs if 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.
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.
The decoder needs more input bytes to continue. In the next JxlDecoderProcessInput call, next_in and avail_in must point to more bytes to continue. If *avail_in is not 0, the new bytes must be appended to the *avail_in last previous bytes.
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.
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. This event is different than JXL_DEC_PREVIEW_HEADER because the latter only outputs the dimensions of the preview image.
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 needs more output buffer to continue encoding.
The encoder doesn’t (yet) support this.
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
Custom white point stored in JxlColorEncoding primaries_red_xy, primaries_green_xy and primaries_blue_xy.
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 JPEGXL 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 428-1
As specified in IEC 61966-2-1 sRGB
None of the other table entries describe the transfer function.
Use 1-bit packed in uint8_t, first pixel in LSB, padded to uint8_t per row. TODO(lode): support first in MSB, other padding.
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.
Use type uint32_t. May clip wide color gamut data.
Custom white point stored in JxlColorEncoding white_point.
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
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.
Creates an instance of 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 JxlDecoderSetDCOutBuffer. Requires the basic image information is available in the decoder.
Get the default pixel format for this decoder.
Deinitializes and frees JxlDecoder instance.
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.
Outputs the basic image information, such as image dimensions, bit depth and all other JxlBasicInfo fields, if available.
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 JxlDecoderGetICCProfileSize returns success. The output buffer must have at least as many bytes as given by JxlDecoderGetICCProfileSize.
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 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 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 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.
Returns the minimum size in bytes of the image output pixel buffer for the given format. This is the buffer for JxlDecoderSetImageOutBuffer. Requires the basic image information is available in the decoder.
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.
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.
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. @param dec decoder object @return 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. This value doesn’t provide information about how many bytes the decoder truly processed internally or how large the original JPEG XL codestream or file are.
Releases buffer which was provided with JxlDecoderSetJPEGBuffer.
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.
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 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.
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.
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.
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. @param dec decoder object @param data pointer to next bytes to read from @param size amount of bytes available starting from data @return JXL_DEC_ERROR if input was already set without releasing, JXL_DEC_SUCCESS otherwise
Sets output buffer for reconstructed JPEG codestream.
Enables or disables preserving of original orientation. Some images are encoded with an orientation tag indicating the image is rotated and/or mirrored (here called the original orientation).
Set the parallel runner for multithreading. May only be set before starting 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 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.
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 *avail_in parameter, but it is not guaranteed to be an upper bound nor a lower bound. 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.
Select for which informative events (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
Decoder library version.
Sets the buffer to read pixels from for the next image to encode. Must call JxlEncoderSetDimensions before JxlEncoderAddImageFrame.
Sets the buffer to read JPEG encoded bytes from for the next frame to encode.
Declares that this encoder will not encode anything further.
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.
Set the decoding speed tier for the provided options. Minimum is 0 (highest quality), and maximum is 4 (lowest quality). Default is 0.
Sets the distance level for lossy compression: target max butteraugli distance, lower = higher quality. Range: 0 .. 15. 0.0 = mathematically lossless (however, use JxlEncoderOptionsSetLossless to use true lossless). 1.0 = visually lossless. Recommended range: 0.5 .. 3.0. Default value: 1.0. If JxlEncoderOptionsSetLossless is used, this value is unused and implied to be 0.
Sets encoder effort/speed level without affecting decoding speed. Valid values are, from faster to slower speed: 3:falcon 4:cheetah 5:hare 6:wombat 7:squirrel 8:kitten 9:tortoise Default: squirrel (7).
Sets lossless/lossy mode for the provided options. Default is lossy.
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 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.
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.
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.
Configure the encoder to use the JPEG XL container format.
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.
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 basic 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 JPEGXL decoder.
Return value for JxlDecoderProcessInput. The values above 0x40 are optional informal events that can be subscribed to, they are never returned if they have not been registered with JxlDecoderSubscribeEvents.
Opaque structure that holds the JPEG XL encoder.
Opaque structure that holds frame specific encoding options for a JPEG XL encoder.
Return value for multiple encoder functions.
Ordering of multi-byte data.
Given type of an extra channel.
Callback function type for JxlDecoderSetImageOutCallback. @see JxlDecoderSetImageOutCallback for usage.
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. Numeric values match CICP (Rec. ITU-T H.273 | ISO/IEC 23091-2:2019(E)).
Renderig intent for color encoding, as specified in ISO 15076-1:2010
The result of JxlSignatureCheck.
Built-in transfer functions for color encoding. Numeric values match CICP (Rec. ITU-T H.273 | ISO/IEC 23091-2:2019(E)) unless specified otherwise.
Built-in whitepoints for color encoding. Numeric values match CICP (Rec. ITU-T H.273 | ISO/IEC 23091-2:2019(E)).
Allocating function for a memory region of a given size.
Deallocating function pointer type.