Sprite Compiler Advanced Features¶

Advanced features and options for the PixelRoot32 Sprite Compiler to optimize sprite conversion and handle complex scenarios.

Dithering¶

Dithering improves the visual quality of converted sprites by simulating intermediate colors through pixel patterns.

Basic Dithering¶

Enable dithering for better gradient handling:

pr32-sprite-compiler sprite.png output.h --dither

Dithering Strength¶

Control dithering intensity:

pr32-sprite-compiler sprite.png output.h --dither --dither-strength 0.5

Values: - 0.0: No dithering - 0.5: Moderate dithering (default) - 1.0: Maximum dithering

Dithering Algorithms¶

Choose dithering algorithm:

# Floyd-Steinberg (default)
pr32-sprite-compiler sprite.png output.h --dither --dither-algorithm floyd-steinberg

# Ordered (Bayer)
pr32-sprite-compiler sprite.png output.h --dither --dither-algorithm ordered

# Atkinson
pr32-sprite-compiler sprite.png output.h --dither --dither-algorithm atkinson

When to use: - Floyd-Steinberg: Best for most images, smooth gradients - Ordered: Faster, good for patterns - Atkinson: Softer, less noticeable patterns

Layer Merging (MultiSprite)¶

Combine compatible sprite layers to reduce draw calls and improve performance.

Basic Layer Merging¶

Merge layers with compatible colors:

pr32-sprite-compiler sprite.png output.h --merge-layers

Layer Compatibility¶

Control which layers can be merged:

pr32-sprite-compiler sprite.png output.h \
    --merge-layers \
    --merge-threshold 0.1

Parameters: - --merge-threshold: Color similarity threshold (0.0-1.0)

Preserve Layer Colors¶

Keep per-layer color assignments:

pr32-sprite-compiler sprite.png output.h \
    --merge-layers \
    --preserve-colors

Bounds & Packing¶

Auto-Trim Transparent Borders¶

Automatically remove transparent borders:

pr32-sprite-compiler sprite.png output.h --trim

Benefits: - Reduces sprite size - Saves memory - Faster rendering

Manual Bounds¶

Specify custom bounds:

pr32-sprite-compiler sprite.png output.h \
    --bounds 2,2,14,14

Format: left,top,right,bottom (in pixels)

Sprite Packing¶

Pack multiple sprites into pages:

pr32-sprite-compiler --batch sprites/*.png \
    --output-dir packed/ \
    --pack \
    --pack-size 256x256

Parameters: - --pack: Enable packing - --pack-size WxH: Page size (default: 256x256) - --pack-padding N: Padding between sprites (default: 1)

Output: - Packed sprite sheet image - Individual sprite headers with offsets - Packing metadata

Output Controls¶

Endianness¶

Specify byte order for multi-byte values:

# Little-endian (default for most systems)
pr32-sprite-compiler sprite.png output.h --endian little

# Big-endian
pr32-sprite-compiler sprite.png output.h --endian big

Alignment¶

Control data structure alignment:

pr32-sprite-compiler sprite.png output.h --align 4

Common values: - 1: No alignment (default) - 2: 2-byte alignment - 4: 4-byte alignment (recommended for ESP32) - 8: 8-byte alignment

Output Format¶

Choose output code style:

# C-style (default)
pr32-sprite-compiler sprite.png output.h --style c

# C++ style
pr32-sprite-compiler sprite.png output.h --style cpp

# Minimal (no comments)
pr32-sprite-compiler sprite.png output.h --style minimal

Custom Header Template¶

Use custom header template:

pr32-sprite-compiler sprite.png output.h \
    --template custom_template.h

Template variables: - {NAME}: Sprite name - {DATA}: Sprite data array - {WIDTH}: Sprite width - {HEIGHT}: Sprite height

Metadata Generation¶

Generate Metadata¶

Include sprite metadata:

pr32-sprite-compiler sprite.png output.h --metadata

Output includes: - Original image dimensions - Conversion parameters - Color information - Format details

JSON Metadata¶

Export metadata as JSON:

pr32-sprite-compiler sprite.png output.h \
    --metadata \
    --metadata-format json \
    --metadata-file sprite.json

JSON structure:

{
  "name": "SPRITE",
  "width": 8,
  "height": 8,
  "format": "1bpp",
  "originalSize": {"width": 8, "height": 8},
  "colors": 2,
  "dataSize": 8
}

Color Processing¶

Color Quantization¶

Reduce colors intelligently:

pr32-sprite-compiler sprite.png output.h \
    --quantize \
    --colors 4

Parameters: - --quantize: Enable quantization - --colors N: Target color count

Color Mapping¶

Custom color mapping:

pr32-sprite-compiler sprite.png output.h \
    --color-map map.json

Map JSON format:

{
  "mappings": [
    {"from": [255, 0, 0], "to": [255, 255, 255]},
    {"from": [0, 255, 0], "to": [0, 0, 0]}
  ]
}

Gamma Correction¶

Apply gamma correction:

pr32-sprite-compiler sprite.png output.h --gamma 2.2

Common values: - 1.0: No correction - 2.2: Standard (sRGB) - 1.8: Mac standard

Performance Optimization¶

Parallel Processing¶

Process multiple files in parallel:

pr32-sprite-compiler --batch sprites/*.png \
    --output-dir generated/ \
    --parallel 4

Parameters: - --parallel N: Number of parallel workers (default: CPU cores)

Caching¶

Enable conversion caching:

pr32-sprite-compiler sprite.png output.h --cache

Benefits: - Faster re-compilation - Skips unchanged files - Cache stored in .sprite-compiler-cache/

Incremental Builds¶

Only process changed files:

pr32-sprite-compiler --batch sprites/*.png \
    --output-dir generated/ \
    --incremental

Validation¶

Validate Output¶

Verify generated sprite data:

pr32-sprite-compiler sprite.png output.h --validate

Checks: - Data array correctness - Size constraints - Format compliance - Memory usage

Preview Mode¶

Preview conversion without generating file:

pr32-sprite-compiler sprite.png --preview

Output: - Console preview of sprite data - Statistics (size, colors, etc.) - Validation results

Multi-Format Output¶

Generate Multiple Formats¶

Output in multiple formats simultaneously:

pr32-sprite-compiler sprite.png output.h \
    --formats 1bpp,2bpp,4bpp \
    --output-dir formats/

Outputs: - output_1bpp.h - output_2bpp.h - output_4bpp.h

Custom Scripts¶

Pre-Processing Script¶

Run custom script before conversion:

pr32-sprite-compiler sprite.png output.h \
    --pre-script preprocess.js

Post-Processing Script¶

Run custom script after conversion:

pr32-sprite-compiler sprite.png output.h \
    --post-script postprocess.js

Script receives: - Input file path - Output file path - Conversion parameters - Metadata

Advanced Batch Options¶

Filter by Size¶

Process only sprites matching size:

pr32-sprite-compiler --batch sprites/*.png \
    --output-dir generated/ \
    --filter-size 8x8

Filter by Format¶

Process only specific formats:

pr32-sprite-compiler --batch sprites/*.png \
    --output-dir generated/ \
    --filter-format indexed

Exclude Patterns¶

Exclude files matching pattern:

pr32-sprite-compiler --batch sprites/*.png \
    --output-dir generated/ \
    --exclude "*_old.png"

Integration Examples¶

Watch Mode¶

Automatically recompile on file changes:

pr32-sprite-compiler --watch assets/sprites/ \
    --output-dir src/sprites/

CI/CD Integration¶

Example GitHub Actions workflow:

name: Compile Sprites
on: [push]
jobs:
  compile:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v2
      - run: npm install -g pr32-sprite-compiler
      - run: pr32-sprite-compiler --batch assets/sprites/*.png --output-dir src/sprites/

Best Practices¶

When to Use Advanced Features¶

Dithering: - Use for gradients and smooth transitions - Avoid for sharp, pixel-art style graphics

Layer Merging: - Use for complex sprites with multiple layers - Test performance impact first

Packing: - Use for large sprite collections - Consider memory vs. performance trade-off

Trimming: - Always use for sprites with transparent borders - Saves memory and improves performance

Performance Tips¶

Use --parallel for batch processing
Enable --cache for development
Use --incremental for large projects
Validate output with --validate

Troubleshooting Advanced Features¶

Dithering Issues¶

Too much noise: - Reduce --dither-strength - Try different algorithm - Consider manual color reduction

Packing Issues¶

Sprites don't fit: - Increase --pack-size - Reduce sprite sizes - Adjust --pack-padding

Performance Issues¶

Slow compilation: - Use --parallel for batch - Enable --cache - Reduce image sizes - Use --incremental