hcie-rust-v3.05/hcie-vector/README.md

# hcie-vector

HCIE projelerinde kullanılan vektör şekil rasterizasyon motoru. 16 farklı şekil türünü piksel düzeyinde render eder, polyline dolgusu, kenar yumuşatma (hardness), döndürme ve boolean birleşim işlemlerini destekler. Ayrıca C-ABI/FFI üzerinden dinamik kütüphane olarak harici projelerden kullanılabilir.

## Kütüphane İçeriği

### Şekil Türleri (`VectorShape`)

| Şekil | Alanları |
|---|---|
| `Line` | x1, y1, x2, y2, stroke, color, angle, cap_start, cap_end, opacity, hardness |
| `Rect` | x1, y1, x2, y2, stroke, color, fill_color, fill, radius, angle, opacity, hardness |
| `Circle` | x1, y1, x2, y2, stroke, color, fill_color, fill, angle, opacity, hardness |
| `Arrow` | x1, y1, x2, y2, stroke, color, fill_color, fill, angle, opacity, hardness, thick |
| `Star` | x1, y1, x2, y2, stroke, color, fill_color, fill, angle, opacity, hardness, points, inner_radius |
| `Polygon` | x1, y1, x2, y2, stroke, color, fill_color, fill, sides, angle, opacity, hardness |
| `Rhombus` | x1, y1, x2, y2, stroke, color, fill_color, fill, angle, opacity, hardness |
| `Cylinder` | x1, y1, x2, y2, stroke, color, fill_color, fill, angle, opacity, hardness |
| `Heart` | x1, y1, x2, y2, stroke, color, fill_color, fill, angle, opacity, hardness |
| `Bubble` | x1, y1, x2, y2, stroke, color, fill_color, fill, angle, opacity, hardness |
| `Gear` | x1, y1, x2, y2, stroke, color, fill_color, fill, angle, opacity, hardness |
| `Cross` | x1, y1, x2, y2, stroke, color, fill_color, fill, angle, opacity, hardness |
| `Crescent` | x1, y1, x2, y2, stroke, color, fill_color, fill, angle, opacity, hardness |
| `Bolt` | x1, y1, x2, y2, stroke, color, fill_color, fill, angle, opacity, hardness |
| `Arrow4` | x1, y1, x2, y2, stroke, color, fill_color, fill, angle, opacity, hardness |
| `FreePath` | pts, closed, stroke, color, fill_color, fill, opacity, hardness |

### Public API

```rust
// Şekilleri bir Layer'ın piksel tamponuna render eder
pub fn render_vector_shapes(layer: &mut Layer);

// Vektör-only katmanlar için piksel tamponunu temizler (0x00 ile doldurur)
pub fn render_vector_clear_bg(layer: &mut Layer);

// Şekli delta derece kadar döndürür
pub fn rotate_shape(shape: &mut VectorShape, delta_degrees: f32);

// Şeklin açısını derece cinsinden belirler
pub fn set_shape_angle(shape: &mut VectorShape, new_angle_degrees: f32);
```

### Path Boolean Modülü (`path_boolean`)

```rust
pub enum BooleanOp { Union, Intersect, Subtract, Xor }

// İki FreePath nokta dizisi üzerinde boolean işlemi
pub fn boolean_path(op: BooleanOp, path_a: &[[f32; 2]], path_b: &[[f32; 2]]) -> Vec<[f32; 2]>;

// İki FreePath VectorShape üzerinde boolean işlemi
pub fn boolean_shapes(op: BooleanOp, a: &VectorShape, b: &VectorShape) -> Option<VectorShape>;
```

### FFI/C-ABI Arayüzü

Kütüphane `cdylib` olarak derlendiğinde şu fonksiyonlar dışa aktarılır:

```c
// Şekil verilerini deserialize edip piksel tamponuna render eder
bool vector_render_shapes(
    uint8_t* pixels_ptr, size_t pixels_len,
    uint32_t width, uint32_t height,
    const uint8_t* shapes_data_ptr, size_t shapes_data_len
);

// İki FreePath şekli üzerinde boolean işlemi
bool vector_boolean_shapes(
    int32_t op_val,  // 0=Union, 1=Intersect, 2=Subtract, 3=Xor
    const uint8_t* shape_a_ptr, size_t shape_a_len,
    const uint8_t* shape_b_ptr, size_t shape_b_len,
    uint8_t** out_buffer_ptr, size_t* out_buffer_len
);

// Boolean işleminden dönen tamponu serbest bırakır
void free_buffer_c(uint8_t* ptr, size_t len);
```

## Derleme

### Geliştirme (debug)

```bash
cargo build
```

### Release

```bash
cargo build --release
```

### Dinamik kütüphane (cdylib)

```bash
cargo build --release
# Çıktı: target/release/libhcie_vector.so (Linux)
# Çıktı: target/release/libhcie_vector.dylib (macOS)
# Çıktı: target/release/hcie_vector.dll (Windows)
```

## Test Çalıştırma

### Birim testler

```bash
cargo test
```

### Etkileşimli GUI testi

```bash
cargo run --example vector_test
```

GUI özellikleri:
- **Shape seçimi**: 16 şekil türü (Line, Rect, Circle, Arrow, Star, Polygon, Rhombus, Cylinder, Heart, Bubble, Gear, Cross, Crescent, Bolt, Arrow4, FreePath)
- **Parametre slider'ları**: Stroke, Angle, Opacity, Hardness, Corner Radius, Star Points, Inner Radius, Polygon Sides, Line Cap, Thick Arrow — şekle göre aktif/pasif
- **Stroke ve Fill renkleri**: RGBA slider'lar
- **Canvas boyutu**: 512×512, 1024×1024, 2048×2048, 4096×4096
- **FPS limitleyici**: 30, 60, 165, ∞
- **FPS sayacı ve tile/dirty durumu**
- **Clear Canvas** butonu

## Kaynak Kodu Olmadan Kullanım (FFI)

Kaynak koda erişimi olmayan projelerde `cdylib` olarak derlenmiş `.so`/`.dylib`/`.dll` dosyası ile kullanılabilir.

### Örnek: C üzerinden şekil render

```c
#include <stdint.h>
#include <stdlib.h>
#include <stdio.h>

// .so dosyasını linkleyin: -lhcie_vector
extern bool vector_render_shapes(
    uint8_t* pixels_ptr, size_t pixels_len,
    uint32_t width, uint32_t height,
    const uint8_t* shapes_data_ptr, size_t shapes_data_len
);

extern void free_buffer_c(uint8_t* ptr, size_t len);

int main() {
    uint32_t w = 800, h = 600;
    size_t px_len = (size_t)w * h * 4;
    uint8_t* pixels = malloc(px_len);
    memset(pixels, 255, px_len); // beyaz arkaplan

    // bincode ile serialize edilmiş Vec<VectorShape> verisi
    // (örneğin Rust tarafında bincode::serialize(&shapes) ile üretilir)
    uint8_t* shapes_data = ...;
    size_t shapes_data_len = ...;

    bool ok = vector_render_shapes(pixels, px_len, w, h, shapes_data, shapes_data_len);
    if (ok) {
        // pixels artık render edilmiş şekilleri içerir
        printf("Render başarılı\n");
    }

    free(pixels);
    return 0;
}
```

### Örnek: C üzerinden boolean işlemi

```c
extern bool vector_boolean_shapes(
    int32_t op_val,
    const uint8_t* shape_a_ptr, size_t shape_a_len,
    const uint8_t* shape_b_ptr, size_t shape_b_len,
    uint8_t** out_buffer_ptr, size_t* out_buffer_len
);

// Union (0), Intersect (1), Subtract (2), Xor (3)
uint8_t* result_buf = NULL;
size_t result_len = 0;
bool ok = vector_boolean_shapes(0, shape_a, shape_a_len, shape_b, shape_b_len, &result_buf, &result_len);
if (ok) {
    // result_buf -> bincode deserialize -> VectorShape
    free_buffer_c(result_buf, result_len);
}
```

## Bağımlılıklar

| Kütüphane | Açıklama |
|---|---|
| `hcie-protocol` | `Layer`, `VectorShape`, `LineCap` tipleri |
| `hcie-blend` | `blend_pixels`, `BlendMode` — piksel karıştırma motoru |
| `serde` | Serileştirme (Serialize, Deserialize) |
| `bincode` | FFI için binary serileştirme |

## Proje Yapısı

```
hcie-vector/
├── Cargo.toml
├── src/
│   ├── lib.rs           # Ana render mantığı, FFI giriş noktaları
│   └── path_boolean.rs  # Boolean birleşim işlemleri (Union, Intersect, Subtract, Xor)
└── examples/
    └── vector_test.rs   # Etkileşimli GUI test uygulaması
```