|
JXL_EXPORT uint32_t | JxlDecoderVersion (void) |
|
JXL_EXPORT JxlSignature | JxlSignatureCheck (const uint8_t *buf, size_t len) |
|
JXL_EXPORT JxlDecoder * | JxlDecoderCreate (const JxlMemoryManager *memory_manager) |
|
JXL_EXPORT void | JxlDecoderReset (JxlDecoder *dec) |
|
JXL_EXPORT void | JxlDecoderDestroy (JxlDecoder *dec) |
|
JXL_EXPORT void | JxlDecoderRewind (JxlDecoder *dec) |
|
JXL_EXPORT void | JxlDecoderSkipFrames (JxlDecoder *dec, size_t amount) |
|
JXL_EXPORT JxlDecoderStatus | JxlDecoderDefaultPixelFormat (const JxlDecoder *dec, JxlPixelFormat *format) |
|
JXL_EXPORT JxlDecoderStatus | JxlDecoderSetParallelRunner (JxlDecoder *dec, JxlParallelRunner parallel_runner, void *parallel_runner_opaque) |
|
JXL_EXPORT size_t | JxlDecoderSizeHintBasicInfo (const JxlDecoder *dec) |
|
JXL_EXPORT JxlDecoderStatus | JxlDecoderSubscribeEvents (JxlDecoder *dec, int events_wanted) |
|
JXL_EXPORT JxlDecoderStatus | JxlDecoderSetKeepOrientation (JxlDecoder *dec, JXL_BOOL keep_orientation) |
|
JXL_EXPORT JxlDecoderStatus | JxlDecoderProcessInput (JxlDecoder *dec) |
|
JXL_EXPORT JxlDecoderStatus | JxlDecoderSetInput (JxlDecoder *dec, const uint8_t *data, size_t size) |
|
JXL_EXPORT size_t | JxlDecoderReleaseInput (JxlDecoder *dec) |
|
JXL_EXPORT JxlDecoderStatus | JxlDecoderGetBasicInfo (const JxlDecoder *dec, JxlBasicInfo *info) |
|
JXL_EXPORT JxlDecoderStatus | JxlDecoderGetExtraChannelInfo (const JxlDecoder *dec, size_t index, JxlExtraChannelInfo *info) |
|
JXL_EXPORT JxlDecoderStatus | JxlDecoderGetExtraChannelName (const JxlDecoder *dec, size_t index, char *name, size_t size) |
|
JXL_EXPORT JxlDecoderStatus | JxlDecoderGetColorAsEncodedProfile (const JxlDecoder *dec, const JxlPixelFormat *format, JxlColorProfileTarget target, JxlColorEncoding *color_encoding) |
|
JXL_EXPORT JxlDecoderStatus | JxlDecoderGetICCProfileSize (const JxlDecoder *dec, const JxlPixelFormat *format, JxlColorProfileTarget target, size_t *size) |
|
JXL_EXPORT JxlDecoderStatus | JxlDecoderGetColorAsICCProfile (const JxlDecoder *dec, const JxlPixelFormat *format, JxlColorProfileTarget target, uint8_t *icc_profile, size_t size) |
|
JXL_EXPORT JxlDecoderStatus | JxlDecoderSetPreferredColorProfile (JxlDecoder *dec, const JxlColorEncoding *color_encoding) |
|
JXL_EXPORT JxlDecoderStatus | JxlDecoderPreviewOutBufferSize (const JxlDecoder *dec, const JxlPixelFormat *format, size_t *size) |
|
JXL_EXPORT JxlDecoderStatus | JxlDecoderSetPreviewOutBuffer (JxlDecoder *dec, const JxlPixelFormat *format, void *buffer, size_t size) |
|
JXL_EXPORT JxlDecoderStatus | JxlDecoderGetFrameHeader (const JxlDecoder *dec, JxlFrameHeader *header) |
|
JXL_EXPORT JxlDecoderStatus | JxlDecoderGetFrameName (const JxlDecoder *dec, char *name, size_t size) |
|
JXL_EXPORT JXL_DEPRECATED JxlDecoderStatus | JxlDecoderDCOutBufferSize (const JxlDecoder *dec, const JxlPixelFormat *format, size_t *size) |
|
JXL_EXPORT JXL_DEPRECATED JxlDecoderStatus | JxlDecoderSetDCOutBuffer (JxlDecoder *dec, const JxlPixelFormat *format, void *buffer, size_t size) |
|
JXL_EXPORT JxlDecoderStatus | JxlDecoderImageOutBufferSize (const JxlDecoder *dec, const JxlPixelFormat *format, size_t *size) |
|
JXL_EXPORT JxlDecoderStatus | JxlDecoderSetImageOutBuffer (JxlDecoder *dec, const JxlPixelFormat *format, void *buffer, size_t size) |
|
JXL_EXPORT JxlDecoderStatus | JxlDecoderSetImageOutCallback (JxlDecoder *dec, const JxlPixelFormat *format, JxlImageOutCallback callback, void *opaque) |
|
JXL_EXPORT JxlDecoderStatus | JxlDecoderExtraChannelBufferSize (const JxlDecoder *dec, const JxlPixelFormat *format, size_t *size, uint32_t index) |
|
JXL_EXPORT JxlDecoderStatus | JxlDecoderSetExtraChannelBuffer (JxlDecoder *dec, const JxlPixelFormat *format, void *buffer, size_t size, uint32_t index) |
|
JXL_EXPORT JxlDecoderStatus | JxlDecoderSetJPEGBuffer (JxlDecoder *dec, uint8_t *data, size_t size) |
|
JXL_EXPORT size_t | JxlDecoderReleaseJPEGBuffer (JxlDecoder *dec) |
|
JXL_EXPORT JxlDecoderStatus | JxlDecoderFlushImage (JxlDecoder *dec) |
|
Decoding API for JPEG XL.
Outputs the color profile as JPEG XL encoded structured data, if available. This is an alternative to an ICC Profile, which can represent a more limited amount of color spaces, but represents them exactly through enum values.
It is often possible to use JxlDecoderGetColorAsICCProfile as an alternative anyway. The following scenarios are possible:
- The JPEG XL image has an attached ICC Profile, in that case, the encoded structured data is not available, this function will return an error status and you must use JxlDecoderGetColorAsICCProfile instead.
- The JPEG XL image has an encoded structured color profile, and it represents an RGB or grayscale color space. This function will return it. You can still use JxlDecoderGetColorAsICCProfile as well as an alternative if desired, though depending on which RGB color space is represented, the ICC profile may be a close approximation. It is also not always feasible to deduce from an ICC profile which named color space it exactly represents, if any, as it can represent any arbitrary space.
- The JPEG XL image has an encoded structured color profile, and it indicates an unknown or xyb color space. In that case, JxlDecoderGetColorAsICCProfile is not available.
If you wish to render the image using a system that supports ICC profiles, use JxlDecoderGetColorAsICCProfile first. If you're looking for a specific color space possibly indicated in the JPEG XL image, use JxlDecoderGetColorAsEncodedProfile first.
- Parameters
-
dec | decoder object |
format | pixel format to output the data to. Only used for JXL_COLOR_PROFILE_TARGET_DATA, may be nullptr otherwise. |
target | whether to get the original color profile from the metadata or the color profile of the decoded pixels. |
color_encoding | struct to copy the information into, or NULL to only check whether the information is available through the return value. |
- Returns
- JXL_DEC_SUCCESS if the data is available and returned, JXL_DEC_NEED_MORE_INPUT if not yet available, JXL_DEC_ERROR in case the encoded structured color profile does not exist in the codestream.
Decodes JPEG XL file using the available bytes. Requires input has been set with JxlDecoderSetInput. After JxlDecoderProcessInput, input can optionally be released with JxlDecoderReleaseInput and then set again to next bytes in the stream. JxlDecoderReleaseInput returns how many bytes are not yet processed, before a next call to JxlDecoderProcessInput all unprocessed bytes must be provided again (the address need not match, but the contents must), and more bytes may be concatenated after the unprocessed bytes.
The returned status indicates whether the decoder needs more input bytes, or more output buffer for a certain type of output data. No matter what the returned status is (other than JXL_DEC_ERROR), new information, such as JxlDecoderGetBasicInfo, may have become available after this call. When the return value is not JXL_DEC_ERROR or JXL_DEC_SUCCESS, the decoding requires more JxlDecoderProcessInput calls to continue.
- Parameters
-
- Returns
- JXL_DEC_SUCCESS when decoding finished and all events handled.
-
JXL_DEC_ERROR when decoding failed, e.g. invalid codestream. TODO(lode) document the input data mechanism
-
JXL_DEC_NEED_MORE_INPUT more input data is necessary.
-
JXL_DEC_BASIC_INFO when basic info such as image dimensions is available and this informative event is subscribed to.
-
JXL_DEC_EXTENSIONS when JPEG XL codestream user extensions are available and this informative event is subscribed to.
-
JXL_DEC_COLOR_ENCODING when color profile information is available and this informative event is subscribed to.
-
JXL_DEC_PREVIEW_IMAGE when preview pixel information is available and output in the preview buffer.
-
JXL_DEC_DC_IMAGE when DC pixel information (8x8 downscaled version of the image) is available and output in the DC buffer.
-
JXL_DEC_FULL_IMAGE when all pixel information at highest detail is available and has been output in the pixel buffer.
JXL_EXPORT size_t JxlDecoderReleaseJPEGBuffer |
( |
JxlDecoder * |
dec | ) |
|
Releases buffer which was provided with JxlDecoderSetJPEGBuffer.
Calling JxlDecoderReleaseJPEGBuffer is required whenever a buffer is already set and a new buffer needs to be added with JxlDecoderSetJPEGBuffer, but is not required before JxlDecoderDestroy or JxlDecoderReset.
Calling JxlDecoderReleaseJPEGBuffer when no input is set is not an error and returns 0.
- Parameters
-
- Returns
- the amount of bytes the decoder has not yet written to of the data set by JxlDecoderSetJPEGBuffer, or 0 if no buffer is set or JxlDecoderReleaseJPEGBuffer was already called.
JXL_EXPORT void JxlDecoderRewind |
( |
JxlDecoder * |
dec | ) |
|
Rewinds decoder to the beginning. The same input must be given again from the beginning of the file and the decoder will emit events from the beginning again. When rewinding (as opposed to JxlDecoderReset), the decoder can keep state about the image, which it can use to skip to a requested frame more efficiently with JxlDecoderSkipFrames. After rewind, JxlDecoderSubscribeEvents can be used again, and it is feasible to leave out events that were already handled before, such as JXL_DEC_BASIC_INFO and JXL_DEC_COLOR_ENCODING, since they will provide the same information as before.
- Parameters
-
Sets pixel output callback. This is an alternative to JxlDecoderSetImageOutBuffer. This can be set when the JXL_DEC_FRAME event occurs, must be set when the JXL_DEC_NEED_IMAGE_OUT_BUFFER event occurs, and applies only for the current frame. Only one of JxlDecoderSetImageOutBuffer or JxlDecoderSetImageOutCallback may be used for the same frame, not both at the same time.
The callback will be called multiple times, to receive the image data in small chunks. The callback receives a horizontal stripe of pixel data, 1 pixel high, xsize pixels wide, called a scanline. The xsize here is not the same as the full image width, the scanline may be a partial section, and xsize may differ between calls. The user can then process and/or copy the partial scanline to an image buffer. The callback may be called simultaneously by different threads when using a threaded parallel runner, on different pixels.
If JxlDecoderFlushImage is not used, then each pixel will be visited exactly once by the different callback calls, during processing with one or more JxlDecoderProcessInput calls. These pixels are decoded to full detail, they are not part of a lower resolution or lower quality progressive pass, but the final pass.
If JxlDecoderFlushImage is used, then in addition each pixel will be visited zero or one times during the blocking JxlDecoderFlushImage call. Pixels visited as a result of JxlDecoderFlushImage may represent a lower resolution or lower quality intermediate progressive pass of the image. Any visited pixel will be of a quality at least as good or better than previous visits of this pixel. A pixel may be visited zero times if it cannot be decoded yet or if it was already decoded to full precision (this behavior is not guaranteed).
- Parameters
-
dec | decoder object |
format | format of the pixels. Object owned by user and its contents are copied internally. |
callback | the callback function receiving partial scanlines of pixel data. |
opaque | optional user data, which will be passed on to the callback, may be NULL. |
- Returns
- JXL_DEC_SUCCESS on success, JXL_DEC_ERROR on error, such as JxlDecoderSetImageOutBuffer already set.
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).
*) If keep_orientation is JXL_FALSE (the default): the decoder will perform work to undo the transformation. This ensures the decoded pixels will not be rotated or mirrored. The decoder will always set the orientation field of the JxlBasicInfo to JXL_ORIENT_IDENTITY to match the returned pixel data. The decoder may also swap xsize and ysize in the JxlBasicInfo compared to the values inside of the codestream, to correctly match the decoded pixel data, e.g. when a 90 degree rotation was performed.
*) If this option is JXL_TRUE: then the image is returned as-is, which may be rotated or mirrored, and the user must check the orientation field in JxlBasicInfo after decoding to correctly interpret the decoded pixel data. This may be faster to decode since the decoder doesn't have to apply the transformation, but can cause wrong display of the image if the orientation tag is not correctly taken into account by the user.
By default, this option is disabled, and the decoder automatically corrects the orientation.
This function must be called at the beginning, before decoding is performed.
- See also
- JxlBasicInfo for the orientation field, and
-
JxlOrientation for the possible values.
- Parameters
-
dec | decoder object |
keep_orientation | JXL_TRUE to enable, JXL_FALSE to disable. |
- Returns
- JXL_DEC_SUCCESS if no error, JXL_DEC_ERROR otherwise.
Sets the color profile to use for 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 JXL_COLOR_PROFILE_TARGET_DATA must still be queried to know the actual data format of the decoded pixels after decoding.
The intended use case of this function is for cases where you are using a color management system to parse the original ICC color profile (JXL_COLOR_PROFILE_TARGET_ORIGINAL), from this you know that the ICC profile represents one of the color profiles supported by JxlColorEncoding (such as sRGB, PQ or HLG): in that case it is beneficial (but not necessary) to use JxlDecoderSetPreferredColorProfile to match the parsed profile. The JXL decoder has no color management system built in, but can convert XYB color to any of the ones supported by JxlColorEncoding.
Can only be set after the JXL_DEC_COLOR_ENCODING event occurred and before any other event occurred, and can affect the result of JXL_COLOR_PROFILE_TARGET_DATA (but not of JXL_COLOR_PROFILE_TARGET_ORIGINAL), so should be used after getting JXL_COLOR_PROFILE_TARGET_ORIGINAL but before getting JXL_COLOR_PROFILE_TARGET_DATA. The color_encoding must be grayscale if num_color_channels from the basic info is 1, RGB if num_color_channels from the basic info is 3.
If JxlDecoderSetPreferredColorProfile is not used, then for images for which uses_original_profile is false and with ICC color profile, the decoder will choose linear sRGB for color images, linear grayscale for grayscale images. This function only sets a preference, since for other images the decoder has no choice what color profile to use, it is determined by the image.
- Parameters
-
dec | decoder object |
color_encoding | the default color encoding to set |
- Returns
- JXL_DEC_SUCCESS if the preference was set successfully, JXL_DEC_ERROR otherwise.
JXL_EXPORT void JxlDecoderSkipFrames |
( |
JxlDecoder * |
dec, |
|
|
size_t |
amount |
|
) |
| |
Makes the decoder skip the next amount
frames. It still needs to process the input, but will not output the frame events. It can be more efficient when skipping frames, and even more so when using this after JxlDecoderRewind. If the decoder is already processing a frame (could have emitted JXL_DEC_FRAME but not yet JXL_DEC_FULL_IMAGE), it starts skipping from the next frame. If the amount is larger than the amount of frames remaining in the image, all remaining frames are skipped. Calling this function multiple times adds the amount to skip to the already existing amount. A frame here is defined as a frame that without skipping emits events such as JXL_DEC_FRAME and JXL_FULL_IMAGE, frames that are internal to the file format but are not rendered as part of an animation, or are not the final still frame of a still image, are not counted.
- Parameters
-
dec | decoder object |
amount | the amount of frames to skip |