shader-converter-wasm/API.md

WebAssembly-based shader language converter and validator. Convert between GLSL, WGSL, SPIR-V, Metal, and HLSL in the browser.

# Shader Converter WASM API Documentation

## Overview

The Shader Converter WASM module provides browser-based shader language processing capabilities including SPIR-V manipulation and shader language conversion.

## Installation

```javascript
import init, { SpirvProcessor, ShaderConverter, ShaderError } from './build/shader_converter_wasm.js';

// Initialize the WASM module
await init();
```

## Classes

### SpirvProcessor

Handles SPIR-V binary and assembly processing operations.

#### Constructor

```javascript
const processor = new SpirvProcessor();
```

#### Methods

##### `binary_to_assembly(binary_data: Uint8Array) -> string`

Convert SPIR-V binary data to assembly text.

**Parameters:**
- `binary_data`: SPIR-V binary data as Uint8Array

**Returns:** Assembly text representation of the SPIR-V module

**Example:**
```javascript
const spirvBytes = new Uint8Array([0x07, 0x23, 0x02, 0x03]); // SPIR-V magic number
const assembly = processor.binary_to_assembly(spirvBytes);
console.log(assembly);
```

##### `assembly_to_binary(assembly_text: string) -> Uint8Array`

Convert SPIR-V assembly text to binary format.

**Parameters:**
- `assembly_text`: SPIR-V assembly text

**Returns:** SPIR-V binary data as Uint8Array

**Example:**
```javascript
const assembly = "; Test assembly\nOpCapability Shader\nOpMemoryModel Logical GLSL450";
const binary = processor.assembly_to_binary(assembly);
console.log(`Binary length: ${binary.length} bytes`);
```

##### `validate_binary(binary_data: Uint8Array) -> boolean`

Validate SPIR-V binary module.

**Parameters:**
- `binary_data`: SPIR-V binary data as Uint8Array

**Returns:** True if valid, false otherwise

**Example:**
```javascript
const isValid = processor.validate_binary(spirvBytes);
if (isValid) {
    console.log("SPIR-V module is valid");
} else {
    console.log("SPIR-V module is invalid");
}
```

##### `get_module_info(binary_data: Uint8Array) -> string`

Extract basic information from SPIR-V module.

**Parameters:**
- `binary_data`: SPIR-V binary data as Uint8Array

**Returns:** Formatted string containing module information

**Example:**
```javascript
const info = processor.get_module_info(spirvBytes);
console.log(info);
// Output:
// Magic: 0x07230203
// Version: 65536
// Generator: 0
// Bound: 1
// Schema: 0
// Size: 20 bytes
// Word count: 5
```

### ShaderConverter

Handles shader language parsing, validation, and conversion.

#### Constructor

```javascript
const converter = new ShaderConverter();
```

#### Methods

##### `parse_glsl(source: string) -> string`

Parse and validate GLSL shader source code.

**Parameters:**
- `source`: GLSL shader source code

**Returns:** Parsing results and validation information

**Example:**
```javascript
const glsl = `#version 330 core
attribute vec3 aPosition;
void main() {
    gl_Position = vec4(aPosition, 1.0);
}`;

const result = converter.parse_glsl(glsl);
console.log(result);
```

##### `parse_wgsl(source: string) -> string`

Parse and validate WGSL shader source code.

**Parameters:**
- `source`: WGSL shader source code

**Returns:** Parsing results and validation information

**Example:**
```javascript
const wgsl = `@vertex
fn vs_main(@location(0) pos: vec3<f32>) -> @builtin(position) vec4<f32> {
    return vec4<f32>(pos, 1.0);
}`;

const result = converter.parse_wgsl(wgsl);
console.log(result);
```

##### `convert_shader(source: string, from_format: string, to_format: string) -> string`

Convert shader from one format to another.

**Parameters:**
- `source`: Source shader code
- `from_format`: Input format ('glsl', 'wgsl', 'spirv')
- `to_format`: Output format ('glsl', 'wgsl', 'spirv', 'msl', 'hlsl')

**Returns:** Converted shader code

**Example:**
```javascript
const glslSource = "#version 330 core\nattribute vec3 pos;\nvoid main() { gl_Position = vec4(pos, 1.0); }";
const wgslResult = converter.convert_shader(glslSource, 'glsl', 'wgsl');
console.log(wgslResult);
```

##### `validate_shader(source: string, format: string) -> string`

Validate shader source code based on format.

**Parameters:**
- `source`: Shader source code
- `format`: Shader format ('glsl', 'wgsl')

**Returns:** Validation results

**Example:**
```javascript
const validation = converter.validate_shader(glslSource, 'glsl');
console.log(validation);
```

## Error Handling

The module uses `ShaderError` for error reporting:

```javascript
try {
    const result = processor.binary_to_assembly(invalidBytes);
} catch (error) {
    console.error('Shader Error:', error.message);
}
```

## Supported Formats

### Input Formats
- **GLSL**: OpenGL Shading Language
- **WGSL**: WebGPU Shading Language
- **SPIR-V**: SPIR-V binary format

### Output Formats
- **GLSL**: OpenGL Shading Language
- **WGSL**: WebGPU Shading Language
- **SPIR-V**: SPIR-V binary/assembly
- **MSL**: Metal Shading Language (placeholder)
- **HLSL**: High-Level Shading Language (placeholder)

## Limitations (MVP Version)

- SPIR-V processing includes basic parsing and header extraction
- Shader conversions use placeholder transformations
- Full naga integration required for accurate conversions
- Performance optimizations not implemented
- No support for advanced SPIR-V features

## Browser Compatibility

- Modern browsers supporting WebAssembly
- ES6 module support required
- CORS headers needed for cross-origin requests