diff options
Diffstat (limited to 'third_party/jpeg-xl/lib/include')
| -rw-r--r-- | third_party/jpeg-xl/lib/include/jxl/cms_interface.h | 27 | ||||
| -rw-r--r-- | third_party/jpeg-xl/lib/include/jxl/codestream_header.h | 35 | ||||
| -rw-r--r-- | third_party/jpeg-xl/lib/include/jxl/color_encoding.h | 39 | ||||
| -rw-r--r-- | third_party/jpeg-xl/lib/include/jxl/decode.h | 411 | ||||
| -rw-r--r-- | third_party/jpeg-xl/lib/include/jxl/encode.h | 403 | ||||
| -rw-r--r-- | third_party/jpeg-xl/lib/include/jxl/parallel_runner.h | 35 | ||||
| -rw-r--r-- | third_party/jpeg-xl/lib/include/jxl/resizable_parallel_runner.h | 10 | ||||
| -rw-r--r-- | third_party/jpeg-xl/lib/include/jxl/stats.h | 8 | ||||
| -rw-r--r-- | third_party/jpeg-xl/lib/include/jxl/thread_parallel_runner.h | 8 | ||||
| -rw-r--r-- | third_party/jpeg-xl/lib/include/jxl/types.h | 10 |
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; |