Files
wuffs/internal/cgen/auxiliary/image.hh
T

217 lines
9.7 KiB
C++
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
// 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. SelectPixfmt
// 3. AllocPixbuf
// 4. AllocWorkbuf
// 5. 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 the
// caller is responsible for examining the opening bytes (a prefix) of the
// input data. SelectDecoder implementations should not modify those bytes.
//
// 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__WBMP
virtual wuffs_base__image_decoder::unique_ptr //
SelectDecoder(uint32_t fourcc, wuffs_base__slice_u8 prefix);
// 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_OutOfMemory[];
extern const char DecodeImage_UnexpectedEndOfFile[];
extern const char DecodeImage_UnsupportedImageFormat[];
extern const char DecodeImage_UnsupportedPixelBlend[];
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.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.
DecodeImageResult //
DecodeImage(DecodeImageCallbacks& callbacks,
sync_io::Input& input,
wuffs_base__pixel_blend pixel_blend = WUFFS_BASE__PIXEL_BLEND__SRC,
wuffs_base__color_u32_argb_premul background_color = 1, // Invalid.
uint32_t max_incl_dimension = 1048575); // 0x000F_FFFF
} // namespace wuffs_aux