dear-imgui-sys 0.1.0

# dear-imgui-sys

Low-level Rust bindings for Dear ImGui C++ library using bindgen.

## Overview

This crate provides unsafe Rust bindings to the Dear ImGui C++ library. It uses `bindgen` to automatically generate FFI bindings from the C++ headers, enabling direct access to the Dear ImGui API from Rust.

## Key Features

- **Direct C++ Bindings**: Uses bindgen to generate bindings directly from Dear ImGui C++ headers
- **MSVC ABI Compatibility**: Includes fixes for MSVC compiler ABI issues with small C++ return types
- **Docking Support**: Built with Dear ImGui's docking branch for advanced window management
- **WebAssembly Support**: Full WASM compatibility with proper configuration for web targets
- **Cross-Platform**: Supports Windows, Linux, macOS, and WebAssembly

## ABI Compatibility Issues and Solutions

### The Problem

When using `bindgen` to generate bindings for C++ libraries, there are known ABI (Application Binary Interface) compatibility issues, particularly with functions that return small C++ class types. This affects multiple platforms:

- **Linux**: System V AMD64 ABI requires non-trivial C++ objects to be returned by pointer ([bindgen#778](https://github.com/rust-lang/rust-bindgen/issues/778))
- **MSVC**: Special handling for small non-POD types causes crashes ([bindgen#2865](https://github.com/rust-lang/rust-bindgen/issues/2865))
- **General**: bindgen assumes register return for small classes ([bindgen#2992](https://github.com/rust-lang/rust-bindgen/issues/2992))

### Our Solution

We implement the solution pioneered by [easy-imgui-rs](https://github.com/rodrigorc/easy-imgui-rs/), which provides a robust fix for MSVC ABI issues:

#### 1. **FFI-Safe Wrapper Types**
```cpp
// FFI-safe POD type equivalent to ImVec2
struct ImVec2_rr { 
    float x, y; 
};
```

#### 2. **C Wrapper Functions**
```cpp
extern "C" {
    ImVec2_rr ImGui_GetContentRegionAvail() { 
        return _rr(ImGui::GetContentRegionAvail()); 
    }
}
```

#### 3. **Selective Function Blocking**
```txt
# msvc_blocklist.txt - Functions that need MSVC ABI fixes
ImGui::GetContentRegionAvail
ImGui::GetCursorScreenPos
ImGui::GetItemRectMin
# ... other problematic functions
```

#### 4. **Conditional Compilation**
```rust
pub fn content_region_avail(&self) -> [f32; 2] {
    unsafe {
        #[cfg(target_env = "msvc")]
        {
            let size_rr = sys::ImGui_GetContentRegionAvail();
            let size: sys::ImVec2 = size_rr.into();
            [size.x, size.y]
        }
        #[cfg(not(target_env = "msvc"))]
        {
            let size = sys::ImGui_GetContentRegionAvail();
            [size.x, size.y]
        }
    }
}
```

### Why This Solution Works

1. **Platform-Specific**: Only applies fixes where needed (MSVC targets)
2. **Type-Safe**: Maintains Rust's type safety through proper conversions
3. **Minimal Impact**: Only affects problematic functions, not the entire API
4. **Proven**: Successfully used by multiple Dear ImGui Rust bindings

## Build Configuration

The build system automatically detects the target environment and applies appropriate fixes:

```rust
// build.rs
if target_env == "msvc" {
    // Apply MSVC ABI fixes
    builder = builder
        .header("hack_msvc.cpp")
        .allowlist_file("hack_msvc.cpp");
        
    // Block problematic functions
    for line in blocklist_content.lines() {
        builder = builder.blocklist_function(line.trim());
    }
}
```

## Related Issues

- [rust-lang/rust-bindgen#778](https://github.com/rust-lang/rust-bindgen/issues/778) - Wrong ABI used for small C++ classes on Linux
- [rust-lang/rust-bindgen#2865](https://github.com/rust-lang/rust-bindgen/issues/2865) - C++ ABI in MSVC and function returning non-POD type  
- [rust-lang/rust-bindgen#2992](https://github.com/rust-lang/rust-bindgen/issues/2992) - bindgen wrongly assumes return by register for tiny C++ classes

## Acknowledgments

Our MSVC ABI fix implementation is based on the excellent work by [rodrigorc/easy-imgui-rs](https://github.com/rodrigorc/easy-imgui-rs/). This solution provides a robust and maintainable approach to handling C++ ABI compatibility issues in Rust FFI bindings.

## WebAssembly Support

This crate provides comprehensive WebAssembly (WASM) support through the `wasm` feature flag. The implementation automatically handles the complexities of cross-compilation and provides a seamless experience for WASM development.

### WASM Implementation Details

Our WASM support includes several key innovations:

- **No C++ Cross-Compilation**: Skips C++ compilation for WASM targets to avoid toolchain complexity
- **Pre-generated Bindings**: Uses reference bindings from native builds to ensure API compatibility
- **Consistent API**: Uses the same `ImGui_*` function naming for both native and WASM targets
- **Platform Abstraction**: Disables platform-specific functions that aren't available in WASM environments
- **Thread-Local Storage**: Properly handles TLS limitations in WASM environments

### Building for WASM

1. **Install WASM target**:
```bash
rustup target add wasm32-unknown-unknown
```

2. **Build for WASM**:
```bash
# Basic WASM build
cargo build --target wasm32-unknown-unknown --features wasm

# With additional features
cargo build --target wasm32-unknown-unknown --features "wasm,docking"

# Check compilation (faster)
cargo check --target wasm32-unknown-unknown --features wasm

# Build WASM example
cargo check --target wasm32-unknown-unknown --features wasm --example wasm_test
```

3. **Use the build script** (optional):
```bash
# Use the provided build script for automation
./build-wasm.sh
```

### WASM Feature Flags

```toml
[dependencies]
dear-imgui-sys = { version = "0.1.0", features = ["wasm"] }

# Or with additional features
dear-imgui-sys = { version = "0.1.0", features = ["wasm", "docking"] }
```

### Integration with wasm-bindgen

The generated WASM binaries are compatible with wasm-bindgen:

```bash
# Generate JavaScript bindings
wasm-bindgen --out-dir wasm --web target/wasm32-unknown-unknown/debug/your_app.wasm
```

### WASM Usage Example

```rust
use dear_imgui_sys::*;

unsafe {
    // Create ImGui context
    let ctx = ImGui_CreateContext(std::ptr::null_mut());
    ImGui_SetCurrentContext(ctx);

    // Verify context is working
    let current_ctx = ImGui_GetCurrentContext();
    assert!(!current_ctx.is_null());

    // Your ImGui code here...
    // Note: You'll need to provide rendering through JavaScript/Canvas

    // Cleanup
    ImGui_DestroyContext(ctx);
}
```

### Rendering in WASM

Since WASM doesn't have direct access to graphics APIs, you'll need to:

1. **Canvas API**: Render ImGui draw data to HTML5 Canvas through JavaScript
2. **WebGL Backend**: Implement a WebGL-based renderer for ImGui
3. **Existing Solutions**: Use existing WASM ImGui renderers or JavaScript bindings

### WASM-Specific Considerations

1. **No File System**: File operations are disabled by default in WASM builds
2. **No Threading**: Uses global context instead of thread-local storage
3. **Memory Management**: Ensure proper cleanup of ImGui contexts in WASM environment
4. **Performance**: WASM builds may have different performance characteristics
5. **Consistent API**: Uses the same `ImGui_*` naming convention for both native and WASM targets

## Usage

This is a low-level sys crate. Most users should use the higher-level `dear-imgui` crate instead, which provides safe Rust wrappers around these bindings.

```toml
[dependencies]
dear-imgui-sys = "0.1.0"

# For WASM targets
dear-imgui-sys = { version = "0.1.0", features = ["wasm"] }
```

## Potential Improvements

While our current solution works well, there are several areas where we could enhance the approach:

### 1. **Automated Detection**

```rust
// Future: Automatically detect problematic functions
fn needs_abi_fix(function: &Function) -> bool {
    function.returns_small_cpp_class() &&
    function.has_non_trivial_members() &&
    target_env == "msvc"
}
```

### 2. **Better Error Messages**

```rust
// Future: Provide clear guidance when ABI issues are detected
#[cfg(target_env = "msvc")]
compile_error!(
    "Function {} requires ABI fix. Add to msvc_blocklist.txt and create wrapper.",
    function_name
);
```

### 3. **Cross-Platform ABI Fixes**

Currently we only handle MSVC, but Linux and other platforms have similar issues. A comprehensive solution would:

- Detect non-trivial C++ types on all platforms
- Generate appropriate wrapper functions automatically
- Provide consistent behavior across all targets

### 4. **Upstream Contributions**

The ideal long-term solution would be improvements to `bindgen` itself:

- Better C++ ABI detection
- Automatic wrapper generation for problematic functions
- Platform-specific ABI handling

### 5. **Alternative Approaches**

#### Option A: Full Opaque Types

```rust
// Make all ImVec2-returning functions opaque
.opaque_type("ImVec2")
.blocklist_function(".*GetContentRegionAvail.*")
```

#### Option B: Custom ABI Annotations

```cpp
// Hypothetical: Explicit ABI annotations
extern "C" __attribute__((sysv_abi)) ImVec2_pod GetContentRegionAvail_pod();
```

#### Option C: Rust-Native Implementations

```rust
// Reimplement problematic functions in pure Rust
pub fn get_content_region_avail() -> [f32; 2] {
    // Direct implementation using ImGui internals
}
```

## Comparison with Other Solutions

| Approach | Pros | Cons | Maintenance |
|----------|------|------|-------------|
| **Our Solution** | ✅ Precise, Type-safe | ⚠️ Manual setup | 🟡 Medium |
| **Full Opaque** | ✅ Simple, Universal | ❌ Loses type info | 🟢 Low |
| **Phantom Data** | ✅ Forces stack return | ❌ Affects all types | 🟡 Medium |
| **Pure Rust** | ✅ No ABI issues | ❌ Reimplementation work | 🔴 High |

## Specific Improvements We Could Make

### 1. **Automated Wrapper Generation**

Instead of manually maintaining `hack_msvc.cpp`, we could generate it automatically:

```rust
// build.rs enhancement
fn generate_msvc_wrappers(functions: &[&str]) -> String {
    let mut code = String::new();
    for func in functions {
        if returns_imvec2(func) {
            code.push_str(&format!(
                "ImVec2_rr ImGui_{}() {{ return _rr(ImGui::{}()); }}\n",
                func, func
            ));
        }
    }
    code
}
```

### 2. **Better Function Detection**

We could automatically detect which functions need fixes by parsing Dear ImGui headers:

```rust
// Automatically find ImVec2-returning functions
fn find_problematic_functions() -> Vec<String> {
    // Parse imgui.h and find all functions returning ImVec2
    // This would eliminate the need for manual blocklist maintenance
}
```

### 3. **Runtime ABI Validation**

Add runtime checks to ensure our fixes work correctly:

```rust
#[cfg(all(test, target_env = "msvc"))]
mod abi_tests {
    #[test]
    fn test_content_region_avail_abi() {
        // Verify that our wrapper returns the same values as direct calls
        // This would catch ABI regressions
    }
}
```

### 4. **Cross-Platform Extension**

Extend the solution to handle Linux ABI issues:

```cpp
// Linux-specific wrappers for non-trivial types
#ifdef __linux__
extern "C" {
    void ImGui_GetContentRegionAvail_linux(ImVec2* out) {
        *out = ImGui::GetContentRegionAvail();
    }
}
#endif
```

## Summary

Our implementation represents a **best-practice solution** for handling C++ ABI compatibility issues in Rust FFI bindings:

### ✅ **What We Do Well**

- **Surgical Precision**: Only fixes problematic functions, leaving the rest of the API untouched
- **Type Safety**: Maintains Rust's type system guarantees through proper conversions
- **Platform Awareness**: Conditional compilation ensures fixes only apply where needed
- **Proven Approach**: Based on the successful easy-imgui-rs implementation
- **Clear Documentation**: Comprehensive explanation of the problem and solution

### 🚀 **Future Enhancements**

- **Automated Detection**: Generate wrapper functions automatically from header analysis
- **Cross-Platform Support**: Extend fixes to Linux and other platforms with similar issues
- **Runtime Validation**: Add tests to ensure ABI compatibility across different environments
- **Upstream Integration**: Contribute improvements back to the bindgen project

### 🎯 **Why This Matters**

C++ ABI compatibility is a fundamental challenge when creating Rust bindings for C++ libraries. Our solution provides:

- **Reliability**: Eliminates crashes and memory corruption
- **Maintainability**: Clear structure that's easy to understand and extend
- **Performance**: No runtime overhead, compile-time solution
- **Compatibility**: Works across different MSVC versions and configurations

This approach can serve as a template for other Rust projects facing similar C++ FFI challenges.

## License

This project follows the same license as Dear ImGui itself. See the Dear ImGui repository for license details.