Common API concepts

group Common API concepts

Defines

JXL_BOOL

A portable bool replacement.

JXL_BOOL is a “documentation” type: actually it is int, but in API it denotes a type, whose only values are JXL_TRUE and JXL_FALSE.

JXL_TRUE

Portable true replacement.

JXL_FALSE

Portable false replacement.

TO_JXL_BOOL(C)

Converts of bool-like value to either JXL_TRUE or JXL_FALSE.

FROM_JXL_BOOL(C)

Converts JXL_BOOL to C++ bool.

Typedefs

typedef void *(*jpegxl_alloc_func)(void *opaque, size_t size)

Allocating function for a memory region of a given size.

Allocates a contiguous memory region of size size bytes. The returned memory may not be aligned to a specific size or initialized at all.

Param opaque:

custom memory manager handle provided by the caller.

Param size:

in bytes of the requested memory region.

Return:

NULL if the memory can not be allocated,

Return:

pointer to the memory otherwise.

typedef void (*jpegxl_free_func)(void *opaque, void *address)

Deallocating function pointer type.

This function MUST do nothing if address is NULL.

Param opaque:

custom memory manager handle provided by the caller.

Param address:

memory region pointer returned by jpegxl_alloc_func, or NULL.

typedef struct JxlMemoryManagerStruct JxlMemoryManager

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

typedef char JxlBoxType[4]

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

Enums

enum JxlDataType

Data type for the sample values per channel per pixel.

Values:

enumerator JXL_TYPE_FLOAT

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.

enumerator JXL_TYPE_UINT8

Use type uint8_t. May clip wide color gamut data.

enumerator JXL_TYPE_UINT16

Use type uint16_t. May clip wide color gamut data.

enumerator JXL_TYPE_FLOAT16

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

enum JxlEndianness

Ordering of multi-byte data.

Values:

enumerator JXL_NATIVE_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.

enumerator JXL_LITTLE_ENDIAN

Force little endian

enumerator JXL_BIG_ENDIAN

Force big endian

enum JxlBitDepthType

Settings for the interpretation of UINT input and output buffers. (buffers using a FLOAT data type are not affected by this)

Values:

enumerator JXL_BIT_DEPTH_FROM_PIXEL_FORMAT

This is the default setting, where the encoder expects the input pixels to use the full range of the pixel format data type (e.g. for UINT16, the input range is 0 .. 65535 and the value 65535 is mapped to 1.0 when converting to float), and the decoder uses the full range to output pixels. If the bit depth in the basic info is different from this, the encoder expects the values to be rescaled accordingly (e.g. multiplied by 65535/4095 for a 12-bit image using UINT16 input data type).

enumerator JXL_BIT_DEPTH_FROM_CODESTREAM

If this setting is selected, the encoder expects the input pixels to be in the range defined by the bits_per_sample value of the basic info (e.g. for 12-bit images using UINT16 input data types, the allowed range is 0 .. 4095 and the value 4095 is mapped to 1.0 when converting to float), and the decoder outputs pixels in this range.

enumerator JXL_BIT_DEPTH_CUSTOM

This setting can only be used in the decoder to select a custom range for pixel output

struct JxlMemoryManagerStruct

#include <memory_manager.h>

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

Public Members

void *opaque

The opaque pointer that will be passed as the first parameter to all the functions in this struct.

jpegxl_alloc_func alloc

Memory allocation function. This can be NULL if and only if also the free() member in this class is NULL. All dynamic memory will be allocated and freed with these functions if they are not NULL, otherwise with the standard malloc/free.

jpegxl_free_func free

Free function matching the alloc() member.

struct JxlPixelFormat

#include <types.h>

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): support different channel orders if needed (RGB, BGR, …)

Public Members

uint32_t num_channels

Amount of channels available in a pixel buffer. 1: single-channel data, e.g. grayscale or a single extra channel 2: single-channel + alpha 3: trichromatic, e.g. RGB 4: trichromatic + alpha TODO(lode): this needs finetuning. It is not yet defined how the user chooses output color space. CMYK+alpha needs 5 channels.

JxlDataType data_type

Data type of each channel.

JxlEndianness endianness

Whether multi-byte data types are represented in big endian or little endian format. This applies to JXL_TYPE_UINT16 and JXL_TYPE_FLOAT.

size_t align

Align scanlines to a multiple of align bytes, or 0 to require no alignment at all (which has the same effect as value 1)

struct JxlBitDepth

#include <types.h>

Data type for describing the interpretation of the input and output buffers in terms of the range of allowed input and output pixel values.

Public Members

JxlBitDepthType type

Bit depth setting, see comment on JxlBitDepthType

uint32_t bits_per_sample

Custom bits per sample

uint32_t exponent_bits_per_sample

Custom exponent bits per sample