From 54175156bd2613bf5a6a3aa6a937f06a30538ee7 Mon Sep 17 00:00:00 2001 From: Nigel Tao Date: Thu, 11 Mar 2021 11:28:50 +1100 Subject: [PATCH] Add more wuffs_aux::DecodeImage comments --- internal/cgen/auxiliary/image.hh | 20 +++++++++++++++----- internal/cgen/data/data.go | 6 +++--- release/c/wuffs-unsupported-snapshot.c | 20 +++++++++++++++----- 3 files changed, 33 insertions(+), 13 deletions(-) diff --git a/internal/cgen/auxiliary/image.hh b/internal/cgen/auxiliary/image.hh index 33de7497..47702dc9 100644 --- a/internal/cgen/auxiliary/image.hh +++ b/internal/cgen/auxiliary/image.hh @@ -117,13 +117,23 @@ extern const char DecodeImage_UnsupportedPixelConfiguration[]; extern const char DecodeImage_UnsupportedPixelFormat[]; // DecodeImage decodes the image data in input. A variety of image file formats -// can be decoded, depending on what callbacks.OnImageFormat returns. For -// animated formats, only the first frame is returned. +// can be decoded, depending on what callbacks.OnImageFormat returns. // -// - On total success, the returned error_message is empty. +// For animated formats, only the first frame is returned, since the API is +// simpler for synchronous I/O and having DecodeImage only return when +// completely done, but rendering animation often involves handling other +// events in between animation frames. To decode multiple frames of animated +// images, or for asynchronous I/O (e.g. when decoding an image streamed over +// the network), use Wuffs' lower level C API instead of its higher level, +// simplified C++ API (the wuffs_aux API). +// +// The DecodeImageResult's fields depend on whether decoding succeeded: +// - On total success, the error_message is empty and pixbuf.pixcfg.is_valid() +// is true. // - On partial success (e.g. the input file was truncated but we are still -// able to decode some pixels), error_message is non-empty but the returned -// pixbuf.pixcfg.is_valid() is true. +// able to decode some of the pixels), error_message is non-empty but +// pixbuf.pixcfg.is_valid() is still true. It is up to the caller whether to +// accept or reject partial success. // - On failure, the error_message is non_empty and pixbuf.pixcfg.is_valid() // is false. // diff --git a/internal/cgen/data/data.go b/internal/cgen/data/data.go index defc6b80..46fb8a90 100644 --- a/internal/cgen/data/data.go +++ b/internal/cgen/data/data.go @@ -757,9 +757,9 @@ const AuxImageHh = "" + "message. The memory is\n // de-allocated when mem_owner goes out of scope and is destroyed.\n struct AllocResult {\n AllocResult(MemOwner&& mem_owner0, wuffs_base__slice_u8 mem_slice0);\n AllocResult(std::string&& error_message0);\n\n MemOwner mem_owner;\n wuffs_base__slice_u8 mem_slice;\n std::string error_message;\n };\n\n // OnImageFormat returns the image decoder for the input data's file format.\n // Returning a nullptr means failure (DecodeImage_UnsupportedImageFormat).\n //\n // Common formats will have a non-zero FourCC value, such as\n // WUFFS_BASE__FOURCC__JPEG. A zero FourCC code means that the caller is\n // responsible for examining the opening bytes (a prefix) of the input data.\n // OnImageFormat implementations should not modify those bytes.\n //\n // OnImageFormat might be called more than once, since some image file\n // formats can wrap others. For example, a nominal BMP file can actually\n // contain a JPEG or a PNG.\n //\n // There is no default implementation, as modular Wuffs b" + "uilds (those that\n // define WUFFS_CONFIG__MODULES) may enable or disable particular codecs.\n virtual wuffs_base__image_decoder::unique_ptr //\n OnImageFormat(uint32_t fourcc, wuffs_base__slice_u8 prefix) = 0;\n\n // OnImageConfig allocates the pixel buffer.\n //\n // The default OnImageConfig implementation allocates zeroed memory.\n virtual AllocResult //\n OnImageConfig(const wuffs_base__image_config& image_config);\n\n // AllocWorkbuf allocates the work buffer. The allocated buffer's length\n // should be at least len.min_incl, but larger allocations (up to\n // len.max_incl) may have better performance (by using more memory).\n //\n // The default AllocWorkbuf implementation allocates len.max_incl bytes of\n // zeroed memory.\n virtual AllocResult //\n AllocWorkbuf(wuffs_base__range_ii_u64 len);\n\n // Done is always the last Callback method called by DecodeImage, whether or\n // not parsing the input encountered an error. Even when successful, trailing\n // data may remain in input and buffer.\n //\n " + "// The image_decoder is the one returned by OnImageFormat (if OnImageFormat\n // was successful), or a no-op unique_ptr otherwise. Like any unique_ptr,\n // ownership moves to the Done implementation.\n //\n // Do not keep a reference to buffer or buffer.data.ptr after Done returns,\n // as DecodeImage may then de-allocate the backing array.\n //\n // The default Done implementation is a no-op, other than running the\n // image_decoder unique_ptr destructor.\n virtual void //\n Done(DecodeImageResult& result,\n sync_io::Input& input,\n IOBuffer& buffer,\n wuffs_base__image_decoder::unique_ptr image_decoder);\n};\n\nextern const char DecodeImage_BufferIsTooShort[];\nextern const char DecodeImage_MaxInclDimensionExceeded[];\nextern const char DecodeImage_OutOfMemory[];\nextern const char DecodeImage_UnexpectedEndOfFile[];\nextern const char DecodeImage_UnsupportedImageFormat[];\nextern const char DecodeImage_UnsupportedPixelBlend[];\nextern const char DecodeImage_UnsupportedPixelConfiguration[];\nextern c" + - "onst char DecodeImage_UnsupportedPixelFormat[];\n\n// DecodeImage decodes the image data in input. A variety of image file formats\n// can be decoded, depending on what callbacks.OnImageFormat returns. For\n// animated formats, only the first frame is returned.\n//\n// - On total success, the returned error_message is empty.\n// - On partial success (e.g. the input file was truncated but we are still\n// able to decode some pixels), error_message is non-empty but the returned\n// pixbuf.pixcfg.is_valid() is true.\n// - On failure, the error_message is non_empty and pixbuf.pixcfg.is_valid()\n// is false.\n//\n// The callbacks allocate the pixel buffer memory and work buffer memory. On\n// success, pixel buffer memory ownership is passed to the DecodeImage caller\n// as the returned pixbuf_mem_owner. Regardless of success or failure, the work\n// buffer memory is deleted.\n//\n// If override_pixel_format_repr is zero then the pixel buffer will have the\n// image file's natural pixel format. For example, GIF images' na" + - "tural pixel\n// format is an indexed one.\n//\n// If override_pixel_format_repr is non-zero (and one of the constants listed\n// below) then the image will be decoded to that particular pixel format:\n// - WUFFS_BASE__PIXEL_FORMAT__BGR_565\n// - WUFFS_BASE__PIXEL_FORMAT__BGR\n// - WUFFS_BASE__PIXEL_FORMAT__BGRA_NONPREMUL\n// - WUFFS_BASE__PIXEL_FORMAT__BGRA_PREMUL\n//\n// The pixel_blend (one of the constants listed below) determines how to\n// composite the decoded image over the pixel buffer's original pixels (as\n// returned by callbacks.OnImageConfig):\n// - WUFFS_BASE__PIXEL_BLEND__SRC\n// - WUFFS_BASE__PIXEL_BLEND__SRC_OVER\n//\n// Decoding fails (with DecodeImage_MaxInclDimensionExceeded) if the image's\n// width or height is greater than max_incl_dimension.\nDecodeImageResult //\nDecodeImage(DecodeImageCallbacks& callbacks,\n sync_io::Input& input,\n uint32_t override_pixel_format_repr,\n wuffs_base__pixel_blend pixel_blend = WUFFS_BASE__PIXEL_BLEND__SRC,\n uint32_t max_inc" + - "l_dimension = 1048575); // 0x000F_FFFF\n\n} // namespace wuffs_aux\n" + + "onst char DecodeImage_UnsupportedPixelFormat[];\n\n// DecodeImage decodes the image data in input. A variety of image file formats\n// can be decoded, depending on what callbacks.OnImageFormat returns.\n//\n// For animated formats, only the first frame is returned, since the API is\n// simpler for synchronous I/O and having DecodeImage only return when\n// completely done, but rendering animation often involves handling other\n// events in between animation frames. To decode multiple frames of animated\n// images, or for asynchronous I/O (e.g. when decoding an image streamed over\n// the network), use Wuffs' lower level C API instead of its higher level,\n// simplified C++ API (the wuffs_aux API).\n//\n// The DecodeImageResult's fields depend on whether decoding succeeded:\n// - On total success, the error_message is empty and pixbuf.pixcfg.is_valid()\n// is true.\n// - On partial success (e.g. the input file was truncated but we are still\n// able to decode some of the pixels), error_message is non-empty but\n// pi" + + "xbuf.pixcfg.is_valid() is still true. It is up to the caller whether to\n// accept or reject partial success.\n// - On failure, the error_message is non_empty and pixbuf.pixcfg.is_valid()\n// is false.\n//\n// The callbacks allocate the pixel buffer memory and work buffer memory. On\n// success, pixel buffer memory ownership is passed to the DecodeImage caller\n// as the returned pixbuf_mem_owner. Regardless of success or failure, the work\n// buffer memory is deleted.\n//\n// If override_pixel_format_repr is zero then the pixel buffer will have the\n// image file's natural pixel format. For example, GIF images' natural pixel\n// format is an indexed one.\n//\n// If override_pixel_format_repr is non-zero (and one of the constants listed\n// below) then the image will be decoded to that particular pixel format:\n// - WUFFS_BASE__PIXEL_FORMAT__BGR_565\n// - WUFFS_BASE__PIXEL_FORMAT__BGR\n// - WUFFS_BASE__PIXEL_FORMAT__BGRA_NONPREMUL\n// - WUFFS_BASE__PIXEL_FORMAT__BGRA_PREMUL\n//\n// The pixel_blend (one of the constants" + + " listed below) determines how to\n// composite the decoded image over the pixel buffer's original pixels (as\n// returned by callbacks.OnImageConfig):\n// - WUFFS_BASE__PIXEL_BLEND__SRC\n// - WUFFS_BASE__PIXEL_BLEND__SRC_OVER\n//\n// Decoding fails (with DecodeImage_MaxInclDimensionExceeded) if the image's\n// width or height is greater than max_incl_dimension.\nDecodeImageResult //\nDecodeImage(DecodeImageCallbacks& callbacks,\n sync_io::Input& input,\n uint32_t override_pixel_format_repr,\n wuffs_base__pixel_blend pixel_blend = WUFFS_BASE__PIXEL_BLEND__SRC,\n uint32_t max_incl_dimension = 1048575); // 0x000F_FFFF\n\n} // namespace wuffs_aux\n" + "" const AuxJsonCc = "" + diff --git a/release/c/wuffs-unsupported-snapshot.c b/release/c/wuffs-unsupported-snapshot.c index cea611fa..c55cd6db 100644 --- a/release/c/wuffs-unsupported-snapshot.c +++ b/release/c/wuffs-unsupported-snapshot.c @@ -9517,13 +9517,23 @@ extern const char DecodeImage_UnsupportedPixelConfiguration[]; extern const char DecodeImage_UnsupportedPixelFormat[]; // DecodeImage decodes the image data in input. A variety of image file formats -// can be decoded, depending on what callbacks.OnImageFormat returns. For -// animated formats, only the first frame is returned. +// can be decoded, depending on what callbacks.OnImageFormat returns. // -// - On total success, the returned error_message is empty. +// For animated formats, only the first frame is returned, since the API is +// simpler for synchronous I/O and having DecodeImage only return when +// completely done, but rendering animation often involves handling other +// events in between animation frames. To decode multiple frames of animated +// images, or for asynchronous I/O (e.g. when decoding an image streamed over +// the network), use Wuffs' lower level C API instead of its higher level, +// simplified C++ API (the wuffs_aux API). +// +// The DecodeImageResult's fields depend on whether decoding succeeded: +// - On total success, the error_message is empty and pixbuf.pixcfg.is_valid() +// is true. // - On partial success (e.g. the input file was truncated but we are still -// able to decode some pixels), error_message is non-empty but the returned -// pixbuf.pixcfg.is_valid() is true. +// able to decode some of the pixels), error_message is non-empty but +// pixbuf.pixcfg.is_valid() is still true. It is up to the caller whether to +// accept or reject partial success. // - On failure, the error_message is non_empty and pixbuf.pixcfg.is_valid() // is false. //