diff options
Diffstat (limited to 'third_party/jpeg-xl/lib/include/jxl/decode.h')
| -rw-r--r-- | third_party/jpeg-xl/lib/include/jxl/decode.h | 411 |
1 files changed, 221 insertions, 190 deletions
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 |