Skip to content

Update C_PLUS_PLUS.md (#21) #22

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ddwmv merged 1 commit into from
Jun 8, 2026
Merged

Update C_PLUS_PLUS.md (#21) #22

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 8 additions & 8 deletions C_PLUS_PLUS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,15 @@

WIMF (Worst IMage Format) uses a high-performance C++ core to handle computationally intensive image processing tasks. This document provides instructions for building, extending, and maintaining the C++ components.

## 🚀 Architecture Overview
## Architecture Overview

The C++ engine is located in `src/main.cpp` and is exposed to Python via `pybind11`. It focuses on three critical areas:

1. **SIMD-Accelerated Haar Wavelets**: Uses manual AVX2 (x86) and NEON (ARM) intrinsics to process 2x2 wavelet blocks in parallel.
2. **Reversible YCoCg-R**: A bit-perfect integer-based color transform implemented in C++ for maximum speed during lossless and lossy encoding.
3. **Fast Paeth Predictor**: Accelerates the lossless spatial prediction filter used in WIMF's "PNG-style" compression.

## 🛠️ Building the Extension
## Building the Extension

### Prerequisites
- A modern C++ compiler (GCC 7+, Clang 10+, or MSVC 2019+)
Expand All @@ -29,7 +29,7 @@ This will compile `src/main.cpp` and place the resulting shared object (`.so` or
python setup.py build_ext --inplace
```

## 🏎️ SIMD Optimizations
## SIMD Optimizations

The engine automatically detects the target architecture during compilation:

Expand All @@ -41,29 +41,29 @@ The Haar transform implementation (`haar_level` and `ihaar_level`) uses:
- **AVX2** (256-bit) on x86_64 to process 4 blocks simultaneously.
- **NEON** (128-bit) on ARM/Android to process 4 blocks simultaneously using `vld2q_f32` and `vst1q_f32`.

## 🌐 Web & Mobile Support
## Web & Mobile Support

### WebAssembly (Wasm)
The core algorithms are exported with C linkage for Wasm compatibility. Functions like `ycocg_forward_raw` and `haar_level_raw` can be called directly from JavaScript when compiled with Emscripten.

### Android
The C++ core is optimized for Android using NEON intrinsics, ensuring the WIMF codec remains high-performance on mobile hardware. It is recommended to build using the Android NDK with `-O3` and NEON enabled.

## 🧪 Testing
## Testing

The C++ components are verified using `pytest`. Ensure you have the extension built before running tests:
```bash
pip install pytest numpy pillow
pytest wimf/
```

## 📂 File Structure
## File Structure

- `src/main.cpp`: The monolithic C++ source containing all core algorithms and Python bindings.
- `setup.py`: Build configuration for the C++ extension.
- `.github/workflows/wheels.yml`: Production CI that builds optimized binary wheels for multiple platforms.

## 🔧 Extending the C++ Engine
## Extending the C++ Engine

To add a new function to the C++ core:

Expand All @@ -76,6 +76,6 @@ To add a new function to the C++ core:
m.def("my_new_function", &my_new_function, "Description of what it does");
```

## 📦 Production Distribution
## Production Distribution

Production builds are handled by `cibuildwheel` in the GitHub Actions workflow. This ensures that users on Linux, Windows, and macOS receive pre-compiled binaries optimized for their specific CPU architecture.