Butteraugli metric
JPEG XL library (libjxl)
Collaboration diagram for Butteraugli metric:

## Files

file | butteraugli.h
| Butteraugli API for JPEG XL.
file | butteraugli_cxx.h
| C++ header-only helper for butteraugli.h.

## Classes

struct | JxlButteraugliApiDestroyStruct
struct | JxlButteraugliResultDestroyStruct

## Typedefs

typedef struct JxlButteraugliApiStruct | JxlButteraugliApi
typedef struct JxlButteraugliResultStruct | JxlButteraugliResult
typedef std::unique_ptr< JxlButteraugliApi, JxlButteraugliApiDestroyStruct > | JxlButteraugliApiPtr
typedef std::unique_ptr< JxlButteraugliResult, JxlButteraugliResultDestroyStruct > | JxlButteraugliResultPtr

## Functions

JXL_EXPORT void | JxlButteraugliResultDestroy (JxlButteraugliResult *result)
JXL_EXPORT JxlButteraugliApi * | JxlButteraugliApiCreate (const JxlMemoryManager *memory_manager)
JXL_EXPORT void | JxlButteraugliApiSetParallelRunner (JxlButteraugliApi *api, JxlParallelRunner parallel_runner, void *parallel_runner_opaque)
JXL_EXPORT void | JxlButteraugliApiSetHFAsymmetry (JxlButteraugliApi *api, float v)
JXL_EXPORT void | JxlButteraugliApiSetIntensityTarget (JxlButteraugliApi *api, float v)
JXL_EXPORT void | JxlButteraugliApiDestroy (JxlButteraugliApi *api)
JXL_EXPORT JxlButteraugliResult * | JxlButteraugliCompute (const JxlButteraugliApi *api, uint32_t xsize, uint32_t ysize, const JxlPixelFormat *pixel_format_orig, const void *buffer_orig, size_t size_orig, const JxlPixelFormat *pixel_format_dist, const void *buffer_dist, size_t size_dist)
JXL_EXPORT float | JxlButteraugliResultGetMaxDistance (const JxlButteraugliResult *result)
JXL_EXPORT float | JxlButteraugliResultGetDistance (const JxlButteraugliResult *result, float pnorm)
JXL_EXPORT void | JxlButteraugliResultGetDistmap (const JxlButteraugliResult *result, const float **buffer, uint32_t *row_stride)

## Detailed Description

## Typedef Documentation

## JxlButteraugliApi

typedef struct JxlButteraugliApiStruct JxlButteraugliApi

Opaque structure that holds a butteraugli API.

Allocated and initialized with JxlButteraugliApiCreate(). Cleaned up and deallocated with JxlButteraugliApiDestroy().

## JxlButteraugliApiPtr

typedef std::unique_ptr<JxlButteraugliApi, JxlButteraugliApiDestroyStruct> JxlButteraugliApiPtr

std::unique_ptr<> type that calls JxlButteraugliApiDestroy() when releasing the pointer.

Use this helper type from C++ sources to ensure the api is destroyed and their internal resources released.

## JxlButteraugliResult

typedef struct JxlButteraugliResultStruct JxlButteraugliResult

Opaque structure that holds intermediary butteraugli results.

Allocated and initialized with JxlButteraugliCompute(). Cleaned up and deallocated with JxlButteraugliResultDestroy().

## JxlButteraugliResultPtr

typedef std::unique_ptr<JxlButteraugliResult, JxlButteraugliResultDestroyStruct> JxlButteraugliResultPtr

std::unique_ptr<> type that calls JxlButteraugliResultDestroy() when releasing the pointer.

Use this helper type from C++ sources to ensure the result object is destroyed and their internal resources released.

## Function Documentation

## JxlButteraugliApiCreate()

JXL_EXPORT JxlButteraugliApi * JxlButteraugliApiCreate | ( | const JxlMemoryManager * | memory_manager | ) |

Creates an instance of JxlButteraugliApi 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 jxl/memory_manager.h for details.

Parameters

  memory_manager | custom 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

## JxlButteraugliApiDestroy()

JXL_EXPORT void JxlButteraugliApiDestroy | ( | JxlButteraugliApi * | api | ) |

Deinitializes and frees JxlButteraugliApi instance.

Parameters

  api | instance to be cleaned up and deallocated.

## JxlButteraugliApiSetHFAsymmetry()

JXL_EXPORT void JxlButteraugliApiSetHFAsymmetry | ( | JxlButteraugliApi * | api,
|  | float | v
| ) |  |

Set the hf_asymmetry option for butteraugli.

Parameters

  api | api instance.
  v | new hf_asymmetry value.

## JxlButteraugliApiSetIntensityTarget()

JXL_EXPORT void JxlButteraugliApiSetIntensityTarget | ( | JxlButteraugliApi * | api,
|  | float | v
| ) |  |

Set the intensity_target option for butteraugli.

Parameters

  api | api instance.
  v | new intensity_target value.

## JxlButteraugliApiSetParallelRunner()

JXL_EXPORT void JxlButteraugliApiSetParallelRunner | ( | JxlButteraugliApi * | api,
|  | JxlParallelRunner | parallel_runner,
|  | void * | parallel_runner_opaque
| ) |  |

Set the parallel runner for multithreading.

Parameters

  api | api instance.
  parallel_runner | function pointer to runner for multithreading. A multithreaded runner should be set to reach fast performance.
  parallel_runner_opaque | opaque pointer for parallel_runner.

## JxlButteraugliCompute()

JXL_EXPORT JxlButteraugliResult * JxlButteraugliCompute | ( | const JxlButteraugliApi * | api,
|  | uint32_t | xsize,
|  | uint32_t | ysize,
|  | const JxlPixelFormat * | pixel_format_orig,
|  | const void * | buffer_orig,
|  | size_t | size_orig,
|  | const JxlPixelFormat * | pixel_format_dist,
|  | const void * | buffer_dist,
|  | size_t | size_dist
| ) |  |

Computes intermediary butteraugli result between an original image and a distortion.

Parameters

  api | api instance for this computation.
  xsize | width of the compared images.
  ysize | height of the compared images.
  pixel_format_orig | pixel format for original image.
  buffer_orig | pixel data for original image.
  size_orig | size of buffer_orig in bytes.
  pixel_format_dist | pixel format for distortion.
  buffer_dist | pixel data for distortion.
  size_dist | size of buffer_dist in bytes.

Returns
  `NULL` if the results can not be computed or initialized.
  pointer to initialized and computed intermediary result.

## JxlButteraugliResultDestroy()

JXL_EXPORT void JxlButteraugliResultDestroy | ( | JxlButteraugliResult * | result | ) |

Deinitializes and frees JxlButteraugliResult instance.

Parameters

  result | instance to be cleaned up and deallocated.

## JxlButteraugliResultGetDistance()

JXL_EXPORT float JxlButteraugliResultGetDistance | ( | const JxlButteraugliResult * | result,
|  | float | pnorm
| ) |  |

Computes a butteraugli distance based on an intermediary butteraugli result.

Parameters

  result | intermediary result instance.
  pnorm | pnorm to calculate.

Returns
  distance using the given pnorm.

## JxlButteraugliResultGetDistmap()

JXL_EXPORT void JxlButteraugliResultGetDistmap | ( | const JxlButteraugliResult * | result,
|  | const float ** | buffer,
|  | uint32_t * | row_stride
| ) |  |

Get a pointer to the distmap in the result.

Parameters

  result | intermediary result instance.
  buffer | will be set to the distmap. The distance value for (x,y) will be available at buffer + y * row_stride + x.
  row_stride | will be set to the row stride of the distmap.

## JxlButteraugliResultGetMaxDistance()

JXL_EXPORT float JxlButteraugliResultGetMaxDistance | ( | const JxlButteraugliResult * | result | ) |

Computes butteraugli max distance based on an intermediary butteraugli result.

Parameters

  result | intermediary result instance.

Returns
  max distance.