207 lines
6.8 KiB
Markdown
207 lines
6.8 KiB
Markdown
# 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ı
|
||
``` |