summaryrefslogtreecommitdiffstats
path: root/third_party/jpeg-xl/lib/include
diff options
context:
space:
mode:
Diffstat (limited to 'third_party/jpeg-xl/lib/include')
-rw-r--r--third_party/jpeg-xl/lib/include/jxl/cms_interface.h27
-rw-r--r--third_party/jpeg-xl/lib/include/jxl/codestream_header.h35
-rw-r--r--third_party/jpeg-xl/lib/include/jxl/color_encoding.h39
-rw-r--r--third_party/jpeg-xl/lib/include/jxl/decode.h411
-rw-r--r--third_party/jpeg-xl/lib/include/jxl/encode.h403
-rw-r--r--third_party/jpeg-xl/lib/include/jxl/parallel_runner.h35
-rw-r--r--third_party/jpeg-xl/lib/include/jxl/resizable_parallel_runner.h10
-rw-r--r--third_party/jpeg-xl/lib/include/jxl/stats.h8
-rw-r--r--third_party/jpeg-xl/lib/include/jxl/thread_parallel_runner.h8
-rw-r--r--third_party/jpeg-xl/lib/include/jxl/types.h10
10 files changed, 521 insertions, 465 deletions
diff --git a/third_party/jpeg-xl/lib/include/jxl/cms_interface.h b/third_party/jpeg-xl/lib/include/jxl/cms_interface.h
index c164eaccb5..25c700867a 100644
--- a/third_party/jpeg-xl/lib/include/jxl/cms_interface.h
+++ b/third_party/jpeg-xl/lib/include/jxl/cms_interface.h
@@ -29,10 +29,10 @@ extern "C" {
/** Parses an ICC profile and populates @p c and @p cmyk with the data.
*
- * @param user_data JxlCmsInterface::set_fields_data passed as-is.
+ * @param user_data @ref JxlCmsInterface::set_fields_data passed as-is.
* @param icc_data the ICC data to parse.
* @param icc_size how many bytes of icc_data are valid.
- * @param c a JxlColorEncoding to populate if applicable.
+ * @param c a @ref JxlColorEncoding to populate if applicable.
* @param cmyk a boolean to set to whether the colorspace is a CMYK colorspace.
* @return Whether the relevant fields in @p c were successfully populated.
*/
@@ -66,22 +66,23 @@ typedef struct {
/** Allocates and returns the data needed for @p num_threads parallel transforms
* from the @p input colorspace to @p output, with up to @p pixels_per_thread
- * pixels to transform per call to JxlCmsInterface::run. @p init_data comes
- * directly from the JxlCmsInterface instance. Since @c run only receives the
- * data returned by @c init, a reference to @p init_data should be kept there
- * if access to it is desired in @c run. Likewise for JxlCmsInterface::destroy.
+ * pixels to transform per call to @ref JxlCmsInterface::run. @p init_data comes
+ * directly from the @ref JxlCmsInterface instance. Since @c run only receives
+ * the data returned by @c init, a reference to @p init_data should be kept
+ * there if access to it is desired in @c run. Likewise for @ref
+ * JxlCmsInterface::destroy.
*
* The ICC data in @p input and @p output is guaranteed to outlive the @c init /
* @c run / @c destroy cycle.
*
- * @param init_data JxlCmsInterface::init_data passed as-is.
+ * @param init_data @ref JxlCmsInterface::init_data passed as-is.
* @param num_threads the maximum number of threads from which
- * JxlCmsInterface::run will be called.
+ * @ref JxlCmsInterface::run will be called.
* @param pixels_per_thread the maximum number of pixels that each call to
- * JxlCmsInterface::run will have to transform.
+ * @ref JxlCmsInterface::run will have to transform.
* @param input_profile the input colorspace for the transform.
- * @param output_profile the colorspace to which JxlCmsInterface::run should
- * convert the input data.
+ * @param output_profile the colorspace to which @ref JxlCmsInterface::run
+ * should convert the input data.
* @param intensity_target for colorspaces where luminance is relative
* (essentially: not PQ), indicates the luminance at which (1, 1, 1) will
* be displayed. This is useful for conversions between PQ and a relative
@@ -135,7 +136,7 @@ typedef float* (*jpegxl_cms_get_buffer_func)(void* user_data, size_t thread);
* @param output_buffer the buffer receiving the transformed pixel data.
* @param num_pixels the number of pixels to transform from @p input to
* @p output.
- * @return JXL_TRUE on success, JXL_FALSE on failure.
+ * @return ::JXL_TRUE on success, ::JXL_FALSE on failure.
*/
typedef JXL_BOOL (*jpegxl_cms_run_func)(void* user_data, size_t thread,
const float* input_buffer,
@@ -226,7 +227,7 @@ typedef void (*jpegxl_cms_destroy_func)(void*);
typedef struct {
/** CMS-specific data that will be passed to @ref set_fields_from_icc. */
void* set_fields_data;
- /** Populates a JxlColorEncoding from an ICC profile. */
+ /** Populates a @ref JxlColorEncoding from an ICC profile. */
jpegxl_cms_set_fields_from_icc_func set_fields_from_icc;
/** CMS-specific data that will be passed to @ref init. */
diff --git a/third_party/jpeg-xl/lib/include/jxl/codestream_header.h b/third_party/jpeg-xl/lib/include/jxl/codestream_header.h
index fb71484233..e60eb03355 100644
--- a/third_party/jpeg-xl/lib/include/jxl/codestream_header.h
+++ b/third_party/jpeg-xl/lib/include/jxl/codestream_header.h
@@ -71,7 +71,7 @@ typedef struct {
} JxlPreviewHeader;
/** The codestream animation header, optionally present in the beginning of
- * the codestream, and if it is it applies to all animation frames, unlike
+ * the codestream, and if it is it applies to all animation frames, unlike @ref
* JxlFrameHeader which applies to an individual frame.
*/
typedef struct {
@@ -166,12 +166,12 @@ typedef struct {
* it to to the original color profile. The decoder also does not convert to
* the target display color profile. To convert the pixel data produced by
* the decoder to the original color profile, one of the JxlDecoderGetColor*
- * functions needs to be called with @ref JXL_COLOR_PROFILE_TARGET_DATA to get
- * the color profile of the decoder output, and then an external CMS can be
- * used for conversion.
- * Note that for lossy compression, this should be set to false for most use
- * cases, and if needed, the image should be converted to the original color
- * profile after decoding, as described above.
+ * functions needs to be called with
+ * ::JXL_COLOR_PROFILE_TARGET_DATA to get the color profile of the decoder
+ * output, and then an external CMS can be used for conversion. Note that for
+ * lossy compression, this should be set to false for most use cases, and if
+ * needed, the image should be converted to the original color profile after
+ * decoding, as described above.
*/
JXL_BOOL uses_original_profile;
@@ -194,17 +194,19 @@ typedef struct {
* grayscale data, or 3 for colored data. This count does not include
* the alpha channel or other extra channels. To check presence of an alpha
* channel, such as in the case of RGBA color, check alpha_bits != 0.
- * If and only if this is 1, the JxlColorSpace in the JxlColorEncoding is
- * JXL_COLOR_SPACE_GRAY.
+ * If and only if this is 1, the @ref JxlColorSpace in the @ref
+ * JxlColorEncoding is
+ * ::JXL_COLOR_SPACE_GRAY.
*/
uint32_t num_color_channels;
/** Number of additional image channels. This includes the main alpha channel,
* but can also include additional channels such as depth, additional alpha
* channels, spot colors, and so on. Information about the extra channels
- * can be queried with JxlDecoderGetExtraChannelInfo. The main alpha channel,
- * if it exists, also has its information available in the alpha_bits,
- * alpha_exponent_bits and alpha_premultiplied fields in this JxlBasicInfo.
+ * can be queried with @ref JxlDecoderGetExtraChannelInfo. The main alpha
+ * channel, if it exists, also has its information available in the
+ * alpha_bits, alpha_exponent_bits and alpha_premultiplied fields in this @ref
+ * JxlBasicInfo.
*/
uint32_t num_extra_channels;
@@ -388,7 +390,8 @@ typedef struct {
/** The header of one displayed frame or non-coalesced layer. */
typedef struct {
/** How long to wait after rendering in ticks. The duration in seconds of a
- * tick is given by tps_numerator and tps_denominator in JxlAnimationHeader.
+ * tick is given by tps_numerator and tps_denominator in @ref
+ * JxlAnimationHeader.
*/
uint32_t duration;
@@ -396,9 +399,9 @@ typedef struct {
* interpreted from most-significant to least-significant as hour, minute,
* second, and frame. If timecode is nonzero, it is strictly larger than that
* of a previous frame with nonzero duration. These values are only available
- * if have_timecodes in JxlAnimationHeader is JXL_TRUE.
- * This value is only used if have_timecodes in JxlAnimationHeader is
- * JXL_TRUE.
+ * if have_timecodes in @ref JxlAnimationHeader is ::JXL_TRUE.
+ * This value is only used if have_timecodes in @ref JxlAnimationHeader is
+ * ::JXL_TRUE.
*/
uint32_t timecode;
diff --git a/third_party/jpeg-xl/lib/include/jxl/color_encoding.h b/third_party/jpeg-xl/lib/include/jxl/color_encoding.h
index 928117e8dd..e6325dcb30 100644
--- a/third_party/jpeg-xl/lib/include/jxl/color_encoding.h
+++ b/third_party/jpeg-xl/lib/include/jxl/color_encoding.h
@@ -24,9 +24,9 @@ extern "C" {
typedef enum {
/** Tristimulus RGB */
JXL_COLOR_SPACE_RGB,
- /** Luminance based, the primaries in JxlColorEncoding must be ignored. This
- * value implies that num_color_channels in JxlBasicInfo is 1, any other value
- * implies num_color_channels is 3. */
+ /** Luminance based, the primaries in @ref JxlColorEncoding must be ignored.
+ * This value implies that num_color_channels in @ref JxlBasicInfo is 1, any
+ * other value implies num_color_channels is 3. */
JXL_COLOR_SPACE_GRAY,
/** XYB (opsin) color space */
JXL_COLOR_SPACE_XYB,
@@ -35,18 +35,18 @@ typedef enum {
} JxlColorSpace;
/** Built-in whitepoints for color encoding. When decoding, the numerical xy
- * whitepoint value can be read from the JxlColorEncoding white_point field
+ * whitepoint value can be read from the @ref JxlColorEncoding white_point field
* regardless of the enum value. When encoding, enum values except
- * JXL_WHITE_POINT_CUSTOM override the numerical fields. Some enum values match
- * a subset of CICP (Rec. ITU-T H.273 | ISO/IEC 23091-2:2019(E)), however the
- * white point and RGB primaries are separate enums here.
+ * ::JXL_WHITE_POINT_CUSTOM override the numerical fields. Some enum values
+ * match a subset of CICP (Rec. ITU-T H.273 | ISO/IEC 23091-2:2019(E)), however
+ * the white point and RGB primaries are separate enums here.
*/
typedef enum {
/** CIE Standard Illuminant D65: 0.3127, 0.3290 */
JXL_WHITE_POINT_D65 = 1,
- /** White point must be read from the JxlColorEncoding white_point field, or
- * as ICC profile. This enum value is not an exact match of the corresponding
- * CICP value. */
+ /** White point must be read from the @ref JxlColorEncoding white_point field,
+ * or as ICC profile. This enum value is not an exact match of the
+ * corresponding CICP value. */
JXL_WHITE_POINT_CUSTOM = 2,
/** CIE Standard Illuminant E (equal-energy): 1/3, 1/3 */
JXL_WHITE_POINT_E = 10,
@@ -55,10 +55,10 @@ typedef enum {
} JxlWhitePoint;
/** Built-in primaries for color encoding. When decoding, the primaries can be
- * read from the JxlColorEncoding primaries_red_xy, primaries_green_xy and
+ * read from the @ref JxlColorEncoding primaries_red_xy, primaries_green_xy and
* primaries_blue_xy fields regardless of the enum value. When encoding, the
- * enum values except JXL_PRIMARIES_CUSTOM override the numerical fields. Some
- * enum values match a subset of CICP (Rec. ITU-T H.273 | ISO/IEC
+ * enum values except ::JXL_PRIMARIES_CUSTOM override the numerical fields.
+ * Some enum values match a subset of CICP (Rec. ITU-T H.273 | ISO/IEC
* 23091-2:2019(E)), however the white point and RGB primaries are separate
* enums here.
*/
@@ -66,7 +66,7 @@ typedef enum {
/** The CIE xy values of the red, green and blue primaries are: 0.639998686,
0.330010138; 0.300003784, 0.600003357; 0.150002046, 0.059997204 */
JXL_PRIMARIES_SRGB = 1,
- /** Primaries must be read from the JxlColorEncoding primaries_red_xy,
+ /** Primaries must be read from the @ref JxlColorEncoding primaries_red_xy,
* primaries_green_xy and primaries_blue_xy fields, or as ICC profile. This
* enum value is not an exact match of the corresponding CICP value. */
JXL_PRIMARIES_CUSTOM = 2,
@@ -94,7 +94,7 @@ typedef enum {
JXL_TRANSFER_FUNCTION_DCI = 17,
/** As specified in Rec. ITU-R BT.2100-1 (HLG) */
JXL_TRANSFER_FUNCTION_HLG = 18,
- /** Transfer function follows power law given by the gamma value in
+ /** Transfer function follows power law given by the gamma value in @ref
JxlColorEncoding. Not a CICP value. */
JXL_TRANSFER_FUNCTION_GAMMA = 65535,
} JxlTransferFunction;
@@ -118,7 +118,7 @@ typedef struct {
*/
JxlColorSpace color_space;
- /** Built-in white point. If this value is JXL_WHITE_POINT_CUSTOM, must
+ /** Built-in white point. If this value is ::JXL_WHITE_POINT_CUSTOM, must
* use the numerical whitepoint values from white_point_xy.
*/
JxlWhitePoint white_point;
@@ -126,10 +126,10 @@ typedef struct {
/** Numerical whitepoint values in CIE xy space. */
double white_point_xy[2];
- /** Built-in RGB primaries. If this value is JXL_PRIMARIES_CUSTOM, must
+ /** Built-in RGB primaries. If this value is ::JXL_PRIMARIES_CUSTOM, must
* use the numerical primaries values below. This field and the custom values
* below are unused and must be ignored if the color space is
- * JXL_COLOR_SPACE_GRAY or JXL_COLOR_SPACE_XYB.
+ * ::JXL_COLOR_SPACE_GRAY or ::JXL_COLOR_SPACE_XYB.
*/
JxlPrimaries primaries;
@@ -145,7 +145,8 @@ typedef struct {
/** Transfer function if have_gamma is 0 */
JxlTransferFunction transfer_function;
- /** Gamma value used when transfer_function is JXL_TRANSFER_FUNCTION_GAMMA
+ /** Gamma value used when transfer_function is @ref
+ * JXL_TRANSFER_FUNCTION_GAMMA
*/
double gamma;
diff --git a/third_party/jpeg-xl/lib/include/jxl/decode.h b/third_party/jpeg-xl/lib/include/jxl/decode.h
index eaee70fa61..599b8336f3 100644
--- a/third_party/jpeg-xl/lib/include/jxl/decode.h
+++ b/third_party/jpeg-xl/lib/include/jxl/decode.h
@@ -66,12 +66,12 @@ typedef enum {
* @p size doesn't need to be a full image, only the beginning of the file.
*
* @return a flag indicating if a JPEG XL signature was found and what type.
- * - @ref JXL_SIG_NOT_ENOUGH_BYTES if not enough bytes were passed to
+ * - ::JXL_SIG_NOT_ENOUGH_BYTES if not enough bytes were passed to
* determine if a valid signature is there.
- * - @ref JXL_SIG_INVALID if no valid signature found for JPEG XL decoding.
- * - @ref JXL_SIG_CODESTREAM if a valid JPEG XL codestream signature was
+ * - ::JXL_SIG_INVALID if no valid signature found for JPEG XL decoding.
+ * - ::JXL_SIG_CODESTREAM if a valid JPEG XL codestream signature was
* found.
- * - @ref JXL_SIG_CONTAINER if a valid JPEG XL container signature was found.
+ * - ::JXL_SIG_CONTAINER if a valid JPEG XL container signature was found.
*/
JXL_EXPORT JxlSignature JxlSignatureCheck(const uint8_t* buf, size_t len);
@@ -115,7 +115,7 @@ JXL_EXPORT void JxlDecoderDestroy(JxlDecoder* dec);
/**
* Return value for @ref JxlDecoderProcessInput.
- * The values from @ref JXL_DEC_BASIC_INFO onwards are optional informative
+ * The values from ::JXL_DEC_BASIC_INFO onwards are optional informative
* events that can be subscribed to, they are never returned if they
* have not been registered with @ref JxlDecoderSubscribeEvents.
*/
@@ -123,12 +123,12 @@ typedef enum {
/** Function call finished successfully, or decoding is finished and there is
* nothing more to be done.
*
- * Note that @ref JxlDecoderProcessInput will return JXL_DEC_SUCCESS if all
- * events that were registered with @ref JxlDecoderSubscribeEvents were
+ * Note that @ref JxlDecoderProcessInput will return ::JXL_DEC_SUCCESS if
+ * all events that were registered with @ref JxlDecoderSubscribeEvents were
* processed, even before the end of the JPEG XL codestream.
*
* In this case, the return value @ref JxlDecoderReleaseInput will be the same
- * as it was at the last signaled event. E.g. if JXL_DEC_FULL_IMAGE was
+ * as it was at the last signaled event. E.g. if ::JXL_DEC_FULL_IMAGE was
* subscribed to, then all bytes from the end of the JPEG XL codestream
* (including possible boxes needed for jpeg reconstruction) will be returned
* as unprocessed.
@@ -151,14 +151,14 @@ typedef enum {
* In most cases, @ref JxlDecoderReleaseInput will return no unprocessed bytes
* at this event, the only exceptions are if the previously set input ended
* within (a) the raw codestream signature, (b) the signature box, (c) a box
- * header, or (d) the first 4 bytes of a brob, ftyp, or jxlp box. In any of
- * these cases the number of unprocessed bytes is less than 20.
+ * header, or (d) the first 4 bytes of a `brob`, `ftyp`, or `jxlp` box. In any
+ * of these cases the number of unprocessed bytes is less than 20.
*/
JXL_DEC_NEED_MORE_INPUT = 2,
/** The decoder is able to decode a preview image and requests setting a
* preview output buffer using @ref JxlDecoderSetPreviewOutBuffer. This occurs
- * if @ref JXL_DEC_PREVIEW_IMAGE is requested and it is possible to decode a
+ * if ::JXL_DEC_PREVIEW_IMAGE is requested and it is possible to decode a
* preview image from the codestream and the preview out buffer was not yet
* set. There is maximum one preview image in a codestream.
* In this case, @ref JxlDecoderReleaseInput will return all bytes from the
@@ -179,13 +179,13 @@ typedef enum {
/** The JPEG reconstruction buffer is too small for reconstructed JPEG
* codestream to fit. @ref JxlDecoderSetJPEGBuffer must be called again to
* make room for remaining bytes. This event may occur multiple times
- * after @ref JXL_DEC_JPEG_RECONSTRUCTION.
+ * after ::JXL_DEC_JPEG_RECONSTRUCTION.
*/
JXL_DEC_JPEG_NEED_MORE_OUTPUT = 6,
/** The box contents output buffer is too small. @ref JxlDecoderSetBoxBuffer
* must be called again to make room for remaining bytes. This event may occur
- * multiple times after @ref JXL_DEC_BOX.
+ * multiple times after ::JXL_DEC_BOX.
*/
JXL_DEC_BOX_NEED_MORE_OUTPUT = 7,
@@ -201,7 +201,7 @@ typedef enum {
/** Informative event by @ref JxlDecoderProcessInput
* "JxlDecoderProcessInput": Color encoding or ICC profile from the
* codestream header. This event occurs max once per image and always later
- * than @ref JXL_DEC_BASIC_INFO and earlier than any pixel data.
+ * than ::JXL_DEC_BASIC_INFO and earlier than any pixel data.
* In this case, @ref JxlDecoderReleaseInput will return all bytes from the
* end of the image header (which is the start of the first frame) as
* unprocessed.
@@ -212,7 +212,7 @@ typedef enum {
* "JxlDecoderProcessInput": Preview image, a small frame, decoded. This
* event can only happen if the image has a preview frame encoded. This event
* occurs max once for the codestream and always later than @ref
- * JXL_DEC_COLOR_ENCODING and before @ref JXL_DEC_FRAME.
+ * JXL_DEC_COLOR_ENCODING and before ::JXL_DEC_FRAME.
* In this case, @ref JxlDecoderReleaseInput will return all bytes from the
* end of the preview frame as unprocessed.
*/
@@ -223,19 +223,19 @@ typedef enum {
* JxlDecoderGetFrameHeader can be used at this point. A note on frames:
* a JPEG XL image can have internal frames that are not intended to be
* displayed (e.g. used for compositing a final frame), but this only returns
- * displayed frames, unless @ref JxlDecoderSetCoalescing was set to JXL_FALSE:
- * in that case, the individual layers are returned, without blending. Note
- * that even when coalescing is disabled, only frames of type kRegularFrame
- * are returned; frames of type kReferenceOnly and kLfFrame are always for
- * internal purposes only and cannot be accessed. A displayed frame either has
- * an animation duration or is the only or last frame in the image. This event
- * occurs max once per displayed frame, always later than @ref
- * JXL_DEC_COLOR_ENCODING, and always earlier than any pixel data. While
- * JPEG XL supports encoding a single frame as the composition of multiple
- * internal sub-frames also called frames, this event is not indicated for the
- * internal frames.
- * In this case, @ref JxlDecoderReleaseInput will return all bytes from the
- * end of the frame header (including ToC) as unprocessed.
+ * displayed frames, unless @ref JxlDecoderSetCoalescing was set to @ref
+ * JXL_FALSE "JXL_FALSE": in that case, the individual layers are returned,
+ * without blending. Note that even when coalescing is disabled, only frames
+ * of type kRegularFrame are returned; frames of type kReferenceOnly
+ * and kLfFrame are always for internal purposes only and cannot be accessed.
+ * A displayed frame either has an animation duration or is the only or last
+ * frame in the image. This event occurs max once per displayed frame, always
+ * later than ::JXL_DEC_COLOR_ENCODING, and always earlier than any pixel
+ * data. While JPEG XL supports encoding a single frame as the composition of
+ * multiple internal sub-frames also called frames, this event is not
+ * indicated for the internal frames. In this case, @ref
+ * JxlDecoderReleaseInput will return all bytes from the end of the frame
+ * header (including ToC) as unprocessed.
*/
JXL_DEC_FRAME = 0x400,
@@ -246,7 +246,7 @@ typedef enum {
* not this return status only indicates we're past this point in the
* codestream. This event occurs max once per frame.
* In this case, @ref JxlDecoderReleaseInput will return all bytes from the
- * end of the frame (or if @ref JXL_DEC_JPEG_RECONSTRUCTION is subscribed to,
+ * end of the frame (or if ::JXL_DEC_JPEG_RECONSTRUCTION is subscribed to,
* from the end of the last box that is needed for jpeg reconstruction) as
* unprocessed.
*/
@@ -259,9 +259,9 @@ typedef enum {
* is set a byte stream identical to the JPEG codestream used to encode the
* image will be written to the JPEG reconstruction buffer instead of pixels
* to the image out buffer. This event occurs max once per image and always
- * before @ref JXL_DEC_FULL_IMAGE.
+ * before ::JXL_DEC_FULL_IMAGE.
* In this case, @ref JxlDecoderReleaseInput will return all bytes from the
- * end of the 'jbrd' box as unprocessed.
+ * end of the `jbrd` box as unprocessed.
*/
JXL_DEC_JPEG_RECONSTRUCTION = 0x2000,
@@ -290,8 +290,8 @@ typedef enum {
*
* The buffer set with @ref JxlDecoderSetBoxBuffer must be set again for each
* next box to be obtained, or can be left unset to skip outputting this box.
- * The output buffer contains the full box data when the next @ref JXL_DEC_BOX
- * event or @ref JXL_DEC_SUCCESS occurs. @ref JXL_DEC_BOX occurs for all
+ * The output buffer contains the full box data when the next ::JXL_DEC_BOX
+ * event or ::JXL_DEC_SUCCESS occurs. ::JXL_DEC_BOX occurs for all
* boxes, including non-metadata boxes such as the signature box or codestream
* boxes. To check whether the box is a metadata type for respectively EXIF,
* XMP or JUMBF, use @ref JxlDecoderGetBoxType and check for types "Exif",
@@ -324,26 +324,40 @@ typedef enum {
* Setting a progressive detail with value N implies all progressive details
* with smaller or equal value. Currently only the following level of
* progressive detail is implemented:
- * - kDC (which implies kFrames)
- * - kLastPasses (which implies kDC and kFrames)
- * - kPasses (which implies kLastPasses, kDC and kFrames)
+ * - @ref kDC (which implies kFrames)
+ * - @ref kLastPasses (which implies @ref kDC and @ref kFrames)
+ * - @ref kPasses (which implies @ref kLastPasses, kDC and @ref kFrames)
*/
typedef enum {
- // after completed kRegularFrames
+ /**
+ * after completed kRegularFrames
+ */
kFrames = 0,
- // after completed DC (1:8)
+ /**
+ * after completed DC (1:8)
+ */
kDC = 1,
- // after completed AC passes that are the last pass for their resolution
- // target.
+ /**
+ * after completed AC passes that are the last pass for their resolution
+ * target.
+ */
kLastPasses = 2,
- // after completed AC passes that are not the last pass for their resolution
- // target.
+ /**
+ * after completed AC passes that are not the last pass for their resolution
+ * target.
+ */
kPasses = 3,
- // during DC frame when lower resolution are completed (1:32, 1:16)
+ /**
+ * during DC frame when lower resolution are completed (1:32, 1:16)
+ */
kDCProgressive = 4,
- // after completed groups
+ /**
+ * after completed groups
+ */
kDCGroups = 5,
- // after completed groups
+ /**
+ * after completed groups
+ */
kGroups = 6,
} JxlProgressiveDetail;
@@ -354,8 +368,8 @@ typedef enum {
* more efficiently with @ref JxlDecoderSkipFrames. Settings such as parallel
* runner or subscribed events are kept. After rewind, @ref
* JxlDecoderSubscribeEvents can be used again, and it is feasible to leave out
- * events that were already handled before, such as @ref JXL_DEC_BASIC_INFO
- * and @ref JXL_DEC_COLOR_ENCODING, since they will provide the same information
+ * events that were already handled before, such as ::JXL_DEC_BASIC_INFO
+ * and ::JXL_DEC_COLOR_ENCODING, since they will provide the same information
* as before.
* The difference to @ref JxlDecoderReset is that some state is kept, namely
* settings set by a call to
@@ -376,14 +390,14 @@ JXL_EXPORT void JxlDecoderRewind(JxlDecoder* dec);
* the input, but will not output the frame events. It can be more efficient
* when skipping frames, and even more so when using this after @ref
* JxlDecoderRewind. If the decoder is already processing a frame (could
- * have emitted @ref JXL_DEC_FRAME but not yet @ref JXL_DEC_FULL_IMAGE), it
+ * have emitted ::JXL_DEC_FRAME but not yet ::JXL_DEC_FULL_IMAGE), it
* starts skipping from the next frame. If the amount is larger than the amount
* of frames remaining in the image, all remaining frames are skipped. Calling
* this function multiple times adds the amount to skip to the already existing
* amount.
*
* A frame here is defined as a frame that without skipping emits events such
- * as @ref JXL_DEC_FRAME and @ref JXL_DEC_FULL_IMAGE, frames that are internal
+ * as ::JXL_DEC_FRAME and ::JXL_DEC_FULL_IMAGE, frames that are internal
* to the file format but are not rendered as part of an animation, or are not
* the final still frame of a still image, are not counted.
*
@@ -394,14 +408,14 @@ JXL_EXPORT void JxlDecoderSkipFrames(JxlDecoder* dec, size_t amount);
/**
* Skips processing the current frame. Can be called after frame processing
- * already started, signaled by a @ref JXL_DEC_NEED_IMAGE_OUT_BUFFER event,
- * but before the corresponding @ref JXL_DEC_FULL_IMAGE event. The next signaled
- * event will be another @ref JXL_DEC_FRAME, or @ref JXL_DEC_SUCCESS if there
+ * already started, signaled by a ::JXL_DEC_NEED_IMAGE_OUT_BUFFER event,
+ * but before the corresponding ::JXL_DEC_FULL_IMAGE event. The next signaled
+ * event will be another ::JXL_DEC_FRAME, or ::JXL_DEC_SUCCESS if there
* are no more frames. If pixel data is required from the already processed part
* of the frame, @ref JxlDecoderFlushImage must be called before this.
*
* @param dec decoder object
- * @return @ref JXL_DEC_SUCCESS if there is a frame to skip, and @ref
+ * @return ::JXL_DEC_SUCCESS if there is a frame to skip, and @ref
* JXL_DEC_ERROR if the function was not called during frame processing.
*/
JXL_EXPORT JxlDecoderStatus JxlDecoderSkipCurrentFrame(JxlDecoder* dec);
@@ -415,7 +429,7 @@ JXL_EXPORT JxlDecoderStatus JxlDecoderSkipCurrentFrame(JxlDecoder* dec);
* be NULL to use the default, single-threaded, runner. A multithreaded
* runner should be set to reach fast performance.
* @param parallel_runner_opaque opaque pointer for parallel_runner.
- * @return @ref JXL_DEC_SUCCESS if the runner was set, @ref JXL_DEC_ERROR
+ * @return ::JXL_DEC_SUCCESS if the runner was set, ::JXL_DEC_ERROR
* otherwise (the previous runner remains set).
*/
JXL_EXPORT JxlDecoderStatus
@@ -439,7 +453,7 @@ JxlDecoderSetParallelRunner(JxlDecoder* dec, JxlParallelRunner parallel_runner,
*/
JXL_EXPORT size_t JxlDecoderSizeHintBasicInfo(const JxlDecoder* dec);
-/** Select for which informative events, i.e. @ref JXL_DEC_BASIC_INFO, etc., the
+/** Select for which informative events, i.e. ::JXL_DEC_BASIC_INFO, etc., the
* decoder should return with a status. It is not required to subscribe to any
* events, data can still be requested from the decoder as soon as it available.
* By default, the decoder is subscribed to no events (events_wanted == 0), and
@@ -449,7 +463,7 @@ JXL_EXPORT size_t JxlDecoderSizeHintBasicInfo(const JxlDecoder* dec);
*
* @param dec decoder object
* @param events_wanted bitfield of desired events.
- * @return @ref JXL_DEC_SUCCESS if no error, @ref JXL_DEC_ERROR otherwise.
+ * @return ::JXL_DEC_SUCCESS if no error, ::JXL_DEC_ERROR otherwise.
*/
JXL_EXPORT JxlDecoderStatus JxlDecoderSubscribeEvents(JxlDecoder* dec,
int events_wanted);
@@ -459,14 +473,14 @@ JXL_EXPORT JxlDecoderStatus JxlDecoderSubscribeEvents(JxlDecoder* dec,
* indicating that the decoder must perform a rotation and/or
* mirroring to the encoded image data.
*
- * - If skip_reorientation is JXL_FALSE (the default): the decoder
+ * - If skip_reorientation is ::JXL_FALSE (the default): the decoder
* will apply the transformation from the orientation setting, hence
* rendering the image according to its specified intent. When
- * producing a JxlBasicInfo, the decoder will always set the
+ * producing a @ref JxlBasicInfo, the decoder will always set the
* orientation field to JXL_ORIENT_IDENTITY (matching the returned
* pixel data) and also align xsize and ysize so that they correspond
* to the width and the height of the returned pixel data.
- * - If skip_reorientation is JXL_TRUE: the decoder will skip
+ * - If skip_reorientation is ::JXL_TRUE "JXL_TRUE": the decoder will skip
* applying the transformation from the orientation setting, returning
* the image in the as-in-bitstream pixeldata orientation.
* This may be faster to decode since the decoder doesn't have to apply the
@@ -483,17 +497,18 @@ JXL_EXPORT JxlDecoderStatus JxlDecoderSubscribeEvents(JxlDecoder* dec,
*
* @param dec decoder object
* @param skip_reorientation JXL_TRUE to enable, JXL_FALSE to disable.
- * @return @ref JXL_DEC_SUCCESS if no error, @ref JXL_DEC_ERROR otherwise.
+ * @return ::JXL_DEC_SUCCESS if no error, ::JXL_DEC_ERROR otherwise.
*/
JXL_EXPORT JxlDecoderStatus
JxlDecoderSetKeepOrientation(JxlDecoder* dec, JXL_BOOL skip_reorientation);
/**
* Enables or disables preserving of associated alpha channels. If
- * unpremul_alpha is set to JXL_FALSE then for associated alpha channel, the
- * pixel data is returned with premultiplied colors. If it is set to JXL_TRUE,
- * The colors will be unpremultiplied based on the alpha channel. This function
- * has no effect if the image does not have an associated alpha channel.
+ * unpremul_alpha is set to ::JXL_FALSE then for associated alpha channel,
+ * the pixel data is returned with premultiplied colors. If it is set to @ref
+ * JXL_TRUE, The colors will be unpremultiplied based on the alpha channel. This
+ * function has no effect if the image does not have an associated alpha
+ * channel.
*
* By default, this option is disabled, and the returned pixel data "as is".
*
@@ -501,20 +516,20 @@ JxlDecoderSetKeepOrientation(JxlDecoder* dec, JXL_BOOL skip_reorientation);
*
* @param dec decoder object
* @param unpremul_alpha JXL_TRUE to enable, JXL_FALSE to disable.
- * @return @ref JXL_DEC_SUCCESS if no error, @ref JXL_DEC_ERROR otherwise.
+ * @return ::JXL_DEC_SUCCESS if no error, ::JXL_DEC_ERROR otherwise.
*/
JXL_EXPORT JxlDecoderStatus
JxlDecoderSetUnpremultiplyAlpha(JxlDecoder* dec, JXL_BOOL unpremul_alpha);
/** Enables or disables rendering spot colors. By default, spot colors
* are rendered, which is OK for viewing the decoded image. If render_spotcolors
- * is JXL_FALSE, then spot colors are not rendered, and have to be retrieved
- * separately using @ref JxlDecoderSetExtraChannelBuffer. This is useful for
- * e.g. printing applications.
+ * is ::JXL_FALSE, then spot colors are not rendered, and have to be
+ * retrieved separately using @ref JxlDecoderSetExtraChannelBuffer. This is
+ * useful for e.g. printing applications.
*
* @param dec decoder object
* @param render_spotcolors JXL_TRUE to enable (default), JXL_FALSE to disable.
- * @return @ref JXL_DEC_SUCCESS if no error, @ref JXL_DEC_ERROR otherwise.
+ * @return ::JXL_DEC_SUCCESS if no error, ::JXL_DEC_ERROR otherwise.
*/
JXL_EXPORT JxlDecoderStatus
JxlDecoderSetRenderSpotcolors(JxlDecoder* dec, JXL_BOOL render_spotcolors);
@@ -530,7 +545,7 @@ JxlDecoderSetRenderSpotcolors(JxlDecoder* dec, JXL_BOOL render_spotcolors);
* @param dec decoder object
* @param coalescing JXL_TRUE to enable coalescing (default), JXL_FALSE to
* disable it.
- * @return @ref JXL_DEC_SUCCESS if no error, @ref JXL_DEC_ERROR otherwise.
+ * @return ::JXL_DEC_SUCCESS if no error, ::JXL_DEC_ERROR otherwise.
*/
JXL_EXPORT JxlDecoderStatus JxlDecoderSetCoalescing(JxlDecoder* dec,
JXL_BOOL coalescing);
@@ -547,32 +562,32 @@ JXL_EXPORT JxlDecoderStatus JxlDecoderSetCoalescing(JxlDecoder* dec,
*
* The returned status indicates whether the decoder needs more input bytes, or
* more output buffer for a certain type of output data. No matter what the
- * returned status is (other than @ref JXL_DEC_ERROR), new information, such
+ * returned status is (other than ::JXL_DEC_ERROR), new information, such
* as @ref JxlDecoderGetBasicInfo, may have become available after this call.
- * When the return value is not @ref JXL_DEC_ERROR or @ref JXL_DEC_SUCCESS, the
+ * When the return value is not ::JXL_DEC_ERROR or ::JXL_DEC_SUCCESS, the
* decoding requires more @ref JxlDecoderProcessInput calls to continue.
*
* @param dec decoder object
- * @return @ref JXL_DEC_SUCCESS when decoding finished and all events handled.
+ * @return ::JXL_DEC_SUCCESS when decoding finished and all events handled.
* If you still have more unprocessed input data anyway, then you can still
* continue by using @ref JxlDecoderSetInput and calling @ref
* JxlDecoderProcessInput again, similar to handling @ref
- * JXL_DEC_NEED_MORE_INPUT. @ref JXL_DEC_SUCCESS can occur instead of @ref
+ * JXL_DEC_NEED_MORE_INPUT. ::JXL_DEC_SUCCESS can occur instead of @ref
* JXL_DEC_NEED_MORE_INPUT when, for example, the input data ended right at
* the boundary of a box of the container format, all essential codestream
* boxes were already decoded, but extra metadata boxes are still present in
* the next data. @ref JxlDecoderProcessInput cannot return success if all
* codestream boxes have not been seen yet.
- * @return @ref JXL_DEC_ERROR when decoding failed, e.g. invalid codestream.
+ * @return ::JXL_DEC_ERROR when decoding failed, e.g. invalid codestream.
* TODO(lode): document the input data mechanism
- * @return @ref JXL_DEC_NEED_MORE_INPUT when more input data is necessary.
- * @return @ref JXL_DEC_BASIC_INFO when basic info such as image dimensions is
+ * @return ::JXL_DEC_NEED_MORE_INPUT when more input data is necessary.
+ * @return ::JXL_DEC_BASIC_INFO when basic info such as image dimensions is
* available and this informative event is subscribed to.
- * @return @ref JXL_DEC_COLOR_ENCODING when color profile information is
+ * @return ::JXL_DEC_COLOR_ENCODING when color profile information is
* available and this informative event is subscribed to.
- * @return @ref JXL_DEC_PREVIEW_IMAGE when preview pixel information is
+ * @return ::JXL_DEC_PREVIEW_IMAGE when preview pixel information is
* available and output in the preview buffer.
- * @return @ref JXL_DEC_FULL_IMAGE when all pixel information at highest detail
+ * @return ::JXL_DEC_FULL_IMAGE when all pixel information at highest detail
* is available and has been output in the pixel buffer.
*/
JXL_EXPORT JxlDecoderStatus JxlDecoderProcessInput(JxlDecoder* dec);
@@ -588,8 +603,8 @@ JXL_EXPORT JxlDecoderStatus JxlDecoderProcessInput(JxlDecoder* dec);
* @param dec decoder object
* @param data pointer to next bytes to read from
* @param size amount of bytes available starting from data
- * @return @ref JXL_DEC_ERROR if input was already set without releasing or @ref
- * JxlDecoderCloseInput was already called, @ref JXL_DEC_SUCCESS otherwise.
+ * @return ::JXL_DEC_ERROR if input was already set without releasing or @ref
+ * JxlDecoderCloseInput was already called, ::JXL_DEC_SUCCESS otherwise.
*/
JXL_EXPORT JxlDecoderStatus JxlDecoderSetInput(JxlDecoder* dec,
const uint8_t* data,
@@ -602,17 +617,17 @@ JXL_EXPORT JxlDecoderStatus JxlDecoderSetInput(JxlDecoder* dec,
* whenever any input is already set and new input needs to be added with @ref
* JxlDecoderSetInput, but is not required before @ref JxlDecoderDestroy or @ref
* JxlDecoderReset. Calling @ref JxlDecoderReleaseInput when no input is set is
- * not an error and returns 0.
+ * not an error and returns `0`.
*
* @param dec decoder object
* @return The amount of bytes the decoder has not yet processed that are still
- * remaining in the data set by @ref JxlDecoderSetInput, or 0 if no input is
- * set or @ref JxlDecoderReleaseInput was already called. For a next call
- * to @ref JxlDecoderProcessInput, the buffer must start with these
- * unprocessed bytes. From this value it is possible to infer the position
- * of certain JPEG XL codestream elements (e.g. end of headers, frame
- * start/end). See the documentation of individual values of @ref
- * JxlDecoderStatus for more information.
+ * remaining in the data set by @ref JxlDecoderSetInput, or `0` if no input
+ * is set or @ref JxlDecoderReleaseInput was already called. For a next call to
+ * @ref JxlDecoderProcessInput, the buffer must start with these unprocessed
+ * bytes. From this value it is possible to infer the position of certain JPEG
+ * XL codestream elements (e.g. end of headers, frame start/end). See the
+ * documentation of individual values of @ref JxlDecoderStatus for more
+ * information.
*/
JXL_EXPORT size_t JxlDecoderReleaseInput(JxlDecoder* dec);
@@ -621,9 +636,9 @@ JXL_EXPORT size_t JxlDecoderReleaseInput(JxlDecoder* dec);
* will be called. This function allows the decoder to determine correctly if it
* should return success, need more input or error in certain cases. For
* backwards compatibility with a previous version of the API, using this
- * function is optional when not using the @ref JXL_DEC_BOX event (the decoder
+ * function is optional when not using the ::JXL_DEC_BOX event (the decoder
* is able to determine the end of the image frames without marking the end),
- * but using this function is required when using @ref JXL_DEC_BOX for getting
+ * but using this function is required when using ::JXL_DEC_BOX for getting
* metadata box contents. This function does not replace @ref
* JxlDecoderReleaseInput, that function should still be called if its return
* value is needed.
@@ -643,8 +658,8 @@ JXL_EXPORT void JxlDecoderCloseInput(JxlDecoder* dec);
* @param dec decoder object
* @param info struct to copy the information into, or NULL to only check
* whether the information is available through the return value.
- * @return @ref JXL_DEC_SUCCESS if the value is available, @ref
- * JXL_DEC_NEED_MORE_INPUT if not yet available, @ref JXL_DEC_ERROR
+ * @return ::JXL_DEC_SUCCESS if the value is available, @ref
+ * JXL_DEC_NEED_MORE_INPUT if not yet available, ::JXL_DEC_ERROR
* in case of other error conditions.
*/
JXL_EXPORT JxlDecoderStatus JxlDecoderGetBasicInfo(const JxlDecoder* dec,
@@ -652,14 +667,14 @@ JXL_EXPORT JxlDecoderStatus JxlDecoderGetBasicInfo(const JxlDecoder* dec,
/**
* Outputs information for extra channel at the given index. The index must be
- * smaller than num_extra_channels in the associated JxlBasicInfo.
+ * smaller than num_extra_channels in the associated @ref JxlBasicInfo.
*
* @param dec decoder object
* @param index index of the extra channel to query.
* @param info struct to copy the information into, or NULL to only check
* whether the information is available through the return value.
- * @return @ref JXL_DEC_SUCCESS if the value is available, @ref
- * JXL_DEC_NEED_MORE_INPUT if not yet available, @ref JXL_DEC_ERROR
+ * @return ::JXL_DEC_SUCCESS if the value is available, @ref
+ * JXL_DEC_NEED_MORE_INPUT if not yet available, ::JXL_DEC_ERROR
* in case of other error conditions.
*/
JXL_EXPORT JxlDecoderStatus JxlDecoderGetExtraChannelInfo(
@@ -667,16 +682,16 @@ JXL_EXPORT JxlDecoderStatus JxlDecoderGetExtraChannelInfo(
/**
* Outputs name for extra channel at the given index in UTF-8. The index must be
- * smaller than num_extra_channels in the associated JxlBasicInfo. The buffer
- * for name must have at least name_length + 1 bytes allocated, gotten from
- * the associated JxlExtraChannelInfo.
+ * smaller than `num_extra_channels` in the associated @ref JxlBasicInfo. The
+ * buffer for name must have at least `name_length + 1` bytes allocated, gotten
+ * from the associated @ref JxlExtraChannelInfo.
*
* @param dec decoder object
* @param index index of the extra channel to query.
* @param name buffer to copy the name into
* @param size size of the name buffer in bytes
- * @return @ref JXL_DEC_SUCCESS if the value is available, @ref
- * JXL_DEC_NEED_MORE_INPUT if not yet available, @ref JXL_DEC_ERROR
+ * @return ::JXL_DEC_SUCCESS if the value is available, @ref
+ * JXL_DEC_NEED_MORE_INPUT if not yet available, ::JXL_DEC_ERROR
* in case of other error conditions.
*/
JXL_EXPORT JxlDecoderStatus JxlDecoderGetExtraChannelName(const JxlDecoder* dec,
@@ -719,7 +734,7 @@ typedef enum {
* problematic, in that: while ICC profiles can encode a transfer function
* that happens to approximate those of PQ and HLG (HLG for only one given
* system gamma at a time, and necessitating a 3D LUT if gamma is to be
- * different from 1), they cannot (before ICCv4.4) semantically signal that
+ * different from `1`), they cannot (before ICCv4.4) semantically signal that
* this is the color space that they represent. Therefore, they will
* typically not actually be interpreted as representing an HDR color space.
* This is especially detrimental to PQ which will then be interpreted as if
@@ -741,8 +756,8 @@ typedef enum {
* or the color profile of the decoded pixels.
* @param color_encoding struct to copy the information into, or NULL to only
* check whether the information is available through the return value.
- * @return @ref JXL_DEC_SUCCESS if the data is available and returned, @ref
- * JXL_DEC_NEED_MORE_INPUT if not yet available, @ref JXL_DEC_ERROR in
+ * @return ::JXL_DEC_SUCCESS if the data is available and returned, @ref
+ * JXL_DEC_NEED_MORE_INPUT if not yet available, ::JXL_DEC_ERROR in
* case the encoded structured color profile does not exist in the
* codestream.
*/
@@ -766,10 +781,10 @@ JXL_EXPORT JxlDecoderStatus JxlDecoderGetColorAsEncodedProfile(
* or the color profile of the decoded pixels.
* @param size variable to output the size into, or NULL to only check the
* return status.
- * @return @ref JXL_DEC_SUCCESS if the ICC profile is available, @ref
+ * @return ::JXL_DEC_SUCCESS if the ICC profile is available, @ref
* JXL_DEC_NEED_MORE_INPUT if the decoder has not yet received enough
* input data to determine whether an ICC profile is available or what its
- * size is, @ref JXL_DEC_ERROR in case the ICC profile is not available and
+ * size is, ::JXL_DEC_ERROR in case the ICC profile is not available and
* cannot be generated.
*/
JXL_EXPORT JxlDecoderStatus JxlDecoderGetICCProfileSize(
@@ -785,8 +800,8 @@ JXL_EXPORT JxlDecoderStatus JxlDecoderGetICCProfileSize(
* or the color profile of the decoded pixels.
* @param icc_profile buffer to copy the ICC profile into
* @param size size of the icc_profile buffer in bytes
- * @return @ref JXL_DEC_SUCCESS if the profile was successfully returned is
- * available, @ref JXL_DEC_NEED_MORE_INPUT if not yet available, @ref
+ * @return ::JXL_DEC_SUCCESS if the profile was successfully returned is
+ * available, ::JXL_DEC_NEED_MORE_INPUT if not yet available, @ref
* JXL_DEC_ERROR if the profile doesn't exist or the output size is not
* large enough.
*/
@@ -801,7 +816,7 @@ JXL_EXPORT JxlDecoderStatus JxlDecoderGetColorAsICCProfile(
*
* @param dec decoder object
* @param color_encoding the default color encoding to set
- * @return @ref JXL_DEC_SUCCESS if the preference was set successfully, @ref
+ * @return ::JXL_DEC_SUCCESS if the preference was set successfully, @ref
* JXL_DEC_ERROR otherwise.
*/
JXL_EXPORT JxlDecoderStatus JxlDecoderSetPreferredColorProfile(
@@ -814,7 +829,7 @@ JXL_EXPORT JxlDecoderStatus JxlDecoderSetPreferredColorProfile(
* change from version to version.
* @param dec decoder object
* @param desired_intensity_target the intended target peak luminance
- * @return @ref JXL_DEC_SUCCESS if the preference was set successfully, @ref
+ * @return ::JXL_DEC_SUCCESS if the preference was set successfully, @ref
* JXL_DEC_ERROR otherwise.
*/
JXL_EXPORT JxlDecoderStatus JxlDecoderSetDesiredIntensityTarget(
@@ -823,7 +838,7 @@ JXL_EXPORT JxlDecoderStatus JxlDecoderSetDesiredIntensityTarget(
/**
* Sets the desired output color profile of the decoded image either from a
* color encoding or an ICC profile. Valid calls of this function have either @c
- * color_encoding or @c icc_data set to NULL and @c icc_size must be 0 if and
+ * color_encoding or @c icc_data set to NULL and @c icc_size must be `0` if and
* only if @c icc_data is NULL.
*
* Depending on whether a color management system (CMS) has been set the
@@ -848,17 +863,17 @@ JXL_EXPORT JxlDecoderStatus JxlDecoderSetDesiredIntensityTarget(
* If called with an ICC profile (after a call to @ref JxlDecoderSetCms), the
* ICC profile has to be a valid RGB or grayscale color profile.
*
- * Can only be set after the @ref JXL_DEC_COLOR_ENCODING event occurred and
+ * Can only be set after the ::JXL_DEC_COLOR_ENCODING event occurred and
* before any other event occurred, and should be used before getting
- * JXL_COLOR_PROFILE_TARGET_DATA.
+ * ::JXL_COLOR_PROFILE_TARGET_DATA.
*
- * This function must not be called before JxlDecoderSetCms.
+ * This function must not be called before @ref JxlDecoderSetCms.
*
* @param dec decoder orbject
* @param color_encoding the output color encoding
* @param icc_data bytes of the icc profile
* @param icc_size size of the icc profile in bytes
- * @return @ref JXL_DEC_SUCCESS if the color profile was set successfully, @ref
+ * @return ::JXL_DEC_SUCCESS if the color profile was set successfully, @ref
* JXL_DEC_ERROR otherwise.
*/
JXL_EXPORT JxlDecoderStatus JxlDecoderSetOutputColorProfile(
@@ -891,7 +906,7 @@ JXL_EXPORT JxlDecoderStatus JxlDecoderSetCms(JxlDecoder* dec,
* @param dec decoder object
* @param format format of pixels
* @param size output value, buffer size in bytes
- * @return @ref JXL_DEC_SUCCESS on success, @ref JXL_DEC_ERROR on error, such as
+ * @return ::JXL_DEC_SUCCESS on success, ::JXL_DEC_ERROR on error, such as
* information not available yet.
*/
JXL_EXPORT JxlDecoderStatus JxlDecoderPreviewOutBufferSize(
@@ -901,15 +916,15 @@ JXL_EXPORT JxlDecoderStatus JxlDecoderPreviewOutBufferSize(
* Sets the buffer to write the small resolution preview image
* to. The size of the buffer must be at least as large as given by @ref
* JxlDecoderPreviewOutBufferSize. The buffer follows the format described
- * by JxlPixelFormat. The preview image dimensions are given by the
- * JxlPreviewHeader. The buffer is owned by the caller.
+ * by @ref JxlPixelFormat. The preview image dimensions are given by the
+ * @ref JxlPreviewHeader. The buffer is owned by the caller.
*
* @param dec decoder object
* @param format format of pixels. Object owned by user and its contents are
* copied internally.
* @param buffer buffer type to output the pixel data to
* @param size size of buffer in bytes
- * @return @ref JXL_DEC_SUCCESS on success, @ref JXL_DEC_ERROR on error, such as
+ * @return ::JXL_DEC_SUCCESS on success, ::JXL_DEC_ERROR on error, such as
* size too small.
*/
JXL_EXPORT JxlDecoderStatus JxlDecoderSetPreviewOutBuffer(
@@ -917,14 +932,14 @@ JXL_EXPORT JxlDecoderStatus JxlDecoderSetPreviewOutBuffer(
/**
* Outputs the information from the frame, such as duration when have_animation.
- * This function can be called when @ref JXL_DEC_FRAME occurred for the current
+ * This function can be called when ::JXL_DEC_FRAME occurred for the current
* frame, even when have_animation in the JxlBasicInfo is JXL_FALSE.
*
* @param dec decoder object
* @param header struct to copy the information into, or NULL to only check
* whether the information is available through the return value.
- * @return @ref JXL_DEC_SUCCESS if the value is available, @ref
- * JXL_DEC_NEED_MORE_INPUT if not yet available, @ref JXL_DEC_ERROR in
+ * @return ::JXL_DEC_SUCCESS if the value is available, @ref
+ * JXL_DEC_NEED_MORE_INPUT if not yet available, ::JXL_DEC_ERROR in
* case of other error conditions.
*/
JXL_EXPORT JxlDecoderStatus JxlDecoderGetFrameHeader(const JxlDecoder* dec,
@@ -932,14 +947,14 @@ JXL_EXPORT JxlDecoderStatus JxlDecoderGetFrameHeader(const JxlDecoder* dec,
/**
* Outputs name for the current frame. The buffer for name must have at least
- * name_length + 1 bytes allocated, gotten from the associated JxlFrameHeader.
+ * `name_length + 1` bytes allocated, gotten from the associated JxlFrameHeader.
*
* @param dec decoder object
* @param name buffer to copy the name into
* @param size size of the name buffer in bytes, including zero termination
- * character, so this must be at least JxlFrameHeader.name_length + 1.
- * @return @ref JXL_DEC_SUCCESS if the value is available, @ref
- * JXL_DEC_NEED_MORE_INPUT if not yet available, @ref JXL_DEC_ERROR in
+ * character, so this must be at least @ref JxlFrameHeader.name_length + 1.
+ * @return ::JXL_DEC_SUCCESS if the value is available, @ref
+ * JXL_DEC_NEED_MORE_INPUT if not yet available, ::JXL_DEC_ERROR in
* case of other error conditions.
*/
JXL_EXPORT JxlDecoderStatus JxlDecoderGetFrameName(const JxlDecoder* dec,
@@ -947,15 +962,15 @@ JXL_EXPORT JxlDecoderStatus JxlDecoderGetFrameName(const JxlDecoder* dec,
/**
* Outputs the blend information for the current frame for a specific extra
- * channel. This function can be called when @ref JXL_DEC_FRAME occurred for the
- * current frame, even when have_animation in the JxlBasicInfo is JXL_FALSE.
- * This information is only useful if coalescing is disabled; otherwise the
- * decoder will have performed blending already.
+ * channel. This function can be called when ::JXL_DEC_FRAME occurred for the
+ * current frame, even when have_animation in the @ref JxlBasicInfo is @ref
+ * JXL_FALSE. This information is only useful if coalescing is disabled;
+ * otherwise the decoder will have performed blending already.
*
* @param dec decoder object
* @param index the index of the extra channel
* @param blend_info struct to copy the information into
- * @return @ref JXL_DEC_SUCCESS on success, @ref JXL_DEC_ERROR on error
+ * @return ::JXL_DEC_SUCCESS on success, ::JXL_DEC_ERROR on error
*/
JXL_EXPORT JxlDecoderStatus JxlDecoderGetExtraChannelBlendInfo(
const JxlDecoder* dec, size_t index, JxlBlendInfo* blend_info);
@@ -965,14 +980,14 @@ JXL_EXPORT JxlDecoderStatus JxlDecoderGetExtraChannelBlendInfo(
* given format. This is the buffer for @ref JxlDecoderSetImageOutBuffer.
* Requires that the basic image information is available in the decoder in the
* case of coalescing enabled (default). In case coalescing is disabled, this
- * can only be called after the @ref JXL_DEC_FRAME event occurs. In that case,
+ * can only be called after the ::JXL_DEC_FRAME event occurs. In that case,
* it will return the size required to store the possibly cropped frame (which
* can be larger or smaller than the image dimensions).
*
* @param dec decoder object
* @param format format of the pixels.
* @param size output value, buffer size in bytes
- * @return @ref JXL_DEC_SUCCESS on success, @ref JXL_DEC_ERROR on error, such as
+ * @return ::JXL_DEC_SUCCESS on success, ::JXL_DEC_ERROR on error, such as
* information not available yet.
*/
JXL_EXPORT JxlDecoderStatus JxlDecoderImageOutBufferSize(
@@ -980,18 +995,18 @@ JXL_EXPORT JxlDecoderStatus JxlDecoderImageOutBufferSize(
/**
* Sets the buffer to write the full resolution image to. This can be set when
- * the @ref JXL_DEC_FRAME event occurs, must be set when the @ref
+ * the ::JXL_DEC_FRAME event occurs, must be set when the @ref
* JXL_DEC_NEED_IMAGE_OUT_BUFFER event occurs, and applies only for the
* current frame. The size of the buffer must be at least as large as given
* by @ref JxlDecoderImageOutBufferSize. The buffer follows the format described
- * by JxlPixelFormat. The buffer is owned by the caller.
+ * by @ref JxlPixelFormat. The buffer is owned by the caller.
*
* @param dec decoder object
* @param format format of the pixels. Object owned by user and its contents
* are copied internally.
* @param buffer buffer type to output the pixel data to
* @param size size of buffer in bytes
- * @return @ref JXL_DEC_SUCCESS on success, @ref JXL_DEC_ERROR on error, such as
+ * @return ::JXL_DEC_SUCCESS on success, ::JXL_DEC_ERROR on error, such as
* size too small.
*/
JXL_EXPORT JxlDecoderStatus JxlDecoderSetImageOutBuffer(
@@ -1062,15 +1077,15 @@ typedef void (*JxlImageOutDestroyCallback)(void* run_opaque);
/**
* Sets pixel output callback. This is an alternative to @ref
- * JxlDecoderSetImageOutBuffer. This can be set when the @ref JXL_DEC_FRAME
- * event occurs, must be set when the @ref JXL_DEC_NEED_IMAGE_OUT_BUFFER event
+ * JxlDecoderSetImageOutBuffer. This can be set when the ::JXL_DEC_FRAME
+ * event occurs, must be set when the ::JXL_DEC_NEED_IMAGE_OUT_BUFFER event
* occurs, and applies only for the current frame. Only one of @ref
* JxlDecoderSetImageOutBuffer or @ref JxlDecoderSetImageOutCallback may be used
* for the same frame, not both at the same time.
*
* The callback will be called multiple times, to receive the image
* data in small chunks. The callback receives a horizontal stripe of pixel
- * data, 1 pixel high, xsize pixels wide, called a scanline. The xsize here is
+ * data, `1` pixel high, xsize pixels wide, called a scanline. The xsize here is
* not the same as the full image width, the scanline may be a partial section,
* and xsize may differ between calls. The user can then process and/or copy the
* partial scanline to an image buffer. The callback may be called
@@ -1099,7 +1114,7 @@ typedef void (*JxlImageOutDestroyCallback)(void* run_opaque);
* data.
* @param opaque optional user data, which will be passed on to the callback,
* may be NULL.
- * @return @ref JXL_DEC_SUCCESS on success, @ref JXL_DEC_ERROR on error, such
+ * @return ::JXL_DEC_SUCCESS on success, ::JXL_DEC_ERROR on error, such
* as @ref JxlDecoderSetImageOutBuffer already set.
*/
JXL_EXPORT JxlDecoderStatus
@@ -1122,7 +1137,7 @@ JxlDecoderSetImageOutCallback(JxlDecoder* dec, const JxlPixelFormat* format,
* @param init_opaque optional user data passed to @c init_callback, may be NULL
* (unlike the return value from @c init_callback which may only be NULL if
* initialization failed).
- * @return @ref JXL_DEC_SUCCESS on success, @ref JXL_DEC_ERROR on error, such
+ * @return ::JXL_DEC_SUCCESS on success, ::JXL_DEC_ERROR on error, such
* as @ref JxlDecoderSetImageOutBuffer having already been called.
*/
JXL_EXPORT JxlDecoderStatus JxlDecoderSetMultithreadedImageOutCallback(
@@ -1137,12 +1152,12 @@ JXL_EXPORT JxlDecoderStatus JxlDecoderSetMultithreadedImageOutCallback(
*
* @param dec decoder object
* @param format format of the pixels. The num_channels value is ignored and is
- * always treated to be 1.
+ * always treated to be `1`.
* @param size output value, buffer size in bytes
* @param index which extra channel to get, matching the index used in @ref
* JxlDecoderGetExtraChannelInfo. Must be smaller than num_extra_channels in
- * the associated JxlBasicInfo.
- * @return @ref JXL_DEC_SUCCESS on success, @ref JXL_DEC_ERROR on error, such as
+ * the associated @ref JxlBasicInfo.
+ * @return ::JXL_DEC_SUCCESS on success, ::JXL_DEC_ERROR on error, such as
* information not available yet or invalid index.
*/
JXL_EXPORT JxlDecoderStatus JxlDecoderExtraChannelBufferSize(
@@ -1151,13 +1166,13 @@ JXL_EXPORT JxlDecoderStatus JxlDecoderExtraChannelBufferSize(
/**
* Sets the buffer to write an extra channel to. This can be set when
- * the @ref JXL_DEC_FRAME or @ref JXL_DEC_NEED_IMAGE_OUT_BUFFER event occurs,
+ * the ::JXL_DEC_FRAME or ::JXL_DEC_NEED_IMAGE_OUT_BUFFER event occurs,
* and applies only for the current frame. The size of the buffer must be at
* least as large as given by @ref JxlDecoderExtraChannelBufferSize. The buffer
- * follows the format described by JxlPixelFormat, but where num_channels is 1.
- * The buffer is owned by the caller. The amount of extra channels is given by
- * the num_extra_channels field in the associated JxlBasicInfo, and the
- * information of individual extra channels can be queried with @ref
+ * follows the format described by @ref JxlPixelFormat, but where num_channels
+ * is `1`. The buffer is owned by the caller. The amount of extra channels is
+ * given by the num_extra_channels field in the associated @ref JxlBasicInfo,
+ * and the information of individual extra channels can be queried with @ref
* JxlDecoderGetExtraChannelInfo. To get multiple extra channels, this function
* must be called multiple times, once for each wanted index. Not all images
* have extra channels. The alpha channel is an extra channel and can be gotten
@@ -1170,13 +1185,13 @@ JXL_EXPORT JxlDecoderStatus JxlDecoderExtraChannelBufferSize(
* @param dec decoder object
* @param format format of the pixels. Object owned by user and its contents
* are copied internally. The num_channels value is ignored and is always
- * treated to be 1.
+ * treated to be `1`.
* @param buffer buffer type to output the pixel data to
* @param size size of buffer in bytes
* @param index which extra channel to get, matching the index used in @ref
* JxlDecoderGetExtraChannelInfo. Must be smaller than num_extra_channels in
- * the associated JxlBasicInfo.
- * @return @ref JXL_DEC_SUCCESS on success, @ref JXL_DEC_ERROR on error, such as
+ * the associated @ref JxlBasicInfo.
+ * @return ::JXL_DEC_SUCCESS on success, ::JXL_DEC_ERROR on error, such as
* size too small or invalid index.
*/
JXL_EXPORT JxlDecoderStatus
@@ -1197,8 +1212,8 @@ JxlDecoderSetExtraChannelBuffer(JxlDecoder* dec, const JxlPixelFormat* format,
* @param dec decoder object
* @param data pointer to next bytes to write to
* @param size amount of bytes available starting from data
- * @return @ref JXL_DEC_ERROR if output buffer was already set and @ref
- * JxlDecoderReleaseJPEGBuffer was not called on it, @ref JXL_DEC_SUCCESS
+ * @return ::JXL_DEC_ERROR if output buffer was already set and @ref
+ * JxlDecoderReleaseJPEGBuffer was not called on it, ::JXL_DEC_SUCCESS
* otherwise
*/
JXL_EXPORT JxlDecoderStatus JxlDecoderSetJPEGBuffer(JxlDecoder* dec,
@@ -1213,11 +1228,11 @@ JXL_EXPORT JxlDecoderStatus JxlDecoderSetJPEGBuffer(JxlDecoder* dec,
* JxlDecoderDestroy or @ref JxlDecoderReset.
*
* Calling @ref JxlDecoderReleaseJPEGBuffer when no buffer is set is
- * not an error and returns 0.
+ * not an error and returns `0`.
*
* @param dec decoder object
* @return the amount of bytes the decoder has not yet written to of the data
- * set by @ref JxlDecoderSetJPEGBuffer, or 0 if no buffer is set or @ref
+ * set by @ref JxlDecoderSetJPEGBuffer, or `0` if no buffer is set or @ref
* JxlDecoderReleaseJPEGBuffer was already called.
*/
JXL_EXPORT size_t JxlDecoderReleaseJPEGBuffer(JxlDecoder* dec);
@@ -1233,15 +1248,15 @@ JXL_EXPORT size_t JxlDecoderReleaseJPEGBuffer(JxlDecoder* dec);
* JxlDecoderReleaseBoxBuffer, bytes that the decoder has already output
* should not be included, only the remaining bytes output must be set.
*
- * The @ref JxlDecoderReleaseBoxBuffer must be used at the next @ref JXL_DEC_BOX
- * event or final @ref JXL_DEC_SUCCESS event to compute the size of the output
+ * The @ref JxlDecoderReleaseBoxBuffer must be used at the next ::JXL_DEC_BOX
+ * event or final ::JXL_DEC_SUCCESS event to compute the size of the output
* box bytes.
*
* @param dec decoder object
* @param data pointer to next bytes to write to
* @param size amount of bytes available starting from data
- * @return @ref JXL_DEC_ERROR if output buffer was already set and @ref
- * JxlDecoderReleaseBoxBuffer was not called on it, @ref JXL_DEC_SUCCESS
+ * @return ::JXL_DEC_ERROR if output buffer was already set and @ref
+ * JxlDecoderReleaseBoxBuffer was not called on it, ::JXL_DEC_SUCCESS
* otherwise
*/
JXL_EXPORT JxlDecoderStatus JxlDecoderSetBoxBuffer(JxlDecoder* dec,
@@ -1256,11 +1271,11 @@ JXL_EXPORT JxlDecoderStatus JxlDecoderSetBoxBuffer(JxlDecoder* dec,
* JxlDecoderDestroy or @ref JxlDecoderReset.
*
* Calling @ref JxlDecoderReleaseBoxBuffer when no buffer is set is
- * not an error and returns 0.
+ * not an error and returns `0`.
*
* @param dec decoder object
* @return the amount of bytes the decoder has not yet written to of the data
- * set by @ref JxlDecoderSetBoxBuffer, or 0 if no buffer is set or @ref
+ * set by @ref JxlDecoderSetBoxBuffer, or `0` if no buffer is set or @ref
* JxlDecoderReleaseBoxBuffer was already called.
*/
JXL_EXPORT size_t JxlDecoderReleaseBoxBuffer(JxlDecoder* dec);
@@ -1274,23 +1289,23 @@ JXL_EXPORT size_t JxlDecoderReleaseBoxBuffer(JxlDecoder* dec);
* finished.
*
* The default mode is raw. This setting can only be changed before decoding, or
- * directly after a @ref JXL_DEC_BOX event, and is remembered until the decoder
+ * directly after a ::JXL_DEC_BOX event, and is remembered until the decoder
* is reset or destroyed.
*
* Enabling decompressed mode requires Brotli support from the library.
*
* @param dec decoder object
- * @param decompress JXL_TRUE to transparently decompress, JXL_FALSE to get
- * boxes in raw mode.
- * @return @ref JXL_DEC_ERROR if decompressed mode is set and Brotli is not
- * available, @ref JXL_DEC_SUCCESS otherwise.
+ * @param decompress ::JXL_TRUE to transparently decompress, ::JXL_FALSE
+ * to get boxes in raw mode.
+ * @return ::JXL_DEC_ERROR if decompressed mode is set and Brotli is not
+ * available, ::JXL_DEC_SUCCESS otherwise.
*/
JXL_EXPORT JxlDecoderStatus JxlDecoderSetDecompressBoxes(JxlDecoder* dec,
JXL_BOOL decompress);
/**
- * Outputs the type of the current box, after a @ref JXL_DEC_BOX event occurred,
- * as 4 characters without null termination character. In case of a compressed
+ * Outputs the type of the current box, after a ::JXL_DEC_BOX event occurred,
+ * as `4` characters without null termination character. In case of a compressed
* "brob" box, this will return "brob" if the decompressed argument is
* JXL_FALSE, or the underlying box type if the decompressed argument is
* JXL_TRUE.
@@ -1306,15 +1321,15 @@ JXL_EXPORT JxlDecoderStatus JxlDecoderSetDecompressBoxes(JxlDecoder* dec,
* - "xml ": a box with XML data, in particular XMP metadata.
* - "jumb": a JUMBF superbox (JPEG Universal Metadata Box Format, ISO/IEC
* 19566-5).
- * - "JXL ": mandatory signature box, must come first, 12 bytes long including
- * the box header
- * - "ftyp": a second mandatory signature box, must come second, 20 bytes long
- * including the box header
- * - "jxll": a JXL level box. This indicates if the codestream is level 5 or
- * level 10 compatible. If not present, it is level 5. Level 10 allows more
- * features such as very high image resolution and bit-depths above 16 bits
- * per channel. Added automatically by the encoder when
- * JxlEncoderSetCodestreamLevel is used
+ * - "JXL ": mandatory signature box, must come first, `12` bytes long
+ * including the box header
+ * - "ftyp": a second mandatory signature box, must come second, `20` bytes
+ * long including the box header
+ * - "jxll": a JXL level box. This indicates if the codestream is level `5` or
+ * level `10` compatible. If not present, it is level `5`. Level `10` allows
+ * more features such as very high image resolution and bit-depths above `16`
+ * bits per channel. Added automatically by the encoder when
+ * @ref JxlEncoderSetCodestreamLevel is used
* - "jxlc": a box with the image codestream, in case the codestream is not
* split across multiple boxes. The codestream contains the JPEG XL image
* itself, including the basic info such as image dimensions, ICC color
@@ -1350,7 +1365,7 @@ JXL_EXPORT JxlDecoderStatus JxlDecoderSetDecompressBoxes(JxlDecoder* dec,
* @param type buffer to copy the type into
* @param decompressed which box type to get: JXL_FALSE to get the raw box type,
* which can be "brob", JXL_TRUE, get the underlying box type.
- * @return @ref JXL_DEC_SUCCESS if the value is available, @ref JXL_DEC_ERROR if
+ * @return ::JXL_DEC_SUCCESS if the value is available, ::JXL_DEC_ERROR if
* not, for example the JXL file does not use the container format.
*/
JXL_EXPORT JxlDecoderStatus JxlDecoderGetBoxType(JxlDecoder* dec,
@@ -1363,13 +1378,29 @@ JXL_EXPORT JxlDecoderStatus JxlDecoderGetBoxType(JxlDecoder* dec,
*
* @param dec decoder object
* @param size raw size of the box in bytes
- * @return @ref JXL_DEC_ERROR if no box size is available, @ref JXL_DEC_SUCCESS
+ * @return ::JXL_DEC_ERROR if no box size is available, ::JXL_DEC_SUCCESS
* otherwise.
*/
JXL_EXPORT JxlDecoderStatus JxlDecoderGetBoxSizeRaw(const JxlDecoder* dec,
uint64_t* size);
/**
+ * Returns the size of the contents of a box, after the @ref
+ * JXL_DEC_BOX event. This does not include any of the headers of the box. For
+ * compressed "brob" boxes, this is the size of the compressed content. Even
+ * when @ref JxlDecoderSetDecompressBoxes is enabled, the return value of
+ * function does not change, and the decompressed size is not known before it
+ * has already been decompressed and output.
+ *
+ * @param dec decoder object
+ * @param size size of the payload of the box in bytes
+ * @return @ref JXL_DEC_ERROR if no box size is available, @ref JXL_DEC_SUCCESS
+ * otherwise.
+ */
+JXL_EXPORT JxlDecoderStatus JxlDecoderGetBoxSizeContents(const JxlDecoder* dec,
+ uint64_t* size);
+
+/**
* Configures at which progressive steps in frame decoding these @ref
* JXL_DEC_FRAME_PROGRESSION event occurs. The default value for the level
* of detail if this function is never called is `kDC`.
@@ -1377,7 +1408,7 @@ JXL_EXPORT JxlDecoderStatus JxlDecoderGetBoxSizeRaw(const JxlDecoder* dec,
* @param dec decoder object
* @param detail at which level of detail to trigger @ref
* JXL_DEC_FRAME_PROGRESSION
- * @return @ref JXL_DEC_SUCCESS on success, @ref JXL_DEC_ERROR on error, such as
+ * @return ::JXL_DEC_SUCCESS on success, ::JXL_DEC_ERROR on error, such as
* an invalid value for the progressive detail.
*/
JXL_EXPORT JxlDecoderStatus
@@ -1385,11 +1416,11 @@ JxlDecoderSetProgressiveDetail(JxlDecoder* dec, JxlProgressiveDetail detail);
/**
* Returns the intended downsampling ratio for the progressive frame produced
- * by @ref JxlDecoderFlushImage after the latest @ref JXL_DEC_FRAME_PROGRESSION
+ * by @ref JxlDecoderFlushImage after the latest ::JXL_DEC_FRAME_PROGRESSION
* event.
*
* @param dec decoder object
- * @return The intended downsampling ratio, can be 1, 2, 4 or 8.
+ * @return The intended downsampling ratio, can be `1`, `2`, `4` or `8`.
*/
JXL_EXPORT size_t JxlDecoderGetIntendedDownsamplingRatio(JxlDecoder* dec);
@@ -1399,12 +1430,12 @@ JXL_EXPORT size_t JxlDecoderGetIntendedDownsamplingRatio(JxlDecoder* dec);
* JxlDecoderSetImageOutBuffer will contain partial image data.
*
* Can be called when @ref JxlDecoderProcessInput returns @ref
- * JXL_DEC_NEED_MORE_INPUT, after the @ref JXL_DEC_FRAME event already occurred
- * and before the @ref JXL_DEC_FULL_IMAGE event occurred for a frame.
+ * JXL_DEC_NEED_MORE_INPUT, after the ::JXL_DEC_FRAME event already occurred
+ * and before the ::JXL_DEC_FULL_IMAGE event occurred for a frame.
*
* @param dec decoder object
- * @return @ref JXL_DEC_SUCCESS if image data was flushed to the output buffer,
- * or @ref JXL_DEC_ERROR when no flush was done, e.g. if not enough image
+ * @return ::JXL_DEC_SUCCESS if image data was flushed to the output buffer,
+ * or ::JXL_DEC_ERROR when no flush was done, e.g. if not enough image
* data was available yet even for flush, or no output buffer was set yet.
* This error is not fatal, it only indicates no flushed image is available
* right now. Regular decoding can still be performed.
@@ -1416,11 +1447,11 @@ JXL_EXPORT JxlDecoderStatus JxlDecoderFlushImage(JxlDecoder* dec);
*
* Can be called after @ref JxlDecoderSetImageOutBuffer or @ref
* JxlDecoderSetImageOutCallback. For float pixel data types, only the default
- * @ref JXL_BIT_DEPTH_FROM_PIXEL_FORMAT setting is supported.
+ * ::JXL_BIT_DEPTH_FROM_PIXEL_FORMAT setting is supported.
*
* @param dec decoder object
* @param bit_depth the bit depth setting of the pixel output
- * @return @ref JXL_DEC_SUCCESS on success, @ref JXL_DEC_ERROR on error, such as
+ * @return ::JXL_DEC_SUCCESS on success, ::JXL_DEC_ERROR on error, such as
* incompatible custom bit depth and pixel data type.
*/
JXL_EXPORT JxlDecoderStatus
diff --git a/third_party/jpeg-xl/lib/include/jxl/encode.h b/third_party/jpeg-xl/lib/include/jxl/encode.h
index 2a87821f06..bb11dd7572 100644
--- a/third_party/jpeg-xl/lib/include/jxl/encode.h
+++ b/third_party/jpeg-xl/lib/include/jxl/encode.h
@@ -41,8 +41,8 @@ JXL_EXPORT uint32_t JxlEncoderVersion(void);
/**
* Opaque structure that holds the JPEG XL encoder.
*
- * Allocated and initialized with JxlEncoderCreate().
- * Cleaned up and deallocated with JxlEncoderDestroy().
+ * Allocated and initialized with @ref JxlEncoderCreate().
+ * Cleaned up and deallocated with @ref JxlEncoderDestroy().
*/
typedef struct JxlEncoderStruct JxlEncoder;
@@ -50,9 +50,9 @@ typedef struct JxlEncoderStruct JxlEncoder;
* Settings and metadata for a single image frame. This includes encoder options
* for a frame such as compression quality and speed.
*
- * Allocated and initialized with JxlEncoderFrameSettingsCreate().
+ * Allocated and initialized with @ref JxlEncoderFrameSettingsCreate().
* Cleaned up and deallocated when the encoder is destroyed with
- * JxlEncoderDestroy().
+ * @ref JxlEncoderDestroy().
*/
typedef struct JxlEncoderFrameSettingsStruct JxlEncoderFrameSettings;
@@ -126,7 +126,7 @@ typedef enum {
typedef enum {
/** 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.
+ * 4:cheetah 5:hare 6:wombat 7:squirrel 8:kitten 9:tortoise 10:glacier.
* Default: squirrel (7).
*/
JXL_ENC_FRAME_SETTING_EFFORT = 0,
@@ -145,7 +145,7 @@ typedef enum {
*/
JXL_ENC_FRAME_SETTING_RESAMPLING = 2,
- /** Similar to JXL_ENC_FRAME_SETTING_RESAMPLING, but for extra channels.
+ /** Similar to ::JXL_ENC_FRAME_SETTING_RESAMPLING, but for extra channels.
* Integer option, use -1 for the default behavior (depends on encoder
* implementation), 1 for no downsampling (1x1), 2 for 2x2 downsampling, 4 for
* 4x4 downsampling, 8 for 8x8 downsampling.
@@ -158,7 +158,7 @@ typedef enum {
* downsampled resolution, not the full image resolution. The downsampled
* resolution is given by ceil(xsize / resampling), ceil(ysize / resampling)
* with xsize and ysize the dimensions given in the basic info, and resampling
- * the factor set with @ref JXL_ENC_FRAME_SETTING_RESAMPLING.
+ * the factor set with ::JXL_ENC_FRAME_SETTING_RESAMPLING.
* Use 0 to disable, 1 to enable. Default value is 0.
*/
JXL_ENC_FRAME_SETTING_ALREADY_DOWNSAMPLED = 4,
@@ -171,8 +171,8 @@ typedef enum {
JXL_ENC_FRAME_SETTING_PHOTON_NOISE = 5,
/** Enables adaptive noise generation. This setting is not recommended for
- * use, please use JXL_ENC_FRAME_SETTING_PHOTON_NOISE instead. Use -1 for the
- * default (encoder chooses), 0 to disable, 1 to enable.
+ * use, please use ::JXL_ENC_FRAME_SETTING_PHOTON_NOISE instead. Use -1 for
+ * the default (encoder chooses), 0 to disable, 1 to enable.
*/
JXL_ENC_FRAME_SETTING_NOISE = 6,
@@ -320,27 +320,28 @@ typedef enum {
* 1 = index this frame within the Frame Index Box.
* If any frames are indexed, the first frame needs to
* be indexed, too. If the first frame is not indexed, and
- * a later frame is attempted to be indexed, JXL_ENC_ERROR will occur.
+ * a later frame is attempted to be indexed, ::JXL_ENC_ERROR will occur.
* If non-keyframes, i.e., frames with cropping, blending or patches are
- * attempted to be indexed, JXL_ENC_ERROR will occur.
+ * attempted to be indexed, ::JXL_ENC_ERROR will occur.
*/
JXL_ENC_FRAME_INDEX_BOX = 31,
- /** Sets brotli encode effort for use in JPEG recompression and compressed
- * metadata boxes (brob). Can be -1 (default) or 0 (fastest) to 11 (slowest).
- * Default is based on the general encode effort in case of JPEG
+ /** Sets brotli encode effort for use in JPEG recompression and
+ * compressed metadata boxes (brob). Can be -1 (default) or 0 (fastest) to 11
+ * (slowest). Default is based on the general encode effort in case of JPEG
* recompression, and 4 for brob boxes.
*/
JXL_ENC_FRAME_SETTING_BROTLI_EFFORT = 32,
/** Enables or disables brotli compression of metadata boxes derived from
- * a JPEG frame when using JxlEncoderAddJPEGFrame. This has no effect on boxes
- * added using JxlEncoderAddBox.
- * -1 = default, 0 = disable compression, 1 = enable compression.
+ * a JPEG frame when using @ref JxlEncoderAddJPEGFrame. This has no effect on
+ * boxes added using @ref JxlEncoderAddBox. -1 = default, 0 = disable
+ * compression, 1 = enable compression.
*/
JXL_ENC_FRAME_SETTING_JPEG_COMPRESS_BOXES = 33,
/** Control what kind of buffering is used, when using chunked image frames.
+ * -1 = default (let the encoder decide)
* 0 = buffers everything, basically the same as non-streamed code path
(mainly for testing)
* 1 = buffers everything for images that are smaller than 2048 x 2048, and
@@ -351,30 +352,30 @@ typedef enum {
*
* When using streaming input and output the encoder minimizes memory usage at
* the cost of compression density. Also note that images produced with
- * streaming mode might can not be decoded progressively.
+ * streaming mode might not be progressively decodeable.
*/
JXL_ENC_FRAME_SETTING_BUFFERING = 34,
/** Keep or discard Exif metadata boxes derived from a JPEG frame when using
- * JxlEncoderAddJPEGFrame. This has no effect on boxes added using
- * JxlEncoderAddBox. When JxlEncoderStoreJPEGMetadata is set to 1, this option
- * cannot be set to 0. Even when Exif metadata is discarded, the orientation
- * will still be applied. 0 = discard Exif metadata, 1 = keep Exif metadata
- * (default).
+ * @ref JxlEncoderAddJPEGFrame. This has no effect on boxes added using
+ * @ref JxlEncoderAddBox. When @ref JxlEncoderStoreJPEGMetadata is set to 1,
+ * this option cannot be set to 0. Even when Exif metadata is discarded, the
+ * orientation will still be applied. 0 = discard Exif metadata, 1 = keep Exif
+ * metadata (default).
*/
JXL_ENC_FRAME_SETTING_JPEG_KEEP_EXIF = 35,
/** Keep or discard XMP metadata boxes derived from a JPEG frame when using
- * JxlEncoderAddJPEGFrame. This has no effect on boxes added using
- * JxlEncoderAddBox. When JxlEncoderStoreJPEGMetadata is set to 1, this option
- * cannot be set to 0. 0 = discard XMP metadata, 1 = keep XMP metadata
- * (default).
+ * @ref JxlEncoderAddJPEGFrame. This has no effect on boxes added using
+ * @ref JxlEncoderAddBox. When @ref JxlEncoderStoreJPEGMetadata is set to 1,
+ * this option cannot be set to 0. 0 = discard XMP metadata, 1 = keep XMP
+ * metadata (default).
*/
JXL_ENC_FRAME_SETTING_JPEG_KEEP_XMP = 36,
/** Keep or discard JUMBF metadata boxes derived from a JPEG frame when using
- * JxlEncoderAddJPEGFrame. This has no effect on boxes added using
- * JxlEncoderAddBox. 0 = discard JUMBF metadata, 1 = keep JUMBF metadata
+ * @ref JxlEncoderAddJPEGFrame. This has no effect on boxes added using
+ * @ref JxlEncoderAddBox. 0 = discard JUMBF metadata, 1 = keep JUMBF metadata
* (default).
*/
JXL_ENC_FRAME_SETTING_JPEG_KEEP_JUMBF = 37,
@@ -395,7 +396,7 @@ typedef enum {
} JxlEncoderFrameSettingId;
/**
- * Creates an instance of JxlEncoder and initializes it.
+ * Creates an instance of @ref JxlEncoder and initializes it.
*
* @p 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
@@ -404,21 +405,21 @@ typedef enum {
* @param memory_manager custom allocator function. It may be NULL. The memory
* manager will be copied internally.
* @return @c NULL if the instance can not be allocated or initialized
- * @return pointer to initialized JxlEncoder otherwise
+ * @return pointer to initialized @ref JxlEncoder otherwise
*/
JXL_EXPORT JxlEncoder* JxlEncoderCreate(const JxlMemoryManager* memory_manager);
/**
- * Re-initializes a JxlEncoder instance, so it can be re-used for encoding
+ * Re-initializes a @ref 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.
+ * newly created with @ref JxlEncoderCreate, but the memory manager is kept.
*
* @param enc instance to be re-initialized.
*/
JXL_EXPORT void JxlEncoderReset(JxlEncoder* enc);
/**
- * Deinitializes and frees JxlEncoder instance.
+ * Deinitializes and frees a @ref JxlEncoder instance.
*
* @param enc instance to be cleaned up and deallocated.
*/
@@ -430,8 +431,8 @@ JXL_EXPORT void JxlEncoderDestroy(JxlEncoder* enc);
* left unset, the default CMS implementation will be used.
*
* @param enc encoder object.
- * @param cms structure representing a CMS implementation. See JxlCmsInterface
- * for more details.
+ * @param cms structure representing a CMS implementation. See @ref
+ * JxlCmsInterface for more details.
*/
JXL_EXPORT void JxlEncoderSetCms(JxlEncoder* enc, JxlCmsInterface cms);
@@ -444,7 +445,7 @@ JXL_EXPORT void JxlEncoderSetCms(JxlEncoder* enc, JxlCmsInterface cms);
* be NULL to use the default, single-threaded, runner. A multithreaded
* runner should be set to reach fast performance.
* @param parallel_runner_opaque opaque pointer for parallel_runner.
- * @return JXL_ENC_SUCCESS if the runner was set, JXL_ENC_ERROR
+ * @return ::JXL_ENC_SUCCESS if the runner was set, ::JXL_ENC_ERROR
* otherwise (the previous runner remains set).
*/
JXL_EXPORT JxlEncoderStatus
@@ -452,16 +453,16 @@ JxlEncoderSetParallelRunner(JxlEncoder* enc, JxlParallelRunner parallel_runner,
void* parallel_runner_opaque);
/**
- * Get the (last) error code in case JXL_ENC_ERROR was returned.
+ * Get the (last) error code in case ::JXL_ENC_ERROR was returned.
*
* @param enc encoder object.
- * @return the JxlEncoderError that caused the (last) JXL_ENC_ERROR to be
- * returned.
+ * @return the @ref JxlEncoderError that caused the (last) ::JXL_ENC_ERROR to
+ * be returned.
*/
JXL_EXPORT JxlEncoderError JxlEncoderGetError(JxlEncoder* enc);
/**
- * Encodes JPEG XL file using the available bytes. @p *avail_out indicates how
+ * Encodes a JPEG XL file using the available bytes. @p *avail_out indicates how
* many output bytes are available, and @p *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
@@ -469,12 +470,12 @@ JXL_EXPORT JxlEncoderError JxlEncoderGetError(JxlEncoder* enc);
* 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.
+ * When the return value is not ::JXL_ENC_ERROR or ::JXL_ENC_SUCCESS, the
+ * encoding requires more @ref JxlEncoderProcessOutput calls to continue.
*
* The caller must guarantee that *avail_out >= 32 when calling
- * JxlEncoderProcessOutput; otherwise, JXL_ENC_NEED_MORE_OUTPUT will be
- * returned. It is guaranteed that, if *avail_out >= 32, at least one byte of
+ * @ref JxlEncoderProcessOutput; otherwise, ::JXL_ENC_NEED_MORE_OUTPUT will
+ * be returned. It is guaranteed that, if *avail_out >= 32, at least one byte of
* output will be written.
*
* This encodes the frames and/or boxes added so far. If the last frame or last
@@ -486,9 +487,9 @@ JXL_EXPORT JxlEncoderError JxlEncoderGetError(JxlEncoder* enc);
* @param enc encoder object.
* @param next_out pointer to next bytes to write to.
* @param avail_out amount of bytes available starting from *next_out.
- * @return JXL_ENC_SUCCESS when encoding finished and all events handled.
- * @return JXL_ENC_ERROR when encoding failed, e.g. invalid input.
- * @return JXL_ENC_NEED_MORE_OUTPUT more output buffer is necessary.
+ * @return ::JXL_ENC_SUCCESS when encoding finished and all events handled.
+ * @return ::JXL_ENC_ERROR when encoding failed, e.g. invalid input.
+ * @return ::JXL_ENC_NEED_MORE_OUTPUT more output buffer is necessary.
*/
JXL_EXPORT JxlEncoderStatus JxlEncoderProcessOutput(JxlEncoder* enc,
uint8_t** next_out,
@@ -509,13 +510,14 @@ JXL_EXPORT JxlEncoderStatus JxlEncoderProcessOutput(JxlEncoder* enc,
* time duration of 0, making them form a composite still. See @ref
* JxlFrameHeader for more information.
*
- * This information is stored in the JxlEncoderFrameSettings and so is used for
- * any frame encoded with these JxlEncoderFrameSettings. It is ok to change
- * between @ref JxlEncoderAddImageFrame calls, each added image frame will have
- * the frame header that was set in the options at the time of calling
- * JxlEncoderAddImageFrame.
+ * This information is stored in the @ref JxlEncoderFrameSettings and so is used
+ * for any frame encoded with these @ref JxlEncoderFrameSettings. It is ok to
+ * change between @ref JxlEncoderAddImageFrame calls, each added image frame
+ * will have the frame header that was set in the options at the time of calling
+ * @ref JxlEncoderAddImageFrame.
*
- * The is_last and name_length fields of the JxlFrameHeader are ignored, use
+ * The is_last and name_length fields of the @ref JxlFrameHeader are ignored,
+ * use
* @ref JxlEncoderCloseFrames to indicate last frame, and @ref
* JxlEncoderSetFrameName to indicate the name and its length instead.
* Calling this function will clear any name that was previously set with @ref
@@ -525,7 +527,7 @@ JXL_EXPORT JxlEncoderStatus JxlEncoderProcessOutput(JxlEncoder* enc,
* includes reference to the encoder object.
* @param frame_header frame header data to set. Object owned by the caller and
* does not need to be kept in memory, its information is copied internally.
- * @return JXL_ENC_SUCCESS on success, JXL_ENC_ERROR on error
+ * @return ::JXL_ENC_SUCCESS on success, ::JXL_ENC_ERROR on error
*/
JXL_EXPORT JxlEncoderStatus
JxlEncoderSetFrameHeader(JxlEncoderFrameSettings* frame_settings,
@@ -540,7 +542,7 @@ JxlEncoderSetFrameHeader(JxlEncoderFrameSettings* frame_settings,
* includes reference to the encoder object.
* @param index index of the extra channel to use.
* @param blend_info blend info to set for the extra channel
- * @return JXL_ENC_SUCCESS on success, JXL_ENC_ERROR on error
+ * @return ::JXL_ENC_SUCCESS on success, ::JXL_ENC_ERROR on error
*/
JXL_EXPORT JxlEncoderStatus JxlEncoderSetExtraChannelBlendInfo(
JxlEncoderFrameSettings* frame_settings, size_t index,
@@ -550,8 +552,9 @@ JXL_EXPORT JxlEncoderStatus JxlEncoderSetExtraChannelBlendInfo(
* Sets the name of the animation frame. This function is optional, frames are
* not required to have a name. This setting is a part of the frame header, and
* the same principles as for @ref JxlEncoderSetFrameHeader apply. The
- * name_length field of JxlFrameHeader is ignored by the encoder, this function
- * determines the name length instead as the length in bytes of the C string.
+ * name_length field of @ref JxlFrameHeader is ignored by the encoder, this
+ * function determines the name length instead as the length in bytes of the C
+ * string.
*
* The maximum possible name length is 1071 bytes (excluding terminating null
* character).
@@ -563,7 +566,7 @@ JXL_EXPORT JxlEncoderStatus JxlEncoderSetExtraChannelBlendInfo(
* includes reference to the encoder object.
* @param frame_name name of the next frame to be encoded, as a UTF-8 encoded C
* string (zero terminated). Owned by the caller, and copied internally.
- * @return JXL_ENC_SUCCESS on success, JXL_ENC_ERROR on error
+ * @return ::JXL_ENC_SUCCESS on success, ::JXL_ENC_ERROR on error
*/
JXL_EXPORT JxlEncoderStatus JxlEncoderSetFrameName(
JxlEncoderFrameSettings* frame_settings, const char* frame_name);
@@ -571,15 +574,17 @@ JXL_EXPORT JxlEncoderStatus JxlEncoderSetFrameName(
/**
* Sets the bit depth of the input buffer.
*
- * For float pixel formats, only the default JXL_BIT_DEPTH_FROM_PIXEL_FORMAT
+ * For float pixel formats, only the default @ref
+ JXL_BIT_DEPTH_FROM_PIXEL_FORMAT
* setting is allowed, while for unsigned pixel formats,
- * JXL_BIT_DEPTH_FROM_CODESTREAM setting is also allowed. See the comment on
+ * ::JXL_BIT_DEPTH_FROM_CODESTREAM setting is also allowed. See the comment
+ on
* @ref JxlEncoderAddImageFrame for the effects of the bit depth setting.
* @param frame_settings set of options and metadata for this frame. Also
* includes reference to the encoder object.
* @param bit_depth the bit depth setting of the pixel input
- * @return JXL_ENC_SUCCESS on success, JXL_ENC_ERROR on error
+ * @return ::JXL_ENC_SUCCESS on success, ::JXL_ENC_ERROR on error
*/
JXL_EXPORT JxlEncoderStatus JxlEncoderSetFrameBitDepth(
JxlEncoderFrameSettings* frame_settings, const JxlBitDepth* bit_depth);
@@ -587,13 +592,13 @@ JXL_EXPORT JxlEncoderStatus JxlEncoderSetFrameBitDepth(
/**
* 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 @ref JxlEncoderSetBasicInfo has not yet been called, calling
+ * @ref 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 @ref JxlEncoderSetColorEncoding or @ref JxlEncoderSetICCProfile has not
+ * yet been called, calling @ref JxlEncoderAddJPEGFrame will implicitly call it
+ * with the parameters of the added JPEG frame.
*
* If the encoder is set to store JPEG reconstruction metadata using @ref
* JxlEncoderStoreJPEGMetadata and a single JPEG frame is added, it will be
@@ -603,12 +608,16 @@ JXL_EXPORT JxlEncoderStatus JxlEncoderSetFrameBitDepth(
* JxlEncoderCloseFrames must be called before the next
* @ref JxlEncoderProcessOutput call.
*
+ * Note, this can only be used to add JPEG frames for lossless compression. To
+ * encode with lossy compression, the JPEG must be decoded manually and a pixel
+ * buffer added using JxlEncoderAddImageFrame.
+ *
* @param frame_settings set of options and metadata for this frame. Also
* includes reference to the encoder object.
* @param buffer bytes to read JPEG from. Owned by the caller and its contents
* are copied internally.
* @param size size of buffer in bytes.
- * @return JXL_ENC_SUCCESS on success, JXL_ENC_ERROR on error
+ * @return ::JXL_ENC_SUCCESS on success, ::JXL_ENC_ERROR on error
*/
JXL_EXPORT JxlEncoderStatus
JxlEncoderAddJPEGFrame(const JxlEncoderFrameSettings* frame_settings,
@@ -616,33 +625,36 @@ JxlEncoderAddJPEGFrame(const JxlEncoderFrameSettings* frame_settings,
/**
* Sets the buffer to read pixels from for the next image to encode. Must call
- * JxlEncoderSetBasicInfo before JxlEncoderAddImageFrame.
+ * @ref JxlEncoderSetBasicInfo before @ref 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
+ * - ::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, together
- * with an optional @ref JxlBitDepth parameter set by @ref
+ * what is described in the @ref JxlBasicInfo. The type in pixel_format,
+ * together with an optional @ref JxlBitDepth parameter set by @ref
* JxlEncoderSetFrameBitDepth 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,
- * while the input frame buffer can be in the following formats:
- * - if pixel format is in JXL_TYPE_UINT16 with default bit depth setting
- * (i.e. JXL_BIT_DEPTH_FROM_PIXEL_FORMAT), input sample values are rescaled
- * to 16-bit, i.e. multiplied by 65535/4095;
- * - if pixel format is in JXL_TYPE_UINT16 with JXL_BIT_DEPTH_FROM_CODESTREAM
- * bit depth setting, input sample values are provided unscaled;
- * - if pixel format is in JXL_TYPE_FLOAT, input sample 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:
+ * buffer. The bits_per_sample and exponent_bits_per_sample in the @ref
+ * 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, while the input frame buffer can be in the following
+ * formats:
+ * - if pixel format is in ::JXL_TYPE_UINT16 with default bit depth setting
+ * (i.e. ::JXL_BIT_DEPTH_FROM_PIXEL_FORMAT), input sample values are
+ * rescaled to 16-bit, i.e. multiplied by 65535/4095;
+ * - if pixel format is in ::JXL_TYPE_UINT16 with @ref
+ * JXL_BIT_DEPTH_FROM_CODESTREAM bit depth setting, input sample values are
+ * provided unscaled;
+ * - if pixel format is in ::JXL_TYPE_FLOAT, input sample 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 @ref JxlBasicInfo.
+ *
+ * We support interleaved channels as described by the @ref JxlPixelFormat
+ * "JxlPixelFormat":
* - single-channel data, e.g. grayscale
* - single-channel + alpha
* - trichromatic, e.g. RGB
@@ -654,10 +666,11 @@ JxlEncoderAddJPEGFrame(const JxlEncoderFrameSettings* frame_settings,
* set to all-opaque (an alpha value of 1.0 everywhere).
*
* The pixels are assumed to be encoded in the original profile that is set with
- * JxlEncoderSetColorEncoding or JxlEncoderSetICCProfile. If none of these
- * functions were used, 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).
+ * @ref JxlEncoderSetColorEncoding or @ref JxlEncoderSetICCProfile. If none of
+ * these functions were used, 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, @ref
+ * 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
@@ -676,14 +689,14 @@ JxlEncoderAddJPEGFrame(const JxlEncoderFrameSettings* frame_settings,
* 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
+ * @return ::JXL_ENC_SUCCESS on success, ::JXL_ENC_ERROR on error
*/
JXL_EXPORT JxlEncoderStatus JxlEncoderAddImageFrame(
const JxlEncoderFrameSettings* frame_settings,
const JxlPixelFormat* pixel_format, const void* buffer, size_t size);
/**
- * The JxlEncoderOutputProcessor structure provides an interface for the
+ * The @ref 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
@@ -785,7 +798,7 @@ struct JxlEncoderOutputProcessor {
* @param enc encoder object.
* @param output_processor the struct containing the callbacks for managing
* output.
- * @return JXL_ENC_SUCCESS on success, JXL_ENC_ERROR on error.
+ * @return ::JXL_ENC_SUCCESS on success, ::JXL_ENC_ERROR on error.
*/
JXL_EXPORT JxlEncoderStatus JxlEncoderSetOutputProcessor(
JxlEncoder* enc, struct JxlEncoderOutputProcessor output_processor);
@@ -801,7 +814,7 @@ JXL_EXPORT JxlEncoderStatus JxlEncoderSetOutputProcessor(
* This should not be used when using @ref JxlEncoderProcessOutput.
*
* @param enc encoder object.
- * @return JXL_ENC_SUCCESS on success, JXL_ENC_ERROR on error.
+ * @return ::JXL_ENC_SUCCESS on success, ::JXL_ENC_ERROR on error.
*/
JXL_EXPORT JxlEncoderStatus JxlEncoderFlushInput(JxlEncoder* enc);
@@ -923,9 +936,9 @@ struct JxlChunkedFrameInputSource {
* chunked or streaming manner, which can be especially useful when dealing with
* large images that may not fit entirely in memory or when trying to optimize
* memory usage. The input data is provided through callbacks defined in the
- * `JxlChunkedFrameInputSource` struct. Once the frame data has been completely
- * retrieved, this function will flush the input and close it if it is the last
- * frame.
+ * @ref JxlChunkedFrameInputSource struct. Once the frame data has been
+ * completely retrieved, this function will flush the input and close it if it
+ * is the last frame.
*
* @param frame_settings set of options and metadata for this frame. Also
* includes reference to the encoder object.
@@ -943,7 +956,7 @@ JXL_EXPORT JxlEncoderStatus JxlEncoderAddChunkedFrame(
/**
* Sets the buffer to read pixels from for an extra channel at a given index.
* The index must be smaller than the num_extra_channels in the associated
- * JxlBasicInfo. Must call @ref JxlEncoderSetExtraChannelInfo before
+ * @ref JxlBasicInfo. Must call @ref JxlEncoderSetExtraChannelInfo before @ref
* JxlEncoderSetExtraChannelBuffer.
*
* TODO(firsching): mention what data types in pixel formats are supported.
@@ -961,15 +974,15 @@ JXL_EXPORT JxlEncoderStatus JxlEncoderAddChunkedFrame(
* @param size size of buffer in bytes. This size should match what is implied
* by the frame dimensions and the pixel format.
* @param index index of the extra channel to use.
- * @return JXL_ENC_SUCCESS on success, JXL_ENC_ERROR on error
+ * @return ::JXL_ENC_SUCCESS on success, ::JXL_ENC_ERROR on error
*/
JXL_EXPORT JxlEncoderStatus JxlEncoderSetExtraChannelBuffer(
const JxlEncoderFrameSettings* frame_settings,
const JxlPixelFormat* pixel_format, const void* buffer, size_t size,
uint32_t index);
-/** Adds a metadata box to the file format. JxlEncoderProcessOutput must be used
- * to effectively write the box to the output. @ref JxlEncoderUseBoxes must
+/** Adds a metadata box to the file format. @ref JxlEncoderProcessOutput must be
+ * used to effectively write the box to the output. @ref JxlEncoderUseBoxes must
* be enabled before using this function.
*
* Boxes allow inserting application-specific data and metadata (Exif, XML/XMP,
@@ -996,10 +1009,10 @@ JXL_EXPORT JxlEncoderStatus JxlEncoderSetExtraChannelBuffer(
* the encoder encodes the size header itself. Most boxes are written
* automatically by the encoder as needed ("JXL ", "ftyp", "jxll", "jxlc",
* "jxlp", "jxli", "jbrd"), and this function only needs to be called to add
- * optional metadata when encoding from pixels (using JxlEncoderAddImageFrame).
- * When recompressing JPEG files (using JxlEncoderAddJPEGFrame), if the input
- * JPEG contains EXIF, XMP or JUMBF metadata, the corresponding boxes are
- * already added automatically.
+ * optional metadata when encoding from pixels (using @ref
+ * JxlEncoderAddImageFrame). When recompressing JPEG files (using @ref
+ * JxlEncoderAddJPEGFrame), if the input JPEG contains EXIF, XMP or JUMBF
+ * metadata, the corresponding boxes are already added automatically.
*
* Box types are given by 4 characters. The following boxes can be added with
* this function:
@@ -1032,9 +1045,9 @@ JXL_EXPORT JxlEncoderStatus JxlEncoderSetExtraChannelBuffer(
* @param size size of the box contents.
* @param compress_box Whether to compress this box as a "brob" box. Requires
* Brotli support.
- * @return JXL_ENC_SUCCESS on success, JXL_ENC_ERROR on error, such as when
- * using this function without JxlEncoderUseContainer, or adding a box type
- * that would result in an invalid file format.
+ * @return ::JXL_ENC_SUCCESS on success, ::JXL_ENC_ERROR on error, such as
+ * when using this function without @ref JxlEncoderUseContainer, or adding a box
+ * type that would result in an invalid file format.
*/
JXL_EXPORT JxlEncoderStatus JxlEncoderAddBox(JxlEncoder* enc,
const JxlBoxType type,
@@ -1061,9 +1074,9 @@ JXL_EXPORT JxlEncoderStatus JxlEncoderUseBoxes(JxlEncoder* enc);
* the stream will be finished. It is not necessary to use this function if
* @ref JxlEncoderUseBoxes is not used. Further frames may still be added.
*
- * Must be called between JxlEncoderAddBox of the last box
- * and the next call to JxlEncoderProcessOutput, or @ref JxlEncoderProcessOutput
- * won't output the last box correctly.
+ * Must be called between @ref JxlEncoderAddBox of the last box
+ * and the next call to @ref JxlEncoderProcessOutput, or @ref
+ * JxlEncoderProcessOutput won't output the last box correctly.
*
* NOTE: if you don't need to close frames and boxes at separate times, you can
* use @ref JxlEncoderCloseInput instead to close both at once.
@@ -1087,10 +1100,10 @@ JXL_EXPORT void JxlEncoderCloseBoxes(JxlEncoder* enc);
JXL_EXPORT void JxlEncoderCloseFrames(JxlEncoder* enc);
/**
- * Closes any input to the encoder, equivalent to calling JxlEncoderCloseFrames
- * as well as calling JxlEncoderCloseBoxes if needed. No further input of any
- * kind may be given to the encoder, but further @ref JxlEncoderProcessOutput
- * calls should be done to create the final output.
+ * Closes any input to the encoder, equivalent to calling @ref
+ * JxlEncoderCloseFrames as well as calling @ref JxlEncoderCloseBoxes if needed.
+ * No further input of any kind may be given to the encoder, but further @ref
+ * JxlEncoderProcessOutput calls should be done to create the final output.
*
* The requirements of both @ref JxlEncoderCloseFrames and @ref
* JxlEncoderCloseBoxes apply to this function. Either this function or the
@@ -1104,39 +1117,39 @@ JXL_EXPORT void JxlEncoderCloseInput(JxlEncoder* enc);
/**
* 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 @ref JxlColorEncoding, while
- * the other sets it as ICC binary data.
- * Must be called after JxlEncoderSetBasicInfo.
+ * is an alternative to @ref JxlEncoderSetICCProfile and only one of these two
+ * must be used. This one sets the color encoding as a @ref JxlColorEncoding,
+ * while the other sets it as ICC binary data. Must be called after @ref
+ * JxlEncoderSetBasicInfo.
*
* @param enc encoder object.
* @param color color encoding. Object owned by the caller and its contents are
* copied internally.
- * @return JXL_ENC_SUCCESS if the operation was successful, JXL_ENC_ERROR or
- * JXL_ENC_NOT_SUPPORTED otherwise
+ * @return ::JXL_ENC_SUCCESS if the operation was successful, @ref
+ * JXL_ENC_ERROR otherwise
*/
JXL_EXPORT JxlEncoderStatus
JxlEncoderSetColorEncoding(JxlEncoder* enc, const JxlColorEncoding* color);
/**
* 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 @ref JxlColorEncoding.
- * Must be called after JxlEncoderSetBasicInfo.
+ * ICC color profile. This is an alternative to @ref 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 @ref JxlColorEncoding. Must
+ * be called after @ref JxlEncoderSetBasicInfo.
*
* @param enc encoder object.
* @param icc_profile bytes of the original ICC profile
* @param size size of the icc_profile buffer in bytes
- * @return JXL_ENC_SUCCESS if the operation was successful, JXL_ENC_ERROR or
- * JXL_ENC_NOT_SUPPORTED otherwise
+ * @return ::JXL_ENC_SUCCESS if the operation was successful, @ref
+ * JXL_ENC_ERROR otherwise
*/
JXL_EXPORT JxlEncoderStatus JxlEncoderSetICCProfile(JxlEncoder* enc,
const uint8_t* icc_profile,
size_t size);
/**
- * Initializes a JxlBasicInfo struct to default values.
+ * Initializes a @ref 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
@@ -1147,7 +1160,7 @@ JXL_EXPORT JxlEncoderStatus JxlEncoderSetICCProfile(JxlEncoder* enc,
JXL_EXPORT void JxlEncoderInitBasicInfo(JxlBasicInfo* info);
/**
- * Initializes a JxlFrameHeader struct to default values.
+ * Initializes a @ref JxlFrameHeader 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 a frame with no animation duration and the
@@ -1159,7 +1172,7 @@ JXL_EXPORT void JxlEncoderInitBasicInfo(JxlBasicInfo* info);
JXL_EXPORT void JxlEncoderInitFrameHeader(JxlFrameHeader* frame_header);
/**
- * Initializes a JxlBlendInfo struct to default values.
+ * Initializes a @ref JxlBlendInfo struct to default values.
* For forwards-compatibility, this function has to be called before values
* are assigned to the struct fields.
*
@@ -1170,26 +1183,26 @@ JXL_EXPORT void JxlEncoderInitBlendInfo(JxlBlendInfo* blend_info);
/**
* Sets the global metadata of the image encoded by this encoder.
*
- * If the JxlBasicInfo contains information of extra channels beyond an alpha
- * channel, then @ref JxlEncoderSetExtraChannelInfo must be called between
- * JxlEncoderSetBasicInfo and @ref JxlEncoderAddImageFrame. In order to indicate
- * extra channels, the value of `info.num_extra_channels` should be set to the
- * number of extra channels, also counting the alpha channel if present.
+ * If the @ref JxlBasicInfo contains information of extra channels beyond an
+ * alpha channel, then @ref JxlEncoderSetExtraChannelInfo must be called between
+ * @ref JxlEncoderSetBasicInfo and @ref JxlEncoderAddImageFrame. In order to
+ * indicate extra channels, the value of `info.num_extra_channels` should be set
+ * to the number of extra channels, also counting the alpha channel if present.
*
* @param enc encoder object.
* @param info global image metadata. Object owned by the caller and its
* contents are copied internally.
- * @return JXL_ENC_SUCCESS if the operation was successful,
- * JXL_ENC_ERROR or JXL_ENC_NOT_SUPPORTED otherwise
+ * @return ::JXL_ENC_SUCCESS if the operation was successful,
+ * ::JXL_ENC_ERROR otherwise
*/
JXL_EXPORT JxlEncoderStatus JxlEncoderSetBasicInfo(JxlEncoder* enc,
const JxlBasicInfo* info);
/**
* Sets the upsampling method the decoder will use in case there are frames
- * with JXL_ENC_FRAME_SETTING_RESAMPLING set. This is useful in combination
- * with the JXL_ENC_FRAME_SETTING_ALREADY_DOWNSAMPLED option, to control the
- * type of upsampling that will be used.
+ * with ::JXL_ENC_FRAME_SETTING_RESAMPLING set. This is useful in combination
+ * with the ::JXL_ENC_FRAME_SETTING_ALREADY_DOWNSAMPLED option, to control
+ * the type of upsampling that will be used.
*
* @param enc encoder object.
* @param factor upsampling factor to configure (1, 2, 4 or 8; for 1 this
@@ -1198,15 +1211,15 @@ JXL_EXPORT JxlEncoderStatus JxlEncoderSetBasicInfo(JxlEncoder* enc,
* -1: default (good for photographic images, no signaling overhead)
* 0: nearest neighbor (good for pixel art)
* 1: 'pixel dots' (same as NN for 2x, diamond-shaped 'pixel dots' for 4x/8x)
- * @return JXL_ENC_SUCCESS if the operation was successful,
- * JXL_ENC_ERROR or JXL_ENC_NOT_SUPPORTED otherwise
+ * @return ::JXL_ENC_SUCCESS if the operation was successful,
+ * ::JXL_ENC_ERROR otherwise
*/
JXL_EXPORT JxlEncoderStatus JxlEncoderSetUpsamplingMode(JxlEncoder* enc,
int64_t factor,
int64_t mode);
/**
- * Initializes a JxlExtraChannelInfo struct to default values.
+ * Initializes a @ref JxlExtraChannelInfo 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 channel of the provided type.
@@ -1220,23 +1233,24 @@ JXL_EXPORT void JxlEncoderInitExtraChannelInfo(JxlExtraChannelType type,
/**
* Sets information for the extra channel at the given index. The index
- * must be smaller than num_extra_channels in the associated JxlBasicInfo.
+ * must be smaller than num_extra_channels in the associated @ref JxlBasicInfo.
*
* @param enc encoder object
* @param index index of the extra channel to set.
* @param info global extra channel metadata. Object owned by the caller and its
* contents are copied internally.
- * @return JXL_ENC_SUCCESS on success, JXL_ENC_ERROR on error
+ * @return ::JXL_ENC_SUCCESS on success, ::JXL_ENC_ERROR on error
*/
JXL_EXPORT JxlEncoderStatus JxlEncoderSetExtraChannelInfo(
JxlEncoder* enc, size_t index, const JxlExtraChannelInfo* info);
/**
* Sets the name for the extra channel at the given index in UTF-8. The index
- * must be smaller than the num_extra_channels in the associated JxlBasicInfo.
+ * must be smaller than the num_extra_channels in the associated @ref
+ * JxlBasicInfo.
*
* TODO(lode): remove size parameter for consistency with
- * JxlEncoderSetFrameName
+ * @ref JxlEncoderSetFrameName
*
* @param enc encoder object
* @param index index of the extra channel to set.
@@ -1252,17 +1266,18 @@ JXL_EXPORT JxlEncoderStatus JxlEncoderSetExtraChannelName(JxlEncoder* enc,
/**
* Sets a frame-specific option of integer type to the encoder options.
- * The JxlEncoderFrameSettingId argument determines which option is set.
+ * The @ref JxlEncoderFrameSettingId argument determines which option is set.
*
* @param frame_settings set of options and metadata for this frame. Also
* includes reference to the encoder object.
* @param option ID of the option to set.
* @param value Integer value to set for this option.
- * @return JXL_ENC_SUCCESS if the operation was successful, JXL_ENC_ERROR in
- * case of an error, such as invalid or unknown option id, or invalid integer
- * value for the given option. If an error is returned, the state of the
- * JxlEncoderFrameSettings object is still valid and is the same as before this
- * function was called.
+ * @return ::JXL_ENC_SUCCESS if the operation was successful, @ref
+ * JXL_ENC_ERROR in case of an error, such as invalid or unknown option id, or
+ * invalid integer value for the given option. If an error is returned, the
+ * state of the
+ * @ref JxlEncoderFrameSettings object is still valid and is the same as before
+ * this function was called.
*/
JXL_EXPORT JxlEncoderStatus JxlEncoderFrameSettingsSetOption(
JxlEncoderFrameSettings* frame_settings, JxlEncoderFrameSettingId option,
@@ -1270,17 +1285,18 @@ JXL_EXPORT JxlEncoderStatus JxlEncoderFrameSettingsSetOption(
/**
* Sets a frame-specific option of float type to the encoder options.
- * The JxlEncoderFrameSettingId argument determines which option is set.
+ * The @ref JxlEncoderFrameSettingId argument determines which option is set.
*
* @param frame_settings set of options and metadata for this frame. Also
* includes reference to the encoder object.
* @param option ID of the option to set.
* @param value Float value to set for this option.
- * @return JXL_ENC_SUCCESS if the operation was successful, JXL_ENC_ERROR in
- * case of an error, such as invalid or unknown option id, or invalid integer
- * value for the given option. If an error is returned, the state of the
- * JxlEncoderFrameSettings object is still valid and is the same as before this
- * function was called.
+ * @return ::JXL_ENC_SUCCESS if the operation was successful, @ref
+ * JXL_ENC_ERROR in case of an error, such as invalid or unknown option id, or
+ * invalid integer value for the given option. If an error is returned, the
+ * state of the
+ * @ref JxlEncoderFrameSettings object is still valid and is the same as before
+ * this function was called.
*/
JXL_EXPORT JxlEncoderStatus JxlEncoderFrameSettingsSetFloatOption(
JxlEncoderFrameSettings* frame_settings, JxlEncoderFrameSettingId option,
@@ -1292,7 +1308,7 @@ JXL_EXPORT JxlEncoderStatus JxlEncoderFrameSettingsSetFloatOption(
* When using @ref JxlEncoderUseBoxes, @ref JxlEncoderStoreJPEGMetadata or @ref
* JxlEncoderSetCodestreamLevel with level 10, the encoder will automatically
* also use the container format, it is not necessary to use
- * JxlEncoderUseContainer for those use cases.
+ * @ref JxlEncoderUseContainer for those use cases.
*
* By default this setting is disabled.
*
@@ -1318,8 +1334,8 @@ JXL_EXPORT JxlEncoderStatus JxlEncoderUseContainer(JxlEncoder* enc,
*
* @param enc encoder object.
* @param store_jpeg_metadata true if the encoder should store JPEG metadata.
- * @return JXL_ENC_SUCCESS if the operation was successful, JXL_ENC_ERROR
- * otherwise.
+ * @return ::JXL_ENC_SUCCESS if the operation was successful, @ref
+ * JXL_ENC_ERROR otherwise.
*/
JXL_EXPORT JxlEncoderStatus
JxlEncoderStoreJPEGMetadata(JxlEncoder* enc, JXL_BOOL store_jpeg_metadata);
@@ -1334,8 +1350,8 @@ JxlEncoderStoreJPEGMetadata(JxlEncoder* enc, JXL_BOOL store_jpeg_metadata);
* 268435456 pixels total with a maximum width or height of 262144 pixels,
* maximum 16-bit color channel depth, maximum 120 frames per second for
* animation, maximum ICC color profile size of 4 MiB, it allows all color
- * models and extra channel types except CMYK and the JXL_CHANNEL_BLACK extra
- * channel, and a maximum of 4 extra channels in addition to the 3 color
+ * models and extra channel types except CMYK and the JXL_CHANNEL_BLACK
+ * extra channel, and a maximum of 4 extra channels in addition to the 3 color
* channels. It also sets boundaries to certain internally used coding tools.
*
* Level 10: this level removes or increases the bounds of most of the level
@@ -1355,8 +1371,8 @@ JxlEncoderStoreJPEGMetadata(JxlEncoder* enc, JXL_BOOL store_jpeg_metadata);
*
* @param enc encoder object.
* @param level the level value to set, must be -1, 5, or 10.
- * @return JXL_ENC_SUCCESS if the operation was successful, JXL_ENC_ERROR
- * otherwise.
+ * @return ::JXL_ENC_SUCCESS if the operation was successful, @ref
+ * JXL_ENC_ERROR otherwise.
*/
JXL_EXPORT JxlEncoderStatus JxlEncoderSetCodestreamLevel(JxlEncoder* enc,
int level);
@@ -1370,9 +1386,10 @@ JXL_EXPORT JxlEncoderStatus JxlEncoderSetCodestreamLevel(JxlEncoder* enc,
* the JPEG XL file.
*
* If this returns 5, nothing needs to be done and the codestream can be
- * compatible with any decoder. If this returns 10, JxlEncoderSetCodestreamLevel
- * has to be used to set the codestream level to 10, or the encoder can be
- * configured differently to allow using the more compatible level 5.
+ * compatible with any decoder. If this returns 10, @ref
+ * JxlEncoderSetCodestreamLevel has to be used to set the codestream level to
+ * 10, or the encoder can be configured differently to allow using the more
+ * compatible level 5.
*
* @param enc encoder object.
* @return -1 if no level can support the configuration (e.g. image dimensions
@@ -1391,14 +1408,14 @@ JXL_EXPORT int JxlEncoderGetRequiredCodestreamLevel(const JxlEncoder* enc);
*
* When disabled, those options are not overridden, but since those options
* could still have been manually set to a combination that operates losslessly,
- * using this function with lossless set to JXL_DEC_FALSE does not guarantee
- * lossy encoding, though the default set of options is lossy.
+ * using this function with lossless set to ::JXL_FALSE does not
+ * guarantee lossy encoding, though the default set of options is lossy.
*
* @param frame_settings set of options and metadata for this frame. Also
* includes reference to the encoder object.
* @param lossless whether to override options for lossless mode
- * @return JXL_ENC_SUCCESS if the operation was successful, JXL_ENC_ERROR
- * otherwise.
+ * @return ::JXL_ENC_SUCCESS if the operation was successful, @ref
+ * JXL_ENC_ERROR otherwise.
*/
JXL_EXPORT JxlEncoderStatus JxlEncoderSetFrameLossless(
JxlEncoderFrameSettings* frame_settings, JXL_BOOL lossless);
@@ -1406,7 +1423,7 @@ JXL_EXPORT JxlEncoderStatus JxlEncoderSetFrameLossless(
/**
* Sets the distance level for lossy compression: target max butteraugli
* distance, lower = higher quality. Range: 0 .. 25.
- * 0.0 = mathematically lossless (however, use JxlEncoderSetFrameLossless
+ * 0.0 = mathematically lossless (however, use @ref JxlEncoderSetFrameLossless
* instead to use true lossless, as setting distance to 0 alone is not the only
* requirement). 1.0 = visually lossless. Recommended range: 0.5 .. 3.0. Default
* value: 1.0.
@@ -1414,24 +1431,25 @@ JXL_EXPORT JxlEncoderStatus JxlEncoderSetFrameLossless(
* @param frame_settings set of options and metadata for this frame. Also
* includes reference to the encoder object.
* @param distance the distance value to set.
- * @return JXL_ENC_SUCCESS if the operation was successful, JXL_ENC_ERROR
- * otherwise.
+ * @return ::JXL_ENC_SUCCESS if the operation was successful, @ref
+ * JXL_ENC_ERROR otherwise.
*/
JXL_EXPORT JxlEncoderStatus JxlEncoderSetFrameDistance(
JxlEncoderFrameSettings* frame_settings, float distance);
/**
* Sets the distance level for lossy compression of extra channels.
- * The distance is as in JxlEncoderSetFrameDistance (lower = higher quality).
- * If not set, or if set to the special value -1, the distance that was set with
- * JxlEncoderSetFrameDistance will be used.
+ * The distance is as in @ref JxlEncoderSetFrameDistance (lower = higher
+ * quality). If not set, or if set to the special value -1, the distance that
+ * was set with
+ * @ref JxlEncoderSetFrameDistance will be used.
*
* @param frame_settings set of options and metadata for this frame. Also
* includes reference to the encoder object.
* @param index index of the extra channel to set a distance value for.
* @param distance the distance value to set.
- * @return JXL_ENC_SUCCESS if the operation was successful, JXL_ENC_ERROR
- * otherwise.
+ * @return ::JXL_ENC_SUCCESS if the operation was successful, @ref
+ * JXL_ENC_ERROR otherwise.
*/
JXL_EXPORT JxlEncoderStatus JxlEncoderSetExtraChannelDistance(
JxlEncoderFrameSettings* frame_settings, size_t index, float distance);
@@ -1441,8 +1459,7 @@ JXL_EXPORT JxlEncoderStatus JxlEncoderSetExtraChannelDistance(
*
* This function takes in input a JPEG-style quality factor `quality` and
* produces as output a `distance` value suitable to be used with @ref
- * JxlEncoderSetFrameDistance and
- * @ref JxlEncoderSetExtraChannelDistance.
+ * JxlEncoderSetFrameDistance and @ref JxlEncoderSetExtraChannelDistance.
*
* The `distance` value influences the level of compression, with lower values
* indicating higher quality:
@@ -1479,10 +1496,10 @@ JXL_EXPORT float JxlEncoderDistanceFromQuality(float quality);
* the @p source options, or set to default if @p 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 @ref JxlEncoder and a @ref JxlEncoderFrameSettings, only
- * JxlEncoderFrameSettings created with this function for the same encoder
- * instance can be used.
+ * deallocated by the encoder when @ref JxlEncoderDestroy() is called. For
+ * functions taking both a @ref JxlEncoder and a @ref JxlEncoderFrameSettings,
+ * only @ref JxlEncoderFrameSettings created with this function for the same
+ * encoder instance can be used.
*
* @param enc encoder object.
* @param source source options to copy initial values from, or NULL to get
@@ -1513,7 +1530,7 @@ JXL_EXPORT void JxlColorEncodingSetToLinearSRGB(
/**
* Enables usage of expert options.
*
- * At the moment, the only expert option is setting an effort value of 10,
+ * At the moment, the only expert option is setting an effort value of 11,
* which gives the best compression for pixel-lossless modes but is very slow.
*
* @param enc encoder object.
diff --git a/third_party/jpeg-xl/lib/include/jxl/parallel_runner.h b/third_party/jpeg-xl/lib/include/jxl/parallel_runner.h
index e71e0aa926..ea66685dbc 100644
--- a/third_party/jpeg-xl/lib/include/jxl/parallel_runner.h
+++ b/third_party/jpeg-xl/lib/include/jxl/parallel_runner.h
@@ -46,39 +46,41 @@ extern "C" {
/** Return code used in the JxlParallel* functions as return value. A value
* of 0 means success and any other value means error. The special value
- * JXL_PARALLEL_RET_RUNNER_ERROR can be used by the runner to indicate any
+ * ::JXL_PARALLEL_RET_RUNNER_ERROR can be used by the runner to indicate any
* other error.
*/
typedef int JxlParallelRetCode;
/**
- * General error returned by the JxlParallelRunInit function to indicate
+ * General error returned by the @ref JxlParallelRunInit function to indicate
* an error.
*/
#define JXL_PARALLEL_RET_RUNNER_ERROR (-1)
/**
- * Parallel run initialization callback. See JxlParallelRunner for details.
+ * Parallel run initialization callback. See @ref JxlParallelRunner for details.
*
* This function MUST be called by the JxlParallelRunner only once, on the
- * same thread that called JxlParallelRunner, before any parallel execution.
- * The purpose of this call is to provide the maximum number of threads that the
- * JxlParallelRunner will use, which can be used by JPEG XL to allocate
+ * same thread that called @ref JxlParallelRunner, before any parallel
+ * execution. The purpose of this call is to provide the maximum number of
+ * threads that the
+ * @ref JxlParallelRunner will use, which can be used by JPEG XL to allocate
* per-thread storage if needed.
*
* @param jpegxl_opaque the @p jpegxl_opaque handle provided to
- * JxlParallelRunner() must be passed here.
+ * @ref JxlParallelRunner() must be passed here.
* @param num_threads the maximum number of threads. This value must be
* positive.
* @return 0 if the initialization process was successful.
* @return an error code if there was an error, which should be returned by
- * JxlParallelRunner().
+ * @ref JxlParallelRunner().
*/
typedef JxlParallelRetCode (*JxlParallelRunInit)(void* jpegxl_opaque,
size_t num_threads);
/**
- * Parallel run data processing callback. See JxlParallelRunner for details.
+ * Parallel run data processing callback. See @ref JxlParallelRunner for
+ * details.
*
* This function MUST be called once for every number in the range [start_range,
* end_range) (including start_range but not including end_range) passing this
@@ -86,11 +88,11 @@ typedef JxlParallelRetCode (*JxlParallelRunInit)(void* jpegxl_opaque,
* different threads in parallel.
*
* @param jpegxl_opaque the @p jpegxl_opaque handle provided to
- * JxlParallelRunner() must be passed here.
+ * @ref JxlParallelRunner() must be passed here.
* @param value the number in the range [start_range, end_range) of the call.
* @param thread_id the thread number where this function is being called from.
* This must be lower than the @p num_threads value passed to
- * JxlParallelRunInit.
+ * @ref JxlParallelRunInit.
*/
typedef void (*JxlParallelRunFunction)(void* jpegxl_opaque, uint32_t value,
size_t thread_id);
@@ -103,11 +105,12 @@ typedef void (*JxlParallelRunFunction)(void* jpegxl_opaque, uint32_t value,
* number in the range [start_range, end_range) (including start_range but not
* including end_range) possibly from different multiple threads in parallel.
*
- * The JxlParallelRunner function does not need to be re-entrant. This means
- * that the same JxlParallelRunner function with the same runner_opaque
- * provided parameter will not be called from the library from either @p init or
+ * The @ref JxlParallelRunner function does not need to be re-entrant. This
+ * means that the same @ref JxlParallelRunner function with the same
+ * runner_opaque provided parameter will not be called from the library from
+ * either @p init or
* @p func in the same decoder or encoder instance. However, a single decoding
- * or encoding instance may call the provided JxlParallelRunner multiple
+ * or encoding instance may call the provided @ref JxlParallelRunner multiple
* times for different parts of the decoding or encoding process.
*
* @return 0 if the @p init call succeeded (returned 0) and no other error
@@ -120,7 +123,7 @@ typedef JxlParallelRetCode (*JxlParallelRunner)(
void* runner_opaque, void* jpegxl_opaque, JxlParallelRunInit init,
JxlParallelRunFunction func, uint32_t start_range, uint32_t end_range);
-/* The following is an example of a JxlParallelRunner that doesn't use any
+/* The following is an example of a @ref JxlParallelRunner that doesn't use any
* multi-threading. Note that this implementation doesn't store any state
* between multiple calls of the ExampleSequentialRunner function, so the
* runner_opaque value is not used.
diff --git a/third_party/jpeg-xl/lib/include/jxl/resizable_parallel_runner.h b/third_party/jpeg-xl/lib/include/jxl/resizable_parallel_runner.h
index a65015d861..c82b0bc23b 100644
--- a/third_party/jpeg-xl/lib/include/jxl/resizable_parallel_runner.h
+++ b/third_party/jpeg-xl/lib/include/jxl/resizable_parallel_runner.h
@@ -16,7 +16,7 @@
* created can be changed after creation of the thread pool; the threads
* (including the main thread) are re-used for every
* ResizableParallelRunner::Runner call. Only one concurrent
- * JxlResizableParallelRunner call per instance is allowed at a time.
+ * @ref JxlResizableParallelRunner call per instance is allowed at a time.
*
* This is a scalable, lower-overhead thread pool runner, especially suitable
* for data-parallel computations in the fork-join model, where clients need to
@@ -41,20 +41,20 @@
extern "C" {
#endif
-/** Parallel runner internally using std::thread. Use as JxlParallelRunner.
+/** Parallel runner internally using std::thread. Use as @ref JxlParallelRunner.
*/
JXL_THREADS_EXPORT JxlParallelRetCode JxlResizableParallelRunner(
void* runner_opaque, void* jpegxl_opaque, JxlParallelRunInit init,
JxlParallelRunFunction func, uint32_t start_range, uint32_t end_range);
-/** Creates the runner for JxlResizableParallelRunner. Use as the opaque
+/** Creates the runner for @ref JxlResizableParallelRunner. Use as the opaque
* runner. The runner will execute tasks on the calling thread until
* @ref JxlResizableParallelRunnerSetThreads is called.
*/
JXL_THREADS_EXPORT void* JxlResizableParallelRunnerCreate(
const JxlMemoryManager* memory_manager);
-/** Changes the number of threads for JxlResizableParallelRunner.
+/** Changes the number of threads for @ref JxlResizableParallelRunner.
*/
JXL_THREADS_EXPORT void JxlResizableParallelRunnerSetThreads(
void* runner_opaque, size_t num_threads);
@@ -64,7 +64,7 @@ JXL_THREADS_EXPORT void JxlResizableParallelRunnerSetThreads(
JXL_THREADS_EXPORT uint32_t
JxlResizableParallelRunnerSuggestThreads(uint64_t xsize, uint64_t ysize);
-/** Destroys the runner created by JxlResizableParallelRunnerCreate.
+/** Destroys the runner created by @ref JxlResizableParallelRunnerCreate.
*/
JXL_THREADS_EXPORT void JxlResizableParallelRunnerDestroy(void* runner_opaque);
diff --git a/third_party/jpeg-xl/lib/include/jxl/stats.h b/third_party/jpeg-xl/lib/include/jxl/stats.h
index c9359dc870..5ed440636f 100644
--- a/third_party/jpeg-xl/lib/include/jxl/stats.h
+++ b/third_party/jpeg-xl/lib/include/jxl/stats.h
@@ -23,15 +23,15 @@ extern "C" {
/**
* Opaque structure that holds the encoder statistics.
*
- * Allocated and initialized with JxlEncoderStatsCreate().
- * Cleaned up and deallocated with JxlEncoderStatsDestroy().
+ * Allocated and initialized with @ref JxlEncoderStatsCreate().
+ * Cleaned up and deallocated with @ref JxlEncoderStatsDestroy().
*/
typedef struct JxlEncoderStatsStruct JxlEncoderStats;
/**
* Creates an instance of JxlEncoderStats and initializes it.
*
- * @return pointer to initialized JxlEncoderStats instance
+ * @return pointer to initialized @ref JxlEncoderStats instance
*/
JXL_EXPORT JxlEncoderStats* JxlEncoderStatsCreate(void);
@@ -43,7 +43,7 @@ JXL_EXPORT JxlEncoderStats* JxlEncoderStatsCreate(void);
*/
JXL_EXPORT void JxlEncoderStatsDestroy(JxlEncoderStats* stats);
-/** Data type for querying JxlEncoderStats object
+/** Data type for querying @ref JxlEncoderStats object
*/
typedef enum {
JXL_ENC_STAT_HEADER_BITS,
diff --git a/third_party/jpeg-xl/lib/include/jxl/thread_parallel_runner.h b/third_party/jpeg-xl/lib/include/jxl/thread_parallel_runner.h
index 6166fe7d36..933f373ce9 100644
--- a/third_party/jpeg-xl/lib/include/jxl/thread_parallel_runner.h
+++ b/third_party/jpeg-xl/lib/include/jxl/thread_parallel_runner.h
@@ -41,24 +41,24 @@
extern "C" {
#endif
-/** Parallel runner internally using std::thread. Use as JxlParallelRunner.
+/** Parallel runner internally using std::thread. Use as @ref JxlParallelRunner.
*/
JXL_THREADS_EXPORT JxlParallelRetCode JxlThreadParallelRunner(
void* runner_opaque, void* jpegxl_opaque, JxlParallelRunInit init,
JxlParallelRunFunction func, uint32_t start_range, uint32_t end_range);
-/** Creates the runner for JxlThreadParallelRunner. Use as the opaque
+/** Creates the runner for @ref JxlThreadParallelRunner. Use as the opaque
* runner.
*/
JXL_THREADS_EXPORT void* JxlThreadParallelRunnerCreate(
const JxlMemoryManager* memory_manager, size_t num_worker_threads);
-/** Destroys the runner created by JxlThreadParallelRunnerCreate.
+/** Destroys the runner created by @ref JxlThreadParallelRunnerCreate.
*/
JXL_THREADS_EXPORT void JxlThreadParallelRunnerDestroy(void* runner_opaque);
/** Returns a default num_worker_threads value for
- * JxlThreadParallelRunnerCreate.
+ * @ref JxlThreadParallelRunnerCreate.
*/
JXL_THREADS_EXPORT size_t JxlThreadParallelRunnerDefaultNumWorkerThreads(void);
diff --git a/third_party/jpeg-xl/lib/include/jxl/types.h b/third_party/jpeg-xl/lib/include/jxl/types.h
index a47216f878..2538dbaa82 100644
--- a/third_party/jpeg-xl/lib/include/jxl/types.h
+++ b/third_party/jpeg-xl/lib/include/jxl/types.h
@@ -13,7 +13,6 @@
#ifndef JXL_TYPES_H_
#define JXL_TYPES_H_
-#include <jxl/jxl_export.h>
#include <stddef.h>
#include <stdint.h>
@@ -32,15 +31,17 @@ extern "C" {
#define JXL_TRUE 1
/** Portable @c false replacement. */
#define JXL_FALSE 0
-/** Converts of bool-like value to either JXL_TRUE or JXL_FALSE. */
+/** Converts of bool-like value to either ::JXL_TRUE or ::JXL_FALSE. */
#define TO_JXL_BOOL(C) (!!(C) ? JXL_TRUE : JXL_FALSE)
+/** Converts JXL_BOOL to C++ bool. */
+#define FROM_JXL_BOOL(C) (static_cast<bool>(C))
/** Data type for the sample values per channel per pixel.
*/
typedef enum {
/** 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
+ * point output, either ::JXL_TYPE_FLOAT or ::JXL_TYPE_FLOAT16, is recommended
* for HDR and wide gamut images when color profile conversion is required. */
JXL_TYPE_FLOAT = 0,
@@ -92,8 +93,7 @@ typedef struct {
JxlDataType data_type;
/** Whether multi-byte data types are represented in big endian or little
- * endian format. This applies to JXL_TYPE_UINT16, JXL_TYPE_UINT32
- * and JXL_TYPE_FLOAT.
+ * endian format. This applies to ::JXL_TYPE_UINT16 and ::JXL_TYPE_FLOAT.
*/
JxlEndianness endianness;