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.
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.
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.
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, …)
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.
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.
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.
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)
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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 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 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 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.
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.
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.
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.
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.
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.
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.
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.
@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.
@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.
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 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 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.
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.
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.
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.
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.
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.
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.
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.
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:
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.
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.