Loading...
Searching...
No Matches
JxlEncoderOutputProcessor Struct Reference
JPEG XL library (libjxl) » JPEG XL Encoder API

`#include <encode.h>`

## Public Attributes

void * | opaque
void *(* | get_buffer )(void *opaque, size_t *size)
void(* | release_buffer )(void *opaque, size_t written_bytes)
void(* | seek )(void *opaque, uint64_t position)
void(* | set_finalized_position )(void *opaque, uint64_t finalized_position)

## Detailed Description

The JxlEncoderOutputProcessor structure provides an interface for the encoder's output processing. Users of the library, who want to do streaming encoding, should implement the required callbacks for buffering, writing, seeking (if supported), and setting a finalized position during the encoding process.

At a high level, the processor can be in one of two states:

- With an active buffer: This indicates that a buffer has been acquired using `get_buffer` and encoded data can be written to it.
- Without an active buffer: In this state, no data can be written. A new buffer must be acquired after releasing any previously active buffer.

The library will not acquire more than one buffer at a given time.

The state of the processor includes `position` and `finalized position`, which have the following meaning.

- position: Represents the current position, in bytes, within the output stream where the encoded data will be written next. This position moves forward with each `release_buffer` call as data is written, and can also be adjusted through the optional seek callback, if provided. At this position the next write will occur.
- finalized position: A position in the output stream that ensures all bytes before this point are finalized and won't be changed by later writes.

All fields but `seek` are required, `seek` is optional and can be NULL.

## Member Data Documentation

## get_buffer

void *(* JxlEncoderOutputProcessor::get_buffer) (void *opaque, size_t *size)

Required. Acquires a buffer at the current position into which the library will write the output data.

If the `size` argument points to 0 and the returned value is NULL, this will be interpreted as asking the output writing to stop. In such a case, the library will return an error. The client is expected to set the size of the returned buffer based on the suggested `size` when this function is called.

Parameters

  opaque | user supplied parameters to the callback
  size | points to a suggested buffer size when called; must be set to the size of the returned buffer once the function returns.

Returns
  a pointer to the acquired buffer or NULL to indicate a stop condition.

## opaque

void* JxlEncoderOutputProcessor::opaque

Required. An opaque pointer that the client can use to store custom data. This data will be passed to the associated callback functions.

## release_buffer

void(* JxlEncoderOutputProcessor::release_buffer) (void *opaque, size_t written_bytes)

Required. Notifies the user of library that the current buffer's data has been written and can be released. This function should advance the current position of the buffer by `written_bytes` number of bytes.

Parameters

  opaque | user supplied parameters to the callback
  written_bytes | the number of bytes written to the buffer.

## seek

void(* JxlEncoderOutputProcessor::seek) (void *opaque, uint64_t position)

Optional, can be NULL Seeks to a specific position in the output. This function is optional and can be set to NULL if the output doesn't support seeking. Can only be done when there is no buffer. Cannot be used to seek before the finalized position.

Parameters

  opaque | user supplied parameters to the callback
  position | the position to seek to, in bytes.

## set_finalized_position

void(* JxlEncoderOutputProcessor::set_finalized_position) (void *opaque, uint64_t finalized_position)

Required. Sets a finalized position on the output data, at a specific position. Seeking will never request a position before the finalized position.

Will only be called if there is no active buffer.

Parameters

  opaque | user supplied parameters to the callback
  finalized_position | the position, in bytes, where the finalized position should be set.

The documentation for this struct was generated from the following file:

- jxl/encode.h