Consolidated image format support (#148)

Author: kunitoki

.github/workflows/coverage.yml

@@ -129,7 +129,7 @@ jobs:
         file: ${{ runner.workspace }}/build/coverage/coverage_final.info
         name: overall-coverage
         fail_ci_if_error: false
-        verbose: false
+        verbose: true
     - name: Upload Test Results
       uses: actions/upload-artifact@v7
       if: always()

.gitignore

@@ -51,3 +51,4 @@ __pycache__/
 .pytest_cache/
 .cache/
 docs/superpowers/
+reasonix.toml

CHANGELOG.md

@@ -30,6 +30,17 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 - New `GpuTarget` class (`rhi/yup_GpuTarget.h`): low-level render-pass-only offscreen GPU surface (`create`, `beginRenderPass`, `asTexture`, `asImage`, `readPixels`). Its backing texture is allocated from the context's main render context, so it does not reserve a dedicated `rive::gpu::RenderContext` — use it for custom `GpuPipeline` work (e.g. post-process passes) that needs no 2D drawing.
 - New `GpuCanvas` class (`rhi/yup_GpuCanvas.h`): consolidated backend-agnostic offscreen GPU surface that now composes a `GpuTarget` (over a `RenderableTarget`) and creates a non-owning `Graphics` lazily only when 2D drawing is requested.
 
+#### Image Formats
+
+- Added TIFF read/write support (`TiffImageFormat`) via libtiff: RGB, RGBA, Grayscale at 8/16-bit; multi-page reading; DPI and EXIF/ICC/XMP metadata extraction.
+- Added TGA read/write support (`TgaImageFormat`): uncompressed and RLE-compressed truecolor and grayscale variants; RGB and RGBA output with alpha channel preservation.
+- Added animated WebP encoding and decoding support to `WebPImageFormatWriter` and `WebPImageFormatReader`: per-frame metadata (canvas dimensions, frame count, loop count, per-frame delays, dispose/blend modes) and frame decompression with manual compositing.
+- Added animated PNG (APNG) encoding and decoding support to `PngImageFormatWriter` and `PngImageFormatReader`: manual chunk-level parsing of `acTL`/`fcTL`/`fdAT` chunks for animation metadata, per-frame libpng decoding via synthetic minimal PNG construction, and canvas compositing supporting all three APNG disposal operations (none, background, previous) and both blend operations (source, over).
+- `ImageFormat::Options` struct controls metadata extraction: `.withMetadata(true)` enables text metadata and DPI; `.withRawChunks(true)` enables raw binary chunks (EXIF, ICC, XMP). When both are false (the default), `ImageMetadata` is not allocated — true zero overhead.
+- Introduced a ref-counted `ImageMetadata` object (`ImageMetadata::Ptr`) attached to `Image` and `ImageFormatReader::metadata`. DPI, text entries, and raw binary chunks are all accessed through the metadata object only when requested via `Options`.
+- Lossless roundtrip tests for all formats (BMP, PNG, WebP, TGA, TIFF, PPM, GIF) now verify pixel-perfect fidelity after write→read; animated roundtrip tests for GIF, WebP, and PNG verify per-frame pixel integrity.
+
+
 ### Shading
 
 - New GLSL→WGSL direct transpiler in `yup_shading`: parses preprocessed GLSL 4.50, lowers GLSL constructs to WGSL equivalents, and emits WGSL 1.0 source. Supports vertex/fragment/compute stages with full builtin mapping, combined sampler splitting, entry-point IO wrapping, and binding assignment matching glslang's SPIR-V assignment 1:1. Does not require SPIR-V or spirv_cross for code generation. Integrated into `ShaderTranspiler`, `ShaderCache`, and `ShaderBundleCompiler`. WGSL variants are supported in YSLB bundles via the `shader_bundler` tool and `yup_add_shader_bundle()` CMake helper.

README.md

@@ -171,6 +171,17 @@ YUP is usable for experimentation, examples, prototypes, and contributors who ar
 | **iOS** (enc)     | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: |                    |
 | **iOS** (dec)     | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: |                    |
 
+## Supported Image Formats
+|                   | **Read**           | **Write**          | **Read Animated**  | **Write Animated** | **Metadata R/W**   | **Dependent on module** |
+|-------------------|:------------------:|:------------------:|:------------------:|:------------------:|:------------------:|:-----------------------:|
+| **BMP**           | :white_check_mark: | :white_check_mark: |                    |                    |                    |                         |
+| **PPM**           | :white_check_mark: | :white_check_mark: |                    |                    |                    |                         |
+| **TGA**           | :white_check_mark: | :white_check_mark: |                    |                    | :white_check_mark: |                         |
+| **TIFF**          | :white_check_mark: | :white_check_mark: |                    |                    | :white_check_mark: | libtiff                 |
+| **JPG**           | :white_check_mark: | :white_check_mark: |                    |                    | :white_check_mark: | libjpeg                 |
+| **PNG**           | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | libpng                  |
+| **GIF**           | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: |                    | libgif                  |
+| **WEBP**          | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | libwebp                 |
 
 ## Prerequisites
 Before building, make sure you have:

cmake/yup_standalone.cmake

@@ -26,7 +26,7 @@ function (yup_standalone_app)
         # Globals
         TARGET_NAME TARGET_VERSION TARGET_CONSOLE TARGET_IDE_GROUP TARGET_APP_NAMESPACE TARGET_ICON TARGET_WHEEL TARGET_CXX_STANDARD
         # Emscripten
-        INITIAL_MEMORY MAXIMUM_MEMORY PTHREAD_POOL_SIZE STACK_SIZE CUSTOM_PLIST CUSTOM_SHELL ENABLE_EMSCRIPTEN_WEBGPU ENABLE_EMSCRIPTEN_GL_DEBUGGING)
+        INITIAL_MEMORY MAXIMUM_MEMORY PTHREAD_POOL_SIZE STACK_SIZE CUSTOM_PLIST CUSTOM_SHELL ENABLE_EMSCRIPTEN_WEBGPU ENABLE_EMSCRIPTEN_GL_DEBUGGING ENABLE_EMSCRIPTEN_NODERAWFS)
     set (multi_value_args
         # Globals
         DEFINITIONS COMPILE_OPTIONS MODULES SOURCES LINK_OPTIONS
@@ -39,6 +39,7 @@ function (yup_standalone_app)
     _yup_set_default (YUP_ARG_TARGET_ICON "${CMAKE_CURRENT_FUNCTION_LIST_DIR}/resources/app-icon.png")
     _yup_set_default (YUP_ARG_ENABLE_EMSCRIPTEN_WEBGPU OFF)
     _yup_set_default (YUP_ARG_ENABLE_EMSCRIPTEN_GL_DEBUGGING OFF)
+    _yup_set_default (YUP_ARG_ENABLE_EMSCRIPTEN_NODERAWFS OFF)
 
     set (target_name "${YUP_ARG_TARGET_NAME}")
     set (target_version "${YUP_ARG_TARGET_VERSION}")
@@ -221,7 +222,7 @@ function (yup_standalone_app)
             $<$<BOOL:${YUP_ARG_MAXIMUM_MEMORY}>:-sMAXIMUM_MEMORY=${YUP_ARG_MAXIMUM_MEMORY}>
             -sPTHREAD_POOL_SIZE=${YUP_ARG_PTHREAD_POOL_SIZE}
             -sFORCE_FILESYSTEM=1
-            -sNODERAWFS=0
+            -sNODERAWFS=$<IF:$<BOOL:${YUP_ARG_ENABLE_EMSCRIPTEN_NODERAWFS}>,1,0>
             -sWASMFS=1
             -sFETCH=1
             -sEXPORTED_RUNTIME_METHODS=ccall,cwrap

docs/graphics/rhi/index.md

@@ -45,6 +45,8 @@ offscreen render-to-texture pipelines.
   shader sources, binding maps, and the pipeline cache.
 - [Offline shader compilation](offline-shaders.md) - build `.ysl` shader bundles
   ahead of time with `yup_add_shader_bundle` and the `yup_shader_bundler` tool.
+- [Shader bundle binary format](shader-bundle-format.md) - the RIFF `YSLB` container
+  specification (FourCCs, chunk layout, reflection blob, versioning).
 - [Buffers & textures](buffers-and-textures.md) - `GpuBuffer` and `GpuTexture`.
 - [Offscreen targets & canvases](targets.md) - `GpuTarget`, `GpuCanvas`, and CPU
   readback.
@@ -59,6 +61,7 @@ concepts
 frames-and-passes
 pipelines
 offline-shaders
+shader-bundle-format
 buffers-and-textures
 targets
 spinning-cube

docs/graphics/rhi/offline-shaders.md

@@ -218,6 +218,8 @@ yup_add_shader_bundle(my_shaders
 ## See also
 
 - [Pipelines & shaders](pipelines.md) - compiling and configuring pipelines.
+- [Shader bundle binary format](shader-bundle-format.md) - the RIFF `YSLB` container
+  specification for `.ysl` files.
 - [`yup_add_embedded_binary_resources`](../../build-system/cmake-api.md#yup_add_embedded_binary_resources) -
   the embedding primitive `yup_add_shader_bundle` builds on.
 - [Walkthrough: the spinning cube](spinning-cube.md) - an end-to-end example.

…/yup_shading/shading/yup_ShaderBundle.md docs/graphics/rhi/shader-bundle-format.mdmodules/yup_shading/shading/yup_ShaderBundle.md renamed to docs/graphics/rhi/shader-bundle-format.md modules/yup_shading/shading/yup_ShaderBundle.md renamed to docs/graphics/rhi/shader-bundle-format.md

@@ -77,7 +77,7 @@ The whole file is a single `RIFF` chunk whose form type is `YSLB`.
 
 ```
 +===========================================================================+
-|  RIFF  |  size  |  'YSLB'                                                  |
+|  RIFF  |  size  |  'YSLB'                                                 |
 +===========================================================================+
          |                                                                  |
          |   +--------+--------+------------------+                         |
@@ -179,13 +179,13 @@ entry point, transpiled source, optional original input source, and reflection.
 +--------------------------------------------------------------------------+
 ```
 
-| Field        | Type          | Meaning                                                |
-|--------------|---------------|--------------------------------------------------------|
-| `language`   | `int32`       | Target `ShaderLanguage` of this variant.               |
-| `entryPoint` | prefixed str  | Entry-point function name (e.g. `"main"`).             |
-| `source`     | prefixed str  | Transpiled source code in `language`.                  |
+| Field        | Type          | Meaning                                                                      |
+|--------------|---------------|------------------------------------------------------------------------------|
+| `language`   | `int32`       | Target `ShaderLanguage` of this variant.                                     |
+| `entryPoint` | prefixed str  | Entry-point function name (e.g. `"main"`).                                   |
+| `source`     | prefixed str  | Transpiled source code in `language`.                                        |
 | `ISRC`       | chunk         | Original Vulkan GLSL input source, raw UTF-8. Optional — omitted when empty. |
-| `REFL`       | chunk         | Serialised `ShaderReflection` (see below).             |
+| `REFL`       | chunk         | Serialised `ShaderReflection` (see below).                                   |
 
 ### `ISRC` — Original input source
 
@@ -237,28 +237,28 @@ independently of the RIFF envelope version.
 
 ## 6. FourCC Reference
 
-| FourCC | Constant          | Role                                          |
-|--------|-------------------|-----------------------------------------------|
-| `RIFF` | `kFourCC_RIFF`    | Outer RIFF container.                         |
-| `LIST` | `kFourCC_LIST`    | Generic list container.                       |
-| `YSLB` | `kFourCC_YSLB`    | Bundle form type (magic).                     |
-| `VERS` | `kFourCC_VERS`    | Format version chunk.                         |
-| `SHAD` | `kFourCC_SHAD`    | List type for the stage list.                 |
-| `SHDR` | `kFourCC_SHDR`    | Per-stage chunk.                              |
-| `SPVB` | `kFourCC_SPVB`    | SPIR-V binary chunk.                          |
-| `VARS` | `kFourCC_VARS`    | List type for the variant list.               |
-| `VART` | `kFourCC_VART`    | Per-variant chunk.                            |
+| FourCC | Constant          | Role                                                 |
+|--------|-------------------|------------------------------------------------------|
+| `RIFF` | `kFourCC_RIFF`    | Outer RIFF container.                                |
+| `LIST` | `kFourCC_LIST`    | Generic list container.                              |
+| `YSLB` | `kFourCC_YSLB`    | Bundle form type (magic).                            |
+| `VERS` | `kFourCC_VERS`    | Format version chunk.                                |
+| `SHAD` | `kFourCC_SHAD`    | List type for the stage list.                        |
+| `SHDR` | `kFourCC_SHDR`    | Per-stage chunk.                                     |
+| `SPVB` | `kFourCC_SPVB`    | SPIR-V binary chunk.                                 |
+| `VARS` | `kFourCC_VARS`    | List type for the variant list.                      |
+| `VART` | `kFourCC_VART`    | Per-variant chunk.                                   |
 | `ISRC` | `kFourCC_ISRC`    | Original input source chunk (per-variant, optional). |
-| `REFL` | `kFourCC_REFL`    | Reflection archive chunk.                     |
+| `REFL` | `kFourCC_REFL`    | Reflection archive chunk.                            |
 
 Current format version: **`2`** (`kCurrentVersion`).
 
 ### Version history
 
-| Version | Change                                                                 |
-|---------|------------------------------------------------------------------------|
+| Version | Change                                                                  |
+|---------|-------------------------------------------------------------------------|
 | 1       | Initial format. Top-level `SRCE` chunk held a single per-bundle source. |
-| 2       | Removed `SRCE`. Added per-variant `ISRC` sub-chunk inside `VART`.     |
+| 2       | Removed `SRCE`. Added per-variant `ISRC` sub-chunk inside `VART`.       |
 
 ---
 

docs/imaging/loading.md

@@ -22,6 +22,15 @@ else
 }
 ```
 
+Pass `ImageFormat::Options` as a second argument to extract metadata:
+
+```cpp
+auto opts = ImageFormat::Options()
+               .withMetadata (true)
+               .withRawChunks (true);
+auto result = Image::loadFromData (encodedBytes, opts);
+```
+
 ## The ImageFormatManager
 
 `ImageFormatManager` is the registry that maps files and streams to the right
@@ -54,10 +63,12 @@ PPM/PGM/PBM have no dependency and are always available.
 | ----------- | ----------------- | -------------- |
 | BMP         | `bmp`             | *(built in)*   |
 | PPM/PGM/PBM | `ppm`             | *(built in)*   |
+| TGA         | `tga`             | *(built in)*   |
 | PNG         | `png`             | `libpng`       |
 | JPEG        | `jpeg`            | `libjpeg`      |
 | WebP        | `webp`            | `libwebp`      |
 | GIF         | `gif`             | `libgif`       |
+| TIFF        | `tiff`            | `libtiff`      |
 
 ```cmake
 yup_standalone_app(
@@ -96,7 +107,7 @@ Ownership of the stream is **always** consumed by the call - on success the
 reader owns it; on failure it is deleted:
 
 ```cpp
-auto stream = someFile.createInputStream();  // std::unique_ptr<InputStream>
+std::unique_ptr<InputStream> stream = someFile.createInputStream();
 if (auto reader = formats.createReaderFor (stream.release()))
 {
     Image image = reader->readImage();
@@ -112,20 +123,45 @@ are plain public fields on `ImageFormatReader`:
 int    w   = reader->width;
 int    h   = reader->height;
 auto   fmt = reader->pixelFormat;
-double dx  = reader->dpiX;    // 0.0 if not present
-double dy  = reader->dpiY;
+```
+
+By default metadata extraction is **disabled** — the `metadata` field is
+`nullptr`. To opt in, pass `ImageFormat::Options` when creating the reader:
+
+```cpp
+// Request text metadata and DPI
+auto reader = formats.createReaderFor (stream.release(),
+                                       ImageFormat::Options().withMetadata (true));
 
-// Arbitrary key/value metadata from the file.
-// Standard keys: "dpiX", "dpiY", "colorSpace", "title", "software", "comment".
-String title = reader->metadataValues.getValue ("title", {});
+if (auto metadata = reader->metadata)
+{
+    double dx = metadata->dpiX;   // 0.0 if not present
+    double dy = metadata->dpiY;
+
+    // Arbitrary key/value pairs from the file
+    // Standard keys: "Title", "Software", "Comment", "dpiX", "dpiY"
+    String title = metadata->textEntries.getValue ("Title", {});
+
+    // Raw binary chunks (EXIF, ICC profile, XMP packet)
+    if (auto* exif = metadata->getRawChunk ("jpeg/exif"))
+        processExif (exif->getData(), exif->getSize());
+}
+```
+
+For `Image::loadFromData()`, pass options as the second argument:
+
+```cpp
+auto result = Image::loadFromData (bytes,
+                                   ImageFormat::Options().withRawChunks (true));
 ```
 
 `getFormatName()` returns the human-readable format label (e.g. `"PNG Image"`).
 
 ## Animated images
 
-Animated formats such as GIF expose multiple frames. Non-animated readers report
-a single frame, so the same code works for both:
+Formats that support animation — GIF, WebP, and PNG (APNG) — expose multiple
+frames through the same reader API. Non-animated readers report a single frame,
+so the same code works for both:
 
 ```cpp
 if (auto reader = formats.createReaderFor (File ("/path/anim.gif")))

docs/imaging/saving.md

@@ -25,8 +25,8 @@ embed metadata, and pick a quality level for compressed formats:
 ```cpp
 std::unique_ptr<ImageFormatWriter> createWriterFor (
     const File&            file,
-    PixelFormat            pixelFormat       = PixelFormat::RGBA,
-    const StringPairArray& metadataValues    = {},
+    PixelFormat            pixelFormat        = PixelFormat::RGBA,
+    const StringPairArray& metadataValues     = {},
     int                    qualityOptionIndex = 0);
 ```
 
@@ -54,8 +54,8 @@ Compressed formats expose named quality levels. Query them from the
 `ImageFormat` and pass the chosen index to `createWriterFor`:
 
 ```cpp
-// getQualityOptions() returns labels like {"Low", "Medium", "High"};
-// isCompressed() is false for BMP/PPM and true for PNG/WebP/JPEG.
+getQualityOptions() // returns labels like {"Low", "Medium", "High"}
+isCompressed()      // is false for BMP/PPM and true for PNG/WebP/JPEG
 ```
 
 `qualityOptionIndex` is ignored by lossless/uncompressed formats.
@@ -85,13 +85,14 @@ if (auto writer = pngFormat.createWriterFor (outStream.release(),
 
 The writer takes ownership of the destination stream.
 
-## Animated GIF output
+## Animated output
 
-Only the GIF writer supports animation (`supportsAnimation()` returns true).
-Bracket the frames between `beginAnimation()` and `endAnimation()`:
+GIF, WebP, and PNG (APNG) writers support animation (`supportsAnimation()`
+returns true). Bracket the frames between `beginAnimation()` and
+`endAnimation()`:
 
 ```cpp
-if (auto writer = formats.createWriterFor (File ("/path/anim.gif")))
+if (auto writer = formats.createWriterFor (File ("/path/anim.webp")))
 {
     if (writer->supportsAnimation())
     {
@@ -105,10 +106,10 @@ if (auto writer = formats.createWriterFor (File ("/path/anim.gif")))
 }
 ```
 
-Each `writeFrame` quantizes the frame to a 256-color palette and appends a
-Graphic Control Extension with the given delay. `loopCount` follows the reader
-convention: `0` = infinite, `1` = play once, `N` = play N times. Calling the
-animation methods on a non-animation writer asserts and returns `false`.
+Each `writeFrame` encodes the frame with the given display duration in
+milliseconds. `loopCount` follows the reader convention: `0` = infinite,
+`1` = play once, `N` = play N times. Calling the animation methods on a
+non-animation writer asserts and returns `false`.
 
 ## See also