Document PNG image preprocessor in user manual (preprocessors section)

[maciejmalecki]

Summary

The PNG image preprocessor (the image processor domain) currently lacks direct documentation in the Preprocessors section of the user manual at https://c64lib.github.io/gradle-retro-assembler-plugin/. While other preprocessors (CharPad, SpritePad, GoatTracker) have dedicated coverage, PNG image processing is not documented as a first-class preprocessor entry, leaving users without a clear reference for its DSL, transformations, and outputs.

Motivation

The image preprocessor is a fully-featured part of the plugin (processors/image) and exposes a rich DSL for converting PNG images into C64-friendly assets:

• Hardware sprites and software sprite shapes (spriteWriter)
• Bitmap output (bitmapWriter)
• Image transformations: cut, split, extend, flip, reduceResolution
• Composable / nested transformation pipelines

Without documentation, users discover this functionality only by reading source code or sample projects, which hurts adoption and increases support load.

Scope

Add a dedicated PNG / Image Preprocessor subsection under Preprocessors in the user manual covering:

1. Overview — what the preprocessor does and when to use it (sprites, bitmaps, sprite sheets)
2. DSL reference — the imagePipelines block under preprocess, including:
   • input (source PNG)
   • useBuildDir flag
   • Output writers: spriteWriter, bitmapWriter
   • Transformations: cut (left/top/width/height), split (width/height), extend (newWidth/newHeight/fillColor), flip (axis), reduceResolution (reduceX/reduceY)
3. Transformation pipeline semantics — order of operations, nesting, multi-image fan-out from split, indexed output naming
4. Examples — minimal end-to-end snippets for the most common cases:
   • Single PNG → hardware sprites
   • PNG → bitmap
   • Sprite sheet split + per-frame output
   • Cut + flip + sprite output
5. Input requirements — supported PNG formats / color depth, palette expectations
6. Output formats — produced binary layouts for sprite vs. bitmap writers
7. Cross-references — link to the flows PNG step (issue Pipeline DSL - support for PNG files #120 follow-up) once available, and to related preprocessors

Source-of-Truth References

• DSL entry point: processors/image/adapters/in/gradle/.../ProcessImage.kt
• DSL extensions: shared/gradle/dsl/ (PreprocessingExtension, ImageTransformationExtension, ImageCutExtension, ImageSplitExtension, ImageExtendExtension, ImageFlipExtension, ImageReduceResolutionExtension)
• Use cases: processors/image/src/main/kotlin/.../usecase/ (ReadSourceImageUseCase, WriteImageUseCase, CutImageUseCase, SplitImageUseCase, ExtendImageUseCase, FlipImageUseCase, ReduceResolutionUseCase)
• Output adapters: processors/image/adapters/out/file/ (C64SpriteWriter, C64CharsetWriter)
• PNG reader: processors/image/adapters/out/png/ReadPngImageAdapter.kt

Acceptance Criteria

• User manual has a dedicated PNG / Image Preprocessor subsection under Preprocessors
• All DSL options (input, useBuildDir, both writers, all five transformations) are documented with parameter descriptions and defaults
• At least three working examples are included (hardware sprites, bitmap, split sprite sheet)
• Pipeline semantics (transformation order, nesting, multi-image output) are explained
• Input PNG requirements (color depth, palette) are stated
• Cross-references to other preprocessors (CharPad, SpritePad) are added
• Documentation is published to https://c64lib.github.io/gradle-retro-assembler-plugin/

Notes

• This issue is documentation-only — no code changes required
• Documentation should describe the preprocessor as it exists today; the future flows-based PNG step (issue Pipeline DSL - support for PNG files #120) is out of scope here and will be documented separately