emscripten_docker/povray_wasm2

POV-Ray to WebAssembly Build System

This Docker-based build system compiles POV-Ray 3.6.1 to WebAssembly using Emscripten. POV-Ray 3.6 is used because it doesn't require Boost threading libraries (libboost-thread), which are incompatible with Emscripten. Version 3.7+ introduced multi-threading support using Boost, making 3.6 the ideal choice for WASM compilation.

Prerequisites

• Docker
• Docker Compose

Directory Structure

.
├── docker-compose.yml
├── Dockerfile
├── scripts/
│   ├── build.sh
│   └── configure_povray.sh
├── patches/
│   └── povray-3.6-emscripten.patch
├── scenes/              # Optional: Sample POV-Ray scene files
└── output/              # Generated WASM files will be placed here

Usage

1. Build the Docker image and compile POV-Ray to WASM

docker-compose up --build

This will:

• Download POV-Ray 3.6.1 source code
• Build required dependencies (zlib, libpng) into Emscripten's sysroot
• Verify dependencies are properly installed
• Apply Emscripten compatibility patches
• Configure POV-Ray without threading support
• Compile to WebAssembly
• Output povray.js and povray.wasm to the output/ directory

2. Clean build (remove containers and rebuild)

docker-compose down
docker-compose up --build

3. Run interactively for debugging

docker-compose run --rm povray-wasm-builder

Configuration

You can customize the build by setting environment variables in docker-compose.yml:

• POVRAY_VERSION: POV-Ray version to build (default: 3.6.1)
• OUTPUT_DIR: Output directory for WASM files (default: /output)

Using the Generated WASM

After building, you'll have two files in the output/ directory:

• povray.js: JavaScript loader and runtime
• povray.wasm: WebAssembly binary

Example Usage in Node.js

const POVRay = require('./output/povray.js');

POVRay().then(instance => {
  // Write a scene file
  instance.FS.writeFile('/scene.pov', `
    camera { location <0, 2, -3> look_at <0, 0, 0> }
    light_source { <2, 4, -3> color rgb 1 }
    sphere { <0, 0, 0>, 1 pigment { color rgb <1, 0, 0> } }
  `);
  
  // Render the scene
  instance.callMain(['-i/scene.pov', '-o/output.png', '+W640', '+H480']);
  
  // Read the output
  const output = instance.FS.readFile('/output.png');
  require('fs').writeFileSync('output.png', output);
});

Example Usage in Browser

<script src="povray.js"></script>
<script>
  POVRay().then(instance => {
    // Write scene and render
    instance.FS.writeFile('/scene.pov', sceneContent);
    instance.callMain(['-i/scene.pov', '-o/output.png', '+W320', '+H240']);
    
    // Get output image
    const imageData = instance.FS.readFile('/output.png');
    // Display in browser...
  });
</script>

Why POV-Ray 3.6?

POV-Ray 3.6 was chosen for this WASM build because:

1. No Boost Threading: Version 3.6 is single-threaded and doesn't use libboost-thread
2. Simpler Dependencies: Fewer external library requirements
3. Emscripten Compatibility: Single-threaded applications compile more reliably to WASM
4. Stable Release: 3.6.1 is a stable, well-tested release

POV-Ray 3.7+ introduced multi-threading using Boost, which is incompatible with Emscripten's threading model, making 3.6 the better choice for WebAssembly compilation.

Notes

• The build disables display support (X11, SDL) as they're not applicable to WASM
• Image format support is limited to PNG (via libpng) and PPM
• Multi-threading is disabled (not supported in WASM for POV-Ray)
• The build uses static linking for all dependencies

Troubleshooting

Build fails with "cannot find -lboost_thread"

This shouldn't happen with POV-Ray 3.6, but if it does, ensure you're using version 3.6.1 and not 3.7+.

Configure fails with "zlib not installed"

This means the zlib dependency wasn't built correctly. Try:

docker-compose down -v
docker-compose up --build

The build system installs zlib and libpng into Emscripten's sysroot (/emsdk/upstream/emscripten/cache/sysroot) and configures POV-Ray to find them there.

WASM file is too large

Adjust optimization flags in scripts/build.sh:

• Use -O3 for size optimization
• Add -s MINIFY_HTML=1 for smaller output

Runtime errors in browser

Check browser console for specific errors. Common issues:

• Memory limits: Increase with -s INITIAL_MEMORY=128MB
• File system access: Ensure FORCE_FILESYSTEM is enabled

License

POV-Ray 3.6 is distributed under the POV-Ray license. See the POV-Ray source for details. Emscripten is licensed under the MIT License.