internal/cgen/auxiliary/image.hh - third_party/wuffs - Git at Google

 // Copyright 2021 The Wuffs Authors.
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
 // You may obtain a copy of the License at
 //
 //    https://www.apache.org/licenses/LICENSE-2.0
 //
 // Unless required by applicable law or agreed to in writing, software
 // distributed under the License is distributed on an "AS IS" BASIS,
 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 // See the License for the specific language governing permissions and
 // limitations under the License.

 // ---------------- Auxiliary - Image

 namespace wuffs_aux {

 struct DecodeImageResult {
   DecodeImageResult(MemOwner&& pixbuf_mem_owner0,
                     wuffs_base__pixel_buffer pixbuf0,
                     std::string&& error_message0);
   DecodeImageResult(std::string&& error_message0);

   MemOwner pixbuf_mem_owner;
   wuffs_base__pixel_buffer pixbuf;
   std::string error_message;
 };

 // DecodeImageCallbacks are the callbacks given to DecodeImage. They are always
 // called in this order:
 //  1. SelectDecoder
 //  2. HandleMetadata
 //  3. SelectPixfmt
 //  4. AllocPixbuf
 //  5. AllocWorkbuf
 //  6. Done
 //
 // It may return early - the third callback might not be invoked if the second
 // one fails - but the final callback (Done) is always invoked.
 class DecodeImageCallbacks {
  public:
   // AllocPixbufResult holds a memory allocation (the result of malloc or new,
   // a statically allocated pointer, etc), or an error message. The memory is
   // de-allocated when mem_owner goes out of scope and is destroyed.
   struct AllocPixbufResult {
     AllocPixbufResult(MemOwner&& mem_owner0, wuffs_base__pixel_buffer pixbuf0);
     AllocPixbufResult(std::string&& error_message0);

     MemOwner mem_owner;
     wuffs_base__pixel_buffer pixbuf;
     std::string error_message;
   };

   // AllocWorkbufResult holds a memory allocation (the result of malloc or new,
   // a statically allocated pointer, etc), or an error message. The memory is
   // de-allocated when mem_owner goes out of scope and is destroyed.
   struct AllocWorkbufResult {
     AllocWorkbufResult(MemOwner&& mem_owner0, wuffs_base__slice_u8 workbuf0);
     AllocWorkbufResult(std::string&& error_message0);

     MemOwner mem_owner;
     wuffs_base__slice_u8 workbuf;
     std::string error_message;
   };

   virtual ~DecodeImageCallbacks();

   // SelectDecoder returns the image decoder for the input data's file format.
   // Returning a nullptr means failure (DecodeImage_UnsupportedImageFormat).
   //
   // Common formats will have a FourCC value in the range [1 ..= 0x7FFF_FFFF],
   // such as WUFFS_BASE__FOURCC__JPEG. A zero FourCC value means that Wuffs'
   // standard library did not recognize the image format but if SelectDecoder
   // was overridden, it may examine the input data's starting bytes and still
   // provide its own image decoder, e.g. for an exotic image file format that's
   // not in Wuffs' standard library. The prefix_etc fields have the same
   // meaning as wuffs_base__magic_number_guess_fourcc arguments. SelectDecoder
   // implementations should not modify prefix_data's contents.
   //
   // SelectDecoder might be called more than once, since some image file
   // formats can wrap others. For example, a nominal BMP file can actually
   // contain a JPEG or a PNG.
   //
   // The default SelectDecoder accepts the FOURCC codes listed below. For
   // modular builds (i.e. when #define'ing WUFFS_CONFIG__MODULES), acceptance
   // of the ETC file format is optional (for each value of ETC) and depends on
   // the corresponding module to be enabled at compile time (i.e. #define'ing
   // WUFFS_CONFIG__MODULE__ETC).
   //  - WUFFS_BASE__FOURCC__BMP
   //  - WUFFS_BASE__FOURCC__GIF
   //  - WUFFS_BASE__FOURCC__NIE
   //  - WUFFS_BASE__FOURCC__PNG
   //  - WUFFS_BASE__FOURCC__TGA
   //  - WUFFS_BASE__FOURCC__WBMP
   virtual wuffs_base__image_decoder::unique_ptr  //
   SelectDecoder(uint32_t fourcc,
                 wuffs_base__slice_u8 prefix_data,
                 bool prefix_closed);

   // HandleMetadata acknowledges image metadata. minfo.flavor will be one of:
   //  - WUFFS_BASE__MORE_INFORMATION__FLAVOR__METADATA_RAW_PASSTHROUGH
   //  - WUFFS_BASE__MORE_INFORMATION__FLAVOR__METADATA_PARSED
   // If it is ETC__METADATA_RAW_ETC then raw contains the metadata bytes. Those
   // bytes should not be retained beyond the the HandleMetadata call.
   //
   // minfo.metadata__fourcc() will typically match one of the
   // DecodeImageArgFlags bits. For example, if (REPORT_METADATA_CHRM |
   // REPORT_METADATA_GAMA) was passed to DecodeImage then the metadata FourCC
   // will be either WUFFS_BASE__FOURCC__CHRM or WUFFS_BASE__FOURCC__GAMA.
   //
   // It returns an error message, or an empty string on success.
   virtual std::string  //
   HandleMetadata(const wuffs_base__more_information& minfo,
                  wuffs_base__slice_u8 raw);

   // SelectPixfmt returns the destination pixel format for AllocPixbuf. It
   // should return wuffs_base__make_pixel_format(etc) called with one of:
   //  - WUFFS_BASE__PIXEL_FORMAT__BGR_565
   //  - WUFFS_BASE__PIXEL_FORMAT__BGR
   //  - WUFFS_BASE__PIXEL_FORMAT__BGRA_NONPREMUL
   //  - WUFFS_BASE__PIXEL_FORMAT__BGRA_NONPREMUL_4X16LE
   //  - WUFFS_BASE__PIXEL_FORMAT__BGRA_PREMUL
   //  - WUFFS_BASE__PIXEL_FORMAT__RGBA_NONPREMUL
   //  - WUFFS_BASE__PIXEL_FORMAT__RGBA_PREMUL
   // or return image_config.pixcfg.pixel_format(). The latter means to use the
   // image file's natural pixel format. For example, GIF images' natural pixel
   // format is an indexed one.
   //
   // Returning otherwise means failure (DecodeImage_UnsupportedPixelFormat).
   //
   // The default SelectPixfmt implementation returns
   // wuffs_base__make_pixel_format(WUFFS_BASE__PIXEL_FORMAT__BGRA_PREMUL) which
   // is 4 bytes per pixel (8 bits per channel × 4 channels).
   virtual wuffs_base__pixel_format  //
   SelectPixfmt(const wuffs_base__image_config& image_config);

   // AllocPixbuf allocates the pixel buffer.
   //
   // allow_uninitialized_memory will be true if a valid background_color was
   // passed to DecodeImage, since the pixel buffer's contents will be
   // overwritten with that color after AllocPixbuf returns.
   //
   // The default AllocPixbuf implementation allocates either uninitialized or
   // zeroed memory. Zeroed memory typically corresponds to filling with opaque
   // black or transparent black, depending on the pixel format.
   virtual AllocPixbufResult  //
   AllocPixbuf(const wuffs_base__image_config& image_config,
               bool allow_uninitialized_memory);

   // AllocWorkbuf allocates the work buffer. The allocated buffer's length
   // should be at least len_range.min_incl, but larger allocations (up to
   // len_range.max_incl) may have better performance (by using more memory).
   //
   // The default AllocWorkbuf implementation allocates len_range.max_incl bytes
   // of either uninitialized or zeroed memory.
   virtual AllocWorkbufResult  //
   AllocWorkbuf(wuffs_base__range_ii_u64 len_range,
                bool allow_uninitialized_memory);

   // Done is always the last Callback method called by DecodeImage, whether or
   // not parsing the input encountered an error. Even when successful, trailing
   // data may remain in input and buffer.
   //
   // The image_decoder is the one returned by SelectDecoder (if SelectDecoder
   // was successful), or a no-op unique_ptr otherwise. Like any unique_ptr,
   // ownership moves to the Done implementation.
   //
   // Do not keep a reference to buffer or buffer.data.ptr after Done returns,
   // as DecodeImage may then de-allocate the backing array.
   //
   // The default Done implementation is a no-op, other than running the
   // image_decoder unique_ptr destructor.
   virtual void  //
   Done(DecodeImageResult& result,
        sync_io::Input& input,
        IOBuffer& buffer,
        wuffs_base__image_decoder::unique_ptr image_decoder);
 };

 extern const char DecodeImage_BufferIsTooShort[];
 extern const char DecodeImage_MaxInclDimensionExceeded[];
 extern const char DecodeImage_MaxInclMetadataLengthExceeded[];
 extern const char DecodeImage_OutOfMemory[];
 extern const char DecodeImage_UnexpectedEndOfFile[];
 extern const char DecodeImage_UnsupportedImageFormat[];
 extern const char DecodeImage_UnsupportedMetadata[];
 extern const char DecodeImage_UnsupportedPixelBlend[];
 extern const char DecodeImage_UnsupportedPixelConfiguration[];
 extern const char DecodeImage_UnsupportedPixelFormat[];

 // The FooArgBar types add structure to Foo's optional arguments. They wrap
 // inner representations for several reasons:
 //  - It provides a home for the DefaultValue static method, for Foo callers
 //    that want to override some but not all optional arguments.
 //  - It provides the "Bar" name at Foo call sites, which can help self-
 //    document Foo calls with many arguemnts.
 //  - It provides some type safety against accidentally transposing or omitting
 //    adjacent fundamentally-numeric-typed optional arguments.

 // DecodeImageArgQuirks wraps an optional argument to DecodeImage.
 struct DecodeImageArgQuirks {
   explicit DecodeImageArgQuirks(wuffs_base__slice_u32 repr0);
   explicit DecodeImageArgQuirks(uint32_t* ptr, size_t len);

   // DefaultValue returns an empty slice.
   static DecodeImageArgQuirks DefaultValue();

   wuffs_base__slice_u32 repr;
 };

 // DecodeImageArgFlags wraps an optional argument to DecodeImage.
 struct DecodeImageArgFlags {
   explicit DecodeImageArgFlags(uint64_t repr0);

   // DefaultValue returns 0.
   static DecodeImageArgFlags DefaultValue();

   // TODO: support all of the REPORT_METADATA_ETC flags, not just CHRM, EXIF,
   // GAMA, ICCP, KVP, SRGB and XMP.

   // Background Color.
   static constexpr uint64_t REPORT_METADATA_BGCL = 0x0001;
   // Primary Chromaticities and White Point.
   static constexpr uint64_t REPORT_METADATA_CHRM = 0x0002;
   // Exchangeable Image File Format.
   static constexpr uint64_t REPORT_METADATA_EXIF = 0x0004;
   // Gamma Correction.
   static constexpr uint64_t REPORT_METADATA_GAMA = 0x0008;
   // International Color Consortium Profile.
   static constexpr uint64_t REPORT_METADATA_ICCP = 0x0010;
   // Key-Value Pair.
   //
   // For PNG files, this includes iTXt, tEXt and zTXt chunks. In the
   // HandleMetadata callback, the raw argument contains UTF-8 strings.
   static constexpr uint64_t REPORT_METADATA_KVP = 0x0020;
   // Modification Time.
   static constexpr uint64_t REPORT_METADATA_MTIM = 0x0040;
   // Offset (2-Dimensional).
   static constexpr uint64_t REPORT_METADATA_OFS2 = 0x0080;
   // Physical Dimensions.
   static constexpr uint64_t REPORT_METADATA_PHYD = 0x0100;
   // Standard Red Green Blue (Rendering Intent).
   static constexpr uint64_t REPORT_METADATA_SRGB = 0x0200;
   // Extensible Metadata Platform.
   static constexpr uint64_t REPORT_METADATA_XMP = 0x0400;

   uint64_t repr;
 };

 // DecodeImageArgPixelBlend wraps an optional argument to DecodeImage.
 struct DecodeImageArgPixelBlend {
   explicit DecodeImageArgPixelBlend(wuffs_base__pixel_blend repr0);

   // DefaultValue returns WUFFS_BASE__PIXEL_BLEND__SRC.
   static DecodeImageArgPixelBlend DefaultValue();

   wuffs_base__pixel_blend repr;
 };

 // DecodeImageArgBackgroundColor wraps an optional argument to DecodeImage.
 struct DecodeImageArgBackgroundColor {
   explicit DecodeImageArgBackgroundColor(
       wuffs_base__color_u32_argb_premul repr0);

   // DefaultValue returns 1, an invalid wuffs_base__color_u32_argb_premul.
   static DecodeImageArgBackgroundColor DefaultValue();

   wuffs_base__color_u32_argb_premul repr;
 };

 // DecodeImageArgMaxInclDimension wraps an optional argument to DecodeImage.
 struct DecodeImageArgMaxInclDimension {
   explicit DecodeImageArgMaxInclDimension(uint32_t repr0);

   // DefaultValue returns 1048575 = 0x000F_FFFF, more than 1 million pixels.
   static DecodeImageArgMaxInclDimension DefaultValue();

   uint32_t repr;
 };

 // DecodeImageArgMaxInclMetadataLength wraps an optional argument to
 // DecodeImage.
 struct DecodeImageArgMaxInclMetadataLength {
   explicit DecodeImageArgMaxInclMetadataLength(uint64_t repr0);

   // DefaultValue returns 16777215 = 0x00FF_FFFF, one less than 16 MiB.
   static DecodeImageArgMaxInclMetadataLength DefaultValue();

   uint64_t repr;
 };

 // DecodeImage decodes the image data in input. A variety of image file formats
 // can be decoded, depending on what callbacks.SelectDecoder returns.
 //
 // 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 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.
 //
 // The callbacks allocate the pixel buffer memory and work buffer memory. On
 // success, pixel buffer memory ownership is passed to the DecodeImage caller
 // as the returned pixbuf_mem_owner. Regardless of success or failure, the work
 // buffer memory is deleted.
 //
 // The pixel_blend (one of the constants listed below) determines how to
 // composite the decoded image over the pixel buffer's original pixels (as
 // returned by callbacks.AllocPixbuf):
 //  - WUFFS_BASE__PIXEL_BLEND__SRC
 //  - WUFFS_BASE__PIXEL_BLEND__SRC_OVER
 //
 // The background_color is used to fill the pixel buffer after
 // callbacks.AllocPixbuf returns, if it is valid in the
 // wuffs_base__color_u32_argb_premul__is_valid sense. The default value,
 // 0x0000_0001, is not valid since its Blue channel value (0x01) is greater
 // than its Alpha channel value (0x00). A valid background_color will typically
 // be overwritten when pixel_blend is WUFFS_BASE__PIXEL_BLEND__SRC, but might
 // still be visible on partial (not total) success or when pixel_blend is
 // WUFFS_BASE__PIXEL_BLEND__SRC_OVER and the decoded image is not fully opaque.
 //
 // Decoding fails (with DecodeImage_MaxInclDimensionExceeded) if the image's
 // width or height is greater than max_incl_dimension or if any opted-in (via
 // flags bits) metadata is longer than max_incl_metadata_length.
 DecodeImageResult  //
 DecodeImage(DecodeImageCallbacks& callbacks,
             sync_io::Input& input,
             DecodeImageArgQuirks quirks = DecodeImageArgQuirks::DefaultValue(),
             DecodeImageArgFlags flags = DecodeImageArgFlags::DefaultValue(),
             DecodeImageArgPixelBlend pixel_blend =
                 DecodeImageArgPixelBlend::DefaultValue(),
             DecodeImageArgBackgroundColor background_color =
                 DecodeImageArgBackgroundColor::DefaultValue(),
             DecodeImageArgMaxInclDimension max_incl_dimension =
                 DecodeImageArgMaxInclDimension::DefaultValue(),
             DecodeImageArgMaxInclMetadataLength max_incl_metadata_length =
                 DecodeImageArgMaxInclMetadataLength::DefaultValue());

 }  // namespace wuffs_aux
	// Copyright 2021 The Wuffs Authors.
	//
	// Licensed under the Apache License, Version 2.0 (the "License");
	// you may not use this file except in compliance with the License.
	// You may obtain a copy of the License at
	//
	// https://www.apache.org/licenses/LICENSE-2.0
	//
	// Unless required by applicable law or agreed to in writing, software
	// distributed under the License is distributed on an "AS IS" BASIS,
	// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	// See the License for the specific language governing permissions and
	// limitations under the License.

	// ---------------- Auxiliary - Image

	namespace wuffs_aux {

	struct DecodeImageResult {
	DecodeImageResult(MemOwner&& pixbuf_mem_owner0,
	wuffs_base__pixel_buffer pixbuf0,
	std::string&& error_message0);
	DecodeImageResult(std::string&& error_message0);

	MemOwner pixbuf_mem_owner;
	wuffs_base__pixel_buffer pixbuf;
	std::string error_message;
	};

	// DecodeImageCallbacks are the callbacks given to DecodeImage. They are always
	// called in this order:
	// 1. SelectDecoder
	// 2. HandleMetadata
	// 3. SelectPixfmt
	// 4. AllocPixbuf
	// 5. AllocWorkbuf
	// 6. Done
	//
	// It may return early - the third callback might not be invoked if the second
	// one fails - but the final callback (Done) is always invoked.
	class DecodeImageCallbacks {
	public:
	// AllocPixbufResult holds a memory allocation (the result of malloc or new,
	// a statically allocated pointer, etc), or an error message. The memory is
	// de-allocated when mem_owner goes out of scope and is destroyed.
	struct AllocPixbufResult {
	AllocPixbufResult(MemOwner&& mem_owner0, wuffs_base__pixel_buffer pixbuf0);
	AllocPixbufResult(std::string&& error_message0);

	MemOwner mem_owner;
	wuffs_base__pixel_buffer pixbuf;
	std::string error_message;
	};

	// AllocWorkbufResult holds a memory allocation (the result of malloc or new,
	// a statically allocated pointer, etc), or an error message. The memory is
	// de-allocated when mem_owner goes out of scope and is destroyed.
	struct AllocWorkbufResult {
	AllocWorkbufResult(MemOwner&& mem_owner0, wuffs_base__slice_u8 workbuf0);
	AllocWorkbufResult(std::string&& error_message0);

	MemOwner mem_owner;
	wuffs_base__slice_u8 workbuf;
	std::string error_message;
	};

	virtual ~DecodeImageCallbacks();

	// SelectDecoder returns the image decoder for the input data's file format.
	// Returning a nullptr means failure (DecodeImage_UnsupportedImageFormat).
	//
	// Common formats will have a FourCC value in the range [1 ..= 0x7FFF_FFFF],
	// such as WUFFS_BASE__FOURCC__JPEG. A zero FourCC value means that Wuffs'
	// standard library did not recognize the image format but if SelectDecoder
	// was overridden, it may examine the input data's starting bytes and still
	// provide its own image decoder, e.g. for an exotic image file format that's
	// not in Wuffs' standard library. The prefix_etc fields have the same
	// meaning as wuffs_base__magic_number_guess_fourcc arguments. SelectDecoder
	// implementations should not modify prefix_data's contents.
	//
	// SelectDecoder might be called more than once, since some image file
	// formats can wrap others. For example, a nominal BMP file can actually
	// contain a JPEG or a PNG.
	//
	// The default SelectDecoder accepts the FOURCC codes listed below. For
	// modular builds (i.e. when #define'ing WUFFS_CONFIG__MODULES), acceptance
	// of the ETC file format is optional (for each value of ETC) and depends on
	// the corresponding module to be enabled at compile time (i.e. #define'ing
	// WUFFS_CONFIG__MODULE__ETC).
	// - WUFFS_BASE__FOURCC__BMP
	// - WUFFS_BASE__FOURCC__GIF
	// - WUFFS_BASE__FOURCC__NIE
	// - WUFFS_BASE__FOURCC__PNG
	// - WUFFS_BASE__FOURCC__TGA
	// - WUFFS_BASE__FOURCC__WBMP
	virtual wuffs_base__image_decoder::unique_ptr //
	SelectDecoder(uint32_t fourcc,
	wuffs_base__slice_u8 prefix_data,
	bool prefix_closed);

	// HandleMetadata acknowledges image metadata. minfo.flavor will be one of:
	// - WUFFS_BASE__MORE_INFORMATION__FLAVOR__METADATA_RAW_PASSTHROUGH
	// - WUFFS_BASE__MORE_INFORMATION__FLAVOR__METADATA_PARSED
	// If it is ETC__METADATA_RAW_ETC then raw contains the metadata bytes. Those
	// bytes should not be retained beyond the the HandleMetadata call.
	//
	// minfo.metadata__fourcc() will typically match one of the
	// DecodeImageArgFlags bits. For example, if (REPORT_METADATA_CHRM \|
	// REPORT_METADATA_GAMA) was passed to DecodeImage then the metadata FourCC
	// will be either WUFFS_BASE__FOURCC__CHRM or WUFFS_BASE__FOURCC__GAMA.
	//
	// It returns an error message, or an empty string on success.
	virtual std::string //
	HandleMetadata(const wuffs_base__more_information& minfo,
	wuffs_base__slice_u8 raw);

	// SelectPixfmt returns the destination pixel format for AllocPixbuf. It
	// should return wuffs_base__make_pixel_format(etc) called with one of:
	// - WUFFS_BASE__PIXEL_FORMAT__BGR_565
	// - WUFFS_BASE__PIXEL_FORMAT__BGR
	// - WUFFS_BASE__PIXEL_FORMAT__BGRA_NONPREMUL
	// - WUFFS_BASE__PIXEL_FORMAT__BGRA_NONPREMUL_4X16LE
	// - WUFFS_BASE__PIXEL_FORMAT__BGRA_PREMUL
	// - WUFFS_BASE__PIXEL_FORMAT__RGBA_NONPREMUL
	// - WUFFS_BASE__PIXEL_FORMAT__RGBA_PREMUL
	// or return image_config.pixcfg.pixel_format(). The latter means to use the
	// image file's natural pixel format. For example, GIF images' natural pixel
	// format is an indexed one.
	//
	// Returning otherwise means failure (DecodeImage_UnsupportedPixelFormat).
	//
	// The default SelectPixfmt implementation returns
	// wuffs_base__make_pixel_format(WUFFS_BASE__PIXEL_FORMAT__BGRA_PREMUL) which
	// is 4 bytes per pixel (8 bits per channel × 4 channels).
	virtual wuffs_base__pixel_format //
	SelectPixfmt(const wuffs_base__image_config& image_config);

	// AllocPixbuf allocates the pixel buffer.
	//
	// allow_uninitialized_memory will be true if a valid background_color was
	// passed to DecodeImage, since the pixel buffer's contents will be
	// overwritten with that color after AllocPixbuf returns.
	//
	// The default AllocPixbuf implementation allocates either uninitialized or
	// zeroed memory. Zeroed memory typically corresponds to filling with opaque
	// black or transparent black, depending on the pixel format.
	virtual AllocPixbufResult //
	AllocPixbuf(const wuffs_base__image_config& image_config,
	bool allow_uninitialized_memory);

	// AllocWorkbuf allocates the work buffer. The allocated buffer's length
	// should be at least len_range.min_incl, but larger allocations (up to
	// len_range.max_incl) may have better performance (by using more memory).
	//
	// The default AllocWorkbuf implementation allocates len_range.max_incl bytes
	// of either uninitialized or zeroed memory.
	virtual AllocWorkbufResult //
	AllocWorkbuf(wuffs_base__range_ii_u64 len_range,
	bool allow_uninitialized_memory);

	// Done is always the last Callback method called by DecodeImage, whether or
	// not parsing the input encountered an error. Even when successful, trailing
	// data may remain in input and buffer.
	//
	// The image_decoder is the one returned by SelectDecoder (if SelectDecoder
	// was successful), or a no-op unique_ptr otherwise. Like any unique_ptr,
	// ownership moves to the Done implementation.
	//
	// Do not keep a reference to buffer or buffer.data.ptr after Done returns,
	// as DecodeImage may then de-allocate the backing array.
	//
	// The default Done implementation is a no-op, other than running the
	// image_decoder unique_ptr destructor.
	virtual void //
	Done(DecodeImageResult& result,
	sync_io::Input& input,
	IOBuffer& buffer,
	wuffs_base__image_decoder::unique_ptr image_decoder);
	};

	extern const char DecodeImage_BufferIsTooShort[];
	extern const char DecodeImage_MaxInclDimensionExceeded[];
	extern const char DecodeImage_MaxInclMetadataLengthExceeded[];
	extern const char DecodeImage_OutOfMemory[];
	extern const char DecodeImage_UnexpectedEndOfFile[];
	extern const char DecodeImage_UnsupportedImageFormat[];
	extern const char DecodeImage_UnsupportedMetadata[];
	extern const char DecodeImage_UnsupportedPixelBlend[];
	extern const char DecodeImage_UnsupportedPixelConfiguration[];
	extern const char DecodeImage_UnsupportedPixelFormat[];

	// The FooArgBar types add structure to Foo's optional arguments. They wrap
	// inner representations for several reasons:
	// - It provides a home for the DefaultValue static method, for Foo callers
	// that want to override some but not all optional arguments.
	// - It provides the "Bar" name at Foo call sites, which can help self-
	// document Foo calls with many arguemnts.
	// - It provides some type safety against accidentally transposing or omitting
	// adjacent fundamentally-numeric-typed optional arguments.

	// DecodeImageArgQuirks wraps an optional argument to DecodeImage.
	struct DecodeImageArgQuirks {
	explicit DecodeImageArgQuirks(wuffs_base__slice_u32 repr0);
	explicit DecodeImageArgQuirks(uint32_t* ptr, size_t len);

	// DefaultValue returns an empty slice.
	static DecodeImageArgQuirks DefaultValue();

	wuffs_base__slice_u32 repr;
	};

	// DecodeImageArgFlags wraps an optional argument to DecodeImage.
	struct DecodeImageArgFlags {
	explicit DecodeImageArgFlags(uint64_t repr0);

	// DefaultValue returns 0.
	static DecodeImageArgFlags DefaultValue();

	// TODO: support all of the REPORT_METADATA_ETC flags, not just CHRM, EXIF,
	// GAMA, ICCP, KVP, SRGB and XMP.

	// Background Color.
	static constexpr uint64_t REPORT_METADATA_BGCL = 0x0001;
	// Primary Chromaticities and White Point.
	static constexpr uint64_t REPORT_METADATA_CHRM = 0x0002;
	// Exchangeable Image File Format.
	static constexpr uint64_t REPORT_METADATA_EXIF = 0x0004;
	// Gamma Correction.
	static constexpr uint64_t REPORT_METADATA_GAMA = 0x0008;
	// International Color Consortium Profile.
	static constexpr uint64_t REPORT_METADATA_ICCP = 0x0010;
	// Key-Value Pair.
	//
	// For PNG files, this includes iTXt, tEXt and zTXt chunks. In the
	// HandleMetadata callback, the raw argument contains UTF-8 strings.
	static constexpr uint64_t REPORT_METADATA_KVP = 0x0020;
	// Modification Time.
	static constexpr uint64_t REPORT_METADATA_MTIM = 0x0040;
	// Offset (2-Dimensional).
	static constexpr uint64_t REPORT_METADATA_OFS2 = 0x0080;
	// Physical Dimensions.
	static constexpr uint64_t REPORT_METADATA_PHYD = 0x0100;
	// Standard Red Green Blue (Rendering Intent).
	static constexpr uint64_t REPORT_METADATA_SRGB = 0x0200;
	// Extensible Metadata Platform.
	static constexpr uint64_t REPORT_METADATA_XMP = 0x0400;

	uint64_t repr;
	};

	// DecodeImageArgPixelBlend wraps an optional argument to DecodeImage.
	struct DecodeImageArgPixelBlend {
	explicit DecodeImageArgPixelBlend(wuffs_base__pixel_blend repr0);

	// DefaultValue returns WUFFS_BASE__PIXEL_BLEND__SRC.
	static DecodeImageArgPixelBlend DefaultValue();

	wuffs_base__pixel_blend repr;
	};

	// DecodeImageArgBackgroundColor wraps an optional argument to DecodeImage.
	struct DecodeImageArgBackgroundColor {
	explicit DecodeImageArgBackgroundColor(
	wuffs_base__color_u32_argb_premul repr0);

	// DefaultValue returns 1, an invalid wuffs_base__color_u32_argb_premul.
	static DecodeImageArgBackgroundColor DefaultValue();

	wuffs_base__color_u32_argb_premul repr;
	};

	// DecodeImageArgMaxInclDimension wraps an optional argument to DecodeImage.
	struct DecodeImageArgMaxInclDimension {
	explicit DecodeImageArgMaxInclDimension(uint32_t repr0);

	// DefaultValue returns 1048575 = 0x000F_FFFF, more than 1 million pixels.
	static DecodeImageArgMaxInclDimension DefaultValue();

	uint32_t repr;
	};

	// DecodeImageArgMaxInclMetadataLength wraps an optional argument to
	// DecodeImage.
	struct DecodeImageArgMaxInclMetadataLength {
	explicit DecodeImageArgMaxInclMetadataLength(uint64_t repr0);

	// DefaultValue returns 16777215 = 0x00FF_FFFF, one less than 16 MiB.
	static DecodeImageArgMaxInclMetadataLength DefaultValue();

	uint64_t repr;
	};

	// DecodeImage decodes the image data in input. A variety of image file formats
	// can be decoded, depending on what callbacks.SelectDecoder returns.
	//
	// 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 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.
	//
	// The callbacks allocate the pixel buffer memory and work buffer memory. On
	// success, pixel buffer memory ownership is passed to the DecodeImage caller
	// as the returned pixbuf_mem_owner. Regardless of success or failure, the work
	// buffer memory is deleted.
	//
	// The pixel_blend (one of the constants listed below) determines how to
	// composite the decoded image over the pixel buffer's original pixels (as
	// returned by callbacks.AllocPixbuf):
	// - WUFFS_BASE__PIXEL_BLEND__SRC
	// - WUFFS_BASE__PIXEL_BLEND__SRC_OVER
	//
	// The background_color is used to fill the pixel buffer after
	// callbacks.AllocPixbuf returns, if it is valid in the
	// wuffs_base__color_u32_argb_premul__is_valid sense. The default value,
	// 0x0000_0001, is not valid since its Blue channel value (0x01) is greater
	// than its Alpha channel value (0x00). A valid background_color will typically
	// be overwritten when pixel_blend is WUFFS_BASE__PIXEL_BLEND__SRC, but might
	// still be visible on partial (not total) success or when pixel_blend is
	// WUFFS_BASE__PIXEL_BLEND__SRC_OVER and the decoded image is not fully opaque.
	//
	// Decoding fails (with DecodeImage_MaxInclDimensionExceeded) if the image's
	// width or height is greater than max_incl_dimension or if any opted-in (via
	// flags bits) metadata is longer than max_incl_metadata_length.
	DecodeImageResult //
	DecodeImage(DecodeImageCallbacks& callbacks,
	sync_io::Input& input,
	DecodeImageArgQuirks quirks = DecodeImageArgQuirks::DefaultValue(),
	DecodeImageArgFlags flags = DecodeImageArgFlags::DefaultValue(),
	DecodeImageArgPixelBlend pixel_blend =
	DecodeImageArgPixelBlend::DefaultValue(),
	DecodeImageArgBackgroundColor background_color =
	DecodeImageArgBackgroundColor::DefaultValue(),
	DecodeImageArgMaxInclDimension max_incl_dimension =
	DecodeImageArgMaxInclDimension::DefaultValue(),
	DecodeImageArgMaxInclMetadataLength max_incl_metadata_length =
	DecodeImageArgMaxInclMetadataLength::DefaultValue());

	} // namespace wuffs_aux