LIBJXL
Typedefs | Enumerations | Functions
encode.h File Reference

Encoding API for JPEG XL. More...

#include "jxl/decode.h"
#include "jxl/jxl_export.h"
#include "jxl/memory_manager.h"
#include "jxl/parallel_runner.h"
Include dependency graph for encode.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Typedefs

typedef struct JxlEncoderStruct JxlEncoder
 
typedef struct JxlEncoderOptionsStruct JxlEncoderOptions
 

Enumerations

enum  JxlEncoderStatus { JXL_ENC_SUCCESS = 0 , JXL_ENC_ERROR = 1 , JXL_ENC_NEED_MORE_OUTPUT = 2 , JXL_ENC_NOT_SUPPORTED = 3 }
 

Functions

JXL_EXPORT uint32_t JxlEncoderVersion (void)
 
JXL_EXPORT JxlEncoderJxlEncoderCreate (const JxlMemoryManager *memory_manager)
 
JXL_EXPORT void JxlEncoderReset (JxlEncoder *enc)
 
JXL_EXPORT void JxlEncoderDestroy (JxlEncoder *enc)
 
JXL_EXPORT JxlEncoderStatus JxlEncoderSetParallelRunner (JxlEncoder *enc, JxlParallelRunner parallel_runner, void *parallel_runner_opaque)
 
JXL_EXPORT JxlEncoderStatus JxlEncoderProcessOutput (JxlEncoder *enc, uint8_t **next_out, size_t *avail_out)
 
JXL_EXPORT JxlEncoderStatus JxlEncoderAddJPEGFrame (const JxlEncoderOptions *options, const uint8_t *buffer, size_t size)
 
JXL_EXPORT JxlEncoderStatus JxlEncoderAddImageFrame (const JxlEncoderOptions *options, const JxlPixelFormat *pixel_format, const void *buffer, size_t size)
 
JXL_EXPORT void JxlEncoderCloseInput (JxlEncoder *enc)
 
JXL_EXPORT JxlEncoderStatus JxlEncoderSetColorEncoding (JxlEncoder *enc, const JxlColorEncoding *color)
 
JXL_EXPORT JxlEncoderStatus JxlEncoderSetICCProfile (JxlEncoder *enc, const uint8_t *icc_profile, size_t size)
 
JXL_EXPORT void JxlEncoderInitBasicInfo (JxlBasicInfo *info)
 
JXL_EXPORT JxlEncoderStatus JxlEncoderSetBasicInfo (JxlEncoder *enc, const JxlBasicInfo *info)
 
JXL_EXPORT JxlEncoderStatus JxlEncoderStoreJPEGMetadata (JxlEncoder *enc, JXL_BOOL store_jpeg_metadata)
 
JXL_EXPORT JxlEncoderStatus JxlEncoderUseContainer (JxlEncoder *enc, JXL_BOOL use_container)
 
JXL_EXPORT JxlEncoderStatus JxlEncoderOptionsSetLossless (JxlEncoderOptions *options, JXL_BOOL lossless)
 
JXL_EXPORT JxlEncoderStatus JxlEncoderOptionsSetDecodingSpeed (JxlEncoderOptions *options, int tier)
 
JXL_EXPORT JxlEncoderStatus JxlEncoderOptionsSetEffort (JxlEncoderOptions *options, int effort)
 
JXL_EXPORT JxlEncoderStatus JxlEncoderOptionsSetDistance (JxlEncoderOptions *options, float distance)
 
JXL_EXPORT JxlEncoderOptionsJxlEncoderOptionsCreate (JxlEncoder *enc, const JxlEncoderOptions *source)
 
JXL_EXPORT void JxlColorEncodingSetToSRGB (JxlColorEncoding *color_encoding, JXL_BOOL is_gray)
 
JXL_EXPORT void JxlColorEncodingSetToLinearSRGB (JxlColorEncoding *color_encoding, JXL_BOOL is_gray)
 

Detailed Description

Encoding API for JPEG XL.

Typedef Documentation

◆ JxlEncoder

typedef struct JxlEncoderStruct JxlEncoder

Opaque structure that holds the JPEG XL encoder.

Allocated and initialized with JxlEncoderCreate(). Cleaned up and deallocated with JxlEncoderDestroy().

◆ JxlEncoderOptions

typedef struct JxlEncoderOptionsStruct JxlEncoderOptions

Opaque structure that holds frame specific encoding options for a JPEG XL encoder.

Allocated and initialized with JxlEncoderOptionsCreate(). Cleaned up and deallocated when the encoder is destroyed with JxlEncoderDestroy().

Enumeration Type Documentation

◆ JxlEncoderStatus

Return value for multiple encoder functions.

Enumerator
JXL_ENC_SUCCESS 

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

JXL_ENC_ERROR 

An error occurred, for example out of memory.

JXL_ENC_NEED_MORE_OUTPUT 

The encoder needs more output buffer to continue encoding.

JXL_ENC_NOT_SUPPORTED 

The encoder doesn't (yet) support this.

Function Documentation

◆ JxlColorEncodingSetToLinearSRGB()

JXL_EXPORT void JxlColorEncodingSetToLinearSRGB ( JxlColorEncoding color_encoding,
JXL_BOOL  is_gray 
)

Sets a color encoding to be linear sRGB.

Parameters
color_encodingcolor encoding instance.
is_graywhether the color encoding should be gray scale or color.

◆ JxlColorEncodingSetToSRGB()

JXL_EXPORT void JxlColorEncodingSetToSRGB ( JxlColorEncoding color_encoding,
JXL_BOOL  is_gray 
)

Sets a color encoding to be sRGB.

Parameters
color_encodingcolor encoding instance.
is_graywhether the color encoding should be gray scale or color.

◆ JxlEncoderAddImageFrame()

JXL_EXPORT JxlEncoderStatus JxlEncoderAddImageFrame ( const JxlEncoderOptions options,
const JxlPixelFormat pixel_format,
const void *  buffer,
size_t  size 
)

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

Currently only some pixel formats are supported:

  • JXL_TYPE_UINT8
  • JXL_TYPE_UINT16
  • JXL_TYPE_FLOAT16, with nominal range 0..1
  • JXL_TYPE_FLOAT, with nominal range 0..1

The color profile of the pixels depends on the value of uses_original_profile in the JxlBasicInfo. If true, the pixels are assumed to be encoded in the original profile that is set with JxlEncoderSetColorEncoding or JxlEncoderSetICCProfile. If false, the pixels are assumed to be nonlinear sRGB for integer data types (JXL_TYPE_UINT8, JXL_TYPE_UINT16), and linear sRGB for floating point data types (JXL_TYPE_FLOAT16, JXL_TYPE_FLOAT).

Parameters
optionsset of encoder options to use when encoding the frame.
pixel_formatformat for pixels. Object owned by the caller and its contents are copied internally.
bufferbuffer type to input the pixel data from. Owned by the caller and its contents are copied internally.
sizesize of buffer in bytes.
Returns
JXL_ENC_SUCCESS on success, JXL_ENC_ERROR on error

◆ JxlEncoderAddJPEGFrame()

JXL_EXPORT JxlEncoderStatus JxlEncoderAddJPEGFrame ( const JxlEncoderOptions options,
const uint8_t *  buffer,
size_t  size 
)

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

If JxlEncoderSetBasicInfo has not yet been called, calling JxlEncoderAddJPEGFrame will implicitly call it with the parameters of the added JPEG frame.

If JxlEncoderSetColorEncoding or JxlEncoderSetICCProfile has not yet been called, calling JxlEncoderAddJPEGFrame will implicitly call it with the parameters of the added JPEG frame.

If the encoder is set to store JPEG reconstruction metadata using JxlEncoderStoreJPEGMetadata and a single JPEG frame is added, it will be possible to losslessly reconstruct the JPEG codestream.

Parameters
optionsset of encoder options to use when encoding the frame.
bufferbytes to read JPEG from. Owned by the caller and its contents are copied internally.
sizesize of buffer in bytes.
Returns
JXL_ENC_SUCCESS on success, JXL_ENC_ERROR on error

◆ JxlEncoderCloseInput()

JXL_EXPORT void JxlEncoderCloseInput ( JxlEncoder enc)

Declares that this encoder will not encode anything further.

Must be called between JxlEncoderAddImageFrame/JPEGFrame of the last frame and the next call to JxlEncoderProcessOutput, or JxlEncoderProcessOutput won't output the last frame correctly.

Parameters
encencoder object.

◆ JxlEncoderCreate()

JXL_EXPORT JxlEncoder * JxlEncoderCreate ( const JxlMemoryManager memory_manager)

Creates an instance of JxlEncoder and initializes it.

memory_manager will be used for all the library dynamic allocations made from this instance. The parameter may be NULL, in which case the default allocator will be used. See jpegxl/memory_manager.h for details.

Parameters
memory_managercustom allocator function. It may be NULL. The memory manager will be copied internally.
Returns
NULL if the instance can not be allocated or initialized
pointer to initialized JxlEncoder otherwise

◆ JxlEncoderDestroy()

JXL_EXPORT void JxlEncoderDestroy ( JxlEncoder enc)

Deinitializes and frees JxlEncoder instance.

Parameters
encinstance to be cleaned up and deallocated.

◆ JxlEncoderInitBasicInfo()

JXL_EXPORT void JxlEncoderInitBasicInfo ( JxlBasicInfo 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.

Parameters
infoglobal image metadata. Object owned by the caller.

◆ JxlEncoderOptionsCreate()

JXL_EXPORT JxlEncoderOptions * JxlEncoderOptionsCreate ( JxlEncoder enc,
const JxlEncoderOptions source 
)

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

The returned pointer is an opaque struct tied to the encoder and it will be deallocated by the encoder when JxlEncoderDestroy() is called. For functions taking both a JxlEncoder and a JxlEncoderOptions, only JxlEncoderOptions created with this function for the same encoder instance can be used.

Parameters
encencoder object.
sourcesource options to copy initial values from, or NULL to get defaults initialized to defaults.
Returns
the opaque struct pointer identifying a new set of encoder options.

◆ JxlEncoderOptionsSetDecodingSpeed()

JXL_EXPORT JxlEncoderStatus JxlEncoderOptionsSetDecodingSpeed ( JxlEncoderOptions options,
int  tier 
)

Set the decoding speed tier for the provided options. Minimum is 0 (highest quality), and maximum is 4 (lowest quality). Default is 0.

Parameters
optionsset of encoder options to update with the new decoding speed tier.
tierthe decoding speed tier to set.
Returns
JXL_ENC_SUCCESS if the operation was successful, JXL_ENC_ERROR otherwise.

◆ JxlEncoderOptionsSetDistance()

JXL_EXPORT JxlEncoderStatus JxlEncoderOptionsSetDistance ( JxlEncoderOptions options,
float  distance 
)

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.

Parameters
optionsset of encoder options to update with the new mode.
distancethe distance value to set.
Returns
JXL_ENC_SUCCESS if the operation was successful, JXL_ENC_ERROR otherwise.

◆ JxlEncoderOptionsSetEffort()

JXL_EXPORT JxlEncoderStatus JxlEncoderOptionsSetEffort ( JxlEncoderOptions options,
int  effort 
)

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

Parameters
optionsset of encoder options to update with the new mode.
effortthe effort value to set.
Returns
JXL_ENC_SUCCESS if the operation was successful, JXL_ENC_ERROR otherwise.

◆ JxlEncoderOptionsSetLossless()

JXL_EXPORT JxlEncoderStatus JxlEncoderOptionsSetLossless ( JxlEncoderOptions options,
JXL_BOOL  lossless 
)

Sets lossless/lossy mode for the provided options. Default is lossy.

Parameters
optionsset of encoder options to update with the new mode
losslesswhether the options should be lossless
Returns
JXL_ENC_SUCCESS if the operation was successful, JXL_ENC_ERROR otherwise.

◆ JxlEncoderProcessOutput()

JXL_EXPORT JxlEncoderStatus JxlEncoderProcessOutput ( JxlEncoder enc,
uint8_t **  next_out,
size_t *  avail_out 
)

Encodes JPEG XL file using the available bytes. *avail_out indicates how many output bytes are available, and *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.

The returned status indicates whether the encoder needs more output bytes. When the return value is not JXL_ENC_ERROR or JXL_ENC_SUCCESS, the encoding requires more JxlEncoderProcessOutput calls to continue.

Parameters
encencoder object.
next_outpointer to next bytes to write to.
avail_outamount of bytes available starting from *next_out.
Returns
JXL_ENC_SUCCESS when encoding finished and all events handled.
JXL_ENC_ERROR when encoding failed, e.g. invalid input.
JXL_ENC_NEED_MORE_OUTPUT more output buffer is necessary.

◆ JxlEncoderReset()

JXL_EXPORT void JxlEncoderReset ( JxlEncoder enc)

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.

Parameters
encinstance to be re-initialized.

◆ JxlEncoderSetBasicInfo()

JXL_EXPORT JxlEncoderStatus JxlEncoderSetBasicInfo ( JxlEncoder enc,
const JxlBasicInfo info 
)

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

Parameters
encencoder object.
infoglobal image metadata. Object owned by the caller and its contents are copied internally.
Returns
JXL_ENC_SUCCESS if the operation was successful, JXL_ENC_ERROR or JXL_ENC_NOT_SUPPORTED otherwise

◆ JxlEncoderSetColorEncoding()

JXL_EXPORT JxlEncoderStatus JxlEncoderSetColorEncoding ( JxlEncoder enc,
const JxlColorEncoding color 
)

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 JxlColorEncoding, while the other sets it as ICC binary data.

Parameters
encencoder object.
colorcolor encoding. Object owned by the caller and its contents are copied internally.
Returns
JXL_ENC_SUCCESS if the operation was successful, JXL_ENC_ERROR or JXL_ENC_NOT_SUPPORTED otherwise

◆ JxlEncoderSetICCProfile()

JXL_EXPORT JxlEncoderStatus JxlEncoderSetICCProfile ( JxlEncoder enc,
const uint8_t *  icc_profile,
size_t  size 
)

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

Parameters
encencoder object.
icc_profilebytes of the original ICC profile
sizesize of the icc_profile buffer in bytes
Returns
JXL_ENC_SUCCESS if the operation was successful, JXL_ENC_ERROR or JXL_ENC_NOT_SUPPORTED otherwise

◆ JxlEncoderSetParallelRunner()

JXL_EXPORT JxlEncoderStatus JxlEncoderSetParallelRunner ( JxlEncoder enc,
JxlParallelRunner  parallel_runner,
void *  parallel_runner_opaque 
)

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

Parameters
encencoder object.
parallel_runnerfunction pointer to runner for multithreading. It may be NULL to use the default, single-threaded, runner. A multithreaded runner should be set to reach fast performance.
parallel_runner_opaqueopaque pointer for parallel_runner.
Returns
JXL_ENC_SUCCESS if the runner was set, JXL_ENC_ERROR otherwise (the previous runner remains set).

◆ JxlEncoderStoreJPEGMetadata()

JXL_EXPORT JxlEncoderStatus JxlEncoderStoreJPEGMetadata ( JxlEncoder enc,
JXL_BOOL  store_jpeg_metadata 
)

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

The encoder must be configured to use the JPEG XL container format using JxlEncoderUseContainer for this to have any effect.

If this is set to true and a single JPEG frame is added, it will be possible to losslessly reconstruct the JPEG codestream.

Parameters
encencoder object.
store_jpeg_metadatatrue if the encoder should store JPEG metadata.
Returns
JXL_ENC_SUCCESS if the operation was successful, JXL_ENC_ERROR otherwise.

◆ JxlEncoderUseContainer()

JXL_EXPORT JxlEncoderStatus JxlEncoderUseContainer ( JxlEncoder enc,
JXL_BOOL  use_container 
)

Configure the encoder to use the JPEG XL container format.

Using the JPEG XL container format allows to store metadata such as JPEG reconstruction (JxlEncoderStoreJPEGMetadata) or other metadata like EXIF; but it adds a few bytes to the encoded file for container headers even if there is no extra metadata.

Parameters
encencoder object.
use_containertrue if the encoder should output the JPEG XL container format.
Returns
JXL_ENC_SUCCESS if the operation was successful, JXL_ENC_ERROR otherwise.

◆ JxlEncoderVersion()

JXL_EXPORT uint32_t JxlEncoderVersion ( void  )

Encoder library version.

Returns
the encoder library version as an integer: MAJOR_VERSION * 1000000 + MINOR_VERSION * 1000 + PATCH_VERSION. For example, version 1.2.3 would return 1002003.