Function libjxl_sys::JxlEncoderAddImageFrame

source · [−]
pub unsafe extern "C" fn JxlEncoderAddImageFrame(
    frame_settings: *const JxlEncoderFrameSettings, 
    pixel_format: *const JxlPixelFormat, 
    buffer: *const c_void, 
    size: usize
) -> JxlEncoderStatus
Expand description

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

Currently only some data types for pixel formats are supported:

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

Note: the sample data type in pixel_format is allowed to be different from what is described in the JxlBasicInfo. The type in pixel_format describes the format of the uncompressed pixel buffer. The bits_per_sample and exponent_bits_per_sample in the JxlBasicInfo describes what will actually be encoded in the JPEG XL codestream. For example, to encode a 12-bit image, you would set bits_per_sample to 12, and you could use e.g. JXL_TYPE_UINT16 (where the values are rescaled to 16-bit, i.e. multiplied by 65535/4095) or JXL_TYPE_FLOAT (where the values are rescaled to 0..1, i.e. multiplied by 1.f/4095.f). While it is allowed, it is obviously not recommended to use a pixel_format with lower precision than what is specified in the JxlBasicInfo.

We support interleaved channels as described by the JxlPixelFormat:

  • single-channel data, e.g. grayscale
  • single-channel + alpha
  • trichromatic, e.g. RGB
  • trichromatic + alpha

Extra channels not handled here need to be set by @ref JxlEncoderSetExtraChannelBuffer. If the image has alpha, and alpha is not passed here, it will implicitly be set to all-opaque (an alpha value of 1.0 everywhere).

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). Sample values in floating-point pixel formats are allowed to be outside the nominal range, e.g. to represent out-of-sRGB-gamut colors in the uses_original_profile=false case. They are however not allowed to be NaN or +-infinity.

If this is the last frame, @ref JxlEncoderCloseInput or @ref JxlEncoderCloseFrames must be called before the next @ref JxlEncoderProcessOutput call.

@param frame_settings set of options and metadata for this frame. Also includes reference to the encoder object. @param pixel_format format for pixels. Object owned by the caller and its contents are copied internally. @param buffer buffer type to input the pixel data from. Owned by the caller and its contents are copied internally. @param size size of buffer in bytes. This size should match what is implied by the frame dimensions and the pixel format. @return JXL_ENC_SUCCESS on success, JXL_ENC_ERROR on error